/ Hex Artifact Content
Login

Artifact 329de1e75636972ba4b9388971ba47d3e2cb9116:


0000: 2f 2a 0a 2a 2a 20 32 30 30 31 20 53 65 70 74 65  /*.** 2001 Septe
0010: 6d 62 65 72 20 31 35 0a 2a 2a 0a 2a 2a 20 54 68  mber 15.**.** Th
0020: 65 20 61 75 74 68 6f 72 20 64 69 73 63 6c 61 69  e author disclai
0030: 6d 73 20 63 6f 70 79 72 69 67 68 74 20 74 6f 20  ms copyright to 
0040: 74 68 69 73 20 73 6f 75 72 63 65 20 63 6f 64 65  this source code
0050: 2e 20 20 49 6e 20 70 6c 61 63 65 20 6f 66 0a 2a  .  In place of.*
0060: 2a 20 61 20 6c 65 67 61 6c 20 6e 6f 74 69 63 65  * a legal notice
0070: 2c 20 68 65 72 65 20 69 73 20 61 20 62 6c 65 73  , here is a bles
0080: 73 69 6e 67 3a 0a 2a 2a 0a 2a 2a 20 20 20 20 4d  sing:.**.**    M
0090: 61 79 20 79 6f 75 20 64 6f 20 67 6f 6f 64 20 61  ay you do good a
00a0: 6e 64 20 6e 6f 74 20 65 76 69 6c 2e 0a 2a 2a 20  nd not evil..** 
00b0: 20 20 20 4d 61 79 20 79 6f 75 20 66 69 6e 64 20     May you find 
00c0: 66 6f 72 67 69 76 65 6e 65 73 73 20 66 6f 72 20  forgiveness for 
00d0: 79 6f 75 72 73 65 6c 66 20 61 6e 64 20 66 6f 72  yourself and for
00e0: 67 69 76 65 20 6f 74 68 65 72 73 2e 0a 2a 2a 20  give others..** 
00f0: 20 20 20 4d 61 79 20 79 6f 75 20 73 68 61 72 65     May you share
0100: 20 66 72 65 65 6c 79 2c 20 6e 65 76 65 72 20 74   freely, never t
0110: 61 6b 69 6e 67 20 6d 6f 72 65 20 74 68 61 6e 20  aking more than 
0120: 79 6f 75 20 67 69 76 65 2e 0a 2a 2a 0a 2a 2a 2a  you give..**.***
0130: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0140: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0150: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0160: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0170: 2a 2a 2a 2a 2a 2a 0a 2a 2a 20 54 68 69 73 20 68  ******.** This h
0180: 65 61 64 65 72 20 66 69 6c 65 20 64 65 66 69 6e  eader file defin
0190: 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  es the interface
01a0: 20 74 68 61 74 20 74 68 65 20 53 51 4c 69 74 65   that the SQLite
01b0: 20 6c 69 62 72 61 72 79 0a 2a 2a 20 70 72 65 73   library.** pres
01c0: 65 6e 74 73 20 74 6f 20 63 6c 69 65 6e 74 20 70  ents to client p
01d0: 72 6f 67 72 61 6d 73 2e 20 20 49 66 20 61 20 43  rograms.  If a C
01e0: 2d 66 75 6e 63 74 69 6f 6e 2c 20 73 74 72 75 63  -function, struc
01f0: 74 75 72 65 2c 20 64 61 74 61 74 79 70 65 2c 0a  ture, datatype,.
0200: 2a 2a 20 6f 72 20 63 6f 6e 73 74 61 6e 74 20 64  ** or constant d
0210: 65 66 69 6e 69 74 69 6f 6e 20 64 6f 65 73 20 6e  efinition does n
0220: 6f 74 20 61 70 70 65 61 72 20 69 6e 20 74 68 69  ot appear in thi
0230: 73 20 66 69 6c 65 2c 20 74 68 65 6e 20 69 74 20  s file, then it 
0240: 69 73 0a 2a 2a 20 6e 6f 74 20 61 20 70 75 62 6c  is.** not a publ
0250: 69 73 68 65 64 20 41 50 49 20 6f 66 20 53 51 4c  ished API of SQL
0260: 69 74 65 2c 20 69 73 20 73 75 62 6a 65 63 74 20  ite, is subject 
0270: 74 6f 20 63 68 61 6e 67 65 20 77 69 74 68 6f 75  to change withou
0280: 74 0a 2a 2a 20 6e 6f 74 69 63 65 2c 20 61 6e 64  t.** notice, and
0290: 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 72   should not be r
02a0: 65 66 65 72 65 6e 63 65 64 20 62 79 20 70 72 6f  eferenced by pro
02b0: 67 72 61 6d 73 20 74 68 61 74 20 75 73 65 20 53  grams that use S
02c0: 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 53 6f 6d  QLite..**.** Som
02d0: 65 20 6f 66 20 74 68 65 20 64 65 66 69 6e 69 74  e of the definit
02e0: 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20 69 6e  ions that are in
02f0: 20 74 68 69 73 20 66 69 6c 65 20 61 72 65 20 6d   this file are m
0300: 61 72 6b 65 64 20 61 73 0a 2a 2a 20 22 65 78 70  arked as.** "exp
0310: 65 72 69 6d 65 6e 74 61 6c 22 2e 20 20 45 78 70  erimental".  Exp
0320: 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74 65 72 66  erimental interf
0330: 61 63 65 73 20 61 72 65 20 6e 6f 72 6d 61 6c 6c  aces are normall
0340: 79 20 6e 65 77 0a 2a 2a 20 66 65 61 74 75 72 65  y new.** feature
0350: 73 20 72 65 63 65 6e 74 6c 79 20 61 64 64 65 64  s recently added
0360: 20 74 6f 20 53 51 4c 69 74 65 2e 20 20 57 65 20   to SQLite.  We 
0370: 64 6f 20 6e 6f 74 20 61 6e 74 69 63 69 70 61 74  do not anticipat
0380: 65 20 63 68 61 6e 67 65 73 0a 2a 2a 20 74 6f 20  e changes.** to 
0390: 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74  experimental int
03a0: 65 72 66 61 63 65 73 20 62 75 74 20 72 65 73 65  erfaces but rese
03b0: 72 76 65 20 74 68 65 20 72 69 67 68 74 20 74 6f  rve the right to
03c0: 20 6d 61 6b 65 20 6d 69 6e 6f 72 20 63 68 61 6e   make minor chan
03d0: 67 65 73 0a 2a 2a 20 69 66 20 65 78 70 65 72 69  ges.** if experi
03e0: 65 6e 63 65 20 66 72 6f 6d 20 75 73 65 20 22 69  ence from use "i
03f0: 6e 20 74 68 65 20 77 69 6c 64 22 20 73 75 67 67  n the wild" sugg
0400: 65 73 74 20 73 75 63 68 20 63 68 61 6e 67 65 73  est such changes
0410: 20 61 72 65 20 70 72 75 64 65 6e 74 2e 0a 2a 2a   are prudent..**
0420: 0a 2a 2a 20 54 68 65 20 6f 66 66 69 63 69 61 6c  .** The official
0430: 20 43 2d 6c 61 6e 67 75 61 67 65 20 41 50 49 20   C-language API 
0440: 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f  documentation fo
0450: 72 20 53 51 4c 69 74 65 20 69 73 20 64 65 72 69  r SQLite is deri
0460: 76 65 64 0a 2a 2a 20 66 72 6f 6d 20 63 6f 6d 6d  ved.** from comm
0470: 65 6e 74 73 20 69 6e 20 74 68 69 73 20 66 69 6c  ents in this fil
0480: 65 2e 20 20 54 68 69 73 20 66 69 6c 65 20 69 73  e.  This file is
0490: 20 74 68 65 20 61 75 74 68 6f 72 69 74 61 74 69   the authoritati
04a0: 76 65 20 73 6f 75 72 63 65 0a 2a 2a 20 6f 6e 20  ve source.** on 
04b0: 68 6f 77 20 53 51 4c 69 74 65 20 69 6e 74 65 72  how SQLite inter
04c0: 66 61 63 65 73 20 61 72 65 20 73 75 70 70 6f 73  faces are suppos
04d0: 65 64 20 74 6f 20 6f 70 65 72 61 74 65 2e 0a 2a  ed to operate..*
04e0: 2a 0a 2a 2a 20 54 68 65 20 6e 61 6d 65 20 6f 66  *.** The name of
04f0: 20 74 68 69 73 20 66 69 6c 65 20 75 6e 64 65 72   this file under
0500: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6d   configuration m
0510: 61 6e 61 67 65 6d 65 6e 74 20 69 73 20 22 73 71  anagement is "sq
0520: 6c 69 74 65 2e 68 2e 69 6e 22 2e 0a 2a 2a 20 54  lite.h.in"..** T
0530: 68 65 20 6d 61 6b 65 66 69 6c 65 20 6d 61 6b 65  he makefile make
0540: 73 20 73 6f 6d 65 20 6d 69 6e 6f 72 20 63 68 61  s some minor cha
0550: 6e 67 65 73 20 74 6f 20 74 68 69 73 20 66 69 6c  nges to this fil
0560: 65 20 28 73 75 63 68 20 61 73 20 69 6e 73 65 72  e (such as inser
0570: 74 69 6e 67 0a 2a 2a 20 74 68 65 20 76 65 72 73  ting.** the vers
0580: 69 6f 6e 20 6e 75 6d 62 65 72 29 20 61 6e 64 20  ion number) and 
0590: 63 68 61 6e 67 65 73 20 69 74 73 20 6e 61 6d 65  changes its name
05a0: 20 74 6f 20 22 73 71 6c 69 74 65 33 2e 68 22 20   to "sqlite3.h" 
05b0: 61 73 0a 2a 2a 20 70 61 72 74 20 6f 66 20 74 68  as.** part of th
05c0: 65 20 62 75 69 6c 64 20 70 72 6f 63 65 73 73 2e  e build process.
05d0: 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c 49  .*/.#ifndef SQLI
05e0: 54 45 33 5f 48 0a 23 64 65 66 69 6e 65 20 53 51  TE3_H.#define SQ
05f0: 4c 49 54 45 33 5f 48 0a 23 69 6e 63 6c 75 64 65  LITE3_H.#include
0600: 20 3c 73 74 64 61 72 67 2e 68 3e 20 20 20 20 20   <stdarg.h>     
0610: 2f 2a 20 4e 65 65 64 65 64 20 66 6f 72 20 74 68  /* Needed for th
0620: 65 20 64 65 66 69 6e 69 74 69 6f 6e 20 6f 66 20  e definition of 
0630: 76 61 5f 6c 69 73 74 20 2a 2f 0a 0a 2f 2a 0a 2a  va_list */../*.*
0640: 2a 20 4d 61 6b 65 20 73 75 72 65 20 77 65 20 63  * Make sure we c
0650: 61 6e 20 63 61 6c 6c 20 74 68 69 73 20 73 74 75  an call this stu
0660: 66 66 20 66 72 6f 6d 20 43 2b 2b 2e 0a 2a 2f 0a  ff from C++..*/.
0670: 23 69 66 64 65 66 20 5f 5f 63 70 6c 75 73 70 6c  #ifdef __cpluspl
0680: 75 73 0a 65 78 74 65 72 6e 20 22 43 22 20 7b 0a  us.extern "C" {.
0690: 23 65 6e 64 69 66 0a 0a 0a 2f 2a 0a 2a 2a 20 50  #endif.../*.** P
06a0: 72 6f 76 69 64 65 20 74 68 65 20 61 62 69 6c 69  rovide the abili
06b0: 74 79 20 74 6f 20 6f 76 65 72 72 69 64 65 20 6c  ty to override l
06c0: 69 6e 6b 61 67 65 20 66 65 61 74 75 72 65 73 20  inkage features 
06d0: 6f 66 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  of the interface
06e0: 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c  ..*/.#ifndef SQL
06f0: 49 54 45 5f 45 58 54 45 52 4e 0a 23 20 64 65 66  ITE_EXTERN.# def
0700: 69 6e 65 20 53 51 4c 49 54 45 5f 45 58 54 45 52  ine SQLITE_EXTER
0710: 4e 20 65 78 74 65 72 6e 0a 23 65 6e 64 69 66 0a  N extern.#endif.
0720: 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 41  #ifndef SQLITE_A
0730: 50 49 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49  PI.# define SQLI
0740: 54 45 5f 41 50 49 0a 23 65 6e 64 69 66 0a 23 69  TE_API.#endif.#i
0750: 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 43 44 45  fndef SQLITE_CDE
0760: 43 4c 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49  CL.# define SQLI
0770: 54 45 5f 43 44 45 43 4c 0a 23 65 6e 64 69 66 0a  TE_CDECL.#endif.
0780: 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 41  #ifndef SQLITE_A
0790: 50 49 43 41 4c 4c 0a 23 20 64 65 66 69 6e 65 20  PICALL.# define 
07a0: 53 51 4c 49 54 45 5f 41 50 49 43 41 4c 4c 0a 23  SQLITE_APICALL.#
07b0: 65 6e 64 69 66 0a 23 69 66 6e 64 65 66 20 53 51  endif.#ifndef SQ
07c0: 4c 49 54 45 5f 53 54 44 43 41 4c 4c 0a 23 20 64  LITE_STDCALL.# d
07d0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 54 44  efine SQLITE_STD
07e0: 43 41 4c 4c 20 53 51 4c 49 54 45 5f 41 50 49 43  CALL SQLITE_APIC
07f0: 41 4c 4c 0a 23 65 6e 64 69 66 0a 23 69 66 6e 64  ALL.#endif.#ifnd
0800: 65 66 20 53 51 4c 49 54 45 5f 43 41 4c 4c 42 41  ef SQLITE_CALLBA
0810: 43 4b 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49  CK.# define SQLI
0820: 54 45 5f 43 41 4c 4c 42 41 43 4b 0a 23 65 6e 64  TE_CALLBACK.#end
0830: 69 66 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54  if.#ifndef SQLIT
0840: 45 5f 53 59 53 41 50 49 0a 23 20 64 65 66 69 6e  E_SYSAPI.# defin
0850: 65 20 53 51 4c 49 54 45 5f 53 59 53 41 50 49 0a  e SQLITE_SYSAPI.
0860: 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 54 68  #endif../*.** Th
0870: 65 73 65 20 6e 6f 2d 6f 70 20 6d 61 63 72 6f 73  ese no-op macros
0880: 20 61 72 65 20 75 73 65 64 20 69 6e 20 66 72 6f   are used in fro
0890: 6e 74 20 6f 66 20 69 6e 74 65 72 66 61 63 65 73  nt of interfaces
08a0: 20 74 6f 20 6d 61 72 6b 20 74 68 6f 73 65 0a 2a   to mark those.*
08b0: 2a 20 69 6e 74 65 72 66 61 63 65 73 20 61 73 20  * interfaces as 
08c0: 65 69 74 68 65 72 20 64 65 70 72 65 63 61 74 65  either deprecate
08d0: 64 20 6f 72 20 65 78 70 65 72 69 6d 65 6e 74 61  d or experimenta
08e0: 6c 2e 20 20 4e 65 77 20 61 70 70 6c 69 63 61 74  l.  New applicat
08f0: 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e  ions.** should n
0900: 6f 74 20 75 73 65 20 64 65 70 72 65 63 61 74 65  ot use deprecate
0910: 64 20 69 6e 74 65 72 66 61 63 65 73 20 2d 20 74  d interfaces - t
0920: 68 65 79 20 61 72 65 20 73 75 70 70 6f 72 74 65  hey are supporte
0930: 64 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73 0a  d for backwards.
0940: 2a 2a 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79  ** compatibility
0950: 20 6f 6e 6c 79 2e 20 20 41 70 70 6c 69 63 61 74   only.  Applicat
0960: 69 6f 6e 20 77 72 69 74 65 72 73 20 73 68 6f 75  ion writers shou
0970: 6c 64 20 62 65 20 61 77 61 72 65 20 74 68 61 74  ld be aware that
0980: 0a 2a 2a 20 65 78 70 65 72 69 6d 65 6e 74 61 6c  .** experimental
0990: 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20   interfaces are 
09a0: 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67  subject to chang
09b0: 65 20 69 6e 20 70 6f 69 6e 74 20 72 65 6c 65 61  e in point relea
09c0: 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ses..**.** These
09d0: 20 6d 61 63 72 6f 73 20 75 73 65 64 20 74 6f 20   macros used to 
09e0: 72 65 73 6f 6c 76 65 20 74 6f 20 76 61 72 69 6f  resolve to vario
09f0: 75 73 20 6b 69 6e 64 73 20 6f 66 20 63 6f 6d 70  us kinds of comp
0a00: 69 6c 65 72 20 6d 61 67 69 63 20 74 68 61 74 0a  iler magic that.
0a10: 2a 2a 20 77 6f 75 6c 64 20 67 65 6e 65 72 61 74  ** would generat
0a20: 65 20 77 61 72 6e 69 6e 67 20 6d 65 73 73 61 67  e warning messag
0a30: 65 73 20 77 68 65 6e 20 74 68 65 79 20 77 65 72  es when they wer
0a40: 65 20 75 73 65 64 2e 20 20 42 75 74 20 74 68 61  e used.  But tha
0a50: 74 0a 2a 2a 20 63 6f 6d 70 69 6c 65 72 20 6d 61  t.** compiler ma
0a60: 67 69 63 20 65 6e 64 65 64 20 75 70 20 67 65 6e  gic ended up gen
0a70: 65 72 61 74 69 6e 67 20 73 75 63 68 20 61 20 66  erating such a f
0a80: 6c 75 72 72 79 20 6f 66 20 62 75 67 20 72 65 70  lurry of bug rep
0a90: 6f 72 74 73 0a 2a 2a 20 74 68 61 74 20 77 65 20  orts.** that we 
0aa0: 68 61 76 65 20 74 61 6b 65 6e 20 69 74 20 61 6c  have taken it al
0ab0: 6c 20 6f 75 74 20 61 6e 64 20 67 6f 6e 65 20 62  l out and gone b
0ac0: 61 63 6b 20 74 6f 20 75 73 69 6e 67 20 73 69 6d  ack to using sim
0ad0: 70 6c 65 0a 2a 2a 20 6e 6f 6f 70 20 6d 61 63 72  ple.** noop macr
0ae0: 6f 73 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  os..*/.#define S
0af0: 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44  QLITE_DEPRECATED
0b00: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
0b10: 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a 0a 2f 2a  EXPERIMENTAL../*
0b20: 0a 2a 2a 20 45 6e 73 75 72 65 20 74 68 65 73 65  .** Ensure these
0b30: 20 73 79 6d 62 6f 6c 73 20 77 65 72 65 20 6e 6f   symbols were no
0b40: 74 20 64 65 66 69 6e 65 64 20 62 79 20 73 6f 6d  t defined by som
0b50: 65 20 70 72 65 76 69 6f 75 73 20 68 65 61 64 65  e previous heade
0b60: 72 20 66 69 6c 65 2e 0a 2a 2f 0a 23 69 66 64 65  r file..*/.#ifde
0b70: 66 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e  f SQLITE_VERSION
0b80: 0a 23 20 75 6e 64 65 66 20 53 51 4c 49 54 45 5f  .# undef SQLITE_
0b90: 56 45 52 53 49 4f 4e 0a 23 65 6e 64 69 66 0a 23  VERSION.#endif.#
0ba0: 69 66 64 65 66 20 53 51 4c 49 54 45 5f 56 45 52  ifdef SQLITE_VER
0bb0: 53 49 4f 4e 5f 4e 55 4d 42 45 52 0a 23 20 75 6e  SION_NUMBER.# un
0bc0: 64 65 66 20 53 51 4c 49 54 45 5f 56 45 52 53 49  def SQLITE_VERSI
0bd0: 4f 4e 5f 4e 55 4d 42 45 52 0a 23 65 6e 64 69 66  ON_NUMBER.#endif
0be0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
0bf0: 3a 20 43 6f 6d 70 69 6c 65 2d 54 69 6d 65 20 4c  : Compile-Time L
0c00: 69 62 72 61 72 79 20 56 65 72 73 69 6f 6e 20 4e  ibrary Version N
0c10: 75 6d 62 65 72 73 0a 2a 2a 0a 2a 2a 20 5e 28 54  umbers.**.** ^(T
0c20: 68 65 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49  he [SQLITE_VERSI
0c30: 4f 4e 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73  ON] C preprocess
0c40: 6f 72 20 6d 61 63 72 6f 20 69 6e 20 74 68 65 20  or macro in the 
0c50: 73 71 6c 69 74 65 33 2e 68 20 68 65 61 64 65 72  sqlite3.h header
0c60: 0a 2a 2a 20 65 76 61 6c 75 61 74 65 73 20 74 6f  .** evaluates to
0c70: 20 61 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61   a string litera
0c80: 6c 20 74 68 61 74 20 69 73 20 74 68 65 20 53 51  l that is the SQ
0c90: 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 69 6e 20  Lite version in 
0ca0: 74 68 65 0a 2a 2a 20 66 6f 72 6d 61 74 20 22 58  the.** format "X
0cb0: 2e 59 2e 5a 22 20 77 68 65 72 65 20 58 20 69 73  .Y.Z" where X is
0cc0: 20 74 68 65 20 6d 61 6a 6f 72 20 76 65 72 73 69   the major versi
0cd0: 6f 6e 20 6e 75 6d 62 65 72 20 28 61 6c 77 61 79  on number (alway
0ce0: 73 20 33 20 66 6f 72 0a 2a 2a 20 53 51 4c 69 74  s 3 for.** SQLit
0cf0: 65 33 29 20 61 6e 64 20 59 20 69 73 20 74 68 65  e3) and Y is the
0d00: 20 6d 69 6e 6f 72 20 76 65 72 73 69 6f 6e 20 6e   minor version n
0d10: 75 6d 62 65 72 20 61 6e 64 20 5a 20 69 73 20 74  umber and Z is t
0d20: 68 65 20 72 65 6c 65 61 73 65 20 6e 75 6d 62 65  he release numbe
0d30: 72 2e 29 5e 0a 2a 2a 20 5e 28 54 68 65 20 5b 53  r.)^.** ^(The [S
0d40: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55  QLITE_VERSION_NU
0d50: 4d 42 45 52 5d 20 43 20 70 72 65 70 72 6f 63 65  MBER] C preproce
0d60: 73 73 6f 72 20 6d 61 63 72 6f 20 72 65 73 6f 6c  ssor macro resol
0d70: 76 65 73 20 74 6f 20 61 6e 20 69 6e 74 65 67 65  ves to an intege
0d80: 72 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 76 61  r.** with the va
0d90: 6c 75 65 20 28 58 2a 31 30 30 30 30 30 30 20 2b  lue (X*1000000 +
0da0: 20 59 2a 31 30 30 30 20 2b 20 5a 29 20 77 68 65   Y*1000 + Z) whe
0db0: 72 65 20 58 2c 20 59 2c 20 61 6e 64 20 5a 20 61  re X, Y, and Z a
0dc0: 72 65 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 6e  re the same.** n
0dd0: 75 6d 62 65 72 73 20 75 73 65 64 20 69 6e 20 5b  umbers used in [
0de0: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d 2e  SQLITE_VERSION].
0df0: 29 5e 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45  )^.** The SQLITE
0e00: 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20  _VERSION_NUMBER 
0e10: 66 6f 72 20 61 6e 79 20 67 69 76 65 6e 20 72 65  for any given re
0e20: 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65 20  lease of SQLite 
0e30: 77 69 6c 6c 20 61 6c 73 6f 0a 2a 2a 20 62 65 20  will also.** be 
0e40: 6c 61 72 67 65 72 20 74 68 61 6e 20 74 68 65 20  larger than the 
0e50: 72 65 6c 65 61 73 65 20 66 72 6f 6d 20 77 68 69  release from whi
0e60: 63 68 20 69 74 20 69 73 20 64 65 72 69 76 65 64  ch it is derived
0e70: 2e 20 20 45 69 74 68 65 72 20 59 20 77 69 6c 6c  .  Either Y will
0e80: 0a 2a 2a 20 62 65 20 68 65 6c 64 20 63 6f 6e 73  .** be held cons
0e90: 74 61 6e 74 20 61 6e 64 20 5a 20 77 69 6c 6c 20  tant and Z will 
0ea0: 62 65 20 69 6e 63 72 65 6d 65 6e 74 65 64 20 6f  be incremented o
0eb0: 72 20 65 6c 73 65 20 59 20 77 69 6c 6c 20 62 65  r else Y will be
0ec0: 20 69 6e 63 72 65 6d 65 6e 74 65 64 0a 2a 2a 20   incremented.** 
0ed0: 61 6e 64 20 5a 20 77 69 6c 6c 20 62 65 20 72 65  and Z will be re
0ee0: 73 65 74 20 74 6f 20 7a 65 72 6f 2e 0a 2a 2a 0a  set to zero..**.
0ef0: 2a 2a 20 53 69 6e 63 65 20 5b 76 65 72 73 69 6f  ** Since [versio
0f00: 6e 20 33 2e 36 2e 31 38 5d 20 28 5b 64 61 74 65  n 3.6.18] ([date
0f10: 6f 66 3a 33 2e 36 2e 31 38 5d 29 2c 20 0a 2a 2a  of:3.6.18]), .**
0f20: 20 53 51 4c 69 74 65 20 73 6f 75 72 63 65 20 63   SQLite source c
0f30: 6f 64 65 20 68 61 73 20 62 65 65 6e 20 73 74 6f  ode has been sto
0f40: 72 65 64 20 69 6e 20 74 68 65 0a 2a 2a 20 3c 61  red in the.** <a
0f50: 20 68 72 65 66 3d 22 68 74 74 70 3a 2f 2f 77 77   href="http://ww
0f60: 77 2e 66 6f 73 73 69 6c 2d 73 63 6d 2e 6f 72 67  w.fossil-scm.org
0f70: 2f 22 3e 46 6f 73 73 69 6c 20 63 6f 6e 66 69 67  /">Fossil config
0f80: 75 72 61 74 69 6f 6e 20 6d 61 6e 61 67 65 6d 65  uration manageme
0f90: 6e 74 0a 2a 2a 20 73 79 73 74 65 6d 3c 2f 61 3e  nt.** system</a>
0fa0: 2e 20 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 53  .  ^The SQLITE_S
0fb0: 4f 55 52 43 45 5f 49 44 20 6d 61 63 72 6f 20 65  OURCE_ID macro e
0fc0: 76 61 6c 75 61 74 65 73 20 74 6f 0a 2a 2a 20 61  valuates to.** a
0fd0: 20 73 74 72 69 6e 67 20 77 68 69 63 68 20 69 64   string which id
0fe0: 65 6e 74 69 66 69 65 73 20 61 20 70 61 72 74 69  entifies a parti
0ff0: 63 75 6c 61 72 20 63 68 65 63 6b 2d 69 6e 20 6f  cular check-in o
1000: 66 20 53 51 4c 69 74 65 0a 2a 2a 20 77 69 74 68  f SQLite.** with
1010: 69 6e 20 69 74 73 20 63 6f 6e 66 69 67 75 72 61  in its configura
1020: 74 69 6f 6e 20 6d 61 6e 61 67 65 6d 65 6e 74 20  tion management 
1030: 73 79 73 74 65 6d 2e 20 20 5e 54 68 65 20 53 51  system.  ^The SQ
1040: 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 0a 2a  LITE_SOURCE_ID.*
1050: 2a 20 73 74 72 69 6e 67 20 63 6f 6e 74 61 69 6e  * string contain
1060: 73 20 74 68 65 20 64 61 74 65 20 61 6e 64 20 74  s the date and t
1070: 69 6d 65 20 6f 66 20 74 68 65 20 63 68 65 63 6b  ime of the check
1080: 2d 69 6e 20 28 55 54 43 29 20 61 6e 64 20 61 6e  -in (UTC) and an
1090: 20 53 48 41 31 0a 2a 2a 20 68 61 73 68 20 6f 66   SHA1.** hash of
10a0: 20 74 68 65 20 65 6e 74 69 72 65 20 73 6f 75 72   the entire sour
10b0: 63 65 20 74 72 65 65 2e 0a 2a 2a 0a 2a 2a 20 53  ce tree..**.** S
10c0: 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65  ee also: [sqlite
10d0: 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29 5d 2c  3_libversion()],
10e0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6c 69 62  .** [sqlite3_lib
10f0: 76 65 72 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 29  version_number()
1100: 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73 6f 75 72  ], [sqlite3_sour
1110: 63 65 69 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c  ceid()],.** [sql
1120: 69 74 65 5f 76 65 72 73 69 6f 6e 28 29 5d 20 61  ite_version()] a
1130: 6e 64 20 5b 73 71 6c 69 74 65 5f 73 6f 75 72 63  nd [sqlite_sourc
1140: 65 5f 69 64 28 29 5d 2e 0a 2a 2f 0a 23 64 65 66  e_id()]..*/.#def
1150: 69 6e 65 20 53 51 4c 49 54 45 5f 56 45 52 53 49  ine SQLITE_VERSI
1160: 4f 4e 20 20 20 20 20 20 20 20 22 2d 2d 56 45 52  ON        "--VER
1170: 53 2d 2d 22 0a 23 64 65 66 69 6e 65 20 53 51 4c  S--".#define SQL
1180: 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42  ITE_VERSION_NUMB
1190: 45 52 20 2d 2d 56 45 52 53 49 4f 4e 2d 4e 55 4d  ER --VERSION-NUM
11a0: 42 45 52 2d 2d 0a 23 64 65 66 69 6e 65 20 53 51  BER--.#define SQ
11b0: 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 20 20  LITE_SOURCE_ID  
11c0: 20 20 20 20 22 2d 2d 53 4f 55 52 43 45 2d 49 44      "--SOURCE-ID
11d0: 2d 2d 22 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  --"../*.** CAPI3
11e0: 52 45 46 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69  REF: Run-Time Li
11f0: 62 72 61 72 79 20 56 65 72 73 69 6f 6e 20 4e 75  brary Version Nu
1200: 6d 62 65 72 73 0a 2a 2a 20 4b 45 59 57 4f 52 44  mbers.** KEYWORD
1210: 53 3a 20 73 71 6c 69 74 65 33 5f 76 65 72 73 69  S: sqlite3_versi
1220: 6f 6e 20 73 71 6c 69 74 65 33 5f 73 6f 75 72 63  on sqlite3_sourc
1230: 65 69 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  eid.**.** These 
1240: 69 6e 74 65 72 66 61 63 65 73 20 70 72 6f 76 69  interfaces provi
1250: 64 65 20 74 68 65 20 73 61 6d 65 20 69 6e 66 6f  de the same info
1260: 72 6d 61 74 69 6f 6e 20 61 73 20 74 68 65 20 5b  rmation as the [
1270: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d 2c  SQLITE_VERSION],
1280: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 56 45 52 53  .** [SQLITE_VERS
1290: 49 4f 4e 5f 4e 55 4d 42 45 52 5d 2c 20 61 6e 64  ION_NUMBER], and
12a0: 20 5b 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f   [SQLITE_SOURCE_
12b0: 49 44 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73  ID] C preprocess
12c0: 6f 72 20 6d 61 63 72 6f 73 0a 2a 2a 20 62 75 74  or macros.** but
12d0: 20 61 72 65 20 61 73 73 6f 63 69 61 74 65 64 20   are associated 
12e0: 77 69 74 68 20 74 68 65 20 6c 69 62 72 61 72 79  with the library
12f0: 20 69 6e 73 74 65 61 64 20 6f 66 20 74 68 65 20   instead of the 
1300: 68 65 61 64 65 72 20 66 69 6c 65 2e 20 20 5e 28  header file.  ^(
1310: 43 61 75 74 69 6f 75 73 0a 2a 2a 20 70 72 6f 67  Cautious.** prog
1320: 72 61 6d 6d 65 72 73 20 6d 69 67 68 74 20 69 6e  rammers might in
1330: 63 6c 75 64 65 20 61 73 73 65 72 74 28 29 20 73  clude assert() s
1340: 74 61 74 65 6d 65 6e 74 73 20 69 6e 20 74 68 65  tatements in the
1350: 69 72 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74  ir application t
1360: 6f 0a 2a 2a 20 76 65 72 69 66 79 20 74 68 61 74  o.** verify that
1370: 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e 65 64   values returned
1380: 20 62 79 20 74 68 65 73 65 20 69 6e 74 65 72 66   by these interf
1390: 61 63 65 73 20 6d 61 74 63 68 20 74 68 65 20 6d  aces match the m
13a0: 61 63 72 6f 73 20 69 6e 0a 2a 2a 20 74 68 65 20  acros in.** the 
13b0: 68 65 61 64 65 72 2c 20 61 6e 64 20 74 68 75 73  header, and thus
13c0: 20 65 6e 73 75 72 65 20 74 68 61 74 20 74 68 65   ensure that the
13d0: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 73 0a   application is.
13e0: 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  ** compiled with
13f0: 20 6d 61 74 63 68 69 6e 67 20 6c 69 62 72 61 72   matching librar
1400: 79 20 61 6e 64 20 68 65 61 64 65 72 20 66 69 6c  y and header fil
1410: 65 73 2e 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  es..**.** <block
1420: 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 61  quote><pre>.** a
1430: 73 73 65 72 74 28 20 73 71 6c 69 74 65 33 5f 6c  ssert( sqlite3_l
1440: 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62 65 72  ibversion_number
1450: 28 29 3d 3d 53 51 4c 49 54 45 5f 56 45 52 53 49  ()==SQLITE_VERSI
1460: 4f 4e 5f 4e 55 4d 42 45 52 20 29 3b 0a 2a 2a 20  ON_NUMBER );.** 
1470: 61 73 73 65 72 74 28 20 73 74 72 63 6d 70 28 73  assert( strcmp(s
1480: 71 6c 69 74 65 33 5f 73 6f 75 72 63 65 69 64 28  qlite3_sourceid(
1490: 29 2c 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f  ),SQLITE_SOURCE_
14a0: 49 44 29 3d 3d 30 20 29 3b 0a 2a 2a 20 61 73 73  ID)==0 );.** ass
14b0: 65 72 74 28 20 73 74 72 63 6d 70 28 73 71 6c 69  ert( strcmp(sqli
14c0: 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29  te3_libversion()
14d0: 2c 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 29  ,SQLITE_VERSION)
14e0: 3d 3d 30 20 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e  ==0 );.** </pre>
14f0: 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a  </blockquote>)^.
1500: 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
1510: 65 33 5f 76 65 72 73 69 6f 6e 5b 5d 20 73 74 72  e3_version[] str
1520: 69 6e 67 20 63 6f 6e 73 74 61 6e 74 20 63 6f 6e  ing constant con
1530: 74 61 69 6e 73 20 74 68 65 20 74 65 78 74 20 6f  tains the text o
1540: 66 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f  f [SQLITE_VERSIO
1550: 4e 5d 0a 2a 2a 20 6d 61 63 72 6f 2e 20 20 5e 54  N].** macro.  ^T
1560: 68 65 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65  he sqlite3_libve
1570: 72 73 69 6f 6e 28 29 20 66 75 6e 63 74 69 6f 6e  rsion() function
1580: 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
1590: 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 74 6f 20  er to the.** to 
15a0: 74 68 65 20 73 71 6c 69 74 65 33 5f 76 65 72 73  the sqlite3_vers
15b0: 69 6f 6e 5b 5d 20 73 74 72 69 6e 67 20 63 6f 6e  ion[] string con
15c0: 73 74 61 6e 74 2e 20 20 54 68 65 20 73 71 6c 69  stant.  The sqli
15d0: 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29  te3_libversion()
15e0: 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  .** function is 
15f0: 70 72 6f 76 69 64 65 64 20 66 6f 72 20 75 73 65  provided for use
1600: 20 69 6e 20 44 4c 4c 73 20 73 69 6e 63 65 20 44   in DLLs since D
1610: 4c 4c 20 75 73 65 72 73 20 75 73 75 61 6c 6c 79  LL users usually
1620: 20 64 6f 20 6e 6f 74 20 68 61 76 65 0a 2a 2a 20   do not have.** 
1630: 64 69 72 65 63 74 20 61 63 63 65 73 73 20 74 6f  direct access to
1640: 20 73 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e 74   string constant
1650: 73 20 77 69 74 68 69 6e 20 74 68 65 20 44 4c 4c  s within the DLL
1660: 2e 20 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 74  .  ^The.** sqlit
1670: 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75  e3_libversion_nu
1680: 6d 62 65 72 28 29 20 66 75 6e 63 74 69 6f 6e 20  mber() function 
1690: 72 65 74 75 72 6e 73 20 61 6e 20 69 6e 74 65 67  returns an integ
16a0: 65 72 20 65 71 75 61 6c 20 74 6f 0a 2a 2a 20 5b  er equal to.** [
16b0: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e  SQLITE_VERSION_N
16c0: 55 4d 42 45 52 5d 2e 20 20 5e 54 68 65 20 73 71  UMBER].  ^The sq
16d0: 6c 69 74 65 33 5f 73 6f 75 72 63 65 69 64 28 29  lite3_sourceid()
16e0: 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e   function return
16f0: 73 20 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20  s .** a pointer 
1700: 74 6f 20 61 20 73 74 72 69 6e 67 20 63 6f 6e 73  to a string cons
1710: 74 61 6e 74 20 77 68 6f 73 65 20 76 61 6c 75 65  tant whose value
1720: 20 69 73 20 74 68 65 20 73 61 6d 65 20 61 73 20   is the same as 
1730: 74 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  the .** [SQLITE_
1740: 53 4f 55 52 43 45 5f 49 44 5d 20 43 20 70 72 65  SOURCE_ID] C pre
1750: 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 2e  processor macro.
1760: 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a  .**.** See also:
1770: 20 5b 73 71 6c 69 74 65 5f 76 65 72 73 69 6f 6e   [sqlite_version
1780: 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 5f  ()] and [sqlite_
1790: 73 6f 75 72 63 65 5f 69 64 28 29 5d 2e 0a 2a 2f  source_id()]..*/
17a0: 0a 53 51 4c 49 54 45 5f 45 58 54 45 52 4e 20 63  .SQLITE_EXTERN c
17b0: 6f 6e 73 74 20 63 68 61 72 20 73 71 6c 69 74 65  onst char sqlite
17c0: 33 5f 76 65 72 73 69 6f 6e 5b 5d 3b 0a 63 6f 6e  3_version[];.con
17d0: 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
17e0: 5f 6c 69 62 76 65 72 73 69 6f 6e 28 76 6f 69 64  _libversion(void
17f0: 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  );.const char *s
1800: 71 6c 69 74 65 33 5f 73 6f 75 72 63 65 69 64 28  qlite3_sourceid(
1810: 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74  void);.int sqlit
1820: 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75  e3_libversion_nu
1830: 6d 62 65 72 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a  mber(void);../*.
1840: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e  ** CAPI3REF: Run
1850: 2d 54 69 6d 65 20 4c 69 62 72 61 72 79 20 43 6f  -Time Library Co
1860: 6d 70 69 6c 61 74 69 6f 6e 20 4f 70 74 69 6f 6e  mpilation Option
1870: 73 20 44 69 61 67 6e 6f 73 74 69 63 73 0a 2a 2a  s Diagnostics.**
1880: 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
1890: 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75  _compileoption_u
18a0: 73 65 64 28 29 20 66 75 6e 63 74 69 6f 6e 20 72  sed() function r
18b0: 65 74 75 72 6e 73 20 30 20 6f 72 20 31 20 0a 2a  eturns 0 or 1 .*
18c0: 2a 20 69 6e 64 69 63 61 74 69 6e 67 20 77 68 65  * indicating whe
18d0: 74 68 65 72 20 74 68 65 20 73 70 65 63 69 66 69  ther the specifi
18e0: 65 64 20 6f 70 74 69 6f 6e 20 77 61 73 20 64 65  ed option was de
18f0: 66 69 6e 65 64 20 61 74 20 0a 2a 2a 20 63 6f 6d  fined at .** com
1900: 70 69 6c 65 20 74 69 6d 65 2e 20 20 5e 54 68 65  pile time.  ^The
1910: 20 53 51 4c 49 54 45 5f 20 70 72 65 66 69 78 20   SQLITE_ prefix 
1920: 6d 61 79 20 62 65 20 6f 6d 69 74 74 65 64 20 66  may be omitted f
1930: 72 6f 6d 20 74 68 65 20 0a 2a 2a 20 6f 70 74 69  rom the .** opti
1940: 6f 6e 20 6e 61 6d 65 20 70 61 73 73 65 64 20 74  on name passed t
1950: 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c  o sqlite3_compil
1960: 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28 29 2e 20  eoption_used(). 
1970: 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c   .**.** ^The sql
1980: 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69  ite3_compileopti
1990: 6f 6e 5f 67 65 74 28 29 20 66 75 6e 63 74 69 6f  on_get() functio
19a0: 6e 20 61 6c 6c 6f 77 73 20 69 74 65 72 61 74 69  n allows iterati
19b0: 6e 67 0a 2a 2a 20 6f 76 65 72 20 74 68 65 20 6c  ng.** over the l
19c0: 69 73 74 20 6f 66 20 6f 70 74 69 6f 6e 73 20 74  ist of options t
19d0: 68 61 74 20 77 65 72 65 20 64 65 66 69 6e 65 64  hat were defined
19e0: 20 61 74 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65   at compile time
19f0: 20 62 79 0a 2a 2a 20 72 65 74 75 72 6e 69 6e 67   by.** returning
1a00: 20 74 68 65 20 4e 2d 74 68 20 63 6f 6d 70 69 6c   the N-th compil
1a10: 65 20 74 69 6d 65 20 6f 70 74 69 6f 6e 20 73 74  e time option st
1a20: 72 69 6e 67 2e 20 20 5e 49 66 20 4e 20 69 73 20  ring.  ^If N is 
1a30: 6f 75 74 20 6f 66 20 72 61 6e 67 65 2c 0a 2a 2a  out of range,.**
1a40: 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65   sqlite3_compile
1a50: 6f 70 74 69 6f 6e 5f 67 65 74 28 29 20 72 65 74  option_get() ret
1a60: 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  urns a NULL poin
1a70: 74 65 72 2e 20 20 5e 54 68 65 20 53 51 4c 49 54  ter.  ^The SQLIT
1a80: 45 5f 20 0a 2a 2a 20 70 72 65 66 69 78 20 69 73  E_ .** prefix is
1a90: 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 61 6e   omitted from an
1aa0: 79 20 73 74 72 69 6e 67 73 20 72 65 74 75 72 6e  y strings return
1ab0: 65 64 20 62 79 20 0a 2a 2a 20 73 71 6c 69 74 65  ed by .** sqlite
1ac0: 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f  3_compileoption_
1ad0: 67 65 74 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 53 75  get()..**.** ^Su
1ae0: 70 70 6f 72 74 20 66 6f 72 20 74 68 65 20 64 69  pport for the di
1af0: 61 67 6e 6f 73 74 69 63 20 66 75 6e 63 74 69 6f  agnostic functio
1b00: 6e 73 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69  ns sqlite3_compi
1b10: 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28 29 0a  leoption_used().
1b20: 2a 2a 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63  ** and sqlite3_c
1b30: 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74  ompileoption_get
1b40: 28 29 20 6d 61 79 20 62 65 20 6f 6d 69 74 74 65  () may be omitte
1b50: 64 20 62 79 20 73 70 65 63 69 66 79 69 6e 67 20  d by specifying 
1b60: 74 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  the .** [SQLITE_
1b70: 4f 4d 49 54 5f 43 4f 4d 50 49 4c 45 4f 50 54 49  OMIT_COMPILEOPTI
1b80: 4f 4e 5f 44 49 41 47 53 5d 20 6f 70 74 69 6f 6e  ON_DIAGS] option
1b90: 20 61 74 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65   at compile time
1ba0: 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
1bb0: 3a 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20  : SQL functions 
1bc0: 5b 73 71 6c 69 74 65 5f 63 6f 6d 70 69 6c 65 6f  [sqlite_compileo
1bd0: 70 74 69 6f 6e 5f 75 73 65 64 28 29 5d 20 61 6e  ption_used()] an
1be0: 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 5f 63 6f 6d  d.** [sqlite_com
1bf0: 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29  pileoption_get()
1c00: 5d 20 61 6e 64 20 74 68 65 20 5b 63 6f 6d 70 69  ] and the [compi
1c10: 6c 65 5f 6f 70 74 69 6f 6e 73 20 70 72 61 67 6d  le_options pragm
1c20: 61 5d 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53  a]..*/.#ifndef S
1c30: 51 4c 49 54 45 5f 4f 4d 49 54 5f 43 4f 4d 50 49  QLITE_OMIT_COMPI
1c40: 4c 45 4f 50 54 49 4f 4e 5f 44 49 41 47 53 0a 69  LEOPTION_DIAGS.i
1c50: 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69  nt sqlite3_compi
1c60: 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28 63 6f  leoption_used(co
1c70: 6e 73 74 20 63 68 61 72 20 2a 7a 4f 70 74 4e 61  nst char *zOptNa
1c80: 6d 65 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20  me);.const char 
1c90: 2a 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65  *sqlite3_compile
1ca0: 6f 70 74 69 6f 6e 5f 67 65 74 28 69 6e 74 20 4e  option_get(int N
1cb0: 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a  );.#endif../*.**
1cc0: 20 43 41 50 49 33 52 45 46 3a 20 54 65 73 74 20   CAPI3REF: Test 
1cd0: 54 6f 20 53 65 65 20 49 66 20 54 68 65 20 4c 69  To See If The Li
1ce0: 62 72 61 72 79 20 49 73 20 54 68 72 65 61 64 73  brary Is Threads
1cf0: 61 66 65 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  afe.**.** ^The s
1d00: 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73 61 66  qlite3_threadsaf
1d10: 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 72 65 74  e() function ret
1d20: 75 72 6e 73 20 7a 65 72 6f 20 69 66 20 61 6e 64  urns zero if and
1d30: 20 6f 6e 6c 79 20 69 66 0a 2a 2a 20 53 51 4c 69   only if.** SQLi
1d40: 74 65 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20  te was compiled 
1d50: 77 69 74 68 20 6d 75 74 65 78 69 6e 67 20 63 6f  with mutexing co
1d60: 64 65 20 6f 6d 69 74 74 65 64 20 64 75 65 20 74  de omitted due t
1d70: 6f 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45  o the.** [SQLITE
1d80: 5f 54 48 52 45 41 44 53 41 46 45 5d 20 63 6f 6d  _THREADSAFE] com
1d90: 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
1da0: 20 62 65 69 6e 67 20 73 65 74 20 74 6f 20 30 2e   being set to 0.
1db0: 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 63 61  .**.** SQLite ca
1dc0: 6e 20 62 65 20 63 6f 6d 70 69 6c 65 64 20 77 69  n be compiled wi
1dd0: 74 68 20 6f 72 20 77 69 74 68 6f 75 74 20 6d 75  th or without mu
1de0: 74 65 78 65 73 2e 20 20 57 68 65 6e 0a 2a 2a 20  texes.  When.** 
1df0: 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45  the [SQLITE_THRE
1e00: 41 44 53 41 46 45 5d 20 43 20 70 72 65 70 72 6f  ADSAFE] C prepro
1e10: 63 65 73 73 6f 72 20 6d 61 63 72 6f 20 69 73 20  cessor macro is 
1e20: 31 20 6f 72 20 32 2c 20 6d 75 74 65 78 65 73 0a  1 or 2, mutexes.
1e30: 2a 2a 20 61 72 65 20 65 6e 61 62 6c 65 64 20 61  ** are enabled a
1e40: 6e 64 20 53 51 4c 69 74 65 20 69 73 20 74 68 72  nd SQLite is thr
1e50: 65 61 64 73 61 66 65 2e 20 20 57 68 65 6e 20 74  eadsafe.  When t
1e60: 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 54 48  he.** [SQLITE_TH
1e70: 52 45 41 44 53 41 46 45 5d 20 6d 61 63 72 6f 20  READSAFE] macro 
1e80: 69 73 20 30 2c 20 0a 2a 2a 20 74 68 65 20 6d 75  is 0, .** the mu
1e90: 74 65 78 65 73 20 61 72 65 20 6f 6d 69 74 74 65  texes are omitte
1ea0: 64 2e 20 20 57 69 74 68 6f 75 74 20 74 68 65 20  d.  Without the 
1eb0: 6d 75 74 65 78 65 73 2c 20 69 74 20 69 73 20 6e  mutexes, it is n
1ec0: 6f 74 20 73 61 66 65 0a 2a 2a 20 74 6f 20 75 73  ot safe.** to us
1ed0: 65 20 53 51 4c 69 74 65 20 63 6f 6e 63 75 72 72  e SQLite concurr
1ee0: 65 6e 74 6c 79 20 66 72 6f 6d 20 6d 6f 72 65 20  ently from more 
1ef0: 74 68 61 6e 20 6f 6e 65 20 74 68 72 65 61 64 2e  than one thread.
1f00: 0a 2a 2a 0a 2a 2a 20 45 6e 61 62 6c 69 6e 67 20  .**.** Enabling 
1f10: 6d 75 74 65 78 65 73 20 69 6e 63 75 72 73 20 61  mutexes incurs a
1f20: 20 6d 65 61 73 75 72 61 62 6c 65 20 70 65 72 66   measurable perf
1f30: 6f 72 6d 61 6e 63 65 20 70 65 6e 61 6c 74 79 2e  ormance penalty.
1f40: 0a 2a 2a 20 53 6f 20 69 66 20 73 70 65 65 64 20  .** So if speed 
1f50: 69 73 20 6f 66 20 75 74 6d 6f 73 74 20 69 6d 70  is of utmost imp
1f60: 6f 72 74 61 6e 63 65 2c 20 69 74 20 6d 61 6b 65  ortance, it make
1f70: 73 20 73 65 6e 73 65 20 74 6f 20 64 69 73 61 62  s sense to disab
1f80: 6c 65 0a 2a 2a 20 74 68 65 20 6d 75 74 65 78 65  le.** the mutexe
1f90: 73 2e 20 20 42 75 74 20 66 6f 72 20 6d 61 78 69  s.  But for maxi
1fa0: 6d 75 6d 20 73 61 66 65 74 79 2c 20 6d 75 74 65  mum safety, mute
1fb0: 78 65 73 20 73 68 6f 75 6c 64 20 62 65 20 65 6e  xes should be en
1fc0: 61 62 6c 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 64  abled..** ^The d
1fd0: 65 66 61 75 6c 74 20 62 65 68 61 76 69 6f 72 20  efault behavior 
1fe0: 69 73 20 66 6f 72 20 6d 75 74 65 78 65 73 20 74  is for mutexes t
1ff0: 6f 20 62 65 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a  o be enabled..**
2000: 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61  .** This interfa
2010: 63 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 62  ce can be used b
2020: 79 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  y an application
2030: 20 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 74 68   to make sure th
2040: 61 74 20 74 68 65 0a 2a 2a 20 76 65 72 73 69 6f  at the.** versio
2050: 6e 20 6f 66 20 53 51 4c 69 74 65 20 74 68 61 74  n of SQLite that
2060: 20 69 74 20 69 73 20 6c 69 6e 6b 69 6e 67 20 61   it is linking a
2070: 67 61 69 6e 73 74 20 77 61 73 20 63 6f 6d 70 69  gainst was compi
2080: 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20  led with.** the 
2090: 64 65 73 69 72 65 64 20 73 65 74 74 69 6e 67 20  desired setting 
20a0: 6f 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54  of the [SQLITE_T
20b0: 48 52 45 41 44 53 41 46 45 5d 20 6d 61 63 72 6f  HREADSAFE] macro
20c0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74  ..**.** This int
20d0: 65 72 66 61 63 65 20 6f 6e 6c 79 20 72 65 70 6f  erface only repo
20e0: 72 74 73 20 6f 6e 20 74 68 65 20 63 6f 6d 70 69  rts on the compi
20f0: 6c 65 2d 74 69 6d 65 20 6d 75 74 65 78 20 73 65  le-time mutex se
2100: 74 74 69 6e 67 0a 2a 2a 20 6f 66 20 74 68 65 20  tting.** of the 
2110: 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41  [SQLITE_THREADSA
2120: 46 45 5d 20 66 6c 61 67 2e 20 20 49 66 20 53 51  FE] flag.  If SQ
2130: 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  Lite is compiled
2140: 20 77 69 74 68 0a 2a 2a 20 53 51 4c 49 54 45 5f   with.** SQLITE_
2150: 54 48 52 45 41 44 53 41 46 45 3d 31 20 6f 72 20  THREADSAFE=1 or 
2160: 3d 32 20 74 68 65 6e 20 6d 75 74 65 78 65 73 20  =2 then mutexes 
2170: 61 72 65 20 65 6e 61 62 6c 65 64 20 62 79 20 64  are enabled by d
2180: 65 66 61 75 6c 74 20 62 75 74 0a 2a 2a 20 63 61  efault but.** ca
2190: 6e 20 62 65 20 66 75 6c 6c 79 20 6f 72 20 70 61  n be fully or pa
21a0: 72 74 69 61 6c 6c 79 20 64 69 73 61 62 6c 65 64  rtially disabled
21b0: 20 75 73 69 6e 67 20 61 20 63 61 6c 6c 20 74 6f   using a call to
21c0: 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
21d0: 28 29 5d 0a 2a 2a 20 77 69 74 68 20 74 68 65 20  ()].** with the 
21e0: 76 65 72 62 73 20 5b 53 51 4c 49 54 45 5f 43 4f  verbs [SQLITE_CO
21f0: 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41  NFIG_SINGLETHREA
2200: 44 5d 2c 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  D], [SQLITE_CONF
2210: 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d 2c  IG_MULTITHREAD],
2220: 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43  .** or [SQLITE_C
2230: 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44  ONFIG_SERIALIZED
2240: 5d 2e 20 20 5e 28 54 68 65 20 72 65 74 75 72 6e  ].  ^(The return
2250: 20 76 61 6c 75 65 20 6f 66 20 74 68 65 0a 2a 2a   value of the.**
2260: 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73   sqlite3_threads
2270: 61 66 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 73  afe() function s
2280: 68 6f 77 73 20 6f 6e 6c 79 20 74 68 65 20 63 6f  hows only the co
2290: 6d 70 69 6c 65 2d 74 69 6d 65 20 73 65 74 74 69  mpile-time setti
22a0: 6e 67 20 6f 66 0a 2a 2a 20 74 68 72 65 61 64 20  ng of.** thread 
22b0: 73 61 66 65 74 79 2c 20 6e 6f 74 20 61 6e 79 20  safety, not any 
22c0: 72 75 6e 2d 74 69 6d 65 20 63 68 61 6e 67 65 73  run-time changes
22d0: 20 74 6f 20 74 68 61 74 20 73 65 74 74 69 6e 67   to that setting
22e0: 20 6d 61 64 65 20 62 79 0a 2a 2a 20 73 71 6c 69   made by.** sqli
22f0: 74 65 33 5f 63 6f 6e 66 69 67 28 29 2e 20 49 6e  te3_config(). In
2300: 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68   other words, th
2310: 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66  e return value f
2320: 72 6f 6d 20 73 71 6c 69 74 65 33 5f 74 68 72 65  rom sqlite3_thre
2330: 61 64 73 61 66 65 28 29 0a 2a 2a 20 69 73 20 75  adsafe().** is u
2340: 6e 63 68 61 6e 67 65 64 20 62 79 20 63 61 6c 6c  nchanged by call
2350: 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6e  s to sqlite3_con
2360: 66 69 67 28 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53  fig().)^.**.** S
2370: 65 65 20 74 68 65 20 5b 74 68 72 65 61 64 69 6e  ee the [threadin
2380: 67 20 6d 6f 64 65 5d 20 64 6f 63 75 6d 65 6e 74  g mode] document
2390: 61 74 69 6f 6e 20 66 6f 72 20 61 64 64 69 74 69  ation for additi
23a0: 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  onal information
23b0: 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
23c0: 5f 74 68 72 65 61 64 73 61 66 65 28 76 6f 69 64  _threadsafe(void
23d0: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
23e0: 45 46 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e  EF: Database Con
23f0: 6e 65 63 74 69 6f 6e 20 48 61 6e 64 6c 65 0a 2a  nection Handle.*
2400: 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 64 61 74  * KEYWORDS: {dat
2410: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
2420: 7d 20 7b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  } {database conn
2430: 65 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 45  ections}.**.** E
2440: 61 63 68 20 6f 70 65 6e 20 53 51 4c 69 74 65 20  ach open SQLite 
2450: 64 61 74 61 62 61 73 65 20 69 73 20 72 65 70 72  database is repr
2460: 65 73 65 6e 74 65 64 20 62 79 20 61 20 70 6f 69  esented by a poi
2470: 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61  nter to an insta
2480: 6e 63 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6f 70  nce of.** the op
2490: 61 71 75 65 20 73 74 72 75 63 74 75 72 65 20 6e  aque structure n
24a0: 61 6d 65 64 20 22 73 71 6c 69 74 65 33 22 2e 20  amed "sqlite3". 
24b0: 20 49 74 20 69 73 20 75 73 65 66 75 6c 20 74 6f   It is useful to
24c0: 20 74 68 69 6e 6b 20 6f 66 20 61 6e 20 73 71 6c   think of an sql
24d0: 69 74 65 33 0a 2a 2a 20 70 6f 69 6e 74 65 72 20  ite3.** pointer 
24e0: 61 73 20 61 6e 20 6f 62 6a 65 63 74 2e 20 20 54  as an object.  T
24f0: 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  he [sqlite3_open
2500: 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70  ()], [sqlite3_op
2510: 65 6e 31 36 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20  en16()], and.** 
2520: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32  [sqlite3_open_v2
2530: 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 20 61  ()] interfaces a
2540: 72 65 20 69 74 73 20 63 6f 6e 73 74 72 75 63 74  re its construct
2550: 6f 72 73 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65  ors, and [sqlite
2560: 33 5f 63 6c 6f 73 65 28 29 5d 0a 2a 2a 20 61 6e  3_close()].** an
2570: 64 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  d [sqlite3_close
2580: 5f 76 32 28 29 5d 20 61 72 65 20 69 74 73 20 64  _v2()] are its d
2590: 65 73 74 72 75 63 74 6f 72 73 2e 20 20 54 68 65  estructors.  The
25a0: 72 65 20 61 72 65 20 6d 61 6e 79 20 6f 74 68 65  re are many othe
25b0: 72 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20  r.** interfaces 
25c0: 28 73 75 63 68 20 61 73 0a 2a 2a 20 5b 73 71 6c  (such as.** [sql
25d0: 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
25e0: 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  )], [sqlite3_cre
25f0: 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 2c  ate_function()],
2600: 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   and.** [sqlite3
2610: 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d  _busy_timeout()]
2620: 20 74 6f 20 6e 61 6d 65 20 62 75 74 20 74 68 72   to name but thr
2630: 65 65 29 20 74 68 61 74 20 61 72 65 20 6d 65 74  ee) that are met
2640: 68 6f 64 73 20 6f 6e 20 61 6e 0a 2a 2a 20 73 71  hods on an.** sq
2650: 6c 69 74 65 33 20 6f 62 6a 65 63 74 2e 0a 2a 2f  lite3 object..*/
2660: 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
2670: 73 71 6c 69 74 65 33 20 73 71 6c 69 74 65 33 3b  sqlite3 sqlite3;
2680: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2690: 3a 20 36 34 2d 42 69 74 20 49 6e 74 65 67 65 72  : 64-Bit Integer
26a0: 20 54 79 70 65 73 0a 2a 2a 20 4b 45 59 57 4f 52   Types.** KEYWOR
26b0: 44 53 3a 20 73 71 6c 69 74 65 5f 69 6e 74 36 34  DS: sqlite_int64
26c0: 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 0a 2a   sqlite_uint64.*
26d0: 2a 0a 2a 2a 20 42 65 63 61 75 73 65 20 74 68 65  *.** Because the
26e0: 72 65 20 69 73 20 6e 6f 20 63 72 6f 73 73 2d 70  re is no cross-p
26f0: 6c 61 74 66 6f 72 6d 20 77 61 79 20 74 6f 20 73  latform way to s
2700: 70 65 63 69 66 79 20 36 34 2d 62 69 74 20 69 6e  pecify 64-bit in
2710: 74 65 67 65 72 20 74 79 70 65 73 0a 2a 2a 20 53  teger types.** S
2720: 51 4c 69 74 65 20 69 6e 63 6c 75 64 65 73 20 74  QLite includes t
2730: 79 70 65 64 65 66 73 20 66 6f 72 20 36 34 2d 62  ypedefs for 64-b
2740: 69 74 20 73 69 67 6e 65 64 20 61 6e 64 20 75 6e  it signed and un
2750: 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 73 2e  signed integers.
2760: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
2770: 65 33 5f 69 6e 74 36 34 20 61 6e 64 20 73 71 6c  e3_int64 and sql
2780: 69 74 65 33 5f 75 69 6e 74 36 34 20 61 72 65 20  ite3_uint64 are 
2790: 74 68 65 20 70 72 65 66 65 72 72 65 64 20 74 79  the preferred ty
27a0: 70 65 20 64 65 66 69 6e 69 74 69 6f 6e 73 2e 0a  pe definitions..
27b0: 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 5f 69 6e  ** The sqlite_in
27c0: 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 5f 75  t64 and sqlite_u
27d0: 69 6e 74 36 34 20 74 79 70 65 73 20 61 72 65 20  int64 types are 
27e0: 73 75 70 70 6f 72 74 65 64 20 66 6f 72 20 62 61  supported for ba
27f0: 63 6b 77 61 72 64 73 0a 2a 2a 20 63 6f 6d 70 61  ckwards.** compa
2800: 74 69 62 69 6c 69 74 79 20 6f 6e 6c 79 2e 0a 2a  tibility only..*
2810: 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
2820: 33 5f 69 6e 74 36 34 20 61 6e 64 20 73 71 6c 69  3_int64 and sqli
2830: 74 65 5f 69 6e 74 36 34 20 74 79 70 65 73 20 63  te_int64 types c
2840: 61 6e 20 73 74 6f 72 65 20 69 6e 74 65 67 65 72  an store integer
2850: 20 76 61 6c 75 65 73 0a 2a 2a 20 62 65 74 77 65   values.** betwe
2860: 65 6e 20 2d 39 32 32 33 33 37 32 30 33 36 38 35  en -922337203685
2870: 34 37 37 35 38 30 38 20 61 6e 64 20 2b 39 32 32  4775808 and +922
2880: 33 33 37 32 30 33 36 38 35 34 37 37 35 38 30 37  3372036854775807
2890: 20 69 6e 63 6c 75 73 69 76 65 2e 20 20 5e 54 68   inclusive.  ^Th
28a0: 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75 69 6e  e.** sqlite3_uin
28b0: 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 5f 75  t64 and sqlite_u
28c0: 69 6e 74 36 34 20 74 79 70 65 73 20 63 61 6e 20  int64 types can 
28d0: 73 74 6f 72 65 20 69 6e 74 65 67 65 72 20 76 61  store integer va
28e0: 6c 75 65 73 20 0a 2a 2a 20 62 65 74 77 65 65 6e  lues .** between
28f0: 20 30 20 61 6e 64 20 2b 31 38 34 34 36 37 34 34   0 and +18446744
2900: 30 37 33 37 30 39 35 35 31 36 31 35 20 69 6e 63  073709551615 inc
2910: 6c 75 73 69 76 65 2e 0a 2a 2f 0a 23 69 66 64 65  lusive..*/.#ifde
2920: 66 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54  f SQLITE_INT64_T
2930: 59 50 45 0a 20 20 74 79 70 65 64 65 66 20 53 51  YPE.  typedef SQ
2940: 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 45 20  LITE_INT64_TYPE 
2950: 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a 23 20  sqlite_int64;.# 
2960: 69 66 64 65 66 20 53 51 4c 49 54 45 5f 55 49 4e  ifdef SQLITE_UIN
2970: 54 36 34 5f 54 59 50 45 0a 20 20 20 20 74 79 70  T64_TYPE.    typ
2980: 65 64 65 66 20 53 51 4c 49 54 45 5f 55 49 4e 54  edef SQLITE_UINT
2990: 36 34 5f 54 59 50 45 20 73 71 6c 69 74 65 5f 75  64_TYPE sqlite_u
29a0: 69 6e 74 36 34 3b 0a 23 20 65 6c 73 65 20 20 0a  int64;.# else  .
29b0: 20 20 20 20 74 79 70 65 64 65 66 20 75 6e 73 69      typedef unsi
29c0: 67 6e 65 64 20 53 51 4c 49 54 45 5f 49 4e 54 36  gned SQLITE_INT6
29d0: 34 5f 54 59 50 45 20 73 71 6c 69 74 65 5f 75 69  4_TYPE sqlite_ui
29e0: 6e 74 36 34 3b 0a 23 20 65 6e 64 69 66 0a 23 65  nt64;.# endif.#e
29f0: 6c 69 66 20 64 65 66 69 6e 65 64 28 5f 4d 53 43  lif defined(_MSC
2a00: 5f 56 45 52 29 20 7c 7c 20 64 65 66 69 6e 65 64  _VER) || defined
2a10: 28 5f 5f 42 4f 52 4c 41 4e 44 43 5f 5f 29 0a 20  (__BORLANDC__). 
2a20: 20 74 79 70 65 64 65 66 20 5f 5f 69 6e 74 36 34   typedef __int64
2a30: 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a 20   sqlite_int64;. 
2a40: 20 74 79 70 65 64 65 66 20 75 6e 73 69 67 6e 65   typedef unsigne
2a50: 64 20 5f 5f 69 6e 74 36 34 20 73 71 6c 69 74 65  d __int64 sqlite
2a60: 5f 75 69 6e 74 36 34 3b 0a 23 65 6c 73 65 0a 20  _uint64;.#else. 
2a70: 20 74 79 70 65 64 65 66 20 6c 6f 6e 67 20 6c 6f   typedef long lo
2a80: 6e 67 20 69 6e 74 20 73 71 6c 69 74 65 5f 69 6e  ng int sqlite_in
2a90: 74 36 34 3b 0a 20 20 74 79 70 65 64 65 66 20 75  t64;.  typedef u
2aa0: 6e 73 69 67 6e 65 64 20 6c 6f 6e 67 20 6c 6f 6e  nsigned long lon
2ab0: 67 20 69 6e 74 20 73 71 6c 69 74 65 5f 75 69 6e  g int sqlite_uin
2ac0: 74 36 34 3b 0a 23 65 6e 64 69 66 0a 74 79 70 65  t64;.#endif.type
2ad0: 64 65 66 20 73 71 6c 69 74 65 5f 69 6e 74 36 34  def sqlite_int64
2ae0: 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 3b 0a   sqlite3_int64;.
2af0: 74 79 70 65 64 65 66 20 73 71 6c 69 74 65 5f 75  typedef sqlite_u
2b00: 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 75 69  int64 sqlite3_ui
2b10: 6e 74 36 34 3b 0a 0a 2f 2a 0a 2a 2a 20 49 66 20  nt64;../*.** If 
2b20: 63 6f 6d 70 69 6c 69 6e 67 20 66 6f 72 20 61 20  compiling for a 
2b30: 70 72 6f 63 65 73 73 6f 72 20 74 68 61 74 20 6c  processor that l
2b40: 61 63 6b 73 20 66 6c 6f 61 74 69 6e 67 20 70 6f  acks floating po
2b50: 69 6e 74 20 73 75 70 70 6f 72 74 2c 0a 2a 2a 20  int support,.** 
2b60: 73 75 62 73 74 69 74 75 74 65 20 69 6e 74 65 67  substitute integ
2b70: 65 72 20 66 6f 72 20 66 6c 6f 61 74 69 6e 67 2d  er for floating-
2b80: 70 6f 69 6e 74 2e 0a 2a 2f 0a 23 69 66 64 65 66  point..*/.#ifdef
2b90: 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 46 4c 4f   SQLITE_OMIT_FLO
2ba0: 41 54 49 4e 47 5f 50 4f 49 4e 54 0a 23 20 64 65  ATING_POINT.# de
2bb0: 66 69 6e 65 20 64 6f 75 62 6c 65 20 73 71 6c 69  fine double sqli
2bc0: 74 65 33 5f 69 6e 74 36 34 0a 23 65 6e 64 69 66  te3_int64.#endif
2bd0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2be0: 3a 20 43 6c 6f 73 69 6e 67 20 41 20 44 61 74 61  : Closing A Data
2bf0: 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 0a  base Connection.
2c00: 2a 2a 20 44 45 53 54 52 55 43 54 4f 52 3a 20 73  ** DESTRUCTOR: s
2c10: 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68  qlite3.**.** ^Th
2c20: 65 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28  e sqlite3_close(
2c30: 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6c  ) and sqlite3_cl
2c40: 6f 73 65 5f 76 32 28 29 20 72 6f 75 74 69 6e 65  ose_v2() routine
2c50: 73 20 61 72 65 20 64 65 73 74 72 75 63 74 6f 72  s are destructor
2c60: 73 0a 2a 2a 20 66 6f 72 20 74 68 65 20 5b 73 71  s.** for the [sq
2c70: 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 2e 0a 2a  lite3] object..*
2c80: 2a 20 5e 43 61 6c 6c 73 20 74 6f 20 73 71 6c 69  * ^Calls to sqli
2c90: 74 65 33 5f 63 6c 6f 73 65 28 29 20 61 6e 64 20  te3_close() and 
2ca0: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32  sqlite3_close_v2
2cb0: 28 29 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  () return [SQLIT
2cc0: 45 5f 4f 4b 5d 20 69 66 0a 2a 2a 20 74 68 65 20  E_OK] if.** the 
2cd0: 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74  [sqlite3] object
2ce0: 20 69 73 20 73 75 63 63 65 73 73 66 75 6c 6c 79   is successfully
2cf0: 20 64 65 73 74 72 6f 79 65 64 20 61 6e 64 20 61   destroyed and a
2d00: 6c 6c 20 61 73 73 6f 63 69 61 74 65 64 0a 2a 2a  ll associated.**
2d10: 20 72 65 73 6f 75 72 63 65 73 20 61 72 65 20 64   resources are d
2d20: 65 61 6c 6c 6f 63 61 74 65 64 2e 0a 2a 2a 0a 2a  eallocated..**.*
2d30: 2a 20 5e 49 66 20 74 68 65 20 64 61 74 61 62 61  * ^If the databa
2d40: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  se connection is
2d50: 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
2d60: 20 75 6e 66 69 6e 61 6c 69 7a 65 64 20 70 72 65   unfinalized pre
2d70: 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65  pared.** stateme
2d80: 6e 74 73 20 6f 72 20 75 6e 66 69 6e 69 73 68 65  nts or unfinishe
2d90: 64 20 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70  d sqlite3_backup
2da0: 20 6f 62 6a 65 63 74 73 20 74 68 65 6e 20 73 71   objects then sq
2db0: 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 0a 2a 2a  lite3_close().**
2dc0: 20 77 69 6c 6c 20 6c 65 61 76 65 20 74 68 65 20   will leave the 
2dd0: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
2de0: 69 6f 6e 20 6f 70 65 6e 20 61 6e 64 20 72 65 74  ion open and ret
2df0: 75 72 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  urn [SQLITE_BUSY
2e00: 5d 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65  ]..** ^If sqlite
2e10: 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 69 73 20  3_close_v2() is 
2e20: 63 61 6c 6c 65 64 20 77 69 74 68 20 75 6e 66 69  called with unfi
2e30: 6e 61 6c 69 7a 65 64 20 70 72 65 70 61 72 65 64  nalized prepared
2e40: 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 61   statements.** a
2e50: 6e 64 2f 6f 72 20 75 6e 66 69 6e 69 73 68 65 64  nd/or unfinished
2e60: 20 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 73   sqlite3_backups
2e70: 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62  , then the datab
2e80: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62  ase connection b
2e90: 65 63 6f 6d 65 73 0a 2a 2a 20 61 6e 20 75 6e 75  ecomes.** an unu
2ea0: 73 61 62 6c 65 20 22 7a 6f 6d 62 69 65 22 20 77  sable "zombie" w
2eb0: 68 69 63 68 20 77 69 6c 6c 20 61 75 74 6f 6d 61  hich will automa
2ec0: 74 69 63 61 6c 6c 79 20 62 65 20 64 65 61 6c 6c  tically be deall
2ed0: 6f 63 61 74 65 64 20 77 68 65 6e 20 74 68 65 0a  ocated when the.
2ee0: 2a 2a 20 6c 61 73 74 20 70 72 65 70 61 72 65 64  ** last prepared
2ef0: 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 66 69   statement is fi
2f00: 6e 61 6c 69 7a 65 64 20 6f 72 20 74 68 65 20 6c  nalized or the l
2f10: 61 73 74 20 73 71 6c 69 74 65 33 5f 62 61 63 6b  ast sqlite3_back
2f20: 75 70 20 69 73 0a 2a 2a 20 66 69 6e 69 73 68 65  up is.** finishe
2f30: 64 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f  d.  The sqlite3_
2f40: 63 6c 6f 73 65 5f 76 32 28 29 20 69 6e 74 65 72  close_v2() inter
2f50: 66 61 63 65 20 69 73 20 69 6e 74 65 6e 64 65 64  face is intended
2f60: 20 66 6f 72 20 75 73 65 20 77 69 74 68 0a 2a 2a   for use with.**
2f70: 20 68 6f 73 74 20 6c 61 6e 67 75 61 67 65 73 20   host languages 
2f80: 74 68 61 74 20 61 72 65 20 67 61 72 62 61 67 65  that are garbage
2f90: 20 63 6f 6c 6c 65 63 74 65 64 2c 20 61 6e 64 20   collected, and 
2fa0: 77 68 65 72 65 20 74 68 65 20 6f 72 64 65 72 20  where the order 
2fb0: 69 6e 20 77 68 69 63 68 0a 2a 2a 20 64 65 73 74  in which.** dest
2fc0: 72 75 63 74 6f 72 73 20 61 72 65 20 63 61 6c 6c  ructors are call
2fd0: 65 64 20 69 73 20 61 72 62 69 74 72 61 72 79 2e  ed is arbitrary.
2fe0: 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69  .**.** Applicati
2ff0: 6f 6e 73 20 73 68 6f 75 6c 64 20 5b 73 71 6c 69  ons should [sqli
3000: 74 65 33 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 66  te3_finalize | f
3010: 69 6e 61 6c 69 7a 65 5d 20 61 6c 6c 20 5b 70 72  inalize] all [pr
3020: 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
3030: 73 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  s],.** [sqlite3_
3040: 62 6c 6f 62 5f 63 6c 6f 73 65 20 7c 20 63 6c 6f  blob_close | clo
3050: 73 65 5d 20 61 6c 6c 20 5b 42 4c 4f 42 20 68 61  se] all [BLOB ha
3060: 6e 64 6c 65 73 5d 2c 20 61 6e 64 20 0a 2a 2a 20  ndles], and .** 
3070: 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5f  [sqlite3_backup_
3080: 66 69 6e 69 73 68 20 7c 20 66 69 6e 69 73 68 5d  finish | finish]
3090: 20 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 62 61   all [sqlite3_ba
30a0: 63 6b 75 70 5d 20 6f 62 6a 65 63 74 73 20 61 73  ckup] objects as
30b0: 73 6f 63 69 61 74 65 64 0a 2a 2a 20 77 69 74 68  sociated.** with
30c0: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f   the [sqlite3] o
30d0: 62 6a 65 63 74 20 70 72 69 6f 72 20 74 6f 20 61  bject prior to a
30e0: 74 74 65 6d 70 74 69 6e 67 20 74 6f 20 63 6c 6f  ttempting to clo
30f0: 73 65 20 74 68 65 20 6f 62 6a 65 63 74 2e 20 20  se the object.  
3100: 5e 49 66 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63  ^If.** sqlite3_c
3110: 6c 6f 73 65 5f 76 32 28 29 20 69 73 20 63 61 6c  lose_v2() is cal
3120: 6c 65 64 20 6f 6e 20 61 20 5b 64 61 74 61 62 61  led on a [databa
3130: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74  se connection] t
3140: 68 61 74 20 73 74 69 6c 6c 20 68 61 73 0a 2a 2a  hat still has.**
3150: 20 6f 75 74 73 74 61 6e 64 69 6e 67 20 5b 70 72   outstanding [pr
3160: 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
3170: 73 5d 2c 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65  s], [BLOB handle
3180: 73 5d 2c 20 61 6e 64 2f 6f 72 0a 2a 2a 20 5b 73  s], and/or.** [s
3190: 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5d 20 6f  qlite3_backup] o
31a0: 62 6a 65 63 74 73 20 74 68 65 6e 20 69 74 20 72  bjects then it r
31b0: 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f  eturns [SQLITE_O
31c0: 4b 5d 20 61 6e 64 20 74 68 65 20 64 65 61 6c 6c  K] and the deall
31d0: 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 72 65  ocation.** of re
31e0: 73 6f 75 72 63 65 73 20 69 73 20 64 65 66 65 72  sources is defer
31f0: 72 65 64 20 75 6e 74 69 6c 20 61 6c 6c 20 5b 70  red until all [p
3200: 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
3210: 74 73 5d 2c 20 5b 42 4c 4f 42 20 68 61 6e 64 6c  ts], [BLOB handl
3220: 65 73 5d 2c 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c  es],.** and [sql
3230: 69 74 65 33 5f 62 61 63 6b 75 70 5d 20 6f 62 6a  ite3_backup] obj
3240: 65 63 74 73 20 61 72 65 20 61 6c 73 6f 20 64 65  ects are also de
3250: 73 74 72 6f 79 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  stroyed..**.** ^
3260: 49 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5d 20  If an [sqlite3] 
3270: 6f 62 6a 65 63 74 20 69 73 20 64 65 73 74 72 6f  object is destro
3280: 79 65 64 20 77 68 69 6c 65 20 61 20 74 72 61 6e  yed while a tran
3290: 73 61 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e 2c  saction is open,
32a0: 0a 2a 2a 20 74 68 65 20 74 72 61 6e 73 61 63 74  .** the transact
32b0: 69 6f 6e 20 69 73 20 61 75 74 6f 6d 61 74 69 63  ion is automatic
32c0: 61 6c 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b  ally rolled back
32d0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 43 20 70 61  ..**.** The C pa
32e0: 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69  rameter to [sqli
32f0: 74 65 33 5f 63 6c 6f 73 65 28 43 29 5d 20 61 6e  te3_close(C)] an
3300: 64 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  d [sqlite3_close
3310: 5f 76 32 28 43 29 5d 0a 2a 2a 20 6d 75 73 74 20  _v2(C)].** must 
3320: 62 65 20 65 69 74 68 65 72 20 61 20 4e 55 4c 4c  be either a NULL
3330: 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 6f 72 20 61  .** pointer or a
3340: 6e 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65  n [sqlite3] obje
3350: 63 74 20 70 6f 69 6e 74 65 72 20 6f 62 74 61 69  ct pointer obtai
3360: 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c  ned.** from [sql
3370: 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73  ite3_open()], [s
3380: 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d  qlite3_open16()]
3390: 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  , or.** [sqlite3
33a0: 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c 20 61 6e 64  _open_v2()], and
33b0: 20 6e 6f 74 20 70 72 65 76 69 6f 75 73 6c 79 20   not previously 
33c0: 63 6c 6f 73 65 64 2e 0a 2a 2a 20 5e 43 61 6c 6c  closed..** ^Call
33d0: 69 6e 67 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73  ing sqlite3_clos
33e0: 65 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63  e() or sqlite3_c
33f0: 6c 6f 73 65 5f 76 32 28 29 20 77 69 74 68 20 61  lose_v2() with a
3400: 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a   NULL pointer.**
3410: 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 68   argument is a h
3420: 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a  armless no-op..*
3430: 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c  /.int sqlite3_cl
3440: 6f 73 65 28 73 71 6c 69 74 65 33 2a 29 3b 0a 69  ose(sqlite3*);.i
3450: 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  nt sqlite3_close
3460: 5f 76 32 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a  _v2(sqlite3*);..
3470: 2f 2a 0a 2a 2a 20 54 68 65 20 74 79 70 65 20 66  /*.** The type f
3480: 6f 72 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75  or a callback fu
3490: 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 54 68 69 73 20  nction..** This 
34a0: 69 73 20 6c 65 67 61 63 79 20 61 6e 64 20 64 65  is legacy and de
34b0: 70 72 65 63 61 74 65 64 2e 20 20 49 74 20 69 73  precated.  It is
34c0: 20 69 6e 63 6c 75 64 65 64 20 66 6f 72 20 68 69   included for hi
34d0: 73 74 6f 72 69 63 61 6c 0a 2a 2a 20 63 6f 6d 70  storical.** comp
34e0: 61 74 69 62 69 6c 69 74 79 20 61 6e 64 20 69 73  atibility and is
34f0: 20 6e 6f 74 20 64 6f 63 75 6d 65 6e 74 65 64 2e   not documented.
3500: 0a 2a 2f 0a 74 79 70 65 64 65 66 20 69 6e 74 20  .*/.typedef int 
3510: 28 2a 73 71 6c 69 74 65 33 5f 63 61 6c 6c 62 61  (*sqlite3_callba
3520: 63 6b 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68  ck)(void*,int,ch
3530: 61 72 2a 2a 2c 20 63 68 61 72 2a 2a 29 3b 0a 0a  ar**, char**);..
3540: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
3550: 4f 6e 65 2d 53 74 65 70 20 51 75 65 72 79 20 45  One-Step Query E
3560: 78 65 63 75 74 69 6f 6e 20 49 6e 74 65 72 66 61  xecution Interfa
3570: 63 65 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  ce.** METHOD: sq
3580: 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 54 68 65 20  lite3.**.** The 
3590: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69  sqlite3_exec() i
35a0: 6e 74 65 72 66 61 63 65 20 69 73 20 61 20 63 6f  nterface is a co
35b0: 6e 76 65 6e 69 65 6e 63 65 20 77 72 61 70 70 65  nvenience wrappe
35c0: 72 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b 73 71 6c  r around.** [sql
35d0: 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
35e0: 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  )], [sqlite3_ste
35f0: 70 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74  p()], and [sqlit
3600: 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 2c 0a  e3_finalize()],.
3610: 2a 2a 20 74 68 61 74 20 61 6c 6c 6f 77 73 20 61  ** that allows a
3620: 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f  n application to
3630: 20 72 75 6e 20 6d 75 6c 74 69 70 6c 65 20 73 74   run multiple st
3640: 61 74 65 6d 65 6e 74 73 20 6f 66 20 53 51 4c 0a  atements of SQL.
3650: 2a 2a 20 77 69 74 68 6f 75 74 20 68 61 76 69 6e  ** without havin
3660: 67 20 74 6f 20 75 73 65 20 61 20 6c 6f 74 20 6f  g to use a lot o
3670: 66 20 43 20 63 6f 64 65 2e 20 0a 2a 2a 0a 2a 2a  f C code. .**.**
3680: 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78   ^The sqlite3_ex
3690: 65 63 28 29 20 69 6e 74 65 72 66 61 63 65 20 72  ec() interface r
36a0: 75 6e 73 20 7a 65 72 6f 20 6f 72 20 6d 6f 72 65  uns zero or more
36b0: 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 2c 0a   UTF-8 encoded,.
36c0: 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70  ** semicolon-sep
36d0: 61 72 61 74 65 20 53 51 4c 20 73 74 61 74 65 6d  arate SQL statem
36e0: 65 6e 74 73 20 70 61 73 73 65 64 20 69 6e 74 6f  ents passed into
36f0: 20 69 74 73 20 32 6e 64 20 61 72 67 75 6d 65 6e   its 2nd argumen
3700: 74 2c 0a 2a 2a 20 69 6e 20 74 68 65 20 63 6f 6e  t,.** in the con
3710: 74 65 78 74 20 6f 66 20 74 68 65 20 5b 64 61 74  text of the [dat
3720: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
3730: 5d 20 70 61 73 73 65 64 20 69 6e 20 61 73 20 69  ] passed in as i
3740: 74 73 20 31 73 74 0a 2a 2a 20 61 72 67 75 6d 65  ts 1st.** argume
3750: 6e 74 2e 20 20 5e 49 66 20 74 68 65 20 63 61 6c  nt.  ^If the cal
3760: 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 6f  lback function o
3770: 66 20 74 68 65 20 33 72 64 20 61 72 67 75 6d 65  f the 3rd argume
3780: 6e 74 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33  nt to.** sqlite3
3790: 5f 65 78 65 63 28 29 20 69 73 20 6e 6f 74 20 4e  _exec() is not N
37a0: 55 4c 4c 2c 20 74 68 65 6e 20 69 74 20 69 73 20  ULL, then it is 
37b0: 69 6e 76 6f 6b 65 64 20 66 6f 72 20 65 61 63 68  invoked for each
37c0: 20 72 65 73 75 6c 74 20 72 6f 77 0a 2a 2a 20 63   result row.** c
37d0: 6f 6d 69 6e 67 20 6f 75 74 20 6f 66 20 74 68 65  oming out of the
37e0: 20 65 76 61 6c 75 61 74 65 64 20 53 51 4c 20 73   evaluated SQL s
37f0: 74 61 74 65 6d 65 6e 74 73 2e 20 20 5e 54 68 65  tatements.  ^The
3800: 20 34 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f   4th argument to
3810: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 63  .** sqlite3_exec
3820: 28 29 20 69 73 20 72 65 6c 61 79 65 64 20 74 68  () is relayed th
3830: 72 6f 75 67 68 20 74 6f 20 74 68 65 20 31 73 74  rough to the 1st
3840: 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 65 61 63   argument of eac
3850: 68 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 69 6e  h.** callback in
3860: 76 6f 63 61 74 69 6f 6e 2e 20 20 5e 49 66 20 74  vocation.  ^If t
3870: 68 65 20 63 61 6c 6c 62 61 63 6b 20 70 6f 69 6e  he callback poin
3880: 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65  ter to sqlite3_e
3890: 78 65 63 28 29 0a 2a 2a 20 69 73 20 4e 55 4c 4c  xec().** is NULL
38a0: 2c 20 74 68 65 6e 20 6e 6f 20 63 61 6c 6c 62 61  , then no callba
38b0: 63 6b 20 69 73 20 65 76 65 72 20 69 6e 76 6f 6b  ck is ever invok
38c0: 65 64 20 61 6e 64 20 72 65 73 75 6c 74 20 72 6f  ed and result ro
38d0: 77 73 20 61 72 65 0a 2a 2a 20 69 67 6e 6f 72 65  ws are.** ignore
38e0: 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20  d..**.** ^If an 
38f0: 65 72 72 6f 72 20 6f 63 63 75 72 73 20 77 68 69  error occurs whi
3900: 6c 65 20 65 76 61 6c 75 61 74 69 6e 67 20 74 68  le evaluating th
3910: 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  e SQL statements
3920: 20 70 61 73 73 65 64 20 69 6e 74 6f 0a 2a 2a 20   passed into.** 
3930: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 2c 20  sqlite3_exec(), 
3940: 74 68 65 6e 20 65 78 65 63 75 74 69 6f 6e 20 6f  then execution o
3950: 66 20 74 68 65 20 63 75 72 72 65 6e 74 20 73 74  f the current st
3960: 61 74 65 6d 65 6e 74 20 73 74 6f 70 73 20 61 6e  atement stops an
3970: 64 0a 2a 2a 20 73 75 62 73 65 71 75 65 6e 74 20  d.** subsequent 
3980: 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20 73  statements are s
3990: 6b 69 70 70 65 64 2e 20 20 5e 49 66 20 74 68 65  kipped.  ^If the
39a0: 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 74   5th parameter t
39b0: 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  o sqlite3_exec()
39c0: 0a 2a 2a 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20  .** is not NULL 
39d0: 74 68 65 6e 20 61 6e 79 20 65 72 72 6f 72 20 6d  then any error m
39e0: 65 73 73 61 67 65 20 69 73 20 77 72 69 74 74 65  essage is writte
39f0: 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62  n into memory ob
3a00: 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b  tained.** from [
3a10: 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
3a20: 5d 20 61 6e 64 20 70 61 73 73 65 64 20 62 61 63  ] and passed bac
3a30: 6b 20 74 68 72 6f 75 67 68 20 74 68 65 20 35 74  k through the 5t
3a40: 68 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20  h parameter..** 
3a50: 54 6f 20 61 76 6f 69 64 20 6d 65 6d 6f 72 79 20  To avoid memory 
3a60: 6c 65 61 6b 73 2c 20 74 68 65 20 61 70 70 6c 69  leaks, the appli
3a70: 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 69 6e  cation should in
3a80: 76 6f 6b 65 20 5b 73 71 6c 69 74 65 33 5f 66 72  voke [sqlite3_fr
3a90: 65 65 28 29 5d 0a 2a 2a 20 6f 6e 20 65 72 72 6f  ee()].** on erro
3aa0: 72 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67  r message string
3ab0: 73 20 72 65 74 75 72 6e 65 64 20 74 68 72 6f 75  s returned throu
3ac0: 67 68 20 74 68 65 20 35 74 68 20 70 61 72 61 6d  gh the 5th param
3ad0: 65 74 65 72 20 6f 66 0a 2a 2a 20 73 71 6c 69 74  eter of.** sqlit
3ae0: 65 33 5f 65 78 65 63 28 29 20 61 66 74 65 72 20  e3_exec() after 
3af0: 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67  the error messag
3b00: 65 20 73 74 72 69 6e 67 20 69 73 20 6e 6f 20 6c  e string is no l
3b10: 6f 6e 67 65 72 20 6e 65 65 64 65 64 2e 0a 2a 2a  onger needed..**
3b20: 20 5e 49 66 20 74 68 65 20 35 74 68 20 70 61 72   ^If the 5th par
3b30: 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
3b40: 33 5f 65 78 65 63 28 29 20 69 73 20 6e 6f 74 20  3_exec() is not 
3b50: 4e 55 4c 4c 20 61 6e 64 20 6e 6f 20 65 72 72 6f  NULL and no erro
3b60: 72 73 0a 2a 2a 20 6f 63 63 75 72 2c 20 74 68 65  rs.** occur, the
3b70: 6e 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  n sqlite3_exec()
3b80: 20 73 65 74 73 20 74 68 65 20 70 6f 69 6e 74 65   sets the pointe
3b90: 72 20 69 6e 20 69 74 73 20 35 74 68 20 70 61 72  r in its 5th par
3ba0: 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 4e 55 4c  ameter to.** NUL
3bb0: 4c 20 62 65 66 6f 72 65 20 72 65 74 75 72 6e 69  L before returni
3bc0: 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e  ng..**.** ^If an
3bd0: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20   sqlite3_exec() 
3be0: 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73  callback returns
3bf0: 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 20 73   non-zero, the s
3c00: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a  qlite3_exec().**
3c10: 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
3c20: 20 53 51 4c 49 54 45 5f 41 42 4f 52 54 20 77 69   SQLITE_ABORT wi
3c30: 74 68 6f 75 74 20 69 6e 76 6f 6b 69 6e 67 20 74  thout invoking t
3c40: 68 65 20 63 61 6c 6c 62 61 63 6b 20 61 67 61 69  he callback agai
3c50: 6e 20 61 6e 64 0a 2a 2a 20 77 69 74 68 6f 75 74  n and.** without
3c60: 20 72 75 6e 6e 69 6e 67 20 61 6e 79 20 73 75 62   running any sub
3c70: 73 65 71 75 65 6e 74 20 53 51 4c 20 73 74 61 74  sequent SQL stat
3c80: 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ements..**.** ^T
3c90: 68 65 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 20  he 2nd argument 
3ca0: 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 65  to the sqlite3_e
3cb0: 78 65 63 28 29 20 63 61 6c 6c 62 61 63 6b 20 66  xec() callback f
3cc0: 75 6e 63 74 69 6f 6e 20 69 73 20 74 68 65 0a 2a  unction is the.*
3cd0: 2a 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75  * number of colu
3ce0: 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 73 75 6c  mns in the resul
3cf0: 74 2e 20 20 5e 54 68 65 20 33 72 64 20 61 72 67  t.  ^The 3rd arg
3d00: 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 73 71 6c  ument to the sql
3d10: 69 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20 63  ite3_exec().** c
3d20: 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 61 72  allback is an ar
3d30: 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20  ray of pointers 
3d40: 74 6f 20 73 74 72 69 6e 67 73 20 6f 62 74 61 69  to strings obtai
3d50: 6e 65 64 20 61 73 20 69 66 20 66 72 6f 6d 0a 2a  ned as if from.*
3d60: 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  * [sqlite3_colum
3d70: 6e 5f 74 65 78 74 28 29 5d 2c 20 6f 6e 65 20 66  n_text()], one f
3d80: 6f 72 20 65 61 63 68 20 63 6f 6c 75 6d 6e 2e 20  or each column. 
3d90: 20 5e 49 66 20 61 6e 20 65 6c 65 6d 65 6e 74 20   ^If an element 
3da0: 6f 66 20 61 0a 2a 2a 20 72 65 73 75 6c 74 20 72  of a.** result r
3db0: 6f 77 20 69 73 20 4e 55 4c 4c 20 74 68 65 6e 20  ow is NULL then 
3dc0: 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e  the correspondin
3dd0: 67 20 73 74 72 69 6e 67 20 70 6f 69 6e 74 65 72  g string pointer
3de0: 20 66 6f 72 20 74 68 65 0a 2a 2a 20 73 71 6c 69   for the.** sqli
3df0: 74 65 33 5f 65 78 65 63 28 29 20 63 61 6c 6c 62  te3_exec() callb
3e00: 61 63 6b 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  ack is a NULL po
3e10: 69 6e 74 65 72 2e 20 20 5e 54 68 65 20 34 74 68  inter.  ^The 4th
3e20: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
3e30: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 63  .** sqlite3_exec
3e40: 28 29 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61  () callback is a
3e50: 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74  n array of point
3e60: 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73 20 77  ers to strings w
3e70: 68 65 72 65 20 65 61 63 68 0a 2a 2a 20 65 6e 74  here each.** ent
3e80: 72 79 20 72 65 70 72 65 73 65 6e 74 73 20 74 68  ry represents th
3e90: 65 20 6e 61 6d 65 20 6f 66 20 63 6f 72 72 65 73  e name of corres
3ea0: 70 6f 6e 64 69 6e 67 20 72 65 73 75 6c 74 20 63  ponding result c
3eb0: 6f 6c 75 6d 6e 20 61 73 20 6f 62 74 61 69 6e 65  olumn as obtaine
3ec0: 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74  d.** from [sqlit
3ed0: 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29  e3_column_name()
3ee0: 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  ]..**.** ^If the
3ef0: 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74   2nd parameter t
3f00: 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  o sqlite3_exec()
3f10: 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
3f20: 65 72 2c 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a  er, a pointer.**
3f30: 20 74 6f 20 61 6e 20 65 6d 70 74 79 20 73 74 72   to an empty str
3f40: 69 6e 67 2c 20 6f 72 20 61 20 70 6f 69 6e 74 65  ing, or a pointe
3f50: 72 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 73 20  r that contains 
3f60: 6f 6e 6c 79 20 77 68 69 74 65 73 70 61 63 65 20  only whitespace 
3f70: 61 6e 64 2f 6f 72 20 0a 2a 2a 20 53 51 4c 20 63  and/or .** SQL c
3f80: 6f 6d 6d 65 6e 74 73 2c 20 74 68 65 6e 20 6e 6f  omments, then no
3f90: 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20   SQL statements 
3fa0: 61 72 65 20 65 76 61 6c 75 61 74 65 64 20 61 6e  are evaluated an
3fb0: 64 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a  d the database.*
3fc0: 2a 20 69 73 20 6e 6f 74 20 63 68 61 6e 67 65 64  * is not changed
3fd0: 2e 0a 2a 2a 0a 2a 2a 20 52 65 73 74 72 69 63 74  ..**.** Restrict
3fe0: 69 6f 6e 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  ions:.**.** <ul>
3ff0: 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 61 70 70  .** <li> The app
4000: 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 65 6e  lication must en
4010: 73 75 72 65 20 74 68 61 74 20 74 68 65 20 31 73  sure that the 1s
4020: 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  t parameter to s
4030: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a  qlite3_exec().**
4040: 20 20 20 20 20 20 69 73 20 61 20 76 61 6c 69 64        is a valid
4050: 20 61 6e 64 20 6f 70 65 6e 20 5b 64 61 74 61 62   and open [datab
4060: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e  ase connection].
4070: 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 61 70 70  .** <li> The app
4080: 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f  lication must no
4090: 74 20 63 6c 6f 73 65 20 74 68 65 20 5b 64 61 74  t close the [dat
40a0: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
40b0: 5d 20 73 70 65 63 69 66 69 65 64 20 62 79 0a 2a  ] specified by.*
40c0: 2a 20 20 20 20 20 20 74 68 65 20 31 73 74 20 70  *      the 1st p
40d0: 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
40e0: 74 65 33 5f 65 78 65 63 28 29 20 77 68 69 6c 65  te3_exec() while
40f0: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20   sqlite3_exec() 
4100: 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 3c  is running..** <
4110: 6c 69 3e 20 54 68 65 20 61 70 70 6c 69 63 61 74  li> The applicat
4120: 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 6d 6f 64  ion must not mod
4130: 69 66 79 20 74 68 65 20 53 51 4c 20 73 74 61 74  ify the SQL stat
4140: 65 6d 65 6e 74 20 74 65 78 74 20 70 61 73 73 65  ement text passe
4150: 64 20 69 6e 74 6f 0a 2a 2a 20 20 20 20 20 20 74  d into.**      t
4160: 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  he 2nd parameter
4170: 20 6f 66 20 73 71 6c 69 74 65 33 5f 65 78 65 63   of sqlite3_exec
4180: 28 29 20 77 68 69 6c 65 20 73 71 6c 69 74 65 33  () while sqlite3
4190: 5f 65 78 65 63 28 29 20 69 73 20 72 75 6e 6e 69  _exec() is runni
41a0: 6e 67 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2f 0a  ng..** </ul>.*/.
41b0: 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 65 63  int sqlite3_exec
41c0: 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 20 20  (.  sqlite3*,   
41d0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
41e0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f                 /
41f0: 2a 20 41 6e 20 6f 70 65 6e 20 64 61 74 61 62 61  * An open databa
4200: 73 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68  se */.  const ch
4210: 61 72 20 2a 73 71 6c 2c 20 20 20 20 20 20 20 20  ar *sql,        
4220: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4230: 20 20 20 2f 2a 20 53 51 4c 20 74 6f 20 62 65 20     /* SQL to be 
4240: 65 76 61 6c 75 61 74 65 64 20 2a 2f 0a 20 20 69  evaluated */.  i
4250: 6e 74 20 28 2a 63 61 6c 6c 62 61 63 6b 29 28 76  nt (*callback)(v
4260: 6f 69 64 2a 2c 69 6e 74 2c 63 68 61 72 2a 2a 2c  oid*,int,char**,
4270: 63 68 61 72 2a 2a 29 2c 20 20 2f 2a 20 43 61 6c  char**),  /* Cal
4280: 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 2a  lback function *
4290: 2f 0a 20 20 76 6f 69 64 20 2a 2c 20 20 20 20 20  /.  void *,     
42a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
42b0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f                 /
42c0: 2a 20 31 73 74 20 61 72 67 75 6d 65 6e 74 20 74  * 1st argument t
42d0: 6f 20 63 61 6c 6c 62 61 63 6b 20 2a 2f 0a 20 20  o callback */.  
42e0: 63 68 61 72 20 2a 2a 65 72 72 6d 73 67 20 20 20  char **errmsg   
42f0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4300: 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 45 72             /* Er
4310: 72 6f 72 20 6d 73 67 20 77 72 69 74 74 65 6e 20  ror msg written 
4320: 68 65 72 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a  here */.);../*.*
4330: 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 75  * CAPI3REF: Resu
4340: 6c 74 20 43 6f 64 65 73 0a 2a 2a 20 4b 45 59 57  lt Codes.** KEYW
4350: 4f 52 44 53 3a 20 7b 72 65 73 75 6c 74 20 63 6f  ORDS: {result co
4360: 64 65 20 64 65 66 69 6e 69 74 69 6f 6e 73 7d 0a  de definitions}.
4370: 2a 2a 0a 2a 2a 20 4d 61 6e 79 20 53 51 4c 69 74  **.** Many SQLit
4380: 65 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75  e functions retu
4390: 72 6e 20 61 6e 20 69 6e 74 65 67 65 72 20 72 65  rn an integer re
43a0: 73 75 6c 74 20 63 6f 64 65 20 66 72 6f 6d 20 74  sult code from t
43b0: 68 65 20 73 65 74 20 73 68 6f 77 6e 0a 2a 2a 20  he set shown.** 
43c0: 68 65 72 65 20 69 6e 20 6f 72 64 65 72 20 74 6f  here in order to
43d0: 20 69 6e 64 69 63 61 74 65 20 73 75 63 63 65 73   indicate succes
43e0: 73 20 6f 72 20 66 61 69 6c 75 72 65 2e 0a 2a 2a  s or failure..**
43f0: 0a 2a 2a 20 4e 65 77 20 65 72 72 6f 72 20 63 6f  .** New error co
4400: 64 65 73 20 6d 61 79 20 62 65 20 61 64 64 65 64  des may be added
4410: 20 69 6e 20 66 75 74 75 72 65 20 76 65 72 73 69   in future versi
4420: 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a  ons of SQLite..*
4430: 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b  *.** See also: [
4440: 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
4450: 63 6f 64 65 20 64 65 66 69 6e 69 74 69 6f 6e 73  code definitions
4460: 5d 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ].*/.#define SQL
4470: 49 54 45 5f 4f 4b 20 20 20 20 20 20 20 20 20 20  ITE_OK          
4480: 20 30 20 20 20 2f 2a 20 53 75 63 63 65 73 73 66   0   /* Successf
4490: 75 6c 20 72 65 73 75 6c 74 20 2a 2f 0a 2f 2a 20  ul result */./* 
44a0: 62 65 67 69 6e 6e 69 6e 67 2d 6f 66 2d 65 72 72  beginning-of-err
44b0: 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a 23 64 65 66  or-codes */.#def
44c0: 69 6e 65 20 53 51 4c 49 54 45 5f 45 52 52 4f 52  ine SQLITE_ERROR
44d0: 20 20 20 20 20 20 20 20 31 20 20 20 2f 2a 20 53          1   /* S
44e0: 51 4c 20 65 72 72 6f 72 20 6f 72 20 6d 69 73 73  QL error or miss
44f0: 69 6e 67 20 64 61 74 61 62 61 73 65 20 2a 2f 0a  ing database */.
4500: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
4510: 4e 54 45 52 4e 41 4c 20 20 20 20 20 32 20 20 20  NTERNAL     2   
4520: 2f 2a 20 49 6e 74 65 72 6e 61 6c 20 6c 6f 67 69  /* Internal logi
4530: 63 20 65 72 72 6f 72 20 69 6e 20 53 51 4c 69 74  c error in SQLit
4540: 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  e */.#define SQL
4550: 49 54 45 5f 50 45 52 4d 20 20 20 20 20 20 20 20  ITE_PERM        
4560: 20 33 20 20 20 2f 2a 20 41 63 63 65 73 73 20 70   3   /* Access p
4570: 65 72 6d 69 73 73 69 6f 6e 20 64 65 6e 69 65 64  ermission denied
4580: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4590: 54 45 5f 41 42 4f 52 54 20 20 20 20 20 20 20 20  TE_ABORT        
45a0: 34 20 20 20 2f 2a 20 43 61 6c 6c 62 61 63 6b 20  4   /* Callback 
45b0: 72 6f 75 74 69 6e 65 20 72 65 71 75 65 73 74 65  routine requeste
45c0: 64 20 61 6e 20 61 62 6f 72 74 20 2a 2f 0a 23 64  d an abort */.#d
45d0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55 53  efine SQLITE_BUS
45e0: 59 20 20 20 20 20 20 20 20 20 35 20 20 20 2f 2a  Y         5   /*
45f0: 20 54 68 65 20 64 61 74 61 62 61 73 65 20 66 69   The database fi
4600: 6c 65 20 69 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a  le is locked */.
4610: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
4620: 4f 43 4b 45 44 20 20 20 20 20 20 20 36 20 20 20  OCKED       6   
4630: 2f 2a 20 41 20 74 61 62 6c 65 20 69 6e 20 74 68  /* A table in th
4640: 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6c 6f  e database is lo
4650: 63 6b 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20  cked */.#define 
4660: 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20 20 20 20  SQLITE_NOMEM    
4670: 20 20 20 20 37 20 20 20 2f 2a 20 41 20 6d 61 6c      7   /* A mal
4680: 6c 6f 63 28 29 20 66 61 69 6c 65 64 20 2a 2f 0a  loc() failed */.
4690: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52  #define SQLITE_R
46a0: 45 41 44 4f 4e 4c 59 20 20 20 20 20 38 20 20 20  EADONLY     8   
46b0: 2f 2a 20 41 74 74 65 6d 70 74 20 74 6f 20 77 72  /* Attempt to wr
46c0: 69 74 65 20 61 20 72 65 61 64 6f 6e 6c 79 20 64  ite a readonly d
46d0: 61 74 61 62 61 73 65 20 2a 2f 0a 23 64 65 66 69  atabase */.#defi
46e0: 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45 52 52  ne SQLITE_INTERR
46f0: 55 50 54 20 20 20 20 39 20 20 20 2f 2a 20 4f 70  UPT    9   /* Op
4700: 65 72 61 74 69 6f 6e 20 74 65 72 6d 69 6e 61 74  eration terminat
4710: 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 69 6e  ed by sqlite3_in
4720: 74 65 72 72 75 70 74 28 29 2a 2f 0a 23 64 65 66  terrupt()*/.#def
4730: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
4740: 20 20 20 20 20 20 20 31 30 20 20 20 2f 2a 20 53         10   /* S
4750: 6f 6d 65 20 6b 69 6e 64 20 6f 66 20 64 69 73 6b  ome kind of disk
4760: 20 49 2f 4f 20 65 72 72 6f 72 20 6f 63 63 75 72   I/O error occur
4770: 72 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  red */.#define S
4780: 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 20 20 20  QLITE_CORRUPT   
4790: 20 20 31 31 20 20 20 2f 2a 20 54 68 65 20 64 61    11   /* The da
47a0: 74 61 62 61 73 65 20 64 69 73 6b 20 69 6d 61 67  tabase disk imag
47b0: 65 20 69 73 20 6d 61 6c 66 6f 72 6d 65 64 20 2a  e is malformed *
47c0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
47d0: 5f 4e 4f 54 46 4f 55 4e 44 20 20 20 20 31 32 20  _NOTFOUND    12 
47e0: 20 20 2f 2a 20 55 6e 6b 6e 6f 77 6e 20 6f 70 63    /* Unknown opc
47f0: 6f 64 65 20 69 6e 20 73 71 6c 69 74 65 33 5f 66  ode in sqlite3_f
4800: 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 20 2a 2f  ile_control() */
4810: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4820: 46 55 4c 4c 20 20 20 20 20 20 20 20 31 33 20 20  FULL        13  
4830: 20 2f 2a 20 49 6e 73 65 72 74 69 6f 6e 20 66 61   /* Insertion fa
4840: 69 6c 65 64 20 62 65 63 61 75 73 65 20 64 61 74  iled because dat
4850: 61 62 61 73 65 20 69 73 20 66 75 6c 6c 20 2a 2f  abase is full */
4860: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4870: 43 41 4e 54 4f 50 45 4e 20 20 20 20 31 34 20 20  CANTOPEN    14  
4880: 20 2f 2a 20 55 6e 61 62 6c 65 20 74 6f 20 6f 70   /* Unable to op
4890: 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  en the database 
48a0: 66 69 6c 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20  file */.#define 
48b0: 53 51 4c 49 54 45 5f 50 52 4f 54 4f 43 4f 4c 20  SQLITE_PROTOCOL 
48c0: 20 20 20 31 35 20 20 20 2f 2a 20 44 61 74 61 62     15   /* Datab
48d0: 61 73 65 20 6c 6f 63 6b 20 70 72 6f 74 6f 63 6f  ase lock protoco
48e0: 6c 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69  l error */.#defi
48f0: 6e 65 20 53 51 4c 49 54 45 5f 45 4d 50 54 59 20  ne SQLITE_EMPTY 
4900: 20 20 20 20 20 20 31 36 20 20 20 2f 2a 20 44 61        16   /* Da
4910: 74 61 62 61 73 65 20 69 73 20 65 6d 70 74 79 20  tabase is empty 
4920: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
4930: 45 5f 53 43 48 45 4d 41 20 20 20 20 20 20 31 37  E_SCHEMA      17
4940: 20 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62 61     /* The databa
4950: 73 65 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65  se schema change
4960: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  d */.#define SQL
4970: 49 54 45 5f 54 4f 4f 42 49 47 20 20 20 20 20 20  ITE_TOOBIG      
4980: 31 38 20 20 20 2f 2a 20 53 74 72 69 6e 67 20 6f  18   /* String o
4990: 72 20 42 4c 4f 42 20 65 78 63 65 65 64 73 20 73  r BLOB exceeds s
49a0: 69 7a 65 20 6c 69 6d 69 74 20 2a 2f 0a 23 64 65  ize limit */.#de
49b0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53  fine SQLITE_CONS
49c0: 54 52 41 49 4e 54 20 20 31 39 20 20 20 2f 2a 20  TRAINT  19   /* 
49d0: 41 62 6f 72 74 20 64 75 65 20 74 6f 20 63 6f 6e  Abort due to con
49e0: 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f  straint violatio
49f0: 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  n */.#define SQL
4a00: 49 54 45 5f 4d 49 53 4d 41 54 43 48 20 20 20 20  ITE_MISMATCH    
4a10: 32 30 20 20 20 2f 2a 20 44 61 74 61 20 74 79 70  20   /* Data typ
4a20: 65 20 6d 69 73 6d 61 74 63 68 20 2a 2f 0a 23 64  e mismatch */.#d
4a30: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 49 53  efine SQLITE_MIS
4a40: 55 53 45 20 20 20 20 20 20 32 31 20 20 20 2f 2a  USE      21   /*
4a50: 20 4c 69 62 72 61 72 79 20 75 73 65 64 20 69 6e   Library used in
4a60: 63 6f 72 72 65 63 74 6c 79 20 2a 2f 0a 23 64 65  correctly */.#de
4a70: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 4c 46  fine SQLITE_NOLF
4a80: 53 20 20 20 20 20 20 20 32 32 20 20 20 2f 2a 20  S       22   /* 
4a90: 55 73 65 73 20 4f 53 20 66 65 61 74 75 72 65 73  Uses OS features
4aa0: 20 6e 6f 74 20 73 75 70 70 6f 72 74 65 64 20 6f   not supported o
4ab0: 6e 20 68 6f 73 74 20 2a 2f 0a 23 64 65 66 69 6e  n host */.#defin
4ac0: 65 20 53 51 4c 49 54 45 5f 41 55 54 48 20 20 20  e SQLITE_AUTH   
4ad0: 20 20 20 20 20 32 33 20 20 20 2f 2a 20 41 75 74       23   /* Aut
4ae0: 68 6f 72 69 7a 61 74 69 6f 6e 20 64 65 6e 69 65  horization denie
4af0: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  d */.#define SQL
4b00: 49 54 45 5f 46 4f 52 4d 41 54 20 20 20 20 20 20  ITE_FORMAT      
4b10: 32 34 20 20 20 2f 2a 20 41 75 78 69 6c 69 61 72  24   /* Auxiliar
4b20: 79 20 64 61 74 61 62 61 73 65 20 66 6f 72 6d 61  y database forma
4b30: 74 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69  t error */.#defi
4b40: 6e 65 20 53 51 4c 49 54 45 5f 52 41 4e 47 45 20  ne SQLITE_RANGE 
4b50: 20 20 20 20 20 20 32 35 20 20 20 2f 2a 20 32 6e        25   /* 2n
4b60: 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  d parameter to s
4b70: 71 6c 69 74 65 33 5f 62 69 6e 64 20 6f 75 74 20  qlite3_bind out 
4b80: 6f 66 20 72 61 6e 67 65 20 2a 2f 0a 23 64 65 66  of range */.#def
4b90: 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 41 44  ine SQLITE_NOTAD
4ba0: 42 20 20 20 20 20 20 32 36 20 20 20 2f 2a 20 46  B      26   /* F
4bb0: 69 6c 65 20 6f 70 65 6e 65 64 20 74 68 61 74 20  ile opened that 
4bc0: 69 73 20 6e 6f 74 20 61 20 64 61 74 61 62 61 73  is not a databas
4bd0: 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65 66 69 6e  e file */.#defin
4be0: 65 20 53 51 4c 49 54 45 5f 4e 4f 54 49 43 45 20  e SQLITE_NOTICE 
4bf0: 20 20 20 20 20 32 37 20 20 20 2f 2a 20 4e 6f 74       27   /* Not
4c00: 69 66 69 63 61 74 69 6f 6e 73 20 66 72 6f 6d 20  ifications from 
4c10: 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 20 2a 2f  sqlite3_log() */
4c20: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4c30: 57 41 52 4e 49 4e 47 20 20 20 20 20 32 38 20 20  WARNING     28  
4c40: 20 2f 2a 20 57 61 72 6e 69 6e 67 73 20 66 72 6f   /* Warnings fro
4c50: 6d 20 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 20  m sqlite3_log() 
4c60: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
4c70: 45 5f 52 4f 57 20 20 20 20 20 20 20 20 20 31 30  E_ROW         10
4c80: 30 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 73 74  0  /* sqlite3_st
4c90: 65 70 28 29 20 68 61 73 20 61 6e 6f 74 68 65 72  ep() has another
4ca0: 20 72 6f 77 20 72 65 61 64 79 20 2a 2f 0a 23 64   row ready */.#d
4cb0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 4f 4e  efine SQLITE_DON
4cc0: 45 20 20 20 20 20 20 20 20 31 30 31 20 20 2f 2a  E        101  /*
4cd0: 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20   sqlite3_step() 
4ce0: 68 61 73 20 66 69 6e 69 73 68 65 64 20 65 78 65  has finished exe
4cf0: 63 75 74 69 6e 67 20 2a 2f 0a 2f 2a 20 65 6e 64  cuting */./* end
4d00: 2d 6f 66 2d 65 72 72 6f 72 2d 63 6f 64 65 73 20  -of-error-codes 
4d10: 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  */../*.** CAPI3R
4d20: 45 46 3a 20 45 78 74 65 6e 64 65 64 20 52 65 73  EF: Extended Res
4d30: 75 6c 74 20 43 6f 64 65 73 0a 2a 2a 20 4b 45 59  ult Codes.** KEY
4d40: 57 4f 52 44 53 3a 20 7b 65 78 74 65 6e 64 65 64  WORDS: {extended
4d50: 20 72 65 73 75 6c 74 20 63 6f 64 65 20 64 65 66   result code def
4d60: 69 6e 69 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20  initions}.**.** 
4d70: 49 6e 20 69 74 73 20 64 65 66 61 75 6c 74 20 63  In its default c
4d80: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 2c 20 53 51  onfiguration, SQ
4d90: 4c 69 74 65 20 41 50 49 20 72 6f 75 74 69 6e 65  Lite API routine
4da0: 73 20 72 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20  s return one of 
4db0: 33 30 20 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 72  30 integer.** [r
4dc0: 65 73 75 6c 74 20 63 6f 64 65 73 5d 2e 20 20 48  esult codes].  H
4dd0: 6f 77 65 76 65 72 2c 20 65 78 70 65 72 69 65 6e  owever, experien
4de0: 63 65 20 68 61 73 20 73 68 6f 77 6e 20 74 68 61  ce has shown tha
4df0: 74 20 6d 61 6e 79 20 6f 66 0a 2a 2a 20 74 68 65  t many of.** the
4e00: 73 65 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20  se result codes 
4e10: 61 72 65 20 74 6f 6f 20 63 6f 61 72 73 65 2d 67  are too coarse-g
4e20: 72 61 69 6e 65 64 2e 20 20 54 68 65 79 20 64 6f  rained.  They do
4e30: 20 6e 6f 74 20 70 72 6f 76 69 64 65 20 61 73 0a   not provide as.
4e40: 2a 2a 20 6d 75 63 68 20 69 6e 66 6f 72 6d 61 74  ** much informat
4e50: 69 6f 6e 20 61 62 6f 75 74 20 70 72 6f 62 6c 65  ion about proble
4e60: 6d 73 20 61 73 20 70 72 6f 67 72 61 6d 6d 65 72  ms as programmer
4e70: 73 20 6d 69 67 68 74 20 6c 69 6b 65 2e 20 20 49  s might like.  I
4e80: 6e 20 61 6e 20 65 66 66 6f 72 74 20 74 6f 0a 2a  n an effort to.*
4e90: 2a 20 61 64 64 72 65 73 73 20 74 68 69 73 2c 20  * address this, 
4ea0: 6e 65 77 65 72 20 76 65 72 73 69 6f 6e 73 20 6f  newer versions o
4eb0: 66 20 53 51 4c 69 74 65 20 28 76 65 72 73 69 6f  f SQLite (versio
4ec0: 6e 20 33 2e 33 2e 38 20 5b 64 61 74 65 6f 66 3a  n 3.3.8 [dateof:
4ed0: 33 2e 33 2e 38 5d 0a 2a 2a 20 61 6e 64 20 6c 61  3.3.8].** and la
4ee0: 74 65 72 29 20 69 6e 63 6c 75 64 65 0a 2a 2a 20  ter) include.** 
4ef0: 73 75 70 70 6f 72 74 20 66 6f 72 20 61 64 64 69  support for addi
4f00: 74 69 6f 6e 61 6c 20 72 65 73 75 6c 74 20 63 6f  tional result co
4f10: 64 65 73 20 74 68 61 74 20 70 72 6f 76 69 64 65  des that provide
4f20: 20 6d 6f 72 65 20 64 65 74 61 69 6c 65 64 20 69   more detailed i
4f30: 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 61 62  nformation.** ab
4f40: 6f 75 74 20 65 72 72 6f 72 73 2e 20 54 68 65 73  out errors. Thes
4f50: 65 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75  e [extended resu
4f60: 6c 74 20 63 6f 64 65 73 5d 20 61 72 65 20 65 6e  lt codes] are en
4f70: 61 62 6c 65 64 20 6f 72 20 64 69 73 61 62 6c 65  abled or disable
4f80: 64 0a 2a 2a 20 6f 6e 20 61 20 70 65 72 20 64 61  d.** on a per da
4f90: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
4fa0: 6e 20 62 61 73 69 73 20 75 73 69 6e 67 20 74 68  n basis using th
4fb0: 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78  e.** [sqlite3_ex
4fc0: 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f  tended_result_co
4fd0: 64 65 73 28 29 5d 20 41 50 49 2e 20 20 4f 72 2c  des()] API.  Or,
4fe0: 20 74 68 65 20 65 78 74 65 6e 64 65 64 20 63 6f   the extended co
4ff0: 64 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 6d 6f  de for.** the mo
5000: 73 74 20 72 65 63 65 6e 74 20 65 72 72 6f 72 20  st recent error 
5010: 63 61 6e 20 62 65 20 6f 62 74 61 69 6e 65 64 20  can be obtained 
5020: 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65  using.** [sqlite
5030: 33 5f 65 78 74 65 6e 64 65 64 5f 65 72 72 63 6f  3_extended_errco
5040: 64 65 28 29 5d 2e 0a 2a 2f 0a 23 64 65 66 69 6e  de()]..*/.#defin
5050: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52  e SQLITE_IOERR_R
5060: 45 41 44 20 20 20 20 20 20 20 20 20 20 20 20 20  EAD             
5070: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c   (SQLITE_IOERR |
5080: 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (1<<8)).#define
5090: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48   SQLITE_IOERR_SH
50a0: 4f 52 54 5f 52 45 41 44 20 20 20 20 20 20 20 20  ORT_READ        
50b0: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
50c0: 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (2<<8)).#define 
50d0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 57 52 49  SQLITE_IOERR_WRI
50e0: 54 45 20 20 20 20 20 20 20 20 20 20 20 20 20 28  TE             (
50f0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
5100: 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  3<<8)).#define S
5110: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 46 53 59 4e  QLITE_IOERR_FSYN
5120: 43 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53  C             (S
5130: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 34  QLITE_IOERR | (4
5140: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5150: 4c 49 54 45 5f 49 4f 45 52 52 5f 44 49 52 5f 46  LITE_IOERR_DIR_F
5160: 53 59 4e 43 20 20 20 20 20 20 20 20 20 28 53 51  SYNC         (SQ
5170: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 35 3c  LITE_IOERR | (5<
5180: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5190: 49 54 45 5f 49 4f 45 52 52 5f 54 52 55 4e 43 41  ITE_IOERR_TRUNCA
51a0: 54 45 20 20 20 20 20 20 20 20 20 20 28 53 51 4c  TE          (SQL
51b0: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 36 3c 3c  ITE_IOERR | (6<<
51c0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
51d0: 54 45 5f 49 4f 45 52 52 5f 46 53 54 41 54 20 20  TE_IOERR_FSTAT  
51e0: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
51f0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 37 3c 3c 38  TE_IOERR | (7<<8
5200: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5210: 45 5f 49 4f 45 52 52 5f 55 4e 4c 4f 43 4b 20 20  E_IOERR_UNLOCK  
5220: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
5230: 45 5f 49 4f 45 52 52 20 7c 20 28 38 3c 3c 38 29  E_IOERR | (8<<8)
5240: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5250: 5f 49 4f 45 52 52 5f 52 44 4c 4f 43 4b 20 20 20  _IOERR_RDLOCK   
5260: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
5270: 5f 49 4f 45 52 52 20 7c 20 28 39 3c 3c 38 29 29  _IOERR | (9<<8))
5280: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5290: 49 4f 45 52 52 5f 44 45 4c 45 54 45 20 20 20 20  IOERR_DELETE    
52a0: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
52b0: 49 4f 45 52 52 20 7c 20 28 31 30 3c 3c 38 29 29  IOERR | (10<<8))
52c0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
52d0: 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 20 20 20  IOERR_BLOCKED   
52e0: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
52f0: 49 4f 45 52 52 20 7c 20 28 31 31 3c 3c 38 29 29  IOERR | (11<<8))
5300: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5310: 49 4f 45 52 52 5f 4e 4f 4d 45 4d 20 20 20 20 20  IOERR_NOMEM     
5320: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
5330: 49 4f 45 52 52 20 7c 20 28 31 32 3c 3c 38 29 29  IOERR | (12<<8))
5340: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5350: 49 4f 45 52 52 5f 41 43 43 45 53 53 20 20 20 20  IOERR_ACCESS    
5360: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
5370: 49 4f 45 52 52 20 7c 20 28 31 33 3c 3c 38 29 29  IOERR | (13<<8))
5380: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5390: 49 4f 45 52 52 5f 43 48 45 43 4b 52 45 53 45 52  IOERR_CHECKRESER
53a0: 56 45 44 4c 4f 43 4b 20 28 53 51 4c 49 54 45 5f  VEDLOCK (SQLITE_
53b0: 49 4f 45 52 52 20 7c 20 28 31 34 3c 3c 38 29 29  IOERR | (14<<8))
53c0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
53d0: 49 4f 45 52 52 5f 4c 4f 43 4b 20 20 20 20 20 20  IOERR_LOCK      
53e0: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
53f0: 49 4f 45 52 52 20 7c 20 28 31 35 3c 3c 38 29 29  IOERR | (15<<8))
5400: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5410: 49 4f 45 52 52 5f 43 4c 4f 53 45 20 20 20 20 20  IOERR_CLOSE     
5420: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
5430: 49 4f 45 52 52 20 7c 20 28 31 36 3c 3c 38 29 29  IOERR | (16<<8))
5440: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5450: 49 4f 45 52 52 5f 44 49 52 5f 43 4c 4f 53 45 20  IOERR_DIR_CLOSE 
5460: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
5470: 49 4f 45 52 52 20 7c 20 28 31 37 3c 3c 38 29 29  IOERR | (17<<8))
5480: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5490: 49 4f 45 52 52 5f 53 48 4d 4f 50 45 4e 20 20 20  IOERR_SHMOPEN   
54a0: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
54b0: 49 4f 45 52 52 20 7c 20 28 31 38 3c 3c 38 29 29  IOERR | (18<<8))
54c0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
54d0: 49 4f 45 52 52 5f 53 48 4d 53 49 5a 45 20 20 20  IOERR_SHMSIZE   
54e0: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
54f0: 49 4f 45 52 52 20 7c 20 28 31 39 3c 3c 38 29 29  IOERR | (19<<8))
5500: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5510: 49 4f 45 52 52 5f 53 48 4d 4c 4f 43 4b 20 20 20  IOERR_SHMLOCK   
5520: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
5530: 49 4f 45 52 52 20 7c 20 28 32 30 3c 3c 38 29 29  IOERR | (20<<8))
5540: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5550: 49 4f 45 52 52 5f 53 48 4d 4d 41 50 20 20 20 20  IOERR_SHMMAP    
5560: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
5570: 49 4f 45 52 52 20 7c 20 28 32 31 3c 3c 38 29 29  IOERR | (21<<8))
5580: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5590: 49 4f 45 52 52 5f 53 45 45 4b 20 20 20 20 20 20  IOERR_SEEK      
55a0: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
55b0: 49 4f 45 52 52 20 7c 20 28 32 32 3c 3c 38 29 29  IOERR | (22<<8))
55c0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
55d0: 49 4f 45 52 52 5f 44 45 4c 45 54 45 5f 4e 4f 45  IOERR_DELETE_NOE
55e0: 4e 54 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f  NT      (SQLITE_
55f0: 49 4f 45 52 52 20 7c 20 28 32 33 3c 3c 38 29 29  IOERR | (23<<8))
5600: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5610: 49 4f 45 52 52 5f 4d 4d 41 50 20 20 20 20 20 20  IOERR_MMAP      
5620: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
5630: 49 4f 45 52 52 20 7c 20 28 32 34 3c 3c 38 29 29  IOERR | (24<<8))
5640: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5650: 49 4f 45 52 52 5f 47 45 54 54 45 4d 50 50 41 54  IOERR_GETTEMPPAT
5660: 48 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f  H       (SQLITE_
5670: 49 4f 45 52 52 20 7c 20 28 32 35 3c 3c 38 29 29  IOERR | (25<<8))
5680: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5690: 49 4f 45 52 52 5f 43 4f 4e 56 50 41 54 48 20 20  IOERR_CONVPATH  
56a0: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
56b0: 49 4f 45 52 52 20 7c 20 28 32 36 3c 3c 38 29 29  IOERR | (26<<8))
56c0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
56d0: 49 4f 45 52 52 5f 56 4e 4f 44 45 20 20 20 20 20  IOERR_VNODE     
56e0: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
56f0: 49 4f 45 52 52 20 7c 20 28 32 37 3c 3c 38 29 29  IOERR | (27<<8))
5700: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5710: 49 4f 45 52 52 5f 41 55 54 48 20 20 20 20 20 20  IOERR_AUTH      
5720: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
5730: 49 4f 45 52 52 20 7c 20 28 32 38 3c 3c 38 29 29  IOERR | (28<<8))
5740: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5750: 4c 4f 43 4b 45 44 5f 53 48 41 52 45 44 43 41 43  LOCKED_SHAREDCAC
5760: 48 45 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f  HE      (SQLITE_
5770: 4c 4f 43 4b 45 44 20 7c 20 20 28 31 3c 3c 38 29  LOCKED |  (1<<8)
5780: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5790: 5f 42 55 53 59 5f 52 45 43 4f 56 45 52 59 20 20  _BUSY_RECOVERY  
57a0: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
57b0: 5f 42 55 53 59 20 20 20 7c 20 20 28 31 3c 3c 38  _BUSY   |  (1<<8
57c0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
57d0: 45 5f 42 55 53 59 5f 53 4e 41 50 53 48 4f 54 20  E_BUSY_SNAPSHOT 
57e0: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
57f0: 45 5f 42 55 53 59 20 20 20 7c 20 20 28 32 3c 3c  E_BUSY   |  (2<<
5800: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5810: 54 45 5f 43 41 4e 54 4f 50 45 4e 5f 4e 4f 54 45  TE_CANTOPEN_NOTE
5820: 4d 50 44 49 52 20 20 20 20 20 20 28 53 51 4c 49  MPDIR      (SQLI
5830: 54 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28 31  TE_CANTOPEN | (1
5840: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5850: 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5f 49 53  LITE_CANTOPEN_IS
5860: 44 49 52 20 20 20 20 20 20 20 20 20 20 28 53 51  DIR          (SQ
5870: 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20  LITE_CANTOPEN | 
5880: 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (2<<8)).#define 
5890: 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5f  SQLITE_CANTOPEN_
58a0: 46 55 4c 4c 50 41 54 48 20 20 20 20 20 20 20 28  FULLPATH       (
58b0: 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20  SQLITE_CANTOPEN 
58c0: 7c 20 28 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (3<<8)).#defin
58d0: 65 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45  e SQLITE_CANTOPE
58e0: 4e 5f 43 4f 4e 56 50 41 54 48 20 20 20 20 20 20  N_CONVPATH      
58f0: 20 28 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45   (SQLITE_CANTOPE
5900: 4e 20 7c 20 28 34 3c 3c 38 29 29 0a 23 64 65 66  N | (4<<8)).#def
5910: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 52 52 55  ine SQLITE_CORRU
5920: 50 54 5f 56 54 41 42 20 20 20 20 20 20 20 20 20  PT_VTAB         
5930: 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 52 52 55     (SQLITE_CORRU
5940: 50 54 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65  PT | (1<<8)).#de
5950: 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44  fine SQLITE_READ
5960: 4f 4e 4c 59 5f 52 45 43 4f 56 45 52 59 20 20 20  ONLY_RECOVERY   
5970: 20 20 20 20 28 53 51 4c 49 54 45 5f 52 45 41 44      (SQLITE_READ
5980: 4f 4e 4c 59 20 7c 20 28 31 3c 3c 38 29 29 0a 23  ONLY | (1<<8)).#
5990: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45  define SQLITE_RE
59a0: 41 44 4f 4e 4c 59 5f 43 41 4e 54 4c 4f 43 4b 20  ADONLY_CANTLOCK 
59b0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 52 45        (SQLITE_RE
59c0: 41 44 4f 4e 4c 59 20 7c 20 28 32 3c 3c 38 29 29  ADONLY | (2<<8))
59d0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
59e0: 52 45 41 44 4f 4e 4c 59 5f 52 4f 4c 4c 42 41 43  READONLY_ROLLBAC
59f0: 4b 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f  K       (SQLITE_
5a00: 52 45 41 44 4f 4e 4c 59 20 7c 20 28 33 3c 3c 38  READONLY | (3<<8
5a10: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5a20: 45 5f 52 45 41 44 4f 4e 4c 59 5f 44 42 4d 4f 56  E_READONLY_DBMOV
5a30: 45 44 20 20 20 20 20 20 20 20 28 53 51 4c 49 54  ED        (SQLIT
5a40: 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28 34 3c  E_READONLY | (4<
5a50: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5a60: 49 54 45 5f 41 42 4f 52 54 5f 52 4f 4c 4c 42 41  ITE_ABORT_ROLLBA
5a70: 43 4b 20 20 20 20 20 20 20 20 20 20 28 53 51 4c  CK          (SQL
5a80: 49 54 45 5f 41 42 4f 52 54 20 7c 20 28 32 3c 3c  ITE_ABORT | (2<<
5a90: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5aa0: 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 43 48  TE_CONSTRAINT_CH
5ab0: 45 43 4b 20 20 20 20 20 20 20 20 28 53 51 4c 49  ECK        (SQLI
5ac0: 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20  TE_CONSTRAINT | 
5ad0: 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (1<<8)).#define 
5ae0: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e  SQLITE_CONSTRAIN
5af0: 54 5f 43 4f 4d 4d 49 54 48 4f 4f 4b 20 20 20 28  T_COMMITHOOK   (
5b00: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e  SQLITE_CONSTRAIN
5b10: 54 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66  T | (2<<8)).#def
5b20: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54  ine SQLITE_CONST
5b30: 52 41 49 4e 54 5f 46 4f 52 45 49 47 4e 4b 45 59  RAINT_FOREIGNKEY
5b40: 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54     (SQLITE_CONST
5b50: 52 41 49 4e 54 20 7c 20 28 33 3c 3c 38 29 29 0a  RAINT | (3<<8)).
5b60: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
5b70: 4f 4e 53 54 52 41 49 4e 54 5f 46 55 4e 43 54 49  ONSTRAINT_FUNCTI
5b80: 4f 4e 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43  ON     (SQLITE_C
5b90: 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 34 3c 3c  ONSTRAINT | (4<<
5ba0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5bb0: 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 4e 4f  TE_CONSTRAINT_NO
5bc0: 54 4e 55 4c 4c 20 20 20 20 20 20 28 53 51 4c 49  TNULL      (SQLI
5bd0: 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20  TE_CONSTRAINT | 
5be0: 28 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (5<<8)).#define 
5bf0: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e  SQLITE_CONSTRAIN
5c00: 54 5f 50 52 49 4d 41 52 59 4b 45 59 20 20 20 28  T_PRIMARYKEY   (
5c10: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e  SQLITE_CONSTRAIN
5c20: 54 20 7c 20 28 36 3c 3c 38 29 29 0a 23 64 65 66  T | (6<<8)).#def
5c30: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54  ine SQLITE_CONST
5c40: 52 41 49 4e 54 5f 54 52 49 47 47 45 52 20 20 20  RAINT_TRIGGER   
5c50: 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54     (SQLITE_CONST
5c60: 52 41 49 4e 54 20 7c 20 28 37 3c 3c 38 29 29 0a  RAINT | (7<<8)).
5c70: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
5c80: 4f 4e 53 54 52 41 49 4e 54 5f 55 4e 49 51 55 45  ONSTRAINT_UNIQUE
5c90: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43         (SQLITE_C
5ca0: 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 38 3c 3c  ONSTRAINT | (8<<
5cb0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5cc0: 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 56 54  TE_CONSTRAINT_VT
5cd0: 41 42 20 20 20 20 20 20 20 20 20 28 53 51 4c 49  AB         (SQLI
5ce0: 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20  TE_CONSTRAINT | 
5cf0: 28 39 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (9<<8)).#define 
5d00: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e  SQLITE_CONSTRAIN
5d10: 54 5f 52 4f 57 49 44 20 20 20 20 20 20 20 20 28  T_ROWID        (
5d20: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e  SQLITE_CONSTRAIN
5d30: 54 20 7c 28 31 30 3c 3c 38 29 29 0a 23 64 65 66  T |(10<<8)).#def
5d40: 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 49 43  ine SQLITE_NOTIC
5d50: 45 5f 52 45 43 4f 56 45 52 5f 57 41 4c 20 20 20  E_RECOVER_WAL   
5d60: 20 20 20 28 53 51 4c 49 54 45 5f 4e 4f 54 49 43     (SQLITE_NOTIC
5d70: 45 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66  E | (1<<8)).#def
5d80: 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 49 43  ine SQLITE_NOTIC
5d90: 45 5f 52 45 43 4f 56 45 52 5f 52 4f 4c 4c 42 41  E_RECOVER_ROLLBA
5da0: 43 4b 20 28 53 51 4c 49 54 45 5f 4e 4f 54 49 43  CK (SQLITE_NOTIC
5db0: 45 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66  E | (2<<8)).#def
5dc0: 69 6e 65 20 53 51 4c 49 54 45 5f 57 41 52 4e 49  ine SQLITE_WARNI
5dd0: 4e 47 5f 41 55 54 4f 49 4e 44 45 58 20 20 20 20  NG_AUTOINDEX    
5de0: 20 20 20 28 53 51 4c 49 54 45 5f 57 41 52 4e 49     (SQLITE_WARNI
5df0: 4e 47 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65  NG | (1<<8)).#de
5e00: 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 55 54 48  fine SQLITE_AUTH
5e10: 5f 55 53 45 52 20 20 20 20 20 20 20 20 20 20 20  _USER           
5e20: 20 20 20 20 28 53 51 4c 49 54 45 5f 41 55 54 48      (SQLITE_AUTH
5e30: 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69   | (1<<8)).#defi
5e40: 6e 65 20 53 51 4c 49 54 45 5f 4f 4b 5f 4c 4f 41  ne SQLITE_OK_LOA
5e50: 44 5f 50 45 52 4d 41 4e 45 4e 54 4c 59 20 20 20  D_PERMANENTLY   
5e60: 20 20 28 53 51 4c 49 54 45 5f 4f 4b 20 7c 20 28    (SQLITE_OK | (
5e70: 31 3c 3c 38 29 29 0a 0a 2f 2a 0a 2a 2a 20 43 41  1<<8))../*.** CA
5e80: 50 49 33 52 45 46 3a 20 46 6c 61 67 73 20 46 6f  PI3REF: Flags Fo
5e90: 72 20 46 69 6c 65 20 4f 70 65 6e 20 4f 70 65 72  r File Open Oper
5ea0: 61 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65  ations.**.** The
5eb0: 73 65 20 62 69 74 20 76 61 6c 75 65 73 20 61 72  se bit values ar
5ec0: 65 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 75  e intended for u
5ed0: 73 65 20 69 6e 20 74 68 65 0a 2a 2a 20 33 72 64  se in the.** 3rd
5ee0: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
5ef0: 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  e [sqlite3_open_
5f00: 76 32 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20  v2()] interface 
5f10: 61 6e 64 0a 2a 2a 20 69 6e 20 74 68 65 20 34 74  and.** in the 4t
5f20: 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  h parameter to t
5f30: 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e  he [sqlite3_vfs.
5f40: 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 2e 0a 2a  xOpen] method..*
5f50: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
5f60: 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 20 20  _OPEN_READONLY  
5f70: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30         0x0000000
5f80: 31 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c  1  /* Ok for sql
5f90: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a  ite3_open_v2() *
5fa0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
5fb0: 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 20  _OPEN_READWRITE 
5fc0: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30         0x0000000
5fd0: 32 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c  2  /* Ok for sql
5fe0: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a  ite3_open_v2() *
5ff0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
6000: 5f 4f 50 45 4e 5f 43 52 45 41 54 45 20 20 20 20  _OPEN_CREATE    
6010: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30         0x0000000
6020: 34 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c  4  /* Ok for sql
6030: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a  ite3_open_v2() *
6040: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
6050: 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c  _OPEN_DELETEONCL
6060: 4f 53 45 20 20 20 20 30 78 30 30 30 30 30 30 30  OSE    0x0000000
6070: 38 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a  8  /* VFS only *
6080: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
6090: 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 20  _OPEN_EXCLUSIVE 
60a0: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 31         0x0000001
60b0: 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a  0  /* VFS only *
60c0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
60d0: 5f 4f 50 45 4e 5f 41 55 54 4f 50 52 4f 58 59 20  _OPEN_AUTOPROXY 
60e0: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 32         0x0000002
60f0: 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a  0  /* VFS only *
6100: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
6110: 5f 4f 50 45 4e 5f 55 52 49 20 20 20 20 20 20 20  _OPEN_URI       
6120: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 34         0x0000004
6130: 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c  0  /* Ok for sql
6140: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a  ite3_open_v2() *
6150: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
6160: 5f 4f 50 45 4e 5f 4d 45 4d 4f 52 59 20 20 20 20  _OPEN_MEMORY    
6170: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 38         0x0000008
6180: 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c  0  /* Ok for sql
6190: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a  ite3_open_v2() *
61a0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
61b0: 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 20 20 20  _OPEN_MAIN_DB   
61c0: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 31 30         0x0000010
61d0: 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a  0  /* VFS only *
61e0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
61f0: 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 20 20 20  _OPEN_TEMP_DB   
6200: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 32 30         0x0000020
6210: 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a  0  /* VFS only *
6220: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
6230: 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e 54 5f  _OPEN_TRANSIENT_
6240: 44 42 20 20 20 20 20 30 78 30 30 30 30 30 34 30  DB     0x0000040
6250: 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a  0  /* VFS only *
6260: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
6270: 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e  _OPEN_MAIN_JOURN
6280: 41 4c 20 20 20 20 20 30 78 30 30 30 30 30 38 30  AL     0x0000080
6290: 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a  0  /* VFS only *
62a0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
62b0: 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e  _OPEN_TEMP_JOURN
62c0: 41 4c 20 20 20 20 20 30 78 30 30 30 30 31 30 30  AL     0x0000100
62d0: 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a  0  /* VFS only *
62e0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
62f0: 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c  _OPEN_SUBJOURNAL
6300: 20 20 20 20 20 20 20 30 78 30 30 30 30 32 30 30         0x0000200
6310: 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a  0  /* VFS only *
6320: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
6330: 5f 4f 50 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55  _OPEN_MASTER_JOU
6340: 52 4e 41 4c 20 20 20 30 78 30 30 30 30 34 30 30  RNAL   0x0000400
6350: 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a  0  /* VFS only *
6360: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
6370: 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 20 20 20  _OPEN_NOMUTEX   
6380: 20 20 20 20 20 20 20 30 78 30 30 30 30 38 30 30         0x0000800
6390: 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c  0  /* Ok for sql
63a0: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a  ite3_open_v2() *
63b0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
63c0: 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 20  _OPEN_FULLMUTEX 
63d0: 20 20 20 20 20 20 20 30 78 30 30 30 31 30 30 30         0x0001000
63e0: 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c  0  /* Ok for sql
63f0: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a  ite3_open_v2() *
6400: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
6410: 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48  _OPEN_SHAREDCACH
6420: 45 20 20 20 20 20 20 30 78 30 30 30 32 30 30 30  E      0x0002000
6430: 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c  0  /* Ok for sql
6440: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a  ite3_open_v2() *
6450: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
6460: 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43  _OPEN_PRIVATECAC
6470: 48 45 20 20 20 20 20 30 78 30 30 30 34 30 30 30  HE     0x0004000
6480: 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c  0  /* Ok for sql
6490: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a  ite3_open_v2() *
64a0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
64b0: 5f 4f 50 45 4e 5f 57 41 4c 20 20 20 20 20 20 20  _OPEN_WAL       
64c0: 20 20 20 20 20 20 20 30 78 30 30 30 38 30 30 30         0x0008000
64d0: 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a  0  /* VFS only *
64e0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
64f0: 5f 4f 50 45 4e 5f 46 49 4c 45 50 52 4f 54 45 43  _OPEN_FILEPROTEC
6500: 54 49 4f 4e 5f 4d 41 53 4b 20 20 20 20 20 20 20  TION_MASK       
6510: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
6520: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 37 30            0x0070
6530: 30 30 30 30 0a 0a 2f 2a 20 52 65 73 65 72 76 65  0000../* Reserve
6540: 64 3a 20 20 20 20 20 20 20 20 20 20 20 20 20 20  d:              
6550: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 46             0x00F
6560: 30 30 30 30 30 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20  00000 */../*.** 
6570: 43 41 50 49 33 52 45 46 3a 20 44 65 76 69 63 65  CAPI3REF: Device
6580: 20 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73   Characteristics
6590: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 44 65 76 69  .**.** The xDevi
65a0: 63 65 43 68 61 72 61 63 74 65 72 69 73 74 69 63  ceCharacteristic
65b0: 73 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20  s method of the 
65c0: 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68  [sqlite3_io_meth
65d0: 6f 64 73 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 72  ods].** object r
65e0: 65 74 75 72 6e 73 20 61 6e 20 69 6e 74 65 67 65  eturns an intege
65f0: 72 20 77 68 69 63 68 20 69 73 20 61 20 76 65 63  r which is a vec
6600: 74 6f 72 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20  tor of these.** 
6610: 62 69 74 20 76 61 6c 75 65 73 20 65 78 70 72 65  bit values expre
6620: 73 73 69 6e 67 20 49 2f 4f 20 63 68 61 72 61 63  ssing I/O charac
6630: 74 65 72 69 73 74 69 63 73 20 6f 66 20 74 68 65  teristics of the
6640: 20 6d 61 73 73 20 73 74 6f 72 61 67 65 0a 2a 2a   mass storage.**
6650: 20 64 65 76 69 63 65 20 74 68 61 74 20 68 6f 6c   device that hol
6660: 64 73 20 74 68 65 20 66 69 6c 65 20 74 68 61 74  ds the file that
6670: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f   the [sqlite3_io
6680: 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 72 65 66  _methods].** ref
6690: 65 72 73 20 74 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68  ers to..**.** Th
66a0: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
66b0: 54 4f 4d 49 43 20 70 72 6f 70 65 72 74 79 20 6d  TOMIC property m
66c0: 65 61 6e 73 20 74 68 61 74 20 61 6c 6c 20 77 72  eans that all wr
66d0: 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73  ites of.** any s
66e0: 69 7a 65 20 61 72 65 20 61 74 6f 6d 69 63 2e 20  ize are atomic. 
66f0: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41   The SQLITE_IOCA
6700: 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75  P_ATOMICnnn valu
6710: 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20  es.** mean that 
6720: 77 72 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73  writes of blocks
6730: 20 74 68 61 74 20 61 72 65 20 6e 6e 6e 20 62 79   that are nnn by
6740: 74 65 73 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a  tes in size and.
6750: 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65 64 20 74  ** are aligned t
6760: 6f 20 61 6e 20 61 64 64 72 65 73 73 20 77 68 69  o an address whi
6770: 63 68 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72  ch is an integer
6780: 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20   multiple of.** 
6790: 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e 20  nnn are atomic. 
67a0: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41   The SQLITE_IOCA
67b0: 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 76 61  P_SAFE_APPEND va
67c0: 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61  lue means.** tha
67d0: 74 20 77 68 65 6e 20 64 61 74 61 20 69 73 20 61  t when data is a
67e0: 70 70 65 6e 64 65 64 20 74 6f 20 61 20 66 69 6c  ppended to a fil
67f0: 65 2c 20 74 68 65 20 64 61 74 61 20 69 73 20 61  e, the data is a
6800: 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74  ppended.** first
6810: 20 74 68 65 6e 20 74 68 65 20 73 69 7a 65 20 6f   then the size o
6820: 66 20 74 68 65 20 66 69 6c 65 20 69 73 20 65 78  f the file is ex
6830: 74 65 6e 64 65 64 2c 20 6e 65 76 65 72 20 74 68  tended, never th
6840: 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20 61  e other.** way a
6850: 72 6f 75 6e 64 2e 20 20 54 68 65 20 53 51 4c 49  round.  The SQLI
6860: 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54  TE_IOCAP_SEQUENT
6870: 49 41 4c 20 70 72 6f 70 65 72 74 79 20 6d 65 61  IAL property mea
6880: 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72  ns that.** infor
6890: 6d 61 74 69 6f 6e 20 69 73 20 77 72 69 74 74 65  mation is writte
68a0: 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20 74 68 65  n to disk in the
68b0: 20 73 61 6d 65 20 6f 72 64 65 72 20 61 73 20 63   same order as c
68c0: 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74  alls.** to xWrit
68d0: 65 28 29 2e 20 20 54 68 65 20 53 51 4c 49 54 45  e().  The SQLITE
68e0: 5f 49 4f 43 41 50 5f 50 4f 57 45 52 53 41 46 45  _IOCAP_POWERSAFE
68f0: 5f 4f 56 45 52 57 52 49 54 45 20 70 72 6f 70 65  _OVERWRITE prope
6900: 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74 0a 2a  rty means that.*
6910: 2a 20 61 66 74 65 72 20 72 65 62 6f 6f 74 20 66  * after reboot f
6920: 6f 6c 6c 6f 77 69 6e 67 20 61 20 63 72 61 73 68  ollowing a crash
6930: 20 6f 72 20 70 6f 77 65 72 20 6c 6f 73 73 2c 20   or power loss, 
6940: 74 68 65 20 6f 6e 6c 79 20 62 79 74 65 73 20 69  the only bytes i
6950: 6e 20 61 0a 2a 2a 20 66 69 6c 65 20 74 68 61 74  n a.** file that
6960: 20 77 65 72 65 20 77 72 69 74 74 65 6e 20 61 74   were written at
6970: 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
6980: 20 6c 65 76 65 6c 20 6d 69 67 68 74 20 68 61 76   level might hav
6990: 65 20 63 68 61 6e 67 65 64 0a 2a 2a 20 61 6e 64  e changed.** and
69a0: 20 74 68 61 74 20 61 64 6a 61 63 65 6e 74 20 62   that adjacent b
69b0: 79 74 65 73 2c 20 65 76 65 6e 20 62 79 74 65 73  ytes, even bytes
69c0: 20 77 69 74 68 69 6e 20 74 68 65 20 73 61 6d 65   within the same
69d0: 20 73 65 63 74 6f 72 20 61 72 65 0a 2a 2a 20 67   sector are.** g
69e0: 75 61 72 61 6e 74 65 65 64 20 74 6f 20 62 65 20  uaranteed to be 
69f0: 75 6e 63 68 61 6e 67 65 64 2e 20 20 54 68 65 20  unchanged.  The 
6a00: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 55 4e 44  SQLITE_IOCAP_UND
6a10: 45 4c 45 54 41 42 4c 45 5f 57 48 45 4e 5f 4f 50  ELETABLE_WHEN_OP
6a20: 45 4e 0a 2a 2a 20 66 6c 61 67 20 69 6e 64 69 63  EN.** flag indic
6a30: 61 74 65 73 20 74 68 61 74 20 61 20 66 69 6c 65  ates that a file
6a40: 20 63 61 6e 6e 6f 74 20 62 65 20 64 65 6c 65 74   cannot be delet
6a50: 65 64 20 77 68 65 6e 20 6f 70 65 6e 2e 20 20 54  ed when open.  T
6a60: 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 49 4f 43  he.** SQLITE_IOC
6a70: 41 50 5f 49 4d 4d 55 54 41 42 4c 45 20 66 6c 61  AP_IMMUTABLE fla
6a80: 67 20 69 6e 64 69 63 61 74 65 73 20 74 68 61 74  g indicates that
6a90: 20 74 68 65 20 66 69 6c 65 20 69 73 20 6f 6e 0a   the file is on.
6aa0: 2a 2a 20 72 65 61 64 2d 6f 6e 6c 79 20 6d 65 64  ** read-only med
6ab0: 69 61 20 61 6e 64 20 63 61 6e 6e 6f 74 20 62 65  ia and cannot be
6ac0: 20 63 68 61 6e 67 65 64 20 65 76 65 6e 20 62 79   changed even by
6ad0: 20 70 72 6f 63 65 73 73 65 73 20 77 69 74 68 0a   processes with.
6ae0: 2a 2a 20 65 6c 65 76 61 74 65 64 20 70 72 69 76  ** elevated priv
6af0: 69 6c 65 67 65 73 2e 0a 2a 2f 0a 23 64 65 66 69  ileges..*/.#defi
6b00: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
6b10: 41 54 4f 4d 49 43 20 20 20 20 20 20 20 20 20 20  ATOMIC          
6b20: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30         0x0000000
6b30: 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  1.#define SQLITE
6b40: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 35 31 32  _IOCAP_ATOMIC512
6b50: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78                0x
6b60: 30 30 30 30 30 30 30 32 0a 23 64 65 66 69 6e 65  00000002.#define
6b70: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
6b80: 4f 4d 49 43 31 4b 20 20 20 20 20 20 20 20 20 20  OMIC1K          
6b90: 20 20 20 20 20 30 78 30 30 30 30 30 30 30 34 0a       0x00000004.
6ba0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
6bb0: 4f 43 41 50 5f 41 54 4f 4d 49 43 32 4b 20 20 20  OCAP_ATOMIC2K   
6bc0: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30              0x00
6bd0: 30 30 30 30 30 38 0a 23 64 65 66 69 6e 65 20 53  000008.#define S
6be0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
6bf0: 49 43 34 4b 20 20 20 20 20 20 20 20 20 20 20 20  IC4K            
6c00: 20 20 20 30 78 30 30 30 30 30 30 31 30 0a 23 64     0x00000010.#d
6c10: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
6c20: 41 50 5f 41 54 4f 4d 49 43 38 4b 20 20 20 20 20  AP_ATOMIC8K     
6c30: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
6c40: 30 30 32 30 0a 23 64 65 66 69 6e 65 20 53 51 4c  0020.#define SQL
6c50: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
6c60: 31 36 4b 20 20 20 20 20 20 20 20 20 20 20 20 20  16K             
6c70: 20 30 78 30 30 30 30 30 30 34 30 0a 23 64 65 66   0x00000040.#def
6c80: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
6c90: 5f 41 54 4f 4d 49 43 33 32 4b 20 20 20 20 20 20  _ATOMIC32K      
6ca0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
6cb0: 38 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  80.#define SQLIT
6cc0: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 36 34  E_IOCAP_ATOMIC64
6cd0: 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30  K              0
6ce0: 78 30 30 30 30 30 31 30 30 0a 23 64 65 66 69 6e  x00000100.#defin
6cf0: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53  e SQLITE_IOCAP_S
6d00: 41 46 45 5f 41 50 50 45 4e 44 20 20 20 20 20 20  AFE_APPEND      
6d10: 20 20 20 20 20 20 30 78 30 30 30 30 30 32 30 30        0x00000200
6d20: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6d30: 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c  IOCAP_SEQUENTIAL
6d40: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30               0x0
6d50: 30 30 30 30 34 30 30 0a 23 64 65 66 69 6e 65 20  0000400.#define 
6d60: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 55 4e 44  SQLITE_IOCAP_UND
6d70: 45 4c 45 54 41 42 4c 45 5f 57 48 45 4e 5f 4f 50  ELETABLE_WHEN_OP
6d80: 45 4e 20 20 30 78 30 30 30 30 30 38 30 30 0a 23  EN  0x00000800.#
6d90: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
6da0: 43 41 50 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56  CAP_POWERSAFE_OV
6db0: 45 52 57 52 49 54 45 20 20 20 20 30 78 30 30 30  ERWRITE    0x000
6dc0: 30 31 30 30 30 0a 23 64 65 66 69 6e 65 20 53 51  01000.#define SQ
6dd0: 4c 49 54 45 5f 49 4f 43 41 50 5f 49 4d 4d 55 54  LITE_IOCAP_IMMUT
6de0: 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 20 20  ABLE            
6df0: 20 20 30 78 30 30 30 30 32 30 30 30 0a 0a 2f 2a    0x00002000../*
6e00: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 69  .** CAPI3REF: Fi
6e10: 6c 65 20 4c 6f 63 6b 69 6e 67 20 4c 65 76 65 6c  le Locking Level
6e20: 73 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75  s.**.** SQLite u
6e30: 73 65 73 20 6f 6e 65 20 6f 66 20 74 68 65 73 65  ses one of these
6e40: 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20   integer values 
6e50: 61 73 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a  as the second.**
6e60: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 63 61 6c   argument to cal
6e70: 6c 73 20 69 74 20 6d 61 6b 65 73 20 74 6f 20 74  ls it makes to t
6e80: 68 65 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20 78  he xLock() and x
6e90: 55 6e 6c 6f 63 6b 28 29 20 6d 65 74 68 6f 64 73  Unlock() methods
6ea0: 0a 2a 2a 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74  .** of an [sqlit
6eb0: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f  e3_io_methods] o
6ec0: 62 6a 65 63 74 2e 0a 2a 2f 0a 23 64 65 66 69 6e  bject..*/.#defin
6ed0: 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f  e SQLITE_LOCK_NO
6ee0: 4e 45 20 20 20 20 20 20 20 20 20 20 30 0a 23 64  NE          0.#d
6ef0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43  efine SQLITE_LOC
6f00: 4b 5f 53 48 41 52 45 44 20 20 20 20 20 20 20 20  K_SHARED        
6f10: 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  1.#define SQLITE
6f20: 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44 20 20  _LOCK_RESERVED  
6f30: 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51      2.#define SQ
6f40: 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e  LITE_LOCK_PENDIN
6f50: 47 20 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e  G       3.#defin
6f60: 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58  e SQLITE_LOCK_EX
6f70: 43 4c 55 53 49 56 45 20 20 20 20 20 34 0a 0a 2f  CLUSIVE     4../
6f80: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53  *.** CAPI3REF: S
6f90: 79 6e 63 68 72 6f 6e 69 7a 61 74 69 6f 6e 20 54  ynchronization T
6fa0: 79 70 65 20 46 6c 61 67 73 0a 2a 2a 0a 2a 2a 20  ype Flags.**.** 
6fb0: 57 68 65 6e 20 53 51 4c 69 74 65 20 69 6e 76 6f  When SQLite invo
6fc0: 6b 65 73 20 74 68 65 20 78 53 79 6e 63 28 29 20  kes the xSync() 
6fd0: 6d 65 74 68 6f 64 20 6f 66 20 61 6e 0a 2a 2a 20  method of an.** 
6fe0: 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68  [sqlite3_io_meth
6ff0: 6f 64 73 5d 20 6f 62 6a 65 63 74 20 69 74 20 75  ods] object it u
7000: 73 65 73 20 61 20 63 6f 6d 62 69 6e 61 74 69 6f  ses a combinatio
7010: 6e 20 6f 66 0a 2a 2a 20 74 68 65 73 65 20 69 6e  n of.** these in
7020: 74 65 67 65 72 20 76 61 6c 75 65 73 20 61 73 20  teger values as 
7030: 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  the second argum
7040: 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20  ent..**.** When 
7050: 74 68 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f  the SQLITE_SYNC_
7060: 44 41 54 41 4f 4e 4c 59 20 66 6c 61 67 20 69 73  DATAONLY flag is
7070: 20 75 73 65 64 2c 20 69 74 20 6d 65 61 6e 73 20   used, it means 
7080: 74 68 61 74 20 74 68 65 0a 2a 2a 20 73 79 6e 63  that the.** sync
7090: 20 6f 70 65 72 61 74 69 6f 6e 20 6f 6e 6c 79 20   operation only 
70a0: 6e 65 65 64 73 20 74 6f 20 66 6c 75 73 68 20 64  needs to flush d
70b0: 61 74 61 20 74 6f 20 6d 61 73 73 20 73 74 6f 72  ata to mass stor
70c0: 61 67 65 2e 20 20 49 6e 6f 64 65 0a 2a 2a 20 69  age.  Inode.** i
70d0: 6e 66 6f 72 6d 61 74 69 6f 6e 20 6e 65 65 64 20  nformation need 
70e0: 6e 6f 74 20 62 65 20 66 6c 75 73 68 65 64 2e 20  not be flushed. 
70f0: 49 66 20 74 68 65 20 6c 6f 77 65 72 20 66 6f 75  If the lower fou
7100: 72 20 62 69 74 73 20 6f 66 20 74 68 65 20 66 6c  r bits of the fl
7110: 61 67 0a 2a 2a 20 65 71 75 61 6c 20 53 51 4c 49  ag.** equal SQLI
7120: 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 2c 20  TE_SYNC_NORMAL, 
7130: 74 68 61 74 20 6d 65 61 6e 73 20 74 6f 20 75 73  that means to us
7140: 65 20 6e 6f 72 6d 61 6c 20 66 73 79 6e 63 28 29  e normal fsync()
7150: 20 73 65 6d 61 6e 74 69 63 73 2e 0a 2a 2a 20 49   semantics..** I
7160: 66 20 74 68 65 20 6c 6f 77 65 72 20 66 6f 75 72  f the lower four
7170: 20 62 69 74 73 20 65 71 75 61 6c 20 53 51 4c 49   bits equal SQLI
7180: 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 2c 20 74 68  TE_SYNC_FULL, th
7190: 61 74 20 6d 65 61 6e 73 0a 2a 2a 20 74 6f 20 75  at means.** to u
71a0: 73 65 20 4d 61 63 20 4f 53 20 58 20 73 74 79 6c  se Mac OS X styl
71b0: 65 20 66 75 6c 6c 73 79 6e 63 20 69 6e 73 74 65  e fullsync inste
71c0: 61 64 20 6f 66 20 66 73 79 6e 63 28 29 2e 0a 2a  ad of fsync()..*
71d0: 2a 0a 2a 2a 20 44 6f 20 6e 6f 74 20 63 6f 6e 66  *.** Do not conf
71e0: 75 73 65 20 74 68 65 20 53 51 4c 49 54 45 5f 53  use the SQLITE_S
71f0: 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53  YNC_NORMAL and S
7200: 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20  QLITE_SYNC_FULL 
7210: 66 6c 61 67 73 0a 2a 2a 20 77 69 74 68 20 74 68  flags.** with th
7220: 65 20 5b 50 52 41 47 4d 41 20 73 79 6e 63 68 72  e [PRAGMA synchr
7230: 6f 6e 6f 75 73 5d 3d 4e 4f 52 4d 41 4c 20 61 6e  onous]=NORMAL an
7240: 64 20 5b 50 52 41 47 4d 41 20 73 79 6e 63 68 72  d [PRAGMA synchr
7250: 6f 6e 6f 75 73 5d 3d 46 55 4c 4c 0a 2a 2a 20 73  onous]=FULL.** s
7260: 65 74 74 69 6e 67 73 2e 20 20 54 68 65 20 5b 73  ettings.  The [s
7270: 79 6e 63 68 72 6f 6e 6f 75 73 20 70 72 61 67 6d  ynchronous pragm
7280: 61 5d 20 64 65 74 65 72 6d 69 6e 65 73 20 77 68  a] determines wh
7290: 65 6e 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 0a  en calls to the.
72a0: 2a 2a 20 78 53 79 6e 63 20 56 46 53 20 6d 65 74  ** xSync VFS met
72b0: 68 6f 64 20 6f 63 63 75 72 20 61 6e 64 20 61 70  hod occur and ap
72c0: 70 6c 69 65 73 20 75 6e 69 66 6f 72 6d 6c 79 20  plies uniformly 
72d0: 61 63 72 6f 73 73 20 61 6c 6c 20 70 6c 61 74 66  across all platf
72e0: 6f 72 6d 73 2e 0a 2a 2a 20 54 68 65 20 53 51 4c  orms..** The SQL
72f0: 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20  ITE_SYNC_NORMAL 
7300: 61 6e 64 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f  and SQLITE_SYNC_
7310: 46 55 4c 4c 20 66 6c 61 67 73 20 64 65 74 65 72  FULL flags deter
7320: 6d 69 6e 65 20 68 6f 77 0a 2a 2a 20 65 6e 65 72  mine how.** ener
7330: 67 65 74 69 63 20 6f 72 20 72 69 67 6f 72 6f 75  getic or rigorou
7340: 73 20 6f 72 20 66 6f 72 63 65 66 75 6c 20 74 68  s or forceful th
7350: 65 20 73 79 6e 63 20 6f 70 65 72 61 74 69 6f 6e  e sync operation
7360: 73 20 61 72 65 20 61 6e 64 0a 2a 2a 20 6f 6e 6c  s are and.** onl
7370: 79 20 6d 61 6b 65 20 61 20 64 69 66 66 65 72 65  y make a differe
7380: 6e 63 65 20 6f 6e 20 4d 61 63 20 4f 53 58 20 66  nce on Mac OSX f
7390: 6f 72 20 74 68 65 20 64 65 66 61 75 6c 74 20 53  or the default S
73a0: 51 4c 69 74 65 20 63 6f 64 65 2e 0a 2a 2a 20 28  QLite code..** (
73b0: 54 68 69 72 64 2d 70 61 72 74 79 20 56 46 53 20  Third-party VFS 
73c0: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
73d0: 6d 69 67 68 74 20 61 6c 73 6f 20 6d 61 6b 65 20  might also make 
73e0: 74 68 65 20 64 69 73 74 69 6e 63 74 69 6f 6e 0a  the distinction.
73f0: 2a 2a 20 62 65 74 77 65 65 6e 20 53 51 4c 49 54  ** between SQLIT
7400: 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e  E_SYNC_NORMAL an
7410: 64 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55  d SQLITE_SYNC_FU
7420: 4c 4c 2c 20 62 75 74 20 61 6d 6f 6e 67 20 74 68  LL, but among th
7430: 65 0a 2a 2a 20 6f 70 65 72 61 74 69 6e 67 20 73  e.** operating s
7440: 79 73 74 65 6d 73 20 6e 61 74 69 76 65 6c 79 20  ystems natively 
7450: 73 75 70 70 6f 72 74 65 64 20 62 79 20 53 51 4c  supported by SQL
7460: 69 74 65 2c 20 6f 6e 6c 79 20 4d 61 63 20 4f 53  ite, only Mac OS
7470: 58 0a 2a 2a 20 63 61 72 65 73 20 61 62 6f 75 74  X.** cares about
7480: 20 74 68 65 20 64 69 66 66 65 72 65 6e 63 65 2e   the difference.
7490: 29 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ).*/.#define SQL
74a0: 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20  ITE_SYNC_NORMAL 
74b0: 20 20 20 20 20 20 20 30 78 30 30 30 30 32 0a 23         0x00002.#
74c0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 59  define SQLITE_SY
74d0: 4e 43 5f 46 55 4c 4c 20 20 20 20 20 20 20 20 20  NC_FULL         
74e0: 20 30 78 30 30 30 30 33 0a 23 64 65 66 69 6e 65   0x00003.#define
74f0: 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54   SQLITE_SYNC_DAT
7500: 41 4f 4e 4c 59 20 20 20 20 20 20 30 78 30 30 30  AONLY      0x000
7510: 31 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  10../*.** CAPI3R
7520: 45 46 3a 20 4f 53 20 49 6e 74 65 72 66 61 63 65  EF: OS Interface
7530: 20 4f 70 65 6e 20 46 69 6c 65 20 48 61 6e 64 6c   Open File Handl
7540: 65 0a 2a 2a 0a 2a 2a 20 41 6e 20 5b 73 71 6c 69  e.**.** An [sqli
7550: 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74  te3_file] object
7560: 20 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20 6f   represents an o
7570: 70 65 6e 20 66 69 6c 65 20 69 6e 20 74 68 65 20  pen file in the 
7580: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  .** [sqlite3_vfs
7590: 20 7c 20 4f 53 20 69 6e 74 65 72 66 61 63 65 20   | OS interface 
75a0: 6c 61 79 65 72 5d 2e 20 20 49 6e 64 69 76 69 64  layer].  Individ
75b0: 75 61 6c 20 4f 53 20 69 6e 74 65 72 66 61 63 65  ual OS interface
75c0: 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  .** implementati
75d0: 6f 6e 73 20 77 69 6c 6c 0a 2a 2a 20 77 61 6e 74  ons will.** want
75e0: 20 74 6f 20 73 75 62 63 6c 61 73 73 20 74 68 69   to subclass thi
75f0: 73 20 6f 62 6a 65 63 74 20 62 79 20 61 70 70 65  s object by appe
7600: 6e 64 69 6e 67 20 61 64 64 69 74 69 6f 6e 61 6c  nding additional
7610: 20 66 69 65 6c 64 73 0a 2a 2a 20 66 6f 72 20 74   fields.** for t
7620: 68 65 69 72 20 6f 77 6e 20 75 73 65 2e 20 20 54  heir own use.  T
7630: 68 65 20 70 4d 65 74 68 6f 64 73 20 65 6e 74 72  he pMethods entr
7640: 79 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  y is a pointer t
7650: 6f 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  o an.** [sqlite3
7660: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a  _io_methods] obj
7670: 65 63 74 20 74 68 61 74 20 64 65 66 69 6e 65 73  ect that defines
7680: 20 6d 65 74 68 6f 64 73 20 66 6f 72 20 70 65 72   methods for per
7690: 66 6f 72 6d 69 6e 67 0a 2a 2a 20 49 2f 4f 20 6f  forming.** I/O o
76a0: 70 65 72 61 74 69 6f 6e 73 20 6f 6e 20 74 68 65  perations on the
76b0: 20 6f 70 65 6e 20 66 69 6c 65 2e 0a 2a 2f 0a 74   open file..*/.t
76c0: 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71  ypedef struct sq
76d0: 6c 69 74 65 33 5f 66 69 6c 65 20 73 71 6c 69 74  lite3_file sqlit
76e0: 65 33 5f 66 69 6c 65 3b 0a 73 74 72 75 63 74 20  e3_file;.struct 
76f0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 20 7b 0a 20  sqlite3_file {. 
7700: 20 63 6f 6e 73 74 20 73 74 72 75 63 74 20 73 71   const struct sq
7710: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
7720: 20 2a 70 4d 65 74 68 6f 64 73 3b 20 20 2f 2a 20   *pMethods;  /* 
7730: 4d 65 74 68 6f 64 73 20 66 6f 72 20 61 6e 20 6f  Methods for an o
7740: 70 65 6e 20 66 69 6c 65 20 2a 2f 0a 7d 3b 0a 0a  pen file */.};..
7750: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
7760: 4f 53 20 49 6e 74 65 72 66 61 63 65 20 46 69 6c  OS Interface Fil
7770: 65 20 56 69 72 74 75 61 6c 20 4d 65 74 68 6f 64  e Virtual Method
7780: 73 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 45  s Object.**.** E
7790: 76 65 72 79 20 66 69 6c 65 20 6f 70 65 6e 65 64  very file opened
77a0: 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33   by the [sqlite3
77b0: 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 6d 65 74 68  _vfs.xOpen] meth
77c0: 6f 64 20 70 6f 70 75 6c 61 74 65 73 20 61 6e 0a  od populates an.
77d0: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  ** [sqlite3_file
77e0: 5d 20 6f 62 6a 65 63 74 20 28 6f 72 2c 20 6d 6f  ] object (or, mo
77f0: 72 65 20 63 6f 6d 6d 6f 6e 6c 79 2c 20 61 20 73  re commonly, a s
7800: 75 62 63 6c 61 73 73 20 6f 66 20 74 68 65 0a 2a  ubclass of the.*
7810: 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d  * [sqlite3_file]
7820: 20 6f 62 6a 65 63 74 29 20 77 69 74 68 20 61 20   object) with a 
7830: 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e  pointer to an in
7840: 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f  stance of this o
7850: 62 6a 65 63 74 2e 0a 2a 2a 20 54 68 69 73 20 6f  bject..** This o
7860: 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74 68  bject defines th
7870: 65 20 6d 65 74 68 6f 64 73 20 75 73 65 64 20 74  e methods used t
7880: 6f 20 70 65 72 66 6f 72 6d 20 76 61 72 69 6f 75  o perform variou
7890: 73 20 6f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 20  s operations.** 
78a0: 61 67 61 69 6e 73 74 20 74 68 65 20 6f 70 65 6e  against the open
78b0: 20 66 69 6c 65 20 72 65 70 72 65 73 65 6e 74 65   file represente
78c0: 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65  d by the [sqlite
78d0: 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 2e 0a  3_file] object..
78e0: 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 5b 73 71  **.** If the [sq
78f0: 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d  lite3_vfs.xOpen]
7900: 20 6d 65 74 68 6f 64 20 73 65 74 73 20 74 68 65   method sets the
7910: 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d   sqlite3_file.pM
7920: 65 74 68 6f 64 73 20 65 6c 65 6d 65 6e 74 20 0a  ethods element .
7930: 2a 2a 20 74 6f 20 61 20 6e 6f 6e 2d 4e 55 4c 4c  ** to a non-NULL
7940: 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 74   pointer, then t
7950: 68 65 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  he sqlite3_io_me
7960: 74 68 6f 64 73 2e 78 43 6c 6f 73 65 20 6d 65 74  thods.xClose met
7970: 68 6f 64 0a 2a 2a 20 6d 61 79 20 62 65 20 69 6e  hod.** may be in
7980: 76 6f 6b 65 64 20 65 76 65 6e 20 69 66 20 74 68  voked even if th
7990: 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78  e [sqlite3_vfs.x
79a0: 4f 70 65 6e 5d 20 72 65 70 6f 72 74 65 64 20 74  Open] reported t
79b0: 68 61 74 20 69 74 20 66 61 69 6c 65 64 2e 20 20  hat it failed.  
79c0: 54 68 65 0a 2a 2a 20 6f 6e 6c 79 20 77 61 79 20  The.** only way 
79d0: 74 6f 20 70 72 65 76 65 6e 74 20 61 20 63 61 6c  to prevent a cal
79e0: 6c 20 74 6f 20 78 43 6c 6f 73 65 20 66 6f 6c 6c  l to xClose foll
79f0: 6f 77 69 6e 67 20 61 20 66 61 69 6c 65 64 20 5b  owing a failed [
7a00: 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65  sqlite3_vfs.xOpe
7a10: 6e 5d 0a 2a 2a 20 69 73 20 66 6f 72 20 74 68 65  n].** is for the
7a20: 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f   [sqlite3_vfs.xO
7a30: 70 65 6e 5d 20 74 6f 20 73 65 74 20 74 68 65 20  pen] to set the 
7a40: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65  sqlite3_file.pMe
7a50: 74 68 6f 64 73 20 65 6c 65 6d 65 6e 74 0a 2a 2a  thods element.**
7a60: 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20   to NULL..**.** 
7a70: 54 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65  The flags argume
7a80: 6e 74 20 74 6f 20 78 53 79 6e 63 20 6d 61 79 20  nt to xSync may 
7a90: 62 65 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54  be one of [SQLIT
7aa0: 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 5d 20 6f  E_SYNC_NORMAL] o
7ab0: 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 53 59 4e  r.** [SQLITE_SYN
7ac0: 43 5f 46 55 4c 4c 5d 2e 20 20 54 68 65 20 66 69  C_FULL].  The fi
7ad0: 72 73 74 20 63 68 6f 69 63 65 20 69 73 20 74 68  rst choice is th
7ae0: 65 20 6e 6f 72 6d 61 6c 20 66 73 79 6e 63 28 29  e normal fsync()
7af0: 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20  ..** The second 
7b00: 63 68 6f 69 63 65 20 69 73 20 61 20 4d 61 63 20  choice is a Mac 
7b10: 4f 53 20 58 20 73 74 79 6c 65 20 66 75 6c 6c 73  OS X style fulls
7b20: 79 6e 63 2e 20 20 54 68 65 20 5b 53 51 4c 49 54  ync.  The [SQLIT
7b30: 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 5d  E_SYNC_DATAONLY]
7b40: 0a 2a 2a 20 66 6c 61 67 20 6d 61 79 20 62 65 20  .** flag may be 
7b50: 4f 52 65 64 20 69 6e 20 74 6f 20 69 6e 64 69 63  ORed in to indic
7b60: 61 74 65 20 74 68 61 74 20 6f 6e 6c 79 20 74 68  ate that only th
7b70: 65 20 64 61 74 61 20 6f 66 20 74 68 65 20 66 69  e data of the fi
7b80: 6c 65 0a 2a 2a 20 61 6e 64 20 6e 6f 74 20 69 74  le.** and not it
7b90: 73 20 69 6e 6f 64 65 20 6e 65 65 64 73 20 74 6f  s inode needs to
7ba0: 20 62 65 20 73 79 6e 63 65 64 2e 0a 2a 2a 0a 2a   be synced..**.*
7bb0: 2a 20 54 68 65 20 69 6e 74 65 67 65 72 20 76 61  * The integer va
7bc0: 6c 75 65 73 20 74 6f 20 78 4c 6f 63 6b 28 29 20  lues to xLock() 
7bd0: 61 6e 64 20 78 55 6e 6c 6f 63 6b 28 29 20 61 72  and xUnlock() ar
7be0: 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 3c 75 6c 3e  e one of.** <ul>
7bf0: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
7c00: 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 0a 2a 2a 20  _LOCK_NONE],.** 
7c10: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43  <li> [SQLITE_LOC
7c20: 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 3c 6c  K_SHARED],.** <l
7c30: 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  i> [SQLITE_LOCK_
7c40: 52 45 53 45 52 56 45 44 5d 2c 0a 2a 2a 20 3c 6c  RESERVED],.** <l
7c50: 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  i> [SQLITE_LOCK_
7c60: 50 45 4e 44 49 4e 47 5d 2c 20 6f 72 0a 2a 2a 20  PENDING], or.** 
7c70: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43  <li> [SQLITE_LOC
7c80: 4b 5f 45 58 43 4c 55 53 49 56 45 5d 2e 0a 2a 2a  K_EXCLUSIVE]..**
7c90: 20 3c 2f 75 6c 3e 0a 2a 2a 20 78 4c 6f 63 6b 28   </ul>.** xLock(
7ca0: 29 20 69 6e 63 72 65 61 73 65 73 20 74 68 65 20  ) increases the 
7cb0: 6c 6f 63 6b 2e 20 78 55 6e 6c 6f 63 6b 28 29 20  lock. xUnlock() 
7cc0: 64 65 63 72 65 61 73 65 73 20 74 68 65 20 6c 6f  decreases the lo
7cd0: 63 6b 2e 0a 2a 2a 20 54 68 65 20 78 43 68 65 63  ck..** The xChec
7ce0: 6b 52 65 73 65 72 76 65 64 4c 6f 63 6b 28 29 20  kReservedLock() 
7cf0: 6d 65 74 68 6f 64 20 63 68 65 63 6b 73 20 77 68  method checks wh
7d00: 65 74 68 65 72 20 61 6e 79 20 64 61 74 61 62 61  ether any databa
7d10: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 0a 2a  se connection,.*
7d20: 2a 20 65 69 74 68 65 72 20 69 6e 20 74 68 69 73  * either in this
7d30: 20 70 72 6f 63 65 73 73 20 6f 72 20 69 6e 20 73   process or in s
7d40: 6f 6d 65 20 6f 74 68 65 72 20 70 72 6f 63 65 73  ome other proces
7d50: 73 2c 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20  s, is holding a 
7d60: 52 45 53 45 52 56 45 44 2c 0a 2a 2a 20 50 45 4e  RESERVED,.** PEN
7d70: 44 49 4e 47 2c 20 6f 72 20 45 58 43 4c 55 53 49  DING, or EXCLUSI
7d80: 56 45 20 6c 6f 63 6b 20 6f 6e 20 74 68 65 20 66  VE lock on the f
7d90: 69 6c 65 2e 20 20 49 74 20 72 65 74 75 72 6e 73  ile.  It returns
7da0: 20 74 72 75 65 0a 2a 2a 20 69 66 20 73 75 63 68   true.** if such
7db0: 20 61 20 6c 6f 63 6b 20 65 78 69 73 74 73 20 61   a lock exists a
7dc0: 6e 64 20 66 61 6c 73 65 20 6f 74 68 65 72 77 69  nd false otherwi
7dd0: 73 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 46  se..**.** The xF
7de0: 69 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d 65 74  ileControl() met
7df0: 68 6f 64 20 69 73 20 61 20 67 65 6e 65 72 69 63  hod is a generic
7e00: 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 20   interface that 
7e10: 61 6c 6c 6f 77 73 20 63 75 73 74 6f 6d 0a 2a 2a  allows custom.**
7e20: 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74   VFS implementat
7e30: 69 6f 6e 73 20 74 6f 20 64 69 72 65 63 74 6c 79  ions to directly
7e40: 20 63 6f 6e 74 72 6f 6c 20 61 6e 20 6f 70 65 6e   control an open
7e50: 20 66 69 6c 65 20 75 73 69 6e 67 20 74 68 65 0a   file using the.
7e60: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  ** [sqlite3_file
7e70: 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 69 6e 74 65  _control()] inte
7e80: 72 66 61 63 65 2e 20 20 54 68 65 20 73 65 63 6f  rface.  The seco
7e90: 6e 64 20 22 6f 70 22 20 61 72 67 75 6d 65 6e 74  nd "op" argument
7ea0: 20 69 73 20 61 6e 0a 2a 2a 20 69 6e 74 65 67 65   is an.** intege
7eb0: 72 20 6f 70 63 6f 64 65 2e 20 20 54 68 65 20 74  r opcode.  The t
7ec0: 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73  hird argument is
7ed0: 20 61 20 67 65 6e 65 72 69 63 20 70 6f 69 6e 74   a generic point
7ee0: 65 72 20 69 6e 74 65 6e 64 65 64 20 74 6f 0a 2a  er intended to.*
7ef0: 2a 20 70 6f 69 6e 74 20 74 6f 20 61 20 73 74 72  * point to a str
7f00: 75 63 74 75 72 65 20 74 68 61 74 20 6d 61 79 20  ucture that may 
7f10: 63 6f 6e 74 61 69 6e 20 61 72 67 75 6d 65 6e 74  contain argument
7f20: 73 20 6f 72 20 73 70 61 63 65 20 69 6e 20 77 68  s or space in wh
7f30: 69 63 68 20 74 6f 0a 2a 2a 20 77 72 69 74 65 20  ich to.** write 
7f40: 72 65 74 75 72 6e 20 76 61 6c 75 65 73 2e 20 20  return values.  
7f50: 50 6f 74 65 6e 74 69 61 6c 20 75 73 65 73 20 66  Potential uses f
7f60: 6f 72 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 28  or xFileControl(
7f70: 29 20 6d 69 67 68 74 20 62 65 0a 2a 2a 20 66 75  ) might be.** fu
7f80: 6e 63 74 69 6f 6e 73 20 74 6f 20 65 6e 61 62 6c  nctions to enabl
7f90: 65 20 62 6c 6f 63 6b 69 6e 67 20 6c 6f 63 6b 73  e blocking locks
7fa0: 20 77 69 74 68 20 74 69 6d 65 6f 75 74 73 2c 20   with timeouts, 
7fb0: 74 6f 20 63 68 61 6e 67 65 20 74 68 65 0a 2a 2a  to change the.**
7fc0: 20 6c 6f 63 6b 69 6e 67 20 73 74 72 61 74 65 67   locking strateg
7fd0: 79 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 74  y (for example t
7fe0: 6f 20 75 73 65 20 64 6f 74 2d 66 69 6c 65 20 6c  o use dot-file l
7ff0: 6f 63 6b 73 29 2c 20 74 6f 20 69 6e 71 75 69 72  ocks), to inquir
8000: 65 0a 2a 2a 20 61 62 6f 75 74 20 74 68 65 20 73  e.** about the s
8010: 74 61 74 75 73 20 6f 66 20 61 20 6c 6f 63 6b 2c  tatus of a lock,
8020: 20 6f 72 20 74 6f 20 62 72 65 61 6b 20 73 74 61   or to break sta
8030: 6c 65 20 6c 6f 63 6b 73 2e 20 20 54 68 65 20 53  le locks.  The S
8040: 51 4c 69 74 65 0a 2a 2a 20 63 6f 72 65 20 72 65  QLite.** core re
8050: 73 65 72 76 65 73 20 61 6c 6c 20 6f 70 63 6f 64  serves all opcod
8060: 65 73 20 6c 65 73 73 20 74 68 61 6e 20 31 30 30  es less than 100
8070: 20 66 6f 72 20 69 74 73 20 6f 77 6e 20 75 73 65   for its own use
8080: 2e 0a 2a 2a 20 41 20 5b 66 69 6c 65 20 63 6f 6e  ..** A [file con
8090: 74 72 6f 6c 20 6f 70 63 6f 64 65 73 20 7c 20 6c  trol opcodes | l
80a0: 69 73 74 20 6f 66 20 6f 70 63 6f 64 65 73 5d 20  ist of opcodes] 
80b0: 6c 65 73 73 20 74 68 61 6e 20 31 30 30 20 69 73  less than 100 is
80c0: 20 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20 41   available..** A
80d0: 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74  pplications that
80e0: 20 64 65 66 69 6e 65 20 61 20 63 75 73 74 6f 6d   define a custom
80f0: 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65   xFileControl me
8100: 74 68 6f 64 20 73 68 6f 75 6c 64 20 75 73 65 20  thod should use 
8110: 6f 70 63 6f 64 65 73 0a 2a 2a 20 67 72 65 61 74  opcodes.** great
8120: 65 72 20 74 68 61 6e 20 31 30 30 20 74 6f 20 61  er than 100 to a
8130: 76 6f 69 64 20 63 6f 6e 66 6c 69 63 74 73 2e 20  void conflicts. 
8140: 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74   VFS implementat
8150: 69 6f 6e 73 20 73 68 6f 75 6c 64 0a 2a 2a 20 72  ions should.** r
8160: 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f  eturn [SQLITE_NO
8170: 54 46 4f 55 4e 44 5d 20 66 6f 72 20 66 69 6c 65  TFOUND] for file
8180: 20 63 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64 65 73   control opcodes
8190: 20 74 68 61 74 20 74 68 65 79 20 64 6f 20 6e 6f   that they do no
81a0: 74 0a 2a 2a 20 72 65 63 6f 67 6e 69 7a 65 2e 0a  t.** recognize..
81b0: 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 65 63 74 6f  **.** The xSecto
81c0: 72 53 69 7a 65 28 29 20 6d 65 74 68 6f 64 20 72  rSize() method r
81d0: 65 74 75 72 6e 73 20 74 68 65 20 73 65 63 74 6f  eturns the secto
81e0: 72 20 73 69 7a 65 20 6f 66 20 74 68 65 0a 2a 2a  r size of the.**
81f0: 20 64 65 76 69 63 65 20 74 68 61 74 20 75 6e 64   device that und
8200: 65 72 6c 69 65 73 20 74 68 65 20 66 69 6c 65 2e  erlies the file.
8210: 20 20 54 68 65 20 73 65 63 74 6f 72 20 73 69 7a    The sector siz
8220: 65 20 69 73 20 74 68 65 0a 2a 2a 20 6d 69 6e 69  e is the.** mini
8230: 6d 75 6d 20 77 72 69 74 65 20 74 68 61 74 20 63  mum write that c
8240: 61 6e 20 62 65 20 70 65 72 66 6f 72 6d 65 64 20  an be performed 
8250: 77 69 74 68 6f 75 74 20 64 69 73 74 75 72 62 69  without disturbi
8260: 6e 67 0a 2a 2a 20 6f 74 68 65 72 20 62 79 74 65  ng.** other byte
8270: 73 20 69 6e 20 74 68 65 20 66 69 6c 65 2e 20 20  s in the file.  
8280: 54 68 65 20 78 44 65 76 69 63 65 43 68 61 72 61  The xDeviceChara
8290: 63 74 65 72 69 73 74 69 63 73 28 29 0a 2a 2a 20  cteristics().** 
82a0: 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 61  method returns a
82b0: 20 62 69 74 20 76 65 63 74 6f 72 20 64 65 73 63   bit vector desc
82c0: 72 69 62 69 6e 67 20 62 65 68 61 76 69 6f 72 73  ribing behaviors
82d0: 20 6f 66 20 74 68 65 0a 2a 2a 20 75 6e 64 65 72   of the.** under
82e0: 6c 79 69 6e 67 20 64 65 76 69 63 65 3a 0a 2a 2a  lying device:.**
82f0: 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
8300: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
8310: 54 4f 4d 49 43 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  TOMIC].** <li> [
8320: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
8330: 4d 49 43 35 31 32 5d 0a 2a 2a 20 3c 6c 69 3e 20  MIC512].** <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 31 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20  OMIC1K].** <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 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20  OMIC2K].** <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 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20  OMIC4K].** <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 38 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20  OMIC8K].** <li> 
83c0: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54  [SQLITE_IOCAP_AT
83d0: 4f 4d 49 43 31 36 4b 5d 0a 2a 2a 20 3c 6c 69 3e  OMIC16K].** <li>
83e0: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
83f0: 54 4f 4d 49 43 33 32 4b 5d 0a 2a 2a 20 3c 6c 69  TOMIC32K].** <li
8400: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
8410: 41 54 4f 4d 49 43 36 34 4b 5d 0a 2a 2a 20 3c 6c  ATOMIC64K].** <l
8420: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  i> [SQLITE_IOCAP
8430: 5f 53 41 46 45 5f 41 50 50 45 4e 44 5d 0a 2a 2a  _SAFE_APPEND].**
8440: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f   <li> [SQLITE_IO
8450: 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 5d 0a  CAP_SEQUENTIAL].
8460: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
8470: 49 4f 43 41 50 5f 55 4e 44 45 4c 45 54 41 42 4c  IOCAP_UNDELETABL
8480: 45 5f 57 48 45 4e 5f 4f 50 45 4e 5d 0a 2a 2a 20  E_WHEN_OPEN].** 
8490: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43  <li> [SQLITE_IOC
84a0: 41 50 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45  AP_POWERSAFE_OVE
84b0: 52 57 52 49 54 45 5d 0a 2a 2a 20 3c 6c 69 3e 20  RWRITE].** <li> 
84c0: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 49 4d  [SQLITE_IOCAP_IM
84d0: 4d 55 54 41 42 4c 45 5d 0a 2a 2a 20 3c 2f 75 6c  MUTABLE].** </ul
84e0: 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49  >.**.** The SQLI
84f0: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20  TE_IOCAP_ATOMIC 
8500: 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74  property means t
8510: 68 61 74 20 61 6c 6c 20 77 72 69 74 65 73 20 6f  hat all writes o
8520: 66 0a 2a 2a 20 61 6e 79 20 73 69 7a 65 20 61 72  f.** any size ar
8530: 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53  e atomic.  The S
8540: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
8550: 49 43 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a 20  ICnnn values.** 
8560: 6d 65 61 6e 20 74 68 61 74 20 77 72 69 74 65 73  mean that writes
8570: 20 6f 66 20 62 6c 6f 63 6b 73 20 74 68 61 74 20   of blocks that 
8580: 61 72 65 20 6e 6e 6e 20 62 79 74 65 73 20 69 6e  are nnn bytes in
8590: 20 73 69 7a 65 20 61 6e 64 0a 2a 2a 20 61 72 65   size and.** are
85a0: 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 61   aligned to an a
85b0: 64 64 72 65 73 73 20 77 68 69 63 68 20 69 73 20  ddress which is 
85c0: 61 6e 20 69 6e 74 65 67 65 72 20 6d 75 6c 74 69  an integer multi
85d0: 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 72  ple of.** nnn ar
85e0: 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53  e atomic.  The S
85f0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45  QLITE_IOCAP_SAFE
8600: 5f 41 50 50 45 4e 44 20 76 61 6c 75 65 20 6d 65  _APPEND value me
8610: 61 6e 73 0a 2a 2a 20 74 68 61 74 20 77 68 65 6e  ans.** that when
8620: 20 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 65   data is appende
8630: 64 20 74 6f 20 61 20 66 69 6c 65 2c 20 74 68 65  d to a file, the
8640: 20 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 65   data is appende
8650: 64 0a 2a 2a 20 66 69 72 73 74 20 74 68 65 6e 20  d.** first then 
8660: 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20  the size of the 
8670: 66 69 6c 65 20 69 73 20 65 78 74 65 6e 64 65 64  file is extended
8680: 2c 20 6e 65 76 65 72 20 74 68 65 20 6f 74 68 65  , never the othe
8690: 72 0a 2a 2a 20 77 61 79 20 61 72 6f 75 6e 64 2e  r.** way around.
86a0: 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43    The SQLITE_IOC
86b0: 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 70 72  AP_SEQUENTIAL pr
86c0: 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61  operty means tha
86d0: 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  t.** information
86e0: 20 69 73 20 77 72 69 74 74 65 6e 20 74 6f 20 64   is written to d
86f0: 69 73 6b 20 69 6e 20 74 68 65 20 73 61 6d 65 20  isk in the same 
8700: 6f 72 64 65 72 20 61 73 20 63 61 6c 6c 73 0a 2a  order as calls.*
8710: 2a 20 74 6f 20 78 57 72 69 74 65 28 29 2e 0a 2a  * to xWrite()..*
8720: 2a 0a 2a 2a 20 49 66 20 78 52 65 61 64 28 29 20  *.** If xRead() 
8730: 72 65 74 75 72 6e 73 20 53 51 4c 49 54 45 5f 49  returns SQLITE_I
8740: 4f 45 52 52 5f 53 48 4f 52 54 5f 52 45 41 44 20  OERR_SHORT_READ 
8750: 69 74 20 6d 75 73 74 20 61 6c 73 6f 20 66 69 6c  it must also fil
8760: 6c 0a 2a 2a 20 69 6e 20 74 68 65 20 75 6e 72 65  l.** in the unre
8770: 61 64 20 70 6f 72 74 69 6f 6e 73 20 6f 66 20 74  ad portions of t
8780: 68 65 20 62 75 66 66 65 72 20 77 69 74 68 20 7a  he buffer with z
8790: 65 72 6f 73 2e 20 20 41 20 56 46 53 20 74 68 61  eros.  A VFS tha
87a0: 74 0a 2a 2a 20 66 61 69 6c 73 20 74 6f 20 7a 65  t.** fails to ze
87b0: 72 6f 2d 66 69 6c 6c 20 73 68 6f 72 74 20 72 65  ro-fill short re
87c0: 61 64 73 20 6d 69 67 68 74 20 73 65 65 6d 20 74  ads might seem t
87d0: 6f 20 77 6f 72 6b 2e 20 20 48 6f 77 65 76 65 72  o work.  However
87e0: 2c 0a 2a 2a 20 66 61 69 6c 75 72 65 20 74 6f 20  ,.** failure to 
87f0: 7a 65 72 6f 2d 66 69 6c 6c 20 73 68 6f 72 74 20  zero-fill short 
8800: 72 65 61 64 73 20 77 69 6c 6c 20 65 76 65 6e 74  reads will event
8810: 75 61 6c 6c 79 20 6c 65 61 64 20 74 6f 0a 2a 2a  ually lead to.**
8820: 20 64 61 74 61 62 61 73 65 20 63 6f 72 72 75 70   database corrup
8830: 74 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 65 64 65 66  tion..*/.typedef
8840: 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
8850: 69 6f 5f 6d 65 74 68 6f 64 73 20 73 71 6c 69 74  io_methods sqlit
8860: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 3b 0a 73  e3_io_methods;.s
8870: 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6f  truct sqlite3_io
8880: 5f 6d 65 74 68 6f 64 73 20 7b 0a 20 20 69 6e 74  _methods {.  int
8890: 20 69 56 65 72 73 69 6f 6e 3b 0a 20 20 69 6e 74   iVersion;.  int
88a0: 20 28 2a 78 43 6c 6f 73 65 29 28 73 71 6c 69 74   (*xClose)(sqlit
88b0: 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74  e3_file*);.  int
88c0: 20 28 2a 78 52 65 61 64 29 28 73 71 6c 69 74 65   (*xRead)(sqlite
88d0: 33 5f 66 69 6c 65 2a 2c 20 76 6f 69 64 2a 2c 20  3_file*, void*, 
88e0: 69 6e 74 20 69 41 6d 74 2c 20 73 71 6c 69 74 65  int iAmt, sqlite
88f0: 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 29 3b 0a  3_int64 iOfst);.
8900: 20 20 69 6e 74 20 28 2a 78 57 72 69 74 65 29 28    int (*xWrite)(
8910: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 63  sqlite3_file*, c
8920: 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 20  onst void*, int 
8930: 69 41 6d 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e  iAmt, sqlite3_in
8940: 74 36 34 20 69 4f 66 73 74 29 3b 0a 20 20 69 6e  t64 iOfst);.  in
8950: 74 20 28 2a 78 54 72 75 6e 63 61 74 65 29 28 73  t (*xTruncate)(s
8960: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71  qlite3_file*, sq
8970: 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 69 7a 65  lite3_int64 size
8980: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 79 6e 63  );.  int (*xSync
8990: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
89a0: 20 69 6e 74 20 66 6c 61 67 73 29 3b 0a 20 20 69   int flags);.  i
89b0: 6e 74 20 28 2a 78 46 69 6c 65 53 69 7a 65 29 28  nt (*xFileSize)(
89c0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73  sqlite3_file*, s
89d0: 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a 70 53  qlite3_int64 *pS
89e0: 69 7a 65 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4c  ize);.  int (*xL
89f0: 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ock)(sqlite3_fil
8a00: 65 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20  e*, int);.  int 
8a10: 28 2a 78 55 6e 6c 6f 63 6b 29 28 73 71 6c 69 74  (*xUnlock)(sqlit
8a20: 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a  e3_file*, int);.
8a30: 20 20 69 6e 74 20 28 2a 78 43 68 65 63 6b 52 65    int (*xCheckRe
8a40: 73 65 72 76 65 64 4c 6f 63 6b 29 28 73 71 6c 69  servedLock)(sqli
8a50: 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 2a  te3_file*, int *
8a60: 70 52 65 73 4f 75 74 29 3b 0a 20 20 69 6e 74 20  pResOut);.  int 
8a70: 28 2a 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 29 28  (*xFileControl)(
8a80: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69  sqlite3_file*, i
8a90: 6e 74 20 6f 70 2c 20 76 6f 69 64 20 2a 70 41 72  nt op, void *pAr
8aa0: 67 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 65 63  g);.  int (*xSec
8ab0: 74 6f 72 53 69 7a 65 29 28 73 71 6c 69 74 65 33  torSize)(sqlite3
8ac0: 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28  _file*);.  int (
8ad0: 2a 78 44 65 76 69 63 65 43 68 61 72 61 63 74 65  *xDeviceCharacte
8ae0: 72 69 73 74 69 63 73 29 28 73 71 6c 69 74 65 33  ristics)(sqlite3
8af0: 5f 66 69 6c 65 2a 29 3b 0a 20 20 2f 2a 20 4d 65  _file*);.  /* Me
8b00: 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20  thods above are 
8b10: 76 61 6c 69 64 20 66 6f 72 20 76 65 72 73 69 6f  valid for versio
8b20: 6e 20 31 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78  n 1 */.  int (*x
8b30: 53 68 6d 4d 61 70 29 28 73 71 6c 69 74 65 33 5f  ShmMap)(sqlite3_
8b40: 66 69 6c 65 2a 2c 20 69 6e 74 20 69 50 67 2c 20  file*, int iPg, 
8b50: 69 6e 74 20 70 67 73 7a 2c 20 69 6e 74 2c 20 76  int pgsz, int, v
8b60: 6f 69 64 20 76 6f 6c 61 74 69 6c 65 2a 2a 29 3b  oid volatile**);
8b70: 0a 20 20 69 6e 74 20 28 2a 78 53 68 6d 4c 6f 63  .  int (*xShmLoc
8b80: 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  k)(sqlite3_file*
8b90: 2c 20 69 6e 74 20 6f 66 66 73 65 74 2c 20 69 6e  , int offset, in
8ba0: 74 20 6e 2c 20 69 6e 74 20 66 6c 61 67 73 29 3b  t n, int flags);
8bb0: 0a 20 20 76 6f 69 64 20 28 2a 78 53 68 6d 42 61  .  void (*xShmBa
8bc0: 72 72 69 65 72 29 28 73 71 6c 69 74 65 33 5f 66  rrier)(sqlite3_f
8bd0: 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78  ile*);.  int (*x
8be0: 53 68 6d 55 6e 6d 61 70 29 28 73 71 6c 69 74 65  ShmUnmap)(sqlite
8bf0: 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 64 65 6c  3_file*, int del
8c00: 65 74 65 46 6c 61 67 29 3b 0a 20 20 2f 2a 20 4d  eteFlag);.  /* M
8c10: 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65  ethods above are
8c20: 20 76 61 6c 69 64 20 66 6f 72 20 76 65 72 73 69   valid for versi
8c30: 6f 6e 20 32 20 2a 2f 0a 20 20 69 6e 74 20 28 2a  on 2 */.  int (*
8c40: 78 46 65 74 63 68 29 28 73 71 6c 69 74 65 33 5f  xFetch)(sqlite3_
8c50: 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69  file*, sqlite3_i
8c60: 6e 74 36 34 20 69 4f 66 73 74 2c 20 69 6e 74 20  nt64 iOfst, int 
8c70: 69 41 6d 74 2c 20 76 6f 69 64 20 2a 2a 70 70 29  iAmt, void **pp)
8c80: 3b 0a 20 20 69 6e 74 20 28 2a 78 55 6e 66 65 74  ;.  int (*xUnfet
8c90: 63 68 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ch)(sqlite3_file
8ca0: 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  *, sqlite3_int64
8cb0: 20 69 4f 66 73 74 2c 20 76 6f 69 64 20 2a 70 29   iOfst, void *p)
8cc0: 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61  ;.  /* Methods a
8cd0: 62 6f 76 65 20 61 72 65 20 76 61 6c 69 64 20 66  bove are valid f
8ce0: 6f 72 20 76 65 72 73 69 6f 6e 20 33 20 2a 2f 0a  or version 3 */.
8cf0: 20 20 2f 2a 20 41 64 64 69 74 69 6f 6e 61 6c 20    /* Additional 
8d00: 6d 65 74 68 6f 64 73 20 6d 61 79 20 62 65 20 61  methods may be a
8d10: 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72  dded in future r
8d20: 65 6c 65 61 73 65 73 20 2a 2f 0a 7d 3b 0a 0a 2f  eleases */.};../
8d30: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53  *.** CAPI3REF: S
8d40: 74 61 6e 64 61 72 64 20 46 69 6c 65 20 43 6f 6e  tandard File Con
8d50: 74 72 6f 6c 20 4f 70 63 6f 64 65 73 0a 2a 2a 20  trol Opcodes.** 
8d60: 4b 45 59 57 4f 52 44 53 3a 20 7b 66 69 6c 65 20  KEYWORDS: {file 
8d70: 63 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64 65 73 7d  control opcodes}
8d80: 20 7b 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f   {file control o
8d90: 70 63 6f 64 65 7d 0a 2a 2a 0a 2a 2a 20 54 68 65  pcode}.**.** The
8da0: 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74  se integer const
8db0: 61 6e 74 73 20 61 72 65 20 6f 70 63 6f 64 65 73  ants are opcodes
8dc0: 20 66 6f 72 20 74 68 65 20 78 46 69 6c 65 43 6f   for the xFileCo
8dd0: 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 0a 2a 2a 20  ntrol method.** 
8de0: 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
8df0: 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65  io_methods] obje
8e00: 63 74 20 61 6e 64 20 66 6f 72 20 74 68 65 20 5b  ct and for the [
8e10: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e  sqlite3_file_con
8e20: 74 72 6f 6c 28 29 5d 0a 2a 2a 20 69 6e 74 65 72  trol()].** inter
8e30: 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  face..**.** <ul>
8e40: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
8e50: 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45  _FCNTL_LOCKSTATE
8e60: 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54  ]].** The [SQLIT
8e70: 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54  E_FCNTL_LOCKSTAT
8e80: 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65  E] opcode is use
8e90: 64 20 66 6f 72 20 64 65 62 75 67 67 69 6e 67 2e  d for debugging.
8ea0: 20 20 54 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65    This.** opcode
8eb0: 20 63 61 75 73 65 73 20 74 68 65 20 78 46 69 6c   causes the xFil
8ec0: 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20  eControl method 
8ed0: 74 6f 20 77 72 69 74 65 20 74 68 65 20 63 75 72  to write the cur
8ee0: 72 65 6e 74 20 73 74 61 74 65 20 6f 66 0a 2a 2a  rent state of.**
8ef0: 20 74 68 65 20 6c 6f 63 6b 20 28 6f 6e 65 20 6f   the lock (one o
8f00: 66 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e  f [SQLITE_LOCK_N
8f10: 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f  ONE], [SQLITE_LO
8f20: 43 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 5b  CK_SHARED],.** [
8f30: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45  SQLITE_LOCK_RESE
8f40: 52 56 45 44 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c  RVED], [SQLITE_L
8f50: 4f 43 4b 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f 72  OCK_PENDING], or
8f60: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58   [SQLITE_LOCK_EX
8f70: 43 4c 55 53 49 56 45 5d 29 0a 2a 2a 20 69 6e 74  CLUSIVE]).** int
8f80: 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 74 68 61  o an integer tha
8f90: 74 20 74 68 65 20 70 41 72 67 20 61 72 67 75 6d  t the pArg argum
8fa0: 65 6e 74 20 70 6f 69 6e 74 73 20 74 6f 2e 20 54  ent points to. T
8fb0: 68 69 73 20 63 61 70 61 62 69 6c 69 74 79 0a 2a  his capability.*
8fc0: 2a 20 69 73 20 75 73 65 64 20 64 75 72 69 6e 67  * is used during
8fd0: 20 74 65 73 74 69 6e 67 20 61 6e 64 20 69 73 20   testing and is 
8fe0: 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 77  only available w
8ff0: 68 65 6e 20 74 68 65 20 53 51 4c 49 54 45 5f 54  hen the SQLITE_T
9000: 45 53 54 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74  EST.** compile-t
9010: 69 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20 75 73  ime option is us
9020: 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  ed..**.** <li>[[
9030: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a  SQLITE_FCNTL_SIZ
9040: 45 5f 48 49 4e 54 5d 5d 0a 2a 2a 20 54 68 65 20  E_HINT]].** The 
9050: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49  [SQLITE_FCNTL_SI
9060: 5a 45 5f 48 49 4e 54 5d 20 6f 70 63 6f 64 65 20  ZE_HINT] opcode 
9070: 69 73 20 75 73 65 64 20 62 79 20 53 51 4c 69 74  is used by SQLit
9080: 65 20 74 6f 20 67 69 76 65 20 74 68 65 20 56 46  e to give the VF
9090: 53 0a 2a 2a 20 6c 61 79 65 72 20 61 20 68 69 6e  S.** layer a hin
90a0: 74 20 6f 66 20 68 6f 77 20 6c 61 72 67 65 20 74  t of how large t
90b0: 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
90c0: 20 77 69 6c 6c 20 67 72 6f 77 20 74 6f 20 62 65   will grow to be
90d0: 20 64 75 72 69 6e 67 20 74 68 65 0a 2a 2a 20 63   during the.** c
90e0: 75 72 72 65 6e 74 20 74 72 61 6e 73 61 63 74 69  urrent transacti
90f0: 6f 6e 2e 20 20 54 68 69 73 20 68 69 6e 74 20 69  on.  This hint i
9100: 73 20 6e 6f 74 20 67 75 61 72 61 6e 74 65 65 64  s not guaranteed
9110: 20 74 6f 20 62 65 20 61 63 63 75 72 61 74 65 20   to be accurate 
9120: 62 75 74 20 69 74 0a 2a 2a 20 69 73 20 6f 66 74  but it.** is oft
9130: 65 6e 20 63 6c 6f 73 65 2e 20 20 54 68 65 20 75  en close.  The u
9140: 6e 64 65 72 6c 79 69 6e 67 20 56 46 53 20 6d 69  nderlying VFS mi
9150: 67 68 74 20 63 68 6f 6f 73 65 20 74 6f 20 70 72  ght choose to pr
9160: 65 61 6c 6c 6f 63 61 74 65 20 64 61 74 61 62 61  eallocate databa
9170: 73 65 0a 2a 2a 20 66 69 6c 65 20 73 70 61 63 65  se.** file space
9180: 20 62 61 73 65 64 20 6f 6e 20 74 68 69 73 20 68   based on this h
9190: 69 6e 74 20 69 6e 20 6f 72 64 65 72 20 74 6f 20  int in order to 
91a0: 68 65 6c 70 20 77 72 69 74 65 73 20 74 6f 20 74  help writes to t
91b0: 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 66  he database.** f
91c0: 69 6c 65 20 72 75 6e 20 66 61 73 74 65 72 2e 0a  ile run faster..
91d0: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
91e0: 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53  TE_FCNTL_CHUNK_S
91f0: 49 5a 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51  IZE]].** The [SQ
9200: 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b  LITE_FCNTL_CHUNK
9210: 5f 53 49 5a 45 5d 20 6f 70 63 6f 64 65 20 69 73  _SIZE] opcode is
9220: 20 75 73 65 64 20 74 6f 20 72 65 71 75 65 73 74   used to request
9230: 20 74 68 61 74 20 74 68 65 20 56 46 53 0a 2a 2a   that the VFS.**
9240: 20 65 78 74 65 6e 64 73 20 61 6e 64 20 74 72 75   extends and tru
9250: 6e 63 61 74 65 73 20 74 68 65 20 64 61 74 61 62  ncates the datab
9260: 61 73 65 20 66 69 6c 65 20 69 6e 20 63 68 75 6e  ase file in chun
9270: 6b 73 20 6f 66 20 61 20 73 69 7a 65 20 73 70 65  ks of a size spe
9280: 63 69 66 69 65 64 0a 2a 2a 20 62 79 20 74 68 65  cified.** by the
9290: 20 75 73 65 72 2e 20 54 68 65 20 66 6f 75 72 74   user. The fourt
92a0: 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73  h argument to [s
92b0: 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74  qlite3_file_cont
92c0: 72 6f 6c 28 29 5d 20 73 68 6f 75 6c 64 20 0a 2a  rol()] should .*
92d0: 2a 20 70 6f 69 6e 74 20 74 6f 20 61 6e 20 69 6e  * point to an in
92e0: 74 65 67 65 72 20 28 74 79 70 65 20 69 6e 74 29  teger (type int)
92f0: 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20   containing the 
9300: 6e 65 77 20 63 68 75 6e 6b 2d 73 69 7a 65 20 74  new chunk-size t
9310: 6f 20 75 73 65 0a 2a 2a 20 66 6f 72 20 74 68 65  o use.** for the
9320: 20 6e 6f 6d 69 6e 61 74 65 64 20 64 61 74 61 62   nominated datab
9330: 61 73 65 2e 20 41 6c 6c 6f 63 61 74 69 6e 67 20  ase. Allocating 
9340: 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 73 70  database file sp
9350: 61 63 65 20 69 6e 20 6c 61 72 67 65 0a 2a 2a 20  ace in large.** 
9360: 63 68 75 6e 6b 73 20 28 73 61 79 20 31 4d 42 20  chunks (say 1MB 
9370: 61 74 20 61 20 74 69 6d 65 29 2c 20 6d 61 79 20  at a time), may 
9380: 72 65 64 75 63 65 20 66 69 6c 65 2d 73 79 73 74  reduce file-syst
9390: 65 6d 20 66 72 61 67 6d 65 6e 74 61 74 69 6f 6e  em fragmentation
93a0: 20 61 6e 64 0a 2a 2a 20 69 6d 70 72 6f 76 65 20   and.** improve 
93b0: 70 65 72 66 6f 72 6d 61 6e 63 65 20 6f 6e 20 73  performance on s
93c0: 6f 6d 65 20 73 79 73 74 65 6d 73 2e 0a 2a 2a 0a  ome systems..**.
93d0: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
93e0: 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54  FCNTL_FILE_POINT
93f0: 45 52 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  ER]].** The [SQL
9400: 49 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50  ITE_FCNTL_FILE_P
9410: 4f 49 4e 54 45 52 5d 20 6f 70 63 6f 64 65 20 69  OINTER] opcode i
9420: 73 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e  s used to obtain
9430: 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f   a pointer.** to
9440: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69   the [sqlite3_fi
9450: 6c 65 5d 20 6f 62 6a 65 63 74 20 61 73 73 6f 63  le] object assoc
9460: 69 61 74 65 64 20 77 69 74 68 20 61 20 70 61 72  iated with a par
9470: 74 69 63 75 6c 61 72 20 64 61 74 61 62 61 73 65  ticular database
9480: 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20  .** connection. 
9490: 20 53 65 65 20 61 6c 73 6f 20 5b 53 51 4c 49 54   See also [SQLIT
94a0: 45 5f 46 43 4e 54 4c 5f 4a 4f 55 52 4e 41 4c 5f  E_FCNTL_JOURNAL_
94b0: 50 4f 49 4e 54 45 52 5d 2e 0a 2a 2a 0a 2a 2a 20  POINTER]..**.** 
94c0: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e  <li>[[SQLITE_FCN
94d0: 54 4c 5f 4a 4f 55 52 4e 41 4c 5f 50 4f 49 4e 54  TL_JOURNAL_POINT
94e0: 45 52 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  ER]].** The [SQL
94f0: 49 54 45 5f 46 43 4e 54 4c 5f 4a 4f 55 52 4e 41  ITE_FCNTL_JOURNA
9500: 4c 5f 50 4f 49 4e 54 45 52 5d 20 6f 70 63 6f 64  L_POINTER] opcod
9510: 65 20 69 73 20 75 73 65 64 20 74 6f 20 6f 62 74  e is used to obt
9520: 61 69 6e 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a  ain a pointer.**
9530: 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
9540: 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 61 73  _file] object as
9550: 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68  sociated with th
9560: 65 20 6a 6f 75 72 6e 61 6c 20 66 69 6c 65 20 28  e journal file (
9570: 65 69 74 68 65 72 0a 2a 2a 20 74 68 65 20 5b 72  either.** the [r
9580: 6f 6c 6c 62 61 63 6b 20 6a 6f 75 72 6e 61 6c 5d  ollback journal]
9590: 20 6f 72 20 74 68 65 20 5b 77 72 69 74 65 2d 61   or the [write-a
95a0: 68 65 61 64 20 6c 6f 67 5d 29 20 66 6f 72 20 61  head log]) for a
95b0: 20 70 61 72 74 69 63 75 6c 61 72 20 64 61 74 61   particular data
95c0: 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69  base.** connecti
95d0: 6f 6e 2e 20 20 53 65 65 20 61 6c 73 6f 20 5b 53  on.  See also [S
95e0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45  QLITE_FCNTL_FILE
95f0: 5f 50 4f 49 4e 54 45 52 5d 2e 0a 2a 2a 0a 2a 2a  _POINTER]..**.**
9600: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
9610: 4e 54 4c 5f 53 59 4e 43 5f 4f 4d 49 54 54 45 44  NTL_SYNC_OMITTED
9620: 5d 5d 0a 2a 2a 20 4e 6f 20 6c 6f 6e 67 65 72 20  ]].** No longer 
9630: 69 6e 20 75 73 65 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  in use..**.** <l
9640: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
9650: 5f 53 59 4e 43 5d 5d 0a 2a 2a 20 54 68 65 20 5b  _SYNC]].** The [
9660: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e  SQLITE_FCNTL_SYN
9670: 43 5d 20 6f 70 63 6f 64 65 20 69 73 20 67 65 6e  C] opcode is gen
9680: 65 72 61 74 65 64 20 69 6e 74 65 72 6e 61 6c 6c  erated internall
9690: 79 20 62 79 20 53 51 4c 69 74 65 20 61 6e 64 0a  y by SQLite and.
96a0: 2a 2a 20 73 65 6e 74 20 74 6f 20 74 68 65 20 56  ** sent to the V
96b0: 46 53 20 69 6d 6d 65 64 69 61 74 65 6c 79 20 62  FS immediately b
96c0: 65 66 6f 72 65 20 74 68 65 20 78 53 79 6e 63 20  efore the xSync 
96d0: 6d 65 74 68 6f 64 20 69 73 20 69 6e 76 6f 6b 65  method is invoke
96e0: 64 20 6f 6e 20 61 0a 2a 2a 20 64 61 74 61 62 61  d on a.** databa
96f0: 73 65 20 66 69 6c 65 20 64 65 73 63 72 69 70 74  se file descript
9700: 6f 72 2e 20 4f 72 2c 20 69 66 20 74 68 65 20 78  or. Or, if the x
9710: 53 79 6e 63 20 6d 65 74 68 6f 64 20 69 73 20 6e  Sync method is n
9720: 6f 74 20 69 6e 76 6f 6b 65 64 20 0a 2a 2a 20 62  ot invoked .** b
9730: 65 63 61 75 73 65 20 74 68 65 20 75 73 65 72 20  ecause the user 
9740: 68 61 73 20 63 6f 6e 66 69 67 75 72 65 64 20 53  has configured S
9750: 51 4c 69 74 65 20 77 69 74 68 20 0a 2a 2a 20 5b  QLite with .** [
9760: 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f  PRAGMA synchrono
9770: 75 73 20 7c 20 50 52 41 47 4d 41 20 73 79 6e 63  us | PRAGMA sync
9780: 68 72 6f 6e 6f 75 73 3d 4f 46 46 5d 20 69 74 20  hronous=OFF] it 
9790: 69 73 20 69 6e 76 6f 6b 65 64 20 69 6e 20 70 6c  is invoked in pl
97a0: 61 63 65 20 0a 2a 2a 20 6f 66 20 74 68 65 20 78  ace .** of the x
97b0: 53 79 6e 63 20 6d 65 74 68 6f 64 2e 20 49 6e 20  Sync method. In 
97c0: 6d 6f 73 74 20 63 61 73 65 73 2c 20 74 68 65 20  most cases, the 
97d0: 70 6f 69 6e 74 65 72 20 61 72 67 75 6d 65 6e 74  pointer argument
97e0: 20 70 61 73 73 65 64 20 77 69 74 68 0a 2a 2a 20   passed with.** 
97f0: 74 68 69 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f  this file-contro
9800: 6c 20 69 73 20 4e 55 4c 4c 2e 20 48 6f 77 65 76  l is NULL. Howev
9810: 65 72 2c 20 69 66 20 74 68 65 20 64 61 74 61 62  er, if the datab
9820: 61 73 65 20 66 69 6c 65 20 69 73 20 62 65 69 6e  ase file is bein
9830: 67 20 73 79 6e 63 65 64 0a 2a 2a 20 61 73 20 70  g synced.** as p
9840: 61 72 74 20 6f 66 20 61 20 6d 75 6c 74 69 2d 64  art of a multi-d
9850: 61 74 61 62 61 73 65 20 63 6f 6d 6d 69 74 2c 20  atabase commit, 
9860: 74 68 65 20 61 72 67 75 6d 65 6e 74 20 70 6f 69  the argument poi
9870: 6e 74 73 20 74 6f 20 61 20 6e 75 6c 2d 74 65 72  nts to a nul-ter
9880: 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e  minated.** strin
9890: 67 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65  g containing the
98a0: 20 74 72 61 6e 73 61 63 74 69 6f 6e 73 20 6d 61   transactions ma
98b0: 73 74 65 72 2d 6a 6f 75 72 6e 61 6c 20 66 69 6c  ster-journal fil
98c0: 65 20 6e 61 6d 65 2e 20 56 46 53 65 73 20 74 68  e name. VFSes th
98d0: 61 74 20 0a 2a 2a 20 64 6f 20 6e 6f 74 20 6e 65  at .** do not ne
98e0: 65 64 20 74 68 69 73 20 73 69 67 6e 61 6c 20 73  ed this signal s
98f0: 68 6f 75 6c 64 20 73 69 6c 65 6e 74 6c 79 20 69  hould silently i
9900: 67 6e 6f 72 65 20 74 68 69 73 20 6f 70 63 6f 64  gnore this opcod
9910: 65 2e 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20  e. Applications 
9920: 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e 6f 74 20 63  .** should not c
9930: 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  all [sqlite3_fil
9940: 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 77 69 74  e_control()] wit
9950: 68 20 74 68 69 73 20 6f 70 63 6f 64 65 20 61 73  h this opcode as
9960: 20 64 6f 69 6e 67 20 73 6f 20 6d 61 79 20 0a 2a   doing so may .*
9970: 2a 20 64 69 73 72 75 70 74 20 74 68 65 20 6f 70  * disrupt the op
9980: 65 72 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 73  eration of the s
9990: 70 65 63 69 61 6c 69 7a 65 64 20 56 46 53 65 73  pecialized VFSes
99a0: 20 74 68 61 74 20 64 6f 20 72 65 71 75 69 72 65   that do require
99b0: 20 69 74 2e 20 20 0a 2a 2a 0a 2a 2a 20 3c 6c 69   it.  .**.** <li
99c0: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
99d0: 43 4f 4d 4d 49 54 5f 50 48 41 53 45 54 57 4f 5d  COMMIT_PHASETWO]
99e0: 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45  ].** The [SQLITE
99f0: 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 50 48  _FCNTL_COMMIT_PH
9a00: 41 53 45 54 57 4f 5d 20 6f 70 63 6f 64 65 20 69  ASETWO] opcode i
9a10: 73 20 67 65 6e 65 72 61 74 65 64 20 69 6e 74 65  s generated inte
9a20: 72 6e 61 6c 6c 79 20 62 79 20 53 51 4c 69 74 65  rnally by SQLite
9a30: 0a 2a 2a 20 61 6e 64 20 73 65 6e 74 20 74 6f 20  .** and sent to 
9a40: 74 68 65 20 56 46 53 20 61 66 74 65 72 20 61 20  the VFS after a 
9a50: 74 72 61 6e 73 61 63 74 69 6f 6e 20 68 61 73 20  transaction has 
9a60: 62 65 65 6e 20 63 6f 6d 6d 69 74 74 65 64 20 69  been committed i
9a70: 6d 6d 65 64 69 61 74 65 6c 79 0a 2a 2a 20 62 75  mmediately.** bu
9a80: 74 20 62 65 66 6f 72 65 20 74 68 65 20 64 61 74  t before the dat
9a90: 61 62 61 73 65 20 69 73 20 75 6e 6c 6f 63 6b 65  abase is unlocke
9aa0: 64 2e 20 56 46 53 65 73 20 74 68 61 74 20 64 6f  d. VFSes that do
9ab0: 20 6e 6f 74 20 6e 65 65 64 20 74 68 69 73 20 73   not need this s
9ac0: 69 67 6e 61 6c 0a 2a 2a 20 73 68 6f 75 6c 64 20  ignal.** should 
9ad0: 73 69 6c 65 6e 74 6c 79 20 69 67 6e 6f 72 65 20  silently ignore 
9ae0: 74 68 69 73 20 6f 70 63 6f 64 65 2e 20 41 70 70  this opcode. App
9af0: 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64  lications should
9b00: 20 6e 6f 74 20 63 61 6c 6c 0a 2a 2a 20 5b 73 71   not call.** [sq
9b10: 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72  lite3_file_contr
9b20: 6f 6c 28 29 5d 20 77 69 74 68 20 74 68 69 73 20  ol()] with this 
9b30: 6f 70 63 6f 64 65 20 61 73 20 64 6f 69 6e 67 20  opcode as doing 
9b40: 73 6f 20 6d 61 79 20 64 69 73 72 75 70 74 20 74  so may disrupt t
9b50: 68 65 20 0a 2a 2a 20 6f 70 65 72 61 74 69 6f 6e  he .** operation
9b60: 20 6f 66 20 74 68 65 20 73 70 65 63 69 61 6c 69   of the speciali
9b70: 7a 65 64 20 56 46 53 65 73 20 74 68 61 74 20 64  zed VFSes that d
9b80: 6f 20 72 65 71 75 69 72 65 20 69 74 2e 20 20 0a  o require it.  .
9b90: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
9ba0: 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 41  TE_FCNTL_WIN32_A
9bb0: 56 5f 52 45 54 52 59 5d 5d 0a 2a 2a 20 5e 54 68  V_RETRY]].** ^Th
9bc0: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
9bd0: 57 49 4e 33 32 5f 41 56 5f 52 45 54 52 59 5d 20  WIN32_AV_RETRY] 
9be0: 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 74  opcode is used t
9bf0: 6f 20 63 6f 6e 66 69 67 75 72 65 20 61 75 74 6f  o configure auto
9c00: 6d 61 74 69 63 0a 2a 2a 20 72 65 74 72 79 20 63  matic.** retry c
9c10: 6f 75 6e 74 73 20 61 6e 64 20 69 6e 74 65 72 76  ounts and interv
9c20: 61 6c 73 20 66 6f 72 20 63 65 72 74 61 69 6e 20  als for certain 
9c30: 64 69 73 6b 20 49 2f 4f 20 6f 70 65 72 61 74 69  disk I/O operati
9c40: 6f 6e 73 20 66 6f 72 20 74 68 65 0a 2a 2a 20 77  ons for the.** w
9c50: 69 6e 64 6f 77 73 20 5b 56 46 53 5d 20 69 6e 20  indows [VFS] in 
9c60: 6f 72 64 65 72 20 74 6f 20 70 72 6f 76 69 64 65  order to provide
9c70: 20 72 6f 62 75 73 74 6e 65 73 73 20 69 6e 20 74   robustness in t
9c80: 68 65 20 70 72 65 73 65 6e 63 65 20 6f 66 0a 2a  he presence of.*
9c90: 2a 20 61 6e 74 69 2d 76 69 72 75 73 20 70 72 6f  * anti-virus pro
9ca0: 67 72 61 6d 73 2e 20 20 42 79 20 64 65 66 61 75  grams.  By defau
9cb0: 6c 74 2c 20 74 68 65 20 77 69 6e 64 6f 77 73 20  lt, the windows 
9cc0: 56 46 53 20 77 69 6c 6c 20 72 65 74 72 79 20 66  VFS will retry f
9cd0: 69 6c 65 20 72 65 61 64 2c 0a 2a 2a 20 66 69 6c  ile read,.** fil
9ce0: 65 20 77 72 69 74 65 2c 20 61 6e 64 20 66 69 6c  e write, and fil
9cf0: 65 20 64 65 6c 65 74 65 20 6f 70 65 72 61 74 69  e delete operati
9d00: 6f 6e 73 20 75 70 20 74 6f 20 31 30 20 74 69 6d  ons up to 10 tim
9d10: 65 73 2c 20 77 69 74 68 20 61 20 64 65 6c 61 79  es, with a delay
9d20: 0a 2a 2a 20 6f 66 20 32 35 20 6d 69 6c 6c 69 73  .** of 25 millis
9d30: 65 63 6f 6e 64 73 20 62 65 66 6f 72 65 20 74 68  econds before th
9d40: 65 20 66 69 72 73 74 20 72 65 74 72 79 20 61 6e  e first retry an
9d50: 64 20 77 69 74 68 20 74 68 65 20 64 65 6c 61 79  d with the delay
9d60: 20 69 6e 63 72 65 61 73 69 6e 67 0a 2a 2a 20 62   increasing.** b
9d70: 79 20 61 6e 20 61 64 64 69 74 69 6f 6e 61 6c 20  y an additional 
9d80: 32 35 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20  25 milliseconds 
9d90: 77 69 74 68 20 65 61 63 68 20 73 75 62 73 65 71  with each subseq
9da0: 75 65 6e 74 20 72 65 74 72 79 2e 20 20 54 68 69  uent retry.  Thi
9db0: 73 0a 2a 2a 20 6f 70 63 6f 64 65 20 61 6c 6c 6f  s.** opcode allo
9dc0: 77 73 20 74 68 65 73 65 20 74 77 6f 20 76 61 6c  ws these two val
9dd0: 75 65 73 20 28 31 30 20 72 65 74 72 69 65 73 20  ues (10 retries 
9de0: 61 6e 64 20 32 35 20 6d 69 6c 6c 69 73 65 63 6f  and 25 milliseco
9df0: 6e 64 73 20 6f 66 20 64 65 6c 61 79 29 0a 2a 2a  nds of delay).**
9e00: 20 74 6f 20 62 65 20 61 64 6a 75 73 74 65 64 2e   to be adjusted.
9e10: 20 20 54 68 65 20 76 61 6c 75 65 73 20 61 72 65    The values are
9e20: 20 63 68 61 6e 67 65 64 20 66 6f 72 20 61 6c 6c   changed for all
9e30: 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
9e40: 74 69 6f 6e 73 0a 2a 2a 20 77 69 74 68 69 6e 20  tions.** within 
9e50: 74 68 65 20 73 61 6d 65 20 70 72 6f 63 65 73 73  the same process
9e60: 2e 20 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20  .  The argument 
9e70: 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
9e80: 61 6e 20 61 72 72 61 79 20 6f 66 20 74 77 6f 0a  an array of two.
9e90: 2a 2a 20 69 6e 74 65 67 65 72 73 20 77 68 65 72  ** integers wher
9ea0: 65 20 74 68 65 20 66 69 72 73 74 20 69 6e 74 65  e the first inte
9eb0: 67 65 72 20 69 20 74 68 65 20 6e 65 77 20 72 65  ger i the new re
9ec0: 74 72 79 20 63 6f 75 6e 74 20 61 6e 64 20 74 68  try count and th
9ed0: 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 69 6e 74 65  e second.** inte
9ee0: 67 65 72 20 69 73 20 74 68 65 20 64 65 6c 61 79  ger is the delay
9ef0: 2e 20 20 49 66 20 65 69 74 68 65 72 20 69 6e 74  .  If either int
9f00: 65 67 65 72 20 69 73 20 6e 65 67 61 74 69 76 65  eger is negative
9f10: 2c 20 74 68 65 6e 20 74 68 65 20 73 65 74 74 69  , then the setti
9f20: 6e 67 0a 2a 2a 20 69 73 20 6e 6f 74 20 63 68 61  ng.** is not cha
9f30: 6e 67 65 64 20 62 75 74 20 69 6e 73 74 65 61 64  nged but instead
9f40: 20 74 68 65 20 70 72 69 6f 72 20 76 61 6c 75 65   the prior value
9f50: 20 6f 66 20 74 68 61 74 20 73 65 74 74 69 6e 67   of that setting
9f60: 20 69 73 20 77 72 69 74 74 65 6e 0a 2a 2a 20 69   is written.** i
9f70: 6e 74 6f 20 74 68 65 20 61 72 72 61 79 20 65 6e  nto the array en
9f80: 74 72 79 2c 20 61 6c 6c 6f 77 69 6e 67 20 74 68  try, allowing th
9f90: 65 20 63 75 72 72 65 6e 74 20 72 65 74 72 79 20  e current retry 
9fa0: 73 65 74 74 69 6e 67 73 20 74 6f 20 62 65 0a 2a  settings to be.*
9fb0: 2a 20 69 6e 74 65 72 72 6f 67 61 74 65 64 2e 20  * interrogated. 
9fc0: 20 54 68 65 20 7a 44 62 4e 61 6d 65 20 70 61 72   The zDbName par
9fd0: 61 6d 65 74 65 72 20 69 73 20 69 67 6e 6f 72 65  ameter is ignore
9fe0: 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53  d..**.** <li>[[S
9ff0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 45 52 53  QLITE_FCNTL_PERS
a000: 49 53 54 5f 57 41 4c 5d 5d 0a 2a 2a 20 5e 54 68  IST_WAL]].** ^Th
a010: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
a020: 50 45 52 53 49 53 54 5f 57 41 4c 5d 20 6f 70 63  PERSIST_WAL] opc
a030: 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f 20 73  ode is used to s
a040: 65 74 20 6f 72 20 71 75 65 72 79 20 74 68 65 0a  et or query the.
a050: 2a 2a 20 70 65 72 73 69 73 74 65 6e 74 20 5b 57  ** persistent [W
a060: 41 4c 20 7c 20 57 72 69 74 65 20 41 68 65 61 64  AL | Write Ahead
a070: 20 4c 6f 67 5d 20 73 65 74 74 69 6e 67 2e 20 20   Log] setting.  
a080: 42 79 20 64 65 66 61 75 6c 74 2c 20 74 68 65 20  By default, the 
a090: 61 75 78 69 6c 69 61 72 79 0a 2a 2a 20 77 72 69  auxiliary.** wri
a0a0: 74 65 20 61 68 65 61 64 20 6c 6f 67 20 61 6e 64  te ahead log and
a0b0: 20 73 68 61 72 65 64 20 6d 65 6d 6f 72 79 20 66   shared memory f
a0c0: 69 6c 65 73 20 75 73 65 64 20 66 6f 72 20 74 72  iles used for tr
a0d0: 61 6e 73 61 63 74 69 6f 6e 20 63 6f 6e 74 72 6f  ansaction contro
a0e0: 6c 0a 2a 2a 20 61 72 65 20 61 75 74 6f 6d 61 74  l.** are automat
a0f0: 69 63 61 6c 6c 79 20 64 65 6c 65 74 65 64 20 77  ically deleted w
a100: 68 65 6e 20 74 68 65 20 6c 61 74 65 73 74 20 63  hen the latest c
a110: 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 74 68 65  onnection to the
a120: 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6c 6f   database.** clo
a130: 73 65 73 2e 20 20 53 65 74 74 69 6e 67 20 70 65  ses.  Setting pe
a140: 72 73 69 73 74 65 6e 74 20 57 41 4c 20 6d 6f 64  rsistent WAL mod
a150: 65 20 63 61 75 73 65 73 20 74 68 6f 73 65 20 66  e causes those f
a160: 69 6c 65 73 20 74 6f 20 70 65 72 73 69 73 74 20  iles to persist 
a170: 61 66 74 65 72 0a 2a 2a 20 63 6c 6f 73 65 2e 20  after.** close. 
a180: 20 50 65 72 73 69 73 74 69 6e 67 20 74 68 65 20   Persisting the 
a190: 66 69 6c 65 73 20 69 73 20 75 73 65 66 75 6c 20  files is useful 
a1a0: 77 68 65 6e 20 6f 74 68 65 72 20 70 72 6f 63 65  when other proce
a1b0: 73 73 65 73 20 74 68 61 74 20 64 6f 20 6e 6f 74  sses that do not
a1c0: 0a 2a 2a 20 68 61 76 65 20 77 72 69 74 65 20 70  .** have write p
a1d0: 65 72 6d 69 73 73 69 6f 6e 20 6f 6e 20 74 68 65  ermission on the
a1e0: 20 64 69 72 65 63 74 6f 72 79 20 63 6f 6e 74 61   directory conta
a1f0: 69 6e 69 6e 67 20 74 68 65 20 64 61 74 61 62 61  ining the databa
a200: 73 65 20 66 69 6c 65 20 77 61 6e 74 0a 2a 2a 20  se file want.** 
a210: 74 6f 20 72 65 61 64 20 74 68 65 20 64 61 74 61  to read the data
a220: 62 61 73 65 20 66 69 6c 65 2c 20 61 73 20 74 68  base file, as th
a230: 65 20 57 41 4c 20 61 6e 64 20 73 68 61 72 65 64  e WAL and shared
a240: 20 6d 65 6d 6f 72 79 20 66 69 6c 65 73 20 6d 75   memory files mu
a250: 73 74 20 65 78 69 73 74 0a 2a 2a 20 69 6e 20 6f  st exist.** in o
a260: 72 64 65 72 20 66 6f 72 20 74 68 65 20 64 61 74  rder for the dat
a270: 61 62 61 73 65 20 74 6f 20 62 65 20 72 65 61 64  abase to be read
a280: 61 62 6c 65 2e 20 20 54 68 65 20 66 6f 75 72 74  able.  The fourt
a290: 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a  h parameter to.*
a2a0: 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f  * [sqlite3_file_
a2b0: 63 6f 6e 74 72 6f 6c 28 29 5d 20 66 6f 72 20 74  control()] for t
a2c0: 68 69 73 20 6f 70 63 6f 64 65 20 73 68 6f 75 6c  his opcode shoul
a2d0: 64 20 62 65 20 61 20 70 6f 69 6e 74 65 72 20 74  d be a pointer t
a2e0: 6f 20 61 6e 20 69 6e 74 65 67 65 72 2e 0a 2a 2a  o an integer..**
a2f0: 20 54 68 61 74 20 69 6e 74 65 67 65 72 20 69 73   That integer is
a300: 20 30 20 74 6f 20 64 69 73 61 62 6c 65 20 70 65   0 to disable pe
a310: 72 73 69 73 74 65 6e 74 20 57 41 4c 20 6d 6f 64  rsistent WAL mod
a320: 65 20 6f 72 20 31 20 74 6f 20 65 6e 61 62 6c 65  e or 1 to enable
a330: 20 70 65 72 73 69 73 74 65 6e 74 0a 2a 2a 20 57   persistent.** W
a340: 41 4c 20 6d 6f 64 65 2e 20 20 49 66 20 74 68 65  AL mode.  If the
a350: 20 69 6e 74 65 67 65 72 20 69 73 20 2d 31 2c 20   integer is -1, 
a360: 74 68 65 6e 20 69 74 20 69 73 20 6f 76 65 72 77  then it is overw
a370: 72 69 74 74 65 6e 20 77 69 74 68 20 74 68 65 20  ritten with the 
a380: 63 75 72 72 65 6e 74 0a 2a 2a 20 57 41 4c 20 70  current.** WAL p
a390: 65 72 73 69 73 74 65 6e 63 65 20 73 65 74 74 69  ersistence setti
a3a0: 6e 67 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  ng..**.** <li>[[
a3b0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 4f 57  SQLITE_FCNTL_POW
a3c0: 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45  ERSAFE_OVERWRITE
a3d0: 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49  ]].** ^The [SQLI
a3e0: 54 45 5f 46 43 4e 54 4c 5f 50 4f 57 45 52 53 41  TE_FCNTL_POWERSA
a3f0: 46 45 5f 4f 56 45 52 57 52 49 54 45 5d 20 6f 70  FE_OVERWRITE] op
a400: 63 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f 20  code is used to 
a410: 73 65 74 20 6f 72 20 71 75 65 72 79 20 74 68 65  set or query the
a420: 0a 2a 2a 20 70 65 72 73 69 73 74 65 6e 74 20 22  .** persistent "
a430: 70 6f 77 65 72 73 61 66 65 2d 6f 76 65 72 77 72  powersafe-overwr
a440: 69 74 65 22 20 6f 72 20 22 50 53 4f 57 22 20 73  ite" or "PSOW" s
a450: 65 74 74 69 6e 67 2e 20 20 54 68 65 20 50 53 4f  etting.  The PSO
a460: 57 20 73 65 74 74 69 6e 67 0a 2a 2a 20 64 65 74  W setting.** det
a470: 65 72 6d 69 6e 65 73 20 74 68 65 20 5b 53 51 4c  ermines the [SQL
a480: 49 54 45 5f 49 4f 43 41 50 5f 50 4f 57 45 52 53  ITE_IOCAP_POWERS
a490: 41 46 45 5f 4f 56 45 52 57 52 49 54 45 5d 20 62  AFE_OVERWRITE] b
a4a0: 69 74 20 6f 66 20 74 68 65 0a 2a 2a 20 78 44 65  it of the.** xDe
a4b0: 76 69 63 65 43 68 61 72 61 63 74 65 72 69 73 74  viceCharacterist
a4c0: 69 63 73 20 6d 65 74 68 6f 64 73 2e 20 54 68 65  ics methods. The
a4d0: 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
a4e0: 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  r to.** [sqlite3
a4f0: 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d  _file_control()]
a500: 20 66 6f 72 20 74 68 69 73 20 6f 70 63 6f 64 65   for this opcode
a510: 20 73 68 6f 75 6c 64 20 62 65 20 61 20 70 6f 69   should be a poi
a520: 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67  nter to an integ
a530: 65 72 2e 0a 2a 2a 20 54 68 61 74 20 69 6e 74 65  er..** That inte
a540: 67 65 72 20 69 73 20 30 20 74 6f 20 64 69 73 61  ger is 0 to disa
a550: 62 6c 65 20 7a 65 72 6f 2d 64 61 6d 61 67 65 20  ble zero-damage 
a560: 6d 6f 64 65 20 6f 72 20 31 20 74 6f 20 65 6e 61  mode or 1 to ena
a570: 62 6c 65 20 7a 65 72 6f 2d 64 61 6d 61 67 65 0a  ble zero-damage.
a580: 2a 2a 20 6d 6f 64 65 2e 20 20 49 66 20 74 68 65  ** mode.  If the
a590: 20 69 6e 74 65 67 65 72 20 69 73 20 2d 31 2c 20   integer is -1, 
a5a0: 74 68 65 6e 20 69 74 20 69 73 20 6f 76 65 72 77  then it is overw
a5b0: 72 69 74 74 65 6e 20 77 69 74 68 20 74 68 65 20  ritten with the 
a5c0: 63 75 72 72 65 6e 74 0a 2a 2a 20 7a 65 72 6f 2d  current.** zero-
a5d0: 64 61 6d 61 67 65 20 6d 6f 64 65 20 73 65 74 74  damage mode sett
a5e0: 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  ing..**.** <li>[
a5f0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f 56  [SQLITE_FCNTL_OV
a600: 45 52 57 52 49 54 45 5d 5d 0a 2a 2a 20 5e 54 68  ERWRITE]].** ^Th
a610: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
a620: 4f 56 45 52 57 52 49 54 45 5d 20 6f 70 63 6f 64  OVERWRITE] opcod
a630: 65 20 69 73 20 69 6e 76 6f 6b 65 64 20 62 79 20  e is invoked by 
a640: 53 51 4c 69 74 65 20 61 66 74 65 72 20 6f 70 65  SQLite after ope
a650: 6e 69 6e 67 0a 2a 2a 20 61 20 77 72 69 74 65 20  ning.** a write 
a660: 74 72 61 6e 73 61 63 74 69 6f 6e 20 74 6f 20 69  transaction to i
a670: 6e 64 69 63 61 74 65 20 74 68 61 74 2c 20 75 6e  ndicate that, un
a680: 6c 65 73 73 20 69 74 20 69 73 20 72 6f 6c 6c 65  less it is rolle
a690: 64 20 62 61 63 6b 20 66 6f 72 20 73 6f 6d 65 0a  d back for some.
a6a0: 2a 2a 20 72 65 61 73 6f 6e 2c 20 74 68 65 20 65  ** reason, the e
a6b0: 6e 74 69 72 65 20 64 61 74 61 62 61 73 65 20 66  ntire database f
a6c0: 69 6c 65 20 77 69 6c 6c 20 62 65 20 6f 76 65 72  ile will be over
a6d0: 77 72 69 74 74 65 6e 20 62 79 20 74 68 65 20 63  written by the c
a6e0: 75 72 72 65 6e 74 20 0a 2a 2a 20 74 72 61 6e 73  urrent .** trans
a6f0: 61 63 74 69 6f 6e 2e 20 54 68 69 73 20 69 73 20  action. This is 
a700: 75 73 65 64 20 62 79 20 56 41 43 55 55 4d 20 6f  used by VACUUM o
a710: 70 65 72 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a  perations..**.**
a720: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
a730: 4e 54 4c 5f 56 46 53 4e 41 4d 45 5d 5d 0a 2a 2a  NTL_VFSNAME]].**
a740: 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43   ^The [SQLITE_FC
a750: 4e 54 4c 5f 56 46 53 4e 41 4d 45 5d 20 6f 70 63  NTL_VFSNAME] opc
a760: 6f 64 65 20 63 61 6e 20 62 65 20 75 73 65 64 20  ode can be used 
a770: 74 6f 20 6f 62 74 61 69 6e 20 74 68 65 20 6e 61  to obtain the na
a780: 6d 65 73 20 6f 66 0a 2a 2a 20 61 6c 6c 20 5b 56  mes of.** all [V
a790: 46 53 65 73 5d 20 69 6e 20 74 68 65 20 56 46 53  FSes] in the VFS
a7a0: 20 73 74 61 63 6b 2e 20 20 54 68 65 20 6e 61 6d   stack.  The nam
a7b0: 65 73 20 61 72 65 20 6f 66 20 61 6c 6c 20 56 46  es are of all VF
a7c0: 53 20 73 68 69 6d 73 20 61 6e 64 20 74 68 65 0a  S shims and the.
a7d0: 2a 2a 20 66 69 6e 61 6c 20 62 6f 74 74 6f 6d 2d  ** final bottom-
a7e0: 6c 65 76 65 6c 20 56 46 53 20 61 72 65 20 77 72  level VFS are wr
a7f0: 69 74 74 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72  itten into memor
a800: 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  y obtained from 
a810: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  .** [sqlite3_mal
a820: 6c 6f 63 28 29 5d 20 61 6e 64 20 74 68 65 20 72  loc()] and the r
a830: 65 73 75 6c 74 20 69 73 20 73 74 6f 72 65 64 20  esult is stored 
a840: 69 6e 20 74 68 65 20 63 68 61 72 2a 20 76 61 72  in the char* var
a850: 69 61 62 6c 65 0a 2a 2a 20 74 68 61 74 20 74 68  iable.** that th
a860: 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
a870: 65 72 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 66  er of [sqlite3_f
a880: 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 70  ile_control()] p
a890: 6f 69 6e 74 73 20 74 6f 2e 0a 2a 2a 20 54 68 65  oints to..** The
a8a0: 20 63 61 6c 6c 65 72 20 69 73 20 72 65 73 70 6f   caller is respo
a8b0: 6e 73 69 62 6c 65 20 66 6f 72 20 66 72 65 65 69  nsible for freei
a8c0: 6e 67 20 74 68 65 20 6d 65 6d 6f 72 79 20 77 68  ng the memory wh
a8d0: 65 6e 20 64 6f 6e 65 2e 20 20 41 73 20 77 69 74  en done.  As wit
a8e0: 68 0a 2a 2a 20 61 6c 6c 20 66 69 6c 65 2d 63 6f  h.** all file-co
a8f0: 6e 74 72 6f 6c 20 61 63 74 69 6f 6e 73 2c 20 74  ntrol actions, t
a900: 68 65 72 65 20 69 73 20 6e 6f 20 67 75 61 72 61  here is no guara
a910: 6e 74 65 65 20 74 68 61 74 20 74 68 69 73 20 77  ntee that this w
a920: 69 6c 6c 20 61 63 74 75 61 6c 6c 79 0a 2a 2a 20  ill actually.** 
a930: 64 6f 20 61 6e 79 74 68 69 6e 67 2e 20 20 43 61  do anything.  Ca
a940: 6c 6c 65 72 73 20 73 68 6f 75 6c 64 20 69 6e 69  llers should ini
a950: 74 69 61 6c 69 7a 65 20 74 68 65 20 63 68 61 72  tialize the char
a960: 2a 20 76 61 72 69 61 62 6c 65 20 74 6f 20 61 20  * variable to a 
a970: 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 20  NULL.** pointer 
a980: 69 6e 20 63 61 73 65 20 74 68 69 73 20 66 69 6c  in case this fil
a990: 65 2d 63 6f 6e 74 72 6f 6c 20 69 73 20 6e 6f 74  e-control is not
a9a0: 20 69 6d 70 6c 65 6d 65 6e 74 65 64 2e 20 20 54   implemented.  T
a9b0: 68 69 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c  his file-control
a9c0: 0a 2a 2a 20 69 73 20 69 6e 74 65 6e 64 65 64 20  .** is intended 
a9d0: 66 6f 72 20 64 69 61 67 6e 6f 73 74 69 63 20 75  for diagnostic u
a9e0: 73 65 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 3c  se only..**.** <
a9f0: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
aa00: 4c 5f 56 46 53 5f 50 4f 49 4e 54 45 52 5d 5d 0a  L_VFS_POINTER]].
aa10: 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f  ** ^The [SQLITE_
aa20: 46 43 4e 54 4c 5f 56 46 53 5f 50 4f 49 4e 54 45  FCNTL_VFS_POINTE
aa30: 52 5d 20 6f 70 63 6f 64 65 20 66 69 6e 64 73 20  R] opcode finds 
aa40: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
aa50: 20 74 6f 70 2d 6c 65 76 65 6c 0a 2a 2a 20 5b 56   top-level.** [V
aa60: 46 53 65 73 5d 20 63 75 72 72 65 6e 74 6c 79 20  FSes] currently 
aa70: 69 6e 20 75 73 65 2e 20 20 5e 28 54 68 65 20 61  in use.  ^(The a
aa80: 72 67 75 6d 65 6e 74 20 58 20 69 6e 0a 2a 2a 20  rgument X in.** 
aa90: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e  sqlite3_file_con
aaa0: 74 72 6f 6c 28 64 62 2c 53 51 4c 49 54 45 5f 46  trol(db,SQLITE_F
aab0: 43 4e 54 4c 5f 56 46 53 5f 50 4f 49 4e 54 45 52  CNTL_VFS_POINTER
aac0: 2c 58 29 20 6d 75 73 74 20 62 65 0a 2a 2a 20 6f  ,X) must be.** o
aad0: 66 20 74 79 70 65 20 22 5b 73 71 6c 69 74 65 33  f type "[sqlite3
aae0: 5f 76 66 73 5d 20 2a 2a 22 2e 20 20 54 68 69 73  _vfs] **".  This
aaf0: 20 6f 70 63 6f 64 65 73 20 77 69 6c 6c 20 73 65   opcodes will se
ab00: 74 20 2a 58 0a 2a 2a 20 74 6f 20 61 20 70 6f 69  t *X.** to a poi
ab10: 6e 74 65 72 20 74 6f 20 74 68 65 20 74 6f 70 2d  nter to the top-
ab20: 6c 65 76 65 6c 20 56 46 53 2e 29 5e 0a 2a 2a 20  level VFS.)^.** 
ab30: 5e 57 68 65 6e 20 74 68 65 72 65 20 61 72 65 20  ^When there are 
ab40: 6d 75 6c 74 69 70 6c 65 20 56 46 53 20 73 68 69  multiple VFS shi
ab50: 6d 73 20 69 6e 20 74 68 65 20 73 74 61 63 6b 2c  ms in the stack,
ab60: 20 74 68 69 73 20 6f 70 63 6f 64 65 20 66 69 6e   this opcode fin
ab70: 64 73 20 74 68 65 0a 2a 2a 20 75 70 70 65 72 2d  ds the.** upper-
ab80: 6d 6f 73 74 20 73 68 69 6d 20 6f 6e 6c 79 2e 0a  most shim only..
ab90: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
aba0: 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d  TE_FCNTL_PRAGMA]
abb0: 5d 0a 2a 2a 20 5e 57 68 65 6e 65 76 65 72 20 61  ].** ^Whenever a
abc0: 20 5b 50 52 41 47 4d 41 5d 20 73 74 61 74 65 6d   [PRAGMA] statem
abd0: 65 6e 74 20 69 73 20 70 61 72 73 65 64 2c 20 61  ent is parsed, a
abe0: 6e 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  n [SQLITE_FCNTL_
abf0: 50 52 41 47 4d 41 5d 20 0a 2a 2a 20 66 69 6c 65  PRAGMA] .** file
ac00: 20 63 6f 6e 74 72 6f 6c 20 69 73 20 73 65 6e 74   control is sent
ac10: 20 74 6f 20 74 68 65 20 6f 70 65 6e 20 5b 73 71   to the open [sq
ac20: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65  lite3_file] obje
ac30: 63 74 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67  ct corresponding
ac40: 0a 2a 2a 20 74 6f 20 74 68 65 20 64 61 74 61 62  .** to the datab
ac50: 61 73 65 20 66 69 6c 65 20 74 6f 20 77 68 69 63  ase file to whic
ac60: 68 20 74 68 65 20 70 72 61 67 6d 61 20 73 74 61  h the pragma sta
ac70: 74 65 6d 65 6e 74 20 72 65 66 65 72 73 2e 20 5e  tement refers. ^
ac80: 54 68 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20  The argument.** 
ac90: 74 6f 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 46  to the [SQLITE_F
aca0: 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c  CNTL_PRAGMA] fil
acb0: 65 20 63 6f 6e 74 72 6f 6c 20 69 73 20 61 6e 20  e control is an 
acc0: 61 72 72 61 79 20 6f 66 0a 2a 2a 20 70 6f 69 6e  array of.** poin
acd0: 74 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73 20  ters to strings 
ace0: 28 63 68 61 72 2a 2a 29 20 69 6e 20 77 68 69 63  (char**) in whic
acf0: 68 20 74 68 65 20 73 65 63 6f 6e 64 20 65 6c 65  h the second ele
ad00: 6d 65 6e 74 20 6f 66 20 74 68 65 20 61 72 72 61  ment of the arra
ad10: 79 0a 2a 2a 20 69 73 20 74 68 65 20 6e 61 6d 65  y.** is the name
ad20: 20 6f 66 20 74 68 65 20 70 72 61 67 6d 61 20 61   of the pragma a
ad30: 6e 64 20 74 68 65 20 74 68 69 72 64 20 65 6c 65  nd the third ele
ad40: 6d 65 6e 74 20 69 73 20 74 68 65 20 61 72 67 75  ment is the argu
ad50: 6d 65 6e 74 20 74 6f 20 74 68 65 0a 2a 2a 20 70  ment to the.** p
ad60: 72 61 67 6d 61 20 6f 72 20 4e 55 4c 4c 20 69 66  ragma or NULL if
ad70: 20 74 68 65 20 70 72 61 67 6d 61 20 68 61 73 20   the pragma has 
ad80: 6e 6f 20 61 72 67 75 6d 65 6e 74 2e 20 20 5e 54  no argument.  ^T
ad90: 68 65 20 68 61 6e 64 6c 65 72 20 66 6f 72 20 61  he handler for a
ada0: 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e  n.** [SQLITE_FCN
adb0: 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65 20  TL_PRAGMA] file 
adc0: 63 6f 6e 74 72 6f 6c 20 63 61 6e 20 6f 70 74 69  control can opti
add0: 6f 6e 61 6c 6c 79 20 6d 61 6b 65 20 74 68 65 20  onally make the 
ade0: 66 69 72 73 74 20 65 6c 65 6d 65 6e 74 0a 2a 2a  first element.**
adf0: 20 6f 66 20 74 68 65 20 63 68 61 72 2a 2a 20 61   of the char** a
ae00: 72 67 75 6d 65 6e 74 20 70 6f 69 6e 74 20 74 6f  rgument point to
ae10: 20 61 20 73 74 72 69 6e 67 20 6f 62 74 61 69 6e   a string obtain
ae20: 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  ed from [sqlite3
ae30: 5f 6d 70 72 69 6e 74 66 28 29 5d 0a 2a 2a 20 6f  _mprintf()].** o
ae40: 72 20 74 68 65 20 65 71 75 69 76 61 6c 65 6e 74  r the equivalent
ae50: 20 61 6e 64 20 74 68 61 74 20 73 74 72 69 6e 67   and that string
ae60: 20 77 69 6c 6c 20 62 65 63 6f 6d 65 20 74 68 65   will become the
ae70: 20 72 65 73 75 6c 74 20 6f 66 20 74 68 65 20 70   result of the p
ae80: 72 61 67 6d 61 20 6f 72 0a 2a 2a 20 74 68 65 20  ragma or.** the 
ae90: 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 69 66  error message if
aea0: 20 74 68 65 20 70 72 61 67 6d 61 20 66 61 69 6c   the pragma fail
aeb0: 73 2e 20 5e 49 66 20 74 68 65 0a 2a 2a 20 5b 53  s. ^If the.** [S
aec0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47  QLITE_FCNTL_PRAG
aed0: 4d 41 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c  MA] file control
aee0: 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
aef0: 5f 4e 4f 54 46 4f 55 4e 44 5d 2c 20 74 68 65 6e  _NOTFOUND], then
af00: 20 6e 6f 72 6d 61 6c 20 0a 2a 2a 20 5b 50 52 41   normal .** [PRA
af10: 47 4d 41 5d 20 70 72 6f 63 65 73 73 69 6e 67 20  GMA] processing 
af20: 63 6f 6e 74 69 6e 75 65 73 2e 20 20 5e 49 66 20  continues.  ^If 
af30: 74 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  the [SQLITE_FCNT
af40: 4c 5f 50 52 41 47 4d 41 5d 0a 2a 2a 20 66 69 6c  L_PRAGMA].** fil
af50: 65 20 63 6f 6e 74 72 6f 6c 20 72 65 74 75 72 6e  e control return
af60: 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74  s [SQLITE_OK], t
af70: 68 65 6e 20 74 68 65 20 70 61 72 73 65 72 20 61  hen the parser a
af80: 73 73 75 6d 65 73 20 74 68 61 74 20 74 68 65 0a  ssumes that the.
af90: 2a 2a 20 56 46 53 20 68 61 73 20 68 61 6e 64 6c  ** VFS has handl
afa0: 65 64 20 74 68 65 20 50 52 41 47 4d 41 20 69 74  ed the PRAGMA it
afb0: 73 65 6c 66 20 61 6e 64 20 74 68 65 20 70 61 72  self and the par
afc0: 73 65 72 20 67 65 6e 65 72 61 74 65 73 20 61 20  ser generates a 
afd0: 6e 6f 2d 6f 70 0a 2a 2a 20 70 72 65 70 61 72 65  no-op.** prepare
afe0: 64 20 73 74 61 74 65 6d 65 6e 74 20 69 66 20 72  d statement if r
aff0: 65 73 75 6c 74 20 73 74 72 69 6e 67 20 69 73 20  esult string is 
b000: 4e 55 4c 4c 2c 20 6f 72 20 74 68 61 74 20 72 65  NULL, or that re
b010: 74 75 72 6e 73 20 61 20 63 6f 70 79 0a 2a 2a 20  turns a copy.** 
b020: 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 74  of the result st
b030: 72 69 6e 67 20 69 66 20 74 68 65 20 73 74 72 69  ring if the stri
b040: 6e 67 20 69 73 20 6e 6f 6e 2d 4e 55 4c 4c 2e 0a  ng is non-NULL..
b050: 2a 2a 20 5e 49 66 20 74 68 65 20 5b 53 51 4c 49  ** ^If the [SQLI
b060: 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d  TE_FCNTL_PRAGMA]
b070: 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 72 65   file control re
b080: 74 75 72 6e 73 0a 2a 2a 20 61 6e 79 20 72 65 73  turns.** any res
b090: 75 6c 74 20 63 6f 64 65 20 6f 74 68 65 72 20 74  ult code other t
b0a0: 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20  han [SQLITE_OK] 
b0b0: 6f 72 20 5b 53 51 4c 49 54 45 5f 4e 4f 54 46 4f  or [SQLITE_NOTFO
b0c0: 55 4e 44 5d 2c 20 74 68 61 74 20 6d 65 61 6e 73  UND], that means
b0d0: 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 56 46 53  .** that the VFS
b0e0: 20 65 6e 63 6f 75 6e 74 65 72 65 64 20 61 6e 20   encountered an 
b0f0: 65 72 72 6f 72 20 77 68 69 6c 65 20 68 61 6e 64  error while hand
b100: 6c 69 6e 67 20 74 68 65 20 5b 50 52 41 47 4d 41  ling the [PRAGMA
b110: 5d 20 61 6e 64 20 74 68 65 0a 2a 2a 20 63 6f 6d  ] and the.** com
b120: 70 69 6c 61 74 69 6f 6e 20 6f 66 20 74 68 65 20  pilation of the 
b130: 50 52 41 47 4d 41 20 66 61 69 6c 73 20 77 69 74  PRAGMA fails wit
b140: 68 20 61 6e 20 65 72 72 6f 72 2e 20 20 5e 54 68  h an error.  ^Th
b150: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
b160: 50 52 41 47 4d 41 5d 0a 2a 2a 20 66 69 6c 65 20  PRAGMA].** file 
b170: 63 6f 6e 74 72 6f 6c 20 6f 63 63 75 72 73 20 61  control occurs a
b180: 74 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20  t the beginning 
b190: 6f 66 20 70 72 61 67 6d 61 20 73 74 61 74 65 6d  of pragma statem
b1a0: 65 6e 74 20 61 6e 61 6c 79 73 69 73 20 61 6e 64  ent analysis and
b1b0: 20 73 6f 0a 2a 2a 20 69 74 20 69 73 20 61 62 6c   so.** it is abl
b1c0: 65 20 74 6f 20 6f 76 65 72 72 69 64 65 20 62 75  e to override bu
b1d0: 69 6c 74 2d 69 6e 20 5b 50 52 41 47 4d 41 5d 20  ilt-in [PRAGMA] 
b1e0: 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a  statements..**.*
b1f0: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
b200: 43 4e 54 4c 5f 42 55 53 59 48 41 4e 44 4c 45 52  CNTL_BUSYHANDLER
b210: 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49  ]].** ^The [SQLI
b220: 54 45 5f 46 43 4e 54 4c 5f 42 55 53 59 48 41 4e  TE_FCNTL_BUSYHAN
b230: 44 4c 45 52 5d 0a 2a 2a 20 66 69 6c 65 2d 63 6f  DLER].** file-co
b240: 6e 74 72 6f 6c 20 6d 61 79 20 62 65 20 69 6e 76  ntrol may be inv
b250: 6f 6b 65 64 20 62 79 20 53 51 4c 69 74 65 20 6f  oked by SQLite o
b260: 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  n the database f
b270: 69 6c 65 20 68 61 6e 64 6c 65 0a 2a 2a 20 73 68  ile handle.** sh
b280: 6f 72 74 6c 79 20 61 66 74 65 72 20 69 74 20 69  ortly after it i
b290: 73 20 6f 70 65 6e 65 64 20 69 6e 20 6f 72 64 65  s opened in orde
b2a0: 72 20 74 6f 20 70 72 6f 76 69 64 65 20 61 20 63  r to provide a c
b2b0: 75 73 74 6f 6d 20 56 46 53 20 77 69 74 68 20 61  ustom VFS with a
b2c0: 63 63 65 73 73 0a 2a 2a 20 74 6f 20 74 68 65 20  ccess.** to the 
b2d0: 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 62 75 73 79  connections busy
b2e0: 2d 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63  -handler callbac
b2f0: 6b 2e 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20  k. The argument 
b300: 69 73 20 6f 66 20 74 79 70 65 20 28 76 6f 69 64  is of type (void
b310: 20 2a 2a 29 0a 2a 2a 20 2d 20 61 6e 20 61 72 72   **).** - an arr
b320: 61 79 20 6f 66 20 74 77 6f 20 28 76 6f 69 64 20  ay of two (void 
b330: 2a 29 20 76 61 6c 75 65 73 2e 20 54 68 65 20 66  *) values. The f
b340: 69 72 73 74 20 28 76 6f 69 64 20 2a 29 20 61 63  irst (void *) ac
b350: 74 75 61 6c 6c 79 20 70 6f 69 6e 74 73 0a 2a 2a  tually points.**
b360: 20 74 6f 20 61 20 66 75 6e 63 74 69 6f 6e 20 6f   to a function o
b370: 66 20 74 79 70 65 20 28 69 6e 74 20 28 2a 29 28  f type (int (*)(
b380: 76 6f 69 64 20 2a 29 29 2e 20 49 6e 20 6f 72 64  void *)). In ord
b390: 65 72 20 74 6f 20 69 6e 76 6f 6b 65 20 74 68 65  er to invoke the
b3a0: 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a 20   connections.** 
b3b0: 62 75 73 79 2d 68 61 6e 64 6c 65 72 2c 20 74 68  busy-handler, th
b3c0: 69 73 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f 75  is function shou
b3d0: 6c 64 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 69  ld be invoked wi
b3e0: 74 68 20 74 68 65 20 73 65 63 6f 6e 64 20 28 76  th the second (v
b3f0: 6f 69 64 20 2a 29 20 69 6e 0a 2a 2a 20 74 68 65  oid *) in.** the
b400: 20 61 72 72 61 79 20 61 73 20 74 68 65 20 6f 6e   array as the on
b410: 6c 79 20 61 72 67 75 6d 65 6e 74 2e 20 49 66 20  ly argument. If 
b420: 69 74 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a  it returns non-z
b430: 65 72 6f 2c 20 74 68 65 6e 20 74 68 65 20 6f 70  ero, then the op
b440: 65 72 61 74 69 6f 6e 0a 2a 2a 20 73 68 6f 75 6c  eration.** shoul
b450: 64 20 62 65 20 72 65 74 72 69 65 64 2e 20 49 66  d be retried. If
b460: 20 69 74 20 72 65 74 75 72 6e 73 20 7a 65 72 6f   it returns zero
b470: 2c 20 74 68 65 20 63 75 73 74 6f 6d 20 56 46 53  , the custom VFS
b480: 20 73 68 6f 75 6c 64 20 61 62 61 6e 64 6f 6e 20   should abandon 
b490: 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 20 6f  the.** current o
b4a0: 70 65 72 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  peration..**.** 
b4b0: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e  <li>[[SQLITE_FCN
b4c0: 54 4c 5f 54 45 4d 50 46 49 4c 45 4e 41 4d 45 5d  TL_TEMPFILENAME]
b4d0: 5d 0a 2a 2a 20 5e 41 70 70 6c 69 63 61 74 69 6f  ].** ^Applicatio
b4e0: 6e 20 63 61 6e 20 69 6e 76 6f 6b 65 20 74 68 65  n can invoke the
b4f0: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54   [SQLITE_FCNTL_T
b500: 45 4d 50 46 49 4c 45 4e 41 4d 45 5d 20 66 69 6c  EMPFILENAME] fil
b510: 65 2d 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 74 6f 20  e-control.** to 
b520: 68 61 76 65 20 53 51 4c 69 74 65 20 67 65 6e 65  have SQLite gene
b530: 72 61 74 65 20 61 0a 2a 2a 20 74 65 6d 70 6f 72  rate a.** tempor
b540: 61 72 79 20 66 69 6c 65 6e 61 6d 65 20 75 73 69  ary filename usi
b550: 6e 67 20 74 68 65 20 73 61 6d 65 20 61 6c 67 6f  ng the same algo
b560: 72 69 74 68 6d 20 74 68 61 74 20 69 73 20 66 6f  rithm that is fo
b570: 6c 6c 6f 77 65 64 20 74 6f 20 67 65 6e 65 72 61  llowed to genera
b580: 74 65 0a 2a 2a 20 74 65 6d 70 6f 72 61 72 79 20  te.** temporary 
b590: 66 69 6c 65 6e 61 6d 65 73 20 66 6f 72 20 54 45  filenames for TE
b5a0: 4d 50 20 74 61 62 6c 65 73 20 61 6e 64 20 6f 74  MP tables and ot
b5b0: 68 65 72 20 69 6e 74 65 72 6e 61 6c 20 75 73 65  her internal use
b5c0: 73 2e 20 20 54 68 65 0a 2a 2a 20 61 72 67 75 6d  s.  The.** argum
b5d0: 65 6e 74 20 73 68 6f 75 6c 64 20 62 65 20 61 20  ent should be a 
b5e0: 63 68 61 72 2a 2a 20 77 68 69 63 68 20 77 69 6c  char** which wil
b5f0: 6c 20 62 65 20 66 69 6c 6c 65 64 20 77 69 74 68  l be filled with
b600: 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 0a 2a 2a   the filename.**
b610: 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 6d 65   written into me
b620: 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72  mory obtained fr
b630: 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  om [sqlite3_mall
b640: 6f 63 28 29 5d 2e 20 20 54 68 65 20 63 61 6c 6c  oc()].  The call
b650: 65 72 20 73 68 6f 75 6c 64 0a 2a 2a 20 69 6e 76  er should.** inv
b660: 6f 6b 65 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  oke [sqlite3_fre
b670: 65 28 29 5d 20 6f 6e 20 74 68 65 20 72 65 73 75  e()] on the resu
b680: 6c 74 20 74 6f 20 61 76 6f 69 64 20 61 20 6d 65  lt to avoid a me
b690: 6d 6f 72 79 20 6c 65 61 6b 2e 0a 2a 2a 0a 2a 2a  mory leak..**.**
b6a0: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
b6b0: 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45 5d 5d 0a  NTL_MMAP_SIZE]].
b6c0: 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  ** The [SQLITE_F
b6d0: 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20  CNTL_MMAP_SIZE] 
b6e0: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73 20  file control is 
b6f0: 75 73 65 64 20 74 6f 20 71 75 65 72 79 20 6f 72  used to query or
b700: 20 73 65 74 20 74 68 65 0a 2a 2a 20 6d 61 78 69   set the.** maxi
b710: 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  mum number of by
b720: 74 65 73 20 74 68 61 74 20 77 69 6c 6c 20 62 65  tes that will be
b730: 20 75 73 65 64 20 66 6f 72 20 6d 65 6d 6f 72 79   used for memory
b740: 2d 6d 61 70 70 65 64 20 49 2f 4f 2e 0a 2a 2a 20  -mapped I/O..** 
b750: 54 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20  The argument is 
b760: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 76  a pointer to a v
b770: 61 6c 75 65 20 6f 66 20 74 79 70 65 20 73 71 6c  alue of type sql
b780: 69 74 65 33 5f 69 6e 74 36 34 20 74 68 61 74 0a  ite3_int64 that.
b790: 2a 2a 20 69 73 20 61 6e 20 61 64 76 69 73 6f 72  ** is an advisor
b7a0: 79 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72  y maximum number
b7b0: 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 65   of bytes in the
b7c0: 20 66 69 6c 65 20 74 6f 20 6d 65 6d 6f 72 79 20   file to memory 
b7d0: 6d 61 70 2e 20 20 54 68 65 0a 2a 2a 20 70 6f 69  map.  The.** poi
b7e0: 6e 74 65 72 20 69 73 20 6f 76 65 72 77 72 69 74  nter is overwrit
b7f0: 74 65 6e 20 77 69 74 68 20 74 68 65 20 6f 6c 64  ten with the old
b800: 20 76 61 6c 75 65 2e 20 20 54 68 65 20 6c 69 6d   value.  The lim
b810: 69 74 20 69 73 20 6e 6f 74 20 63 68 61 6e 67 65  it is not change
b820: 64 20 69 66 0a 2a 2a 20 74 68 65 20 76 61 6c 75  d if.** the valu
b830: 65 20 6f 72 69 67 69 6e 61 6c 6c 79 20 70 6f 69  e originally poi
b840: 6e 74 65 64 20 74 6f 20 69 73 20 6e 65 67 61 74  nted to is negat
b850: 69 76 65 2c 20 61 6e 64 20 73 6f 20 74 68 65 20  ive, and so the 
b860: 63 75 72 72 65 6e 74 20 6c 69 6d 69 74 20 0a 2a  current limit .*
b870: 2a 20 63 61 6e 20 62 65 20 71 75 65 72 69 65 64  * can be queried
b880: 20 62 79 20 70 61 73 73 69 6e 67 20 69 6e 20 61   by passing in a
b890: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 6e 65   pointer to a ne
b8a0: 67 61 74 69 76 65 20 6e 75 6d 62 65 72 2e 20 20  gative number.  
b8b0: 54 68 69 73 0a 2a 2a 20 66 69 6c 65 2d 63 6f 6e  This.** file-con
b8c0: 74 72 6f 6c 20 69 73 20 75 73 65 64 20 69 6e 74  trol is used int
b8d0: 65 72 6e 61 6c 6c 79 20 74 6f 20 69 6d 70 6c 65  ernally to imple
b8e0: 6d 65 6e 74 20 5b 50 52 41 47 4d 41 20 6d 6d 61  ment [PRAGMA mma
b8f0: 70 5f 73 69 7a 65 5d 2e 0a 2a 2a 0a 2a 2a 20 3c  p_size]..**.** <
b900: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
b910: 4c 5f 54 52 41 43 45 5d 5d 0a 2a 2a 20 54 68 65  L_TRACE]].** The
b920: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54   [SQLITE_FCNTL_T
b930: 52 41 43 45 5d 20 66 69 6c 65 20 63 6f 6e 74 72  RACE] file contr
b940: 6f 6c 20 70 72 6f 76 69 64 65 73 20 61 64 76 69  ol provides advi
b950: 73 6f 72 79 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  sory information
b960: 0a 2a 2a 20 74 6f 20 74 68 65 20 56 46 53 20 61  .** to the VFS a
b970: 62 6f 75 74 20 77 68 61 74 20 74 68 65 20 68 69  bout what the hi
b980: 67 68 65 72 20 6c 61 79 65 72 73 20 6f 66 20 74  gher layers of t
b990: 68 65 20 53 51 4c 69 74 65 20 73 74 61 63 6b 20  he SQLite stack 
b9a0: 61 72 65 20 64 6f 69 6e 67 2e 0a 2a 2a 20 54 68  are doing..** Th
b9b0: 69 73 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20  is file control 
b9c0: 69 73 20 75 73 65 64 20 62 79 20 73 6f 6d 65 20  is used by some 
b9d0: 56 46 53 20 61 63 74 69 76 69 74 79 20 74 72 61  VFS activity tra
b9e0: 63 69 6e 67 20 5b 73 68 69 6d 73 5d 2e 0a 2a 2a  cing [shims]..**
b9f0: 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73   The argument is
ba00: 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74   a zero-terminat
ba10: 65 64 20 73 74 72 69 6e 67 2e 20 20 48 69 67 68  ed string.  High
ba20: 65 72 20 6c 61 79 65 72 73 20 69 6e 20 74 68 65  er layers in the
ba30: 0a 2a 2a 20 53 51 4c 69 74 65 20 73 74 61 63 6b  .** SQLite stack
ba40: 20 6d 61 79 20 67 65 6e 65 72 61 74 65 20 69 6e   may generate in
ba50: 73 74 61 6e 63 65 73 20 6f 66 20 74 68 69 73 20  stances of this 
ba60: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 66 0a  file control if.
ba70: 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 55  ** the [SQLITE_U
ba80: 53 45 5f 46 43 4e 54 4c 5f 54 52 41 43 45 5d 20  SE_FCNTL_TRACE] 
ba90: 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
baa0: 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 2e 0a  ion is enabled..
bab0: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
bac0: 54 45 5f 46 43 4e 54 4c 5f 48 41 53 5f 4d 4f 56  TE_FCNTL_HAS_MOV
bad0: 45 44 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  ED]].** The [SQL
bae0: 49 54 45 5f 46 43 4e 54 4c 5f 48 41 53 5f 4d 4f  ITE_FCNTL_HAS_MO
baf0: 56 45 44 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f  VED] file contro
bb00: 6c 20 69 6e 74 65 72 70 72 65 74 73 20 69 74 73  l interprets its
bb10: 20 61 72 67 75 6d 65 6e 74 20 61 73 20 61 0a 2a   argument as a.*
bb20: 2a 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  * pointer to an 
bb30: 69 6e 74 65 67 65 72 20 61 6e 64 20 69 74 20 77  integer and it w
bb40: 72 69 74 65 73 20 61 20 62 6f 6f 6c 65 61 6e 20  rites a boolean 
bb50: 69 6e 74 6f 20 74 68 61 74 20 69 6e 74 65 67 65  into that intege
bb60: 72 20 64 65 70 65 6e 64 69 6e 67 0a 2a 2a 20 6f  r depending.** o
bb70: 6e 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  n whether or not
bb80: 20 74 68 65 20 66 69 6c 65 20 68 61 73 20 62 65   the file has be
bb90: 65 6e 20 72 65 6e 61 6d 65 64 2c 20 6d 6f 76 65  en renamed, move
bba0: 64 2c 20 6f 72 20 64 65 6c 65 74 65 64 20 73 69  d, or deleted si
bbb0: 6e 63 65 20 69 74 0a 2a 2a 20 77 61 73 20 66 69  nce it.** was fi
bbc0: 72 73 74 20 6f 70 65 6e 65 64 2e 0a 2a 2a 0a 2a  rst opened..**.*
bbd0: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
bbe0: 43 4e 54 4c 5f 57 49 4e 33 32 5f 47 45 54 5f 48  CNTL_WIN32_GET_H
bbf0: 41 4e 44 4c 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b  ANDLE]].** The [
bc00: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e  SQLITE_FCNTL_WIN
bc10: 33 32 5f 47 45 54 5f 48 41 4e 44 4c 45 5d 20 6f  32_GET_HANDLE] o
bc20: 70 63 6f 64 65 20 63 61 6e 20 62 65 20 75 73 65  pcode can be use
bc30: 64 20 74 6f 20 6f 62 74 61 69 6e 20 74 68 65 0a  d to obtain the.
bc40: 2a 2a 20 75 6e 64 65 72 6c 79 69 6e 67 20 6e 61  ** underlying na
bc50: 74 69 76 65 20 66 69 6c 65 20 68 61 6e 64 6c 65  tive file handle
bc60: 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
bc70: 20 61 20 66 69 6c 65 20 68 61 6e 64 6c 65 2e 20   a file handle. 
bc80: 20 54 68 69 73 20 66 69 6c 65 0a 2a 2a 20 63 6f   This file.** co
bc90: 6e 74 72 6f 6c 20 69 6e 74 65 72 70 72 65 74 73  ntrol interprets
bca0: 20 69 74 73 20 61 72 67 75 6d 65 6e 74 20 61 73   its argument as
bcb0: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20   a pointer to a 
bcc0: 6e 61 74 69 76 65 20 66 69 6c 65 20 68 61 6e 64  native file hand
bcd0: 6c 65 20 61 6e 64 0a 2a 2a 20 77 72 69 74 65 73  le and.** writes
bce0: 20 74 68 65 20 72 65 73 75 6c 74 69 6e 67 20 76   the resulting v
bcf0: 61 6c 75 65 20 74 68 65 72 65 2e 0a 2a 2a 0a 2a  alue there..**.*
bd00: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
bd10: 43 4e 54 4c 5f 57 49 4e 33 32 5f 53 45 54 5f 48  CNTL_WIN32_SET_H
bd20: 41 4e 44 4c 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b  ANDLE]].** The [
bd30: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e  SQLITE_FCNTL_WIN
bd40: 33 32 5f 53 45 54 5f 48 41 4e 44 4c 45 5d 20 6f  32_SET_HANDLE] o
bd50: 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 66 6f  pcode is used fo
bd60: 72 20 64 65 62 75 67 67 69 6e 67 2e 20 20 54 68  r debugging.  Th
bd70: 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 20 63 61 75  is.** opcode cau
bd80: 73 65 73 20 74 68 65 20 78 46 69 6c 65 43 6f 6e  ses the xFileCon
bd90: 74 72 6f 6c 20 6d 65 74 68 6f 64 20 74 6f 20 73  trol method to s
bda0: 77 61 70 20 74 68 65 20 66 69 6c 65 20 68 61 6e  wap the file han
bdb0: 64 6c 65 20 77 69 74 68 20 74 68 65 20 6f 6e 65  dle with the one
bdc0: 0a 2a 2a 20 70 6f 69 6e 74 65 64 20 74 6f 20 62  .** pointed to b
bdd0: 79 20 74 68 65 20 70 41 72 67 20 61 72 67 75 6d  y the pArg argum
bde0: 65 6e 74 2e 20 20 54 68 69 73 20 63 61 70 61 62  ent.  This capab
bdf0: 69 6c 69 74 79 20 69 73 20 75 73 65 64 20 64 75  ility is used du
be00: 72 69 6e 67 20 74 65 73 74 69 6e 67 0a 2a 2a 20  ring testing.** 
be10: 61 6e 64 20 6f 6e 6c 79 20 6e 65 65 64 73 20 74  and only needs t
be20: 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64 20 77  o be supported w
be30: 68 65 6e 20 53 51 4c 49 54 45 5f 54 45 53 54 20  hen SQLITE_TEST 
be40: 69 73 20 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a  is defined..**.*
be50: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
be60: 43 4e 54 4c 5f 57 41 4c 5f 42 4c 4f 43 4b 5d 5d  CNTL_WAL_BLOCK]]
be70: 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  .** The [SQLITE_
be80: 46 43 4e 54 4c 5f 57 41 4c 5f 42 4c 4f 43 4b 5d  FCNTL_WAL_BLOCK]
be90: 20 69 73 20 61 20 73 69 67 6e 61 6c 20 74 6f 20   is a signal to 
bea0: 74 68 65 20 56 46 53 20 6c 61 79 65 72 20 74 68  the VFS layer th
beb0: 61 74 20 69 74 20 6d 69 67 68 74 0a 2a 2a 20 62  at it might.** b
bec0: 65 20 61 64 76 61 6e 74 61 67 65 6f 75 73 20 74  e advantageous t
bed0: 6f 20 62 6c 6f 63 6b 20 6f 6e 20 74 68 65 20 6e  o block on the n
bee0: 65 78 74 20 57 41 4c 20 6c 6f 63 6b 20 69 66 20  ext WAL lock if 
bef0: 74 68 65 20 6c 6f 63 6b 20 69 73 20 6e 6f 74 20  the lock is not 
bf00: 69 6d 6d 65 64 69 61 74 65 6c 79 0a 2a 2a 20 61  immediately.** a
bf10: 76 61 69 6c 61 62 6c 65 2e 20 20 54 68 65 20 57  vailable.  The W
bf20: 41 4c 20 73 75 62 73 79 73 74 65 6d 20 69 73 73  AL subsystem iss
bf30: 75 65 73 20 74 68 69 73 20 73 69 67 6e 61 6c 20  ues this signal 
bf40: 64 75 72 69 6e 67 20 72 61 72 65 0a 2a 2a 20 63  during rare.** c
bf50: 69 72 63 75 6d 73 74 61 6e 63 65 73 20 69 6e 20  ircumstances in 
bf60: 6f 72 64 65 72 20 74 6f 20 66 69 78 20 61 20 70  order to fix a p
bf70: 72 6f 62 6c 65 6d 20 77 69 74 68 20 70 72 69 6f  roblem with prio
bf80: 72 69 74 79 20 69 6e 76 65 72 73 69 6f 6e 2e 0a  rity inversion..
bf90: 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20  ** Applications 
bfa0: 73 68 6f 75 6c 64 20 3c 65 6d 3e 6e 6f 74 3c 2f  should <em>not</
bfb0: 65 6d 3e 20 75 73 65 20 74 68 69 73 20 66 69 6c  em> use this fil
bfc0: 65 2d 63 6f 6e 74 72 6f 6c 2e 0a 2a 2a 0a 2a 2a  e-control..**.**
bfd0: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
bfe0: 4e 54 4c 5f 5a 49 50 56 46 53 5d 5d 0a 2a 2a 20  NTL_ZIPVFS]].** 
bff0: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
c000: 4c 5f 5a 49 50 56 46 53 5d 20 6f 70 63 6f 64 65  L_ZIPVFS] opcode
c010: 20 69 73 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20   is implemented 
c020: 62 79 20 7a 69 70 76 66 73 20 6f 6e 6c 79 2e 20  by zipvfs only. 
c030: 41 6c 6c 20 6f 74 68 65 72 0a 2a 2a 20 56 46 53  All other.** VFS
c040: 20 73 68 6f 75 6c 64 20 72 65 74 75 72 6e 20 53   should return S
c050: 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 20 66  QLITE_NOTFOUND f
c060: 6f 72 20 74 68 69 73 20 6f 70 63 6f 64 65 2e 0a  or this opcode..
c070: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
c080: 54 45 5f 46 43 4e 54 4c 5f 52 42 55 5d 5d 0a 2a  TE_FCNTL_RBU]].*
c090: 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43  * The [SQLITE_FC
c0a0: 4e 54 4c 5f 52 42 55 5d 20 6f 70 63 6f 64 65 20  NTL_RBU] opcode 
c0b0: 69 73 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 62  is implemented b
c0c0: 79 20 74 68 65 20 73 70 65 63 69 61 6c 20 56 46  y the special VF
c0d0: 53 20 75 73 65 64 20 62 79 0a 2a 2a 20 74 68 65  S used by.** the
c0e0: 20 52 42 55 20 65 78 74 65 6e 73 69 6f 6e 20 6f   RBU extension o
c0f0: 6e 6c 79 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20  nly.  All other 
c100: 56 46 53 20 73 68 6f 75 6c 64 20 72 65 74 75 72  VFS should retur
c110: 6e 20 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e  n SQLITE_NOTFOUN
c120: 44 20 66 6f 72 0a 2a 2a 20 74 68 69 73 20 6f 70  D for.** this op
c130: 63 6f 64 65 2e 20 20 0a 2a 2a 20 3c 2f 75 6c 3e  code.  .** </ul>
c140: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
c150: 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41  TE_FCNTL_LOCKSTA
c160: 54 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20  TE              
c170: 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   1.#define SQLIT
c180: 45 5f 46 43 4e 54 4c 5f 47 45 54 5f 4c 4f 43 4b  E_FCNTL_GET_LOCK
c190: 50 52 4f 58 59 46 49 4c 45 20 20 20 20 20 20 20  PROXYFILE       
c1a0: 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  2.#define SQLITE
c1b0: 5f 46 43 4e 54 4c 5f 53 45 54 5f 4c 4f 43 4b 50  _FCNTL_SET_LOCKP
c1c0: 52 4f 58 59 46 49 4c 45 20 20 20 20 20 20 20 33  ROXYFILE       3
c1d0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
c1e0: 46 43 4e 54 4c 5f 4c 41 53 54 5f 45 52 52 4e 4f  FCNTL_LAST_ERRNO
c1f0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 34 0a                4.
c200: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
c210: 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e 54 20 20  CNTL_SIZE_HINT  
c220: 20 20 20 20 20 20 20 20 20 20 20 20 20 35 0a 23               5.#
c230: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
c240: 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45 20 20  NTL_CHUNK_SIZE  
c250: 20 20 20 20 20 20 20 20 20 20 20 20 36 0a 23 64              6.#d
c260: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
c270: 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52 20  TL_FILE_POINTER 
c280: 20 20 20 20 20 20 20 20 20 20 20 37 0a 23 64 65             7.#de
c290: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
c2a0: 4c 5f 53 59 4e 43 5f 4f 4d 49 54 54 45 44 20 20  L_SYNC_OMITTED  
c2b0: 20 20 20 20 20 20 20 20 20 20 38 0a 23 64 65 66            8.#def
c2c0: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
c2d0: 5f 57 49 4e 33 32 5f 41 56 5f 52 45 54 52 59 20  _WIN32_AV_RETRY 
c2e0: 20 20 20 20 20 20 20 20 20 39 0a 23 64 65 66 69           9.#defi
c2f0: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
c300: 50 45 52 53 49 53 54 5f 57 41 4c 20 20 20 20 20  PERSIST_WAL     
c310: 20 20 20 20 20 20 20 31 30 0a 23 64 65 66 69 6e         10.#defin
c320: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f  e SQLITE_FCNTL_O
c330: 56 45 52 57 52 49 54 45 20 20 20 20 20 20 20 20  VERWRITE        
c340: 20 20 20 20 20 20 31 31 0a 23 64 65 66 69 6e 65        11.#define
c350: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46   SQLITE_FCNTL_VF
c360: 53 4e 41 4d 45 20 20 20 20 20 20 20 20 20 20 20  SNAME           
c370: 20 20 20 20 20 31 32 0a 23 64 65 66 69 6e 65 20       12.#define 
c380: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 4f 57  SQLITE_FCNTL_POW
c390: 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45  ERSAFE_OVERWRITE
c3a0: 20 20 20 20 31 33 0a 23 64 65 66 69 6e 65 20 53      13.#define S
c3b0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47  QLITE_FCNTL_PRAG
c3c0: 4d 41 20 20 20 20 20 20 20 20 20 20 20 20 20 20  MA              
c3d0: 20 20 20 31 34 0a 23 64 65 66 69 6e 65 20 53 51     14.#define SQ
c3e0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 55 53 59 48  LITE_FCNTL_BUSYH
c3f0: 41 4e 44 4c 45 52 20 20 20 20 20 20 20 20 20 20  ANDLER          
c400: 20 20 31 35 0a 23 64 65 66 69 6e 65 20 53 51 4c    15.#define SQL
c410: 49 54 45 5f 46 43 4e 54 4c 5f 54 45 4d 50 46 49  ITE_FCNTL_TEMPFI
c420: 4c 45 4e 41 4d 45 20 20 20 20 20 20 20 20 20 20  LENAME          
c430: 20 31 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   16.#define SQLI
c440: 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49  TE_FCNTL_MMAP_SI
c450: 5a 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ZE              
c460: 31 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  18.#define SQLIT
c470: 45 5f 46 43 4e 54 4c 5f 54 52 41 43 45 20 20 20  E_FCNTL_TRACE   
c480: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31                 1
c490: 39 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  9.#define SQLITE
c4a0: 5f 46 43 4e 54 4c 5f 48 41 53 5f 4d 4f 56 45 44  _FCNTL_HAS_MOVED
c4b0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 30                20
c4c0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
c4d0: 46 43 4e 54 4c 5f 53 59 4e 43 20 20 20 20 20 20  FCNTL_SYNC      
c4e0: 20 20 20 20 20 20 20 20 20 20 20 20 20 32 31 0a               21.
c4f0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
c500: 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 50 48 41 53  CNTL_COMMIT_PHAS
c510: 45 54 57 4f 20 20 20 20 20 20 20 20 32 32 0a 23  ETWO        22.#
c520: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
c530: 4e 54 4c 5f 57 49 4e 33 32 5f 53 45 54 5f 48 41  NTL_WIN32_SET_HA
c540: 4e 44 4c 45 20 20 20 20 20 20 20 32 33 0a 23 64  NDLE       23.#d
c550: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
c560: 54 4c 5f 57 41 4c 5f 42 4c 4f 43 4b 20 20 20 20  TL_WAL_BLOCK    
c570: 20 20 20 20 20 20 20 20 20 20 32 34 0a 23 64 65            24.#de
c580: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
c590: 4c 5f 5a 49 50 56 46 53 20 20 20 20 20 20 20 20  L_ZIPVFS        
c5a0: 20 20 20 20 20 20 20 20 20 32 35 0a 23 64 65 66           25.#def
c5b0: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
c5c0: 5f 52 42 55 20 20 20 20 20 20 20 20 20 20 20 20  _RBU            
c5d0: 20 20 20 20 20 20 20 20 32 36 0a 23 64 65 66 69          26.#defi
c5e0: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
c5f0: 56 46 53 5f 50 4f 49 4e 54 45 52 20 20 20 20 20  VFS_POINTER     
c600: 20 20 20 20 20 20 20 32 37 0a 23 64 65 66 69 6e         27.#defin
c610: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4a  e SQLITE_FCNTL_J
c620: 4f 55 52 4e 41 4c 5f 50 4f 49 4e 54 45 52 20 20  OURNAL_POINTER  
c630: 20 20 20 20 20 20 32 38 0a 23 64 65 66 69 6e 65        28.#define
c640: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49   SQLITE_FCNTL_WI
c650: 4e 33 32 5f 47 45 54 5f 48 41 4e 44 4c 45 20 20  N32_GET_HANDLE  
c660: 20 20 20 20 20 32 39 0a 23 64 65 66 69 6e 65 20       29.#define 
c670: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 44 42  SQLITE_FCNTL_PDB
c680: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
c690: 20 20 20 20 33 30 0a 0a 2f 2a 20 64 65 70 72 65      30../* depre
c6a0: 63 61 74 65 64 20 6e 61 6d 65 73 20 2a 2f 0a 23  cated names */.#
c6b0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 47 45  define SQLITE_GE
c6c0: 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20  T_LOCKPROXYFILE 
c6d0: 20 20 20 20 20 53 51 4c 49 54 45 5f 46 43 4e 54       SQLITE_FCNT
c6e0: 4c 5f 47 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46  L_GET_LOCKPROXYF
c6f0: 49 4c 45 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  ILE.#define SQLI
c700: 54 45 5f 53 45 54 5f 4c 4f 43 4b 50 52 4f 58 59  TE_SET_LOCKPROXY
c710: 46 49 4c 45 20 20 20 20 20 20 53 51 4c 49 54 45  FILE      SQLITE
c720: 5f 46 43 4e 54 4c 5f 53 45 54 5f 4c 4f 43 4b 50  _FCNTL_SET_LOCKP
c730: 52 4f 58 59 46 49 4c 45 0a 23 64 65 66 69 6e 65  ROXYFILE.#define
c740: 20 53 51 4c 49 54 45 5f 4c 41 53 54 5f 45 52 52   SQLITE_LAST_ERR
c750: 4e 4f 20 20 20 20 20 20 20 20 20 20 20 20 20 53  NO             S
c760: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 41 53 54  QLITE_FCNTL_LAST
c770: 5f 45 52 52 4e 4f 0a 0a 0a 2f 2a 0a 2a 2a 20 43  _ERRNO.../*.** C
c780: 41 50 49 33 52 45 46 3a 20 4d 75 74 65 78 20 48  API3REF: Mutex H
c790: 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20 54 68 65 20  andle.**.** The 
c7a0: 6d 75 74 65 78 20 6d 6f 64 75 6c 65 20 77 69 74  mutex module wit
c7b0: 68 69 6e 20 53 51 4c 69 74 65 20 64 65 66 69 6e  hin SQLite defin
c7c0: 65 73 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  es [sqlite3_mute
c7d0: 78 5d 20 74 6f 20 62 65 20 61 6e 0a 2a 2a 20 61  x] to be an.** a
c7e0: 62 73 74 72 61 63 74 20 74 79 70 65 20 66 6f 72  bstract type for
c7f0: 20 61 20 6d 75 74 65 78 20 6f 62 6a 65 63 74 2e   a mutex object.
c800: 20 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72    The SQLite cor
c810: 65 20 6e 65 76 65 72 20 6c 6f 6f 6b 73 0a 2a 2a  e never looks.**
c820: 20 61 74 20 74 68 65 20 69 6e 74 65 72 6e 61 6c   at the internal
c830: 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20   representation 
c840: 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 6d  of an [sqlite3_m
c850: 75 74 65 78 5d 2e 20 20 49 74 20 6f 6e 6c 79 0a  utex].  It only.
c860: 2a 2a 20 64 65 61 6c 73 20 77 69 74 68 20 70 6f  ** deals with po
c870: 69 6e 74 65 72 73 20 74 6f 20 74 68 65 20 5b 73  inters to the [s
c880: 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 20 6f 62  qlite3_mutex] ob
c890: 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 4d 75 74 65  ject..**.** Mute
c8a0: 78 65 73 20 61 72 65 20 63 72 65 61 74 65 64 20  xes are created 
c8b0: 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d  using [sqlite3_m
c8c0: 75 74 65 78 5f 61 6c 6c 6f 63 28 29 5d 2e 0a 2a  utex_alloc()]..*
c8d0: 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74  /.typedef struct
c8e0: 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 20 73   sqlite3_mutex s
c8f0: 71 6c 69 74 65 33 5f 6d 75 74 65 78 3b 0a 0a 2f  qlite3_mutex;../
c900: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4c  *.** CAPI3REF: L
c910: 6f 61 64 61 62 6c 65 20 45 78 74 65 6e 73 69 6f  oadable Extensio
c920: 6e 20 54 68 75 6e 6b 0a 2a 2a 0a 2a 2a 20 41 20  n Thunk.**.** A 
c930: 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 6f  pointer to the o
c940: 70 61 71 75 65 20 73 71 6c 69 74 65 33 5f 61 70  paque sqlite3_ap
c950: 69 5f 72 6f 75 74 69 6e 65 73 20 73 74 72 75 63  i_routines struc
c960: 74 75 72 65 20 69 73 20 70 61 73 73 65 64 20 61  ture is passed a
c970: 73 0a 2a 2a 20 74 68 65 20 74 68 69 72 64 20 70  s.** the third p
c980: 61 72 61 6d 65 74 65 72 20 74 6f 20 65 6e 74 72  arameter to entr
c990: 79 20 70 6f 69 6e 74 73 20 6f 66 20 5b 6c 6f 61  y points of [loa
c9a0: 64 61 62 6c 65 20 65 78 74 65 6e 73 69 6f 6e 73  dable extensions
c9b0: 5d 2e 20 20 54 68 69 73 0a 2a 2a 20 73 74 72 75  ].  This.** stru
c9c0: 63 74 75 72 65 20 6d 75 73 74 20 62 65 20 74 79  cture must be ty
c9d0: 70 65 64 65 66 65 64 20 69 6e 20 6f 72 64 65 72  pedefed in order
c9e0: 20 74 6f 20 77 6f 72 6b 20 61 72 6f 75 6e 64 20   to work around 
c9f0: 63 6f 6d 70 69 6c 65 72 20 77 61 72 6e 69 6e 67  compiler warning
ca00: 73 0a 2a 2a 20 6f 6e 20 73 6f 6d 65 20 70 6c 61  s.** on some pla
ca10: 74 66 6f 72 6d 73 2e 0a 2a 2f 0a 74 79 70 65 64  tforms..*/.typed
ca20: 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  ef struct sqlite
ca30: 33 5f 61 70 69 5f 72 6f 75 74 69 6e 65 73 20 73  3_api_routines s
ca40: 71 6c 69 74 65 33 5f 61 70 69 5f 72 6f 75 74 69  qlite3_api_routi
ca50: 6e 65 73 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  nes;../*.** CAPI
ca60: 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66 61  3REF: OS Interfa
ca70: 63 65 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20  ce Object.**.** 
ca80: 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  An instance of t
ca90: 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 20 6f  he sqlite3_vfs o
caa0: 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74 68  bject defines th
cab0: 65 20 69 6e 74 65 72 66 61 63 65 20 62 65 74 77  e interface betw
cac0: 65 65 6e 0a 2a 2a 20 74 68 65 20 53 51 4c 69 74  een.** the SQLit
cad0: 65 20 63 6f 72 65 20 61 6e 64 20 74 68 65 20 75  e core and the u
cae0: 6e 64 65 72 6c 79 69 6e 67 20 6f 70 65 72 61 74  nderlying operat
caf0: 69 6e 67 20 73 79 73 74 65 6d 2e 20 20 54 68 65  ing system.  The
cb00: 20 22 76 66 73 22 0a 2a 2a 20 69 6e 20 74 68 65   "vfs".** in the
cb10: 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 6f 62 6a   name of the obj
cb20: 65 63 74 20 73 74 61 6e 64 73 20 66 6f 72 20 22  ect stands for "
cb30: 76 69 72 74 75 61 6c 20 66 69 6c 65 20 73 79 73  virtual file sys
cb40: 74 65 6d 22 2e 20 20 53 65 65 0a 2a 2a 20 74 68  tem".  See.** th
cb50: 65 20 5b 56 46 53 20 7c 20 56 46 53 20 64 6f 63  e [VFS | VFS doc
cb60: 75 6d 65 6e 74 61 74 69 6f 6e 5d 20 66 6f 72 20  umentation] for 
cb70: 66 75 72 74 68 65 72 20 69 6e 66 6f 72 6d 61 74  further informat
cb80: 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 76  ion..**.** The v
cb90: 61 6c 75 65 20 6f 66 20 74 68 65 20 69 56 65 72  alue of the iVer
cba0: 73 69 6f 6e 20 66 69 65 6c 64 20 69 73 20 69 6e  sion field is in
cbb0: 69 74 69 61 6c 6c 79 20 31 20 62 75 74 20 6d 61  itially 1 but ma
cbc0: 79 20 62 65 20 6c 61 72 67 65 72 20 69 6e 0a 2a  y be larger in.*
cbd0: 2a 20 66 75 74 75 72 65 20 76 65 72 73 69 6f 6e  * future version
cbe0: 73 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 41 64  s of SQLite.  Ad
cbf0: 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73 20  ditional fields 
cc00: 6d 61 79 20 62 65 20 61 70 70 65 6e 64 65 64 20  may be appended 
cc10: 74 6f 20 74 68 69 73 0a 2a 2a 20 6f 62 6a 65 63  to this.** objec
cc20: 74 20 77 68 65 6e 20 74 68 65 20 69 56 65 72 73  t when the iVers
cc30: 69 6f 6e 20 76 61 6c 75 65 20 69 73 20 69 6e 63  ion value is inc
cc40: 72 65 61 73 65 64 2e 20 20 4e 6f 74 65 20 74 68  reased.  Note th
cc50: 61 74 20 74 68 65 20 73 74 72 75 63 74 75 72 65  at the structure
cc60: 0a 2a 2a 20 6f 66 20 74 68 65 20 73 71 6c 69 74  .** of the sqlit
cc70: 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 20 63 68  e3_vfs object ch
cc80: 61 6e 67 65 73 20 69 6e 20 74 68 65 20 74 72 61  anges in the tra
cc90: 6e 73 61 63 74 69 6f 6e 20 62 65 74 77 65 65 6e  nsaction between
cca0: 0a 2a 2a 20 53 51 4c 69 74 65 20 76 65 72 73 69  .** SQLite versi
ccb0: 6f 6e 20 33 2e 35 2e 39 20 61 6e 64 20 33 2e 36  on 3.5.9 and 3.6
ccc0: 2e 30 20 61 6e 64 20 79 65 74 20 74 68 65 20 69  .0 and yet the i
ccd0: 56 65 72 73 69 6f 6e 20 66 69 65 6c 64 20 77 61  Version field wa
cce0: 73 20 6e 6f 74 0a 2a 2a 20 6d 6f 64 69 66 69 65  s not.** modifie
ccf0: 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 7a 4f  d..**.** The szO
cd00: 73 46 69 6c 65 20 66 69 65 6c 64 20 69 73 20 74  sFile field is t
cd10: 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 73  he size of the s
cd20: 75 62 63 6c 61 73 73 65 64 20 5b 73 71 6c 69 74  ubclassed [sqlit
cd30: 65 33 5f 66 69 6c 65 5d 0a 2a 2a 20 73 74 72 75  e3_file].** stru
cd40: 63 74 75 72 65 20 75 73 65 64 20 62 79 20 74 68  cture used by th
cd50: 69 73 20 56 46 53 2e 20 20 6d 78 50 61 74 68 6e  is VFS.  mxPathn
cd60: 61 6d 65 20 69 73 20 74 68 65 20 6d 61 78 69 6d  ame is the maxim
cd70: 75 6d 20 6c 65 6e 67 74 68 20 6f 66 0a 2a 2a 20  um length of.** 
cd80: 61 20 70 61 74 68 6e 61 6d 65 20 69 6e 20 74 68  a pathname in th
cd90: 69 73 20 56 46 53 2e 0a 2a 2a 0a 2a 2a 20 52 65  is VFS..**.** Re
cda0: 67 69 73 74 65 72 65 64 20 73 71 6c 69 74 65 33  gistered sqlite3
cdb0: 5f 76 66 73 20 6f 62 6a 65 63 74 73 20 61 72 65  _vfs objects are
cdc0: 20 6b 65 70 74 20 6f 6e 20 61 20 6c 69 6e 6b 65   kept on a linke
cdd0: 64 20 6c 69 73 74 20 66 6f 72 6d 65 64 20 62 79  d list formed by
cde0: 0a 2a 2a 20 74 68 65 20 70 4e 65 78 74 20 70 6f  .** the pNext po
cdf0: 69 6e 74 65 72 2e 20 20 54 68 65 20 5b 73 71 6c  inter.  The [sql
ce00: 69 74 65 33 5f 76 66 73 5f 72 65 67 69 73 74 65  ite3_vfs_registe
ce10: 72 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c  r()].** and [sql
ce20: 69 74 65 33 5f 76 66 73 5f 75 6e 72 65 67 69 73  ite3_vfs_unregis
ce30: 74 65 72 28 29 5d 20 69 6e 74 65 72 66 61 63 65  ter()] interface
ce40: 73 20 6d 61 6e 61 67 65 20 74 68 69 73 20 6c 69  s manage this li
ce50: 73 74 0a 2a 2a 20 69 6e 20 61 20 74 68 72 65 61  st.** in a threa
ce60: 64 2d 73 61 66 65 20 77 61 79 2e 20 20 54 68 65  d-safe way.  The
ce70: 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f 66 69   [sqlite3_vfs_fi
ce80: 6e 64 28 29 5d 20 69 6e 74 65 72 66 61 63 65 0a  nd()] interface.
ce90: 2a 2a 20 73 65 61 72 63 68 65 73 20 74 68 65 20  ** searches the 
cea0: 6c 69 73 74 2e 20 20 4e 65 69 74 68 65 72 20 74  list.  Neither t
ceb0: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 63  he application c
cec0: 6f 64 65 20 6e 6f 72 20 74 68 65 20 56 46 53 0a  ode nor the VFS.
ced0: 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ** implementatio
cee0: 6e 20 73 68 6f 75 6c 64 20 75 73 65 20 74 68 65  n should use the
cef0: 20 70 4e 65 78 74 20 70 6f 69 6e 74 65 72 2e 0a   pNext pointer..
cf00: 2a 2a 0a 2a 2a 20 54 68 65 20 70 4e 65 78 74 20  **.** The pNext 
cf10: 66 69 65 6c 64 20 69 73 20 74 68 65 20 6f 6e 6c  field is the onl
cf20: 79 20 66 69 65 6c 64 20 69 6e 20 74 68 65 20 73  y field in the s
cf30: 71 6c 69 74 65 33 5f 76 66 73 0a 2a 2a 20 73 74  qlite3_vfs.** st
cf40: 72 75 63 74 75 72 65 20 74 68 61 74 20 53 51 4c  ructure that SQL
cf50: 69 74 65 20 77 69 6c 6c 20 65 76 65 72 20 6d 6f  ite will ever mo
cf60: 64 69 66 79 2e 20 20 53 51 4c 69 74 65 20 77 69  dify.  SQLite wi
cf70: 6c 6c 20 6f 6e 6c 79 20 61 63 63 65 73 73 0a 2a  ll only access.*
cf80: 2a 20 6f 72 20 6d 6f 64 69 66 79 20 74 68 69 73  * or modify this
cf90: 20 66 69 65 6c 64 20 77 68 69 6c 65 20 68 6f 6c   field while hol
cfa0: 64 69 6e 67 20 61 20 70 61 72 74 69 63 75 6c 61  ding a particula
cfb0: 72 20 73 74 61 74 69 63 20 6d 75 74 65 78 2e 0a  r static mutex..
cfc0: 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  ** The applicati
cfd0: 6f 6e 20 73 68 6f 75 6c 64 20 6e 65 76 65 72 20  on should never 
cfe0: 6d 6f 64 69 66 79 20 61 6e 79 74 68 69 6e 67 20  modify anything 
cff0: 77 69 74 68 69 6e 20 74 68 65 20 73 71 6c 69 74  within the sqlit
d000: 65 33 5f 76 66 73 0a 2a 2a 20 6f 62 6a 65 63 74  e3_vfs.** object
d010: 20 6f 6e 63 65 20 74 68 65 20 6f 62 6a 65 63 74   once the object
d020: 20 68 61 73 20 62 65 65 6e 20 72 65 67 69 73 74   has been regist
d030: 65 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ered..**.** The 
d040: 7a 4e 61 6d 65 20 66 69 65 6c 64 20 68 6f 6c 64  zName field hold
d050: 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  s the name of th
d060: 65 20 56 46 53 20 6d 6f 64 75 6c 65 2e 20 20 54  e VFS module.  T
d070: 68 65 20 6e 61 6d 65 20 6d 75 73 74 0a 2a 2a 20  he name must.** 
d080: 62 65 20 75 6e 69 71 75 65 20 61 63 72 6f 73 73  be unique across
d090: 20 61 6c 6c 20 56 46 53 20 6d 6f 64 75 6c 65 73   all VFS modules
d0a0: 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 73 71 6c 69 74 65  ..**.** [[sqlite
d0b0: 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 5d 0a 2a 2a  3_vfs.xOpen]].**
d0c0: 20 5e 53 51 4c 69 74 65 20 67 75 61 72 61 6e 74   ^SQLite guarant
d0d0: 65 65 73 20 74 68 61 74 20 74 68 65 20 7a 46 69  ees that the zFi
d0e0: 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72  lename parameter
d0f0: 20 74 6f 20 78 4f 70 65 6e 0a 2a 2a 20 69 73 20   to xOpen.** is 
d100: 65 69 74 68 65 72 20 61 20 4e 55 4c 4c 20 70 6f  either a NULL po
d110: 69 6e 74 65 72 20 6f 72 20 73 74 72 69 6e 67 20  inter or string 
d120: 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d  obtained.** from
d130: 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 28 29   xFullPathname()
d140: 20 77 69 74 68 20 61 6e 20 6f 70 74 69 6f 6e 61   with an optiona
d150: 6c 20 73 75 66 66 69 78 20 61 64 64 65 64 2e 0a  l suffix added..
d160: 2a 2a 20 5e 49 66 20 61 20 73 75 66 66 69 78 20  ** ^If a suffix 
d170: 69 73 20 61 64 64 65 64 20 74 6f 20 74 68 65 20  is added to the 
d180: 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65  zFilename parame
d190: 74 65 72 2c 20 69 74 20 77 69 6c 6c 0a 2a 2a 20  ter, it will.** 
d1a0: 63 6f 6e 73 69 73 74 20 6f 66 20 61 20 73 69 6e  consist of a sin
d1b0: 67 6c 65 20 22 2d 22 20 63 68 61 72 61 63 74 65  gle "-" characte
d1c0: 72 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 6e 6f  r followed by no
d1d0: 20 6d 6f 72 65 20 74 68 61 6e 0a 2a 2a 20 31 31   more than.** 11
d1e0: 20 61 6c 70 68 61 6e 75 6d 65 72 69 63 20 61 6e   alphanumeric an
d1f0: 64 2f 6f 72 20 22 2d 22 20 63 68 61 72 61 63 74  d/or "-" charact
d200: 65 72 73 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20  ers..** ^SQLite 
d210: 66 75 72 74 68 65 72 20 67 75 61 72 61 6e 74 65  further guarante
d220: 65 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 73  es that.** the s
d230: 74 72 69 6e 67 20 77 69 6c 6c 20 62 65 20 76 61  tring will be va
d240: 6c 69 64 20 61 6e 64 20 75 6e 63 68 61 6e 67 65  lid and unchange
d250: 64 20 75 6e 74 69 6c 20 78 43 6c 6f 73 65 28 29  d until xClose()
d260: 20 69 73 0a 2a 2a 20 63 61 6c 6c 65 64 2e 20 42   is.** called. B
d270: 65 63 61 75 73 65 20 6f 66 20 74 68 65 20 70 72  ecause of the pr
d280: 65 76 69 6f 75 73 20 73 65 6e 74 65 6e 63 65 2c  evious sentence,
d290: 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33  .** the [sqlite3
d2a0: 5f 66 69 6c 65 5d 20 63 61 6e 20 73 61 66 65 6c  _file] can safel
d2b0: 79 20 73 74 6f 72 65 20 61 20 70 6f 69 6e 74 65  y store a pointe
d2c0: 72 20 74 6f 20 74 68 65 0a 2a 2a 20 66 69 6c 65  r to the.** file
d2d0: 6e 61 6d 65 20 69 66 20 69 74 20 6e 65 65 64 73  name if it needs
d2e0: 20 74 6f 20 72 65 6d 65 6d 62 65 72 20 74 68 65   to remember the
d2f0: 20 66 69 6c 65 6e 61 6d 65 20 66 6f 72 20 73 6f   filename for so
d300: 6d 65 20 72 65 61 73 6f 6e 2e 0a 2a 2a 20 49 66  me reason..** If
d310: 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70   the zFilename p
d320: 61 72 61 6d 65 74 65 72 20 74 6f 20 78 4f 70 65  arameter to xOpe
d330: 6e 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  n is a NULL poin
d340: 74 65 72 20 74 68 65 6e 20 78 4f 70 65 6e 0a 2a  ter then xOpen.*
d350: 2a 20 6d 75 73 74 20 69 6e 76 65 6e 74 20 69 74  * must invent it
d360: 73 20 6f 77 6e 20 74 65 6d 70 6f 72 61 72 79 20  s own temporary 
d370: 6e 61 6d 65 20 66 6f 72 20 74 68 65 20 66 69 6c  name for the fil
d380: 65 2e 20 20 5e 57 68 65 6e 65 76 65 72 20 74 68  e.  ^Whenever th
d390: 65 20 0a 2a 2a 20 78 46 69 6c 65 6e 61 6d 65 20  e .** xFilename 
d3a0: 70 61 72 61 6d 65 74 65 72 20 69 73 20 4e 55 4c  parameter is NUL
d3b0: 4c 20 69 74 20 77 69 6c 6c 20 61 6c 73 6f 20 62  L it will also b
d3c0: 65 20 74 68 65 20 63 61 73 65 20 74 68 61 74 20  e the case that 
d3d0: 74 68 65 0a 2a 2a 20 66 6c 61 67 73 20 70 61 72  the.** flags par
d3e0: 61 6d 65 74 65 72 20 77 69 6c 6c 20 69 6e 63 6c  ameter will incl
d3f0: 75 64 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  ude [SQLITE_OPEN
d400: 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 2e  _DELETEONCLOSE].
d410: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c 61 67 73  .**.** The flags
d420: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 4f 70   argument to xOp
d430: 65 6e 28 29 20 69 6e 63 6c 75 64 65 73 20 61 6c  en() includes al
d440: 6c 20 62 69 74 73 20 73 65 74 20 69 6e 0a 2a 2a  l bits set in.**
d450: 20 74 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d   the flags argum
d460: 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  ent to [sqlite3_
d470: 6f 70 65 6e 5f 76 32 28 29 5d 2e 20 20 4f 72 20  open_v2()].  Or 
d480: 69 66 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  if [sqlite3_open
d490: 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74  ()].** or [sqlit
d4a0: 65 33 5f 6f 70 65 6e 31 36 28 29 5d 20 69 73 20  e3_open16()] is 
d4b0: 75 73 65 64 2c 20 74 68 65 6e 20 66 6c 61 67 73  used, then flags
d4c0: 20 69 6e 63 6c 75 64 65 73 20 61 74 20 6c 65 61   includes at lea
d4d0: 73 74 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50  st.** [SQLITE_OP
d4e0: 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 20 7c 20  EN_READWRITE] | 
d4f0: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45  [SQLITE_OPEN_CRE
d500: 41 54 45 5d 2e 20 0a 2a 2a 20 49 66 20 78 4f 70  ATE]. .** If xOp
d510: 65 6e 28 29 20 6f 70 65 6e 73 20 61 20 66 69 6c  en() opens a fil
d520: 65 20 72 65 61 64 2d 6f 6e 6c 79 20 74 68 65 6e  e read-only then
d530: 20 69 74 20 73 65 74 73 20 2a 70 4f 75 74 46 6c   it sets *pOutFl
d540: 61 67 73 20 74 6f 0a 2a 2a 20 69 6e 63 6c 75 64  ags to.** includ
d550: 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52  e [SQLITE_OPEN_R
d560: 45 41 44 4f 4e 4c 59 5d 2e 20 20 4f 74 68 65 72  EADONLY].  Other
d570: 20 62 69 74 73 20 69 6e 20 2a 70 4f 75 74 46 6c   bits in *pOutFl
d580: 61 67 73 20 6d 61 79 20 62 65 20 73 65 74 2e 0a  ags may be set..
d590: 2a 2a 0a 2a 2a 20 5e 28 53 51 4c 69 74 65 20 77  **.** ^(SQLite w
d5a0: 69 6c 6c 20 61 6c 73 6f 20 61 64 64 20 6f 6e 65  ill also add one
d5b0: 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e   of the followin
d5c0: 67 20 66 6c 61 67 73 20 74 6f 20 74 68 65 20 78  g flags to the x
d5d0: 4f 70 65 6e 28 29 0a 2a 2a 20 63 61 6c 6c 2c 20  Open().** call, 
d5e0: 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65  depending on the
d5f0: 20 6f 62 6a 65 63 74 20 62 65 69 6e 67 20 6f 70   object being op
d600: 65 6e 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  ened:.**.** <ul>
d610: 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54  .** <li>  [SQLIT
d620: 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 5d 0a  E_OPEN_MAIN_DB].
d630: 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45  ** <li>  [SQLITE
d640: 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e  _OPEN_MAIN_JOURN
d650: 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51  AL].** <li>  [SQ
d660: 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44  LITE_OPEN_TEMP_D
d670: 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c  B].** <li>  [SQL
d680: 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f  ITE_OPEN_TEMP_JO
d690: 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20  URNAL].** <li>  
d6a0: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 52 41  [SQLITE_OPEN_TRA
d6b0: 4e 53 49 45 4e 54 5f 44 42 5d 0a 2a 2a 20 3c 6c  NSIENT_DB].** <l
d6c0: 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  i>  [SQLITE_OPEN
d6d0: 5f 53 55 42 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20  _SUBJOURNAL].** 
d6e0: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50  <li>  [SQLITE_OP
d6f0: 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55 52 4e 41  EN_MASTER_JOURNA
d700: 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c  L].** <li>  [SQL
d710: 49 54 45 5f 4f 50 45 4e 5f 57 41 4c 5d 0a 2a 2a  ITE_OPEN_WAL].**
d720: 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54   </ul>)^.**.** T
d730: 68 65 20 66 69 6c 65 20 49 2f 4f 20 69 6d 70 6c  he file I/O impl
d740: 65 6d 65 6e 74 61 74 69 6f 6e 20 63 61 6e 20 75  ementation can u
d750: 73 65 20 74 68 65 20 6f 62 6a 65 63 74 20 74 79  se the object ty
d760: 70 65 20 66 6c 61 67 73 20 74 6f 0a 2a 2a 20 63  pe flags to.** c
d770: 68 61 6e 67 65 20 74 68 65 20 77 61 79 20 69 74  hange the way it
d780: 20 64 65 61 6c 73 20 77 69 74 68 20 66 69 6c 65   deals with file
d790: 73 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c  s.  For example,
d7a0: 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a   an application.
d7b0: 2a 2a 20 74 68 61 74 20 64 6f 65 73 20 6e 6f 74  ** that does not
d7c0: 20 63 61 72 65 20 61 62 6f 75 74 20 63 72 61 73   care about cras
d7d0: 68 20 72 65 63 6f 76 65 72 79 20 6f 72 20 72 6f  h recovery or ro
d7e0: 6c 6c 62 61 63 6b 20 6d 69 67 68 74 20 6d 61 6b  llback might mak
d7f0: 65 0a 2a 2a 20 74 68 65 20 6f 70 65 6e 20 6f 66  e.** the open of
d800: 20 61 20 6a 6f 75 72 6e 61 6c 20 66 69 6c 65 20   a journal file 
d810: 61 20 6e 6f 2d 6f 70 2e 20 20 57 72 69 74 65 73  a no-op.  Writes
d820: 20 74 6f 20 74 68 69 73 20 6a 6f 75 72 6e 61 6c   to this journal
d830: 20 77 6f 75 6c 64 0a 2a 2a 20 61 6c 73 6f 20 62   would.** also b
d840: 65 20 6e 6f 2d 6f 70 73 2c 20 61 6e 64 20 61 6e  e no-ops, and an
d850: 79 20 61 74 74 65 6d 70 74 20 74 6f 20 72 65 61  y attempt to rea
d860: 64 20 74 68 65 20 6a 6f 75 72 6e 61 6c 20 77 6f  d the journal wo
d870: 75 6c 64 20 72 65 74 75 72 6e 0a 2a 2a 20 53 51  uld return.** SQ
d880: 4c 49 54 45 5f 49 4f 45 52 52 2e 20 20 4f 72 20  LITE_IOERR.  Or 
d890: 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  the implementati
d8a0: 6f 6e 20 6d 69 67 68 74 20 72 65 63 6f 67 6e 69  on might recogni
d8b0: 7a 65 20 74 68 61 74 20 61 20 64 61 74 61 62 61  ze that a databa
d8c0: 73 65 0a 2a 2a 20 66 69 6c 65 20 77 69 6c 6c 20  se.** file will 
d8d0: 62 65 20 64 6f 69 6e 67 20 70 61 67 65 2d 61 6c  be doing page-al
d8e0: 69 67 6e 65 64 20 73 65 63 74 6f 72 20 72 65 61  igned sector rea
d8f0: 64 73 20 61 6e 64 20 77 72 69 74 65 73 20 69 6e  ds and writes in
d900: 20 61 20 72 61 6e 64 6f 6d 0a 2a 2a 20 6f 72 64   a random.** ord
d910: 65 72 20 61 6e 64 20 73 65 74 20 75 70 20 69 74  er and set up it
d920: 73 20 49 2f 4f 20 73 75 62 73 79 73 74 65 6d 20  s I/O subsystem 
d930: 61 63 63 6f 72 64 69 6e 67 6c 79 2e 0a 2a 2a 0a  accordingly..**.
d940: 2a 2a 20 53 51 4c 69 74 65 20 6d 69 67 68 74 20  ** SQLite might 
d950: 61 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20  also add one of 
d960: 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c  the following fl
d970: 61 67 73 20 74 6f 20 74 68 65 20 78 4f 70 65 6e  ags to the xOpen
d980: 20 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c   method:.**.** <
d990: 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  ul>.** <li> [SQL
d9a0: 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f  ITE_OPEN_DELETEO
d9b0: 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 3c 6c 69 3e 20  NCLOSE].** <li> 
d9c0: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43  [SQLITE_OPEN_EXC
d9d0: 4c 55 53 49 56 45 5d 0a 2a 2a 20 3c 2f 75 6c 3e  LUSIVE].** </ul>
d9e0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49  .**.** The [SQLI
d9f0: 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e  TE_OPEN_DELETEON
da00: 43 4c 4f 53 45 5d 20 66 6c 61 67 20 6d 65 61 6e  CLOSE] flag mean
da10: 73 20 74 68 65 20 66 69 6c 65 20 73 68 6f 75 6c  s the file shoul
da20: 64 20 62 65 0a 2a 2a 20 64 65 6c 65 74 65 64 20  d be.** deleted 
da30: 77 68 65 6e 20 69 74 20 69 73 20 63 6c 6f 73 65  when it is close
da40: 64 2e 20 20 5e 54 68 65 20 5b 53 51 4c 49 54 45  d.  ^The [SQLITE
da50: 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c  _OPEN_DELETEONCL
da60: 4f 53 45 5d 0a 2a 2a 20 77 69 6c 6c 20 62 65 20  OSE].** will be 
da70: 73 65 74 20 66 6f 72 20 54 45 4d 50 20 64 61 74  set for TEMP dat
da80: 61 62 61 73 65 73 20 61 6e 64 20 74 68 65 69 72  abases and their
da90: 20 6a 6f 75 72 6e 61 6c 73 2c 20 74 72 61 6e 73   journals, trans
daa0: 69 65 6e 74 0a 2a 2a 20 64 61 74 61 62 61 73 65  ient.** database
dab0: 73 2c 20 61 6e 64 20 73 75 62 6a 6f 75 72 6e 61  s, and subjourna
dac0: 6c 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b  ls..**.** ^The [
dad0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c  SQLITE_OPEN_EXCL
dae0: 55 53 49 56 45 5d 20 66 6c 61 67 20 69 73 20 61  USIVE] flag is a
daf0: 6c 77 61 79 73 20 75 73 65 64 20 69 6e 20 63 6f  lways used in co
db00: 6e 6a 75 6e 63 74 69 6f 6e 0a 2a 2a 20 77 69 74  njunction.** wit
db10: 68 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50  h the [SQLITE_OP
db20: 45 4e 5f 43 52 45 41 54 45 5d 20 66 6c 61 67 2c  EN_CREATE] flag,
db30: 20 77 68 69 63 68 20 61 72 65 20 62 6f 74 68 20   which are both 
db40: 64 69 72 65 63 74 6c 79 0a 2a 2a 20 61 6e 61 6c  directly.** anal
db50: 6f 67 6f 75 73 20 74 6f 20 74 68 65 20 4f 5f 45  ogous to the O_E
db60: 58 43 4c 20 61 6e 64 20 4f 5f 43 52 45 41 54 20  XCL and O_CREAT 
db70: 66 6c 61 67 73 20 6f 66 20 74 68 65 20 50 4f 53  flags of the POS
db80: 49 58 20 6f 70 65 6e 28 29 0a 2a 2a 20 41 50 49  IX open().** API
db90: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 4f 50  .  The SQLITE_OP
dba0: 45 4e 5f 45 58 43 4c 55 53 49 56 45 20 66 6c 61  EN_EXCLUSIVE fla
dbb0: 67 2c 20 77 68 65 6e 20 70 61 69 72 65 64 20 77  g, when paired w
dbc0: 69 74 68 20 74 68 65 20 0a 2a 2a 20 53 51 4c 49  ith the .** SQLI
dbd0: 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 2c 20  TE_OPEN_CREATE, 
dbe0: 69 73 20 75 73 65 64 20 74 6f 20 69 6e 64 69 63  is used to indic
dbf0: 61 74 65 20 74 68 61 74 20 66 69 6c 65 20 73 68  ate that file sh
dc00: 6f 75 6c 64 20 61 6c 77 61 79 73 0a 2a 2a 20 62  ould always.** b
dc10: 65 20 63 72 65 61 74 65 64 2c 20 61 6e 64 20 74  e created, and t
dc20: 68 61 74 20 69 74 20 69 73 20 61 6e 20 65 72 72  hat it is an err
dc30: 6f 72 20 69 66 20 69 74 20 61 6c 72 65 61 64 79  or if it already
dc40: 20 65 78 69 73 74 73 2e 0a 2a 2a 20 49 74 20 69   exists..** It i
dc50: 73 20 3c 69 3e 6e 6f 74 3c 2f 69 3e 20 75 73 65  s <i>not</i> use
dc60: 64 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68  d to indicate th
dc70: 65 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 62 65  e file should be
dc80: 20 6f 70 65 6e 65 64 20 0a 2a 2a 20 66 6f 72 20   opened .** for 
dc90: 65 78 63 6c 75 73 69 76 65 20 61 63 63 65 73 73  exclusive access
dca0: 2e 0a 2a 2a 0a 2a 2a 20 5e 41 74 20 6c 65 61 73  ..**.** ^At leas
dcb0: 74 20 73 7a 4f 73 46 69 6c 65 20 62 79 74 65 73  t szOsFile bytes
dcc0: 20 6f 66 20 6d 65 6d 6f 72 79 20 61 72 65 20 61   of memory are a
dcd0: 6c 6c 6f 63 61 74 65 64 20 62 79 20 53 51 4c 69  llocated by SQLi
dce0: 74 65 0a 2a 2a 20 74 6f 20 68 6f 6c 64 20 74 68  te.** to hold th
dcf0: 65 20 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  e  [sqlite3_file
dd00: 5d 20 73 74 72 75 63 74 75 72 65 20 70 61 73 73  ] structure pass
dd10: 65 64 20 61 73 20 74 68 65 20 74 68 69 72 64 0a  ed as the third.
dd20: 2a 2a 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78  ** argument to x
dd30: 4f 70 65 6e 2e 20 20 54 68 65 20 78 4f 70 65 6e  Open.  The xOpen
dd40: 20 6d 65 74 68 6f 64 20 64 6f 65 73 20 6e 6f 74   method does not
dd50: 20 68 61 76 65 20 74 6f 0a 2a 2a 20 61 6c 6c 6f   have to.** allo
dd60: 63 61 74 65 20 74 68 65 20 73 74 72 75 63 74 75  cate the structu
dd70: 72 65 3b 20 69 74 20 73 68 6f 75 6c 64 20 6a 75  re; it should ju
dd80: 73 74 20 66 69 6c 6c 20 69 74 20 69 6e 2e 20 20  st fill it in.  
dd90: 4e 6f 74 65 20 74 68 61 74 0a 2a 2a 20 74 68 65  Note that.** the
dda0: 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 6d 75   xOpen method mu
ddb0: 73 74 20 73 65 74 20 74 68 65 20 73 71 6c 69 74  st set the sqlit
ddc0: 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73  e3_file.pMethods
ddd0: 20 74 6f 20 65 69 74 68 65 72 0a 2a 2a 20 61 20   to either.** a 
dde0: 76 61 6c 69 64 20 5b 73 71 6c 69 74 65 33 5f 69  valid [sqlite3_i
ddf0: 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63  o_methods] objec
de00: 74 20 6f 72 20 74 6f 20 4e 55 4c 4c 2e 20 20 78  t or to NULL.  x
de10: 4f 70 65 6e 20 6d 75 73 74 20 64 6f 0a 2a 2a 20  Open must do.** 
de20: 74 68 69 73 20 65 76 65 6e 20 69 66 20 74 68 65  this even if the
de30: 20 6f 70 65 6e 20 66 61 69 6c 73 2e 20 20 53 51   open fails.  SQ
de40: 4c 69 74 65 20 65 78 70 65 63 74 73 20 74 68 61  Lite expects tha
de50: 74 20 74 68 65 20 73 71 6c 69 74 65 33 5f 66 69  t the sqlite3_fi
de60: 6c 65 2e 70 4d 65 74 68 6f 64 73 0a 2a 2a 20 65  le.pMethods.** e
de70: 6c 65 6d 65 6e 74 20 77 69 6c 6c 20 62 65 20 76  lement will be v
de80: 61 6c 69 64 20 61 66 74 65 72 20 78 4f 70 65 6e  alid after xOpen
de90: 20 72 65 74 75 72 6e 73 20 72 65 67 61 72 64 6c   returns regardl
dea0: 65 73 73 20 6f 66 20 74 68 65 20 73 75 63 63 65  ess of the succe
deb0: 73 73 0a 2a 2a 20 6f 72 20 66 61 69 6c 75 72 65  ss.** or failure
dec0: 20 6f 66 20 74 68 65 20 78 4f 70 65 6e 20 63 61   of the xOpen ca
ded0: 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 73 71 6c 69  ll..**.** [[sqli
dee0: 74 65 33 5f 76 66 73 2e 78 41 63 63 65 73 73 5d  te3_vfs.xAccess]
def0: 5d 0a 2a 2a 20 5e 54 68 65 20 66 6c 61 67 73 20  ].** ^The flags 
df00: 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 41 63 63  argument to xAcc
df10: 65 73 73 28 29 20 6d 61 79 20 62 65 20 5b 53 51  ess() may be [SQ
df20: 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49 53  LITE_ACCESS_EXIS
df30: 54 53 5d 0a 2a 2a 20 74 6f 20 74 65 73 74 20 66  TS].** to test f
df40: 6f 72 20 74 68 65 20 65 78 69 73 74 65 6e 63 65  or the existence
df50: 20 6f 66 20 61 20 66 69 6c 65 2c 20 6f 72 20 5b   of a file, or [
df60: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45  SQLITE_ACCESS_RE
df70: 41 44 57 52 49 54 45 5d 20 74 6f 0a 2a 2a 20 74  ADWRITE] to.** t
df80: 65 73 74 20 77 68 65 74 68 65 72 20 61 20 66 69  est whether a fi
df90: 6c 65 20 69 73 20 72 65 61 64 61 62 6c 65 20 61  le is readable a
dfa0: 6e 64 20 77 72 69 74 61 62 6c 65 2c 20 6f 72 20  nd writable, or 
dfb0: 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52  [SQLITE_ACCESS_R
dfc0: 45 41 44 5d 0a 2a 2a 20 74 6f 20 74 65 73 74 20  EAD].** to test 
dfd0: 77 68 65 74 68 65 72 20 61 20 66 69 6c 65 20 69  whether a file i
dfe0: 73 20 61 74 20 6c 65 61 73 74 20 72 65 61 64 61  s at least reada
dff0: 62 6c 65 2e 20 20 20 54 68 65 20 66 69 6c 65 20  ble.   The file 
e000: 63 61 6e 20 62 65 20 61 0a 2a 2a 20 64 69 72 65  can be a.** dire
e010: 63 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51  ctory..**.** ^SQ
e020: 4c 69 74 65 20 77 69 6c 6c 20 61 6c 77 61 79 73  Lite will always
e030: 20 61 6c 6c 6f 63 61 74 65 20 61 74 20 6c 65 61   allocate at lea
e040: 73 74 20 6d 78 50 61 74 68 6e 61 6d 65 2b 31 20  st mxPathname+1 
e050: 62 79 74 65 73 20 66 6f 72 20 74 68 65 0a 2a 2a  bytes for the.**
e060: 20 6f 75 74 70 75 74 20 62 75 66 66 65 72 20 78   output buffer x
e070: 46 75 6c 6c 50 61 74 68 6e 61 6d 65 2e 20 20 54  FullPathname.  T
e080: 68 65 20 65 78 61 63 74 20 73 69 7a 65 20 6f 66  he exact size of
e090: 20 74 68 65 20 6f 75 74 70 75 74 20 62 75 66 66   the output buff
e0a0: 65 72 0a 2a 2a 20 69 73 20 61 6c 73 6f 20 70 61  er.** is also pa
e0b0: 73 73 65 64 20 61 73 20 61 20 70 61 72 61 6d 65  ssed as a parame
e0c0: 74 65 72 20 74 6f 20 62 6f 74 68 20 20 6d 65 74  ter to both  met
e0d0: 68 6f 64 73 2e 20 49 66 20 74 68 65 20 6f 75 74  hods. If the out
e0e0: 70 75 74 20 62 75 66 66 65 72 0a 2a 2a 20 69 73  put buffer.** is
e0f0: 20 6e 6f 74 20 6c 61 72 67 65 20 65 6e 6f 75 67   not large enoug
e100: 68 2c 20 5b 53 51 4c 49 54 45 5f 43 41 4e 54 4f  h, [SQLITE_CANTO
e110: 50 45 4e 5d 20 73 68 6f 75 6c 64 20 62 65 20 72  PEN] should be r
e120: 65 74 75 72 6e 65 64 2e 20 53 69 6e 63 65 20 74  eturned. Since t
e130: 68 69 73 20 69 73 0a 2a 2a 20 68 61 6e 64 6c 65  his is.** handle
e140: 64 20 61 73 20 61 20 66 61 74 61 6c 20 65 72 72  d as a fatal err
e150: 6f 72 20 62 79 20 53 51 4c 69 74 65 2c 20 76 66  or by SQLite, vf
e160: 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  s implementation
e170: 73 20 73 68 6f 75 6c 64 20 65 6e 64 65 61 76 6f  s should endeavo
e180: 72 0a 2a 2a 20 74 6f 20 70 72 65 76 65 6e 74 20  r.** to prevent 
e190: 74 68 69 73 20 62 79 20 73 65 74 74 69 6e 67 20  this by setting 
e1a0: 6d 78 50 61 74 68 6e 61 6d 65 20 74 6f 20 61 20  mxPathname to a 
e1b0: 73 75 66 66 69 63 69 65 6e 74 6c 79 20 6c 61 72  sufficiently lar
e1c0: 67 65 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20  ge value..**.** 
e1d0: 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 28  The xRandomness(
e1e0: 29 2c 20 78 53 6c 65 65 70 28 29 2c 20 78 43 75  ), xSleep(), xCu
e1f0: 72 72 65 6e 74 54 69 6d 65 28 29 2c 20 61 6e 64  rrentTime(), and
e200: 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e 74   xCurrentTimeInt
e210: 36 34 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63  64().** interfac
e220: 65 73 20 61 72 65 20 6e 6f 74 20 73 74 72 69 63  es are not stric
e230: 74 6c 79 20 61 20 70 61 72 74 20 6f 66 20 74 68  tly a part of th
e240: 65 20 66 69 6c 65 73 79 73 74 65 6d 2c 20 62 75  e filesystem, bu
e250: 74 20 74 68 65 79 20 61 72 65 0a 2a 2a 20 69 6e  t they are.** in
e260: 63 6c 75 64 65 64 20 69 6e 20 74 68 65 20 56 46  cluded in the VF
e270: 53 20 73 74 72 75 63 74 75 72 65 20 66 6f 72 20  S structure for 
e280: 63 6f 6d 70 6c 65 74 65 6e 65 73 73 2e 0a 2a 2a  completeness..**
e290: 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73   The xRandomness
e2a0: 28 29 20 66 75 6e 63 74 69 6f 6e 20 61 74 74 65  () function atte
e2b0: 6d 70 74 73 20 74 6f 20 72 65 74 75 72 6e 20 6e  mpts to return n
e2c0: 42 79 74 65 73 20 62 79 74 65 73 0a 2a 2a 20 6f  Bytes bytes.** o
e2d0: 66 20 67 6f 6f 64 2d 71 75 61 6c 69 74 79 20 72  f good-quality r
e2e0: 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 7a  andomness into z
e2f0: 4f 75 74 2e 20 20 54 68 65 20 72 65 74 75 72 6e  Out.  The return
e300: 20 76 61 6c 75 65 20 69 73 0a 2a 2a 20 74 68 65   value is.** the
e310: 20 61 63 74 75 61 6c 20 6e 75 6d 62 65 72 20 6f   actual number o
e320: 66 20 62 79 74 65 73 20 6f 66 20 72 61 6e 64 6f  f bytes of rando
e330: 6d 6e 65 73 73 20 6f 62 74 61 69 6e 65 64 2e 0a  mness obtained..
e340: 2a 2a 20 54 68 65 20 78 53 6c 65 65 70 28 29 20  ** The xSleep() 
e350: 6d 65 74 68 6f 64 20 63 61 75 73 65 73 20 74 68  method causes th
e360: 65 20 63 61 6c 6c 69 6e 67 20 74 68 72 65 61 64  e calling thread
e370: 20 74 6f 20 73 6c 65 65 70 20 66 6f 72 20 61 74   to sleep for at
e380: 0a 2a 2a 20 6c 65 61 73 74 20 74 68 65 20 6e 75  .** least the nu
e390: 6d 62 65 72 20 6f 66 20 6d 69 63 72 6f 73 65 63  mber of microsec
e3a0: 6f 6e 64 73 20 67 69 76 65 6e 2e 20 20 5e 54 68  onds given.  ^Th
e3b0: 65 20 78 43 75 72 72 65 6e 74 54 69 6d 65 28 29  e xCurrentTime()
e3c0: 0a 2a 2a 20 6d 65 74 68 6f 64 20 72 65 74 75 72  .** method retur
e3d0: 6e 73 20 61 20 4a 75 6c 69 61 6e 20 44 61 79 20  ns a Julian Day 
e3e0: 4e 75 6d 62 65 72 20 66 6f 72 20 74 68 65 20 63  Number for the c
e3f0: 75 72 72 65 6e 74 20 64 61 74 65 20 61 6e 64 20  urrent date and 
e400: 74 69 6d 65 20 61 73 0a 2a 2a 20 61 20 66 6c 6f  time as.** a flo
e410: 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75  ating point valu
e420: 65 2e 0a 2a 2a 20 5e 54 68 65 20 78 43 75 72 72  e..** ^The xCurr
e430: 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 20 6d  entTimeInt64() m
e440: 65 74 68 6f 64 20 72 65 74 75 72 6e 73 2c 20 61  ethod returns, a
e450: 73 20 61 6e 20 69 6e 74 65 67 65 72 2c 20 74 68  s an integer, th
e460: 65 20 4a 75 6c 69 61 6e 0a 2a 2a 20 44 61 79 20  e Julian.** Day 
e470: 4e 75 6d 62 65 72 20 6d 75 6c 74 69 70 6c 69 65  Number multiplie
e480: 64 20 62 79 20 38 36 34 30 30 30 30 30 20 28 74  d by 86400000 (t
e490: 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 6c  he number of mil
e4a0: 6c 69 73 65 63 6f 6e 64 73 20 69 6e 20 0a 2a 2a  liseconds in .**
e4b0: 20 61 20 32 34 2d 68 6f 75 72 20 64 61 79 29 2e   a 24-hour day).
e4c0: 20 20 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69    .** ^SQLite wi
e4d0: 6c 6c 20 75 73 65 20 74 68 65 20 78 43 75 72 72  ll use the xCurr
e4e0: 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 20 6d  entTimeInt64() m
e4f0: 65 74 68 6f 64 20 74 6f 20 67 65 74 20 74 68 65  ethod to get the
e500: 20 63 75 72 72 65 6e 74 0a 2a 2a 20 64 61 74 65   current.** date
e510: 20 61 6e 64 20 74 69 6d 65 20 69 66 20 74 68 61   and time if tha
e520: 74 20 6d 65 74 68 6f 64 20 69 73 20 61 76 61 69  t method is avai
e530: 6c 61 62 6c 65 20 28 69 66 20 69 56 65 72 73 69  lable (if iVersi
e540: 6f 6e 20 69 73 20 32 20 6f 72 20 0a 2a 2a 20 67  on is 2 or .** g
e550: 72 65 61 74 65 72 20 61 6e 64 20 74 68 65 20 66  reater and the f
e560: 75 6e 63 74 69 6f 6e 20 70 6f 69 6e 74 65 72 20  unction pointer 
e570: 69 73 20 6e 6f 74 20 4e 55 4c 4c 29 20 61 6e 64  is not NULL) and
e580: 20 77 69 6c 6c 20 66 61 6c 6c 20 62 61 63 6b 0a   will fall back.
e590: 2a 2a 20 74 6f 20 78 43 75 72 72 65 6e 74 54 69  ** to xCurrentTi
e5a0: 6d 65 28 29 20 69 66 20 78 43 75 72 72 65 6e 74  me() if xCurrent
e5b0: 54 69 6d 65 49 6e 74 36 34 28 29 20 69 73 20 75  TimeInt64() is u
e5c0: 6e 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 0a 2a  navailable..**.*
e5d0: 2a 20 5e 54 68 65 20 78 53 65 74 53 79 73 74 65  * ^The xSetSyste
e5e0: 6d 43 61 6c 6c 28 29 2c 20 78 47 65 74 53 79 73  mCall(), xGetSys
e5f0: 74 65 6d 43 61 6c 6c 28 29 2c 20 61 6e 64 20 78  temCall(), and x
e600: 4e 65 73 74 53 79 73 74 65 6d 43 61 6c 6c 28 29  NestSystemCall()
e610: 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 61   interfaces.** a
e620: 72 65 20 6e 6f 74 20 75 73 65 64 20 62 79 20 74  re not used by t
e630: 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 2e 20  he SQLite core. 
e640: 20 54 68 65 73 65 20 6f 70 74 69 6f 6e 61 6c 20   These optional 
e650: 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 70  interfaces are p
e660: 72 6f 76 69 64 65 64 0a 2a 2a 20 62 79 20 73 6f  rovided.** by so
e670: 6d 65 20 56 46 53 65 73 20 74 6f 20 66 61 63 69  me VFSes to faci
e680: 6c 69 74 61 74 65 20 74 65 73 74 69 6e 67 20 6f  litate testing o
e690: 66 20 74 68 65 20 56 46 53 20 63 6f 64 65 2e 20  f the VFS code. 
e6a0: 42 79 20 6f 76 65 72 72 69 64 69 6e 67 20 0a 2a  By overriding .*
e6b0: 2a 20 73 79 73 74 65 6d 20 63 61 6c 6c 73 20 77  * system calls w
e6c0: 69 74 68 20 66 75 6e 63 74 69 6f 6e 73 20 75 6e  ith functions un
e6d0: 64 65 72 20 69 74 73 20 63 6f 6e 74 72 6f 6c 2c  der its control,
e6e0: 20 61 20 74 65 73 74 20 70 72 6f 67 72 61 6d 20   a test program 
e6f0: 63 61 6e 0a 2a 2a 20 73 69 6d 75 6c 61 74 65 20  can.** simulate 
e700: 66 61 75 6c 74 73 20 61 6e 64 20 65 72 72 6f 72  faults and error
e710: 20 63 6f 6e 64 69 74 69 6f 6e 73 20 74 68 61 74   conditions that
e720: 20 77 6f 75 6c 64 20 6f 74 68 65 72 77 69 73 65   would otherwise
e730: 20 62 65 20 64 69 66 66 69 63 75 6c 74 0a 2a 2a   be difficult.**
e740: 20 6f 72 20 69 6d 70 6f 73 73 69 62 6c 65 20 74   or impossible t
e750: 6f 20 69 6e 64 75 63 65 2e 20 20 54 68 65 20 73  o induce.  The s
e760: 65 74 20 6f 66 20 73 79 73 74 65 6d 20 63 61 6c  et of system cal
e770: 6c 73 20 74 68 61 74 20 63 61 6e 20 62 65 20 6f  ls that can be o
e780: 76 65 72 72 69 64 64 65 6e 0a 2a 2a 20 76 61 72  verridden.** var
e790: 69 65 73 20 66 72 6f 6d 20 6f 6e 65 20 56 46 53  ies from one VFS
e7a0: 20 74 6f 20 61 6e 6f 74 68 65 72 2c 20 61 6e 64   to another, and
e7b0: 20 66 72 6f 6d 20 6f 6e 65 20 76 65 72 73 69 6f   from one versio
e7c0: 6e 20 6f 66 20 74 68 65 20 73 61 6d 65 20 56 46  n of the same VF
e7d0: 53 20 74 6f 20 74 68 65 0a 2a 2a 20 6e 65 78 74  S to the.** next
e7e0: 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20  .  Applications 
e7f0: 74 68 61 74 20 75 73 65 20 74 68 65 73 65 20 69  that use these i
e800: 6e 74 65 72 66 61 63 65 73 20 6d 75 73 74 20 62  nterfaces must b
e810: 65 20 70 72 65 70 61 72 65 64 20 66 6f 72 20 61  e prepared for a
e820: 6e 79 0a 2a 2a 20 6f 72 20 61 6c 6c 20 6f 66 20  ny.** or all of 
e830: 74 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73  these interfaces
e840: 20 74 6f 20 62 65 20 4e 55 4c 4c 20 6f 72 20 66   to be NULL or f
e850: 6f 72 20 74 68 65 69 72 20 62 65 68 61 76 69 6f  or their behavio
e860: 72 20 74 6f 20 63 68 61 6e 67 65 0a 2a 2a 20 66  r to change.** f
e870: 72 6f 6d 20 6f 6e 65 20 72 65 6c 65 61 73 65 20  rom one release 
e880: 74 6f 20 74 68 65 20 6e 65 78 74 2e 20 20 41 70  to the next.  Ap
e890: 70 6c 69 63 61 74 69 6f 6e 73 20 6d 75 73 74 20  plications must 
e8a0: 6e 6f 74 20 61 74 74 65 6d 70 74 20 74 6f 20 61  not attempt to a
e8b0: 63 63 65 73 73 0a 2a 2a 20 61 6e 79 20 6f 66 20  ccess.** any of 
e8c0: 74 68 65 73 65 20 6d 65 74 68 6f 64 73 20 69 66  these methods if
e8d0: 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20 6f 66   the iVersion of
e8e0: 20 74 68 65 20 56 46 53 20 69 73 20 6c 65 73 73   the VFS is less
e8f0: 20 74 68 61 6e 20 33 2e 0a 2a 2f 0a 74 79 70 65   than 3..*/.type
e900: 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
e910: 65 33 5f 76 66 73 20 73 71 6c 69 74 65 33 5f 76  e3_vfs sqlite3_v
e920: 66 73 3b 0a 74 79 70 65 64 65 66 20 76 6f 69 64  fs;.typedef void
e930: 20 28 2a 73 71 6c 69 74 65 33 5f 73 79 73 63 61   (*sqlite3_sysca
e940: 6c 6c 5f 70 74 72 29 28 76 6f 69 64 29 3b 0a 73  ll_ptr)(void);.s
e950: 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76 66  truct sqlite3_vf
e960: 73 20 7b 0a 20 20 69 6e 74 20 69 56 65 72 73 69  s {.  int iVersi
e970: 6f 6e 3b 20 20 20 20 20 20 20 20 20 20 20 20 2f  on;            /
e980: 2a 20 53 74 72 75 63 74 75 72 65 20 76 65 72 73  * Structure vers
e990: 69 6f 6e 20 6e 75 6d 62 65 72 20 28 63 75 72 72  ion number (curr
e9a0: 65 6e 74 6c 79 20 33 29 20 2a 2f 0a 20 20 69 6e  ently 3) */.  in
e9b0: 74 20 73 7a 4f 73 46 69 6c 65 3b 20 20 20 20 20  t szOsFile;     
e9c0: 20 20 20 20 20 20 20 2f 2a 20 53 69 7a 65 20 6f         /* Size o
e9d0: 66 20 73 75 62 63 6c 61 73 73 65 64 20 73 71 6c  f subclassed sql
e9e0: 69 74 65 33 5f 66 69 6c 65 20 2a 2f 0a 20 20 69  ite3_file */.  i
e9f0: 6e 74 20 6d 78 50 61 74 68 6e 61 6d 65 3b 20 20  nt mxPathname;  
ea00: 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d          /* Maxim
ea10: 75 6d 20 66 69 6c 65 20 70 61 74 68 6e 61 6d 65  um file pathname
ea20: 20 6c 65 6e 67 74 68 20 2a 2f 0a 20 20 73 71 6c   length */.  sql
ea30: 69 74 65 33 5f 76 66 73 20 2a 70 4e 65 78 74 3b  ite3_vfs *pNext;
ea40: 20 20 20 20 20 20 2f 2a 20 4e 65 78 74 20 72 65        /* Next re
ea50: 67 69 73 74 65 72 65 64 20 56 46 53 20 2a 2f 0a  gistered VFS */.
ea60: 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e    const char *zN
ea70: 61 6d 65 3b 20 20 20 20 20 20 20 2f 2a 20 4e 61  ame;       /* Na
ea80: 6d 65 20 6f 66 20 74 68 69 73 20 76 69 72 74 75  me of this virtu
ea90: 61 6c 20 66 69 6c 65 20 73 79 73 74 65 6d 20 2a  al file system *
eaa0: 2f 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 44 61  /.  void *pAppDa
eab0: 74 61 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20  ta;          /* 
eac0: 50 6f 69 6e 74 65 72 20 74 6f 20 61 70 70 6c 69  Pointer to appli
ead0: 63 61 74 69 6f 6e 2d 73 70 65 63 69 66 69 63 20  cation-specific 
eae0: 64 61 74 61 20 2a 2f 0a 20 20 69 6e 74 20 28 2a  data */.  int (*
eaf0: 78 4f 70 65 6e 29 28 73 71 6c 69 74 65 33 5f 76  xOpen)(sqlite3_v
eb00: 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  fs*, const char 
eb10: 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69 74 65 33 5f  *zName, sqlite3_
eb20: 66 69 6c 65 2a 2c 0a 20 20 20 20 20 20 20 20 20  file*,.         
eb30: 20 20 20 20 20 20 69 6e 74 20 66 6c 61 67 73 2c        int flags,
eb40: 20 69 6e 74 20 2a 70 4f 75 74 46 6c 61 67 73 29   int *pOutFlags)
eb50: 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65 6c 65 74  ;.  int (*xDelet
eb60: 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  e)(sqlite3_vfs*,
eb70: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61   const char *zNa
eb80: 6d 65 2c 20 69 6e 74 20 73 79 6e 63 44 69 72 29  me, int syncDir)
eb90: 3b 0a 20 20 69 6e 74 20 28 2a 78 41 63 63 65 73  ;.  int (*xAcces
eba0: 73 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  s)(sqlite3_vfs*,
ebb0: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61   const char *zNa
ebc0: 6d 65 2c 20 69 6e 74 20 66 6c 61 67 73 2c 20 69  me, int flags, i
ebd0: 6e 74 20 2a 70 52 65 73 4f 75 74 29 3b 0a 20 20  nt *pResOut);.  
ebe0: 69 6e 74 20 28 2a 78 46 75 6c 6c 50 61 74 68 6e  int (*xFullPathn
ebf0: 61 6d 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73  ame)(sqlite3_vfs
ec00: 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  *, const char *z
ec10: 4e 61 6d 65 2c 20 69 6e 74 20 6e 4f 75 74 2c 20  Name, int nOut, 
ec20: 63 68 61 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 76  char *zOut);.  v
ec30: 6f 69 64 20 2a 28 2a 78 44 6c 4f 70 65 6e 29 28  oid *(*xDlOpen)(
ec40: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f  sqlite3_vfs*, co
ec50: 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c 65 6e  nst char *zFilen
ec60: 61 6d 65 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78  ame);.  void (*x
ec70: 44 6c 45 72 72 6f 72 29 28 73 71 6c 69 74 65 33  DlError)(sqlite3
ec80: 5f 76 66 73 2a 2c 20 69 6e 74 20 6e 42 79 74 65  _vfs*, int nByte
ec90: 2c 20 63 68 61 72 20 2a 7a 45 72 72 4d 73 67 29  , char *zErrMsg)
eca0: 3b 0a 20 20 76 6f 69 64 20 28 2a 28 2a 78 44 6c  ;.  void (*(*xDl
ecb0: 53 79 6d 29 28 73 71 6c 69 74 65 33 5f 76 66 73  Sym)(sqlite3_vfs
ecc0: 2a 2c 76 6f 69 64 2a 2c 20 63 6f 6e 73 74 20 63  *,void*, const c
ecd0: 68 61 72 20 2a 7a 53 79 6d 62 6f 6c 29 29 28 76  har *zSymbol))(v
ece0: 6f 69 64 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78  oid);.  void (*x
ecf0: 44 6c 43 6c 6f 73 65 29 28 73 71 6c 69 74 65 33  DlClose)(sqlite3
ed00: 5f 76 66 73 2a 2c 20 76 6f 69 64 2a 29 3b 0a 20  _vfs*, void*);. 
ed10: 20 69 6e 74 20 28 2a 78 52 61 6e 64 6f 6d 6e 65   int (*xRandomne
ed20: 73 73 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  ss)(sqlite3_vfs*
ed30: 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 63 68 61  , int nByte, cha
ed40: 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 69 6e 74 20  r *zOut);.  int 
ed50: 28 2a 78 53 6c 65 65 70 29 28 73 71 6c 69 74 65  (*xSleep)(sqlite
ed60: 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6d 69 63 72  3_vfs*, int micr
ed70: 6f 73 65 63 6f 6e 64 73 29 3b 0a 20 20 69 6e 74  oseconds);.  int
ed80: 20 28 2a 78 43 75 72 72 65 6e 74 54 69 6d 65 29   (*xCurrentTime)
ed90: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 64  (sqlite3_vfs*, d
eda0: 6f 75 62 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28  ouble*);.  int (
edb0: 2a 78 47 65 74 4c 61 73 74 45 72 72 6f 72 29 28  *xGetLastError)(
edc0: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e  sqlite3_vfs*, in
edd0: 74 2c 20 63 68 61 72 20 2a 29 3b 0a 20 20 2f 2a  t, char *);.  /*
ede0: 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 68 6f 64  .  ** The method
edf0: 73 20 61 62 6f 76 65 20 61 72 65 20 69 6e 20 76  s above are in v
ee00: 65 72 73 69 6f 6e 20 31 20 6f 66 20 74 68 65 20  ersion 1 of the 
ee10: 73 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a 65 63  sqlite_vfs objec
ee20: 74 0a 20 20 2a 2a 20 64 65 66 69 6e 69 74 69 6f  t.  ** definitio
ee30: 6e 2e 20 20 54 68 6f 73 65 20 74 68 61 74 20 66  n.  Those that f
ee40: 6f 6c 6c 6f 77 20 61 72 65 20 61 64 64 65 64 20  ollow are added 
ee50: 69 6e 20 76 65 72 73 69 6f 6e 20 32 20 6f 72 20  in version 2 or 
ee60: 6c 61 74 65 72 0a 20 20 2a 2f 0a 20 20 69 6e 74  later.  */.  int
ee70: 20 28 2a 78 43 75 72 72 65 6e 74 54 69 6d 65 49   (*xCurrentTimeI
ee80: 6e 74 36 34 29 28 73 71 6c 69 74 65 33 5f 76 66  nt64)(sqlite3_vf
ee90: 73 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  s*, sqlite3_int6
eea0: 34 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54  4*);.  /*.  ** T
eeb0: 68 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65  he methods above
eec0: 20 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e 73   are in versions
eed0: 20 31 20 61 6e 64 20 32 20 6f 66 20 74 68 65 20   1 and 2 of the 
eee0: 73 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a 65 63  sqlite_vfs objec
eef0: 74 2e 0a 20 20 2a 2a 20 54 68 6f 73 65 20 62 65  t..  ** Those be
ef00: 6c 6f 77 20 61 72 65 20 66 6f 72 20 76 65 72 73  low are for vers
ef10: 69 6f 6e 20 33 20 61 6e 64 20 67 72 65 61 74 65  ion 3 and greate
ef20: 72 2e 0a 20 20 2a 2f 0a 20 20 69 6e 74 20 28 2a  r..  */.  int (*
ef30: 78 53 65 74 53 79 73 74 65 6d 43 61 6c 6c 29 28  xSetSystemCall)(
ef40: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f  sqlite3_vfs*, co
ef50: 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c  nst char *zName,
ef60: 20 73 71 6c 69 74 65 33 5f 73 79 73 63 61 6c 6c   sqlite3_syscall
ef70: 5f 70 74 72 29 3b 0a 20 20 73 71 6c 69 74 65 33  _ptr);.  sqlite3
ef80: 5f 73 79 73 63 61 6c 6c 5f 70 74 72 20 28 2a 78  _syscall_ptr (*x
ef90: 47 65 74 53 79 73 74 65 6d 43 61 6c 6c 29 28 73  GetSystemCall)(s
efa0: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e  qlite3_vfs*, con
efb0: 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b  st char *zName);
efc0: 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 28  .  const char *(
efd0: 2a 78 4e 65 78 74 53 79 73 74 65 6d 43 61 6c 6c  *xNextSystemCall
efe0: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
eff0: 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
f000: 65 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54 68  e);.  /*.  ** Th
f010: 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 20  e methods above 
f020: 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e 73 20  are in versions 
f030: 31 20 74 68 72 6f 75 67 68 20 33 20 6f 66 20 74  1 through 3 of t
f040: 68 65 20 73 71 6c 69 74 65 5f 76 66 73 20 6f 62  he sqlite_vfs ob
f050: 6a 65 63 74 2e 0a 20 20 2a 2a 20 4e 65 77 20 66  ject..  ** New f
f060: 69 65 6c 64 73 20 6d 61 79 20 62 65 20 61 70 70  ields may be app
f070: 65 6e 64 65 64 20 69 6e 20 66 75 74 75 72 65 20  ended in future 
f080: 76 65 72 73 69 6f 6e 73 2e 20 20 54 68 65 20 69  versions.  The i
f090: 56 65 72 73 69 6f 6e 0a 20 20 2a 2a 20 76 61 6c  Version.  ** val
f0a0: 75 65 20 77 69 6c 6c 20 69 6e 63 72 65 6d 65 6e  ue will incremen
f0b0: 74 20 77 68 65 6e 65 76 65 72 20 74 68 69 73 20  t whenever this 
f0c0: 68 61 70 70 65 6e 73 2e 20 0a 20 20 2a 2f 0a 7d  happens. .  */.}
f0d0: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
f0e0: 46 3a 20 46 6c 61 67 73 20 66 6f 72 20 74 68 65  F: Flags for the
f0f0: 20 78 41 63 63 65 73 73 20 56 46 53 20 6d 65 74   xAccess VFS met
f100: 68 6f 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  hod.**.** These 
f110: 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74  integer constant
f120: 73 20 63 61 6e 20 62 65 20 75 73 65 64 20 61 73  s can be used as
f130: 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d   the third param
f140: 65 74 65 72 20 74 6f 0a 2a 2a 20 74 68 65 20 78  eter to.** the x
f150: 41 63 63 65 73 73 20 6d 65 74 68 6f 64 20 6f 66  Access method of
f160: 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 76 66 73   an [sqlite3_vfs
f170: 5d 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 79 20  ] object.  They 
f180: 64 65 74 65 72 6d 69 6e 65 0a 2a 2a 20 77 68 61  determine.** wha
f190: 74 20 6b 69 6e 64 20 6f 66 20 70 65 72 6d 69 73  t kind of permis
f1a0: 73 69 6f 6e 73 20 74 68 65 20 78 41 63 63 65 73  sions the xAcces
f1b0: 73 20 6d 65 74 68 6f 64 20 69 73 20 6c 6f 6f 6b  s method is look
f1c0: 69 6e 67 20 66 6f 72 2e 0a 2a 2a 20 57 69 74 68  ing for..** With
f1d0: 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45   SQLITE_ACCESS_E
f1e0: 58 49 53 54 53 2c 20 74 68 65 20 78 41 63 63 65  XISTS, the xAcce
f1f0: 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 73 69 6d  ss method.** sim
f200: 70 6c 79 20 63 68 65 63 6b 73 20 77 68 65 74 68  ply checks wheth
f210: 65 72 20 74 68 65 20 66 69 6c 65 20 65 78 69 73  er the file exis
f220: 74 73 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49  ts..** With SQLI
f230: 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52  TE_ACCESS_READWR
f240: 49 54 45 2c 20 74 68 65 20 78 41 63 63 65 73 73  ITE, the xAccess
f250: 20 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65 63 6b   method.** check
f260: 73 20 77 68 65 74 68 65 72 20 74 68 65 20 6e 61  s whether the na
f270: 6d 65 64 20 64 69 72 65 63 74 6f 72 79 20 69 73  med directory is
f280: 20 62 6f 74 68 20 72 65 61 64 61 62 6c 65 20 61   both readable a
f290: 6e 64 20 77 72 69 74 61 62 6c 65 0a 2a 2a 20 28  nd writable.** (
f2a0: 69 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20  in other words, 
f2b0: 69 66 20 66 69 6c 65 73 20 63 61 6e 20 62 65 20  if files can be 
f2c0: 61 64 64 65 64 2c 20 72 65 6d 6f 76 65 64 2c 20  added, removed, 
f2d0: 61 6e 64 20 72 65 6e 61 6d 65 64 20 77 69 74 68  and renamed with
f2e0: 69 6e 0a 2a 2a 20 74 68 65 20 64 69 72 65 63 74  in.** the direct
f2f0: 6f 72 79 29 2e 0a 2a 2a 20 54 68 65 20 53 51 4c  ory)..** The SQL
f300: 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57  ITE_ACCESS_READW
f310: 52 49 54 45 20 63 6f 6e 73 74 61 6e 74 20 69 73  RITE constant is
f320: 20 63 75 72 72 65 6e 74 6c 79 20 75 73 65 64 20   currently used 
f330: 6f 6e 6c 79 20 62 79 20 74 68 65 0a 2a 2a 20 5b  only by the.** [
f340: 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 63  temp_store_direc
f350: 74 6f 72 79 20 70 72 61 67 6d 61 5d 2c 20 74 68  tory pragma], th
f360: 6f 75 67 68 20 74 68 69 73 20 63 6f 75 6c 64 20  ough this could 
f370: 63 68 61 6e 67 65 20 69 6e 20 61 20 66 75 74 75  change in a futu
f380: 72 65 0a 2a 2a 20 72 65 6c 65 61 73 65 20 6f 66  re.** release of
f390: 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 57 69 74 68   SQLite..** With
f3a0: 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52   SQLITE_ACCESS_R
f3b0: 45 41 44 2c 20 74 68 65 20 78 41 63 63 65 73 73  EAD, the xAccess
f3c0: 20 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65 63 6b   method.** check
f3d0: 73 20 77 68 65 74 68 65 72 20 74 68 65 20 66 69  s whether the fi
f3e0: 6c 65 20 69 73 20 72 65 61 64 61 62 6c 65 2e 20  le is readable. 
f3f0: 20 54 68 65 20 53 51 4c 49 54 45 5f 41 43 43 45   The SQLITE_ACCE
f400: 53 53 5f 52 45 41 44 20 63 6f 6e 73 74 61 6e 74  SS_READ constant
f410: 20 69 73 0a 2a 2a 20 63 75 72 72 65 6e 74 6c 79   is.** currently
f420: 20 75 6e 75 73 65 64 2c 20 74 68 6f 75 67 68 20   unused, though 
f430: 69 74 20 6d 69 67 68 74 20 62 65 20 75 73 65 64  it might be used
f440: 20 69 6e 20 61 20 66 75 74 75 72 65 20 72 65 6c   in a future rel
f450: 65 61 73 65 20 6f 66 0a 2a 2a 20 53 51 4c 69 74  ease of.** SQLit
f460: 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  e..*/.#define SQ
f470: 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49 53  LITE_ACCESS_EXIS
f480: 54 53 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20  TS    0.#define 
f490: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45  SQLITE_ACCESS_RE
f4a0: 41 44 57 52 49 54 45 20 31 20 20 20 2f 2a 20 55  ADWRITE 1   /* U
f4b0: 73 65 64 20 62 79 20 50 52 41 47 4d 41 20 74 65  sed by PRAGMA te
f4c0: 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 63 74 6f  mp_store_directo
f4d0: 72 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ry */.#define SQ
f4e0: 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44  LITE_ACCESS_READ
f4f0: 20 20 20 20 20 20 32 20 20 20 2f 2a 20 55 6e 75        2   /* Unu
f500: 73 65 64 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41  sed */../*.** CA
f510: 50 49 33 52 45 46 3a 20 46 6c 61 67 73 20 66 6f  PI3REF: Flags fo
f520: 72 20 74 68 65 20 78 53 68 6d 4c 6f 63 6b 20 56  r the xShmLock V
f530: 46 53 20 6d 65 74 68 6f 64 0a 2a 2a 0a 2a 2a 20  FS method.**.** 
f540: 54 68 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f  These integer co
f550: 6e 73 74 61 6e 74 73 20 64 65 66 69 6e 65 20 74  nstants define t
f560: 68 65 20 76 61 72 69 6f 75 73 20 6c 6f 63 6b 69  he various locki
f570: 6e 67 20 6f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a  ng operations.**
f580: 20 61 6c 6c 6f 77 65 64 20 62 79 20 74 68 65 20   allowed by the 
f590: 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20  xShmLock method 
f5a0: 6f 66 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  of [sqlite3_io_m
f5b0: 65 74 68 6f 64 73 5d 2e 20 20 54 68 65 0a 2a 2a  ethods].  The.**
f5c0: 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 72 65 20 74   following are t
f5d0: 68 65 20 6f 6e 6c 79 20 6c 65 67 61 6c 20 63 6f  he only legal co
f5e0: 6d 62 69 6e 61 74 69 6f 6e 73 20 6f 66 20 66 6c  mbinations of fl
f5f0: 61 67 73 20 74 6f 20 74 68 65 0a 2a 2a 20 78 53  ags to the.** xS
f600: 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 3a 0a 2a  hmLock method:.*
f610: 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ul>.** <li
f620: 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f  >  SQLITE_SHM_LO
f630: 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f  CK | SQLITE_SHM_
f640: 53 48 41 52 45 44 0a 2a 2a 20 3c 6c 69 3e 20 20  SHARED.** <li>  
f650: 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20  SQLITE_SHM_LOCK 
f660: 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45 58 43  | SQLITE_SHM_EXC
f670: 4c 55 53 49 56 45 0a 2a 2a 20 3c 6c 69 3e 20 20  LUSIVE.** <li>  
f680: 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43  SQLITE_SHM_UNLOC
f690: 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53  K | SQLITE_SHM_S
f6a0: 48 41 52 45 44 0a 2a 2a 20 3c 6c 69 3e 20 20 53  HARED.** <li>  S
f6b0: 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b  QLITE_SHM_UNLOCK
f6c0: 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45 58   | SQLITE_SHM_EX
f6d0: 43 4c 55 53 49 56 45 0a 2a 2a 20 3c 2f 75 6c 3e  CLUSIVE.** </ul>
f6e0: 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 75 6e 6c 6f  .**.** When unlo
f6f0: 63 6b 69 6e 67 2c 20 74 68 65 20 73 61 6d 65 20  cking, the same 
f700: 53 48 41 52 45 44 20 6f 72 20 45 58 43 4c 55 53  SHARED or EXCLUS
f710: 49 56 45 20 66 6c 61 67 20 6d 75 73 74 20 62 65  IVE flag must be
f720: 20 73 75 70 70 6c 69 65 64 20 61 73 0a 2a 2a 20   supplied as.** 
f730: 77 61 73 20 67 69 76 65 6e 20 6f 6e 20 74 68 65  was given on the
f740: 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 6c   corresponding l
f750: 6f 63 6b 2e 20 20 0a 2a 2a 0a 2a 2a 20 54 68 65  ock.  .**.** The
f760: 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64   xShmLock method
f770: 20 63 61 6e 20 74 72 61 6e 73 69 74 69 6f 6e 20   can transition 
f780: 62 65 74 77 65 65 6e 20 75 6e 6c 6f 63 6b 65 64  between unlocked
f790: 20 61 6e 64 20 53 48 41 52 45 44 20 6f 72 0a 2a   and SHARED or.*
f7a0: 2a 20 62 65 74 77 65 65 6e 20 75 6e 6c 6f 63 6b  * between unlock
f7b0: 65 64 20 61 6e 64 20 45 58 43 4c 55 53 49 56 45  ed and EXCLUSIVE
f7c0: 2e 20 20 49 74 20 63 61 6e 6e 6f 74 20 74 72 61  .  It cannot tra
f7d0: 6e 73 69 74 69 6f 6e 20 62 65 74 77 65 65 6e 20  nsition between 
f7e0: 53 48 41 52 45 44 0a 2a 2a 20 61 6e 64 20 45 58  SHARED.** and EX
f7f0: 43 4c 55 53 49 56 45 2e 0a 2a 2f 0a 23 64 65 66  CLUSIVE..*/.#def
f800: 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 55  ine SQLITE_SHM_U
f810: 4e 4c 4f 43 4b 20 20 20 20 20 20 20 31 0a 23 64  NLOCK       1.#d
f820: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d  efine SQLITE_SHM
f830: 5f 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 32 0a  _LOCK         2.
f840: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
f850: 48 4d 5f 53 48 41 52 45 44 20 20 20 20 20 20 20  HM_SHARED       
f860: 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  4.#define SQLITE
f870: 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 45 20 20  _SHM_EXCLUSIVE  
f880: 20 20 38 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33    8../*.** CAPI3
f890: 52 45 46 3a 20 4d 61 78 69 6d 75 6d 20 78 53 68  REF: Maximum xSh
f8a0: 6d 4c 6f 63 6b 20 69 6e 64 65 78 0a 2a 2a 0a 2a  mLock index.**.*
f8b0: 2a 20 54 68 65 20 78 53 68 6d 4c 6f 63 6b 20 6d  * The xShmLock m
f8c0: 65 74 68 6f 64 20 6f 6e 20 5b 73 71 6c 69 74 65  ethod on [sqlite
f8d0: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6d 61  3_io_methods] ma
f8e0: 79 20 75 73 65 20 76 61 6c 75 65 73 0a 2a 2a 20  y use values.** 
f8f0: 62 65 74 77 65 65 6e 20 30 20 61 6e 64 20 74 68  between 0 and th
f900: 69 73 20 75 70 70 65 72 20 62 6f 75 6e 64 20 61  is upper bound a
f910: 73 20 69 74 73 20 22 6f 66 66 73 65 74 22 20 61  s its "offset" a
f920: 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 54 68 65 20  rgument..** The 
f930: 53 51 4c 69 74 65 20 63 6f 72 65 20 77 69 6c 6c  SQLite core will
f940: 20 6e 65 76 65 72 20 61 74 74 65 6d 70 74 20 74   never attempt t
f950: 6f 20 61 63 71 75 69 72 65 20 6f 72 20 72 65 6c  o acquire or rel
f960: 65 61 73 65 20 61 0a 2a 2a 20 6c 6f 63 6b 20 6f  ease a.** lock o
f970: 75 74 73 69 64 65 20 6f 66 20 74 68 69 73 20 72  utside of this r
f980: 61 6e 67 65 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  ange.*/.#define 
f990: 53 51 4c 49 54 45 5f 53 48 4d 5f 4e 4c 4f 43 4b  SQLITE_SHM_NLOCK
f9a0: 20 20 20 20 20 20 20 20 38 0a 0a 0a 2f 2a 0a 2a          8.../*.*
f9b0: 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e 69 74  * CAPI3REF: Init
f9c0: 69 61 6c 69 7a 65 20 54 68 65 20 53 51 4c 69 74  ialize The SQLit
f9d0: 65 20 4c 69 62 72 61 72 79 0a 2a 2a 0a 2a 2a 20  e Library.**.** 
f9e0: 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69  ^The sqlite3_ini
f9f0: 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e  tialize() routin
fa00: 65 20 69 6e 69 74 69 61 6c 69 7a 65 73 20 74 68  e initializes th
fa10: 65 0a 2a 2a 20 53 51 4c 69 74 65 20 6c 69 62 72  e.** SQLite libr
fa20: 61 72 79 2e 20 20 5e 54 68 65 20 73 71 6c 69 74  ary.  ^The sqlit
fa30: 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 72 6f  e3_shutdown() ro
fa40: 75 74 69 6e 65 0a 2a 2a 20 64 65 61 6c 6c 6f 63  utine.** dealloc
fa50: 61 74 65 73 20 61 6e 79 20 72 65 73 6f 75 72 63  ates any resourc
fa60: 65 73 20 74 68 61 74 20 77 65 72 65 20 61 6c 6c  es that were all
fa70: 6f 63 61 74 65 64 20 62 79 20 73 71 6c 69 74 65  ocated by sqlite
fa80: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 2e 0a  3_initialize()..
fa90: 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
faa0: 73 20 61 72 65 20 64 65 73 69 67 6e 65 64 20 74  s are designed t
fab0: 6f 20 61 69 64 20 69 6e 20 70 72 6f 63 65 73 73  o aid in process
fac0: 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20   initialization 
fad0: 61 6e 64 0a 2a 2a 20 73 68 75 74 64 6f 77 6e 20  and.** shutdown 
fae0: 6f 6e 20 65 6d 62 65 64 64 65 64 20 73 79 73 74  on embedded syst
faf0: 65 6d 73 2e 20 20 57 6f 72 6b 73 74 61 74 69 6f  ems.  Workstatio
fb00: 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 75  n applications u
fb10: 73 69 6e 67 0a 2a 2a 20 53 51 4c 69 74 65 20 6e  sing.** SQLite n
fb20: 6f 72 6d 61 6c 6c 79 20 64 6f 20 6e 6f 74 20 6e  ormally do not n
fb30: 65 65 64 20 74 6f 20 69 6e 76 6f 6b 65 20 65 69  eed to invoke ei
fb40: 74 68 65 72 20 6f 66 20 74 68 65 73 65 20 72 6f  ther of these ro
fb50: 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 41 20  utines..**.** A 
fb60: 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f  call to sqlite3_
fb70: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20  initialize() is 
fb80: 61 6e 20 22 65 66 66 65 63 74 69 76 65 22 20 63  an "effective" c
fb90: 61 6c 6c 20 69 66 20 69 74 20 69 73 0a 2a 2a 20  all if it is.** 
fba0: 74 68 65 20 66 69 72 73 74 20 74 69 6d 65 20 73  the first time s
fbb0: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
fbc0: 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 20 64  e() is invoked d
fbd0: 75 72 69 6e 67 20 74 68 65 20 6c 69 66 65 74 69  uring the lifeti
fbe0: 6d 65 20 6f 66 0a 2a 2a 20 74 68 65 20 70 72 6f  me of.** the pro
fbf0: 63 65 73 73 2c 20 6f 72 20 69 66 20 69 74 20 69  cess, or if it i
fc00: 73 20 74 68 65 20 66 69 72 73 74 20 74 69 6d 65  s the first time
fc10: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
fc20: 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64  ize() is invoked
fc30: 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20  .** following a 
fc40: 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f  call to sqlite3_
fc50: 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 5e 28 4f  shutdown().  ^(O
fc60: 6e 6c 79 20 61 6e 20 65 66 66 65 63 74 69 76 65  nly an effective
fc70: 20 63 61 6c 6c 0a 2a 2a 20 6f 66 20 73 71 6c 69   call.** of sqli
fc80: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
fc90: 20 64 6f 65 73 20 61 6e 79 20 69 6e 69 74 69 61   does any initia
fca0: 6c 69 7a 61 74 69 6f 6e 2e 20 20 41 6c 6c 20 6f  lization.  All o
fcb0: 74 68 65 72 20 63 61 6c 6c 73 0a 2a 2a 20 61 72  ther calls.** ar
fcc0: 65 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70  e harmless no-op
fcd0: 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c  s.)^.**.** A cal
fce0: 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75  l to sqlite3_shu
fcf0: 74 64 6f 77 6e 28 29 20 69 73 20 61 6e 20 22 65  tdown() is an "e
fd00: 66 66 65 63 74 69 76 65 22 20 63 61 6c 6c 20 69  ffective" call i
fd10: 66 20 69 74 20 69 73 20 74 68 65 20 66 69 72 73  f it is the firs
fd20: 74 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 73 71 6c  t.** call to sql
fd30: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20  ite3_shutdown() 
fd40: 73 69 6e 63 65 20 74 68 65 20 6c 61 73 74 20 73  since the last s
fd50: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
fd60: 65 28 29 2e 20 20 5e 28 4f 6e 6c 79 0a 2a 2a 20  e().  ^(Only.** 
fd70: 61 6e 20 65 66 66 65 63 74 69 76 65 20 63 61 6c  an effective cal
fd80: 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75  l to sqlite3_shu
fd90: 74 64 6f 77 6e 28 29 20 64 6f 65 73 20 61 6e 79  tdown() does any
fda0: 20 64 65 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f   deinitializatio
fdb0: 6e 2e 0a 2a 2a 20 41 6c 6c 20 6f 74 68 65 72 20  n..** All other 
fdc0: 76 61 6c 69 64 20 63 61 6c 6c 73 20 74 6f 20 73  valid calls to s
fdd0: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
fde0: 29 20 61 72 65 20 68 61 72 6d 6c 65 73 73 20 6e  ) are harmless n
fdf0: 6f 2d 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54  o-ops.)^.**.** T
fe00: 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  he sqlite3_initi
fe10: 61 6c 69 7a 65 28 29 20 69 6e 74 65 72 66 61 63  alize() interfac
fe20: 65 20 69 73 20 74 68 72 65 61 64 73 61 66 65 2c  e is threadsafe,
fe30: 20 62 75 74 20 73 71 6c 69 74 65 33 5f 73 68 75   but sqlite3_shu
fe40: 74 64 6f 77 6e 28 29 0a 2a 2a 20 69 73 20 6e 6f  tdown().** is no
fe50: 74 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f  t.  The sqlite3_
fe60: 73 68 75 74 64 6f 77 6e 28 29 20 69 6e 74 65 72  shutdown() inter
fe70: 66 61 63 65 20 6d 75 73 74 20 6f 6e 6c 79 20 62  face must only b
fe80: 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 61 0a  e called from a.
fe90: 2a 2a 20 73 69 6e 67 6c 65 20 74 68 72 65 61 64  ** single thread
fea0: 2e 20 20 41 6c 6c 20 6f 70 65 6e 20 5b 64 61 74  .  All open [dat
feb0: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
fec0: 73 5d 20 6d 75 73 74 20 62 65 20 63 6c 6f 73 65  s] must be close
fed0: 64 20 61 6e 64 20 61 6c 6c 0a 2a 2a 20 6f 74 68  d and all.** oth
fee0: 65 72 20 53 51 4c 69 74 65 20 72 65 73 6f 75 72  er SQLite resour
fef0: 63 65 73 20 6d 75 73 74 20 62 65 20 64 65 61 6c  ces must be deal
ff00: 6c 6f 63 61 74 65 64 20 70 72 69 6f 72 20 74 6f  located prior to
ff10: 20 69 6e 76 6f 6b 69 6e 67 0a 2a 2a 20 73 71 6c   invoking.** sql
ff20: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e  ite3_shutdown().
ff30: 0a 2a 2a 0a 2a 2a 20 41 6d 6f 6e 67 20 6f 74 68  .**.** Among oth
ff40: 65 72 20 74 68 69 6e 67 73 2c 20 5e 73 71 6c 69  er things, ^sqli
ff50: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
ff60: 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 0a 2a 2a 20   will invoke.** 
ff70: 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28  sqlite3_os_init(
ff80: 29 2e 20 20 53 69 6d 69 6c 61 72 6c 79 2c 20 5e  ).  Similarly, ^
ff90: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
ffa0: 28 29 0a 2a 2a 20 77 69 6c 6c 20 69 6e 76 6f 6b  ().** will invok
ffb0: 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64  e sqlite3_os_end
ffc0: 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ()..**.** ^The s
ffd0: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
ffe0: 65 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75  e() routine retu
fff0: 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20  rns [SQLITE_OK] 
10000 6f 6e 20 73 75 63 63 65 73 73 2e 0a 2a 2a 20 5e  on success..** ^
10010 49 66 20 66 6f 72 20 73 6f 6d 65 20 72 65 61 73  If for some reas
10020 6f 6e 2c 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  on, sqlite3_init
10030 69 61 6c 69 7a 65 28 29 20 69 73 20 75 6e 61 62  ialize() is unab
10040 6c 65 20 74 6f 20 69 6e 69 74 69 61 6c 69 7a 65  le to initialize
10050 0a 2a 2a 20 74 68 65 20 6c 69 62 72 61 72 79 20  .** the library 
10060 28 70 65 72 68 61 70 73 20 69 74 20 69 73 20 75  (perhaps it is u
10070 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74  nable to allocat
10080 65 20 61 20 6e 65 65 64 65 64 20 72 65 73 6f 75  e a needed resou
10090 72 63 65 20 73 75 63 68 0a 2a 2a 20 61 73 20 61  rce such.** as a
100a0 20 6d 75 74 65 78 29 20 69 74 20 72 65 74 75 72   mutex) it retur
100b0 6e 73 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64  ns an [error cod
100c0 65 5d 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53  e] other than [S
100d0 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a  QLITE_OK]..**.**
100e0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e   ^The sqlite3_in
100f0 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74 69  itialize() routi
10100 6e 65 20 69 73 20 63 61 6c 6c 65 64 20 69 6e 74  ne is called int
10110 65 72 6e 61 6c 6c 79 20 62 79 20 6d 61 6e 79 20  ernally by many 
10120 6f 74 68 65 72 0a 2a 2a 20 53 51 4c 69 74 65 20  other.** SQLite 
10130 69 6e 74 65 72 66 61 63 65 73 20 73 6f 20 74 68  interfaces so th
10140 61 74 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f  at an applicatio
10150 6e 20 75 73 75 61 6c 6c 79 20 64 6f 65 73 20 6e  n usually does n
10160 6f 74 20 6e 65 65 64 20 74 6f 0a 2a 2a 20 69 6e  ot need to.** in
10170 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 69 6e 69  voke sqlite3_ini
10180 74 69 61 6c 69 7a 65 28 29 20 64 69 72 65 63 74  tialize() direct
10190 6c 79 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c 65  ly.  For example
101a0 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  , [sqlite3_open(
101b0 29 5d 0a 2a 2a 20 63 61 6c 6c 73 20 73 71 6c 69  )].** calls sqli
101c0 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
101d0 20 73 6f 20 74 68 65 20 53 51 4c 69 74 65 20 6c   so the SQLite l
101e0 69 62 72 61 72 79 20 77 69 6c 6c 20 62 65 20 61  ibrary will be a
101f0 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20  utomatically.** 
10200 69 6e 69 74 69 61 6c 69 7a 65 64 20 77 68 65 6e  initialized when
10210 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29   [sqlite3_open()
10220 5d 20 69 73 20 63 61 6c 6c 65 64 20 69 66 20 69  ] is called if i
10230 74 20 68 61 73 20 6e 6f 74 20 62 65 20 69 6e 69  t has not be ini
10240 74 69 61 6c 69 7a 65 64 0a 2a 2a 20 61 6c 72 65  tialized.** alre
10250 61 64 79 2e 20 20 5e 48 6f 77 65 76 65 72 2c 20  ady.  ^However, 
10260 69 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  if SQLite is com
10270 70 69 6c 65 64 20 77 69 74 68 20 74 68 65 20 5b  piled with the [
10280 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f  SQLITE_OMIT_AUTO
10290 49 4e 49 54 5d 0a 2a 2a 20 63 6f 6d 70 69 6c 65  INIT].** compile
102a0 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2c 20 74 68  -time option, th
102b0 65 6e 20 74 68 65 20 61 75 74 6f 6d 61 74 69 63  en the automatic
102c0 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65   calls to sqlite
102d0 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 0a 2a  3_initialize().*
102e0 2a 20 61 72 65 20 6f 6d 69 74 74 65 64 20 61 6e  * are omitted an
102f0 64 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  d the applicatio
10300 6e 20 6d 75 73 74 20 63 61 6c 6c 20 73 71 6c 69  n must call sqli
10310 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
10320 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 70 72 69   directly.** pri
10330 6f 72 20 74 6f 20 75 73 69 6e 67 20 61 6e 79 20  or to using any 
10340 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74  other SQLite int
10350 65 72 66 61 63 65 2e 20 20 46 6f 72 20 6d 61 78  erface.  For max
10360 69 6d 75 6d 20 70 6f 72 74 61 62 69 6c 69 74 79  imum portability
10370 2c 0a 2a 2a 20 69 74 20 69 73 20 72 65 63 6f 6d  ,.** it is recom
10380 6d 65 6e 64 65 64 20 74 68 61 74 20 61 70 70 6c  mended that appl
10390 69 63 61 74 69 6f 6e 73 20 61 6c 77 61 79 73 20  ications always 
103a0 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 69  invoke sqlite3_i
103b0 6e 69 74 69 61 6c 69 7a 65 28 29 0a 2a 2a 20 64  nitialize().** d
103c0 69 72 65 63 74 6c 79 20 70 72 69 6f 72 20 74 6f  irectly prior to
103d0 20 75 73 69 6e 67 20 61 6e 79 20 6f 74 68 65 72   using any other
103e0 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63   SQLite interfac
103f0 65 2e 20 20 46 75 74 75 72 65 20 72 65 6c 65 61  e.  Future relea
10400 73 65 73 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65  ses.** of SQLite
10410 20 6d 61 79 20 72 65 71 75 69 72 65 20 74 68 69   may require thi
10420 73 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72  s.  In other wor
10430 64 73 2c 20 74 68 65 20 62 65 68 61 76 69 6f 72  ds, the behavior
10440 20 65 78 68 69 62 69 74 65 64 0a 2a 2a 20 77 68   exhibited.** wh
10450 65 6e 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  en SQLite is com
10460 70 69 6c 65 64 20 77 69 74 68 20 5b 53 51 4c 49  piled with [SQLI
10470 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e 49 54  TE_OMIT_AUTOINIT
10480 5d 20 6d 69 67 68 74 20 62 65 63 6f 6d 65 20 74  ] might become t
10490 68 65 0a 2a 2a 20 64 65 66 61 75 6c 74 20 62 65  he.** default be
104a0 68 61 76 69 6f 72 20 69 6e 20 73 6f 6d 65 20 66  havior in some f
104b0 75 74 75 72 65 20 72 65 6c 65 61 73 65 20 6f 66  uture release of
104c0 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54   SQLite..**.** T
104d0 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  he sqlite3_os_in
104e0 69 74 28 29 20 72 6f 75 74 69 6e 65 20 64 6f 65  it() routine doe
104f0 73 20 6f 70 65 72 61 74 69 6e 67 2d 73 79 73 74  s operating-syst
10500 65 6d 20 73 70 65 63 69 66 69 63 0a 2a 2a 20 69  em specific.** i
10510 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 6f 66  nitialization of
10520 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72   the SQLite libr
10530 61 72 79 2e 20 20 54 68 65 20 73 71 6c 69 74 65  ary.  The sqlite
10540 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 72 6f  3_os_end().** ro
10550 75 74 69 6e 65 20 75 6e 64 6f 65 73 20 74 68 65  utine undoes the
10560 20 65 66 66 65 63 74 20 6f 66 20 73 71 6c 69 74   effect of sqlit
10570 65 33 5f 6f 73 5f 69 6e 69 74 28 29 2e 20 20 54  e3_os_init().  T
10580 79 70 69 63 61 6c 20 74 61 73 6b 73 0a 2a 2a 20  ypical tasks.** 
10590 70 65 72 66 6f 72 6d 65 64 20 62 79 20 74 68 65  performed by the
105a0 73 65 20 72 6f 75 74 69 6e 65 73 20 69 6e 63 6c  se routines incl
105b0 75 64 65 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6f  ude allocation o
105c0 72 20 64 65 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a  r deallocation.*
105d0 2a 20 6f 66 20 73 74 61 74 69 63 20 72 65 73 6f  * of static reso
105e0 75 72 63 65 73 2c 20 69 6e 69 74 69 61 6c 69 7a  urces, initializ
105f0 61 74 69 6f 6e 20 6f 66 20 67 6c 6f 62 61 6c 20  ation of global 
10600 76 61 72 69 61 62 6c 65 73 2c 0a 2a 2a 20 73 65  variables,.** se
10610 74 74 69 6e 67 20 75 70 20 61 20 64 65 66 61 75  tting up a defau
10620 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d  lt [sqlite3_vfs]
10630 20 6d 6f 64 75 6c 65 2c 20 6f 72 20 73 65 74 74   module, or sett
10640 69 6e 67 20 75 70 0a 2a 2a 20 61 20 64 65 66 61  ing up.** a defa
10650 75 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ult configuratio
10660 6e 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  n using [sqlite3
10670 5f 63 6f 6e 66 69 67 28 29 5d 2e 0a 2a 2a 0a 2a  _config()]..**.*
10680 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * The applicatio
10690 6e 20 73 68 6f 75 6c 64 20 6e 65 76 65 72 20 69  n should never i
106a0 6e 76 6f 6b 65 20 65 69 74 68 65 72 20 73 71 6c  nvoke either sql
106b0 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 0a 2a  ite3_os_init().*
106c0 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f  * or sqlite3_os_
106d0 65 6e 64 28 29 20 64 69 72 65 63 74 6c 79 2e 20  end() directly. 
106e0 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   The application
106f0 20 73 68 6f 75 6c 64 20 6f 6e 6c 79 20 69 6e 76   should only inv
10700 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 69  oke.** sqlite3_i
10710 6e 69 74 69 61 6c 69 7a 65 28 29 20 61 6e 64 20  nitialize() and 
10720 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
10730 28 29 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33  ().  The sqlite3
10740 5f 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a 20 69 6e  _os_init().** in
10750 74 65 72 66 61 63 65 20 69 73 20 63 61 6c 6c 65  terface is calle
10760 64 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  d automatically 
10770 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  by sqlite3_initi
10780 61 6c 69 7a 65 28 29 20 61 6e 64 0a 2a 2a 20 73  alize() and.** s
10790 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 20  qlite3_os_end() 
107a0 69 73 20 63 61 6c 6c 65 64 20 62 79 20 73 71 6c  is called by sql
107b0 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e  ite3_shutdown().
107c0 20 20 41 70 70 72 6f 70 72 69 61 74 65 0a 2a 2a    Appropriate.**
107d0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
107e0 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f   for sqlite3_os_
107f0 69 6e 69 74 28 29 20 61 6e 64 20 73 71 6c 69 74  init() and sqlit
10800 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 61  e3_os_end().** a
10810 72 65 20 62 75 69 6c 74 20 69 6e 74 6f 20 53 51  re built into SQ
10820 4c 69 74 65 20 77 68 65 6e 20 69 74 20 69 73 20  Lite when it is 
10830 63 6f 6d 70 69 6c 65 64 20 66 6f 72 20 55 6e 69  compiled for Uni
10840 78 2c 20 57 69 6e 64 6f 77 73 2c 20 6f 72 20 4f  x, Windows, or O
10850 53 2f 32 2e 0a 2a 2a 20 57 68 65 6e 20 5b 63 75  S/2..** When [cu
10860 73 74 6f 6d 20 62 75 69 6c 64 73 20 7c 20 62 75  stom builds | bu
10870 69 6c 74 20 66 6f 72 20 6f 74 68 65 72 20 70 6c  ilt for other pl
10880 61 74 66 6f 72 6d 73 5d 0a 2a 2a 20 28 75 73 69  atforms].** (usi
10890 6e 67 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f  ng the [SQLITE_O
108a0 53 5f 4f 54 48 45 52 3d 31 5d 20 63 6f 6d 70 69  S_OTHER=1] compi
108b0 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74 69 6f  le-time.** optio
108c0 6e 29 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  n) the applicati
108d0 6f 6e 20 6d 75 73 74 20 73 75 70 70 6c 79 20 61  on must supply a
108e0 20 73 75 69 74 61 62 6c 65 20 69 6d 70 6c 65 6d   suitable implem
108f0 65 6e 74 61 74 69 6f 6e 20 66 6f 72 0a 2a 2a 20  entation for.** 
10900 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28  sqlite3_os_init(
10910 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 73  ) and sqlite3_os
10920 5f 65 6e 64 28 29 2e 20 20 41 6e 20 61 70 70 6c  _end().  An appl
10930 69 63 61 74 69 6f 6e 2d 73 75 70 70 6c 69 65 64  ication-supplied
10940 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  .** implementati
10950 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 73  on of sqlite3_os
10960 5f 69 6e 69 74 28 29 20 6f 72 20 73 71 6c 69 74  _init() or sqlit
10970 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 6d  e3_os_end().** m
10980 75 73 74 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  ust return [SQLI
10990 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73  TE_OK] on succes
109a0 73 20 61 6e 64 20 73 6f 6d 65 20 6f 74 68 65 72  s and some other
109b0 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 75 70   [error code] up
109c0 6f 6e 0a 2a 2a 20 66 61 69 6c 75 72 65 2e 0a 2a  on.** failure..*
109d0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 69 6e  /.int sqlite3_in
109e0 69 74 69 61 6c 69 7a 65 28 76 6f 69 64 29 3b 0a  itialize(void);.
109f0 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 68 75 74  int sqlite3_shut
10a00 64 6f 77 6e 28 76 6f 69 64 29 3b 0a 69 6e 74 20  down(void);.int 
10a10 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28  sqlite3_os_init(
10a20 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74  void);.int sqlit
10a30 65 33 5f 6f 73 5f 65 6e 64 28 76 6f 69 64 29 3b  e3_os_end(void);
10a40 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
10a50 3a 20 43 6f 6e 66 69 67 75 72 69 6e 67 20 54 68  : Configuring Th
10a60 65 20 53 51 4c 69 74 65 20 4c 69 62 72 61 72 79  e SQLite Library
10a70 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
10a80 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65  e3_config() inte
10a90 72 66 61 63 65 20 69 73 20 75 73 65 64 20 74 6f  rface is used to
10aa0 20 6d 61 6b 65 20 67 6c 6f 62 61 6c 20 63 6f 6e   make global con
10ab0 66 69 67 75 72 61 74 69 6f 6e 0a 2a 2a 20 63 68  figuration.** ch
10ac0 61 6e 67 65 73 20 74 6f 20 53 51 4c 69 74 65 20  anges to SQLite 
10ad0 69 6e 20 6f 72 64 65 72 20 74 6f 20 74 75 6e 65  in order to tune
10ae0 20 53 51 4c 69 74 65 20 74 6f 20 74 68 65 20 73   SQLite to the s
10af0 70 65 63 69 66 69 63 20 6e 65 65 64 73 20 6f 66  pecific needs of
10b00 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74  .** the applicat
10b10 69 6f 6e 2e 20 20 54 68 65 20 64 65 66 61 75 6c  ion.  The defaul
10b20 74 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  t configuration 
10b30 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66  is recommended f
10b40 6f 72 20 6d 6f 73 74 0a 2a 2a 20 61 70 70 6c 69  or most.** appli
10b50 63 61 74 69 6f 6e 73 20 61 6e 64 20 73 6f 20 74  cations and so t
10b60 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 75  his routine is u
10b70 73 75 61 6c 6c 79 20 6e 6f 74 20 6e 65 63 65 73  sually not neces
10b80 73 61 72 79 2e 20 20 49 74 20 69 73 0a 2a 2a 20  sary.  It is.** 
10b90 70 72 6f 76 69 64 65 64 20 74 6f 20 73 75 70 70  provided to supp
10ba0 6f 72 74 20 72 61 72 65 20 61 70 70 6c 69 63 61  ort rare applica
10bb0 74 69 6f 6e 73 20 77 69 74 68 20 75 6e 75 73 75  tions with unusu
10bc0 61 6c 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20  al needs..**.** 
10bd0 3c 62 3e 54 68 65 20 73 71 6c 69 74 65 33 5f 63  <b>The sqlite3_c
10be0 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61 63  onfig() interfac
10bf0 65 20 69 73 20 6e 6f 74 20 74 68 72 65 61 64 73  e is not threads
10c00 61 66 65 2e 20 54 68 65 20 61 70 70 6c 69 63 61  afe. The applica
10c10 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 65 6e 73  tion.** must ens
10c20 75 72 65 20 74 68 61 74 20 6e 6f 20 6f 74 68 65  ure that no othe
10c30 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61  r SQLite interfa
10c40 63 65 73 20 61 72 65 20 69 6e 76 6f 6b 65 64 20  ces are invoked 
10c50 62 79 20 6f 74 68 65 72 0a 2a 2a 20 74 68 72 65  by other.** thre
10c60 61 64 73 20 77 68 69 6c 65 20 73 71 6c 69 74 65  ads while sqlite
10c70 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 72 75  3_config() is ru
10c80 6e 6e 69 6e 67 2e 3c 2f 62 3e 0a 2a 2a 0a 2a 2a  nning.</b>.**.**
10c90 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e   The sqlite3_con
10ca0 66 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 0a  fig() interface.
10cb0 2a 2a 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 69  ** may only be i
10cc0 6e 76 6f 6b 65 64 20 70 72 69 6f 72 20 74 6f 20  nvoked prior to 
10cd0 6c 69 62 72 61 72 79 20 69 6e 69 74 69 61 6c 69  library initiali
10ce0 7a 61 74 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20  zation using.** 
10cf0 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c  [sqlite3_initial
10d00 69 7a 65 28 29 5d 20 6f 72 20 61 66 74 65 72 20  ize()] or after 
10d10 73 68 75 74 64 6f 77 6e 20 62 79 20 5b 73 71 6c  shutdown by [sql
10d20 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d  ite3_shutdown()]
10d30 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33  ..** ^If sqlite3
10d40 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 63 61 6c  _config() is cal
10d50 6c 65 64 20 61 66 74 65 72 20 5b 73 71 6c 69 74  led after [sqlit
10d60 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d  e3_initialize()]
10d70 20 61 6e 64 20 62 65 66 6f 72 65 0a 2a 2a 20 5b   and before.** [
10d80 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
10d90 28 29 5d 20 74 68 65 6e 20 69 74 20 77 69 6c 6c  ()] then it will
10da0 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4d   return SQLITE_M
10db0 49 53 55 53 45 2e 0a 2a 2a 20 4e 6f 74 65 2c 20  ISUSE..** Note, 
10dc0 68 6f 77 65 76 65 72 2c 20 74 68 61 74 20 5e 73  however, that ^s
10dd0 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20  qlite3_config() 
10de0 63 61 6e 20 62 65 20 63 61 6c 6c 65 64 20 61 73  can be called as
10df0 20 70 61 72 74 20 6f 66 20 74 68 65 0a 2a 2a 20   part of the.** 
10e00 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f  implementation o
10e10 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  f an application
10e20 2d 64 65 66 69 6e 65 64 20 5b 73 71 6c 69 74 65  -defined [sqlite
10e30 33 5f 6f 73 5f 69 6e 69 74 28 29 5d 2e 0a 2a 2a  3_os_init()]..**
10e40 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72  .** The first ar
10e50 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65  gument to sqlite
10e60 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 61 6e  3_config() is an
10e70 20 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 63 6f 6e   integer.** [con
10e80 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
10e90 6e 5d 20 74 68 61 74 20 64 65 74 65 72 6d 69 6e  n] that determin
10ea0 65 73 0a 2a 2a 20 77 68 61 74 20 70 72 6f 70 65  es.** what prope
10eb0 72 74 79 20 6f 66 20 53 51 4c 69 74 65 20 69 73  rty of SQLite is
10ec0 20 74 6f 20 62 65 20 63 6f 6e 66 69 67 75 72 65   to be configure
10ed0 64 2e 20 20 53 75 62 73 65 71 75 65 6e 74 20 61  d.  Subsequent a
10ee0 72 67 75 6d 65 6e 74 73 0a 2a 2a 20 76 61 72 79  rguments.** vary
10ef0 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68   depending on th
10f00 65 20 5b 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  e [configuration
10f10 20 6f 70 74 69 6f 6e 5d 0a 2a 2a 20 69 6e 20 74   option].** in t
10f20 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
10f30 74 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 65 6e 20 61  t..**.** ^When a
10f40 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
10f50 70 74 69 6f 6e 20 69 73 20 73 65 74 2c 20 73 71  ption is set, sq
10f60 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 72  lite3_config() r
10f70 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f  eturns [SQLITE_O
10f80 4b 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6f  K]..** ^If the o
10f90 70 74 69 6f 6e 20 69 73 20 75 6e 6b 6e 6f 77 6e  ption is unknown
10fa0 20 6f 72 20 53 51 4c 69 74 65 20 69 73 20 75 6e   or SQLite is un
10fb0 61 62 6c 65 20 74 6f 20 73 65 74 20 74 68 65 20  able to set the 
10fc0 6f 70 74 69 6f 6e 0a 2a 2a 20 74 68 65 6e 20 74  option.** then t
10fd0 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75  his routine retu
10fe0 72 6e 73 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 5b  rns a non-zero [
10ff0 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2f 0a  error code]..*/.
11000 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66  int sqlite3_conf
11010 69 67 28 69 6e 74 2c 20 2e 2e 2e 29 3b 0a 0a 2f  ig(int, ...);../
11020 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
11030 6f 6e 66 69 67 75 72 65 20 64 61 74 61 62 61 73  onfigure databas
11040 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a  e connections.**
11050 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
11060 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
11070 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 20 69  e3_db_config() i
11080 6e 74 65 72 66 61 63 65 20 69 73 20 75 73 65 64  nterface is used
11090 20 74 6f 20 6d 61 6b 65 20 63 6f 6e 66 69 67 75   to make configu
110a0 72 61 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65  ration.** change
110b0 73 20 74 6f 20 61 20 5b 64 61 74 61 62 61 73 65  s to a [database
110c0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 54   connection].  T
110d0 68 65 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  he interface is 
110e0 73 69 6d 69 6c 61 72 20 74 6f 0a 2a 2a 20 5b 73  similar to.** [s
110f0 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
11100 20 65 78 63 65 70 74 20 74 68 61 74 20 74 68 65   except that the
11110 20 63 68 61 6e 67 65 73 20 61 70 70 6c 79 20 74   changes apply t
11120 6f 20 61 20 73 69 6e 67 6c 65 0a 2a 2a 20 5b 64  o a single.** [d
11130 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
11140 6f 6e 5d 20 28 73 70 65 63 69 66 69 65 64 20 69  on] (specified i
11150 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  n the first argu
11160 6d 65 6e 74 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ment)..**.** The
11170 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
11180 20 74 6f 20 73 71 6c 69 74 65 33 5f 64 62 5f 63   to sqlite3_db_c
11190 6f 6e 66 69 67 28 44 2c 56 2c 2e 2e 2e 29 20 20  onfig(D,V,...)  
111a0 69 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54  is the.** [SQLIT
111b0 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41  E_DBCONFIG_LOOKA
111c0 53 49 44 45 20 7c 20 63 6f 6e 66 69 67 75 72 61  SIDE | configura
111d0 74 69 6f 6e 20 76 65 72 62 5d 20 2d 20 61 6e 20  tion verb] - an 
111e0 69 6e 74 65 67 65 72 20 63 6f 64 65 20 0a 2a 2a  integer code .**
111f0 20 74 68 61 74 20 69 6e 64 69 63 61 74 65 73 20   that indicates 
11200 77 68 61 74 20 61 73 70 65 63 74 20 6f 66 20 74  what aspect of t
11210 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
11220 6e 65 63 74 69 6f 6e 5d 20 69 73 20 62 65 69 6e  nection] is bein
11230 67 20 63 6f 6e 66 69 67 75 72 65 64 2e 0a 2a 2a  g configured..**
11240 20 53 75 62 73 65 71 75 65 6e 74 20 61 72 67 75   Subsequent argu
11250 6d 65 6e 74 73 20 76 61 72 79 20 64 65 70 65 6e  ments vary depen
11260 64 69 6e 67 20 6f 6e 20 74 68 65 20 63 6f 6e 66  ding on the conf
11270 69 67 75 72 61 74 69 6f 6e 20 76 65 72 62 2e 0a  iguration verb..
11280 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 73 20 74 6f 20  **.** ^Calls to 
11290 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69  sqlite3_db_confi
112a0 67 28 29 20 72 65 74 75 72 6e 20 53 51 4c 49 54  g() return SQLIT
112b0 45 5f 4f 4b 20 69 66 20 61 6e 64 20 6f 6e 6c 79  E_OK if and only
112c0 20 69 66 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20   if.** the call 
112d0 69 73 20 63 6f 6e 73 69 64 65 72 65 64 20 73 75  is considered su
112e0 63 63 65 73 73 66 75 6c 2e 0a 2a 2f 0a 69 6e 74  ccessful..*/.int
112f0 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66   sqlite3_db_conf
11300 69 67 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74  ig(sqlite3*, int
11310 20 6f 70 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a   op, ...);../*.*
11320 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f  * CAPI3REF: Memo
11330 72 79 20 41 6c 6c 6f 63 61 74 69 6f 6e 20 52 6f  ry Allocation Ro
11340 75 74 69 6e 65 73 0a 2a 2a 0a 2a 2a 20 41 6e 20  utines.**.** An 
11350 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73  instance of this
11360 20 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20   object defines 
11370 74 68 65 20 69 6e 74 65 72 66 61 63 65 20 62 65  the interface be
11380 74 77 65 65 6e 20 53 51 4c 69 74 65 0a 2a 2a 20  tween SQLite.** 
11390 61 6e 64 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65  and low-level me
113a0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
113b0 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20  routines..**.** 
113c0 54 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20 75  This object is u
113d0 73 65 64 20 69 6e 20 6f 6e 6c 79 20 6f 6e 65 20  sed in only one 
113e0 70 6c 61 63 65 20 69 6e 20 74 68 65 20 53 51 4c  place in the SQL
113f0 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a  ite interface..*
11400 2a 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  * A pointer to a
11410 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  n instance of th
11420 69 73 20 6f 62 6a 65 63 74 20 69 73 20 74 68 65  is object is the
11430 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20   argument to.** 
11440 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
11450 29 5d 20 77 68 65 6e 20 74 68 65 20 63 6f 6e 66  )] when the conf
11460 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
11470 20 69 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43   is.** [SQLITE_C
11480 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 20 6f 72  ONFIG_MALLOC] or
11490 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
114a0 47 45 54 4d 41 4c 4c 4f 43 5d 2e 20 20 0a 2a 2a  GETMALLOC].  .**
114b0 20 42 79 20 63 72 65 61 74 69 6e 67 20 61 6e 20   By creating an 
114c0 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73  instance of this
114d0 20 6f 62 6a 65 63 74 0a 2a 2a 20 61 6e 64 20 70   object.** and p
114e0 61 73 73 69 6e 67 20 69 74 20 74 6f 20 5b 73 71  assing it to [sq
114f0 6c 69 74 65 33 5f 63 6f 6e 66 69 67 5d 28 5b 53  lite3_config]([S
11500 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c  QLITE_CONFIG_MAL
11510 4c 4f 43 5d 29 0a 2a 2a 20 64 75 72 69 6e 67 20  LOC]).** during 
11520 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 2c 20 61  configuration, a
11530 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 63 61  n application ca
11540 6e 20 73 70 65 63 69 66 79 20 61 6e 20 61 6c 74  n specify an alt
11550 65 72 6e 61 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f  ernative.** memo
11560 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75  ry allocation su
11570 62 73 79 73 74 65 6d 20 66 6f 72 20 53 51 4c 69  bsystem for SQLi
11580 74 65 20 74 6f 20 75 73 65 20 66 6f 72 20 61 6c  te to use for al
11590 6c 20 6f 66 20 69 74 73 0a 2a 2a 20 64 79 6e 61  l of its.** dyna
115a0 6d 69 63 20 6d 65 6d 6f 72 79 20 6e 65 65 64 73  mic memory needs
115b0 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61  ..**.** Note tha
115c0 74 20 53 51 4c 69 74 65 20 63 6f 6d 65 73 20 77  t SQLite comes w
115d0 69 74 68 20 73 65 76 65 72 61 6c 20 5b 62 75 69  ith several [bui
115e0 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c  lt-in memory all
115f0 6f 63 61 74 6f 72 73 5d 0a 2a 2a 20 74 68 61 74  ocators].** that
11600 20 61 72 65 20 70 65 72 66 65 63 74 6c 79 20 61   are perfectly a
11610 64 65 71 75 61 74 65 20 66 6f 72 20 74 68 65 20  dequate for the 
11620 6f 76 65 72 77 68 65 6c 6d 69 6e 67 20 6d 61 6a  overwhelming maj
11630 6f 72 69 74 79 20 6f 66 20 61 70 70 6c 69 63 61  ority of applica
11640 74 69 6f 6e 73 0a 2a 2a 20 61 6e 64 20 74 68 61  tions.** and tha
11650 74 20 74 68 69 73 20 6f 62 6a 65 63 74 20 69 73  t this object is
11660 20 6f 6e 6c 79 20 75 73 65 66 75 6c 20 74 6f 20   only useful to 
11670 61 20 74 69 6e 79 20 6d 69 6e 6f 72 69 74 79 20  a tiny minority 
11680 6f 66 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a  of applications.
11690 2a 2a 20 77 69 74 68 20 73 70 65 63 69 61 6c 69  ** with speciali
116a0 7a 65 64 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  zed memory alloc
116b0 61 74 69 6f 6e 20 72 65 71 75 69 72 65 6d 65 6e  ation requiremen
116c0 74 73 2e 20 20 54 68 69 73 20 6f 62 6a 65 63 74  ts.  This object
116d0 20 69 73 0a 2a 2a 20 61 6c 73 6f 20 75 73 65 64   is.** also used
116e0 20 64 75 72 69 6e 67 20 74 65 73 74 69 6e 67 20   during testing 
116f0 6f 66 20 53 51 4c 69 74 65 20 69 6e 20 6f 72 64  of SQLite in ord
11700 65 72 20 74 6f 20 73 70 65 63 69 66 79 20 61 6e  er to specify an
11710 20 61 6c 74 65 72 6e 61 74 69 76 65 0a 2a 2a 20   alternative.** 
11720 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72  memory allocator
11730 20 74 68 61 74 20 73 69 6d 75 6c 61 74 65 73 20   that simulates 
11740 6d 65 6d 6f 72 79 20 6f 75 74 2d 6f 66 2d 6d 65  memory out-of-me
11750 6d 6f 72 79 20 63 6f 6e 64 69 74 69 6f 6e 73 20  mory conditions 
11760 69 6e 0a 2a 2a 20 6f 72 64 65 72 20 74 6f 20 76  in.** order to v
11770 65 72 69 66 79 20 74 68 61 74 20 53 51 4c 69 74  erify that SQLit
11780 65 20 72 65 63 6f 76 65 72 73 20 67 72 61 63 65  e recovers grace
11790 66 75 6c 6c 79 20 66 72 6f 6d 20 73 75 63 68 0a  fully from such.
117a0 2a 2a 20 63 6f 6e 64 69 74 69 6f 6e 73 2e 0a 2a  ** conditions..*
117b0 2a 0a 2a 2a 20 54 68 65 20 78 4d 61 6c 6c 6f 63  *.** The xMalloc
117c0 2c 20 78 52 65 61 6c 6c 6f 63 2c 20 61 6e 64 20  , xRealloc, and 
117d0 78 46 72 65 65 20 6d 65 74 68 6f 64 73 20 6d 75  xFree methods mu
117e0 73 74 20 77 6f 72 6b 20 6c 69 6b 65 20 74 68 65  st work like the
117f0 0a 2a 2a 20 6d 61 6c 6c 6f 63 28 29 2c 20 72 65  .** malloc(), re
11800 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 65 65  alloc() and free
11810 28 29 20 66 75 6e 63 74 69 6f 6e 73 20 66 72 6f  () functions fro
11820 6d 20 74 68 65 20 73 74 61 6e 64 61 72 64 20 43  m the standard C
11830 20 6c 69 62 72 61 72 79 2e 0a 2a 2a 20 5e 53 51   library..** ^SQ
11840 4c 69 74 65 20 67 75 61 72 61 6e 74 65 65 73 20  Lite guarantees 
11850 74 68 61 74 20 74 68 65 20 73 65 63 6f 6e 64 20  that the second 
11860 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 78  argument to.** x
11870 52 65 61 6c 6c 6f 63 20 69 73 20 61 6c 77 61 79  Realloc is alway
11880 73 20 61 20 76 61 6c 75 65 20 72 65 74 75 72 6e  s a value return
11890 65 64 20 62 79 20 61 20 70 72 69 6f 72 20 63 61  ed by a prior ca
118a0 6c 6c 20 74 6f 20 78 52 6f 75 6e 64 75 70 2e 0a  ll to xRoundup..
118b0 2a 2a 0a 2a 2a 20 78 53 69 7a 65 20 73 68 6f 75  **.** xSize shou
118c0 6c 64 20 72 65 74 75 72 6e 20 74 68 65 20 61 6c  ld return the al
118d0 6c 6f 63 61 74 65 64 20 73 69 7a 65 20 6f 66 20  located size of 
118e0 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  a memory allocat
118f0 69 6f 6e 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c  ion.** previousl
11900 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  y obtained from 
11910 78 4d 61 6c 6c 6f 63 20 6f 72 20 78 52 65 61 6c  xMalloc or xReal
11920 6c 6f 63 2e 20 20 54 68 65 20 61 6c 6c 6f 63 61  loc.  The alloca
11930 74 65 64 20 73 69 7a 65 0a 2a 2a 20 69 73 20 61  ted size.** is a
11940 6c 77 61 79 73 20 61 74 20 6c 65 61 73 74 20 61  lways at least a
11950 73 20 62 69 67 20 61 73 20 74 68 65 20 72 65 71  s big as the req
11960 75 65 73 74 65 64 20 73 69 7a 65 20 62 75 74 20  uested size but 
11970 6d 61 79 20 62 65 20 6c 61 72 67 65 72 2e 0a 2a  may be larger..*
11980 2a 0a 2a 2a 20 54 68 65 20 78 52 6f 75 6e 64 75  *.** The xRoundu
11990 70 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73  p method returns
119a0 20 77 68 61 74 20 77 6f 75 6c 64 20 62 65 20 74   what would be t
119b0 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a  he allocated siz
119c0 65 20 6f 66 0a 2a 2a 20 61 20 6d 65 6d 6f 72 79  e of.** a memory
119d0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 67 69 76 65   allocation give
119e0 6e 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 72  n a particular r
119f0 65 71 75 65 73 74 65 64 20 73 69 7a 65 2e 20 20  equested size.  
11a00 4d 6f 73 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61  Most memory.** a
11a10 6c 6c 6f 63 61 74 6f 72 73 20 72 6f 75 6e 64 20  llocators round 
11a20 75 70 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  up memory alloca
11a30 74 69 6f 6e 73 20 61 74 20 6c 65 61 73 74 20 74  tions at least t
11a40 6f 20 74 68 65 20 6e 65 78 74 20 6d 75 6c 74 69  o the next multi
11a50 70 6c 65 0a 2a 2a 20 6f 66 20 38 2e 20 20 53 6f  ple.** of 8.  So
11a60 6d 65 20 61 6c 6c 6f 63 61 74 6f 72 73 20 72 6f  me allocators ro
11a70 75 6e 64 20 75 70 20 74 6f 20 61 20 6c 61 72 67  und up to a larg
11a80 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 72 20 74  er multiple or t
11a90 6f 20 61 20 70 6f 77 65 72 20 6f 66 20 32 2e 0a  o a power of 2..
11aa0 2a 2a 20 45 76 65 72 79 20 6d 65 6d 6f 72 79 20  ** Every memory 
11ab0 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 65 71 75 65  allocation reque
11ac0 73 74 20 63 6f 6d 69 6e 67 20 69 6e 20 74 68 72  st coming in thr
11ad0 6f 75 67 68 20 5b 73 71 6c 69 74 65 33 5f 6d 61  ough [sqlite3_ma
11ae0 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73  lloc()].** or [s
11af0 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
11b00 5d 20 66 69 72 73 74 20 63 61 6c 6c 73 20 78 52  ] first calls xR
11b10 6f 75 6e 64 75 70 2e 20 20 49 66 20 78 52 6f 75  oundup.  If xRou
11b20 6e 64 75 70 20 72 65 74 75 72 6e 73 20 30 2c 20  ndup returns 0, 
11b30 0a 2a 2a 20 74 68 61 74 20 63 61 75 73 65 73 20  .** that causes 
11b40 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e  the correspondin
11b50 67 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  g memory allocat
11b60 69 6f 6e 20 74 6f 20 66 61 69 6c 2e 0a 2a 2a 0a  ion to fail..**.
11b70 2a 2a 20 54 68 65 20 78 49 6e 69 74 20 6d 65 74  ** The xInit met
11b80 68 6f 64 20 69 6e 69 74 69 61 6c 69 7a 65 73 20  hod initializes 
11b90 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  the memory alloc
11ba0 61 74 6f 72 2e 20 20 46 6f 72 20 65 78 61 6d 70  ator.  For examp
11bb0 6c 65 2c 0a 2a 2a 20 69 74 20 6d 69 67 68 74 20  le,.** it might 
11bc0 61 6c 6c 6f 63 61 74 65 20 61 6e 79 20 72 65 71  allocate any req
11bd0 75 69 72 65 20 6d 75 74 65 78 65 73 20 6f 72 20  uire mutexes or 
11be0 69 6e 69 74 69 61 6c 69 7a 65 20 69 6e 74 65 72  initialize inter
11bf0 6e 61 6c 20 64 61 74 61 0a 2a 2a 20 73 74 72 75  nal data.** stru
11c00 63 74 75 72 65 73 2e 20 20 54 68 65 20 78 53 68  ctures.  The xSh
11c10 75 74 64 6f 77 6e 20 6d 65 74 68 6f 64 20 69 73  utdown method is
11c20 20 69 6e 76 6f 6b 65 64 20 28 69 6e 64 69 72 65   invoked (indire
11c30 63 74 6c 79 29 20 62 79 0a 2a 2a 20 5b 73 71 6c  ctly) by.** [sql
11c40 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d  ite3_shutdown()]
11c50 20 61 6e 64 20 73 68 6f 75 6c 64 20 64 65 61 6c   and should deal
11c60 6c 6f 63 61 74 65 20 61 6e 79 20 72 65 73 6f 75  locate any resou
11c70 72 63 65 73 20 61 63 71 75 69 72 65 64 0a 2a 2a  rces acquired.**
11c80 20 62 79 20 78 49 6e 69 74 2e 20 20 54 68 65 20   by xInit.  The 
11c90 70 41 70 70 44 61 74 61 20 70 6f 69 6e 74 65 72  pAppData pointer
11ca0 20 69 73 20 75 73 65 64 20 61 73 20 74 68 65 20   is used as the 
11cb0 6f 6e 6c 79 20 70 61 72 61 6d 65 74 65 72 20 74  only parameter t
11cc0 6f 0a 2a 2a 20 78 49 6e 69 74 20 61 6e 64 20 78  o.** xInit and x
11cd0 53 68 75 74 64 6f 77 6e 2e 0a 2a 2a 0a 2a 2a 20  Shutdown..**.** 
11ce0 53 51 4c 69 74 65 20 68 6f 6c 64 73 20 74 68 65  SQLite holds the
11cf0 20 5b 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53   [SQLITE_MUTEX_S
11d00 54 41 54 49 43 5f 4d 41 53 54 45 52 5d 20 6d 75  TATIC_MASTER] mu
11d10 74 65 78 20 77 68 65 6e 20 69 74 20 69 6e 76 6f  tex when it invo
11d20 6b 65 73 0a 2a 2a 20 74 68 65 20 78 49 6e 69 74  kes.** the xInit
11d30 20 6d 65 74 68 6f 64 2c 20 73 6f 20 74 68 65 20   method, so the 
11d40 78 49 6e 69 74 20 6d 65 74 68 6f 64 20 6e 65 65  xInit method nee
11d50 64 20 6e 6f 74 20 62 65 20 74 68 72 65 61 64 73  d not be threads
11d60 61 66 65 2e 20 20 54 68 65 0a 2a 2a 20 78 53 68  afe.  The.** xSh
11d70 75 74 64 6f 77 6e 20 6d 65 74 68 6f 64 20 69 73  utdown method is
11d80 20 6f 6e 6c 79 20 63 61 6c 6c 65 64 20 66 72 6f   only called fro
11d90 6d 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64  m [sqlite3_shutd
11da0 6f 77 6e 28 29 5d 20 73 6f 20 69 74 20 64 6f 65  own()] so it doe
11db0 73 0a 2a 2a 20 6e 6f 74 20 6e 65 65 64 20 74 6f  s.** not need to
11dc0 20 62 65 20 74 68 72 65 61 64 73 61 66 65 20 65   be threadsafe e
11dd0 69 74 68 65 72 2e 20 20 46 6f 72 20 61 6c 6c 20  ither.  For all 
11de0 6f 74 68 65 72 20 6d 65 74 68 6f 64 73 2c 20 53  other methods, S
11df0 51 4c 69 74 65 0a 2a 2a 20 68 6f 6c 64 73 20 74  QLite.** holds t
11e00 68 65 20 5b 53 51 4c 49 54 45 5f 4d 55 54 45 58  he [SQLITE_MUTEX
11e10 5f 53 54 41 54 49 43 5f 4d 45 4d 5d 20 6d 75 74  _STATIC_MEM] mut
11e20 65 78 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68  ex as long as th
11e30 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e  e.** [SQLITE_CON
11e40 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d 20 63  FIG_MEMSTATUS] c
11e50 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
11e60 69 6f 6e 20 69 73 20 74 75 72 6e 65 64 20 6f 6e  ion is turned on
11e70 20 28 77 68 69 63 68 0a 2a 2a 20 69 74 20 69 73   (which.** it is
11e80 20 62 79 20 64 65 66 61 75 6c 74 29 20 61 6e 64   by default) and
11e90 20 73 6f 20 74 68 65 20 6d 65 74 68 6f 64 73 20   so the methods 
11ea0 61 72 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  are automaticall
11eb0 79 20 73 65 72 69 61 6c 69 7a 65 64 2e 0a 2a 2a  y serialized..**
11ec0 20 48 6f 77 65 76 65 72 2c 20 69 66 20 5b 53 51   However, if [SQ
11ed0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53  LITE_CONFIG_MEMS
11ee0 54 41 54 55 53 5d 20 69 73 20 64 69 73 61 62 6c  TATUS] is disabl
11ef0 65 64 2c 20 74 68 65 6e 20 74 68 65 20 6f 74 68  ed, then the oth
11f00 65 72 0a 2a 2a 20 6d 65 74 68 6f 64 73 20 6d 75  er.** methods mu
11f10 73 74 20 62 65 20 74 68 72 65 61 64 73 61 66 65  st be threadsafe
11f20 20 6f 72 20 65 6c 73 65 20 6d 61 6b 65 20 74 68   or else make th
11f30 65 69 72 20 6f 77 6e 20 61 72 72 61 6e 67 65 6d  eir own arrangem
11f40 65 6e 74 73 20 66 6f 72 0a 2a 2a 20 73 65 72 69  ents for.** seri
11f50 61 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  alization..**.**
11f60 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 6e 65 76   SQLite will nev
11f70 65 72 20 69 6e 76 6f 6b 65 20 78 49 6e 69 74 28  er invoke xInit(
11f80 29 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65  ) more than once
11f90 20 77 69 74 68 6f 75 74 20 61 6e 20 69 6e 74 65   without an inte
11fa0 72 76 65 6e 69 6e 67 0a 2a 2a 20 63 61 6c 6c 20  rvening.** call 
11fb0 74 6f 20 78 53 68 75 74 64 6f 77 6e 28 29 2e 0a  to xShutdown()..
11fc0 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63  */.typedef struc
11fd0 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65  t sqlite3_mem_me
11fe0 74 68 6f 64 73 20 73 71 6c 69 74 65 33 5f 6d 65  thods sqlite3_me
11ff0 6d 5f 6d 65 74 68 6f 64 73 3b 0a 73 74 72 75 63  m_methods;.struc
12000 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65  t sqlite3_mem_me
12010 74 68 6f 64 73 20 7b 0a 20 20 76 6f 69 64 20 2a  thods {.  void *
12020 28 2a 78 4d 61 6c 6c 6f 63 29 28 69 6e 74 29 3b  (*xMalloc)(int);
12030 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 65 6d 6f           /* Memo
12040 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 75  ry allocation fu
12050 6e 63 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64  nction */.  void
12060 20 28 2a 78 46 72 65 65 29 28 76 6f 69 64 2a 29   (*xFree)(void*)
12070 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20 46 72  ;          /* Fr
12080 65 65 20 61 20 70 72 69 6f 72 20 61 6c 6c 6f 63  ee a prior alloc
12090 61 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20  ation */.  void 
120a0 2a 28 2a 78 52 65 61 6c 6c 6f 63 29 28 76 6f 69  *(*xRealloc)(voi
120b0 64 2a 2c 69 6e 74 29 3b 20 20 2f 2a 20 52 65 73  d*,int);  /* Res
120c0 69 7a 65 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f  ize an allocatio
120d0 6e 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 53 69  n */.  int (*xSi
120e0 7a 65 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20  ze)(void*);     
120f0 20 20 20 20 20 20 2f 2a 20 52 65 74 75 72 6e 20        /* Return 
12100 74 68 65 20 73 69 7a 65 20 6f 66 20 61 6e 20 61  the size of an a
12110 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 69  llocation */.  i
12120 6e 74 20 28 2a 78 52 6f 75 6e 64 75 70 29 28 69  nt (*xRoundup)(i
12130 6e 74 29 3b 20 20 20 20 20 20 20 20 20 20 2f 2a  nt);          /*
12140 20 52 6f 75 6e 64 20 75 70 20 72 65 71 75 65 73   Round up reques
12150 74 20 73 69 7a 65 20 74 6f 20 61 6c 6c 6f 63 61  t size to alloca
12160 74 69 6f 6e 20 73 69 7a 65 20 2a 2f 0a 20 20 69  tion size */.  i
12170 6e 74 20 28 2a 78 49 6e 69 74 29 28 76 6f 69 64  nt (*xInit)(void
12180 2a 29 3b 20 20 20 20 20 20 20 20 20 20 20 2f 2a  *);           /*
12190 20 49 6e 69 74 69 61 6c 69 7a 65 20 74 68 65 20   Initialize the 
121a0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72  memory allocator
121b0 20 2a 2f 0a 20 20 76 6f 69 64 20 28 2a 78 53 68   */.  void (*xSh
121c0 75 74 64 6f 77 6e 29 28 76 6f 69 64 2a 29 3b 20  utdown)(void*); 
121d0 20 20 20 20 20 2f 2a 20 44 65 69 6e 69 74 69 61       /* Deinitia
121e0 6c 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79 20  lize the memory 
121f0 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20 20 76  allocator */.  v
12200 6f 69 64 20 2a 70 41 70 70 44 61 74 61 3b 20 20  oid *pAppData;  
12210 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
12220 20 41 72 67 75 6d 65 6e 74 20 74 6f 20 78 49 6e   Argument to xIn
12230 69 74 28 29 20 61 6e 64 20 78 53 68 75 74 64 6f  it() and xShutdo
12240 77 6e 28 29 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a  wn() */.};../*.*
12250 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66  * CAPI3REF: Conf
12260 69 67 75 72 61 74 69 6f 6e 20 4f 70 74 69 6f 6e  iguration Option
12270 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  s.** KEYWORDS: {
12280 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
12290 74 69 6f 6e 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73  tion}.**.** Thes
122a0 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20  e constants are 
122b0 74 68 65 20 61 76 61 69 6c 61 62 6c 65 20 69 6e  the available in
122c0 74 65 67 65 72 20 63 6f 6e 66 69 67 75 72 61 74  teger configurat
122d0 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 74 68 61 74  ion options that
122e0 0a 2a 2a 20 63 61 6e 20 62 65 20 70 61 73 73 65  .** can be passe
122f0 64 20 61 73 20 74 68 65 20 66 69 72 73 74 20 61  d as the first a
12300 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b  rgument to the [
12310 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
12320 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a  ] interface..**.
12330 2a 2a 20 4e 65 77 20 63 6f 6e 66 69 67 75 72 61  ** New configura
12340 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 61 79  tion options may
12350 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 74   be added in fut
12360 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20  ure releases of 
12370 53 51 4c 69 74 65 2e 0a 2a 2a 20 45 78 69 73 74  SQLite..** Exist
12380 69 6e 67 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ing configuratio
12390 6e 20 6f 70 74 69 6f 6e 73 20 6d 69 67 68 74 20  n options might 
123a0 62 65 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 2e  be discontinued.
123b0 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a    Applications.*
123c0 2a 20 73 68 6f 75 6c 64 20 63 68 65 63 6b 20 74  * should check t
123d0 68 65 20 72 65 74 75 72 6e 20 63 6f 64 65 20 66  he return code f
123e0 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  rom [sqlite3_con
123f0 66 69 67 28 29 5d 20 74 6f 20 6d 61 6b 65 20 73  fig()] to make s
12400 75 72 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20  ure that.** the 
12410 63 61 6c 6c 20 77 6f 72 6b 65 64 2e 20 20 54 68  call worked.  Th
12420 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  e [sqlite3_confi
12430 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 77  g()] interface w
12440 69 6c 6c 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20  ill return a.** 
12450 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20  non-zero [error 
12460 63 6f 64 65 5d 20 69 66 20 61 20 64 69 73 63 6f  code] if a disco
12470 6e 74 69 6e 75 65 64 20 6f 72 20 75 6e 73 75 70  ntinued or unsup
12480 70 6f 72 74 65 64 20 63 6f 6e 66 69 67 75 72 61  ported configura
12490 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69  tion option.** i
124a0 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a  s invoked..**.**
124b0 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c 49 54   <dl>.** [[SQLIT
124c0 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54  E_CONFIG_SINGLET
124d0 48 52 45 41 44 5d 5d 20 3c 64 74 3e 53 51 4c 49  HREAD]] <dt>SQLI
124e0 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45  TE_CONFIG_SINGLE
124f0 54 48 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c  THREAD</dt>.** <
12500 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e 6f 20  dd>There are no 
12510 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69  arguments to thi
12520 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68 69 73  s option.  ^This
12530 20 6f 70 74 69 6f 6e 20 73 65 74 73 20 74 68 65   option sets the
12540 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67 20 6d  .** [threading m
12550 6f 64 65 5d 20 74 6f 20 53 69 6e 67 6c 65 2d 74  ode] to Single-t
12560 68 72 65 61 64 2e 20 20 49 6e 20 6f 74 68 65 72  hread.  In other
12570 20 77 6f 72 64 73 2c 20 69 74 20 64 69 73 61 62   words, it disab
12580 6c 65 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65 78  les.** all mutex
12590 69 6e 67 20 61 6e 64 20 70 75 74 73 20 53 51 4c  ing and puts SQL
125a0 69 74 65 20 69 6e 74 6f 20 61 20 6d 6f 64 65 20  ite into a mode 
125b0 77 68 65 72 65 20 69 74 20 63 61 6e 20 6f 6e 6c  where it can onl
125c0 79 20 62 65 20 75 73 65 64 0a 2a 2a 20 62 79 20  y be used.** by 
125d0 61 20 73 69 6e 67 6c 65 20 74 68 72 65 61 64 2e  a single thread.
125e0 20 20 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73     ^If SQLite is
125f0 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a   compiled with.*
12600 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48  * the [SQLITE_TH
12610 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54  READSAFE | SQLIT
12620 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20  E_THREADSAFE=0] 
12630 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
12640 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69  ion then.** it i
12650 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 74  s not possible t
12660 6f 20 63 68 61 6e 67 65 20 74 68 65 20 5b 74 68  o change the [th
12670 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 66 72  reading mode] fr
12680 6f 6d 20 69 74 73 20 64 65 66 61 75 6c 74 0a 2a  om its default.*
12690 2a 20 76 61 6c 75 65 20 6f 66 20 53 69 6e 67 6c  * value of Singl
126a0 65 2d 74 68 72 65 61 64 20 61 6e 64 20 73 6f 20  e-thread and so 
126b0 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
126c0 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 0a  )] will return .
126d0 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  ** [SQLITE_ERROR
126e0 5d 20 69 66 20 63 61 6c 6c 65 64 20 77 69 74 68  ] if called with
126f0 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46   the SQLITE_CONF
12700 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 0a  IG_SINGLETHREAD.
12710 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ** configuration
12720 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a   option.</dd>.**
12730 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
12740 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d  FIG_MULTITHREAD]
12750 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
12760 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 3c  FIG_MULTITHREAD<
12770 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72  /dt>.** <dd>Ther
12780 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e  e are no argumen
12790 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f  ts to this optio
127a0 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e  n.  ^This option
127b0 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74 68   sets the.** [th
127c0 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f  reading mode] to
127d0 20 4d 75 6c 74 69 2d 74 68 72 65 61 64 2e 20 20   Multi-thread.  
127e0 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20  In other words, 
127f0 69 74 20 64 69 73 61 62 6c 65 73 0a 2a 2a 20 6d  it disables.** m
12800 75 74 65 78 69 6e 67 20 6f 6e 20 5b 64 61 74 61  utexing on [data
12810 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
12820 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73   and [prepared s
12830 74 61 74 65 6d 65 6e 74 5d 20 6f 62 6a 65 63 74  tatement] object
12840 73 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63  s..** The applic
12850 61 74 69 6f 6e 20 69 73 20 72 65 73 70 6f 6e 73  ation is respons
12860 69 62 6c 65 20 66 6f 72 20 73 65 72 69 61 6c 69  ible for seriali
12870 7a 69 6e 67 20 61 63 63 65 73 73 20 74 6f 0a 2a  zing access to.*
12880 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  * [database conn
12890 65 63 74 69 6f 6e 73 5d 20 61 6e 64 20 5b 70 72  ections] and [pr
128a0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
128b0 73 5d 2e 20 20 42 75 74 20 6f 74 68 65 72 20 6d  s].  But other m
128c0 75 74 65 78 65 73 0a 2a 2a 20 61 72 65 20 65 6e  utexes.** are en
128d0 61 62 6c 65 64 20 73 6f 20 74 68 61 74 20 53 51  abled so that SQ
128e0 4c 69 74 65 20 77 69 6c 6c 20 62 65 20 73 61 66  Lite will be saf
128f0 65 20 74 6f 20 75 73 65 20 69 6e 20 61 20 6d 75  e to use in a mu
12900 6c 74 69 2d 74 68 72 65 61 64 65 64 0a 2a 2a 20  lti-threaded.** 
12910 65 6e 76 69 72 6f 6e 6d 65 6e 74 20 61 73 20 6c  environment as l
12920 6f 6e 67 20 61 73 20 6e 6f 20 74 77 6f 20 74 68  ong as no two th
12930 72 65 61 64 73 20 61 74 74 65 6d 70 74 20 74 6f  reads attempt to
12940 20 75 73 65 20 74 68 65 20 73 61 6d 65 0a 2a 2a   use the same.**
12950 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
12960 63 74 69 6f 6e 5d 20 61 74 20 74 68 65 20 73 61  ction] at the sa
12970 6d 65 20 74 69 6d 65 2e 20 20 5e 49 66 20 53 51  me time.  ^If SQ
12980 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  Lite is compiled
12990 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51   with.** the [SQ
129a0 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 20  LITE_THREADSAFE 
129b0 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53  | SQLITE_THREADS
129c0 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74  AFE=0] compile-t
129d0 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a  ime option then.
129e0 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20 70 6f 73  ** it is not pos
129f0 73 69 62 6c 65 20 74 6f 20 73 65 74 20 74 68 65  sible to set the
12a00 20 4d 75 6c 74 69 2d 74 68 72 65 61 64 20 5b 74   Multi-thread [t
12a10 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61  hreading mode] a
12a20 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  nd.** [sqlite3_c
12a30 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20 72 65  onfig()] will re
12a40 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52  turn [SQLITE_ERR
12a50 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64 20 77 69  OR] if called wi
12a60 74 68 20 74 68 65 0a 2a 2a 20 53 51 4c 49 54 45  th the.** SQLITE
12a70 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52  _CONFIG_MULTITHR
12a80 45 41 44 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  EAD configuratio
12a90 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a  n option.</dd>.*
12aa0 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
12ab0 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 5d  NFIG_SERIALIZED]
12ac0 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
12ad0 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 3c 2f  FIG_SERIALIZED</
12ae0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65  dt>.** <dd>There
12af0 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74   are no argument
12b00 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e  s to this option
12b10 2e 20 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20  .  ^This option 
12b20 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72  sets the.** [thr
12b30 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20  eading mode] to 
12b40 53 65 72 69 61 6c 69 7a 65 64 2e 20 49 6e 20 6f  Serialized. In o
12b50 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68 69 73  ther words, this
12b60 20 6f 70 74 69 6f 6e 20 65 6e 61 62 6c 65 73 0a   option enables.
12b70 2a 2a 20 61 6c 6c 20 6d 75 74 65 78 65 73 20 69  ** all mutexes i
12b80 6e 63 6c 75 64 69 6e 67 20 74 68 65 20 72 65 63  ncluding the rec
12b90 75 72 73 69 76 65 0a 2a 2a 20 6d 75 74 65 78 65  ursive.** mutexe
12ba0 73 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63  s on [database c
12bb0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64 20 5b  onnection] and [
12bc0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
12bd0 6e 74 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20  nt] objects..** 
12be0 49 6e 20 74 68 69 73 20 6d 6f 64 65 20 28 77 68  In this mode (wh
12bf0 69 63 68 20 69 73 20 74 68 65 20 64 65 66 61 75  ich is the defau
12c00 6c 74 20 77 68 65 6e 20 53 51 4c 69 74 65 20 69  lt when SQLite i
12c10 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a  s compiled with.
12c20 2a 2a 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41  ** [SQLITE_THREA
12c30 44 53 41 46 45 3d 31 5d 29 20 74 68 65 20 53 51  DSAFE=1]) the SQ
12c40 4c 69 74 65 20 6c 69 62 72 61 72 79 20 77 69 6c  Lite library wil
12c50 6c 20 69 74 73 65 6c 66 20 73 65 72 69 61 6c 69  l itself seriali
12c60 7a 65 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20  ze access.** to 
12c70 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
12c80 74 69 6f 6e 73 5d 20 61 6e 64 20 5b 70 72 65 70  tions] and [prep
12c90 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d  ared statements]
12ca0 20 73 6f 20 74 68 61 74 20 74 68 65 0a 2a 2a 20   so that the.** 
12cb0 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 73 20 66  application is f
12cc0 72 65 65 20 74 6f 20 75 73 65 20 74 68 65 20 73  ree to use the s
12cd0 61 6d 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  ame [database co
12ce0 6e 6e 65 63 74 69 6f 6e 5d 20 6f 72 20 74 68 65  nnection] or the
12cf0 0a 2a 2a 20 73 61 6d 65 20 5b 70 72 65 70 61 72  .** same [prepar
12d00 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 6e  ed statement] in
12d10 20 64 69 66 66 65 72 65 6e 74 20 74 68 72 65 61   different threa
12d20 64 73 20 61 74 20 74 68 65 20 73 61 6d 65 20 74  ds at the same t
12d30 69 6d 65 2e 0a 2a 2a 20 5e 49 66 20 53 51 4c 69  ime..** ^If SQLi
12d40 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77  te is compiled w
12d50 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49  ith.** the [SQLI
12d60 54 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20  TE_THREADSAFE | 
12d70 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
12d80 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  E=0] compile-tim
12d90 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a  e option then.**
12da0 20 69 74 20 69 73 20 6e 6f 74 20 70 6f 73 73 69   it is not possi
12db0 62 6c 65 20 74 6f 20 73 65 74 20 74 68 65 20 53  ble to set the S
12dc0 65 72 69 61 6c 69 7a 65 64 20 5b 74 68 72 65 61  erialized [threa
12dd0 64 69 6e 67 20 6d 6f 64 65 5d 20 61 6e 64 0a 2a  ding mode] and.*
12de0 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  * [sqlite3_confi
12df0 67 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e  g()] will return
12e00 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20   [SQLITE_ERROR] 
12e10 69 66 20 63 61 6c 6c 65 64 20 77 69 74 68 20 74  if called with t
12e20 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 43 4f 4e  he.** SQLITE_CON
12e30 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 20 63  FIG_SERIALIZED c
12e40 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
12e50 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ion.</dd>.**.** 
12e60 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
12e70 4d 41 4c 4c 4f 43 5d 5d 20 3c 64 74 3e 53 51 4c  MALLOC]] <dt>SQL
12e80 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f  ITE_CONFIG_MALLO
12e90 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  C</dt>.** <dd> ^
12ea0 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  (The SQLITE_CONF
12eb0 49 47 5f 4d 41 4c 4c 4f 43 20 6f 70 74 69 6f 6e  IG_MALLOC option
12ec0 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20   takes a single 
12ed0 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69  argument which i
12ee0 73 20 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20  s .** a pointer 
12ef0 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f  to an instance o
12f00 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d  f the [sqlite3_m
12f10 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75  em_methods] stru
12f20 63 74 75 72 65 2e 0a 2a 2a 20 54 68 65 20 61 72  cture..** The ar
12f30 67 75 6d 65 6e 74 20 73 70 65 63 69 66 69 65 73  gument specifies
12f40 0a 2a 2a 20 61 6c 74 65 72 6e 61 74 69 76 65 20  .** alternative 
12f50 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72 79  low-level memory
12f60 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74   allocation rout
12f70 69 6e 65 73 20 74 6f 20 62 65 20 75 73 65 64 20  ines to be used 
12f80 69 6e 20 70 6c 61 63 65 20 6f 66 0a 2a 2a 20 74  in place of.** t
12f90 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  he memory alloca
12fa0 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 20 62 75  tion routines bu
12fb0 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 2e  ilt into SQLite.
12fc0 29 5e 20 5e 53 51 4c 69 74 65 20 6d 61 6b 65 73  )^ ^SQLite makes
12fd0 0a 2a 2a 20 69 74 73 20 6f 77 6e 20 70 72 69 76  .** its own priv
12fe0 61 74 65 20 63 6f 70 79 20 6f 66 20 74 68 65 20  ate copy of the 
12ff0 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 5b  content of the [
13000 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68  sqlite3_mem_meth
13010 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 0a 2a  ods] structure.*
13020 2a 20 62 65 66 6f 72 65 20 74 68 65 20 5b 73 71  * before the [sq
13030 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20  lite3_config()] 
13040 63 61 6c 6c 20 72 65 74 75 72 6e 73 2e 3c 2f 64  call returns.</d
13050 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
13060 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c  E_CONFIG_GETMALL
13070 4f 43 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  OC]] <dt>SQLITE_
13080 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43  CONFIG_GETMALLOC
13090 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28  </dt>.** <dd> ^(
130a0 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  The SQLITE_CONFI
130b0 47 5f 47 45 54 4d 41 4c 4c 4f 43 20 6f 70 74 69  G_GETMALLOC opti
130c0 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c  on takes a singl
130d0 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68  e argument which
130e0 0a 2a 2a 20 69 73 20 61 20 70 6f 69 6e 74 65 72  .** is a pointer
130f0 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20   to an instance 
13100 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
13110 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72  mem_methods] str
13120 75 63 74 75 72 65 2e 0a 2a 2a 20 54 68 65 20 5b  ucture..** The [
13130 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68  sqlite3_mem_meth
13140 6f 64 73 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72  ods].** structur
13150 65 20 69 73 20 66 69 6c 6c 65 64 20 77 69 74 68  e is filled with
13160 20 74 68 65 20 63 75 72 72 65 6e 74 6c 79 20 64   the currently d
13170 65 66 69 6e 65 64 20 6d 65 6d 6f 72 79 20 61 6c  efined memory al
13180 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65  location routine
13190 73 2e 29 5e 0a 2a 2a 20 54 68 69 73 20 6f 70 74  s.)^.** This opt
131a0 69 6f 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20  ion can be used 
131b0 74 6f 20 6f 76 65 72 6c 6f 61 64 20 74 68 65 20  to overload the 
131c0 64 65 66 61 75 6c 74 20 6d 65 6d 6f 72 79 20 61  default memory a
131d0 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75  llocation.** rou
131e0 74 69 6e 65 73 20 77 69 74 68 20 61 20 77 72 61  tines with a wra
131f0 70 70 65 72 20 74 68 61 74 20 73 69 6d 75 6c 61  pper that simula
13200 74 69 6f 6e 73 20 6d 65 6d 6f 72 79 20 61 6c 6c  tions memory all
13210 6f 63 61 74 69 6f 6e 20 66 61 69 6c 75 72 65 20  ocation failure 
13220 6f 72 0a 2a 2a 20 74 72 61 63 6b 73 20 6d 65 6d  or.** tracks mem
13230 6f 72 79 20 75 73 61 67 65 2c 20 66 6f 72 20 65  ory usage, for e
13240 78 61 6d 70 6c 65 2e 20 3c 2f 64 64 3e 0a 2a 2a  xample. </dd>.**
13250 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
13260 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d 5d 20  FIG_MEMSTATUS]] 
13270 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
13280 47 5f 4d 45 4d 53 54 41 54 55 53 3c 2f 64 74 3e  G_MEMSTATUS</dt>
13290 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 65 20 53 51  .** <dd> ^The SQ
132a0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53  LITE_CONFIG_MEMS
132b0 54 41 54 55 53 20 6f 70 74 69 6f 6e 20 74 61 6b  TATUS option tak
132c0 65 73 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65  es single argume
132d0 6e 74 20 6f 66 20 74 79 70 65 20 69 6e 74 2c 0a  nt of type int,.
132e0 2a 2a 20 69 6e 74 65 72 70 72 65 74 65 64 20 61  ** interpreted a
132f0 73 20 61 20 62 6f 6f 6c 65 61 6e 2c 20 77 68 69  s a boolean, whi
13300 63 68 20 65 6e 61 62 6c 65 73 20 6f 72 20 64 69  ch enables or di
13310 73 61 62 6c 65 73 20 74 68 65 20 63 6f 6c 6c 65  sables the colle
13320 63 74 69 6f 6e 20 6f 66 0a 2a 2a 20 6d 65 6d 6f  ction of.** memo
13330 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74  ry allocation st
13340 61 74 69 73 74 69 63 73 2e 20 5e 28 57 68 65 6e  atistics. ^(When
13350 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
13360 6f 6e 20 73 74 61 74 69 73 74 69 63 73 20 61 72  on statistics ar
13370 65 0a 2a 2a 20 64 69 73 61 62 6c 65 64 2c 20 74  e.** disabled, t
13380 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 53 51 4c  he following SQL
13390 69 74 65 20 69 6e 74 65 72 66 61 63 65 73 20 62  ite interfaces b
133a0 65 63 6f 6d 65 20 6e 6f 6e 2d 6f 70 65 72 61 74  ecome non-operat
133b0 69 6f 6e 61 6c 3a 0a 2a 2a 20 20 20 3c 75 6c 3e  ional:.**   <ul>
133c0 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69  .**   <li> [sqli
133d0 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28  te3_memory_used(
133e0 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71  )].**   <li> [sq
133f0 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67  lite3_memory_hig
13400 68 77 61 74 65 72 28 29 5d 0a 2a 2a 20 20 20 3c  hwater()].**   <
13410 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 73 6f 66  li> [sqlite3_sof
13420 74 5f 68 65 61 70 5f 6c 69 6d 69 74 36 34 28 29  t_heap_limit64()
13430 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c  ].**   <li> [sql
13440 69 74 65 33 5f 73 74 61 74 75 73 36 34 28 29 5d  ite3_status64()]
13450 0a 2a 2a 20 20 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a  .**   </ul>)^.**
13460 20 5e 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74   ^Memory allocat
13470 69 6f 6e 20 73 74 61 74 69 73 74 69 63 73 20 61  ion statistics a
13480 72 65 20 65 6e 61 62 6c 65 64 20 62 79 20 64 65  re enabled by de
13490 66 61 75 6c 74 20 75 6e 6c 65 73 73 20 53 51 4c  fault unless SQL
134a0 69 74 65 20 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c  ite is.** compil
134b0 65 64 20 77 69 74 68 20 5b 53 51 4c 49 54 45 5f  ed with [SQLITE_
134c0 44 45 46 41 55 4c 54 5f 4d 45 4d 53 54 41 54 55  DEFAULT_MEMSTATU
134d0 53 5d 3d 30 20 69 6e 20 77 68 69 63 68 20 63 61  S]=0 in which ca
134e0 73 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c  se memory.** all
134f0 6f 63 61 74 69 6f 6e 20 73 74 61 74 69 73 74 69  ocation statisti
13500 63 73 20 61 72 65 20 64 69 73 61 62 6c 65 64 20  cs are disabled 
13510 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 20 3c  by default..** <
13520 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
13530 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54  ITE_CONFIG_SCRAT
13540 43 48 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  CH]] <dt>SQLITE_
13550 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 3c 2f  CONFIG_SCRATCH</
13560 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 65  dt>.** <dd> ^The
13570 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53   SQLITE_CONFIG_S
13580 43 52 41 54 43 48 20 6f 70 74 69 6f 6e 20 73 70  CRATCH option sp
13590 65 63 69 66 69 65 73 20 61 20 73 74 61 74 69 63  ecifies a static
135a0 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 0a 2a   memory buffer.*
135b0 2a 20 74 68 61 74 20 53 51 4c 69 74 65 20 63 61  * that SQLite ca
135c0 6e 20 75 73 65 20 66 6f 72 20 73 63 72 61 74 63  n use for scratc
135d0 68 20 6d 65 6d 6f 72 79 2e 20 20 5e 28 54 68 65  h memory.  ^(The
135e0 72 65 20 61 72 65 20 74 68 72 65 65 20 61 72 67  re are three arg
135f0 75 6d 65 6e 74 73 0a 2a 2a 20 74 6f 20 53 51 4c  uments.** to SQL
13600 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54  ITE_CONFIG_SCRAT
13610 43 48 3a 20 20 41 20 70 6f 69 6e 74 65 72 20 61  CH:  A pointer a
13620 6e 20 38 2d 62 79 74 65 0a 2a 2a 20 61 6c 69 67  n 8-byte.** alig
13630 6e 65 64 20 6d 65 6d 6f 72 79 20 62 75 66 66 65  ned memory buffe
13640 72 20 66 72 6f 6d 20 77 68 69 63 68 20 74 68 65  r from which the
13650 20 73 63 72 61 74 63 68 20 61 6c 6c 6f 63 61 74   scratch allocat
13660 69 6f 6e 73 20 77 69 6c 6c 20 62 65 0a 2a 2a 20  ions will be.** 
13670 64 72 61 77 6e 2c 20 74 68 65 20 73 69 7a 65 20  drawn, the size 
13680 6f 66 20 65 61 63 68 20 73 63 72 61 74 63 68 20  of each scratch 
13690 61 6c 6c 6f 63 61 74 69 6f 6e 20 28 73 7a 29 2c  allocation (sz),
136a0 0a 2a 2a 20 61 6e 64 20 74 68 65 20 6d 61 78 69  .** and the maxi
136b0 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 73 63  mum number of sc
136c0 72 61 74 63 68 20 61 6c 6c 6f 63 61 74 69 6f 6e  ratch allocation
136d0 73 20 28 4e 29 2e 29 5e 0a 2a 2a 20 54 68 65 20  s (N).)^.** The 
136e0 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 6d  first argument m
136f0 75 73 74 20 62 65 20 61 20 70 6f 69 6e 74 65 72  ust be a pointer
13700 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 20 61 6c   to an 8-byte al
13710 69 67 6e 65 64 20 62 75 66 66 65 72 0a 2a 2a 20  igned buffer.** 
13720 6f 66 20 61 74 20 6c 65 61 73 74 20 73 7a 2a 4e  of at least sz*N
13730 20 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79   bytes of memory
13740 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c  ..** ^SQLite wil
13750 6c 20 6e 6f 74 20 75 73 65 20 6d 6f 72 65 20 74  l not use more t
13760 68 61 6e 20 6f 6e 65 20 73 63 72 61 74 63 68 20  han one scratch 
13770 62 75 66 66 65 72 73 20 70 65 72 20 74 68 72 65  buffers per thre
13780 61 64 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77  ad..** ^SQLite w
13790 69 6c 6c 20 6e 65 76 65 72 20 72 65 71 75 65 73  ill never reques
137a0 74 20 61 20 73 63 72 61 74 63 68 20 62 75 66 66  t a scratch buff
137b0 65 72 20 74 68 61 74 20 69 73 20 6d 6f 72 65 20  er that is more 
137c0 74 68 61 6e 20 36 0a 2a 2a 20 74 69 6d 65 73 20  than 6.** times 
137d0 74 68 65 20 64 61 74 61 62 61 73 65 20 70 61 67  the database pag
137e0 65 20 73 69 7a 65 2e 0a 2a 2a 20 5e 49 66 20 53  e size..** ^If S
137f0 51 4c 69 74 65 20 6e 65 65 64 73 20 6e 65 65 64  QLite needs need
13800 73 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20  s additional.** 
13810 73 63 72 61 74 63 68 20 6d 65 6d 6f 72 79 20 62  scratch memory b
13820 65 79 6f 6e 64 20 77 68 61 74 20 69 73 20 70 72  eyond what is pr
13830 6f 76 69 64 65 64 20 62 79 20 74 68 69 73 20 63  ovided by this c
13840 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
13850 69 6f 6e 2c 20 74 68 65 6e 20 0a 2a 2a 20 5b 73  ion, then .** [s
13860 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
13870 20 77 69 6c 6c 20 62 65 20 75 73 65 64 20 74 6f   will be used to
13880 20 6f 62 74 61 69 6e 20 74 68 65 20 6d 65 6d 6f   obtain the memo
13890 72 79 20 6e 65 65 64 65 64 2e 3c 70 3e 0a 2a 2a  ry needed.<p>.**
138a0 20 5e 57 68 65 6e 20 74 68 65 20 61 70 70 6c 69   ^When the appli
138b0 63 61 74 69 6f 6e 20 70 72 6f 76 69 64 65 73 20  cation provides 
138c0 61 6e 79 20 61 6d 6f 75 6e 74 20 6f 66 20 73 63  any amount of sc
138d0 72 61 74 63 68 20 6d 65 6d 6f 72 79 20 75 73 69  ratch memory usi
138e0 6e 67 0a 2a 2a 20 53 51 4c 49 54 45 5f 43 4f 4e  ng.** SQLITE_CON
138f0 46 49 47 5f 53 43 52 41 54 43 48 2c 20 53 51 4c  FIG_SCRATCH, SQL
13900 69 74 65 20 61 76 6f 69 64 73 20 75 6e 6e 65 63  ite avoids unnec
13910 65 73 73 61 72 79 20 6c 61 72 67 65 0a 2a 2a 20  essary large.** 
13920 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 7c  [sqlite3_malloc|
13930 68 65 61 70 20 61 6c 6c 6f 63 61 74 69 6f 6e 73  heap allocations
13940 5d 2e 0a 2a 2a 20 54 68 69 73 20 63 61 6e 20 68  ]..** This can h
13950 65 6c 70 20 5b 52 6f 62 73 6f 6e 20 70 72 6f 6f  elp [Robson proo
13960 66 7c 70 72 65 76 65 6e 74 20 6d 65 6d 6f 72 79  f|prevent memory
13970 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c   allocation fail
13980 75 72 65 73 5d 20 64 75 65 20 74 6f 20 68 65 61  ures] due to hea
13990 70 0a 2a 2a 20 66 72 61 67 6d 65 6e 74 61 74 69  p.** fragmentati
139a0 6f 6e 20 69 6e 20 6c 6f 77 2d 6d 65 6d 6f 72 79  on in low-memory
139b0 20 65 6d 62 65 64 64 65 64 20 73 79 73 74 65 6d   embedded system
139c0 73 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a  s..** </dd>.**.*
139d0 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
139e0 47 5f 50 41 47 45 43 41 43 48 45 5d 5d 20 3c 64  G_PAGECACHE]] <d
139f0 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
13a00 50 41 47 45 43 41 43 48 45 3c 2f 64 74 3e 0a 2a  PAGECACHE</dt>.*
13a10 2a 20 3c 64 64 3e 20 5e 54 68 65 20 53 51 4c 49  * <dd> ^The SQLI
13a20 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41  TE_CONFIG_PAGECA
13a30 43 48 45 20 6f 70 74 69 6f 6e 20 73 70 65 63 69  CHE option speci
13a40 66 69 65 73 20 61 20 6d 65 6d 6f 72 79 20 70 6f  fies a memory po
13a50 6f 6c 0a 2a 2a 20 74 68 61 74 20 53 51 4c 69 74  ol.** that SQLit
13a60 65 20 63 61 6e 20 75 73 65 20 66 6f 72 20 74 68  e can use for th
13a70 65 20 64 61 74 61 62 61 73 65 20 70 61 67 65 20  e database page 
13a80 63 61 63 68 65 20 77 69 74 68 20 74 68 65 20 64  cache with the d
13a90 65 66 61 75 6c 74 20 70 61 67 65 0a 2a 2a 20 63  efault page.** c
13aa0 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  ache implementat
13ab0 69 6f 6e 2e 20 20 0a 2a 2a 20 54 68 69 73 20 63  ion.  .** This c
13ac0 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
13ad0 69 6f 6e 20 69 73 20 61 20 6e 6f 2d 6f 70 20 69  ion is a no-op i
13ae0 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  f an application
13af0 2d 64 65 66 69 6e 65 20 70 61 67 65 0a 2a 2a 20  -define page.** 
13b00 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61  cache implementa
13b10 74 69 6f 6e 20 69 73 20 6c 6f 61 64 65 64 20 75  tion is loaded u
13b20 73 69 6e 67 20 74 68 65 20 5b 53 51 4c 49 54 45  sing the [SQLITE
13b30 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 5d  _CONFIG_PCACHE2]
13b40 2e 0a 2a 2a 20 5e 54 68 65 72 65 20 61 72 65 20  ..** ^There are 
13b50 74 68 72 65 65 20 61 72 67 75 6d 65 6e 74 73 20  three arguments 
13b60 74 6f 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  to SQLITE_CONFIG
13b70 5f 50 41 47 45 43 41 43 48 45 3a 20 41 20 70 6f  _PAGECACHE: A po
13b80 69 6e 74 65 72 20 74 6f 0a 2a 2a 20 38 2d 62 79  inter to.** 8-by
13b90 74 65 20 61 6c 69 67 6e 65 64 20 6d 65 6d 6f 72  te aligned memor
13ba0 79 20 28 70 4d 65 6d 29 2c 20 74 68 65 20 73 69  y (pMem), the si
13bb0 7a 65 20 6f 66 20 65 61 63 68 20 70 61 67 65 20  ze of each page 
13bc0 63 61 63 68 65 20 6c 69 6e 65 20 28 73 7a 29 2c  cache line (sz),
13bd0 0a 2a 2a 20 61 6e 64 20 74 68 65 20 6e 75 6d 62  .** and the numb
13be0 65 72 20 6f 66 20 63 61 63 68 65 20 6c 69 6e 65  er of cache line
13bf0 73 20 28 4e 29 2e 0a 2a 2a 20 54 68 65 20 73 7a  s (N)..** The sz
13c00 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64   argument should
13c10 20 62 65 20 74 68 65 20 73 69 7a 65 20 6f 66 20   be the size of 
13c20 74 68 65 20 6c 61 72 67 65 73 74 20 64 61 74 61  the largest data
13c30 62 61 73 65 20 70 61 67 65 0a 2a 2a 20 28 61 20  base page.** (a 
13c40 70 6f 77 65 72 20 6f 66 20 74 77 6f 20 62 65 74  power of two bet
13c50 77 65 65 6e 20 35 31 32 20 61 6e 64 20 36 35 35  ween 512 and 655
13c60 33 36 29 20 70 6c 75 73 20 73 6f 6d 65 20 65 78  36) plus some ex
13c70 74 72 61 20 62 79 74 65 73 20 66 6f 72 20 65 61  tra bytes for ea
13c80 63 68 0a 2a 2a 20 70 61 67 65 20 68 65 61 64 65  ch.** page heade
13c90 72 2e 20 20 5e 54 68 65 20 6e 75 6d 62 65 72 20  r.  ^The number 
13ca0 6f 66 20 65 78 74 72 61 20 62 79 74 65 73 20 6e  of extra bytes n
13cb0 65 65 64 65 64 20 62 79 20 74 68 65 20 70 61 67  eeded by the pag
13cc0 65 20 68 65 61 64 65 72 0a 2a 2a 20 63 61 6e 20  e header.** can 
13cd0 62 65 20 64 65 74 65 72 6d 69 6e 65 64 20 75 73  be determined us
13ce0 69 6e 67 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ing [SQLITE_CONF
13cf0 49 47 5f 50 43 41 43 48 45 5f 48 44 52 53 5a 5d  IG_PCACHE_HDRSZ]
13d00 2e 0a 2a 2a 20 5e 49 74 20 69 73 20 68 61 72 6d  ..** ^It is harm
13d10 6c 65 73 73 2c 20 61 70 61 72 74 20 66 72 6f 6d  less, apart from
13d20 20 74 68 65 20 77 61 73 74 65 64 20 6d 65 6d 6f   the wasted memo
13d30 72 79 2c 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73  ry,.** for the s
13d40 7a 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 62  z parameter to b
13d50 65 20 6c 61 72 67 65 72 20 74 68 61 6e 20 6e 65  e larger than ne
13d60 63 65 73 73 61 72 79 2e 20 20 54 68 65 20 70 4d  cessary.  The pM
13d70 65 6d 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6d  em.** argument m
13d80 75 73 74 20 62 65 20 65 69 74 68 65 72 20 61 20  ust be either a 
13d90 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 6f 72 20  NULL pointer or 
13da0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  a pointer to an 
13db0 38 2d 62 79 74 65 0a 2a 2a 20 61 6c 69 67 6e 65  8-byte.** aligne
13dc0 64 20 62 6c 6f 63 6b 20 6f 66 20 6d 65 6d 6f 72  d block of memor
13dd0 79 20 6f 66 20 61 74 20 6c 65 61 73 74 20 73 7a  y of at least sz
13de0 2a 4e 20 62 79 74 65 73 2c 20 6f 74 68 65 72 77  *N bytes, otherw
13df0 69 73 65 0a 2a 2a 20 73 75 62 73 65 71 75 65 6e  ise.** subsequen
13e00 74 20 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e  t behavior is un
13e10 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 5e 57 68 65  defined..** ^Whe
13e20 6e 20 70 4d 65 6d 20 69 73 20 6e 6f 74 20 4e 55  n pMem is not NU
13e30 4c 4c 2c 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  LL, SQLite will 
13e40 73 74 72 69 76 65 20 74 6f 20 75 73 65 20 74 68  strive to use th
13e50 65 20 6d 65 6d 6f 72 79 20 70 72 6f 76 69 64 65  e memory provide
13e60 64 0a 2a 2a 20 74 6f 20 73 61 74 69 73 66 79 20  d.** to satisfy 
13e70 70 61 67 65 20 63 61 63 68 65 20 6e 65 65 64 73  page cache needs
13e80 2c 20 66 61 6c 6c 69 6e 67 20 62 61 63 6b 20 74  , falling back t
13e90 6f 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  o [sqlite3_mallo
13ea0 63 28 29 5d 20 69 66 0a 2a 2a 20 61 20 70 61 67  c()] if.** a pag
13eb0 65 20 63 61 63 68 65 20 6c 69 6e 65 20 69 73 20  e cache line is 
13ec0 6c 61 72 67 65 72 20 74 68 61 6e 20 73 7a 20 62  larger than sz b
13ed0 79 74 65 73 20 6f 72 20 69 66 20 61 6c 6c 20 6f  ytes or if all o
13ee0 66 20 74 68 65 20 70 4d 65 6d 20 62 75 66 66 65  f the pMem buffe
13ef0 72 0a 2a 2a 20 69 73 20 65 78 68 61 75 73 74 65  r.** is exhauste
13f00 64 2e 0a 2a 2a 20 5e 49 66 20 70 4d 65 6d 20 69  d..** ^If pMem i
13f10 73 20 4e 55 4c 4c 20 61 6e 64 20 4e 20 69 73 20  s NULL and N is 
13f20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 65  non-zero, then e
13f30 61 63 68 20 64 61 74 61 62 61 73 65 20 63 6f 6e  ach database con
13f40 6e 65 63 74 69 6f 6e 0a 2a 2a 20 64 6f 65 73 20  nection.** does 
13f50 61 6e 20 69 6e 69 74 69 61 6c 20 62 75 6c 6b 20  an initial bulk 
13f60 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 6f 72 20 70  allocation for p
13f70 61 67 65 20 63 61 63 68 65 20 6d 65 6d 6f 72 79  age cache memory
13f80 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  .** from [sqlite
13f90 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 73 75 66 66  3_malloc()] suff
13fa0 69 63 69 65 6e 74 20 66 6f 72 20 4e 20 63 61 63  icient for N cac
13fb0 68 65 20 6c 69 6e 65 73 20 69 66 20 4e 20 69 73  he lines if N is
13fc0 20 70 6f 73 69 74 69 76 65 20 6f 72 0a 2a 2a 20   positive or.** 
13fd0 6f 66 20 2d 31 30 32 34 2a 4e 20 62 79 74 65 73  of -1024*N bytes
13fe0 20 69 66 20 4e 20 69 73 20 6e 65 67 61 74 69 76   if N is negativ
13ff0 65 2c 20 2e 20 5e 49 66 20 61 64 64 69 74 69 6f  e, . ^If additio
14000 6e 61 6c 0a 2a 2a 20 70 61 67 65 20 63 61 63 68  nal.** page cach
14010 65 20 6d 65 6d 6f 72 79 20 69 73 20 6e 65 65 64  e memory is need
14020 65 64 20 62 65 79 6f 6e 64 20 77 68 61 74 20 69  ed beyond what i
14030 73 20 70 72 6f 76 69 64 65 64 20 62 79 20 74 68  s provided by th
14040 65 20 69 6e 69 74 69 61 6c 0a 2a 2a 20 61 6c 6c  e initial.** all
14050 6f 63 61 74 69 6f 6e 2c 20 74 68 65 6e 20 53 51  ocation, then SQ
14060 4c 69 74 65 20 67 6f 65 73 20 74 6f 20 5b 73 71  Lite goes to [sq
14070 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20  lite3_malloc()] 
14080 73 65 70 61 72 61 74 65 6c 79 20 66 6f 72 20 65  separately for e
14090 61 63 68 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 61  ach.** additiona
140a0 6c 20 63 61 63 68 65 20 6c 69 6e 65 2e 20 3c 2f  l cache line. </
140b0 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
140c0 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 5d 5d  TE_CONFIG_HEAP]]
140d0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
140e0 49 47 5f 48 45 41 50 3c 2f 64 74 3e 0a 2a 2a 20  IG_HEAP</dt>.** 
140f0 3c 64 64 3e 20 5e 54 68 65 20 53 51 4c 49 54 45  <dd> ^The SQLITE
14100 5f 43 4f 4e 46 49 47 5f 48 45 41 50 20 6f 70 74  _CONFIG_HEAP opt
14110 69 6f 6e 20 73 70 65 63 69 66 69 65 73 20 61 20  ion specifies a 
14120 73 74 61 74 69 63 20 6d 65 6d 6f 72 79 20 62 75  static memory bu
14130 66 66 65 72 20 0a 2a 2a 20 74 68 61 74 20 53 51  ffer .** that SQ
14140 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20 66 6f  Lite will use fo
14150 72 20 61 6c 6c 20 6f 66 20 69 74 73 20 64 79 6e  r all of its dyn
14160 61 6d 69 63 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  amic memory allo
14170 63 61 74 69 6f 6e 20 6e 65 65 64 73 0a 2a 2a 20  cation needs.** 
14180 62 65 79 6f 6e 64 20 74 68 6f 73 65 20 70 72 6f  beyond those pro
14190 76 69 64 65 64 20 66 6f 72 20 62 79 20 5b 53 51  vided for by [SQ
141a0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41  LITE_CONFIG_SCRA
141b0 54 43 48 5d 20 61 6e 64 0a 2a 2a 20 5b 53 51 4c  TCH] and.** [SQL
141c0 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43  ITE_CONFIG_PAGEC
141d0 41 43 48 45 5d 2e 0a 2a 2a 20 5e 54 68 65 20 53  ACHE]..** ^The S
141e0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41  QLITE_CONFIG_HEA
141f0 50 20 6f 70 74 69 6f 6e 20 69 73 20 6f 6e 6c 79  P option is only
14200 20 61 76 61 69 6c 61 62 6c 65 20 69 66 20 53 51   available if SQ
14210 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  Lite is compiled
14220 0a 2a 2a 20 77 69 74 68 20 65 69 74 68 65 72 20  .** with either 
14230 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d  [SQLITE_ENABLE_M
14240 45 4d 53 59 53 33 5d 20 6f 72 20 5b 53 51 4c 49  EMSYS3] or [SQLI
14250 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53 59 53  TE_ENABLE_MEMSYS
14260 35 5d 20 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a  5] and returns.*
14270 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d  * [SQLITE_ERROR]
14280 20 69 66 20 69 6e 76 6f 6b 65 64 20 6f 74 68 65   if invoked othe
14290 72 77 69 73 65 2e 0a 2a 2a 20 5e 54 68 65 72 65  rwise..** ^There
142a0 20 61 72 65 20 74 68 72 65 65 20 61 72 67 75 6d   are three argum
142b0 65 6e 74 73 20 74 6f 20 53 51 4c 49 54 45 5f 43  ents to SQLITE_C
142c0 4f 4e 46 49 47 5f 48 45 41 50 3a 0a 2a 2a 20 41  ONFIG_HEAP:.** A
142d0 6e 20 38 2d 62 79 74 65 20 61 6c 69 67 6e 65 64  n 8-byte aligned
142e0 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20   pointer to the 
142f0 6d 65 6d 6f 72 79 2c 0a 2a 2a 20 74 68 65 20 6e  memory,.** the n
14300 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69  umber of bytes i
14310 6e 20 74 68 65 20 6d 65 6d 6f 72 79 20 62 75 66  n the memory buf
14320 66 65 72 2c 20 61 6e 64 20 74 68 65 20 6d 69 6e  fer, and the min
14330 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  imum allocation 
14340 73 69 7a 65 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  size..** ^If the
14350 20 66 69 72 73 74 20 70 6f 69 6e 74 65 72 20 28   first pointer (
14360 74 68 65 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74  the memory point
14370 65 72 29 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65  er) is NULL, the
14380 6e 20 53 51 4c 69 74 65 20 72 65 76 65 72 74 73  n SQLite reverts
14390 0a 2a 2a 20 74 6f 20 75 73 69 6e 67 20 69 74 73  .** to using its
143a0 20 64 65 66 61 75 6c 74 20 6d 65 6d 6f 72 79 20   default memory 
143b0 61 6c 6c 6f 63 61 74 6f 72 20 28 74 68 65 20 73  allocator (the s
143c0 79 73 74 65 6d 20 6d 61 6c 6c 6f 63 28 29 20 69  ystem malloc() i
143d0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 29 2c 0a  mplementation),.
143e0 2a 2a 20 75 6e 64 6f 69 6e 67 20 61 6e 79 20 70  ** undoing any p
143f0 72 69 6f 72 20 69 6e 76 6f 63 61 74 69 6f 6e 20  rior invocation 
14400 6f 66 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  of [SQLITE_CONFI
14410 47 5f 4d 41 4c 4c 4f 43 5d 2e 20 20 5e 49 66 20  G_MALLOC].  ^If 
14420 74 68 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 70 6f  the.** memory po
14430 69 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e 55 4c  inter is not NUL
14440 4c 20 74 68 65 6e 20 74 68 65 20 61 6c 74 65 72  L then the alter
14450 6e 61 74 69 76 65 20 6d 65 6d 6f 72 79 0a 2a 2a  native memory.**
14460 20 61 6c 6c 6f 63 61 74 6f 72 20 69 73 20 65 6e   allocator is en
14470 67 61 67 65 64 20 74 6f 20 68 61 6e 64 6c 65 20  gaged to handle 
14480 61 6c 6c 20 6f 66 20 53 51 4c 69 74 65 73 20 6d  all of SQLites m
14490 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
144a0 20 6e 65 65 64 73 2e 0a 2a 2a 20 54 68 65 20 66   needs..** The f
144b0 69 72 73 74 20 70 6f 69 6e 74 65 72 20 28 74 68  irst pointer (th
144c0 65 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72  e memory pointer
144d0 29 20 6d 75 73 74 20 62 65 20 61 6c 69 67 6e 65  ) must be aligne
144e0 64 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 0a 2a  d to an 8-byte.*
144f0 2a 20 62 6f 75 6e 64 61 72 79 20 6f 72 20 73 75  * boundary or su
14500 62 73 65 71 75 65 6e 74 20 62 65 68 61 76 69 6f  bsequent behavio
14510 72 20 6f 66 20 53 51 4c 69 74 65 20 77 69 6c 6c  r of SQLite will
14520 20 62 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a   be undefined..*
14530 2a 20 54 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c  * The minimum al
14540 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20 69 73  location size is
14550 20 63 61 70 70 65 64 20 61 74 20 32 2a 2a 31 32   capped at 2**12
14560 2e 20 52 65 61 73 6f 6e 61 62 6c 65 20 76 61 6c  . Reasonable val
14570 75 65 73 0a 2a 2a 20 66 6f 72 20 74 68 65 20 6d  ues.** for the m
14580 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f  inimum allocatio
14590 6e 20 73 69 7a 65 20 61 72 65 20 32 2a 2a 35 20  n size are 2**5 
145a0 74 68 72 6f 75 67 68 20 32 2a 2a 38 2e 3c 2f 64  through 2**8.</d
145b0 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
145c0 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 5d 5d  E_CONFIG_MUTEX]]
145d0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
145e0 49 47 5f 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a  IG_MUTEX</dt>.**
145f0 20 3c 64 64 3e 20 5e 28 54 68 65 20 53 51 4c 49   <dd> ^(The SQLI
14600 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 20  TE_CONFIG_MUTEX 
14610 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73  option takes a s
14620 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77  ingle argument w
14630 68 69 63 68 20 69 73 20 61 0a 2a 2a 20 70 6f 69  hich is a.** poi
14640 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61  nter to an insta
14650 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  nce of the [sqli
14660 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64  te3_mutex_method
14670 73 5d 20 73 74 72 75 63 74 75 72 65 2e 0a 2a 2a  s] structure..**
14680 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 73 70   The argument sp
14690 65 63 69 66 69 65 73 20 61 6c 74 65 72 6e 61 74  ecifies alternat
146a0 69 76 65 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 75  ive low-level mu
146b0 74 65 78 20 72 6f 75 74 69 6e 65 73 20 74 6f 20  tex routines to 
146c0 62 65 20 75 73 65 64 0a 2a 2a 20 69 6e 20 70 6c  be used.** in pl
146d0 61 63 65 20 74 68 65 20 6d 75 74 65 78 20 72 6f  ace the mutex ro
146e0 75 74 69 6e 65 73 20 62 75 69 6c 74 20 69 6e 74  utines built int
146f0 6f 20 53 51 4c 69 74 65 2e 29 5e 20 20 5e 53 51  o SQLite.)^  ^SQ
14700 4c 69 74 65 20 6d 61 6b 65 73 20 61 20 63 6f 70  Lite makes a cop
14710 79 20 6f 66 0a 2a 2a 20 74 68 65 20 63 6f 6e 74  y of.** the cont
14720 65 6e 74 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  ent of the [sqli
14730 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64  te3_mutex_method
14740 73 5d 20 73 74 72 75 63 74 75 72 65 20 62 65 66  s] structure bef
14750 6f 72 65 20 74 68 65 20 63 61 6c 6c 20 74 6f 0a  ore the call to.
14760 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  ** [sqlite3_conf
14770 69 67 28 29 5d 20 72 65 74 75 72 6e 73 2e 20 5e  ig()] returns. ^
14780 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  If SQLite is com
14790 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68  piled with.** th
147a0 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44  e [SQLITE_THREAD
147b0 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48  SAFE | SQLITE_TH
147c0 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70  READSAFE=0] comp
147d0 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20  ile-time option 
147e0 74 68 65 6e 0a 2a 2a 20 74 68 65 20 65 6e 74 69  then.** the enti
147f0 72 65 20 6d 75 74 65 78 69 6e 67 20 73 75 62 73  re mutexing subs
14800 79 73 74 65 6d 20 69 73 20 6f 6d 69 74 74 65 64  ystem is omitted
14810 20 66 72 6f 6d 20 74 68 65 20 62 75 69 6c 64 20   from the build 
14820 61 6e 64 20 68 65 6e 63 65 20 63 61 6c 6c 73 20  and hence calls 
14830 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  to.** [sqlite3_c
14840 6f 6e 66 69 67 28 29 5d 20 77 69 74 68 20 74 68  onfig()] with th
14850 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
14860 4d 55 54 45 58 20 63 6f 6e 66 69 67 75 72 61 74  MUTEX configurat
14870 69 6f 6e 20 6f 70 74 69 6f 6e 20 77 69 6c 6c 0a  ion option will.
14880 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  ** return [SQLIT
14890 45 5f 45 52 52 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a  E_ERROR].</dd>.*
148a0 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
148b0 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 5d 5d 20  NFIG_GETMUTEX]] 
148c0 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
148d0 47 5f 47 45 54 4d 55 54 45 58 3c 2f 64 74 3e 0a  G_GETMUTEX</dt>.
148e0 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 53 51  ** <dd> ^(The SQ
148f0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d  LITE_CONFIG_GETM
14900 55 54 45 58 20 6f 70 74 69 6f 6e 20 74 61 6b 65  UTEX option take
14910 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d  s a single argum
14920 65 6e 74 20 77 68 69 63 68 0a 2a 2a 20 69 73 20  ent which.** is 
14930 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  a pointer to an 
14940 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20  instance of the 
14950 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d  [sqlite3_mutex_m
14960 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72  ethods] structur
14970 65 2e 20 20 54 68 65 0a 2a 2a 20 5b 73 71 6c 69  e.  The.** [sqli
14980 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64  te3_mutex_method
14990 73 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20  s].** structure 
149a0 69 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20 74  is filled with t
149b0 68 65 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66  he currently def
149c0 69 6e 65 64 20 6d 75 74 65 78 20 72 6f 75 74 69  ined mutex routi
149d0 6e 65 73 2e 29 5e 0a 2a 2a 20 54 68 69 73 20 6f  nes.)^.** This o
149e0 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 73 65  ption can be use
149f0 64 20 74 6f 20 6f 76 65 72 6c 6f 61 64 20 74 68  d to overload th
14a00 65 20 64 65 66 61 75 6c 74 20 6d 75 74 65 78 20  e default mutex 
14a10 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72 6f  allocation.** ro
14a20 75 74 69 6e 65 73 20 77 69 74 68 20 61 20 77 72  utines with a wr
14a30 61 70 70 65 72 20 75 73 65 64 20 74 6f 20 74 72  apper used to tr
14a40 61 63 6b 20 6d 75 74 65 78 20 75 73 61 67 65 20  ack mutex usage 
14a50 66 6f 72 20 70 65 72 66 6f 72 6d 61 6e 63 65 0a  for performance.
14a60 2a 2a 20 70 72 6f 66 69 6c 69 6e 67 20 6f 72 20  ** profiling or 
14a70 74 65 73 74 69 6e 67 2c 20 66 6f 72 20 65 78 61  testing, for exa
14a80 6d 70 6c 65 2e 20 20 20 5e 49 66 20 53 51 4c 69  mple.   ^If SQLi
14a90 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77  te is compiled w
14aa0 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49  ith.** the [SQLI
14ab0 54 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20  TE_THREADSAFE | 
14ac0 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
14ad0 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  E=0] compile-tim
14ae0 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a  e option then.**
14af0 20 74 68 65 20 65 6e 74 69 72 65 20 6d 75 74 65   the entire mute
14b00 78 69 6e 67 20 73 75 62 73 79 73 74 65 6d 20 69  xing subsystem i
14b10 73 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 74  s omitted from t
14b20 68 65 20 62 75 69 6c 64 20 61 6e 64 20 68 65 6e  he build and hen
14b30 63 65 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b  ce calls to.** [
14b40 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
14b50 5d 20 77 69 74 68 20 74 68 65 20 53 51 4c 49 54  ] with the SQLIT
14b60 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45  E_CONFIG_GETMUTE
14b70 58 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  X configuration 
14b80 6f 70 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 72  option will.** r
14b90 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52  eturn [SQLITE_ER
14ba0 52 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  ROR].</dd>.**.**
14bb0 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
14bc0 5f 4c 4f 4f 4b 41 53 49 44 45 5d 5d 20 3c 64 74  _LOOKASIDE]] <dt
14bd0 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c  >SQLITE_CONFIG_L
14be0 4f 4f 4b 41 53 49 44 45 3c 2f 64 74 3e 0a 2a 2a  OOKASIDE</dt>.**
14bf0 20 3c 64 64 3e 20 5e 28 54 68 65 20 53 51 4c 49   <dd> ^(The SQLI
14c00 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53  TE_CONFIG_LOOKAS
14c10 49 44 45 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  IDE option takes
14c20 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 20 74   two arguments t
14c30 68 61 74 20 64 65 74 65 72 6d 69 6e 65 0a 2a 2a  hat determine.**
14c40 20 74 68 65 20 64 65 66 61 75 6c 74 20 73 69 7a   the default siz
14c50 65 20 6f 66 20 6c 6f 6f 6b 61 73 69 64 65 20 6d  e of lookaside m
14c60 65 6d 6f 72 79 20 6f 6e 20 65 61 63 68 20 5b 64  emory on each [d
14c70 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
14c80 6f 6e 5d 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73  on]..** The firs
14c90 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68  t argument is th
14ca0 65 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 65 61 63  e.** size of eac
14cb0 68 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66 66  h lookaside buff
14cc0 65 72 20 73 6c 6f 74 20 61 6e 64 20 74 68 65 20  er slot and the 
14cd0 73 65 63 6f 6e 64 20 69 73 20 74 68 65 20 6e 75  second is the nu
14ce0 6d 62 65 72 20 6f 66 0a 2a 2a 20 73 6c 6f 74 73  mber of.** slots
14cf0 20 61 6c 6c 6f 63 61 74 65 64 20 74 6f 20 65 61   allocated to ea
14d00 63 68 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ch database conn
14d10 65 63 74 69 6f 6e 2e 29 5e 20 20 5e 28 53 51 4c  ection.)^  ^(SQL
14d20 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41  ITE_CONFIG_LOOKA
14d30 53 49 44 45 0a 2a 2a 20 73 65 74 73 20 74 68 65  SIDE.** sets the
14d40 20 3c 69 3e 64 65 66 61 75 6c 74 3c 2f 69 3e 20   <i>default</i> 
14d50 6c 6f 6f 6b 61 73 69 64 65 20 73 69 7a 65 2e 20  lookaside size. 
14d60 54 68 65 20 5b 53 51 4c 49 54 45 5f 44 42 43 4f  The [SQLITE_DBCO
14d70 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 0a  NFIG_LOOKASIDE].
14d80 2a 2a 20 6f 70 74 69 6f 6e 20 74 6f 20 5b 73 71  ** option to [sq
14d90 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28  lite3_db_config(
14da0 29 5d 20 63 61 6e 20 62 65 20 75 73 65 64 20 74  )] can be used t
14db0 6f 20 63 68 61 6e 67 65 20 74 68 65 20 6c 6f 6f  o change the loo
14dc0 6b 61 73 69 64 65 0a 2a 2a 20 63 6f 6e 66 69 67  kaside.** config
14dd0 75 72 61 74 69 6f 6e 20 6f 6e 20 69 6e 64 69 76  uration on indiv
14de0 69 64 75 61 6c 20 63 6f 6e 6e 65 63 74 69 6f 6e  idual connection
14df0 73 2e 29 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  s.)^ </dd>.**.**
14e00 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
14e10 5f 50 43 41 43 48 45 32 5d 5d 20 3c 64 74 3e 53  _PCACHE2]] <dt>S
14e20 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41  QLITE_CONFIG_PCA
14e30 43 48 45 32 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  CHE2</dt>.** <dd
14e40 3e 20 5e 28 54 68 65 20 53 51 4c 49 54 45 5f 43  > ^(The SQLITE_C
14e50 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 20 6f 70  ONFIG_PCACHE2 op
14e60 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e  tion takes a sin
14e70 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69  gle argument whi
14e80 63 68 20 69 73 20 0a 2a 2a 20 61 20 70 6f 69 6e  ch is .** a poin
14e90 74 65 72 20 74 6f 20 61 6e 20 5b 73 71 6c 69 74  ter to an [sqlit
14ea0 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64  e3_pcache_method
14eb0 73 32 5d 20 6f 62 6a 65 63 74 2e 20 20 54 68 69  s2] object.  Thi
14ec0 73 20 6f 62 6a 65 63 74 20 73 70 65 63 69 66 69  s object specifi
14ed0 65 73 0a 2a 2a 20 74 68 65 20 69 6e 74 65 72 66  es.** the interf
14ee0 61 63 65 20 74 6f 20 61 20 63 75 73 74 6f 6d 20  ace to a custom 
14ef0 70 61 67 65 20 63 61 63 68 65 20 69 6d 70 6c 65  page cache imple
14f00 6d 65 6e 74 61 74 69 6f 6e 2e 29 5e 0a 2a 2a 20  mentation.)^.** 
14f10 5e 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 61 20  ^SQLite makes a 
14f20 63 6f 70 79 20 6f 66 20 74 68 65 20 5b 73 71 6c  copy of the [sql
14f30 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68  ite3_pcache_meth
14f40 6f 64 73 32 5d 20 6f 62 6a 65 63 74 2e 3c 2f 64  ods2] object.</d
14f50 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
14f60 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43  E_CONFIG_GETPCAC
14f70 48 45 32 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45  HE2]] <dt>SQLITE
14f80 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48  _CONFIG_GETPCACH
14f90 45 32 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  E2</dt>.** <dd> 
14fa0 5e 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e  ^(The SQLITE_CON
14fb0 46 49 47 5f 47 45 54 50 43 41 43 48 45 32 20 6f  FIG_GETPCACHE2 o
14fc0 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69  ption takes a si
14fd0 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68  ngle argument wh
14fe0 69 63 68 0a 2a 2a 20 69 73 20 61 20 70 6f 69 6e  ich.** is a poin
14ff0 74 65 72 20 74 6f 20 61 6e 20 5b 73 71 6c 69 74  ter to an [sqlit
15000 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64  e3_pcache_method
15010 73 32 5d 20 6f 62 6a 65 63 74 2e 20 20 53 51 4c  s2] object.  SQL
15020 69 74 65 20 63 6f 70 69 65 73 20 6f 66 0a 2a 2a  ite copies of.**
15030 20 74 68 65 20 63 75 72 72 65 6e 74 20 70 61 67   the current pag
15040 65 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e  e cache implemen
15050 74 61 74 69 6f 6e 20 69 6e 74 6f 20 74 68 61 74  tation into that
15060 20 6f 62 6a 65 63 74 2e 29 5e 20 3c 2f 64 64 3e   object.)^ </dd>
15070 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
15080 43 4f 4e 46 49 47 5f 4c 4f 47 5d 5d 20 3c 64 74  CONFIG_LOG]] <dt
15090 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c  >SQLITE_CONFIG_L
150a0 4f 47 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  OG</dt>.** <dd> 
150b0 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  The SQLITE_CONFI
150c0 47 5f 4c 4f 47 20 6f 70 74 69 6f 6e 20 69 73 20  G_LOG option is 
150d0 75 73 65 64 20 74 6f 20 63 6f 6e 66 69 67 75 72  used to configur
150e0 65 20 74 68 65 20 53 51 4c 69 74 65 0a 2a 2a 20  e the SQLite.** 
150f0 67 6c 6f 62 61 6c 20 5b 65 72 72 6f 72 20 6c 6f  global [error lo
15100 67 5d 2e 0a 2a 2a 20 28 5e 54 68 65 20 53 51 4c  g]..** (^The SQL
15110 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 6f  ITE_CONFIG_LOG o
15120 70 74 69 6f 6e 20 74 61 6b 65 73 20 74 77 6f 20  ption takes two 
15130 61 72 67 75 6d 65 6e 74 73 3a 20 61 20 70 6f 69  arguments: a poi
15140 6e 74 65 72 20 74 6f 20 61 0a 2a 2a 20 66 75 6e  nter to a.** fun
15150 63 74 69 6f 6e 20 77 69 74 68 20 61 20 63 61 6c  ction with a cal
15160 6c 20 73 69 67 6e 61 74 75 72 65 20 6f 66 20 76  l signature of v
15170 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 69 6e 74  oid(*)(void*,int
15180 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c 20 0a  ,const char*), .
15190 2a 2a 20 61 6e 64 20 61 20 70 6f 69 6e 74 65 72  ** and a pointer
151a0 20 74 6f 20 76 6f 69 64 2e 20 5e 49 66 20 74 68   to void. ^If th
151b0 65 20 66 75 6e 63 74 69 6f 6e 20 70 6f 69 6e 74  e function point
151c0 65 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20  er is not NULL, 
151d0 69 74 20 69 73 0a 2a 2a 20 69 6e 76 6f 6b 65 64  it is.** invoked
151e0 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 67   by [sqlite3_log
151f0 28 29 5d 20 74 6f 20 70 72 6f 63 65 73 73 20 65  ()] to process e
15200 61 63 68 20 6c 6f 67 67 69 6e 67 20 65 76 65 6e  ach logging even
15210 74 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 66  t.  ^If the.** f
15220 75 6e 63 74 69 6f 6e 20 70 6f 69 6e 74 65 72 20  unction pointer 
15230 69 73 20 4e 55 4c 4c 2c 20 74 68 65 20 5b 73 71  is NULL, the [sq
15240 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20 69 6e 74  lite3_log()] int
15250 65 72 66 61 63 65 20 62 65 63 6f 6d 65 73 20 61  erface becomes a
15260 20 6e 6f 2d 6f 70 2e 0a 2a 2a 20 5e 54 68 65 20   no-op..** ^The 
15270 76 6f 69 64 20 70 6f 69 6e 74 65 72 20 74 68 61  void pointer tha
15280 74 20 69 73 20 74 68 65 20 73 65 63 6f 6e 64 20  t is the second 
15290 61 72 67 75 6d 65 6e 74 20 74 6f 20 53 51 4c 49  argument to SQLI
152a0 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 69 73  TE_CONFIG_LOG is
152b0 0a 2a 2a 20 70 61 73 73 65 64 20 74 68 72 6f 75  .** passed throu
152c0 67 68 20 61 73 20 74 68 65 20 66 69 72 73 74 20  gh as the first 
152d0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
152e0 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
152f0 69 6e 65 64 20 6c 6f 67 67 65 72 0a 2a 2a 20 66  ined logger.** f
15300 75 6e 63 74 69 6f 6e 20 77 68 65 6e 65 76 65 72  unction whenever
15310 20 74 68 61 74 20 66 75 6e 63 74 69 6f 6e 20 69   that function i
15320 73 20 69 6e 76 6f 6b 65 64 2e 20 20 5e 54 68 65  s invoked.  ^The
15330 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
15340 72 20 74 6f 0a 2a 2a 20 74 68 65 20 6c 6f 67 67  r to.** the logg
15350 65 72 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 61  er function is a
15360 20 63 6f 70 79 20 6f 66 20 74 68 65 20 66 69 72   copy of the fir
15370 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  st parameter to 
15380 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e  the correspondin
15390 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6c 6f  g.** [sqlite3_lo
153a0 67 28 29 5d 20 63 61 6c 6c 20 61 6e 64 20 69 73  g()] call and is
153b0 20 69 6e 74 65 6e 64 65 64 20 74 6f 20 62 65 20   intended to be 
153c0 61 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d 20  a [result code] 
153d0 6f 72 20 61 6e 0a 2a 2a 20 5b 65 78 74 65 6e 64  or an.** [extend
153e0 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 5d 2e  ed result code].
153f0 20 20 5e 54 68 65 20 74 68 69 72 64 20 70 61 72    ^The third par
15400 61 6d 65 74 65 72 20 70 61 73 73 65 64 20 74 6f  ameter passed to
15410 20 74 68 65 20 6c 6f 67 67 65 72 20 69 73 0a 2a   the logger is.*
15420 2a 20 6c 6f 67 20 6d 65 73 73 61 67 65 20 61 66  * log message af
15430 74 65 72 20 66 6f 72 6d 61 74 74 69 6e 67 20 76  ter formatting v
15440 69 61 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72  ia [sqlite3_snpr
15450 69 6e 74 66 28 29 5d 2e 0a 2a 2a 20 54 68 65 20  intf()]..** The 
15460 53 51 4c 69 74 65 20 6c 6f 67 67 69 6e 67 20 69  SQLite logging i
15470 6e 74 65 72 66 61 63 65 20 69 73 20 6e 6f 74 20  nterface is not 
15480 72 65 65 6e 74 72 61 6e 74 3b 20 74 68 65 20 6c  reentrant; the l
15490 6f 67 67 65 72 20 66 75 6e 63 74 69 6f 6e 0a 2a  ogger function.*
154a0 2a 20 73 75 70 70 6c 69 65 64 20 62 79 20 74 68  * supplied by th
154b0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75  e application mu
154c0 73 74 20 6e 6f 74 20 69 6e 76 6f 6b 65 20 61 6e  st not invoke an
154d0 79 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61  y SQLite interfa
154e0 63 65 2e 0a 2a 2a 20 49 6e 20 61 20 6d 75 6c 74  ce..** In a mult
154f0 69 2d 74 68 72 65 61 64 65 64 20 61 70 70 6c 69  i-threaded appli
15500 63 61 74 69 6f 6e 2c 20 74 68 65 20 61 70 70 6c  cation, the appl
15510 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
15520 6c 6f 67 67 65 72 0a 2a 2a 20 66 75 6e 63 74 69  logger.** functi
15530 6f 6e 20 6d 75 73 74 20 62 65 20 74 68 72 65 61  on must be threa
15540 64 73 61 66 65 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a  dsafe. </dd>.**.
15550 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
15560 49 47 5f 55 52 49 5d 5d 20 3c 64 74 3e 53 51 4c  IG_URI]] <dt>SQL
15570 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 0a 2a  ITE_CONFIG_URI.*
15580 2a 20 3c 64 64 3e 5e 28 54 68 65 20 53 51 4c 49  * <dd>^(The SQLI
15590 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 20 6f 70  TE_CONFIG_URI op
155a0 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e  tion takes a sin
155b0 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 6f 66 20  gle argument of 
155c0 74 79 70 65 20 69 6e 74 2e 0a 2a 2a 20 49 66 20  type int..** If 
155d0 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 55  non-zero, then U
155e0 52 49 20 68 61 6e 64 6c 69 6e 67 20 69 73 20 67  RI handling is g
155f0 6c 6f 62 61 6c 6c 79 20 65 6e 61 62 6c 65 64 2e  lobally enabled.
15600 20 49 66 20 74 68 65 20 70 61 72 61 6d 65 74 65   If the paramete
15610 72 20 69 73 20 7a 65 72 6f 2c 0a 2a 2a 20 74 68  r is zero,.** th
15620 65 6e 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 20  en URI handling 
15630 69 73 20 67 6c 6f 62 61 6c 6c 79 20 64 69 73 61  is globally disa
15640 62 6c 65 64 2e 29 5e 20 5e 49 66 20 55 52 49 20  bled.)^ ^If URI 
15650 68 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62  handling is glob
15660 61 6c 6c 79 0a 2a 2a 20 65 6e 61 62 6c 65 64 2c  ally.** enabled,
15670 20 61 6c 6c 20 66 69 6c 65 6e 61 6d 65 73 20 70   all filenames p
15680 61 73 73 65 64 20 74 6f 20 5b 73 71 6c 69 74 65  assed to [sqlite
15690 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69  3_open()], [sqli
156a0 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c 0a  te3_open_v2()],.
156b0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ** [sqlite3_open
156c0 31 36 28 29 5d 20 6f 72 0a 2a 2a 20 73 70 65 63  16()] or.** spec
156d0 69 66 69 65 64 20 61 73 20 70 61 72 74 20 6f 66  ified as part of
156e0 20 5b 41 54 54 41 43 48 5d 20 63 6f 6d 6d 61 6e   [ATTACH] comman
156f0 64 73 20 61 72 65 20 69 6e 74 65 72 70 72 65 74  ds are interpret
15700 65 64 20 61 73 20 55 52 49 73 2c 20 72 65 67 61  ed as URIs, rega
15710 72 64 6c 65 73 73 0a 2a 2a 20 6f 66 20 77 68 65  rdless.** of whe
15720 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20  ther or not the 
15730 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49  [SQLITE_OPEN_URI
15740 5d 20 66 6c 61 67 20 69 73 20 73 65 74 20 77 68  ] flag is set wh
15750 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 0a  en the database.
15760 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  ** connection is
15770 20 6f 70 65 6e 65 64 2e 20 5e 49 66 20 69 74 20   opened. ^If it 
15780 69 73 20 67 6c 6f 62 61 6c 6c 79 20 64 69 73 61  is globally disa
15790 62 6c 65 64 2c 20 66 69 6c 65 6e 61 6d 65 73 20  bled, filenames 
157a0 61 72 65 0a 2a 2a 20 6f 6e 6c 79 20 69 6e 74 65  are.** only inte
157b0 72 70 72 65 74 65 64 20 61 73 20 55 52 49 73 20  rpreted as URIs 
157c0 69 66 20 74 68 65 20 53 51 4c 49 54 45 5f 4f 50  if the SQLITE_OP
157d0 45 4e 5f 55 52 49 20 66 6c 61 67 20 69 73 20 73  EN_URI flag is s
157e0 65 74 20 77 68 65 6e 20 74 68 65 0a 2a 2a 20 64  et when the.** d
157f0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
15800 6f 6e 20 69 73 20 6f 70 65 6e 65 64 2e 20 5e 28  on is opened. ^(
15810 42 79 20 64 65 66 61 75 6c 74 2c 20 55 52 49 20  By default, URI 
15820 68 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62  handling is glob
15830 61 6c 6c 79 0a 2a 2a 20 64 69 73 61 62 6c 65 64  ally.** disabled
15840 2e 20 54 68 65 20 64 65 66 61 75 6c 74 20 76 61  . The default va
15850 6c 75 65 20 6d 61 79 20 62 65 20 63 68 61 6e 67  lue may be chang
15860 65 64 20 62 79 20 63 6f 6d 70 69 6c 69 6e 67 20  ed by compiling 
15870 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c  with the.** [SQL
15880 49 54 45 5f 55 53 45 5f 55 52 49 5d 20 73 79 6d  ITE_USE_URI] sym
15890 62 6f 6c 20 64 65 66 69 6e 65 64 2e 29 5e 0a 2a  bol defined.)^.*
158a0 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
158b0 4e 46 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49 4e  NFIG_COVERING_IN
158c0 44 45 58 5f 53 43 41 4e 5d 5d 20 3c 64 74 3e 53  DEX_SCAN]] <dt>S
158d0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56  QLITE_CONFIG_COV
158e0 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e  ERING_INDEX_SCAN
158f0 0a 2a 2a 20 3c 64 64 3e 5e 54 68 65 20 53 51 4c  .** <dd>^The SQL
15900 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56 45 52  ITE_CONFIG_COVER
15910 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 20 6f  ING_INDEX_SCAN o
15920 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69  ption takes a si
15930 6e 67 6c 65 20 69 6e 74 65 67 65 72 0a 2a 2a 20  ngle integer.** 
15940 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69  argument which i
15950 73 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73  s interpreted as
15960 20 61 20 62 6f 6f 6c 65 61 6e 20 69 6e 20 6f 72   a boolean in or
15970 64 65 72 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72  der to enable or
15980 20 64 69 73 61 62 6c 65 0a 2a 2a 20 74 68 65 20   disable.** the 
15990 75 73 65 20 6f 66 20 63 6f 76 65 72 69 6e 67 20  use of covering 
159a0 69 6e 64 69 63 65 73 20 66 6f 72 20 66 75 6c 6c  indices for full
159b0 20 74 61 62 6c 65 20 73 63 61 6e 73 20 69 6e 20   table scans in 
159c0 74 68 65 20 71 75 65 72 79 20 6f 70 74 69 6d 69  the query optimi
159d0 7a 65 72 2e 0a 2a 2a 20 5e 54 68 65 20 64 65 66  zer..** ^The def
159e0 61 75 6c 74 20 73 65 74 74 69 6e 67 20 69 73 20  ault setting is 
159f0 64 65 74 65 72 6d 69 6e 65 64 0a 2a 2a 20 62 79  determined.** by
15a00 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 41 4c 4c   the [SQLITE_ALL
15a10 4f 57 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45  OW_COVERING_INDE
15a20 58 5f 53 43 41 4e 5d 20 63 6f 6d 70 69 6c 65 2d  X_SCAN] compile-
15a30 74 69 6d 65 20 6f 70 74 69 6f 6e 2c 20 6f 72 20  time option, or 
15a40 69 73 20 22 6f 6e 22 0a 2a 2a 20 69 66 20 74 68  is "on".** if th
15a50 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  at compile-time 
15a60 6f 70 74 69 6f 6e 20 69 73 20 6f 6d 69 74 74 65  option is omitte
15a70 64 2e 0a 2a 2a 20 54 68 65 20 61 62 69 6c 69 74  d..** The abilit
15a80 79 20 74 6f 20 64 69 73 61 62 6c 65 20 74 68 65  y to disable the
15a90 20 75 73 65 20 6f 66 20 63 6f 76 65 72 69 6e 67   use of covering
15aa0 20 69 6e 64 69 63 65 73 20 66 6f 72 20 66 75 6c   indices for ful
15ab0 6c 20 74 61 62 6c 65 20 73 63 61 6e 73 0a 2a 2a  l table scans.**
15ac0 20 69 73 20 62 65 63 61 75 73 65 20 73 6f 6d 65   is because some
15ad0 20 69 6e 63 6f 72 72 65 63 74 6c 79 20 63 6f 64   incorrectly cod
15ae0 65 64 20 6c 65 67 61 63 79 20 61 70 70 6c 69 63  ed legacy applic
15af0 61 74 69 6f 6e 73 20 6d 69 67 68 74 20 6d 61 6c  ations might mal
15b00 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 77 68 65 6e  function.** when
15b10 20 74 68 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f   the optimizatio
15b20 6e 20 69 73 20 65 6e 61 62 6c 65 64 2e 20 20 50  n is enabled.  P
15b30 72 6f 76 69 64 69 6e 67 20 74 68 65 20 61 62 69  roviding the abi
15b40 6c 69 74 79 20 74 6f 0a 2a 2a 20 64 69 73 61 62  lity to.** disab
15b50 6c 65 20 74 68 65 20 6f 70 74 69 6d 69 7a 61 74  le the optimizat
15b60 69 6f 6e 20 61 6c 6c 6f 77 73 20 74 68 65 20 6f  ion allows the o
15b70 6c 64 65 72 2c 20 62 75 67 67 79 20 61 70 70 6c  lder, buggy appl
15b80 69 63 61 74 69 6f 6e 20 63 6f 64 65 20 74 6f 20  ication code to 
15b90 77 6f 72 6b 0a 2a 2a 20 77 69 74 68 6f 75 74 20  work.** without 
15ba0 63 68 61 6e 67 65 20 65 76 65 6e 20 77 69 74 68  change even with
15bb0 20 6e 65 77 65 72 20 76 65 72 73 69 6f 6e 73 20   newer versions 
15bc0 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a  of SQLite..**.**
15bd0 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
15be0 5f 50 43 41 43 48 45 5d 5d 20 5b 5b 53 51 4c 49  _PCACHE]] [[SQLI
15bf0 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41  TE_CONFIG_GETPCA
15c00 43 48 45 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c  CHE]].** <dt>SQL
15c10 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48  ITE_CONFIG_PCACH
15c20 45 20 61 6e 64 20 53 51 4c 49 54 45 5f 43 4f 4e  E and SQLITE_CON
15c30 46 49 47 5f 47 45 54 50 43 41 43 48 45 0a 2a 2a  FIG_GETPCACHE.**
15c40 20 3c 64 64 3e 20 54 68 65 73 65 20 6f 70 74 69   <dd> These opti
15c50 6f 6e 73 20 61 72 65 20 6f 62 73 6f 6c 65 74 65  ons are obsolete
15c60 20 61 6e 64 20 73 68 6f 75 6c 64 20 6e 6f 74 20   and should not 
15c70 62 65 20 75 73 65 64 20 62 79 20 6e 65 77 20 63  be used by new c
15c80 6f 64 65 2e 0a 2a 2a 20 54 68 65 79 20 61 72 65  ode..** They are
15c90 20 72 65 74 61 69 6e 65 64 20 66 6f 72 20 62 61   retained for ba
15ca0 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62  ckwards compatib
15cb0 69 6c 69 74 79 20 62 75 74 20 61 72 65 20 6e 6f  ility but are no
15cc0 77 20 6e 6f 2d 6f 70 73 2e 0a 2a 2a 20 3c 2f 64  w no-ops..** </d
15cd0 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
15ce0 45 5f 43 4f 4e 46 49 47 5f 53 51 4c 4c 4f 47 5d  E_CONFIG_SQLLOG]
15cf0 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  ].** <dt>SQLITE_
15d00 43 4f 4e 46 49 47 5f 53 51 4c 4c 4f 47 0a 2a 2a  CONFIG_SQLLOG.**
15d10 20 3c 64 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e   <dd>This option
15d20 20 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62   is only availab
15d30 6c 65 20 69 66 20 73 71 6c 69 74 65 20 69 73 20  le if sqlite is 
15d40 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68  compiled with th
15d50 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41  e.** [SQLITE_ENA
15d60 42 4c 45 5f 53 51 4c 4c 4f 47 5d 20 70 72 65 2d  BLE_SQLLOG] pre-
15d70 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 20  processor macro 
15d80 64 65 66 69 6e 65 64 2e 20 54 68 65 20 66 69 72  defined. The fir
15d90 73 74 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75  st argument shou
15da0 6c 64 0a 2a 2a 20 62 65 20 61 20 70 6f 69 6e 74  ld.** be a point
15db0 65 72 20 74 6f 20 61 20 66 75 6e 63 74 69 6f 6e  er to a function
15dc0 20 6f 66 20 74 79 70 65 20 76 6f 69 64 28 2a 29   of type void(*)
15dd0 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 2a 2c  (void*,sqlite3*,
15de0 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e 74  const char*, int
15df0 29 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64  )..** The second
15e00 20 73 68 6f 75 6c 64 20 62 65 20 6f 66 20 74 79   should be of ty
15e10 70 65 20 28 76 6f 69 64 2a 29 2e 20 54 68 65 20  pe (void*). The 
15e20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f  callback is invo
15e30 6b 65 64 20 62 79 20 74 68 65 20 6c 69 62 72 61  ked by the libra
15e40 72 79 0a 2a 2a 20 69 6e 20 74 68 72 65 65 20 73  ry.** in three s
15e50 65 70 61 72 61 74 65 20 63 69 72 63 75 6d 73 74  eparate circumst
15e60 61 6e 63 65 73 2c 20 69 64 65 6e 74 69 66 69 65  ances, identifie
15e70 64 20 62 79 20 74 68 65 20 76 61 6c 75 65 20 70  d by the value p
15e80 61 73 73 65 64 20 61 73 20 74 68 65 0a 2a 2a 20  assed as the.** 
15e90 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
15ea0 2e 20 49 66 20 74 68 65 20 66 6f 75 72 74 68 20  . If the fourth 
15eb0 70 61 72 61 6d 65 74 65 72 20 69 73 20 30 2c 20  parameter is 0, 
15ec0 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73  then the databas
15ed0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20  e connection.** 
15ee0 70 61 73 73 65 64 20 61 73 20 74 68 65 20 73 65  passed as the se
15ef0 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 68 61  cond argument ha
15f00 73 20 6a 75 73 74 20 62 65 65 6e 20 6f 70 65 6e  s just been open
15f10 65 64 2e 20 54 68 65 20 74 68 69 72 64 20 61 72  ed. The third ar
15f20 67 75 6d 65 6e 74 0a 2a 2a 20 70 6f 69 6e 74 73  gument.** points
15f30 20 74 6f 20 61 20 62 75 66 66 65 72 20 63 6f 6e   to a buffer con
15f40 74 61 69 6e 69 6e 67 20 74 68 65 20 6e 61 6d 65  taining the name
15f50 20 6f 66 20 74 68 65 20 6d 61 69 6e 20 64 61 74   of the main dat
15f60 61 62 61 73 65 20 66 69 6c 65 2e 20 49 66 20 74  abase file. If t
15f70 68 65 0a 2a 2a 20 66 6f 75 72 74 68 20 70 61 72  he.** fourth par
15f80 61 6d 65 74 65 72 20 69 73 20 31 2c 20 74 68 65  ameter is 1, the
15f90 6e 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  n the SQL statem
15fa0 65 6e 74 20 74 68 61 74 20 74 68 65 20 74 68 69  ent that the thi
15fb0 72 64 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20  rd parameter.** 
15fc0 70 6f 69 6e 74 73 20 74 6f 20 68 61 73 20 6a 75  points to has ju
15fd0 73 74 20 62 65 65 6e 20 65 78 65 63 75 74 65 64  st been executed
15fe0 2e 20 4f 72 2c 20 69 66 20 74 68 65 20 66 6f 75  . Or, if the fou
15ff0 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73  rth parameter is
16000 20 32 2c 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20   2, then.** the 
16010 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 65 69 6e 67  connection being
16020 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 73   passed as the s
16030 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
16040 69 73 20 62 65 69 6e 67 20 63 6c 6f 73 65 64 2e  is being closed.
16050 20 54 68 65 0a 2a 2a 20 74 68 69 72 64 20 70 61   The.** third pa
16060 72 61 6d 65 74 65 72 20 69 73 20 70 61 73 73 65  rameter is passe
16070 64 20 4e 55 4c 4c 20 49 6e 20 74 68 69 73 20 63  d NULL In this c
16080 61 73 65 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65  ase.  An example
16090 20 6f 66 20 75 73 69 6e 67 20 74 68 69 73 0a 2a   of using this.*
160a0 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  * configuration 
160b0 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 73 65  option can be se
160c0 65 6e 20 69 6e 20 74 68 65 20 22 74 65 73 74 5f  en in the "test_
160d0 73 71 6c 6c 6f 67 2e 63 22 20 73 6f 75 72 63 65  sqllog.c" source
160e0 20 66 69 6c 65 20 69 6e 0a 2a 2a 20 74 68 65 20   file in.** the 
160f0 63 61 6e 6f 6e 69 63 61 6c 20 53 51 4c 69 74 65  canonical SQLite
16100 20 73 6f 75 72 63 65 20 74 72 65 65 2e 3c 2f 64   source tree.</d
16110 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
16120 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f 53 49  E_CONFIG_MMAP_SI
16130 5a 45 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  ZE]].** <dt>SQLI
16140 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f 53  TE_CONFIG_MMAP_S
16150 49 5a 45 0a 2a 2a 20 3c 64 64 3e 5e 53 51 4c 49  IZE.** <dd>^SQLI
16160 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f 53  TE_CONFIG_MMAP_S
16170 49 5a 45 20 74 61 6b 65 73 20 74 77 6f 20 36 34  IZE takes two 64
16180 2d 62 69 74 20 69 6e 74 65 67 65 72 20 28 73 71  -bit integer (sq
16190 6c 69 74 65 33 5f 69 6e 74 36 34 29 20 76 61 6c  lite3_int64) val
161a0 75 65 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20  ues.** that are 
161b0 74 68 65 20 64 65 66 61 75 6c 74 20 6d 6d 61 70  the default mmap
161c0 20 73 69 7a 65 20 6c 69 6d 69 74 20 28 74 68 65   size limit (the
161d0 20 64 65 66 61 75 6c 74 20 73 65 74 74 69 6e 67   default setting
161e0 20 66 6f 72 0a 2a 2a 20 5b 50 52 41 47 4d 41 20   for.** [PRAGMA 
161f0 6d 6d 61 70 5f 73 69 7a 65 5d 29 20 61 6e 64 20  mmap_size]) and 
16200 74 68 65 20 6d 61 78 69 6d 75 6d 20 61 6c 6c 6f  the maximum allo
16210 77 65 64 20 6d 6d 61 70 20 73 69 7a 65 20 6c 69  wed mmap size li
16220 6d 69 74 2e 0a 2a 2a 20 5e 54 68 65 20 64 65 66  mit..** ^The def
16230 61 75 6c 74 20 73 65 74 74 69 6e 67 20 63 61 6e  ault setting can
16240 20 62 65 20 6f 76 65 72 72 69 64 64 65 6e 20 62   be overridden b
16250 79 20 65 61 63 68 20 64 61 74 61 62 61 73 65 20  y each database 
16260 63 6f 6e 6e 65 63 74 69 6f 6e 20 75 73 69 6e 67  connection using
16270 0a 2a 2a 20 65 69 74 68 65 72 20 74 68 65 20 5b  .** either the [
16280 50 52 41 47 4d 41 20 6d 6d 61 70 5f 73 69 7a 65  PRAGMA mmap_size
16290 5d 20 63 6f 6d 6d 61 6e 64 2c 20 6f 72 20 62 79  ] command, or by
162a0 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 53   using the.** [S
162b0 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41 50  QLITE_FCNTL_MMAP
162c0 5f 53 49 5a 45 5d 20 66 69 6c 65 20 63 6f 6e 74  _SIZE] file cont
162d0 72 6f 6c 2e 20 20 5e 28 54 68 65 20 6d 61 78 69  rol.  ^(The maxi
162e0 6d 75 6d 20 61 6c 6c 6f 77 65 64 20 6d 6d 61 70  mum allowed mmap
162f0 20 73 69 7a 65 0a 2a 2a 20 77 69 6c 6c 20 62 65   size.** will be
16300 20 73 69 6c 65 6e 74 6c 79 20 74 72 75 6e 63 61   silently trunca
16310 74 65 64 20 69 66 20 6e 65 63 65 73 73 61 72 79  ted if necessary
16320 20 73 6f 20 74 68 61 74 20 69 74 20 64 6f 65 73   so that it does
16330 20 6e 6f 74 20 65 78 63 65 65 64 20 74 68 65 0a   not exceed the.
16340 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  ** compile-time 
16350 6d 61 78 69 6d 75 6d 20 6d 6d 61 70 20 73 69 7a  maximum mmap siz
16360 65 20 73 65 74 20 62 79 20 74 68 65 0a 2a 2a 20  e set by the.** 
16370 5b 53 51 4c 49 54 45 5f 4d 41 58 5f 4d 4d 41 50  [SQLITE_MAX_MMAP
16380 5f 53 49 5a 45 5d 20 63 6f 6d 70 69 6c 65 2d 74  _SIZE] compile-t
16390 69 6d 65 20 6f 70 74 69 6f 6e 2e 29 5e 0a 2a 2a  ime option.)^.**
163a0 20 5e 49 66 20 65 69 74 68 65 72 20 61 72 67 75   ^If either argu
163b0 6d 65 6e 74 20 74 6f 20 74 68 69 73 20 6f 70 74  ment to this opt
163c0 69 6f 6e 20 69 73 20 6e 65 67 61 74 69 76 65 2c  ion is negative,
163d0 20 74 68 65 6e 20 74 68 61 74 20 61 72 67 75 6d   then that argum
163e0 65 6e 74 20 69 73 0a 2a 2a 20 63 68 61 6e 67 65  ent is.** change
163f0 64 20 74 6f 20 69 74 73 20 63 6f 6d 70 69 6c 65  d to its compile
16400 2d 74 69 6d 65 20 64 65 66 61 75 6c 74 2e 0a 2a  -time default..*
16410 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
16420 4e 46 49 47 5f 57 49 4e 33 32 5f 48 45 41 50 53  NFIG_WIN32_HEAPS
16430 49 5a 45 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c  IZE]].** <dt>SQL
16440 49 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32  ITE_CONFIG_WIN32
16450 5f 48 45 41 50 53 49 5a 45 0a 2a 2a 20 3c 64 64  _HEAPSIZE.** <dd
16460 3e 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e  >^The SQLITE_CON
16470 46 49 47 5f 57 49 4e 33 32 5f 48 45 41 50 53 49  FIG_WIN32_HEAPSI
16480 5a 45 20 6f 70 74 69 6f 6e 20 69 73 20 6f 6e 6c  ZE option is onl
16490 79 20 61 76 61 69 6c 61 62 6c 65 20 69 66 20 53  y available if S
164a0 51 4c 69 74 65 20 69 73 0a 2a 2a 20 63 6f 6d 70  QLite is.** comp
164b0 69 6c 65 64 20 66 6f 72 20 57 69 6e 64 6f 77 73  iled for Windows
164c0 20 77 69 74 68 20 74 68 65 20 5b 53 51 4c 49 54   with the [SQLIT
164d0 45 5f 57 49 4e 33 32 5f 4d 41 4c 4c 4f 43 5d 20  E_WIN32_MALLOC] 
164e0 70 72 65 2d 70 72 6f 63 65 73 73 6f 72 20 6d 61  pre-processor ma
164f0 63 72 6f 0a 2a 2a 20 64 65 66 69 6e 65 64 2e 20  cro.** defined. 
16500 5e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 57  ^SQLITE_CONFIG_W
16510 49 4e 33 32 5f 48 45 41 50 53 49 5a 45 20 74 61  IN32_HEAPSIZE ta
16520 6b 65 73 20 61 20 33 32 2d 62 69 74 20 75 6e 73  kes a 32-bit uns
16530 69 67 6e 65 64 20 69 6e 74 65 67 65 72 20 76 61  igned integer va
16540 6c 75 65 0a 2a 2a 20 74 68 61 74 20 73 70 65 63  lue.** that spec
16550 69 66 69 65 73 20 74 68 65 20 6d 61 78 69 6d 75  ifies the maximu
16560 6d 20 73 69 7a 65 20 6f 66 20 74 68 65 20 63 72  m size of the cr
16570 65 61 74 65 64 20 68 65 61 70 2e 0a 2a 2a 0a 2a  eated heap..**.*
16580 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
16590 47 5f 50 43 41 43 48 45 5f 48 44 52 53 5a 5d 5d  G_PCACHE_HDRSZ]]
165a0 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  .** <dt>SQLITE_C
165b0 4f 4e 46 49 47 5f 50 43 41 43 48 45 5f 48 44 52  ONFIG_PCACHE_HDR
165c0 53 5a 0a 2a 2a 20 3c 64 64 3e 5e 54 68 65 20 53  SZ.** <dd>^The S
165d0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41  QLITE_CONFIG_PCA
165e0 43 48 45 5f 48 44 52 53 5a 20 6f 70 74 69 6f 6e  CHE_HDRSZ option
165f0 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20   takes a single 
16600 70 61 72 61 6d 65 74 65 72 20 77 68 69 63 68 0a  parameter which.
16610 2a 2a 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20  ** is a pointer 
16620 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 61 6e  to an integer an
16630 64 20 77 72 69 74 65 73 20 69 6e 74 6f 20 74 68  d writes into th
16640 61 74 20 69 6e 74 65 67 65 72 20 74 68 65 20 6e  at integer the n
16650 75 6d 62 65 72 20 6f 66 20 65 78 74 72 61 0a 2a  umber of extra.*
16660 2a 20 62 79 74 65 73 20 70 65 72 20 70 61 67 65  * bytes per page
16670 20 72 65 71 75 69 72 65 64 20 66 6f 72 20 65 61   required for ea
16680 63 68 20 70 61 67 65 20 69 6e 20 5b 53 51 4c 49  ch page in [SQLI
16690 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41  TE_CONFIG_PAGECA
166a0 43 48 45 5d 2e 0a 2a 2a 20 54 68 65 20 61 6d 6f  CHE]..** The amo
166b0 75 6e 74 20 6f 66 20 65 78 74 72 61 20 73 70 61  unt of extra spa
166c0 63 65 20 72 65 71 75 69 72 65 64 20 63 61 6e 20  ce required can 
166d0 63 68 61 6e 67 65 20 64 65 70 65 6e 64 69 6e 67  change depending
166e0 20 6f 6e 20 74 68 65 20 63 6f 6d 70 69 6c 65 72   on the compiler
166f0 2c 0a 2a 2a 20 74 61 72 67 65 74 20 70 6c 61 74  ,.** target plat
16700 66 6f 72 6d 2c 20 61 6e 64 20 53 51 4c 69 74 65  form, and SQLite
16710 20 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20   version..**.** 
16720 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
16730 50 4d 41 53 5a 5d 5d 0a 2a 2a 20 3c 64 74 3e 53  PMASZ]].** <dt>S
16740 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 4d 41  QLITE_CONFIG_PMA
16750 53 5a 0a 2a 2a 20 3c 64 64 3e 5e 54 68 65 20 53  SZ.** <dd>^The S
16760 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 4d 41  QLITE_CONFIG_PMA
16770 53 5a 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  SZ option takes 
16780 61 20 73 69 6e 67 6c 65 20 70 61 72 61 6d 65 74  a single paramet
16790 65 72 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 61  er which.** is a
167a0 6e 20 75 6e 73 69 67 6e 65 64 20 69 6e 74 65 67  n unsigned integ
167b0 65 72 20 61 6e 64 20 73 65 74 73 20 74 68 65 20  er and sets the 
167c0 22 4d 69 6e 69 6d 75 6d 20 50 4d 41 20 53 69 7a  "Minimum PMA Siz
167d0 65 22 20 66 6f 72 20 74 68 65 20 6d 75 6c 74 69  e" for the multi
167e0 74 68 72 65 61 64 65 64 0a 2a 2a 20 73 6f 72 74  threaded.** sort
167f0 65 72 20 74 6f 20 74 68 61 74 20 69 6e 74 65 67  er to that integ
16800 65 72 2e 20 20 54 68 65 20 64 65 66 61 75 6c 74  er.  The default
16810 20 6d 69 6e 69 6d 75 6d 20 50 4d 41 20 53 69 7a   minimum PMA Siz
16820 65 20 69 73 20 73 65 74 20 62 79 20 74 68 65 0a  e is set by the.
16830 2a 2a 20 5b 53 51 4c 49 54 45 5f 53 4f 52 54 45  ** [SQLITE_SORTE
16840 52 5f 50 4d 41 53 5a 5d 20 63 6f 6d 70 69 6c 65  R_PMASZ] compile
16850 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2e 20 20 4e  -time option.  N
16860 65 77 20 74 68 72 65 61 64 73 20 61 72 65 20 6c  ew threads are l
16870 61 75 6e 63 68 65 64 0a 2a 2a 20 74 6f 20 68 65  aunched.** to he
16880 6c 70 20 77 69 74 68 20 73 6f 72 74 20 6f 70 65  lp with sort ope
16890 72 61 74 69 6f 6e 73 20 77 68 65 6e 20 6d 75 6c  rations when mul
168a0 74 69 74 68 72 65 61 64 65 64 20 73 6f 72 74 69  tithreaded sorti
168b0 6e 67 0a 2a 2a 20 69 73 20 65 6e 61 62 6c 65 64  ng.** is enabled
168c0 20 28 75 73 69 6e 67 20 74 68 65 20 5b 50 52 41   (using the [PRA
168d0 47 4d 41 20 74 68 72 65 61 64 73 5d 20 63 6f 6d  GMA threads] com
168e0 6d 61 6e 64 29 20 61 6e 64 20 74 68 65 20 61 6d  mand) and the am
168f0 6f 75 6e 74 20 6f 66 20 63 6f 6e 74 65 6e 74 0a  ount of content.
16900 2a 2a 20 74 6f 20 62 65 20 73 6f 72 74 65 64 20  ** to be sorted 
16910 65 78 63 65 65 64 73 20 74 68 65 20 70 61 67 65  exceeds the page
16920 20 73 69 7a 65 20 74 69 6d 65 73 20 74 68 65 20   size times the 
16930 6d 69 6e 69 6d 75 6d 20 6f 66 20 74 68 65 0a 2a  minimum of the.*
16940 2a 20 5b 50 52 41 47 4d 41 20 63 61 63 68 65 5f  * [PRAGMA cache_
16950 73 69 7a 65 5d 20 73 65 74 74 69 6e 67 20 61 6e  size] setting an
16960 64 20 74 68 69 73 20 76 61 6c 75 65 2e 0a 2a 2a  d this value..**
16970 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
16980 46 49 47 5f 53 54 4d 54 4a 52 4e 4c 5f 53 50 49  FIG_STMTJRNL_SPI
16990 4c 4c 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  LL]].** <dt>SQLI
169a0 54 45 5f 43 4f 4e 46 49 47 5f 53 54 4d 54 4a 52  TE_CONFIG_STMTJR
169b0 4e 4c 5f 53 50 49 4c 4c 0a 2a 2a 20 3c 64 64 3e  NL_SPILL.** <dd>
169c0 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  ^The SQLITE_CONF
169d0 49 47 5f 53 54 4d 54 4a 52 4e 4c 5f 53 50 49 4c  IG_STMTJRNL_SPIL
169e0 4c 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61  L option takes a
169f0 20 73 69 6e 67 6c 65 20 70 61 72 61 6d 65 74 65   single paramete
16a00 72 20 77 68 69 63 68 0a 2a 2a 20 62 65 63 6f 6d  r which.** becom
16a10 65 73 20 74 68 65 20 5b 73 74 61 74 65 6d 65 6e  es the [statemen
16a20 74 20 6a 6f 75 72 6e 61 6c 5d 20 73 70 69 6c 6c  t journal] spill
16a30 2d 74 6f 2d 64 69 73 6b 20 74 68 72 65 73 68 6f  -to-disk thresho
16a40 6c 64 2e 20 20 0a 2a 2a 20 5b 53 74 61 74 65 6d  ld.  .** [Statem
16a50 65 6e 74 20 6a 6f 75 72 6e 61 6c 73 5d 20 61 72  ent journals] ar
16a60 65 20 68 65 6c 64 20 69 6e 20 6d 65 6d 6f 72 79  e held in memory
16a70 20 75 6e 74 69 6c 20 74 68 65 69 72 20 73 69 7a   until their siz
16a80 65 20 28 69 6e 20 62 79 74 65 73 29 0a 2a 2a 20  e (in bytes).** 
16a90 65 78 63 65 65 64 73 20 74 68 69 73 20 74 68 72  exceeds this thr
16aa0 65 73 68 6f 6c 64 2c 20 61 74 20 77 68 69 63 68  eshold, at which
16ab0 20 70 6f 69 6e 74 20 74 68 65 79 20 61 72 65 20   point they are 
16ac0 77 72 69 74 74 65 6e 20 74 6f 20 64 69 73 6b 2e  written to disk.
16ad0 0a 2a 2a 20 4f 72 20 69 66 20 74 68 65 20 74 68  .** Or if the th
16ae0 72 65 73 68 6f 6c 64 20 69 73 20 2d 31 2c 20 73  reshold is -1, s
16af0 74 61 74 65 6d 65 6e 74 20 6a 6f 75 72 6e 61 6c  tatement journal
16b00 73 20 61 72 65 20 61 6c 77 61 79 73 20 68 65 6c  s are always hel
16b10 64 0a 2a 2a 20 65 78 63 6c 75 73 69 76 65 6c 79  d.** exclusively
16b20 20 69 6e 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 53   in memory..** S
16b30 69 6e 63 65 20 6d 61 6e 79 20 73 74 61 74 65 6d  ince many statem
16b40 65 6e 74 20 6a 6f 75 72 6e 61 6c 73 20 6e 65 76  ent journals nev
16b50 65 72 20 62 65 63 6f 6d 65 20 6c 61 72 67 65 2c  er become large,
16b60 20 73 65 74 74 69 6e 67 20 74 68 65 20 73 70 69   setting the spi
16b70 6c 6c 0a 2a 2a 20 74 68 72 65 73 68 6f 6c 64 20  ll.** threshold 
16b80 74 6f 20 61 20 76 61 6c 75 65 20 73 75 63 68 20  to a value such 
16b90 61 73 20 36 34 4b 69 42 20 63 61 6e 20 67 72 65  as 64KiB can gre
16ba0 61 74 6c 79 20 72 65 64 75 63 65 20 74 68 65 20  atly reduce the 
16bb0 61 6d 6f 75 6e 74 20 6f 66 0a 2a 2a 20 49 2f 4f  amount of.** I/O
16bc0 20 72 65 71 75 69 72 65 64 20 74 6f 20 73 75 70   required to sup
16bd0 70 6f 72 74 20 73 74 61 74 65 6d 65 6e 74 20 72  port statement r
16be0 6f 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 54 68 65 20  ollback..** The 
16bf0 64 65 66 61 75 6c 74 20 76 61 6c 75 65 20 66 6f  default value fo
16c00 72 20 74 68 69 73 20 73 65 74 74 69 6e 67 20 69  r this setting i
16c10 73 20 63 6f 6e 74 72 6f 6c 6c 65 64 20 62 79 20  s controlled by 
16c20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 53  the.** [SQLITE_S
16c30 54 4d 54 4a 52 4e 4c 5f 53 50 49 4c 4c 5d 20 63  TMTJRNL_SPILL] c
16c40 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
16c50 6f 6e 2e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a  on..** </dl>.*/.
16c60 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
16c70 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45  ONFIG_SINGLETHRE
16c80 41 44 20 20 31 20 20 2f 2a 20 6e 69 6c 20 2a 2f  AD  1  /* nil */
16c90 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
16ca0 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45  CONFIG_MULTITHRE
16cb0 41 44 20 20 20 32 20 20 2f 2a 20 6e 69 6c 20 2a  AD   2  /* nil *
16cc0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
16cd0 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a  _CONFIG_SERIALIZ
16ce0 45 44 20 20 20 20 33 20 20 2f 2a 20 6e 69 6c 20  ED    3  /* nil 
16cf0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
16d00 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 20  E_CONFIG_MALLOC 
16d10 20 20 20 20 20 20 20 34 20 20 2f 2a 20 73 71 6c         4  /* sql
16d20 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73  ite3_mem_methods
16d30 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  * */.#define SQL
16d40 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41  ITE_CONFIG_GETMA
16d50 4c 4c 4f 43 20 20 20 20 20 35 20 20 2f 2a 20 73  LLOC     5  /* s
16d60 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f  qlite3_mem_metho
16d70 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ds* */.#define S
16d80 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52  QLITE_CONFIG_SCR
16d90 41 54 43 48 20 20 20 20 20 20 20 36 20 20 2f 2a  ATCH       6  /*
16da0 20 76 6f 69 64 2a 2c 20 69 6e 74 20 73 7a 2c 20   void*, int sz, 
16db0 69 6e 74 20 4e 20 2a 2f 0a 23 64 65 66 69 6e 65  int N */.#define
16dc0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50   SQLITE_CONFIG_P
16dd0 41 47 45 43 41 43 48 45 20 20 20 20 20 37 20 20  AGECACHE     7  
16de0 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 73 7a  /* void*, int sz
16df0 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23 64 65 66 69  , int N */.#defi
16e00 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
16e10 5f 48 45 41 50 20 20 20 20 20 20 20 20 20 20 38  _HEAP          8
16e20 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20    /* void*, int 
16e30 6e 42 79 74 65 2c 20 69 6e 74 20 6d 69 6e 20 2a  nByte, int min *
16e40 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
16e50 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55  _CONFIG_MEMSTATU
16e60 53 20 20 20 20 20 39 20 20 2f 2a 20 62 6f 6f 6c  S     9  /* bool
16e70 65 61 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ean */.#define S
16e80 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54  QLITE_CONFIG_MUT
16e90 45 58 20 20 20 20 20 20 20 20 31 30 20 20 2f 2a  EX        10  /*
16ea0 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d   sqlite3_mutex_m
16eb0 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69  ethods* */.#defi
16ec0 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
16ed0 5f 47 45 54 4d 55 54 45 58 20 20 20 20 20 31 31  _GETMUTEX     11
16ee0 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74    /* sqlite3_mut
16ef0 65 78 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 2f  ex_methods* */./
16f00 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 53 51 4c  * previously SQL
16f10 49 54 45 5f 43 4f 4e 46 49 47 5f 43 48 55 4e 4b  ITE_CONFIG_CHUNK
16f20 41 4c 4c 4f 43 20 31 32 20 77 68 69 63 68 20 69  ALLOC 12 which i
16f30 73 20 6e 6f 77 20 75 6e 75 73 65 64 2e 20 2a 2f  s now unused. */
16f40 20 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45   .#define SQLITE
16f50 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44  _CONFIG_LOOKASID
16f60 45 20 20 20 20 31 33 20 20 2f 2a 20 69 6e 74 20  E    13  /* int 
16f70 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  int */.#define S
16f80 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41  QLITE_CONFIG_PCA
16f90 43 48 45 20 20 20 20 20 20 20 31 34 20 20 2f 2a  CHE       14  /*
16fa0 20 6e 6f 2d 6f 70 20 2a 2f 0a 23 64 65 66 69 6e   no-op */.#defin
16fb0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
16fc0 47 45 54 50 43 41 43 48 45 20 20 20 20 31 35 20  GETPCACHE    15 
16fd0 20 2f 2a 20 6e 6f 2d 6f 70 20 2a 2f 0a 23 64 65   /* no-op */.#de
16fe0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
16ff0 49 47 5f 4c 4f 47 20 20 20 20 20 20 20 20 20 20  IG_LOG          
17000 31 36 20 20 2f 2a 20 78 46 75 6e 63 2c 20 76 6f  16  /* xFunc, vo
17010 69 64 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  id* */.#define S
17020 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49  QLITE_CONFIG_URI
17030 20 20 20 20 20 20 20 20 20 20 31 37 20 20 2f 2a            17  /*
17040 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20   int */.#define 
17050 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43  SQLITE_CONFIG_PC
17060 41 43 48 45 32 20 20 20 20 20 20 31 38 20 20 2f  ACHE2      18  /
17070 2a 20 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65  * sqlite3_pcache
17080 5f 6d 65 74 68 6f 64 73 32 2a 20 2a 2f 0a 23 64  _methods2* */.#d
17090 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
170a0 46 49 47 5f 47 45 54 50 43 41 43 48 45 32 20 20  FIG_GETPCACHE2  
170b0 20 31 39 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f   19  /* sqlite3_
170c0 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 32 2a  pcache_methods2*
170d0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
170e0 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56 45 52 49  TE_CONFIG_COVERI
170f0 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 20 32 30  NG_INDEX_SCAN 20
17100 20 20 2f 2a 20 69 6e 74 20 2a 2f 0a 23 64 65 66    /* int */.#def
17110 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
17120 47 5f 53 51 4c 4c 4f 47 20 20 20 20 20 20 20 32  G_SQLLOG       2
17130 31 20 20 2f 2a 20 78 53 71 6c 6c 6f 67 2c 20 76  1  /* xSqllog, v
17140 6f 69 64 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20  oid* */.#define 
17150 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d  SQLITE_CONFIG_MM
17160 41 50 5f 53 49 5a 45 20 20 20 20 32 32 20 20 2f  AP_SIZE    22  /
17170 2a 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 2c  * sqlite3_int64,
17180 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a   sqlite3_int64 *
17190 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
171a0 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f 48 45  _CONFIG_WIN32_HE
171b0 41 50 53 49 5a 45 20 20 20 20 20 20 32 33 20 20  APSIZE      23  
171c0 2f 2a 20 69 6e 74 20 6e 42 79 74 65 20 2a 2f 0a  /* int nByte */.
171d0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
171e0 4f 4e 46 49 47 5f 50 43 41 43 48 45 5f 48 44 52  ONFIG_PCACHE_HDR
171f0 53 5a 20 20 20 20 20 20 20 20 32 34 20 20 2f 2a  SZ        24  /*
17200 20 69 6e 74 20 2a 70 73 7a 20 2a 2f 0a 23 64 65   int *psz */.#de
17210 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
17220 49 47 5f 50 4d 41 53 5a 20 20 20 20 20 20 20 20  IG_PMASZ        
17230 20 20 20 20 20 20 20 32 35 20 20 2f 2a 20 75 6e         25  /* un
17240 73 69 67 6e 65 64 20 69 6e 74 20 73 7a 50 6d 61  signed int szPma
17250 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
17260 54 45 5f 43 4f 4e 46 49 47 5f 53 54 4d 54 4a 52  TE_CONFIG_STMTJR
17270 4e 4c 5f 53 50 49 4c 4c 20 20 20 20 20 20 32 36  NL_SPILL      26
17280 20 20 2f 2a 20 69 6e 74 20 6e 42 79 74 65 20 2a    /* int nByte *
17290 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  /../*.** CAPI3RE
172a0 46 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e  F: Database Conn
172b0 65 63 74 69 6f 6e 20 43 6f 6e 66 69 67 75 72 61  ection Configura
172c0 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a 0a  tion Options.**.
172d0 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e  ** These constan
172e0 74 73 20 61 72 65 20 74 68 65 20 61 76 61 69 6c  ts are the avail
172f0 61 62 6c 65 20 69 6e 74 65 67 65 72 20 63 6f 6e  able integer con
17300 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
17310 6e 73 20 74 68 61 74 0a 2a 2a 20 63 61 6e 20 62  ns that.** can b
17320 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20  e passed as the 
17330 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20  second argument 
17340 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
17350 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74  db_config()] int
17360 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65  erface..**.** Ne
17370 77 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  w configuration 
17380 6f 70 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 61  options may be a
17390 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72  dded in future r
173a0 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74  eleases of SQLit
173b0 65 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20 63  e..** Existing c
173c0 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
173d0 69 6f 6e 73 20 6d 69 67 68 74 20 62 65 20 64 69  ions might be di
173e0 73 63 6f 6e 74 69 6e 75 65 64 2e 20 20 41 70 70  scontinued.  App
173f0 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f  lications.** sho
17400 75 6c 64 20 63 68 65 63 6b 20 74 68 65 20 72 65  uld check the re
17410 74 75 72 6e 20 63 6f 64 65 20 66 72 6f 6d 20 5b  turn code from [
17420 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69  sqlite3_db_confi
17430 67 28 29 5d 20 74 6f 20 6d 61 6b 65 20 73 75 72  g()] to make sur
17440 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 63 61  e that.** the ca
17450 6c 6c 20 77 6f 72 6b 65 64 2e 20 20 5e 54 68 65  ll worked.  ^The
17460 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e   [sqlite3_db_con
17470 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65  fig()] interface
17480 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 61 0a 2a   will return a.*
17490 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f  * non-zero [erro
174a0 72 20 63 6f 64 65 5d 20 69 66 20 61 20 64 69 73  r code] if a dis
174b0 63 6f 6e 74 69 6e 75 65 64 20 6f 72 20 75 6e 73  continued or uns
174c0 75 70 70 6f 72 74 65 64 20 63 6f 6e 66 69 67 75  upported configu
174d0 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a 2a  ration option.**
174e0 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a   is invoked..**.
174f0 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 3e 53  ** <dl>.** <dt>S
17500 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c  QLITE_DBCONFIG_L
17510 4f 4f 4b 41 53 49 44 45 3c 2f 64 74 3e 0a 2a 2a  OOKASIDE</dt>.**
17520 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69   <dd> ^This opti
17530 6f 6e 20 74 61 6b 65 73 20 74 68 72 65 65 20 61  on takes three a
17540 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65  dditional argume
17550 6e 74 73 20 74 68 61 74 20 64 65 74 65 72 6d 69  nts that determi
17560 6e 65 20 74 68 65 20 0a 2a 2a 20 5b 6c 6f 6f 6b  ne the .** [look
17570 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 61 6c 6c  aside memory all
17580 6f 63 61 74 6f 72 5d 20 63 6f 6e 66 69 67 75 72  ocator] configur
17590 61 74 69 6f 6e 20 66 6f 72 20 74 68 65 20 5b 64  ation for the [d
175a0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
175b0 6f 6e 5d 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 72  on]..** ^The fir
175c0 73 74 20 61 72 67 75 6d 65 6e 74 20 28 74 68 65  st argument (the
175d0 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
175e0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f   to [sqlite3_db_
175f0 63 6f 6e 66 69 67 28 29 5d 20 69 73 20 61 0a 2a  config()] is a.*
17600 2a 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 6d  * pointer to a m
17610 65 6d 6f 72 79 20 62 75 66 66 65 72 20 74 6f 20  emory buffer to 
17620 75 73 65 20 66 6f 72 20 6c 6f 6f 6b 61 73 69 64  use for lookasid
17630 65 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 54 68  e memory..** ^Th
17640 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
17650 20 61 66 74 65 72 20 74 68 65 20 53 51 4c 49 54   after the SQLIT
17660 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41  E_DBCONFIG_LOOKA
17670 53 49 44 45 20 76 65 72 62 0a 2a 2a 20 6d 61 79  SIDE verb.** may
17680 20 62 65 20 4e 55 4c 4c 20 69 6e 20 77 68 69 63   be NULL in whic
17690 68 20 63 61 73 65 20 53 51 4c 69 74 65 20 77 69  h case SQLite wi
176a0 6c 6c 20 61 6c 6c 6f 63 61 74 65 20 74 68 65 0a  ll allocate the.
176b0 2a 2a 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66  ** lookaside buf
176c0 66 65 72 20 69 74 73 65 6c 66 20 75 73 69 6e 67  fer itself using
176d0 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
176e0 28 29 5d 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64  ()]. ^The second
176f0 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65   argument is the
17700 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 65 61 63 68  .** size of each
17710 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66 66 65   lookaside buffe
17720 72 20 73 6c 6f 74 2e 20 20 5e 54 68 65 20 74 68  r slot.  ^The th
17730 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20  ird argument is 
17740 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a  the number of.**
17750 20 73 6c 6f 74 73 2e 20 20 54 68 65 20 73 69 7a   slots.  The siz
17760 65 20 6f 66 20 74 68 65 20 62 75 66 66 65 72 20  e of the buffer 
17770 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67  in the first arg
17780 75 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 67 72  ument must be gr
17790 65 61 74 65 72 20 74 68 61 6e 0a 2a 2a 20 6f 72  eater than.** or
177a0 20 65 71 75 61 6c 20 74 6f 20 74 68 65 20 70 72   equal to the pr
177b0 6f 64 75 63 74 20 6f 66 20 74 68 65 20 73 65 63  oduct of the sec
177c0 6f 6e 64 20 61 6e 64 20 74 68 69 72 64 20 61 72  ond and third ar
177d0 67 75 6d 65 6e 74 73 2e 20 20 54 68 65 20 62 75  guments.  The bu
177e0 66 66 65 72 0a 2a 2a 20 6d 75 73 74 20 62 65 20  ffer.** must be 
177f0 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 38 2d  aligned to an 8-
17800 62 79 74 65 20 62 6f 75 6e 64 61 72 79 2e 20 20  byte boundary.  
17810 5e 49 66 20 74 68 65 20 73 65 63 6f 6e 64 20 61  ^If the second a
17820 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 53 51  rgument to.** SQ
17830 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f  LITE_DBCONFIG_LO
17840 4f 4b 41 53 49 44 45 20 69 73 20 6e 6f 74 20 61  OKASIDE is not a
17850 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20 38 2c 20   multiple of 8, 
17860 69 74 20 69 73 20 69 6e 74 65 72 6e 61 6c 6c 79  it is internally
17870 0a 2a 2a 20 72 6f 75 6e 64 65 64 20 64 6f 77 6e  .** rounded down
17880 20 74 6f 20 74 68 65 20 6e 65 78 74 20 73 6d 61   to the next sma
17890 6c 6c 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66  ller multiple of
178a0 20 38 2e 20 20 5e 28 54 68 65 20 6c 6f 6f 6b 61   8.  ^(The looka
178b0 73 69 64 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 63  side memory.** c
178c0 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 66 6f 72  onfiguration for
178d0 20 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e   a database conn
178e0 65 63 74 69 6f 6e 20 63 61 6e 20 6f 6e 6c 79 20  ection can only 
178f0 62 65 20 63 68 61 6e 67 65 64 20 77 68 65 6e 20  be changed when 
17900 74 68 61 74 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69  that.** connecti
17910 6f 6e 20 69 73 20 6e 6f 74 20 63 75 72 72 65 6e  on is not curren
17920 74 6c 79 20 75 73 69 6e 67 20 6c 6f 6f 6b 61 73  tly using lookas
17930 69 64 65 20 6d 65 6d 6f 72 79 2c 20 6f 72 20 69  ide memory, or i
17940 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 0a 2a 2a  n other words.**
17950 20 77 68 65 6e 20 74 68 65 20 22 63 75 72 72 65   when the "curre
17960 6e 74 20 76 61 6c 75 65 22 20 72 65 74 75 72 6e  nt value" return
17970 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65  ed by.** [sqlite
17980 33 5f 64 62 5f 73 74 61 74 75 73 5d 28 44 2c 5b  3_db_status](D,[
17990 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f  SQLITE_CONFIG_LO
179a0 4f 4b 41 53 49 44 45 5d 2c 2e 2e 2e 29 20 69 73  OKASIDE],...) is
179b0 20 7a 65 72 6f 2e 0a 2a 2a 20 41 6e 79 20 61 74   zero..** Any at
179c0 74 65 6d 70 74 20 74 6f 20 63 68 61 6e 67 65 20  tempt to change 
179d0 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65  the lookaside me
179e0 6d 6f 72 79 20 63 6f 6e 66 69 67 75 72 61 74 69  mory configurati
179f0 6f 6e 20 77 68 65 6e 20 6c 6f 6f 6b 61 73 69 64  on when lookasid
17a00 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 69 73 20 69  e.** memory is i
17a10 6e 20 75 73 65 20 6c 65 61 76 65 73 20 74 68 65  n use leaves the
17a20 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 75   configuration u
17a30 6e 63 68 61 6e 67 65 64 20 61 6e 64 20 72 65 74  nchanged and ret
17a40 75 72 6e 73 20 0a 2a 2a 20 5b 53 51 4c 49 54 45  urns .** [SQLITE
17a50 5f 42 55 53 59 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a  _BUSY].)^</dd>.*
17a60 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  *.** <dt>SQLITE_
17a70 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f  DBCONFIG_ENABLE_
17a80 46 4b 45 59 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  FKEY</dt>.** <dd
17a90 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 69  > ^This option i
17aa0 73 20 75 73 65 64 20 74 6f 20 65 6e 61 62 6c 65  s used to enable
17ab0 20 6f 72 20 64 69 73 61 62 6c 65 20 74 68 65 20   or disable the 
17ac0 65 6e 66 6f 72 63 65 6d 65 6e 74 20 6f 66 0a 2a  enforcement of.*
17ad0 2a 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20 63  * [foreign key c
17ae0 6f 6e 73 74 72 61 69 6e 74 73 5d 2e 20 20 54 68  onstraints].  Th
17af0 65 72 65 20 73 68 6f 75 6c 64 20 62 65 20 74 77  ere should be tw
17b00 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 67  o additional arg
17b10 75 6d 65 6e 74 73 2e 0a 2a 2a 20 54 68 65 20 66  uments..** The f
17b20 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73  irst argument is
17b30 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68 69 63   an integer whic
17b40 68 20 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c  h is 0 to disabl
17b50 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74  e FK enforcement
17b60 2c 0a 2a 2a 20 70 6f 73 69 74 69 76 65 20 74 6f  ,.** positive to
17b70 20 65 6e 61 62 6c 65 20 46 4b 20 65 6e 66 6f 72   enable FK enfor
17b80 63 65 6d 65 6e 74 20 6f 72 20 6e 65 67 61 74 69  cement or negati
17b90 76 65 20 74 6f 20 6c 65 61 76 65 20 46 4b 20 65  ve to leave FK e
17ba0 6e 66 6f 72 63 65 6d 65 6e 74 0a 2a 2a 20 75 6e  nforcement.** un
17bb0 63 68 61 6e 67 65 64 2e 20 20 54 68 65 20 73 65  changed.  The se
17bc0 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69  cond parameter i
17bd0 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
17be0 6e 20 69 6e 74 65 67 65 72 20 69 6e 74 6f 20 77  n integer into w
17bf0 68 69 63 68 0a 2a 2a 20 69 73 20 77 72 69 74 74  hich.** is writt
17c00 65 6e 20 30 20 6f 72 20 31 20 74 6f 20 69 6e 64  en 0 or 1 to ind
17c10 69 63 61 74 65 20 77 68 65 74 68 65 72 20 46 4b  icate whether FK
17c20 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 69 73 20   enforcement is 
17c30 6f 66 66 20 6f 72 20 6f 6e 0a 2a 2a 20 66 6f 6c  off or on.** fol
17c40 6c 6f 77 69 6e 67 20 74 68 69 73 20 63 61 6c 6c  lowing this call
17c50 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61  .  The second pa
17c60 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20 61  rameter may be a
17c70 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69   NULL pointer, i
17c80 6e 0a 2a 2a 20 77 68 69 63 68 20 63 61 73 65 20  n.** which case 
17c90 74 68 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65  the FK enforceme
17ca0 6e 74 20 73 65 74 74 69 6e 67 20 69 73 20 6e 6f  nt setting is no
17cb0 74 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b 2e  t reported back.
17cc0 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74   </dd>.**.** <dt
17cd0 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47  >SQLITE_DBCONFIG
17ce0 5f 45 4e 41 42 4c 45 5f 54 52 49 47 47 45 52 3c  _ENABLE_TRIGGER<
17cf0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68  /dt>.** <dd> ^Th
17d00 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65  is option is use
17d10 64 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64  d to enable or d
17d20 69 73 61 62 6c 65 20 5b 43 52 45 41 54 45 20 54  isable [CREATE T
17d30 52 49 47 47 45 52 20 7c 20 74 72 69 67 67 65 72  RIGGER | trigger
17d40 73 5d 2e 0a 2a 2a 20 54 68 65 72 65 20 73 68 6f  s]..** There sho
17d50 75 6c 64 20 62 65 20 74 77 6f 20 61 64 64 69 74  uld be two addit
17d60 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 2e  ional arguments.
17d70 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72  .** The first ar
17d80 67 75 6d 65 6e 74 20 69 73 20 61 6e 20 69 6e 74  gument is an int
17d90 65 67 65 72 20 77 68 69 63 68 20 69 73 20 30 20  eger which is 0 
17da0 74 6f 20 64 69 73 61 62 6c 65 20 74 72 69 67 67  to disable trigg
17db0 65 72 73 2c 0a 2a 2a 20 70 6f 73 69 74 69 76 65  ers,.** positive
17dc0 20 74 6f 20 65 6e 61 62 6c 65 20 74 72 69 67 67   to enable trigg
17dd0 65 72 73 20 6f 72 20 6e 65 67 61 74 69 76 65 20  ers or negative 
17de0 74 6f 20 6c 65 61 76 65 20 74 68 65 20 73 65 74  to leave the set
17df0 74 69 6e 67 20 75 6e 63 68 61 6e 67 65 64 2e 0a  ting unchanged..
17e00 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61  ** The second pa
17e10 72 61 6d 65 74 65 72 20 69 73 20 61 20 70 6f 69  rameter is a poi
17e20 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67  nter to an integ
17e30 65 72 20 69 6e 74 6f 20 77 68 69 63 68 0a 2a 2a  er into which.**
17e40 20 69 73 20 77 72 69 74 74 65 6e 20 30 20 6f 72   is written 0 or
17e50 20 31 20 74 6f 20 69 6e 64 69 63 61 74 65 20 77   1 to indicate w
17e60 68 65 74 68 65 72 20 74 72 69 67 67 65 72 73 20  hether triggers 
17e70 61 72 65 20 64 69 73 61 62 6c 65 64 20 6f 72 20  are disabled or 
17e80 65 6e 61 62 6c 65 64 0a 2a 2a 20 66 6f 6c 6c 6f  enabled.** follo
17e90 77 69 6e 67 20 74 68 69 73 20 63 61 6c 6c 2e 20  wing this call. 
17ea0 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   The second para
17eb0 6d 65 74 65 72 20 6d 61 79 20 62 65 20 61 20 4e  meter may be a N
17ec0 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69 6e 0a  ULL pointer, in.
17ed0 2a 2a 20 77 68 69 63 68 20 63 61 73 65 20 74 68  ** which case th
17ee0 65 20 74 72 69 67 67 65 72 20 73 65 74 74 69 6e  e trigger settin
17ef0 67 20 69 73 20 6e 6f 74 20 72 65 70 6f 72 74 65  g is not reporte
17f00 64 20 62 61 63 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a  d back. </dd>.**
17f10 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44  .** <dt>SQLITE_D
17f20 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 46  BCONFIG_ENABLE_F
17f30 54 53 33 5f 54 4f 4b 45 4e 49 5a 45 52 3c 2f 64  TS3_TOKENIZER</d
17f40 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73  t>.** <dd> ^This
17f50 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64 20   option is used 
17f60 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64 69 73  to enable or dis
17f70 61 62 6c 65 20 74 68 65 20 74 77 6f 2d 61 72 67  able the two-arg
17f80 75 6d 65 6e 74 0a 2a 2a 20 76 65 72 73 69 6f 6e  ument.** version
17f90 20 6f 66 20 74 68 65 20 5b 66 74 73 33 5f 74 6f   of the [fts3_to
17fa0 6b 65 6e 69 7a 65 72 28 29 5d 20 66 75 6e 63 74  kenizer()] funct
17fb0 69 6f 6e 20 77 68 69 63 68 20 69 73 20 70 61 72  ion which is par
17fc0 74 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 46 54 53  t of the.** [FTS
17fd0 33 5d 20 66 75 6c 6c 2d 74 65 78 74 20 73 65 61  3] full-text sea
17fe0 72 63 68 20 65 6e 67 69 6e 65 20 65 78 74 65 6e  rch engine exten
17ff0 73 69 6f 6e 2e 0a 2a 2a 20 54 68 65 72 65 20 73  sion..** There s
18000 68 6f 75 6c 64 20 62 65 20 74 77 6f 20 61 64 64  hould be two add
18010 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74  itional argument
18020 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20  s..** The first 
18030 61 72 67 75 6d 65 6e 74 20 69 73 20 61 6e 20 69  argument is an i
18040 6e 74 65 67 65 72 20 77 68 69 63 68 20 69 73 20  nteger which is 
18050 30 20 74 6f 20 64 69 73 61 62 6c 65 20 66 74 73  0 to disable fts
18060 33 5f 74 6f 6b 65 6e 69 7a 65 72 28 29 20 6f 72  3_tokenizer() or
18070 0a 2a 2a 20 70 6f 73 69 74 69 76 65 20 74 6f 20  .** positive to 
18080 65 6e 61 62 6c 65 20 66 74 73 33 5f 74 6f 6b 65  enable fts3_toke
18090 6e 69 7a 65 72 28 29 20 6f 72 20 6e 65 67 61 74  nizer() or negat
180a0 69 76 65 20 74 6f 20 6c 65 61 76 65 20 74 68 65  ive to leave the
180b0 20 73 65 74 74 69 6e 67 0a 2a 2a 20 75 6e 63 68   setting.** unch
180c0 61 6e 67 65 64 2e 0a 2a 2a 20 54 68 65 20 73 65  anged..** The se
180d0 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69  cond parameter i
180e0 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
180f0 6e 20 69 6e 74 65 67 65 72 20 69 6e 74 6f 20 77  n integer into w
18100 68 69 63 68 0a 2a 2a 20 69 73 20 77 72 69 74 74  hich.** is writt
18110 65 6e 20 30 20 6f 72 20 31 20 74 6f 20 69 6e 64  en 0 or 1 to ind
18120 69 63 61 74 65 20 77 68 65 74 68 65 72 20 66 74  icate whether ft
18130 73 33 5f 74 6f 6b 65 6e 69 7a 65 72 20 69 73 20  s3_tokenizer is 
18140 64 69 73 61 62 6c 65 64 20 6f 72 20 65 6e 61 62  disabled or enab
18150 6c 65 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67  led.** following
18160 20 74 68 69 73 20 63 61 6c 6c 2e 20 20 54 68 65   this call.  The
18170 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
18180 72 20 6d 61 79 20 62 65 20 61 20 4e 55 4c 4c 20  r may be a NULL 
18190 70 6f 69 6e 74 65 72 2c 20 69 6e 0a 2a 2a 20 77  pointer, in.** w
181a0 68 69 63 68 20 63 61 73 65 20 74 68 65 20 6e 65  hich case the ne
181b0 77 20 73 65 74 74 69 6e 67 20 69 73 20 6e 6f 74  w setting is not
181c0 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b 2e 20   reported back. 
181d0 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e  </dd>.**.** <dt>
181e0 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
181f0 45 4e 41 42 4c 45 5f 4c 4f 41 44 5f 45 58 54 45  ENABLE_LOAD_EXTE
18200 4e 53 49 4f 4e 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  NSION</dt>.** <d
18210 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20  d> ^This option 
18220 69 73 20 75 73 65 64 20 74 6f 20 65 6e 61 62 6c  is used to enabl
18230 65 20 6f 72 20 64 69 73 61 62 6c 65 20 74 68 65  e or disable the
18240 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 61 64 5f 65   [sqlite3_load_e
18250 78 74 65 6e 73 69 6f 6e 28 29 5d 0a 2a 2a 20 69  xtension()].** i
18260 6e 74 65 72 66 61 63 65 20 69 6e 64 65 70 65 6e  nterface indepen
18270 64 65 6e 74 6c 79 20 6f 66 20 74 68 65 20 5b 6c  dently of the [l
18280 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d  oad_extension()]
18290 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a   SQL function..*
182a0 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 65  * The [sqlite3_e
182b0 6e 61 62 6c 65 5f 6c 6f 61 64 5f 65 78 74 65 6e  nable_load_exten
182c0 73 69 6f 6e 28 29 5d 20 41 50 49 20 65 6e 61 62  sion()] API enab
182d0 6c 65 73 20 6f 72 20 64 69 73 61 62 6c 65 73 20  les or disables 
182e0 62 6f 74 68 20 74 68 65 0a 2a 2a 20 43 2d 41 50  both the.** C-AP
182f0 49 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 61 64 5f  I [sqlite3_load_
18300 65 78 74 65 6e 73 69 6f 6e 28 29 5d 20 61 6e 64  extension()] and
18310 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f   the SQL functio
18320 6e 20 5b 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f  n [load_extensio
18330 6e 28 29 5d 2e 0a 2a 2a 20 54 68 65 72 65 20 73  n()]..** There s
18340 68 6f 75 6c 64 20 62 65 20 74 77 6f 20 61 64 64  hould be two add
18350 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74  itional argument
18360 73 2e 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 66  s..** When the f
18370 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f  irst argument to
18380 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 20   this interface 
18390 69 73 20 31 2c 20 74 68 65 6e 20 6f 6e 6c 79 20  is 1, then only 
183a0 74 68 65 20 43 2d 41 50 49 20 69 73 0a 2a 2a 20  the C-API is.** 
183b0 65 6e 61 62 6c 65 64 20 61 6e 64 20 74 68 65 20  enabled and the 
183c0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65 6d  SQL function rem
183d0 61 69 6e 73 20 64 69 73 61 62 6c 65 64 2e 20 20  ains disabled.  
183e0 49 66 20 74 68 65 20 66 69 72 73 74 20 61 72 67  If the first arg
183f0 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 74 68 69 73  ument to.** this
18400 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 30 2c   interface is 0,
18410 20 74 68 65 6e 20 62 6f 74 68 20 74 68 65 20 43   then both the C
18420 2d 41 50 49 20 61 6e 64 20 74 68 65 20 53 51 4c  -API and the SQL
18430 20 66 75 6e 63 74 69 6f 6e 20 61 72 65 20 64 69   function are di
18440 73 61 62 6c 65 64 2e 0a 2a 2a 20 49 66 20 74 68  sabled..** If th
18450 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
18460 20 69 73 20 2d 31 2c 20 74 68 65 6e 20 6e 6f 20   is -1, then no 
18470 63 68 61 6e 67 65 73 20 61 72 65 20 6d 61 64 65  changes are made
18480 20 74 6f 20 73 74 61 74 65 20 6f 66 20 65 69 74   to state of eit
18490 68 65 72 20 74 68 65 0a 2a 2a 20 43 2d 41 50 49  her the.** C-API
184a0 20 6f 72 20 74 68 65 20 53 51 4c 20 66 75 6e 63   or the SQL func
184b0 74 69 6f 6e 2e 0a 2a 2a 20 54 68 65 20 73 65 63  tion..** The sec
184c0 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73  ond parameter is
184d0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
184e0 20 69 6e 74 65 67 65 72 20 69 6e 74 6f 20 77 68   integer into wh
184f0 69 63 68 0a 2a 2a 20 69 73 20 77 72 69 74 74 65  ich.** is writte
18500 6e 20 30 20 6f 72 20 31 20 74 6f 20 69 6e 64 69  n 0 or 1 to indi
18510 63 61 74 65 20 77 68 65 74 68 65 72 20 5b 73 71  cate whether [sq
18520 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65 6e  lite3_load_exten
18530 73 69 6f 6e 28 29 5d 20 69 6e 74 65 72 66 61 63  sion()] interfac
18540 65 0a 2a 2a 20 69 73 20 64 69 73 61 62 6c 65 64  e.** is disabled
18550 20 6f 72 20 65 6e 61 62 6c 65 64 20 66 6f 6c 6c   or enabled foll
18560 6f 77 69 6e 67 20 74 68 69 73 20 63 61 6c 6c 2e  owing this call.
18570 20 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72    The second par
18580 61 6d 65 74 65 72 20 6d 61 79 0a 2a 2a 20 62 65  ameter may.** be
18590 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c   a NULL pointer,
185a0 20 69 6e 20 77 68 69 63 68 20 63 61 73 65 20 74   in which case t
185b0 68 65 20 6e 65 77 20 73 65 74 74 69 6e 67 20 69  he new setting i
185c0 73 20 6e 6f 74 20 72 65 70 6f 72 74 65 64 20 62  s not reported b
185d0 61 63 6b 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a  ack..** </dd>.**
185e0 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44  .** <dt>SQLITE_D
185f0 42 43 4f 4e 46 49 47 5f 4d 41 49 4e 44 42 4e 41  BCONFIG_MAINDBNA
18600 4d 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  ME</dt>.** <dd> 
18610 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20  ^This option is 
18620 75 73 65 64 20 74 6f 20 63 68 61 6e 67 65 20 74  used to change t
18630 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 22  he name of the "
18640 6d 61 69 6e 22 20 64 61 74 61 62 61 73 65 0a 2a  main" database.*
18650 2a 20 73 63 68 65 6d 61 2e 20 20 5e 54 68 65 20  * schema.  ^The 
18660 73 6f 6c 65 20 61 72 67 75 6d 65 6e 74 20 69 73  sole argument is
18670 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20   a pointer to a 
18680 63 6f 6e 73 74 61 6e 74 20 55 54 46 38 20 73 74  constant UTF8 st
18690 72 69 6e 67 0a 2a 2a 20 77 68 69 63 68 20 77 69  ring.** which wi
186a0 6c 6c 20 62 65 63 6f 6d 65 20 74 68 65 20 6e 65  ll become the ne
186b0 77 20 73 63 68 65 6d 61 20 6e 61 6d 65 20 69 6e  w schema name in
186c0 20 70 6c 61 63 65 20 6f 66 20 22 6d 61 69 6e 22   place of "main"
186d0 2e 20 20 5e 53 51 4c 69 74 65 0a 2a 2a 20 64 6f  .  ^SQLite.** do
186e0 65 73 20 6e 6f 74 20 6d 61 6b 65 20 61 20 63 6f  es not make a co
186f0 70 79 20 6f 66 20 74 68 65 20 6e 65 77 20 6d 61  py of the new ma
18700 69 6e 20 73 63 68 65 6d 61 20 6e 61 6d 65 20 73  in schema name s
18710 74 72 69 6e 67 2c 20 73 6f 20 74 68 65 20 61 70  tring, so the ap
18720 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 6d 75 73  plication.** mus
18730 74 20 65 6e 73 75 72 65 20 74 68 61 74 20 74 68  t ensure that th
18740 65 20 61 72 67 75 6d 65 6e 74 20 70 61 73 73 65  e argument passe
18750 64 20 69 6e 74 6f 20 74 68 69 73 20 44 42 43 4f  d into this DBCO
18760 4e 46 49 47 20 6f 70 74 69 6f 6e 20 69 73 20 75  NFIG option is u
18770 6e 63 68 61 6e 67 65 64 0a 2a 2a 20 75 6e 74 69  nchanged.** unti
18780 6c 20 61 66 74 65 72 20 74 68 65 20 64 61 74 61  l after the data
18790 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
187a0 63 6c 6f 73 65 73 2e 0a 2a 2a 20 3c 2f 64 64 3e  closes..** </dd>
187b0 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  .**.** <dt>SQLIT
187c0 45 5f 44 42 43 4f 4e 46 49 47 5f 4e 4f 5f 43 4b  E_DBCONFIG_NO_CK
187d0 50 54 5f 4f 4e 5f 43 4c 4f 53 45 3c 2f 64 74 3e  PT_ON_CLOSE</dt>
187e0 0a 2a 2a 20 3c 64 64 3e 20 55 73 75 61 6c 6c 79  .** <dd> Usually
187f0 2c 20 77 68 65 6e 20 61 20 64 61 74 61 62 61 73  , when a databas
18800 65 20 69 6e 20 77 61 6c 20 6d 6f 64 65 20 69 73  e in wal mode is
18810 20 63 6c 6f 73 65 64 20 6f 72 20 64 65 74 61 63   closed or detac
18820 68 65 64 20 66 72 6f 6d 20 61 20 0a 2a 2a 20 64  hed from a .** d
18830 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 2c 20  atabase handle, 
18840 53 51 4c 69 74 65 20 63 68 65 63 6b 73 20 69 66  SQLite checks if
18850 20 74 68 69 73 20 77 69 6c 6c 20 6d 65 61 6e 20   this will mean 
18860 74 68 61 74 20 74 68 65 72 65 20 61 72 65 20 6e  that there are n
18870 6f 77 20 6e 6f 20 0a 2a 2a 20 63 6f 6e 6e 65 63  ow no .** connec
18880 74 69 6f 6e 73 20 61 74 20 61 6c 6c 20 74 6f 20  tions at all to 
18890 74 68 65 20 64 61 74 61 62 61 73 65 2e 20 49 66  the database. If
188a0 20 73 6f 2c 20 69 74 20 70 65 72 66 6f 72 6d 73   so, it performs
188b0 20 61 20 63 68 65 63 6b 70 6f 69 6e 74 20 0a 2a   a checkpoint .*
188c0 2a 20 6f 70 65 72 61 74 69 6f 6e 20 62 65 66 6f  * operation befo
188d0 72 65 20 63 6c 6f 73 69 6e 67 20 74 68 65 20 63  re closing the c
188e0 6f 6e 6e 65 63 74 69 6f 6e 2e 20 54 68 69 73 20  onnection. This 
188f0 6f 70 74 69 6f 6e 20 6d 61 79 20 62 65 20 75 73  option may be us
18900 65 64 20 74 6f 0a 2a 2a 20 6f 76 65 72 72 69 64  ed to.** overrid
18910 65 20 74 68 69 73 20 62 65 68 61 76 69 6f 75 72  e this behaviour
18920 2e 20 54 68 65 20 66 69 72 73 74 20 70 61 72 61  . The first para
18930 6d 65 74 65 72 20 70 61 73 73 65 64 20 74 6f 20  meter passed to 
18940 74 68 69 73 20 6f 70 65 72 61 74 69 6f 6e 0a 2a  this operation.*
18950 2a 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20  * is an integer 
18960 2d 20 6e 6f 6e 2d 7a 65 72 6f 20 74 6f 20 64 69  - non-zero to di
18970 73 61 62 6c 65 20 63 68 65 63 6b 70 6f 69 6e 74  sable checkpoint
18980 73 2d 6f 6e 2d 63 6c 6f 73 65 2c 20 6f 72 20 7a  s-on-close, or z
18990 65 72 6f 20 28 74 68 65 0a 2a 2a 20 64 65 66 61  ero (the.** defa
189a0 75 6c 74 29 20 74 6f 20 65 6e 61 62 6c 65 20 74  ult) to enable t
189b0 68 65 6d 2e 20 54 68 65 20 73 65 63 6f 6e 64 20  hem. The second 
189c0 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 70  parameter is a p
189d0 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74  ointer to an int
189e0 65 67 65 72 0a 2a 2a 20 69 6e 74 6f 20 77 68 69  eger.** into whi
189f0 63 68 20 69 73 20 77 72 69 74 74 65 6e 20 30 20  ch is written 0 
18a00 6f 72 20 31 20 74 6f 20 69 6e 64 69 63 61 74 65  or 1 to indicate
18a10 20 77 68 65 74 68 65 72 20 63 68 65 63 6b 70 6f   whether checkpo
18a20 69 6e 74 73 2d 6f 6e 2d 63 6c 6f 73 65 0a 2a 2a  ints-on-close.**
18a30 20 68 61 76 65 20 62 65 65 6e 20 64 69 73 61 62   have been disab
18a40 6c 65 64 20 2d 20 30 20 69 66 20 74 68 65 79 20  led - 0 if they 
18a50 61 72 65 20 6e 6f 74 20 64 69 73 61 62 6c 65 64  are not disabled
18a60 2c 20 31 20 69 66 20 74 68 65 79 20 61 72 65 2e  , 1 if they are.
18a70 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  .** </dd>.**.** 
18a80 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65  </dl>.*/.#define
18a90 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47   SQLITE_DBCONFIG
18aa0 5f 4d 41 49 4e 44 42 4e 41 4d 45 20 20 20 20 20  _MAINDBNAME     
18ab0 20 20 20 20 20 20 20 31 30 30 30 20 2f 2a 20 63         1000 /* c
18ac0 6f 6e 73 74 20 63 68 61 72 2a 20 2a 2f 0a 23 64  onst char* */.#d
18ad0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43  efine SQLITE_DBC
18ae0 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20  ONFIG_LOOKASIDE 
18af0 20 20 20 20 20 20 20 20 20 20 20 20 31 30 30 31              1001
18b00 20 2f 2a 20 76 6f 69 64 2a 20 69 6e 74 20 69 6e   /* void* int in
18b10 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  t */.#define SQL
18b20 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41  ITE_DBCONFIG_ENA
18b30 42 4c 45 5f 46 4b 45 59 20 20 20 20 20 20 20 20  BLE_FKEY        
18b40 20 20 20 31 30 30 32 20 2f 2a 20 69 6e 74 20 69     1002 /* int i
18b50 6e 74 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nt* */.#define S
18b60 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45  QLITE_DBCONFIG_E
18b70 4e 41 42 4c 45 5f 54 52 49 47 47 45 52 20 20 20  NABLE_TRIGGER   
18b80 20 20 20 20 20 31 30 30 33 20 2f 2a 20 69 6e 74       1003 /* int
18b90 20 69 6e 74 2a 20 2a 2f 0a 23 64 65 66 69 6e 65   int* */.#define
18ba0 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47   SQLITE_DBCONFIG
18bb0 5f 45 4e 41 42 4c 45 5f 46 54 53 33 5f 54 4f 4b  _ENABLE_FTS3_TOK
18bc0 45 4e 49 5a 45 52 20 31 30 30 34 20 2f 2a 20 69  ENIZER 1004 /* i
18bd0 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23 64 65 66 69  nt int* */.#defi
18be0 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46  ne SQLITE_DBCONF
18bf0 49 47 5f 45 4e 41 42 4c 45 5f 4c 4f 41 44 5f 45  IG_ENABLE_LOAD_E
18c00 58 54 45 4e 53 49 4f 4e 20 31 30 30 35 20 2f 2a  XTENSION 1005 /*
18c10 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23 64 65   int int* */.#de
18c20 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f  fine SQLITE_DBCO
18c30 4e 46 49 47 5f 4e 4f 5f 43 4b 50 54 5f 4f 4e 5f  NFIG_NO_CKPT_ON_
18c40 43 4c 4f 53 45 20 20 20 20 20 20 31 30 30 36 20  CLOSE      1006 
18c50 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 0a  /* int int* */..
18c60 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
18c70 20 45 6e 61 62 6c 65 20 4f 72 20 44 69 73 61 62   Enable Or Disab
18c80 6c 65 20 45 78 74 65 6e 64 65 64 20 52 65 73 75  le Extended Resu
18c90 6c 74 20 43 6f 64 65 73 0a 2a 2a 20 4d 45 54 48  lt Codes.** METH
18ca0 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a  OD: sqlite3.**.*
18cb0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65  * ^The sqlite3_e
18cc0 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63  xtended_result_c
18cd0 6f 64 65 73 28 29 20 72 6f 75 74 69 6e 65 20 65  odes() routine e
18ce0 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62 6c  nables or disabl
18cf0 65 73 20 74 68 65 0a 2a 2a 20 5b 65 78 74 65 6e  es the.** [exten
18d00 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73  ded result codes
18d10 5d 20 66 65 61 74 75 72 65 20 6f 66 20 53 51 4c  ] feature of SQL
18d20 69 74 65 2e 20 5e 54 68 65 20 65 78 74 65 6e 64  ite. ^The extend
18d30 65 64 20 72 65 73 75 6c 74 0a 2a 2a 20 63 6f 64  ed result.** cod
18d40 65 73 20 61 72 65 20 64 69 73 61 62 6c 65 64 20  es are disabled 
18d50 62 79 20 64 65 66 61 75 6c 74 20 66 6f 72 20 68  by default for h
18d60 69 73 74 6f 72 69 63 61 6c 20 63 6f 6d 70 61 74  istorical compat
18d70 69 62 69 6c 69 74 79 2e 0a 2a 2f 0a 69 6e 74 20  ibility..*/.int 
18d80 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64  sqlite3_extended
18d90 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 73 71  _result_codes(sq
18da0 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6f 6e 6f 66  lite3*, int onof
18db0 66 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  f);../*.** CAPI3
18dc0 52 45 46 3a 20 4c 61 73 74 20 49 6e 73 65 72 74  REF: Last Insert
18dd0 20 52 6f 77 69 64 0a 2a 2a 20 4d 45 54 48 4f 44   Rowid.** METHOD
18de0 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20  : sqlite3.**.** 
18df0 5e 45 61 63 68 20 65 6e 74 72 79 20 69 6e 20 6d  ^Each entry in m
18e00 6f 73 74 20 53 51 4c 69 74 65 20 74 61 62 6c 65  ost SQLite table
18e10 73 20 28 65 78 63 65 70 74 20 66 6f 72 20 5b 57  s (except for [W
18e20 49 54 48 4f 55 54 20 52 4f 57 49 44 5d 20 74 61  ITHOUT ROWID] ta
18e30 62 6c 65 73 29 0a 2a 2a 20 68 61 73 20 61 20 75  bles).** has a u
18e40 6e 69 71 75 65 20 36 34 2d 62 69 74 20 73 69 67  nique 64-bit sig
18e50 6e 65 64 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6b  ned.** integer k
18e60 65 79 20 63 61 6c 6c 65 64 20 74 68 65 20 5b 52  ey called the [R
18e70 4f 57 49 44 20 7c 20 22 72 6f 77 69 64 22 5d 2e  OWID | "rowid"].
18e80 20 5e 54 68 65 20 72 6f 77 69 64 20 69 73 20 61   ^The rowid is a
18e90 6c 77 61 79 73 20 61 76 61 69 6c 61 62 6c 65 0a  lways available.
18ea0 2a 2a 20 61 73 20 61 6e 20 75 6e 64 65 63 6c 61  ** as an undecla
18eb0 72 65 64 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 64  red column named
18ec0 20 52 4f 57 49 44 2c 20 4f 49 44 2c 20 6f 72 20   ROWID, OID, or 
18ed0 5f 52 4f 57 49 44 5f 20 61 73 20 6c 6f 6e 67 20  _ROWID_ as long 
18ee0 61 73 20 74 68 6f 73 65 0a 2a 2a 20 6e 61 6d 65  as those.** name
18ef0 73 20 61 72 65 20 6e 6f 74 20 61 6c 73 6f 20 75  s are not also u
18f00 73 65 64 20 62 79 20 65 78 70 6c 69 63 69 74 6c  sed by explicitl
18f10 79 20 64 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d  y declared colum
18f20 6e 73 2e 20 5e 49 66 0a 2a 2a 20 74 68 65 20 74  ns. ^If.** the t
18f30 61 62 6c 65 20 68 61 73 20 61 20 63 6f 6c 75 6d  able has a colum
18f40 6e 20 6f 66 20 74 79 70 65 20 5b 49 4e 54 45 47  n of type [INTEG
18f50 45 52 20 50 52 49 4d 41 52 59 20 4b 45 59 5d 20  ER PRIMARY KEY] 
18f60 74 68 65 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e  then that column
18f70 0a 2a 2a 20 69 73 20 61 6e 6f 74 68 65 72 20 61  .** is another a
18f80 6c 69 61 73 20 66 6f 72 20 74 68 65 20 72 6f 77  lias for the row
18f90 69 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  id..**.** ^The s
18fa0 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65  qlite3_last_inse
18fb0 72 74 5f 72 6f 77 69 64 28 44 29 20 69 6e 74 65  rt_rowid(D) inte
18fc0 72 66 61 63 65 20 75 73 75 61 6c 6c 79 20 72 65  rface usually re
18fd0 74 75 72 6e 73 20 74 68 65 20 5b 72 6f 77 69 64  turns the [rowid
18fe0 5d 20 6f 66 0a 2a 2a 20 74 68 65 20 6d 6f 73 74  ] of.** the most
18ff0 20 72 65 63 65 6e 74 20 73 75 63 63 65 73 73 66   recent successf
19000 75 6c 20 5b 49 4e 53 45 52 54 5d 20 69 6e 74 6f  ul [INSERT] into
19010 20 61 20 72 6f 77 69 64 20 74 61 62 6c 65 20 6f   a rowid table o
19020 72 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65  r [virtual table
19030 5d 0a 2a 2a 20 6f 6e 20 64 61 74 61 62 61 73 65  ].** on database
19040 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2e 20 5e   connection D. ^
19050 49 6e 73 65 72 74 73 20 69 6e 74 6f 20 5b 57 49  Inserts into [WI
19060 54 48 4f 55 54 20 52 4f 57 49 44 5d 20 74 61 62  THOUT ROWID] tab
19070 6c 65 73 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 72  les are not.** r
19080 65 63 6f 72 64 65 64 2e 20 5e 49 66 20 6e 6f 20  ecorded. ^If no 
19090 73 75 63 63 65 73 73 66 75 6c 20 5b 49 4e 53 45  successful [INSE
190a0 52 54 5d 73 20 69 6e 74 6f 20 72 6f 77 69 64 20  RT]s into rowid 
190b0 74 61 62 6c 65 73 20 68 61 76 65 20 65 76 65 72  tables have ever
190c0 20 6f 63 63 75 72 72 65 64 20 0a 2a 2a 20 6f 6e   occurred .** on
190d0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
190e0 6e 6e 65 63 74 69 6f 6e 20 44 2c 20 74 68 65 6e  nnection D, then
190f0 20 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e   sqlite3_last_in
19100 73 65 72 74 5f 72 6f 77 69 64 28 44 29 20 72 65  sert_rowid(D) re
19110 74 75 72 6e 73 20 0a 2a 2a 20 7a 65 72 6f 2e 0a  turns .** zero..
19120 2a 2a 0a 2a 2a 20 41 73 20 77 65 6c 6c 20 61 73  **.** As well as
19130 20 62 65 69 6e 67 20 73 65 74 20 61 75 74 6f 6d   being set autom
19140 61 74 69 63 61 6c 6c 79 20 61 73 20 72 6f 77 73  atically as rows
19150 20 61 72 65 20 69 6e 73 65 72 74 65 64 20 69 6e   are inserted in
19160 74 6f 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 74  to database.** t
19170 61 62 6c 65 73 2c 20 74 68 65 20 76 61 6c 75 65  ables, the value
19180 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 69   returned by thi
19190 73 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79 20 62  s function may b
191a0 65 20 73 65 74 20 65 78 70 6c 69 63 69 74 6c 79  e set explicitly
191b0 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   by.** [sqlite3_
191c0 73 65 74 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f  set_last_insert_
191d0 72 6f 77 69 64 28 29 5d 0a 2a 2a 0a 2a 2a 20 53  rowid()].**.** S
191e0 6f 6d 65 20 76 69 72 74 75 61 6c 20 74 61 62 6c  ome virtual tabl
191f0 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
19200 73 20 6d 61 79 20 49 4e 53 45 52 54 20 72 6f 77  s may INSERT row
19210 73 20 69 6e 74 6f 20 72 6f 77 69 64 20 74 61 62  s into rowid tab
19220 6c 65 73 20 61 73 0a 2a 2a 20 70 61 72 74 20 6f  les as.** part o
19230 66 20 63 6f 6d 6d 69 74 74 69 6e 67 20 61 20 74  f committing a t
19240 72 61 6e 73 61 63 74 69 6f 6e 20 28 65 2e 67 2e  ransaction (e.g.
19250 20 74 6f 20 66 6c 75 73 68 20 64 61 74 61 20 61   to flush data a
19260 63 63 75 6d 75 6c 61 74 65 64 20 69 6e 20 6d 65  ccumulated in me
19270 6d 6f 72 79 0a 2a 2a 20 74 6f 20 64 69 73 6b 29  mory.** to disk)
19280 2e 20 49 6e 20 74 68 69 73 20 63 61 73 65 20 73  . In this case s
19290 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20  ubsequent calls 
192a0 74 6f 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e  to this function
192b0 20 72 65 74 75 72 6e 20 74 68 65 20 72 6f 77 69   return the rowi
192c0 64 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20  d.** associated 
192d0 77 69 74 68 20 74 68 65 73 65 20 69 6e 74 65 72  with these inter
192e0 6e 61 6c 20 49 4e 53 45 52 54 20 6f 70 65 72 61  nal INSERT opera
192f0 74 69 6f 6e 73 2c 20 77 68 69 63 68 20 6c 65 61  tions, which lea
19300 64 73 20 74 6f 20 0a 2a 2a 20 75 6e 69 6e 74 75  ds to .** unintu
19310 69 74 69 76 65 20 72 65 73 75 6c 74 73 2e 20 56  itive results. V
19320 69 72 74 75 61 6c 20 74 61 62 6c 65 20 69 6d 70  irtual table imp
19330 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 74 68 61  lementations tha
19340 74 20 64 6f 20 77 72 69 74 65 20 74 6f 20 72 6f  t do write to ro
19350 77 69 64 0a 2a 2a 20 74 61 62 6c 65 73 20 69 6e  wid.** tables in
19360 20 74 68 69 73 20 77 61 79 20 63 61 6e 20 61 76   this way can av
19370 6f 69 64 20 74 68 69 73 20 70 72 6f 62 6c 65 6d  oid this problem
19380 20 62 79 20 72 65 73 74 6f 72 69 6e 67 20 74 68   by restoring th
19390 65 20 6f 72 69 67 69 6e 61 6c 20 0a 2a 2a 20 72  e original .** r
193a0 6f 77 69 64 20 76 61 6c 75 65 20 75 73 69 6e 67  owid value using
193b0 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 6c 61   [sqlite3_set_la
193c0 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28  st_insert_rowid(
193d0 29 5d 20 62 65 66 6f 72 65 20 72 65 74 75 72 6e  )] before return
193e0 69 6e 67 20 0a 2a 2a 20 63 6f 6e 74 72 6f 6c 20  ing .** control 
193f0 74 6f 20 74 68 65 20 75 73 65 72 2e 0a 2a 2a 0a  to the user..**.
19400 2a 2a 20 5e 28 49 66 20 61 6e 20 5b 49 4e 53 45  ** ^(If an [INSE
19410 52 54 5d 20 6f 63 63 75 72 73 20 77 69 74 68 69  RT] occurs withi
19420 6e 20 61 20 74 72 69 67 67 65 72 20 74 68 65 6e  n a trigger then
19430 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69   this routine wi
19440 6c 6c 20 0a 2a 2a 20 72 65 74 75 72 6e 20 74 68  ll .** return th
19450 65 20 5b 72 6f 77 69 64 5d 20 6f 66 20 74 68 65  e [rowid] of the
19460 20 69 6e 73 65 72 74 65 64 20 72 6f 77 20 61 73   inserted row as
19470 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 74 72 69   long as the tri
19480 67 67 65 72 20 69 73 20 0a 2a 2a 20 72 75 6e 6e  gger is .** runn
19490 69 6e 67 2e 20 4f 6e 63 65 20 74 68 65 20 74 72  ing. Once the tr
194a0 69 67 67 65 72 20 70 72 6f 67 72 61 6d 20 65 6e  igger program en
194b0 64 73 2c 20 74 68 65 20 76 61 6c 75 65 20 72 65  ds, the value re
194c0 74 75 72 6e 65 64 20 0a 2a 2a 20 62 79 20 74 68  turned .** by th
194d0 69 73 20 72 6f 75 74 69 6e 65 20 72 65 76 65 72  is routine rever
194e0 74 73 20 74 6f 20 77 68 61 74 20 69 74 20 77 61  ts to what it wa
194f0 73 20 62 65 66 6f 72 65 20 74 68 65 20 74 72 69  s before the tri
19500 67 67 65 72 20 77 61 73 20 66 69 72 65 64 2e 29  gger was fired.)
19510 5e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 5b 49 4e 53  ^.**.** ^An [INS
19520 45 52 54 5d 20 74 68 61 74 20 66 61 69 6c 73 20  ERT] that fails 
19530 64 75 65 20 74 6f 20 61 20 63 6f 6e 73 74 72 61  due to a constra
19540 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 20 69 73  int violation is
19550 20 6e 6f 74 20 61 0a 2a 2a 20 73 75 63 63 65 73   not a.** succes
19560 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d 20 61 6e  sful [INSERT] an
19570 64 20 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67  d does not chang
19580 65 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75  e the value retu
19590 72 6e 65 64 20 62 79 20 74 68 69 73 0a 2a 2a 20  rned by this.** 
195a0 72 6f 75 74 69 6e 65 2e 20 20 5e 54 68 75 73 20  routine.  ^Thus 
195b0 49 4e 53 45 52 54 20 4f 52 20 46 41 49 4c 2c 20  INSERT OR FAIL, 
195c0 49 4e 53 45 52 54 20 4f 52 20 49 47 4e 4f 52 45  INSERT OR IGNORE
195d0 2c 20 49 4e 53 45 52 54 20 4f 52 20 52 4f 4c 4c  , INSERT OR ROLL
195e0 42 41 43 4b 2c 0a 2a 2a 20 61 6e 64 20 49 4e 53  BACK,.** and INS
195f0 45 52 54 20 4f 52 20 41 42 4f 52 54 20 6d 61 6b  ERT OR ABORT mak
19600 65 20 6e 6f 20 63 68 61 6e 67 65 73 20 74 6f 20  e no changes to 
19610 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  the return value
19620 20 6f 66 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74   of this.** rout
19630 69 6e 65 20 77 68 65 6e 20 74 68 65 69 72 20 69  ine when their i
19640 6e 73 65 72 74 69 6f 6e 20 66 61 69 6c 73 2e 20  nsertion fails. 
19650 20 5e 28 57 68 65 6e 20 49 4e 53 45 52 54 20 4f   ^(When INSERT O
19660 52 20 52 45 50 4c 41 43 45 0a 2a 2a 20 65 6e 63  R REPLACE.** enc
19670 6f 75 6e 74 65 72 73 20 61 20 63 6f 6e 73 74 72  ounters a constr
19680 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 2c 20  aint violation, 
19690 69 74 20 64 6f 65 73 20 6e 6f 74 20 66 61 69 6c  it does not fail
196a0 2e 20 20 54 68 65 0a 2a 2a 20 49 4e 53 45 52 54  .  The.** INSERT
196b0 20 63 6f 6e 74 69 6e 75 65 73 20 74 6f 20 63 6f   continues to co
196c0 6d 70 6c 65 74 69 6f 6e 20 61 66 74 65 72 20 64  mpletion after d
196d0 65 6c 65 74 69 6e 67 20 72 6f 77 73 20 74 68 61  eleting rows tha
196e0 74 20 63 61 75 73 65 64 0a 2a 2a 20 74 68 65 20  t caused.** the 
196f0 63 6f 6e 73 74 72 61 69 6e 74 20 70 72 6f 62 6c  constraint probl
19700 65 6d 20 73 6f 20 49 4e 53 45 52 54 20 4f 52 20  em so INSERT OR 
19710 52 45 50 4c 41 43 45 20 77 69 6c 6c 20 61 6c 77  REPLACE will alw
19720 61 79 73 20 63 68 61 6e 67 65 0a 2a 2a 20 74 68  ays change.** th
19730 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f  e return value o
19740 66 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65  f this interface
19750 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 46 6f 72 20 74  .)^.**.** ^For t
19760 68 65 20 70 75 72 70 6f 73 65 73 20 6f 66 20 74  he purposes of t
19770 68 69 73 20 72 6f 75 74 69 6e 65 2c 20 61 6e 20  his routine, an 
19780 5b 49 4e 53 45 52 54 5d 20 69 73 20 63 6f 6e 73  [INSERT] is cons
19790 69 64 65 72 65 64 20 74 6f 0a 2a 2a 20 62 65 20  idered to.** be 
197a0 73 75 63 63 65 73 73 66 75 6c 20 65 76 65 6e 20  successful even 
197b0 69 66 20 69 74 20 69 73 20 73 75 62 73 65 71 75  if it is subsequ
197c0 65 6e 74 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63  ently rolled bac
197d0 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75  k..**.** This fu
197e0 6e 63 74 69 6f 6e 20 69 73 20 61 63 63 65 73 73  nction is access
197f0 69 62 6c 65 20 74 6f 20 53 51 4c 20 73 74 61 74  ible to SQL stat
19800 65 6d 65 6e 74 73 20 76 69 61 20 74 68 65 0a 2a  ements via the.*
19810 2a 20 5b 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72  * [last_insert_r
19820 6f 77 69 64 28 29 20 53 51 4c 20 66 75 6e 63 74  owid() SQL funct
19830 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61  ion]..**.** If a
19840 20 73 65 70 61 72 61 74 65 20 74 68 72 65 61 64   separate thread
19850 20 70 65 72 66 6f 72 6d 73 20 61 20 6e 65 77 20   performs a new 
19860 5b 49 4e 53 45 52 54 5d 20 6f 6e 20 74 68 65 20  [INSERT] on the 
19870 73 61 6d 65 0a 2a 2a 20 64 61 74 61 62 61 73 65  same.** database
19880 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 77 68 69 6c   connection whil
19890 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c  e the [sqlite3_l
198a0 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64  ast_insert_rowid
198b0 28 29 5d 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  ()].** function 
198c0 69 73 20 72 75 6e 6e 69 6e 67 20 61 6e 64 20 74  is running and t
198d0 68 75 73 20 63 68 61 6e 67 65 73 20 74 68 65 20  hus changes the 
198e0 6c 61 73 74 20 69 6e 73 65 72 74 20 5b 72 6f 77  last insert [row
198f0 69 64 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65  id],.** then the
19900 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20   value returned 
19910 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74  by [sqlite3_last
19920 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 5d  _insert_rowid()]
19930 20 69 73 0a 2a 2a 20 75 6e 70 72 65 64 69 63 74   is.** unpredict
19940 61 62 6c 65 20 61 6e 64 20 6d 69 67 68 74 20 6e  able and might n
19950 6f 74 20 65 71 75 61 6c 20 65 69 74 68 65 72 20  ot equal either 
19960 74 68 65 20 6f 6c 64 20 6f 72 20 74 68 65 20 6e  the old or the n
19970 65 77 0a 2a 2a 20 6c 61 73 74 20 69 6e 73 65 72  ew.** last inser
19980 74 20 5b 72 6f 77 69 64 5d 2e 0a 2a 2f 0a 73 71  t [rowid]..*/.sq
19990 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69  lite3_int64 sqli
199a0 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f  te3_last_insert_
199b0 72 6f 77 69 64 28 73 71 6c 69 74 65 33 2a 29 3b  rowid(sqlite3*);
199c0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
199d0 3a 20 53 65 74 20 74 68 65 20 4c 61 73 74 20 49  : Set the Last I
199e0 6e 73 65 72 74 20 52 6f 77 69 64 20 76 61 6c 75  nsert Rowid valu
199f0 65 2e 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  e..** METHOD: sq
19a00 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 54 68 65 20  lite3.**.** The 
19a10 73 71 6c 69 74 65 33 5f 73 65 74 5f 6c 61 73 74  sqlite3_set_last
19a20 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 44 2c  _insert_rowid(D,
19a30 20 52 29 20 6d 65 74 68 6f 64 20 61 6c 6c 6f 77   R) method allow
19a40 73 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  s the applicatio
19a50 6e 20 74 6f 0a 2a 2a 20 73 65 74 20 74 68 65 20  n to.** set the 
19a60 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62  value returned b
19a70 79 20 63 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65  y calling sqlite
19a80 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f  3_last_insert_ro
19a90 77 69 64 28 44 29 20 74 6f 20 52 20 0a 2a 2a 20  wid(D) to R .** 
19aa0 77 69 74 68 6f 75 74 20 69 6e 73 65 72 74 69 6e  without insertin
19ab0 67 20 61 20 72 6f 77 20 69 6e 74 6f 20 74 68 65  g a row into the
19ac0 20 64 61 74 61 62 61 73 65 2e 0a 2a 2f 0a 76 6f   database..*/.vo
19ad0 69 64 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 6c  id sqlite3_set_l
19ae0 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64  ast_insert_rowid
19af0 28 73 71 6c 69 74 65 33 2a 2c 73 71 6c 69 74 65  (sqlite3*,sqlite
19b00 33 5f 69 6e 74 36 34 29 3b 0a 0a 2f 2a 0a 2a 2a  3_int64);../*.**
19b10 20 43 41 50 49 33 52 45 46 3a 20 43 6f 75 6e 74   CAPI3REF: Count
19b20 20 54 68 65 20 4e 75 6d 62 65 72 20 4f 66 20 52   The Number Of R
19b30 6f 77 73 20 4d 6f 64 69 66 69 65 64 0a 2a 2a 20  ows Modified.** 
19b40 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a  METHOD: sqlite3.
19b50 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63  **.** ^This func
19b60 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65  tion returns the
19b70 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 20   number of rows 
19b80 6d 6f 64 69 66 69 65 64 2c 20 69 6e 73 65 72 74  modified, insert
19b90 65 64 20 6f 72 0a 2a 2a 20 64 65 6c 65 74 65 64  ed or.** deleted
19ba0 20 62 79 20 74 68 65 20 6d 6f 73 74 20 72 65 63   by the most rec
19bb0 65 6e 74 6c 79 20 63 6f 6d 70 6c 65 74 65 64 20  ently completed 
19bc0 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 20 6f  INSERT, UPDATE o
19bd0 72 20 44 45 4c 45 54 45 0a 2a 2a 20 73 74 61 74  r DELETE.** stat
19be0 65 6d 65 6e 74 20 6f 6e 20 74 68 65 20 64 61 74  ement on the dat
19bf0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
19c00 20 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68   specified by th
19c10 65 20 6f 6e 6c 79 20 70 61 72 61 6d 65 74 65 72  e only parameter
19c20 2e 0a 2a 2a 20 5e 45 78 65 63 75 74 69 6e 67 20  ..** ^Executing 
19c30 61 6e 79 20 6f 74 68 65 72 20 74 79 70 65 20 6f  any other type o
19c40 66 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  f SQL statement 
19c50 64 6f 65 73 20 6e 6f 74 20 6d 6f 64 69 66 79 20  does not modify 
19c60 74 68 65 20 76 61 6c 75 65 0a 2a 2a 20 72 65 74  the value.** ret
19c70 75 72 6e 65 64 20 62 79 20 74 68 69 73 20 66 75  urned by this fu
19c80 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 4f  nction..**.** ^O
19c90 6e 6c 79 20 63 68 61 6e 67 65 73 20 6d 61 64 65  nly changes made
19ca0 20 64 69 72 65 63 74 6c 79 20 62 79 20 74 68 65   directly by the
19cb0 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 20   INSERT, UPDATE 
19cc0 6f 72 20 44 45 4c 45 54 45 20 73 74 61 74 65 6d  or DELETE statem
19cd0 65 6e 74 20 61 72 65 0a 2a 2a 20 63 6f 6e 73 69  ent are.** consi
19ce0 64 65 72 65 64 20 2d 20 61 75 78 69 6c 69 61 72  dered - auxiliar
19cf0 79 20 63 68 61 6e 67 65 73 20 63 61 75 73 65 64  y changes caused
19d00 20 62 79 20 5b 43 52 45 41 54 45 20 54 52 49 47   by [CREATE TRIG
19d10 47 45 52 20 7c 20 74 72 69 67 67 65 72 73 5d 2c  GER | triggers],
19d20 20 0a 2a 2a 20 5b 66 6f 72 65 69 67 6e 20 6b 65   .** [foreign ke
19d30 79 20 61 63 74 69 6f 6e 73 5d 20 6f 72 20 5b 52  y actions] or [R
19d40 45 50 4c 41 43 45 5d 20 63 6f 6e 73 74 72 61 69  EPLACE] constrai
19d50 6e 74 20 72 65 73 6f 6c 75 74 69 6f 6e 20 61 72  nt resolution ar
19d60 65 20 6e 6f 74 20 63 6f 75 6e 74 65 64 2e 0a 2a  e not counted..*
19d70 2a 20 0a 2a 2a 20 43 68 61 6e 67 65 73 20 74 6f  * .** Changes to
19d80 20 61 20 76 69 65 77 20 74 68 61 74 20 61 72 65   a view that are
19d90 20 69 6e 74 65 72 63 65 70 74 65 64 20 62 79 20   intercepted by 
19da0 0a 2a 2a 20 5b 49 4e 53 54 45 41 44 20 4f 46 20  .** [INSTEAD OF 
19db0 74 72 69 67 67 65 72 20 7c 20 49 4e 53 54 45 41  trigger | INSTEA
19dc0 44 20 4f 46 20 74 72 69 67 67 65 72 73 5d 20 61  D OF triggers] a
19dd0 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65 64 2e 20  re not counted. 
19de0 5e 54 68 65 20 76 61 6c 75 65 20 0a 2a 2a 20 72  ^The value .** r
19df0 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74  eturned by sqlit
19e00 65 33 5f 63 68 61 6e 67 65 73 28 29 20 69 6d 6d  e3_changes() imm
19e10 65 64 69 61 74 65 6c 79 20 61 66 74 65 72 20 61  ediately after a
19e20 6e 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45  n INSERT, UPDATE
19e30 20 6f 72 20 0a 2a 2a 20 44 45 4c 45 54 45 20 73   or .** DELETE s
19e40 74 61 74 65 6d 65 6e 74 20 72 75 6e 20 6f 6e 20  tatement run on 
19e50 61 20 76 69 65 77 20 69 73 20 61 6c 77 61 79 73  a view is always
19e60 20 7a 65 72 6f 2e 20 4f 6e 6c 79 20 63 68 61 6e   zero. Only chan
19e70 67 65 73 20 6d 61 64 65 20 74 6f 20 72 65 61 6c  ges made to real
19e80 20 0a 2a 2a 20 74 61 62 6c 65 73 20 61 72 65 20   .** tables are 
19e90 63 6f 75 6e 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  counted..**.** T
19ea0 68 69 6e 67 73 20 61 72 65 20 6d 6f 72 65 20 63  hings are more c
19eb0 6f 6d 70 6c 69 63 61 74 65 64 20 69 66 20 74 68  omplicated if th
19ec0 65 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65  e sqlite3_change
19ed0 73 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 0a  s() function is.
19ee0 2a 2a 20 65 78 65 63 75 74 65 64 20 77 68 69 6c  ** executed whil
19ef0 65 20 61 20 74 72 69 67 67 65 72 20 70 72 6f 67  e a trigger prog
19f00 72 61 6d 20 69 73 20 72 75 6e 6e 69 6e 67 2e 20  ram is running. 
19f10 54 68 69 73 20 6d 61 79 20 68 61 70 70 65 6e 20  This may happen 
19f20 69 66 20 74 68 65 0a 2a 2a 20 70 72 6f 67 72 61  if the.** progra
19f30 6d 20 75 73 65 73 20 74 68 65 20 5b 63 68 61 6e  m uses the [chan
19f40 67 65 73 28 29 20 53 51 4c 20 66 75 6e 63 74 69  ges() SQL functi
19f50 6f 6e 5d 2c 20 6f 72 20 69 66 20 73 6f 6d 65 20  on], or if some 
19f60 6f 74 68 65 72 20 63 61 6c 6c 62 61 63 6b 0a 2a  other callback.*
19f70 2a 20 66 75 6e 63 74 69 6f 6e 20 69 6e 76 6f 6b  * function invok
19f80 65 73 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67  es sqlite3_chang
19f90 65 73 28 29 20 64 69 72 65 63 74 6c 79 2e 20 45  es() directly. E
19fa0 73 73 65 6e 74 69 61 6c 6c 79 3a 0a 2a 2a 20 0a  ssentially:.** .
19fb0 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69  ** <ul>.**   <li
19fc0 3e 20 5e 28 42 65 66 6f 72 65 20 65 6e 74 65 72  > ^(Before enter
19fd0 69 6e 67 20 61 20 74 72 69 67 67 65 72 20 70 72  ing a trigger pr
19fe0 6f 67 72 61 6d 20 74 68 65 20 76 61 6c 75 65 20  ogram the value 
19ff0 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 20  returned by.**  
1a000 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63 68        sqlite3_ch
1a010 61 6e 67 65 73 28 29 20 66 75 6e 63 74 69 6f 6e  anges() function
1a020 20 69 73 20 73 61 76 65 64 2e 20 41 66 74 65 72   is saved. After
1a030 20 74 68 65 20 74 72 69 67 67 65 72 20 70 72 6f   the trigger pro
1a040 67 72 61 6d 20 0a 2a 2a 20 20 20 20 20 20 20 20  gram .**        
1a050 68 61 73 20 66 69 6e 69 73 68 65 64 2c 20 74 68  has finished, th
1a060 65 20 6f 72 69 67 69 6e 61 6c 20 76 61 6c 75 65  e original value
1a070 20 69 73 20 72 65 73 74 6f 72 65 64 2e 29 5e 0a   is restored.)^.
1a080 2a 2a 20 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5e 28  ** .**   <li> ^(
1a090 57 69 74 68 69 6e 20 61 20 74 72 69 67 67 65 72  Within a trigger
1a0a0 20 70 72 6f 67 72 61 6d 20 65 61 63 68 20 49 4e   program each IN
1a0b0 53 45 52 54 2c 20 55 50 44 41 54 45 20 61 6e 64  SERT, UPDATE and
1a0c0 20 44 45 4c 45 54 45 20 0a 2a 2a 20 20 20 20 20   DELETE .**     
1a0d0 20 20 20 73 74 61 74 65 6d 65 6e 74 20 73 65 74     statement set
1a0e0 73 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75  s the value retu
1a0f0 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  rned by sqlite3_
1a100 63 68 61 6e 67 65 73 28 29 20 0a 2a 2a 20 20 20  changes() .**   
1a110 20 20 20 20 20 75 70 6f 6e 20 63 6f 6d 70 6c 65       upon comple
1a120 74 69 6f 6e 20 61 73 20 6e 6f 72 6d 61 6c 2e 20  tion as normal. 
1a130 4f 66 20 63 6f 75 72 73 65 2c 20 74 68 69 73 20  Of course, this 
1a140 76 61 6c 75 65 20 77 69 6c 6c 20 6e 6f 74 20 69  value will not i
1a150 6e 63 6c 75 64 65 20 0a 2a 2a 20 20 20 20 20 20  nclude .**      
1a160 20 20 61 6e 79 20 63 68 61 6e 67 65 73 20 70 65    any changes pe
1a170 72 66 6f 72 6d 65 64 20 62 79 20 73 75 62 2d 74  rformed by sub-t
1a180 72 69 67 67 65 72 73 2c 20 61 73 20 74 68 65 20  riggers, as the 
1a190 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28  sqlite3_changes(
1a1a0 29 20 0a 2a 2a 20 20 20 20 20 20 20 20 76 61 6c  ) .**        val
1a1b0 75 65 20 77 69 6c 6c 20 62 65 20 73 61 76 65 64  ue will be saved
1a1c0 20 61 6e 64 20 72 65 73 74 6f 72 65 64 20 61 66   and restored af
1a1d0 74 65 72 20 65 61 63 68 20 73 75 62 2d 74 72 69  ter each sub-tri
1a1e0 67 67 65 72 20 68 61 73 20 72 75 6e 2e 29 5e 0a  gger has run.)^.
1a1f0 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 20 0a 2a 2a 20  ** </ul>.** .** 
1a200 5e 54 68 69 73 20 6d 65 61 6e 73 20 74 68 61 74  ^This means that
1a210 20 69 66 20 74 68 65 20 63 68 61 6e 67 65 73 28   if the changes(
1a220 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 28  ) SQL function (
1a230 6f 72 20 73 69 6d 69 6c 61 72 29 20 69 73 20 75  or similar) is u
1a240 73 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 66 69  sed.** by the fi
1a250 72 73 74 20 49 4e 53 45 52 54 2c 20 55 50 44 41  rst INSERT, UPDA
1a260 54 45 20 6f 72 20 44 45 4c 45 54 45 20 73 74 61  TE or DELETE sta
1a270 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 61 20  tement within a 
1a280 74 72 69 67 67 65 72 2c 20 69 74 20 0a 2a 2a 20  trigger, it .** 
1a290 72 65 74 75 72 6e 73 20 74 68 65 20 76 61 6c 75  returns the valu
1a2a0 65 20 61 73 20 73 65 74 20 77 68 65 6e 20 74 68  e as set when th
1a2b0 65 20 63 61 6c 6c 69 6e 67 20 73 74 61 74 65 6d  e calling statem
1a2c0 65 6e 74 20 62 65 67 61 6e 20 65 78 65 63 75 74  ent began execut
1a2d0 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 69 74 20 69  ing..** ^If it i
1a2e0 73 20 75 73 65 64 20 62 79 20 74 68 65 20 73 65  s used by the se
1a2f0 63 6f 6e 64 20 6f 72 20 73 75 62 73 65 71 75 65  cond or subseque
1a300 6e 74 20 73 75 63 68 20 73 74 61 74 65 6d 65 6e  nt such statemen
1a310 74 20 77 69 74 68 69 6e 20 61 20 74 72 69 67 67  t within a trigg
1a320 65 72 20 0a 2a 2a 20 70 72 6f 67 72 61 6d 2c 20  er .** program, 
1a330 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e  the value return
1a340 65 64 20 72 65 66 6c 65 63 74 73 20 74 68 65 20  ed reflects the 
1a350 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 20 6d  number of rows m
1a360 6f 64 69 66 69 65 64 20 62 79 20 74 68 65 20 0a  odified by the .
1a370 2a 2a 20 70 72 65 76 69 6f 75 73 20 49 4e 53 45  ** previous INSE
1a380 52 54 2c 20 55 50 44 41 54 45 20 6f 72 20 44 45  RT, UPDATE or DE
1a390 4c 45 54 45 20 73 74 61 74 65 6d 65 6e 74 20 77  LETE statement w
1a3a0 69 74 68 69 6e 20 74 68 65 20 73 61 6d 65 20 74  ithin the same t
1a3b0 72 69 67 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 53 65  rigger..**.** Se
1a3c0 65 20 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69  e also the [sqli
1a3d0 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65  te3_total_change
1a3e0 73 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2c 20  s()] interface, 
1a3f0 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e 74 5f 63 68  the.** [count_ch
1a400 61 6e 67 65 73 20 70 72 61 67 6d 61 5d 2c 20 61  anges pragma], a
1a410 6e 64 20 74 68 65 20 5b 63 68 61 6e 67 65 73 28  nd the [changes(
1a420 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e  ) SQL function].
1a430 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70 61  .**.** If a sepa
1a440 72 61 74 65 20 74 68 72 65 61 64 20 6d 61 6b 65  rate thread make
1a450 73 20 63 68 61 6e 67 65 73 20 6f 6e 20 74 68 65  s changes on the
1a460 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63   same database c
1a470 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 77 68 69  onnection.** whi
1a480 6c 65 20 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e  le [sqlite3_chan
1a490 67 65 73 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e  ges()] is runnin
1a4a0 67 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65  g then the value
1a4b0 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 69 73 20   returned.** is 
1a4c0 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e  unpredictable an
1a4d0 64 20 6e 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c  d not meaningful
1a4e0 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
1a4f0 5f 63 68 61 6e 67 65 73 28 73 71 6c 69 74 65 33  _changes(sqlite3
1a500 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
1a510 52 45 46 3a 20 54 6f 74 61 6c 20 4e 75 6d 62 65  REF: Total Numbe
1a520 72 20 4f 66 20 52 6f 77 73 20 4d 6f 64 69 66 69  r Of Rows Modifi
1a530 65 64 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  ed.** METHOD: sq
1a540 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 69  lite3.**.** ^Thi
1a550 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72  s function retur
1a560 6e 73 20 74 68 65 20 74 6f 74 61 6c 20 6e 75 6d  ns the total num
1a570 62 65 72 20 6f 66 20 72 6f 77 73 20 69 6e 73 65  ber of rows inse
1a580 72 74 65 64 2c 20 6d 6f 64 69 66 69 65 64 20 6f  rted, modified o
1a590 72 0a 2a 2a 20 64 65 6c 65 74 65 64 20 62 79 20  r.** deleted by 
1a5a0 61 6c 6c 20 5b 49 4e 53 45 52 54 5d 2c 20 5b 55  all [INSERT], [U
1a5b0 50 44 41 54 45 5d 20 6f 72 20 5b 44 45 4c 45 54  PDATE] or [DELET
1a5c0 45 5d 20 73 74 61 74 65 6d 65 6e 74 73 20 63 6f  E] statements co
1a5d0 6d 70 6c 65 74 65 64 0a 2a 2a 20 73 69 6e 63 65  mpleted.** since
1a5e0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
1a5f0 6e 6e 65 63 74 69 6f 6e 20 77 61 73 20 6f 70 65  nnection was ope
1a600 6e 65 64 2c 20 69 6e 63 6c 75 64 69 6e 67 20 74  ned, including t
1a610 68 6f 73 65 20 65 78 65 63 75 74 65 64 20 61 73  hose executed as
1a620 0a 2a 2a 20 70 61 72 74 20 6f 66 20 74 72 69 67  .** part of trig
1a630 67 65 72 20 70 72 6f 67 72 61 6d 73 2e 20 5e 45  ger programs. ^E
1a640 78 65 63 75 74 69 6e 67 20 61 6e 79 20 6f 74 68  xecuting any oth
1a650 65 72 20 74 79 70 65 20 6f 66 20 53 51 4c 20 73  er type of SQL s
1a660 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 64 6f 65 73  tatement.** does
1a670 20 6e 6f 74 20 61 66 66 65 63 74 20 74 68 65 20   not affect the 
1a680 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62  value returned b
1a690 79 20 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f  y sqlite3_total_
1a6a0 63 68 61 6e 67 65 73 28 29 2e 0a 2a 2a 20 0a 2a  changes()..** .*
1a6b0 2a 20 5e 43 68 61 6e 67 65 73 20 6d 61 64 65 20  * ^Changes made 
1a6c0 61 73 20 70 61 72 74 20 6f 66 20 5b 66 6f 72 65  as part of [fore
1a6d0 69 67 6e 20 6b 65 79 20 61 63 74 69 6f 6e 73 5d  ign key actions]
1a6e0 20 61 72 65 20 69 6e 63 6c 75 64 65 64 20 69 6e   are included in
1a6f0 20 74 68 65 0a 2a 2a 20 63 6f 75 6e 74 2c 20 62   the.** count, b
1a700 75 74 20 74 68 6f 73 65 20 6d 61 64 65 20 61 73  ut those made as
1a710 20 70 61 72 74 20 6f 66 20 52 45 50 4c 41 43 45   part of REPLACE
1a720 20 63 6f 6e 73 74 72 61 69 6e 74 20 72 65 73 6f   constraint reso
1a730 6c 75 74 69 6f 6e 20 61 72 65 0a 2a 2a 20 6e 6f  lution are.** no
1a740 74 2e 20 5e 43 68 61 6e 67 65 73 20 74 6f 20 61  t. ^Changes to a
1a750 20 76 69 65 77 20 74 68 61 74 20 61 72 65 20 69   view that are i
1a760 6e 74 65 72 63 65 70 74 65 64 20 62 79 20 49 4e  ntercepted by IN
1a770 53 54 45 41 44 20 4f 46 20 74 72 69 67 67 65 72  STEAD OF trigger
1a780 73 20 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 63 6f  s .** are not co
1a790 75 6e 74 65 64 2e 0a 2a 2a 20 0a 2a 2a 20 53 65  unted..** .** Se
1a7a0 65 20 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69  e also the [sqli
1a7b0 74 65 33 5f 63 68 61 6e 67 65 73 28 29 5d 20 69  te3_changes()] i
1a7c0 6e 74 65 72 66 61 63 65 2c 20 74 68 65 0a 2a 2a  nterface, the.**
1a7d0 20 5b 63 6f 75 6e 74 5f 63 68 61 6e 67 65 73 20   [count_changes 
1a7e0 70 72 61 67 6d 61 5d 2c 20 61 6e 64 20 74 68 65  pragma], and the
1a7f0 20 5b 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28   [total_changes(
1a800 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e  ) SQL function].
1a810 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70 61  .**.** If a sepa
1a820 72 61 74 65 20 74 68 72 65 61 64 20 6d 61 6b 65  rate thread make
1a830 73 20 63 68 61 6e 67 65 73 20 6f 6e 20 74 68 65  s changes on the
1a840 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63   same database c
1a850 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 77 68 69  onnection.** whi
1a860 6c 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61  le [sqlite3_tota
1a870 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 73 20  l_changes()] is 
1a880 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20 74 68 65  running then the
1a890 20 76 61 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e   value.** return
1a8a0 65 64 20 69 73 20 75 6e 70 72 65 64 69 63 74 61  ed is unpredicta
1a8b0 62 6c 65 20 61 6e 64 20 6e 6f 74 20 6d 65 61 6e  ble and not mean
1a8c0 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 73  ingful..*/.int s
1a8d0 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61  qlite3_total_cha
1a8e0 6e 67 65 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a  nges(sqlite3*);.
1a8f0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1a900 20 49 6e 74 65 72 72 75 70 74 20 41 20 4c 6f 6e   Interrupt A Lon
1a910 67 2d 52 75 6e 6e 69 6e 67 20 51 75 65 72 79 0a  g-Running Query.
1a920 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
1a930 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66  e3.**.** ^This f
1a940 75 6e 63 74 69 6f 6e 20 63 61 75 73 65 73 20 61  unction causes a
1a950 6e 79 20 70 65 6e 64 69 6e 67 20 64 61 74 61 62  ny pending datab
1a960 61 73 65 20 6f 70 65 72 61 74 69 6f 6e 20 74 6f  ase operation to
1a970 20 61 62 6f 72 74 20 61 6e 64 0a 2a 2a 20 72 65   abort and.** re
1a980 74 75 72 6e 20 61 74 20 69 74 73 20 65 61 72 6c  turn at its earl
1a990 69 65 73 74 20 6f 70 70 6f 72 74 75 6e 69 74 79  iest opportunity
1a9a0 2e 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 69  . This routine i
1a9b0 73 20 74 79 70 69 63 61 6c 6c 79 0a 2a 2a 20 63  s typically.** c
1a9c0 61 6c 6c 65 64 20 69 6e 20 72 65 73 70 6f 6e 73  alled in respons
1a9d0 65 20 74 6f 20 61 20 75 73 65 72 20 61 63 74 69  e to a user acti
1a9e0 6f 6e 20 73 75 63 68 20 61 73 20 70 72 65 73 73  on such as press
1a9f0 69 6e 67 20 22 43 61 6e 63 65 6c 22 0a 2a 2a 20  ing "Cancel".** 
1aa00 6f 72 20 43 74 72 6c 2d 43 20 77 68 65 72 65 20  or Ctrl-C where 
1aa10 74 68 65 20 75 73 65 72 20 77 61 6e 74 73 20 61  the user wants a
1aa20 20 6c 6f 6e 67 20 71 75 65 72 79 20 6f 70 65 72   long query oper
1aa30 61 74 69 6f 6e 20 74 6f 20 68 61 6c 74 0a 2a 2a  ation to halt.**
1aa40 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e 0a 2a 2a   immediately..**
1aa50 0a 2a 2a 20 5e 49 74 20 69 73 20 73 61 66 65 20  .** ^It is safe 
1aa60 74 6f 20 63 61 6c 6c 20 74 68 69 73 20 72 6f 75  to call this rou
1aa70 74 69 6e 65 20 66 72 6f 6d 20 61 20 74 68 72 65  tine from a thre
1aa80 61 64 20 64 69 66 66 65 72 65 6e 74 20 66 72 6f  ad different fro
1aa90 6d 20 74 68 65 0a 2a 2a 20 74 68 72 65 61 64 20  m the.** thread 
1aaa0 74 68 61 74 20 69 73 20 63 75 72 72 65 6e 74 6c  that is currentl
1aab0 79 20 72 75 6e 6e 69 6e 67 20 74 68 65 20 64 61  y running the da
1aac0 74 61 62 61 73 65 20 6f 70 65 72 61 74 69 6f 6e  tabase operation
1aad0 2e 20 20 42 75 74 20 69 74 0a 2a 2a 20 69 73 20  .  But it.** is 
1aae0 6e 6f 74 20 73 61 66 65 20 74 6f 20 63 61 6c 6c  not safe to call
1aaf0 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69   this routine wi
1ab00 74 68 20 61 20 5b 64 61 74 61 62 61 73 65 20 63  th a [database c
1ab10 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 68 61 74 0a  onnection] that.
1ab20 2a 2a 20 69 73 20 63 6c 6f 73 65 64 20 6f 72 20  ** is closed or 
1ab30 6d 69 67 68 74 20 63 6c 6f 73 65 20 62 65 66 6f  might close befo
1ab40 72 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  re sqlite3_inter
1ab50 72 75 70 74 28 29 20 72 65 74 75 72 6e 73 2e 0a  rupt() returns..
1ab60 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20 53 51 4c  **.** ^If an SQL
1ab70 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 76 65   operation is ve
1ab80 72 79 20 6e 65 61 72 6c 79 20 66 69 6e 69 73 68  ry nearly finish
1ab90 65 64 20 61 74 20 74 68 65 20 74 69 6d 65 20 77  ed at the time w
1aba0 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 69  hen.** sqlite3_i
1abb0 6e 74 65 72 72 75 70 74 28 29 20 69 73 20 63 61  nterrupt() is ca
1abc0 6c 6c 65 64 2c 20 74 68 65 6e 20 69 74 20 6d 69  lled, then it mi
1abd0 67 68 74 20 6e 6f 74 20 68 61 76 65 20 61 6e 20  ght not have an 
1abe0 6f 70 70 6f 72 74 75 6e 69 74 79 0a 2a 2a 20 74  opportunity.** t
1abf0 6f 20 62 65 20 69 6e 74 65 72 72 75 70 74 65 64  o be interrupted
1ac00 20 61 6e 64 20 6d 69 67 68 74 20 63 6f 6e 74 69   and might conti
1ac10 6e 75 65 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f  nue to completio
1ac20 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 53 51 4c  n..**.** ^An SQL
1ac30 20 6f 70 65 72 61 74 69 6f 6e 20 74 68 61 74 20   operation that 
1ac40 69 73 20 69 6e 74 65 72 72 75 70 74 65 64 20 77  is interrupted w
1ac50 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  ill return [SQLI
1ac60 54 45 5f 49 4e 54 45 52 52 55 50 54 5d 2e 0a 2a  TE_INTERRUPT]..*
1ac70 2a 20 5e 49 66 20 74 68 65 20 69 6e 74 65 72 72  * ^If the interr
1ac80 75 70 74 65 64 20 53 51 4c 20 6f 70 65 72 61 74  upted SQL operat
1ac90 69 6f 6e 20 69 73 20 61 6e 20 49 4e 53 45 52 54  ion is an INSERT
1aca0 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44 45 4c  , UPDATE, or DEL
1acb0 45 54 45 0a 2a 2a 20 74 68 61 74 20 69 73 20 69  ETE.** that is i
1acc0 6e 73 69 64 65 20 61 6e 20 65 78 70 6c 69 63 69  nside an explici
1acd0 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 2c 20 74  t transaction, t
1ace0 68 65 6e 20 74 68 65 20 65 6e 74 69 72 65 20 74  hen the entire t
1acf0 72 61 6e 73 61 63 74 69 6f 6e 0a 2a 2a 20 77 69  ransaction.** wi
1ad00 6c 6c 20 62 65 20 72 6f 6c 6c 65 64 20 62 61 63  ll be rolled bac
1ad10 6b 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e  k automatically.
1ad20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
1ad30 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 44 29  te3_interrupt(D)
1ad40 20 63 61 6c 6c 20 69 73 20 69 6e 20 65 66 66 65   call is in effe
1ad50 63 74 20 75 6e 74 69 6c 20 61 6c 6c 20 63 75 72  ct until all cur
1ad60 72 65 6e 74 6c 79 20 72 75 6e 6e 69 6e 67 0a 2a  rently running.*
1ad70 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  * SQL statements
1ad80 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f   on [database co
1ad90 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 63 6f 6d 70  nnection] D comp
1ada0 6c 65 74 65 2e 20 20 5e 41 6e 79 20 6e 65 77 20  lete.  ^Any new 
1adb0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a  SQL statements.*
1adc0 2a 20 74 68 61 74 20 61 72 65 20 73 74 61 72 74  * that are start
1add0 65 64 20 61 66 74 65 72 20 74 68 65 20 73 71 6c  ed after the sql
1ade0 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29  ite3_interrupt()
1adf0 20 63 61 6c 6c 20 61 6e 64 20 62 65 66 6f 72 65   call and before
1ae00 20 74 68 65 20 0a 2a 2a 20 72 75 6e 6e 69 6e 67   the .** running
1ae10 20 73 74 61 74 65 6d 65 6e 74 73 20 72 65 61 63   statements reac
1ae20 68 65 73 20 7a 65 72 6f 20 61 72 65 20 69 6e 74  hes zero are int
1ae30 65 72 72 75 70 74 65 64 20 61 73 20 69 66 20 74  errupted as if t
1ae40 68 65 79 20 68 61 64 20 62 65 65 6e 0a 2a 2a 20  hey had been.** 
1ae50 72 75 6e 6e 69 6e 67 20 70 72 69 6f 72 20 74 6f  running prior to
1ae60 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74   the sqlite3_int
1ae70 65 72 72 75 70 74 28 29 20 63 61 6c 6c 2e 20 20  errupt() call.  
1ae80 5e 4e 65 77 20 53 51 4c 20 73 74 61 74 65 6d 65  ^New SQL stateme
1ae90 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20  nts.** that are 
1aea0 73 74 61 72 74 65 64 20 61 66 74 65 72 20 74 68  started after th
1aeb0 65 20 72 75 6e 6e 69 6e 67 20 73 74 61 74 65 6d  e running statem
1aec0 65 6e 74 20 63 6f 75 6e 74 20 72 65 61 63 68 65  ent count reache
1aed0 73 20 7a 65 72 6f 20 61 72 65 0a 2a 2a 20 6e 6f  s zero are.** no
1aee0 74 20 65 66 66 65 63 74 65 64 20 62 79 20 74 68  t effected by th
1aef0 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72  e sqlite3_interr
1af00 75 70 74 28 29 2e 0a 2a 2a 20 5e 41 20 63 61 6c  upt()..** ^A cal
1af10 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e 74  l to sqlite3_int
1af20 65 72 72 75 70 74 28 44 29 20 74 68 61 74 20 6f  errupt(D) that o
1af30 63 63 75 72 73 20 77 68 65 6e 20 74 68 65 72 65  ccurs when there
1af40 20 61 72 65 20 6e 6f 20 72 75 6e 6e 69 6e 67 0a   are no running.
1af50 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ** SQL statement
1af60 73 20 69 73 20 61 20 6e 6f 2d 6f 70 20 61 6e 64  s is a no-op and
1af70 20 68 61 73 20 6e 6f 20 65 66 66 65 63 74 20 6f   has no effect o
1af80 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  n SQL statements
1af90 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 73 74 61  .** that are sta
1afa0 72 74 65 64 20 61 66 74 65 72 20 74 68 65 20 73  rted after the s
1afb0 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
1afc0 28 29 20 63 61 6c 6c 20 72 65 74 75 72 6e 73 2e  () call returns.
1afd0 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 64 61  .**.** If the da
1afe0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1aff0 6e 20 63 6c 6f 73 65 73 20 77 68 69 6c 65 20 5b  n closes while [
1b000 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
1b010 74 28 29 5d 0a 2a 2a 20 69 73 20 72 75 6e 6e 69  t()].** is runni
1b020 6e 67 20 74 68 65 6e 20 62 61 64 20 74 68 69 6e  ng then bad thin
1b030 67 73 20 77 69 6c 6c 20 6c 69 6b 65 6c 79 20 68  gs will likely h
1b040 61 70 70 65 6e 2e 0a 2a 2f 0a 76 6f 69 64 20 73  appen..*/.void s
1b050 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
1b060 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a  (sqlite3*);../*.
1b070 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 74  ** CAPI3REF: Det
1b080 65 72 6d 69 6e 65 20 49 66 20 41 6e 20 53 51 4c  ermine If An SQL
1b090 20 53 74 61 74 65 6d 65 6e 74 20 49 73 20 43 6f   Statement Is Co
1b0a0 6d 70 6c 65 74 65 0a 2a 2a 0a 2a 2a 20 54 68 65  mplete.**.** The
1b0b0 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20  se routines are 
1b0c0 75 73 65 66 75 6c 20 64 75 72 69 6e 67 20 63 6f  useful during co
1b0d0 6d 6d 61 6e 64 2d 6c 69 6e 65 20 69 6e 70 75 74  mmand-line input
1b0e0 20 74 6f 20 64 65 74 65 72 6d 69 6e 65 20 69 66   to determine if
1b0f0 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 6c   the.** currentl
1b100 79 20 65 6e 74 65 72 65 64 20 74 65 78 74 20 73  y entered text s
1b110 65 65 6d 73 20 74 6f 20 66 6f 72 6d 20 61 20 63  eems to form a c
1b120 6f 6d 70 6c 65 74 65 20 53 51 4c 20 73 74 61 74  omplete SQL stat
1b130 65 6d 65 6e 74 20 6f 72 0a 2a 2a 20 69 66 20 61  ement or.** if a
1b140 64 64 69 74 69 6f 6e 61 6c 20 69 6e 70 75 74 20  dditional input 
1b150 69 73 20 6e 65 65 64 65 64 20 62 65 66 6f 72 65  is needed before
1b160 20 73 65 6e 64 69 6e 67 20 74 68 65 20 74 65 78   sending the tex
1b170 74 20 69 6e 74 6f 0a 2a 2a 20 53 51 4c 69 74 65  t into.** SQLite
1b180 20 66 6f 72 20 70 61 72 73 69 6e 67 2e 20 20 5e   for parsing.  ^
1b190 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72  These routines r
1b1a0 65 74 75 72 6e 20 31 20 69 66 20 74 68 65 20 69  eturn 1 if the i
1b1b0 6e 70 75 74 20 73 74 72 69 6e 67 0a 2a 2a 20 61  nput string.** a
1b1c0 70 70 65 61 72 73 20 74 6f 20 62 65 20 61 20 63  ppears to be a c
1b1d0 6f 6d 70 6c 65 74 65 20 53 51 4c 20 73 74 61 74  omplete SQL stat
1b1e0 65 6d 65 6e 74 2e 20 20 5e 41 20 73 74 61 74 65  ement.  ^A state
1b1f0 6d 65 6e 74 20 69 73 20 6a 75 64 67 65 64 20 74  ment is judged t
1b200 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65  o be.** complete
1b210 20 69 66 20 69 74 20 65 6e 64 73 20 77 69 74 68   if it ends with
1b220 20 61 20 73 65 6d 69 63 6f 6c 6f 6e 20 74 6f 6b   a semicolon tok
1b230 65 6e 20 61 6e 64 20 69 73 20 6e 6f 74 20 61 20  en and is not a 
1b240 70 72 65 66 69 78 20 6f 66 20 61 0a 2a 2a 20 77  prefix of a.** w
1b250 65 6c 6c 2d 66 6f 72 6d 65 64 20 43 52 45 41 54  ell-formed CREAT
1b260 45 20 54 52 49 47 47 45 52 20 73 74 61 74 65 6d  E TRIGGER statem
1b270 65 6e 74 2e 20 20 5e 53 65 6d 69 63 6f 6c 6f 6e  ent.  ^Semicolon
1b280 73 20 74 68 61 74 20 61 72 65 20 65 6d 62 65 64  s that are embed
1b290 64 65 64 20 77 69 74 68 69 6e 0a 2a 2a 20 73 74  ded within.** st
1b2a0 72 69 6e 67 20 6c 69 74 65 72 61 6c 73 20 6f 72  ring literals or
1b2b0 20 71 75 6f 74 65 64 20 69 64 65 6e 74 69 66 69   quoted identifi
1b2c0 65 72 20 6e 61 6d 65 73 20 6f 72 20 63 6f 6d 6d  er names or comm
1b2d0 65 6e 74 73 20 61 72 65 20 6e 6f 74 0a 2a 2a 20  ents are not.** 
1b2e0 69 6e 64 65 70 65 6e 64 65 6e 74 20 74 6f 6b 65  independent toke
1b2f0 6e 73 20 28 74 68 65 79 20 61 72 65 20 70 61 72  ns (they are par
1b300 74 20 6f 66 20 74 68 65 20 74 6f 6b 65 6e 20 69  t of the token i
1b310 6e 20 77 68 69 63 68 20 74 68 65 79 20 61 72 65  n which they are
1b320 0a 2a 2a 20 65 6d 62 65 64 64 65 64 29 20 61 6e  .** embedded) an
1b330 64 20 74 68 75 73 20 64 6f 20 6e 6f 74 20 63 6f  d thus do not co
1b340 75 6e 74 20 61 73 20 61 20 73 74 61 74 65 6d 65  unt as a stateme
1b350 6e 74 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20  nt terminator.  
1b360 5e 57 68 69 74 65 73 70 61 63 65 0a 2a 2a 20 61  ^Whitespace.** a
1b370 6e 64 20 63 6f 6d 6d 65 6e 74 73 20 74 68 61 74  nd comments that
1b380 20 66 6f 6c 6c 6f 77 20 74 68 65 20 66 69 6e 61   follow the fina
1b390 6c 20 73 65 6d 69 63 6f 6c 6f 6e 20 61 72 65 20  l semicolon are 
1b3a0 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  ignored..**.** ^
1b3b0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72  These routines r
1b3c0 65 74 75 72 6e 20 30 20 69 66 20 74 68 65 20 73  eturn 0 if the s
1b3d0 74 61 74 65 6d 65 6e 74 20 69 73 20 69 6e 63 6f  tatement is inco
1b3e0 6d 70 6c 65 74 65 2e 20 20 5e 49 66 20 61 0a 2a  mplete.  ^If a.*
1b3f0 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  * memory allocat
1b400 69 6f 6e 20 66 61 69 6c 73 2c 20 74 68 65 6e 20  ion fails, then 
1b410 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20 69 73 20  SQLITE_NOMEM is 
1b420 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  returned..**.** 
1b430 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20  ^These routines 
1b440 64 6f 20 6e 6f 74 20 70 61 72 73 65 20 74 68 65  do not parse the
1b450 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20   SQL statements 
1b460 74 68 75 73 0a 2a 2a 20 77 69 6c 6c 20 6e 6f 74  thus.** will not
1b470 20 64 65 74 65 63 74 20 73 79 6e 74 61 63 74 69   detect syntacti
1b480 63 61 6c 6c 79 20 69 6e 63 6f 72 72 65 63 74 20  cally incorrect 
1b490 53 51 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20  SQL..**.** ^(If 
1b4a0 53 51 4c 69 74 65 20 68 61 73 20 6e 6f 74 20 62  SQLite has not b
1b4b0 65 65 6e 20 69 6e 69 74 69 61 6c 69 7a 65 64 20  een initialized 
1b4c0 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 69  using [sqlite3_i
1b4d0 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20 70 72 69  nitialize()] pri
1b4e0 6f 72 20 0a 2a 2a 20 74 6f 20 69 6e 76 6f 6b 69  or .** to invoki
1b4f0 6e 67 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c  ng sqlite3_compl
1b500 65 74 65 31 36 28 29 20 74 68 65 6e 20 73 71 6c  ete16() then sql
1b510 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
1b520 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20  ) is invoked.** 
1b530 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62 79  automatically by
1b540 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74   sqlite3_complet
1b550 65 31 36 28 29 2e 20 20 49 66 20 74 68 61 74 20  e16().  If that 
1b560 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 66  initialization f
1b570 61 69 6c 73 2c 0a 2a 2a 20 74 68 65 6e 20 74 68  ails,.** then th
1b580 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66  e return value f
1b590 72 6f 6d 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70  rom sqlite3_comp
1b5a0 6c 65 74 65 31 36 28 29 20 77 69 6c 6c 20 62 65  lete16() will be
1b5b0 20 6e 6f 6e 2d 7a 65 72 6f 0a 2a 2a 20 72 65 67   non-zero.** reg
1b5c0 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68  ardless of wheth
1b5d0 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 69 6e  er or not the in
1b5e0 70 75 74 20 53 51 4c 20 69 73 20 63 6f 6d 70 6c  put SQL is compl
1b5f0 65 74 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65  ete.)^.**.** The
1b600 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 74   input to [sqlit
1b610 65 33 5f 63 6f 6d 70 6c 65 74 65 28 29 5d 20 6d  e3_complete()] m
1b620 75 73 74 20 62 65 20 61 20 7a 65 72 6f 2d 74 65  ust be a zero-te
1b630 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d  rminated.** UTF-
1b640 38 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20  8 string..**.** 
1b650 54 68 65 20 69 6e 70 75 74 20 74 6f 20 5b 73 71  The input to [sq
1b660 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36  lite3_complete16
1b670 28 29 5d 20 6d 75 73 74 20 62 65 20 61 20 7a 65  ()] must be a ze
1b680 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a  ro-terminated.**
1b690 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20 69   UTF-16 string i
1b6a0 6e 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72  n native byte or
1b6b0 64 65 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  der..*/.int sqli
1b6c0 74 65 33 5f 63 6f 6d 70 6c 65 74 65 28 63 6f 6e  te3_complete(con
1b6d0 73 74 20 63 68 61 72 20 2a 73 71 6c 29 3b 0a 69  st char *sql);.i
1b6e0 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c  nt sqlite3_compl
1b6f0 65 74 65 31 36 28 63 6f 6e 73 74 20 76 6f 69 64  ete16(const void
1b700 20 2a 73 71 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43   *sql);../*.** C
1b710 41 50 49 33 52 45 46 3a 20 52 65 67 69 73 74 65  API3REF: Registe
1b720 72 20 41 20 43 61 6c 6c 62 61 63 6b 20 54 6f 20  r A Callback To 
1b730 48 61 6e 64 6c 65 20 53 51 4c 49 54 45 5f 42 55  Handle SQLITE_BU
1b740 53 59 20 45 72 72 6f 72 73 0a 2a 2a 20 4b 45 59  SY Errors.** KEY
1b750 57 4f 52 44 53 3a 20 7b 62 75 73 79 2d 68 61 6e  WORDS: {busy-han
1b760 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b 7d 20 7b  dler callback} {
1b770 62 75 73 79 20 68 61 6e 64 6c 65 72 7d 0a 2a 2a  busy handler}.**
1b780 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
1b790 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
1b7a0 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72  te3_busy_handler
1b7b0 28 44 2c 58 2c 50 29 20 72 6f 75 74 69 6e 65 20  (D,X,P) routine 
1b7c0 73 65 74 73 20 61 20 63 61 6c 6c 62 61 63 6b 20  sets a callback 
1b7d0 66 75 6e 63 74 69 6f 6e 20 58 0a 2a 2a 20 74 68  function X.** th
1b7e0 61 74 20 6d 69 67 68 74 20 62 65 20 69 6e 76 6f  at might be invo
1b7f0 6b 65 64 20 77 69 74 68 20 61 72 67 75 6d 65 6e  ked with argumen
1b800 74 20 50 20 77 68 65 6e 65 76 65 72 0a 2a 2a 20  t P whenever.** 
1b810 61 6e 20 61 74 74 65 6d 70 74 20 69 73 20 6d 61  an attempt is ma
1b820 64 65 20 74 6f 20 61 63 63 65 73 73 20 61 20 64  de to access a d
1b830 61 74 61 62 61 73 65 20 74 61 62 6c 65 20 61 73  atabase table as
1b840 73 6f 63 69 61 74 65 64 20 77 69 74 68 0a 2a 2a  sociated with.**
1b850 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
1b860 63 74 69 6f 6e 5d 20 44 20 77 68 65 6e 20 61 6e  ction] D when an
1b870 6f 74 68 65 72 20 74 68 72 65 61 64 0a 2a 2a 20  other thread.** 
1b880 6f 72 20 70 72 6f 63 65 73 73 20 68 61 73 20 74  or process has t
1b890 68 65 20 74 61 62 6c 65 20 6c 6f 63 6b 65 64 2e  he table locked.
1b8a0 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
1b8b0 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 29 20 69  busy_handler() i
1b8c0 6e 74 65 72 66 61 63 65 20 69 73 20 75 73 65 64  nterface is used
1b8d0 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 0a 2a 2a   to implement.**
1b8e0 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74   [sqlite3_busy_t
1b8f0 69 6d 65 6f 75 74 28 29 5d 20 61 6e 64 20 5b 50  imeout()] and [P
1b900 52 41 47 4d 41 20 62 75 73 79 5f 74 69 6d 65 6f  RAGMA busy_timeo
1b910 75 74 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  ut]..**.** ^If t
1b920 68 65 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b  he busy callback
1b930 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 5b   is NULL, then [
1b940 53 51 4c 49 54 45 5f 42 55 53 59 5d 0a 2a 2a 20  SQLITE_BUSY].** 
1b950 69 73 20 72 65 74 75 72 6e 65 64 20 69 6d 6d 65  is returned imme
1b960 64 69 61 74 65 6c 79 20 75 70 6f 6e 20 65 6e 63  diately upon enc
1b970 6f 75 6e 74 65 72 69 6e 67 20 74 68 65 20 6c 6f  ountering the lo
1b980 63 6b 2e 20 20 5e 49 66 20 74 68 65 20 62 75 73  ck.  ^If the bus
1b990 79 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73  y callback.** is
1b9a0 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 20   not NULL, then 
1b9b0 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 6d 69 67  the callback mig
1b9c0 68 74 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 69  ht be invoked wi
1b9d0 74 68 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73  th two arguments
1b9e0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72  ..**.** ^The fir
1b9f0 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  st argument to t
1ba00 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20  he busy handler 
1ba10 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  is a copy of the
1ba20 20 76 6f 69 64 2a 20 70 6f 69 6e 74 65 72 20 77   void* pointer w
1ba30 68 69 63 68 0a 2a 2a 20 69 73 20 74 68 65 20 74  hich.** is the t
1ba40 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f  hird argument to
1ba50 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61   sqlite3_busy_ha
1ba60 6e 64 6c 65 72 28 29 2e 20 20 5e 54 68 65 20 73  ndler().  ^The s
1ba70 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74  econd argument t
1ba80 6f 0a 2a 2a 20 74 68 65 20 62 75 73 79 20 68 61  o.** the busy ha
1ba90 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b 20 69  ndler callback i
1baa0 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
1bab0 74 69 6d 65 73 20 74 68 61 74 20 74 68 65 20 62  times that the b
1bac0 75 73 79 20 68 61 6e 64 6c 65 72 20 68 61 73 0a  usy handler has.
1bad0 2a 2a 20 62 65 65 6e 20 69 6e 76 6f 6b 65 64 20  ** been invoked 
1bae0 70 72 65 76 69 6f 75 73 6c 79 20 66 6f 72 20 74  previously for t
1baf0 68 65 20 73 61 6d 65 20 6c 6f 63 6b 69 6e 67 20  he same locking 
1bb00 65 76 65 6e 74 2e 20 20 5e 49 66 20 74 68 65 0a  event.  ^If the.
1bb10 2a 2a 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b  ** busy callback
1bb20 20 72 65 74 75 72 6e 73 20 30 2c 20 74 68 65 6e   returns 0, then
1bb30 20 6e 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61   no additional a
1bb40 74 74 65 6d 70 74 73 20 61 72 65 20 6d 61 64 65  ttempts are made
1bb50 20 74 6f 0a 2a 2a 20 61 63 63 65 73 73 20 74 68   to.** access th
1bb60 65 20 64 61 74 61 62 61 73 65 20 61 6e 64 20 5b  e database and [
1bb70 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 69 73 20  SQLITE_BUSY] is 
1bb80 72 65 74 75 72 6e 65 64 0a 2a 2a 20 74 6f 20 74  returned.** to t
1bb90 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 0a  he application..
1bba0 2a 2a 20 5e 49 66 20 74 68 65 20 63 61 6c 6c 62  ** ^If the callb
1bbb0 61 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d  ack returns non-
1bbc0 7a 65 72 6f 2c 20 74 68 65 6e 20 61 6e 6f 74 68  zero, then anoth
1bbd0 65 72 20 61 74 74 65 6d 70 74 0a 2a 2a 20 69 73  er attempt.** is
1bbe0 20 6d 61 64 65 20 74 6f 20 61 63 63 65 73 73 20   made to access 
1bbf0 74 68 65 20 64 61 74 61 62 61 73 65 20 61 6e 64  the database and
1bc00 20 74 68 65 20 63 79 63 6c 65 20 72 65 70 65 61   the cycle repea
1bc10 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72  ts..**.** The pr
1bc20 65 73 65 6e 63 65 20 6f 66 20 61 20 62 75 73 79  esence of a busy
1bc30 20 68 61 6e 64 6c 65 72 20 64 6f 65 73 20 6e 6f   handler does no
1bc40 74 20 67 75 61 72 61 6e 74 65 65 20 74 68 61 74  t guarantee that
1bc50 20 69 74 20 77 69 6c 6c 20 62 65 20 69 6e 76 6f   it will be invo
1bc60 6b 65 64 0a 2a 2a 20 77 68 65 6e 20 74 68 65 72  ked.** when ther
1bc70 65 20 69 73 20 6c 6f 63 6b 20 63 6f 6e 74 65 6e  e is lock conten
1bc80 74 69 6f 6e 2e 20 5e 49 66 20 53 51 4c 69 74 65  tion. ^If SQLite
1bc90 20 64 65 74 65 72 6d 69 6e 65 73 20 74 68 61 74   determines that
1bca0 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20 62 75   invoking the bu
1bcb0 73 79 0a 2a 2a 20 68 61 6e 64 6c 65 72 20 63 6f  sy.** handler co
1bcc0 75 6c 64 20 72 65 73 75 6c 74 20 69 6e 20 61 20  uld result in a 
1bcd0 64 65 61 64 6c 6f 63 6b 2c 20 69 74 20 77 69 6c  deadlock, it wil
1bce0 6c 20 67 6f 20 61 68 65 61 64 20 61 6e 64 20 72  l go ahead and r
1bcf0 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 42 55  eturn [SQLITE_BU
1bd00 53 59 5d 0a 2a 2a 20 74 6f 20 74 68 65 20 61 70  SY].** to the ap
1bd10 70 6c 69 63 61 74 69 6f 6e 20 69 6e 73 74 65 61  plication instea
1bd20 64 20 6f 66 20 69 6e 76 6f 6b 69 6e 67 20 74 68  d of invoking th
1bd30 65 20 0a 2a 2a 20 62 75 73 79 20 68 61 6e 64 6c  e .** busy handl
1bd40 65 72 2e 0a 2a 2a 20 43 6f 6e 73 69 64 65 72 20  er..** Consider 
1bd50 61 20 73 63 65 6e 61 72 69 6f 20 77 68 65 72 65  a scenario where
1bd60 20 6f 6e 65 20 70 72 6f 63 65 73 73 20 69 73 20   one process is 
1bd70 68 6f 6c 64 69 6e 67 20 61 20 72 65 61 64 20 6c  holding a read l
1bd80 6f 63 6b 20 74 68 61 74 0a 2a 2a 20 69 74 20 69  ock that.** it i
1bd90 73 20 74 72 79 69 6e 67 20 74 6f 20 70 72 6f 6d  s trying to prom
1bda0 6f 74 65 20 74 6f 20 61 20 72 65 73 65 72 76 65  ote to a reserve
1bdb0 64 20 6c 6f 63 6b 20 61 6e 64 0a 2a 2a 20 61 20  d lock and.** a 
1bdc0 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 69  second process i
1bdd0 73 20 68 6f 6c 64 69 6e 67 20 61 20 72 65 73 65  s holding a rese
1bde0 72 76 65 64 20 6c 6f 63 6b 20 74 68 61 74 20 69  rved lock that i
1bdf0 74 20 69 73 20 74 72 79 69 6e 67 0a 2a 2a 20 74  t is trying.** t
1be00 6f 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61 6e 20  o promote to an 
1be10 65 78 63 6c 75 73 69 76 65 20 6c 6f 63 6b 2e 20  exclusive lock. 
1be20 20 54 68 65 20 66 69 72 73 74 20 70 72 6f 63 65   The first proce
1be30 73 73 20 63 61 6e 6e 6f 74 20 70 72 6f 63 65 65  ss cannot procee
1be40 64 0a 2a 2a 20 62 65 63 61 75 73 65 20 69 74 20  d.** because it 
1be50 69 73 20 62 6c 6f 63 6b 65 64 20 62 79 20 74 68  is blocked by th
1be60 65 20 73 65 63 6f 6e 64 20 61 6e 64 20 74 68 65  e second and the
1be70 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20   second process 
1be80 63 61 6e 6e 6f 74 0a 2a 2a 20 70 72 6f 63 65 65  cannot.** procee
1be90 64 20 62 65 63 61 75 73 65 20 69 74 20 69 73 20  d because it is 
1bea0 62 6c 6f 63 6b 65 64 20 62 79 20 74 68 65 20 66  blocked by the f
1beb0 69 72 73 74 2e 20 20 49 66 20 62 6f 74 68 20 70  irst.  If both p
1bec0 72 6f 63 65 73 73 65 73 0a 2a 2a 20 69 6e 76 6f  rocesses.** invo
1bed0 6b 65 20 74 68 65 20 62 75 73 79 20 68 61 6e 64  ke the busy hand
1bee0 6c 65 72 73 2c 20 6e 65 69 74 68 65 72 20 77 69  lers, neither wi
1bef0 6c 6c 20 6d 61 6b 65 20 61 6e 79 20 70 72 6f 67  ll make any prog
1bf00 72 65 73 73 2e 20 20 54 68 65 72 65 66 6f 72 65  ress.  Therefore
1bf10 2c 0a 2a 2a 20 53 51 4c 69 74 65 20 72 65 74 75  ,.** SQLite retu
1bf20 72 6e 73 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  rns [SQLITE_BUSY
1bf30 5d 20 66 6f 72 20 74 68 65 20 66 69 72 73 74 20  ] for the first 
1bf40 70 72 6f 63 65 73 73 2c 20 68 6f 70 69 6e 67 20  process, hoping 
1bf50 74 68 61 74 20 74 68 69 73 0a 2a 2a 20 77 69 6c  that this.** wil
1bf60 6c 20 69 6e 64 75 63 65 20 74 68 65 20 66 69 72  l induce the fir
1bf70 73 74 20 70 72 6f 63 65 73 73 20 74 6f 20 72 65  st process to re
1bf80 6c 65 61 73 65 20 69 74 73 20 72 65 61 64 20 6c  lease its read l
1bf90 6f 63 6b 20 61 6e 64 20 61 6c 6c 6f 77 0a 2a 2a  ock and allow.**
1bfa0 20 74 68 65 20 73 65 63 6f 6e 64 20 70 72 6f 63   the second proc
1bfb0 65 73 73 20 74 6f 20 70 72 6f 63 65 65 64 2e 0a  ess to proceed..
1bfc0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75  **.** ^The defau
1bfd0 6c 74 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b  lt busy callback
1bfe0 20 69 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20   is NULL..**.** 
1bff0 5e 28 54 68 65 72 65 20 63 61 6e 20 6f 6e 6c 79  ^(There can only
1c000 20 62 65 20 61 20 73 69 6e 67 6c 65 20 62 75 73   be a single bus
1c010 79 20 68 61 6e 64 6c 65 72 20 64 65 66 69 6e 65  y handler define
1c020 64 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20 5b 64  d for each.** [d
1c030 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1c040 6f 6e 5d 2e 20 20 53 65 74 74 69 6e 67 20 61 20  on].  Setting a 
1c050 6e 65 77 20 62 75 73 79 20 68 61 6e 64 6c 65 72  new busy handler
1c060 20 63 6c 65 61 72 73 20 61 6e 79 0a 2a 2a 20 70   clears any.** p
1c070 72 65 76 69 6f 75 73 6c 79 20 73 65 74 20 68 61  reviously set ha
1c080 6e 64 6c 65 72 2e 29 5e 20 20 5e 4e 6f 74 65 20  ndler.)^  ^Note 
1c090 74 68 61 74 20 63 61 6c 6c 69 6e 67 20 5b 73 71  that calling [sq
1c0a0 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f  lite3_busy_timeo
1c0b0 75 74 28 29 5d 0a 2a 2a 20 6f 72 20 65 76 61 6c  ut()].** or eval
1c0c0 75 61 74 69 6e 67 20 5b 50 52 41 47 4d 41 20 62  uating [PRAGMA b
1c0d0 75 73 79 5f 74 69 6d 65 6f 75 74 3d 4e 5d 20 77  usy_timeout=N] w
1c0e0 69 6c 6c 20 63 68 61 6e 67 65 20 74 68 65 0a 2a  ill change the.*
1c0f0 2a 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 61  * busy handler a
1c100 6e 64 20 74 68 75 73 20 63 6c 65 61 72 20 61 6e  nd thus clear an
1c110 79 20 70 72 65 76 69 6f 75 73 6c 79 20 73 65 74  y previously set
1c120 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a   busy handler..*
1c130 2a 0a 2a 2a 20 54 68 65 20 62 75 73 79 20 63 61  *.** The busy ca
1c140 6c 6c 62 61 63 6b 20 73 68 6f 75 6c 64 20 6e 6f  llback should no
1c150 74 20 74 61 6b 65 20 61 6e 79 20 61 63 74 69 6f  t take any actio
1c160 6e 73 20 77 68 69 63 68 20 6d 6f 64 69 66 79 20  ns which modify 
1c170 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20  the.** database 
1c180 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20  connection that 
1c190 69 6e 76 6f 6b 65 64 20 74 68 65 20 62 75 73 79  invoked the busy
1c1a0 20 68 61 6e 64 6c 65 72 2e 20 20 49 6e 20 6f 74   handler.  In ot
1c1b0 68 65 72 20 77 6f 72 64 73 2c 0a 2a 2a 20 74 68  her words,.** th
1c1c0 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 69  e busy handler i
1c1d0 73 20 6e 6f 74 20 72 65 65 6e 74 72 61 6e 74 2e  s not reentrant.
1c1e0 20 20 41 6e 79 20 73 75 63 68 20 61 63 74 69 6f    Any such actio
1c1f0 6e 73 0a 2a 2a 20 72 65 73 75 6c 74 20 69 6e 20  ns.** result in 
1c200 75 6e 64 65 66 69 6e 65 64 20 62 65 68 61 76 69  undefined behavi
1c210 6f 72 2e 0a 2a 2a 20 0a 2a 2a 20 41 20 62 75 73  or..** .** A bus
1c220 79 20 68 61 6e 64 6c 65 72 20 6d 75 73 74 20 6e  y handler must n
1c230 6f 74 20 63 6c 6f 73 65 20 74 68 65 20 64 61 74  ot close the dat
1c240 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1c250 0a 2a 2a 20 6f 72 20 5b 70 72 65 70 61 72 65 64  .** or [prepared
1c260 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74   statement] that
1c270 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 62 75 73   invoked the bus
1c280 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2f 0a 69 6e  y handler..*/.in
1c290 74 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68  t sqlite3_busy_h
1c2a0 61 6e 64 6c 65 72 28 73 71 6c 69 74 65 33 2a 2c  andler(sqlite3*,
1c2b0 69 6e 74 28 2a 29 28 76 6f 69 64 2a 2c 69 6e 74  int(*)(void*,int
1c2c0 29 2c 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  ),void*);../*.**
1c2d0 20 43 41 50 49 33 52 45 46 3a 20 53 65 74 20 41   CAPI3REF: Set A
1c2e0 20 42 75 73 79 20 54 69 6d 65 6f 75 74 0a 2a 2a   Busy Timeout.**
1c2f0 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
1c300 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75  .**.** ^This rou
1c310 74 69 6e 65 20 73 65 74 73 20 61 20 5b 73 71 6c  tine sets a [sql
1c320 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65  ite3_busy_handle
1c330 72 20 7c 20 62 75 73 79 20 68 61 6e 64 6c 65 72  r | busy handler
1c340 5d 20 74 68 61 74 20 73 6c 65 65 70 73 0a 2a 2a  ] that sleeps.**
1c350 20 66 6f 72 20 61 20 73 70 65 63 69 66 69 65 64   for a specified
1c360 20 61 6d 6f 75 6e 74 20 6f 66 20 74 69 6d 65 20   amount of time 
1c370 77 68 65 6e 20 61 20 74 61 62 6c 65 20 69 73 20  when a table is 
1c380 6c 6f 63 6b 65 64 2e 20 20 5e 54 68 65 20 68 61  locked.  ^The ha
1c390 6e 64 6c 65 72 0a 2a 2a 20 77 69 6c 6c 20 73 6c  ndler.** will sl
1c3a0 65 65 70 20 6d 75 6c 74 69 70 6c 65 20 74 69 6d  eep multiple tim
1c3b0 65 73 20 75 6e 74 69 6c 20 61 74 20 6c 65 61 73  es until at leas
1c3c0 74 20 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63 6f  t "ms" milliseco
1c3d0 6e 64 73 20 6f 66 20 73 6c 65 65 70 69 6e 67 0a  nds of sleeping.
1c3e0 2a 2a 20 68 61 76 65 20 61 63 63 75 6d 75 6c 61  ** have accumula
1c3f0 74 65 64 2e 20 20 5e 41 66 74 65 72 20 61 74 20  ted.  ^After at 
1c400 6c 65 61 73 74 20 22 6d 73 22 20 6d 69 6c 6c 69  least "ms" milli
1c410 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70  seconds of sleep
1c420 69 6e 67 2c 0a 2a 2a 20 74 68 65 20 68 61 6e 64  ing,.** the hand
1c430 6c 65 72 20 72 65 74 75 72 6e 73 20 30 20 77 68  ler returns 0 wh
1c440 69 63 68 20 63 61 75 73 65 73 20 5b 73 71 6c 69  ich causes [sqli
1c450 74 65 33 5f 73 74 65 70 28 29 5d 20 74 6f 20 72  te3_step()] to r
1c460 65 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45  eturn.** [SQLITE
1c470 5f 42 55 53 59 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 43  _BUSY]..**.** ^C
1c480 61 6c 6c 69 6e 67 20 74 68 69 73 20 72 6f 75 74  alling this rout
1c490 69 6e 65 20 77 69 74 68 20 61 6e 20 61 72 67 75  ine with an argu
1c4a0 6d 65 6e 74 20 6c 65 73 73 20 74 68 61 6e 20 6f  ment less than o
1c4b0 72 20 65 71 75 61 6c 20 74 6f 20 7a 65 72 6f 0a  r equal to zero.
1c4c0 2a 2a 20 74 75 72 6e 73 20 6f 66 66 20 61 6c 6c  ** turns off all
1c4d0 20 62 75 73 79 20 68 61 6e 64 6c 65 72 73 2e 0a   busy handlers..
1c4e0 2a 2a 0a 2a 2a 20 5e 28 54 68 65 72 65 20 63 61  **.** ^(There ca
1c4f0 6e 20 6f 6e 6c 79 20 62 65 20 61 20 73 69 6e 67  n only be a sing
1c500 6c 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20  le busy handler 
1c510 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61 72  for a particular
1c520 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f  .** [database co
1c530 6e 6e 65 63 74 69 6f 6e 5d 20 61 74 20 61 6e 79  nnection] at any
1c540 20 67 69 76 65 6e 20 6d 6f 6d 65 6e 74 2e 20 20   given moment.  
1c550 49 66 20 61 6e 6f 74 68 65 72 20 62 75 73 79 20  If another busy 
1c560 68 61 6e 64 6c 65 72 0a 2a 2a 20 77 61 73 20 64  handler.** was d
1c570 65 66 69 6e 65 64 20 20 28 75 73 69 6e 67 20 5b  efined  (using [
1c580 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e  sqlite3_busy_han
1c590 64 6c 65 72 28 29 5d 29 20 70 72 69 6f 72 20 74  dler()]) prior t
1c5a0 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 74 68 69  o calling.** thi
1c5b0 73 20 72 6f 75 74 69 6e 65 2c 20 74 68 61 74 20  s routine, that 
1c5c0 6f 74 68 65 72 20 62 75 73 79 20 68 61 6e 64 6c  other busy handl
1c5d0 65 72 20 69 73 20 63 6c 65 61 72 65 64 2e 29 5e  er is cleared.)^
1c5e0 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a  .**.** See also:
1c5f0 20 20 5b 50 52 41 47 4d 41 20 62 75 73 79 5f 74    [PRAGMA busy_t
1c600 69 6d 65 6f 75 74 5d 0a 2a 2f 0a 69 6e 74 20 73  imeout].*/.int s
1c610 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65  qlite3_busy_time
1c620 6f 75 74 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e  out(sqlite3*, in
1c630 74 20 6d 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  t ms);../*.** CA
1c640 50 49 33 52 45 46 3a 20 43 6f 6e 76 65 6e 69 65  PI3REF: Convenie
1c650 6e 63 65 20 52 6f 75 74 69 6e 65 73 20 46 6f 72  nce Routines For
1c660 20 52 75 6e 6e 69 6e 67 20 51 75 65 72 69 65 73   Running Queries
1c670 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
1c680 74 65 33 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69  te3.**.** This i
1c690 73 20 61 20 6c 65 67 61 63 79 20 69 6e 74 65 72  s a legacy inter
1c6a0 66 61 63 65 20 74 68 61 74 20 69 73 20 70 72 65  face that is pre
1c6b0 73 65 72 76 65 64 20 66 6f 72 20 62 61 63 6b 77  served for backw
1c6c0 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69  ards compatibili
1c6d0 74 79 2e 0a 2a 2a 20 55 73 65 20 6f 66 20 74 68  ty..** Use of th
1c6e0 69 73 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  is interface is 
1c6f0 6e 6f 74 20 72 65 63 6f 6d 6d 65 6e 64 65 64 2e  not recommended.
1c700 0a 2a 2a 0a 2a 2a 20 44 65 66 69 6e 69 74 69 6f  .**.** Definitio
1c710 6e 3a 20 41 20 3c 62 3e 72 65 73 75 6c 74 20 74  n: A <b>result t
1c720 61 62 6c 65 3c 2f 62 3e 20 69 73 20 6d 65 6d 6f  able</b> is memo
1c730 72 79 20 64 61 74 61 20 73 74 72 75 63 74 75 72  ry data structur
1c740 65 20 63 72 65 61 74 65 64 20 62 79 20 74 68 65  e created by the
1c750 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 67 65 74  .** [sqlite3_get
1c760 5f 74 61 62 6c 65 28 29 5d 20 69 6e 74 65 72 66  _table()] interf
1c770 61 63 65 2e 20 20 41 20 72 65 73 75 6c 74 20 74  ace.  A result t
1c780 61 62 6c 65 20 72 65 63 6f 72 64 73 20 74 68 65  able records the
1c790 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 20 71 75 65  .** complete que
1c7a0 72 79 20 72 65 73 75 6c 74 73 20 66 72 6f 6d 20  ry results from 
1c7b0 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 71 75 65 72  one or more quer
1c7c0 69 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74  ies..**.** The t
1c7d0 61 62 6c 65 20 63 6f 6e 63 65 70 74 75 61 6c 6c  able conceptuall
1c7e0 79 20 68 61 73 20 61 20 6e 75 6d 62 65 72 20 6f  y has a number o
1c7f0 66 20 72 6f 77 73 20 61 6e 64 20 63 6f 6c 75 6d  f rows and colum
1c800 6e 73 2e 20 20 42 75 74 0a 2a 2a 20 74 68 65 73  ns.  But.** thes
1c810 65 20 6e 75 6d 62 65 72 73 20 61 72 65 20 6e 6f  e numbers are no
1c820 74 20 70 61 72 74 20 6f 66 20 74 68 65 20 72 65  t part of the re
1c830 73 75 6c 74 20 74 61 62 6c 65 20 69 74 73 65 6c  sult table itsel
1c840 66 2e 20 20 54 68 65 73 65 0a 2a 2a 20 6e 75 6d  f.  These.** num
1c850 62 65 72 73 20 61 72 65 20 6f 62 74 61 69 6e 65  bers are obtaine
1c860 64 20 73 65 70 61 72 61 74 65 6c 79 2e 20 20 4c  d separately.  L
1c870 65 74 20 4e 20 62 65 20 74 68 65 20 6e 75 6d 62  et N be the numb
1c880 65 72 20 6f 66 20 72 6f 77 73 0a 2a 2a 20 61 6e  er of rows.** an
1c890 64 20 4d 20 62 65 20 74 68 65 20 6e 75 6d 62 65  d M be the numbe
1c8a0 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a  r of columns..**
1c8b0 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 61 62  .** A result tab
1c8c0 6c 65 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f  le is an array o
1c8d0 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 7a 65  f pointers to ze
1c8e0 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54  ro-terminated UT
1c8f0 46 2d 38 20 73 74 72 69 6e 67 73 2e 0a 2a 2a 20  F-8 strings..** 
1c900 54 68 65 72 65 20 61 72 65 20 28 4e 2b 31 29 2a  There are (N+1)*
1c910 4d 20 65 6c 65 6d 65 6e 74 73 20 69 6e 20 74 68  M elements in th
1c920 65 20 61 72 72 61 79 2e 20 20 54 68 65 20 66 69  e array.  The fi
1c930 72 73 74 20 4d 20 70 6f 69 6e 74 65 72 73 20 70  rst M pointers p
1c940 6f 69 6e 74 0a 2a 2a 20 74 6f 20 7a 65 72 6f 2d  oint.** to zero-
1c950 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72 69 6e  terminated strin
1c960 67 73 20 74 68 61 74 20 20 63 6f 6e 74 61 69 6e  gs that  contain
1c970 20 74 68 65 20 6e 61 6d 65 73 20 6f 66 20 74 68   the names of th
1c980 65 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 20 54 68  e columns..** Th
1c990 65 20 72 65 6d 61 69 6e 69 6e 67 20 65 6e 74 72  e remaining entr
1c9a0 69 65 73 20 61 6c 6c 20 70 6f 69 6e 74 20 74 6f  ies all point to
1c9b0 20 71 75 65 72 79 20 72 65 73 75 6c 74 73 2e 20   query results. 
1c9c0 20 4e 55 4c 4c 20 76 61 6c 75 65 73 20 72 65 73   NULL values res
1c9d0 75 6c 74 0a 2a 2a 20 69 6e 20 4e 55 4c 4c 20 70  ult.** in NULL p
1c9e0 6f 69 6e 74 65 72 73 2e 20 20 41 6c 6c 20 6f 74  ointers.  All ot
1c9f0 68 65 72 20 76 61 6c 75 65 73 20 61 72 65 20 69  her values are i
1ca00 6e 20 74 68 65 69 72 20 55 54 46 2d 38 20 7a 65  n their UTF-8 ze
1ca10 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a  ro-terminated.**
1ca20 20 73 74 72 69 6e 67 20 72 65 70 72 65 73 65 6e   string represen
1ca30 74 61 74 69 6f 6e 20 61 73 20 72 65 74 75 72 6e  tation as return
1ca40 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63  ed by [sqlite3_c
1ca50 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2e 0a 2a  olumn_text()]..*
1ca60 2a 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 61  *.** A result ta
1ca70 62 6c 65 20 6d 69 67 68 74 20 63 6f 6e 73 69 73  ble might consis
1ca80 74 20 6f 66 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  t of one or more
1ca90 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
1caa0 6f 6e 73 2e 0a 2a 2a 20 49 74 20 69 73 20 6e 6f  ons..** It is no
1cab0 74 20 73 61 66 65 20 74 6f 20 70 61 73 73 20 61  t safe to pass a
1cac0 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 64 69   result table di
1cad0 72 65 63 74 6c 79 20 74 6f 20 5b 73 71 6c 69 74  rectly to [sqlit
1cae0 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 20 41  e3_free()]..** A
1caf0 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 73 68   result table sh
1cb00 6f 75 6c 64 20 62 65 20 64 65 61 6c 6c 6f 63 61  ould be dealloca
1cb10 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ted using [sqlit
1cb20 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 5d  e3_free_table()]
1cb30 2e 0a 2a 2a 0a 2a 2a 20 5e 28 41 73 20 61 6e 20  ..**.** ^(As an 
1cb40 65 78 61 6d 70 6c 65 20 6f 66 20 74 68 65 20 72  example of the r
1cb50 65 73 75 6c 74 20 74 61 62 6c 65 20 66 6f 72 6d  esult table form
1cb60 61 74 2c 20 73 75 70 70 6f 73 65 20 61 20 71 75  at, suppose a qu
1cb70 65 72 79 20 72 65 73 75 6c 74 0a 2a 2a 20 69 73  ery result.** is
1cb80 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a   as follows:.**.
1cb90 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c  ** <blockquote><
1cba0 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20 20 20 4e  pre>.**        N
1cbb0 61 6d 65 20 20 20 20 20 20 20 20 7c 20 41 67 65  ame        | Age
1cbc0 0a 2a 2a 20 20 20 20 20 20 20 20 2d 2d 2d 2d 2d  .**        -----
1cbd0 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
1cbe0 2d 2d 0a 2a 2a 20 20 20 20 20 20 20 20 41 6c 69  --.**        Ali
1cbf0 63 65 20 20 20 20 20 20 20 7c 20 34 33 0a 2a 2a  ce       | 43.**
1cc00 20 20 20 20 20 20 20 20 42 6f 62 20 20 20 20 20          Bob     
1cc10 20 20 20 20 7c 20 32 38 0a 2a 2a 20 20 20 20 20      | 28.**     
1cc20 20 20 20 43 69 6e 64 79 20 20 20 20 20 20 20 7c     Cindy       |
1cc30 20 32 31 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62   21.** </pre></b
1cc40 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a  lockquote>.**.**
1cc50 20 54 68 65 72 65 20 61 72 65 20 74 77 6f 20 63   There are two c
1cc60 6f 6c 75 6d 6e 20 28 4d 3d 3d 32 29 20 61 6e 64  olumn (M==2) and
1cc70 20 74 68 72 65 65 20 72 6f 77 73 20 28 4e 3d 3d   three rows (N==
1cc80 33 29 2e 20 20 54 68 75 73 20 74 68 65 0a 2a 2a  3).  Thus the.**
1cc90 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 68 61   result table ha
1cca0 73 20 38 20 65 6e 74 72 69 65 73 2e 20 20 53 75  s 8 entries.  Su
1ccb0 70 70 6f 73 65 20 74 68 65 20 72 65 73 75 6c 74  ppose the result
1ccc0 20 74 61 62 6c 65 20 69 73 20 73 74 6f 72 65 64   table is stored
1ccd0 0a 2a 2a 20 69 6e 20 61 6e 20 61 72 72 61 79 20  .** in an array 
1cce0 6e 61 6d 65 73 20 61 7a 52 65 73 75 6c 74 2e 20  names azResult. 
1ccf0 20 54 68 65 6e 20 61 7a 52 65 73 75 6c 74 20 68   Then azResult h
1cd00 6f 6c 64 73 20 74 68 69 73 20 63 6f 6e 74 65 6e  olds this conten
1cd10 74 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71  t:.**.** <blockq
1cd20 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20  uote><pre>.**   
1cd30 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39       azResult&#9
1cd40 31 3b 30 5d 20 3d 20 22 4e 61 6d 65 22 3b 0a 2a  1;0] = "Name";.*
1cd50 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c  *        azResul
1cd60 74 26 23 39 31 3b 31 5d 20 3d 20 22 41 67 65 22  t&#91;1] = "Age"
1cd70 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65  ;.**        azRe
1cd80 73 75 6c 74 26 23 39 31 3b 32 5d 20 3d 20 22 41  sult&#91;2] = "A
1cd90 6c 69 63 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20  lice";.**       
1cda0 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 33 5d   azResult&#91;3]
1cdb0 20 3d 20 22 34 33 22 3b 0a 2a 2a 20 20 20 20 20   = "43";.**     
1cdc0 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b     azResult&#91;
1cdd0 34 5d 20 3d 20 22 42 6f 62 22 3b 0a 2a 2a 20 20  4] = "Bob";.**  
1cde0 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23        azResult&#
1cdf0 39 31 3b 35 5d 20 3d 20 22 32 38 22 3b 0a 2a 2a  91;5] = "28";.**
1ce00 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74          azResult
1ce10 26 23 39 31 3b 36 5d 20 3d 20 22 43 69 6e 64 79  &#91;6] = "Cindy
1ce20 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52  ";.**        azR
1ce30 65 73 75 6c 74 26 23 39 31 3b 37 5d 20 3d 20 22  esult&#91;7] = "
1ce40 32 31 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f  21";.** </pre></
1ce50 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a  blockquote>)^.**
1ce60 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
1ce70 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 66 75 6e  _get_table() fun
1ce80 63 74 69 6f 6e 20 65 76 61 6c 75 61 74 65 73 20  ction evaluates 
1ce90 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 73  one or more.** s
1cea0 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61 72 61 74  emicolon-separat
1ceb0 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ed SQL statement
1cec0 73 20 69 6e 20 74 68 65 20 7a 65 72 6f 2d 74 65  s in the zero-te
1ced0 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 0a 2a  rminated UTF-8.*
1cee0 2a 20 73 74 72 69 6e 67 20 6f 66 20 69 74 73 20  * string of its 
1cef0 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61 6e  2nd parameter an
1cf00 64 20 72 65 74 75 72 6e 73 20 61 20 72 65 73 75  d returns a resu
1cf10 6c 74 20 74 61 62 6c 65 20 74 6f 20 74 68 65 0a  lt table to the.
1cf20 2a 2a 20 70 6f 69 6e 74 65 72 20 67 69 76 65 6e  ** pointer given
1cf30 20 69 6e 20 69 74 73 20 33 72 64 20 70 61 72 61   in its 3rd para
1cf40 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 41 66 74  meter..**.** Aft
1cf50 65 72 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  er the applicati
1cf60 6f 6e 20 68 61 73 20 66 69 6e 69 73 68 65 64 20  on has finished 
1cf70 77 69 74 68 20 74 68 65 20 72 65 73 75 6c 74 20  with the result 
1cf80 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 67 65 74  from sqlite3_get
1cf90 5f 74 61 62 6c 65 28 29 2c 0a 2a 2a 20 69 74 20  _table(),.** it 
1cfa0 6d 75 73 74 20 70 61 73 73 20 74 68 65 20 72 65  must pass the re
1cfb0 73 75 6c 74 20 74 61 62 6c 65 20 70 6f 69 6e 74  sult table point
1cfc0 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 66 72  er to sqlite3_fr
1cfd0 65 65 5f 74 61 62 6c 65 28 29 20 69 6e 20 6f 72  ee_table() in or
1cfe0 64 65 72 20 74 6f 0a 2a 2a 20 72 65 6c 65 61 73  der to.** releas
1cff0 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 74 68 61  e the memory tha
1d000 74 20 77 61 73 20 6d 61 6c 6c 6f 63 65 64 2e 20  t was malloced. 
1d010 20 42 65 63 61 75 73 65 20 6f 66 20 74 68 65 20   Because of the 
1d020 77 61 79 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69  way the.** [sqli
1d030 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 68 61  te3_malloc()] ha
1d040 70 70 65 6e 73 20 77 69 74 68 69 6e 20 73 71 6c  ppens within sql
1d050 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29  ite3_get_table()
1d060 2c 20 74 68 65 20 63 61 6c 6c 69 6e 67 0a 2a 2a  , the calling.**
1d070 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 6e   function must n
1d080 6f 74 20 74 72 79 20 74 6f 20 63 61 6c 6c 20 5b  ot try to call [
1d090 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20  sqlite3_free()] 
1d0a0 64 69 72 65 63 74 6c 79 2e 20 20 4f 6e 6c 79 0a  directly.  Only.
1d0b0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  ** [sqlite3_free
1d0c0 5f 74 61 62 6c 65 28 29 5d 20 69 73 20 61 62 6c  _table()] is abl
1d0d0 65 20 74 6f 20 72 65 6c 65 61 73 65 20 74 68 65  e to release the
1d0e0 20 6d 65 6d 6f 72 79 20 70 72 6f 70 65 72 6c 79   memory properly
1d0f0 20 61 6e 64 20 73 61 66 65 6c 79 2e 0a 2a 2a 0a   and safely..**.
1d100 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 67  ** The sqlite3_g
1d110 65 74 5f 74 61 62 6c 65 28 29 20 69 6e 74 65 72  et_table() inter
1d120 66 61 63 65 20 69 73 20 69 6d 70 6c 65 6d 65 6e  face is implemen
1d130 74 65 64 20 61 73 20 61 20 77 72 61 70 70 65 72  ted as a wrapper
1d140 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b 73 71 6c 69   around.** [sqli
1d150 74 65 33 5f 65 78 65 63 28 29 5d 2e 20 20 54 68  te3_exec()].  Th
1d160 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61  e sqlite3_get_ta
1d170 62 6c 65 28 29 20 72 6f 75 74 69 6e 65 20 64 6f  ble() routine do
1d180 65 73 20 6e 6f 74 20 68 61 76 65 20 61 63 63 65  es not have acce
1d190 73 73 0a 2a 2a 20 74 6f 20 61 6e 79 20 69 6e 74  ss.** to any int
1d1a0 65 72 6e 61 6c 20 64 61 74 61 20 73 74 72 75 63  ernal data struc
1d1b0 74 75 72 65 73 20 6f 66 20 53 51 4c 69 74 65 2e  tures of SQLite.
1d1c0 20 20 49 74 20 75 73 65 73 20 6f 6e 6c 79 20 74    It uses only t
1d1d0 68 65 20 70 75 62 6c 69 63 0a 2a 2a 20 69 6e 74  he public.** int
1d1e0 65 72 66 61 63 65 20 64 65 66 69 6e 65 64 20 68  erface defined h
1d1f0 65 72 65 2e 20 20 41 73 20 61 20 63 6f 6e 73 65  ere.  As a conse
1d200 71 75 65 6e 63 65 2c 20 65 72 72 6f 72 73 20 74  quence, errors t
1d210 68 61 74 20 6f 63 63 75 72 20 69 6e 20 74 68 65  hat occur in the
1d220 0a 2a 2a 20 77 72 61 70 70 65 72 20 6c 61 79 65  .** wrapper laye
1d230 72 20 6f 75 74 73 69 64 65 20 6f 66 20 74 68 65  r outside of the
1d240 20 69 6e 74 65 72 6e 61 6c 20 5b 73 71 6c 69 74   internal [sqlit
1d250 65 33 5f 65 78 65 63 28 29 5d 20 63 61 6c 6c 20  e3_exec()] call 
1d260 61 72 65 20 6e 6f 74 0a 2a 2a 20 72 65 66 6c 65  are not.** refle
1d270 63 74 65 64 20 69 6e 20 73 75 62 73 65 71 75 65  cted in subseque
1d280 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c  nt calls to [sql
1d290 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d 20  ite3_errcode()] 
1d2a0 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65  or.** [sqlite3_e
1d2b0 72 72 6d 73 67 28 29 5d 2e 0a 2a 2f 0a 69 6e 74  rrmsg()]..*/.int
1d2c0 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62   sqlite3_get_tab
1d2d0 6c 65 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64  le(.  sqlite3 *d
1d2e0 62 2c 20 20 20 20 20 20 20 20 20 20 2f 2a 20 41  b,          /* A
1d2f0 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65 20  n open database 
1d300 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  */.  const char 
1d310 2a 7a 53 71 6c 2c 20 20 20 20 20 2f 2a 20 53 51  *zSql,     /* SQ
1d320 4c 20 74 6f 20 62 65 20 65 76 61 6c 75 61 74 65  L to be evaluate
1d330 64 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 2a 70  d */.  char ***p
1d340 61 7a 52 65 73 75 6c 74 2c 20 20 20 20 2f 2a 20  azResult,    /* 
1d350 52 65 73 75 6c 74 73 20 6f 66 20 74 68 65 20 71  Results of the q
1d360 75 65 72 79 20 2a 2f 0a 20 20 69 6e 74 20 2a 70  uery */.  int *p
1d370 6e 52 6f 77 2c 20 20 20 20 20 20 20 20 20 20 20  nRow,           
1d380 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 72 65 73  /* Number of res
1d390 75 6c 74 20 72 6f 77 73 20 77 72 69 74 74 65 6e  ult rows written
1d3a0 20 68 65 72 65 20 2a 2f 0a 20 20 69 6e 74 20 2a   here */.  int *
1d3b0 70 6e 43 6f 6c 75 6d 6e 2c 20 20 20 20 20 20 20  pnColumn,       
1d3c0 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 72 65   /* Number of re
1d3d0 73 75 6c 74 20 63 6f 6c 75 6d 6e 73 20 77 72 69  sult columns wri
1d3e0 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 20 20 63  tten here */.  c
1d3f0 68 61 72 20 2a 2a 70 7a 45 72 72 6d 73 67 20 20  har **pzErrmsg  
1d400 20 20 20 20 20 2f 2a 20 45 72 72 6f 72 20 6d 73       /* Error ms
1d410 67 20 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a  g written here *
1d420 2f 0a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  /.);.void sqlite
1d430 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 63 68 61  3_free_table(cha
1d440 72 20 2a 2a 72 65 73 75 6c 74 29 3b 0a 0a 2f 2a  r **result);../*
1d450 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6f  .** CAPI3REF: Fo
1d460 72 6d 61 74 74 65 64 20 53 74 72 69 6e 67 20 50  rmatted String P
1d470 72 69 6e 74 69 6e 67 20 46 75 6e 63 74 69 6f 6e  rinting Function
1d480 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f  s.**.** These ro
1d490 75 74 69 6e 65 73 20 61 72 65 20 77 6f 72 6b 2d  utines are work-
1d4a0 61 6c 69 6b 65 73 20 6f 66 20 74 68 65 20 22 70  alikes of the "p
1d4b0 72 69 6e 74 66 28 29 22 20 66 61 6d 69 6c 79 20  rintf()" family 
1d4c0 6f 66 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20  of functions.** 
1d4d0 66 72 6f 6d 20 74 68 65 20 73 74 61 6e 64 61 72  from the standar
1d4e0 64 20 43 20 6c 69 62 72 61 72 79 2e 0a 2a 2a 20  d C library..** 
1d4f0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 75  These routines u
1d500 6e 64 65 72 73 74 61 6e 64 20 6d 6f 73 74 20 6f  nderstand most o
1d510 66 20 74 68 65 20 63 6f 6d 6d 6f 6e 20 4b 26 52  f the common K&R
1d520 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 69   formatting opti
1d530 6f 6e 73 2c 0a 2a 2a 20 70 6c 75 73 20 73 6f 6d  ons,.** plus som
1d540 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 6e 6f 6e  e additional non
1d550 2d 73 74 61 6e 64 61 72 64 20 66 6f 72 6d 61 74  -standard format
1d560 73 2c 20 64 65 74 61 69 6c 65 64 20 62 65 6c 6f  s, detailed belo
1d570 77 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20  w..** Note that 
1d580 73 6f 6d 65 20 6f 66 20 74 68 65 20 6d 6f 72 65  some of the more
1d590 20 6f 62 73 63 75 72 65 20 66 6f 72 6d 61 74 74   obscure formatt
1d5a0 69 6e 67 20 6f 70 74 69 6f 6e 73 20 66 72 6f 6d  ing options from
1d5b0 20 72 65 63 65 6e 74 0a 2a 2a 20 43 2d 6c 69 62   recent.** C-lib
1d5c0 72 61 72 79 20 73 74 61 6e 64 61 72 64 73 20 61  rary standards a
1d5d0 72 65 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20  re omitted from 
1d5e0 74 68 69 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74  this implementat
1d5f0 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ion..**.** ^The 
1d600 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28  sqlite3_mprintf(
1d610 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 76 6d  ) and sqlite3_vm
1d620 70 72 69 6e 74 66 28 29 20 72 6f 75 74 69 6e 65  printf() routine
1d630 73 20 77 72 69 74 65 20 74 68 65 69 72 0a 2a 2a  s write their.**
1d640 20 72 65 73 75 6c 74 73 20 69 6e 74 6f 20 6d 65   results into me
1d650 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72  mory obtained fr
1d660 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  om [sqlite3_mall
1d670 6f 63 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73 74  oc()]..** The st
1d680 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20 62  rings returned b
1d690 79 20 74 68 65 73 65 20 74 77 6f 20 72 6f 75 74  y these two rout
1d6a0 69 6e 65 73 20 73 68 6f 75 6c 64 20 62 65 0a 2a  ines should be.*
1d6b0 2a 20 72 65 6c 65 61 73 65 64 20 62 79 20 5b 73  * released by [s
1d6c0 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 20  qlite3_free()]. 
1d6d0 20 5e 42 6f 74 68 20 72 6f 75 74 69 6e 65 73 20   ^Both routines 
1d6e0 72 65 74 75 72 6e 20 61 0a 2a 2a 20 4e 55 4c 4c  return a.** NULL
1d6f0 20 70 6f 69 6e 74 65 72 20 69 66 20 5b 73 71 6c   pointer if [sql
1d700 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 69  ite3_malloc()] i
1d710 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f  s unable to allo
1d720 63 61 74 65 20 65 6e 6f 75 67 68 0a 2a 2a 20 6d  cate enough.** m
1d730 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68  emory to hold th
1d740 65 20 72 65 73 75 6c 74 69 6e 67 20 73 74 72 69  e resulting stri
1d750 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20  ng..**.** ^(The 
1d760 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66  sqlite3_snprintf
1d770 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20 73 69  () routine is si
1d780 6d 69 6c 61 72 20 74 6f 20 22 73 6e 70 72 69 6e  milar to "snprin
1d790 74 66 28 29 22 20 66 72 6f 6d 0a 2a 2a 20 74 68  tf()" from.** th
1d7a0 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62  e standard C lib
1d7b0 72 61 72 79 2e 20 20 54 68 65 20 72 65 73 75 6c  rary.  The resul
1d7c0 74 20 69 73 20 77 72 69 74 74 65 6e 20 69 6e 74  t is written int
1d7d0 6f 20 74 68 65 0a 2a 2a 20 62 75 66 66 65 72 20  o the.** buffer 
1d7e0 73 75 70 70 6c 69 65 64 20 61 73 20 74 68 65 20  supplied as the 
1d7f0 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
1d800 20 77 68 6f 73 65 20 73 69 7a 65 20 69 73 20 67   whose size is g
1d810 69 76 65 6e 20 62 79 0a 2a 2a 20 74 68 65 20 66  iven by.** the f
1d820 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 2e 20  irst parameter. 
1d830 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 6f 72  Note that the or
1d840 64 65 72 20 6f 66 20 74 68 65 0a 2a 2a 20 66 69  der of the.** fi
1d850 72 73 74 20 74 77 6f 20 70 61 72 61 6d 65 74 65  rst two paramete
1d860 72 73 20 69 73 20 72 65 76 65 72 73 65 64 20 66  rs is reversed f
1d870 72 6f 6d 20 73 6e 70 72 69 6e 74 66 28 29 2e 29  rom snprintf().)
1d880 5e 20 20 54 68 69 73 20 69 73 20 61 6e 0a 2a 2a  ^  This is an.**
1d890 20 68 69 73 74 6f 72 69 63 61 6c 20 61 63 63 69   historical acci
1d8a0 64 65 6e 74 20 74 68 61 74 20 63 61 6e 6e 6f 74  dent that cannot
1d8b0 20 62 65 20 66 69 78 65 64 20 77 69 74 68 6f 75   be fixed withou
1d8c0 74 20 62 72 65 61 6b 69 6e 67 0a 2a 2a 20 62 61  t breaking.** ba
1d8d0 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62  ckwards compatib
1d8e0 69 6c 69 74 79 2e 20 20 5e 28 4e 6f 74 65 20 61  ility.  ^(Note a
1d8f0 6c 73 6f 20 74 68 61 74 20 73 71 6c 69 74 65 33  lso that sqlite3
1d900 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 72  _snprintf().** r
1d910 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
1d920 20 74 6f 20 69 74 73 20 62 75 66 66 65 72 20 69   to its buffer i
1d930 6e 73 74 65 61 64 20 6f 66 20 74 68 65 20 6e 75  nstead of the nu
1d940 6d 62 65 72 20 6f 66 0a 2a 2a 20 63 68 61 72 61  mber of.** chara
1d950 63 74 65 72 73 20 61 63 74 75 61 6c 6c 79 20 77  cters actually w
1d960 72 69 74 74 65 6e 20 69 6e 74 6f 20 74 68 65 20  ritten into the 
1d970 62 75 66 66 65 72 2e 29 5e 20 20 57 65 20 61 64  buffer.)^  We ad
1d980 6d 69 74 20 74 68 61 74 0a 2a 2a 20 74 68 65 20  mit that.** the 
1d990 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63  number of charac
1d9a0 74 65 72 73 20 77 72 69 74 74 65 6e 20 77 6f 75  ters written wou
1d9b0 6c 64 20 62 65 20 61 20 6d 6f 72 65 20 75 73 65  ld be a more use
1d9c0 66 75 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 76 61  ful return.** va
1d9d0 6c 75 65 20 62 75 74 20 77 65 20 63 61 6e 6e 6f  lue but we canno
1d9e0 74 20 63 68 61 6e 67 65 20 74 68 65 20 69 6d 70  t change the imp
1d9f0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 73  lementation of s
1da00 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28  qlite3_snprintf(
1da10 29 0a 2a 2a 20 6e 6f 77 20 77 69 74 68 6f 75 74  ).** now without
1da20 20 62 72 65 61 6b 69 6e 67 20 63 6f 6d 70 61 74   breaking compat
1da30 69 62 69 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e  ibility..**.** ^
1da40 41 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 62  As long as the b
1da50 75 66 66 65 72 20 73 69 7a 65 20 69 73 20 67 72  uffer size is gr
1da60 65 61 74 65 72 20 74 68 61 6e 20 7a 65 72 6f 2c  eater than zero,
1da70 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74   sqlite3_snprint
1da80 66 28 29 0a 2a 2a 20 67 75 61 72 61 6e 74 65 65  f().** guarantee
1da90 73 20 74 68 61 74 20 74 68 65 20 62 75 66 66 65  s that the buffe
1daa0 72 20 69 73 20 61 6c 77 61 79 73 20 7a 65 72 6f  r is always zero
1dab0 2d 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 5e 54  -terminated.  ^T
1dac0 68 65 20 66 69 72 73 74 0a 2a 2a 20 70 61 72 61  he first.** para
1dad0 6d 65 74 65 72 20 22 6e 22 20 69 73 20 74 68 65  meter "n" is the
1dae0 20 74 6f 74 61 6c 20 73 69 7a 65 20 6f 66 20 74   total size of t
1daf0 68 65 20 62 75 66 66 65 72 2c 20 69 6e 63 6c 75  he buffer, inclu
1db00 64 69 6e 67 20 73 70 61 63 65 20 66 6f 72 0a 2a  ding space for.*
1db10 2a 20 74 68 65 20 7a 65 72 6f 20 74 65 72 6d 69  * the zero termi
1db20 6e 61 74 6f 72 2e 20 20 53 6f 20 74 68 65 20 6c  nator.  So the l
1db30 6f 6e 67 65 73 74 20 73 74 72 69 6e 67 20 74 68  ongest string th
1db40 61 74 20 63 61 6e 20 62 65 20 63 6f 6d 70 6c 65  at can be comple
1db50 74 65 6c 79 0a 2a 2a 20 77 72 69 74 74 65 6e 20  tely.** written 
1db60 77 69 6c 6c 20 62 65 20 6e 2d 31 20 63 68 61 72  will be n-1 char
1db70 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54  acters..**.** ^T
1db80 68 65 20 73 71 6c 69 74 65 33 5f 76 73 6e 70 72  he sqlite3_vsnpr
1db90 69 6e 74 66 28 29 20 72 6f 75 74 69 6e 65 20 69  intf() routine i
1dba0 73 20 61 20 76 61 72 61 72 67 73 20 76 65 72 73  s a varargs vers
1dbb0 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f 73  ion of sqlite3_s
1dbc0 6e 70 72 69 6e 74 66 28 29 2e 0a 2a 2a 0a 2a 2a  nprintf()..**.**
1dbd0 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
1dbe0 61 6c 6c 20 69 6d 70 6c 65 6d 65 6e 74 20 73 6f  all implement so
1dbf0 6d 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 6f  me additional fo
1dc00 72 6d 61 74 74 69 6e 67 0a 2a 2a 20 6f 70 74 69  rmatting.** opti
1dc10 6f 6e 73 20 74 68 61 74 20 61 72 65 20 75 73 65  ons that are use
1dc20 66 75 6c 20 66 6f 72 20 63 6f 6e 73 74 72 75 63  ful for construc
1dc30 74 69 6e 67 20 53 51 4c 20 73 74 61 74 65 6d 65  ting SQL stateme
1dc40 6e 74 73 2e 0a 2a 2a 20 41 6c 6c 20 6f 66 20 74  nts..** All of t
1dc50 68 65 20 75 73 75 61 6c 20 70 72 69 6e 74 66 28  he usual printf(
1dc60 29 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74  ) formatting opt
1dc70 69 6f 6e 73 20 61 70 70 6c 79 2e 20 20 49 6e 20  ions apply.  In 
1dc80 61 64 64 69 74 69 6f 6e 2c 20 74 68 65 72 65 0a  addition, there.
1dc90 2a 2a 20 69 73 20 61 72 65 20 22 25 71 22 2c 20  ** is are "%q", 
1dca0 22 25 51 22 2c 20 22 25 77 22 20 61 6e 64 20 22  "%Q", "%w" and "
1dcb0 25 7a 22 20 6f 70 74 69 6f 6e 73 2e 0a 2a 2a 0a  %z" options..**.
1dcc0 2a 2a 20 5e 28 54 68 65 20 25 71 20 6f 70 74 69  ** ^(The %q opti
1dcd0 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20 25 73  on works like %s
1dce0 20 69 6e 20 74 68 61 74 20 69 74 20 73 75 62 73   in that it subs
1dcf0 74 69 74 75 74 65 73 20 61 20 6e 75 6c 2d 74 65  titutes a nul-te
1dd00 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74 72 69  rminated.** stri
1dd10 6e 67 20 66 72 6f 6d 20 74 68 65 20 61 72 67 75  ng from the argu
1dd20 6d 65 6e 74 20 6c 69 73 74 2e 20 20 42 75 74 20  ment list.  But 
1dd30 25 71 20 61 6c 73 6f 20 64 6f 75 62 6c 65 73 20  %q also doubles 
1dd40 65 76 65 72 79 20 27 5c 27 27 20 63 68 61 72 61  every '\'' chara
1dd50 63 74 65 72 2e 0a 2a 2a 20 25 71 20 69 73 20 64  cter..** %q is d
1dd60 65 73 69 67 6e 65 64 20 66 6f 72 20 75 73 65 20  esigned for use 
1dd70 69 6e 73 69 64 65 20 61 20 73 74 72 69 6e 67 20  inside a string 
1dd80 6c 69 74 65 72 61 6c 2e 29 5e 20 20 42 79 20 64  literal.)^  By d
1dd90 6f 75 62 6c 69 6e 67 20 65 61 63 68 20 27 5c 27  oubling each '\'
1dda0 27 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 20 69  '.** character i
1ddb0 74 20 65 73 63 61 70 65 73 20 74 68 61 74 20 63  t escapes that c
1ddc0 68 61 72 61 63 74 65 72 20 61 6e 64 20 61 6c 6c  haracter and all
1ddd0 6f 77 73 20 69 74 20 74 6f 20 62 65 20 69 6e 73  ows it to be ins
1dde0 65 72 74 65 64 20 69 6e 74 6f 0a 2a 2a 20 74 68  erted into.** th
1ddf0 65 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20  e string..**.** 
1de00 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 61 73 73  For example, ass
1de10 75 6d 65 20 74 68 65 20 73 74 72 69 6e 67 20 76  ume the string v
1de20 61 72 69 61 62 6c 65 20 7a 54 65 78 74 20 63 6f  ariable zText co
1de30 6e 74 61 69 6e 73 20 74 65 78 74 20 61 73 20 66  ntains text as f
1de40 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62  ollows:.**.** <b
1de50 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a  lockquote><pre>.
1de60 2a 2a 20 20 63 68 61 72 20 2a 7a 54 65 78 74 20  **  char *zText 
1de70 3d 20 22 49 74 27 73 20 61 20 68 61 70 70 79 20  = "It's a happy 
1de80 64 61 79 21 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e  day!";.** </pre>
1de90 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a  </blockquote>.**
1dea0 0a 2a 2a 20 4f 6e 65 20 63 61 6e 20 75 73 65 20  .** One can use 
1deb0 74 68 69 73 20 74 65 78 74 20 69 6e 20 61 6e 20  this text in an 
1dec0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 61 73  SQL statement as
1ded0 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20   follows:.**.** 
1dee0 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65  <blockquote><pre
1def0 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 53 51 4c  >.**  char *zSQL
1df00 20 3d 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e   = sqlite3_mprin
1df10 74 66 28 22 49 4e 53 45 52 54 20 49 4e 54 4f 20  tf("INSERT INTO 
1df20 74 61 62 6c 65 20 56 41 4c 55 45 53 28 27 25 71  table VALUES('%q
1df30 27 29 22 2c 20 7a 54 65 78 74 29 3b 0a 2a 2a 20  ')", zText);.** 
1df40 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 64 62   sqlite3_exec(db
1df50 2c 20 7a 53 51 4c 2c 20 30 2c 20 30 2c 20 30 29  , zSQL, 0, 0, 0)
1df60 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 66 72  ;.**  sqlite3_fr
1df70 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70  ee(zSQL);.** </p
1df80 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e  re></blockquote>
1df90 0a 2a 2a 0a 2a 2a 20 42 65 63 61 75 73 65 20 74  .**.** Because t
1dfa0 68 65 20 25 71 20 66 6f 72 6d 61 74 20 73 74 72  he %q format str
1dfb0 69 6e 67 20 69 73 20 75 73 65 64 2c 20 74 68 65  ing is used, the
1dfc0 20 27 5c 27 27 20 63 68 61 72 61 63 74 65 72 20   '\'' character 
1dfd0 69 6e 20 7a 54 65 78 74 0a 2a 2a 20 69 73 20 65  in zText.** is e
1dfe0 73 63 61 70 65 64 20 61 6e 64 20 74 68 65 20 53  scaped and the S
1dff0 51 4c 20 67 65 6e 65 72 61 74 65 64 20 69 73 20  QL generated is 
1e000 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a  as follows:.**.*
1e010 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70  * <blockquote><p
1e020 72 65 3e 0a 2a 2a 20 20 49 4e 53 45 52 54 20 49  re>.**  INSERT I
1e030 4e 54 4f 20 74 61 62 6c 65 31 20 56 41 4c 55 45  NTO table1 VALUE
1e040 53 28 27 49 74 27 27 73 20 61 20 68 61 70 70 79  S('It''s a happy
1e050 20 64 61 79 21 27 29 0a 2a 2a 20 3c 2f 70 72 65   day!').** </pre
1e060 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a  ></blockquote>.*
1e070 2a 0a 2a 2a 20 54 68 69 73 20 69 73 20 63 6f 72  *.** This is cor
1e080 72 65 63 74 2e 20 20 48 61 64 20 77 65 20 75 73  rect.  Had we us
1e090 65 64 20 25 73 20 69 6e 73 74 65 61 64 20 6f 66  ed %s instead of
1e0a0 20 25 71 2c 20 74 68 65 20 67 65 6e 65 72 61 74   %q, the generat
1e0b0 65 64 20 53 51 4c 0a 2a 2a 20 77 6f 75 6c 64 20  ed SQL.** would 
1e0c0 68 61 76 65 20 6c 6f 6f 6b 65 64 20 6c 69 6b 65  have looked like
1e0d0 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c   this:.**.** <bl
1e0e0 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a  ockquote><pre>.*
1e0f0 2a 20 20 49 4e 53 45 52 54 20 49 4e 54 4f 20 74  *  INSERT INTO t
1e100 61 62 6c 65 31 20 56 41 4c 55 45 53 28 27 49 74  able1 VALUES('It
1e110 27 73 20 61 20 68 61 70 70 79 20 64 61 79 21 27  's a happy day!'
1e120 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c  );.** </pre></bl
1e130 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20  ockquote>.**.** 
1e140 54 68 69 73 20 73 65 63 6f 6e 64 20 65 78 61 6d  This second exam
1e150 70 6c 65 20 69 73 20 61 6e 20 53 51 4c 20 73 79  ple is an SQL sy
1e160 6e 74 61 78 20 65 72 72 6f 72 2e 20 20 41 73 20  ntax error.  As 
1e170 61 20 67 65 6e 65 72 61 6c 20 72 75 6c 65 20 79  a general rule y
1e180 6f 75 20 73 68 6f 75 6c 64 0a 2a 2a 20 61 6c 77  ou should.** alw
1e190 61 79 73 20 75 73 65 20 25 71 20 69 6e 73 74 65  ays use %q inste
1e1a0 61 64 20 6f 66 20 25 73 20 77 68 65 6e 20 69 6e  ad of %s when in
1e1b0 73 65 72 74 69 6e 67 20 74 65 78 74 20 69 6e 74  serting text int
1e1c0 6f 20 61 20 73 74 72 69 6e 67 20 6c 69 74 65 72  o a string liter
1e1d0 61 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20  al..**.** ^(The 
1e1e0 25 51 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20  %Q option works 
1e1f0 6c 69 6b 65 20 25 71 20 65 78 63 65 70 74 20 69  like %q except i
1e200 74 20 61 6c 73 6f 20 61 64 64 73 20 73 69 6e 67  t also adds sing
1e210 6c 65 20 71 75 6f 74 65 73 20 61 72 6f 75 6e 64  le quotes around
1e220 0a 2a 2a 20 74 68 65 20 6f 75 74 73 69 64 65 20  .** the outside 
1e230 6f 66 20 74 68 65 20 74 6f 74 61 6c 20 73 74 72  of the total str
1e240 69 6e 67 2e 20 20 41 64 64 69 74 69 6f 6e 61 6c  ing.  Additional
1e250 6c 79 2c 20 69 66 20 74 68 65 20 70 61 72 61 6d  ly, if the param
1e260 65 74 65 72 20 69 6e 20 74 68 65 0a 2a 2a 20 61  eter in the.** a
1e270 72 67 75 6d 65 6e 74 20 6c 69 73 74 20 69 73 20  rgument list is 
1e280 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20  a NULL pointer, 
1e290 25 51 20 73 75 62 73 74 69 74 75 74 65 73 20 74  %Q substitutes t
1e2a0 68 65 20 74 65 78 74 20 22 4e 55 4c 4c 22 20 28  he text "NULL" (
1e2b0 77 69 74 68 6f 75 74 0a 2a 2a 20 73 69 6e 67 6c  without.** singl
1e2c0 65 20 71 75 6f 74 65 73 29 2e 29 5e 20 20 53 6f  e quotes).)^  So
1e2d0 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20 6f  , for example, o
1e2e0 6e 65 20 63 6f 75 6c 64 20 73 61 79 3a 0a 2a 2a  ne could say:.**
1e2f0 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
1e300 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a  <pre>.**  char *
1e310 7a 53 51 4c 20 3d 20 73 71 6c 69 74 65 33 5f 6d  zSQL = sqlite3_m
1e320 70 72 69 6e 74 66 28 22 49 4e 53 45 52 54 20 49  printf("INSERT I
1e330 4e 54 4f 20 74 61 62 6c 65 20 56 41 4c 55 45 53  NTO table VALUES
1e340 28 25 51 29 22 2c 20 7a 54 65 78 74 29 3b 0a 2a  (%Q)", zText);.*
1e350 2a 20 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  *  sqlite3_exec(
1e360 64 62 2c 20 7a 53 51 4c 2c 20 30 2c 20 30 2c 20  db, zSQL, 0, 0, 
1e370 30 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f  0);.**  sqlite3_
1e380 66 72 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c  free(zSQL);.** <
1e390 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
1e3a0 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64  e>.**.** The cod
1e3b0 65 20 61 62 6f 76 65 20 77 69 6c 6c 20 72 65 6e  e above will ren
1e3c0 64 65 72 20 61 20 63 6f 72 72 65 63 74 20 53 51  der a correct SQ
1e3d0 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 74  L statement in t
1e3e0 68 65 20 7a 53 51 4c 0a 2a 2a 20 76 61 72 69 61  he zSQL.** varia
1e3f0 62 6c 65 20 65 76 65 6e 20 69 66 20 74 68 65 20  ble even if the 
1e400 7a 54 65 78 74 20 76 61 72 69 61 62 6c 65 20 69  zText variable i
1e410 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
1e420 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 22 25  ..**.** ^(The "%
1e430 77 22 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70  w" formatting op
1e440 74 69 6f 6e 20 69 73 20 6c 69 6b 65 20 22 25 71  tion is like "%q
1e450 22 20 65 78 63 65 70 74 20 74 68 61 74 20 69 74  " except that it
1e460 20 65 78 70 65 63 74 73 20 74 6f 0a 2a 2a 20 62   expects to.** b
1e470 65 20 63 6f 6e 74 61 69 6e 65 64 20 77 69 74 68  e contained with
1e480 69 6e 20 64 6f 75 62 6c 65 2d 71 75 6f 74 65 73  in double-quotes
1e490 20 69 6e 73 74 65 61 64 20 6f 66 20 73 69 6e 67   instead of sing
1e4a0 6c 65 20 71 75 6f 74 65 73 2c 20 61 6e 64 20 69  le quotes, and i
1e4b0 74 0a 2a 2a 20 65 73 63 61 70 65 73 20 74 68 65  t.** escapes the
1e4c0 20 64 6f 75 62 6c 65 2d 71 75 6f 74 65 20 63 68   double-quote ch
1e4d0 61 72 61 63 74 65 72 20 69 6e 73 74 65 61 64 20  aracter instead 
1e4e0 6f 66 20 74 68 65 20 73 69 6e 67 6c 65 2d 71 75  of the single-qu
1e4f0 6f 74 65 0a 2a 2a 20 63 68 61 72 61 63 74 65 72  ote.** character
1e500 2e 29 5e 20 20 54 68 65 20 22 25 77 22 20 66 6f  .)^  The "%w" fo
1e510 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 20  rmatting option 
1e520 69 73 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20  is intended for 
1e530 73 61 66 65 6c 79 20 69 6e 73 65 72 74 69 6e 67  safely inserting
1e540 0a 2a 2a 20 74 61 62 6c 65 20 61 6e 64 20 63 6f  .** table and co
1e550 6c 75 6d 6e 20 6e 61 6d 65 73 20 69 6e 74 6f 20  lumn names into 
1e560 61 20 63 6f 6e 73 74 72 75 63 74 65 64 20 53 51  a constructed SQ
1e570 4c 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 0a  L statement..**.
1e580 2a 2a 20 5e 28 54 68 65 20 22 25 7a 22 20 66 6f  ** ^(The "%z" fo
1e590 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 20  rmatting option 
1e5a0 77 6f 72 6b 73 20 6c 69 6b 65 20 22 25 73 22 20  works like "%s" 
1e5b0 62 75 74 20 77 69 74 68 20 74 68 65 0a 2a 2a 20  but with the.** 
1e5c0 61 64 64 69 74 69 6f 6e 20 74 68 61 74 20 61 66  addition that af
1e5d0 74 65 72 20 74 68 65 20 73 74 72 69 6e 67 20 68  ter the string h
1e5e0 61 73 20 62 65 65 6e 20 72 65 61 64 20 61 6e 64  as been read and
1e5f0 20 63 6f 70 69 65 64 20 69 6e 74 6f 0a 2a 2a 20   copied into.** 
1e600 74 68 65 20 72 65 73 75 6c 74 2c 20 5b 73 71 6c  the result, [sql
1e610 69 74 65 33 5f 66 72 65 65 28 29 5d 20 69 73 20  ite3_free()] is 
1e620 63 61 6c 6c 65 64 20 6f 6e 20 74 68 65 20 69 6e  called on the in
1e630 70 75 74 20 73 74 72 69 6e 67 2e 29 5e 0a 2a 2f  put string.)^.*/
1e640 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 6d  .char *sqlite3_m
1e650 70 72 69 6e 74 66 28 63 6f 6e 73 74 20 63 68 61  printf(const cha
1e660 72 2a 2c 2e 2e 2e 29 3b 0a 63 68 61 72 20 2a 73  r*,...);.char *s
1e670 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74 66 28  qlite3_vmprintf(
1e680 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 76 61 5f  const char*, va_
1e690 6c 69 73 74 29 3b 0a 63 68 61 72 20 2a 73 71 6c  list);.char *sql
1e6a0 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 69 6e  ite3_snprintf(in
1e6b0 74 2c 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68  t,char*,const ch
1e6c0 61 72 2a 2c 20 2e 2e 2e 29 3b 0a 63 68 61 72 20  ar*, ...);.char 
1e6d0 2a 73 71 6c 69 74 65 33 5f 76 73 6e 70 72 69 6e  *sqlite3_vsnprin
1e6e0 74 66 28 69 6e 74 2c 63 68 61 72 2a 2c 63 6f 6e  tf(int,char*,con
1e6f0 73 74 20 63 68 61 72 2a 2c 20 76 61 5f 6c 69 73  st char*, va_lis
1e700 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
1e710 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f  REF: Memory Allo
1e720 63 61 74 69 6f 6e 20 53 75 62 73 79 73 74 65 6d  cation Subsystem
1e730 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74  .**.** The SQLit
1e740 65 20 63 6f 72 65 20 75 73 65 73 20 74 68 65 73  e core uses thes
1e750 65 20 74 68 72 65 65 20 72 6f 75 74 69 6e 65 73  e three routines
1e760 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73 20   for all of its 
1e770 6f 77 6e 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c 20  own.** internal 
1e780 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
1e790 6e 20 6e 65 65 64 73 2e 20 22 43 6f 72 65 22 20  n needs. "Core" 
1e7a0 69 6e 20 74 68 65 20 70 72 65 76 69 6f 75 73 20  in the previous 
1e7b0 73 65 6e 74 65 6e 63 65 0a 2a 2a 20 64 6f 65 73  sentence.** does
1e7c0 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 6f 70 65   not include ope
1e7d0 72 61 74 69 6e 67 2d 73 79 73 74 65 6d 20 73 70  rating-system sp
1e7e0 65 63 69 66 69 63 20 56 46 53 20 69 6d 70 6c 65  ecific VFS imple
1e7f0 6d 65 6e 74 61 74 69 6f 6e 2e 20 20 54 68 65 0a  mentation.  The.
1e800 2a 2a 20 57 69 6e 64 6f 77 73 20 56 46 53 20 75  ** Windows VFS u
1e810 73 65 73 20 6e 61 74 69 76 65 20 6d 61 6c 6c 6f  ses native mallo
1e820 63 28 29 20 61 6e 64 20 66 72 65 65 28 29 20 66  c() and free() f
1e830 6f 72 20 73 6f 6d 65 20 6f 70 65 72 61 74 69 6f  or some operatio
1e840 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ns..**.** ^The s
1e850 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20  qlite3_malloc() 
1e860 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
1e870 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 62  a pointer to a b
1e880 6c 6f 63 6b 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72  lock.** of memor
1e890 79 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74  y at least N byt
1e8a0 65 73 20 69 6e 20 6c 65 6e 67 74 68 2c 20 77 68  es in length, wh
1e8b0 65 72 65 20 4e 20 69 73 20 74 68 65 20 70 61 72  ere N is the par
1e8c0 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 73  ameter..** ^If s
1e8d0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20  qlite3_malloc() 
1e8e0 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 6f 62 74  is unable to obt
1e8f0 61 69 6e 20 73 75 66 66 69 63 69 65 6e 74 20 66  ain sufficient f
1e900 72 65 65 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20 69  ree.** memory, i
1e910 74 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c  t returns a NULL
1e920 20 70 6f 69 6e 74 65 72 2e 20 20 5e 49 66 20 74   pointer.  ^If t
1e930 68 65 20 70 61 72 61 6d 65 74 65 72 20 4e 20 74  he parameter N t
1e940 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c  o.** sqlite3_mal
1e950 6c 6f 63 28 29 20 69 73 20 7a 65 72 6f 20 6f 72  loc() is zero or
1e960 20 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20 73   negative then s
1e970 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20  qlite3_malloc() 
1e980 72 65 74 75 72 6e 73 0a 2a 2a 20 61 20 4e 55 4c  returns.** a NUL
1e990 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a  L pointer..**.**
1e9a0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 61   ^The sqlite3_ma
1e9b0 6c 6c 6f 63 36 34 28 4e 29 20 72 6f 75 74 69 6e  lloc64(N) routin
1e9c0 65 20 77 6f 72 6b 73 20 6a 75 73 74 20 6c 69 6b  e works just lik
1e9d0 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c  e.** sqlite3_mal
1e9e0 6c 6f 63 28 4e 29 20 65 78 63 65 70 74 20 74 68  loc(N) except th
1e9f0 61 74 20 4e 20 69 73 20 61 6e 20 75 6e 73 69 67  at N is an unsig
1ea00 6e 65 64 20 36 34 2d 62 69 74 20 69 6e 74 65 67  ned 64-bit integ
1ea10 65 72 20 69 6e 73 74 65 61 64 0a 2a 2a 20 6f 66  er instead.** of
1ea20 20 61 20 73 69 67 6e 65 64 20 33 32 2d 62 69 74   a signed 32-bit
1ea30 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 0a 2a 2a 20   integer..**.** 
1ea40 5e 43 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33  ^Calling sqlite3
1ea50 5f 66 72 65 65 28 29 20 77 69 74 68 20 61 20 70  _free() with a p
1ea60 6f 69 6e 74 65 72 20 70 72 65 76 69 6f 75 73 6c  ointer previousl
1ea70 79 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79  y returned.** by
1ea80 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28   sqlite3_malloc(
1ea90 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 61  ) or sqlite3_rea
1eaa0 6c 6c 6f 63 28 29 20 72 65 6c 65 61 73 65 73 20  lloc() releases 
1eab0 74 68 61 74 20 6d 65 6d 6f 72 79 20 73 6f 0a 2a  that memory so.*
1eac0 2a 20 74 68 61 74 20 69 74 20 6d 69 67 68 74 20  * that it might 
1ead0 62 65 20 72 65 75 73 65 64 2e 20 20 5e 54 68 65  be reused.  ^The
1eae0 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20   sqlite3_free() 
1eaf0 72 6f 75 74 69 6e 65 20 69 73 0a 2a 2a 20 61 20  routine is.** a 
1eb00 6e 6f 2d 6f 70 20 69 66 20 69 73 20 63 61 6c 6c  no-op if is call
1eb10 65 64 20 77 69 74 68 20 61 20 4e 55 4c 4c 20 70  ed with a NULL p
1eb20 6f 69 6e 74 65 72 2e 20 20 50 61 73 73 69 6e 67  ointer.  Passing
1eb30 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a   a NULL pointer.
1eb40 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f 66 72  ** to sqlite3_fr
1eb50 65 65 28 29 20 69 73 20 68 61 72 6d 6c 65 73 73  ee() is harmless
1eb60 2e 20 20 41 66 74 65 72 20 62 65 69 6e 67 20 66  .  After being f
1eb70 72 65 65 64 2c 20 6d 65 6d 6f 72 79 0a 2a 2a 20  reed, memory.** 
1eb80 73 68 6f 75 6c 64 20 6e 65 69 74 68 65 72 20 62  should neither b
1eb90 65 20 72 65 61 64 20 6e 6f 72 20 77 72 69 74 74  e read nor writt
1eba0 65 6e 2e 20 20 45 76 65 6e 20 72 65 61 64 69 6e  en.  Even readin
1ebb0 67 20 70 72 65 76 69 6f 75 73 6c 79 20 66 72 65  g previously fre
1ebc0 65 64 0a 2a 2a 20 6d 65 6d 6f 72 79 20 6d 69 67  ed.** memory mig
1ebd0 68 74 20 72 65 73 75 6c 74 20 69 6e 20 61 20 73  ht result in a s
1ebe0 65 67 6d 65 6e 74 61 74 69 6f 6e 20 66 61 75 6c  egmentation faul
1ebf0 74 20 6f 72 20 6f 74 68 65 72 20 73 65 76 65 72  t or other sever
1ec00 65 20 65 72 72 6f 72 2e 0a 2a 2a 20 4d 65 6d 6f  e error..** Memo
1ec10 72 79 20 63 6f 72 72 75 70 74 69 6f 6e 2c 20 61  ry corruption, a
1ec20 20 73 65 67 6d 65 6e 74 61 74 69 6f 6e 20 66 61   segmentation fa
1ec30 75 6c 74 2c 20 6f 72 20 6f 74 68 65 72 20 73 65  ult, or other se
1ec40 76 65 72 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 69  vere error.** mi
1ec50 67 68 74 20 72 65 73 75 6c 74 20 69 66 20 73 71  ght result if sq
1ec60 6c 69 74 65 33 5f 66 72 65 65 28 29 20 69 73 20  lite3_free() is 
1ec70 63 61 6c 6c 65 64 20 77 69 74 68 20 61 20 6e 6f  called with a no
1ec80 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74  n-NULL pointer t
1ec90 68 61 74 0a 2a 2a 20 77 61 73 20 6e 6f 74 20 6f  hat.** was not o
1eca0 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 73 71 6c  btained from sql
1ecb0 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72  ite3_malloc() or
1ecc0 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
1ecd0 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ()..**.** ^The s
1ece0 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58  qlite3_realloc(X
1ecf0 2c 4e 29 20 69 6e 74 65 72 66 61 63 65 20 61 74  ,N) interface at
1ed00 74 65 6d 70 74 73 20 74 6f 20 72 65 73 69 7a 65  tempts to resize
1ed10 20 61 0a 2a 2a 20 70 72 69 6f 72 20 6d 65 6d 6f   a.** prior memo
1ed20 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 58 20  ry allocation X 
1ed30 74 6f 20 62 65 20 61 74 20 6c 65 61 73 74 20 4e  to be at least N
1ed40 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 49 66 20 74   bytes..** ^If t
1ed50 68 65 20 58 20 70 61 72 61 6d 65 74 65 72 20 74  he X parameter t
1ed60 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  o sqlite3_reallo
1ed70 63 28 58 2c 4e 29 0a 2a 2a 20 69 73 20 61 20 4e  c(X,N).** is a N
1ed80 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e  ULL pointer then
1ed90 20 69 74 73 20 62 65 68 61 76 69 6f 72 20 69 73   its behavior is
1eda0 20 69 64 65 6e 74 69 63 61 6c 20 74 6f 20 63 61   identical to ca
1edb0 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33  lling.** sqlite3
1edc0 5f 6d 61 6c 6c 6f 63 28 4e 29 2e 0a 2a 2a 20 5e  _malloc(N)..** ^
1edd0 49 66 20 74 68 65 20 4e 20 70 61 72 61 6d 65 74  If the N paramet
1ede0 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65  er to sqlite3_re
1edf0 61 6c 6c 6f 63 28 58 2c 4e 29 20 69 73 20 7a 65  alloc(X,N) is ze
1ee00 72 6f 20 6f 72 0a 2a 2a 20 6e 65 67 61 74 69 76  ro or.** negativ
1ee10 65 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76  e then the behav
1ee20 69 6f 72 20 69 73 20 65 78 61 63 74 6c 79 20 74  ior is exactly t
1ee30 68 65 20 73 61 6d 65 20 61 73 20 63 61 6c 6c 69  he same as calli
1ee40 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 66 72  ng.** sqlite3_fr
1ee50 65 65 28 58 29 2e 0a 2a 2a 20 5e 73 71 6c 69 74  ee(X)..** ^sqlit
1ee60 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 20  e3_realloc(X,N) 
1ee70 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65  returns a pointe
1ee80 72 20 74 6f 20 61 20 6d 65 6d 6f 72 79 20 61 6c  r to a memory al
1ee90 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 61  location.** of a
1eea0 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73 20  t least N bytes 
1eeb0 69 6e 20 73 69 7a 65 20 6f 72 20 4e 55 4c 4c 20  in size or NULL 
1eec0 69 66 20 69 6e 73 75 66 66 69 63 69 65 6e 74 20  if insufficient 
1eed0 6d 65 6d 6f 72 79 20 69 73 20 61 76 61 69 6c 61  memory is availa
1eee0 62 6c 65 2e 0a 2a 2a 20 5e 49 66 20 4d 20 69 73  ble..** ^If M is
1eef0 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65   the size of the
1ef00 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f   prior allocatio
1ef10 6e 2c 20 74 68 65 6e 20 6d 69 6e 28 4e 2c 4d 29  n, then min(N,M)
1ef20 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 74 68 65   bytes.** of the
1ef30 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f   prior allocatio
1ef40 6e 20 61 72 65 20 63 6f 70 69 65 64 20 69 6e 74  n are copied int
1ef50 6f 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20  o the beginning 
1ef60 6f 66 20 62 75 66 66 65 72 20 72 65 74 75 72 6e  of buffer return
1ef70 65 64 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 33  ed.** by sqlite3
1ef80 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 20 61 6e  _realloc(X,N) an
1ef90 64 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f  d the prior allo
1efa0 63 61 74 69 6f 6e 20 69 73 20 66 72 65 65 64 2e  cation is freed.
1efb0 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f  .** ^If sqlite3_
1efc0 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 20 72 65 74  realloc(X,N) ret
1efd0 75 72 6e 73 20 4e 55 4c 4c 20 61 6e 64 20 4e 20  urns NULL and N 
1efe0 69 73 20 70 6f 73 69 74 69 76 65 2c 20 74 68 65  is positive, the
1eff0 6e 20 74 68 65 0a 2a 2a 20 70 72 69 6f 72 20 61  n the.** prior a
1f000 6c 6c 6f 63 61 74 69 6f 6e 20 69 73 20 6e 6f 74  llocation is not
1f010 20 66 72 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54   freed..**.** ^T
1f020 68 65 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  he sqlite3_reall
1f030 6f 63 36 34 28 58 2c 4e 29 20 69 6e 74 65 72 66  oc64(X,N) interf
1f040 61 63 65 73 20 77 6f 72 6b 73 20 74 68 65 20 73  aces works the s
1f050 61 6d 65 20 61 73 0a 2a 2a 20 73 71 6c 69 74 65  ame as.** sqlite
1f060 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 20 65  3_realloc(X,N) e
1f070 78 63 65 70 74 20 74 68 61 74 20 4e 20 69 73 20  xcept that N is 
1f080 61 20 36 34 2d 62 69 74 20 75 6e 73 69 67 6e 65  a 64-bit unsigne
1f090 64 20 69 6e 74 65 67 65 72 20 69 6e 73 74 65 61  d integer instea
1f0a0 64 0a 2a 2a 20 6f 66 20 61 20 33 32 2d 62 69 74  d.** of a 32-bit
1f0b0 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 2e   signed integer.
1f0c0 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 58 20 69 73 20  .**.** ^If X is 
1f0d0 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  a memory allocat
1f0e0 69 6f 6e 20 70 72 65 76 69 6f 75 73 6c 79 20 6f  ion previously o
1f0f0 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 73 71 6c  btained from sql
1f100 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 2c 0a 2a  ite3_malloc(),.*
1f110 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  * sqlite3_malloc
1f120 36 34 28 29 2c 20 73 71 6c 69 74 65 33 5f 72 65  64(), sqlite3_re
1f130 61 6c 6c 6f 63 28 29 2c 20 6f 72 20 73 71 6c 69  alloc(), or sqli
1f140 74 65 33 5f 72 65 61 6c 6c 6f 63 36 34 28 29 2c  te3_realloc64(),
1f150 20 74 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33   then.** sqlite3
1f160 5f 6d 73 69 7a 65 28 58 29 20 72 65 74 75 72 6e  _msize(X) return
1f170 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68  s the size of th
1f180 61 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  at memory alloca
1f190 74 69 6f 6e 20 69 6e 20 62 79 74 65 73 2e 0a 2a  tion in bytes..*
1f1a0 2a 20 5e 54 68 65 20 76 61 6c 75 65 20 72 65 74  * ^The value ret
1f1b0 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33  urned by sqlite3
1f1c0 5f 6d 73 69 7a 65 28 58 29 20 6d 69 67 68 74 20  _msize(X) might 
1f1d0 62 65 20 6c 61 72 67 65 72 20 74 68 61 6e 20 74  be larger than t
1f1e0 68 65 20 6e 75 6d 62 65 72 0a 2a 2a 20 6f 66 20  he number.** of 
1f1f0 62 79 74 65 73 20 72 65 71 75 65 73 74 65 64 20  bytes requested 
1f200 77 68 65 6e 20 58 20 77 61 73 20 61 6c 6c 6f 63  when X was alloc
1f210 61 74 65 64 2e 20 20 5e 49 66 20 58 20 69 73 20  ated.  ^If X is 
1f220 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74  a NULL pointer t
1f230 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d  hen.** sqlite3_m
1f240 73 69 7a 65 28 58 29 20 72 65 74 75 72 6e 73 20  size(X) returns 
1f250 7a 65 72 6f 2e 20 20 49 66 20 58 20 70 6f 69 6e  zero.  If X poin
1f260 74 73 20 74 6f 20 73 6f 6d 65 74 68 69 6e 67 20  ts to something 
1f270 74 68 61 74 20 69 73 20 6e 6f 74 0a 2a 2a 20 74  that is not.** t
1f280 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20  he beginning of 
1f290 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
1f2a0 6e 2c 20 6f 72 20 69 66 20 69 74 20 70 6f 69 6e  n, or if it poin
1f2b0 74 73 20 74 6f 20 61 20 66 6f 72 6d 65 72 6c 79  ts to a formerly
1f2c0 0a 2a 2a 20 76 61 6c 69 64 20 6d 65 6d 6f 72 79  .** valid memory
1f2d0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 68 61 74   allocation that
1f2e0 20 68 61 73 20 6e 6f 77 20 62 65 65 6e 20 66 72   has now been fr
1f2f0 65 65 64 2c 20 74 68 65 6e 20 74 68 65 20 62 65  eed, then the be
1f300 68 61 76 69 6f 72 0a 2a 2a 20 6f 66 20 73 71 6c  havior.** of sql
1f310 69 74 65 33 5f 6d 73 69 7a 65 28 58 29 20 69 73  ite3_msize(X) is
1f320 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 20 70   undefined and p
1f330 6f 73 73 69 62 6c 79 20 68 61 72 6d 66 75 6c 2e  ossibly harmful.
1f340 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6d 65 6d 6f  .**.** ^The memo
1f350 72 79 20 72 65 74 75 72 6e 65 64 20 62 79 20 73  ry returned by s
1f360 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 2c  qlite3_malloc(),
1f370 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
1f380 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d  (),.** sqlite3_m
1f390 61 6c 6c 6f 63 36 34 28 29 2c 20 61 6e 64 20 73  alloc64(), and s
1f3a0 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 36 34  qlite3_realloc64
1f3b0 28 29 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73 20  ().** is always 
1f3c0 61 6c 69 67 6e 65 64 20 74 6f 20 61 74 20 6c 65  aligned to at le
1f3d0 61 73 74 20 61 6e 20 38 20 62 79 74 65 20 62 6f  ast an 8 byte bo
1f3e0 75 6e 64 61 72 79 2c 20 6f 72 20 74 6f 20 61 0a  undary, or to a.
1f3f0 2a 2a 20 34 20 62 79 74 65 20 62 6f 75 6e 64 61  ** 4 byte bounda
1f400 72 79 20 69 66 20 74 68 65 20 5b 53 51 4c 49 54  ry if the [SQLIT
1f410 45 5f 34 5f 42 59 54 45 5f 41 4c 49 47 4e 45 44  E_4_BYTE_ALIGNED
1f420 5f 4d 41 4c 4c 4f 43 5d 20 63 6f 6d 70 69 6c 65  _MALLOC] compile
1f430 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e 20  -time.** option 
1f440 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 49  is used..**.** I
1f450 6e 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e  n SQLite version
1f460 20 33 2e 35 2e 30 20 61 6e 64 20 33 2e 35 2e 31   3.5.0 and 3.5.1
1f470 2c 20 69 74 20 77 61 73 20 70 6f 73 73 69 62 6c  , it was possibl
1f480 65 20 74 6f 20 64 65 66 69 6e 65 0a 2a 2a 20 74  e to define.** t
1f490 68 65 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 4d  he SQLITE_OMIT_M
1f4a0 45 4d 4f 52 59 5f 41 4c 4c 4f 43 41 54 49 4f 4e  EMORY_ALLOCATION
1f4b0 20 77 68 69 63 68 20 77 6f 75 6c 64 20 63 61 75   which would cau
1f4c0 73 65 20 74 68 65 20 62 75 69 6c 74 2d 69 6e 0a  se the built-in.
1f4d0 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ** implementatio
1f4e0 6e 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69  n of these routi
1f4f0 6e 65 73 20 74 6f 20 62 65 20 6f 6d 69 74 74 65  nes to be omitte
1f500 64 2e 20 20 54 68 61 74 20 63 61 70 61 62 69 6c  d.  That capabil
1f510 69 74 79 0a 2a 2a 20 69 73 20 6e 6f 20 6c 6f 6e  ity.** is no lon
1f520 67 65 72 20 70 72 6f 76 69 64 65 64 2e 20 20 4f  ger provided.  O
1f530 6e 6c 79 20 62 75 69 6c 74 2d 69 6e 20 6d 65 6d  nly built-in mem
1f540 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 73 20 63  ory allocators c
1f550 61 6e 20 62 65 20 75 73 65 64 2e 0a 2a 2a 0a 2a  an be used..**.*
1f560 2a 20 50 72 69 6f 72 20 74 6f 20 53 51 4c 69 74  * Prior to SQLit
1f570 65 20 76 65 72 73 69 6f 6e 20 33 2e 37 2e 31 30  e version 3.7.10
1f580 2c 20 74 68 65 20 57 69 6e 64 6f 77 73 20 4f 53  , the Windows OS
1f590 20 69 6e 74 65 72 66 61 63 65 20 6c 61 79 65 72   interface layer
1f5a0 20 63 61 6c 6c 65 64 0a 2a 2a 20 74 68 65 20 73   called.** the s
1f5b0 79 73 74 65 6d 20 6d 61 6c 6c 6f 63 28 29 20 61  ystem malloc() a
1f5c0 6e 64 20 66 72 65 65 28 29 20 64 69 72 65 63 74  nd free() direct
1f5d0 6c 79 20 77 68 65 6e 20 63 6f 6e 76 65 72 74 69  ly when converti
1f5e0 6e 67 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 73 20  ng.** filenames 
1f5f0 62 65 74 77 65 65 6e 20 74 68 65 20 55 54 46 2d  between the UTF-
1f600 38 20 65 6e 63 6f 64 69 6e 67 20 75 73 65 64 20  8 encoding used 
1f610 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64  by SQLite.** and
1f620 20 77 68 61 74 65 76 65 72 20 66 69 6c 65 6e 61   whatever filena
1f630 6d 65 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 75  me encoding is u
1f640 73 65 64 20 62 79 20 74 68 65 20 70 61 72 74 69  sed by the parti
1f650 63 75 6c 61 72 20 57 69 6e 64 6f 77 73 0a 2a 2a  cular Windows.**
1f660 20 69 6e 73 74 61 6c 6c 61 74 69 6f 6e 2e 20 20   installation.  
1f670 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  Memory allocatio
1f680 6e 20 65 72 72 6f 72 73 20 77 65 72 65 20 64 65  n errors were de
1f690 74 65 63 74 65 64 2c 20 62 75 74 0a 2a 2a 20 74  tected, but.** t
1f6a0 68 65 79 20 77 65 72 65 20 72 65 70 6f 72 74 65  hey were reporte
1f6b0 64 20 62 61 63 6b 20 61 73 20 5b 53 51 4c 49 54  d back as [SQLIT
1f6c0 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 6f 72 0a 2a  E_CANTOPEN] or.*
1f6d0 2a 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5d  * [SQLITE_IOERR]
1f6e0 20 72 61 74 68 65 72 20 74 68 61 6e 20 5b 53 51   rather than [SQ
1f6f0 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a 0a  LITE_NOMEM]..**.
1f700 2a 2a 20 54 68 65 20 70 6f 69 6e 74 65 72 20 61  ** The pointer a
1f710 72 67 75 6d 65 6e 74 73 20 74 6f 20 5b 73 71 6c  rguments to [sql
1f720 69 74 65 33 5f 66 72 65 65 28 29 5d 20 61 6e 64  ite3_free()] and
1f730 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f   [sqlite3_reallo
1f740 63 28 29 5d 0a 2a 2a 20 6d 75 73 74 20 62 65 20  c()].** must be 
1f750 65 69 74 68 65 72 20 4e 55 4c 4c 20 6f 72 20 65  either NULL or e
1f760 6c 73 65 20 70 6f 69 6e 74 65 72 73 20 6f 62 74  lse pointers obt
1f770 61 69 6e 65 64 20 66 72 6f 6d 20 61 20 70 72 69  ained from a pri
1f780 6f 72 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e  or.** invocation
1f790 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c   of [sqlite3_mal
1f7a0 6c 6f 63 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  loc()] or [sqlit
1f7b0 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 20 74 68  e3_realloc()] th
1f7c0 61 74 20 68 61 76 65 0a 2a 2a 20 6e 6f 74 20 79  at have.** not y
1f7d0 65 74 20 62 65 65 6e 20 72 65 6c 65 61 73 65 64  et been released
1f7e0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c  ..**.** The appl
1f7f0 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74  ication must not
1f800 20 72 65 61 64 20 6f 72 20 77 72 69 74 65 20 61   read or write a
1f810 6e 79 20 70 61 72 74 20 6f 66 0a 2a 2a 20 61 20  ny part of.** a 
1f820 62 6c 6f 63 6b 20 6f 66 20 6d 65 6d 6f 72 79 20  block of memory 
1f830 61 66 74 65 72 20 69 74 20 68 61 73 20 62 65 65  after it has bee
1f840 6e 20 72 65 6c 65 61 73 65 64 20 75 73 69 6e 67  n released using
1f850 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  .** [sqlite3_fre
1f860 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  e()] or [sqlite3
1f870 5f 72 65 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a  _realloc()]..*/.
1f880 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 6d 61  void *sqlite3_ma
1f890 6c 6c 6f 63 28 69 6e 74 29 3b 0a 76 6f 69 64 20  lloc(int);.void 
1f8a0 2a 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 36  *sqlite3_malloc6
1f8b0 34 28 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34  4(sqlite3_uint64
1f8c0 29 3b 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  );.void *sqlite3
1f8d0 5f 72 65 61 6c 6c 6f 63 28 76 6f 69 64 2a 2c 20  _realloc(void*, 
1f8e0 69 6e 74 29 3b 0a 76 6f 69 64 20 2a 73 71 6c 69  int);.void *sqli
1f8f0 74 65 33 5f 72 65 61 6c 6c 6f 63 36 34 28 76 6f  te3_realloc64(vo
1f900 69 64 2a 2c 20 73 71 6c 69 74 65 33 5f 75 69 6e  id*, sqlite3_uin
1f910 74 36 34 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  t64);.void sqlit
1f920 65 33 5f 66 72 65 65 28 76 6f 69 64 2a 29 3b 0a  e3_free(void*);.
1f930 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 20 73  sqlite3_uint64 s
1f940 71 6c 69 74 65 33 5f 6d 73 69 7a 65 28 76 6f 69  qlite3_msize(voi
1f950 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  d*);../*.** CAPI
1f960 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c  3REF: Memory All
1f970 6f 63 61 74 6f 72 20 53 74 61 74 69 73 74 69 63  ocator Statistic
1f980 73 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 70  s.**.** SQLite p
1f990 72 6f 76 69 64 65 73 20 74 68 65 73 65 20 74 77  rovides these tw
1f9a0 6f 20 69 6e 74 65 72 66 61 63 65 73 20 66 6f 72  o interfaces for
1f9b0 20 72 65 70 6f 72 74 69 6e 67 20 6f 6e 20 74 68   reporting on th
1f9c0 65 20 73 74 61 74 75 73 0a 2a 2a 20 6f 66 20 74  e status.** of t
1f9d0 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  he [sqlite3_mall
1f9e0 6f 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  oc()], [sqlite3_
1f9f0 66 72 65 65 28 29 5d 2c 20 61 6e 64 20 5b 73 71  free()], and [sq
1fa00 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d  lite3_realloc()]
1fa10 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 2c 20 77 68  .** routines, wh
1fa20 69 63 68 20 66 6f 72 6d 20 74 68 65 20 62 75 69  ich form the bui
1fa30 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c  lt-in memory all
1fa40 6f 63 61 74 69 6f 6e 20 73 75 62 73 79 73 74 65  ocation subsyste
1fa50 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73  m..**.** ^The [s
1fa60 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73  qlite3_memory_us
1fa70 65 64 28 29 5d 20 72 6f 75 74 69 6e 65 20 72 65  ed()] routine re
1fa80 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72  turns the number
1fa90 20 6f 66 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20   of bytes.** of 
1faa0 6d 65 6d 6f 72 79 20 63 75 72 72 65 6e 74 6c 79  memory currently
1fab0 20 6f 75 74 73 74 61 6e 64 69 6e 67 20 28 6d 61   outstanding (ma
1fac0 6c 6c 6f 63 65 64 20 62 75 74 20 6e 6f 74 20 66  lloced but not f
1fad0 72 65 65 64 29 2e 0a 2a 2a 20 5e 54 68 65 20 5b  reed)..** ^The [
1fae0 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68  sqlite3_memory_h
1faf0 69 67 68 77 61 74 65 72 28 29 5d 20 72 6f 75 74  ighwater()] rout
1fb00 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 20  ine returns the 
1fb10 6d 61 78 69 6d 75 6d 0a 2a 2a 20 76 61 6c 75 65  maximum.** value
1fb20 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d   of [sqlite3_mem
1fb30 6f 72 79 5f 75 73 65 64 28 29 5d 20 73 69 6e 63  ory_used()] sinc
1fb40 65 20 74 68 65 20 68 69 67 68 2d 77 61 74 65 72  e the high-water
1fb50 20 6d 61 72 6b 0a 2a 2a 20 77 61 73 20 6c 61 73   mark.** was las
1fb60 74 20 72 65 73 65 74 2e 20 20 5e 54 68 65 20 76  t reset.  ^The v
1fb70 61 6c 75 65 73 20 72 65 74 75 72 6e 65 64 20 62  alues returned b
1fb80 79 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  y [sqlite3_memor
1fb90 79 5f 75 73 65 64 28 29 5d 20 61 6e 64 0a 2a 2a  y_used()] and.**
1fba0 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79   [sqlite3_memory
1fbb0 5f 68 69 67 68 77 61 74 65 72 28 29 5d 20 69 6e  _highwater()] in
1fbc0 63 6c 75 64 65 20 61 6e 79 20 6f 76 65 72 68 65  clude any overhe
1fbd0 61 64 0a 2a 2a 20 61 64 64 65 64 20 62 79 20 53  ad.** added by S
1fbe0 51 4c 69 74 65 20 69 6e 20 69 74 73 20 69 6d 70  QLite in its imp
1fbf0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 5b  lementation of [
1fc00 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
1fc10 5d 2c 0a 2a 2a 20 62 75 74 20 6e 6f 74 20 6f 76  ],.** but not ov
1fc20 65 72 68 65 61 64 20 61 64 64 65 64 20 62 79 20  erhead added by 
1fc30 74 68 65 20 61 6e 79 20 75 6e 64 65 72 6c 79 69  the any underlyi
1fc40 6e 67 20 73 79 73 74 65 6d 20 6c 69 62 72 61 72  ng system librar
1fc50 79 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 74 68  y.** routines th
1fc60 61 74 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  at [sqlite3_mall
1fc70 6f 63 28 29 5d 20 6d 61 79 20 63 61 6c 6c 2e 0a  oc()] may call..
1fc80 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6d 65 6d 6f 72  **.** ^The memor
1fc90 79 20 68 69 67 68 2d 77 61 74 65 72 20 6d 61 72  y high-water mar
1fca0 6b 20 69 73 20 72 65 73 65 74 20 74 6f 20 74 68  k is reset to th
1fcb0 65 20 63 75 72 72 65 6e 74 20 76 61 6c 75 65 20  e current value 
1fcc0 6f 66 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d  of.** [sqlite3_m
1fcd0 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 69 66  emory_used()] if
1fce0 20 61 6e 64 20 6f 6e 6c 79 20 69 66 20 74 68 65   and only if the
1fcf0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a   parameter to.**
1fd00 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79   [sqlite3_memory
1fd10 5f 68 69 67 68 77 61 74 65 72 28 29 5d 20 69 73  _highwater()] is
1fd20 20 74 72 75 65 2e 20 20 5e 54 68 65 20 76 61 6c   true.  ^The val
1fd30 75 65 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62  ue returned.** b
1fd40 79 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  y [sqlite3_memor
1fd50 79 5f 68 69 67 68 77 61 74 65 72 28 31 29 5d 20  y_highwater(1)] 
1fd60 69 73 20 74 68 65 20 68 69 67 68 2d 77 61 74 65  is the high-wate
1fd70 72 20 6d 61 72 6b 0a 2a 2a 20 70 72 69 6f 72 20  r mark.** prior 
1fd80 74 6f 20 74 68 65 20 72 65 73 65 74 2e 0a 2a 2f  to the reset..*/
1fd90 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73  .sqlite3_int64 s
1fda0 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73  qlite3_memory_us
1fdb0 65 64 28 76 6f 69 64 29 3b 0a 73 71 6c 69 74 65  ed(void);.sqlite
1fdc0 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f  3_int64 sqlite3_
1fdd0 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72  memory_highwater
1fde0 28 69 6e 74 20 72 65 73 65 74 46 6c 61 67 29 3b  (int resetFlag);
1fdf0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1fe00 3a 20 50 73 65 75 64 6f 2d 52 61 6e 64 6f 6d 20  : Pseudo-Random 
1fe10 4e 75 6d 62 65 72 20 47 65 6e 65 72 61 74 6f 72  Number Generator
1fe20 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 63 6f  .**.** SQLite co
1fe30 6e 74 61 69 6e 73 20 61 20 68 69 67 68 2d 71 75  ntains a high-qu
1fe40 61 6c 69 74 79 20 70 73 65 75 64 6f 2d 72 61 6e  ality pseudo-ran
1fe50 64 6f 6d 20 6e 75 6d 62 65 72 20 67 65 6e 65 72  dom number gener
1fe60 61 74 6f 72 20 28 50 52 4e 47 29 20 75 73 65 64  ator (PRNG) used
1fe70 20 74 6f 0a 2a 2a 20 73 65 6c 65 63 74 20 72 61   to.** select ra
1fe80 6e 64 6f 6d 20 5b 52 4f 57 49 44 20 7c 20 52 4f  ndom [ROWID | RO
1fe90 57 49 44 73 5d 20 77 68 65 6e 20 69 6e 73 65 72  WIDs] when inser
1fea0 74 69 6e 67 20 6e 65 77 20 72 65 63 6f 72 64 73  ting new records
1feb0 20 69 6e 74 6f 20 61 20 74 61 62 6c 65 20 74 68   into a table th
1fec0 61 74 0a 2a 2a 20 61 6c 72 65 61 64 79 20 75 73  at.** already us
1fed0 65 73 20 74 68 65 20 6c 61 72 67 65 73 74 20 70  es the largest p
1fee0 6f 73 73 69 62 6c 65 20 5b 52 4f 57 49 44 5d 2e  ossible [ROWID].
1fef0 20 20 54 68 65 20 50 52 4e 47 20 69 73 20 61 6c    The PRNG is al
1ff00 73 6f 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20 74  so used for.** t
1ff10 68 65 20 62 75 69 6c 64 2d 69 6e 20 72 61 6e 64  he build-in rand
1ff20 6f 6d 28 29 20 61 6e 64 20 72 61 6e 64 6f 6d 62  om() and randomb
1ff30 6c 6f 62 28 29 20 53 51 4c 20 66 75 6e 63 74 69  lob() SQL functi
1ff40 6f 6e 73 2e 20 20 54 68 69 73 20 69 6e 74 65 72  ons.  This inter
1ff50 66 61 63 65 20 61 6c 6c 6f 77 73 0a 2a 2a 20 61  face allows.** a
1ff60 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 6f 20 61  pplications to a
1ff70 63 63 65 73 73 20 74 68 65 20 73 61 6d 65 20 50  ccess the same P
1ff80 52 4e 47 20 66 6f 72 20 6f 74 68 65 72 20 70 75  RNG for other pu
1ff90 72 70 6f 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41  rposes..**.** ^A
1ffa0 20 63 61 6c 6c 20 74 6f 20 74 68 69 73 20 72 6f   call to this ro
1ffb0 75 74 69 6e 65 20 73 74 6f 72 65 73 20 4e 20 62  utine stores N b
1ffc0 79 74 65 73 20 6f 66 20 72 61 6e 64 6f 6d 6e 65  ytes of randomne
1ffd0 73 73 20 69 6e 74 6f 20 62 75 66 66 65 72 20 50  ss into buffer P
1ffe0 2e 0a 2a 2a 20 5e 54 68 65 20 50 20 70 61 72 61  ..** ^The P para
1fff0 6d 65 74 65 72 20 63 61 6e 20 62 65 20 61 20 4e  meter can be a N
20000 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a  ULL pointer..**.
20010 2a 2a 20 5e 49 66 20 74 68 69 73 20 72 6f 75 74  ** ^If this rout
20020 69 6e 65 20 68 61 73 20 6e 6f 74 20 62 65 65 6e  ine has not been
20030 20 70 72 65 76 69 6f 75 73 6c 79 20 63 61 6c 6c   previously call
20040 65 64 20 6f 72 20 69 66 20 74 68 65 20 70 72 65  ed or if the pre
20050 76 69 6f 75 73 0a 2a 2a 20 63 61 6c 6c 20 68 61  vious.** call ha
20060 64 20 4e 20 6c 65 73 73 20 74 68 61 6e 20 6f 6e  d N less than on
20070 65 20 6f 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  e or a NULL poin
20080 74 65 72 20 66 6f 72 20 50 2c 20 74 68 65 6e 20  ter for P, then 
20090 74 68 65 20 50 52 4e 47 20 69 73 0a 2a 2a 20 73  the PRNG is.** s
200a0 65 65 64 65 64 20 75 73 69 6e 67 20 72 61 6e 64  eeded using rand
200b0 6f 6d 6e 65 73 73 20 6f 62 74 61 69 6e 65 64 20  omness obtained 
200c0 66 72 6f 6d 20 74 68 65 20 78 52 61 6e 64 6f 6d  from the xRandom
200d0 6e 65 73 73 20 6d 65 74 68 6f 64 20 6f 66 0a 2a  ness method of.*
200e0 2a 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73  * the default [s
200f0 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65  qlite3_vfs] obje
20100 63 74 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 70  ct..** ^If the p
20110 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20  revious call to 
20120 74 68 69 73 20 72 6f 75 74 69 6e 65 20 68 61 64  this routine had
20130 20 61 6e 20 4e 20 6f 66 20 31 20 6f 72 20 6d 6f   an N of 1 or mo
20140 72 65 20 61 6e 64 20 61 0a 2a 2a 20 6e 6f 6e 2d  re and a.** non-
20150 4e 55 4c 4c 20 50 20 74 68 65 6e 20 74 68 65 20  NULL P then the 
20160 70 73 65 75 64 6f 2d 72 61 6e 64 6f 6d 6e 65 73  pseudo-randomnes
20170 73 20 69 73 20 67 65 6e 65 72 61 74 65 64 0a 2a  s is generated.*
20180 2a 20 69 6e 74 65 72 6e 61 6c 6c 79 20 61 6e 64  * internally and
20190 20 77 69 74 68 6f 75 74 20 72 65 63 6f 75 72 73   without recours
201a0 65 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  e to the [sqlite
201b0 33 5f 76 66 73 5d 20 78 52 61 6e 64 6f 6d 6e 65  3_vfs] xRandomne
201c0 73 73 0a 2a 2a 20 6d 65 74 68 6f 64 2e 0a 2a 2f  ss.** method..*/
201d0 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 61  .void sqlite3_ra
201e0 6e 64 6f 6d 6e 65 73 73 28 69 6e 74 20 4e 2c 20  ndomness(int N, 
201f0 76 6f 69 64 20 2a 50 29 3b 0a 0a 2f 2a 0a 2a 2a  void *P);../*.**
20200 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6d 70 69   CAPI3REF: Compi
20210 6c 65 2d 54 69 6d 65 20 41 75 74 68 6f 72 69 7a  le-Time Authoriz
20220 61 74 69 6f 6e 20 43 61 6c 6c 62 61 63 6b 73 0a  ation Callbacks.
20230 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
20240 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72  e3.**.** ^This r
20250 6f 75 74 69 6e 65 20 72 65 67 69 73 74 65 72 73  outine registers
20260 20 61 6e 20 61 75 74 68 6f 72 69 7a 65 72 20 63   an authorizer c
20270 61 6c 6c 62 61 63 6b 20 77 69 74 68 20 61 20 70  allback with a p
20280 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20 5b 64 61  articular.** [da
20290 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
202a0 6e 5d 2c 20 73 75 70 70 6c 69 65 64 20 69 6e 20  n], supplied in 
202b0 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
202c0 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 61 75 74 68  nt..** ^The auth
202d0 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
202e0 69 73 20 69 6e 76 6f 6b 65 64 20 61 73 20 53 51  is invoked as SQ
202f0 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65  L statements are
20300 20 62 65 69 6e 67 20 63 6f 6d 70 69 6c 65 64 0a   being compiled.
20310 2a 2a 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 70  ** by [sqlite3_p
20320 72 65 70 61 72 65 28 29 5d 20 6f 72 20 69 74 73  repare()] or its
20330 20 76 61 72 69 61 6e 74 73 20 5b 73 71 6c 69 74   variants [sqlit
20340 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
20350 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72  ,.** [sqlite3_pr
20360 65 70 61 72 65 31 36 28 29 5d 20 61 6e 64 20 5b  epare16()] and [
20370 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
20380 36 5f 76 32 28 29 5d 2e 20 20 5e 41 74 20 76 61  6_v2()].  ^At va
20390 72 69 6f 75 73 0a 2a 2a 20 70 6f 69 6e 74 73 20  rious.** points 
203a0 64 75 72 69 6e 67 20 74 68 65 20 63 6f 6d 70 69  during the compi
203b0 6c 61 74 69 6f 6e 20 70 72 6f 63 65 73 73 2c 20  lation process, 
203c0 61 73 20 6c 6f 67 69 63 20 69 73 20 62 65 69 6e  as logic is bein
203d0 67 20 63 72 65 61 74 65 64 0a 2a 2a 20 74 6f 20  g created.** to 
203e0 70 65 72 66 6f 72 6d 20 76 61 72 69 6f 75 73 20  perform various 
203f0 61 63 74 69 6f 6e 73 2c 20 74 68 65 20 61 75 74  actions, the aut
20400 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
20410 20 69 73 20 69 6e 76 6f 6b 65 64 20 74 6f 0a 2a   is invoked to.*
20420 2a 20 73 65 65 20 69 66 20 74 68 6f 73 65 20 61  * see if those a
20430 63 74 69 6f 6e 73 20 61 72 65 20 61 6c 6c 6f 77  ctions are allow
20440 65 64 2e 20 20 5e 54 68 65 20 61 75 74 68 6f 72  ed.  ^The author
20450 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 73 68  izer callback sh
20460 6f 75 6c 64 0a 2a 2a 20 72 65 74 75 72 6e 20 5b  ould.** return [
20470 53 51 4c 49 54 45 5f 4f 4b 5d 20 74 6f 20 61 6c  SQLITE_OK] to al
20480 6c 6f 77 20 74 68 65 20 61 63 74 69 6f 6e 2c 20  low the action, 
20490 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20  [SQLITE_IGNORE] 
204a0 74 6f 20 64 69 73 61 6c 6c 6f 77 20 74 68 65 0a  to disallow the.
204b0 2a 2a 20 73 70 65 63 69 66 69 63 20 61 63 74 69  ** specific acti
204c0 6f 6e 20 62 75 74 20 61 6c 6c 6f 77 20 74 68 65  on but allow the
204d0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74   SQL statement t
204e0 6f 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 62 65  o continue to be
204f0 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 2c 20 6f 72  .** compiled, or
20500 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 20 74   [SQLITE_DENY] t
20510 6f 20 63 61 75 73 65 20 74 68 65 20 65 6e 74 69  o cause the enti
20520 72 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  re SQL statement
20530 20 74 6f 20 62 65 0a 2a 2a 20 72 65 6a 65 63 74   to be.** reject
20540 65 64 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72  ed with an error
20550 2e 20 20 5e 49 66 20 74 68 65 20 61 75 74 68 6f  .  ^If the autho
20560 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 72  rizer callback r
20570 65 74 75 72 6e 73 0a 2a 2a 20 61 6e 79 20 76 61  eturns.** any va
20580 6c 75 65 20 6f 74 68 65 72 20 74 68 61 6e 20 5b  lue other than [
20590 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 2c 20  SQLITE_IGNORE], 
205a0 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 6f 72 20  [SQLITE_OK], or 
205b0 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 0a 2a 2a  [SQLITE_DENY].**
205c0 20 74 68 65 6e 20 74 68 65 20 5b 73 71 6c 69 74   then the [sqlit
205d0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
205e0 20 6f 72 20 65 71 75 69 76 61 6c 65 6e 74 20 63   or equivalent c
205f0 61 6c 6c 20 74 68 61 74 20 74 72 69 67 67 65 72  all that trigger
20600 65 64 0a 2a 2a 20 74 68 65 20 61 75 74 68 6f 72  ed.** the author
20610 69 7a 65 72 20 77 69 6c 6c 20 66 61 69 6c 20 77  izer will fail w
20620 69 74 68 20 61 6e 20 65 72 72 6f 72 20 6d 65 73  ith an error mes
20630 73 61 67 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e  sage..**.** When
20640 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65   the callback re
20650 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b  turns [SQLITE_OK
20660 5d 2c 20 74 68 61 74 20 6d 65 61 6e 73 20 74 68  ], that means th
20670 65 20 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 72  e operation.** r
20680 65 71 75 65 73 74 65 64 20 69 73 20 6f 6b 2e 20  equested is ok. 
20690 20 5e 57 68 65 6e 20 74 68 65 20 63 61 6c 6c 62   ^When the callb
206a0 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c  ack returns [SQL
206b0 49 54 45 5f 44 45 4e 59 5d 2c 20 74 68 65 0a 2a  ITE_DENY], the.*
206c0 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  * [sqlite3_prepa
206d0 72 65 5f 76 32 28 29 5d 20 6f 72 20 65 71 75 69  re_v2()] or equi
206e0 76 61 6c 65 6e 74 20 63 61 6c 6c 20 74 68 61 74  valent call that
206f0 20 74 72 69 67 67 65 72 65 64 20 74 68 65 0a 2a   triggered the.*
20700 2a 20 61 75 74 68 6f 72 69 7a 65 72 20 77 69 6c  * authorizer wil
20710 6c 20 66 61 69 6c 20 77 69 74 68 20 61 6e 20 65  l fail with an e
20720 72 72 6f 72 20 6d 65 73 73 61 67 65 20 65 78 70  rror message exp
20730 6c 61 69 6e 69 6e 67 20 74 68 61 74 0a 2a 2a 20  laining that.** 
20740 61 63 63 65 73 73 20 69 73 20 64 65 6e 69 65 64  access is denied
20750 2e 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69  . .**.** ^The fi
20760 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f  rst parameter to
20770 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   the authorizer 
20780 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 20 63 6f  callback is a co
20790 70 79 20 6f 66 20 74 68 65 20 74 68 69 72 64 0a  py of the third.
207a0 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  ** parameter to 
207b0 74 68 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f  the sqlite3_set_
207c0 61 75 74 68 6f 72 69 7a 65 72 28 29 20 69 6e 74  authorizer() int
207d0 65 72 66 61 63 65 2e 20 5e 54 68 65 20 73 65 63  erface. ^The sec
207e0 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a  ond parameter.**
207f0 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b   to the callback
20800 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 5b   is an integer [
20810 53 51 4c 49 54 45 5f 43 4f 50 59 20 7c 20 61 63  SQLITE_COPY | ac
20820 74 69 6f 6e 20 63 6f 64 65 5d 20 74 68 61 74 20  tion code] that 
20830 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 74 68 65  specifies.** the
20840 20 70 61 72 74 69 63 75 6c 61 72 20 61 63 74 69   particular acti
20850 6f 6e 20 74 6f 20 62 65 20 61 75 74 68 6f 72 69  on to be authori
20860 7a 65 64 2e 20 5e 54 68 65 20 74 68 69 72 64 20  zed. ^The third 
20870 74 68 72 6f 75 67 68 20 73 69 78 74 68 20 70 61  through sixth pa
20880 72 61 6d 65 74 65 72 73 0a 2a 2a 20 74 6f 20 74  rameters.** to t
20890 68 65 20 63 61 6c 6c 62 61 63 6b 20 61 72 65 20  he callback are 
208a0 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20  zero-terminated 
208b0 73 74 72 69 6e 67 73 20 74 68 61 74 20 63 6f 6e  strings that con
208c0 74 61 69 6e 20 61 64 64 69 74 69 6f 6e 61 6c 0a  tain additional.
208d0 2a 2a 20 64 65 74 61 69 6c 73 20 61 62 6f 75 74  ** details about
208e0 20 74 68 65 20 61 63 74 69 6f 6e 20 74 6f 20 62   the action to b
208f0 65 20 61 75 74 68 6f 72 69 7a 65 64 2e 0a 2a 2a  e authorized..**
20900 0a 2a 2a 20 5e 49 66 20 74 68 65 20 61 63 74 69  .** ^If the acti
20910 6f 6e 20 63 6f 64 65 20 69 73 20 5b 53 51 4c 49  on code is [SQLI
20920 54 45 5f 52 45 41 44 5d 0a 2a 2a 20 61 6e 64 20  TE_READ].** and 
20930 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  the callback ret
20940 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 49 47 4e  urns [SQLITE_IGN
20950 4f 52 45 5d 20 74 68 65 6e 20 74 68 65 0a 2a 2a  ORE] then the.**
20960 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
20970 6d 65 6e 74 5d 20 73 74 61 74 65 6d 65 6e 74 20  ment] statement 
20980 69 73 20 63 6f 6e 73 74 72 75 63 74 65 64 20 74  is constructed t
20990 6f 20 73 75 62 73 74 69 74 75 74 65 0a 2a 2a 20  o substitute.** 
209a0 61 20 4e 55 4c 4c 20 76 61 6c 75 65 20 69 6e 20  a NULL value in 
209b0 70 6c 61 63 65 20 6f 66 20 74 68 65 20 74 61 62  place of the tab
209c0 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 77  le column that w
209d0 6f 75 6c 64 20 68 61 76 65 0a 2a 2a 20 62 65 65  ould have.** bee
209e0 6e 20 72 65 61 64 20 69 66 20 5b 53 51 4c 49 54  n read if [SQLIT
209f0 45 5f 4f 4b 5d 20 68 61 64 20 62 65 65 6e 20 72  E_OK] had been r
20a00 65 74 75 72 6e 65 64 2e 20 20 54 68 65 20 5b 53  eturned.  The [S
20a10 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 0a 2a 2a  QLITE_IGNORE].**
20a20 20 72 65 74 75 72 6e 20 63 61 6e 20 62 65 20 75   return can be u
20a30 73 65 64 20 74 6f 20 64 65 6e 79 20 61 6e 20 75  sed to deny an u
20a40 6e 74 72 75 73 74 65 64 20 75 73 65 72 20 61 63  ntrusted user ac
20a50 63 65 73 73 20 74 6f 20 69 6e 64 69 76 69 64 75  cess to individu
20a60 61 6c 0a 2a 2a 20 63 6f 6c 75 6d 6e 73 20 6f 66  al.** columns of
20a70 20 61 20 74 61 62 6c 65 2e 0a 2a 2a 20 5e 49 66   a table..** ^If
20a80 20 74 68 65 20 61 63 74 69 6f 6e 20 63 6f 64 65   the action code
20a90 20 69 73 20 5b 53 51 4c 49 54 45 5f 44 45 4c 45   is [SQLITE_DELE
20aa0 54 45 5d 20 61 6e 64 20 74 68 65 20 63 61 6c 6c  TE] and the call
20ab0 62 61 63 6b 20 72 65 74 75 72 6e 73 0a 2a 2a 20  back returns.** 
20ac0 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20  [SQLITE_IGNORE] 
20ad0 74 68 65 6e 20 74 68 65 20 5b 44 45 4c 45 54 45  then the [DELETE
20ae0 5d 20 6f 70 65 72 61 74 69 6f 6e 20 70 72 6f 63  ] operation proc
20af0 65 65 64 73 20 62 75 74 20 74 68 65 0a 2a 2a 20  eeds but the.** 
20b00 5b 74 72 75 6e 63 61 74 65 20 6f 70 74 69 6d 69  [truncate optimi
20b10 7a 61 74 69 6f 6e 5d 20 69 73 20 64 69 73 61 62  zation] is disab
20b20 6c 65 64 20 61 6e 64 20 61 6c 6c 20 72 6f 77 73  led and all rows
20b30 20 61 72 65 20 64 65 6c 65 74 65 64 20 69 6e 64   are deleted ind
20b40 69 76 69 64 75 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a  ividually..**.**
20b50 20 41 6e 20 61 75 74 68 6f 72 69 7a 65 72 20 69   An authorizer i
20b60 73 20 75 73 65 64 20 77 68 65 6e 20 5b 73 71 6c  s used when [sql
20b70 69 74 65 33 5f 70 72 65 70 61 72 65 20 7c 20 70  ite3_prepare | p
20b80 72 65 70 61 72 69 6e 67 5d 0a 2a 2a 20 53 51 4c  reparing].** SQL
20b90 20 73 74 61 74 65 6d 65 6e 74 73 20 66 72 6f 6d   statements from
20ba0 20 61 6e 20 75 6e 74 72 75 73 74 65 64 20 73 6f   an untrusted so
20bb0 75 72 63 65 2c 20 74 6f 20 65 6e 73 75 72 65 20  urce, to ensure 
20bc0 74 68 61 74 20 74 68 65 20 53 51 4c 20 73 74 61  that the SQL sta
20bd0 74 65 6d 65 6e 74 73 0a 2a 2a 20 64 6f 20 6e 6f  tements.** do no
20be0 74 20 74 72 79 20 74 6f 20 61 63 63 65 73 73 20  t try to access 
20bf0 64 61 74 61 20 74 68 65 79 20 61 72 65 20 6e 6f  data they are no
20c00 74 20 61 6c 6c 6f 77 65 64 20 74 6f 20 73 65 65  t allowed to see
20c10 2c 20 6f 72 20 74 68 61 74 20 74 68 65 79 20 64  , or that they d
20c20 6f 20 6e 6f 74 0a 2a 2a 20 74 72 79 20 74 6f 20  o not.** try to 
20c30 65 78 65 63 75 74 65 20 6d 61 6c 69 63 69 6f 75  execute maliciou
20c40 73 20 73 74 61 74 65 6d 65 6e 74 73 20 74 68 61  s statements tha
20c50 74 20 64 61 6d 61 67 65 20 74 68 65 20 64 61 74  t damage the dat
20c60 61 62 61 73 65 2e 20 20 46 6f 72 0a 2a 2a 20 65  abase.  For.** e
20c70 78 61 6d 70 6c 65 2c 20 61 6e 20 61 70 70 6c 69  xample, an appli
20c80 63 61 74 69 6f 6e 20 6d 61 79 20 61 6c 6c 6f 77  cation may allow
20c90 20 61 20 75 73 65 72 20 74 6f 20 65 6e 74 65 72   a user to enter
20ca0 20 61 72 62 69 74 72 61 72 79 0a 2a 2a 20 53 51   arbitrary.** SQ
20cb0 4c 20 71 75 65 72 69 65 73 20 66 6f 72 20 65 76  L queries for ev
20cc0 61 6c 75 61 74 69 6f 6e 20 62 79 20 61 20 64 61  aluation by a da
20cd0 74 61 62 61 73 65 2e 20 20 42 75 74 20 74 68 65  tabase.  But the
20ce0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 6f 65   application doe
20cf0 73 0a 2a 2a 20 6e 6f 74 20 77 61 6e 74 20 74 68  s.** not want th
20d00 65 20 75 73 65 72 20 74 6f 20 62 65 20 61 62 6c  e user to be abl
20d10 65 20 74 6f 20 6d 61 6b 65 20 61 72 62 69 74 72  e to make arbitr
20d20 61 72 79 20 63 68 61 6e 67 65 73 20 74 6f 20 74  ary changes to t
20d30 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 2e 20  he.** database. 
20d40 20 41 6e 20 61 75 74 68 6f 72 69 7a 65 72 20 63   An authorizer c
20d50 6f 75 6c 64 20 74 68 65 6e 20 62 65 20 70 75 74  ould then be put
20d60 20 69 6e 20 70 6c 61 63 65 20 77 68 69 6c 65 20   in place while 
20d70 74 68 65 0a 2a 2a 20 75 73 65 72 2d 65 6e 74 65  the.** user-ente
20d80 72 65 64 20 53 51 4c 20 69 73 20 62 65 69 6e 67  red SQL is being
20d90 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
20da0 65 20 7c 20 70 72 65 70 61 72 65 64 5d 20 74 68  e | prepared] th
20db0 61 74 0a 2a 2a 20 64 69 73 61 6c 6c 6f 77 73 20  at.** disallows 
20dc0 65 76 65 72 79 74 68 69 6e 67 20 65 78 63 65 70  everything excep
20dd0 74 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65  t [SELECT] state
20de0 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 41 70 70  ments..**.** App
20df0 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 6e  lications that n
20e00 65 65 64 20 74 6f 20 70 72 6f 63 65 73 73 20 53  eed to process S
20e10 51 4c 20 66 72 6f 6d 20 75 6e 74 72 75 73 74 65  QL from untruste
20e20 64 20 73 6f 75 72 63 65 73 0a 2a 2a 20 6d 69 67  d sources.** mig
20e30 68 74 20 61 6c 73 6f 20 63 6f 6e 73 69 64 65 72  ht also consider
20e40 20 6c 6f 77 65 72 69 6e 67 20 72 65 73 6f 75 72   lowering resour
20e50 63 65 20 6c 69 6d 69 74 73 20 75 73 69 6e 67 20  ce limits using 
20e60 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29  [sqlite3_limit()
20e70 5d 0a 2a 2a 20 61 6e 64 20 6c 69 6d 69 74 69 6e  ].** and limitin
20e80 67 20 64 61 74 61 62 61 73 65 20 73 69 7a 65 20  g database size 
20e90 75 73 69 6e 67 20 74 68 65 20 5b 6d 61 78 5f 70  using the [max_p
20ea0 61 67 65 5f 63 6f 75 6e 74 5d 20 5b 50 52 41 47  age_count] [PRAG
20eb0 4d 41 5d 0a 2a 2a 20 69 6e 20 61 64 64 69 74 69  MA].** in additi
20ec0 6f 6e 20 74 6f 20 75 73 69 6e 67 20 61 6e 20 61  on to using an a
20ed0 75 74 68 6f 72 69 7a 65 72 2e 0a 2a 2a 0a 2a 2a  uthorizer..**.**
20ee0 20 5e 28 4f 6e 6c 79 20 61 20 73 69 6e 67 6c 65   ^(Only a single
20ef0 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6e 20   authorizer can 
20f00 62 65 20 69 6e 20 70 6c 61 63 65 20 6f 6e 20 61  be in place on a
20f10 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
20f20 74 69 6f 6e 0a 2a 2a 20 61 74 20 61 20 74 69 6d  tion.** at a tim
20f30 65 2e 20 20 45 61 63 68 20 63 61 6c 6c 20 74 6f  e.  Each call to
20f40 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74   sqlite3_set_aut
20f50 68 6f 72 69 7a 65 72 20 6f 76 65 72 72 69 64 65  horizer override
20f60 73 20 74 68 65 0a 2a 2a 20 70 72 65 76 69 6f 75  s the.** previou
20f70 73 20 63 61 6c 6c 2e 29 5e 20 20 5e 44 69 73 61  s call.)^  ^Disa
20f80 62 6c 65 20 74 68 65 20 61 75 74 68 6f 72 69 7a  ble the authoriz
20f90 65 72 20 62 79 20 69 6e 73 74 61 6c 6c 69 6e 67  er by installing
20fa0 20 61 20 4e 55 4c 4c 20 63 61 6c 6c 62 61 63 6b   a NULL callback
20fb0 2e 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f 72 69  ..** The authori
20fc0 7a 65 72 20 69 73 20 64 69 73 61 62 6c 65 64 20  zer is disabled 
20fd0 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 0a 2a  by default..**.*
20fe0 2a 20 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72  * The authorizer
20ff0 20 63 61 6c 6c 62 61 63 6b 20 6d 75 73 74 20 6e   callback must n
21000 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e 67 20 74  ot do anything t
21010 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a  hat will modify.
21020 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ** the database 
21030 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20  connection that 
21040 69 6e 76 6f 6b 65 64 20 74 68 65 20 61 75 74 68  invoked the auth
21050 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 2e  orizer callback.
21060 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b 73  .** Note that [s
21070 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
21080 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  2()] and [sqlite
21090 33 5f 73 74 65 70 28 29 5d 20 62 6f 74 68 20 6d  3_step()] both m
210a0 6f 64 69 66 79 20 74 68 65 69 72 0a 2a 2a 20 64  odify their.** d
210b0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
210c0 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d 65 61 6e  ons for the mean
210d0 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79 22 20  ing of "modify" 
210e0 69 6e 20 74 68 69 73 20 70 61 72 61 67 72 61 70  in this paragrap
210f0 68 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 65 6e 20 5b  h..**.** ^When [
21100 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
21110 76 32 28 29 5d 20 69 73 20 75 73 65 64 20 74 6f  v2()] is used to
21120 20 70 72 65 70 61 72 65 20 61 20 73 74 61 74 65   prepare a state
21130 6d 65 6e 74 2c 20 74 68 65 0a 2a 2a 20 73 74 61  ment, the.** sta
21140 74 65 6d 65 6e 74 20 6d 69 67 68 74 20 62 65 20  tement might be 
21150 72 65 2d 70 72 65 70 61 72 65 64 20 64 75 72 69  re-prepared duri
21160 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  ng [sqlite3_step
21170 28 29 5d 20 64 75 65 20 74 6f 20 61 20 0a 2a 2a  ()] due to a .**
21180 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65 2e 20   schema change. 
21190 20 48 65 6e 63 65 2c 20 74 68 65 20 61 70 70 6c   Hence, the appl
211a0 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 65  ication should e
211b0 6e 73 75 72 65 20 74 68 61 74 20 74 68 65 0a 2a  nsure that the.*
211c0 2a 20 63 6f 72 72 65 63 74 20 61 75 74 68 6f 72  * correct author
211d0 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 72 65  izer callback re
211e0 6d 61 69 6e 73 20 69 6e 20 70 6c 61 63 65 20 64  mains in place d
211f0 75 72 69 6e 67 20 74 68 65 20 5b 73 71 6c 69 74  uring the [sqlit
21200 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 0a 2a  e3_step()]..**.*
21210 2a 20 5e 4e 6f 74 65 20 74 68 61 74 20 74 68 65  * ^Note that the
21220 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
21230 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20  back is invoked 
21240 6f 6e 6c 79 20 64 75 72 69 6e 67 0a 2a 2a 20 5b  only during.** [
21250 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28  sqlite3_prepare(
21260 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e  )] or its varian
21270 74 73 2e 20 20 41 75 74 68 6f 72 69 7a 61 74 69  ts.  Authorizati
21280 6f 6e 20 69 73 20 6e 6f 74 0a 2a 2a 20 70 65 72  on is not.** per
21290 66 6f 72 6d 65 64 20 64 75 72 69 6e 67 20 73 74  formed during st
212a0 61 74 65 6d 65 6e 74 20 65 76 61 6c 75 61 74 69  atement evaluati
212b0 6f 6e 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f 73  on in [sqlite3_s
212c0 74 65 70 28 29 5d 2c 20 75 6e 6c 65 73 73 0a 2a  tep()], unless.*
212d0 2a 20 61 73 20 73 74 61 74 65 64 20 69 6e 20 74  * as stated in t
212e0 68 65 20 70 72 65 76 69 6f 75 73 20 70 61 72 61  he previous para
212f0 67 72 61 70 68 2c 20 73 71 6c 69 74 65 33 5f 73  graph, sqlite3_s
21300 74 65 70 28 29 20 69 6e 76 6f 6b 65 73 0a 2a 2a  tep() invokes.**
21310 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
21320 5f 76 32 28 29 20 74 6f 20 72 65 70 72 65 70 61  _v2() to reprepa
21330 72 65 20 61 20 73 74 61 74 65 6d 65 6e 74 20 61  re a statement a
21340 66 74 65 72 20 61 20 73 63 68 65 6d 61 20 63 68  fter a schema ch
21350 61 6e 67 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  ange..*/.int sql
21360 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69  ite3_set_authori
21370 7a 65 72 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c  zer(.  sqlite3*,
21380 0a 20 20 69 6e 74 20 28 2a 78 41 75 74 68 29 28  .  int (*xAuth)(
21390 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20  void*,int,const 
213a0 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72  char*,const char
213b0 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f  *,const char*,co
213c0 6e 73 74 20 63 68 61 72 2a 29 2c 0a 20 20 76 6f  nst char*),.  vo
213d0 69 64 20 2a 70 55 73 65 72 44 61 74 61 0a 29 3b  id *pUserData.);
213e0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
213f0 3a 20 41 75 74 68 6f 72 69 7a 65 72 20 52 65 74  : Authorizer Ret
21400 75 72 6e 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20  urn Codes.**.** 
21410 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74  The [sqlite3_set
21420 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c 20 61 75  _authorizer | au
21430 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
21440 6b 20 66 75 6e 63 74 69 6f 6e 5d 20 6d 75 73 74  k function] must
21450 0a 2a 2a 20 72 65 74 75 72 6e 20 65 69 74 68 65  .** return eithe
21460 72 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72  r [SQLITE_OK] or
21470 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 74 77   one of these tw
21480 6f 20 63 6f 6e 73 74 61 6e 74 73 20 69 6e 20 6f  o constants in o
21490 72 64 65 72 0a 2a 2a 20 74 6f 20 73 69 67 6e 61  rder.** to signa
214a0 6c 20 53 51 4c 69 74 65 20 77 68 65 74 68 65 72  l SQLite whether
214b0 20 6f 72 20 6e 6f 74 20 74 68 65 20 61 63 74 69   or not the acti
214c0 6f 6e 20 69 73 20 70 65 72 6d 69 74 74 65 64 2e  on is permitted.
214d0 20 20 53 65 65 20 74 68 65 0a 2a 2a 20 5b 73 71    See the.** [sq
214e0 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72  lite3_set_author
214f0 69 7a 65 72 20 7c 20 61 75 74 68 6f 72 69 7a 65  izer | authorize
21500 72 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 5d  r documentation]
21510 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a   for additional.
21520 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a  ** information..
21530 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20  **.** Note that 
21540 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 20 69 73  SQLITE_IGNORE is
21550 20 61 6c 73 6f 20 75 73 65 64 20 61 73 20 61 20   also used as a 
21560 5b 63 6f 6e 66 6c 69 63 74 20 72 65 73 6f 6c 75  [conflict resolu
21570 74 69 6f 6e 20 6d 6f 64 65 5d 0a 2a 2a 20 72 65  tion mode].** re
21580 74 75 72 6e 65 64 20 66 72 6f 6d 20 74 68 65 20  turned from the 
21590 5b 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 6f 6e  [sqlite3_vtab_on
215a0 5f 63 6f 6e 66 6c 69 63 74 28 29 5d 20 69 6e 74  _conflict()] int
215b0 65 72 66 61 63 65 2e 0a 2a 2f 0a 23 64 65 66 69  erface..*/.#defi
215c0 6e 65 20 53 51 4c 49 54 45 5f 44 45 4e 59 20 20  ne SQLITE_DENY  
215d0 20 31 20 20 20 2f 2a 20 41 62 6f 72 74 20 74 68   1   /* Abort th
215e0 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  e SQL statement 
215f0 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20 2a 2f  with an error */
21600 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
21610 49 47 4e 4f 52 45 20 32 20 20 20 2f 2a 20 44 6f  IGNORE 2   /* Do
21620 6e 27 74 20 61 6c 6c 6f 77 20 61 63 63 65 73 73  n't allow access
21630 2c 20 62 75 74 20 64 6f 6e 27 74 20 67 65 6e 65  , but don't gene
21640 72 61 74 65 20 61 6e 20 65 72 72 6f 72 20 2a 2f  rate an error */
21650 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
21660 3a 20 41 75 74 68 6f 72 69 7a 65 72 20 41 63 74  : Authorizer Act
21670 69 6f 6e 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20  ion Codes.**.** 
21680 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74  The [sqlite3_set
21690 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 5d 20 69  _authorizer()] i
216a0 6e 74 65 72 66 61 63 65 20 72 65 67 69 73 74 65  nterface registe
216b0 72 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75  rs a callback fu
216c0 6e 63 74 69 6f 6e 0a 2a 2a 20 74 68 61 74 20 69  nction.** that i
216d0 73 20 69 6e 76 6f 6b 65 64 20 74 6f 20 61 75 74  s invoked to aut
216e0 68 6f 72 69 7a 65 20 63 65 72 74 61 69 6e 20 53  horize certain S
216f0 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 61 63 74  QL statement act
21700 69 6f 6e 73 2e 20 20 54 68 65 0a 2a 2a 20 73 65  ions.  The.** se
21710 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74  cond parameter t
21720 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69  o the callback i
21730 73 20 61 6e 20 69 6e 74 65 67 65 72 20 63 6f 64  s an integer cod
21740 65 20 74 68 61 74 20 73 70 65 63 69 66 69 65 73  e that specifies
21750 0a 2a 2a 20 77 68 61 74 20 61 63 74 69 6f 6e 20  .** what action 
21760 69 73 20 62 65 69 6e 67 20 61 75 74 68 6f 72 69  is being authori
21770 7a 65 64 2e 20 20 54 68 65 73 65 20 61 72 65 20  zed.  These are 
21780 74 68 65 20 69 6e 74 65 67 65 72 20 61 63 74 69  the integer acti
21790 6f 6e 20 63 6f 64 65 73 20 74 68 61 74 0a 2a 2a  on codes that.**
217a0 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   the authorizer 
217b0 63 61 6c 6c 62 61 63 6b 20 6d 61 79 20 62 65 20  callback may be 
217c0 70 61 73 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  passed..**.** Th
217d0 65 73 65 20 61 63 74 69 6f 6e 20 63 6f 64 65 20  ese action code 
217e0 76 61 6c 75 65 73 20 73 69 67 6e 69 66 79 20 77  values signify w
217f0 68 61 74 20 6b 69 6e 64 20 6f 66 20 6f 70 65 72  hat kind of oper
21800 61 74 69 6f 6e 20 69 73 20 74 6f 20 62 65 0a 2a  ation is to be.*
21810 2a 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 20 54  * authorized.  T
21820 68 65 20 33 72 64 20 61 6e 64 20 34 74 68 20 70  he 3rd and 4th p
21830 61 72 61 6d 65 74 65 72 73 20 74 6f 20 74 68 65  arameters to the
21840 20 61 75 74 68 6f 72 69 7a 61 74 69 6f 6e 0a 2a   authorization.*
21850 2a 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  * callback funct
21860 69 6f 6e 20 77 69 6c 6c 20 62 65 20 70 61 72 61  ion will be para
21870 6d 65 74 65 72 73 20 6f 72 20 4e 55 4c 4c 20 64  meters or NULL d
21880 65 70 65 6e 64 69 6e 67 20 6f 6e 20 77 68 69 63  epending on whic
21890 68 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 63 6f  h of these.** co
218a0 64 65 73 20 69 73 20 75 73 65 64 20 61 73 20 74  des is used as t
218b0 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
218c0 74 65 72 2e 20 20 5e 28 54 68 65 20 35 74 68 20  ter.  ^(The 5th 
218d0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
218e0 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 72 20 63  .** authorizer c
218f0 61 6c 6c 62 61 63 6b 20 69 73 20 74 68 65 20 6e  allback is the n
21900 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61 62  ame of the datab
21910 61 73 65 20 28 22 6d 61 69 6e 22 2c 20 22 74 65  ase ("main", "te
21920 6d 70 22 2c 0a 2a 2a 20 65 74 63 2e 29 20 69 66  mp",.** etc.) if
21930 20 61 70 70 6c 69 63 61 62 6c 65 2e 29 5e 20 20   applicable.)^  
21940 5e 54 68 65 20 36 74 68 20 70 61 72 61 6d 65 74  ^The 6th paramet
21950 65 72 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72  er to the author
21960 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a  izer callback.**
21970 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20   is the name of 
21980 74 68 65 20 69 6e 6e 65 72 2d 6d 6f 73 74 20 74  the inner-most t
21990 72 69 67 67 65 72 20 6f 72 20 76 69 65 77 20 74  rigger or view t
219a0 68 61 74 20 69 73 20 72 65 73 70 6f 6e 73 69 62  hat is responsib
219b0 6c 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 61 63  le for.** the ac
219c0 63 65 73 73 20 61 74 74 65 6d 70 74 20 6f 72 20  cess attempt or 
219d0 4e 55 4c 4c 20 69 66 20 74 68 69 73 20 61 63 63  NULL if this acc
219e0 65 73 73 20 61 74 74 65 6d 70 74 20 69 73 20 64  ess attempt is d
219f0 69 72 65 63 74 6c 79 20 66 72 6f 6d 0a 2a 2a 20  irectly from.** 
21a00 74 6f 70 2d 6c 65 76 65 6c 20 53 51 4c 20 63 6f  top-level SQL co
21a10 64 65 2e 0a 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a  de..*/./********
21a20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
21a30 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
21a40 2a 2a 2a 20 33 72 64 20 2a 2a 2a 2a 2a 2a 2a 2a  *** 3rd ********
21a50 2a 2a 2a 2a 20 34 74 68 20 2a 2a 2a 2a 2a 2a 2a  **** 4th *******
21a60 2a 2a 2a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ****/.#define SQ
21a70 4c 49 54 45 5f 43 52 45 41 54 45 5f 49 4e 44 45  LITE_CREATE_INDE
21a80 58 20 20 20 20 20 20 20 20 20 20 31 20 20 20 2f  X          1   /
21a90 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20  * Index Name    
21aa0 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20    Table Name    
21ab0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
21ac0 49 54 45 5f 43 52 45 41 54 45 5f 54 41 42 4c 45  ITE_CREATE_TABLE
21ad0 20 20 20 20 20 20 20 20 20 20 32 20 20 20 2f 2a            2   /*
21ae0 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
21af0 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
21b00 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
21b10 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 49  TE_CREATE_TEMP_I
21b20 4e 44 45 58 20 20 20 20 20 33 20 20 20 2f 2a 20  NDEX     3   /* 
21b30 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20  Index Name      
21b40 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
21b50 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
21b60 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 54 41  E_CREATE_TEMP_TA
21b70 42 4c 45 20 20 20 20 20 34 20 20 20 2f 2a 20 54  BLE     4   /* T
21b80 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e  able Name      N
21b90 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
21ba0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
21bb0 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 54 52 49  _CREATE_TEMP_TRI
21bc0 47 47 45 52 20 20 20 35 20 20 20 2f 2a 20 54 72  GGER   5   /* Tr
21bd0 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61  igger Name    Ta
21be0 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f  ble Name      */
21bf0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
21c00 43 52 45 41 54 45 5f 54 45 4d 50 5f 56 49 45 57  CREATE_TEMP_VIEW
21c10 20 20 20 20 20 20 36 20 20 20 2f 2a 20 56 69 65        6   /* Vie
21c20 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c  w Name       NUL
21c30 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
21c40 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
21c50 52 45 41 54 45 5f 54 52 49 47 47 45 52 20 20 20  REATE_TRIGGER   
21c60 20 20 20 20 20 37 20 20 20 2f 2a 20 54 72 69 67       7   /* Trig
21c70 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c  ger Name    Tabl
21c80 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23  e Name      */.#
21c90 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52  define SQLITE_CR
21ca0 45 41 54 45 5f 56 49 45 57 20 20 20 20 20 20 20  EATE_VIEW       
21cb0 20 20 20 20 38 20 20 20 2f 2a 20 56 69 65 77 20      8   /* View 
21cc0 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20  Name       NULL 
21cd0 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
21ce0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 4c  efine SQLITE_DEL
21cf0 45 54 45 20 20 20 20 20 20 20 20 20 20 20 20 20  ETE             
21d00 20 20 20 39 20 20 20 2f 2a 20 54 61 62 6c 65 20     9   /* Table 
21d10 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20  Name      NULL  
21d20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
21d30 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50  fine SQLITE_DROP
21d40 5f 49 4e 44 45 58 20 20 20 20 20 20 20 20 20 20  _INDEX          
21d50 20 31 30 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e   10   /* Index N
21d60 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e  ame      Table N
21d70 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66  ame      */.#def
21d80 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f  ine SQLITE_DROP_
21d90 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 20  TABLE           
21da0 31 31 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61  11   /* Table Na
21db0 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  me      NULL    
21dc0 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
21dd0 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54  ne SQLITE_DROP_T
21de0 45 4d 50 5f 49 4e 44 45 58 20 20 20 20 20 20 31  EMP_INDEX      1
21df0 32 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d  2   /* Index Nam
21e00 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d  e      Table Nam
21e10 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  e      */.#defin
21e20 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45  e SQLITE_DROP_TE
21e30 4d 50 5f 54 41 42 4c 45 20 20 20 20 20 20 31 33  MP_TABLE      13
21e40 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
21e50 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
21e60 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
21e70 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d   SQLITE_DROP_TEM
21e80 50 5f 54 52 49 47 47 45 52 20 20 20 20 31 34 20  P_TRIGGER    14 
21e90 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d    /* Trigger Nam
21ea0 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20  e    Table Name 
21eb0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
21ec0 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50  SQLITE_DROP_TEMP
21ed0 5f 56 49 45 57 20 20 20 20 20 20 20 31 35 20 20  _VIEW       15  
21ee0 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20   /* View Name   
21ef0 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
21f00 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
21f10 51 4c 49 54 45 5f 44 52 4f 50 5f 54 52 49 47 47  QLITE_DROP_TRIGG
21f20 45 52 20 20 20 20 20 20 20 20 20 31 36 20 20 20  ER         16   
21f30 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20  /* Trigger Name 
21f40 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20     Table Name   
21f50 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
21f60 4c 49 54 45 5f 44 52 4f 50 5f 56 49 45 57 20 20  LITE_DROP_VIEW  
21f70 20 20 20 20 20 20 20 20 20 20 31 37 20 20 20 2f            17   /
21f80 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20  * View Name     
21f90 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
21fa0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
21fb0 49 54 45 5f 49 4e 53 45 52 54 20 20 20 20 20 20  ITE_INSERT      
21fc0 20 20 20 20 20 20 20 20 20 31 38 20 20 20 2f 2a           18   /*
21fd0 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
21fe0 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
21ff0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
22000 54 45 5f 50 52 41 47 4d 41 20 20 20 20 20 20 20  TE_PRAGMA       
22010 20 20 20 20 20 20 20 20 31 39 20 20 20 2f 2a 20          19   /* 
22020 50 72 61 67 6d 61 20 4e 61 6d 65 20 20 20 20 20  Pragma Name     
22030 31 73 74 20 61 72 67 20 6f 72 20 4e 55 4c 4c 20  1st arg or NULL 
22040 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
22050 45 5f 52 45 41 44 20 20 20 20 20 20 20 20 20 20  E_READ          
22060 20 20 20 20 20 20 20 32 30 20 20 20 2f 2a 20 54         20   /* T
22070 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 43  able Name      C
22080 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20 20 2a  olumn Name     *
22090 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
220a0 5f 53 45 4c 45 43 54 20 20 20 20 20 20 20 20 20  _SELECT         
220b0 20 20 20 20 20 20 32 31 20 20 20 2f 2a 20 4e 55        21   /* NU
220c0 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 4e 55  LL            NU
220d0 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
220e0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
220f0 54 52 41 4e 53 41 43 54 49 4f 4e 20 20 20 20 20  TRANSACTION     
22100 20 20 20 20 20 32 32 20 20 20 2f 2a 20 4f 70 65       22   /* Ope
22110 72 61 74 69 6f 6e 20 20 20 20 20 20 20 4e 55 4c  ration       NUL
22120 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
22130 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55  #define SQLITE_U
22140 50 44 41 54 45 20 20 20 20 20 20 20 20 20 20 20  PDATE           
22150 20 20 20 20 32 33 20 20 20 2f 2a 20 54 61 62 6c      23   /* Tabl
22160 65 20 4e 61 6d 65 20 20 20 20 20 20 43 6f 6c 75  e Name      Colu
22170 6d 6e 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23  mn Name     */.#
22180 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 54  define SQLITE_AT
22190 54 41 43 48 20 20 20 20 20 20 20 20 20 20 20 20  TACH            
221a0 20 20 20 32 34 20 20 20 2f 2a 20 46 69 6c 65 6e     24   /* Filen
221b0 61 6d 65 20 20 20 20 20 20 20 20 4e 55 4c 4c 20  ame        NULL 
221c0 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
221d0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 54  efine SQLITE_DET
221e0 41 43 48 20 20 20 20 20 20 20 20 20 20 20 20 20  ACH             
221f0 20 20 32 35 20 20 20 2f 2a 20 44 61 74 61 62 61    25   /* Databa
22200 73 65 20 4e 61 6d 65 20 20 20 4e 55 4c 4c 20 20  se Name   NULL  
22210 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
22220 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4c 54 45  fine SQLITE_ALTE
22230 52 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20 20  R_TABLE         
22240 20 32 36 20 20 20 2f 2a 20 44 61 74 61 62 61 73   26   /* Databas
22250 65 20 4e 61 6d 65 20 20 20 54 61 62 6c 65 20 4e  e Name   Table N
22260 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66  ame      */.#def
22270 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 49 4e 44  ine SQLITE_REIND
22280 45 58 20 20 20 20 20 20 20 20 20 20 20 20 20 20  EX              
22290 32 37 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61  27   /* Index Na
222a0 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  me      NULL    
222b0 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
222c0 6e 65 20 53 51 4c 49 54 45 5f 41 4e 41 4c 59 5a  ne SQLITE_ANALYZ
222d0 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32  E              2
222e0 38 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  8   /* Table Nam
222f0 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20  e      NULL     
22300 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
22310 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f  e SQLITE_CREATE_
22320 56 54 41 42 4c 45 20 20 20 20 20 20 20 20 32 39  VTABLE        29
22330 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
22340 20 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e 61 6d        Module Nam
22350 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65  e     */.#define
22360 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56 54 41   SQLITE_DROP_VTA
22370 42 4c 45 20 20 20 20 20 20 20 20 20 20 33 30 20  BLE          30 
22380 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20    /* Table Name 
22390 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e 61 6d 65       Module Name
223a0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
223b0 53 51 4c 49 54 45 5f 46 55 4e 43 54 49 4f 4e 20  SQLITE_FUNCTION 
223c0 20 20 20 20 20 20 20 20 20 20 20 20 33 31 20 20              31  
223d0 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20 20   /* NULL        
223e0 20 20 20 20 46 75 6e 63 74 69 6f 6e 20 4e 61 6d      Function Nam
223f0 65 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  e   */.#define S
22400 51 4c 49 54 45 5f 53 41 56 45 50 4f 49 4e 54 20  QLITE_SAVEPOINT 
22410 20 20 20 20 20 20 20 20 20 20 20 33 32 20 20 20             32   
22420 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20 20 20 20  /* Operation    
22430 20 20 20 53 61 76 65 70 6f 69 6e 74 20 4e 61 6d     Savepoint Nam
22440 65 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  e  */.#define SQ
22450 4c 49 54 45 5f 43 4f 50 59 20 20 20 20 20 20 20  LITE_COPY       
22460 20 20 20 20 20 20 20 20 20 20 20 30 20 20 20 2f             0   /
22470 2a 20 4e 6f 20 6c 6f 6e 67 65 72 20 75 73 65 64  * No longer used
22480 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
22490 54 45 5f 52 45 43 55 52 53 49 56 45 20 20 20 20  TE_RECURSIVE    
224a0 20 20 20 20 20 20 20 20 33 33 20 20 20 2f 2a 20          33   /* 
224b0 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
224c0 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
224d0 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  */../*.** CAPI3R
224e0 45 46 3a 20 54 72 61 63 69 6e 67 20 41 6e 64 20  EF: Tracing And 
224f0 50 72 6f 66 69 6c 69 6e 67 20 46 75 6e 63 74 69  Profiling Functi
22500 6f 6e 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  ons.** METHOD: s
22510 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 54 68 65  qlite3.**.** The
22520 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20  se routines are 
22530 64 65 70 72 65 63 61 74 65 64 2e 20 55 73 65 20  deprecated. Use 
22540 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 74 72 61  the [sqlite3_tra
22550 63 65 5f 76 32 28 29 5d 20 69 6e 74 65 72 66 61  ce_v2()] interfa
22560 63 65 0a 2a 2a 20 69 6e 73 74 65 61 64 20 6f 66  ce.** instead of
22570 20 74 68 65 20 72 6f 75 74 69 6e 65 73 20 64 65   the routines de
22580 73 63 72 69 62 65 64 20 68 65 72 65 2e 0a 2a 2a  scribed here..**
22590 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
225a0 65 73 20 72 65 67 69 73 74 65 72 20 63 61 6c 6c  es register call
225b0 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 73 20 74  back functions t
225c0 68 61 74 20 63 61 6e 20 62 65 20 75 73 65 64 20  hat can be used 
225d0 66 6f 72 0a 2a 2a 20 74 72 61 63 69 6e 67 20 61  for.** tracing a
225e0 6e 64 20 70 72 6f 66 69 6c 69 6e 67 20 74 68 65  nd profiling the
225f0 20 65 78 65 63 75 74 69 6f 6e 20 6f 66 20 53 51   execution of SQ
22600 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a  L statements..**
22610 0a 2a 2a 20 5e 54 68 65 20 63 61 6c 6c 62 61 63  .** ^The callbac
22620 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 67 69 73  k function regis
22630 74 65 72 65 64 20 62 79 20 73 71 6c 69 74 65 33  tered by sqlite3
22640 5f 74 72 61 63 65 28 29 20 69 73 20 69 6e 76 6f  _trace() is invo
22650 6b 65 64 20 61 74 0a 2a 2a 20 76 61 72 69 6f 75  ked at.** variou
22660 73 20 74 69 6d 65 73 20 77 68 65 6e 20 61 6e 20  s times when an 
22670 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 73  SQL statement is
22680 20 62 65 69 6e 67 20 72 75 6e 20 62 79 20 5b 73   being run by [s
22690 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a  qlite3_step()]..
226a0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
226b0 74 72 61 63 65 28 29 20 63 61 6c 6c 62 61 63 6b  trace() callback
226c0 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 69 74 68   is invoked with
226d0 20 61 20 55 54 46 2d 38 20 72 65 6e 64 65 72 69   a UTF-8 renderi
226e0 6e 67 20 6f 66 20 74 68 65 0a 2a 2a 20 53 51 4c  ng of the.** SQL
226f0 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20   statement text 
22700 61 73 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  as the statement
22710 20 66 69 72 73 74 20 62 65 67 69 6e 73 20 65 78   first begins ex
22720 65 63 75 74 69 6e 67 2e 0a 2a 2a 20 5e 28 41 64  ecuting..** ^(Ad
22730 64 69 74 69 6f 6e 61 6c 20 73 71 6c 69 74 65 33  ditional sqlite3
22740 5f 74 72 61 63 65 28 29 20 63 61 6c 6c 62 61 63  _trace() callbac
22750 6b 73 20 6d 69 67 68 74 20 6f 63 63 75 72 0a 2a  ks might occur.*
22760 2a 20 61 73 20 65 61 63 68 20 74 72 69 67 67 65  * as each trigge
22770 72 65 64 20 73 75 62 70 72 6f 67 72 61 6d 20 69  red subprogram i
22780 73 20 65 6e 74 65 72 65 64 2e 20 20 54 68 65 20  s entered.  The 
22790 63 61 6c 6c 62 61 63 6b 73 20 66 6f 72 20 74 72  callbacks for tr
227a0 69 67 67 65 72 73 0a 2a 2a 20 63 6f 6e 74 61 69  iggers.** contai
227b0 6e 20 61 20 55 54 46 2d 38 20 53 51 4c 20 63 6f  n a UTF-8 SQL co
227c0 6d 6d 65 6e 74 20 74 68 61 74 20 69 64 65 6e 74  mment that ident
227d0 69 66 69 65 73 20 74 68 65 20 74 72 69 67 67 65  ifies the trigge
227e0 72 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b  r.)^.**.** The [
227f0 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 53 49 5a  SQLITE_TRACE_SIZ
22800 45 5f 4c 49 4d 49 54 5d 20 63 6f 6d 70 69 6c 65  E_LIMIT] compile
22810 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 63 61 6e  -time option can
22820 20 62 65 20 75 73 65 64 20 74 6f 20 6c 69 6d 69   be used to limi
22830 74 0a 2a 2a 20 74 68 65 20 6c 65 6e 67 74 68 20  t.** the length 
22840 6f 66 20 5b 62 6f 75 6e 64 20 70 61 72 61 6d 65  of [bound parame
22850 74 65 72 5d 20 65 78 70 61 6e 73 69 6f 6e 20 69  ter] expansion i
22860 6e 20 74 68 65 20 6f 75 74 70 75 74 20 6f 66 20  n the output of 
22870 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 2e  sqlite3_trace().
22880 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 61 6c 6c  .**.** ^The call
22890 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65  back function re
228a0 67 69 73 74 65 72 65 64 20 62 79 20 73 71 6c 69  gistered by sqli
228b0 74 65 33 5f 70 72 6f 66 69 6c 65 28 29 20 69 73  te3_profile() is
228c0 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61 73 20 65   invoked.** as e
228d0 61 63 68 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ach SQL statemen
228e0 74 20 66 69 6e 69 73 68 65 73 2e 20 20 5e 54 68  t finishes.  ^Th
228f0 65 20 70 72 6f 66 69 6c 65 20 63 61 6c 6c 62 61  e profile callba
22900 63 6b 20 63 6f 6e 74 61 69 6e 73 0a 2a 2a 20 74  ck contains.** t
22910 68 65 20 6f 72 69 67 69 6e 61 6c 20 73 74 61 74  he original stat
22920 65 6d 65 6e 74 20 74 65 78 74 20 61 6e 64 20 61  ement text and a
22930 6e 20 65 73 74 69 6d 61 74 65 20 6f 66 20 77 61  n estimate of wa
22940 6c 6c 2d 63 6c 6f 63 6b 20 74 69 6d 65 0a 2a 2a  ll-clock time.**
22950 20 6f 66 20 68 6f 77 20 6c 6f 6e 67 20 74 68 61   of how long tha
22960 74 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 6f 6b  t statement took
22970 20 74 6f 20 72 75 6e 2e 20 20 5e 54 68 65 20 70   to run.  ^The p
22980 72 6f 66 69 6c 65 20 63 61 6c 6c 62 61 63 6b 0a  rofile callback.
22990 2a 2a 20 74 69 6d 65 20 69 73 20 69 6e 20 75 6e  ** time is in un
229a0 69 74 73 20 6f 66 20 6e 61 6e 6f 73 65 63 6f 6e  its of nanosecon
229b0 64 73 2c 20 68 6f 77 65 76 65 72 20 74 68 65 20  ds, however the 
229c0 63 75 72 72 65 6e 74 20 69 6d 70 6c 65 6d 65 6e  current implemen
229d0 74 61 74 69 6f 6e 0a 2a 2a 20 69 73 20 6f 6e 6c  tation.** is onl
229e0 79 20 63 61 70 61 62 6c 65 20 6f 66 20 6d 69 6c  y capable of mil
229f0 6c 69 73 65 63 6f 6e 64 20 72 65 73 6f 6c 75 74  lisecond resolut
22a00 69 6f 6e 20 73 6f 20 74 68 65 20 73 69 78 20 6c  ion so the six l
22a10 65 61 73 74 20 73 69 67 6e 69 66 69 63 61 6e 74  east significant
22a20 0a 2a 2a 20 64 69 67 69 74 73 20 69 6e 20 74 68  .** digits in th
22a30 65 20 74 69 6d 65 20 61 72 65 20 6d 65 61 6e 69  e time are meani
22a40 6e 67 6c 65 73 73 2e 20 20 46 75 74 75 72 65 20  ngless.  Future 
22a50 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69  versions of SQLi
22a60 74 65 0a 2a 2a 20 6d 69 67 68 74 20 70 72 6f 76  te.** might prov
22a70 69 64 65 20 67 72 65 61 74 65 72 20 72 65 73 6f  ide greater reso
22a80 6c 75 74 69 6f 6e 20 6f 6e 20 74 68 65 20 70 72  lution on the pr
22a90 6f 66 69 6c 65 72 20 63 61 6c 6c 62 61 63 6b 2e  ofiler callback.
22aa0 20 20 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33    The.** sqlite3
22ab0 5f 70 72 6f 66 69 6c 65 28 29 20 66 75 6e 63 74  _profile() funct
22ac0 69 6f 6e 20 69 73 20 63 6f 6e 73 69 64 65 72 65  ion is considere
22ad0 64 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 61  d experimental a
22ae0 6e 64 20 69 73 0a 2a 2a 20 73 75 62 6a 65 63 74  nd is.** subject
22af0 20 74 6f 20 63 68 61 6e 67 65 20 69 6e 20 66 75   to change in fu
22b00 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66  ture versions of
22b10 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 53 51 4c 49   SQLite..*/.SQLI
22b20 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 76 6f  TE_DEPRECATED vo
22b30 69 64 20 2a 73 71 6c 69 74 65 33 5f 74 72 61 63  id *sqlite3_trac
22b40 65 28 73 71 6c 69 74 65 33 2a 2c 0a 20 20 20 76  e(sqlite3*,.   v
22b50 6f 69 64 28 2a 78 54 72 61 63 65 29 28 76 6f 69  oid(*xTrace)(voi
22b60 64 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c  d*,const char*),
22b70 20 76 6f 69 64 2a 29 3b 0a 53 51 4c 49 54 45 5f   void*);.SQLITE_
22b80 44 45 50 52 45 43 41 54 45 44 20 76 6f 69 64 20  DEPRECATED void 
22b90 2a 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65  *sqlite3_profile
22ba0 28 73 71 6c 69 74 65 33 2a 2c 0a 20 20 20 76 6f  (sqlite3*,.   vo
22bb0 69 64 28 2a 78 50 72 6f 66 69 6c 65 29 28 76 6f  id(*xProfile)(vo
22bc0 69 64 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c  id*,const char*,
22bd0 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 29 2c  sqlite3_uint64),
22be0 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20   void*);../*.** 
22bf0 43 41 50 49 33 52 45 46 3a 20 53 51 4c 20 54 72  CAPI3REF: SQL Tr
22c00 61 63 65 20 45 76 65 6e 74 20 43 6f 64 65 73 0a  ace Event Codes.
22c10 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 53 51 4c  ** KEYWORDS: SQL
22c20 49 54 45 5f 54 52 41 43 45 0a 2a 2a 0a 2a 2a 20  ITE_TRACE.**.** 
22c30 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20  These constants 
22c40 69 64 65 6e 74 69 66 79 20 63 6c 61 73 73 65 73  identify classes
22c50 20 6f 66 20 65 76 65 6e 74 73 20 74 68 61 74 20   of events that 
22c60 63 61 6e 20 62 65 20 6d 6f 6e 69 74 6f 72 65 64  can be monitored
22c70 0a 2a 2a 20 75 73 69 6e 67 20 74 68 65 20 5b 73  .** using the [s
22c80 71 6c 69 74 65 33 5f 74 72 61 63 65 5f 76 32 28  qlite3_trace_v2(
22c90 29 5d 20 74 72 61 63 69 6e 67 20 6c 6f 67 69 63  )] tracing logic
22ca0 2e 20 20 54 68 65 20 74 68 69 72 64 20 61 72 67  .  The third arg
22cb0 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 5b 73 71 6c  ument.** to [sql
22cc0 69 74 65 33 5f 74 72 61 63 65 5f 76 32 28 29 5d  ite3_trace_v2()]
22cd0 20 69 73 20 61 6e 20 4f 52 2d 65 64 20 63 6f 6d   is an OR-ed com
22ce0 62 69 6e 61 74 69 6f 6e 20 6f 66 20 6f 6e 65 20  bination of one 
22cf0 6f 72 20 6d 6f 72 65 20 6f 66 0a 2a 2a 20 74 68  or more of.** th
22d00 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 63 6f 6e 73  e following cons
22d10 74 61 6e 74 73 2e 20 20 5e 54 68 65 20 66 69 72  tants.  ^The fir
22d20 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  st argument to t
22d30 68 65 20 74 72 61 63 65 20 63 61 6c 6c 62 61 63  he trace callbac
22d40 6b 0a 2a 2a 20 69 73 20 6f 6e 65 20 6f 66 20 74  k.** is one of t
22d50 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 63 6f 6e  he following con
22d60 73 74 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 4e 65  stants..**.** Ne
22d70 77 20 74 72 61 63 69 6e 67 20 63 6f 6e 73 74 61  w tracing consta
22d80 6e 74 73 20 6d 61 79 20 62 65 20 61 64 64 65 64  nts may be added
22d90 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61   in future relea
22da0 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 20 74 72  ses..**.** ^A tr
22db0 61 63 65 20 63 61 6c 6c 62 61 63 6b 20 68 61 73  ace callback has
22dc0 20 66 6f 75 72 20 61 72 67 75 6d 65 6e 74 73 3a   four arguments:
22dd0 20 78 43 61 6c 6c 62 61 63 6b 28 54 2c 43 2c 50   xCallback(T,C,P
22de0 2c 58 29 2e 0a 2a 2a 20 5e 54 68 65 20 54 20 61  ,X)..** ^The T a
22df0 72 67 75 6d 65 6e 74 20 69 73 20 6f 6e 65 20 6f  rgument is one o
22e00 66 20 74 68 65 20 69 6e 74 65 67 65 72 20 74 79  f the integer ty
22e10 70 65 20 63 6f 64 65 73 20 61 62 6f 76 65 2e 0a  pe codes above..
22e20 2a 2a 20 5e 54 68 65 20 43 20 61 72 67 75 6d 65  ** ^The C argume
22e30 6e 74 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20  nt is a copy of 
22e40 74 68 65 20 63 6f 6e 74 65 78 74 20 70 6f 69 6e  the context poin
22e50 74 65 72 20 70 61 73 73 65 64 20 69 6e 20 61 73  ter passed in as
22e60 20 74 68 65 0a 2a 2a 20 66 6f 75 72 74 68 20 61   the.** fourth a
22e70 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69  rgument to [sqli
22e80 74 65 33 5f 74 72 61 63 65 5f 76 32 28 29 5d 2e  te3_trace_v2()].
22e90 0a 2a 2a 20 54 68 65 20 50 20 61 6e 64 20 58 20  .** The P and X 
22ea0 61 72 67 75 6d 65 6e 74 73 20 61 72 65 20 70 6f  arguments are po
22eb0 69 6e 74 65 72 73 20 77 68 6f 73 65 20 6d 65 61  inters whose mea
22ec0 6e 69 6e 67 73 20 64 65 70 65 6e 64 20 6f 6e 20  nings depend on 
22ed0 54 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a  T..**.** <dl>.**
22ee0 20 5b 5b 53 51 4c 49 54 45 5f 54 52 41 43 45 5f   [[SQLITE_TRACE_
22ef0 53 54 4d 54 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  STMT]] <dt>SQLIT
22f00 45 5f 54 52 41 43 45 5f 53 54 4d 54 3c 2f 64 74  E_TRACE_STMT</dt
22f10 3e 0a 2a 2a 20 3c 64 64 3e 5e 41 6e 20 53 51 4c  >.** <dd>^An SQL
22f20 49 54 45 5f 54 52 41 43 45 5f 53 54 4d 54 20 63  ITE_TRACE_STMT c
22f30 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b  allback is invok
22f40 65 64 20 77 68 65 6e 20 61 20 70 72 65 70 61 72  ed when a prepar
22f50 65 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20  ed statement.** 
22f60 66 69 72 73 74 20 62 65 67 69 6e 73 20 72 75 6e  first begins run
22f70 6e 69 6e 67 20 61 6e 64 20 70 6f 73 73 69 62 6c  ning and possibl
22f80 79 20 61 74 20 6f 74 68 65 72 20 74 69 6d 65 73  y at other times
22f90 20 64 75 72 69 6e 67 20 74 68 65 0a 2a 2a 20 65   during the.** e
22fa0 78 65 63 75 74 69 6f 6e 20 6f 66 20 74 68 65 20  xecution of the 
22fb0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
22fc0 6e 74 2c 20 73 75 63 68 20 61 73 20 61 74 20 74  nt, such as at t
22fd0 68 65 20 73 74 61 72 74 20 6f 66 20 65 61 63 68  he start of each
22fe0 0a 2a 2a 20 74 72 69 67 67 65 72 20 73 75 62 70  .** trigger subp
22ff0 72 6f 67 72 61 6d 2e 20 5e 54 68 65 20 50 20 61  rogram. ^The P a
23000 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69  rgument is a poi
23010 6e 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 5b  nter to the.** [
23020 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
23030 6e 74 5d 2e 20 5e 54 68 65 20 58 20 61 72 67 75  nt]. ^The X argu
23040 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65  ment is a pointe
23050 72 20 74 6f 20 61 20 73 74 72 69 6e 67 20 77 68  r to a string wh
23060 69 63 68 0a 2a 2a 20 69 73 20 74 68 65 20 75 6e  ich.** is the un
23070 65 78 70 61 6e 64 65 64 20 53 51 4c 20 74 65 78  expanded SQL tex
23080 74 20 6f 66 20 74 68 65 20 70 72 65 70 61 72 65  t of the prepare
23090 64 20 73 74 61 74 65 6d 65 6e 74 20 6f 72 20 61  d statement or a
230a0 6e 20 53 51 4c 20 63 6f 6d 6d 65 6e 74 20 0a 2a  n SQL comment .*
230b0 2a 20 74 68 61 74 20 69 6e 64 69 63 61 74 65 73  * that indicates
230c0 20 74 68 65 20 69 6e 76 6f 63 61 74 69 6f 6e 20   the invocation 
230d0 6f 66 20 61 20 74 72 69 67 67 65 72 2e 20 20 5e  of a trigger.  ^
230e0 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 63 61 6e  The callback can
230f0 20 63 6f 6d 70 75 74 65 0a 2a 2a 20 74 68 65 20   compute.** the 
23100 73 61 6d 65 20 74 65 78 74 20 74 68 61 74 20 77  same text that w
23110 6f 75 6c 64 20 68 61 76 65 20 62 65 65 6e 20 72  ould have been r
23120 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 20 6c  eturned by the l
23130 65 67 61 63 79 20 5b 73 71 6c 69 74 65 33 5f 74  egacy [sqlite3_t
23140 72 61 63 65 28 29 5d 0a 2a 2a 20 69 6e 74 65 72  race()].** inter
23150 66 61 63 65 20 62 79 20 75 73 69 6e 67 20 74 68  face by using th
23160 65 20 58 20 61 72 67 75 6d 65 6e 74 20 77 68 65  e X argument whe
23170 6e 20 58 20 62 65 67 69 6e 73 20 77 69 74 68 20  n X begins with 
23180 22 2d 2d 22 20 61 6e 64 20 69 6e 76 6f 6b 69 6e  "--" and invokin
23190 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78  g.** [sqlite3_ex
231a0 70 61 6e 64 65 64 5f 73 71 6c 28 50 29 5d 20 6f  panded_sql(P)] o
231b0 74 68 65 72 77 69 73 65 2e 0a 2a 2a 0a 2a 2a 20  therwise..**.** 
231c0 5b 5b 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 50  [[SQLITE_TRACE_P
231d0 52 4f 46 49 4c 45 5d 5d 20 3c 64 74 3e 53 51 4c  ROFILE]] <dt>SQL
231e0 49 54 45 5f 54 52 41 43 45 5f 50 52 4f 46 49 4c  ITE_TRACE_PROFIL
231f0 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 5e 41  E</dt>.** <dd>^A
23200 6e 20 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 50  n SQLITE_TRACE_P
23210 52 4f 46 49 4c 45 20 63 61 6c 6c 62 61 63 6b 20  ROFILE callback 
23220 70 72 6f 76 69 64 65 73 20 61 70 70 72 6f 78 69  provides approxi
23230 6d 61 74 65 6c 79 20 74 68 65 20 73 61 6d 65 0a  mately the same.
23240 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61  ** information a
23250 73 20 69 73 20 70 72 6f 76 69 64 65 64 20 62 79  s is provided by
23260 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 72   the [sqlite3_pr
23270 6f 66 69 6c 65 28 29 5d 20 63 61 6c 6c 62 61 63  ofile()] callbac
23280 6b 2e 0a 2a 2a 20 5e 54 68 65 20 50 20 61 72 67  k..** ^The P arg
23290 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74  ument is a point
232a0 65 72 20 74 6f 20 74 68 65 20 5b 70 72 65 70 61  er to the [prepa
232b0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 61  red statement] a
232c0 6e 64 20 74 68 65 0a 2a 2a 20 58 20 61 72 67 75  nd the.** X argu
232d0 6d 65 6e 74 20 70 6f 69 6e 74 73 20 74 6f 20 61  ment points to a
232e0 20 36 34 2d 62 69 74 20 69 6e 74 65 67 65 72 20   64-bit integer 
232f0 77 68 69 63 68 20 69 73 20 74 68 65 20 65 73 74  which is the est
23300 69 6d 61 74 65 64 20 6f 66 0a 2a 2a 20 74 68 65  imated of.** the
23310 20 6e 75 6d 62 65 72 20 6f 66 20 6e 61 6e 6f 73   number of nanos
23320 65 63 6f 6e 64 20 74 68 61 74 20 74 68 65 20 70  econd that the p
23330 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
23340 74 20 74 6f 6f 6b 20 74 6f 20 72 75 6e 2e 0a 2a  t took to run..*
23350 2a 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 54 52  * ^The SQLITE_TR
23360 41 43 45 5f 50 52 4f 46 49 4c 45 20 63 61 6c 6c  ACE_PROFILE call
23370 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20  back is invoked 
23380 77 68 65 6e 20 74 68 65 20 73 74 61 74 65 6d 65  when the stateme
23390 6e 74 20 66 69 6e 69 73 68 65 73 2e 0a 2a 2a 0a  nt finishes..**.
233a0 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 54 52 41 43  ** [[SQLITE_TRAC
233b0 45 5f 52 4f 57 5d 5d 20 3c 64 74 3e 53 51 4c 49  E_ROW]] <dt>SQLI
233c0 54 45 5f 54 52 41 43 45 5f 52 4f 57 3c 2f 64 74  TE_TRACE_ROW</dt
233d0 3e 0a 2a 2a 20 3c 64 64 3e 5e 41 6e 20 53 51 4c  >.** <dd>^An SQL
233e0 49 54 45 5f 54 52 41 43 45 5f 52 4f 57 20 63 61  ITE_TRACE_ROW ca
233f0 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65  llback is invoke
23400 64 20 77 68 65 6e 65 76 65 72 20 61 20 70 72 65  d whenever a pre
23410 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65  pared.** stateme
23420 6e 74 20 67 65 6e 65 72 61 74 65 73 20 61 20 73  nt generates a s
23430 69 6e 67 6c 65 20 72 6f 77 20 6f 66 20 72 65 73  ingle row of res
23440 75 6c 74 2e 20 20 0a 2a 2a 20 5e 54 68 65 20 50  ult.  .** ^The P
23450 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70   argument is a p
23460 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 70  ointer to the [p
23470 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
23480 74 5d 20 61 6e 64 20 74 68 65 0a 2a 2a 20 58 20  t] and the.** X 
23490 61 72 67 75 6d 65 6e 74 20 69 73 20 75 6e 75 73  argument is unus
234a0 65 64 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  ed..**.** [[SQLI
234b0 54 45 5f 54 52 41 43 45 5f 43 4c 4f 53 45 5d 5d  TE_TRACE_CLOSE]]
234c0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 54 52 41 43   <dt>SQLITE_TRAC
234d0 45 5f 43 4c 4f 53 45 3c 2f 64 74 3e 0a 2a 2a 20  E_CLOSE</dt>.** 
234e0 3c 64 64 3e 5e 41 6e 20 53 51 4c 49 54 45 5f 54  <dd>^An SQLITE_T
234f0 52 41 43 45 5f 43 4c 4f 53 45 20 63 61 6c 6c 62  RACE_CLOSE callb
23500 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 77  ack is invoked w
23510 68 65 6e 20 61 20 64 61 74 61 62 61 73 65 0a 2a  hen a database.*
23520 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f  * connection clo
23530 73 65 73 2e 0a 2a 2a 20 5e 54 68 65 20 50 20 61  ses..** ^The P a
23540 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69  rgument is a poi
23550 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 64 61 74  nter to the [dat
23560 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
23570 5d 20 6f 62 6a 65 63 74 0a 2a 2a 20 61 6e 64 20  ] object.** and 
23580 74 68 65 20 58 20 61 72 67 75 6d 65 6e 74 20 69  the X argument i
23590 73 20 75 6e 75 73 65 64 2e 0a 2a 2a 20 3c 2f 64  s unused..** </d
235a0 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  l>.*/.#define SQ
235b0 4c 49 54 45 5f 54 52 41 43 45 5f 53 54 4d 54 20  LITE_TRACE_STMT 
235c0 20 20 20 20 20 20 30 78 30 31 0a 23 64 65 66 69        0x01.#defi
235d0 6e 65 20 53 51 4c 49 54 45 5f 54 52 41 43 45 5f  ne SQLITE_TRACE_
235e0 50 52 4f 46 49 4c 45 20 20 20 20 30 78 30 32 0a  PROFILE    0x02.
235f0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54  #define SQLITE_T
23600 52 41 43 45 5f 52 4f 57 20 20 20 20 20 20 20 20  RACE_ROW        
23610 30 78 30 34 0a 23 64 65 66 69 6e 65 20 53 51 4c  0x04.#define SQL
23620 49 54 45 5f 54 52 41 43 45 5f 43 4c 4f 53 45 20  ITE_TRACE_CLOSE 
23630 20 20 20 20 20 30 78 30 38 0a 0a 2f 2a 0a 2a 2a       0x08../*.**
23640 20 43 41 50 49 33 52 45 46 3a 20 53 51 4c 20 54   CAPI3REF: SQL T
23650 72 61 63 65 20 48 6f 6f 6b 0a 2a 2a 20 4d 45 54  race Hook.** MET
23660 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a  HOD: sqlite3.**.
23670 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
23680 74 72 61 63 65 5f 76 32 28 44 2c 4d 2c 58 2c 50  trace_v2(D,M,X,P
23690 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 67 69  ) interface regi
236a0 73 74 65 72 73 20 61 20 74 72 61 63 65 20 63 61  sters a trace ca
236b0 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 69  llback.** functi
236c0 6f 6e 20 58 20 61 67 61 69 6e 73 74 20 5b 64 61  on X against [da
236d0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
236e0 6e 5d 20 44 2c 20 75 73 69 6e 67 20 70 72 6f 70  n] D, using prop
236f0 65 72 74 79 20 6d 61 73 6b 20 4d 0a 2a 2a 20 61  erty mask M.** a
23700 6e 64 20 63 6f 6e 74 65 78 74 20 70 6f 69 6e 74  nd context point
23710 65 72 20 50 2e 20 20 5e 49 66 20 74 68 65 20 58  er P.  ^If the X
23720 20 63 61 6c 6c 62 61 63 6b 20 69 73 0a 2a 2a 20   callback is.** 
23730 4e 55 4c 4c 20 6f 72 20 69 66 20 74 68 65 20 4d  NULL or if the M
23740 20 6d 61 73 6b 20 69 73 20 7a 65 72 6f 2c 20 74   mask is zero, t
23750 68 65 6e 20 74 72 61 63 69 6e 67 20 69 73 20 64  hen tracing is d
23760 69 73 61 62 6c 65 64 2e 20 20 54 68 65 0a 2a 2a  isabled.  The.**
23770 20 4d 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75   M argument shou
23780 6c 64 20 62 65 20 74 68 65 20 62 69 74 77 69 73  ld be the bitwis
23790 65 20 4f 52 2d 65 64 20 63 6f 6d 62 69 6e 61 74  e OR-ed combinat
237a0 69 6f 6e 20 6f 66 0a 2a 2a 20 7a 65 72 6f 20 6f  ion of.** zero o
237b0 72 20 6d 6f 72 65 20 5b 53 51 4c 49 54 45 5f 54  r more [SQLITE_T
237c0 52 41 43 45 5d 20 63 6f 6e 73 74 61 6e 74 73 2e  RACE] constants.
237d0 0a 2a 2a 0a 2a 2a 20 5e 45 61 63 68 20 63 61 6c  .**.** ^Each cal
237e0 6c 20 74 6f 20 65 69 74 68 65 72 20 73 71 6c 69  l to either sqli
237f0 74 65 33 5f 74 72 61 63 65 28 29 20 6f 72 20 73  te3_trace() or s
23800 71 6c 69 74 65 33 5f 74 72 61 63 65 5f 76 32 28  qlite3_trace_v2(
23810 29 20 6f 76 65 72 72 69 64 65 73 20 0a 2a 2a 20  ) overrides .** 
23820 28 63 61 6e 63 65 6c 73 29 20 61 6e 79 20 70 72  (cancels) any pr
23830 69 6f 72 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c  ior calls to sql
23840 69 74 65 33 5f 74 72 61 63 65 28 29 20 6f 72 20  ite3_trace() or 
23850 73 71 6c 69 74 65 33 5f 74 72 61 63 65 5f 76 32  sqlite3_trace_v2
23860 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 58  ()..**.** ^The X
23870 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76   callback is inv
23880 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 20 61 6e  oked whenever an
23890 79 20 6f 66 20 74 68 65 20 65 76 65 6e 74 73 20  y of the events 
238a0 69 64 65 6e 74 69 66 69 65 64 20 62 79 20 0a 2a  identified by .*
238b0 2a 20 6d 61 73 6b 20 4d 20 6f 63 63 75 72 2e 20  * mask M occur. 
238c0 20 5e 54 68 65 20 69 6e 74 65 67 65 72 20 72 65   ^The integer re
238d0 74 75 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20  turn value from 
238e0 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  the callback is 
238f0 63 75 72 72 65 6e 74 6c 79 0a 2a 2a 20 69 67 6e  currently.** ign
23900 6f 72 65 64 2c 20 74 68 6f 75 67 68 20 74 68 69  ored, though thi
23910 73 20 6d 61 79 20 63 68 61 6e 67 65 20 69 6e 20  s may change in 
23920 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 2e  future releases.
23930 20 20 43 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 6d    Callback.** im
23940 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 73 68  plementations sh
23950 6f 75 6c 64 20 72 65 74 75 72 6e 20 7a 65 72 6f  ould return zero
23960 20 74 6f 20 65 6e 73 75 72 65 20 66 75 74 75 72   to ensure futur
23970 65 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e  e compatibility.
23980 0a 2a 2a 0a 2a 2a 20 5e 41 20 74 72 61 63 65 20  .**.** ^A trace 
23990 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f  callback is invo
239a0 6b 65 64 20 77 69 74 68 20 66 6f 75 72 20 61 72  ked with four ar
239b0 67 75 6d 65 6e 74 73 3a 20 63 61 6c 6c 62 61 63  guments: callbac
239c0 6b 28 54 2c 43 2c 50 2c 58 29 2e 0a 2a 2a 20 5e  k(T,C,P,X)..** ^
239d0 54 68 65 20 54 20 61 72 67 75 6d 65 6e 74 20 69  The T argument i
239e0 73 20 6f 6e 65 20 6f 66 20 74 68 65 20 5b 53 51  s one of the [SQ
239f0 4c 49 54 45 5f 54 52 41 43 45 5d 0a 2a 2a 20 63  LITE_TRACE].** c
23a00 6f 6e 73 74 61 6e 74 73 20 74 6f 20 69 6e 64 69  onstants to indi
23a10 63 61 74 65 20 77 68 79 20 74 68 65 20 63 61 6c  cate why the cal
23a20 6c 62 61 63 6b 20 77 61 73 20 69 6e 76 6f 6b 65  lback was invoke
23a30 64 2e 0a 2a 2a 20 5e 54 68 65 20 43 20 61 72 67  d..** ^The C arg
23a40 75 6d 65 6e 74 20 69 73 20 61 20 63 6f 70 79 20  ument is a copy 
23a50 6f 66 20 74 68 65 20 63 6f 6e 74 65 78 74 20 70  of the context p
23a60 6f 69 6e 74 65 72 2e 0a 2a 2a 20 54 68 65 20 50  ointer..** The P
23a70 20 61 6e 64 20 58 20 61 72 67 75 6d 65 6e 74 73   and X arguments
23a80 20 61 72 65 20 70 6f 69 6e 74 65 72 73 20 77 68   are pointers wh
23a90 6f 73 65 20 6d 65 61 6e 69 6e 67 73 20 64 65 70  ose meanings dep
23aa0 65 6e 64 20 6f 6e 20 54 2e 0a 2a 2a 0a 2a 2a 20  end on T..**.** 
23ab0 54 68 65 20 73 71 6c 69 74 65 33 5f 74 72 61 63  The sqlite3_trac
23ac0 65 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63 65  e_v2() interface
23ad0 20 69 73 20 69 6e 74 65 6e 64 65 64 20 74 6f 20   is intended to 
23ae0 72 65 70 6c 61 63 65 20 74 68 65 20 6c 65 67 61  replace the lega
23af0 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73  cy.** interfaces
23b00 20 5b 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28   [sqlite3_trace(
23b10 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
23b20 70 72 6f 66 69 6c 65 28 29 5d 2c 20 62 6f 74 68  profile()], both
23b30 20 6f 66 20 77 68 69 63 68 0a 2a 2a 20 61 72 65   of which.** are
23b40 20 64 65 70 72 65 63 61 74 65 64 2e 0a 2a 2f 0a   deprecated..*/.
23b50 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 72 61 63  int sqlite3_trac
23b60 65 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 2a  e_v2(.  sqlite3*
23b70 2c 0a 20 20 75 6e 73 69 67 6e 65 64 20 75 4d 61  ,.  unsigned uMa
23b80 73 6b 2c 0a 20 20 69 6e 74 28 2a 78 43 61 6c 6c  sk,.  int(*xCall
23b90 62 61 63 6b 29 28 75 6e 73 69 67 6e 65 64 2c 76  back)(unsigned,v
23ba0 6f 69 64 2a 2c 76 6f 69 64 2a 2c 76 6f 69 64 2a  oid*,void*,void*
23bb0 29 2c 0a 20 20 76 6f 69 64 20 2a 70 43 74 78 0a  ),.  void *pCtx.
23bc0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
23bd0 45 46 3a 20 51 75 65 72 79 20 50 72 6f 67 72 65  EF: Query Progre
23be0 73 73 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 20  ss Callbacks.** 
23bf0 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a  METHOD: sqlite3.
23c00 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
23c10 65 33 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e 64  e3_progress_hand
23c20 6c 65 72 28 44 2c 4e 2c 58 2c 50 29 20 69 6e 74  ler(D,N,X,P) int
23c30 65 72 66 61 63 65 20 63 61 75 73 65 73 20 74 68  erface causes th
23c40 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75  e callback.** fu
23c50 6e 63 74 69 6f 6e 20 58 20 74 6f 20 62 65 20 69  nction X to be i
23c60 6e 76 6f 6b 65 64 20 70 65 72 69 6f 64 69 63 61  nvoked periodica
23c70 6c 6c 79 20 64 75 72 69 6e 67 20 6c 6f 6e 67 20  lly during long 
23c80 72 75 6e 6e 69 6e 67 20 63 61 6c 6c 73 20 74 6f  running calls to
23c90 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 65  .** [sqlite3_exe
23ca0 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73  c()], [sqlite3_s
23cb0 74 65 70 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  tep()] and [sqli
23cc0 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d  te3_get_table()]
23cd0 20 66 6f 72 0a 2a 2a 20 64 61 74 61 62 61 73 65   for.** database
23ce0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2e 20 20   connection D.  
23cf0 41 6e 20 65 78 61 6d 70 6c 65 20 75 73 65 20 66  An example use f
23d00 6f 72 20 74 68 69 73 0a 2a 2a 20 69 6e 74 65 72  or this.** inter
23d10 66 61 63 65 20 69 73 20 74 6f 20 6b 65 65 70 20  face is to keep 
23d20 61 20 47 55 49 20 75 70 64 61 74 65 64 20 64 75  a GUI updated du
23d30 72 69 6e 67 20 61 20 6c 61 72 67 65 20 71 75 65  ring a large que
23d40 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 70  ry..**.** ^The p
23d50 61 72 61 6d 65 74 65 72 20 50 20 69 73 20 70 61  arameter P is pa
23d60 73 73 65 64 20 74 68 72 6f 75 67 68 20 61 73 20  ssed through as 
23d70 74 68 65 20 6f 6e 6c 79 20 70 61 72 61 6d 65 74  the only paramet
23d80 65 72 20 74 6f 20 74 68 65 20 0a 2a 2a 20 63 61  er to the .** ca
23d90 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
23da0 58 2e 20 20 5e 54 68 65 20 70 61 72 61 6d 65 74  X.  ^The paramet
23db0 65 72 20 4e 20 69 73 20 74 68 65 20 61 70 70 72  er N is the appr
23dc0 6f 78 69 6d 61 74 65 20 6e 75 6d 62 65 72 20 6f  oximate number o
23dd0 66 20 0a 2a 2a 20 5b 76 69 72 74 75 61 6c 20 6d  f .** [virtual m
23de0 61 63 68 69 6e 65 20 69 6e 73 74 72 75 63 74 69  achine instructi
23df0 6f 6e 73 5d 20 74 68 61 74 20 61 72 65 20 65 76  ons] that are ev
23e00 61 6c 75 61 74 65 64 20 62 65 74 77 65 65 6e 20  aluated between 
23e10 73 75 63 63 65 73 73 69 76 65 0a 2a 2a 20 69 6e  successive.** in
23e20 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 65  vocations of the
23e30 20 63 61 6c 6c 62 61 63 6b 20 58 2e 20 20 5e 49   callback X.  ^I
23e40 66 20 4e 20 69 73 20 6c 65 73 73 20 74 68 61 6e  f N is less than
23e50 20 6f 6e 65 20 74 68 65 6e 20 74 68 65 20 70 72   one then the pr
23e60 6f 67 72 65 73 73 0a 2a 2a 20 68 61 6e 64 6c 65  ogress.** handle
23e70 72 20 69 73 20 64 69 73 61 62 6c 65 64 2e 0a 2a  r is disabled..*
23e80 2a 0a 2a 2a 20 5e 4f 6e 6c 79 20 61 20 73 69 6e  *.** ^Only a sin
23e90 67 6c 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e  gle progress han
23ea0 64 6c 65 72 20 6d 61 79 20 62 65 20 64 65 66 69  dler may be defi
23eb0 6e 65 64 20 61 74 20 6f 6e 65 20 74 69 6d 65 20  ned at one time 
23ec0 70 65 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65  per.** [database
23ed0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 3b 20 73 65   connection]; se
23ee0 74 74 69 6e 67 20 61 20 6e 65 77 20 70 72 6f 67  tting a new prog
23ef0 72 65 73 73 20 68 61 6e 64 6c 65 72 20 63 61 6e  ress handler can
23f00 63 65 6c 73 20 74 68 65 0a 2a 2a 20 6f 6c 64 20  cels the.** old 
23f10 6f 6e 65 2e 20 20 5e 53 65 74 74 69 6e 67 20 70  one.  ^Setting p
23f20 61 72 61 6d 65 74 65 72 20 58 20 74 6f 20 4e 55  arameter X to NU
23f30 4c 4c 20 64 69 73 61 62 6c 65 73 20 74 68 65 20  LL disables the 
23f40 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72  progress handler
23f50 2e 0a 2a 2a 20 5e 54 68 65 20 70 72 6f 67 72 65  ..** ^The progre
23f60 73 73 20 68 61 6e 64 6c 65 72 20 69 73 20 61 6c  ss handler is al
23f70 73 6f 20 64 69 73 61 62 6c 65 64 20 62 79 20 73  so disabled by s
23f80 65 74 74 69 6e 67 20 4e 20 74 6f 20 61 20 76 61  etting N to a va
23f90 6c 75 65 20 6c 65 73 73 0a 2a 2a 20 74 68 61 6e  lue less.** than
23fa0 20 31 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68   1..**.** ^If th
23fb0 65 20 70 72 6f 67 72 65 73 73 20 63 61 6c 6c 62  e progress callb
23fc0 61 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d  ack returns non-
23fd0 7a 65 72 6f 2c 20 74 68 65 20 6f 70 65 72 61 74  zero, the operat
23fe0 69 6f 6e 20 69 73 0a 2a 2a 20 69 6e 74 65 72 72  ion is.** interr
23ff0 75 70 74 65 64 2e 20 20 54 68 69 73 20 66 65 61  upted.  This fea
24000 74 75 72 65 20 63 61 6e 20 62 65 20 75 73 65 64  ture can be used
24010 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 61 0a   to implement a.
24020 2a 2a 20 22 43 61 6e 63 65 6c 22 20 62 75 74 74  ** "Cancel" butt
24030 6f 6e 20 6f 6e 20 61 20 47 55 49 20 70 72 6f 67  on on a GUI prog
24040 72 65 73 73 20 64 69 61 6c 6f 67 20 62 6f 78 2e  ress dialog box.
24050 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 6f 67 72  .**.** The progr
24060 65 73 73 20 68 61 6e 64 6c 65 72 20 63 61 6c 6c  ess handler call
24070 62 61 63 6b 20 6d 75 73 74 20 6e 6f 74 20 64 6f  back must not do
24080 20 61 6e 79 74 68 69 6e 67 20 74 68 61 74 20 77   anything that w
24090 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68  ill modify.** th
240a0 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
240b0 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b  ction that invok
240c0 65 64 20 74 68 65 20 70 72 6f 67 72 65 73 73 20  ed the progress 
240d0 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 4e 6f 74 65  handler..** Note
240e0 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 70   that [sqlite3_p
240f0 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64  repare_v2()] and
24100 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
24110 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79 20 74 68  ] both modify th
24120 65 69 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20  eir.** database 
24130 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20  connections for 
24140 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22  the meaning of "
24150 6d 6f 64 69 66 79 22 20 69 6e 20 74 68 69 73 20  modify" in this 
24160 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2f  paragraph..**.*/
24170 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 70 72  .void sqlite3_pr
24180 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65 72 28 73  ogress_handler(s
24190 71 6c 69 74 65 33 2a 2c 20 69 6e 74 2c 20 69 6e  qlite3*, int, in
241a0 74 28 2a 29 28 76 6f 69 64 2a 29 2c 20 76 6f 69  t(*)(void*), voi
241b0 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  d*);../*.** CAPI
241c0 33 52 45 46 3a 20 4f 70 65 6e 69 6e 67 20 41 20  3REF: Opening A 
241d0 4e 65 77 20 44 61 74 61 62 61 73 65 20 43 6f 6e  New Database Con
241e0 6e 65 63 74 69 6f 6e 0a 2a 2a 20 43 4f 4e 53 54  nection.** CONST
241f0 52 55 43 54 4f 52 3a 20 73 71 6c 69 74 65 33 0a  RUCTOR: sqlite3.
24200 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75  **.** ^These rou
24210 74 69 6e 65 73 20 6f 70 65 6e 20 61 6e 20 53 51  tines open an SQ
24220 4c 69 74 65 20 64 61 74 61 62 61 73 65 20 66 69  Lite database fi
24230 6c 65 20 61 73 20 73 70 65 63 69 66 69 65 64 20  le as specified 
24240 62 79 20 74 68 65 20 0a 2a 2a 20 66 69 6c 65 6e  by the .** filen
24250 61 6d 65 20 61 72 67 75 6d 65 6e 74 2e 20 5e 54  ame argument. ^T
24260 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75  he filename argu
24270 6d 65 6e 74 20 69 73 20 69 6e 74 65 72 70 72 65  ment is interpre
24280 74 65 64 20 61 73 20 55 54 46 2d 38 20 66 6f 72  ted as UTF-8 for
24290 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  .** sqlite3_open
242a0 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f  () and sqlite3_o
242b0 70 65 6e 5f 76 32 28 29 20 61 6e 64 20 61 73 20  pen_v2() and as 
242c0 55 54 46 2d 31 36 20 69 6e 20 74 68 65 20 6e 61  UTF-16 in the na
242d0 74 69 76 65 20 62 79 74 65 0a 2a 2a 20 6f 72 64  tive byte.** ord
242e0 65 72 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f  er for sqlite3_o
242f0 70 65 6e 31 36 28 29 2e 20 5e 28 41 20 5b 64 61  pen16(). ^(A [da
24300 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
24310 6e 5d 20 68 61 6e 64 6c 65 20 69 73 20 75 73 75  n] handle is usu
24320 61 6c 6c 79 0a 2a 2a 20 72 65 74 75 72 6e 65 64  ally.** returned
24330 20 69 6e 20 2a 70 70 44 62 2c 20 65 76 65 6e 20   in *ppDb, even 
24340 69 66 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75  if an error occu
24350 72 73 2e 20 20 54 68 65 20 6f 6e 6c 79 20 65 78  rs.  The only ex
24360 63 65 70 74 69 6f 6e 20 69 73 20 74 68 61 74 0a  ception is that.
24370 2a 2a 20 69 66 20 53 51 4c 69 74 65 20 69 73 20  ** if SQLite is 
24380 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61  unable to alloca
24390 74 65 20 6d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c  te memory to hol
243a0 64 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20  d the [sqlite3] 
243b0 6f 62 6a 65 63 74 2c 0a 2a 2a 20 61 20 4e 55 4c  object,.** a NUL
243c0 4c 20 77 69 6c 6c 20 62 65 20 77 72 69 74 74 65  L will be writte
243d0 6e 20 69 6e 74 6f 20 2a 70 70 44 62 20 69 6e 73  n into *ppDb ins
243e0 74 65 61 64 20 6f 66 20 61 20 70 6f 69 6e 74 65  tead of a pointe
243f0 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  r to the [sqlite
24400 33 5d 0a 2a 2a 20 6f 62 6a 65 63 74 2e 29 5e 20  3].** object.)^ 
24410 5e 28 49 66 20 74 68 65 20 64 61 74 61 62 61 73  ^(If the databas
24420 65 20 69 73 20 6f 70 65 6e 65 64 20 28 61 6e 64  e is opened (and
24430 2f 6f 72 20 63 72 65 61 74 65 64 29 20 73 75 63  /or created) suc
24440 63 65 73 73 66 75 6c 6c 79 2c 20 74 68 65 6e 0a  cessfully, then.
24450 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69  ** [SQLITE_OK] i
24460 73 20 72 65 74 75 72 6e 65 64 2e 20 20 4f 74 68  s returned.  Oth
24470 65 72 77 69 73 65 20 61 6e 20 5b 65 72 72 6f 72  erwise an [error
24480 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e   code] is return
24490 65 64 2e 29 5e 20 5e 54 68 65 0a 2a 2a 20 5b 73  ed.)^ ^The.** [s
244a0 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d  qlite3_errmsg()]
244b0 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 65 72 72   or [sqlite3_err
244c0 6d 73 67 31 36 28 29 5d 20 72 6f 75 74 69 6e 65  msg16()] routine
244d0 73 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  s can be used to
244e0 20 6f 62 74 61 69 6e 0a 2a 2a 20 61 6e 20 45 6e   obtain.** an En
244f0 67 6c 69 73 68 20 6c 61 6e 67 75 61 67 65 20 64  glish language d
24500 65 73 63 72 69 70 74 69 6f 6e 20 6f 66 20 74 68  escription of th
24510 65 20 65 72 72 6f 72 20 66 6f 6c 6c 6f 77 69 6e  e error followin
24520 67 20 61 20 66 61 69 6c 75 72 65 20 6f 66 20 61  g a failure of a
24530 6e 79 0a 2a 2a 20 6f 66 20 74 68 65 20 73 71 6c  ny.** of the sql
24540 69 74 65 33 5f 6f 70 65 6e 28 29 20 72 6f 75 74  ite3_open() rout
24550 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ines..**.** ^The
24560 20 64 65 66 61 75 6c 74 20 65 6e 63 6f 64 69 6e   default encodin
24570 67 20 77 69 6c 6c 20 62 65 20 55 54 46 2d 38 20  g will be UTF-8 
24580 66 6f 72 20 64 61 74 61 62 61 73 65 73 20 63 72  for databases cr
24590 65 61 74 65 64 20 75 73 69 6e 67 0a 2a 2a 20 73  eated using.** s
245a0 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72  qlite3_open() or
245b0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
245c0 28 29 2e 20 20 5e 54 68 65 20 64 65 66 61 75 6c  ().  ^The defaul
245d0 74 20 65 6e 63 6f 64 69 6e 67 20 66 6f 72 20 64  t encoding for d
245e0 61 74 61 62 61 73 65 73 0a 2a 2a 20 63 72 65 61  atabases.** crea
245f0 74 65 64 20 75 73 69 6e 67 20 73 71 6c 69 74 65  ted using sqlite
24600 33 5f 6f 70 65 6e 31 36 28 29 20 77 69 6c 6c 20  3_open16() will 
24610 62 65 20 55 54 46 2d 31 36 20 69 6e 20 74 68 65  be UTF-16 in the
24620 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64   native byte ord
24630 65 72 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 74 68 65  er..**.** Whethe
24640 72 20 6f 72 20 6e 6f 74 20 61 6e 20 65 72 72 6f  r or not an erro
24650 72 20 6f 63 63 75 72 73 20 77 68 65 6e 20 69 74  r occurs when it
24660 20 69 73 20 6f 70 65 6e 65 64 2c 20 72 65 73 6f   is opened, reso
24670 75 72 63 65 73 0a 2a 2a 20 61 73 73 6f 63 69 61  urces.** associa
24680 74 65 64 20 77 69 74 68 20 74 68 65 20 5b 64 61  ted with the [da
24690 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
246a0 6e 5d 20 68 61 6e 64 6c 65 20 73 68 6f 75 6c 64  n] handle should
246b0 20 62 65 20 72 65 6c 65 61 73 65 64 20 62 79 0a   be released by.
246c0 2a 2a 20 70 61 73 73 69 6e 67 20 69 74 20 74 6f  ** passing it to
246d0 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28   [sqlite3_close(
246e0 29 5d 20 77 68 65 6e 20 69 74 20 69 73 20 6e 6f  )] when it is no
246f0 20 6c 6f 6e 67 65 72 20 72 65 71 75 69 72 65 64   longer required
24700 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
24710 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 6e  te3_open_v2() in
24720 74 65 72 66 61 63 65 20 77 6f 72 6b 73 20 6c 69  terface works li
24730 6b 65 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  ke sqlite3_open(
24740 29 0a 2a 2a 20 65 78 63 65 70 74 20 74 68 61 74  ).** except that
24750 20 69 74 20 61 63 63 65 70 74 73 20 74 77 6f 20   it accepts two 
24760 61 64 64 69 74 69 6f 6e 61 6c 20 70 61 72 61 6d  additional param
24770 65 74 65 72 73 20 66 6f 72 20 61 64 64 69 74 69  eters for additi
24780 6f 6e 61 6c 20 63 6f 6e 74 72 6f 6c 0a 2a 2a 20  onal control.** 
24790 6f 76 65 72 20 74 68 65 20 6e 65 77 20 64 61 74  over the new dat
247a0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
247b0 2e 20 20 5e 28 54 68 65 20 66 6c 61 67 73 20 70  .  ^(The flags p
247c0 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 73  arameter to.** s
247d0 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
247e0 20 63 61 6e 20 74 61 6b 65 20 6f 6e 65 20 6f 66   can take one of
247f0 0a 2a 2a 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e  .** the followin
24800 67 20 74 68 72 65 65 20 76 61 6c 75 65 73 2c 20  g three values, 
24810 6f 70 74 69 6f 6e 61 6c 6c 79 20 63 6f 6d 62 69  optionally combi
24820 6e 65 64 20 77 69 74 68 20 74 68 65 20 0a 2a 2a  ned with the .**
24830 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f   [SQLITE_OPEN_NO
24840 4d 55 54 45 58 5d 2c 20 5b 53 51 4c 49 54 45 5f  MUTEX], [SQLITE_
24850 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d 2c  OPEN_FULLMUTEX],
24860 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48   [SQLITE_OPEN_SH
24870 41 52 45 44 43 41 43 48 45 5d 2c 0a 2a 2a 20 5b  AREDCACHE],.** [
24880 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56  SQLITE_OPEN_PRIV
24890 41 54 45 43 41 43 48 45 5d 2c 20 61 6e 64 2f 6f  ATECACHE], and/o
248a0 72 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55  r [SQLITE_OPEN_U
248b0 52 49 5d 20 66 6c 61 67 73 3a 29 5e 0a 2a 2a 0a  RI] flags:)^.**.
248c0 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5e 28 3c 64 74  ** <dl>.** ^(<dt
248d0 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45  >[SQLITE_OPEN_RE
248e0 41 44 4f 4e 4c 59 5d 3c 2f 64 74 3e 0a 2a 2a 20  ADONLY]</dt>.** 
248f0 3c 64 64 3e 54 68 65 20 64 61 74 61 62 61 73 65  <dd>The database
24900 20 69 73 20 6f 70 65 6e 65 64 20 69 6e 20 72 65   is opened in re
24910 61 64 2d 6f 6e 6c 79 20 6d 6f 64 65 2e 20 20 49  ad-only mode.  I
24920 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 64  f the database d
24930 6f 65 73 20 6e 6f 74 0a 2a 2a 20 61 6c 72 65 61  oes not.** alrea
24940 64 79 20 65 78 69 73 74 2c 20 61 6e 20 65 72 72  dy exist, an err
24950 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 3c  or is returned.<
24960 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c  /dd>)^.**.** ^(<
24970 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  dt>[SQLITE_OPEN_
24980 52 45 41 44 57 52 49 54 45 5d 3c 2f 64 74 3e 0a  READWRITE]</dt>.
24990 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 74 61 62  ** <dd>The datab
249a0 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f  ase is opened fo
249b0 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20 77 72  r reading and wr
249c0 69 74 69 6e 67 20 69 66 20 70 6f 73 73 69 62 6c  iting if possibl
249d0 65 2c 20 6f 72 20 72 65 61 64 69 6e 67 0a 2a 2a  e, or reading.**
249e0 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 66 69 6c   only if the fil
249f0 65 20 69 73 20 77 72 69 74 65 20 70 72 6f 74 65  e is write prote
24a00 63 74 65 64 20 62 79 20 74 68 65 20 6f 70 65 72  cted by the oper
24a10 61 74 69 6e 67 20 73 79 73 74 65 6d 2e 20 20 49  ating system.  I
24a20 6e 20 65 69 74 68 65 72 0a 2a 2a 20 63 61 73 65  n either.** case
24a30 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6d 75   the database mu
24a40 73 74 20 61 6c 72 65 61 64 79 20 65 78 69 73 74  st already exist
24a50 2c 20 6f 74 68 65 72 77 69 73 65 20 61 6e 20 65  , otherwise an e
24a60 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64  rror is returned
24a70 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  .</dd>)^.**.** ^
24a80 28 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45  (<dt>[SQLITE_OPE
24a90 4e 5f 52 45 41 44 57 52 49 54 45 5d 20 7c 20 5b  N_READWRITE] | [
24aa0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41  SQLITE_OPEN_CREA
24ab0 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  TE]</dt>.** <dd>
24ac0 54 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20  The database is 
24ad0 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64 69  opened for readi
24ae0 6e 67 20 61 6e 64 20 77 72 69 74 69 6e 67 2c 20  ng and writing, 
24af0 61 6e 64 20 69 73 20 63 72 65 61 74 65 64 20 69  and is created i
24b00 66 0a 2a 2a 20 69 74 20 64 6f 65 73 20 6e 6f 74  f.** it does not
24b10 20 61 6c 72 65 61 64 79 20 65 78 69 73 74 2e 20   already exist. 
24b20 54 68 69 73 20 69 73 20 74 68 65 20 62 65 68 61  This is the beha
24b30 76 69 6f 72 20 74 68 61 74 20 69 73 20 61 6c 77  vior that is alw
24b40 61 79 73 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20  ays used for.** 
24b50 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 61  sqlite3_open() a
24b60 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  nd sqlite3_open1
24b70 36 28 29 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 20 3c  6().</dd>)^.** <
24b80 2f 64 6c 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68  /dl>.**.** If th
24b90 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20  e 3rd parameter 
24ba0 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  to sqlite3_open_
24bb0 76 32 28 29 20 69 73 20 6e 6f 74 20 6f 6e 65 20  v2() is not one 
24bc0 6f 66 20 74 68 65 0a 2a 2a 20 63 6f 6d 62 69 6e  of the.** combin
24bd0 61 74 69 6f 6e 73 20 73 68 6f 77 6e 20 61 62 6f  ations shown abo
24be0 76 65 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 63 6f  ve optionally co
24bf0 6d 62 69 6e 65 64 20 77 69 74 68 20 6f 74 68 65  mbined with othe
24c00 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45  r.** [SQLITE_OPE
24c10 4e 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 53 51 4c  N_READONLY | SQL
24c20 49 54 45 5f 4f 50 45 4e 5f 2a 20 62 69 74 73 5d  ITE_OPEN_* bits]
24c30 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 62 65 68  .** then the beh
24c40 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e  avior is undefin
24c50 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  ed..**.** ^If th
24c60 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e  e [SQLITE_OPEN_N
24c70 4f 4d 55 54 45 58 5d 20 66 6c 61 67 20 69 73 20  OMUTEX] flag is 
24c80 73 65 74 2c 20 74 68 65 6e 20 74 68 65 20 64 61  set, then the da
24c90 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
24ca0 6e 0a 2a 2a 20 6f 70 65 6e 73 20 69 6e 20 74 68  n.** opens in th
24cb0 65 20 6d 75 6c 74 69 2d 74 68 72 65 61 64 20 5b  e multi-thread [
24cc0 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20  threading mode] 
24cd0 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 73  as long as the s
24ce0 69 6e 67 6c 65 2d 74 68 72 65 61 64 0a 2a 2a 20  ingle-thread.** 
24cf0 6d 6f 64 65 20 68 61 73 20 6e 6f 74 20 62 65 65  mode has not bee
24d00 6e 20 73 65 74 20 61 74 20 63 6f 6d 70 69 6c 65  n set at compile
24d10 2d 74 69 6d 65 20 6f 72 20 73 74 61 72 74 2d 74  -time or start-t
24d20 69 6d 65 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a  ime.  ^If the.**
24d30 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55   [SQLITE_OPEN_FU
24d40 4c 4c 4d 55 54 45 58 5d 20 66 6c 61 67 20 69 73  LLMUTEX] flag is
24d50 20 73 65 74 20 74 68 65 6e 20 74 68 65 20 64 61   set then the da
24d60 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
24d70 6e 20 6f 70 65 6e 73 0a 2a 2a 20 69 6e 20 74 68  n opens.** in th
24d80 65 20 73 65 72 69 61 6c 69 7a 65 64 20 5b 74 68  e serialized [th
24d90 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 75 6e  reading mode] un
24da0 6c 65 73 73 20 73 69 6e 67 6c 65 2d 74 68 72 65  less single-thre
24db0 61 64 20 77 61 73 0a 2a 2a 20 70 72 65 76 69 6f  ad was.** previo
24dc0 75 73 6c 79 20 73 65 6c 65 63 74 65 64 20 61 74  usly selected at
24dd0 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 72   compile-time or
24de0 20 73 74 61 72 74 2d 74 69 6d 65 2e 0a 2a 2a 20   start-time..** 
24df0 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45  ^The [SQLITE_OPE
24e00 4e 5f 53 48 41 52 45 44 43 41 43 48 45 5d 20 66  N_SHAREDCACHE] f
24e10 6c 61 67 20 63 61 75 73 65 73 20 74 68 65 20 64  lag causes the d
24e20 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
24e30 6f 6e 20 74 6f 20 62 65 0a 2a 2a 20 65 6c 69 67  on to be.** elig
24e40 69 62 6c 65 20 74 6f 20 75 73 65 20 5b 73 68 61  ible to use [sha
24e50 72 65 64 20 63 61 63 68 65 20 6d 6f 64 65 5d 2c  red cache mode],
24e60 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77   regardless of w
24e70 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 73 68  hether or not sh
24e80 61 72 65 64 0a 2a 2a 20 63 61 63 68 65 20 69 73  ared.** cache is
24e90 20 65 6e 61 62 6c 65 64 20 75 73 69 6e 67 20 5b   enabled using [
24ea0 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 73  sqlite3_enable_s
24eb0 68 61 72 65 64 5f 63 61 63 68 65 28 29 5d 2e 20  hared_cache()]. 
24ec0 20 5e 54 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45   ^The.** [SQLITE
24ed0 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43  _OPEN_PRIVATECAC
24ee0 48 45 5d 20 66 6c 61 67 20 63 61 75 73 65 73 20  HE] flag causes 
24ef0 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
24f00 6e 65 63 74 69 6f 6e 20 74 6f 20 6e 6f 74 0a 2a  nection to not.*
24f10 2a 20 70 61 72 74 69 63 69 70 61 74 65 20 69 6e  * participate in
24f20 20 5b 73 68 61 72 65 64 20 63 61 63 68 65 20 6d   [shared cache m
24f30 6f 64 65 5d 20 65 76 65 6e 20 69 66 20 69 74 20  ode] even if it 
24f40 69 73 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a  is enabled..**.*
24f50 2a 20 5e 54 68 65 20 66 6f 75 72 74 68 20 70 61  * ^The fourth pa
24f60 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
24f70 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20  e3_open_v2() is 
24f80 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 0a  the name of the.
24f90 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d  ** [sqlite3_vfs]
24fa0 20 6f 62 6a 65 63 74 20 74 68 61 74 20 64 65 66   object that def
24fb0 69 6e 65 73 20 74 68 65 20 6f 70 65 72 61 74 69  ines the operati
24fc0 6e 67 20 73 79 73 74 65 6d 20 69 6e 74 65 72 66  ng system interf
24fd0 61 63 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20  ace that.** the 
24fe0 6e 65 77 20 64 61 74 61 62 61 73 65 20 63 6f 6e  new database con
24ff0 6e 65 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20 75  nection should u
25000 73 65 2e 20 20 5e 49 66 20 74 68 65 20 66 6f 75  se.  ^If the fou
25010 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73  rth parameter is
25020 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  .** a NULL point
25030 65 72 20 74 68 65 6e 20 74 68 65 20 64 65 66 61  er then the defa
25040 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  ult [sqlite3_vfs
25050 5d 20 6f 62 6a 65 63 74 20 69 73 20 75 73 65 64  ] object is used
25060 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
25070 66 69 6c 65 6e 61 6d 65 20 69 73 20 22 3a 6d 65  filename is ":me
25080 6d 6f 72 79 3a 22 2c 20 74 68 65 6e 20 61 20 70  mory:", then a p
25090 72 69 76 61 74 65 2c 20 74 65 6d 70 6f 72 61 72  rivate, temporar
250a0 79 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61  y in-memory data
250b0 62 61 73 65 0a 2a 2a 20 69 73 20 63 72 65 61 74  base.** is creat
250c0 65 64 20 66 6f 72 20 74 68 65 20 63 6f 6e 6e 65  ed for the conne
250d0 63 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 69 6e  ction.  ^This in
250e0 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65  -memory database
250f0 20 77 69 6c 6c 20 76 61 6e 69 73 68 20 77 68 65   will vanish whe
25100 6e 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73  n.** the databas
25110 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20  e connection is 
25120 63 6c 6f 73 65 64 2e 20 20 46 75 74 75 72 65 20  closed.  Future 
25130 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69  versions of SQLi
25140 74 65 20 6d 69 67 68 74 0a 2a 2a 20 6d 61 6b 65  te might.** make
25150 20 75 73 65 20 6f 66 20 61 64 64 69 74 69 6f 6e   use of addition
25160 61 6c 20 73 70 65 63 69 61 6c 20 66 69 6c 65 6e  al special filen
25170 61 6d 65 73 20 74 68 61 74 20 62 65 67 69 6e 20  ames that begin 
25180 77 69 74 68 20 74 68 65 20 22 3a 22 20 63 68 61  with the ":" cha
25190 72 61 63 74 65 72 2e 0a 2a 2a 20 49 74 20 69 73  racter..** It is
251a0 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61   recommended tha
251b0 74 20 77 68 65 6e 20 61 20 64 61 74 61 62 61 73  t when a databas
251c0 65 20 66 69 6c 65 6e 61 6d 65 20 61 63 74 75 61  e filename actua
251d0 6c 6c 79 20 64 6f 65 73 20 62 65 67 69 6e 20 77  lly does begin w
251e0 69 74 68 0a 2a 2a 20 61 20 22 3a 22 20 63 68 61  ith.** a ":" cha
251f0 72 61 63 74 65 72 20 79 6f 75 20 73 68 6f 75 6c  racter you shoul
25200 64 20 70 72 65 66 69 78 20 74 68 65 20 66 69 6c  d prefix the fil
25210 65 6e 61 6d 65 20 77 69 74 68 20 61 20 70 61 74  ename with a pat
25220 68 6e 61 6d 65 20 73 75 63 68 20 61 73 0a 2a 2a  hname such as.**
25230 20 22 2e 2f 22 20 74 6f 20 61 76 6f 69 64 20 61   "./" to avoid a
25240 6d 62 69 67 75 69 74 79 2e 0a 2a 2a 0a 2a 2a 20  mbiguity..**.** 
25250 5e 49 66 20 74 68 65 20 66 69 6c 65 6e 61 6d 65  ^If the filename
25260 20 69 73 20 61 6e 20 65 6d 70 74 79 20 73 74 72   is an empty str
25270 69 6e 67 2c 20 74 68 65 6e 20 61 20 70 72 69 76  ing, then a priv
25280 61 74 65 2c 20 74 65 6d 70 6f 72 61 72 79 0a 2a  ate, temporary.*
25290 2a 20 6f 6e 2d 64 69 73 6b 20 64 61 74 61 62 61  * on-disk databa
252a0 73 65 20 77 69 6c 6c 20 62 65 20 63 72 65 61 74  se will be creat
252b0 65 64 2e 20 20 5e 54 68 69 73 20 70 72 69 76 61  ed.  ^This priva
252c0 74 65 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c  te database will
252d0 20 62 65 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63   be.** automatic
252e0 61 6c 6c 79 20 64 65 6c 65 74 65 64 20 61 73 20  ally deleted as 
252f0 73 6f 6f 6e 20 61 73 20 74 68 65 20 64 61 74 61  soon as the data
25300 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
25310 69 73 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a  is closed..**.**
25320 20 5b 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65 73   [[URI filenames
25330 20 69 6e 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e   in sqlite3_open
25340 28 29 5d 5d 20 3c 68 33 3e 55 52 49 20 46 69 6c  ()]] <h3>URI Fil
25350 65 6e 61 6d 65 73 3c 2f 68 33 3e 0a 2a 2a 0a 2a  enames</h3>.**.*
25360 2a 20 5e 49 66 20 5b 55 52 49 20 66 69 6c 65 6e  * ^If [URI filen
25370 61 6d 65 5d 20 69 6e 74 65 72 70 72 65 74 61 74  ame] interpretat
25380 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 2c 20  ion is enabled, 
25390 61 6e 64 20 74 68 65 20 66 69 6c 65 6e 61 6d 65  and the filename
253a0 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 62 65 67   argument.** beg
253b0 69 6e 73 20 77 69 74 68 20 22 66 69 6c 65 3a 22  ins with "file:"
253c0 2c 20 74 68 65 6e 20 74 68 65 20 66 69 6c 65 6e  , then the filen
253d0 61 6d 65 20 69 73 20 69 6e 74 65 72 70 72 65 74  ame is interpret
253e0 65 64 20 61 73 20 61 20 55 52 49 2e 20 5e 55 52  ed as a URI. ^UR
253f0 49 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 69 6e  I.** filename in
25400 74 65 72 70 72 65 74 61 74 69 6f 6e 20 69 73 20  terpretation is 
25410 65 6e 61 62 6c 65 64 20 69 66 20 74 68 65 20 5b  enabled if the [
25420 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d  SQLITE_OPEN_URI]
25430 20 66 6c 61 67 20 69 73 0a 2a 2a 20 73 65 74 20   flag is.** set 
25440 69 6e 20 74 68 65 20 66 6f 75 72 74 68 20 61 72  in the fourth ar
25450 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65  gument to sqlite
25460 33 5f 6f 70 65 6e 5f 76 32 28 29 2c 20 6f 72 20  3_open_v2(), or 
25470 69 66 20 69 74 20 68 61 73 0a 2a 2a 20 62 65 65  if it has.** bee
25480 6e 20 65 6e 61 62 6c 65 64 20 67 6c 6f 62 61 6c  n enabled global
25490 6c 79 20 75 73 69 6e 67 20 74 68 65 20 5b 53 51  ly using the [SQ
254a0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 5d  LITE_CONFIG_URI]
254b0 20 6f 70 74 69 6f 6e 20 77 69 74 68 20 74 68 65   option with the
254c0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  .** [sqlite3_con
254d0 66 69 67 28 29 5d 20 6d 65 74 68 6f 64 20 6f 72  fig()] method or
254e0 20 62 79 20 74 68 65 20 5b 53 51 4c 49 54 45 5f   by the [SQLITE_
254f0 55 53 45 5f 55 52 49 5d 20 63 6f 6d 70 69 6c 65  USE_URI] compile
25500 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2e 0a 2a 2a  -time option..**
25510 20 41 73 20 6f 66 20 53 51 4c 69 74 65 20 76 65   As of SQLite ve
25520 72 73 69 6f 6e 20 33 2e 37 2e 37 2c 20 55 52 49  rsion 3.7.7, URI
25530 20 66 69 6c 65 6e 61 6d 65 20 69 6e 74 65 72 70   filename interp
25540 72 65 74 61 74 69 6f 6e 20 69 73 20 74 75 72 6e  retation is turn
25550 65 64 20 6f 66 66 0a 2a 2a 20 62 79 20 64 65 66  ed off.** by def
25560 61 75 6c 74 2c 20 62 75 74 20 66 75 74 75 72 65  ault, but future
25570 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c   releases of SQL
25580 69 74 65 20 6d 69 67 68 74 20 65 6e 61 62 6c 65  ite might enable
25590 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 0a 2a 2a   URI filename.**
255a0 20 69 6e 74 65 72 70 72 65 74 61 74 69 6f 6e 20   interpretation 
255b0 62 79 20 64 65 66 61 75 6c 74 2e 20 20 53 65 65  by default.  See
255c0 20 22 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65 73   "[URI filenames
255d0 5d 22 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61  ]" for additiona
255e0 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  l.** information
255f0 2e 0a 2a 2a 0a 2a 2a 20 55 52 49 20 66 69 6c 65  ..**.** URI file
25600 6e 61 6d 65 73 20 61 72 65 20 70 61 72 73 65 64  names are parsed
25610 20 61 63 63 6f 72 64 69 6e 67 20 74 6f 20 52 46   according to RF
25620 43 20 33 39 38 36 2e 20 5e 49 66 20 74 68 65 20  C 3986. ^If the 
25630 55 52 49 20 63 6f 6e 74 61 69 6e 73 20 61 6e 0a  URI contains an.
25640 2a 2a 20 61 75 74 68 6f 72 69 74 79 2c 20 74 68  ** authority, th
25650 65 6e 20 69 74 20 6d 75 73 74 20 62 65 20 65 69  en it must be ei
25660 74 68 65 72 20 61 6e 20 65 6d 70 74 79 20 73 74  ther an empty st
25670 72 69 6e 67 20 6f 72 20 74 68 65 20 73 74 72 69  ring or the stri
25680 6e 67 20 0a 2a 2a 20 22 6c 6f 63 61 6c 68 6f 73  ng .** "localhos
25690 74 22 2e 20 5e 49 66 20 74 68 65 20 61 75 74 68  t". ^If the auth
256a0 6f 72 69 74 79 20 69 73 20 6e 6f 74 20 61 6e 20  ority is not an 
256b0 65 6d 70 74 79 20 73 74 72 69 6e 67 20 6f 72 20  empty string or 
256c0 22 6c 6f 63 61 6c 68 6f 73 74 22 2c 20 61 6e 20  "localhost", an 
256d0 0a 2a 2a 20 65 72 72 6f 72 20 69 73 20 72 65 74  .** error is ret
256e0 75 72 6e 65 64 20 74 6f 20 74 68 65 20 63 61 6c  urned to the cal
256f0 6c 65 72 2e 20 5e 54 68 65 20 66 72 61 67 6d 65  ler. ^The fragme
25700 6e 74 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20  nt component of 
25710 61 20 55 52 49 2c 20 69 66 20 0a 2a 2a 20 70 72  a URI, if .** pr
25720 65 73 65 6e 74 2c 20 69 73 20 69 67 6e 6f 72 65  esent, is ignore
25730 64 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65  d..**.** ^SQLite
25740 20 75 73 65 73 20 74 68 65 20 70 61 74 68 20 63   uses the path c
25750 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 74 68 65 20  omponent of the 
25760 55 52 49 20 61 73 20 74 68 65 20 6e 61 6d 65 20  URI as the name 
25770 6f 66 20 74 68 65 20 64 69 73 6b 20 66 69 6c 65  of the disk file
25780 0a 2a 2a 20 77 68 69 63 68 20 63 6f 6e 74 61 69  .** which contai
25790 6e 73 20 74 68 65 20 64 61 74 61 62 61 73 65 2e  ns the database.
257a0 20 5e 49 66 20 74 68 65 20 70 61 74 68 20 62 65   ^If the path be
257b0 67 69 6e 73 20 77 69 74 68 20 61 20 27 2f 27 20  gins with a '/' 
257c0 63 68 61 72 61 63 74 65 72 2c 20 0a 2a 2a 20 74  character, .** t
257d0 68 65 6e 20 69 74 20 69 73 20 69 6e 74 65 72 70  hen it is interp
257e0 72 65 74 65 64 20 61 73 20 61 6e 20 61 62 73 6f  reted as an abso
257f0 6c 75 74 65 20 70 61 74 68 2e 20 5e 49 66 20 74  lute path. ^If t
25800 68 65 20 70 61 74 68 20 64 6f 65 73 20 6e 6f 74  he path does not
25810 20 62 65 67 69 6e 20 0a 2a 2a 20 77 69 74 68 20   begin .** with 
25820 61 20 27 2f 27 20 28 6d 65 61 6e 69 6e 67 20 74  a '/' (meaning t
25830 68 61 74 20 74 68 65 20 61 75 74 68 6f 72 69 74  hat the authorit
25840 79 20 73 65 63 74 69 6f 6e 20 69 73 20 6f 6d 69  y section is omi
25850 74 74 65 64 20 66 72 6f 6d 20 74 68 65 20 55 52  tted from the UR
25860 49 29 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 70  I).** then the p
25870 61 74 68 20 69 73 20 69 6e 74 65 72 70 72 65 74  ath is interpret
25880 65 64 20 61 73 20 61 20 72 65 6c 61 74 69 76 65  ed as a relative
25890 20 70 61 74 68 2e 20 0a 2a 2a 20 5e 28 4f 6e 20   path. .** ^(On 
258a0 77 69 6e 64 6f 77 73 2c 20 74 68 65 20 66 69 72  windows, the fir
258b0 73 74 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20  st component of 
258c0 61 6e 20 61 62 73 6f 6c 75 74 65 20 70 61 74 68  an absolute path
258d0 20 0a 2a 2a 20 69 73 20 61 20 64 72 69 76 65 20   .** is a drive 
258e0 73 70 65 63 69 66 69 63 61 74 69 6f 6e 20 28 65  specification (e
258f0 2e 67 2e 20 22 43 3a 22 29 2e 29 5e 0a 2a 2a 0a  .g. "C:").)^.**.
25900 2a 2a 20 5b 5b 63 6f 72 65 20 55 52 49 20 71 75  ** [[core URI qu
25910 65 72 79 20 70 61 72 61 6d 65 74 65 72 73 5d 5d  ery parameters]]
25920 0a 2a 2a 20 54 68 65 20 71 75 65 72 79 20 63 6f  .** The query co
25930 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 20 55 52 49  mponent of a URI
25940 20 6d 61 79 20 63 6f 6e 74 61 69 6e 20 70 61 72   may contain par
25950 61 6d 65 74 65 72 73 20 74 68 61 74 20 61 72 65  ameters that are
25960 20 69 6e 74 65 72 70 72 65 74 65 64 0a 2a 2a 20   interpreted.** 
25970 65 69 74 68 65 72 20 62 79 20 53 51 4c 69 74 65  either by SQLite
25980 20 69 74 73 65 6c 66 2c 20 6f 72 20 62 79 20 61   itself, or by a
25990 20 5b 56 46 53 20 7c 20 63 75 73 74 6f 6d 20 56   [VFS | custom V
259a0 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  FS implementatio
259b0 6e 5d 2e 0a 2a 2a 20 53 51 4c 69 74 65 20 61 6e  n]..** SQLite an
259c0 64 20 69 74 73 20 62 75 69 6c 74 2d 69 6e 20 5b  d its built-in [
259d0 56 46 53 65 73 5d 20 69 6e 74 65 72 70 72 65 74  VFSes] interpret
259e0 20 74 68 65 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e   the.** followin
259f0 67 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65  g query paramete
25a00 72 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a  rs:.**.** <ul>.*
25a10 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e 76 66 73 3c  *   <li> <b>vfs<
25a20 2f 62 3e 3a 20 5e 54 68 65 20 22 76 66 73 22 20  /b>: ^The "vfs" 
25a30 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65  parameter may be
25a40 20 75 73 65 64 20 74 6f 20 73 70 65 63 69 66 79   used to specify
25a50 20 74 68 65 20 6e 61 6d 65 20 6f 66 0a 2a 2a 20   the name of.** 
25a60 20 20 20 20 61 20 56 46 53 20 6f 62 6a 65 63 74      a VFS object
25a70 20 74 68 61 74 20 70 72 6f 76 69 64 65 73 20 74   that provides t
25a80 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73  he operating sys
25a90 74 65 6d 20 69 6e 74 65 72 66 61 63 65 20 74 68  tem interface th
25aa0 61 74 20 73 68 6f 75 6c 64 0a 2a 2a 20 20 20 20  at should.**    
25ab0 20 62 65 20 75 73 65 64 20 74 6f 20 61 63 63 65   be used to acce
25ac0 73 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ss the database 
25ad0 66 69 6c 65 20 6f 6e 20 64 69 73 6b 2e 20 5e 49  file on disk. ^I
25ae0 66 20 74 68 69 73 20 6f 70 74 69 6f 6e 20 69 73  f this option is
25af0 20 73 65 74 20 74 6f 0a 2a 2a 20 20 20 20 20 61   set to.**     a
25b00 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 20 74  n empty string t
25b10 68 65 20 64 65 66 61 75 6c 74 20 56 46 53 20 6f  he default VFS o
25b20 62 6a 65 63 74 20 69 73 20 75 73 65 64 2e 20 5e  bject is used. ^
25b30 53 70 65 63 69 66 79 69 6e 67 20 61 6e 20 75 6e  Specifying an un
25b40 6b 6e 6f 77 6e 0a 2a 2a 20 20 20 20 20 56 46 53  known.**     VFS
25b50 20 69 73 20 61 6e 20 65 72 72 6f 72 2e 20 5e 49   is an error. ^I
25b60 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  f sqlite3_open_v
25b70 32 28 29 20 69 73 20 75 73 65 64 20 61 6e 64 20  2() is used and 
25b80 74 68 65 20 76 66 73 20 6f 70 74 69 6f 6e 20 69  the vfs option i
25b90 73 0a 2a 2a 20 20 20 20 20 70 72 65 73 65 6e 74  s.**     present
25ba0 2c 20 74 68 65 6e 20 74 68 65 20 56 46 53 20 73  , then the VFS s
25bb0 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20  pecified by the 
25bc0 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 70 72 65  option takes pre
25bd0 63 65 64 65 6e 63 65 20 6f 76 65 72 0a 2a 2a 20  cedence over.** 
25be0 20 20 20 20 74 68 65 20 76 61 6c 75 65 20 70 61      the value pa
25bf0 73 73 65 64 20 61 73 20 74 68 65 20 66 6f 75 72  ssed as the four
25c00 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
25c10 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
25c20 29 2e 0a 2a 2a 0a 2a 2a 20 20 20 3c 6c 69 3e 20  )..**.**   <li> 
25c30 3c 62 3e 6d 6f 64 65 3c 2f 62 3e 3a 20 5e 28 54  <b>mode</b>: ^(T
25c40 68 65 20 6d 6f 64 65 20 70 61 72 61 6d 65 74 65  he mode paramete
25c50 72 20 6d 61 79 20 62 65 20 73 65 74 20 74 6f 20  r may be set to 
25c60 65 69 74 68 65 72 20 22 72 6f 22 2c 20 22 72 77  either "ro", "rw
25c70 22 2c 0a 2a 2a 20 20 20 20 20 22 72 77 63 22 2c  ",.**     "rwc",
25c80 20 6f 72 20 22 6d 65 6d 6f 72 79 22 2e 20 41 74   or "memory". At
25c90 74 65 6d 70 74 69 6e 67 20 74 6f 20 73 65 74 20  tempting to set 
25ca0 69 74 20 74 6f 20 61 6e 79 20 6f 74 68 65 72 20  it to any other 
25cb0 76 61 6c 75 65 20 69 73 0a 2a 2a 20 20 20 20 20  value is.**     
25cc0 61 6e 20 65 72 72 6f 72 29 5e 2e 20 0a 2a 2a 20  an error)^. .** 
25cd0 20 20 20 20 5e 49 66 20 22 72 6f 22 20 69 73 20      ^If "ro" is 
25ce0 73 70 65 63 69 66 69 65 64 2c 20 74 68 65 6e 20  specified, then 
25cf0 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20  the database is 
25d00 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64 2d  opened for read-
25d10 6f 6e 6c 79 20 0a 2a 2a 20 20 20 20 20 61 63 63  only .**     acc
25d20 65 73 73 2c 20 6a 75 73 74 20 61 73 20 69 66 20  ess, just as if 
25d30 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  the [SQLITE_OPEN
25d40 5f 52 45 41 44 4f 4e 4c 59 5d 20 66 6c 61 67 20  _READONLY] flag 
25d50 68 61 64 20 62 65 65 6e 20 73 65 74 20 69 6e 20  had been set in 
25d60 74 68 65 20 0a 2a 2a 20 20 20 20 20 74 68 69 72  the .**     thir
25d70 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71  d argument to sq
25d80 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e  lite3_open_v2().
25d90 20 5e 49 66 20 74 68 65 20 6d 6f 64 65 20 6f 70   ^If the mode op
25da0 74 69 6f 6e 20 69 73 20 73 65 74 20 74 6f 20 0a  tion is set to .
25db0 2a 2a 20 20 20 20 20 22 72 77 22 2c 20 74 68 65  **     "rw", the
25dc0 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69  n the database i
25dd0 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61  s opened for rea
25de0 64 2d 77 72 69 74 65 20 28 62 75 74 20 6e 6f 74  d-write (but not
25df0 20 63 72 65 61 74 65 29 20 0a 2a 2a 20 20 20 20   create) .**    
25e00 20 61 63 63 65 73 73 2c 20 61 73 20 69 66 20 53   access, as if S
25e10 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57  QLITE_OPEN_READW
25e20 52 49 54 45 20 28 62 75 74 20 6e 6f 74 20 53 51  RITE (but not SQ
25e30 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45  LITE_OPEN_CREATE
25e40 29 20 68 61 64 20 0a 2a 2a 20 20 20 20 20 62 65  ) had .**     be
25e50 65 6e 20 73 65 74 2e 20 5e 56 61 6c 75 65 20 22  en set. ^Value "
25e60 72 77 63 22 20 69 73 20 65 71 75 69 76 61 6c 65  rwc" is equivale
25e70 6e 74 20 74 6f 20 73 65 74 74 69 6e 67 20 62 6f  nt to setting bo
25e80 74 68 20 0a 2a 2a 20 20 20 20 20 53 51 4c 49 54  th .**     SQLIT
25e90 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45  E_OPEN_READWRITE
25ea0 20 61 6e 64 20 53 51 4c 49 54 45 5f 4f 50 45 4e   and SQLITE_OPEN
25eb0 5f 43 52 45 41 54 45 2e 20 20 5e 49 66 20 74 68  _CREATE.  ^If th
25ec0 65 20 6d 6f 64 65 20 6f 70 74 69 6f 6e 20 69 73  e mode option is
25ed0 0a 2a 2a 20 20 20 20 20 73 65 74 20 74 6f 20 22  .**     set to "
25ee0 6d 65 6d 6f 72 79 22 20 74 68 65 6e 20 61 20 70  memory" then a p
25ef0 75 72 65 20 5b 69 6e 2d 6d 65 6d 6f 72 79 20 64  ure [in-memory d
25f00 61 74 61 62 61 73 65 5d 20 74 68 61 74 20 6e 65  atabase] that ne
25f10 76 65 72 20 72 65 61 64 73 0a 2a 2a 20 20 20 20  ver reads.**    
25f20 20 6f 72 20 77 72 69 74 65 73 20 66 72 6f 6d 20   or writes from 
25f30 64 69 73 6b 20 69 73 20 75 73 65 64 2e 20 5e 49  disk is used. ^I
25f40 74 20 69 73 20 61 6e 20 65 72 72 6f 72 20 74 6f  t is an error to
25f50 20 73 70 65 63 69 66 79 20 61 20 76 61 6c 75 65   specify a value
25f60 20 66 6f 72 0a 2a 2a 20 20 20 20 20 74 68 65 20   for.**     the 
25f70 6d 6f 64 65 20 70 61 72 61 6d 65 74 65 72 20 74  mode parameter t
25f80 68 61 74 20 69 73 20 6c 65 73 73 20 72 65 73 74  hat is less rest
25f90 72 69 63 74 69 76 65 20 74 68 61 6e 20 74 68 61  rictive than tha
25fa0 74 20 73 70 65 63 69 66 69 65 64 20 62 79 0a 2a  t specified by.*
25fb0 2a 20 20 20 20 20 74 68 65 20 66 6c 61 67 73 20  *     the flags 
25fc0 70 61 73 73 65 64 20 69 6e 20 74 68 65 20 74 68  passed in the th
25fd0 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ird parameter to
25fe0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
25ff0 28 29 2e 0a 2a 2a 0a 2a 2a 20 20 20 3c 6c 69 3e  ()..**.**   <li>
26000 20 3c 62 3e 63 61 63 68 65 3c 2f 62 3e 3a 20 5e   <b>cache</b>: ^
26010 54 68 65 20 63 61 63 68 65 20 70 61 72 61 6d 65  The cache parame
26020 74 65 72 20 6d 61 79 20 62 65 20 73 65 74 20 74  ter may be set t
26030 6f 20 65 69 74 68 65 72 20 22 73 68 61 72 65 64  o either "shared
26040 22 20 6f 72 0a 2a 2a 20 20 20 20 20 22 70 72 69  " or.**     "pri
26050 76 61 74 65 22 2e 20 5e 53 65 74 74 69 6e 67 20  vate". ^Setting 
26060 69 74 20 74 6f 20 22 73 68 61 72 65 64 22 20 69  it to "shared" i
26070 73 20 65 71 75 69 76 61 6c 65 6e 74 20 74 6f 20  s equivalent to 
26080 73 65 74 74 69 6e 67 20 74 68 65 0a 2a 2a 20 20  setting the.**  
26090 20 20 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53     SQLITE_OPEN_S
260a0 48 41 52 45 44 43 41 43 48 45 20 62 69 74 20 69  HAREDCACHE bit i
260b0 6e 20 74 68 65 20 66 6c 61 67 73 20 61 72 67 75  n the flags argu
260c0 6d 65 6e 74 20 70 61 73 73 65 64 20 74 6f 0a 2a  ment passed to.*
260d0 2a 20 20 20 20 20 73 71 6c 69 74 65 33 5f 6f 70  *     sqlite3_op
260e0 65 6e 5f 76 32 28 29 2e 20 5e 53 65 74 74 69 6e  en_v2(). ^Settin
260f0 67 20 74 68 65 20 63 61 63 68 65 20 70 61 72 61  g the cache para
26100 6d 65 74 65 72 20 74 6f 20 22 70 72 69 76 61 74  meter to "privat
26110 65 22 20 69 73 20 0a 2a 2a 20 20 20 20 20 65 71  e" is .**     eq
26120 75 69 76 61 6c 65 6e 74 20 74 6f 20 73 65 74 74  uivalent to sett
26130 69 6e 67 20 74 68 65 20 53 51 4c 49 54 45 5f 4f  ing the SQLITE_O
26140 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45  PEN_PRIVATECACHE
26150 20 62 69 74 2e 0a 2a 2a 20 20 20 20 20 5e 49 66   bit..**     ^If
26160 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
26170 28 29 20 69 73 20 75 73 65 64 20 61 6e 64 20 74  () is used and t
26180 68 65 20 22 63 61 63 68 65 22 20 70 61 72 61 6d  he "cache" param
26190 65 74 65 72 20 69 73 20 70 72 65 73 65 6e 74 20  eter is present 
261a0 69 6e 0a 2a 2a 20 20 20 20 20 61 20 55 52 49 20  in.**     a URI 
261b0 66 69 6c 65 6e 61 6d 65 2c 20 69 74 73 20 76 61  filename, its va
261c0 6c 75 65 20 6f 76 65 72 72 69 64 65 73 20 61 6e  lue overrides an
261d0 79 20 62 65 68 61 76 69 6f 72 20 72 65 71 75 65  y behavior reque
261e0 73 74 65 64 20 62 79 20 73 65 74 74 69 6e 67 0a  sted by setting.
261f0 2a 2a 20 20 20 20 20 53 51 4c 49 54 45 5f 4f 50  **     SQLITE_OP
26200 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45 20  EN_PRIVATECACHE 
26210 6f 72 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53  or SQLITE_OPEN_S
26220 48 41 52 45 44 43 41 43 48 45 20 66 6c 61 67 2e  HAREDCACHE flag.
26230 0a 2a 2a 0a 2a 2a 20 20 3c 6c 69 3e 20 3c 62 3e  .**.**  <li> <b>
26240 70 73 6f 77 3c 2f 62 3e 3a 20 5e 54 68 65 20 70  psow</b>: ^The p
26250 73 6f 77 20 70 61 72 61 6d 65 74 65 72 20 69 6e  sow parameter in
26260 64 69 63 61 74 65 73 20 77 68 65 74 68 65 72 20  dicates whether 
26270 6f 72 20 6e 6f 74 20 74 68 65 0a 2a 2a 20 20 20  or not the.**   
26280 20 20 5b 70 6f 77 65 72 73 61 66 65 20 6f 76 65    [powersafe ove
26290 72 77 72 69 74 65 5d 20 70 72 6f 70 65 72 74 79  rwrite] property
262a0 20 64 6f 65 73 20 6f 72 20 64 6f 65 73 20 6e 6f   does or does no
262b0 74 20 61 70 70 6c 79 20 74 6f 20 74 68 65 0a 2a  t apply to the.*
262c0 2a 20 20 20 20 20 73 74 6f 72 61 67 65 20 6d 65  *     storage me
262d0 64 69 61 20 6f 6e 20 77 68 69 63 68 20 74 68 65  dia on which the
262e0 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 72   database file r
262f0 65 73 69 64 65 73 2e 0a 2a 2a 0a 2a 2a 20 20 3c  esides..**.**  <
26300 6c 69 3e 20 3c 62 3e 6e 6f 6c 6f 63 6b 3c 2f 62  li> <b>nolock</b
26310 3e 3a 20 5e 54 68 65 20 6e 6f 6c 6f 63 6b 20 70  >: ^The nolock p
26320 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 62 6f  arameter is a bo
26330 6f 6c 65 61 6e 20 71 75 65 72 79 20 70 61 72 61  olean query para
26340 6d 65 74 65 72 0a 2a 2a 20 20 20 20 20 77 68 69  meter.**     whi
26350 63 68 20 69 66 20 73 65 74 20 64 69 73 61 62 6c  ch if set disabl
26360 65 73 20 66 69 6c 65 20 6c 6f 63 6b 69 6e 67 20  es file locking 
26370 69 6e 20 72 6f 6c 6c 62 61 63 6b 20 6a 6f 75 72  in rollback jour
26380 6e 61 6c 20 6d 6f 64 65 73 2e 20 20 54 68 69 73  nal modes.  This
26390 0a 2a 2a 20 20 20 20 20 69 73 20 75 73 65 66 75  .**     is usefu
263a0 6c 20 66 6f 72 20 61 63 63 65 73 73 69 6e 67 20  l for accessing 
263b0 61 20 64 61 74 61 62 61 73 65 20 6f 6e 20 61 20  a database on a 
263c0 66 69 6c 65 73 79 73 74 65 6d 20 74 68 61 74 20  filesystem that 
263d0 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 20 20 20 20  does not.**     
263e0 73 75 70 70 6f 72 74 20 6c 6f 63 6b 69 6e 67 2e  support locking.
263f0 20 20 43 61 75 74 69 6f 6e 3a 20 20 44 61 74 61    Caution:  Data
26400 62 61 73 65 20 63 6f 72 72 75 70 74 69 6f 6e 20  base corruption 
26410 6d 69 67 68 74 20 72 65 73 75 6c 74 20 69 66 20  might result if 
26420 74 77 6f 0a 2a 2a 20 20 20 20 20 6f 72 20 6d 6f  two.**     or mo
26430 72 65 20 70 72 6f 63 65 73 73 65 73 20 77 72 69  re processes wri
26440 74 65 20 74 6f 20 74 68 65 20 73 61 6d 65 20 64  te to the same d
26450 61 74 61 62 61 73 65 20 61 6e 64 20 61 6e 79 20  atabase and any 
26460 6f 6e 65 20 6f 66 20 74 68 6f 73 65 0a 2a 2a 20  one of those.** 
26470 20 20 20 20 70 72 6f 63 65 73 73 65 73 20 75 73      processes us
26480 65 73 20 6e 6f 6c 6f 63 6b 3d 31 2e 0a 2a 2a 0a  es nolock=1..**.
26490 2a 2a 20 20 3c 6c 69 3e 20 3c 62 3e 69 6d 6d 75  **  <li> <b>immu
264a0 74 61 62 6c 65 3c 2f 62 3e 3a 20 5e 54 68 65 20  table</b>: ^The 
264b0 69 6d 6d 75 74 61 62 6c 65 20 70 61 72 61 6d 65  immutable parame
264c0 74 65 72 20 69 73 20 61 20 62 6f 6f 6c 65 61 6e  ter is a boolean
264d0 20 71 75 65 72 79 0a 2a 2a 20 20 20 20 20 70 61   query.**     pa
264e0 72 61 6d 65 74 65 72 20 74 68 61 74 20 69 6e 64  rameter that ind
264f0 69 63 61 74 65 73 20 74 68 61 74 20 74 68 65 20  icates that the 
26500 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 69 73  database file is
26510 20 73 74 6f 72 65 64 20 6f 6e 0a 2a 2a 20 20 20   stored on.**   
26520 20 20 72 65 61 64 2d 6f 6e 6c 79 20 6d 65 64 69    read-only medi
26530 61 2e 20 20 5e 57 68 65 6e 20 69 6d 6d 75 74 61  a.  ^When immuta
26540 62 6c 65 20 69 73 20 73 65 74 2c 20 53 51 4c 69  ble is set, SQLi
26550 74 65 20 61 73 73 75 6d 65 73 20 74 68 61 74 20  te assumes that 
26560 74 68 65 0a 2a 2a 20 20 20 20 20 64 61 74 61 62  the.**     datab
26570 61 73 65 20 66 69 6c 65 20 63 61 6e 6e 6f 74 20  ase file cannot 
26580 62 65 20 63 68 61 6e 67 65 64 2c 20 65 76 65 6e  be changed, even
26590 20 62 79 20 61 20 70 72 6f 63 65 73 73 20 77 69   by a process wi
265a0 74 68 20 68 69 67 68 65 72 0a 2a 2a 20 20 20 20  th higher.**    
265b0 20 70 72 69 76 69 6c 65 67 65 2c 20 61 6e 64 20   privilege, and 
265c0 73 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 20  so the database 
265d0 69 73 20 6f 70 65 6e 65 64 20 72 65 61 64 2d 6f  is opened read-o
265e0 6e 6c 79 20 61 6e 64 20 61 6c 6c 20 6c 6f 63 6b  nly and all lock
265f0 69 6e 67 0a 2a 2a 20 20 20 20 20 61 6e 64 20 63  ing.**     and c
26600 68 61 6e 67 65 20 64 65 74 65 63 74 69 6f 6e 20  hange detection 
26610 69 73 20 64 69 73 61 62 6c 65 64 2e 20 20 43 61  is disabled.  Ca
26620 75 74 69 6f 6e 3a 20 53 65 74 74 69 6e 67 20 74  ution: Setting t
26630 68 65 20 69 6d 6d 75 74 61 62 6c 65 0a 2a 2a 20  he immutable.** 
26640 20 20 20 20 70 72 6f 70 65 72 74 79 20 6f 6e 20      property on 
26650 61 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  a database file 
26660 74 68 61 74 20 64 6f 65 73 20 69 6e 20 66 61 63  that does in fac
26670 74 20 63 68 61 6e 67 65 20 63 61 6e 20 72 65 73  t change can res
26680 75 6c 74 0a 2a 2a 20 20 20 20 20 69 6e 20 69 6e  ult.**     in in
26690 63 6f 72 72 65 63 74 20 71 75 65 72 79 20 72 65  correct query re
266a0 73 75 6c 74 73 20 61 6e 64 2f 6f 72 20 5b 53 51  sults and/or [SQ
266b0 4c 49 54 45 5f 43 4f 52 52 55 50 54 5d 20 65 72  LITE_CORRUPT] er
266c0 72 6f 72 73 2e 0a 2a 2a 20 20 20 20 20 53 65 65  rors..**     See
266d0 20 61 6c 73 6f 3a 20 5b 53 51 4c 49 54 45 5f 49   also: [SQLITE_I
266e0 4f 43 41 50 5f 49 4d 4d 55 54 41 42 4c 45 5d 2e  OCAP_IMMUTABLE].
266f0 0a 2a 2a 20 20 20 20 20 20 20 0a 2a 2a 20 3c 2f  .**       .** </
26700 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 53 70 65 63 69  ul>.**.** ^Speci
26710 66 79 69 6e 67 20 61 6e 20 75 6e 6b 6e 6f 77 6e  fying an unknown
26720 20 70 61 72 61 6d 65 74 65 72 20 69 6e 20 74 68   parameter in th
26730 65 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e  e query componen
26740 74 20 6f 66 20 61 20 55 52 49 20 69 73 20 6e 6f  t of a URI is no
26750 74 20 61 6e 0a 2a 2a 20 65 72 72 6f 72 2e 20 20  t an.** error.  
26760 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20  Future versions 
26770 6f 66 20 53 51 4c 69 74 65 20 6d 69 67 68 74 20  of SQLite might 
26780 75 6e 64 65 72 73 74 61 6e 64 20 61 64 64 69 74  understand addit
26790 69 6f 6e 61 6c 20 71 75 65 72 79 0a 2a 2a 20 70  ional query.** p
267a0 61 72 61 6d 65 74 65 72 73 2e 20 20 53 65 65 20  arameters.  See 
267b0 22 5b 71 75 65 72 79 20 70 61 72 61 6d 65 74 65  "[query paramete
267c0 72 73 20 77 69 74 68 20 73 70 65 63 69 61 6c 20  rs with special 
267d0 6d 65 61 6e 69 6e 67 20 74 6f 20 53 51 4c 69 74  meaning to SQLit
267e0 65 5d 22 20 66 6f 72 0a 2a 2a 20 61 64 64 69 74  e]" for.** addit
267f0 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f  ional informatio
26800 6e 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 55 52 49 20 66  n..**.** [[URI f
26810 69 6c 65 6e 61 6d 65 20 65 78 61 6d 70 6c 65 73  ilename examples
26820 5d 5d 20 3c 68 33 3e 55 52 49 20 66 69 6c 65 6e  ]] <h3>URI filen
26830 61 6d 65 20 65 78 61 6d 70 6c 65 73 3c 2f 68 33  ame examples</h3
26840 3e 0a 2a 2a 0a 2a 2a 20 3c 74 61 62 6c 65 20 62  >.**.** <table b
26850 6f 72 64 65 72 3d 22 31 22 20 61 6c 69 67 6e 3d  order="1" align=
26860 63 65 6e 74 65 72 20 63 65 6c 6c 70 61 64 64 69  center cellpaddi
26870 6e 67 3d 35 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68  ng=5>.** <tr><th
26880 3e 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 20  > URI filenames 
26890 3c 74 68 3e 20 52 65 73 75 6c 74 73 0a 2a 2a 20  <th> Results.** 
268a0 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 64 61  <tr><td> file:da
268b0 74 61 2e 64 62 20 3c 74 64 3e 20 0a 2a 2a 20 20  ta.db <td> .**  
268c0 20 20 20 20 20 20 20 20 4f 70 65 6e 20 74 68 65          Open the
268d0 20 66 69 6c 65 20 22 64 61 74 61 2e 64 62 22 20   file "data.db" 
268e0 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20 64  in the current d
268f0 69 72 65 63 74 6f 72 79 2e 0a 2a 2a 20 3c 74 72  irectory..** <tr
26900 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f 68 6f 6d 65  ><td> file:/home
26910 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 3c 62 72  /fred/data.db<br
26920 3e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 69  >.**          fi
26930 6c 65 3a 2f 2f 2f 68 6f 6d 65 2f 66 72 65 64 2f  le:///home/fred/
26940 64 61 74 61 2e 64 62 20 3c 62 72 3e 20 0a 2a 2a  data.db <br> .**
26950 20 20 20 20 20 20 20 20 20 20 66 69 6c 65 3a 2f            file:/
26960 2f 6c 6f 63 61 6c 68 6f 73 74 2f 68 6f 6d 65 2f  /localhost/home/
26970 66 72 65 64 2f 64 61 74 61 2e 64 62 20 3c 62 72  fred/data.db <br
26980 3e 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20  > <td> .**      
26990 20 20 20 20 4f 70 65 6e 20 74 68 65 20 64 61 74      Open the dat
269a0 61 62 61 73 65 20 66 69 6c 65 20 22 2f 68 6f 6d  abase file "/hom
269b0 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 22 2e  e/fred/data.db".
269c0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c  .** <tr><td> fil
269d0 65 3a 2f 2f 64 61 72 6b 73 74 61 72 2f 68 6f 6d  e://darkstar/hom
269e0 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 20 3c  e/fred/data.db <
269f0 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20  td> .**         
26a00 20 41 6e 20 65 72 72 6f 72 2e 20 22 64 61 72 6b   An error. "dark
26a10 73 74 61 72 22 20 69 73 20 6e 6f 74 20 61 20 72  star" is not a r
26a20 65 63 6f 67 6e 69 7a 65 64 20 61 75 74 68 6f 72  ecognized author
26a30 69 74 79 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 20  ity..** <tr><td 
26a40 73 74 79 6c 65 3d 22 77 68 69 74 65 2d 73 70 61  style="white-spa
26a50 63 65 3a 6e 6f 77 72 61 70 22 3e 20 0a 2a 2a 20  ce:nowrap"> .** 
26a60 20 20 20 20 20 20 20 20 20 66 69 6c 65 3a 2f 2f           file://
26a70 2f 43 3a 2f 44 6f 63 75 6d 65 6e 74 73 25 32 30  /C:/Documents%20
26a80 61 6e 64 25 32 30 53 65 74 74 69 6e 67 73 2f 66  and%20Settings/f
26a90 72 65 64 2f 44 65 73 6b 74 6f 70 2f 64 61 74 61  red/Desktop/data
26aa0 2e 64 62 0a 2a 2a 20 20 20 20 20 3c 74 64 3e 20  .db.**     <td> 
26ab0 57 69 6e 64 6f 77 73 20 6f 6e 6c 79 3a 20 4f 70  Windows only: Op
26ac0 65 6e 20 74 68 65 20 66 69 6c 65 20 22 64 61 74  en the file "dat
26ad0 61 2e 64 62 22 20 6f 6e 20 66 72 65 64 27 73 20  a.db" on fred's 
26ae0 64 65 73 6b 74 6f 70 20 6f 6e 20 64 72 69 76 65  desktop on drive
26af0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 43 3a 2e  .**          C:.
26b00 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 25   Note that the %
26b10 32 30 20 65 73 63 61 70 69 6e 67 20 69 6e 20 74  20 escaping in t
26b20 68 69 73 20 65 78 61 6d 70 6c 65 20 69 73 20 6e  his example is n
26b30 6f 74 20 73 74 72 69 63 74 6c 79 20 0a 2a 2a 20  ot strictly .** 
26b40 20 20 20 20 20 20 20 20 20 6e 65 63 65 73 73 61           necessa
26b50 72 79 20 2d 20 73 70 61 63 65 20 63 68 61 72 61  ry - space chara
26b60 63 74 65 72 73 20 63 61 6e 20 62 65 20 75 73 65  cters can be use
26b70 64 20 6c 69 74 65 72 61 6c 6c 79 0a 2a 2a 20 20  d literally.**  
26b80 20 20 20 20 20 20 20 20 69 6e 20 55 52 49 20 66          in URI f
26b90 69 6c 65 6e 61 6d 65 73 2e 0a 2a 2a 20 3c 74 72  ilenames..** <tr
26ba0 3e 3c 74 64 3e 20 66 69 6c 65 3a 64 61 74 61 2e  ><td> file:data.
26bb0 64 62 3f 6d 6f 64 65 3d 72 6f 26 63 61 63 68 65  db?mode=ro&cache
26bc0 3d 70 72 69 76 61 74 65 20 3c 74 64 3e 20 0a 2a  =private <td> .*
26bd0 2a 20 20 20 20 20 20 20 20 20 20 4f 70 65 6e 20  *          Open 
26be0 66 69 6c 65 20 22 64 61 74 61 2e 64 62 22 20 69  file "data.db" i
26bf0 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20 64 69  n the current di
26c00 72 65 63 74 6f 72 79 20 66 6f 72 20 72 65 61 64  rectory for read
26c10 2d 6f 6e 6c 79 20 61 63 63 65 73 73 2e 0a 2a 2a  -only access..**
26c20 20 20 20 20 20 20 20 20 20 20 52 65 67 61 72 64            Regard
26c30 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65 72 20  less of whether 
26c40 6f 72 20 6e 6f 74 20 73 68 61 72 65 64 2d 63 61  or not shared-ca
26c50 63 68 65 20 6d 6f 64 65 20 69 73 20 65 6e 61 62  che mode is enab
26c60 6c 65 64 20 62 79 0a 2a 2a 20 20 20 20 20 20 20  led by.**       
26c70 20 20 20 64 65 66 61 75 6c 74 2c 20 75 73 65 20     default, use 
26c80 61 20 70 72 69 76 61 74 65 20 63 61 63 68 65 2e  a private cache.
26c90 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c  .** <tr><td> fil
26ca0 65 3a 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74  e:/home/fred/dat
26cb0 61 2e 64 62 3f 76 66 73 3d 75 6e 69 78 2d 64 6f  a.db?vfs=unix-do
26cc0 74 66 69 6c 65 20 3c 74 64 3e 0a 2a 2a 20 20 20  tfile <td>.**   
26cd0 20 20 20 20 20 20 20 4f 70 65 6e 20 66 69 6c 65         Open file
26ce0 20 22 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74   "/home/fred/dat
26cf0 61 2e 64 62 22 2e 20 55 73 65 20 74 68 65 20 73  a.db". Use the s
26d00 70 65 63 69 61 6c 20 56 46 53 20 22 75 6e 69 78  pecial VFS "unix
26d10 2d 64 6f 74 66 69 6c 65 22 0a 2a 2a 20 20 20 20  -dotfile".**    
26d20 20 20 20 20 20 20 74 68 61 74 20 75 73 65 73 20        that uses 
26d30 64 6f 74 2d 66 69 6c 65 73 20 69 6e 20 70 6c 61  dot-files in pla
26d40 63 65 20 6f 66 20 70 6f 73 69 78 20 61 64 76 69  ce of posix advi
26d50 73 6f 72 79 20 6c 6f 63 6b 69 6e 67 2e 0a 2a 2a  sory locking..**
26d60 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 64   <tr><td> file:d
26d70 61 74 61 2e 64 62 3f 6d 6f 64 65 3d 72 65 61 64  ata.db?mode=read
26d80 6f 6e 6c 79 20 3c 74 64 3e 20 0a 2a 2a 20 20 20  only <td> .**   
26d90 20 20 20 20 20 20 20 41 6e 20 65 72 72 6f 72 2e         An error.
26da0 20 22 72 65 61 64 6f 6e 6c 79 22 20 69 73 20 6e   "readonly" is n
26db0 6f 74 20 61 20 76 61 6c 69 64 20 6f 70 74 69 6f  ot a valid optio
26dc0 6e 20 66 6f 72 20 74 68 65 20 22 6d 6f 64 65 22  n for the "mode"
26dd0 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 3c   parameter..** <
26de0 2f 74 61 62 6c 65 3e 0a 2a 2a 0a 2a 2a 20 5e 55  /table>.**.** ^U
26df0 52 49 20 68 65 78 61 64 65 63 69 6d 61 6c 20 65  RI hexadecimal e
26e00 73 63 61 70 65 20 73 65 71 75 65 6e 63 65 73 20  scape sequences 
26e10 28 25 48 48 29 20 61 72 65 20 73 75 70 70 6f 72  (%HH) are suppor
26e20 74 65 64 20 77 69 74 68 69 6e 20 74 68 65 20 70  ted within the p
26e30 61 74 68 20 61 6e 64 0a 2a 2a 20 71 75 65 72 79  ath and.** query
26e40 20 63 6f 6d 70 6f 6e 65 6e 74 73 20 6f 66 20 61   components of a
26e50 20 55 52 49 2e 20 41 20 68 65 78 61 64 65 63 69   URI. A hexadeci
26e60 6d 61 6c 20 65 73 63 61 70 65 20 73 65 71 75 65  mal escape seque
26e70 6e 63 65 20 63 6f 6e 73 69 73 74 73 20 6f 66 20  nce consists of 
26e80 61 0a 2a 2a 20 70 65 72 63 65 6e 74 20 73 69 67  a.** percent sig
26e90 6e 20 2d 20 22 25 22 20 2d 20 66 6f 6c 6c 6f 77  n - "%" - follow
26ea0 65 64 20 62 79 20 65 78 61 63 74 6c 79 20 74 77  ed by exactly tw
26eb0 6f 20 68 65 78 61 64 65 63 69 6d 61 6c 20 64 69  o hexadecimal di
26ec0 67 69 74 73 20 0a 2a 2a 20 73 70 65 63 69 66 79  gits .** specify
26ed0 69 6e 67 20 61 6e 20 6f 63 74 65 74 20 76 61 6c  ing an octet val
26ee0 75 65 2e 20 5e 42 65 66 6f 72 65 20 74 68 65 20  ue. ^Before the 
26ef0 70 61 74 68 20 6f 72 20 71 75 65 72 79 20 63 6f  path or query co
26f00 6d 70 6f 6e 65 6e 74 73 20 6f 66 20 61 0a 2a 2a  mponents of a.**
26f10 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 20 61 72   URI filename ar
26f20 65 20 69 6e 74 65 72 70 72 65 74 65 64 2c 20 74  e interpreted, t
26f30 68 65 79 20 61 72 65 20 65 6e 63 6f 64 65 64 20  hey are encoded 
26f40 75 73 69 6e 67 20 55 54 46 2d 38 20 61 6e 64 20  using UTF-8 and 
26f50 61 6c 6c 20 0a 2a 2a 20 68 65 78 61 64 65 63 69  all .** hexadeci
26f60 6d 61 6c 20 65 73 63 61 70 65 20 73 65 71 75 65  mal escape seque
26f70 6e 63 65 73 20 72 65 70 6c 61 63 65 64 20 62 79  nces replaced by
26f80 20 61 20 73 69 6e 67 6c 65 20 62 79 74 65 20 63   a single byte c
26f90 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 0a 2a 2a  ontaining the.**
26fa0 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 6f   corresponding o
26fb0 63 74 65 74 2e 20 49 66 20 74 68 69 73 20 70 72  ctet. If this pr
26fc0 6f 63 65 73 73 20 67 65 6e 65 72 61 74 65 73 20  ocess generates 
26fd0 61 6e 20 69 6e 76 61 6c 69 64 20 55 54 46 2d 38  an invalid UTF-8
26fe0 20 65 6e 63 6f 64 69 6e 67 2c 0a 2a 2a 20 74 68   encoding,.** th
26ff0 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e  e results are un
27000 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c  defined..**.** <
27010 62 3e 4e 6f 74 65 20 74 6f 20 57 69 6e 64 6f 77  b>Note to Window
27020 73 20 75 73 65 72 73 3a 3c 2f 62 3e 20 20 54 68  s users:</b>  Th
27030 65 20 65 6e 63 6f 64 69 6e 67 20 75 73 65 64 20  e encoding used 
27040 66 6f 72 20 74 68 65 20 66 69 6c 65 6e 61 6d 65  for the filename
27050 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 6f 66 20   argument.** of 
27060 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 61  sqlite3_open() a
27070 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  nd sqlite3_open_
27080 76 32 28 29 20 6d 75 73 74 20 62 65 20 55 54 46  v2() must be UTF
27090 2d 38 2c 20 6e 6f 74 20 77 68 61 74 65 76 65 72  -8, not whatever
270a0 0a 2a 2a 20 63 6f 64 65 70 61 67 65 20 69 73 20  .** codepage is 
270b0 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65  currently define
270c0 64 2e 20 20 46 69 6c 65 6e 61 6d 65 73 20 63 6f  d.  Filenames co
270d0 6e 74 61 69 6e 69 6e 67 20 69 6e 74 65 72 6e 61  ntaining interna
270e0 74 69 6f 6e 61 6c 0a 2a 2a 20 63 68 61 72 61 63  tional.** charac
270f0 74 65 72 73 20 6d 75 73 74 20 62 65 20 63 6f 6e  ters must be con
27100 76 65 72 74 65 64 20 74 6f 20 55 54 46 2d 38 20  verted to UTF-8 
27110 70 72 69 6f 72 20 74 6f 20 70 61 73 73 69 6e 67  prior to passing
27120 20 74 68 65 6d 20 69 6e 74 6f 0a 2a 2a 20 73 71   them into.** sq
27130 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20  lite3_open() or 
27140 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
27150 29 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74 65  )..**.** <b>Note
27160 20 74 6f 20 57 69 6e 64 6f 77 73 20 52 75 6e 74   to Windows Runt
27170 69 6d 65 20 75 73 65 72 73 3a 3c 2f 62 3e 20 20  ime users:</b>  
27180 54 68 65 20 74 65 6d 70 6f 72 61 72 79 20 64 69  The temporary di
27190 72 65 63 74 6f 72 79 20 6d 75 73 74 20 62 65 20  rectory must be 
271a0 73 65 74 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20  set.** prior to 
271b0 63 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f  calling sqlite3_
271c0 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c 69 74 65  open() or sqlite
271d0 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 20 4f 74  3_open_v2().  Ot
271e0 68 65 72 77 69 73 65 2c 20 76 61 72 69 6f 75 73  herwise, various
271f0 0a 2a 2a 20 66 65 61 74 75 72 65 73 20 74 68 61  .** features tha
27200 74 20 72 65 71 75 69 72 65 20 74 68 65 20 75 73  t require the us
27210 65 20 6f 66 20 74 65 6d 70 6f 72 61 72 79 20 66  e of temporary f
27220 69 6c 65 73 20 6d 61 79 20 66 61 69 6c 2e 0a 2a  iles may fail..*
27230 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b  *.** See also: [
27240 73 71 6c 69 74 65 33 5f 74 65 6d 70 5f 64 69 72  sqlite3_temp_dir
27250 65 63 74 6f 72 79 5d 0a 2a 2f 0a 69 6e 74 20 73  ectory].*/.int s
27260 71 6c 69 74 65 33 5f 6f 70 65 6e 28 0a 20 20 63  qlite3_open(.  c
27270 6f 6e 73 74 20 63 68 61 72 20 2a 66 69 6c 65 6e  onst char *filen
27280 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 61  ame,   /* Databa
27290 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 46  se filename (UTF
272a0 2d 38 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33  -8) */.  sqlite3
272b0 20 2a 2a 70 70 44 62 20 20 20 20 20 20 20 20 20   **ppDb         
272c0 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 20   /* OUT: SQLite 
272d0 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a  db handle */.);.
272e0 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  int sqlite3_open
272f0 31 36 28 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64  16(.  const void
27300 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a   *filename,   /*
27310 20 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61   Database filena
27320 6d 65 20 28 55 54 46 2d 31 36 29 20 2a 2f 0a 20  me (UTF-16) */. 
27330 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 20   sqlite3 **ppDb 
27340 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a           /* OUT:
27350 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c   SQLite db handl
27360 65 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69  e */.);.int sqli
27370 74 65 33 5f 6f 70 65 6e 5f 76 32 28 0a 20 20 63  te3_open_v2(.  c
27380 6f 6e 73 74 20 63 68 61 72 20 2a 66 69 6c 65 6e  onst char *filen
27390 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 61  ame,   /* Databa
273a0 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 46  se filename (UTF
273b0 2d 38 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33  -8) */.  sqlite3
273c0 20 2a 2a 70 70 44 62 2c 20 20 20 20 20 20 20 20   **ppDb,        
273d0 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 20   /* OUT: SQLite 
273e0 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 69  db handle */.  i
273f0 6e 74 20 66 6c 61 67 73 2c 20 20 20 20 20 20 20  nt flags,       
27400 20 20 20 20 20 20 20 2f 2a 20 46 6c 61 67 73 20         /* Flags 
27410 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  */.  const char 
27420 2a 7a 56 66 73 20 20 20 20 20 20 20 20 2f 2a 20  *zVfs        /* 
27430 4e 61 6d 65 20 6f 66 20 56 46 53 20 6d 6f 64 75  Name of VFS modu
27440 6c 65 20 74 6f 20 75 73 65 20 2a 2f 0a 29 3b 0a  le to use */.);.
27450 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
27460 20 4f 62 74 61 69 6e 20 56 61 6c 75 65 73 20 46   Obtain Values F
27470 6f 72 20 55 52 49 20 50 61 72 61 6d 65 74 65 72  or URI Parameter
27480 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61 72  s.**.** These ar
27490 65 20 75 74 69 6c 69 74 79 20 72 6f 75 74 69 6e  e utility routin
274a0 65 73 2c 20 75 73 65 66 75 6c 20 74 6f 20 56 46  es, useful to VF
274b0 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  S implementation
274c0 73 2c 20 74 68 61 74 20 63 68 65 63 6b 0a 2a 2a  s, that check.**
274d0 20 74 6f 20 73 65 65 20 69 66 20 61 20 64 61 74   to see if a dat
274e0 61 62 61 73 65 20 66 69 6c 65 20 77 61 73 20 61  abase file was a
274f0 20 55 52 49 20 74 68 61 74 20 63 6f 6e 74 61 69   URI that contai
27500 6e 65 64 20 61 20 73 70 65 63 69 66 69 63 20 71  ned a specific q
27510 75 65 72 79 20 0a 2a 2a 20 70 61 72 61 6d 65 74  uery .** paramet
27520 65 72 2c 20 61 6e 64 20 69 66 20 73 6f 20 6f 62  er, and if so ob
27530 74 61 69 6e 73 20 74 68 65 20 76 61 6c 75 65 20  tains the value 
27540 6f 66 20 74 68 61 74 20 71 75 65 72 79 20 70 61  of that query pa
27550 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 49  rameter..**.** I
27560 66 20 46 20 69 73 20 74 68 65 20 64 61 74 61 62  f F is the datab
27570 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 70 6f 69  ase filename poi
27580 6e 74 65 72 20 70 61 73 73 65 64 20 69 6e 74 6f  nter passed into
27590 20 74 68 65 20 78 4f 70 65 6e 28 29 20 6d 65 74   the xOpen() met
275a0 68 6f 64 20 6f 66 20 0a 2a 2a 20 61 20 56 46 53  hod of .** a VFS
275b0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
275c0 77 68 65 6e 20 74 68 65 20 66 6c 61 67 73 20 70  when the flags p
275d0 61 72 61 6d 65 74 65 72 20 74 6f 20 78 4f 70 65  arameter to xOpe
275e0 6e 28 29 20 68 61 73 20 6f 6e 65 20 6f 72 20 0a  n() has one or .
275f0 2a 2a 20 6d 6f 72 65 20 6f 66 20 74 68 65 20 5b  ** more of the [
27600 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d  SQLITE_OPEN_URI]
27610 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e   or [SQLITE_OPEN
27620 5f 4d 41 49 4e 5f 44 42 5d 20 62 69 74 73 20 73  _MAIN_DB] bits s
27630 65 74 20 61 6e 64 0a 2a 2a 20 50 20 69 73 20 74  et and.** P is t
27640 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 71  he name of the q
27650 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 2c 20  uery parameter, 
27660 74 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  then.** sqlite3_
27670 75 72 69 5f 70 61 72 61 6d 65 74 65 72 28 46 2c  uri_parameter(F,
27680 50 29 20 72 65 74 75 72 6e 73 20 74 68 65 20 76  P) returns the v
27690 61 6c 75 65 20 6f 66 20 74 68 65 20 50 0a 2a 2a  alue of the P.**
276a0 20 70 61 72 61 6d 65 74 65 72 20 69 66 20 69 74   parameter if it
276b0 20 65 78 69 73 74 73 20 6f 72 20 61 20 4e 55 4c   exists or a NUL
276c0 4c 20 70 6f 69 6e 74 65 72 20 69 66 20 50 20 64  L pointer if P d
276d0 6f 65 73 20 6e 6f 74 20 61 70 70 65 61 72 20 61  oes not appear a
276e0 73 20 61 20 0a 2a 2a 20 71 75 65 72 79 20 70 61  s a .** query pa
276f0 72 61 6d 65 74 65 72 20 6f 6e 20 46 2e 20 20 49  rameter on F.  I
27700 66 20 50 20 69 73 20 61 20 71 75 65 72 79 20 70  f P is a query p
27710 61 72 61 6d 65 74 65 72 20 6f 66 20 46 0a 2a 2a  arameter of F.**
27720 20 68 61 73 20 6e 6f 20 65 78 70 6c 69 63 69 74   has no explicit
27730 20 76 61 6c 75 65 2c 20 74 68 65 6e 20 73 71 6c   value, then sql
27740 69 74 65 33 5f 75 72 69 5f 70 61 72 61 6d 65 74  ite3_uri_paramet
27750 65 72 28 46 2c 50 29 20 72 65 74 75 72 6e 73 0a  er(F,P) returns.
27760 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ** a pointer to 
27770 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 2e  an empty string.
27780 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
27790 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46  e3_uri_boolean(F
277a0 2c 50 2c 42 29 20 72 6f 75 74 69 6e 65 20 61 73  ,P,B) routine as
277b0 73 75 6d 65 73 20 74 68 61 74 20 50 20 69 73 20  sumes that P is 
277c0 61 20 62 6f 6f 6c 65 61 6e 0a 2a 2a 20 70 61 72  a boolean.** par
277d0 61 6d 65 74 65 72 20 61 6e 64 20 72 65 74 75 72  ameter and retur
277e0 6e 73 20 74 72 75 65 20 28 31 29 20 6f 72 20 66  ns true (1) or f
277f0 61 6c 73 65 20 28 30 29 20 61 63 63 6f 72 64 69  alse (0) accordi
27800 6e 67 20 74 6f 20 74 68 65 20 76 61 6c 75 65 0a  ng to the value.
27810 2a 2a 20 6f 66 20 50 2e 20 20 54 68 65 20 73 71  ** of P.  The sq
27820 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61  lite3_uri_boolea
27830 6e 28 46 2c 50 2c 42 29 20 72 6f 75 74 69 6e 65  n(F,P,B) routine
27840 20 72 65 74 75 72 6e 73 20 74 72 75 65 20 28 31   returns true (1
27850 29 20 69 66 20 74 68 65 0a 2a 2a 20 76 61 6c 75  ) if the.** valu
27860 65 20 6f 66 20 71 75 65 72 79 20 70 61 72 61 6d  e of query param
27870 65 74 65 72 20 50 20 69 73 20 6f 6e 65 20 6f 66  eter P is one of
27880 20 22 79 65 73 22 2c 20 22 74 72 75 65 22 2c 20   "yes", "true", 
27890 6f 72 20 22 6f 6e 22 20 69 6e 20 61 6e 79 0a 2a  or "on" in any.*
278a0 2a 20 63 61 73 65 20 6f 72 20 69 66 20 74 68 65  * case or if the
278b0 20 76 61 6c 75 65 20 62 65 67 69 6e 73 20 77 69   value begins wi
278c0 74 68 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 6e 75  th a non-zero nu
278d0 6d 62 65 72 2e 20 20 54 68 65 20 0a 2a 2a 20 73  mber.  The .** s
278e0 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65  qlite3_uri_boole
278f0 61 6e 28 46 2c 50 2c 42 29 20 72 6f 75 74 69 6e  an(F,P,B) routin
27900 65 73 20 72 65 74 75 72 6e 73 20 66 61 6c 73 65  es returns false
27910 20 28 30 29 20 69 66 20 74 68 65 20 76 61 6c 75   (0) if the valu
27920 65 20 6f 66 0a 2a 2a 20 71 75 65 72 79 20 70 61  e of.** query pa
27930 72 61 6d 65 74 65 72 20 50 20 69 73 20 6f 6e 65  rameter P is one
27940 20 6f 66 20 22 6e 6f 22 2c 20 22 66 61 6c 73 65   of "no", "false
27950 22 2c 20 6f 72 20 22 6f 66 66 22 20 69 6e 20 61  ", or "off" in a
27960 6e 79 20 63 61 73 65 20 6f 72 0a 2a 2a 20 69 66  ny case or.** if
27970 20 74 68 65 20 76 61 6c 75 65 20 62 65 67 69 6e   the value begin
27980 73 20 77 69 74 68 20 61 20 6e 75 6d 65 72 69 63  s with a numeric
27990 20 7a 65 72 6f 2e 20 20 49 66 20 50 20 69 73 20   zero.  If P is 
279a0 6e 6f 74 20 61 20 71 75 65 72 79 0a 2a 2a 20 70  not a query.** p
279b0 61 72 61 6d 65 74 65 72 20 6f 6e 20 46 20 6f 72  arameter on F or
279c0 20 69 66 20 74 68 65 20 76 61 6c 75 65 20 6f 66   if the value of
279d0 20 50 20 69 73 20 64 6f 65 73 20 6e 6f 74 20 6d   P is does not m
279e0 61 74 63 68 20 61 6e 79 20 6f 66 20 74 68 65 0a  atch any of the.
279f0 2a 2a 20 61 62 6f 76 65 2c 20 74 68 65 6e 20 73  ** above, then s
27a00 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65  qlite3_uri_boole
27a10 61 6e 28 46 2c 50 2c 42 29 20 72 65 74 75 72 6e  an(F,P,B) return
27a20 73 20 28 42 21 3d 30 29 2e 0a 2a 2a 0a 2a 2a 20  s (B!=0)..**.** 
27a30 54 68 65 20 73 71 6c 69 74 65 33 5f 75 72 69 5f  The sqlite3_uri_
27a40 69 6e 74 36 34 28 46 2c 50 2c 44 29 20 72 6f 75  int64(F,P,D) rou
27a50 74 69 6e 65 20 63 6f 6e 76 65 72 74 73 20 74 68  tine converts th
27a60 65 20 76 61 6c 75 65 20 6f 66 20 50 20 69 6e 74  e value of P int
27a70 6f 20 61 0a 2a 2a 20 36 34 2d 62 69 74 20 73 69  o a.** 64-bit si
27a80 67 6e 65 64 20 69 6e 74 65 67 65 72 20 61 6e 64  gned integer and
27a90 20 72 65 74 75 72 6e 73 20 74 68 61 74 20 69 6e   returns that in
27aa0 74 65 67 65 72 2c 20 6f 72 20 44 20 69 66 20 50  teger, or D if P
27ab0 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 65 78 69   does not.** exi
27ac0 73 74 2e 20 20 49 66 20 74 68 65 20 76 61 6c 75  st.  If the valu
27ad0 65 20 6f 66 20 50 20 69 73 20 73 6f 6d 65 74 68  e of P is someth
27ae0 69 6e 67 20 6f 74 68 65 72 20 74 68 61 6e 20 61  ing other than a
27af0 6e 20 69 6e 74 65 67 65 72 2c 20 74 68 65 6e 0a  n integer, then.
27b00 2a 2a 20 7a 65 72 6f 20 69 73 20 72 65 74 75 72  ** zero is retur
27b10 6e 65 64 2e 0a 2a 2a 20 0a 2a 2a 20 49 66 20 46  ned..** .** If F
27b20 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
27b30 65 72 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33  er, then sqlite3
27b40 5f 75 72 69 5f 70 61 72 61 6d 65 74 65 72 28 46  _uri_parameter(F
27b50 2c 50 29 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c  ,P) returns NULL
27b60 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   and.** sqlite3_
27b70 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c  uri_boolean(F,P,
27b80 42 29 20 72 65 74 75 72 6e 73 20 42 2e 20 20 49  B) returns B.  I
27b90 66 20 46 20 69 73 20 6e 6f 74 20 61 20 4e 55 4c  f F is not a NUL
27ba0 4c 20 70 6f 69 6e 74 65 72 20 61 6e 64 0a 2a 2a  L pointer and.**
27bb0 20 69 73 20 6e 6f 74 20 61 20 64 61 74 61 62 61   is not a databa
27bc0 73 65 20 66 69 6c 65 20 70 61 74 68 6e 61 6d 65  se file pathname
27bd0 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20 53 51   pointer that SQ
27be0 4c 69 74 65 20 70 61 73 73 65 64 20 69 6e 74 6f  Lite passed into
27bf0 20 74 68 65 20 78 4f 70 65 6e 0a 2a 2a 20 56 46   the xOpen.** VF
27c00 53 20 6d 65 74 68 6f 64 2c 20 74 68 65 6e 20 74  S method, then t
27c10 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20 74  he behavior of t
27c20 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 75  his routine is u
27c30 6e 64 65 66 69 6e 65 64 20 61 6e 64 20 70 72 6f  ndefined and pro
27c40 62 61 62 6c 79 0a 2a 2a 20 75 6e 64 65 73 69 72  bably.** undesir
27c50 61 62 6c 65 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63  able..*/.const c
27c60 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 75 72 69  har *sqlite3_uri
27c70 5f 70 61 72 61 6d 65 74 65 72 28 63 6f 6e 73 74  _parameter(const
27c80 20 63 68 61 72 20 2a 7a 46 69 6c 65 6e 61 6d 65   char *zFilename
27c90 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 50  , const char *zP
27ca0 61 72 61 6d 29 3b 0a 69 6e 74 20 73 71 6c 69 74  aram);.int sqlit
27cb0 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 63  e3_uri_boolean(c
27cc0 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c 65  onst char *zFile
27cd0 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 50  , const char *zP
27ce0 61 72 61 6d 2c 20 69 6e 74 20 62 44 65 66 61 75  aram, int bDefau
27cf0 6c 74 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74  lt);.sqlite3_int
27d00 36 34 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 69  64 sqlite3_uri_i
27d10 6e 74 36 34 28 63 6f 6e 73 74 20 63 68 61 72 2a  nt64(const char*
27d20 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 73  , const char*, s
27d30 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 0a  qlite3_int64);..
27d40 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
27d50 20 45 72 72 6f 72 20 43 6f 64 65 73 20 41 6e 64   Error Codes And
27d60 20 4d 65 73 73 61 67 65 73 0a 2a 2a 20 4d 45 54   Messages.** MET
27d70 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a  HOD: sqlite3.**.
27d80 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20  ** ^If the most 
27d90 72 65 63 65 6e 74 20 73 71 6c 69 74 65 33 5f 2a  recent sqlite3_*
27da0 20 41 50 49 20 63 61 6c 6c 20 61 73 73 6f 63 69   API call associ
27db0 61 74 65 64 20 77 69 74 68 20 0a 2a 2a 20 5b 64  ated with .** [d
27dc0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
27dd0 6f 6e 5d 20 44 20 66 61 69 6c 65 64 2c 20 74 68  on] D failed, th
27de0 65 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 65  en the sqlite3_e
27df0 72 72 63 6f 64 65 28 44 29 20 69 6e 74 65 72 66  rrcode(D) interf
27e00 61 63 65 0a 2a 2a 20 72 65 74 75 72 6e 73 20 74  ace.** returns t
27e10 68 65 20 6e 75 6d 65 72 69 63 20 5b 72 65 73 75  he numeric [resu
27e20 6c 74 20 63 6f 64 65 5d 20 6f 72 20 5b 65 78 74  lt code] or [ext
27e30 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
27e40 65 5d 20 66 6f 72 20 74 68 61 74 0a 2a 2a 20 41  e] for that.** A
27e50 50 49 20 63 61 6c 6c 2e 0a 2a 2a 20 49 66 20 74  PI call..** If t
27e60 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 41  he most recent A
27e70 50 49 20 63 61 6c 6c 20 77 61 73 20 73 75 63 63  PI call was succ
27e80 65 73 73 66 75 6c 2c 0a 2a 2a 20 74 68 65 6e 20  essful,.** then 
27e90 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  the return value
27ea0 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 65 72   from sqlite3_er
27eb0 72 63 6f 64 65 28 29 20 69 73 20 75 6e 64 65 66  rcode() is undef
27ec0 69 6e 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 73 71  ined..** ^The sq
27ed0 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 65  lite3_extended_e
27ee0 72 72 63 6f 64 65 28 29 0a 2a 2a 20 69 6e 74 65  rrcode().** inte
27ef0 72 66 61 63 65 20 69 73 20 74 68 65 20 73 61 6d  rface is the sam
27f00 65 20 65 78 63 65 70 74 20 74 68 61 74 20 69 74  e except that it
27f10 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20   always returns 
27f20 74 68 65 20 0a 2a 2a 20 5b 65 78 74 65 6e 64 65  the .** [extende
27f30 64 20 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 65  d result code] e
27f40 76 65 6e 20 77 68 65 6e 20 65 78 74 65 6e 64 65  ven when extende
27f50 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61  d result codes a
27f60 72 65 0a 2a 2a 20 64 69 73 61 62 6c 65 64 2e 0a  re.** disabled..
27f70 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
27f80 65 33 5f 65 72 72 6d 73 67 28 29 20 61 6e 64 20  e3_errmsg() and 
27f90 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36  sqlite3_errmsg16
27fa0 28 29 20 72 65 74 75 72 6e 20 45 6e 67 6c 69 73  () return Englis
27fb0 68 2d 6c 61 6e 67 75 61 67 65 0a 2a 2a 20 74 65  h-language.** te
27fc0 78 74 20 74 68 61 74 20 64 65 73 63 72 69 62 65  xt that describe
27fd0 73 20 74 68 65 20 65 72 72 6f 72 2c 20 61 73 20  s the error, as 
27fe0 65 69 74 68 65 72 20 55 54 46 2d 38 20 6f 72 20  either UTF-8 or 
27ff0 55 54 46 2d 31 36 20 72 65 73 70 65 63 74 69 76  UTF-16 respectiv
28000 65 6c 79 2e 0a 2a 2a 20 5e 28 4d 65 6d 6f 72 79  ely..** ^(Memory
28010 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 65 72 72   to hold the err
28020 6f 72 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e  or message strin
28030 67 20 69 73 20 6d 61 6e 61 67 65 64 20 69 6e 74  g is managed int
28040 65 72 6e 61 6c 6c 79 2e 0a 2a 2a 20 54 68 65 20  ernally..** The 
28050 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 6f 65 73  application does
28060 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 77 6f 72   not need to wor
28070 72 79 20 61 62 6f 75 74 20 66 72 65 65 69 6e 67  ry about freeing
28080 20 74 68 65 20 72 65 73 75 6c 74 2e 0a 2a 2a 20   the result..** 
28090 48 6f 77 65 76 65 72 2c 20 74 68 65 20 65 72 72  However, the err
280a0 6f 72 20 73 74 72 69 6e 67 20 6d 69 67 68 74 20  or string might 
280b0 62 65 20 6f 76 65 72 77 72 69 74 74 65 6e 20 6f  be overwritten o
280c0 72 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 62 79  r deallocated by
280d0 0a 2a 2a 20 73 75 62 73 65 71 75 65 6e 74 20 63  .** subsequent c
280e0 61 6c 6c 73 20 74 6f 20 6f 74 68 65 72 20 53 51  alls to other SQ
280f0 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 20 66  Lite interface f
28100 75 6e 63 74 69 6f 6e 73 2e 29 5e 0a 2a 2a 0a 2a  unctions.)^.**.*
28110 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65  * ^The sqlite3_e
28120 72 72 73 74 72 28 29 20 69 6e 74 65 72 66 61 63  rrstr() interfac
28130 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 45 6e  e returns the En
28140 67 6c 69 73 68 2d 6c 61 6e 67 75 61 67 65 20 74  glish-language t
28150 65 78 74 0a 2a 2a 20 74 68 61 74 20 64 65 73 63  ext.** that desc
28160 72 69 62 65 73 20 74 68 65 20 5b 72 65 73 75 6c  ribes the [resul
28170 74 20 63 6f 64 65 5d 2c 20 61 73 20 55 54 46 2d  t code], as UTF-
28180 38 2e 0a 2a 2a 20 5e 28 4d 65 6d 6f 72 79 20 74  8..** ^(Memory t
28190 6f 20 68 6f 6c 64 20 74 68 65 20 65 72 72 6f 72  o hold the error
281a0 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67 20   message string 
281b0 69 73 20 6d 61 6e 61 67 65 64 20 69 6e 74 65 72  is managed inter
281c0 6e 61 6c 6c 79 0a 2a 2a 20 61 6e 64 20 6d 75 73  nally.** and mus
281d0 74 20 6e 6f 74 20 62 65 20 66 72 65 65 64 20 62  t not be freed b
281e0 79 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  y the applicatio
281f0 6e 29 5e 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20  n)^..**.** When 
28200 74 68 65 20 73 65 72 69 61 6c 69 7a 65 64 20 5b  the serialized [
28210 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20  threading mode] 
28220 69 73 20 69 6e 20 75 73 65 2c 20 69 74 20 6d 69  is in use, it mi
28230 67 68 74 20 62 65 20 74 68 65 0a 2a 2a 20 63 61  ght be the.** ca
28240 73 65 20 74 68 61 74 20 61 20 73 65 63 6f 6e 64  se that a second
28250 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 6f 6e   error occurs on
28260 20 61 20 73 65 70 61 72 61 74 65 20 74 68 72 65   a separate thre
28270 61 64 20 69 6e 20 62 65 74 77 65 65 6e 0a 2a 2a  ad in between.**
28280 20 74 68 65 20 74 69 6d 65 20 6f 66 20 74 68 65   the time of the
28290 20 66 69 72 73 74 20 65 72 72 6f 72 20 61 6e 64   first error and
282a0 20 74 68 65 20 63 61 6c 6c 20 74 6f 20 74 68 65   the call to the
282b0 73 65 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a  se interfaces..*
282c0 2a 20 57 68 65 6e 20 74 68 61 74 20 68 61 70 70  * When that happ
282d0 65 6e 73 2c 20 74 68 65 20 73 65 63 6f 6e 64 20  ens, the second 
282e0 65 72 72 6f 72 20 77 69 6c 6c 20 62 65 20 72 65  error will be re
282f0 70 6f 72 74 65 64 20 73 69 6e 63 65 20 74 68 65  ported since the
28300 73 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73  se.** interfaces
28310 20 61 6c 77 61 79 73 20 72 65 70 6f 72 74 20 74   always report t
28320 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 72  he most recent r
28330 65 73 75 6c 74 2e 20 20 54 6f 20 61 76 6f 69 64  esult.  To avoid
28340 0a 2a 2a 20 74 68 69 73 2c 20 65 61 63 68 20 74  .** this, each t
28350 68 72 65 61 64 20 63 61 6e 20 6f 62 74 61 69 6e  hread can obtain
28360 20 65 78 63 6c 75 73 69 76 65 20 75 73 65 20 6f   exclusive use o
28370 66 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  f the [database 
28380 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 0a 2a 2a  connection] D.**
28390 20 62 79 20 69 6e 76 6f 6b 69 6e 67 20 5b 73 71   by invoking [sq
283a0 6c 69 74 65 33 5f 6d 75 74 65 78 5f 65 6e 74 65  lite3_mutex_ente
283b0 72 5d 28 5b 73 71 6c 69 74 65 33 5f 64 62 5f 6d  r]([sqlite3_db_m
283c0 75 74 65 78 5d 28 44 29 29 20 62 65 66 6f 72 65  utex](D)) before
283d0 20 62 65 67 69 6e 6e 69 6e 67 0a 2a 2a 20 74 6f   beginning.** to
283e0 20 75 73 65 20 44 20 61 6e 64 20 69 6e 76 6f 6b   use D and invok
283f0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74  ing [sqlite3_mut
28400 65 78 5f 6c 65 61 76 65 5d 28 5b 73 71 6c 69 74  ex_leave]([sqlit
28410 65 33 5f 64 62 5f 6d 75 74 65 78 5d 28 44 29 29  e3_db_mutex](D))
28420 20 61 66 74 65 72 0a 2a 2a 20 61 6c 6c 20 63 61   after.** all ca
28430 6c 6c 73 20 74 6f 20 74 68 65 20 69 6e 74 65 72  lls to the inter
28440 66 61 63 65 73 20 6c 69 73 74 65 64 20 68 65 72  faces listed her
28450 65 20 61 72 65 20 63 6f 6d 70 6c 65 74 65 64 2e  e are completed.
28460 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 20 69 6e 74  .**.** If an int
28470 65 72 66 61 63 65 20 66 61 69 6c 73 20 77 69 74  erface fails wit
28480 68 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 2c  h SQLITE_MISUSE,
28490 20 74 68 61 74 20 6d 65 61 6e 73 20 74 68 65 20   that means the 
284a0 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 77 61 73  interface.** was
284b0 20 69 6e 76 6f 6b 65 64 20 69 6e 63 6f 72 72 65   invoked incorre
284c0 63 74 6c 79 20 62 79 20 74 68 65 20 61 70 70 6c  ctly by the appl
284d0 69 63 61 74 69 6f 6e 2e 20 20 49 6e 20 74 68 61  ication.  In tha
284e0 74 20 63 61 73 65 2c 20 74 68 65 0a 2a 2a 20 65  t case, the.** e
284f0 72 72 6f 72 20 63 6f 64 65 20 61 6e 64 20 6d 65  rror code and me
28500 73 73 61 67 65 20 6d 61 79 20 6f 72 20 6d 61 79  ssage may or may
28510 20 6e 6f 74 20 62 65 20 73 65 74 2e 0a 2a 2f 0a   not be set..*/.
28520 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 72 72 63  int sqlite3_errc
28530 6f 64 65 28 73 71 6c 69 74 65 33 20 2a 64 62 29  ode(sqlite3 *db)
28540 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78  ;.int sqlite3_ex
28550 74 65 6e 64 65 64 5f 65 72 72 63 6f 64 65 28 73  tended_errcode(s
28560 71 6c 69 74 65 33 20 2a 64 62 29 3b 0a 63 6f 6e  qlite3 *db);.con
28570 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
28580 5f 65 72 72 6d 73 67 28 73 71 6c 69 74 65 33 2a  _errmsg(sqlite3*
28590 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  );.const void *s
285a0 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28  qlite3_errmsg16(
285b0 73 71 6c 69 74 65 33 2a 29 3b 0a 63 6f 6e 73 74  sqlite3*);.const
285c0 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 65   char *sqlite3_e
285d0 72 72 73 74 72 28 69 6e 74 29 3b 0a 0a 2f 2a 0a  rrstr(int);../*.
285e0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 50 72 65  ** CAPI3REF: Pre
285f0 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20  pared Statement 
28600 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45 59 57 4f 52  Object.** KEYWOR
28610 44 53 3a 20 7b 70 72 65 70 61 72 65 64 20 73 74  DS: {prepared st
28620 61 74 65 6d 65 6e 74 7d 20 7b 70 72 65 70 61 72  atement} {prepar
28630 65 64 20 73 74 61 74 65 6d 65 6e 74 73 7d 0a 2a  ed statements}.*
28640 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65  *.** An instance
28650 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20   of this object 
28660 72 65 70 72 65 73 65 6e 74 73 20 61 20 73 69 6e  represents a sin
28670 67 6c 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  gle SQL statemen
28680 74 20 74 68 61 74 0a 2a 2a 20 68 61 73 20 62 65  t that.** has be
28690 65 6e 20 63 6f 6d 70 69 6c 65 64 20 69 6e 74 6f  en compiled into
286a0 20 62 69 6e 61 72 79 20 66 6f 72 6d 20 61 6e 64   binary form and
286b0 20 69 73 20 72 65 61 64 79 20 74 6f 20 62 65 20   is ready to be 
286c0 65 76 61 6c 75 61 74 65 64 2e 0a 2a 2a 0a 2a 2a  evaluated..**.**
286d0 20 54 68 69 6e 6b 20 6f 66 20 65 61 63 68 20 53   Think of each S
286e0 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 61 73 20  QL statement as 
286f0 61 20 73 65 70 61 72 61 74 65 20 63 6f 6d 70 75  a separate compu
28700 74 65 72 20 70 72 6f 67 72 61 6d 2e 20 20 54 68  ter program.  Th
28710 65 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 20 53 51  e.** original SQ
28720 4c 20 74 65 78 74 20 69 73 20 73 6f 75 72 63 65  L text is source
28730 20 63 6f 64 65 2e 20 20 41 20 70 72 65 70 61 72   code.  A prepar
28740 65 64 20 73 74 61 74 65 6d 65 6e 74 20 6f 62 6a  ed statement obj
28750 65 63 74 20 0a 2a 2a 20 69 73 20 74 68 65 20 63  ect .** is the c
28760 6f 6d 70 69 6c 65 64 20 6f 62 6a 65 63 74 20 63  ompiled object c
28770 6f 64 65 2e 20 20 41 6c 6c 20 53 51 4c 20 6d 75  ode.  All SQL mu
28780 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64 20  st be converted 
28790 69 6e 74 6f 20 61 0a 2a 2a 20 70 72 65 70 61 72  into a.** prepar
287a0 65 64 20 73 74 61 74 65 6d 65 6e 74 20 62 65 66  ed statement bef
287b0 6f 72 65 20 69 74 20 63 61 6e 20 62 65 20 72 75  ore it can be ru
287c0 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6c 69 66  n..**.** The lif
287d0 65 2d 63 79 63 6c 65 20 6f 66 20 61 20 70 72 65  e-cycle of a pre
287e0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20  pared statement 
287f0 6f 62 6a 65 63 74 20 75 73 75 61 6c 6c 79 20 67  object usually g
28800 6f 65 73 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a  oes like this:.*
28810 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ol>.** <li
28820 3e 20 43 72 65 61 74 65 20 74 68 65 20 70 72 65  > Create the pre
28830 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20  pared statement 
28840 6f 62 6a 65 63 74 20 75 73 69 6e 67 20 5b 73 71  object using [sq
28850 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
28860 28 29 5d 2e 0a 2a 2a 20 3c 6c 69 3e 20 42 69 6e  ()]..** <li> Bin
28870 64 20 76 61 6c 75 65 73 20 74 6f 20 5b 70 61 72  d values to [par
28880 61 6d 65 74 65 72 73 5d 20 75 73 69 6e 67 20 74  ameters] using t
28890 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  he sqlite3_bind_
288a0 2a 28 29 0a 2a 2a 20 20 20 20 20 20 69 6e 74 65  *().**      inte
288b0 72 66 61 63 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20  rfaces..** <li> 
288c0 52 75 6e 20 74 68 65 20 53 51 4c 20 62 79 20 63  Run the SQL by c
288d0 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  alling [sqlite3_
288e0 73 74 65 70 28 29 5d 20 6f 6e 65 20 6f 72 20 6d  step()] one or m
288f0 6f 72 65 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c  ore times..** <l
28900 69 3e 20 52 65 73 65 74 20 74 68 65 20 70 72 65  i> Reset the pre
28910 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20  pared statement 
28920 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72  using [sqlite3_r
28930 65 73 65 74 28 29 5d 20 74 68 65 6e 20 67 6f 20  eset()] then go 
28940 62 61 63 6b 0a 2a 2a 20 20 20 20 20 20 74 6f 20  back.**      to 
28950 73 74 65 70 20 32 2e 20 20 44 6f 20 74 68 69 73  step 2.  Do this
28960 20 7a 65 72 6f 20 6f 72 20 6d 6f 72 65 20 74 69   zero or more ti
28970 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 44 65 73  mes..** <li> Des
28980 74 72 6f 79 20 74 68 65 20 6f 62 6a 65 63 74 20  troy the object 
28990 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66  using [sqlite3_f
289a0 69 6e 61 6c 69 7a 65 28 29 5d 2e 0a 2a 2a 20 3c  inalize()]..** <
289b0 2f 6f 6c 3e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  /ol>.*/.typedef 
289c0 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 73  struct sqlite3_s
289d0 74 6d 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  tmt sqlite3_stmt
289e0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
289f0 46 3a 20 52 75 6e 2d 74 69 6d 65 20 4c 69 6d 69  F: Run-time Limi
28a00 74 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  ts.** METHOD: sq
28a10 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  lite3.**.** ^(Th
28a20 69 73 20 69 6e 74 65 72 66 61 63 65 20 61 6c 6c  is interface all
28a30 6f 77 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20  ows the size of 
28a40 76 61 72 69 6f 75 73 20 63 6f 6e 73 74 72 75 63  various construc
28a50 74 73 20 74 6f 20 62 65 20 6c 69 6d 69 74 65 64  ts to be limited
28a60 0a 2a 2a 20 6f 6e 20 61 20 63 6f 6e 6e 65 63 74  .** on a connect
28a70 69 6f 6e 20 62 79 20 63 6f 6e 6e 65 63 74 69 6f  ion by connectio
28a80 6e 20 62 61 73 69 73 2e 20 20 54 68 65 20 66 69  n basis.  The fi
28a90 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73  rst parameter is
28aa0 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73   the.** [databas
28ab0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 77 68  e connection] wh
28ac0 6f 73 65 20 6c 69 6d 69 74 20 69 73 20 74 6f 20  ose limit is to 
28ad0 62 65 20 73 65 74 20 6f 72 20 71 75 65 72 69 65  be set or querie
28ae0 64 2e 20 20 54 68 65 0a 2a 2a 20 73 65 63 6f 6e  d.  The.** secon
28af0 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 6f  d parameter is o
28b00 6e 65 20 6f 66 20 74 68 65 20 5b 6c 69 6d 69 74  ne of the [limit
28b10 20 63 61 74 65 67 6f 72 69 65 73 5d 20 74 68 61   categories] tha
28b20 74 20 64 65 66 69 6e 65 20 61 0a 2a 2a 20 63 6c  t define a.** cl
28b30 61 73 73 20 6f 66 20 63 6f 6e 73 74 72 75 63 74  ass of construct
28b40 73 20 74 6f 20 62 65 20 73 69 7a 65 20 6c 69 6d  s to be size lim
28b50 69 74 65 64 2e 20 20 54 68 65 20 74 68 69 72 64  ited.  The third
28b60 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68   parameter is th
28b70 65 0a 2a 2a 20 6e 65 77 20 6c 69 6d 69 74 20 66  e.** new limit f
28b80 6f 72 20 74 68 61 74 20 63 6f 6e 73 74 72 75 63  or that construc
28b90 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  t.)^.**.** ^If t
28ba0 68 65 20 6e 65 77 20 6c 69 6d 69 74 20 69 73 20  he new limit is 
28bb0 61 20 6e 65 67 61 74 69 76 65 20 6e 75 6d 62 65  a negative numbe
28bc0 72 2c 20 74 68 65 20 6c 69 6d 69 74 20 69 73 20  r, the limit is 
28bd0 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 20 5e 28  unchanged..** ^(
28be0 46 6f 72 20 65 61 63 68 20 6c 69 6d 69 74 20 63  For each limit c
28bf0 61 74 65 67 6f 72 79 20 53 51 4c 49 54 45 5f 4c  ategory SQLITE_L
28c00 49 4d 49 54 5f 3c 69 3e 4e 41 4d 45 3c 2f 69 3e  IMIT_<i>NAME</i>
28c10 20 74 68 65 72 65 20 69 73 20 61 20 0a 2a 2a 20   there is a .** 
28c20 5b 6c 69 6d 69 74 73 20 7c 20 68 61 72 64 20 75  [limits | hard u
28c30 70 70 65 72 20 62 6f 75 6e 64 5d 0a 2a 2a 20 73  pper bound].** s
28c40 65 74 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69  et at compile-ti
28c50 6d 65 20 62 79 20 61 20 43 20 70 72 65 70 72 6f  me by a C prepro
28c60 63 65 73 73 6f 72 20 6d 61 63 72 6f 20 63 61 6c  cessor macro cal
28c70 6c 65 64 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c  led.** [limits |
28c80 20 53 51 4c 49 54 45 5f 4d 41 58 5f 3c 69 3e 4e   SQLITE_MAX_<i>N
28c90 41 4d 45 3c 2f 69 3e 5d 2e 0a 2a 2a 20 28 54 68  AME</i>]..** (Th
28ca0 65 20 22 5f 4c 49 4d 49 54 5f 22 20 69 6e 20 74  e "_LIMIT_" in t
28cb0 68 65 20 6e 61 6d 65 20 69 73 20 63 68 61 6e 67  he name is chang
28cc0 65 64 20 74 6f 20 22 5f 4d 41 58 5f 22 2e 29 29  ed to "_MAX_".))
28cd0 5e 0a 2a 2a 20 5e 41 74 74 65 6d 70 74 73 20 74  ^.** ^Attempts t
28ce0 6f 20 69 6e 63 72 65 61 73 65 20 61 20 6c 69 6d  o increase a lim
28cf0 69 74 20 61 62 6f 76 65 20 69 74 73 20 68 61 72  it above its har
28d00 64 20 75 70 70 65 72 20 62 6f 75 6e 64 20 61 72  d upper bound ar
28d10 65 0a 2a 2a 20 73 69 6c 65 6e 74 6c 79 20 74 72  e.** silently tr
28d20 75 6e 63 61 74 65 64 20 74 6f 20 74 68 65 20 68  uncated to the h
28d30 61 72 64 20 75 70 70 65 72 20 62 6f 75 6e 64 2e  ard upper bound.
28d40 0a 2a 2a 0a 2a 2a 20 5e 52 65 67 61 72 64 6c 65  .**.** ^Regardle
28d50 73 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72  ss of whether or
28d60 20 6e 6f 74 20 74 68 65 20 6c 69 6d 69 74 20 77   not the limit w
28d70 61 73 20 63 68 61 6e 67 65 64 2c 20 74 68 65 20  as changed, the 
28d80 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d  .** [sqlite3_lim
28d90 69 74 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20  it()] interface 
28da0 72 65 74 75 72 6e 73 20 74 68 65 20 70 72 69 6f  returns the prio
28db0 72 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 6c  r value of the l
28dc0 69 6d 69 74 2e 0a 2a 2a 20 5e 48 65 6e 63 65 2c  imit..** ^Hence,
28dd0 20 74 6f 20 66 69 6e 64 20 74 68 65 20 63 75 72   to find the cur
28de0 72 65 6e 74 20 76 61 6c 75 65 20 6f 66 20 61 20  rent value of a 
28df0 6c 69 6d 69 74 20 77 69 74 68 6f 75 74 20 63 68  limit without ch
28e00 61 6e 67 69 6e 67 20 69 74 2c 0a 2a 2a 20 73 69  anging it,.** si
28e10 6d 70 6c 79 20 69 6e 76 6f 6b 65 20 74 68 69 73  mply invoke this
28e20 20 69 6e 74 65 72 66 61 63 65 20 77 69 74 68 20   interface with 
28e30 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65  the third parame
28e40 74 65 72 20 73 65 74 20 74 6f 20 2d 31 2e 0a 2a  ter set to -1..*
28e50 2a 0a 2a 2a 20 52 75 6e 2d 74 69 6d 65 20 6c 69  *.** Run-time li
28e60 6d 69 74 73 20 61 72 65 20 69 6e 74 65 6e 64 65  mits are intende
28e70 64 20 66 6f 72 20 75 73 65 20 69 6e 20 61 70 70  d for use in app
28e80 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 6d  lications that m
28e90 61 6e 61 67 65 0a 2a 2a 20 62 6f 74 68 20 74 68  anage.** both th
28ea0 65 69 72 20 6f 77 6e 20 69 6e 74 65 72 6e 61 6c  eir own internal
28eb0 20 64 61 74 61 62 61 73 65 20 61 6e 64 20 61 6c   database and al
28ec0 73 6f 20 64 61 74 61 62 61 73 65 73 20 74 68 61  so databases tha
28ed0 74 20 61 72 65 20 63 6f 6e 74 72 6f 6c 6c 65 64  t are controlled
28ee0 0a 2a 2a 20 62 79 20 75 6e 74 72 75 73 74 65 64  .** by untrusted
28ef0 20 65 78 74 65 72 6e 61 6c 20 73 6f 75 72 63 65   external source
28f00 73 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65 20 61  s.  An example a
28f10 70 70 6c 69 63 61 74 69 6f 6e 20 6d 69 67 68 74  pplication might
28f20 20 62 65 20 61 0a 2a 2a 20 77 65 62 20 62 72 6f   be a.** web bro
28f30 77 73 65 72 20 74 68 61 74 20 68 61 73 20 69 74  wser that has it
28f40 73 20 6f 77 6e 20 64 61 74 61 62 61 73 65 73 20  s own databases 
28f50 66 6f 72 20 73 74 6f 72 69 6e 67 20 68 69 73 74  for storing hist
28f60 6f 72 79 20 61 6e 64 0a 2a 2a 20 73 65 70 61 72  ory and.** separ
28f70 61 74 65 20 64 61 74 61 62 61 73 65 73 20 63 6f  ate databases co
28f80 6e 74 72 6f 6c 6c 65 64 20 62 79 20 4a 61 76 61  ntrolled by Java
28f90 53 63 72 69 70 74 20 61 70 70 6c 69 63 61 74 69  Script applicati
28fa0 6f 6e 73 20 64 6f 77 6e 6c 6f 61 64 65 64 0a 2a  ons downloaded.*
28fb0 2a 20 6f 66 66 20 74 68 65 20 49 6e 74 65 72 6e  * off the Intern
28fc0 65 74 2e 20 20 54 68 65 20 69 6e 74 65 72 6e 61  et.  The interna
28fd0 6c 20 64 61 74 61 62 61 73 65 73 20 63 61 6e 20  l databases can 
28fe0 62 65 20 67 69 76 65 6e 20 74 68 65 0a 2a 2a 20  be given the.** 
28ff0 6c 61 72 67 65 2c 20 64 65 66 61 75 6c 74 20 6c  large, default l
29000 69 6d 69 74 73 2e 20 20 44 61 74 61 62 61 73 65  imits.  Database
29010 73 20 6d 61 6e 61 67 65 64 20 62 79 20 65 78 74  s managed by ext
29020 65 72 6e 61 6c 20 73 6f 75 72 63 65 73 20 63 61  ernal sources ca
29030 6e 0a 2a 2a 20 62 65 20 67 69 76 65 6e 20 6d 75  n.** be given mu
29040 63 68 20 73 6d 61 6c 6c 65 72 20 6c 69 6d 69 74  ch smaller limit
29050 73 20 64 65 73 69 67 6e 65 64 20 74 6f 20 70 72  s designed to pr
29060 65 76 65 6e 74 20 61 20 64 65 6e 69 61 6c 20 6f  event a denial o
29070 66 20 73 65 72 76 69 63 65 0a 2a 2a 20 61 74 74  f service.** att
29080 61 63 6b 2e 20 20 44 65 76 65 6c 6f 70 65 72 73  ack.  Developers
29090 20 6d 69 67 68 74 20 61 6c 73 6f 20 77 61 6e 74   might also want
290a0 20 74 6f 20 75 73 65 20 74 68 65 20 5b 73 71 6c   to use the [sql
290b0 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69  ite3_set_authori
290c0 7a 65 72 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66  zer()].** interf
290d0 61 63 65 20 74 6f 20 66 75 72 74 68 65 72 20 63  ace to further c
290e0 6f 6e 74 72 6f 6c 20 75 6e 74 72 75 73 74 65 64  ontrol untrusted
290f0 20 53 51 4c 2e 20 20 54 68 65 20 73 69 7a 65 20   SQL.  The size 
29100 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 0a  of the database.
29110 2a 2a 20 63 72 65 61 74 65 64 20 62 79 20 61 6e  ** created by an
29120 20 75 6e 74 72 75 73 74 65 64 20 73 63 72 69 70   untrusted scrip
29130 74 20 63 61 6e 20 62 65 20 63 6f 6e 74 61 69 6e  t can be contain
29140 65 64 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20  ed using the.** 
29150 5b 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e 74 5d  [max_page_count]
29160 20 5b 50 52 41 47 4d 41 5d 2e 0a 2a 2a 0a 2a 2a   [PRAGMA]..**.**
29170 20 4e 65 77 20 72 75 6e 2d 74 69 6d 65 20 6c 69   New run-time li
29180 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73 20 6d  mit categories m
29190 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66  ay be added in f
291a0 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 2e 0a  uture releases..
291b0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6c  */.int sqlite3_l
291c0 69 6d 69 74 28 73 71 6c 69 74 65 33 2a 2c 20 69  imit(sqlite3*, i
291d0 6e 74 20 69 64 2c 20 69 6e 74 20 6e 65 77 56 61  nt id, int newVa
291e0 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  l);../*.** CAPI3
291f0 52 45 46 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69  REF: Run-Time Li
29200 6d 69 74 20 43 61 74 65 67 6f 72 69 65 73 0a 2a  mit Categories.*
29210 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 6c 69 6d  * KEYWORDS: {lim
29220 69 74 20 63 61 74 65 67 6f 72 79 7d 20 7b 2a 6c  it category} {*l
29230 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73 7d  imit categories}
29240 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e  .**.** These con
29250 73 74 61 6e 74 73 20 64 65 66 69 6e 65 20 76 61  stants define va
29260 72 69 6f 75 73 20 70 65 72 66 6f 72 6d 61 6e 63  rious performanc
29270 65 20 6c 69 6d 69 74 73 0a 2a 2a 20 74 68 61 74  e limits.** that
29280 20 63 61 6e 20 62 65 20 6c 6f 77 65 72 65 64 20   can be lowered 
29290 61 74 20 72 75 6e 2d 74 69 6d 65 20 75 73 69 6e  at run-time usin
292a0 67 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74  g [sqlite3_limit
292b0 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73 79 6e 6f  ()]..** The syno
292c0 70 73 69 73 20 6f 66 20 74 68 65 20 6d 65 61 6e  psis of the mean
292d0 69 6e 67 73 20 6f 66 20 74 68 65 20 76 61 72 69  ings of the vari
292e0 6f 75 73 20 6c 69 6d 69 74 73 20 69 73 20 73 68  ous limits is sh
292f0 6f 77 6e 20 62 65 6c 6f 77 2e 0a 2a 2a 20 41 64  own below..** Ad
29300 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61  ditional informa
29310 74 69 6f 6e 20 69 73 20 61 76 61 69 6c 61 62 6c  tion is availabl
29320 65 20 61 74 20 5b 6c 69 6d 69 74 73 20 7c 20 4c  e at [limits | L
29330 69 6d 69 74 73 20 69 6e 20 53 51 4c 69 74 65 5d  imits in SQLite]
29340 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20  ..**.** <dl>.** 
29350 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c  [[SQLITE_LIMIT_L
29360 45 4e 47 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51  ENGTH]] ^(<dt>SQ
29370 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54  LITE_LIMIT_LENGT
29380 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  H</dt>.** <dd>Th
29390 65 20 6d 61 78 69 6d 75 6d 20 73 69 7a 65 20 6f  e maximum size o
293a0 66 20 61 6e 79 20 73 74 72 69 6e 67 20 6f 72 20  f any string or 
293b0 42 4c 4f 42 20 6f 72 20 74 61 62 6c 65 20 72 6f  BLOB or table ro
293c0 77 2c 20 69 6e 20 62 79 74 65 73 2e 3c 64 64 3e  w, in bytes.<dd>
293d0 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  )^.**.** [[SQLIT
293e0 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47  E_LIMIT_SQL_LENG
293f0 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54  TH]] ^(<dt>SQLIT
29400 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47  E_LIMIT_SQL_LENG
29410 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  TH</dt>.** <dd>T
29420 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74  he maximum lengt
29430 68 20 6f 66 20 61 6e 20 53 51 4c 20 73 74 61 74  h of an SQL stat
29440 65 6d 65 6e 74 2c 20 69 6e 20 62 79 74 65 73 2e  ement, in bytes.
29450 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b  </dd>)^.**.** [[
29460 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c  SQLITE_LIMIT_COL
29470 55 4d 4e 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49  UMN]] ^(<dt>SQLI
29480 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 3c  TE_LIMIT_COLUMN<
29490 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
294a0 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f  maximum number o
294b0 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 74  f columns in a t
294c0 61 62 6c 65 20 64 65 66 69 6e 69 74 69 6f 6e 20  able definition 
294d0 6f 72 20 69 6e 20 74 68 65 0a 2a 2a 20 72 65 73  or in the.** res
294e0 75 6c 74 20 73 65 74 20 6f 66 20 61 20 5b 53 45  ult set of a [SE
294f0 4c 45 43 54 5d 20 6f 72 20 74 68 65 20 6d 61 78  LECT] or the max
29500 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 63  imum number of c
29510 6f 6c 75 6d 6e 73 20 69 6e 20 61 6e 20 69 6e 64  olumns in an ind
29520 65 78 0a 2a 2a 20 6f 72 20 69 6e 20 61 6e 20 4f  ex.** or in an O
29530 52 44 45 52 20 42 59 20 6f 72 20 47 52 4f 55 50  RDER BY or GROUP
29540 20 42 59 20 63 6c 61 75 73 65 2e 3c 2f 64 64 3e   BY clause.</dd>
29550 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  )^.**.** [[SQLIT
29560 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45 50  E_LIMIT_EXPR_DEP
29570 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54  TH]] ^(<dt>SQLIT
29580 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45 50  E_LIMIT_EXPR_DEP
29590 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  TH</dt>.** <dd>T
295a0 68 65 20 6d 61 78 69 6d 75 6d 20 64 65 70 74 68  he maximum depth
295b0 20 6f 66 20 74 68 65 20 70 61 72 73 65 20 74 72   of the parse tr
295c0 65 65 20 6f 6e 20 61 6e 79 20 65 78 70 72 65 73  ee on any expres
295d0 73 69 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a  sion.</dd>)^.**.
295e0 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49  ** [[SQLITE_LIMI
295f0 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43  T_COMPOUND_SELEC
29600 54 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45  T]] ^(<dt>SQLITE
29610 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f  _LIMIT_COMPOUND_
29620 53 45 4c 45 43 54 3c 2f 64 74 3e 0a 2a 2a 20 3c  SELECT</dt>.** <
29630 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e  dd>The maximum n
29640 75 6d 62 65 72 20 6f 66 20 74 65 72 6d 73 20 69  umber of terms i
29650 6e 20 61 20 63 6f 6d 70 6f 75 6e 64 20 53 45 4c  n a compound SEL
29660 45 43 54 20 73 74 61 74 65 6d 65 6e 74 2e 3c 2f  ECT statement.</
29670 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  dd>)^.**.** [[SQ
29680 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f  LITE_LIMIT_VDBE_
29690 4f 50 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54  OP]] ^(<dt>SQLIT
296a0 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50 3c  E_LIMIT_VDBE_OP<
296b0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
296c0 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f  maximum number o
296d0 66 20 69 6e 73 74 72 75 63 74 69 6f 6e 73 20 69  f instructions i
296e0 6e 20 61 20 76 69 72 74 75 61 6c 20 6d 61 63 68  n a virtual mach
296f0 69 6e 65 20 70 72 6f 67 72 61 6d 0a 2a 2a 20 75  ine program.** u
29700 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74  sed to implement
29710 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   an SQL statemen
29720 74 2e 20 20 54 68 69 73 20 6c 69 6d 69 74 20 69  t.  This limit i
29730 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79 0a  s not currently.
29740 2a 2a 20 65 6e 66 6f 72 63 65 64 2c 20 74 68 6f  ** enforced, tho
29750 75 67 68 20 74 68 61 74 20 6d 69 67 68 74 20 62  ugh that might b
29760 65 20 61 64 64 65 64 20 69 6e 20 73 6f 6d 65 20  e added in some 
29770 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 20 6f  future release o
29780 66 0a 2a 2a 20 53 51 4c 69 74 65 2e 3c 2f 64 64  f.** SQLite.</dd
29790 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  >)^.**.** [[SQLI
297a0 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f  TE_LIMIT_FUNCTIO
297b0 4e 5f 41 52 47 5d 5d 20 5e 28 3c 64 74 3e 53 51  N_ARG]] ^(<dt>SQ
297c0 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54  LITE_LIMIT_FUNCT
297d0 49 4f 4e 5f 41 52 47 3c 2f 64 74 3e 0a 2a 2a 20  ION_ARG</dt>.** 
297e0 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
297f0 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65  number of argume
29800 6e 74 73 20 6f 6e 20 61 20 66 75 6e 63 74 69 6f  nts on a functio
29810 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20  n.</dd>)^.**.** 
29820 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41  [[SQLITE_LIMIT_A
29830 54 54 41 43 48 45 44 5d 5d 20 5e 28 3c 64 74 3e  TTACHED]] ^(<dt>
29840 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54  SQLITE_LIMIT_ATT
29850 41 43 48 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ACHED</dt>.** <d
29860 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75  d>The maximum nu
29870 6d 62 65 72 20 6f 66 20 5b 41 54 54 41 43 48 20  mber of [ATTACH 
29880 7c 20 61 74 74 61 63 68 65 64 20 64 61 74 61 62  | attached datab
29890 61 73 65 73 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a  ases].)^</dd>.**
298a0 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d  .** [[SQLITE_LIM
298b0 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f  IT_LIKE_PATTERN_
298c0 4c 45 4e 47 54 48 5d 5d 0a 2a 2a 20 5e 28 3c 64  LENGTH]].** ^(<d
298d0 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c  t>SQLITE_LIMIT_L
298e0 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47  IKE_PATTERN_LENG
298f0 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  TH</dt>.** <dd>T
29900 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74  he maximum lengt
29910 68 20 6f 66 20 74 68 65 20 70 61 74 74 65 72 6e  h of the pattern
29920 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
29930 20 5b 4c 49 4b 45 5d 20 6f 72 0a 2a 2a 20 5b 47   [LIKE] or.** [G
29940 4c 4f 42 5d 20 6f 70 65 72 61 74 6f 72 73 2e 3c  LOB] operators.<
29950 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  /dd>)^.**.** [[S
29960 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49  QLITE_LIMIT_VARI
29970 41 42 4c 45 5f 4e 55 4d 42 45 52 5d 5d 0a 2a 2a  ABLE_NUMBER]].**
29980 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49   ^(<dt>SQLITE_LI
29990 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d  MIT_VARIABLE_NUM
299a0 42 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  BER</dt>.** <dd>
299b0 54 68 65 20 6d 61 78 69 6d 75 6d 20 69 6e 64 65  The maximum inde
299c0 78 20 6e 75 6d 62 65 72 20 6f 66 20 61 6e 79 20  x number of any 
299d0 5b 70 61 72 61 6d 65 74 65 72 5d 20 69 6e 20 61  [parameter] in a
299e0 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e  n SQL statement.
299f0 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  )^.**.** [[SQLIT
29a00 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45 52 5f  E_LIMIT_TRIGGER_
29a10 44 45 50 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51  DEPTH]] ^(<dt>SQ
29a20 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47  LITE_LIMIT_TRIGG
29a30 45 52 5f 44 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a  ER_DEPTH</dt>.**
29a40 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
29a50 20 64 65 70 74 68 20 6f 66 20 72 65 63 75 72 73   depth of recurs
29a60 69 6f 6e 20 66 6f 72 20 74 72 69 67 67 65 72 73  ion for triggers
29a70 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b  .</dd>)^.**.** [
29a80 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 57 4f  [SQLITE_LIMIT_WO
29a90 52 4b 45 52 5f 54 48 52 45 41 44 53 5d 5d 20 5e  RKER_THREADS]] ^
29aa0 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49  (<dt>SQLITE_LIMI
29ab0 54 5f 57 4f 52 4b 45 52 5f 54 48 52 45 41 44 53  T_WORKER_THREADS
29ac0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
29ad0 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20   maximum number 
29ae0 6f 66 20 61 75 78 69 6c 69 61 72 79 20 77 6f 72  of auxiliary wor
29af0 6b 65 72 20 74 68 72 65 61 64 73 20 74 68 61 74  ker threads that
29b00 20 61 20 73 69 6e 67 6c 65 0a 2a 2a 20 5b 70 72   a single.** [pr
29b10 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
29b20 5d 20 6d 61 79 20 73 74 61 72 74 2e 3c 2f 64 64  ] may start.</dd
29b30 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a  >)^.** </dl>.*/.
29b40 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
29b50 49 4d 49 54 5f 4c 45 4e 47 54 48 20 20 20 20 20  IMIT_LENGTH     
29b60 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30                 0
29b70 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
29b80 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48  LIMIT_SQL_LENGTH
29b90 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
29ba0 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  1.#define SQLITE
29bb0 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 20 20 20  _LIMIT_COLUMN   
29bc0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
29bd0 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   2.#define SQLIT
29be0 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45 50  E_LIMIT_EXPR_DEP
29bf0 54 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20  TH              
29c00 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    3.#define SQLI
29c10 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e  TE_LIMIT_COMPOUN
29c20 44 5f 53 45 4c 45 43 54 20 20 20 20 20 20 20 20  D_SELECT        
29c30 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c     4.#define SQL
29c40 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f  ITE_LIMIT_VDBE_O
29c50 50 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  P               
29c60 20 20 20 20 35 0a 23 64 65 66 69 6e 65 20 53 51      5.#define SQ
29c70 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54  LITE_LIMIT_FUNCT
29c80 49 4f 4e 5f 41 52 47 20 20 20 20 20 20 20 20 20  ION_ARG         
29c90 20 20 20 20 20 36 0a 23 64 65 66 69 6e 65 20 53       6.#define S
29ca0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41  QLITE_LIMIT_ATTA
29cb0 43 48 45 44 20 20 20 20 20 20 20 20 20 20 20 20  CHED            
29cc0 20 20 20 20 20 20 37 0a 23 64 65 66 69 6e 65 20        7.#define 
29cd0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b  SQLITE_LIMIT_LIK
29ce0 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48  E_PATTERN_LENGTH
29cf0 20 20 20 20 20 20 20 38 0a 23 64 65 66 69 6e 65         8.#define
29d00 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41   SQLITE_LIMIT_VA
29d10 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 20 20 20  RIABLE_NUMBER   
29d20 20 20 20 20 20 20 20 20 39 0a 23 64 65 66 69 6e          9.#defin
29d30 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54  e SQLITE_LIMIT_T
29d40 52 49 47 47 45 52 5f 44 45 50 54 48 20 20 20 20  RIGGER_DEPTH    
29d50 20 20 20 20 20 20 20 20 31 30 0a 23 64 65 66 69          10.#defi
29d60 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
29d70 57 4f 52 4b 45 52 5f 54 48 52 45 41 44 53 20 20  WORKER_THREADS  
29d80 20 20 20 20 20 20 20 20 20 31 31 0a 0a 2f 2a 0a           11../*.
29d90 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6d  ** CAPI3REF: Com
29da0 70 69 6c 69 6e 67 20 41 6e 20 53 51 4c 20 53 74  piling An SQL St
29db0 61 74 65 6d 65 6e 74 0a 2a 2a 20 4b 45 59 57 4f  atement.** KEYWO
29dc0 52 44 53 3a 20 7b 53 51 4c 20 73 74 61 74 65 6d  RDS: {SQL statem
29dd0 65 6e 74 20 63 6f 6d 70 69 6c 65 72 7d 0a 2a 2a  ent compiler}.**
29de0 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
29df0 0a 2a 2a 20 43 4f 4e 53 54 52 55 43 54 4f 52 3a  .** CONSTRUCTOR:
29e00 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a   sqlite3_stmt.**
29e10 0a 2a 2a 20 54 6f 20 65 78 65 63 75 74 65 20 61  .** To execute a
29e20 6e 20 53 51 4c 20 71 75 65 72 79 2c 20 69 74 20  n SQL query, it 
29e30 6d 75 73 74 20 66 69 72 73 74 20 62 65 20 63 6f  must first be co
29e40 6d 70 69 6c 65 64 20 69 6e 74 6f 20 61 20 62 79  mpiled into a by
29e50 74 65 2d 63 6f 64 65 0a 2a 2a 20 70 72 6f 67 72  te-code.** progr
29e60 61 6d 20 75 73 69 6e 67 20 6f 6e 65 20 6f 66 20  am using one of 
29e70 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a  these routines..
29e80 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20  **.** The first 
29e90 61 72 67 75 6d 65 6e 74 2c 20 22 64 62 22 2c 20  argument, "db", 
29ea0 69 73 20 61 20 5b 64 61 74 61 62 61 73 65 20 63  is a [database c
29eb0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 62 74 61 69  onnection] obtai
29ec0 6e 65 64 20 66 72 6f 6d 20 61 0a 2a 2a 20 70 72  ned from a.** pr
29ed0 69 6f 72 20 73 75 63 63 65 73 73 66 75 6c 20 63  ior successful c
29ee0 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
29ef0 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65  open()], [sqlite
29f00 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 6f 72 0a  3_open_v2()] or.
29f10 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ** [sqlite3_open
29f20 31 36 28 29 5d 2e 20 20 54 68 65 20 64 61 74 61  16()].  The data
29f30 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
29f40 6d 75 73 74 20 6e 6f 74 20 68 61 76 65 20 62 65  must not have be
29f50 65 6e 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a  en closed..**.**
29f60 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   The second argu
29f70 6d 65 6e 74 2c 20 22 7a 53 71 6c 22 2c 20 69 73  ment, "zSql", is
29f80 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 74   the statement t
29f90 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64 2c 20 65  o be compiled, e
29fa0 6e 63 6f 64 65 64 0a 2a 2a 20 61 73 20 65 69 74  ncoded.** as eit
29fb0 68 65 72 20 55 54 46 2d 38 20 6f 72 20 55 54 46  her UTF-8 or UTF
29fc0 2d 31 36 2e 20 20 54 68 65 20 73 71 6c 69 74 65  -16.  The sqlite
29fd0 33 5f 70 72 65 70 61 72 65 28 29 20 61 6e 64 20  3_prepare() and 
29fe0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
29ff0 76 32 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63  v2().** interfac
2a000 65 73 20 75 73 65 20 55 54 46 2d 38 2c 20 61 6e  es use UTF-8, an
2a010 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  d sqlite3_prepar
2a020 65 31 36 28 29 20 61 6e 64 20 73 71 6c 69 74 65  e16() and sqlite
2a030 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29  3_prepare16_v2()
2a040 0a 2a 2a 20 75 73 65 20 55 54 46 2d 31 36 2e 0a  .** use UTF-16..
2a050 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6e 42  **.** ^If the nB
2a060 79 74 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20  yte argument is 
2a070 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 7a  negative, then z
2a080 53 71 6c 20 69 73 20 72 65 61 64 20 75 70 20 74  Sql is read up t
2a090 6f 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 7a  o the.** first z
2a0a0 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20  ero terminator. 
2a0b0 5e 49 66 20 6e 42 79 74 65 20 69 73 20 70 6f 73  ^If nByte is pos
2a0c0 69 74 69 76 65 2c 20 74 68 65 6e 20 69 74 20 69  itive, then it i
2a0d0 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20  s the.** number 
2a0e0 6f 66 20 62 79 74 65 73 20 72 65 61 64 20 66 72  of bytes read fr
2a0f0 6f 6d 20 7a 53 71 6c 2e 20 20 5e 49 66 20 6e 42  om zSql.  ^If nB
2a100 79 74 65 20 69 73 20 7a 65 72 6f 2c 20 74 68 65  yte is zero, the
2a110 6e 20 6e 6f 20 70 72 65 70 61 72 65 64 0a 2a 2a  n no prepared.**
2a120 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 67 65   statement is ge
2a130 6e 65 72 61 74 65 64 2e 0a 2a 2a 20 49 66 20 74  nerated..** If t
2a140 68 65 20 63 61 6c 6c 65 72 20 6b 6e 6f 77 73 20  he caller knows 
2a150 74 68 61 74 20 74 68 65 20 73 75 70 70 6c 69 65  that the supplie
2a160 64 20 73 74 72 69 6e 67 20 69 73 20 6e 75 6c 2d  d string is nul-
2a170 74 65 72 6d 69 6e 61 74 65 64 2c 20 74 68 65 6e  terminated, then
2a180 0a 2a 2a 20 74 68 65 72 65 20 69 73 20 61 20 73  .** there is a s
2a190 6d 61 6c 6c 20 70 65 72 66 6f 72 6d 61 6e 63 65  mall performance
2a1a0 20 61 64 76 61 6e 74 61 67 65 20 74 6f 20 70 61   advantage to pa
2a1b0 73 73 69 6e 67 20 61 6e 20 6e 42 79 74 65 20 70  ssing an nByte p
2a1c0 61 72 61 6d 65 74 65 72 20 74 68 61 74 0a 2a 2a  arameter that.**
2a1d0 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   is the number o
2a1e0 66 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 69  f bytes in the i
2a1f0 6e 70 75 74 20 73 74 72 69 6e 67 20 3c 69 3e 69  nput string <i>i
2a200 6e 63 6c 75 64 69 6e 67 3c 2f 69 3e 0a 2a 2a 20  ncluding</i>.** 
2a210 74 68 65 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74  the nul-terminat
2a220 6f 72 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 70 7a  or..**.** ^If pz
2a230 54 61 69 6c 20 69 73 20 6e 6f 74 20 4e 55 4c 4c  Tail is not NULL
2a240 20 74 68 65 6e 20 2a 70 7a 54 61 69 6c 20 69 73   then *pzTail is
2a250 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74 20 74   made to point t
2a260 6f 20 74 68 65 20 66 69 72 73 74 20 62 79 74 65  o the first byte
2a270 0a 2a 2a 20 70 61 73 74 20 74 68 65 20 65 6e 64  .** past the end
2a280 20 6f 66 20 74 68 65 20 66 69 72 73 74 20 53 51   of the first SQ
2a290 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 7a  L statement in z
2a2a0 53 71 6c 2e 20 20 54 68 65 73 65 20 72 6f 75 74  Sql.  These rout
2a2b0 69 6e 65 73 20 6f 6e 6c 79 0a 2a 2a 20 63 6f 6d  ines only.** com
2a2c0 70 69 6c 65 20 74 68 65 20 66 69 72 73 74 20 73  pile the first s
2a2d0 74 61 74 65 6d 65 6e 74 20 69 6e 20 7a 53 71 6c  tatement in zSql
2a2e0 2c 20 73 6f 20 2a 70 7a 54 61 69 6c 20 69 73 20  , so *pzTail is 
2a2f0 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67 20 74 6f  left pointing to
2a300 0a 2a 2a 20 77 68 61 74 20 72 65 6d 61 69 6e 73  .** what remains
2a310 20 75 6e 63 6f 6d 70 69 6c 65 64 2e 0a 2a 2a 0a   uncompiled..**.
2a320 2a 2a 20 5e 2a 70 70 53 74 6d 74 20 69 73 20 6c  ** ^*ppStmt is l
2a330 65 66 74 20 70 6f 69 6e 74 69 6e 67 20 74 6f 20  eft pointing to 
2a340 61 20 63 6f 6d 70 69 6c 65 64 20 5b 70 72 65 70  a compiled [prep
2a350 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
2a360 74 68 61 74 20 63 61 6e 20 62 65 0a 2a 2a 20 65  that can be.** e
2a370 78 65 63 75 74 65 64 20 75 73 69 6e 67 20 5b 73  xecuted using [s
2a380 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 20  qlite3_step()]. 
2a390 20 5e 49 66 20 74 68 65 72 65 20 69 73 20 61 6e   ^If there is an
2a3a0 20 65 72 72 6f 72 2c 20 2a 70 70 53 74 6d 74 20   error, *ppStmt 
2a3b0 69 73 20 73 65 74 0a 2a 2a 20 74 6f 20 4e 55 4c  is set.** to NUL
2a3c0 4c 2e 20 20 5e 49 66 20 74 68 65 20 69 6e 70 75  L.  ^If the inpu
2a3d0 74 20 74 65 78 74 20 63 6f 6e 74 61 69 6e 73 20  t text contains 
2a3e0 6e 6f 20 53 51 4c 20 28 69 66 20 74 68 65 20 69  no SQL (if the i
2a3f0 6e 70 75 74 20 69 73 20 61 6e 20 65 6d 70 74 79  nput is an empty
2a400 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 72 20 61 20  .** string or a 
2a410 63 6f 6d 6d 65 6e 74 29 20 74 68 65 6e 20 2a 70  comment) then *p
2a420 70 53 74 6d 74 20 69 73 20 73 65 74 20 74 6f 20  pStmt is set to 
2a430 4e 55 4c 4c 2e 0a 2a 2a 20 54 68 65 20 63 61 6c  NULL..** The cal
2a440 6c 69 6e 67 20 70 72 6f 63 65 64 75 72 65 20 69  ling procedure i
2a450 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f  s responsible fo
2a460 72 20 64 65 6c 65 74 69 6e 67 20 74 68 65 20 63  r deleting the c
2a470 6f 6d 70 69 6c 65 64 0a 2a 2a 20 53 51 4c 20 73  ompiled.** SQL s
2a480 74 61 74 65 6d 65 6e 74 20 75 73 69 6e 67 20 5b  tatement using [
2a490 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
2a4a0 28 29 5d 20 61 66 74 65 72 20 69 74 20 68 61 73  ()] after it has
2a4b0 20 66 69 6e 69 73 68 65 64 20 77 69 74 68 20 69   finished with i
2a4c0 74 2e 0a 2a 2a 20 70 70 53 74 6d 74 20 6d 61 79  t..** ppStmt may
2a4d0 20 6e 6f 74 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a   not be NULL..**
2a4e0 0a 2a 2a 20 5e 4f 6e 20 73 75 63 63 65 73 73 2c  .** ^On success,
2a4f0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65   the sqlite3_pre
2a500 70 61 72 65 28 29 20 66 61 6d 69 6c 79 20 6f 66  pare() family of
2a510 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
2a520 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 3b 0a 2a 2a   [SQLITE_OK];.**
2a530 20 6f 74 68 65 72 77 69 73 65 20 61 6e 20 5b 65   otherwise an [e
2a540 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65  rror code] is re
2a550 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  turned..**.** Th
2a560 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  e sqlite3_prepar
2a570 65 5f 76 32 28 29 20 61 6e 64 20 73 71 6c 69 74  e_v2() and sqlit
2a580 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
2a590 29 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65  ) interfaces are
2a5a0 0a 2a 2a 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20  .** recommended 
2a5b0 66 6f 72 20 61 6c 6c 20 6e 65 77 20 70 72 6f 67  for all new prog
2a5c0 72 61 6d 73 2e 20 54 68 65 20 74 77 6f 20 6f 6c  rams. The two ol
2a5d0 64 65 72 20 69 6e 74 65 72 66 61 63 65 73 20 61  der interfaces a
2a5e0 72 65 20 72 65 74 61 69 6e 65 64 0a 2a 2a 20 66  re retained.** f
2a5f0 6f 72 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d  or backwards com
2a600 70 61 74 69 62 69 6c 69 74 79 2c 20 62 75 74 20  patibility, but 
2a610 74 68 65 69 72 20 75 73 65 20 69 73 20 64 69 73  their use is dis
2a620 63 6f 75 72 61 67 65 64 2e 0a 2a 2a 20 5e 49 6e  couraged..** ^In
2a630 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66   the "v2" interf
2a640 61 63 65 73 2c 20 74 68 65 20 70 72 65 70 61 72  aces, the prepar
2a650 65 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20  ed statement.** 
2a660 74 68 61 74 20 69 73 20 72 65 74 75 72 6e 65 64  that is returned
2a670 20 28 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73   (the [sqlite3_s
2a680 74 6d 74 5d 20 6f 62 6a 65 63 74 29 20 63 6f 6e  tmt] object) con
2a690 74 61 69 6e 73 20 61 20 63 6f 70 79 20 6f 66 20  tains a copy of 
2a6a0 74 68 65 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 20  the.** original 
2a6b0 53 51 4c 20 74 65 78 74 2e 20 54 68 69 73 20 63  SQL text. This c
2a6c0 61 75 73 65 73 20 74 68 65 20 5b 73 71 6c 69 74  auses the [sqlit
2a6d0 65 33 5f 73 74 65 70 28 29 5d 20 69 6e 74 65 72  e3_step()] inter
2a6e0 66 61 63 65 20 74 6f 0a 2a 2a 20 62 65 68 61 76  face to.** behav
2a6f0 65 20 64 69 66 66 65 72 65 6e 74 6c 79 20 69 6e  e differently in
2a700 20 74 68 72 65 65 20 77 61 79 73 3a 0a 2a 2a 0a   three ways:.**.
2a710 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 0a  ** <ol>.** <li>.
2a720 2a 2a 20 5e 49 66 20 74 68 65 20 64 61 74 61 62  ** ^If the datab
2a730 61 73 65 20 73 63 68 65 6d 61 20 63 68 61 6e 67  ase schema chang
2a740 65 73 2c 20 69 6e 73 74 65 61 64 20 6f 66 20 72  es, instead of r
2a750 65 74 75 72 6e 69 6e 67 20 5b 53 51 4c 49 54 45  eturning [SQLITE
2a760 5f 53 43 48 45 4d 41 5d 20 61 73 20 69 74 0a 2a  _SCHEMA] as it.*
2a770 2a 20 61 6c 77 61 79 73 20 75 73 65 64 20 74 6f  * always used to
2a780 20 64 6f 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74   do, [sqlite3_st
2a790 65 70 28 29 5d 20 77 69 6c 6c 20 61 75 74 6f 6d  ep()] will autom
2a7a0 61 74 69 63 61 6c 6c 79 20 72 65 63 6f 6d 70 69  atically recompi
2a7b0 6c 65 20 74 68 65 20 53 51 4c 0a 2a 2a 20 73 74  le the SQL.** st
2a7c0 61 74 65 6d 65 6e 74 20 61 6e 64 20 74 72 79 20  atement and try 
2a7d0 74 6f 20 72 75 6e 20 69 74 20 61 67 61 69 6e 2e  to run it again.
2a7e0 20 41 73 20 6d 61 6e 79 20 61 73 20 5b 53 51 4c   As many as [SQL
2a7f0 49 54 45 5f 4d 41 58 5f 53 43 48 45 4d 41 5f 52  ITE_MAX_SCHEMA_R
2a800 45 54 52 59 5d 0a 2a 2a 20 72 65 74 72 69 65 73  ETRY].** retries
2a810 20 77 69 6c 6c 20 6f 63 63 75 72 20 62 65 66 6f   will occur befo
2a820 72 65 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  re sqlite3_step(
2a830 29 20 67 69 76 65 73 20 75 70 20 61 6e 64 20 72  ) gives up and r
2a840 65 74 75 72 6e 73 20 61 6e 20 65 72 72 6f 72 2e  eturns an error.
2a850 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20  .** </li>.**.** 
2a860 3c 6c 69 3e 0a 2a 2a 20 5e 57 68 65 6e 20 61 6e  <li>.** ^When an
2a870 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2c 20 5b   error occurs, [
2a880 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
2a890 77 69 6c 6c 20 72 65 74 75 72 6e 20 6f 6e 65 20  will return one 
2a8a0 6f 66 20 74 68 65 20 64 65 74 61 69 6c 65 64 0a  of the detailed.
2a8b0 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d  ** [error codes]
2a8c0 20 6f 72 20 5b 65 78 74 65 6e 64 65 64 20 65 72   or [extended er
2a8d0 72 6f 72 20 63 6f 64 65 73 5d 2e 20 20 5e 54 68  ror codes].  ^Th
2a8e0 65 20 6c 65 67 61 63 79 20 62 65 68 61 76 69 6f  e legacy behavio
2a8f0 72 20 77 61 73 20 74 68 61 74 0a 2a 2a 20 5b 73  r was that.** [s
2a900 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77  qlite3_step()] w
2a910 6f 75 6c 64 20 6f 6e 6c 79 20 72 65 74 75 72 6e  ould only return
2a920 20 61 20 67 65 6e 65 72 69 63 20 5b 53 51 4c 49   a generic [SQLI
2a930 54 45 5f 45 52 52 4f 52 5d 20 72 65 73 75 6c 74  TE_ERROR] result
2a940 20 63 6f 64 65 0a 2a 2a 20 61 6e 64 20 74 68 65   code.** and the
2a950 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 77 6f 75   application wou
2a960 6c 64 20 68 61 76 65 20 74 6f 20 6d 61 6b 65 20  ld have to make 
2a970 61 20 73 65 63 6f 6e 64 20 63 61 6c 6c 20 74 6f  a second call to
2a980 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
2a990 29 5d 0a 2a 2a 20 69 6e 20 6f 72 64 65 72 20 74  )].** in order t
2a9a0 6f 20 66 69 6e 64 20 74 68 65 20 75 6e 64 65 72  o find the under
2a9b0 6c 79 69 6e 67 20 63 61 75 73 65 20 6f 66 20 74  lying cause of t
2a9c0 68 65 20 70 72 6f 62 6c 65 6d 2e 20 57 69 74 68  he problem. With
2a9d0 20 74 68 65 20 22 76 32 22 20 70 72 65 70 61 72   the "v2" prepar
2a9e0 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 2c  e.** interfaces,
2a9f0 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20   the underlying 
2aa00 72 65 61 73 6f 6e 20 66 6f 72 20 74 68 65 20 65  reason for the e
2aa10 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64  rror is returned
2aa20 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e 0a 2a 2a   immediately..**
2aa30 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69   </li>.**.** <li
2aa40 3e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 73 70 65  >.** ^If the spe
2aa50 63 69 66 69 63 20 76 61 6c 75 65 20 62 6f 75 6e  cific value boun
2aa60 64 20 74 6f 20 5b 70 61 72 61 6d 65 74 65 72 20  d to [parameter 
2aa70 7c 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72  | host parameter
2aa80 5d 20 69 6e 20 74 68 65 20 0a 2a 2a 20 57 48 45  ] in the .** WHE
2aa90 52 45 20 63 6c 61 75 73 65 20 6d 69 67 68 74 20  RE clause might 
2aaa0 69 6e 66 6c 75 65 6e 63 65 20 74 68 65 20 63 68  influence the ch
2aab0 6f 69 63 65 20 6f 66 20 71 75 65 72 79 20 70 6c  oice of query pl
2aac0 61 6e 20 66 6f 72 20 61 20 73 74 61 74 65 6d 65  an for a stateme
2aad0 6e 74 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20  nt,.** then the 
2aae0 73 74 61 74 65 6d 65 6e 74 20 77 69 6c 6c 20 62  statement will b
2aaf0 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  e automatically 
2ab00 72 65 63 6f 6d 70 69 6c 65 64 2c 20 61 73 20 69  recompiled, as i
2ab10 66 20 74 68 65 72 65 20 68 61 64 20 62 65 65 6e  f there had been
2ab20 20 0a 2a 2a 20 61 20 73 63 68 65 6d 61 20 63 68   .** a schema ch
2ab30 61 6e 67 65 2c 20 6f 6e 20 74 68 65 20 66 69 72  ange, on the fir
2ab40 73 74 20 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  st  [sqlite3_ste
2ab50 70 28 29 5d 20 63 61 6c 6c 20 66 6f 6c 6c 6f 77  p()] call follow
2ab60 69 6e 67 20 61 6e 79 20 63 68 61 6e 67 65 0a 2a  ing any change.*
2ab70 2a 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  * to the [sqlite
2ab80 33 5f 62 69 6e 64 5f 74 65 78 74 20 7c 20 62 69  3_bind_text | bi
2ab90 6e 64 69 6e 67 73 5d 20 6f 66 20 74 68 61 74 20  ndings] of that 
2aba0 5b 70 61 72 61 6d 65 74 65 72 5d 2e 20 0a 2a 2a  [parameter]. .**
2abb0 20 5e 54 68 65 20 73 70 65 63 69 66 69 63 20 76   ^The specific v
2abc0 61 6c 75 65 20 6f 66 20 57 48 45 52 45 2d 63 6c  alue of WHERE-cl
2abd0 61 75 73 65 20 5b 70 61 72 61 6d 65 74 65 72 5d  ause [parameter]
2abe0 20 6d 69 67 68 74 20 69 6e 66 6c 75 65 6e 63 65   might influence
2abf0 20 74 68 65 20 0a 2a 2a 20 63 68 6f 69 63 65 20   the .** choice 
2ac00 6f 66 20 71 75 65 72 79 20 70 6c 61 6e 20 69 66  of query plan if
2ac10 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 69   the parameter i
2ac20 73 20 74 68 65 20 6c 65 66 74 2d 68 61 6e 64 20  s the left-hand 
2ac30 73 69 64 65 20 6f 66 20 61 20 5b 4c 49 4b 45 5d  side of a [LIKE]
2ac40 0a 2a 2a 20 6f 72 20 5b 47 4c 4f 42 5d 20 6f 70  .** or [GLOB] op
2ac50 65 72 61 74 6f 72 20 6f 72 20 69 66 20 74 68 65  erator or if the
2ac60 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 63 6f   parameter is co
2ac70 6d 70 61 72 65 64 20 74 6f 20 61 6e 20 69 6e 64  mpared to an ind
2ac80 65 78 65 64 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 61  exed column.** a
2ac90 6e 64 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 45  nd the [SQLITE_E
2aca0 4e 41 42 4c 45 5f 53 54 41 54 33 5d 20 63 6f 6d  NABLE_STAT3] com
2acb0 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
2acc0 20 69 73 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 20   is enabled..** 
2acd0 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a  </li>.** </ol>.*
2ace0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72  /.int sqlite3_pr
2acf0 65 70 61 72 65 28 0a 20 20 73 71 6c 69 74 65 33  epare(.  sqlite3
2ad00 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20   *db,           
2ad10 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e   /* Database han
2ad20 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  dle */.  const c
2ad30 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20  har *zSql,      
2ad40 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   /* SQL statemen
2ad50 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64  t, UTF-8 encoded
2ad60 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c   */.  int nByte,
2ad70 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
2ad80 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20   Maximum length 
2ad90 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73  of zSql in bytes
2ada0 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73  . */.  sqlite3_s
2adb0 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f  tmt **ppStmt,  /
2adc0 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74  * OUT: Statement
2add0 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e   handle */.  con
2ade0 73 74 20 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c  st char **pzTail
2adf0 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69       /* OUT: Poi
2ae00 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70  nter to unused p
2ae10 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a  ortion of zSql *
2ae20 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  /.);.int sqlite3
2ae30 5f 70 72 65 70 61 72 65 5f 76 32 28 0a 20 20 73  _prepare_v2(.  s
2ae40 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20  qlite3 *db,     
2ae50 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61         /* Databa
2ae60 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63  se handle */.  c
2ae70 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c  onst char *zSql,
2ae80 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74         /* SQL st
2ae90 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65  atement, UTF-8 e
2aea0 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20  ncoded */.  int 
2aeb0 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20  nByte,          
2aec0 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c      /* Maximum l
2aed0 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e  ength of zSql in
2aee0 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c   bytes. */.  sql
2aef0 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74  ite3_stmt **ppSt
2af00 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61  mt,  /* OUT: Sta
2af10 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f  tement handle */
2af20 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a  .  const char **
2af30 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55  pzTail     /* OU
2af40 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e  T: Pointer to un
2af50 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20  used portion of 
2af60 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73  zSql */.);.int s
2af70 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
2af80 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
2af90 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44              /* D
2afa0 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a  atabase handle *
2afb0 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a  /.  const void *
2afc0 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53  zSql,       /* S
2afd0 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54  QL statement, UT
2afe0 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f 0a  F-16 encoded */.
2aff0 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20    int nByte,    
2b000 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78            /* Max
2b010 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a  imum length of z
2b020 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f  Sql in bytes. */
2b030 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  .  sqlite3_stmt 
2b040 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55  **ppStmt,  /* OU
2b050 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e  T: Statement han
2b060 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76  dle */.  const v
2b070 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20  oid **pzTail    
2b080 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72   /* OUT: Pointer
2b090 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69   to unused porti
2b0a0 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b  on of zSql */.);
2b0b0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65  .int sqlite3_pre
2b0c0 70 61 72 65 31 36 5f 76 32 28 0a 20 20 73 71 6c  pare16_v2(.  sql
2b0d0 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20  ite3 *db,       
2b0e0 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65       /* Database
2b0f0 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e   handle */.  con
2b100 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20 20  st void *zSql,  
2b110 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74       /* SQL stat
2b120 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20 65 6e  ement, UTF-16 en
2b130 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e  coded */.  int n
2b140 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 20  Byte,           
2b150 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65     /* Maximum le
2b160 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20  ngth of zSql in 
2b170 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69  bytes. */.  sqli
2b180 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d  te3_stmt **ppStm
2b190 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74  t,  /* OUT: Stat
2b1a0 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a  ement handle */.
2b1b0 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a 70    const void **p
2b1c0 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54  zTail     /* OUT
2b1d0 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75  : Pointer to unu
2b1e0 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a  sed portion of z
2b1f0 53 71 6c 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a  Sql */.);../*.**
2b200 20 43 41 50 49 33 52 45 46 3a 20 52 65 74 72 69   CAPI3REF: Retri
2b210 65 76 69 6e 67 20 53 74 61 74 65 6d 65 6e 74 20  eving Statement 
2b220 53 51 4c 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  SQL.** METHOD: s
2b230 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a  qlite3_stmt.**.*
2b240 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73  * ^The sqlite3_s
2b250 71 6c 28 50 29 20 69 6e 74 65 72 66 61 63 65 20  ql(P) interface 
2b260 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65  returns a pointe
2b270 72 20 74 6f 20 61 20 63 6f 70 79 20 6f 66 20 74  r to a copy of t
2b280 68 65 20 55 54 46 2d 38 0a 2a 2a 20 53 51 4c 20  he UTF-8.** SQL 
2b290 74 65 78 74 20 75 73 65 64 20 74 6f 20 63 72 65  text used to cre
2b2a0 61 74 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  ate [prepared st
2b2b0 61 74 65 6d 65 6e 74 5d 20 50 20 69 66 20 50 20  atement] P if P 
2b2c0 77 61 73 0a 2a 2a 20 63 72 65 61 74 65 64 20 62  was.** created b
2b2d0 79 20 65 69 74 68 65 72 20 5b 73 71 6c 69 74 65  y either [sqlite
2b2e0 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
2b2f0 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  or [sqlite3_prep
2b300 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a 20  are16_v2()]..** 
2b310 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 70  ^The sqlite3_exp
2b320 61 6e 64 65 64 5f 73 71 6c 28 50 29 20 69 6e 74  anded_sql(P) int
2b330 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61  erface returns a
2b340 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 55 54   pointer to a UT
2b350 46 2d 38 0a 2a 2a 20 73 74 72 69 6e 67 20 63 6f  F-8.** string co
2b360 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 53 51 4c  ntaining the SQL
2b370 20 74 65 78 74 20 6f 66 20 70 72 65 70 61 72 65   text of prepare
2b380 64 20 73 74 61 74 65 6d 65 6e 74 20 50 20 77 69  d statement P wi
2b390 74 68 0a 2a 2a 20 5b 62 6f 75 6e 64 20 70 61 72  th.** [bound par
2b3a0 61 6d 65 74 65 72 73 5d 20 65 78 70 61 6e 64 65  ameters] expande
2b3b0 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 46 6f 72 20 65  d..**.** ^(For e
2b3c0 78 61 6d 70 6c 65 2c 20 69 66 20 61 20 70 72 65  xample, if a pre
2b3d0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20  pared statement 
2b3e0 69 73 20 63 72 65 61 74 65 64 20 75 73 69 6e 67  is created using
2b3f0 20 74 68 65 20 53 51 4c 0a 2a 2a 20 74 65 78 74   the SQL.** text
2b400 20 22 53 45 4c 45 43 54 20 24 61 62 63 2c 3a 78   "SELECT $abc,:x
2b410 79 7a 22 20 61 6e 64 20 69 66 20 70 61 72 61 6d  yz" and if param
2b420 65 74 65 72 20 24 61 62 63 20 69 73 20 62 6f 75  eter $abc is bou
2b430 6e 64 20 74 6f 20 69 6e 74 65 67 65 72 20 32 33  nd to integer 23
2b440 34 35 0a 2a 2a 20 61 6e 64 20 70 61 72 61 6d 65  45.** and parame
2b450 74 65 72 20 3a 78 79 7a 20 69 73 20 75 6e 62 6f  ter :xyz is unbo
2b460 75 6e 64 2c 20 74 68 65 6e 20 73 71 6c 69 74 65  und, then sqlite
2b470 33 5f 73 71 6c 28 29 20 77 69 6c 6c 20 72 65 74  3_sql() will ret
2b480 75 72 6e 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69  urn.** the origi
2b490 6e 61 6c 20 73 74 72 69 6e 67 2c 20 22 53 45 4c  nal string, "SEL
2b4a0 45 43 54 20 24 61 62 63 2c 3a 78 79 7a 22 20 62  ECT $abc,:xyz" b
2b4b0 75 74 20 73 71 6c 69 74 65 33 5f 65 78 70 61 6e  ut sqlite3_expan
2b4c0 64 65 64 5f 73 71 6c 28 29 0a 2a 2a 20 77 69 6c  ded_sql().** wil
2b4d0 6c 20 72 65 74 75 72 6e 20 22 53 45 4c 45 43 54  l return "SELECT
2b4e0 20 32 33 34 35 2c 4e 55 4c 4c 22 2e 29 5e 0a 2a   2345,NULL".)^.*
2b4f0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
2b500 33 5f 65 78 70 61 6e 64 65 64 5f 73 71 6c 28 29  3_expanded_sql()
2b510 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
2b520 6e 73 20 4e 55 4c 4c 20 69 66 20 69 6e 73 75 66  ns NULL if insuf
2b530 66 69 63 69 65 6e 74 20 6d 65 6d 6f 72 79 0a 2a  ficient memory.*
2b540 2a 20 69 73 20 61 76 61 69 6c 61 62 6c 65 20 74  * is available t
2b550 6f 20 68 6f 6c 64 20 74 68 65 20 72 65 73 75 6c  o hold the resul
2b560 74 2c 20 6f 72 20 69 66 20 74 68 65 20 72 65 73  t, or if the res
2b570 75 6c 74 20 77 6f 75 6c 64 20 65 78 63 65 65 64  ult would exceed
2b580 20 74 68 65 0a 2a 2a 20 74 68 65 20 6d 61 78 69   the.** the maxi
2b590 6d 75 6d 20 73 74 72 69 6e 67 20 6c 65 6e 67 74  mum string lengt
2b5a0 68 20 64 65 74 65 72 6d 69 6e 65 64 20 62 79 20  h determined by 
2b5b0 74 68 65 20 5b 53 51 4c 49 54 45 5f 4c 49 4d 49  the [SQLITE_LIMI
2b5c0 54 5f 4c 45 4e 47 54 48 5d 2e 0a 2a 2a 0a 2a 2a  T_LENGTH]..**.**
2b5d0 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 54 52   ^The [SQLITE_TR
2b5e0 41 43 45 5f 53 49 5a 45 5f 4c 49 4d 49 54 5d 20  ACE_SIZE_LIMIT] 
2b5f0 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
2b600 69 6f 6e 20 6c 69 6d 69 74 73 20 74 68 65 20 73  ion limits the s
2b610 69 7a 65 20 6f 66 0a 2a 2a 20 62 6f 75 6e 64 20  ize of.** bound 
2b620 70 61 72 61 6d 65 74 65 72 20 65 78 70 61 6e 73  parameter expans
2b630 69 6f 6e 73 2e 20 20 5e 54 68 65 20 5b 53 51 4c  ions.  ^The [SQL
2b640 49 54 45 5f 4f 4d 49 54 5f 54 52 41 43 45 5d 20  ITE_OMIT_TRACE] 
2b650 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20  compile-time.** 
2b660 6f 70 74 69 6f 6e 20 63 61 75 73 65 73 20 73 71  option causes sq
2b670 6c 69 74 65 33 5f 65 78 70 61 6e 64 65 64 5f 73  lite3_expanded_s
2b680 71 6c 28 29 20 74 6f 20 61 6c 77 61 79 73 20 72  ql() to always r
2b690 65 74 75 72 6e 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a  eturn NULL..**.*
2b6a0 2a 20 5e 54 68 65 20 73 74 72 69 6e 67 20 72 65  * ^The string re
2b6b0 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65  turned by sqlite
2b6c0 33 5f 73 71 6c 28 50 29 20 69 73 20 6d 61 6e 61  3_sql(P) is mana
2b6d0 67 65 64 20 62 79 20 53 51 4c 69 74 65 20 61 6e  ged by SQLite an
2b6e0 64 20 69 73 0a 2a 2a 20 61 75 74 6f 6d 61 74 69  d is.** automati
2b6f0 63 61 6c 6c 79 20 66 72 65 65 64 20 77 68 65 6e  cally freed when
2b700 20 74 68 65 20 70 72 65 70 61 72 65 64 20 73 74   the prepared st
2b710 61 74 65 6d 65 6e 74 20 69 73 20 66 69 6e 61 6c  atement is final
2b720 69 7a 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 73 74  ized..** ^The st
2b730 72 69 6e 67 20 72 65 74 75 72 6e 65 64 20 62 79  ring returned by
2b740 20 73 71 6c 69 74 65 33 5f 65 78 70 61 6e 64 65   sqlite3_expande
2b750 64 5f 73 71 6c 28 50 29 2c 20 6f 6e 20 74 68 65  d_sql(P), on the
2b760 20 6f 74 68 65 72 20 68 61 6e 64 2c 0a 2a 2a 20   other hand,.** 
2b770 69 73 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  is obtained from
2b780 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
2b790 28 29 5d 20 61 6e 64 20 6d 75 73 74 20 62 65 20  ()] and must be 
2b7a0 66 72 65 65 20 62 79 20 74 68 65 20 61 70 70 6c  free by the appl
2b7b0 69 63 61 74 69 6f 6e 0a 2a 2a 20 62 79 20 70 61  ication.** by pa
2b7c0 73 73 69 6e 67 20 69 74 20 74 6f 20 5b 73 71 6c  ssing it to [sql
2b7d0 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2f  ite3_free()]..*/
2b7e0 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  .const char *sql
2b7f0 69 74 65 33 5f 73 71 6c 28 73 71 6c 69 74 65 33  ite3_sql(sqlite3
2b800 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 63  _stmt *pStmt);.c
2b810 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 65 78 70  har *sqlite3_exp
2b820 61 6e 64 65 64 5f 73 71 6c 28 73 71 6c 69 74 65  anded_sql(sqlite
2b830 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a  3_stmt *pStmt);.
2b840 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2b850 20 44 65 74 65 72 6d 69 6e 65 20 49 66 20 41 6e   Determine If An
2b860 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 57   SQL Statement W
2b870 72 69 74 65 73 20 54 68 65 20 44 61 74 61 62 61  rites The Databa
2b880 73 65 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  se.** METHOD: sq
2b890 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a  lite3_stmt.**.**
2b8a0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 74   ^The sqlite3_st
2b8b0 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 58 29 20 69  mt_readonly(X) i
2b8c0 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
2b8d0 20 74 72 75 65 20 28 6e 6f 6e 2d 7a 65 72 6f 29   true (non-zero)
2b8e0 20 69 66 0a 2a 2a 20 61 6e 64 20 6f 6e 6c 79 20   if.** and only 
2b8f0 69 66 20 74 68 65 20 5b 70 72 65 70 61 72 65 64  if the [prepared
2b900 20 73 74 61 74 65 6d 65 6e 74 5d 20 58 20 6d 61   statement] X ma
2b910 6b 65 73 20 6e 6f 20 64 69 72 65 63 74 20 63 68  kes no direct ch
2b920 61 6e 67 65 73 20 74 6f 0a 2a 2a 20 74 68 65 20  anges to.** the 
2b930 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 64  content of the d
2b940 61 74 61 62 61 73 65 20 66 69 6c 65 2e 0a 2a 2a  atabase file..**
2b950 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b 61  .** Note that [a
2b960 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
2b970 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  ed SQL functions
2b980 5d 20 6f 72 0a 2a 2a 20 5b 76 69 72 74 75 61 6c  ] or.** [virtual
2b990 20 74 61 62 6c 65 73 5d 20 6d 69 67 68 74 20 63   tables] might c
2b9a0 68 61 6e 67 65 20 74 68 65 20 64 61 74 61 62 61  hange the databa
2b9b0 73 65 20 69 6e 64 69 72 65 63 74 6c 79 20 61 73  se indirectly as
2b9c0 20 61 20 73 69 64 65 20 65 66 66 65 63 74 2e 20   a side effect. 
2b9d0 20 0a 2a 2a 20 5e 28 46 6f 72 20 65 78 61 6d 70   .** ^(For examp
2b9e0 6c 65 2c 20 69 66 20 61 6e 20 61 70 70 6c 69 63  le, if an applic
2b9f0 61 74 69 6f 6e 20 64 65 66 69 6e 65 73 20 61 20  ation defines a 
2ba00 66 75 6e 63 74 69 6f 6e 20 22 65 76 61 6c 28 29  function "eval()
2ba10 22 20 74 68 61 74 20 0a 2a 2a 20 63 61 6c 6c 73  " that .** calls
2ba20 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29   [sqlite3_exec()
2ba30 5d 2c 20 74 68 65 6e 20 74 68 65 20 66 6f 6c 6c  ], then the foll
2ba40 6f 77 69 6e 67 20 53 51 4c 20 73 74 61 74 65 6d  owing SQL statem
2ba50 65 6e 74 20 77 6f 75 6c 64 0a 2a 2a 20 63 68 61  ent would.** cha
2ba60 6e 67 65 20 74 68 65 20 64 61 74 61 62 61 73 65  nge the database
2ba70 20 66 69 6c 65 20 74 68 72 6f 75 67 68 20 73 69   file through si
2ba80 64 65 2d 65 66 66 65 63 74 73 3a 0a 2a 2a 0a 2a  de-effects:.**.*
2ba90 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70  * <blockquote><p
2baa0 72 65 3e 0a 2a 2a 20 20 20 20 53 45 4c 45 43 54  re>.**    SELECT
2bab0 20 65 76 61 6c 28 27 44 45 4c 45 54 45 20 46 52   eval('DELETE FR
2bac0 4f 4d 20 74 31 27 29 20 46 52 4f 4d 20 74 32 3b  OM t1') FROM t2;
2bad0 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63  .** </pre></bloc
2bae0 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 42 75  kquote>.**.** Bu
2baf0 74 20 62 65 63 61 75 73 65 20 74 68 65 20 5b 53  t because the [S
2bb00 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74  ELECT] statement
2bb10 20 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67 65   does not change
2bb20 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
2bb30 6c 65 0a 2a 2a 20 64 69 72 65 63 74 6c 79 2c 20  le.** directly, 
2bb40 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61  sqlite3_stmt_rea
2bb50 64 6f 6e 6c 79 28 29 20 77 6f 75 6c 64 20 73 74  donly() would st
2bb60 69 6c 6c 20 72 65 74 75 72 6e 20 74 72 75 65 2e  ill return true.
2bb70 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 72 61 6e 73 61  )^.**.** ^Transa
2bb80 63 74 69 6f 6e 20 63 6f 6e 74 72 6f 6c 20 73 74  ction control st
2bb90 61 74 65 6d 65 6e 74 73 20 73 75 63 68 20 61 73  atements such as
2bba0 20 5b 42 45 47 49 4e 5d 2c 20 5b 43 4f 4d 4d 49   [BEGIN], [COMMI
2bbb0 54 5d 2c 20 5b 52 4f 4c 4c 42 41 43 4b 5d 2c 0a  T], [ROLLBACK],.
2bbc0 2a 2a 20 5b 53 41 56 45 50 4f 49 4e 54 5d 2c 20  ** [SAVEPOINT], 
2bbd0 61 6e 64 20 5b 52 45 4c 45 41 53 45 5d 20 63 61  and [RELEASE] ca
2bbe0 75 73 65 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  use sqlite3_stmt
2bbf0 5f 72 65 61 64 6f 6e 6c 79 28 29 20 74 6f 20 72  _readonly() to r
2bc00 65 74 75 72 6e 20 74 72 75 65 2c 0a 2a 2a 20 73  eturn true,.** s
2bc10 69 6e 63 65 20 74 68 65 20 73 74 61 74 65 6d 65  ince the stateme
2bc20 6e 74 73 20 74 68 65 6d 73 65 6c 76 65 73 20 64  nts themselves d
2bc30 6f 20 6e 6f 74 20 61 63 74 75 61 6c 6c 79 20 6d  o not actually m
2bc40 6f 64 69 66 79 20 74 68 65 20 64 61 74 61 62 61  odify the databa
2bc50 73 65 20 62 75 74 0a 2a 2a 20 72 61 74 68 65 72  se but.** rather
2bc60 20 74 68 65 79 20 63 6f 6e 74 72 6f 6c 20 74 68   they control th
2bc70 65 20 74 69 6d 69 6e 67 20 6f 66 20 77 68 65 6e  e timing of when
2bc80 20 6f 74 68 65 72 20 73 74 61 74 65 6d 65 6e 74   other statement
2bc90 73 20 6d 6f 64 69 66 79 20 74 68 65 20 0a 2a 2a  s modify the .**
2bca0 20 64 61 74 61 62 61 73 65 2e 20 20 5e 54 68 65   database.  ^The
2bcb0 20 5b 41 54 54 41 43 48 5d 20 61 6e 64 20 5b 44   [ATTACH] and [D
2bcc0 45 54 41 43 48 5d 20 73 74 61 74 65 6d 65 6e 74  ETACH] statement
2bcd0 73 20 61 6c 73 6f 20 63 61 75 73 65 0a 2a 2a 20  s also cause.** 
2bce0 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61  sqlite3_stmt_rea
2bcf0 64 6f 6e 6c 79 28 29 20 74 6f 20 72 65 74 75 72  donly() to retur
2bd00 6e 20 74 72 75 65 20 73 69 6e 63 65 2c 20 77 68  n true since, wh
2bd10 69 6c 65 20 74 68 6f 73 65 20 73 74 61 74 65 6d  ile those statem
2bd20 65 6e 74 73 0a 2a 2a 20 63 68 61 6e 67 65 20 74  ents.** change t
2bd30 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  he configuration
2bd40 20 6f 66 20 61 20 64 61 74 61 62 61 73 65 20 63   of a database c
2bd50 6f 6e 6e 65 63 74 69 6f 6e 2c 20 74 68 65 79 20  onnection, they 
2bd60 64 6f 20 6e 6f 74 20 6d 61 6b 65 20 0a 2a 2a 20  do not make .** 
2bd70 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65 20 63  changes to the c
2bd80 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 64 61  ontent of the da
2bd90 74 61 62 61 73 65 20 66 69 6c 65 73 20 6f 6e 20  tabase files on 
2bda0 64 69 73 6b 2e 0a 2a 2a 20 5e 54 68 65 20 73 71  disk..** ^The sq
2bdb0 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f  lite3_stmt_reado
2bdc0 6e 6c 79 28 29 20 69 6e 74 65 72 66 61 63 65 20  nly() interface 
2bdd0 72 65 74 75 72 6e 73 20 74 72 75 65 20 66 6f 72  returns true for
2bde0 20 5b 42 45 47 49 4e 5d 20 73 69 6e 63 65 0a 2a   [BEGIN] since.*
2bdf0 2a 20 5b 42 45 47 49 4e 5d 20 6d 65 72 65 6c 79  * [BEGIN] merely
2be00 20 73 65 74 73 20 69 6e 74 65 72 6e 61 6c 20 66   sets internal f
2be10 6c 61 67 73 2c 20 62 75 74 20 74 68 65 20 5b 42  lags, but the [B
2be20 45 47 49 4e 7c 42 45 47 49 4e 20 49 4d 4d 45 44  EGIN|BEGIN IMMED
2be30 49 41 54 45 5d 20 61 6e 64 0a 2a 2a 20 5b 42 45  IATE] and.** [BE
2be40 47 49 4e 7c 42 45 47 49 4e 20 45 58 43 4c 55 53  GIN|BEGIN EXCLUS
2be50 49 56 45 5d 20 63 6f 6d 6d 61 6e 64 73 20 64 6f  IVE] commands do
2be60 20 74 6f 75 63 68 20 74 68 65 20 64 61 74 61 62   touch the datab
2be70 61 73 65 20 61 6e 64 20 73 6f 0a 2a 2a 20 73 71  ase and so.** sq
2be80 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f  lite3_stmt_reado
2be90 6e 6c 79 28 29 20 72 65 74 75 72 6e 73 20 66 61  nly() returns fa
2bea0 6c 73 65 20 66 6f 72 20 74 68 6f 73 65 20 63 6f  lse for those co
2beb0 6d 6d 61 6e 64 73 2e 0a 2a 2f 0a 69 6e 74 20 73  mmands..*/.int s
2bec0 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64  qlite3_stmt_read
2bed0 6f 6e 6c 79 28 73 71 6c 69 74 65 33 5f 73 74 6d  only(sqlite3_stm
2bee0 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a  t *pStmt);../*.*
2bef0 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 74 65  * CAPI3REF: Dete
2bf00 72 6d 69 6e 65 20 49 66 20 41 20 50 72 65 70 61  rmine If A Prepa
2bf10 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20 48 61  red Statement Ha
2bf20 73 20 42 65 65 6e 20 52 65 73 65 74 0a 2a 2a 20  s Been Reset.** 
2bf30 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f  METHOD: sqlite3_
2bf40 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  stmt.**.** ^The 
2bf50 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 62 75 73  sqlite3_stmt_bus
2bf60 79 28 53 29 20 69 6e 74 65 72 66 61 63 65 20 72  y(S) interface r
2bf70 65 74 75 72 6e 73 20 74 72 75 65 20 28 6e 6f 6e  eturns true (non
2bf80 2d 7a 65 72 6f 29 20 69 66 20 74 68 65 0a 2a 2a  -zero) if the.**
2bf90 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2bfa0 6d 65 6e 74 5d 20 53 20 68 61 73 20 62 65 65 6e  ment] S has been
2bfb0 20 73 74 65 70 70 65 64 20 61 74 20 6c 65 61 73   stepped at leas
2bfc0 74 20 6f 6e 63 65 20 75 73 69 6e 67 20 0a 2a 2a  t once using .**
2bfd0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53   [sqlite3_step(S
2bfe0 29 5d 20 62 75 74 20 68 61 73 20 6e 65 69 74 68  )] but has neith
2bff0 65 72 20 72 75 6e 20 74 6f 20 63 6f 6d 70 6c 65  er run to comple
2c000 74 69 6f 6e 20 28 72 65 74 75 72 6e 65 64 0a 2a  tion (returned.*
2c010 2a 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 20  * [SQLITE_DONE] 
2c020 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 73 74  from [sqlite3_st
2c030 65 70 28 53 29 5d 29 20 6e 6f 72 0a 2a 2a 20 62  ep(S)]) nor.** b
2c040 65 65 6e 20 72 65 73 65 74 20 75 73 69 6e 67 20  een reset using 
2c050 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53  [sqlite3_reset(S
2c060 29 5d 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65  )].  ^The sqlite
2c070 33 5f 73 74 6d 74 5f 62 75 73 79 28 53 29 0a 2a  3_stmt_busy(S).*
2c080 2a 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  * interface retu
2c090 72 6e 73 20 66 61 6c 73 65 20 69 66 20 53 20 69  rns false if S i
2c0a0 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
2c0b0 2e 20 20 49 66 20 53 20 69 73 20 6e 6f 74 20 61  .  If S is not a
2c0c0 20 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65   .** NULL pointe
2c0d0 72 20 61 6e 64 20 69 73 20 6e 6f 74 20 61 20 70  r and is not a p
2c0e0 6f 69 6e 74 65 72 20 74 6f 20 61 20 76 61 6c 69  ointer to a vali
2c0f0 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  d [prepared stat
2c100 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 6a 65 63 74  ement].** object
2c110 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76  , then the behav
2c120 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64  ior is undefined
2c130 20 61 6e 64 20 70 72 6f 62 61 62 6c 79 20 75 6e   and probably un
2c140 64 65 73 69 72 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a  desirable..**.**
2c150 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20   This interface 
2c160 63 61 6e 20 62 65 20 75 73 65 64 20 69 6e 20 63  can be used in c
2c170 6f 6d 62 69 6e 61 74 69 6f 6e 20 5b 73 71 6c 69  ombination [sqli
2c180 74 65 33 5f 6e 65 78 74 5f 73 74 6d 74 28 29 5d  te3_next_stmt()]
2c190 0a 2a 2a 20 74 6f 20 6c 6f 63 61 74 65 20 61 6c  .** to locate al
2c1a0 6c 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  l prepared state
2c1b0 6d 65 6e 74 73 20 61 73 73 6f 63 69 61 74 65 64  ments associated
2c1c0 20 77 69 74 68 20 61 20 64 61 74 61 62 61 73 65   with a database
2c1d0 20 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20   .** connection 
2c1e0 74 68 61 74 20 61 72 65 20 69 6e 20 6e 65 65 64  that are in need
2c1f0 20 6f 66 20 62 65 69 6e 67 20 72 65 73 65 74 2e   of being reset.
2c200 20 20 54 68 69 73 20 63 61 6e 20 62 65 20 75 73    This can be us
2c210 65 64 2c 0a 2a 2a 20 66 6f 72 20 65 78 61 6d 70  ed,.** for examp
2c220 6c 65 2c 20 69 6e 20 64 69 61 67 6e 6f 73 74 69  le, in diagnosti
2c230 63 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 73 65  c routines to se
2c240 61 72 63 68 20 66 6f 72 20 70 72 65 70 61 72 65  arch for prepare
2c250 64 20 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 73  d .** statements
2c260 20 74 68 61 74 20 61 72 65 20 68 6f 6c 64 69 6e   that are holdin
2c270 67 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  g a transaction 
2c280 6f 70 65 6e 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  open..*/.int sql
2c290 69 74 65 33 5f 73 74 6d 74 5f 62 75 73 79 28 73  ite3_stmt_busy(s
2c2a0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a  qlite3_stmt*);..
2c2b0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
2c2c0 44 79 6e 61 6d 69 63 61 6c 6c 79 20 54 79 70 65  Dynamically Type
2c2d0 64 20 56 61 6c 75 65 20 4f 62 6a 65 63 74 0a 2a  d Value Object.*
2c2e0 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70 72 6f  * KEYWORDS: {pro
2c2f0 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
2c300 61 6c 75 65 7d 20 7b 75 6e 70 72 6f 74 65 63 74  alue} {unprotect
2c310 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
2c320 7d 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75  }.**.** SQLite u
2c330 73 65 73 20 74 68 65 20 73 71 6c 69 74 65 33 5f  ses the sqlite3_
2c340 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 74 6f 20  value object to 
2c350 72 65 70 72 65 73 65 6e 74 20 61 6c 6c 20 76 61  represent all va
2c360 6c 75 65 73 0a 2a 2a 20 74 68 61 74 20 63 61 6e  lues.** that can
2c370 20 62 65 20 73 74 6f 72 65 64 20 69 6e 20 61 20   be stored in a 
2c380 64 61 74 61 62 61 73 65 20 74 61 62 6c 65 2e 20  database table. 
2c390 53 51 4c 69 74 65 20 75 73 65 73 20 64 79 6e 61  SQLite uses dyna
2c3a0 6d 69 63 20 74 79 70 69 6e 67 0a 2a 2a 20 66 6f  mic typing.** fo
2c3b0 72 20 74 68 65 20 76 61 6c 75 65 73 20 69 74 20  r the values it 
2c3c0 73 74 6f 72 65 73 2e 20 20 5e 56 61 6c 75 65 73  stores.  ^Values
2c3d0 20 73 74 6f 72 65 64 20 69 6e 20 73 71 6c 69 74   stored in sqlit
2c3e0 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73  e3_value objects
2c3f0 0a 2a 2a 20 63 61 6e 20 62 65 20 69 6e 74 65 67  .** can be integ
2c400 65 72 73 2c 20 66 6c 6f 61 74 69 6e 67 20 70 6f  ers, floating po
2c410 69 6e 74 20 76 61 6c 75 65 73 2c 20 73 74 72 69  int values, stri
2c420 6e 67 73 2c 20 42 4c 4f 42 73 2c 20 6f 72 20 4e  ngs, BLOBs, or N
2c430 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 73 71  ULL..**.** An sq
2c440 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
2c450 63 74 20 6d 61 79 20 62 65 20 65 69 74 68 65 72  ct may be either
2c460 20 22 70 72 6f 74 65 63 74 65 64 22 20 6f 72 20   "protected" or 
2c470 22 75 6e 70 72 6f 74 65 63 74 65 64 22 2e 0a 2a  "unprotected"..*
2c480 2a 20 53 6f 6d 65 20 69 6e 74 65 72 66 61 63 65  * Some interface
2c490 73 20 72 65 71 75 69 72 65 20 61 20 70 72 6f 74  s require a prot
2c4a0 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
2c4b0 6c 75 65 2e 20 20 4f 74 68 65 72 20 69 6e 74 65  lue.  Other inte
2c4c0 72 66 61 63 65 73 0a 2a 2a 20 77 69 6c 6c 20 61  rfaces.** will a
2c4d0 63 63 65 70 74 20 65 69 74 68 65 72 20 61 20 70  ccept either a p
2c4e0 72 6f 74 65 63 74 65 64 20 6f 72 20 61 6e 20 75  rotected or an u
2c4f0 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  nprotected sqlit
2c500 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a 20 45 76 65  e3_value..** Eve
2c510 72 79 20 69 6e 74 65 72 66 61 63 65 20 74 68 61  ry interface tha
2c520 74 20 61 63 63 65 70 74 73 20 73 71 6c 69 74 65  t accepts sqlite
2c530 33 5f 76 61 6c 75 65 20 61 72 67 75 6d 65 6e 74  3_value argument
2c540 73 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 77  s specifies.** w
2c550 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 69 74  hether or not it
2c560 20 72 65 71 75 69 72 65 73 20 61 20 70 72 6f 74   requires a prot
2c570 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
2c580 6c 75 65 2e 20 20 54 68 65 0a 2a 2a 20 5b 73 71  lue.  The.** [sq
2c590 6c 69 74 65 33 5f 76 61 6c 75 65 5f 64 75 70 28  lite3_value_dup(
2c5a0 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e  )] interface can
2c5b0 20 62 65 20 75 73 65 64 20 74 6f 20 63 6f 6e 73   be used to cons
2c5c0 74 72 75 63 74 20 61 20 6e 65 77 20 0a 2a 2a 20  truct a new .** 
2c5d0 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
2c5e0 33 5f 76 61 6c 75 65 20 66 72 6f 6d 20 61 6e 20  3_value from an 
2c5f0 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  unprotected sqli
2c600 74 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a  te3_value..**.**
2c610 20 54 68 65 20 74 65 72 6d 73 20 22 70 72 6f 74   The terms "prot
2c620 65 63 74 65 64 22 20 61 6e 64 20 22 75 6e 70 72  ected" and "unpr
2c630 6f 74 65 63 74 65 64 22 20 72 65 66 65 72 20 74  otected" refer t
2c640 6f 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  o whether or not
2c650 0a 2a 2a 20 61 20 6d 75 74 65 78 20 69 73 20 68  .** a mutex is h
2c660 65 6c 64 2e 20 20 41 6e 20 69 6e 74 65 72 6e 61  eld.  An interna
2c670 6c 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64 20  l mutex is held 
2c680 66 6f 72 20 61 20 70 72 6f 74 65 63 74 65 64 0a  for a protected.
2c690 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ** sqlite3_value
2c6a0 20 6f 62 6a 65 63 74 20 62 75 74 20 6e 6f 20 6d   object but no m
2c6b0 75 74 65 78 20 69 73 20 68 65 6c 64 20 66 6f 72  utex is held for
2c6c0 20 61 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 0a   an unprotected.
2c6d0 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ** sqlite3_value
2c6e0 20 6f 62 6a 65 63 74 2e 20 20 49 66 20 53 51 4c   object.  If SQL
2c6f0 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20  ite is compiled 
2c700 74 6f 20 62 65 20 73 69 6e 67 6c 65 2d 74 68 72  to be single-thr
2c710 65 61 64 65 64 0a 2a 2a 20 28 77 69 74 68 20 5b  eaded.** (with [
2c720 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
2c730 45 3d 30 5d 20 61 6e 64 20 77 69 74 68 20 5b 73  E=0] and with [s
2c740 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73 61 66  qlite3_threadsaf
2c750 65 28 29 5d 20 72 65 74 75 72 6e 69 6e 67 20 30  e()] returning 0
2c760 29 0a 2a 2a 20 6f 72 20 69 66 20 53 51 4c 69 74  ).** or if SQLit
2c770 65 20 69 73 20 72 75 6e 20 69 6e 20 6f 6e 65 20  e is run in one 
2c780 6f 66 20 72 65 64 75 63 65 64 20 6d 75 74 65 78  of reduced mutex
2c790 20 6d 6f 64 65 73 20 0a 2a 2a 20 5b 53 51 4c 49   modes .** [SQLI
2c7a0 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45  TE_CONFIG_SINGLE
2c7b0 54 48 52 45 41 44 5d 20 6f 72 20 5b 53 51 4c 49  THREAD] or [SQLI
2c7c0 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54  TE_CONFIG_MULTIT
2c7d0 48 52 45 41 44 5d 0a 2a 2a 20 74 68 65 6e 20 74  HREAD].** then t
2c7e0 68 65 72 65 20 69 73 20 6e 6f 20 64 69 73 74 69  here is no disti
2c7f0 6e 63 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 70  nction between p
2c800 72 6f 74 65 63 74 65 64 20 61 6e 64 20 75 6e 70  rotected and unp
2c810 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69  rotected.** sqli
2c820 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
2c830 73 20 61 6e 64 20 74 68 65 79 20 63 61 6e 20 62  s and they can b
2c840 65 20 75 73 65 64 20 69 6e 74 65 72 63 68 61 6e  e used interchan
2c850 67 65 61 62 6c 79 2e 20 20 48 6f 77 65 76 65 72  geably.  However
2c860 2c 0a 2a 2a 20 66 6f 72 20 6d 61 78 69 6d 75 6d  ,.** for maximum
2c870 20 63 6f 64 65 20 70 6f 72 74 61 62 69 6c 69 74   code portabilit
2c880 79 20 69 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e  y it is recommen
2c890 64 65 64 20 74 68 61 74 20 61 70 70 6c 69 63 61  ded that applica
2c8a0 74 69 6f 6e 73 0a 2a 2a 20 73 74 69 6c 6c 20 6d  tions.** still m
2c8b0 61 6b 65 20 74 68 65 20 64 69 73 74 69 6e 63 74  ake the distinct
2c8c0 69 6f 6e 20 62 65 74 77 65 65 6e 20 70 72 6f 74  ion between prot
2c8d0 65 63 74 65 64 20 61 6e 64 20 75 6e 70 72 6f 74  ected and unprot
2c8e0 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33  ected.** sqlite3
2c8f0 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 65  _value objects e
2c900 76 65 6e 20 77 68 65 6e 20 6e 6f 74 20 73 74 72  ven when not str
2c910 69 63 74 6c 79 20 72 65 71 75 69 72 65 64 2e 0a  ictly required..
2c920 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
2c930 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73  e3_value objects
2c940 20 74 68 61 74 20 61 72 65 20 70 61 73 73 65 64   that are passed
2c950 20 61 73 20 70 61 72 61 6d 65 74 65 72 73 20 69   as parameters i
2c960 6e 74 6f 20 74 68 65 0a 2a 2a 20 69 6d 70 6c 65  nto the.** imple
2c970 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 5b 61 70  mentation of [ap
2c980 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
2c990 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d  d SQL functions]
2c9a0 20 61 72 65 20 70 72 6f 74 65 63 74 65 64 2e 0a   are protected..
2c9b0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
2c9c0 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 72 65 74  value object ret
2c9d0 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c  urned by.** [sql
2c9e0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75  ite3_column_valu
2c9f0 65 28 29 5d 20 69 73 20 75 6e 70 72 6f 74 65 63  e()] is unprotec
2ca00 74 65 64 2e 0a 2a 2a 20 55 6e 70 72 6f 74 65 63  ted..** Unprotec
2ca10 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
2ca20 65 20 6f 62 6a 65 63 74 73 20 6d 61 79 20 6f 6e  e objects may on
2ca30 6c 79 20 62 65 20 75 73 65 64 20 77 69 74 68 0a  ly be used with.
2ca40 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75  ** [sqlite3_resu
2ca50 6c 74 5f 76 61 6c 75 65 28 29 5d 20 61 6e 64 20  lt_value()] and 
2ca60 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61  [sqlite3_bind_va
2ca70 6c 75 65 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 5b  lue()]..** The [
2ca80 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c  sqlite3_value_bl
2ca90 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f 76 61 6c  ob | sqlite3_val
2caa0 75 65 5f 74 79 70 65 28 29 5d 20 66 61 6d 69 6c  ue_type()] famil
2cab0 79 20 6f 66 0a 2a 2a 20 69 6e 74 65 72 66 61 63  y of.** interfac
2cac0 65 73 20 72 65 71 75 69 72 65 20 70 72 6f 74 65  es require prote
2cad0 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
2cae0 75 65 20 6f 62 6a 65 63 74 73 2e 0a 2a 2f 0a 74  ue objects..*/.t
2caf0 79 70 65 64 65 66 20 73 74 72 75 63 74 20 4d 65  ypedef struct Me
2cb00 6d 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 3b  m sqlite3_value;
2cb10 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2cb20 3a 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 20 43  : SQL Function C
2cb30 6f 6e 74 65 78 74 20 4f 62 6a 65 63 74 0a 2a 2a  ontext Object.**
2cb40 0a 2a 2a 20 54 68 65 20 63 6f 6e 74 65 78 74 20  .** The context 
2cb50 69 6e 20 77 68 69 63 68 20 61 6e 20 53 51 4c 20  in which an SQL 
2cb60 66 75 6e 63 74 69 6f 6e 20 65 78 65 63 75 74 65  function execute
2cb70 73 20 69 73 20 73 74 6f 72 65 64 20 69 6e 20 61  s is stored in a
2cb80 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6e  n.** sqlite3_con
2cb90 74 65 78 74 20 6f 62 6a 65 63 74 2e 20 20 5e 41  text object.  ^A
2cba0 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 73   pointer to an s
2cbb0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 6f  qlite3_context o
2cbc0 62 6a 65 63 74 0a 2a 2a 20 69 73 20 61 6c 77 61  bject.** is alwa
2cbd0 79 73 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  ys first paramet
2cbe0 65 72 20 74 6f 20 5b 61 70 70 6c 69 63 61 74 69  er to [applicati
2cbf0 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66  on-defined SQL f
2cc00 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 54 68  unctions]..** Th
2cc10 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  e application-de
2cc20 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69  fined SQL functi
2cc30 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  on implementatio
2cc40 6e 20 77 69 6c 6c 20 70 61 73 73 20 74 68 69 73  n will pass this
2cc50 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74 68 72 6f  .** pointer thro
2cc60 75 67 68 20 69 6e 74 6f 20 63 61 6c 6c 73 20 74  ugh into calls t
2cc70 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  o [sqlite3_resul
2cc80 74 5f 69 6e 74 20 7c 20 73 71 6c 69 74 65 33 5f  t_int | sqlite3_
2cc90 72 65 73 75 6c 74 28 29 5d 2c 0a 2a 2a 20 5b 73  result()],.** [s
2cca0 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65  qlite3_aggregate
2ccb0 5f 63 6f 6e 74 65 78 74 28 29 5d 2c 20 5b 73 71  _context()], [sq
2ccc0 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28  lite3_user_data(
2ccd0 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  )],.** [sqlite3_
2cce0 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c  context_db_handl
2ccf0 65 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 67  e()], [sqlite3_g
2cd00 65 74 5f 61 75 78 64 61 74 61 28 29 5d 2c 0a 2a  et_auxdata()],.*
2cd10 2a 20 61 6e 64 2f 6f 72 20 5b 73 71 6c 69 74 65  * and/or [sqlite
2cd20 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 5d  3_set_auxdata()]
2cd30 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72  ..*/.typedef str
2cd40 75 63 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74  uct sqlite3_cont
2cd50 65 78 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ext sqlite3_cont
2cd60 65 78 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ext;../*.** CAPI
2cd70 33 52 45 46 3a 20 42 69 6e 64 69 6e 67 20 56 61  3REF: Binding Va
2cd80 6c 75 65 73 20 54 6f 20 50 72 65 70 61 72 65 64  lues To Prepared
2cd90 20 53 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 4b   Statements.** K
2cda0 45 59 57 4f 52 44 53 3a 20 7b 68 6f 73 74 20 70  EYWORDS: {host p
2cdb0 61 72 61 6d 65 74 65 72 7d 20 7b 68 6f 73 74 20  arameter} {host 
2cdc0 70 61 72 61 6d 65 74 65 72 73 7d 20 7b 68 6f 73  parameters} {hos
2cdd0 74 20 70 61 72 61 6d 65 74 65 72 20 6e 61 6d 65  t parameter name
2cde0 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  }.** KEYWORDS: {
2cdf0 53 51 4c 20 70 61 72 61 6d 65 74 65 72 7d 20 7b  SQL parameter} {
2ce00 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 7d 20  SQL parameters} 
2ce10 7b 70 61 72 61 6d 65 74 65 72 20 62 69 6e 64 69  {parameter bindi
2ce20 6e 67 7d 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  ng}.** METHOD: s
2ce30 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a  qlite3_stmt.**.*
2ce40 2a 20 5e 28 49 6e 20 74 68 65 20 53 51 4c 20 73  * ^(In the SQL s
2ce50 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20 69 6e  tatement text in
2ce60 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  put to [sqlite3_
2ce70 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e  prepare_v2()] an
2ce80 64 20 69 74 73 20 76 61 72 69 61 6e 74 73 2c 0a  d its variants,.
2ce90 2a 2a 20 6c 69 74 65 72 61 6c 73 20 6d 61 79 20  ** literals may 
2cea0 62 65 20 72 65 70 6c 61 63 65 64 20 62 79 20 61  be replaced by a
2ceb0 20 5b 70 61 72 61 6d 65 74 65 72 5d 20 74 68 61   [parameter] tha
2cec0 74 20 6d 61 74 63 68 65 73 20 6f 6e 65 20 6f 66  t matches one of
2ced0 20 66 6f 6c 6c 6f 77 69 6e 67 0a 2a 2a 20 74 65   following.** te
2cee0 6d 70 6c 61 74 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c  mplates:.**.** <
2cef0 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 0a 2a  ul>.** <li>  ?.*
2cf00 2a 20 3c 6c 69 3e 20 20 3f 4e 4e 4e 0a 2a 2a 20  * <li>  ?NNN.** 
2cf10 3c 6c 69 3e 20 20 3a 56 56 56 0a 2a 2a 20 3c 6c  <li>  :VVV.** <l
2cf20 69 3e 20 20 40 56 56 56 0a 2a 2a 20 3c 6c 69 3e  i>  @VVV.** <li>
2cf30 20 20 24 56 56 56 0a 2a 2a 20 3c 2f 75 6c 3e 0a    $VVV.** </ul>.
2cf40 2a 2a 0a 2a 2a 20 49 6e 20 74 68 65 20 74 65 6d  **.** In the tem
2cf50 70 6c 61 74 65 73 20 61 62 6f 76 65 2c 20 4e 4e  plates above, NN
2cf60 4e 20 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20  N represents an 
2cf70 69 6e 74 65 67 65 72 20 6c 69 74 65 72 61 6c 2c  integer literal,
2cf80 0a 2a 2a 20 61 6e 64 20 56 56 56 20 72 65 70 72  .** and VVV repr
2cf90 65 73 65 6e 74 73 20 61 6e 20 61 6c 70 68 61 6e  esents an alphan
2cfa0 75 6d 65 72 69 63 20 69 64 65 6e 74 69 66 69 65  umeric identifie
2cfb0 72 2e 29 5e 20 20 5e 54 68 65 20 76 61 6c 75 65  r.)^  ^The value
2cfc0 73 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 70 61  s of these.** pa
2cfd0 72 61 6d 65 74 65 72 73 20 28 61 6c 73 6f 20 63  rameters (also c
2cfe0 61 6c 6c 65 64 20 22 68 6f 73 74 20 70 61 72 61  alled "host para
2cff0 6d 65 74 65 72 20 6e 61 6d 65 73 22 20 6f 72 20  meter names" or 
2d000 22 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 22  "SQL parameters"
2d010 29 0a 2a 2a 20 63 61 6e 20 62 65 20 73 65 74 20  ).** can be set 
2d020 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69 74 65  using the sqlite
2d030 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69  3_bind_*() routi
2d040 6e 65 73 20 64 65 66 69 6e 65 64 20 68 65 72 65  nes defined here
2d050 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72  ..**.** ^The fir
2d060 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  st argument to t
2d070 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  he sqlite3_bind_
2d080 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 69 73 20  *() routines is 
2d090 61 6c 77 61 79 73 0a 2a 2a 20 61 20 70 6f 69 6e  always.** a poin
2d0a0 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69  ter to the [sqli
2d0b0 74 65 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74  te3_stmt] object
2d0c0 20 72 65 74 75 72 6e 65 64 20 66 72 6f 6d 0a 2a   returned from.*
2d0d0 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  * [sqlite3_prepa
2d0e0 72 65 5f 76 32 28 29 5d 20 6f 72 20 69 74 73 20  re_v2()] or its 
2d0f0 76 61 72 69 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20  variants..**.** 
2d100 5e 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75  ^The second argu
2d110 6d 65 6e 74 20 69 73 20 74 68 65 20 69 6e 64 65  ment is the inde
2d120 78 20 6f 66 20 74 68 65 20 53 51 4c 20 70 61 72  x of the SQL par
2d130 61 6d 65 74 65 72 20 74 6f 20 62 65 20 73 65 74  ameter to be set
2d140 2e 0a 2a 2a 20 5e 54 68 65 20 6c 65 66 74 6d 6f  ..** ^The leftmo
2d150 73 74 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72  st SQL parameter
2d160 20 68 61 73 20 61 6e 20 69 6e 64 65 78 20 6f 66   has an index of
2d170 20 31 2e 20 20 5e 57 68 65 6e 20 74 68 65 20 73   1.  ^When the s
2d180 61 6d 65 20 6e 61 6d 65 64 0a 2a 2a 20 53 51 4c  ame named.** SQL
2d190 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 75 73   parameter is us
2d1a0 65 64 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 63  ed more than onc
2d1b0 65 2c 20 73 65 63 6f 6e 64 20 61 6e 64 20 73 75  e, second and su
2d1c0 62 73 65 71 75 65 6e 74 0a 2a 2a 20 6f 63 63 75  bsequent.** occu
2d1d0 72 72 65 6e 63 65 73 20 68 61 76 65 20 74 68 65  rrences have the
2d1e0 20 73 61 6d 65 20 69 6e 64 65 78 20 61 73 20 74   same index as t
2d1f0 68 65 20 66 69 72 73 74 20 6f 63 63 75 72 72 65  he first occurre
2d200 6e 63 65 2e 0a 2a 2a 20 5e 54 68 65 20 69 6e 64  nce..** ^The ind
2d210 65 78 20 66 6f 72 20 6e 61 6d 65 64 20 70 61 72  ex for named par
2d220 61 6d 65 74 65 72 73 20 63 61 6e 20 62 65 20 6c  ameters can be l
2d230 6f 6f 6b 65 64 20 75 70 20 75 73 69 6e 67 20 74  ooked up using t
2d240 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  he.** [sqlite3_b
2d250 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e  ind_parameter_in
2d260 64 65 78 28 29 5d 20 41 50 49 20 69 66 20 64 65  dex()] API if de
2d270 73 69 72 65 64 2e 20 20 5e 54 68 65 20 69 6e 64  sired.  ^The ind
2d280 65 78 0a 2a 2a 20 66 6f 72 20 22 3f 4e 4e 4e 22  ex.** for "?NNN"
2d290 20 70 61 72 61 6d 65 74 65 72 73 20 69 73 20 74   parameters is t
2d2a0 68 65 20 76 61 6c 75 65 20 6f 66 20 4e 4e 4e 2e  he value of NNN.
2d2b0 0a 2a 2a 20 5e 54 68 65 20 4e 4e 4e 20 76 61 6c  .** ^The NNN val
2d2c0 75 65 20 6d 75 73 74 20 62 65 20 62 65 74 77 65  ue must be betwe
2d2d0 65 6e 20 31 20 61 6e 64 20 74 68 65 20 5b 73 71  en 1 and the [sq
2d2e0 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a  lite3_limit()].*
2d2f0 2a 20 70 61 72 61 6d 65 74 65 72 20 5b 53 51 4c  * parameter [SQL
2d300 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42  ITE_LIMIT_VARIAB
2d310 4c 45 5f 4e 55 4d 42 45 52 5d 20 28 64 65 66 61  LE_NUMBER] (defa
2d320 75 6c 74 20 76 61 6c 75 65 3a 20 39 39 39 29 2e  ult value: 999).
2d330 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74 68 69 72  .**.** ^The thir
2d340 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68  d argument is th
2d350 65 20 76 61 6c 75 65 20 74 6f 20 62 69 6e 64 20  e value to bind 
2d360 74 6f 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  to the parameter
2d370 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 74 68 69  ..** ^If the thi
2d380 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  rd parameter to 
2d390 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
2d3a0 74 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 62  t() or sqlite3_b
2d3b0 69 6e 64 5f 74 65 78 74 31 36 28 29 0a 2a 2a 20  ind_text16().** 
2d3c0 6f 72 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  or sqlite3_bind_
2d3d0 62 6c 6f 62 28 29 20 69 73 20 61 20 4e 55 4c 4c  blob() is a NULL
2d3e0 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 74 68   pointer then th
2d3f0 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
2d400 65 72 0a 2a 2a 20 69 73 20 69 67 6e 6f 72 65 64  er.** is ignored
2d410 20 61 6e 64 20 74 68 65 20 65 6e 64 20 72 65 73   and the end res
2d420 75 6c 74 20 69 73 20 74 68 65 20 73 61 6d 65 20  ult is the same 
2d430 61 73 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  as sqlite3_bind_
2d440 6e 75 6c 6c 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 28  null()..**.** ^(
2d450 49 6e 20 74 68 6f 73 65 20 72 6f 75 74 69 6e 65  In those routine
2d460 73 20 74 68 61 74 20 68 61 76 65 20 61 20 66 6f  s that have a fo
2d470 75 72 74 68 20 61 72 67 75 6d 65 6e 74 2c 20 69  urth argument, i
2d480 74 73 20 76 61 6c 75 65 20 69 73 20 74 68 65 0a  ts value is the.
2d490 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  ** number of byt
2d4a0 65 73 20 69 6e 20 74 68 65 20 70 61 72 61 6d 65  es in the parame
2d4b0 74 65 72 2e 20 20 54 6f 20 62 65 20 63 6c 65 61  ter.  To be clea
2d4c0 72 3a 20 74 68 65 20 76 61 6c 75 65 20 69 73 20  r: the value is 
2d4d0 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66  the.** number of
2d4e0 20 3c 75 3e 62 79 74 65 73 3c 2f 75 3e 20 69 6e   <u>bytes</u> in
2d4f0 20 74 68 65 20 76 61 6c 75 65 2c 20 6e 6f 74 20   the value, not 
2d500 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68  the number of ch
2d510 61 72 61 63 74 65 72 73 2e 29 5e 0a 2a 2a 20 5e  aracters.)^.** ^
2d520 49 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61  If the fourth pa
2d530 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
2d540 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 29 20 6f  e3_bind_text() o
2d550 72 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74  r sqlite3_bind_t
2d560 65 78 74 31 36 28 29 0a 2a 2a 20 69 73 20 6e 65  ext16().** is ne
2d570 67 61 74 69 76 65 2c 20 74 68 65 6e 20 74 68 65  gative, then the
2d580 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20 73   length of the s
2d590 74 72 69 6e 67 20 69 73 0a 2a 2a 20 74 68 65 20  tring is.** the 
2d5a0 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
2d5b0 75 70 20 74 6f 20 74 68 65 20 66 69 72 73 74 20  up to the first 
2d5c0 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e  zero terminator.
2d5d0 0a 2a 2a 20 49 66 20 74 68 65 20 66 6f 75 72 74  .** If the fourt
2d5e0 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  h parameter to s
2d5f0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
2d600 28 29 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20  () is negative, 
2d610 74 68 65 6e 0a 2a 2a 20 74 68 65 20 62 65 68 61  then.** the beha
2d620 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65  vior is undefine
2d630 64 2e 0a 2a 2a 20 49 66 20 61 20 6e 6f 6e 2d 6e  d..** If a non-n
2d640 65 67 61 74 69 76 65 20 66 6f 75 72 74 68 20 70  egative fourth p
2d650 61 72 61 6d 65 74 65 72 20 69 73 20 70 72 6f 76  arameter is prov
2d660 69 64 65 64 20 74 6f 20 73 71 6c 69 74 65 33 5f  ided to sqlite3_
2d670 62 69 6e 64 5f 74 65 78 74 28 29 0a 2a 2a 20 6f  bind_text().** o
2d680 72 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74  r sqlite3_bind_t
2d690 65 78 74 31 36 28 29 20 6f 72 20 73 71 6c 69 74  ext16() or sqlit
2d6a0 65 33 5f 62 69 6e 64 5f 74 65 78 74 36 34 28 29  e3_bind_text64()
2d6b0 20 74 68 65 6e 0a 2a 2a 20 74 68 61 74 20 70 61   then.** that pa
2d6c0 72 61 6d 65 74 65 72 20 6d 75 73 74 20 62 65 20  rameter must be 
2d6d0 74 68 65 20 62 79 74 65 20 6f 66 66 73 65 74 0a  the byte offset.
2d6e0 2a 2a 20 77 68 65 72 65 20 74 68 65 20 4e 55 4c  ** where the NUL
2d6f0 20 74 65 72 6d 69 6e 61 74 6f 72 20 77 6f 75 6c   terminator woul
2d700 64 20 6f 63 63 75 72 20 61 73 73 75 6d 69 6e 67  d occur assuming
2d710 20 74 68 65 20 73 74 72 69 6e 67 20 77 65 72 65   the string were
2d720 20 4e 55 4c 0a 2a 2a 20 74 65 72 6d 69 6e 61 74   NUL.** terminat
2d730 65 64 2e 20 20 49 66 20 61 6e 79 20 4e 55 4c 20  ed.  If any NUL 
2d740 63 68 61 72 61 63 74 65 72 73 20 6f 63 63 75 72  characters occur
2d750 20 61 74 20 62 79 74 65 20 6f 66 66 73 65 74 73   at byte offsets
2d760 20 6c 65 73 73 20 74 68 61 6e 20 0a 2a 2a 20 74   less than .** t
2d770 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20  he value of the 
2d780 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
2d790 20 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74   then the result
2d7a0 69 6e 67 20 73 74 72 69 6e 67 20 76 61 6c 75 65  ing string value
2d7b0 20 77 69 6c 6c 0a 2a 2a 20 63 6f 6e 74 61 69 6e   will.** contain
2d7c0 20 65 6d 62 65 64 64 65 64 20 4e 55 4c 73 2e 20   embedded NULs. 
2d7d0 20 54 68 65 20 72 65 73 75 6c 74 20 6f 66 20 65   The result of e
2d7e0 78 70 72 65 73 73 69 6f 6e 73 20 69 6e 76 6f 6c  xpressions invol
2d7f0 76 69 6e 67 20 73 74 72 69 6e 67 73 0a 2a 2a 20  ving strings.** 
2d800 77 69 74 68 20 65 6d 62 65 64 64 65 64 20 4e 55  with embedded NU
2d810 4c 73 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e  Ls is undefined.
2d820 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 66 74  .**.** ^The fift
2d830 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  h argument to th
2d840 65 20 42 4c 4f 42 20 61 6e 64 20 73 74 72 69 6e  e BLOB and strin
2d850 67 20 62 69 6e 64 69 6e 67 20 69 6e 74 65 72 66  g binding interf
2d860 61 63 65 73 0a 2a 2a 20 69 73 20 61 20 64 65 73  aces.** is a des
2d870 74 72 75 63 74 6f 72 20 75 73 65 64 20 74 6f 20  tructor used to 
2d880 64 69 73 70 6f 73 65 20 6f 66 20 74 68 65 20 42  dispose of the B
2d890 4c 4f 42 20 6f 72 0a 2a 2a 20 73 74 72 69 6e 67  LOB or.** string
2d8a0 20 61 66 74 65 72 20 53 51 4c 69 74 65 20 68 61   after SQLite ha
2d8b0 73 20 66 69 6e 69 73 68 65 64 20 77 69 74 68 20  s finished with 
2d8c0 69 74 2e 20 20 5e 54 68 65 20 64 65 73 74 72 75  it.  ^The destru
2d8d0 63 74 6f 72 20 69 73 20 63 61 6c 6c 65 64 0a 2a  ctor is called.*
2d8e0 2a 20 74 6f 20 64 69 73 70 6f 73 65 20 6f 66 20  * to dispose of 
2d8f0 74 68 65 20 42 4c 4f 42 20 6f 72 20 73 74 72 69  the BLOB or stri
2d900 6e 67 20 65 76 65 6e 20 69 66 20 74 68 65 20 63  ng even if the c
2d910 61 6c 6c 20 74 6f 20 62 69 6e 64 20 41 50 49 20  all to bind API 
2d920 66 61 69 6c 73 2e 0a 2a 2a 20 5e 49 66 20 74 68  fails..** ^If th
2d930 65 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74  e fifth argument
2d940 20 69 73 0a 2a 2a 20 74 68 65 20 73 70 65 63 69   is.** the speci
2d950 61 6c 20 76 61 6c 75 65 20 5b 53 51 4c 49 54 45  al value [SQLITE
2d960 5f 53 54 41 54 49 43 5d 2c 20 74 68 65 6e 20 53  _STATIC], then S
2d970 51 4c 69 74 65 20 61 73 73 75 6d 65 73 20 74 68  QLite assumes th
2d980 61 74 20 74 68 65 0a 2a 2a 20 69 6e 66 6f 72 6d  at the.** inform
2d990 61 74 69 6f 6e 20 69 73 20 69 6e 20 73 74 61 74  ation is in stat
2d9a0 69 63 2c 20 75 6e 6d 61 6e 61 67 65 64 20 73 70  ic, unmanaged sp
2d9b0 61 63 65 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74  ace and does not
2d9c0 20 6e 65 65 64 20 74 6f 20 62 65 20 66 72 65 65   need to be free
2d9d0 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69  d..** ^If the fi
2d9e0 66 74 68 20 61 72 67 75 6d 65 6e 74 20 68 61 73  fth argument has
2d9f0 20 74 68 65 20 76 61 6c 75 65 20 5b 53 51 4c 49   the value [SQLI
2da00 54 45 5f 54 52 41 4e 53 49 45 4e 54 5d 2c 20 74  TE_TRANSIENT], t
2da10 68 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 61  hen.** SQLite ma
2da20 6b 65 73 20 69 74 73 20 6f 77 6e 20 70 72 69 76  kes its own priv
2da30 61 74 65 20 63 6f 70 79 20 6f 66 20 74 68 65 20  ate copy of the 
2da40 64 61 74 61 20 69 6d 6d 65 64 69 61 74 65 6c 79  data immediately
2da50 2c 20 62 65 66 6f 72 65 0a 2a 2a 20 74 68 65 20  , before.** the 
2da60 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29  sqlite3_bind_*()
2da70 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
2da80 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 69 78  ..**.** ^The six
2da90 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73  th argument to s
2daa0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
2dab0 36 34 28 29 20 6d 75 73 74 20 62 65 20 6f 6e 65  64() must be one
2dac0 20 6f 66 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55   of.** [SQLITE_U
2dad0 54 46 38 5d 2c 20 5b 53 51 4c 49 54 45 5f 55 54  TF8], [SQLITE_UT
2dae0 46 31 36 5d 2c 20 5b 53 51 4c 49 54 45 5f 55 54  F16], [SQLITE_UT
2daf0 46 31 36 42 45 5d 2c 20 6f 72 20 5b 53 51 4c 49  F16BE], or [SQLI
2db00 54 45 5f 55 54 46 31 36 4c 45 5d 0a 2a 2a 20 74  TE_UTF16LE].** t
2db10 6f 20 73 70 65 63 69 66 79 20 74 68 65 20 65 6e  o specify the en
2db20 63 6f 64 69 6e 67 20 6f 66 20 74 68 65 20 74 65  coding of the te
2db30 78 74 20 69 6e 20 74 68 65 20 74 68 69 72 64 20  xt in the third 
2db40 70 61 72 61 6d 65 74 65 72 2e 20 20 49 66 0a 2a  parameter.  If.*
2db50 2a 20 74 68 65 20 73 69 78 74 68 20 61 72 67 75  * the sixth argu
2db60 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f  ment to sqlite3_
2db70 62 69 6e 64 5f 74 65 78 74 36 34 28 29 20 69 73  bind_text64() is
2db80 20 6e 6f 74 20 6f 6e 65 20 6f 66 20 74 68 65 0a   not one of the.
2db90 2a 2a 20 61 6c 6c 6f 77 65 64 20 76 61 6c 75 65  ** allowed value
2dba0 73 20 73 68 6f 77 6e 20 61 62 6f 76 65 2c 20 6f  s shown above, o
2dbb0 72 20 69 66 20 74 68 65 20 74 65 78 74 20 65 6e  r if the text en
2dbc0 63 6f 64 69 6e 67 20 69 73 20 64 69 66 66 65 72  coding is differ
2dbd0 65 6e 74 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20  ent.** from the 
2dbe0 65 6e 63 6f 64 69 6e 67 20 73 70 65 63 69 66 69  encoding specifi
2dbf0 65 64 20 62 79 20 74 68 65 20 73 69 78 74 68 20  ed by the sixth 
2dc00 70 61 72 61 6d 65 74 65 72 2c 20 74 68 65 6e 20  parameter, then 
2dc10 74 68 65 20 62 65 68 61 76 69 6f 72 0a 2a 2a 20  the behavior.** 
2dc20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  is undefined..**
2dc30 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
2dc40 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 29  _bind_zeroblob()
2dc50 20 72 6f 75 74 69 6e 65 20 62 69 6e 64 73 20 61   routine binds a
2dc60 20 42 4c 4f 42 20 6f 66 20 6c 65 6e 67 74 68 20   BLOB of length 
2dc70 4e 20 74 68 61 74 0a 2a 2a 20 69 73 20 66 69 6c  N that.** is fil
2dc80 6c 65 64 20 77 69 74 68 20 7a 65 72 6f 65 73 2e  led with zeroes.
2dc90 20 20 5e 41 20 7a 65 72 6f 62 6c 6f 62 20 75 73    ^A zeroblob us
2dca0 65 73 20 61 20 66 69 78 65 64 20 61 6d 6f 75 6e  es a fixed amoun
2dcb0 74 20 6f 66 20 6d 65 6d 6f 72 79 0a 2a 2a 20 28  t of memory.** (
2dcc0 6a 75 73 74 20 61 6e 20 69 6e 74 65 67 65 72 20  just an integer 
2dcd0 74 6f 20 68 6f 6c 64 20 69 74 73 20 73 69 7a 65  to hold its size
2dce0 29 20 77 68 69 6c 65 20 69 74 20 69 73 20 62 65  ) while it is be
2dcf0 69 6e 67 20 70 72 6f 63 65 73 73 65 64 2e 0a 2a  ing processed..*
2dd00 2a 20 5a 65 72 6f 62 6c 6f 62 73 20 61 72 65 20  * Zeroblobs are 
2dd10 69 6e 74 65 6e 64 65 64 20 74 6f 20 73 65 72 76  intended to serv
2dd20 65 20 61 73 20 70 6c 61 63 65 68 6f 6c 64 65 72  e as placeholder
2dd30 73 20 66 6f 72 20 42 4c 4f 42 73 20 77 68 6f 73  s for BLOBs whos
2dd40 65 0a 2a 2a 20 63 6f 6e 74 65 6e 74 20 69 73 20  e.** content is 
2dd50 6c 61 74 65 72 20 77 72 69 74 74 65 6e 20 75 73  later written us
2dd60 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ing.** [sqlite3_
2dd70 62 6c 6f 62 5f 6f 70 65 6e 20 7c 20 69 6e 63 72  blob_open | incr
2dd80 65 6d 65 6e 74 61 6c 20 42 4c 4f 42 20 49 2f 4f  emental BLOB I/O
2dd90 5d 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 20 5e  ] routines..** ^
2dda0 41 20 6e 65 67 61 74 69 76 65 20 76 61 6c 75 65  A negative value
2ddb0 20 66 6f 72 20 74 68 65 20 7a 65 72 6f 62 6c 6f   for the zeroblo
2ddc0 62 20 72 65 73 75 6c 74 73 20 69 6e 20 61 20 7a  b results in a z
2ddd0 65 72 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f 42 2e  ero-length BLOB.
2dde0 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 79 20 6f  .**.** ^If any o
2ddf0 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69  f the sqlite3_bi
2de00 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20  nd_*() routines 
2de10 61 72 65 20 63 61 6c 6c 65 64 20 77 69 74 68 20  are called with 
2de20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a  a NULL pointer.*
2de30 2a 20 66 6f 72 20 74 68 65 20 5b 70 72 65 70 61  * for the [prepa
2de40 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f  red statement] o
2de50 72 20 77 69 74 68 20 61 20 70 72 65 70 61 72 65  r with a prepare
2de60 64 20 73 74 61 74 65 6d 65 6e 74 20 66 6f 72 20  d statement for 
2de70 77 68 69 63 68 0a 2a 2a 20 5b 73 71 6c 69 74 65  which.** [sqlite
2de80 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20 62 65  3_step()] has be
2de90 65 6e 20 63 61 6c 6c 65 64 20 6d 6f 72 65 20 72  en called more r
2dea0 65 63 65 6e 74 6c 79 20 74 68 61 6e 20 5b 73 71  ecently than [sq
2deb0 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 2c 0a  lite3_reset()],.
2dec0 2a 2a 20 74 68 65 6e 20 74 68 65 20 63 61 6c 6c  ** then the call
2ded0 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51   will return [SQ
2dee0 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20 49  LITE_MISUSE].  I
2def0 66 20 61 6e 79 20 73 71 6c 69 74 65 33 5f 62 69  f any sqlite3_bi
2df00 6e 64 5f 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65  nd_().** routine
2df10 20 69 73 20 70 61 73 73 65 64 20 61 20 5b 70 72   is passed a [pr
2df20 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2df30 5d 20 74 68 61 74 20 68 61 73 20 62 65 65 6e 20  ] that has been 
2df40 66 69 6e 61 6c 69 7a 65 64 2c 20 74 68 65 0a 2a  finalized, the.*
2df50 2a 20 72 65 73 75 6c 74 20 69 73 20 75 6e 64 65  * result is unde
2df60 66 69 6e 65 64 20 61 6e 64 20 70 72 6f 62 61 62  fined and probab
2df70 6c 79 20 68 61 72 6d 66 75 6c 2e 0a 2a 2a 0a 2a  ly harmful..**.*
2df80 2a 20 5e 42 69 6e 64 69 6e 67 73 20 61 72 65 20  * ^Bindings are 
2df90 6e 6f 74 20 63 6c 65 61 72 65 64 20 62 79 20 74  not cleared by t
2dfa0 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  he [sqlite3_rese
2dfb0 74 28 29 5d 20 72 6f 75 74 69 6e 65 2e 0a 2a 2a  t()] routine..**
2dfc0 20 5e 55 6e 62 6f 75 6e 64 20 70 61 72 61 6d 65   ^Unbound parame
2dfd0 74 65 72 73 20 61 72 65 20 69 6e 74 65 72 70 72  ters are interpr
2dfe0 65 74 65 64 20 61 73 20 4e 55 4c 4c 2e 0a 2a 2a  eted as NULL..**
2dff0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
2e000 5f 62 69 6e 64 5f 2a 20 72 6f 75 74 69 6e 65 73  _bind_* routines
2e010 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
2e020 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 20 6f  OK] on success o
2e030 72 20 61 6e 0a 2a 2a 20 5b 65 72 72 6f 72 20 63  r an.** [error c
2e040 6f 64 65 5d 20 69 66 20 61 6e 79 74 68 69 6e 67  ode] if anything
2e050 20 67 6f 65 73 20 77 72 6f 6e 67 2e 0a 2a 2a 20   goes wrong..** 
2e060 5e 5b 53 51 4c 49 54 45 5f 54 4f 4f 42 49 47 5d  ^[SQLITE_TOOBIG]
2e070 20 6d 69 67 68 74 20 62 65 20 72 65 74 75 72 6e   might be return
2e080 65 64 20 69 66 20 74 68 65 20 73 69 7a 65 20 6f  ed if the size o
2e090 66 20 61 20 73 74 72 69 6e 67 20 6f 72 20 42 4c  f a string or BL
2e0a0 4f 42 0a 2a 2a 20 65 78 63 65 65 64 73 20 6c 69  OB.** exceeds li
2e0b0 6d 69 74 73 20 69 6d 70 6f 73 65 64 20 62 79 20  mits imposed by 
2e0c0 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 5d 28  [sqlite3_limit](
2e0d0 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45  [SQLITE_LIMIT_LE
2e0e0 4e 47 54 48 5d 29 20 6f 72 0a 2a 2a 20 5b 53 51  NGTH]) or.** [SQ
2e0f0 4c 49 54 45 5f 4d 41 58 5f 4c 45 4e 47 54 48 5d  LITE_MAX_LENGTH]
2e100 2e 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 52 41  ..** ^[SQLITE_RA
2e110 4e 47 45 5d 20 69 73 20 72 65 74 75 72 6e 65 64  NGE] is returned
2e120 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65   if the paramete
2e130 72 0a 2a 2a 20 69 6e 64 65 78 20 69 73 20 6f 75  r.** index is ou
2e140 74 20 6f 66 20 72 61 6e 67 65 2e 20 20 5e 5b 53  t of range.  ^[S
2e150 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 20 69 73 20  QLITE_NOMEM] is 
2e160 72 65 74 75 72 6e 65 64 20 69 66 20 6d 61 6c 6c  returned if mall
2e170 6f 63 28 29 20 66 61 69 6c 73 2e 0a 2a 2a 0a 2a  oc() fails..**.*
2e180 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c  * See also: [sql
2e190 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
2e1a0 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 0a 2a 2a  ter_count()],.**
2e1b0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
2e1c0 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d  arameter_name()]
2e1d0 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62  , and [sqlite3_b
2e1e0 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e  ind_parameter_in
2e1f0 64 65 78 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73  dex()]..*/.int s
2e200 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
2e210 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
2e220 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a  int, const void*
2e230 2c 20 69 6e 74 20 6e 2c 20 76 6f 69 64 28 2a 29  , int n, void(*)
2e240 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71  (void*));.int sq
2e250 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 36  lite3_bind_blob6
2e260 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  4(sqlite3_stmt*,
2e270 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64   int, const void
2e280 2a 2c 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36  *, sqlite3_uint6
2e290 34 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20  4,.             
2e2a0 20 20 20 20 20 20 20 20 20 20 20 76 6f 69 64 28             void(
2e2b0 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20  *)(void*));.int 
2e2c0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 64 6f 75  sqlite3_bind_dou
2e2d0 62 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ble(sqlite3_stmt
2e2e0 2a 2c 20 69 6e 74 2c 20 64 6f 75 62 6c 65 29 3b  *, int, double);
2e2f0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e  .int sqlite3_bin
2e300 64 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 73 74  d_int(sqlite3_st
2e310 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 29 3b 0a  mt*, int, int);.
2e320 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
2e330 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 73  _int64(sqlite3_s
2e340 74 6d 74 2a 2c 20 69 6e 74 2c 20 73 71 6c 69 74  tmt*, int, sqlit
2e350 65 33 5f 69 6e 74 36 34 29 3b 0a 69 6e 74 20 73  e3_int64);.int s
2e360 71 6c 69 74 65 33 5f 62 69 6e 64 5f 6e 75 6c 6c  qlite3_bind_null
2e370 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
2e380 69 6e 74 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  int);.int sqlite
2e390 33 5f 62 69 6e 64 5f 74 65 78 74 28 73 71 6c 69  3_bind_text(sqli
2e3a0 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 2c 63 6f  te3_stmt*,int,co
2e3b0 6e 73 74 20 63 68 61 72 2a 2c 69 6e 74 2c 76 6f  nst char*,int,vo
2e3c0 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69  id(*)(void*));.i
2e3d0 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
2e3e0 74 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f 73  text16(sqlite3_s
2e3f0 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74  tmt*, int, const
2e400 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69   void*, int, voi
2e410 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e  d(*)(void*));.in
2e420 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74  t sqlite3_bind_t
2e430 65 78 74 36 34 28 73 71 6c 69 74 65 33 5f 73 74  ext64(sqlite3_st
2e440 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20  mt*, int, const 
2e450 63 68 61 72 2a 2c 20 73 71 6c 69 74 65 33 5f 75  char*, sqlite3_u
2e460 69 6e 74 36 34 2c 0a 20 20 20 20 20 20 20 20 20  int64,.         
2e470 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2e480 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 2c 20  void(*)(void*), 
2e490 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20 65 6e  unsigned char en
2e4a0 63 6f 64 69 6e 67 29 3b 0a 69 6e 74 20 73 71 6c  coding);.int sql
2e4b0 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28  ite3_bind_value(
2e4c0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
2e4d0 6e 74 2c 20 63 6f 6e 73 74 20 73 71 6c 69 74 65  nt, const sqlite
2e4e0 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73  3_value*);.int s
2e4f0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f  qlite3_bind_zero
2e500 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d  blob(sqlite3_stm
2e510 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 20 6e 29 3b  t*, int, int n);
2e520 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e  .int sqlite3_bin
2e530 64 5f 7a 65 72 6f 62 6c 6f 62 36 34 28 73 71 6c  d_zeroblob64(sql
2e540 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c  ite3_stmt*, int,
2e550 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 29   sqlite3_uint64)
2e560 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2e570 46 3a 20 4e 75 6d 62 65 72 20 4f 66 20 53 51 4c  F: Number Of SQL
2e580 20 50 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 4d   Parameters.** M
2e590 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73  ETHOD: sqlite3_s
2e5a0 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20  tmt.**.** ^This 
2e5b0 72 6f 75 74 69 6e 65 20 63 61 6e 20 62 65 20 75  routine can be u
2e5c0 73 65 64 20 74 6f 20 66 69 6e 64 20 74 68 65 20  sed to find the 
2e5d0 6e 75 6d 62 65 72 20 6f 66 20 5b 53 51 4c 20 70  number of [SQL p
2e5e0 61 72 61 6d 65 74 65 72 73 5d 0a 2a 2a 20 69 6e  arameters].** in
2e5f0 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
2e600 74 65 6d 65 6e 74 5d 2e 20 20 53 51 4c 20 70 61  tement].  SQL pa
2e610 72 61 6d 65 74 65 72 73 20 61 72 65 20 74 6f 6b  rameters are tok
2e620 65 6e 73 20 6f 66 20 74 68 65 0a 2a 2a 20 66 6f  ens of the.** fo
2e630 72 6d 20 22 3f 22 2c 20 22 3f 4e 4e 4e 22 2c 20  rm "?", "?NNN", 
2e640 22 3a 41 41 41 22 2c 20 22 24 41 41 41 22 2c 20  ":AAA", "$AAA", 
2e650 6f 72 20 22 40 41 41 41 22 20 74 68 61 74 20 73  or "@AAA" that s
2e660 65 72 76 65 20 61 73 0a 2a 2a 20 70 6c 61 63 65  erve as.** place
2e670 68 6f 6c 64 65 72 73 20 66 6f 72 20 76 61 6c 75  holders for valu
2e680 65 73 20 74 68 61 74 20 61 72 65 20 5b 73 71 6c  es that are [sql
2e690 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c  ite3_bind_blob |
2e6a0 20 62 6f 75 6e 64 5d 0a 2a 2a 20 74 6f 20 74 68   bound].** to th
2e6b0 65 20 70 61 72 61 6d 65 74 65 72 73 20 61 74 20  e parameters at 
2e6c0 61 20 6c 61 74 65 72 20 74 69 6d 65 2e 0a 2a 2a  a later time..**
2e6d0 0a 2a 2a 20 5e 28 54 68 69 73 20 72 6f 75 74 69  .** ^(This routi
2e6e0 6e 65 20 61 63 74 75 61 6c 6c 79 20 72 65 74 75  ne actually retu
2e6f0 72 6e 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66  rns the index of
2e700 20 74 68 65 20 6c 61 72 67 65 73 74 20 28 72 69   the largest (ri
2e710 67 68 74 6d 6f 73 74 29 0a 2a 2a 20 70 61 72 61  ghtmost).** para
2e720 6d 65 74 65 72 2e 20 46 6f 72 20 61 6c 6c 20 66  meter. For all f
2e730 6f 72 6d 73 20 65 78 63 65 70 74 20 3f 4e 4e 4e  orms except ?NNN
2e740 2c 20 74 68 69 73 20 77 69 6c 6c 20 63 6f 72 72  , this will corr
2e750 65 73 70 6f 6e 64 20 74 6f 20 74 68 65 0a 2a 2a  espond to the.**
2e760 20 6e 75 6d 62 65 72 20 6f 66 20 75 6e 69 71 75   number of uniqu
2e770 65 20 70 61 72 61 6d 65 74 65 72 73 2e 20 20 49  e parameters.  I
2e780 66 20 70 61 72 61 6d 65 74 65 72 73 20 6f 66 20  f parameters of 
2e790 74 68 65 20 3f 4e 4e 4e 20 66 6f 72 6d 20 61 72  the ?NNN form ar
2e7a0 65 20 75 73 65 64 2c 0a 2a 2a 20 74 68 65 72 65  e used,.** there
2e7b0 20 6d 61 79 20 62 65 20 67 61 70 73 20 69 6e 20   may be gaps in 
2e7c0 74 68 65 20 6c 69 73 74 2e 29 5e 0a 2a 2a 0a 2a  the list.)^.**.*
2e7d0 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c  * See also: [sql
2e7e0 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73  ite3_bind_blob|s
2e7f0 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a  qlite3_bind()],.
2e800 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  ** [sqlite3_bind
2e810 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28  _parameter_name(
2e820 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69  )], and.** [sqli
2e830 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
2e840 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a  er_index()]..*/.
2e850 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
2e860 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74  _parameter_count
2e870 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b  (sqlite3_stmt*);
2e880 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2e890 3a 20 4e 61 6d 65 20 4f 66 20 41 20 48 6f 73 74  : Name Of A Host
2e8a0 20 50 61 72 61 6d 65 74 65 72 0a 2a 2a 20 4d 45   Parameter.** ME
2e8b0 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74  THOD: sqlite3_st
2e8c0 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  mt.**.** ^The sq
2e8d0 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
2e8e0 65 74 65 72 5f 6e 61 6d 65 28 50 2c 4e 29 20 69  eter_name(P,N) i
2e8f0 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
2e900 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20 6f 66 20  .** the name of 
2e910 74 68 65 20 4e 2d 74 68 20 5b 53 51 4c 20 70 61  the N-th [SQL pa
2e920 72 61 6d 65 74 65 72 5d 20 69 6e 20 74 68 65 20  rameter] in the 
2e930 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2e940 65 6e 74 5d 20 50 2e 0a 2a 2a 20 5e 28 53 51 4c  ent] P..** ^(SQL
2e950 20 70 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74   parameters of t
2e960 68 65 20 66 6f 72 6d 20 22 3f 4e 4e 4e 22 20 6f  he form "?NNN" o
2e970 72 20 22 3a 41 41 41 22 20 6f 72 20 22 40 41 41  r ":AAA" or "@AA
2e980 41 22 20 6f 72 20 22 24 41 41 41 22 0a 2a 2a 20  A" or "$AAA".** 
2e990 68 61 76 65 20 61 20 6e 61 6d 65 20 77 68 69 63  have a name whic
2e9a0 68 20 69 73 20 74 68 65 20 73 74 72 69 6e 67 20  h is the string 
2e9b0 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41 41 41 22  "?NNN" or ":AAA"
2e9c0 20 6f 72 20 22 40 41 41 41 22 20 6f 72 20 22 24   or "@AAA" or "$
2e9d0 41 41 41 22 0a 2a 2a 20 72 65 73 70 65 63 74 69  AAA".** respecti
2e9e0 76 65 6c 79 2e 0a 2a 2a 20 49 6e 20 6f 74 68 65  vely..** In othe
2e9f0 72 20 77 6f 72 64 73 2c 20 74 68 65 20 69 6e 69  r words, the ini
2ea00 74 69 61 6c 20 22 3a 22 20 6f 72 20 22 24 22 20  tial ":" or "$" 
2ea10 6f 72 20 22 40 22 20 6f 72 20 22 3f 22 0a 2a 2a  or "@" or "?".**
2ea20 20 69 73 20 69 6e 63 6c 75 64 65 64 20 61 73 20   is included as 
2ea30 70 61 72 74 20 6f 66 20 74 68 65 20 6e 61 6d 65  part of the name
2ea40 2e 29 5e 0a 2a 2a 20 5e 50 61 72 61 6d 65 74 65  .)^.** ^Paramete
2ea50 72 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22  rs of the form "
2ea60 3f 22 20 77 69 74 68 6f 75 74 20 61 20 66 6f 6c  ?" without a fol
2ea70 6c 6f 77 69 6e 67 20 69 6e 74 65 67 65 72 20 68  lowing integer h
2ea80 61 76 65 20 6e 6f 20 6e 61 6d 65 0a 2a 2a 20 61  ave no name.** a
2ea90 6e 64 20 61 72 65 20 72 65 66 65 72 72 65 64 20  nd are referred 
2eaa0 74 6f 20 61 73 20 22 6e 61 6d 65 6c 65 73 73 22  to as "nameless"
2eab0 20 6f 72 20 22 61 6e 6f 6e 79 6d 6f 75 73 20 70   or "anonymous p
2eac0 61 72 61 6d 65 74 65 72 73 22 2e 0a 2a 2a 0a 2a  arameters"..**.*
2ead0 2a 20 5e 54 68 65 20 66 69 72 73 74 20 68 6f 73  * ^The first hos
2eae0 74 20 70 61 72 61 6d 65 74 65 72 20 68 61 73 20  t parameter has 
2eaf0 61 6e 20 69 6e 64 65 78 20 6f 66 20 31 2c 20 6e  an index of 1, n
2eb00 6f 74 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  ot 0..**.** ^If 
2eb10 74 68 65 20 76 61 6c 75 65 20 4e 20 69 73 20 6f  the value N is o
2eb20 75 74 20 6f 66 20 72 61 6e 67 65 20 6f 72 20 69  ut of range or i
2eb30 66 20 74 68 65 20 4e 2d 74 68 20 70 61 72 61 6d  f the N-th param
2eb40 65 74 65 72 20 69 73 0a 2a 2a 20 6e 61 6d 65 6c  eter is.** namel
2eb50 65 73 73 2c 20 74 68 65 6e 20 4e 55 4c 4c 20 69  ess, then NULL i
2eb60 73 20 72 65 74 75 72 6e 65 64 2e 20 20 5e 54 68  s returned.  ^Th
2eb70 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e  e returned strin
2eb80 67 20 69 73 0a 2a 2a 20 61 6c 77 61 79 73 20 69  g is.** always i
2eb90 6e 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67  n UTF-8 encoding
2eba0 20 65 76 65 6e 20 69 66 20 74 68 65 20 6e 61 6d   even if the nam
2ebb0 65 64 20 70 61 72 61 6d 65 74 65 72 20 77 61 73  ed parameter was
2ebc0 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 6c 79 20 73  .** originally s
2ebd0 70 65 63 69 66 69 65 64 20 61 73 20 55 54 46 2d  pecified as UTF-
2ebe0 31 36 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f 70  16 in [sqlite3_p
2ebf0 72 65 70 61 72 65 31 36 28 29 5d 20 6f 72 0a 2a  repare16()] or.*
2ec00 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  * [sqlite3_prepa
2ec10 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a  re16_v2()]..**.*
2ec20 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c  * See also: [sql
2ec30 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73  ite3_bind_blob|s
2ec40 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a  qlite3_bind()],.
2ec50 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  ** [sqlite3_bind
2ec60 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74  _parameter_count
2ec70 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c  ()], and.** [sql
2ec80 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
2ec90 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f  ter_index()]..*/
2eca0 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  .const char *sql
2ecb0 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
2ecc0 74 65 72 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33  ter_name(sqlite3
2ecd0 5f 73 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a 0a 2f  _stmt*, int);../
2ece0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49  *.** CAPI3REF: I
2ecf0 6e 64 65 78 20 4f 66 20 41 20 50 61 72 61 6d 65  ndex Of A Parame
2ed00 74 65 72 20 57 69 74 68 20 41 20 47 69 76 65 6e  ter With A Given
2ed10 20 4e 61 6d 65 0a 2a 2a 20 4d 45 54 48 4f 44 3a   Name.** METHOD:
2ed20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a   sqlite3_stmt.**
2ed30 0a 2a 2a 20 5e 52 65 74 75 72 6e 20 74 68 65 20  .** ^Return the 
2ed40 69 6e 64 65 78 20 6f 66 20 61 6e 20 53 51 4c 20  index of an SQL 
2ed50 70 61 72 61 6d 65 74 65 72 20 67 69 76 65 6e 20  parameter given 
2ed60 69 74 73 20 6e 61 6d 65 2e 20 20 5e 54 68 65 0a  its name.  ^The.
2ed70 2a 2a 20 69 6e 64 65 78 20 76 61 6c 75 65 20 72  ** index value r
2ed80 65 74 75 72 6e 65 64 20 69 73 20 73 75 69 74 61  eturned is suita
2ed90 62 6c 65 20 66 6f 72 20 75 73 65 20 61 73 20 74  ble for use as t
2eda0 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 70 61 72  he second.** par
2edb0 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74  ameter to [sqlit
2edc0 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c  e3_bind_blob|sql
2edd0 69 74 65 33 5f 62 69 6e 64 28 29 5d 2e 20 20 5e  ite3_bind()].  ^
2ede0 41 20 7a 65 72 6f 0a 2a 2a 20 69 73 20 72 65 74  A zero.** is ret
2edf0 75 72 6e 65 64 20 69 66 20 6e 6f 20 6d 61 74 63  urned if no matc
2ee00 68 69 6e 67 20 70 61 72 61 6d 65 74 65 72 20 69  hing parameter i
2ee10 73 20 66 6f 75 6e 64 2e 20 20 5e 54 68 65 20 70  s found.  ^The p
2ee20 61 72 61 6d 65 74 65 72 0a 2a 2a 20 6e 61 6d 65  arameter.** name
2ee30 20 6d 75 73 74 20 62 65 20 67 69 76 65 6e 20 69   must be given i
2ee40 6e 20 55 54 46 2d 38 20 65 76 65 6e 20 69 66 20  n UTF-8 even if 
2ee50 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 73 74 61  the original sta
2ee60 74 65 6d 65 6e 74 0a 2a 2a 20 77 61 73 20 70 72  tement.** was pr
2ee70 65 70 61 72 65 64 20 66 72 6f 6d 20 55 54 46 2d  epared from UTF-
2ee80 31 36 20 74 65 78 74 20 75 73 69 6e 67 20 5b 73  16 text using [s
2ee90 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
2eea0 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65  _v2()]..**.** Se
2eeb0 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33  e also: [sqlite3
2eec0 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74  _bind_blob|sqlit
2eed0 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b  e3_bind()],.** [
2eee0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
2eef0 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c  ameter_count()],
2ef00 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   and.** [sqlite3
2ef10 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
2ef20 6e 61 6d 65 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20  name()]..*/.int 
2ef30 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
2ef40 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 73 71 6c  ameter_index(sql
2ef50 69 74 65 33 5f 73 74 6d 74 2a 2c 20 63 6f 6e 73  ite3_stmt*, cons
2ef60 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a  t char *zName);.
2ef70 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2ef80 20 52 65 73 65 74 20 41 6c 6c 20 42 69 6e 64 69   Reset All Bindi
2ef90 6e 67 73 20 4f 6e 20 41 20 50 72 65 70 61 72 65  ngs On A Prepare
2efa0 64 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 4d  d Statement.** M
2efb0 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73  ETHOD: sqlite3_s
2efc0 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e 74 72  tmt.**.** ^Contr
2efd0 61 72 79 20 74 6f 20 74 68 65 20 69 6e 74 75 69  ary to the intui
2efe0 74 69 6f 6e 20 6f 66 20 6d 61 6e 79 2c 20 5b 73  tion of many, [s
2eff0 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
2f000 64 6f 65 73 20 6e 6f 74 20 72 65 73 65 74 0a 2a  does not reset.*
2f010 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62  * the [sqlite3_b
2f020 69 6e 64 5f 62 6c 6f 62 20 7c 20 62 69 6e 64 69  ind_blob | bindi
2f030 6e 67 73 5d 20 6f 6e 20 61 20 5b 70 72 65 70 61  ngs] on a [prepa
2f040 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a  red statement]..
2f050 2a 2a 20 5e 55 73 65 20 74 68 69 73 20 72 6f 75  ** ^Use this rou
2f060 74 69 6e 65 20 74 6f 20 72 65 73 65 74 20 61 6c  tine to reset al
2f070 6c 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72  l host parameter
2f080 73 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2f 0a 69 6e  s to NULL..*/.in
2f090 74 20 73 71 6c 69 74 65 33 5f 63 6c 65 61 72 5f  t sqlite3_clear_
2f0a0 62 69 6e 64 69 6e 67 73 28 73 71 6c 69 74 65 33  bindings(sqlite3
2f0b0 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  _stmt*);../*.** 
2f0c0 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72  CAPI3REF: Number
2f0d0 20 4f 66 20 43 6f 6c 75 6d 6e 73 20 49 6e 20 41   Of Columns In A
2f0e0 20 52 65 73 75 6c 74 20 53 65 74 0a 2a 2a 20 4d   Result Set.** M
2f0f0 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73  ETHOD: sqlite3_s
2f100 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 52 65 74 75 72  tmt.**.** ^Retur
2f110 6e 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  n the number of 
2f120 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72  columns in the r
2f130 65 73 75 6c 74 20 73 65 74 20 72 65 74 75 72 6e  esult set return
2f140 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 5b 70 72  ed by the.** [pr
2f150 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2f160 5d 2e 20 5e 49 66 20 74 68 69 73 20 72 6f 75 74  ]. ^If this rout
2f170 69 6e 65 20 72 65 74 75 72 6e 73 20 30 2c 20 74  ine returns 0, t
2f180 68 61 74 20 6d 65 61 6e 73 20 74 68 65 20 0a 2a  hat means the .*
2f190 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  * [prepared stat
2f1a0 65 6d 65 6e 74 5d 20 72 65 74 75 72 6e 73 20 6e  ement] returns n
2f1b0 6f 20 64 61 74 61 20 28 66 6f 72 20 65 78 61 6d  o data (for exam
2f1c0 70 6c 65 20 61 6e 20 5b 55 50 44 41 54 45 5d 29  ple an [UPDATE])
2f1d0 2e 0a 2a 2a 20 5e 48 6f 77 65 76 65 72 2c 20 6a  ..** ^However, j
2f1e0 75 73 74 20 62 65 63 61 75 73 65 20 74 68 69 73  ust because this
2f1f0 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
2f200 20 61 20 70 6f 73 69 74 69 76 65 20 6e 75 6d 62   a positive numb
2f210 65 72 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 6d  er does not.** m
2f220 65 61 6e 20 74 68 61 74 20 6f 6e 65 20 6f 72 20  ean that one or 
2f230 6d 6f 72 65 20 72 6f 77 73 20 6f 66 20 64 61 74  more rows of dat
2f240 61 20 77 69 6c 6c 20 62 65 20 72 65 74 75 72 6e  a will be return
2f250 65 64 2e 20 20 5e 41 20 53 45 4c 45 43 54 20 73  ed.  ^A SELECT s
2f260 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 77 69 6c 6c  tatement.** will
2f270 20 61 6c 77 61 79 73 20 68 61 76 65 20 61 20 70   always have a p
2f280 6f 73 69 74 69 76 65 20 73 71 6c 69 74 65 33 5f  ositive sqlite3_
2f290 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 29 20 62  column_count() b
2f2a0 75 74 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20  ut depending on 
2f2b0 74 68 65 0a 2a 2a 20 57 48 45 52 45 20 63 6c 61  the.** WHERE cla
2f2c0 75 73 65 20 63 6f 6e 73 74 72 61 69 6e 74 73 20  use constraints 
2f2d0 61 6e 64 20 74 68 65 20 74 61 62 6c 65 20 63 6f  and the table co
2f2e0 6e 74 65 6e 74 2c 20 69 74 20 6d 69 67 68 74 20  ntent, it might 
2f2f0 72 65 74 75 72 6e 20 6e 6f 20 72 6f 77 73 2e 0a  return no rows..
2f300 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20  **.** See also: 
2f310 5b 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f  [sqlite3_data_co
2f320 75 6e 74 28 29 5d 0a 2a 2f 0a 69 6e 74 20 73 71  unt()].*/.int sq
2f330 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75  lite3_column_cou
2f340 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  nt(sqlite3_stmt 
2f350 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  *pStmt);../*.** 
2f360 43 41 50 49 33 52 45 46 3a 20 43 6f 6c 75 6d 6e  CAPI3REF: Column
2f370 20 4e 61 6d 65 73 20 49 6e 20 41 20 52 65 73 75   Names In A Resu
2f380 6c 74 20 53 65 74 0a 2a 2a 20 4d 45 54 48 4f 44  lt Set.** METHOD
2f390 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a  : sqlite3_stmt.*
2f3a0 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74  *.** ^These rout
2f3b0 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65 20  ines return the 
2f3c0 6e 61 6d 65 20 61 73 73 69 67 6e 65 64 20 74 6f  name assigned to
2f3d0 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 63 6f   a particular co
2f3e0 6c 75 6d 6e 0a 2a 2a 20 69 6e 20 74 68 65 20 72  lumn.** in the r
2f3f0 65 73 75 6c 74 20 73 65 74 20 6f 66 20 61 20 5b  esult set of a [
2f400 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e  SELECT] statemen
2f410 74 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33  t.  ^The sqlite3
2f420 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 0a 2a  _column_name().*
2f430 2a 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  * interface retu
2f440 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
2f450 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74   a zero-terminat
2f460 65 64 20 55 54 46 2d 38 20 73 74 72 69 6e 67 0a  ed UTF-8 string.
2f470 2a 2a 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63  ** and sqlite3_c
2f480 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 72  olumn_name16() r
2f490 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
2f4a0 20 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69   to a zero-termi
2f4b0 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d 31 36 20  nated.** UTF-16 
2f4c0 73 74 72 69 6e 67 2e 20 20 5e 54 68 65 20 66 69  string.  ^The fi
2f4d0 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73  rst parameter is
2f4e0 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
2f4f0 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 74 68 61  tatement].** tha
2f500 74 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65  t implements the
2f510 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d   [SELECT] statem
2f520 65 6e 74 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64  ent. ^The second
2f530 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68   parameter is th
2f540 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62  e.** column numb
2f550 65 72 2e 20 20 5e 54 68 65 20 6c 65 66 74 6d 6f  er.  ^The leftmo
2f560 73 74 20 63 6f 6c 75 6d 6e 20 69 73 20 6e 75 6d  st column is num
2f570 62 65 72 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ber 0..**.** ^Th
2f580 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e  e returned strin
2f590 67 20 70 6f 69 6e 74 65 72 20 69 73 20 76 61 6c  g pointer is val
2f5a0 69 64 20 75 6e 74 69 6c 20 65 69 74 68 65 72 20  id until either 
2f5b0 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
2f5c0 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 69 73 20 64  atement].** is d
2f5d0 65 73 74 72 6f 79 65 64 20 62 79 20 5b 73 71 6c  estroyed by [sql
2f5e0 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
2f5f0 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 73 74   or until the st
2f600 61 74 65 6d 65 6e 74 20 69 73 20 61 75 74 6f 6d  atement is autom
2f610 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 72 65 70 72  atically.** repr
2f620 65 70 61 72 65 64 20 62 79 20 74 68 65 20 66 69  epared by the fi
2f630 72 73 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  rst call to [sql
2f640 69 74 65 33 5f 73 74 65 70 28 29 5d 20 66 6f 72  ite3_step()] for
2f650 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 72 75   a particular ru
2f660 6e 0a 2a 2a 20 6f 72 20 75 6e 74 69 6c 20 74 68  n.** or until th
2f670 65 20 6e 65 78 74 20 63 61 6c 6c 20 74 6f 0a 2a  e next call to.*
2f680 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  * sqlite3_column
2f690 5f 6e 61 6d 65 28 29 20 6f 72 20 73 71 6c 69 74  _name() or sqlit
2f6a0 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36  e3_column_name16
2f6b0 28 29 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 63  () on the same c
2f6c0 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  olumn..**.** ^If
2f6d0 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28   sqlite3_malloc(
2f6e0 29 20 66 61 69 6c 73 20 64 75 72 69 6e 67 20 74  ) fails during t
2f6f0 68 65 20 70 72 6f 63 65 73 73 69 6e 67 20 6f 66  he processing of
2f700 20 65 69 74 68 65 72 20 72 6f 75 74 69 6e 65 0a   either routine.
2f710 2a 2a 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20  ** (for example 
2f720 64 75 72 69 6e 67 20 61 20 63 6f 6e 76 65 72 73  during a convers
2f730 69 6f 6e 20 66 72 6f 6d 20 55 54 46 2d 38 20 74  ion from UTF-8 t
2f740 6f 20 55 54 46 2d 31 36 29 20 74 68 65 6e 20 61  o UTF-16) then a
2f750 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  .** NULL pointer
2f760 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a   is returned..**
2f770 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66  .** ^The name of
2f780 20 61 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e   a result column
2f790 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66   is the value of
2f7a0 20 74 68 65 20 22 41 53 22 20 63 6c 61 75 73 65   the "AS" clause
2f7b0 20 66 6f 72 0a 2a 2a 20 74 68 61 74 20 63 6f 6c   for.** that col
2f7c0 75 6d 6e 2c 20 69 66 20 74 68 65 72 65 20 69 73  umn, if there is
2f7d0 20 61 6e 20 41 53 20 63 6c 61 75 73 65 2e 20 20   an AS clause.  
2f7e0 49 66 20 74 68 65 72 65 20 69 73 20 6e 6f 20 41  If there is no A
2f7f0 53 20 63 6c 61 75 73 65 0a 2a 2a 20 74 68 65 6e  S clause.** then
2f800 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
2f810 20 63 6f 6c 75 6d 6e 20 69 73 20 75 6e 73 70 65   column is unspe
2f820 63 69 66 69 65 64 20 61 6e 64 20 6d 61 79 20 63  cified and may c
2f830 68 61 6e 67 65 20 66 72 6f 6d 0a 2a 2a 20 6f 6e  hange from.** on
2f840 65 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c  e release of SQL
2f850 69 74 65 20 74 6f 20 74 68 65 20 6e 65 78 74 2e  ite to the next.
2f860 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a  .*/.const char *
2f870 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e  sqlite3_column_n
2f880 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ame(sqlite3_stmt
2f890 2a 2c 20 69 6e 74 20 4e 29 3b 0a 63 6f 6e 73 74  *, int N);.const
2f8a0 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63   void *sqlite3_c
2f8b0 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 73 71 6c  olumn_name16(sql
2f8c0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
2f8d0 4e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  N);../*.** CAPI3
2f8e0 52 45 46 3a 20 53 6f 75 72 63 65 20 4f 66 20 44  REF: Source Of D
2f8f0 61 74 61 20 49 6e 20 41 20 51 75 65 72 79 20 52  ata In A Query R
2f900 65 73 75 6c 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a  esult.** METHOD:
2f910 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a   sqlite3_stmt.**
2f920 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69  .** ^These routi
2f930 6e 65 73 20 70 72 6f 76 69 64 65 20 61 20 6d 65  nes provide a me
2f940 61 6e 73 20 74 6f 20 64 65 74 65 72 6d 69 6e 65  ans to determine
2f950 20 74 68 65 20 64 61 74 61 62 61 73 65 2c 20 74   the database, t
2f960 61 62 6c 65 2c 20 61 6e 64 0a 2a 2a 20 74 61 62  able, and.** tab
2f970 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 69  le column that i
2f980 73 20 74 68 65 20 6f 72 69 67 69 6e 20 6f 66 20  s the origin of 
2f990 61 20 70 61 72 74 69 63 75 6c 61 72 20 72 65 73  a particular res
2f9a0 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 6e 0a 2a 2a  ult column in.**
2f9b0 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d   [SELECT] statem
2f9c0 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d  ent..** ^The nam
2f9d0 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73  e of the databas
2f9e0 65 20 6f 72 20 74 61 62 6c 65 20 6f 72 20 63 6f  e or table or co
2f9f0 6c 75 6d 6e 20 63 61 6e 20 62 65 20 72 65 74 75  lumn can be retu
2fa00 72 6e 65 64 20 61 73 0a 2a 2a 20 65 69 74 68 65  rned as.** eithe
2fa10 72 20 61 20 55 54 46 2d 38 20 6f 72 20 55 54 46  r a UTF-8 or UTF
2fa20 2d 31 36 20 73 74 72 69 6e 67 2e 20 20 5e 54 68  -16 string.  ^Th
2fa30 65 20 5f 64 61 74 61 62 61 73 65 5f 20 72 6f 75  e _database_ rou
2fa40 74 69 6e 65 73 20 72 65 74 75 72 6e 0a 2a 2a 20  tines return.** 
2fa50 74 68 65 20 64 61 74 61 62 61 73 65 20 6e 61 6d  the database nam
2fa60 65 2c 20 74 68 65 20 5f 74 61 62 6c 65 5f 20 72  e, the _table_ r
2fa70 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74  outines return t
2fa80 68 65 20 74 61 62 6c 65 20 6e 61 6d 65 2c 20 61  he table name, a
2fa90 6e 64 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e  nd.** the origin
2faa0 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  _ routines retur
2fab0 6e 20 74 68 65 20 63 6f 6c 75 6d 6e 20 6e 61 6d  n the column nam
2fac0 65 2e 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75 72  e..** ^The retur
2fad0 6e 65 64 20 73 74 72 69 6e 67 20 69 73 20 76 61  ned string is va
2fae0 6c 69 64 20 75 6e 74 69 6c 20 74 68 65 20 5b 70  lid until the [p
2faf0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2fb00 74 5d 20 69 73 20 64 65 73 74 72 6f 79 65 64 0a  t] is destroyed.
2fb10 2a 2a 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ** using [sqlite
2fb20 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72  3_finalize()] or
2fb30 20 75 6e 74 69 6c 20 74 68 65 20 73 74 61 74 65   until the state
2fb40 6d 65 6e 74 20 69 73 20 61 75 74 6f 6d 61 74 69  ment is automati
2fb50 63 61 6c 6c 79 0a 2a 2a 20 72 65 70 72 65 70 61  cally.** reprepa
2fb60 72 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74  red by the first
2fb70 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
2fb80 33 5f 73 74 65 70 28 29 5d 20 66 6f 72 20 61 20  3_step()] for a 
2fb90 70 61 72 74 69 63 75 6c 61 72 20 72 75 6e 0a 2a  particular run.*
2fba0 2a 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 73  * or until the s
2fbb0 61 6d 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  ame information 
2fbc0 69 73 20 72 65 71 75 65 73 74 65 64 0a 2a 2a 20  is requested.** 
2fbd0 61 67 61 69 6e 20 69 6e 20 61 20 64 69 66 66 65  again in a diffe
2fbe0 72 65 6e 74 20 65 6e 63 6f 64 69 6e 67 2e 0a 2a  rent encoding..*
2fbf0 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 73 20  *.** ^The names 
2fc00 72 65 74 75 72 6e 65 64 20 61 72 65 20 74 68 65  returned are the
2fc10 20 6f 72 69 67 69 6e 61 6c 20 75 6e 2d 61 6c 69   original un-ali
2fc20 61 73 65 64 20 6e 61 6d 65 73 20 6f 66 20 74 68  ased names of th
2fc30 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 2c 20 74  e.** database, t
2fc40 61 62 6c 65 2c 20 61 6e 64 20 63 6f 6c 75 6d 6e  able, and column
2fc50 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72  ..**.** ^The fir
2fc60 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  st argument to t
2fc70 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 20  hese interfaces 
2fc80 69 73 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  is a [prepared s
2fc90 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 54  tatement]..** ^T
2fca0 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 72  hese functions r
2fcb0 65 74 75 72 6e 20 69 6e 66 6f 72 6d 61 74 69 6f  eturn informatio
2fcc0 6e 20 61 62 6f 75 74 20 74 68 65 20 4e 74 68 20  n about the Nth 
2fcd0 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 72 65  result column re
2fce0 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 74 68 65  turned by.** the
2fcf0 20 73 74 61 74 65 6d 65 6e 74 2c 20 77 68 65 72   statement, wher
2fd00 65 20 4e 20 69 73 20 74 68 65 20 73 65 63 6f 6e  e N is the secon
2fd10 64 20 66 75 6e 63 74 69 6f 6e 20 61 72 67 75 6d  d function argum
2fd20 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 6c 65 66  ent..** ^The lef
2fd30 74 2d 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 69 73  t-most column is
2fd40 20 63 6f 6c 75 6d 6e 20 30 20 66 6f 72 20 74 68   column 0 for th
2fd50 65 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a  ese routines..**
2fd60 0a 2a 2a 20 5e 49 66 20 74 68 65 20 4e 74 68 20  .** ^If the Nth 
2fd70 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65 64 20  column returned 
2fd80 62 79 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  by the statement
2fd90 20 69 73 20 61 6e 20 65 78 70 72 65 73 73 69 6f   is an expressio
2fda0 6e 20 6f 72 0a 2a 2a 20 73 75 62 71 75 65 72 79  n or.** subquery
2fdb0 20 61 6e 64 20 69 73 20 6e 6f 74 20 61 20 63 6f   and is not a co
2fdc0 6c 75 6d 6e 20 76 61 6c 75 65 2c 20 74 68 65 6e  lumn value, then
2fdd0 20 61 6c 6c 20 6f 66 20 74 68 65 73 65 20 66 75   all of these fu
2fde0 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 0a 2a  nctions return.*
2fdf0 2a 20 4e 55 4c 4c 2e 20 20 5e 54 68 65 73 65 20  * NULL.  ^These 
2fe00 72 6f 75 74 69 6e 65 20 6d 69 67 68 74 20 61 6c  routine might al
2fe10 73 6f 20 72 65 74 75 72 6e 20 4e 55 4c 4c 20 69  so return NULL i
2fe20 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  f a memory alloc
2fe30 61 74 69 6f 6e 20 65 72 72 6f 72 0a 2a 2a 20 6f  ation error.** o
2fe40 63 63 75 72 73 2e 20 20 5e 4f 74 68 65 72 77 69  ccurs.  ^Otherwi
2fe50 73 65 2c 20 74 68 65 79 20 72 65 74 75 72 6e 20  se, they return 
2fe60 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
2fe70 61 74 74 61 63 68 65 64 20 64 61 74 61 62 61 73  attached databas
2fe80 65 2c 20 74 61 62 6c 65 2c 0a 2a 2a 20 6f 72 20  e, table,.** or 
2fe90 63 6f 6c 75 6d 6e 20 74 68 61 74 20 71 75 65 72  column that quer
2fea0 79 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20  y result column 
2feb0 77 61 73 20 65 78 74 72 61 63 74 65 64 20 66 72  was extracted fr
2fec0 6f 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 77 69  om..**.** ^As wi
2fed0 74 68 20 61 6c 6c 20 6f 74 68 65 72 20 53 51 4c  th all other SQL
2fee0 69 74 65 20 41 50 49 73 2c 20 74 68 6f 73 65 20  ite APIs, those 
2fef0 77 68 6f 73 65 20 6e 61 6d 65 73 20 65 6e 64 20  whose names end 
2ff00 77 69 74 68 20 22 31 36 22 20 72 65 74 75 72 6e  with "16" return
2ff10 0a 2a 2a 20 55 54 46 2d 31 36 20 65 6e 63 6f 64  .** UTF-16 encod
2ff20 65 64 20 73 74 72 69 6e 67 73 20 61 6e 64 20 74  ed strings and t
2ff30 68 65 20 6f 74 68 65 72 20 66 75 6e 63 74 69 6f  he other functio
2ff40 6e 73 20 72 65 74 75 72 6e 20 55 54 46 2d 38 2e  ns return UTF-8.
2ff50 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 41 50  .**.** ^These AP
2ff60 49 73 20 61 72 65 20 6f 6e 6c 79 20 61 76 61 69  Is are only avai
2ff70 6c 61 62 6c 65 20 69 66 20 74 68 65 20 6c 69 62  lable if the lib
2ff80 72 61 72 79 20 77 61 73 20 63 6f 6d 70 69 6c 65  rary was compile
2ff90 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53  d with the.** [S
2ffa0 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 43 4f 4c  QLITE_ENABLE_COL
2ffb0 55 4d 4e 5f 4d 45 54 41 44 41 54 41 5d 20 43 2d  UMN_METADATA] C-
2ffc0 70 72 65 70 72 6f 63 65 73 73 6f 72 20 73 79 6d  preprocessor sym
2ffd0 62 6f 6c 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 77  bol..**.** If tw
2ffe0 6f 20 6f 72 20 6d 6f 72 65 20 74 68 72 65 61 64  o or more thread
2fff0 73 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f  s call one or mo
30000 72 65 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74  re of these rout
30010 69 6e 65 73 20 61 67 61 69 6e 73 74 20 74 68 65  ines against the
30020 20 73 61 6d 65 0a 2a 2a 20 70 72 65 70 61 72 65   same.** prepare
30030 64 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20  d statement and 
30040 63 6f 6c 75 6d 6e 20 61 74 20 74 68 65 20 73 61  column at the sa
30050 6d 65 20 74 69 6d 65 20 74 68 65 6e 20 74 68 65  me time then the
30060 20 72 65 73 75 6c 74 73 20 61 72 65 0a 2a 2a 20   results are.** 
30070 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a  undefined..**.**
30080 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20   If two or more 
30090 74 68 72 65 61 64 73 20 63 61 6c 6c 20 6f 6e 65  threads call one
300a0 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 5b 73 71 6c   or more.** [sql
300b0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61  ite3_column_data
300c0 62 61 73 65 5f 6e 61 6d 65 20 7c 20 63 6f 6c 75  base_name | colu
300d0 6d 6e 20 6d 65 74 61 64 61 74 61 20 69 6e 74 65  mn metadata inte
300e0 72 66 61 63 65 73 5d 0a 2a 2a 20 66 6f 72 20 74  rfaces].** for t
300f0 68 65 20 73 61 6d 65 20 5b 70 72 65 70 61 72 65  he same [prepare
30100 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 61 6e 64  d statement] and
30110 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 0a 2a   result column.*
30120 2a 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 69  * at the same ti
30130 6d 65 20 74 68 65 6e 20 74 68 65 20 72 65 73 75  me then the resu
30140 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65  lts are undefine
30150 64 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72  d..*/.const char
30160 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
30170 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 28 73  _database_name(s
30180 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74  qlite3_stmt*,int
30190 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  );.const void *s
301a0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61  qlite3_column_da
301b0 74 61 62 61 73 65 5f 6e 61 6d 65 31 36 28 73 71  tabase_name16(sq
301c0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29  lite3_stmt*,int)
301d0 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  ;.const char *sq
301e0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62  lite3_column_tab
301f0 6c 65 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f  le_name(sqlite3_
30200 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73  stmt*,int);.cons
30210 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
30220 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d  column_table_nam
30230 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  e16(sqlite3_stmt
30240 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 63 68  *,int);.const ch
30250 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ar *sqlite3_colu
30260 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 28 73  mn_origin_name(s
30270 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74  qlite3_stmt*,int
30280 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  );.const void *s
30290 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72  qlite3_column_or
302a0 69 67 69 6e 5f 6e 61 6d 65 31 36 28 73 71 6c 69  igin_name16(sqli
302b0 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a  te3_stmt*,int);.
302c0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
302d0 20 44 65 63 6c 61 72 65 64 20 44 61 74 61 74 79   Declared Dataty
302e0 70 65 20 4f 66 20 41 20 51 75 65 72 79 20 52 65  pe Of A Query Re
302f0 73 75 6c 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  sult.** METHOD: 
30300 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a  sqlite3_stmt.**.
30310 2a 2a 20 5e 28 54 68 65 20 66 69 72 73 74 20 70  ** ^(The first p
30320 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 5b 70  arameter is a [p
30330 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
30340 74 5d 2e 0a 2a 2a 20 49 66 20 74 68 69 73 20 73  t]..** If this s
30350 74 61 74 65 6d 65 6e 74 20 69 73 20 61 20 5b 53  tatement is a [S
30360 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74  ELECT] statement
30370 20 61 6e 64 20 74 68 65 20 4e 74 68 20 63 6f 6c   and the Nth col
30380 75 6d 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 72 65  umn of the.** re
30390 74 75 72 6e 65 64 20 72 65 73 75 6c 74 20 73 65  turned result se
303a0 74 20 6f 66 20 74 68 61 74 20 5b 53 45 4c 45 43  t of that [SELEC
303b0 54 5d 20 69 73 20 61 20 74 61 62 6c 65 20 63 6f  T] is a table co
303c0 6c 75 6d 6e 20 28 6e 6f 74 20 61 6e 0a 2a 2a 20  lumn (not an.** 
303d0 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 73 75  expression or su
303e0 62 71 75 65 72 79 29 20 74 68 65 6e 20 74 68 65  bquery) then the
303f0 20 64 65 63 6c 61 72 65 64 20 74 79 70 65 20 6f   declared type o
30400 66 20 74 68 65 20 74 61 62 6c 65 0a 2a 2a 20 63  f the table.** c
30410 6f 6c 75 6d 6e 20 69 73 20 72 65 74 75 72 6e 65  olumn is returne
30420 64 2e 29 5e 20 20 5e 49 66 20 74 68 65 20 4e 74  d.)^  ^If the Nt
30430 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20  h column of the 
30440 72 65 73 75 6c 74 20 73 65 74 20 69 73 20 61 6e  result set is an
30450 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e 20 6f  .** expression o
30460 72 20 73 75 62 71 75 65 72 79 2c 20 74 68 65 6e  r subquery, then
30470 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
30480 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20  is returned..** 
30490 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 74  ^The returned st
304a0 72 69 6e 67 20 69 73 20 61 6c 77 61 79 73 20 55  ring is always U
304b0 54 46 2d 38 20 65 6e 63 6f 64 65 64 2e 0a 2a 2a  TF-8 encoded..**
304c0 0a 2a 2a 20 5e 28 46 6f 72 20 65 78 61 6d 70 6c  .** ^(For exampl
304d0 65 2c 20 67 69 76 65 6e 20 74 68 65 20 64 61 74  e, given the dat
304e0 61 62 61 73 65 20 73 63 68 65 6d 61 3a 0a 2a 2a  abase schema:.**
304f0 0a 2a 2a 20 43 52 45 41 54 45 20 54 41 42 4c 45  .** CREATE TABLE
30500 20 74 31 28 63 31 20 56 41 52 49 41 4e 54 29 3b   t1(c1 VARIANT);
30510 0a 2a 2a 0a 2a 2a 20 61 6e 64 20 74 68 65 20 66  .**.** and the f
30520 6f 6c 6c 6f 77 69 6e 67 20 73 74 61 74 65 6d 65  ollowing stateme
30530 6e 74 20 74 6f 20 62 65 20 63 6f 6d 70 69 6c 65  nt to be compile
30540 64 3a 0a 2a 2a 0a 2a 2a 20 53 45 4c 45 43 54 20  d:.**.** SELECT 
30550 63 31 20 2b 20 31 2c 20 63 31 20 46 52 4f 4d 20  c1 + 1, c1 FROM 
30560 74 31 3b 0a 2a 2a 0a 2a 2a 20 74 68 69 73 20 72  t1;.**.** this r
30570 6f 75 74 69 6e 65 20 77 6f 75 6c 64 20 72 65 74  outine would ret
30580 75 72 6e 20 74 68 65 20 73 74 72 69 6e 67 20 22  urn the string "
30590 56 41 52 49 41 4e 54 22 20 66 6f 72 20 74 68 65  VARIANT" for the
305a0 20 73 65 63 6f 6e 64 20 72 65 73 75 6c 74 0a 2a   second result.*
305b0 2a 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d 31 29 2c  * column (i==1),
305c0 20 61 6e 64 20 61 20 4e 55 4c 4c 20 70 6f 69 6e   and a NULL poin
305d0 74 65 72 20 66 6f 72 20 74 68 65 20 66 69 72 73  ter for the firs
305e0 74 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20  t result column 
305f0 28 69 3d 3d 30 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20  (i==0).)^.**.** 
30600 5e 53 51 4c 69 74 65 20 75 73 65 73 20 64 79 6e  ^SQLite uses dyn
30610 61 6d 69 63 20 72 75 6e 2d 74 69 6d 65 20 74 79  amic run-time ty
30620 70 69 6e 67 2e 20 20 5e 53 6f 20 6a 75 73 74 20  ping.  ^So just 
30630 62 65 63 61 75 73 65 20 61 20 63 6f 6c 75 6d 6e  because a column
30640 0a 2a 2a 20 69 73 20 64 65 63 6c 61 72 65 64 20  .** is declared 
30650 74 6f 20 63 6f 6e 74 61 69 6e 20 61 20 70 61 72  to contain a par
30660 74 69 63 75 6c 61 72 20 74 79 70 65 20 64 6f 65  ticular type doe
30670 73 20 6e 6f 74 20 6d 65 61 6e 20 74 68 61 74 20  s not mean that 
30680 74 68 65 0a 2a 2a 20 64 61 74 61 20 73 74 6f 72  the.** data stor
30690 65 64 20 69 6e 20 74 68 61 74 20 63 6f 6c 75 6d  ed in that colum
306a0 6e 20 69 73 20 6f 66 20 74 68 65 20 64 65 63 6c  n is of the decl
306b0 61 72 65 64 20 74 79 70 65 2e 20 20 53 51 4c 69  ared type.  SQLi
306c0 74 65 20 69 73 0a 2a 2a 20 73 74 72 6f 6e 67 6c  te is.** strongl
306d0 79 20 74 79 70 65 64 2c 20 62 75 74 20 74 68 65  y typed, but the
306e0 20 74 79 70 69 6e 67 20 69 73 20 64 79 6e 61 6d   typing is dynam
306f0 69 63 20 6e 6f 74 20 73 74 61 74 69 63 2e 20 20  ic not static.  
30700 5e 54 79 70 65 0a 2a 2a 20 69 73 20 61 73 73 6f  ^Type.** is asso
30710 63 69 61 74 65 64 20 77 69 74 68 20 69 6e 64 69  ciated with indi
30720 76 69 64 75 61 6c 20 76 61 6c 75 65 73 2c 20 6e  vidual values, n
30730 6f 74 20 77 69 74 68 20 74 68 65 20 63 6f 6e 74  ot with the cont
30740 61 69 6e 65 72 73 0a 2a 2a 20 75 73 65 64 20 74  ainers.** used t
30750 6f 20 68 6f 6c 64 20 74 68 6f 73 65 20 76 61 6c  o hold those val
30760 75 65 73 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68  ues..*/.const ch
30770 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ar *sqlite3_colu
30780 6d 6e 5f 64 65 63 6c 74 79 70 65 28 73 71 6c 69  mn_decltype(sqli
30790 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a  te3_stmt*,int);.
307a0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
307b0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74  te3_column_declt
307c0 79 70 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74  ype16(sqlite3_st
307d0 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a  mt*,int);../*.**
307e0 20 43 41 50 49 33 52 45 46 3a 20 45 76 61 6c 75   CAPI3REF: Evalu
307f0 61 74 65 20 41 6e 20 53 51 4c 20 53 74 61 74 65  ate An SQL State
30800 6d 65 6e 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  ment.** METHOD: 
30810 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a  sqlite3_stmt.**.
30820 2a 2a 20 41 66 74 65 72 20 61 20 5b 70 72 65 70  ** After a [prep
30830 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
30840 68 61 73 20 62 65 65 6e 20 70 72 65 70 61 72 65  has been prepare
30850 64 20 75 73 69 6e 67 20 65 69 74 68 65 72 0a 2a  d using either.*
30860 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  * [sqlite3_prepa
30870 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c  re_v2()] or [sql
30880 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
30890 32 28 29 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 74  2()] or one of t
308a0 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74  he legacy.** int
308b0 65 72 66 61 63 65 73 20 5b 73 71 6c 69 74 65 33  erfaces [sqlite3
308c0 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20 5b  _prepare()] or [
308d0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
308e0 36 28 29 5d 2c 20 74 68 69 73 20 66 75 6e 63 74  6()], this funct
308f0 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 62 65 20 63  ion.** must be c
30900 61 6c 6c 65 64 20 6f 6e 65 20 6f 72 20 6d 6f 72  alled one or mor
30910 65 20 74 69 6d 65 73 20 74 6f 20 65 76 61 6c 75  e times to evalu
30920 61 74 65 20 74 68 65 20 73 74 61 74 65 6d 65 6e  ate the statemen
30930 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64 65 74  t..**.** The det
30940 61 69 6c 73 20 6f 66 20 74 68 65 20 62 65 68 61  ails of the beha
30950 76 69 6f 72 20 6f 66 20 74 68 65 20 73 71 6c 69  vior of the sqli
30960 74 65 33 5f 73 74 65 70 28 29 20 69 6e 74 65 72  te3_step() inter
30970 66 61 63 65 20 64 65 70 65 6e 64 0a 2a 2a 20 6f  face depend.** o
30980 6e 20 77 68 65 74 68 65 72 20 74 68 65 20 73 74  n whether the st
30990 61 74 65 6d 65 6e 74 20 77 61 73 20 70 72 65 70  atement was prep
309a0 61 72 65 64 20 75 73 69 6e 67 20 74 68 65 20 6e  ared using the n
309b0 65 77 65 72 20 22 76 32 22 20 69 6e 74 65 72 66  ewer "v2" interf
309c0 61 63 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ace.** [sqlite3_
309d0 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e  prepare_v2()] an
309e0 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  d [sqlite3_prepa
309f0 72 65 31 36 5f 76 32 28 29 5d 20 6f 72 20 74 68  re16_v2()] or th
30a00 65 20 6f 6c 64 65 72 20 6c 65 67 61 63 79 0a 2a  e older legacy.*
30a10 2a 20 69 6e 74 65 72 66 61 63 65 20 5b 73 71 6c  * interface [sql
30a20 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20  ite3_prepare()] 
30a30 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  and [sqlite3_pre
30a40 70 61 72 65 31 36 28 29 5d 2e 20 20 54 68 65 20  pare16()].  The 
30a50 75 73 65 20 6f 66 20 74 68 65 0a 2a 2a 20 6e 65  use of the.** ne
30a60 77 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65  w "v2" interface
30a70 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20   is recommended 
30a80 66 6f 72 20 6e 65 77 20 61 70 70 6c 69 63 61 74  for new applicat
30a90 69 6f 6e 73 20 62 75 74 20 74 68 65 20 6c 65 67  ions but the leg
30aa0 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  acy.** interface
30ab0 20 77 69 6c 6c 20 63 6f 6e 74 69 6e 75 65 20 74   will continue t
30ac0 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64 2e 0a  o be supported..
30ad0 2a 2a 0a 2a 2a 20 5e 49 6e 20 74 68 65 20 6c 65  **.** ^In the le
30ae0 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20  gacy interface, 
30af0 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  the return value
30b00 20 77 69 6c 6c 20 62 65 20 65 69 74 68 65 72 20   will be either 
30b10 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2c 0a 2a  [SQLITE_BUSY],.*
30b20 2a 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c  * [SQLITE_DONE],
30b30 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 5b   [SQLITE_ROW], [
30b40 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c 20 6f  SQLITE_ERROR], o
30b50 72 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  r [SQLITE_MISUSE
30b60 5d 2e 0a 2a 2a 20 5e 57 69 74 68 20 74 68 65 20  ]..** ^With the 
30b70 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 2c 20  "v2" interface, 
30b80 61 6e 79 20 6f 66 20 74 68 65 20 6f 74 68 65 72  any of the other
30b90 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20   [result codes] 
30ba0 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20  or.** [extended 
30bb0 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 6d 69  result codes] mi
30bc0 67 68 74 20 62 65 20 72 65 74 75 72 6e 65 64 20  ght be returned 
30bd0 61 73 20 77 65 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e  as well..**.** ^
30be0 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 6d 65  [SQLITE_BUSY] me
30bf0 61 6e 73 20 74 68 61 74 20 74 68 65 20 64 61 74  ans that the dat
30c00 61 62 61 73 65 20 65 6e 67 69 6e 65 20 77 61 73  abase engine was
30c10 20 75 6e 61 62 6c 65 20 74 6f 20 61 63 71 75 69   unable to acqui
30c20 72 65 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61  re the.** databa
30c30 73 65 20 6c 6f 63 6b 73 20 69 74 20 6e 65 65 64  se locks it need
30c40 73 20 74 6f 20 64 6f 20 69 74 73 20 6a 6f 62 2e  s to do its job.
30c50 20 20 5e 49 66 20 74 68 65 20 73 74 61 74 65 6d    ^If the statem
30c60 65 6e 74 20 69 73 20 61 20 5b 43 4f 4d 4d 49 54  ent is a [COMMIT
30c70 5d 0a 2a 2a 20 6f 72 20 6f 63 63 75 72 73 20 6f  ].** or occurs o
30c80 75 74 73 69 64 65 20 6f 66 20 61 6e 20 65 78 70  utside of an exp
30c90 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f  licit transactio
30ca0 6e 2c 20 74 68 65 6e 20 79 6f 75 20 63 61 6e 20  n, then you can 
30cb0 72 65 74 72 79 20 74 68 65 0a 2a 2a 20 73 74 61  retry the.** sta
30cc0 74 65 6d 65 6e 74 2e 20 20 49 66 20 74 68 65 20  tement.  If the 
30cd0 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6e 6f 74  statement is not
30ce0 20 61 20 5b 43 4f 4d 4d 49 54 5d 20 61 6e 64 20   a [COMMIT] and 
30cf0 6f 63 63 75 72 73 20 77 69 74 68 69 6e 20 61 6e  occurs within an
30d00 0a 2a 2a 20 65 78 70 6c 69 63 69 74 20 74 72 61  .** explicit tra
30d10 6e 73 61 63 74 69 6f 6e 20 74 68 65 6e 20 79 6f  nsaction then yo
30d20 75 20 73 68 6f 75 6c 64 20 72 6f 6c 6c 62 61 63  u should rollbac
30d30 6b 20 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f  k the transactio
30d40 6e 20 62 65 66 6f 72 65 0a 2a 2a 20 63 6f 6e 74  n before.** cont
30d50 69 6e 75 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 5b  inuing..**.** ^[
30d60 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 20 6d 65 61  SQLITE_DONE] mea
30d70 6e 73 20 74 68 61 74 20 74 68 65 20 73 74 61 74  ns that the stat
30d80 65 6d 65 6e 74 20 68 61 73 20 66 69 6e 69 73 68  ement has finish
30d90 65 64 20 65 78 65 63 75 74 69 6e 67 0a 2a 2a 20  ed executing.** 
30da0 73 75 63 63 65 73 73 66 75 6c 6c 79 2e 20 20 73  successfully.  s
30db0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 73 68  qlite3_step() sh
30dc0 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63 61 6c 6c  ould not be call
30dd0 65 64 20 61 67 61 69 6e 20 6f 6e 20 74 68 69 73  ed again on this
30de0 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 63 68   virtual.** mach
30df0 69 6e 65 20 77 69 74 68 6f 75 74 20 66 69 72 73  ine without firs
30e00 74 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74  t calling [sqlit
30e10 65 33 5f 72 65 73 65 74 28 29 5d 20 74 6f 20 72  e3_reset()] to r
30e20 65 73 65 74 20 74 68 65 20 76 69 72 74 75 61 6c  eset the virtual
30e30 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 62 61 63 6b  .** machine back
30e40 20 74 6f 20 69 74 73 20 69 6e 69 74 69 61 6c 20   to its initial 
30e50 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  state..**.** ^If
30e60 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
30e70 6e 74 20 62 65 69 6e 67 20 65 78 65 63 75 74 65  nt being execute
30e80 64 20 72 65 74 75 72 6e 73 20 61 6e 79 20 64 61  d returns any da
30e90 74 61 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54 45  ta, then [SQLITE
30ea0 5f 52 4f 57 5d 0a 2a 2a 20 69 73 20 72 65 74 75  _ROW].** is retu
30eb0 72 6e 65 64 20 65 61 63 68 20 74 69 6d 65 20 61  rned each time a
30ec0 20 6e 65 77 20 72 6f 77 20 6f 66 20 64 61 74 61   new row of data
30ed0 20 69 73 20 72 65 61 64 79 20 66 6f 72 20 70 72   is ready for pr
30ee0 6f 63 65 73 73 69 6e 67 20 62 79 20 74 68 65 0a  ocessing by the.
30ef0 2a 2a 20 63 61 6c 6c 65 72 2e 20 54 68 65 20 76  ** caller. The v
30f00 61 6c 75 65 73 20 6d 61 79 20 62 65 20 61 63 63  alues may be acc
30f10 65 73 73 65 64 20 75 73 69 6e 67 20 74 68 65 20  essed using the 
30f20 5b 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 66  [column access f
30f30 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 73 71  unctions]..** sq
30f40 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69 73 20  lite3_step() is 
30f50 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 74 6f 20  called again to 
30f60 72 65 74 72 69 65 76 65 20 74 68 65 20 6e 65 78  retrieve the nex
30f70 74 20 72 6f 77 20 6f 66 20 64 61 74 61 2e 0a 2a  t row of data..*
30f80 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 45 52  *.** ^[SQLITE_ER
30f90 52 4f 52 5d 20 6d 65 61 6e 73 20 74 68 61 74 20  ROR] means that 
30fa0 61 20 72 75 6e 2d 74 69 6d 65 20 65 72 72 6f 72  a run-time error
30fb0 20 28 73 75 63 68 20 61 73 20 61 20 63 6f 6e 73   (such as a cons
30fc0 74 72 61 69 6e 74 0a 2a 2a 20 76 69 6f 6c 61 74  traint.** violat
30fd0 69 6f 6e 29 20 68 61 73 20 6f 63 63 75 72 72 65  ion) has occurre
30fe0 64 2e 20 20 73 71 6c 69 74 65 33 5f 73 74 65 70  d.  sqlite3_step
30ff0 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65  () should not be
31000 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e   called again on
31010 0a 2a 2a 20 74 68 65 20 56 4d 2e 20 4d 6f 72 65  .** the VM. More
31020 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 6d 61 79   information may
31030 20 62 65 20 66 6f 75 6e 64 20 62 79 20 63 61 6c   be found by cal
31040 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65 72  ling [sqlite3_er
31050 72 6d 73 67 28 29 5d 2e 0a 2a 2a 20 5e 57 69 74  rmsg()]..** ^Wit
31060 68 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74  h the legacy int
31070 65 72 66 61 63 65 2c 20 61 20 6d 6f 72 65 20 73  erface, a more s
31080 70 65 63 69 66 69 63 20 65 72 72 6f 72 20 63 6f  pecific error co
31090 64 65 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 2c  de (for example,
310a0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45  .** [SQLITE_INTE
310b0 52 52 55 50 54 5d 2c 20 5b 53 51 4c 49 54 45 5f  RRUPT], [SQLITE_
310c0 53 43 48 45 4d 41 5d 2c 20 5b 53 51 4c 49 54 45  SCHEMA], [SQLITE
310d0 5f 43 4f 52 52 55 50 54 5d 2c 20 61 6e 64 20 73  _CORRUPT], and s
310e0 6f 20 66 6f 72 74 68 29 0a 2a 2a 20 63 61 6e 20  o forth).** can 
310f0 62 65 20 6f 62 74 61 69 6e 65 64 20 62 79 20 63  be obtained by c
31100 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  alling [sqlite3_
31110 72 65 73 65 74 28 29 5d 20 6f 6e 20 74 68 65 0a  reset()] on the.
31120 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  ** [prepared sta
31130 74 65 6d 65 6e 74 5d 2e 20 20 5e 49 6e 20 74 68  tement].  ^In th
31140 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65  e "v2" interface
31150 2c 0a 2a 2a 20 74 68 65 20 6d 6f 72 65 20 73 70  ,.** the more sp
31160 65 63 69 66 69 63 20 65 72 72 6f 72 20 63 6f 64  ecific error cod
31170 65 20 69 73 20 72 65 74 75 72 6e 65 64 20 64 69  e is returned di
31180 72 65 63 74 6c 79 20 62 79 20 73 71 6c 69 74 65  rectly by sqlite
31190 33 5f 73 74 65 70 28 29 2e 0a 2a 2a 0a 2a 2a 20  3_step()..**.** 
311a0 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20  [SQLITE_MISUSE] 
311b0 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 74  means that the t
311c0 68 69 73 20 72 6f 75 74 69 6e 65 20 77 61 73 20  his routine was 
311d0 63 61 6c 6c 65 64 20 69 6e 61 70 70 72 6f 70 72  called inappropr
311e0 69 61 74 65 6c 79 2e 0a 2a 2a 20 50 65 72 68 61  iately..** Perha
311f0 70 73 20 69 74 20 77 61 73 20 63 61 6c 6c 65 64  ps it was called
31200 20 6f 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20   on a [prepared 
31210 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20  statement] that 
31220 68 61 73 0a 2a 2a 20 61 6c 72 65 61 64 79 20 62  has.** already b
31230 65 65 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e  een [sqlite3_fin
31240 61 6c 69 7a 65 20 7c 20 66 69 6e 61 6c 69 7a 65  alize | finalize
31250 64 5d 20 6f 72 20 6f 6e 20 6f 6e 65 20 74 68 61  d] or on one tha
31260 74 20 68 61 64 0a 2a 2a 20 70 72 65 76 69 6f 75  t had.** previou
31270 73 6c 79 20 72 65 74 75 72 6e 65 64 20 5b 53 51  sly returned [SQ
31280 4c 49 54 45 5f 45 52 52 4f 52 5d 20 6f 72 20 5b  LITE_ERROR] or [
31290 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20 20 4f  SQLITE_DONE].  O
312a0 72 20 69 74 20 63 6f 75 6c 64 0a 2a 2a 20 62 65  r it could.** be
312b0 20 74 68 65 20 63 61 73 65 20 74 68 61 74 20 74   the case that t
312c0 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65  he same database
312d0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 62   connection is b
312e0 65 69 6e 67 20 75 73 65 64 20 62 79 20 74 77 6f  eing used by two
312f0 20 6f 72 0a 2a 2a 20 6d 6f 72 65 20 74 68 72 65   or.** more thre
31300 61 64 73 20 61 74 20 74 68 65 20 73 61 6d 65 20  ads at the same 
31310 6d 6f 6d 65 6e 74 20 69 6e 20 74 69 6d 65 2e 0a  moment in time..
31320 2a 2a 0a 2a 2a 20 46 6f 72 20 61 6c 6c 20 76 65  **.** For all ve
31330 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65  rsions of SQLite
31340 20 75 70 20 74 6f 20 61 6e 64 20 69 6e 63 6c 75   up to and inclu
31350 64 69 6e 67 20 33 2e 36 2e 32 33 2e 31 2c 20 61  ding 3.6.23.1, a
31360 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c   call to.** [sql
31370 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 77 61  ite3_reset()] wa
31380 73 20 72 65 71 75 69 72 65 64 20 61 66 74 65 72  s required after
31390 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20   sqlite3_step() 
313a0 72 65 74 75 72 6e 65 64 20 61 6e 79 74 68 69 6e  returned anythin
313b0 67 0a 2a 2a 20 6f 74 68 65 72 20 74 68 61 6e 20  g.** other than 
313c0 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 62 65 66  [SQLITE_ROW] bef
313d0 6f 72 65 20 61 6e 79 20 73 75 62 73 65 71 75 65  ore any subseque
313e0 6e 74 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66  nt invocation of
313f0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70  .** sqlite3_step
31400 28 29 2e 20 20 46 61 69 6c 75 72 65 20 74 6f 20  ().  Failure to 
31410 72 65 73 65 74 20 74 68 65 20 70 72 65 70 61 72  reset the prepar
31420 65 64 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69  ed statement usi
31430 6e 67 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ng .** [sqlite3_
31440 72 65 73 65 74 28 29 5d 20 77 6f 75 6c 64 20 72  reset()] would r
31450 65 73 75 6c 74 20 69 6e 20 61 6e 20 5b 53 51 4c  esult in an [SQL
31460 49 54 45 5f 4d 49 53 55 53 45 5d 20 72 65 74 75  ITE_MISUSE] retu
31470 72 6e 20 66 72 6f 6d 0a 2a 2a 20 73 71 6c 69 74  rn from.** sqlit
31480 65 33 5f 73 74 65 70 28 29 2e 20 20 42 75 74 20  e3_step().  But 
31490 61 66 74 65 72 20 5b 76 65 72 73 69 6f 6e 20 33  after [version 3
314a0 2e 36 2e 32 33 2e 31 5d 20 28 5b 64 61 74 65 6f  .6.23.1] ([dateo
314b0 66 3a 33 2e 36 2e 32 33 2e 31 5d 2c 0a 2a 2a 20  f:3.6.23.1],.** 
314c0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 62  sqlite3_step() b
314d0 65 67 61 6e 0a 2a 2a 20 63 61 6c 6c 69 6e 67 20  egan.** calling 
314e0 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
314f0 5d 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  ] automatically 
31500 69 6e 20 74 68 69 73 20 63 69 72 63 75 6d 73 74  in this circumst
31510 61 6e 63 65 20 72 61 74 68 65 72 0a 2a 2a 20 74  ance rather.** t
31520 68 61 6e 20 72 65 74 75 72 6e 69 6e 67 20 5b 53  han returning [S
31530 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20  QLITE_MISUSE].  
31540 54 68 69 73 20 69 73 20 6e 6f 74 20 63 6f 6e 73  This is not cons
31550 69 64 65 72 65 64 20 61 20 63 6f 6d 70 61 74 69  idered a compati
31560 62 69 6c 69 74 79 0a 2a 2a 20 62 72 65 61 6b 20  bility.** break 
31570 62 65 63 61 75 73 65 20 61 6e 79 20 61 70 70 6c  because any appl
31580 69 63 61 74 69 6f 6e 20 74 68 61 74 20 65 76 65  ication that eve
31590 72 20 72 65 63 65 69 76 65 73 20 61 6e 20 53 51  r receives an SQ
315a0 4c 49 54 45 5f 4d 49 53 55 53 45 20 65 72 72 6f  LITE_MISUSE erro
315b0 72 0a 2a 2a 20 69 73 20 62 72 6f 6b 65 6e 20 62  r.** is broken b
315c0 79 20 64 65 66 69 6e 69 74 69 6f 6e 2e 20 20 54  y definition.  T
315d0 68 65 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f  he [SQLITE_OMIT_
315e0 41 55 54 4f 52 45 53 45 54 5d 20 63 6f 6d 70 69  AUTORESET] compi
315f0 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 0a 2a  le-time option.*
31600 2a 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  * can be used to
31610 20 72 65 73 74 6f 72 65 20 74 68 65 20 6c 65 67   restore the leg
31620 61 63 79 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a  acy behavior..**
31630 0a 2a 2a 20 3c 62 3e 47 6f 6f 66 79 20 49 6e 74  .** <b>Goofy Int
31640 65 72 66 61 63 65 20 41 6c 65 72 74 3a 3c 2f 62  erface Alert:</b
31650 3e 20 49 6e 20 74 68 65 20 6c 65 67 61 63 79 20  > In the legacy 
31660 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65 20 73  interface, the s
31670 71 6c 69 74 65 33 5f 73 74 65 70 28 29 0a 2a 2a  qlite3_step().**
31680 20 41 50 49 20 61 6c 77 61 79 73 20 72 65 74 75   API always retu
31690 72 6e 73 20 61 20 67 65 6e 65 72 69 63 20 65 72  rns a generic er
316a0 72 6f 72 20 63 6f 64 65 2c 20 5b 53 51 4c 49 54  ror code, [SQLIT
316b0 45 5f 45 52 52 4f 52 5d 2c 20 66 6f 6c 6c 6f 77  E_ERROR], follow
316c0 69 6e 67 20 61 6e 79 0a 2a 2a 20 65 72 72 6f 72  ing any.** error
316d0 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c   other than [SQL
316e0 49 54 45 5f 42 55 53 59 5d 20 61 6e 64 20 5b 53  ITE_BUSY] and [S
316f0 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20  QLITE_MISUSE].  
31700 59 6f 75 20 6d 75 73 74 20 63 61 6c 6c 0a 2a 2a  You must call.**
31710 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
31720 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66  )] or [sqlite3_f
31730 69 6e 61 6c 69 7a 65 28 29 5d 20 69 6e 20 6f 72  inalize()] in or
31740 64 65 72 20 74 6f 20 66 69 6e 64 20 6f 6e 65 20  der to find one 
31750 6f 66 20 74 68 65 0a 2a 2a 20 73 70 65 63 69 66  of the.** specif
31760 69 63 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d  ic [error codes]
31770 20 74 68 61 74 20 62 65 74 74 65 72 20 64 65 73   that better des
31780 63 72 69 62 65 73 20 74 68 65 20 65 72 72 6f 72  cribes the error
31790 2e 0a 2a 2a 20 57 65 20 61 64 6d 69 74 20 74 68  ..** We admit th
317a0 61 74 20 74 68 69 73 20 69 73 20 61 20 67 6f 6f  at this is a goo
317b0 66 79 20 64 65 73 69 67 6e 2e 20 20 54 68 65 20  fy design.  The 
317c0 70 72 6f 62 6c 65 6d 20 68 61 73 20 62 65 65 6e  problem has been
317d0 20 66 69 78 65 64 0a 2a 2a 20 77 69 74 68 20 74   fixed.** with t
317e0 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63  he "v2" interfac
317f0 65 2e 20 20 49 66 20 79 6f 75 20 70 72 65 70 61  e.  If you prepa
31800 72 65 20 61 6c 6c 20 6f 66 20 79 6f 75 72 20 53  re all of your S
31810 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a  QL statements.**
31820 20 75 73 69 6e 67 20 65 69 74 68 65 72 20 5b 73   using either [s
31830 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
31840 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  2()] or [sqlite3
31850 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d  _prepare16_v2()]
31860 20 69 6e 73 74 65 61 64 0a 2a 2a 20 6f 66 20 74   instead.** of t
31870 68 65 20 6c 65 67 61 63 79 20 5b 73 71 6c 69 74  he legacy [sqlit
31880 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 61 6e  e3_prepare()] an
31890 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  d [sqlite3_prepa
318a0 72 65 31 36 28 29 5d 20 69 6e 74 65 72 66 61 63  re16()] interfac
318b0 65 73 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20  es,.** then the 
318c0 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20 5b 65  more specific [e
318d0 72 72 6f 72 20 63 6f 64 65 73 5d 20 61 72 65 20  rror codes] are 
318e0 72 65 74 75 72 6e 65 64 20 64 69 72 65 63 74 6c  returned directl
318f0 79 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f  y.** by sqlite3_
31900 73 74 65 70 28 29 2e 20 20 54 68 65 20 75 73 65  step().  The use
31910 20 6f 66 20 74 68 65 20 22 76 32 22 20 69 6e 74   of the "v2" int
31920 65 72 66 61 63 65 20 69 73 20 72 65 63 6f 6d 6d  erface is recomm
31930 65 6e 64 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71  ended..*/.int sq
31940 6c 69 74 65 33 5f 73 74 65 70 28 73 71 6c 69 74  lite3_step(sqlit
31950 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a  e3_stmt*);../*.*
31960 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62  * CAPI3REF: Numb
31970 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e  er of columns in
31980 20 61 20 72 65 73 75 6c 74 20 73 65 74 0a 2a 2a   a result set.**
31990 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
319a0 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  _stmt.**.** ^The
319b0 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f   sqlite3_data_co
319c0 75 6e 74 28 50 29 20 69 6e 74 65 72 66 61 63 65  unt(P) interface
319d0 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d   returns the num
319e0 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69  ber of columns i
319f0 6e 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74  n the.** current
31a00 20 72 6f 77 20 6f 66 20 74 68 65 20 72 65 73 75   row of the resu
31a10 6c 74 20 73 65 74 20 6f 66 20 5b 70 72 65 70 61  lt set of [prepa
31a20 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 50  red statement] P
31a30 2e 0a 2a 2a 20 5e 49 66 20 70 72 65 70 61 72 65  ..** ^If prepare
31a40 64 20 73 74 61 74 65 6d 65 6e 74 20 50 20 64 6f  d statement P do
31a50 65 73 20 6e 6f 74 20 68 61 76 65 20 72 65 73 75  es not have resu
31a60 6c 74 73 20 72 65 61 64 79 20 74 6f 20 72 65 74  lts ready to ret
31a70 75 72 6e 0a 2a 2a 20 28 76 69 61 20 63 61 6c 6c  urn.** (via call
31a80 73 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  s to the [sqlite
31a90 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 20 7c 20 73  3_column_int | s
31aa0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 2a 28  qlite3_column_*(
31ab0 29 5d 20 6f 66 0a 2a 2a 20 69 6e 74 65 72 66 61  )] of.** interfa
31ac0 63 65 73 29 20 74 68 65 6e 20 73 71 6c 69 74 65  ces) then sqlite
31ad0 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 20  3_data_count(P) 
31ae0 72 65 74 75 72 6e 73 20 30 2e 0a 2a 2a 20 5e 54  returns 0..** ^T
31af0 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f  he sqlite3_data_
31b00 63 6f 75 6e 74 28 50 29 20 72 6f 75 74 69 6e 65  count(P) routine
31b10 20 61 6c 73 6f 20 72 65 74 75 72 6e 73 20 30 20   also returns 0 
31b20 69 66 20 50 20 69 73 20 61 20 4e 55 4c 4c 20 70  if P is a NULL p
31b30 6f 69 6e 74 65 72 2e 0a 2a 2a 20 5e 54 68 65 20  ointer..** ^The 
31b40 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75  sqlite3_data_cou
31b50 6e 74 28 50 29 20 72 6f 75 74 69 6e 65 20 72 65  nt(P) routine re
31b60 74 75 72 6e 73 20 30 20 69 66 20 74 68 65 20 70  turns 0 if the p
31b70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 0a  revious call to.
31b80 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  ** [sqlite3_step
31b90 5d 28 50 29 20 72 65 74 75 72 6e 65 64 20 5b 53  ](P) returned [S
31ba0 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20 20 5e 54  QLITE_DONE].  ^T
31bb0 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f  he sqlite3_data_
31bc0 63 6f 75 6e 74 28 50 29 0a 2a 2a 20 77 69 6c 6c  count(P).** will
31bd0 20 72 65 74 75 72 6e 20 6e 6f 6e 2d 7a 65 72 6f   return non-zero
31be0 20 69 66 20 70 72 65 76 69 6f 75 73 20 63 61 6c   if previous cal
31bf0 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74  l to [sqlite3_st
31c00 65 70 5d 28 50 29 20 72 65 74 75 72 6e 65 64 0a  ep](P) returned.
31c10 2a 2a 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c  ** [SQLITE_ROW],
31c20 20 65 78 63 65 70 74 20 69 6e 20 74 68 65 20 63   except in the c
31c30 61 73 65 20 6f 66 20 74 68 65 20 5b 50 52 41 47  ase of the [PRAG
31c40 4d 41 20 69 6e 63 72 65 6d 65 6e 74 61 6c 5f 76  MA incremental_v
31c50 61 63 75 75 6d 5d 0a 2a 2a 20 77 68 65 72 65 20  acuum].** where 
31c60 69 74 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e  it always return
31c70 73 20 7a 65 72 6f 20 73 69 6e 63 65 20 65 61 63  s zero since eac
31c80 68 20 73 74 65 70 20 6f 66 20 74 68 61 74 20 6d  h step of that m
31c90 75 6c 74 69 2d 73 74 65 70 0a 2a 2a 20 70 72 61  ulti-step.** pra
31ca0 67 6d 61 20 72 65 74 75 72 6e 73 20 30 20 63 6f  gma returns 0 co
31cb0 6c 75 6d 6e 73 20 6f 66 20 64 61 74 61 2e 0a 2a  lumns of data..*
31cc0 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b  *.** See also: [
31cd0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63  sqlite3_column_c
31ce0 6f 75 6e 74 28 29 5d 0a 2a 2f 0a 69 6e 74 20 73  ount()].*/.int s
31cf0 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e  qlite3_data_coun
31d00 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a  t(sqlite3_stmt *
31d10 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  pStmt);../*.** C
31d20 41 50 49 33 52 45 46 3a 20 46 75 6e 64 61 6d 65  API3REF: Fundame
31d30 6e 74 61 6c 20 44 61 74 61 74 79 70 65 73 0a 2a  ntal Datatypes.*
31d40 2a 20 4b 45 59 57 4f 52 44 53 3a 20 53 51 4c 49  * KEYWORDS: SQLI
31d50 54 45 5f 54 45 58 54 0a 2a 2a 0a 2a 2a 20 5e 28  TE_TEXT.**.** ^(
31d60 45 76 65 72 79 20 76 61 6c 75 65 20 69 6e 20 53  Every value in S
31d70 51 4c 69 74 65 20 68 61 73 20 6f 6e 65 20 6f 66  QLite has one of
31d80 20 66 69 76 65 20 66 75 6e 64 61 6d 65 6e 74 61   five fundamenta
31d90 6c 20 64 61 74 61 74 79 70 65 73 3a 0a 2a 2a 0a  l datatypes:.**.
31da0 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20  ** <ul>.** <li> 
31db0 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e  64-bit signed in
31dc0 74 65 67 65 72 0a 2a 2a 20 3c 6c 69 3e 20 36 34  teger.** <li> 64
31dd0 2d 62 69 74 20 49 45 45 45 20 66 6c 6f 61 74 69  -bit IEEE floati
31de0 6e 67 20 70 6f 69 6e 74 20 6e 75 6d 62 65 72 0a  ng point number.
31df0 2a 2a 20 3c 6c 69 3e 20 73 74 72 69 6e 67 0a 2a  ** <li> string.*
31e00 2a 20 3c 6c 69 3e 20 42 4c 4f 42 0a 2a 2a 20 3c  * <li> BLOB.** <
31e10 6c 69 3e 20 4e 55 4c 4c 0a 2a 2a 20 3c 2f 75 6c  li> NULL.** </ul
31e20 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  >)^.**.** These 
31e30 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 63 6f  constants are co
31e40 64 65 73 20 66 6f 72 20 65 61 63 68 20 6f 66 20  des for each of 
31e50 74 68 6f 73 65 20 74 79 70 65 73 2e 0a 2a 2a 0a  those types..**.
31e60 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65  ** Note that the
31e70 20 53 51 4c 49 54 45 5f 54 45 58 54 20 63 6f 6e   SQLITE_TEXT con
31e80 73 74 61 6e 74 20 77 61 73 20 61 6c 73 6f 20 75  stant was also u
31e90 73 65 64 20 69 6e 20 53 51 4c 69 74 65 20 76 65  sed in SQLite ve
31ea0 72 73 69 6f 6e 20 32 0a 2a 2a 20 66 6f 72 20 61  rsion 2.** for a
31eb0 20 63 6f 6d 70 6c 65 74 65 6c 79 20 64 69 66 66   completely diff
31ec0 65 72 65 6e 74 20 6d 65 61 6e 69 6e 67 2e 20 20  erent meaning.  
31ed0 53 6f 66 74 77 61 72 65 20 74 68 61 74 20 6c 69  Software that li
31ee0 6e 6b 73 20 61 67 61 69 6e 73 74 20 62 6f 74 68  nks against both
31ef0 0a 2a 2a 20 53 51 4c 69 74 65 20 76 65 72 73 69  .** SQLite versi
31f00 6f 6e 20 32 20 61 6e 64 20 53 51 4c 69 74 65 20  on 2 and SQLite 
31f10 76 65 72 73 69 6f 6e 20 33 20 73 68 6f 75 6c 64  version 3 should
31f20 20 75 73 65 20 53 51 4c 49 54 45 33 5f 54 45 58   use SQLITE3_TEX
31f30 54 2c 20 6e 6f 74 0a 2a 2a 20 53 51 4c 49 54 45  T, not.** SQLITE
31f40 5f 54 45 58 54 2e 0a 2a 2f 0a 23 64 65 66 69 6e  _TEXT..*/.#defin
31f50 65 20 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52  e SQLITE_INTEGER
31f60 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    1.#define SQLI
31f70 54 45 5f 46 4c 4f 41 54 20 20 20 20 32 0a 23 64  TE_FLOAT    2.#d
31f80 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 4c 4f  efine SQLITE_BLO
31f90 42 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20  B     4.#define 
31fa0 53 51 4c 49 54 45 5f 4e 55 4c 4c 20 20 20 20 20  SQLITE_NULL     
31fb0 35 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f  5.#ifdef SQLITE_
31fc0 54 45 58 54 0a 23 20 75 6e 64 65 66 20 53 51 4c  TEXT.# undef SQL
31fd0 49 54 45 5f 54 45 58 54 0a 23 65 6c 73 65 0a 23  ITE_TEXT.#else.#
31fe0 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54   define SQLITE_T
31ff0 45 58 54 20 20 20 20 20 33 0a 23 65 6e 64 69 66  EXT     3.#endif
32000 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 33  .#define SQLITE3
32010 5f 54 45 58 54 20 20 20 20 20 33 0a 0a 2f 2a 0a  _TEXT     3../*.
32020 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73  ** CAPI3REF: Res
32030 75 6c 74 20 56 61 6c 75 65 73 20 46 72 6f 6d 20  ult Values From 
32040 41 20 51 75 65 72 79 0a 2a 2a 20 4b 45 59 57 4f  A Query.** KEYWO
32050 52 44 53 3a 20 7b 63 6f 6c 75 6d 6e 20 61 63 63  RDS: {column acc
32060 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 7d 0a 2a  ess functions}.*
32070 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65  * METHOD: sqlite
32080 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68  3_stmt.**.** ^Th
32090 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74  ese routines ret
320a0 75 72 6e 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  urn information 
320b0 61 62 6f 75 74 20 61 20 73 69 6e 67 6c 65 20 63  about a single c
320c0 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 63 75 72  olumn of the cur
320d0 72 65 6e 74 0a 2a 2a 20 72 65 73 75 6c 74 20 72  rent.** result r
320e0 6f 77 20 6f 66 20 61 20 71 75 65 72 79 2e 20 20  ow of a query.  
320f0 5e 49 6e 20 65 76 65 72 79 20 63 61 73 65 20 74  ^In every case t
32100 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
32110 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72 0a 2a  t is a pointer.*
32120 2a 20 74 6f 20 74 68 65 20 5b 70 72 65 70 61 72  * to the [prepar
32130 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68  ed statement] th
32140 61 74 20 69 73 20 62 65 69 6e 67 20 65 76 61 6c  at is being eval
32150 75 61 74 65 64 20 28 74 68 65 20 5b 73 71 6c 69  uated (the [sqli
32160 74 65 33 5f 73 74 6d 74 2a 5d 0a 2a 2a 20 74 68  te3_stmt*].** th
32170 61 74 20 77 61 73 20 72 65 74 75 72 6e 65 64 20  at was returned 
32180 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 70 72  from [sqlite3_pr
32190 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 6f  epare_v2()] or o
321a0 6e 65 20 6f 66 20 69 74 73 20 76 61 72 69 61 6e  ne of its varian
321b0 74 73 29 0a 2a 2a 20 61 6e 64 20 74 68 65 20 73  ts).** and the s
321c0 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69  econd argument i
321d0 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74  s the index of t
321e0 68 65 20 63 6f 6c 75 6d 6e 20 66 6f 72 20 77 68  he column for wh
321f0 69 63 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a  ich information.
32200 2a 2a 20 73 68 6f 75 6c 64 20 62 65 20 72 65 74  ** should be ret
32210 75 72 6e 65 64 2e 20 5e 54 68 65 20 6c 65 66 74  urned. ^The left
32220 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 74  most column of t
32230 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 68 61  he result set ha
32240 73 20 74 68 65 20 69 6e 64 65 78 20 30 2e 0a 2a  s the index 0..*
32250 2a 20 5e 54 68 65 20 6e 75 6d 62 65 72 20 6f 66  * ^The number of
32260 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20   columns in the 
32270 72 65 73 75 6c 74 20 63 61 6e 20 62 65 20 64 65  result can be de
32280 74 65 72 6d 69 6e 65 64 20 75 73 69 6e 67 0a 2a  termined using.*
32290 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  * [sqlite3_colum
322a0 6e 5f 63 6f 75 6e 74 28 29 5d 2e 0a 2a 2a 0a 2a  n_count()]..**.*
322b0 2a 20 49 66 20 74 68 65 20 53 51 4c 20 73 74 61  * If the SQL sta
322c0 74 65 6d 65 6e 74 20 64 6f 65 73 20 6e 6f 74 20  tement does not 
322d0 63 75 72 72 65 6e 74 6c 79 20 70 6f 69 6e 74 20  currently point 
322e0 74 6f 20 61 20 76 61 6c 69 64 20 72 6f 77 2c 20  to a valid row, 
322f0 6f 72 20 69 66 20 74 68 65 0a 2a 2a 20 63 6f 6c  or if the.** col
32300 75 6d 6e 20 69 6e 64 65 78 20 69 73 20 6f 75 74  umn index is out
32310 20 6f 66 20 72 61 6e 67 65 2c 20 74 68 65 20 72   of range, the r
32320 65 73 75 6c 74 20 69 73 20 75 6e 64 65 66 69 6e  esult is undefin
32330 65 64 2e 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  ed..** These rou
32340 74 69 6e 65 73 20 6d 61 79 20 6f 6e 6c 79 20 62  tines may only b
32350 65 20 63 61 6c 6c 65 64 20 77 68 65 6e 20 74 68  e called when th
32360 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61  e most recent ca
32370 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  ll to.** [sqlite
32380 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20 72 65  3_step()] has re
32390 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 52  turned [SQLITE_R
323a0 4f 57 5d 20 61 6e 64 20 6e 65 69 74 68 65 72 0a  OW] and neither.
323b0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  ** [sqlite3_rese
323c0 74 28 29 5d 20 6e 6f 72 20 5b 73 71 6c 69 74 65  t()] nor [sqlite
323d0 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 68 61  3_finalize()] ha
323e0 76 65 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 73  ve been called s
323f0 75 62 73 65 71 75 65 6e 74 6c 79 2e 0a 2a 2a 20  ubsequently..** 
32400 49 66 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20  If any of these 
32410 72 6f 75 74 69 6e 65 73 20 61 72 65 20 63 61 6c  routines are cal
32420 6c 65 64 20 61 66 74 65 72 20 5b 73 71 6c 69 74  led after [sqlit
32430 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a  e3_reset()] or.*
32440 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  * [sqlite3_final
32450 69 7a 65 28 29 5d 20 6f 72 20 61 66 74 65 72 20  ize()] or after 
32460 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
32470 20 68 61 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a   has returned.**
32480 20 73 6f 6d 65 74 68 69 6e 67 20 6f 74 68 65 72   something other
32490 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 52 4f   than [SQLITE_RO
324a0 57 5d 2c 20 74 68 65 20 72 65 73 75 6c 74 73 20  W], the results 
324b0 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a  are undefined..*
324c0 2a 20 49 66 20 5b 73 71 6c 69 74 65 33 5f 73 74  * If [sqlite3_st
324d0 65 70 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  ep()] or [sqlite
324e0 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 20 5b 73  3_reset()] or [s
324f0 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
32500 29 5d 0a 2a 2a 20 61 72 65 20 63 61 6c 6c 65 64  )].** are called
32510 20 66 72 6f 6d 20 61 20 64 69 66 66 65 72 65 6e   from a differen
32520 74 20 74 68 72 65 61 64 20 77 68 69 6c 65 20 61  t thread while a
32530 6e 79 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74  ny of these rout
32540 69 6e 65 73 0a 2a 2a 20 61 72 65 20 70 65 6e 64  ines.** are pend
32550 69 6e 67 2c 20 74 68 65 6e 20 74 68 65 20 72 65  ing, then the re
32560 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69  sults are undefi
32570 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ned..**.** ^The 
32580 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
32590 79 70 65 28 29 20 72 6f 75 74 69 6e 65 20 72 65  ype() routine re
325a0 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20 5b 53 51  turns the.** [SQ
325b0 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 7c 20 64  LITE_INTEGER | d
325c0 61 74 61 74 79 70 65 20 63 6f 64 65 5d 20 66 6f  atatype code] fo
325d0 72 20 74 68 65 20 69 6e 69 74 69 61 6c 20 64 61  r the initial da
325e0 74 61 20 74 79 70 65 0a 2a 2a 20 6f 66 20 74 68  ta type.** of th
325f0 65 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 2e  e result column.
32600 20 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20    ^The returned 
32610 76 61 6c 75 65 20 69 73 20 6f 6e 65 20 6f 66 20  value is one of 
32620 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 5d  [SQLITE_INTEGER]
32630 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 4c 4f  ,.** [SQLITE_FLO
32640 41 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 54 45 58  AT], [SQLITE_TEX
32650 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 42 4c 4f 42  T], [SQLITE_BLOB
32660 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4e 55  ], or [SQLITE_NU
32670 4c 4c 5d 2e 20 20 54 68 65 20 76 61 6c 75 65 0a  LL].  The value.
32680 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 79 20 73  ** returned by s
32690 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79  qlite3_column_ty
326a0 70 65 28 29 20 69 73 20 6f 6e 6c 79 20 6d 65 61  pe() is only mea
326b0 6e 69 6e 67 66 75 6c 20 69 66 20 6e 6f 20 74 79  ningful if no ty
326c0 70 65 0a 2a 2a 20 63 6f 6e 76 65 72 73 69 6f 6e  pe.** conversion
326d0 73 20 68 61 76 65 20 6f 63 63 75 72 72 65 64 20  s have occurred 
326e0 61 73 20 64 65 73 63 72 69 62 65 64 20 62 65 6c  as described bel
326f0 6f 77 2e 20 20 41 66 74 65 72 20 61 20 74 79 70  ow.  After a typ
32700 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2c 0a 2a 2a  e conversion,.**
32710 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72   the value retur
32720 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63  ned by sqlite3_c
32730 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 69 73 20  olumn_type() is 
32740 75 6e 64 65 66 69 6e 65 64 2e 20 20 46 75 74 75  undefined.  Futu
32750 72 65 0a 2a 2a 20 76 65 72 73 69 6f 6e 73 20 6f  re.** versions o
32760 66 20 53 51 4c 69 74 65 20 6d 61 79 20 63 68 61  f SQLite may cha
32770 6e 67 65 20 74 68 65 20 62 65 68 61 76 69 6f 72  nge the behavior
32780 20 6f 66 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   of sqlite3_colu
32790 6d 6e 5f 74 79 70 65 28 29 0a 2a 2a 20 66 6f 6c  mn_type().** fol
327a0 6c 6f 77 69 6e 67 20 61 20 74 79 70 65 20 63 6f  lowing a type co
327b0 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  nversion..**.** 
327c0 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69  ^If the result i
327d0 73 20 61 20 42 4c 4f 42 20 6f 72 20 55 54 46 2d  s a BLOB or UTF-
327e0 38 20 73 74 72 69 6e 67 20 74 68 65 6e 20 74 68  8 string then th
327f0 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  e sqlite3_column
32800 5f 62 79 74 65 73 28 29 0a 2a 2a 20 72 6f 75 74  _bytes().** rout
32810 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 20  ine returns the 
32820 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
32830 69 6e 20 74 68 61 74 20 42 4c 4f 42 20 6f 72 20  in that BLOB or 
32840 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74  string..** ^If t
32850 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 55  he result is a U
32860 54 46 2d 31 36 20 73 74 72 69 6e 67 2c 20 74 68  TF-16 string, th
32870 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  en sqlite3_colum
32880 6e 5f 62 79 74 65 73 28 29 20 63 6f 6e 76 65 72  n_bytes() conver
32890 74 73 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67  ts.** the string
328a0 20 74 6f 20 55 54 46 2d 38 20 61 6e 64 20 74 68   to UTF-8 and th
328b0 65 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e  en returns the n
328c0 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 2e 0a  umber of bytes..
328d0 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c  ** ^If the resul
328e0 74 20 69 73 20 61 20 6e 75 6d 65 72 69 63 20 76  t is a numeric v
328f0 61 6c 75 65 20 74 68 65 6e 20 73 71 6c 69 74 65  alue then sqlite
32900 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
32910 20 75 73 65 73 0a 2a 2a 20 5b 73 71 6c 69 74 65   uses.** [sqlite
32920 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 74 6f  3_snprintf()] to
32930 20 63 6f 6e 76 65 72 74 20 74 68 61 74 20 76 61   convert that va
32940 6c 75 65 20 74 6f 20 61 20 55 54 46 2d 38 20 73  lue to a UTF-8 s
32950 74 72 69 6e 67 20 61 6e 64 20 72 65 74 75 72 6e  tring and return
32960 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20  s.** the number 
32970 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 61 74  of bytes in that
32980 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20   string..** ^If 
32990 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 4e 55  the result is NU
329a0 4c 4c 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33  LL, then sqlite3
329b0 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20  _column_bytes() 
329c0 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a  returns zero..**
329d0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75  .** ^If the resu
329e0 6c 74 20 69 73 20 61 20 42 4c 4f 42 20 6f 72 20  lt is a BLOB or 
329f0 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20 74 68  UTF-16 string th
32a00 65 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63  en the sqlite3_c
32a10 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 0a  olumn_bytes16().
32a20 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  ** routine retur
32a30 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ns the number of
32a40 20 62 79 74 65 73 20 69 6e 20 74 68 61 74 20 42   bytes in that B
32a50 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 2e 0a 2a  LOB or string..*
32a60 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74  * ^If the result
32a70 20 69 73 20 61 20 55 54 46 2d 38 20 73 74 72 69   is a UTF-8 stri
32a80 6e 67 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33  ng, then sqlite3
32a90 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
32aa0 29 20 63 6f 6e 76 65 72 74 73 0a 2a 2a 20 74 68  ) converts.** th
32ab0 65 20 73 74 72 69 6e 67 20 74 6f 20 55 54 46 2d  e string to UTF-
32ac0 31 36 20 61 6e 64 20 74 68 65 6e 20 72 65 74 75  16 and then retu
32ad0 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  rns the number o
32ae0 66 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 49 66 20  f bytes..** ^If 
32af0 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20  the result is a 
32b00 6e 75 6d 65 72 69 63 20 76 61 6c 75 65 20 74 68  numeric value th
32b10 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  en sqlite3_colum
32b20 6e 5f 62 79 74 65 73 31 36 28 29 20 75 73 65 73  n_bytes16() uses
32b30 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70  .** [sqlite3_snp
32b40 72 69 6e 74 66 28 29 5d 20 74 6f 20 63 6f 6e 76  rintf()] to conv
32b50 65 72 74 20 74 68 61 74 20 76 61 6c 75 65 20 74  ert that value t
32b60 6f 20 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e  o a UTF-16 strin
32b70 67 20 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a 2a  g and returns.**
32b80 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62   the number of b
32b90 79 74 65 73 20 69 6e 20 74 68 61 74 20 73 74 72  ytes in that str
32ba0 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ing..** ^If the 
32bb0 72 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c 2c 20  result is NULL, 
32bc0 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c  then sqlite3_col
32bd0 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 72 65  umn_bytes16() re
32be0 74 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a  turns zero..**.*
32bf0 2a 20 5e 54 68 65 20 76 61 6c 75 65 73 20 72 65  * ^The values re
32c00 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74  turned by [sqlit
32c10 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
32c20 29 5d 20 61 6e 64 20 0a 2a 2a 20 5b 73 71 6c 69  )] and .** [sqli
32c30 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
32c40 31 36 28 29 5d 20 64 6f 20 6e 6f 74 20 69 6e 63  16()] do not inc
32c50 6c 75 64 65 20 74 68 65 20 7a 65 72 6f 20 74 65  lude the zero te
32c60 72 6d 69 6e 61 74 6f 72 73 20 61 74 20 74 68 65  rminators at the
32c70 20 65 6e 64 0a 2a 2a 20 6f 66 20 74 68 65 20 73   end.** of the s
32c80 74 72 69 6e 67 2e 20 20 5e 46 6f 72 20 63 6c 61  tring.  ^For cla
32c90 72 69 74 79 3a 20 74 68 65 20 76 61 6c 75 65 73  rity: the values
32ca0 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20   returned by.** 
32cb0 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
32cc0 62 79 74 65 73 28 29 5d 20 61 6e 64 20 5b 73 71  bytes()] and [sq
32cd0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
32ce0 65 73 31 36 28 29 5d 20 61 72 65 20 74 68 65 20  es16()] are the 
32cf0 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 62 79 74  number of.** byt
32d00 65 73 20 69 6e 20 74 68 65 20 73 74 72 69 6e 67  es in the string
32d10 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62 65 72  , not the number
32d20 20 6f 66 20 63 68 61 72 61 63 74 65 72 73 2e 0a   of characters..
32d30 2a 2a 0a 2a 2a 20 5e 53 74 72 69 6e 67 73 20 72  **.** ^Strings r
32d40 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74  eturned by sqlit
32d50 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29  e3_column_text()
32d60 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c   and sqlite3_col
32d70 75 6d 6e 5f 74 65 78 74 31 36 28 29 2c 0a 2a 2a  umn_text16(),.**
32d80 20 65 76 65 6e 20 65 6d 70 74 79 20 73 74 72 69   even empty stri
32d90 6e 67 73 2c 20 61 72 65 20 61 6c 77 61 79 73 20  ngs, are always 
32da0 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 2e  zero-terminated.
32db0 20 20 5e 54 68 65 20 72 65 74 75 72 6e 0a 2a 2a    ^The return.**
32dc0 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69   value from sqli
32dd0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28  te3_column_blob(
32de0 29 20 66 6f 72 20 61 20 7a 65 72 6f 2d 6c 65 6e  ) for a zero-len
32df0 67 74 68 20 42 4c 4f 42 20 69 73 20 61 20 4e 55  gth BLOB is a NU
32e00 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a  LL pointer..**.*
32e10 2a 20 3c 62 3e 57 61 72 6e 69 6e 67 3a 3c 2f 62  * <b>Warning:</b
32e20 3e 20 5e 54 68 65 20 6f 62 6a 65 63 74 20 72 65  > ^The object re
32e30 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74  turned by [sqlit
32e40 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28  e3_column_value(
32e50 29 5d 20 69 73 20 61 6e 0a 2a 2a 20 5b 75 6e 70  )] is an.** [unp
32e60 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
32e70 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 2e 20  _value] object. 
32e80 20 49 6e 20 61 20 6d 75 6c 74 69 74 68 72 65 61   In a multithrea
32e90 64 65 64 20 65 6e 76 69 72 6f 6e 6d 65 6e 74 2c  ded environment,
32ea0 0a 2a 2a 20 61 6e 20 75 6e 70 72 6f 74 65 63 74  .** an unprotect
32eb0 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
32ec0 20 6f 62 6a 65 63 74 20 6d 61 79 20 6f 6e 6c 79   object may only
32ed0 20 62 65 20 75 73 65 64 20 73 61 66 65 6c 79 20   be used safely 
32ee0 77 69 74 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  with.** [sqlite3
32ef0 5f 62 69 6e 64 5f 76 61 6c 75 65 28 29 5d 20 61  _bind_value()] a
32f00 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75  nd [sqlite3_resu
32f10 6c 74 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20  lt_value()]..** 
32f20 49 66 20 74 68 65 20 5b 75 6e 70 72 6f 74 65 63  If the [unprotec
32f30 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
32f40 65 5d 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e  e] object return
32f50 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65  ed by.** [sqlite
32f60 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29  3_column_value()
32f70 5d 20 69 73 20 75 73 65 64 20 69 6e 20 61 6e 79  ] is used in any
32f80 20 6f 74 68 65 72 20 77 61 79 2c 20 69 6e 63 6c   other way, incl
32f90 75 64 69 6e 67 20 63 61 6c 6c 73 0a 2a 2a 20 74  uding calls.** t
32fa0 6f 20 72 6f 75 74 69 6e 65 73 20 6c 69 6b 65 20  o routines like 
32fb0 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69  [sqlite3_value_i
32fc0 6e 74 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  nt()], [sqlite3_
32fd0 76 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 0a 2a  value_text()],.*
32fe0 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 76 61  * or [sqlite3_va
32ff0 6c 75 65 5f 62 79 74 65 73 28 29 5d 2c 20 74 68  lue_bytes()], th
33000 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 6e 6f  e behavior is no
33010 74 20 74 68 72 65 61 64 73 61 66 65 2e 0a 2a 2a  t threadsafe..**
33020 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
33030 65 73 20 61 74 74 65 6d 70 74 20 74 6f 20 63 6f  es attempt to co
33040 6e 76 65 72 74 20 74 68 65 20 76 61 6c 75 65 20  nvert the value 
33050 77 68 65 72 65 20 61 70 70 72 6f 70 72 69 61 74  where appropriat
33060 65 2e 20 20 5e 46 6f 72 0a 2a 2a 20 65 78 61 6d  e.  ^For.** exam
33070 70 6c 65 2c 20 69 66 20 74 68 65 20 69 6e 74 65  ple, if the inte
33080 72 6e 61 6c 20 72 65 70 72 65 73 65 6e 74 61 74  rnal representat
33090 69 6f 6e 20 69 73 20 46 4c 4f 41 54 20 61 6e 64  ion is FLOAT and
330a0 20 61 20 74 65 78 74 20 72 65 73 75 6c 74 0a 2a   a text result.*
330b0 2a 20 69 73 20 72 65 71 75 65 73 74 65 64 2c 20  * is requested, 
330c0 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74  [sqlite3_snprint
330d0 66 28 29 5d 20 69 73 20 75 73 65 64 20 69 6e 74  f()] is used int
330e0 65 72 6e 61 6c 6c 79 20 74 6f 20 70 65 72 66 6f  ernally to perfo
330f0 72 6d 20 74 68 65 0a 2a 2a 20 63 6f 6e 76 65 72  rm the.** conver
33100 73 69 6f 6e 20 61 75 74 6f 6d 61 74 69 63 61 6c  sion automatical
33110 6c 79 2e 20 20 5e 28 54 68 65 20 66 6f 6c 6c 6f  ly.  ^(The follo
33120 77 69 6e 67 20 74 61 62 6c 65 20 64 65 74 61 69  wing table detai
33130 6c 73 20 74 68 65 20 63 6f 6e 76 65 72 73 69 6f  ls the conversio
33140 6e 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 61  ns.** that are a
33150 70 70 6c 69 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 62  pplied:.**.** <b
33160 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 20 3c 74  lockquote>.** <t
33170 61 62 6c 65 20 62 6f 72 64 65 72 3d 22 31 22 3e  able border="1">
33180 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20 49 6e 74  .** <tr><th> Int
33190 65 72 6e 61 6c 3c 62 72 3e 54 79 70 65 20 3c 74  ernal<br>Type <t
331a0 68 3e 20 52 65 71 75 65 73 74 65 64 3c 62 72 3e  h> Requested<br>
331b0 54 79 70 65 20 3c 74 68 3e 20 20 43 6f 6e 76 65  Type <th>  Conve
331c0 72 73 69 6f 6e 0a 2a 2a 0a 2a 2a 20 3c 74 72 3e  rsion.**.** <tr>
331d0 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74  <td>  NULL    <t
331e0 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64  d> INTEGER   <td
331f0 3e 20 52 65 73 75 6c 74 20 69 73 20 30 0a 2a 2a  > Result is 0.**
33200 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20   <tr><td>  NULL 
33210 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20     <td>  FLOAT  
33220 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73    <td> Result is
33230 20 30 2e 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e   0.0.** <tr><td>
33240 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20    NULL    <td>  
33250 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 52 65   TEXT    <td> Re
33260 73 75 6c 74 20 69 73 20 61 20 4e 55 4c 4c 20 70  sult is a NULL p
33270 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74  ointer.** <tr><t
33280 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e  d>  NULL    <td>
33290 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20     BLOB    <td> 
332a0 52 65 73 75 6c 74 20 69 73 20 61 20 4e 55 4c 4c  Result is a NULL
332b0 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e   pointer.** <tr>
332c0 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74  <td> INTEGER  <t
332d0 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64  d>  FLOAT    <td
332e0 3e 20 43 6f 6e 76 65 72 74 20 66 72 6f 6d 20 69  > Convert from i
332f0 6e 74 65 67 65 72 20 74 6f 20 66 6c 6f 61 74 0a  nteger to float.
33300 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45  ** <tr><td> INTE
33310 47 45 52 20 20 3c 74 64 3e 20 20 20 54 45 58 54  GER  <td>   TEXT
33320 20 20 20 20 3c 74 64 3e 20 41 53 43 49 49 20 72      <td> ASCII r
33330 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65 20  endering of the 
33340 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 74 72 3e 3c  integer.** <tr><
33350 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64  td> INTEGER  <td
33360 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e  >   BLOB    <td>
33370 20 53 61 6d 65 20 61 73 20 49 4e 54 45 47 45 52   Same as INTEGER
33380 2d 3e 54 45 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74  ->TEXT.** <tr><t
33390 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e  d>  FLOAT   <td>
333a0 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20   INTEGER   <td> 
333b0 5b 43 41 53 54 5d 20 74 6f 20 49 4e 54 45 47 45  [CAST] to INTEGE
333c0 52 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46  R.** <tr><td>  F
333d0 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20 20 54 45  LOAT   <td>   TE
333e0 58 54 20 20 20 20 3c 74 64 3e 20 41 53 43 49 49  XT    <td> ASCII
333f0 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68   rendering of th
33400 65 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c  e float.** <tr><
33410 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64  td>  FLOAT   <td
33420 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e  >   BLOB    <td>
33430 20 5b 43 41 53 54 5d 20 74 6f 20 42 4c 4f 42 0a   [CAST] to BLOB.
33440 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58  ** <tr><td>  TEX
33450 54 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45  T    <td> INTEGE
33460 52 20 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20  R   <td> [CAST] 
33470 74 6f 20 49 4e 54 45 47 45 52 0a 2a 2a 20 3c 74  to INTEGER.** <t
33480 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20  r><td>  TEXT    
33490 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c  <td>  FLOAT    <
334a0 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20 52 45  td> [CAST] to RE
334b0 41 4c 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  AL.** <tr><td>  
334c0 54 45 58 54 20 20 20 20 3c 74 64 3e 20 20 20 42  TEXT    <td>   B
334d0 4c 4f 42 20 20 20 20 3c 74 64 3e 20 4e 6f 20 63  LOB    <td> No c
334e0 68 61 6e 67 65 0a 2a 2a 20 3c 74 72 3e 3c 74 64  hange.** <tr><td
334f0 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20  >  BLOB    <td> 
33500 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 5b  INTEGER   <td> [
33510 43 41 53 54 5d 20 74 6f 20 49 4e 54 45 47 45 52  CAST] to INTEGER
33520 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c  .** <tr><td>  BL
33530 4f 42 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41  OB    <td>  FLOA
33540 54 20 20 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d  T    <td> [CAST]
33550 20 74 6f 20 52 45 41 4c 0a 2a 2a 20 3c 74 72 3e   to REAL.** <tr>
33560 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74  <td>  BLOB    <t
33570 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74 64  d>   TEXT    <td
33580 3e 20 41 64 64 20 61 20 7a 65 72 6f 20 74 65 72  > Add a zero ter
33590 6d 69 6e 61 74 6f 72 20 69 66 20 6e 65 65 64 65  minator if neede
335a0 64 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a  d.** </table>.**
335b0 20 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e   </blockquote>)^
335c0 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74  .**.** Note that
335d0 20 77 68 65 6e 20 74 79 70 65 20 63 6f 6e 76 65   when type conve
335e0 72 73 69 6f 6e 73 20 6f 63 63 75 72 2c 20 70 6f  rsions occur, po
335f0 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64 20  inters returned 
33600 62 79 20 70 72 69 6f 72 0a 2a 2a 20 63 61 6c 6c  by prior.** call
33610 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c  s to sqlite3_col
33620 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20 73 71 6c 69  umn_blob(), sqli
33630 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
33640 29 2c 20 61 6e 64 2f 6f 72 0a 2a 2a 20 73 71 6c  ), and/or.** sql
33650 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
33660 31 36 28 29 20 6d 61 79 20 62 65 20 69 6e 76 61  16() may be inva
33670 6c 69 64 61 74 65 64 2e 0a 2a 2a 20 54 79 70 65  lidated..** Type
33680 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 61 6e 64   conversions and
33690 20 70 6f 69 6e 74 65 72 20 69 6e 76 61 6c 69 64   pointer invalid
336a0 61 74 69 6f 6e 73 20 6d 69 67 68 74 20 6f 63 63  ations might occ
336b0 75 72 0a 2a 2a 20 69 6e 20 74 68 65 20 66 6f 6c  ur.** in the fol
336c0 6c 6f 77 69 6e 67 20 63 61 73 65 73 3a 0a 2a 2a  lowing cases:.**
336d0 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
336e0 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e   The initial con
336f0 74 65 6e 74 20 69 73 20 61 20 42 4c 4f 42 20 61  tent is a BLOB a
33700 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nd sqlite3_colum
33710 6e 5f 74 65 78 74 28 29 20 6f 72 0a 2a 2a 20 20  n_text() or.**  
33720 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75      sqlite3_colu
33730 6d 6e 5f 74 65 78 74 31 36 28 29 20 69 73 20 63  mn_text16() is c
33740 61 6c 6c 65 64 2e 20 20 41 20 7a 65 72 6f 2d 74  alled.  A zero-t
33750 65 72 6d 69 6e 61 74 6f 72 20 6d 69 67 68 74 0a  erminator might.
33760 2a 2a 20 20 20 20 20 20 6e 65 65 64 20 74 6f 20  **      need to 
33770 62 65 20 61 64 64 65 64 20 74 6f 20 74 68 65 20  be added to the 
33780 73 74 72 69 6e 67 2e 3c 2f 6c 69 3e 0a 2a 2a 20  string.</li>.** 
33790 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74 69 61 6c  <li> The initial
337a0 20 63 6f 6e 74 65 6e 74 20 69 73 20 55 54 46 2d   content is UTF-
337b0 38 20 74 65 78 74 20 61 6e 64 20 73 71 6c 69 74  8 text and sqlit
337c0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
337d0 36 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73  6() or.**      s
337e0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
337f0 78 74 31 36 28 29 20 69 73 20 63 61 6c 6c 65 64  xt16() is called
33800 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e 74 20 6d  .  The content m
33810 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64  ust be converted
33820 0a 2a 2a 20 20 20 20 20 20 74 6f 20 55 54 46 2d  .**      to UTF-
33830 31 36 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e  16.</li>.** <li>
33840 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e   The initial con
33850 74 65 6e 74 20 69 73 20 55 54 46 2d 31 36 20 74  tent is UTF-16 t
33860 65 78 74 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  ext and sqlite3_
33870 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f  column_bytes() o
33880 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 74 65  r.**      sqlite
33890 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20  3_column_text() 
338a0 69 73 20 63 61 6c 6c 65 64 2e 20 20 54 68 65 20  is called.  The 
338b0 63 6f 6e 74 65 6e 74 20 6d 75 73 74 20 62 65 20  content must be 
338c0 63 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 20 20 20  converted.**    
338d0 20 20 74 6f 20 55 54 46 2d 38 2e 3c 2f 6c 69 3e    to UTF-8.</li>
338e0 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20  .** </ul>.**.** 
338f0 5e 43 6f 6e 76 65 72 73 69 6f 6e 73 20 62 65 74  ^Conversions bet
33900 77 65 65 6e 20 55 54 46 2d 31 36 62 65 20 61 6e  ween UTF-16be an
33910 64 20 55 54 46 2d 31 36 6c 65 20 61 72 65 20 61  d UTF-16le are a
33920 6c 77 61 79 73 20 64 6f 6e 65 20 69 6e 20 70 6c  lways done in pl
33930 61 63 65 20 61 6e 64 20 64 6f 0a 2a 2a 20 6e 6f  ace and do.** no
33940 74 20 69 6e 76 61 6c 69 64 61 74 65 20 61 20 70  t invalidate a p
33950 72 69 6f 72 20 70 6f 69 6e 74 65 72 2c 20 74 68  rior pointer, th
33960 6f 75 67 68 20 6f 66 20 63 6f 75 72 73 65 20 74  ough of course t
33970 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68  he content of th
33980 65 20 62 75 66 66 65 72 0a 2a 2a 20 74 68 61 74  e buffer.** that
33990 20 74 68 65 20 70 72 69 6f 72 20 70 6f 69 6e 74   the prior point
339a0 65 72 20 72 65 66 65 72 65 6e 63 65 73 20 77 69  er references wi
339b0 6c 6c 20 68 61 76 65 20 62 65 65 6e 20 6d 6f 64  ll have been mod
339c0 69 66 69 65 64 2e 20 20 4f 74 68 65 72 20 6b 69  ified.  Other ki
339d0 6e 64 73 0a 2a 2a 20 6f 66 20 63 6f 6e 76 65 72  nds.** of conver
339e0 73 69 6f 6e 20 61 72 65 20 64 6f 6e 65 20 69 6e  sion are done in
339f0 20 70 6c 61 63 65 20 77 68 65 6e 20 69 74 20 69   place when it i
33a00 73 20 70 6f 73 73 69 62 6c 65 2c 20 62 75 74 20  s possible, but 
33a10 73 6f 6d 65 74 69 6d 65 73 20 74 68 65 79 0a 2a  sometimes they.*
33a20 2a 20 61 72 65 20 6e 6f 74 20 70 6f 73 73 69 62  * are not possib
33a30 6c 65 20 61 6e 64 20 69 6e 20 74 68 6f 73 65 20  le and in those 
33a40 63 61 73 65 73 20 70 72 69 6f 72 20 70 6f 69 6e  cases prior poin
33a50 74 65 72 73 20 61 72 65 20 69 6e 76 61 6c 69 64  ters are invalid
33a60 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ated..**.** The 
33a70 73 61 66 65 73 74 20 70 6f 6c 69 63 79 20 69 73  safest policy is
33a80 20 74 6f 20 69 6e 76 6f 6b 65 20 74 68 65 73 65   to invoke these
33a90 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 69 6e 20   routines.** in 
33aa0 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f  one of the follo
33ab0 77 69 6e 67 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a  wing ways:.**.**
33ac0 20 3c 75 6c 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71   <ul>.**  <li>sq
33ad0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
33ae0 74 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20  t() followed by 
33af0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
33b00 79 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20  ytes()</li>.**  
33b10 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75  <li>sqlite3_colu
33b20 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f 6c 6c 6f 77  mn_blob() follow
33b30 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f  ed by sqlite3_co
33b40 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3c 2f 6c 69  lumn_bytes()</li
33b50 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65  >.**  <li>sqlite
33b60 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28  3_column_text16(
33b70 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71  ) followed by sq
33b80 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
33b90 65 73 31 36 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 3c  es16()</li>.** <
33ba0 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 6f 74  /ul>.**.** In ot
33bb0 68 65 72 20 77 6f 72 64 73 2c 20 79 6f 75 20 73  her words, you s
33bc0 68 6f 75 6c 64 20 63 61 6c 6c 20 73 71 6c 69 74  hould call sqlit
33bd0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29  e3_column_text()
33be0 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c  ,.** sqlite3_col
33bf0 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20 6f 72 20 73  umn_blob(), or s
33c00 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
33c10 78 74 31 36 28 29 20 66 69 72 73 74 20 74 6f 20  xt16() first to 
33c20 66 6f 72 63 65 20 74 68 65 20 72 65 73 75 6c 74  force the result
33c30 0a 2a 2a 20 69 6e 74 6f 20 74 68 65 20 64 65 73  .** into the des
33c40 69 72 65 64 20 66 6f 72 6d 61 74 2c 20 74 68 65  ired format, the
33c50 6e 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33  n invoke sqlite3
33c60 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20  _column_bytes() 
33c70 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f  or.** sqlite3_co
33c80 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 74  lumn_bytes16() t
33c90 6f 20 66 69 6e 64 20 74 68 65 20 73 69 7a 65 20  o find the size 
33ca0 6f 66 20 74 68 65 20 72 65 73 75 6c 74 2e 20 20  of the result.  
33cb0 44 6f 20 6e 6f 74 20 6d 69 78 20 63 61 6c 6c 73  Do not mix calls
33cc0 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  .** to sqlite3_c
33cd0 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 6f 72 20  olumn_text() or 
33ce0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
33cf0 6c 6f 62 28 29 20 77 69 74 68 20 63 61 6c 6c 73  lob() with calls
33d00 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63   to.** sqlite3_c
33d10 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 2c  olumn_bytes16(),
33d20 20 61 6e 64 20 64 6f 20 6e 6f 74 20 6d 69 78 20   and do not mix 
33d30 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33  calls to sqlite3
33d40 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29  _column_text16()
33d50 0a 2a 2a 20 77 69 74 68 20 63 61 6c 6c 73 20 74  .** with calls t
33d60 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  o sqlite3_column
33d70 5f 62 79 74 65 73 28 29 2e 0a 2a 2a 0a 2a 2a 20  _bytes()..**.** 
33d80 5e 54 68 65 20 70 6f 69 6e 74 65 72 73 20 72 65  ^The pointers re
33d90 74 75 72 6e 65 64 20 61 72 65 20 76 61 6c 69 64  turned are valid
33da0 20 75 6e 74 69 6c 20 61 20 74 79 70 65 20 63 6f   until a type co
33db0 6e 76 65 72 73 69 6f 6e 20 6f 63 63 75 72 73 20  nversion occurs 
33dc0 61 73 0a 2a 2a 20 64 65 73 63 72 69 62 65 64 20  as.** described 
33dd0 61 62 6f 76 65 2c 20 6f 72 20 75 6e 74 69 6c 20  above, or until 
33de0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
33df0 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73   or [sqlite3_res
33e00 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c  et()] or.** [sql
33e10 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
33e20 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 5e 54 68   is called.  ^Th
33e30 65 20 6d 65 6d 6f 72 79 20 73 70 61 63 65 20 75  e memory space u
33e40 73 65 64 20 74 6f 20 68 6f 6c 64 20 73 74 72 69  sed to hold stri
33e50 6e 67 73 0a 2a 2a 20 61 6e 64 20 42 4c 4f 42 73  ngs.** and BLOBs
33e60 20 69 73 20 66 72 65 65 64 20 61 75 74 6f 6d 61   is freed automa
33e70 74 69 63 61 6c 6c 79 2e 20 20 44 6f 20 3c 65 6d  tically.  Do <em
33e80 3e 6e 6f 74 3c 2f 65 6d 3e 20 70 61 73 73 20 74  >not</em> pass t
33e90 68 65 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75  he pointers retu
33ea0 72 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71  rned.** from [sq
33eb0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f  lite3_column_blo
33ec0 62 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63  b()], [sqlite3_c
33ed0 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2c 20 65  olumn_text()], e
33ee0 74 63 2e 20 69 6e 74 6f 0a 2a 2a 20 5b 73 71 6c  tc. into.** [sql
33ef0 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a  ite3_free()]..**
33f00 0a 2a 2a 20 5e 28 49 66 20 61 20 6d 65 6d 6f 72  .** ^(If a memor
33f10 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72  y allocation err
33f20 6f 72 20 6f 63 63 75 72 73 20 64 75 72 69 6e 67  or occurs during
33f30 20 74 68 65 20 65 76 61 6c 75 61 74 69 6f 6e 20   the evaluation 
33f40 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66 20 74 68 65  of any.** of the
33f50 73 65 20 72 6f 75 74 69 6e 65 73 2c 20 61 20 64  se routines, a d
33f60 65 66 61 75 6c 74 20 76 61 6c 75 65 20 69 73 20  efault value is 
33f70 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65 20 64  returned.  The d
33f80 65 66 61 75 6c 74 20 76 61 6c 75 65 0a 2a 2a 20  efault value.** 
33f90 69 73 20 65 69 74 68 65 72 20 74 68 65 20 69 6e  is either the in
33fa0 74 65 67 65 72 20 30 2c 20 74 68 65 20 66 6c 6f  teger 0, the flo
33fb0 61 74 69 6e 67 20 70 6f 69 6e 74 20 6e 75 6d 62  ating point numb
33fc0 65 72 20 30 2e 30 2c 20 6f 72 20 61 20 4e 55 4c  er 0.0, or a NUL
33fd0 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 2e 20 20 53  L.** pointer.  S
33fe0 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20  ubsequent calls 
33ff0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63  to [sqlite3_errc
34000 6f 64 65 28 29 5d 20 77 69 6c 6c 20 72 65 74 75  ode()] will retu
34010 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4e 4f  rn.** [SQLITE_NO
34020 4d 45 4d 5d 2e 29 5e 0a 2a 2f 0a 63 6f 6e 73 74  MEM].)^.*/.const
34030 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63   void *sqlite3_c
34040 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 73 71 6c 69 74  olumn_blob(sqlit
34050 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
34060 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  ol);.int sqlite3
34070 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 73 71  _column_bytes(sq
34080 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
34090 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69   iCol);.int sqli
340a0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
340b0 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  16(sqlite3_stmt*
340c0 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 64 6f 75  , int iCol);.dou
340d0 62 6c 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ble sqlite3_colu
340e0 6d 6e 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65  mn_double(sqlite
340f0 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
34100 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  l);.int sqlite3_
34110 63 6f 6c 75 6d 6e 5f 69 6e 74 28 73 71 6c 69 74  column_int(sqlit
34120 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
34130 6f 6c 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74  ol);.sqlite3_int
34140 36 34 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  64 sqlite3_colum
34150 6e 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f  n_int64(sqlite3_
34160 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
34170 3b 0a 63 6f 6e 73 74 20 75 6e 73 69 67 6e 65 64  ;.const unsigned
34180 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63   char *sqlite3_c
34190 6f 6c 75 6d 6e 5f 74 65 78 74 28 73 71 6c 69 74  olumn_text(sqlit
341a0 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
341b0 6f 6c 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20  ol);.const void 
341c0 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
341d0 74 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f 73  text16(sqlite3_s
341e0 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
341f0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c  .int sqlite3_col
34200 75 6d 6e 5f 74 79 70 65 28 73 71 6c 69 74 65 33  umn_type(sqlite3
34210 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
34220 29 3b 0a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  );.sqlite3_value
34230 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
34240 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f 73  _value(sqlite3_s
34250 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
34260 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
34270 3a 20 44 65 73 74 72 6f 79 20 41 20 50 72 65 70  : Destroy A Prep
34280 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20 4f  ared Statement O
34290 62 6a 65 63 74 0a 2a 2a 20 44 45 53 54 52 55 43  bject.** DESTRUC
342a0 54 4f 52 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d  TOR: sqlite3_stm
342b0 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  t.**.** ^The sql
342c0 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20  ite3_finalize() 
342d0 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 61 6c 6c  function is call
342e0 65 64 20 74 6f 20 64 65 6c 65 74 65 20 61 20 5b  ed to delete a [
342f0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
34300 6e 74 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  nt]..** ^If the 
34310 6d 6f 73 74 20 72 65 63 65 6e 74 20 65 76 61 6c  most recent eval
34320 75 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 73 74  uation of the st
34330 61 74 65 6d 65 6e 74 20 65 6e 63 6f 75 6e 74 65  atement encounte
34340 72 65 64 20 6e 6f 20 65 72 72 6f 72 73 0a 2a 2a  red no errors.**
34350 20 6f 72 20 69 66 20 74 68 65 20 73 74 61 74 65   or if the state
34360 6d 65 6e 74 20 69 73 20 6e 65 76 65 72 20 62 65  ment is never be
34370 65 6e 20 65 76 61 6c 75 61 74 65 64 2c 20 74 68  en evaluated, th
34380 65 6e 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  en sqlite3_final
34390 69 7a 65 28 29 20 72 65 74 75 72 6e 73 0a 2a 2a  ize() returns.**
343a0 20 53 51 4c 49 54 45 5f 4f 4b 2e 20 20 5e 49 66   SQLITE_OK.  ^If
343b0 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
343c0 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20 73   evaluation of s
343d0 74 61 74 65 6d 65 6e 74 20 53 20 66 61 69 6c 65  tatement S faile
343e0 64 2c 20 74 68 65 6e 0a 2a 2a 20 73 71 6c 69 74  d, then.** sqlit
343f0 65 33 5f 66 69 6e 61 6c 69 7a 65 28 53 29 20 72  e3_finalize(S) r
34400 65 74 75 72 6e 73 20 74 68 65 20 61 70 70 72 6f  eturns the appro
34410 70 72 69 61 74 65 20 5b 65 72 72 6f 72 20 63 6f  priate [error co
34420 64 65 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e  de] or.** [exten
34430 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65 5d 2e  ded error code].
34440 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
34450 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 53 29 20  te3_finalize(S) 
34460 72 6f 75 74 69 6e 65 20 63 61 6e 20 62 65 20 63  routine can be c
34470 61 6c 6c 65 64 20 61 74 20 61 6e 79 20 70 6f 69  alled at any poi
34480 6e 74 20 64 75 72 69 6e 67 0a 2a 2a 20 74 68 65  nt during.** the
34490 20 6c 69 66 65 20 63 79 63 6c 65 20 6f 66 20 5b   life cycle of [
344a0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
344b0 6e 74 5d 20 53 3a 0a 2a 2a 20 62 65 66 6f 72 65  nt] S:.** before
344c0 20 73 74 61 74 65 6d 65 6e 74 20 53 20 69 73 20   statement S is 
344d0 65 76 65 72 20 65 76 61 6c 75 61 74 65 64 2c 20  ever evaluated, 
344e0 61 66 74 65 72 0a 2a 2a 20 6f 6e 65 20 6f 72 20  after.** one or 
344f0 6d 6f 72 65 20 63 61 6c 6c 73 20 74 6f 20 5b 73  more calls to [s
34500 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 2c  qlite3_reset()],
34510 20 6f 72 20 61 66 74 65 72 20 61 6e 79 20 63 61   or after any ca
34520 6c 6c 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65  ll.** to [sqlite
34530 33 5f 73 74 65 70 28 29 5d 20 72 65 67 61 72 64  3_step()] regard
34540 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65 72 20  less of whether 
34550 6f 72 20 6e 6f 74 20 74 68 65 20 73 74 61 74 65  or not the state
34560 6d 65 6e 74 20 68 61 73 0a 2a 2a 20 63 6f 6d 70  ment has.** comp
34570 6c 65 74 65 64 20 65 78 65 63 75 74 69 6f 6e 2e  leted execution.
34580 0a 2a 2a 0a 2a 2a 20 5e 49 6e 76 6f 6b 69 6e 67  .**.** ^Invoking
34590 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a   sqlite3_finaliz
345a0 65 28 29 20 6f 6e 20 61 20 4e 55 4c 4c 20 70 6f  e() on a NULL po
345b0 69 6e 74 65 72 20 69 73 20 61 20 68 61 72 6d 6c  inter is a harml
345c0 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2a 0a 2a 2a  ess no-op..**.**
345d0 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   The application
345e0 20 6d 75 73 74 20 66 69 6e 61 6c 69 7a 65 20 65   must finalize e
345f0 76 65 72 79 20 5b 70 72 65 70 61 72 65 64 20 73  very [prepared s
34600 74 61 74 65 6d 65 6e 74 5d 20 69 6e 20 6f 72 64  tatement] in ord
34610 65 72 20 74 6f 20 61 76 6f 69 64 0a 2a 2a 20 72  er to avoid.** r
34620 65 73 6f 75 72 63 65 20 6c 65 61 6b 73 2e 20 20  esource leaks.  
34630 49 74 20 69 73 20 61 20 67 72 69 65 76 6f 75 73  It is a grievous
34640 20 65 72 72 6f 72 20 66 6f 72 20 74 68 65 20 61   error for the a
34650 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f 20 74 72  pplication to tr
34660 79 20 74 6f 20 75 73 65 0a 2a 2a 20 61 20 70 72  y to use.** a pr
34670 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
34680 20 61 66 74 65 72 20 69 74 20 68 61 73 20 62 65   after it has be
34690 65 6e 20 66 69 6e 61 6c 69 7a 65 64 2e 20 20 41  en finalized.  A
346a0 6e 79 20 75 73 65 20 6f 66 20 61 20 70 72 65 70  ny use of a prep
346b0 61 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e  ared.** statemen
346c0 74 20 61 66 74 65 72 20 69 74 20 68 61 73 20 62  t after it has b
346d0 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64 20 63 61  een finalized ca
346e0 6e 20 72 65 73 75 6c 74 20 69 6e 20 75 6e 64 65  n result in unde
346f0 66 69 6e 65 64 20 61 6e 64 0a 2a 2a 20 75 6e 64  fined and.** und
34700 65 73 69 72 61 62 6c 65 20 62 65 68 61 76 69 6f  esirable behavio
34710 72 20 73 75 63 68 20 61 73 20 73 65 67 66 61 75  r such as segfau
34720 6c 74 73 20 61 6e 64 20 68 65 61 70 20 63 6f 72  lts and heap cor
34730 72 75 70 74 69 6f 6e 2e 0a 2a 2f 0a 69 6e 74 20  ruption..*/.int 
34740 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
34750 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70  (sqlite3_stmt *p
34760 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  Stmt);../*.** CA
34770 50 49 33 52 45 46 3a 20 52 65 73 65 74 20 41 20  PI3REF: Reset A 
34780 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65  Prepared Stateme
34790 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 20 4d 45 54  nt Object.** MET
347a0 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d  HOD: sqlite3_stm
347b0 74 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  t.**.** The sqli
347c0 74 65 33 5f 72 65 73 65 74 28 29 20 66 75 6e 63  te3_reset() func
347d0 74 69 6f 6e 20 69 73 20 63 61 6c 6c 65 64 20 74  tion is called t
347e0 6f 20 72 65 73 65 74 20 61 20 5b 70 72 65 70 61  o reset a [prepa
347f0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a  red statement].*
34800 2a 20 6f 62 6a 65 63 74 20 62 61 63 6b 20 74 6f  * object back to
34810 20 69 74 73 20 69 6e 69 74 69 61 6c 20 73 74 61   its initial sta
34820 74 65 2c 20 72 65 61 64 79 20 74 6f 20 62 65 20  te, ready to be 
34830 72 65 2d 65 78 65 63 75 74 65 64 2e 0a 2a 2a 20  re-executed..** 
34840 5e 41 6e 79 20 53 51 4c 20 73 74 61 74 65 6d 65  ^Any SQL stateme
34850 6e 74 20 76 61 72 69 61 62 6c 65 73 20 74 68 61  nt variables tha
34860 74 20 68 61 64 20 76 61 6c 75 65 73 20 62 6f 75  t had values bou
34870 6e 64 20 74 6f 20 74 68 65 6d 20 75 73 69 6e 67  nd to them using
34880 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33  .** the [sqlite3
34890 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 73 71 6c  _bind_blob | sql
348a0 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 41 50  ite3_bind_*() AP
348b0 49 5d 20 72 65 74 61 69 6e 20 74 68 65 69 72 20  I] retain their 
348c0 76 61 6c 75 65 73 2e 0a 2a 2a 20 55 73 65 20 5b  values..** Use [
348d0 73 71 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62 69  sqlite3_clear_bi
348e0 6e 64 69 6e 67 73 28 29 5d 20 74 6f 20 72 65 73  ndings()] to res
348f0 65 74 20 74 68 65 20 62 69 6e 64 69 6e 67 73 2e  et the bindings.
34900 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c  .**.** ^The [sql
34910 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20 69  ite3_reset(S)] i
34920 6e 74 65 72 66 61 63 65 20 72 65 73 65 74 73 20  nterface resets 
34930 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
34940 61 74 65 6d 65 6e 74 5d 20 53 0a 2a 2a 20 62 61  atement] S.** ba
34950 63 6b 20 74 6f 20 74 68 65 20 62 65 67 69 6e 6e  ck to the beginn
34960 69 6e 67 20 6f 66 20 69 74 73 20 70 72 6f 67 72  ing of its progr
34970 61 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  am..**.** ^If th
34980 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61  e most recent ca
34990 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73  ll to [sqlite3_s
349a0 74 65 70 28 53 29 5d 20 66 6f 72 20 74 68 65 0a  tep(S)] for the.
349b0 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  ** [prepared sta
349c0 74 65 6d 65 6e 74 5d 20 53 20 72 65 74 75 72 6e  tement] S return
349d0 65 64 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20  ed [SQLITE_ROW] 
349e0 6f 72 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d  or [SQLITE_DONE]
349f0 2c 0a 2a 2a 20 6f 72 20 69 66 20 5b 73 71 6c 69  ,.** or if [sqli
34a00 74 65 33 5f 73 74 65 70 28 53 29 5d 20 68 61 73  te3_step(S)] has
34a10 20 6e 65 76 65 72 20 62 65 66 6f 72 65 20 62 65   never before be
34a20 65 6e 20 63 61 6c 6c 65 64 20 6f 6e 20 53 2c 0a  en called on S,.
34a30 2a 2a 20 74 68 65 6e 20 5b 73 71 6c 69 74 65 33  ** then [sqlite3
34a40 5f 72 65 73 65 74 28 53 29 5d 20 72 65 74 75 72  _reset(S)] retur
34a50 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a  ns [SQLITE_OK]..
34a60 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f  **.** ^If the mo
34a70 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74  st recent call t
34a80 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  o [sqlite3_step(
34a90 53 29 5d 20 66 6f 72 20 74 68 65 0a 2a 2a 20 5b  S)] for the.** [
34aa0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
34ab0 6e 74 5d 20 53 20 69 6e 64 69 63 61 74 65 64 20  nt] S indicated 
34ac0 61 6e 20 65 72 72 6f 72 2c 20 74 68 65 6e 0a 2a  an error, then.*
34ad0 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  * [sqlite3_reset
34ae0 28 53 29 5d 20 72 65 74 75 72 6e 73 20 61 6e 20  (S)] returns an 
34af0 61 70 70 72 6f 70 72 69 61 74 65 20 5b 65 72 72  appropriate [err
34b00 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20  or code]..**.** 
34b10 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65  ^The [sqlite3_re
34b20 73 65 74 28 53 29 5d 20 69 6e 74 65 72 66 61 63  set(S)] interfac
34b30 65 20 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67  e does not chang
34b40 65 20 74 68 65 20 76 61 6c 75 65 73 0a 2a 2a 20  e the values.** 
34b50 6f 66 20 61 6e 79 20 5b 73 71 6c 69 74 65 33 5f  of any [sqlite3_
34b60 62 69 6e 64 5f 62 6c 6f 62 7c 62 69 6e 64 69 6e  bind_blob|bindin
34b70 67 73 5d 20 6f 6e 20 74 68 65 20 5b 70 72 65 70  gs] on the [prep
34b80 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
34b90 53 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  S..*/.int sqlite
34ba0 33 5f 72 65 73 65 74 28 73 71 6c 69 74 65 33 5f  3_reset(sqlite3_
34bb0 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f  stmt *pStmt);../
34bc0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
34bd0 72 65 61 74 65 20 4f 72 20 52 65 64 65 66 69 6e  reate Or Redefin
34be0 65 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 73 0a  e SQL Functions.
34bf0 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 66 75  ** KEYWORDS: {fu
34c00 6e 63 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20  nction creation 
34c10 72 6f 75 74 69 6e 65 73 7d 0a 2a 2a 20 4b 45 59  routines}.** KEY
34c20 57 4f 52 44 53 3a 20 7b 61 70 70 6c 69 63 61 74  WORDS: {applicat
34c30 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20  ion-defined SQL 
34c40 66 75 6e 63 74 69 6f 6e 7d 0a 2a 2a 20 4b 45 59  function}.** KEY
34c50 57 4f 52 44 53 3a 20 7b 61 70 70 6c 69 63 61 74  WORDS: {applicat
34c60 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20  ion-defined SQL 
34c70 66 75 6e 63 74 69 6f 6e 73 7d 0a 2a 2a 20 4d 45  functions}.** ME
34c80 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a  THOD: sqlite3.**
34c90 0a 2a 2a 20 5e 54 68 65 73 65 20 66 75 6e 63 74  .** ^These funct
34ca0 69 6f 6e 73 20 28 63 6f 6c 6c 65 63 74 69 76 65  ions (collective
34cb0 6c 79 20 6b 6e 6f 77 6e 20 61 73 20 22 66 75 6e  ly known as "fun
34cc0 63 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20 72  ction creation r
34cd0 6f 75 74 69 6e 65 73 22 29 0a 2a 2a 20 61 72 65  outines").** are
34ce0 20 75 73 65 64 20 74 6f 20 61 64 64 20 53 51 4c   used to add SQL
34cf0 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20 61 67   functions or ag
34d00 67 72 65 67 61 74 65 73 20 6f 72 20 74 6f 20 72  gregates or to r
34d10 65 64 65 66 69 6e 65 20 74 68 65 20 62 65 68 61  edefine the beha
34d20 76 69 6f 72 0a 2a 2a 20 6f 66 20 65 78 69 73 74  vior.** of exist
34d30 69 6e 67 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ing SQL function
34d40 73 20 6f 72 20 61 67 67 72 65 67 61 74 65 73 2e  s or aggregates.
34d50 20 20 54 68 65 20 6f 6e 6c 79 20 64 69 66 66 65    The only diffe
34d60 72 65 6e 63 65 73 20 62 65 74 77 65 65 6e 0a 2a  rences between.*
34d70 2a 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * these routines
34d80 20 61 72 65 20 74 68 65 20 74 65 78 74 20 65 6e   are the text en
34d90 63 6f 64 69 6e 67 20 65 78 70 65 63 74 65 64 20  coding expected 
34da0 66 6f 72 0a 2a 2a 20 74 68 65 20 73 65 63 6f 6e  for.** the secon
34db0 64 20 70 61 72 61 6d 65 74 65 72 20 28 74 68 65  d parameter (the
34dc0 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 66 75 6e   name of the fun
34dd0 63 74 69 6f 6e 20 62 65 69 6e 67 20 63 72 65 61  ction being crea
34de0 74 65 64 29 0a 2a 2a 20 61 6e 64 20 74 68 65 20  ted).** and the 
34df0 70 72 65 73 65 6e 63 65 20 6f 72 20 61 62 73 65  presence or abse
34e00 6e 63 65 20 6f 66 20 61 20 64 65 73 74 72 75 63  nce of a destruc
34e10 74 6f 72 20 63 61 6c 6c 62 61 63 6b 20 66 6f 72  tor callback for
34e20 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74  .** the applicat
34e30 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74 65 72  ion data pointer
34e40 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72  ..**.** ^The fir
34e50 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  st parameter is 
34e60 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
34e70 6e 6e 65 63 74 69 6f 6e 5d 20 74 6f 20 77 68 69  nnection] to whi
34e80 63 68 20 74 68 65 20 53 51 4c 0a 2a 2a 20 66 75  ch the SQL.** fu
34e90 6e 63 74 69 6f 6e 20 69 73 20 74 6f 20 62 65 20  nction is to be 
34ea0 61 64 64 65 64 2e 20 20 5e 49 66 20 61 6e 20 61  added.  ^If an a
34eb0 70 70 6c 69 63 61 74 69 6f 6e 20 75 73 65 73 20  pplication uses 
34ec0 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 64 61  more than one da
34ed0 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63  tabase.** connec
34ee0 74 69 6f 6e 20 74 68 65 6e 20 61 70 70 6c 69 63  tion then applic
34ef0 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51  ation-defined SQ
34f00 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6d 75 73 74  L functions must
34f10 20 62 65 20 61 64 64 65 64 0a 2a 2a 20 74 6f 20   be added.** to 
34f20 65 61 63 68 20 64 61 74 61 62 61 73 65 20 63 6f  each database co
34f30 6e 6e 65 63 74 69 6f 6e 20 73 65 70 61 72 61 74  nnection separat
34f40 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ely..**.** ^The 
34f50 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
34f60 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20   is the name of 
34f70 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  the SQL function
34f80 20 74 6f 20 62 65 20 63 72 65 61 74 65 64 20 6f   to be created o
34f90 72 0a 2a 2a 20 72 65 64 65 66 69 6e 65 64 2e 20  r.** redefined. 
34fa0 20 5e 54 68 65 20 6c 65 6e 67 74 68 20 6f 66 20   ^The length of 
34fb0 74 68 65 20 6e 61 6d 65 20 69 73 20 6c 69 6d 69  the name is limi
34fc0 74 65 64 20 74 6f 20 32 35 35 20 62 79 74 65 73  ted to 255 bytes
34fd0 20 69 6e 20 61 20 55 54 46 2d 38 0a 2a 2a 20 72   in a UTF-8.** r
34fe0 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 2c 20 65  epresentation, e
34ff0 78 63 6c 75 73 69 76 65 20 6f 66 20 74 68 65 20  xclusive of the 
35000 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 6f 72 2e  zero-terminator.
35010 20 20 5e 4e 6f 74 65 20 74 68 61 74 20 74 68 65    ^Note that the
35020 20 6e 61 6d 65 0a 2a 2a 20 6c 65 6e 67 74 68 20   name.** length 
35030 6c 69 6d 69 74 20 69 73 20 69 6e 20 55 54 46 2d  limit is in UTF-
35040 38 20 62 79 74 65 73 2c 20 6e 6f 74 20 63 68 61  8 bytes, not cha
35050 72 61 63 74 65 72 73 20 6e 6f 72 20 55 54 46 2d  racters nor UTF-
35060 31 36 20 62 79 74 65 73 2e 20 20 0a 2a 2a 20 5e  16 bytes.  .** ^
35070 41 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20 63  Any attempt to c
35080 72 65 61 74 65 20 61 20 66 75 6e 63 74 69 6f 6e  reate a function
35090 20 77 69 74 68 20 61 20 6c 6f 6e 67 65 72 20 6e   with a longer n
350a0 61 6d 65 0a 2a 2a 20 77 69 6c 6c 20 72 65 73 75  ame.** will resu
350b0 6c 74 20 69 6e 20 5b 53 51 4c 49 54 45 5f 4d 49  lt in [SQLITE_MI
350c0 53 55 53 45 5d 20 62 65 69 6e 67 20 72 65 74 75  SUSE] being retu
350d0 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  rned..**.** ^The
350e0 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
350f0 20 28 6e 41 72 67 29 0a 2a 2a 20 69 73 20 74 68   (nArg).** is th
35100 65 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75  e number of argu
35110 6d 65 6e 74 73 20 74 68 61 74 20 74 68 65 20 53  ments that the S
35120 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a  QL function or.*
35130 2a 20 61 67 67 72 65 67 61 74 65 20 74 61 6b 65  * aggregate take
35140 73 2e 20 5e 49 66 20 74 68 69 73 20 70 61 72 61  s. ^If this para
35150 6d 65 74 65 72 20 69 73 20 2d 31 2c 20 74 68 65  meter is -1, the
35160 6e 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69  n the SQL functi
35170 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61  on or.** aggrega
35180 74 65 20 6d 61 79 20 74 61 6b 65 20 61 6e 79 20  te may take any 
35190 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65  number of argume
351a0 6e 74 73 20 62 65 74 77 65 65 6e 20 30 20 61 6e  nts between 0 an
351b0 64 20 74 68 65 20 6c 69 6d 69 74 0a 2a 2a 20 73  d the limit.** s
351c0 65 74 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c  et by [sqlite3_l
351d0 69 6d 69 74 5d 28 5b 53 51 4c 49 54 45 5f 4c 49  imit]([SQLITE_LI
351e0 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47  MIT_FUNCTION_ARG
351f0 5d 29 2e 20 20 49 66 20 74 68 65 20 74 68 69 72  ]).  If the thir
35200 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 69  d.** parameter i
35210 73 20 6c 65 73 73 20 74 68 61 6e 20 2d 31 20 6f  s less than -1 o
35220 72 20 67 72 65 61 74 65 72 20 74 68 61 6e 20 31  r greater than 1
35230 32 37 20 74 68 65 6e 20 74 68 65 20 62 65 68 61  27 then the beha
35240 76 69 6f 72 20 69 73 0a 2a 2a 20 75 6e 64 65 66  vior is.** undef
35250 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ined..**.** ^The
35260 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
35270 72 2c 20 65 54 65 78 74 52 65 70 2c 20 73 70 65  r, eTextRep, spe
35280 63 69 66 69 65 73 20 77 68 61 74 0a 2a 2a 20 5b  cifies what.** [
35290 53 51 4c 49 54 45 5f 55 54 46 38 20 7c 20 74 65  SQLITE_UTF8 | te
352a0 78 74 20 65 6e 63 6f 64 69 6e 67 5d 20 74 68 69  xt encoding] thi
352b0 73 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 70  s SQL function p
352c0 72 65 66 65 72 73 20 66 6f 72 0a 2a 2a 20 69 74  refers for.** it
352d0 73 20 70 61 72 61 6d 65 74 65 72 73 2e 20 20 54  s parameters.  T
352e0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73  he application s
352f0 68 6f 75 6c 64 20 73 65 74 20 74 68 69 73 20 70  hould set this p
35300 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b  arameter to.** [
35310 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d 20  SQLITE_UTF16LE] 
35320 69 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20  if the function 
35330 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69  implementation i
35340 6e 76 6f 6b 65 73 20 0a 2a 2a 20 5b 73 71 6c 69  nvokes .** [sqli
35350 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36  te3_value_text16
35360 6c 65 28 29 5d 20 6f 6e 20 61 6e 20 69 6e 70 75  le()] on an inpu
35370 74 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55 54  t, or [SQLITE_UT
35380 46 31 36 42 45 5d 20 69 66 20 74 68 65 0a 2a 2a  F16BE] if the.**
35390 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
353a0 69 6e 76 6f 6b 65 73 20 5b 73 71 6c 69 74 65 33  invokes [sqlite3
353b0 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 62 65 28  _value_text16be(
353c0 29 5d 20 6f 6e 20 61 6e 20 69 6e 70 75 74 2c 20  )] on an input, 
353d0 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54  or.** [SQLITE_UT
353e0 46 31 36 5d 20 69 66 20 5b 73 71 6c 69 74 65 33  F16] if [sqlite3
353f0 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29 5d  _value_text16()]
35400 20 69 73 20 75 73 65 64 2c 20 6f 72 20 5b 53 51   is used, or [SQ
35410 4c 49 54 45 5f 55 54 46 38 5d 0a 2a 2a 20 6f 74  LITE_UTF8].** ot
35420 68 65 72 77 69 73 65 2e 20 20 5e 54 68 65 20 73  herwise.  ^The s
35430 61 6d 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ame SQL function
35440 20 6d 61 79 20 62 65 20 72 65 67 69 73 74 65 72   may be register
35450 65 64 20 6d 75 6c 74 69 70 6c 65 20 74 69 6d 65  ed multiple time
35460 73 20 75 73 69 6e 67 0a 2a 2a 20 64 69 66 66 65  s using.** diffe
35470 72 65 6e 74 20 70 72 65 66 65 72 72 65 64 20 74  rent preferred t
35480 65 78 74 20 65 6e 63 6f 64 69 6e 67 73 2c 20 77  ext encodings, w
35490 69 74 68 20 64 69 66 66 65 72 65 6e 74 20 69 6d  ith different im
354a0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 66 6f  plementations fo
354b0 72 0a 2a 2a 20 65 61 63 68 20 65 6e 63 6f 64 69  r.** each encodi
354c0 6e 67 2e 0a 2a 2a 20 5e 57 68 65 6e 20 6d 75 6c  ng..** ^When mul
354d0 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61  tiple implementa
354e0 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d  tions of the sam
354f0 65 20 66 75 6e 63 74 69 6f 6e 20 61 72 65 20 61  e function are a
35500 76 61 69 6c 61 62 6c 65 2c 20 53 51 4c 69 74 65  vailable, SQLite
35510 0a 2a 2a 20 77 69 6c 6c 20 70 69 63 6b 20 74 68  .** will pick th
35520 65 20 6f 6e 65 20 74 68 61 74 20 69 6e 76 6f 6c  e one that invol
35530 76 65 73 20 74 68 65 20 6c 65 61 73 74 20 61 6d  ves the least am
35540 6f 75 6e 74 20 6f 66 20 64 61 74 61 20 63 6f 6e  ount of data con
35550 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e  version..**.** ^
35560 54 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  The fourth param
35570 65 74 65 72 20 6d 61 79 20 6f 70 74 69 6f 6e 61  eter may optiona
35580 6c 6c 79 20 62 65 20 4f 52 65 64 20 77 69 74 68  lly be ORed with
35590 20 5b 53 51 4c 49 54 45 5f 44 45 54 45 52 4d 49   [SQLITE_DETERMI
355a0 4e 49 53 54 49 43 5d 0a 2a 2a 20 74 6f 20 73 69  NISTIC].** to si
355b0 67 6e 61 6c 20 74 68 61 74 20 74 68 65 20 66 75  gnal that the fu
355c0 6e 63 74 69 6f 6e 20 77 69 6c 6c 20 61 6c 77 61  nction will alwa
355d0 79 73 20 72 65 74 75 72 6e 20 74 68 65 20 73 61  ys return the sa
355e0 6d 65 20 72 65 73 75 6c 74 20 67 69 76 65 6e 0a  me result given.
355f0 2a 2a 20 74 68 65 20 73 61 6d 65 20 69 6e 70 75  ** the same inpu
35600 74 73 20 77 69 74 68 69 6e 20 61 20 73 69 6e 67  ts within a sing
35610 6c 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  le SQL statement
35620 2e 20 20 4d 6f 73 74 20 53 51 4c 20 66 75 6e 63  .  Most SQL func
35630 74 69 6f 6e 73 20 61 72 65 0a 2a 2a 20 64 65 74  tions are.** det
35640 65 72 6d 69 6e 69 73 74 69 63 2e 20 20 54 68 65  erministic.  The
35650 20 62 75 69 6c 74 2d 69 6e 20 5b 72 61 6e 64 6f   built-in [rando
35660 6d 28 29 5d 20 53 51 4c 20 66 75 6e 63 74 69 6f  m()] SQL functio
35670 6e 20 69 73 20 61 6e 20 65 78 61 6d 70 6c 65 20  n is an example 
35680 6f 66 20 61 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  of a.** function
35690 20 74 68 61 74 20 69 73 20 6e 6f 74 20 64 65 74   that is not det
356a0 65 72 6d 69 6e 69 73 74 69 63 2e 20 20 54 68 65  erministic.  The
356b0 20 53 51 4c 69 74 65 20 71 75 65 72 79 20 70 6c   SQLite query pl
356c0 61 6e 6e 65 72 20 69 73 20 61 62 6c 65 20 74 6f  anner is able to
356d0 0a 2a 2a 20 70 65 72 66 6f 72 6d 20 61 64 64 69  .** perform addi
356e0 74 69 6f 6e 61 6c 20 6f 70 74 69 6d 69 7a 61 74  tional optimizat
356f0 69 6f 6e 73 20 6f 6e 20 64 65 74 65 72 6d 69 6e  ions on determin
35700 69 73 74 69 63 20 66 75 6e 63 74 69 6f 6e 73 2c  istic functions,
35710 20 73 6f 20 75 73 65 0a 2a 2a 20 6f 66 20 74 68   so use.** of th
35720 65 20 5b 53 51 4c 49 54 45 5f 44 45 54 45 52 4d  e [SQLITE_DETERM
35730 49 4e 49 53 54 49 43 5d 20 66 6c 61 67 20 69 73  INISTIC] flag is
35740 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 77 68 65   recommended whe
35750 72 65 20 70 6f 73 73 69 62 6c 65 2e 0a 2a 2a 0a  re possible..**.
35760 2a 2a 20 5e 28 54 68 65 20 66 69 66 74 68 20 70  ** ^(The fifth p
35770 61 72 61 6d 65 74 65 72 20 69 73 20 61 6e 20 61  arameter is an a
35780 72 62 69 74 72 61 72 79 20 70 6f 69 6e 74 65 72  rbitrary pointer
35790 2e 20 20 54 68 65 20 69 6d 70 6c 65 6d 65 6e 74  .  The implement
357a0 61 74 69 6f 6e 20 6f 66 20 74 68 65 0a 2a 2a 20  ation of the.** 
357b0 66 75 6e 63 74 69 6f 6e 20 63 61 6e 20 67 61 69  function can gai
357c0 6e 20 61 63 63 65 73 73 20 74 6f 20 74 68 69 73  n access to this
357d0 20 70 6f 69 6e 74 65 72 20 75 73 69 6e 67 20 5b   pointer using [
357e0 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74  sqlite3_user_dat
357f0 61 28 29 5d 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54  a()].)^.**.** ^T
35800 68 65 20 73 69 78 74 68 2c 20 73 65 76 65 6e 74  he sixth, sevent
35810 68 20 61 6e 64 20 65 69 67 68 74 68 20 70 61 72  h and eighth par
35820 61 6d 65 74 65 72 73 2c 20 78 46 75 6e 63 2c 20  ameters, xFunc, 
35830 78 53 74 65 70 20 61 6e 64 20 78 46 69 6e 61 6c  xStep and xFinal
35840 2c 20 61 72 65 0a 2a 2a 20 70 6f 69 6e 74 65 72  , are.** pointer
35850 73 20 74 6f 20 43 2d 6c 61 6e 67 75 61 67 65 20  s to C-language 
35860 66 75 6e 63 74 69 6f 6e 73 20 74 68 61 74 20 69  functions that i
35870 6d 70 6c 65 6d 65 6e 74 20 74 68 65 20 53 51 4c  mplement the SQL
35880 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20   function or.** 
35890 61 67 67 72 65 67 61 74 65 2e 20 5e 41 20 73 63  aggregate. ^A sc
358a0 61 6c 61 72 20 53 51 4c 20 66 75 6e 63 74 69 6f  alar SQL functio
358b0 6e 20 72 65 71 75 69 72 65 73 20 61 6e 20 69 6d  n requires an im
358c0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
358d0 74 68 65 20 78 46 75 6e 63 0a 2a 2a 20 63 61 6c  the xFunc.** cal
358e0 6c 62 61 63 6b 20 6f 6e 6c 79 3b 20 4e 55 4c 4c  lback only; NULL
358f0 20 70 6f 69 6e 74 65 72 73 20 6d 75 73 74 20 62   pointers must b
35900 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20  e passed as the 
35910 78 53 74 65 70 20 61 6e 64 20 78 46 69 6e 61 6c  xStep and xFinal
35920 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 2e 20  .** parameters. 
35930 5e 41 6e 20 61 67 67 72 65 67 61 74 65 20 53 51  ^An aggregate SQ
35940 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69  L function requi
35950 72 65 73 20 61 6e 20 69 6d 70 6c 65 6d 65 6e 74  res an implement
35960 61 74 69 6f 6e 20 6f 66 20 78 53 74 65 70 0a 2a  ation of xStep.*
35970 2a 20 61 6e 64 20 78 46 69 6e 61 6c 20 61 6e 64  * and xFinal and
35980 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 6d 75   NULL pointer mu
35990 73 74 20 62 65 20 70 61 73 73 65 64 20 66 6f 72  st be passed for
359a0 20 78 46 75 6e 63 2e 20 5e 54 6f 20 64 65 6c 65   xFunc. ^To dele
359b0 74 65 20 61 6e 20 65 78 69 73 74 69 6e 67 0a 2a  te an existing.*
359c0 2a 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f  * SQL function o
359d0 72 20 61 67 67 72 65 67 61 74 65 2c 20 70 61 73  r aggregate, pas
359e0 73 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73 20  s NULL pointers 
359f0 66 6f 72 20 61 6c 6c 20 74 68 72 65 65 20 66 75  for all three fu
35a00 6e 63 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 61  nction.** callba
35a10 63 6b 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20  cks..**.** ^(If 
35a20 74 68 65 20 6e 69 6e 74 68 20 70 61 72 61 6d 65  the ninth parame
35a30 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  ter to sqlite3_c
35a40 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76  reate_function_v
35a50 32 28 29 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c  2() is not NULL,
35a60 0a 2a 2a 20 74 68 65 6e 20 69 74 20 69 73 20 64  .** then it is d
35a70 65 73 74 72 75 63 74 6f 72 20 66 6f 72 20 74 68  estructor for th
35a80 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61  e application da
35a90 74 61 20 70 6f 69 6e 74 65 72 2e 20 0a 2a 2a 20  ta pointer. .** 
35aa0 54 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 69  The destructor i
35ab0 73 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 74  s invoked when t
35ac0 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 64  he function is d
35ad0 65 6c 65 74 65 64 2c 20 65 69 74 68 65 72 20 62  eleted, either b
35ae0 79 20 62 65 69 6e 67 0a 2a 2a 20 6f 76 65 72 6c  y being.** overl
35af0 6f 61 64 65 64 20 6f 72 20 77 68 65 6e 20 74 68  oaded or when th
35b00 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
35b10 63 74 69 6f 6e 20 63 6c 6f 73 65 73 2e 29 5e 0a  ction closes.)^.
35b20 2a 2a 20 5e 54 68 65 20 64 65 73 74 72 75 63 74  ** ^The destruct
35b30 6f 72 20 69 73 20 61 6c 73 6f 20 69 6e 76 6f 6b  or is also invok
35b40 65 64 20 69 66 20 74 68 65 20 63 61 6c 6c 20 74  ed if the call t
35b50 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 72 65  o.** sqlite3_cre
35b60 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28  ate_function_v2(
35b70 29 20 66 61 69 6c 73 2e 0a 2a 2a 20 5e 57 68 65  ) fails..** ^Whe
35b80 6e 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72  n the destructor
35b90 20 63 61 6c 6c 62 61 63 6b 20 6f 66 20 74 68 65   callback of the
35ba0 20 74 65 6e 74 68 20 70 61 72 61 6d 65 74 65 72   tenth parameter
35bb0 20 69 73 20 69 6e 76 6f 6b 65 64 2c 20 69 74 0a   is invoked, it.
35bc0 2a 2a 20 69 73 20 70 61 73 73 65 64 20 61 20 73  ** is passed a s
35bd0 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77  ingle argument w
35be0 68 69 63 68 20 69 73 20 61 20 63 6f 70 79 20 6f  hich is a copy o
35bf0 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  f the applicatio
35c00 6e 20 64 61 74 61 20 0a 2a 2a 20 70 6f 69 6e 74  n data .** point
35c10 65 72 20 77 68 69 63 68 20 77 61 73 20 74 68 65  er which was the
35c20 20 66 69 66 74 68 20 70 61 72 61 6d 65 74 65 72   fifth parameter
35c30 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 72 65 61   to sqlite3_crea
35c40 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28 29  te_function_v2()
35c50 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74 20 69 73 20 70  ..**.** ^It is p
35c60 65 72 6d 69 74 74 65 64 20 74 6f 20 72 65 67 69  ermitted to regi
35c70 73 74 65 72 20 6d 75 6c 74 69 70 6c 65 20 69 6d  ster multiple im
35c80 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66  plementations of
35c90 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 66 75 6e   the same.** fun
35ca0 63 74 69 6f 6e 73 20 77 69 74 68 20 74 68 65 20  ctions with the 
35cb0 73 61 6d 65 20 6e 61 6d 65 20 62 75 74 20 77 69  same name but wi
35cc0 74 68 20 65 69 74 68 65 72 20 64 69 66 66 65 72  th either differ
35cd0 69 6e 67 20 6e 75 6d 62 65 72 73 20 6f 66 0a 2a  ing numbers of.*
35ce0 2a 20 61 72 67 75 6d 65 6e 74 73 20 6f 72 20 64  * arguments or d
35cf0 69 66 66 65 72 69 6e 67 20 70 72 65 66 65 72 72  iffering preferr
35d00 65 64 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67  ed text encoding
35d10 73 2e 20 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c  s.  ^SQLite will
35d20 20 75 73 65 0a 2a 2a 20 74 68 65 20 69 6d 70 6c   use.** the impl
35d30 65 6d 65 6e 74 61 74 69 6f 6e 20 74 68 61 74 20  ementation that 
35d40 6d 6f 73 74 20 63 6c 6f 73 65 6c 79 20 6d 61 74  most closely mat
35d50 63 68 65 73 20 74 68 65 20 77 61 79 20 69 6e 20  ches the way in 
35d60 77 68 69 63 68 20 74 68 65 0a 2a 2a 20 53 51 4c  which the.** SQL
35d70 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 75 73 65   function is use
35d80 64 2e 20 20 5e 41 20 66 75 6e 63 74 69 6f 6e 20  d.  ^A function 
35d90 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77  implementation w
35da0 69 74 68 20 61 20 6e 6f 6e 2d 6e 65 67 61 74 69  ith a non-negati
35db0 76 65 0a 2a 2a 20 6e 41 72 67 20 70 61 72 61 6d  ve.** nArg param
35dc0 65 74 65 72 20 69 73 20 61 20 62 65 74 74 65 72  eter is a better
35dd0 20 6d 61 74 63 68 20 74 68 61 6e 20 61 20 66 75   match than a fu
35de0 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74  nction implement
35df0 61 74 69 6f 6e 20 77 69 74 68 0a 2a 2a 20 61 20  ation with.** a 
35e00 6e 65 67 61 74 69 76 65 20 6e 41 72 67 2e 20 20  negative nArg.  
35e10 5e 41 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72  ^A function wher
35e20 65 20 74 68 65 20 70 72 65 66 65 72 72 65 64 20  e the preferred 
35e30 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 0a 2a 2a  text encoding.**
35e40 20 6d 61 74 63 68 65 73 20 74 68 65 20 64 61 74   matches the dat
35e50 61 62 61 73 65 20 65 6e 63 6f 64 69 6e 67 20 69  abase encoding i
35e60 73 20 61 20 62 65 74 74 65 72 0a 2a 2a 20 6d 61  s a better.** ma
35e70 74 63 68 20 74 68 61 6e 20 61 20 66 75 6e 63 74  tch than a funct
35e80 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20 65 6e  ion where the en
35e90 63 6f 64 69 6e 67 20 69 73 20 64 69 66 66 65 72  coding is differ
35ea0 65 6e 74 2e 20 20 0a 2a 2a 20 5e 41 20 66 75 6e  ent.  .** ^A fun
35eb0 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20  ction where the 
35ec0 65 6e 63 6f 64 69 6e 67 20 64 69 66 66 65 72 65  encoding differe
35ed0 6e 63 65 20 69 73 20 62 65 74 77 65 65 6e 20 55  nce is between U
35ee0 54 46 31 36 6c 65 20 61 6e 64 20 55 54 46 31 36  TF16le and UTF16
35ef0 62 65 0a 2a 2a 20 69 73 20 61 20 63 6c 6f 73 65  be.** is a close
35f00 72 20 6d 61 74 63 68 20 74 68 61 6e 20 61 20 66  r match than a f
35f10 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68  unction where th
35f20 65 20 65 6e 63 6f 64 69 6e 67 20 64 69 66 66 65  e encoding diffe
35f30 72 65 6e 63 65 20 69 73 0a 2a 2a 20 62 65 74 77  rence is.** betw
35f40 65 65 6e 20 55 54 46 38 20 61 6e 64 20 55 54 46  een UTF8 and UTF
35f50 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e 42 75 69 6c 74  16..**.** ^Built
35f60 2d 69 6e 20 66 75 6e 63 74 69 6f 6e 73 20 6d 61  -in functions ma
35f70 79 20 62 65 20 6f 76 65 72 6c 6f 61 64 65 64 20  y be overloaded 
35f80 62 79 20 6e 65 77 20 61 70 70 6c 69 63 61 74 69  by new applicati
35f90 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
35fa0 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20  ions..**.** ^An 
35fb0 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
35fc0 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  ned function is 
35fd0 70 65 72 6d 69 74 74 65 64 20 74 6f 20 63 61 6c  permitted to cal
35fe0 6c 20 6f 74 68 65 72 0a 2a 2a 20 53 51 4c 69 74  l other.** SQLit
35ff0 65 20 69 6e 74 65 72 66 61 63 65 73 2e 20 20 48  e interfaces.  H
36000 6f 77 65 76 65 72 2c 20 73 75 63 68 20 63 61 6c  owever, such cal
36010 6c 73 20 6d 75 73 74 20 6e 6f 74 0a 2a 2a 20 63  ls must not.** c
36020 6c 6f 73 65 20 74 68 65 20 64 61 74 61 62 61 73  lose the databas
36030 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6e 6f 72  e connection nor
36040 20 66 69 6e 61 6c 69 7a 65 20 6f 72 20 72 65 73   finalize or res
36050 65 74 20 74 68 65 20 70 72 65 70 61 72 65 64 0a  et the prepared.
36060 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20  ** statement in 
36070 77 68 69 63 68 20 74 68 65 20 66 75 6e 63 74 69  which the functi
36080 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a  on is running..*
36090 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72  /.int sqlite3_cr
360a0 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 0a 20  eate_function(. 
360b0 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20   sqlite3 *db,.  
360c0 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 75 6e  const char *zFun
360d0 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74  ctionName,.  int
360e0 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65 54 65   nArg,.  int eTe
360f0 78 74 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70  xtRep,.  void *p
36100 41 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46  App,.  void (*xF
36110 75 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e  unc)(sqlite3_con
36120 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65  text*,int,sqlite
36130 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f  3_value**),.  vo
36140 69 64 20 28 2a 78 53 74 65 70 29 28 73 71 6c 69  id (*xStep)(sqli
36150 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74  te3_context*,int
36160 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a  ,sqlite3_value**
36170 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 69 6e  ),.  void (*xFin
36180 61 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  al)(sqlite3_cont
36190 65 78 74 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c  ext*).);.int sql
361a0 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
361b0 74 69 6f 6e 31 36 28 0a 20 20 73 71 6c 69 74 65  tion16(.  sqlite
361c0 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20 76  3 *db,.  const v
361d0 6f 69 64 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61  oid *zFunctionNa
361e0 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a  me,.  int nArg,.
361f0 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 0a    int eTextRep,.
36200 20 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20    void *pApp,.  
36210 76 6f 69 64 20 28 2a 78 46 75 6e 63 29 28 73 71  void (*xFunc)(sq
36220 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69  lite3_context*,i
36230 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt,sqlite3_value
36240 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53  **),.  void (*xS
36250 74 65 70 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e  tep)(sqlite3_con
36260 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65  text*,int,sqlite
36270 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f  3_value**),.  vo
36280 69 64 20 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c  id (*xFinal)(sql
36290 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 0a 29  ite3_context*).)
362a0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72  ;.int sqlite3_cr
362b0 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32  eate_function_v2
362c0 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
362d0 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
362e0 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20  FunctionName,.  
362f0 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20  int nArg,.  int 
36300 65 54 65 78 74 52 65 70 2c 0a 20 20 76 6f 69 64  eTextRep,.  void
36310 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64 20 28   *pApp,.  void (
36320 2a 78 46 75 6e 63 29 28 73 71 6c 69 74 65 33 5f  *xFunc)(sqlite3_
36330 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c  context*,int,sql
36340 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20  ite3_value**),. 
36350 20 76 6f 69 64 20 28 2a 78 53 74 65 70 29 28 73   void (*xStep)(s
36360 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
36370 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75  int,sqlite3_valu
36380 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78  e**),.  void (*x
36390 46 69 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f 63  Final)(sqlite3_c
363a0 6f 6e 74 65 78 74 2a 29 2c 0a 20 20 76 6f 69 64  ontext*),.  void
363b0 28 2a 78 44 65 73 74 72 6f 79 29 28 76 6f 69 64  (*xDestroy)(void
363c0 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  *).);../*.** CAP
363d0 49 33 52 45 46 3a 20 54 65 78 74 20 45 6e 63 6f  I3REF: Text Enco
363e0 64 69 6e 67 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73  dings.**.** Thes
363f0 65 20 63 6f 6e 73 74 61 6e 74 20 64 65 66 69 6e  e constant defin
36400 65 20 69 6e 74 65 67 65 72 20 63 6f 64 65 73 20  e integer codes 
36410 74 68 61 74 20 72 65 70 72 65 73 65 6e 74 20 74  that represent t
36420 68 65 20 76 61 72 69 6f 75 73 0a 2a 2a 20 74 65  he various.** te
36430 78 74 20 65 6e 63 6f 64 69 6e 67 73 20 73 75 70  xt encodings sup
36440 70 6f 72 74 65 64 20 62 79 20 53 51 4c 69 74 65  ported by SQLite
36450 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
36460 49 54 45 5f 55 54 46 38 20 20 20 20 20 20 20 20  ITE_UTF8        
36470 20 20 20 31 20 20 20 20 2f 2a 20 49 4d 50 3a 20     1    /* IMP: 
36480 52 2d 33 37 35 31 34 2d 33 35 35 36 36 20 2a 2f  R-37514-35566 */
36490 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
364a0 55 54 46 31 36 4c 45 20 20 20 20 20 20 20 20 32  UTF16LE        2
364b0 20 20 20 20 2f 2a 20 49 4d 50 3a 20 52 2d 30 33      /* IMP: R-03
364c0 33 37 31 2d 33 37 36 33 37 20 2a 2f 0a 23 64 65  371-37637 */.#de
364d0 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31  fine SQLITE_UTF1
364e0 36 42 45 20 20 20 20 20 20 20 20 33 20 20 20 20  6BE        3    
364f0 2f 2a 20 49 4d 50 3a 20 52 2d 35 31 39 37 31 2d  /* IMP: R-51971-
36500 33 34 31 35 34 20 2a 2f 0a 23 64 65 66 69 6e 65  34154 */.#define
36510 20 53 51 4c 49 54 45 5f 55 54 46 31 36 20 20 20   SQLITE_UTF16   
36520 20 20 20 20 20 20 20 34 20 20 20 20 2f 2a 20 55         4    /* U
36530 73 65 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f  se native byte o
36540 72 64 65 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20  rder */.#define 
36550 53 51 4c 49 54 45 5f 41 4e 59 20 20 20 20 20 20  SQLITE_ANY      
36560 20 20 20 20 20 20 35 20 20 20 20 2f 2a 20 44 65        5    /* De
36570 70 72 65 63 61 74 65 64 20 2a 2f 0a 23 64 65 66  precated */.#def
36580 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36  ine SQLITE_UTF16
36590 5f 41 4c 49 47 4e 45 44 20 20 38 20 20 20 20 2f  _ALIGNED  8    /
365a0 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  * sqlite3_create
365b0 5f 63 6f 6c 6c 61 74 69 6f 6e 20 6f 6e 6c 79 20  _collation only 
365c0 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  */../*.** CAPI3R
365d0 45 46 3a 20 46 75 6e 63 74 69 6f 6e 20 46 6c 61  EF: Function Fla
365e0 67 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63  gs.**.** These c
365f0 6f 6e 73 74 61 6e 74 73 20 6d 61 79 20 62 65 20  onstants may be 
36600 4f 52 65 64 20 74 6f 67 65 74 68 65 72 20 77 69  ORed together wi
36610 74 68 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c 49  th the .** [SQLI
36620 54 45 5f 55 54 46 38 20 7c 20 70 72 65 66 65 72  TE_UTF8 | prefer
36630 72 65 64 20 74 65 78 74 20 65 6e 63 6f 64 69 6e  red text encodin
36640 67 5d 20 61 73 20 74 68 65 20 66 6f 75 72 74 68  g] as the fourth
36650 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20   argument.** to 
36660 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
36670 66 75 6e 63 74 69 6f 6e 28 29 5d 2c 20 5b 73 71  function()], [sq
36680 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
36690 63 74 69 6f 6e 31 36 28 29 5d 2c 20 6f 72 0a 2a  ction16()], or.*
366a0 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  * [sqlite3_creat
366b0 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28 29 5d  e_function_v2()]
366c0 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
366d0 49 54 45 5f 44 45 54 45 52 4d 49 4e 49 53 54 49  ITE_DETERMINISTI
366e0 43 20 20 20 20 30 78 38 30 30 0a 0a 2f 2a 0a 2a  C    0x800../*.*
366f0 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 70 72  * CAPI3REF: Depr
36700 65 63 61 74 65 64 20 46 75 6e 63 74 69 6f 6e 73  ecated Functions
36710 0a 2a 2a 20 44 45 50 52 45 43 41 54 45 44 0a 2a  .** DEPRECATED.*
36720 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74  *.** These funct
36730 69 6f 6e 73 20 61 72 65 20 5b 64 65 70 72 65 63  ions are [deprec
36740 61 74 65 64 5d 2e 20 20 49 6e 20 6f 72 64 65 72  ated].  In order
36750 20 74 6f 20 6d 61 69 6e 74 61 69 6e 0a 2a 2a 20   to maintain.** 
36760 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74  backwards compat
36770 69 62 69 6c 69 74 79 20 77 69 74 68 20 6f 6c 64  ibility with old
36780 65 72 20 63 6f 64 65 2c 20 74 68 65 73 65 20 66  er code, these f
36790 75 6e 63 74 69 6f 6e 73 20 63 6f 6e 74 69 6e 75  unctions continu
367a0 65 20 0a 2a 2a 20 74 6f 20 62 65 20 73 75 70 70  e .** to be supp
367b0 6f 72 74 65 64 2e 20 20 48 6f 77 65 76 65 72 2c  orted.  However,
367c0 20 6e 65 77 20 61 70 70 6c 69 63 61 74 69 6f 6e   new application
367d0 73 20 73 68 6f 75 6c 64 20 61 76 6f 69 64 0a 2a  s should avoid.*
367e0 2a 20 74 68 65 20 75 73 65 20 6f 66 20 74 68 65  * the use of the
367f0 73 65 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 54  se functions.  T
36800 6f 20 65 6e 63 6f 75 72 61 67 65 20 70 72 6f 67  o encourage prog
36810 72 61 6d 6d 65 72 73 20 74 6f 20 61 76 6f 69 64  rammers to avoid
36820 0a 2a 2a 20 74 68 65 73 65 20 66 75 6e 63 74 69  .** these functi
36830 6f 6e 73 2c 20 77 65 20 77 69 6c 6c 20 6e 6f 74  ons, we will not
36840 20 65 78 70 6c 61 69 6e 20 77 68 61 74 20 74 68   explain what th
36850 65 79 20 64 6f 2e 0a 2a 2f 0a 23 69 66 6e 64 65  ey do..*/.#ifnde
36860 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 44 45  f SQLITE_OMIT_DE
36870 50 52 45 43 41 54 45 44 0a 53 51 4c 49 54 45 5f  PRECATED.SQLITE_
36880 44 45 50 52 45 43 41 54 45 44 20 69 6e 74 20 73  DEPRECATED int s
36890 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65  qlite3_aggregate
368a0 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 63  _count(sqlite3_c
368b0 6f 6e 74 65 78 74 2a 29 3b 0a 53 51 4c 49 54 45  ontext*);.SQLITE
368c0 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e 74 20  _DEPRECATED int 
368d0 73 71 6c 69 74 65 33 5f 65 78 70 69 72 65 64 28  sqlite3_expired(
368e0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a  sqlite3_stmt*);.
368f0 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45  SQLITE_DEPRECATE
36900 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 72  D int sqlite3_tr
36910 61 6e 73 66 65 72 5f 62 69 6e 64 69 6e 67 73 28  ansfer_bindings(
36920 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 73  sqlite3_stmt*, s
36930 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 53  qlite3_stmt*);.S
36940 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44  QLITE_DEPRECATED
36950 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 67 6c 6f   int sqlite3_glo
36960 62 61 6c 5f 72 65 63 6f 76 65 72 28 76 6f 69 64  bal_recover(void
36970 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43  );.SQLITE_DEPREC
36980 41 54 45 44 20 76 6f 69 64 20 73 71 6c 69 74 65  ATED void sqlite
36990 33 5f 74 68 72 65 61 64 5f 63 6c 65 61 6e 75 70  3_thread_cleanup
369a0 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f 44  (void);.SQLITE_D
369b0 45 50 52 45 43 41 54 45 44 20 69 6e 74 20 73 71  EPRECATED int sq
369c0 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 61 6c 61  lite3_memory_ala
369d0 72 6d 28 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a  rm(void(*)(void*
369e0 2c 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 2c 69  ,sqlite3_int64,i
369f0 6e 74 29 2c 0a 20 20 20 20 20 20 20 20 20 20 20  nt),.           
36a00 20 20 20 20 20 20 20 20 20 20 20 76 6f 69 64 2a             void*
36a10 2c 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b  ,sqlite3_int64);
36a20 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43  .#endif../*.** C
36a30 41 50 49 33 52 45 46 3a 20 4f 62 74 61 69 6e 69  API3REF: Obtaini
36a40 6e 67 20 53 51 4c 20 56 61 6c 75 65 73 0a 2a 2a  ng SQL Values.**
36a50 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
36a60 5f 76 61 6c 75 65 0a 2a 2a 0a 2a 2a 20 54 68 65  _value.**.** The
36a70 20 43 2d 6c 61 6e 67 75 61 67 65 20 69 6d 70 6c   C-language impl
36a80 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 53 51  ementation of SQ
36a90 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20  L functions and 
36aa0 61 67 67 72 65 67 61 74 65 73 20 75 73 65 73 0a  aggregates uses.
36ab0 2a 2a 20 74 68 69 73 20 73 65 74 20 6f 66 20 69  ** this set of i
36ac0 6e 74 65 72 66 61 63 65 20 72 6f 75 74 69 6e 65  nterface routine
36ad0 73 20 74 6f 20 61 63 63 65 73 73 20 74 68 65 20  s to access the 
36ae0 70 61 72 61 6d 65 74 65 72 20 76 61 6c 75 65 73  parameter values
36af0 20 6f 6e 0a 2a 2a 20 74 68 65 20 66 75 6e 63 74   on.** the funct
36b00 69 6f 6e 20 6f 72 20 61 67 67 72 65 67 61 74 65  ion or aggregate
36b10 2e 20 20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 46  .  .**.** The xF
36b20 75 6e 63 20 28 66 6f 72 20 73 63 61 6c 61 72 20  unc (for scalar 
36b30 66 75 6e 63 74 69 6f 6e 73 29 20 6f 72 20 78 53  functions) or xS
36b40 74 65 70 20 28 66 6f 72 20 61 67 67 72 65 67 61  tep (for aggrega
36b50 74 65 73 29 20 70 61 72 61 6d 65 74 65 72 73 0a  tes) parameters.
36b60 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  ** to [sqlite3_c
36b70 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29  reate_function()
36b80 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63  ] and [sqlite3_c
36b90 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36  reate_function16
36ba0 28 29 5d 0a 2a 2a 20 64 65 66 69 6e 65 20 63 61  ()].** define ca
36bb0 6c 6c 62 61 63 6b 73 20 74 68 61 74 20 69 6d 70  llbacks that imp
36bc0 6c 65 6d 65 6e 74 20 74 68 65 20 53 51 4c 20 66  lement the SQL f
36bd0 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67  unctions and agg
36be0 72 65 67 61 74 65 73 2e 0a 2a 2a 20 54 68 65 20  regates..** The 
36bf0 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  3rd parameter to
36c00 20 74 68 65 73 65 20 63 61 6c 6c 62 61 63 6b 73   these callbacks
36c10 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20   is an array of 
36c20 70 6f 69 6e 74 65 72 73 20 74 6f 0a 2a 2a 20 5b  pointers to.** [
36c30 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
36c40 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73  3_value] objects
36c50 2e 20 20 54 68 65 72 65 20 69 73 20 6f 6e 65 20  .  There is one 
36c60 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20  [sqlite3_value] 
36c70 6f 62 6a 65 63 74 20 66 6f 72 0a 2a 2a 20 65 61  object for.** ea
36c80 63 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  ch parameter to 
36c90 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  the SQL function
36ca0 2e 20 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  .  These routine
36cb0 73 20 61 72 65 20 75 73 65 64 20 74 6f 0a 2a 2a  s are used to.**
36cc0 20 65 78 74 72 61 63 74 20 76 61 6c 75 65 73 20   extract values 
36cd0 66 72 6f 6d 20 74 68 65 20 5b 73 71 6c 69 74 65  from the [sqlite
36ce0 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73  3_value] objects
36cf0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f  ..**.** These ro
36d00 75 74 69 6e 65 73 20 77 6f 72 6b 20 6f 6e 6c 79  utines work only
36d10 20 77 69 74 68 20 5b 70 72 6f 74 65 63 74 65 64   with [protected
36d20 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20   sqlite3_value] 
36d30 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 41 6e 79 20  objects..** Any 
36d40 61 74 74 65 6d 70 74 20 74 6f 20 75 73 65 20 74  attempt to use t
36d50 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 6e  hese routines on
36d60 20 61 6e 20 5b 75 6e 70 72 6f 74 65 63 74 65 64   an [unprotected
36d70 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 0a   sqlite3_value].
36d80 2a 2a 20 6f 62 6a 65 63 74 20 72 65 73 75 6c 74  ** object result
36d90 73 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 62  s in undefined b
36da0 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 5e  ehavior..**.** ^
36db0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 77  These routines w
36dc0 6f 72 6b 20 6a 75 73 74 20 6c 69 6b 65 20 74 68  ork just like th
36dd0 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20  e corresponding 
36de0 5b 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 66  [column access f
36df0 75 6e 63 74 69 6f 6e 73 5d 0a 2a 2a 20 65 78 63  unctions].** exc
36e00 65 70 74 20 74 68 61 74 20 74 68 65 73 65 20 72  ept that these r
36e10 6f 75 74 69 6e 65 73 20 74 61 6b 65 20 61 20 73  outines take a s
36e20 69 6e 67 6c 65 20 5b 70 72 6f 74 65 63 74 65 64  ingle [protected
36e30 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20   sqlite3_value] 
36e40 6f 62 6a 65 63 74 0a 2a 2a 20 70 6f 69 6e 74 65  object.** pointe
36e50 72 20 69 6e 73 74 65 61 64 20 6f 66 20 61 20 5b  r instead of a [
36e60 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 5d 20 70  sqlite3_stmt*] p
36e70 6f 69 6e 74 65 72 20 61 6e 64 20 61 6e 20 69 6e  ointer and an in
36e80 74 65 67 65 72 20 63 6f 6c 75 6d 6e 20 6e 75 6d  teger column num
36e90 62 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ber..**.** ^The 
36ea0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
36eb0 78 74 31 36 28 29 20 69 6e 74 65 72 66 61 63 65  xt16() interface
36ec0 20 65 78 74 72 61 63 74 73 20 61 20 55 54 46 2d   extracts a UTF-
36ed0 31 36 20 73 74 72 69 6e 67 0a 2a 2a 20 69 6e 20  16 string.** in 
36ee0 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 65 2d  the native byte-
36ef0 6f 72 64 65 72 20 6f 66 20 74 68 65 20 68 6f 73  order of the hos
36f00 74 20 6d 61 63 68 69 6e 65 2e 20 20 5e 54 68 65  t machine.  ^The
36f10 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  .** sqlite3_valu
36f20 65 5f 74 65 78 74 31 36 62 65 28 29 20 61 6e 64  e_text16be() and
36f30 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74   sqlite3_value_t
36f40 65 78 74 31 36 6c 65 28 29 20 69 6e 74 65 72 66  ext16le() interf
36f50 61 63 65 73 0a 2a 2a 20 65 78 74 72 61 63 74 20  aces.** extract 
36f60 55 54 46 2d 31 36 20 73 74 72 69 6e 67 73 20 61  UTF-16 strings a
36f70 73 20 62 69 67 2d 65 6e 64 69 61 6e 20 61 6e 64  s big-endian and
36f80 20 6c 69 74 74 6c 65 2d 65 6e 64 69 61 6e 20 72   little-endian r
36f90 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 0a  espectively..**.
36fa0 2a 2a 20 5e 28 54 68 65 20 73 71 6c 69 74 65 33  ** ^(The sqlite3
36fb0 5f 76 61 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 74  _value_numeric_t
36fc0 79 70 65 28 29 20 69 6e 74 65 72 66 61 63 65 20  ype() interface 
36fd0 61 74 74 65 6d 70 74 73 20 74 6f 20 61 70 70 6c  attempts to appl
36fe0 79 0a 2a 2a 20 6e 75 6d 65 72 69 63 20 61 66 66  y.** numeric aff
36ff0 69 6e 69 74 79 20 74 6f 20 74 68 65 20 76 61 6c  inity to the val
37000 75 65 2e 20 20 54 68 69 73 20 6d 65 61 6e 73 20  ue.  This means 
37010 74 68 61 74 20 61 6e 20 61 74 74 65 6d 70 74 20  that an attempt 
37020 69 73 0a 2a 2a 20 6d 61 64 65 20 74 6f 20 63 6f  is.** made to co
37030 6e 76 65 72 74 20 74 68 65 20 76 61 6c 75 65 20  nvert the value 
37040 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 6f 72  to an integer or
37050 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 2e   floating point.
37060 20 20 49 66 0a 2a 2a 20 73 75 63 68 20 61 20 63    If.** such a c
37070 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 70 6f 73  onversion is pos
37080 73 69 62 6c 65 20 77 69 74 68 6f 75 74 20 6c 6f  sible without lo
37090 73 73 20 6f 66 20 69 6e 66 6f 72 6d 61 74 69 6f  ss of informatio
370a0 6e 20 28 69 6e 20 6f 74 68 65 72 0a 2a 2a 20 77  n (in other.** w
370b0 6f 72 64 73 2c 20 69 66 20 74 68 65 20 76 61 6c  ords, if the val
370c0 75 65 20 69 73 20 61 20 73 74 72 69 6e 67 20 74  ue is a string t
370d0 68 61 74 20 6c 6f 6f 6b 73 20 6c 69 6b 65 20 61  hat looks like a
370e0 20 6e 75 6d 62 65 72 29 0a 2a 2a 20 74 68 65 6e   number).** then
370f0 20 74 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20   the conversion 
37100 69 73 20 70 65 72 66 6f 72 6d 65 64 2e 20 20 4f  is performed.  O
37110 74 68 65 72 77 69 73 65 20 6e 6f 20 63 6f 6e 76  therwise no conv
37120 65 72 73 69 6f 6e 20 6f 63 63 75 72 73 2e 0a 2a  ersion occurs..*
37130 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 49 4e  * The [SQLITE_IN
37140 54 45 47 45 52 20 7c 20 64 61 74 61 74 79 70 65  TEGER | datatype
37150 5d 20 61 66 74 65 72 20 63 6f 6e 76 65 72 73 69  ] after conversi
37160 6f 6e 20 69 73 20 72 65 74 75 72 6e 65 64 2e 29  on is returned.)
37170 5e 0a 2a 2a 0a 2a 2a 20 50 6c 65 61 73 65 20 70  ^.**.** Please p
37180 61 79 20 70 61 72 74 69 63 75 6c 61 72 20 61 74  ay particular at
37190 74 65 6e 74 69 6f 6e 20 74 6f 20 74 68 65 20 66  tention to the f
371a0 61 63 74 20 74 68 61 74 20 74 68 65 20 70 6f 69  act that the poi
371b0 6e 74 65 72 20 72 65 74 75 72 6e 65 64 0a 2a 2a  nter returned.**
371c0 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 76   from [sqlite3_v
371d0 61 6c 75 65 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73  alue_blob()], [s
371e0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
371f0 74 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c  t()], or.** [sql
37200 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31  ite3_value_text1
37210 36 28 29 5d 20 63 61 6e 20 62 65 20 69 6e 76 61  6()] can be inva
37220 6c 69 64 61 74 65 64 20 62 79 20 61 20 73 75 62  lidated by a sub
37230 73 65 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f 0a  sequent call to.
37240 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  ** [sqlite3_valu
37250 65 5f 62 79 74 65 73 28 29 5d 2c 20 5b 73 71 6c  e_bytes()], [sql
37260 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73  ite3_value_bytes
37270 31 36 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  16()], [sqlite3_
37280 76 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 0a 2a  value_text()],.*
37290 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 76 61  * or [sqlite3_va
372a0 6c 75 65 5f 74 65 78 74 31 36 28 29 5d 2e 0a 2a  lue_text16()]..*
372b0 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
372c0 6e 65 73 20 6d 75 73 74 20 62 65 20 63 61 6c 6c  nes must be call
372d0 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65  ed from the same
372e0 20 74 68 72 65 61 64 20 61 73 0a 2a 2a 20 74 68   thread as.** th
372f0 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74  e SQL function t
37300 68 61 74 20 73 75 70 70 6c 69 65 64 20 74 68 65  hat supplied the
37310 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a   [sqlite3_value*
37320 5d 20 70 61 72 61 6d 65 74 65 72 73 2e 0a 2a 2f  ] parameters..*/
37330 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  .const void *sql
37340 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28  ite3_value_blob(
37350 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
37360 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c  .int sqlite3_val
37370 75 65 5f 62 79 74 65 73 28 73 71 6c 69 74 65 33  ue_bytes(sqlite3
37380 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71  _value*);.int sq
37390 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65  lite3_value_byte
373a0 73 31 36 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  s16(sqlite3_valu
373b0 65 2a 29 3b 0a 64 6f 75 62 6c 65 20 73 71 6c 69  e*);.double sqli
373c0 74 65 33 5f 76 61 6c 75 65 5f 64 6f 75 62 6c 65  te3_value_double
373d0 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
373e0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61  ;.int sqlite3_va
373f0 6c 75 65 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f  lue_int(sqlite3_
37400 76 61 6c 75 65 2a 29 3b 0a 73 71 6c 69 74 65 33  value*);.sqlite3
37410 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 76  _int64 sqlite3_v
37420 61 6c 75 65 5f 69 6e 74 36 34 28 73 71 6c 69 74  alue_int64(sqlit
37430 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73  e3_value*);.cons
37440 74 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20  t unsigned char 
37450 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  *sqlite3_value_t
37460 65 78 74 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  ext(sqlite3_valu
37470 65 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20  e*);.const void 
37480 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  *sqlite3_value_t
37490 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f 76 61  ext16(sqlite3_va
374a0 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69  lue*);.const voi
374b0 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  d *sqlite3_value
374c0 5f 74 65 78 74 31 36 6c 65 28 73 71 6c 69 74 65  _text16le(sqlite
374d0 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74  3_value*);.const
374e0 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76   void *sqlite3_v
374f0 61 6c 75 65 5f 74 65 78 74 31 36 62 65 28 73 71  alue_text16be(sq
37500 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69  lite3_value*);.i
37510 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt sqlite3_value
37520 5f 74 79 70 65 28 73 71 6c 69 74 65 33 5f 76 61  _type(sqlite3_va
37530 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74  lue*);.int sqlit
37540 65 33 5f 76 61 6c 75 65 5f 6e 75 6d 65 72 69 63  e3_value_numeric
37550 5f 74 79 70 65 28 73 71 6c 69 74 65 33 5f 76 61  _type(sqlite3_va
37560 6c 75 65 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  lue*);../*.** CA
37570 50 49 33 52 45 46 3a 20 46 69 6e 64 69 6e 67 20  PI3REF: Finding 
37580 54 68 65 20 53 75 62 74 79 70 65 20 4f 66 20 53  The Subtype Of S
37590 51 4c 20 56 61 6c 75 65 73 0a 2a 2a 20 4d 45 54  QL Values.** MET
375a0 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 76 61 6c  HOD: sqlite3_val
375b0 75 65 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  ue.**.** The sql
375c0 69 74 65 33 5f 76 61 6c 75 65 5f 73 75 62 74 79  ite3_value_subty
375d0 70 65 28 56 29 20 66 75 6e 63 74 69 6f 6e 20 72  pe(V) function r
375e0 65 74 75 72 6e 73 20 74 68 65 20 73 75 62 74 79  eturns the subty
375f0 70 65 20 66 6f 72 0a 2a 2a 20 61 6e 20 5b 61 70  pe for.** an [ap
37600 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
37610 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 20  d SQL function] 
37620 61 72 67 75 6d 65 6e 74 20 56 2e 20 20 54 68 65  argument V.  The
37630 20 73 75 62 74 79 70 65 0a 2a 2a 20 69 6e 66 6f   subtype.** info
37640 72 6d 61 74 69 6f 6e 20 63 61 6e 20 62 65 20 75  rmation can be u
37650 73 65 64 20 74 6f 20 70 61 73 73 20 61 20 6c 69  sed to pass a li
37660 6d 69 74 65 64 20 61 6d 6f 75 6e 74 20 6f 66 20  mited amount of 
37670 63 6f 6e 74 65 78 74 20 66 72 6f 6d 0a 2a 2a 20  context from.** 
37680 6f 6e 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  one SQL function
37690 20 74 6f 20 61 6e 6f 74 68 65 72 2e 20 20 55 73   to another.  Us
376a0 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 72  e the [sqlite3_r
376b0 65 73 75 6c 74 5f 73 75 62 74 79 70 65 28 29 5d  esult_subtype()]
376c0 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 74 6f 20 73  .** routine to s
376d0 65 74 20 74 68 65 20 73 75 62 74 79 70 65 20 66  et the subtype f
376e0 6f 72 20 74 68 65 20 72 65 74 75 72 6e 20 76 61  or the return va
376f0 6c 75 65 20 6f 66 20 61 6e 20 53 51 4c 20 66 75  lue of an SQL fu
37700 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51  nction..**.** SQ
37710 4c 69 74 65 20 6d 61 6b 65 73 20 6e 6f 20 75 73  Lite makes no us
37720 65 20 6f 66 20 73 75 62 74 79 70 65 20 69 74 73  e of subtype its
37730 65 6c 66 2e 20 20 49 74 20 6d 65 72 65 6c 79 20  elf.  It merely 
37740 70 61 73 73 65 73 20 74 68 65 20 73 75 62 74 79  passes the subty
37750 70 65 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20 72  pe.** from the r
37760 65 73 75 6c 74 20 6f 66 20 6f 6e 65 20 5b 61 70  esult of one [ap
37770 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
37780 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 20  d SQL function] 
37790 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 69 6e 70 75  into the.** inpu
377a0 74 20 6f 66 20 61 6e 6f 74 68 65 72 2e 0a 2a 2f  t of another..*/
377b0 0a 75 6e 73 69 67 6e 65 64 20 69 6e 74 20 73 71  .unsigned int sq
377c0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 73 75 62 74  lite3_value_subt
377d0 79 70 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  ype(sqlite3_valu
377e0 65 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  e*);../*.** CAPI
377f0 33 52 45 46 3a 20 43 6f 70 79 20 41 6e 64 20 46  3REF: Copy And F
37800 72 65 65 20 53 51 4c 20 56 61 6c 75 65 73 0a 2a  ree SQL Values.*
37810 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65  * METHOD: sqlite
37820 33 5f 76 61 6c 75 65 0a 2a 2a 0a 2a 2a 20 5e 54  3_value.**.** ^T
37830 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  he sqlite3_value
37840 5f 64 75 70 28 56 29 20 69 6e 74 65 72 66 61 63  _dup(V) interfac
37850 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f  e makes a copy o
37860 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  f the [sqlite3_v
37870 61 6c 75 65 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20  alue].** object 
37880 44 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20  D and returns a 
37890 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 61 74 20  pointer to that 
378a0 63 6f 70 79 2e 20 20 5e 54 68 65 20 5b 73 71 6c  copy.  ^The [sql
378b0 69 74 65 33 5f 76 61 6c 75 65 5d 20 72 65 74 75  ite3_value] retu
378c0 72 6e 65 64 0a 2a 2a 20 69 73 20 61 20 5b 70 72  rned.** is a [pr
378d0 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
378e0 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 65 76  value] object ev
378f0 65 6e 20 69 66 20 74 68 65 20 69 6e 70 75 74 20  en if the input 
37900 69 73 20 6e 6f 74 2e 0a 2a 2a 20 5e 54 68 65 20  is not..** ^The 
37910 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 64 75  sqlite3_value_du
37920 70 28 56 29 20 69 6e 74 65 72 66 61 63 65 20 72  p(V) interface r
37930 65 74 75 72 6e 73 20 4e 55 4c 4c 20 69 66 20 56  eturns NULL if V
37940 20 69 73 20 4e 55 4c 4c 20 6f 72 20 69 66 20 61   is NULL or if a
37950 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  .** memory alloc
37960 61 74 69 6f 6e 20 66 61 69 6c 73 2e 0a 2a 2a 0a  ation fails..**.
37970 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
37980 76 61 6c 75 65 5f 66 72 65 65 28 56 29 20 69 6e  value_free(V) in
37990 74 65 72 66 61 63 65 20 66 72 65 65 73 20 61 6e  terface frees an
379a0 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d   [sqlite3_value]
379b0 20 6f 62 6a 65 63 74 0a 2a 2a 20 70 72 65 76 69   object.** previ
379c0 6f 75 73 6c 79 20 6f 62 74 61 69 6e 65 64 20 66  ously obtained f
379d0 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  rom [sqlite3_val
379e0 75 65 5f 64 75 70 28 29 5d 2e 20 20 5e 49 66 20  ue_dup()].  ^If 
379f0 56 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  V is a NULL poin
37a00 74 65 72 0a 2a 2a 20 74 68 65 6e 20 73 71 6c 69  ter.** then sqli
37a10 74 65 33 5f 76 61 6c 75 65 5f 66 72 65 65 28 56  te3_value_free(V
37a20 29 20 69 73 20 61 20 68 61 72 6d 6c 65 73 73 20  ) is a harmless 
37a30 6e 6f 2d 6f 70 2e 0a 2a 2f 0a 73 71 6c 69 74 65  no-op..*/.sqlite
37a40 33 5f 76 61 6c 75 65 20 2a 73 71 6c 69 74 65 33  3_value *sqlite3
37a50 5f 76 61 6c 75 65 5f 64 75 70 28 63 6f 6e 73 74  _value_dup(const
37a60 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29   sqlite3_value*)
37a70 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 76  ;.void sqlite3_v
37a80 61 6c 75 65 5f 66 72 65 65 28 73 71 6c 69 74 65  alue_free(sqlite
37a90 33 5f 76 61 6c 75 65 2a 29 3b 0a 0a 2f 2a 0a 2a  3_value*);../*.*
37aa0 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 62 74 61  * CAPI3REF: Obta
37ab0 69 6e 20 41 67 67 72 65 67 61 74 65 20 46 75 6e  in Aggregate Fun
37ac0 63 74 69 6f 6e 20 43 6f 6e 74 65 78 74 0a 2a 2a  ction Context.**
37ad0 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
37ae0 5f 63 6f 6e 74 65 78 74 0a 2a 2a 0a 2a 2a 20 49  _context.**.** I
37af0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f  mplementations o
37b00 66 20 61 67 67 72 65 67 61 74 65 20 53 51 4c 20  f aggregate SQL 
37b10 66 75 6e 63 74 69 6f 6e 73 20 75 73 65 20 74 68  functions use th
37b20 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 74 6f  is.** routine to
37b30 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79   allocate memory
37b40 20 66 6f 72 20 73 74 6f 72 69 6e 67 20 74 68 65   for storing the
37b50 69 72 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20  ir state..**.** 
37b60 5e 54 68 65 20 66 69 72 73 74 20 74 69 6d 65 20  ^The first time 
37b70 74 68 65 20 73 71 6c 69 74 65 33 5f 61 67 67 72  the sqlite3_aggr
37b80 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c  egate_context(C,
37b90 4e 29 20 72 6f 75 74 69 6e 65 20 69 73 20 63 61  N) routine is ca
37ba0 6c 6c 65 64 20 0a 2a 2a 20 66 6f 72 20 61 20 70  lled .** for a p
37bb0 61 72 74 69 63 75 6c 61 72 20 61 67 67 72 65 67  articular aggreg
37bc0 61 74 65 20 66 75 6e 63 74 69 6f 6e 2c 20 53 51  ate function, SQ
37bd0 4c 69 74 65 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65  Lite.** allocate
37be0 73 20 4e 20 6f 66 20 6d 65 6d 6f 72 79 2c 20 7a  s N of memory, z
37bf0 65 72 6f 65 73 20 6f 75 74 20 74 68 61 74 20 6d  eroes out that m
37c00 65 6d 6f 72 79 2c 20 61 6e 64 20 72 65 74 75 72  emory, and retur
37c10 6e 73 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20  ns a pointer.** 
37c20 74 6f 20 74 68 65 20 6e 65 77 20 6d 65 6d 6f 72  to the new memor
37c30 79 2e 20 5e 4f 6e 20 73 65 63 6f 6e 64 20 61 6e  y. ^On second an
37c40 64 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c  d subsequent cal
37c50 6c 73 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33  ls to.** sqlite3
37c60 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65  _aggregate_conte
37c70 78 74 28 29 20 66 6f 72 20 74 68 65 20 73 61 6d  xt() for the sam
37c80 65 20 61 67 67 72 65 67 61 74 65 20 66 75 6e 63  e aggregate func
37c90 74 69 6f 6e 20 69 6e 73 74 61 6e 63 65 2c 0a 2a  tion instance,.*
37ca0 2a 20 74 68 65 20 73 61 6d 65 20 62 75 66 66 65  * the same buffe
37cb0 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20  r is returned.  
37cc0 53 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74  Sqlite3_aggregat
37cd0 65 5f 63 6f 6e 74 65 78 74 28 29 20 69 73 20 6e  e_context() is n
37ce0 6f 72 6d 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65  ormally.** calle
37cf0 64 20 6f 6e 63 65 20 66 6f 72 20 65 61 63 68 20  d once for each 
37d00 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 74 68  invocation of th
37d10 65 20 78 53 74 65 70 20 63 61 6c 6c 62 61 63 6b  e xStep callback
37d20 20 61 6e 64 20 74 68 65 6e 20 6f 6e 65 0a 2a 2a   and then one.**
37d30 20 6c 61 73 74 20 74 69 6d 65 20 77 68 65 6e 20   last time when 
37d40 74 68 65 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62  the xFinal callb
37d50 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 2e 20  ack is invoked. 
37d60 20 5e 28 57 68 65 6e 20 6e 6f 20 72 6f 77 73 20   ^(When no rows 
37d70 6d 61 74 63 68 0a 2a 2a 20 61 6e 20 61 67 67 72  match.** an aggr
37d80 65 67 61 74 65 20 71 75 65 72 79 2c 20 74 68 65  egate query, the
37d90 20 78 53 74 65 70 28 29 20 63 61 6c 6c 62 61 63   xStep() callbac
37da0 6b 20 6f 66 20 74 68 65 20 61 67 67 72 65 67 61  k of the aggrega
37db0 74 65 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 69  te function.** i
37dc0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73  mplementation is
37dd0 20 6e 65 76 65 72 20 63 61 6c 6c 65 64 20 61 6e   never called an
37de0 64 20 78 46 69 6e 61 6c 28 29 20 69 73 20 63 61  d xFinal() is ca
37df0 6c 6c 65 64 20 65 78 61 63 74 6c 79 20 6f 6e 63  lled exactly onc
37e00 65 2e 0a 2a 2a 20 49 6e 20 74 68 6f 73 65 20 63  e..** In those c
37e10 61 73 65 73 2c 20 73 71 6c 69 74 65 33 5f 61 67  ases, sqlite3_ag
37e20 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28  gregate_context(
37e30 29 20 6d 69 67 68 74 20 62 65 20 63 61 6c 6c 65  ) might be calle
37e40 64 20 66 6f 72 20 74 68 65 0a 2a 2a 20 66 69 72  d for the.** fir
37e50 73 74 20 74 69 6d 65 20 66 72 6f 6d 20 77 69 74  st time from wit
37e60 68 69 6e 20 78 46 69 6e 61 6c 28 29 2e 29 5e 0a  hin xFinal().)^.
37e70 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
37e80 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e  e3_aggregate_con
37e90 74 65 78 74 28 43 2c 4e 29 20 72 6f 75 74 69 6e  text(C,N) routin
37ea0 65 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c  e returns a NULL
37eb0 20 70 6f 69 6e 74 65 72 20 0a 2a 2a 20 77 68 65   pointer .** whe
37ec0 6e 20 66 69 72 73 74 20 63 61 6c 6c 65 64 20 69  n first called i
37ed0 66 20 4e 20 69 73 20 6c 65 73 73 20 74 68 61 6e  f N is less than
37ee0 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 7a 65 72   or equal to zer
37ef0 6f 20 6f 72 20 69 66 20 61 20 6d 65 6d 6f 72 79  o or if a memory
37f00 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 20 65 72 72  .** allocate err
37f10 6f 72 20 6f 63 63 75 72 73 2e 0a 2a 2a 0a 2a 2a  or occurs..**.**
37f20 20 5e 28 54 68 65 20 61 6d 6f 75 6e 74 20 6f 66   ^(The amount of
37f30 20 73 70 61 63 65 20 61 6c 6c 6f 63 61 74 65 64   space allocated
37f40 20 62 79 20 73 71 6c 69 74 65 33 5f 61 67 67 72   by sqlite3_aggr
37f50 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c  egate_context(C,
37f60 4e 29 20 69 73 0a 2a 2a 20 64 65 74 65 72 6d 69  N) is.** determi
37f70 6e 65 64 20 62 79 20 74 68 65 20 4e 20 70 61 72  ned by the N par
37f80 61 6d 65 74 65 72 20 6f 6e 20 66 69 72 73 74 20  ameter on first 
37f90 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 2e  successful call.
37fa0 20 20 43 68 61 6e 67 69 6e 67 20 74 68 65 0a 2a    Changing the.*
37fb0 2a 20 76 61 6c 75 65 20 6f 66 20 4e 20 69 6e 20  * value of N in 
37fc0 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 20  subsequent call 
37fd0 74 6f 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65  to sqlite3_aggre
37fe0 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 77  gate_context() w
37ff0 69 74 68 69 6e 0a 2a 2a 20 74 68 65 20 73 61 6d  ithin.** the sam
38000 65 20 61 67 67 72 65 67 61 74 65 20 66 75 6e 63  e aggregate func
38010 74 69 6f 6e 20 69 6e 73 74 61 6e 63 65 20 77 69  tion instance wi
38020 6c 6c 20 6e 6f 74 20 72 65 73 69 7a 65 20 74 68  ll not resize th
38030 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f  e memory.** allo
38040 63 61 74 69 6f 6e 2e 29 5e 20 20 57 69 74 68 69  cation.)^  Withi
38050 6e 20 74 68 65 20 78 46 69 6e 61 6c 20 63 61 6c  n the xFinal cal
38060 6c 62 61 63 6b 2c 20 69 74 20 69 73 20 63 75 73  lback, it is cus
38070 74 6f 6d 61 72 79 20 74 6f 20 73 65 74 0a 2a 2a  tomary to set.**
38080 20 4e 3d 30 20 69 6e 20 63 61 6c 6c 73 20 74 6f   N=0 in calls to
38090 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61   sqlite3_aggrega
380a0 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20  te_context(C,N) 
380b0 73 6f 20 74 68 61 74 20 6e 6f 20 0a 2a 2a 20 70  so that no .** p
380c0 6f 69 6e 74 6c 65 73 73 20 6d 65 6d 6f 72 79 20  ointless memory 
380d0 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 6f 63 63 75  allocations occu
380e0 72 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65  r..**.** ^SQLite
380f0 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 66   automatically f
38100 72 65 65 73 20 74 68 65 20 6d 65 6d 6f 72 79 20  rees the memory 
38110 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 0a 2a 2a  allocated by .**
38120 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61   sqlite3_aggrega
38130 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 77 68 65  te_context() whe
38140 6e 20 74 68 65 20 61 67 67 72 65 67 61 74 65 20  n the aggregate 
38150 71 75 65 72 79 20 63 6f 6e 63 6c 75 64 65 73 2e  query concludes.
38160 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74  .**.** The first
38170 20 70 61 72 61 6d 65 74 65 72 20 6d 75 73 74 20   parameter must 
38180 62 65 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  be a copy of the
38190 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  .** [sqlite3_con
381a0 74 65 78 74 20 7c 20 53 51 4c 20 66 75 6e 63 74  text | SQL funct
381b0 69 6f 6e 20 63 6f 6e 74 65 78 74 5d 20 74 68 61  ion context] tha
381c0 74 20 69 73 20 74 68 65 20 66 69 72 73 74 20 70  t is the first p
381d0 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74 6f 20 74  arameter.** to t
381e0 68 65 20 78 53 74 65 70 20 6f 72 20 78 46 69 6e  he xStep or xFin
381f0 61 6c 20 63 61 6c 6c 62 61 63 6b 20 72 6f 75 74  al callback rout
38200 69 6e 65 20 74 68 61 74 20 69 6d 70 6c 65 6d 65  ine that impleme
38210 6e 74 73 20 74 68 65 20 61 67 67 72 65 67 61 74  nts the aggregat
38220 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a  e.** function..*
38230 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e  *.** This routin
38240 65 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64  e must be called
38250 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74   from the same t
38260 68 72 65 61 64 20 69 6e 20 77 68 69 63 68 0a 2a  hread in which.*
38270 2a 20 74 68 65 20 61 67 67 72 65 67 61 74 65 20  * the aggregate 
38280 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  SQL function is 
38290 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76 6f 69 64  running..*/.void
382a0 20 2a 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67   *sqlite3_aggreg
382b0 61 74 65 5f 63 6f 6e 74 65 78 74 28 73 71 6c 69  ate_context(sqli
382c0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e  te3_context*, in
382d0 74 20 6e 42 79 74 65 73 29 3b 0a 0a 2f 2a 0a 2a  t nBytes);../*.*
382e0 2a 20 43 41 50 49 33 52 45 46 3a 20 55 73 65 72  * CAPI3REF: User
382f0 20 44 61 74 61 20 46 6f 72 20 46 75 6e 63 74 69   Data For Functi
38300 6f 6e 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  ons.** METHOD: s
38310 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 0a 2a  qlite3_context.*
38320 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
38330 33 5f 75 73 65 72 5f 64 61 74 61 28 29 20 69 6e  3_user_data() in
38340 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
38350 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65  a copy of.** the
38360 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20 77 61   pointer that wa
38370 73 20 74 68 65 20 70 55 73 65 72 44 61 74 61 20  s the pUserData 
38380 70 61 72 61 6d 65 74 65 72 20 28 74 68 65 20 35  parameter (the 5
38390 74 68 20 70 61 72 61 6d 65 74 65 72 29 0a 2a 2a  th parameter).**
383a0 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
383b0 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
383c0 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69  ()].** and [sqli
383d0 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
383e0 69 6f 6e 31 36 28 29 5d 20 72 6f 75 74 69 6e 65  ion16()] routine
383f0 73 20 74 68 61 74 20 6f 72 69 67 69 6e 61 6c 6c  s that originall
38400 79 0a 2a 2a 20 72 65 67 69 73 74 65 72 65 64 20  y.** registered 
38410 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
38420 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
38430 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75  ..**.** This rou
38440 74 69 6e 65 20 6d 75 73 74 20 62 65 20 63 61 6c  tine must be cal
38450 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d  led from the sam
38460 65 20 74 68 72 65 61 64 20 69 6e 20 77 68 69 63  e thread in whic
38470 68 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61  h.** the applica
38480 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
38490 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67  ction is running
384a0 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74  ..*/.void *sqlit
384b0 65 33 5f 75 73 65 72 5f 64 61 74 61 28 73 71 6c  e3_user_data(sql
384c0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a  ite3_context*);.
384d0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
384e0 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63   Database Connec
384f0 74 69 6f 6e 20 46 6f 72 20 46 75 6e 63 74 69 6f  tion For Functio
38500 6e 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  ns.** METHOD: sq
38510 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 0a 2a 2a  lite3_context.**
38520 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
38530 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64  _context_db_hand
38540 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 72  le() interface r
38550 65 74 75 72 6e 73 20 61 20 63 6f 70 79 20 6f 66  eturns a copy of
38560 0a 2a 2a 20 74 68 65 20 70 6f 69 6e 74 65 72 20  .** the pointer 
38570 74 6f 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  to the [database
38580 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 74 68   connection] (th
38590 65 20 31 73 74 20 70 61 72 61 6d 65 74 65 72 29  e 1st parameter)
385a0 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  .** of the [sqli
385b0 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
385c0 69 6f 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73  ion()].** and [s
385d0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
385e0 6e 63 74 69 6f 6e 31 36 28 29 5d 20 72 6f 75 74  nction16()] rout
385f0 69 6e 65 73 20 74 68 61 74 20 6f 72 69 67 69 6e  ines that origin
38600 61 6c 6c 79 0a 2a 2a 20 72 65 67 69 73 74 65 72  ally.** register
38610 65 64 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  ed the applicati
38620 6f 6e 20 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on defined funct
38630 69 6f 6e 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 20  ion..*/.sqlite3 
38640 2a 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  *sqlite3_context
38650 5f 64 62 5f 68 61 6e 64 6c 65 28 73 71 6c 69 74  _db_handle(sqlit
38660 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 0a 2f  e3_context*);../
38670 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46  *.** CAPI3REF: F
38680 75 6e 63 74 69 6f 6e 20 41 75 78 69 6c 69 61 72  unction Auxiliar
38690 79 20 44 61 74 61 0a 2a 2a 20 4d 45 54 48 4f 44  y Data.** METHOD
386a0 3a 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  : sqlite3_contex
386b0 74 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75  t.**.** These fu
386c0 6e 63 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 75  nctions may be u
386d0 73 65 64 20 62 79 20 28 6e 6f 6e 2d 61 67 67 72  sed by (non-aggr
386e0 65 67 61 74 65 29 20 53 51 4c 20 66 75 6e 63 74  egate) SQL funct
386f0 69 6f 6e 73 20 74 6f 0a 2a 2a 20 61 73 73 6f 63  ions to.** assoc
38700 69 61 74 65 20 6d 65 74 61 64 61 74 61 20 77 69  iate metadata wi
38710 74 68 20 61 72 67 75 6d 65 6e 74 20 76 61 6c 75  th argument valu
38720 65 73 2e 20 49 66 20 74 68 65 20 73 61 6d 65 20  es. If the same 
38730 76 61 6c 75 65 20 69 73 20 70 61 73 73 65 64 20  value is passed 
38740 74 6f 0a 2a 2a 20 6d 75 6c 74 69 70 6c 65 20 69  to.** multiple i
38750 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 68  nvocations of th
38760 65 20 73 61 6d 65 20 53 51 4c 20 66 75 6e 63 74  e same SQL funct
38770 69 6f 6e 20 64 75 72 69 6e 67 20 71 75 65 72 79  ion during query
38780 20 65 78 65 63 75 74 69 6f 6e 2c 20 75 6e 64 65   execution, unde
38790 72 0a 2a 2a 20 73 6f 6d 65 20 63 69 72 63 75 6d  r.** some circum
387a0 73 74 61 6e 63 65 73 20 74 68 65 20 61 73 73 6f  stances the asso
387b0 63 69 61 74 65 64 20 6d 65 74 61 64 61 74 61 20  ciated metadata 
387c0 6d 61 79 20 62 65 20 70 72 65 73 65 72 76 65 64  may be preserved
387d0 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65 0a 2a 2a  .  An example.**
387e0 20 6f 66 20 77 68 65 72 65 20 74 68 69 73 20 6d   of where this m
387f0 69 67 68 74 20 62 65 20 75 73 65 66 75 6c 20 69  ight be useful i
38800 73 20 69 6e 20 61 20 72 65 67 75 6c 61 72 2d 65  s in a regular-e
38810