/ Hex Artifact Content
Login

Artifact 5f72af637ba0f35c2b25f8f97ea63bac6f4ea133eb904ee0b6d61450401507d3:


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 0a 2f 2a 20 52 65 73 65 72 76 65 64 3a 20  /../* Reserved: 
64f0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
6500: 20 20 20 20 20 20 20 20 30 78 30 30 46 30 30 30          0x00F000
6510: 30 30 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  00 */../*.** CAP
6520: 49 33 52 45 46 3a 20 44 65 76 69 63 65 20 43 68  I3REF: Device Ch
6530: 61 72 61 63 74 65 72 69 73 74 69 63 73 0a 2a 2a  aracteristics.**
6540: 0a 2a 2a 20 54 68 65 20 78 44 65 76 69 63 65 43  .** The xDeviceC
6550: 68 61 72 61 63 74 65 72 69 73 74 69 63 73 20 6d  haracteristics m
6560: 65 74 68 6f 64 20 6f 66 20 74 68 65 20 5b 73 71  ethod of the [sq
6570: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
6580: 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 72 65 74 75  ].** object retu
6590: 72 6e 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77  rns an integer w
65a0: 68 69 63 68 20 69 73 20 61 20 76 65 63 74 6f 72  hich is a vector
65b0: 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 62 69 74   of these.** bit
65c0: 20 76 61 6c 75 65 73 20 65 78 70 72 65 73 73 69   values expressi
65d0: 6e 67 20 49 2f 4f 20 63 68 61 72 61 63 74 65 72  ng I/O character
65e0: 69 73 74 69 63 73 20 6f 66 20 74 68 65 20 6d 61  istics of the ma
65f0: 73 73 20 73 74 6f 72 61 67 65 0a 2a 2a 20 64 65  ss storage.** de
6600: 76 69 63 65 20 74 68 61 74 20 68 6f 6c 64 73 20  vice that holds 
6610: 74 68 65 20 66 69 6c 65 20 74 68 61 74 20 74 68  the file that th
6620: 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  e [sqlite3_io_me
6630: 74 68 6f 64 73 5d 0a 2a 2a 20 72 65 66 65 72 73  thods].** refers
6640: 20 74 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53   to..**.** The S
6650: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
6660: 49 43 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e  IC property mean
6670: 73 20 74 68 61 74 20 61 6c 6c 20 77 72 69 74 65  s that all write
6680: 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69 7a 65  s of.** any size
6690: 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68   are atomic.  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 6e 6e 6e 20 76 61 6c 75 65 73 0a  TOMICnnn values.
66c0: 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20 77 72 69  ** mean that wri
66d0: 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20 74 68  tes of blocks th
66e0: 61 74 20 61 72 65 20 6e 6e 6e 20 62 79 74 65 73  at are nnn bytes
66f0: 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a 2a 20   in size and.** 
6700: 61 72 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61  are aligned to a
6710: 6e 20 61 64 64 72 65 73 73 20 77 68 69 63 68 20  n address which 
6720: 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6d 75  is an integer mu
6730: 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e  ltiple of.** nnn
6740: 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68   are atomic.  Th
6750: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53  e SQLITE_IOCAP_S
6760: 41 46 45 5f 41 50 50 45 4e 44 20 76 61 6c 75 65  AFE_APPEND value
6770: 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20 77   means.** that w
6780: 68 65 6e 20 64 61 74 61 20 69 73 20 61 70 70 65  hen data is appe
6790: 6e 64 65 64 20 74 6f 20 61 20 66 69 6c 65 2c 20  nded to a file, 
67a0: 74 68 65 20 64 61 74 61 20 69 73 20 61 70 70 65  the data is appe
67b0: 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74 20 74 68  nded.** first th
67c0: 65 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74  en the size of t
67d0: 68 65 20 66 69 6c 65 20 69 73 20 65 78 74 65 6e  he file is exten
67e0: 64 65 64 2c 20 6e 65 76 65 72 20 74 68 65 20 6f  ded, never the o
67f0: 74 68 65 72 0a 2a 2a 20 77 61 79 20 61 72 6f 75  ther.** way arou
6800: 6e 64 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f  nd.  The SQLITE_
6810: 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c  IOCAP_SEQUENTIAL
6820: 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20   property means 
6830: 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74  that.** informat
6840: 69 6f 6e 20 69 73 20 77 72 69 74 74 65 6e 20 74  ion is written t
6850: 6f 20 64 69 73 6b 20 69 6e 20 74 68 65 20 73 61  o disk in the sa
6860: 6d 65 20 6f 72 64 65 72 20 61 73 20 63 61 6c 6c  me order as call
6870: 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65 28 29  s.** to xWrite()
6880: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f  .  The SQLITE_IO
6890: 43 41 50 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56  CAP_POWERSAFE_OV
68a0: 45 52 57 52 49 54 45 20 70 72 6f 70 65 72 74 79  ERWRITE property
68b0: 20 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20 61   means that.** a
68c0: 66 74 65 72 20 72 65 62 6f 6f 74 20 66 6f 6c 6c  fter reboot foll
68d0: 6f 77 69 6e 67 20 61 20 63 72 61 73 68 20 6f 72  owing a crash or
68e0: 20 70 6f 77 65 72 20 6c 6f 73 73 2c 20 74 68 65   power loss, the
68f0: 20 6f 6e 6c 79 20 62 79 74 65 73 20 69 6e 20 61   only bytes in a
6900: 0a 2a 2a 20 66 69 6c 65 20 74 68 61 74 20 77 65  .** file that we
6910: 72 65 20 77 72 69 74 74 65 6e 20 61 74 20 74 68  re written at th
6920: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6c 65  e application le
6930: 76 65 6c 20 6d 69 67 68 74 20 68 61 76 65 20 63  vel might have c
6940: 68 61 6e 67 65 64 0a 2a 2a 20 61 6e 64 20 74 68  hanged.** and th
6950: 61 74 20 61 64 6a 61 63 65 6e 74 20 62 79 74 65  at adjacent byte
6960: 73 2c 20 65 76 65 6e 20 62 79 74 65 73 20 77 69  s, even bytes wi
6970: 74 68 69 6e 20 74 68 65 20 73 61 6d 65 20 73 65  thin the same se
6980: 63 74 6f 72 20 61 72 65 0a 2a 2a 20 67 75 61 72  ctor are.** guar
6990: 61 6e 74 65 65 64 20 74 6f 20 62 65 20 75 6e 63  anteed to be unc
69a0: 68 61 6e 67 65 64 2e 20 20 54 68 65 20 53 51 4c  hanged.  The SQL
69b0: 49 54 45 5f 49 4f 43 41 50 5f 55 4e 44 45 4c 45  ITE_IOCAP_UNDELE
69c0: 54 41 42 4c 45 5f 57 48 45 4e 5f 4f 50 45 4e 0a  TABLE_WHEN_OPEN.
69d0: 2a 2a 20 66 6c 61 67 20 69 6e 64 69 63 61 74 65  ** flag indicate
69e0: 73 20 74 68 61 74 20 61 20 66 69 6c 65 20 63 61  s that a file ca
69f0: 6e 6e 6f 74 20 62 65 20 64 65 6c 65 74 65 64 20  nnot be deleted 
6a00: 77 68 65 6e 20 6f 70 65 6e 2e 20 20 54 68 65 0a  when open.  The.
6a10: 2a 2a 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ** SQLITE_IOCAP_
6a20: 49 4d 4d 55 54 41 42 4c 45 20 66 6c 61 67 20 69  IMMUTABLE flag i
6a30: 6e 64 69 63 61 74 65 73 20 74 68 61 74 20 74 68  ndicates that th
6a40: 65 20 66 69 6c 65 20 69 73 20 6f 6e 0a 2a 2a 20  e file is on.** 
6a50: 72 65 61 64 2d 6f 6e 6c 79 20 6d 65 64 69 61 20  read-only media 
6a60: 61 6e 64 20 63 61 6e 6e 6f 74 20 62 65 20 63 68  and cannot be ch
6a70: 61 6e 67 65 64 20 65 76 65 6e 20 62 79 20 70 72  anged even by pr
6a80: 6f 63 65 73 73 65 73 20 77 69 74 68 0a 2a 2a 20  ocesses with.** 
6a90: 65 6c 65 76 61 74 65 64 20 70 72 69 76 69 6c 65  elevated privile
6aa0: 67 65 73 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  ges..*/.#define 
6ab0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
6ac0: 4d 49 43 20 20 20 20 20 20 20 20 20 20 20 20 20  MIC             
6ad0: 20 20 20 20 30 78 30 30 30 30 30 30 30 31 0a 23      0x00000001.#
6ae0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
6af0: 43 41 50 5f 41 54 4f 4d 49 43 35 31 32 20 20 20  CAP_ATOMIC512   
6b00: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
6b10: 30 30 30 30 32 0a 23 64 65 66 69 6e 65 20 53 51  00002.#define SQ
6b20: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
6b30: 43 31 4b 20 20 20 20 20 20 20 20 20 20 20 20 20  C1K             
6b40: 20 20 30 78 30 30 30 30 30 30 30 34 0a 23 64 65    0x00000004.#de
6b50: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
6b60: 50 5f 41 54 4f 4d 49 43 32 4b 20 20 20 20 20 20  P_ATOMIC2K      
6b70: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
6b80: 30 30 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  008.#define SQLI
6b90: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 34  TE_IOCAP_ATOMIC4
6ba0: 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  K               
6bb0: 30 78 30 30 30 30 30 30 31 30 0a 23 64 65 66 69  0x00000010.#defi
6bc0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
6bd0: 41 54 4f 4d 49 43 38 4b 20 20 20 20 20 20 20 20  ATOMIC8K        
6be0: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 32         0x0000002
6bf0: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
6c00: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 36 4b  _IOCAP_ATOMIC16K
6c10: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78                0x
6c20: 30 30 30 30 30 30 34 30 0a 23 64 65 66 69 6e 65  00000040.#define
6c30: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
6c40: 4f 4d 49 43 33 32 4b 20 20 20 20 20 20 20 20 20  OMIC32K         
6c50: 20 20 20 20 20 30 78 30 30 30 30 30 30 38 30 0a       0x00000080.
6c60: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
6c70: 4f 43 41 50 5f 41 54 4f 4d 49 43 36 34 4b 20 20  OCAP_ATOMIC64K  
6c80: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30              0x00
6c90: 30 30 30 31 30 30 0a 23 64 65 66 69 6e 65 20 53  000100.#define S
6ca0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45  QLITE_IOCAP_SAFE
6cb0: 5f 41 50 50 45 4e 44 20 20 20 20 20 20 20 20 20  _APPEND         
6cc0: 20 20 20 30 78 30 30 30 30 30 32 30 30 0a 23 64     0x00000200.#d
6cd0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
6ce0: 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 20 20  AP_SEQUENTIAL   
6cf0: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
6d00: 30 34 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c  0400.#define SQL
6d10: 49 54 45 5f 49 4f 43 41 50 5f 55 4e 44 45 4c 45  ITE_IOCAP_UNDELE
6d20: 54 41 42 4c 45 5f 57 48 45 4e 5f 4f 50 45 4e 20  TABLE_WHEN_OPEN 
6d30: 20 30 78 30 30 30 30 30 38 30 30 0a 23 64 65 66   0x00000800.#def
6d40: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
6d50: 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57  _POWERSAFE_OVERW
6d60: 52 49 54 45 20 20 20 20 30 78 30 30 30 30 31 30  RITE    0x000010
6d70: 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  00.#define SQLIT
6d80: 45 5f 49 4f 43 41 50 5f 49 4d 4d 55 54 41 42 4c  E_IOCAP_IMMUTABL
6d90: 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30  E              0
6da0: 78 30 30 30 30 32 30 30 30 0a 0a 2f 2a 0a 2a 2a  x00002000../*.**
6db0: 20 43 41 50 49 33 52 45 46 3a 20 46 69 6c 65 20   CAPI3REF: File 
6dc0: 4c 6f 63 6b 69 6e 67 20 4c 65 76 65 6c 73 0a 2a  Locking Levels.*
6dd0: 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73 65 73  *.** SQLite uses
6de0: 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 69 6e   one of these in
6df0: 74 65 67 65 72 20 76 61 6c 75 65 73 20 61 73 20  teger values as 
6e00: 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 61 72  the second.** ar
6e10: 67 75 6d 65 6e 74 20 74 6f 20 63 61 6c 6c 73 20  gument to calls 
6e20: 69 74 20 6d 61 6b 65 73 20 74 6f 20 74 68 65 20  it makes to the 
6e30: 78 4c 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e 6c  xLock() and xUnl
6e40: 6f 63 6b 28 29 20 6d 65 74 68 6f 64 73 0a 2a 2a  ock() methods.**
6e50: 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f   of an [sqlite3_
6e60: 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65  io_methods] obje
6e70: 63 74 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ct..*/.#define S
6e80: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 20  QLITE_LOCK_NONE 
6e90: 20 20 20 20 20 20 20 20 20 30 0a 23 64 65 66 69           0.#defi
6ea0: 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53  ne SQLITE_LOCK_S
6eb0: 48 41 52 45 44 20 20 20 20 20 20 20 20 31 0a 23  HARED        1.#
6ec0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f  define SQLITE_LO
6ed0: 43 4b 5f 52 45 53 45 52 56 45 44 20 20 20 20 20  CK_RESERVED     
6ee0: 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   2.#define SQLIT
6ef0: 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 20 20  E_LOCK_PENDING  
6f00: 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53       3.#define S
6f10: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55  QLITE_LOCK_EXCLU
6f20: 53 49 56 45 20 20 20 20 20 34 0a 0a 2f 2a 0a 2a  SIVE     4../*.*
6f30: 2a 20 43 41 50 49 33 52 45 46 3a 20 53 79 6e 63  * CAPI3REF: Sync
6f40: 68 72 6f 6e 69 7a 61 74 69 6f 6e 20 54 79 70 65  hronization Type
6f50: 20 46 6c 61 67 73 0a 2a 2a 0a 2a 2a 20 57 68 65   Flags.**.** Whe
6f60: 6e 20 53 51 4c 69 74 65 20 69 6e 76 6f 6b 65 73  n SQLite invokes
6f70: 20 74 68 65 20 78 53 79 6e 63 28 29 20 6d 65 74   the xSync() met
6f80: 68 6f 64 20 6f 66 20 61 6e 0a 2a 2a 20 5b 73 71  hod of an.** [sq
6f90: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
6fa0: 5d 20 6f 62 6a 65 63 74 20 69 74 20 75 73 65 73  ] object it uses
6fb0: 20 61 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 6f   a combination o
6fc0: 66 0a 2a 2a 20 74 68 65 73 65 20 69 6e 74 65 67  f.** these integ
6fd0: 65 72 20 76 61 6c 75 65 73 20 61 73 20 74 68 65  er values as the
6fe0: 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
6ff0: 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65  ..**.** When the
7000: 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54   SQLITE_SYNC_DAT
7010: 41 4f 4e 4c 59 20 66 6c 61 67 20 69 73 20 75 73  AONLY flag is us
7020: 65 64 2c 20 69 74 20 6d 65 61 6e 73 20 74 68 61  ed, it means tha
7030: 74 20 74 68 65 0a 2a 2a 20 73 79 6e 63 20 6f 70  t the.** sync op
7040: 65 72 61 74 69 6f 6e 20 6f 6e 6c 79 20 6e 65 65  eration only nee
7050: 64 73 20 74 6f 20 66 6c 75 73 68 20 64 61 74 61  ds to flush data
7060: 20 74 6f 20 6d 61 73 73 20 73 74 6f 72 61 67 65   to mass storage
7070: 2e 20 20 49 6e 6f 64 65 0a 2a 2a 20 69 6e 66 6f  .  Inode.** info
7080: 72 6d 61 74 69 6f 6e 20 6e 65 65 64 20 6e 6f 74  rmation need not
7090: 20 62 65 20 66 6c 75 73 68 65 64 2e 20 49 66 20   be flushed. If 
70a0: 74 68 65 20 6c 6f 77 65 72 20 66 6f 75 72 20 62  the lower four b
70b0: 69 74 73 20 6f 66 20 74 68 65 20 66 6c 61 67 0a  its of the flag.
70c0: 2a 2a 20 65 71 75 61 6c 20 53 51 4c 49 54 45 5f  ** equal SQLITE_
70d0: 53 59 4e 43 5f 4e 4f 52 4d 41 4c 2c 20 74 68 61  SYNC_NORMAL, tha
70e0: 74 20 6d 65 61 6e 73 20 74 6f 20 75 73 65 20 6e  t means to use n
70f0: 6f 72 6d 61 6c 20 66 73 79 6e 63 28 29 20 73 65  ormal fsync() se
7100: 6d 61 6e 74 69 63 73 2e 0a 2a 2a 20 49 66 20 74  mantics..** If t
7110: 68 65 20 6c 6f 77 65 72 20 66 6f 75 72 20 62 69  he lower four bi
7120: 74 73 20 65 71 75 61 6c 20 53 51 4c 49 54 45 5f  ts equal SQLITE_
7130: 53 59 4e 43 5f 46 55 4c 4c 2c 20 74 68 61 74 20  SYNC_FULL, that 
7140: 6d 65 61 6e 73 0a 2a 2a 20 74 6f 20 75 73 65 20  means.** to use 
7150: 4d 61 63 20 4f 53 20 58 20 73 74 79 6c 65 20 66  Mac OS X style f
7160: 75 6c 6c 73 79 6e 63 20 69 6e 73 74 65 61 64 20  ullsync instead 
7170: 6f 66 20 66 73 79 6e 63 28 29 2e 0a 2a 2a 0a 2a  of fsync()..**.*
7180: 2a 20 44 6f 20 6e 6f 74 20 63 6f 6e 66 75 73 65  * Do not confuse
7190: 20 74 68 65 20 53 51 4c 49 54 45 5f 53 59 4e 43   the SQLITE_SYNC
71a0: 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49  _NORMAL and SQLI
71b0: 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 66 6c 61  TE_SYNC_FULL fla
71c0: 67 73 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b  gs.** with the [
71d0: 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f  PRAGMA synchrono
71e0: 75 73 5d 3d 4e 4f 52 4d 41 4c 20 61 6e 64 20 5b  us]=NORMAL and [
71f0: 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f  PRAGMA synchrono
7200: 75 73 5d 3d 46 55 4c 4c 0a 2a 2a 20 73 65 74 74  us]=FULL.** sett
7210: 69 6e 67 73 2e 20 20 54 68 65 20 5b 73 79 6e 63  ings.  The [sync
7220: 68 72 6f 6e 6f 75 73 20 70 72 61 67 6d 61 5d 20  hronous pragma] 
7230: 64 65 74 65 72 6d 69 6e 65 73 20 77 68 65 6e 20  determines when 
7240: 63 61 6c 6c 73 20 74 6f 20 74 68 65 0a 2a 2a 20  calls to the.** 
7250: 78 53 79 6e 63 20 56 46 53 20 6d 65 74 68 6f 64  xSync VFS method
7260: 20 6f 63 63 75 72 20 61 6e 64 20 61 70 70 6c 69   occur and appli
7270: 65 73 20 75 6e 69 66 6f 72 6d 6c 79 20 61 63 72  es uniformly acr
7280: 6f 73 73 20 61 6c 6c 20 70 6c 61 74 66 6f 72 6d  oss all platform
7290: 73 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45  s..** The SQLITE
72a0: 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64  _SYNC_NORMAL and
72b0: 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c   SQLITE_SYNC_FUL
72c0: 4c 20 66 6c 61 67 73 20 64 65 74 65 72 6d 69 6e  L flags determin
72d0: 65 20 68 6f 77 0a 2a 2a 20 65 6e 65 72 67 65 74  e how.** energet
72e0: 69 63 20 6f 72 20 72 69 67 6f 72 6f 75 73 20 6f  ic or rigorous o
72f0: 72 20 66 6f 72 63 65 66 75 6c 20 74 68 65 20 73  r forceful the s
7300: 79 6e 63 20 6f 70 65 72 61 74 69 6f 6e 73 20 61  ync operations a
7310: 72 65 20 61 6e 64 0a 2a 2a 20 6f 6e 6c 79 20 6d  re and.** only m
7320: 61 6b 65 20 61 20 64 69 66 66 65 72 65 6e 63 65  ake a difference
7330: 20 6f 6e 20 4d 61 63 20 4f 53 58 20 66 6f 72 20   on Mac OSX for 
7340: 74 68 65 20 64 65 66 61 75 6c 74 20 53 51 4c 69  the default SQLi
7350: 74 65 20 63 6f 64 65 2e 0a 2a 2a 20 28 54 68 69  te code..** (Thi
7360: 72 64 2d 70 61 72 74 79 20 56 46 53 20 69 6d 70  rd-party VFS imp
7370: 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6d 69 67  lementations mig
7380: 68 74 20 61 6c 73 6f 20 6d 61 6b 65 20 74 68 65  ht also make the
7390: 20 64 69 73 74 69 6e 63 74 69 6f 6e 0a 2a 2a 20   distinction.** 
73a0: 62 65 74 77 65 65 6e 20 53 51 4c 49 54 45 5f 53  between SQLITE_S
73b0: 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53  YNC_NORMAL and S
73c0: 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 2c  QLITE_SYNC_FULL,
73d0: 20 62 75 74 20 61 6d 6f 6e 67 20 74 68 65 0a 2a   but among the.*
73e0: 2a 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74  * operating syst
73f0: 65 6d 73 20 6e 61 74 69 76 65 6c 79 20 73 75 70  ems natively sup
7400: 70 6f 72 74 65 64 20 62 79 20 53 51 4c 69 74 65  ported by SQLite
7410: 2c 20 6f 6e 6c 79 20 4d 61 63 20 4f 53 58 0a 2a  , only Mac OSX.*
7420: 2a 20 63 61 72 65 73 20 61 62 6f 75 74 20 74 68  * cares about th
7430: 65 20 64 69 66 66 65 72 65 6e 63 65 2e 29 0a 2a  e difference.).*
7440: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
7450: 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 20 20 20  _SYNC_NORMAL    
7460: 20 20 20 20 30 78 30 30 30 30 32 0a 23 64 65 66      0x00002.#def
7470: 69 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f  ine SQLITE_SYNC_
7480: 46 55 4c 4c 20 20 20 20 20 20 20 20 20 20 30 78  FULL          0x
7490: 30 30 30 30 33 0a 23 64 65 66 69 6e 65 20 53 51  00003.#define SQ
74a0: 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e  LITE_SYNC_DATAON
74b0: 4c 59 20 20 20 20 20 20 30 78 30 30 30 31 30 0a  LY      0x00010.
74c0: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
74d0: 20 4f 53 20 49 6e 74 65 72 66 61 63 65 20 4f 70   OS Interface Op
74e0: 65 6e 20 46 69 6c 65 20 48 61 6e 64 6c 65 0a 2a  en File Handle.*
74f0: 2a 0a 2a 2a 20 41 6e 20 5b 73 71 6c 69 74 65 33  *.** An [sqlite3
7500: 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 72 65  _file] object re
7510: 70 72 65 73 65 6e 74 73 20 61 6e 20 6f 70 65 6e  presents an open
7520: 20 66 69 6c 65 20 69 6e 20 74 68 65 20 0a 2a 2a   file in the .**
7530: 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 20 7c 20   [sqlite3_vfs | 
7540: 4f 53 20 69 6e 74 65 72 66 61 63 65 20 6c 61 79  OS interface lay
7550: 65 72 5d 2e 20 20 49 6e 64 69 76 69 64 75 61 6c  er].  Individual
7560: 20 4f 53 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a   OS interface.**
7570: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
7580: 20 77 69 6c 6c 0a 2a 2a 20 77 61 6e 74 20 74 6f   will.** want to
7590: 20 73 75 62 63 6c 61 73 73 20 74 68 69 73 20 6f   subclass this o
75a0: 62 6a 65 63 74 20 62 79 20 61 70 70 65 6e 64 69  bject by appendi
75b0: 6e 67 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 69  ng additional fi
75c0: 65 6c 64 73 0a 2a 2a 20 66 6f 72 20 74 68 65 69  elds.** for thei
75d0: 72 20 6f 77 6e 20 75 73 65 2e 20 20 54 68 65 20  r own use.  The 
75e0: 70 4d 65 74 68 6f 64 73 20 65 6e 74 72 79 20 69  pMethods entry i
75f0: 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
7600: 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6f  n.** [sqlite3_io
7610: 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74  _methods] object
7620: 20 74 68 61 74 20 64 65 66 69 6e 65 73 20 6d 65   that defines me
7630: 74 68 6f 64 73 20 66 6f 72 20 70 65 72 66 6f 72  thods for perfor
7640: 6d 69 6e 67 0a 2a 2a 20 49 2f 4f 20 6f 70 65 72  ming.** I/O oper
7650: 61 74 69 6f 6e 73 20 6f 6e 20 74 68 65 20 6f 70  ations on the op
7660: 65 6e 20 66 69 6c 65 2e 0a 2a 2f 0a 74 79 70 65  en file..*/.type
7670: 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
7680: 65 33 5f 66 69 6c 65 20 73 71 6c 69 74 65 33 5f  e3_file sqlite3_
7690: 66 69 6c 65 3b 0a 73 74 72 75 63 74 20 73 71 6c  file;.struct sql
76a0: 69 74 65 33 5f 66 69 6c 65 20 7b 0a 20 20 63 6f  ite3_file {.  co
76b0: 6e 73 74 20 73 74 72 75 63 74 20 73 71 6c 69 74  nst struct sqlit
76c0: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 2a 70  e3_io_methods *p
76d0: 4d 65 74 68 6f 64 73 3b 20 20 2f 2a 20 4d 65 74  Methods;  /* Met
76e0: 68 6f 64 73 20 66 6f 72 20 61 6e 20 6f 70 65 6e  hods for an open
76f0: 20 66 69 6c 65 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a   file */.};../*.
7700: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20  ** CAPI3REF: OS 
7710: 49 6e 74 65 72 66 61 63 65 20 46 69 6c 65 20 56  Interface File V
7720: 69 72 74 75 61 6c 20 4d 65 74 68 6f 64 73 20 4f  irtual Methods O
7730: 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 45 76 65 72  bject.**.** Ever
7740: 79 20 66 69 6c 65 20 6f 70 65 6e 65 64 20 62 79  y file opened by
7750: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66   the [sqlite3_vf
7760: 73 2e 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 20  s.xOpen] method 
7770: 70 6f 70 75 6c 61 74 65 73 20 61 6e 0a 2a 2a 20  populates an.** 
7780: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f  [sqlite3_file] o
7790: 62 6a 65 63 74 20 28 6f 72 2c 20 6d 6f 72 65 20  bject (or, more 
77a0: 63 6f 6d 6d 6f 6e 6c 79 2c 20 61 20 73 75 62 63  commonly, a subc
77b0: 6c 61 73 73 20 6f 66 20 74 68 65 0a 2a 2a 20 5b  lass of the.** [
77c0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62  sqlite3_file] ob
77d0: 6a 65 63 74 29 20 77 69 74 68 20 61 20 70 6f 69  ject) with a poi
77e0: 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61  nter to an insta
77f0: 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65  nce of this obje
7800: 63 74 2e 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65  ct..** This obje
7810: 63 74 20 64 65 66 69 6e 65 73 20 74 68 65 20 6d  ct defines the m
7820: 65 74 68 6f 64 73 20 75 73 65 64 20 74 6f 20 70  ethods used to p
7830: 65 72 66 6f 72 6d 20 76 61 72 69 6f 75 73 20 6f  erform various o
7840: 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 20 61 67 61  perations.** aga
7850: 69 6e 73 74 20 74 68 65 20 6f 70 65 6e 20 66 69  inst the open fi
7860: 6c 65 20 72 65 70 72 65 73 65 6e 74 65 64 20 62  le represented b
7870: 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66  y the [sqlite3_f
7880: 69 6c 65 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a  ile] object..**.
7890: 2a 2a 20 49 66 20 74 68 65 20 5b 73 71 6c 69 74  ** If the [sqlit
78a0: 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 6d 65  e3_vfs.xOpen] me
78b0: 74 68 6f 64 20 73 65 74 73 20 74 68 65 20 73 71  thod sets the sq
78c0: 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68  lite3_file.pMeth
78d0: 6f 64 73 20 65 6c 65 6d 65 6e 74 20 0a 2a 2a 20  ods element .** 
78e0: 74 6f 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f  to a non-NULL po
78f0: 69 6e 74 65 72 2c 20 74 68 65 6e 20 74 68 65 20  inter, then the 
7900: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
7910: 64 73 2e 78 43 6c 6f 73 65 20 6d 65 74 68 6f 64  ds.xClose method
7920: 0a 2a 2a 20 6d 61 79 20 62 65 20 69 6e 76 6f 6b  .** may be invok
7930: 65 64 20 65 76 65 6e 20 69 66 20 74 68 65 20 5b  ed even if the [
7940: 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65  sqlite3_vfs.xOpe
7950: 6e 5d 20 72 65 70 6f 72 74 65 64 20 74 68 61 74  n] reported that
7960: 20 69 74 20 66 61 69 6c 65 64 2e 20 20 54 68 65   it failed.  The
7970: 0a 2a 2a 20 6f 6e 6c 79 20 77 61 79 20 74 6f 20  .** only way to 
7980: 70 72 65 76 65 6e 74 20 61 20 63 61 6c 6c 20 74  prevent a call t
7990: 6f 20 78 43 6c 6f 73 65 20 66 6f 6c 6c 6f 77 69  o xClose followi
79a0: 6e 67 20 61 20 66 61 69 6c 65 64 20 5b 73 71 6c  ng a failed [sql
79b0: 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 0a  ite3_vfs.xOpen].
79c0: 2a 2a 20 69 73 20 66 6f 72 20 74 68 65 20 5b 73  ** is for the [s
79d0: 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e  qlite3_vfs.xOpen
79e0: 5d 20 74 6f 20 73 65 74 20 74 68 65 20 73 71 6c  ] to set the sql
79f0: 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f  ite3_file.pMetho
7a00: 64 73 20 65 6c 65 6d 65 6e 74 0a 2a 2a 20 74 6f  ds element.** to
7a10: 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65   NULL..**.** The
7a20: 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20   flags argument 
7a30: 74 6f 20 78 53 79 6e 63 20 6d 61 79 20 62 65 20  to xSync may be 
7a40: 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 53  one of [SQLITE_S
7a50: 59 4e 43 5f 4e 4f 52 4d 41 4c 5d 20 6f 72 0a 2a  YNC_NORMAL] or.*
7a60: 2a 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46  * [SQLITE_SYNC_F
7a70: 55 4c 4c 5d 2e 20 20 54 68 65 20 66 69 72 73 74  ULL].  The first
7a80: 20 63 68 6f 69 63 65 20 69 73 20 74 68 65 20 6e   choice is the n
7a90: 6f 72 6d 61 6c 20 66 73 79 6e 63 28 29 2e 0a 2a  ormal fsync()..*
7aa0: 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 63 68 6f  * The second cho
7ab0: 69 63 65 20 69 73 20 61 20 4d 61 63 20 4f 53 20  ice is a Mac OS 
7ac0: 58 20 73 74 79 6c 65 20 66 75 6c 6c 73 79 6e 63  X style fullsync
7ad0: 2e 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 53  .  The [SQLITE_S
7ae0: 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 5d 0a 2a 2a  YNC_DATAONLY].**
7af0: 20 66 6c 61 67 20 6d 61 79 20 62 65 20 4f 52 65   flag may be ORe
7b00: 64 20 69 6e 20 74 6f 20 69 6e 64 69 63 61 74 65  d in to indicate
7b10: 20 74 68 61 74 20 6f 6e 6c 79 20 74 68 65 20 64   that only the d
7b20: 61 74 61 20 6f 66 20 74 68 65 20 66 69 6c 65 0a  ata of the file.
7b30: 2a 2a 20 61 6e 64 20 6e 6f 74 20 69 74 73 20 69  ** and not its i
7b40: 6e 6f 64 65 20 6e 65 65 64 73 20 74 6f 20 62 65  node needs to be
7b50: 20 73 79 6e 63 65 64 2e 0a 2a 2a 0a 2a 2a 20 54   synced..**.** T
7b60: 68 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65  he integer value
7b70: 73 20 74 6f 20 78 4c 6f 63 6b 28 29 20 61 6e 64  s to xLock() and
7b80: 20 78 55 6e 6c 6f 63 6b 28 29 20 61 72 65 20 6f   xUnlock() are o
7b90: 6e 65 20 6f 66 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  ne of.** <ul>.**
7ba0: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f   <li> [SQLITE_LO
7bb0: 43 4b 5f 4e 4f 4e 45 5d 2c 0a 2a 2a 20 3c 6c 69  CK_NONE],.** <li
7bc0: 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53  > [SQLITE_LOCK_S
7bd0: 48 41 52 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20  HARED],.** <li> 
7be0: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53  [SQLITE_LOCK_RES
7bf0: 45 52 56 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20  ERVED],.** <li> 
7c00: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e  [SQLITE_LOCK_PEN
7c10: 44 49 4e 47 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c 69  DING], or.** <li
7c20: 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45  > [SQLITE_LOCK_E
7c30: 58 43 4c 55 53 49 56 45 5d 2e 0a 2a 2a 20 3c 2f  XCLUSIVE]..** </
7c40: 75 6c 3e 0a 2a 2a 20 78 4c 6f 63 6b 28 29 20 69  ul>.** xLock() i
7c50: 6e 63 72 65 61 73 65 73 20 74 68 65 20 6c 6f 63  ncreases the loc
7c60: 6b 2e 20 78 55 6e 6c 6f 63 6b 28 29 20 64 65 63  k. xUnlock() dec
7c70: 72 65 61 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e  reases the lock.
7c80: 0a 2a 2a 20 54 68 65 20 78 43 68 65 63 6b 52 65  .** The xCheckRe
7c90: 73 65 72 76 65 64 4c 6f 63 6b 28 29 20 6d 65 74  servedLock() met
7ca0: 68 6f 64 20 63 68 65 63 6b 73 20 77 68 65 74 68  hod checks wheth
7cb0: 65 72 20 61 6e 79 20 64 61 74 61 62 61 73 65 20  er any database 
7cc0: 63 6f 6e 6e 65 63 74 69 6f 6e 2c 0a 2a 2a 20 65  connection,.** e
7cd0: 69 74 68 65 72 20 69 6e 20 74 68 69 73 20 70 72  ither in this pr
7ce0: 6f 63 65 73 73 20 6f 72 20 69 6e 20 73 6f 6d 65  ocess or in some
7cf0: 20 6f 74 68 65 72 20 70 72 6f 63 65 73 73 2c 20   other process, 
7d00: 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 52 45 53  is holding a RES
7d10: 45 52 56 45 44 2c 0a 2a 2a 20 50 45 4e 44 49 4e  ERVED,.** PENDIN
7d20: 47 2c 20 6f 72 20 45 58 43 4c 55 53 49 56 45 20  G, or EXCLUSIVE 
7d30: 6c 6f 63 6b 20 6f 6e 20 74 68 65 20 66 69 6c 65  lock on the file
7d40: 2e 20 20 49 74 20 72 65 74 75 72 6e 73 20 74 72  .  It returns tr
7d50: 75 65 0a 2a 2a 20 69 66 20 73 75 63 68 20 61 20  ue.** if such a 
7d60: 6c 6f 63 6b 20 65 78 69 73 74 73 20 61 6e 64 20  lock exists and 
7d70: 66 61 6c 73 65 20 6f 74 68 65 72 77 69 73 65 2e  false otherwise.
7d80: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 46 69 6c 65  .**.** The xFile
7d90: 43 6f 6e 74 72 6f 6c 28 29 20 6d 65 74 68 6f 64  Control() method
7da0: 20 69 73 20 61 20 67 65 6e 65 72 69 63 20 69 6e   is a generic in
7db0: 74 65 72 66 61 63 65 20 74 68 61 74 20 61 6c 6c  terface that all
7dc0: 6f 77 73 20 63 75 73 74 6f 6d 0a 2a 2a 20 56 46  ows custom.** VF
7dd0: 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  S implementation
7de0: 73 20 74 6f 20 64 69 72 65 63 74 6c 79 20 63 6f  s to directly co
7df0: 6e 74 72 6f 6c 20 61 6e 20 6f 70 65 6e 20 66 69  ntrol an open fi
7e00: 6c 65 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20  le using the.** 
7e10: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f  [sqlite3_file_co
7e20: 6e 74 72 6f 6c 28 29 5d 20 69 6e 74 65 72 66 61  ntrol()] interfa
7e30: 63 65 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20  ce.  The second 
7e40: 22 6f 70 22 20 61 72 67 75 6d 65 6e 74 20 69 73  "op" argument is
7e50: 20 61 6e 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6f   an.** integer o
7e60: 70 63 6f 64 65 2e 20 20 54 68 65 20 74 68 69 72  pcode.  The thir
7e70: 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20  d argument is a 
7e80: 67 65 6e 65 72 69 63 20 70 6f 69 6e 74 65 72 20  generic pointer 
7e90: 69 6e 74 65 6e 64 65 64 20 74 6f 0a 2a 2a 20 70  intended to.** p
7ea0: 6f 69 6e 74 20 74 6f 20 61 20 73 74 72 75 63 74  oint to a struct
7eb0: 75 72 65 20 74 68 61 74 20 6d 61 79 20 63 6f 6e  ure that may con
7ec0: 74 61 69 6e 20 61 72 67 75 6d 65 6e 74 73 20 6f  tain arguments o
7ed0: 72 20 73 70 61 63 65 20 69 6e 20 77 68 69 63 68  r space in which
7ee0: 20 74 6f 0a 2a 2a 20 77 72 69 74 65 20 72 65 74   to.** write ret
7ef0: 75 72 6e 20 76 61 6c 75 65 73 2e 20 20 50 6f 74  urn values.  Pot
7f00: 65 6e 74 69 61 6c 20 75 73 65 73 20 66 6f 72 20  ential uses for 
7f10: 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d  xFileControl() m
7f20: 69 67 68 74 20 62 65 0a 2a 2a 20 66 75 6e 63 74  ight be.** funct
7f30: 69 6f 6e 73 20 74 6f 20 65 6e 61 62 6c 65 20 62  ions to enable b
7f40: 6c 6f 63 6b 69 6e 67 20 6c 6f 63 6b 73 20 77 69  locking locks wi
7f50: 74 68 20 74 69 6d 65 6f 75 74 73 2c 20 74 6f 20  th timeouts, to 
7f60: 63 68 61 6e 67 65 20 74 68 65 0a 2a 2a 20 6c 6f  change the.** lo
7f70: 63 6b 69 6e 67 20 73 74 72 61 74 65 67 79 20 28  cking strategy (
7f80: 66 6f 72 20 65 78 61 6d 70 6c 65 20 74 6f 20 75  for example to u
7f90: 73 65 20 64 6f 74 2d 66 69 6c 65 20 6c 6f 63 6b  se dot-file lock
7fa0: 73 29 2c 20 74 6f 20 69 6e 71 75 69 72 65 0a 2a  s), to inquire.*
7fb0: 2a 20 61 62 6f 75 74 20 74 68 65 20 73 74 61 74  * about the stat
7fc0: 75 73 20 6f 66 20 61 20 6c 6f 63 6b 2c 20 6f 72  us of a lock, or
7fd0: 20 74 6f 20 62 72 65 61 6b 20 73 74 61 6c 65 20   to break stale 
7fe0: 6c 6f 63 6b 73 2e 20 20 54 68 65 20 53 51 4c 69  locks.  The SQLi
7ff0: 74 65 0a 2a 2a 20 63 6f 72 65 20 72 65 73 65 72  te.** core reser
8000: 76 65 73 20 61 6c 6c 20 6f 70 63 6f 64 65 73 20  ves all opcodes 
8010: 6c 65 73 73 20 74 68 61 6e 20 31 30 30 20 66 6f  less than 100 fo
8020: 72 20 69 74 73 20 6f 77 6e 20 75 73 65 2e 0a 2a  r its own use..*
8030: 2a 20 41 20 5b 66 69 6c 65 20 63 6f 6e 74 72 6f  * A [file contro
8040: 6c 20 6f 70 63 6f 64 65 73 20 7c 20 6c 69 73 74  l opcodes | list
8050: 20 6f 66 20 6f 70 63 6f 64 65 73 5d 20 6c 65 73   of opcodes] les
8060: 73 20 74 68 61 6e 20 31 30 30 20 69 73 20 61 76  s than 100 is av
8070: 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20 41 70 70 6c  ailable..** Appl
8080: 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 64 65  ications that de
8090: 66 69 6e 65 20 61 20 63 75 73 74 6f 6d 20 78 46  fine a custom xF
80a0: 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f  ileControl metho
80b0: 64 20 73 68 6f 75 6c 64 20 75 73 65 20 6f 70 63  d should use opc
80c0: 6f 64 65 73 0a 2a 2a 20 67 72 65 61 74 65 72 20  odes.** greater 
80d0: 74 68 61 6e 20 31 30 30 20 74 6f 20 61 76 6f 69  than 100 to avoi
80e0: 64 20 63 6f 6e 66 6c 69 63 74 73 2e 20 20 56 46  d conflicts.  VF
80f0: 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  S implementation
8100: 73 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 75  s should.** retu
8110: 72 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f 54 46 4f  rn [SQLITE_NOTFO
8120: 55 4e 44 5d 20 66 6f 72 20 66 69 6c 65 20 63 6f  UND] for file co
8130: 6e 74 72 6f 6c 20 6f 70 63 6f 64 65 73 20 74 68  ntrol opcodes th
8140: 61 74 20 74 68 65 79 20 64 6f 20 6e 6f 74 0a 2a  at they do not.*
8150: 2a 20 72 65 63 6f 67 6e 69 7a 65 2e 0a 2a 2a 0a  * recognize..**.
8160: 2a 2a 20 54 68 65 20 78 53 65 63 74 6f 72 53 69  ** The xSectorSi
8170: 7a 65 28 29 20 6d 65 74 68 6f 64 20 72 65 74 75  ze() method retu
8180: 72 6e 73 20 74 68 65 20 73 65 63 74 6f 72 20 73  rns the sector s
8190: 69 7a 65 20 6f 66 20 74 68 65 0a 2a 2a 20 64 65  ize of the.** de
81a0: 76 69 63 65 20 74 68 61 74 20 75 6e 64 65 72 6c  vice that underl
81b0: 69 65 73 20 74 68 65 20 66 69 6c 65 2e 20 20 54  ies the file.  T
81c0: 68 65 20 73 65 63 74 6f 72 20 73 69 7a 65 20 69  he sector size i
81d0: 73 20 74 68 65 0a 2a 2a 20 6d 69 6e 69 6d 75 6d  s the.** minimum
81e0: 20 77 72 69 74 65 20 74 68 61 74 20 63 61 6e 20   write that can 
81f0: 62 65 20 70 65 72 66 6f 72 6d 65 64 20 77 69 74  be performed wit
8200: 68 6f 75 74 20 64 69 73 74 75 72 62 69 6e 67 0a  hout disturbing.
8210: 2a 2a 20 6f 74 68 65 72 20 62 79 74 65 73 20 69  ** other bytes i
8220: 6e 20 74 68 65 20 66 69 6c 65 2e 20 20 54 68 65  n the file.  The
8230: 20 78 44 65 76 69 63 65 43 68 61 72 61 63 74 65   xDeviceCharacte
8240: 72 69 73 74 69 63 73 28 29 0a 2a 2a 20 6d 65 74  ristics().** met
8250: 68 6f 64 20 72 65 74 75 72 6e 73 20 61 20 62 69  hod returns a bi
8260: 74 20 76 65 63 74 6f 72 20 64 65 73 63 72 69 62  t vector describ
8270: 69 6e 67 20 62 65 68 61 76 69 6f 72 73 20 6f 66  ing behaviors of
8280: 20 74 68 65 0a 2a 2a 20 75 6e 64 65 72 6c 79 69   the.** underlyi
8290: 6e 67 20 64 65 76 69 63 65 3a 0a 2a 2a 0a 2a 2a  ng device:.**.**
82a0: 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53   <ul>.** <li> [S
82b0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
82c0: 49 43 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  IC].** <li> [SQL
82d0: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
82e0: 35 31 32 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  512].** <li> [SQ
82f0: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
8300: 43 31 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  C1K].** <li> [SQ
8310: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
8320: 43 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  C2K].** <li> [SQ
8330: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
8340: 43 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  C4K].** <li> [SQ
8350: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
8360: 43 38 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  C8K].** <li> [SQ
8370: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
8380: 43 31 36 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  C16K].** <li> [S
8390: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
83a0: 49 43 33 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  IC32K].** <li> [
83b0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
83c0: 4d 49 43 36 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20  MIC64K].** <li> 
83d0: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41  [SQLITE_IOCAP_SA
83e0: 46 45 5f 41 50 50 45 4e 44 5d 0a 2a 2a 20 3c 6c  FE_APPEND].** <l
83f0: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  i> [SQLITE_IOCAP
8400: 5f 53 45 51 55 45 4e 54 49 41 4c 5d 0a 2a 2a 20  _SEQUENTIAL].** 
8410: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43  <li> [SQLITE_IOC
8420: 41 50 5f 55 4e 44 45 4c 45 54 41 42 4c 45 5f 57  AP_UNDELETABLE_W
8430: 48 45 4e 5f 4f 50 45 4e 5d 0a 2a 2a 20 3c 6c 69  HEN_OPEN].** <li
8440: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
8450: 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52  POWERSAFE_OVERWR
8460: 49 54 45 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  ITE].** <li> [SQ
8470: 4c 49 54 45 5f 49 4f 43 41 50 5f 49 4d 4d 55 54  LITE_IOCAP_IMMUT
8480: 41 42 4c 45 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a  ABLE].** </ul>.*
8490: 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f  *.** The SQLITE_
84a0: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20 70 72 6f  IOCAP_ATOMIC pro
84b0: 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74  perty means that
84c0: 20 61 6c 6c 20 77 72 69 74 65 73 20 6f 66 0a 2a   all writes of.*
84d0: 2a 20 61 6e 79 20 73 69 7a 65 20 61 72 65 20 61  * any size are a
84e0: 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 4c 49  tomic.  The SQLI
84f0: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 6e  TE_IOCAP_ATOMICn
8500: 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a 20 6d 65 61  nn values.** mea
8510: 6e 20 74 68 61 74 20 77 72 69 74 65 73 20 6f 66  n that writes of
8520: 20 62 6c 6f 63 6b 73 20 74 68 61 74 20 61 72 65   blocks that are
8530: 20 6e 6e 6e 20 62 79 74 65 73 20 69 6e 20 73 69   nnn bytes in si
8540: 7a 65 20 61 6e 64 0a 2a 2a 20 61 72 65 20 61 6c  ze and.** are al
8550: 69 67 6e 65 64 20 74 6f 20 61 6e 20 61 64 64 72  igned to an addr
8560: 65 73 73 20 77 68 69 63 68 20 69 73 20 61 6e 20  ess which is an 
8570: 69 6e 74 65 67 65 72 20 6d 75 6c 74 69 70 6c 65  integer multiple
8580: 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 72 65 20 61   of.** nnn are a
8590: 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 4c 49  tomic.  The SQLI
85a0: 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50  TE_IOCAP_SAFE_AP
85b0: 50 45 4e 44 20 76 61 6c 75 65 20 6d 65 61 6e 73  PEND value means
85c0: 0a 2a 2a 20 74 68 61 74 20 77 68 65 6e 20 64 61  .** that when da
85d0: 74 61 20 69 73 20 61 70 70 65 6e 64 65 64 20 74  ta is appended t
85e0: 6f 20 61 20 66 69 6c 65 2c 20 74 68 65 20 64 61  o a file, the da
85f0: 74 61 20 69 73 20 61 70 70 65 6e 64 65 64 0a 2a  ta is appended.*
8600: 2a 20 66 69 72 73 74 20 74 68 65 6e 20 74 68 65  * first then the
8610: 20 73 69 7a 65 20 6f 66 20 74 68 65 20 66 69 6c   size of the fil
8620: 65 20 69 73 20 65 78 74 65 6e 64 65 64 2c 20 6e  e is extended, n
8630: 65 76 65 72 20 74 68 65 20 6f 74 68 65 72 0a 2a  ever the other.*
8640: 2a 20 77 61 79 20 61 72 6f 75 6e 64 2e 20 20 54  * way around.  T
8650: 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  he SQLITE_IOCAP_
8660: 53 45 51 55 45 4e 54 49 41 4c 20 70 72 6f 70 65  SEQUENTIAL prope
8670: 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74 0a 2a  rty means that.*
8680: 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73  * information is
8690: 20 77 72 69 74 74 65 6e 20 74 6f 20 64 69 73 6b   written to disk
86a0: 20 69 6e 20 74 68 65 20 73 61 6d 65 20 6f 72 64   in the same ord
86b0: 65 72 20 61 73 20 63 61 6c 6c 73 0a 2a 2a 20 74  er as calls.** t
86c0: 6f 20 78 57 72 69 74 65 28 29 2e 0a 2a 2a 0a 2a  o xWrite()..**.*
86d0: 2a 20 49 66 20 78 52 65 61 64 28 29 20 72 65 74  * If xRead() ret
86e0: 75 72 6e 73 20 53 51 4c 49 54 45 5f 49 4f 45 52  urns SQLITE_IOER
86f0: 52 5f 53 48 4f 52 54 5f 52 45 41 44 20 69 74 20  R_SHORT_READ it 
8700: 6d 75 73 74 20 61 6c 73 6f 20 66 69 6c 6c 0a 2a  must also fill.*
8710: 2a 20 69 6e 20 74 68 65 20 75 6e 72 65 61 64 20  * in the unread 
8720: 70 6f 72 74 69 6f 6e 73 20 6f 66 20 74 68 65 20  portions of the 
8730: 62 75 66 66 65 72 20 77 69 74 68 20 7a 65 72 6f  buffer with zero
8740: 73 2e 20 20 41 20 56 46 53 20 74 68 61 74 0a 2a  s.  A VFS that.*
8750: 2a 20 66 61 69 6c 73 20 74 6f 20 7a 65 72 6f 2d  * fails to zero-
8760: 66 69 6c 6c 20 73 68 6f 72 74 20 72 65 61 64 73  fill short reads
8770: 20 6d 69 67 68 74 20 73 65 65 6d 20 74 6f 20 77   might seem to w
8780: 6f 72 6b 2e 20 20 48 6f 77 65 76 65 72 2c 0a 2a  ork.  However,.*
8790: 2a 20 66 61 69 6c 75 72 65 20 74 6f 20 7a 65 72  * failure to zer
87a0: 6f 2d 66 69 6c 6c 20 73 68 6f 72 74 20 72 65 61  o-fill short rea
87b0: 64 73 20 77 69 6c 6c 20 65 76 65 6e 74 75 61 6c  ds will eventual
87c0: 6c 79 20 6c 65 61 64 20 74 6f 0a 2a 2a 20 64 61  ly lead to.** da
87d0: 74 61 62 61 73 65 20 63 6f 72 72 75 70 74 69 6f  tabase corruptio
87e0: 6e 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74  n..*/.typedef st
87f0: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f  ruct sqlite3_io_
8800: 6d 65 74 68 6f 64 73 20 73 71 6c 69 74 65 33 5f  methods sqlite3_
8810: 69 6f 5f 6d 65 74 68 6f 64 73 3b 0a 73 74 72 75  io_methods;.stru
8820: 63 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  ct sqlite3_io_me
8830: 74 68 6f 64 73 20 7b 0a 20 20 69 6e 74 20 69 56  thods {.  int iV
8840: 65 72 73 69 6f 6e 3b 0a 20 20 69 6e 74 20 28 2a  ersion;.  int (*
8850: 78 43 6c 6f 73 65 29 28 73 71 6c 69 74 65 33 5f  xClose)(sqlite3_
8860: 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a  file*);.  int (*
8870: 78 52 65 61 64 29 28 73 71 6c 69 74 65 33 5f 66  xRead)(sqlite3_f
8880: 69 6c 65 2a 2c 20 76 6f 69 64 2a 2c 20 69 6e 74  ile*, void*, int
8890: 20 69 41 6d 74 2c 20 73 71 6c 69 74 65 33 5f 69   iAmt, sqlite3_i
88a0: 6e 74 36 34 20 69 4f 66 73 74 29 3b 0a 20 20 69  nt64 iOfst);.  i
88b0: 6e 74 20 28 2a 78 57 72 69 74 65 29 28 73 71 6c  nt (*xWrite)(sql
88c0: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 63 6f 6e 73  ite3_file*, cons
88d0: 74 20 76 6f 69 64 2a 2c 20 69 6e 74 20 69 41 6d  t void*, int iAm
88e0: 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  t, sqlite3_int64
88f0: 20 69 4f 66 73 74 29 3b 0a 20 20 69 6e 74 20 28   iOfst);.  int (
8900: 2a 78 54 72 75 6e 63 61 74 65 29 28 73 71 6c 69  *xTruncate)(sqli
8910: 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74  te3_file*, sqlit
8920: 65 33 5f 69 6e 74 36 34 20 73 69 7a 65 29 3b 0a  e3_int64 size);.
8930: 20 20 69 6e 74 20 28 2a 78 53 79 6e 63 29 28 73    int (*xSync)(s
8940: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e  qlite3_file*, in
8950: 74 20 66 6c 61 67 73 29 3b 0a 20 20 69 6e 74 20  t flags);.  int 
8960: 28 2a 78 46 69 6c 65 53 69 7a 65 29 28 73 71 6c  (*xFileSize)(sql
8970: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69  ite3_file*, sqli
8980: 74 65 33 5f 69 6e 74 36 34 20 2a 70 53 69 7a 65  te3_int64 *pSize
8990: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4c 6f 63 6b  );.  int (*xLock
89a0: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
89b0: 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78   int);.  int (*x
89c0: 55 6e 6c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f  Unlock)(sqlite3_
89d0: 66 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20 20 69  file*, int);.  i
89e0: 6e 74 20 28 2a 78 43 68 65 63 6b 52 65 73 65 72  nt (*xCheckReser
89f0: 76 65 64 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33  vedLock)(sqlite3
8a00: 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 2a 70 52 65  _file*, int *pRe
8a10: 73 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78  sOut);.  int (*x
8a20: 46 69 6c 65 43 6f 6e 74 72 6f 6c 29 28 73 71 6c  FileControl)(sql
8a30: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20  ite3_file*, int 
8a40: 6f 70 2c 20 76 6f 69 64 20 2a 70 41 72 67 29 3b  op, void *pArg);
8a50: 0a 20 20 69 6e 74 20 28 2a 78 53 65 63 74 6f 72  .  int (*xSector
8a60: 53 69 7a 65 29 28 73 71 6c 69 74 65 33 5f 66 69  Size)(sqlite3_fi
8a70: 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44  le*);.  int (*xD
8a80: 65 76 69 63 65 43 68 61 72 61 63 74 65 72 69 73  eviceCharacteris
8a90: 74 69 63 73 29 28 73 71 6c 69 74 65 33 5f 66 69  tics)(sqlite3_fi
8aa0: 6c 65 2a 29 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f  le*);.  /* Metho
8ab0: 64 73 20 61 62 6f 76 65 20 61 72 65 20 76 61 6c  ds above are val
8ac0: 69 64 20 66 6f 72 20 76 65 72 73 69 6f 6e 20 31  id for version 1
8ad0: 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 53 68 6d   */.  int (*xShm
8ae0: 4d 61 70 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  Map)(sqlite3_fil
8af0: 65 2a 2c 20 69 6e 74 20 69 50 67 2c 20 69 6e 74  e*, int iPg, int
8b00: 20 70 67 73 7a 2c 20 69 6e 74 2c 20 76 6f 69 64   pgsz, int, void
8b10: 20 76 6f 6c 61 74 69 6c 65 2a 2a 29 3b 0a 20 20   volatile**);.  
8b20: 69 6e 74 20 28 2a 78 53 68 6d 4c 6f 63 6b 29 28  int (*xShmLock)(
8b30: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69  sqlite3_file*, i
8b40: 6e 74 20 6f 66 66 73 65 74 2c 20 69 6e 74 20 6e  nt offset, int n
8b50: 2c 20 69 6e 74 20 66 6c 61 67 73 29 3b 0a 20 20  , int flags);.  
8b60: 76 6f 69 64 20 28 2a 78 53 68 6d 42 61 72 72 69  void (*xShmBarri
8b70: 65 72 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  er)(sqlite3_file
8b80: 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 68 6d  *);.  int (*xShm
8b90: 55 6e 6d 61 70 29 28 73 71 6c 69 74 65 33 5f 66  Unmap)(sqlite3_f
8ba0: 69 6c 65 2a 2c 20 69 6e 74 20 64 65 6c 65 74 65  ile*, int delete
8bb0: 46 6c 61 67 29 3b 0a 20 20 2f 2a 20 4d 65 74 68  Flag);.  /* Meth
8bc0: 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 76 61  ods above are va
8bd0: 6c 69 64 20 66 6f 72 20 76 65 72 73 69 6f 6e 20  lid for version 
8be0: 32 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 46 65  2 */.  int (*xFe
8bf0: 74 63 68 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  tch)(sqlite3_fil
8c00: 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  e*, sqlite3_int6
8c10: 34 20 69 4f 66 73 74 2c 20 69 6e 74 20 69 41 6d  4 iOfst, int iAm
8c20: 74 2c 20 76 6f 69 64 20 2a 2a 70 70 29 3b 0a 20  t, void **pp);. 
8c30: 20 69 6e 74 20 28 2a 78 55 6e 66 65 74 63 68 29   int (*xUnfetch)
8c40: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
8c50: 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f  sqlite3_int64 iO
8c60: 66 73 74 2c 20 76 6f 69 64 20 2a 70 29 3b 0a 20  fst, void *p);. 
8c70: 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61 62 6f 76   /* Methods abov
8c80: 65 20 61 72 65 20 76 61 6c 69 64 20 66 6f 72 20  e are valid for 
8c90: 76 65 72 73 69 6f 6e 20 33 20 2a 2f 0a 20 20 2f  version 3 */.  /
8ca0: 2a 20 41 64 64 69 74 69 6f 6e 61 6c 20 6d 65 74  * Additional met
8cb0: 68 6f 64 73 20 6d 61 79 20 62 65 20 61 64 64 65  hods may be adde
8cc0: 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65  d in future rele
8cd0: 61 73 65 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a  ases */.};../*.*
8ce0: 2a 20 43 41 50 49 33 52 45 46 3a 20 53 74 61 6e  * CAPI3REF: Stan
8cf0: 64 61 72 64 20 46 69 6c 65 20 43 6f 6e 74 72 6f  dard File Contro
8d00: 6c 20 4f 70 63 6f 64 65 73 0a 2a 2a 20 4b 45 59  l Opcodes.** KEY
8d10: 57 4f 52 44 53 3a 20 7b 66 69 6c 65 20 63 6f 6e  WORDS: {file con
8d20: 74 72 6f 6c 20 6f 70 63 6f 64 65 73 7d 20 7b 66  trol opcodes} {f
8d30: 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f 70 63 6f  ile control opco
8d40: 64 65 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  de}.**.** These 
8d50: 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74  integer constant
8d60: 73 20 61 72 65 20 6f 70 63 6f 64 65 73 20 66 6f  s are opcodes fo
8d70: 72 20 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 72  r the xFileContr
8d80: 6f 6c 20 6d 65 74 68 6f 64 0a 2a 2a 20 6f 66 20  ol method.** of 
8d90: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f  the [sqlite3_io_
8da0: 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20  methods] object 
8db0: 61 6e 64 20 66 6f 72 20 74 68 65 20 5b 73 71 6c  and for the [sql
8dc0: 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f  ite3_file_contro
8dd0: 6c 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63  l()].** interfac
8de0: 65 2e 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  e..**.** <ul>.**
8df0: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
8e00: 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 5d 5d 0a  NTL_LOCKSTATE]].
8e10: 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  ** The [SQLITE_F
8e20: 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 5d 20  CNTL_LOCKSTATE] 
8e30: 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 66  opcode is used f
8e40: 6f 72 20 64 65 62 75 67 67 69 6e 67 2e 20 20 54  or debugging.  T
8e50: 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 20 63 61  his.** opcode ca
8e60: 75 73 65 73 20 74 68 65 20 78 46 69 6c 65 43 6f  uses the xFileCo
8e70: 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 74 6f 20  ntrol method to 
8e80: 77 72 69 74 65 20 74 68 65 20 63 75 72 72 65 6e  write the curren
8e90: 74 20 73 74 61 74 65 20 6f 66 0a 2a 2a 20 74 68  t state of.** th
8ea0: 65 20 6c 6f 63 6b 20 28 6f 6e 65 20 6f 66 20 5b  e lock (one of [
8eb0: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45  SQLITE_LOCK_NONE
8ec0: 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  ], [SQLITE_LOCK_
8ed0: 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 5b 53 51 4c  SHARED],.** [SQL
8ee0: 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45  ITE_LOCK_RESERVE
8ef0: 44 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b  D], [SQLITE_LOCK
8f00: 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f 72 20 5b 53  _PENDING], or [S
8f10: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55  QLITE_LOCK_EXCLU
8f20: 53 49 56 45 5d 29 0a 2a 2a 20 69 6e 74 6f 20 61  SIVE]).** into a
8f30: 6e 20 69 6e 74 65 67 65 72 20 74 68 61 74 20 74  n integer that t
8f40: 68 65 20 70 41 72 67 20 61 72 67 75 6d 65 6e 74  he pArg argument
8f50: 20 70 6f 69 6e 74 73 20 74 6f 2e 20 54 68 69 73   points to. This
8f60: 20 63 61 70 61 62 69 6c 69 74 79 0a 2a 2a 20 69   capability.** i
8f70: 73 20 75 73 65 64 20 64 75 72 69 6e 67 20 74 65  s used during te
8f80: 73 74 69 6e 67 20 61 6e 64 20 69 73 20 6f 6e 6c  sting and is onl
8f90: 79 20 61 76 61 69 6c 61 62 6c 65 20 77 68 65 6e  y available when
8fa0: 20 74 68 65 20 53 51 4c 49 54 45 5f 54 45 53 54   the SQLITE_TEST
8fb0: 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  .** compile-time
8fc0: 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64 2e   option is used.
8fd0: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
8fe0: 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f 48  ITE_FCNTL_SIZE_H
8ff0: 49 4e 54 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51  INT]].** The [SQ
9000: 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f  LITE_FCNTL_SIZE_
9010: 48 49 4e 54 5d 20 6f 70 63 6f 64 65 20 69 73 20  HINT] opcode is 
9020: 75 73 65 64 20 62 79 20 53 51 4c 69 74 65 20 74  used by SQLite t
9030: 6f 20 67 69 76 65 20 74 68 65 20 56 46 53 0a 2a  o give the VFS.*
9040: 2a 20 6c 61 79 65 72 20 61 20 68 69 6e 74 20 6f  * layer a hint o
9050: 66 20 68 6f 77 20 6c 61 72 67 65 20 74 68 65 20  f how large the 
9060: 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 77 69  database file wi
9070: 6c 6c 20 67 72 6f 77 20 74 6f 20 62 65 20 64 75  ll grow to be du
9080: 72 69 6e 67 20 74 68 65 0a 2a 2a 20 63 75 72 72  ring the.** curr
9090: 65 6e 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 2e  ent transaction.
90a0: 20 20 54 68 69 73 20 68 69 6e 74 20 69 73 20 6e    This hint is n
90b0: 6f 74 20 67 75 61 72 61 6e 74 65 65 64 20 74 6f  ot guaranteed to
90c0: 20 62 65 20 61 63 63 75 72 61 74 65 20 62 75 74   be accurate but
90d0: 20 69 74 0a 2a 2a 20 69 73 20 6f 66 74 65 6e 20   it.** is often 
90e0: 63 6c 6f 73 65 2e 20 20 54 68 65 20 75 6e 64 65  close.  The unde
90f0: 72 6c 79 69 6e 67 20 56 46 53 20 6d 69 67 68 74  rlying VFS might
9100: 20 63 68 6f 6f 73 65 20 74 6f 20 70 72 65 61 6c   choose to preal
9110: 6c 6f 63 61 74 65 20 64 61 74 61 62 61 73 65 0a  locate database.
9120: 2a 2a 20 66 69 6c 65 20 73 70 61 63 65 20 62 61  ** file space ba
9130: 73 65 64 20 6f 6e 20 74 68 69 73 20 68 69 6e 74  sed on this hint
9140: 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 68 65 6c   in order to hel
9150: 70 20 77 72 69 74 65 73 20 74 6f 20 74 68 65 20  p writes to the 
9160: 64 61 74 61 62 61 73 65 0a 2a 2a 20 66 69 6c 65  database.** file
9170: 20 72 75 6e 20 66 61 73 74 65 72 2e 0a 2a 2a 0a   run faster..**.
9180: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
9190: 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45  FCNTL_CHUNK_SIZE
91a0: 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54  ]].** The [SQLIT
91b0: 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49  E_FCNTL_CHUNK_SI
91c0: 5a 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73  ZE] opcode is us
91d0: 65 64 20 74 6f 20 72 65 71 75 65 73 74 20 74 68  ed to request th
91e0: 61 74 20 74 68 65 20 56 46 53 0a 2a 2a 20 65 78  at the VFS.** ex
91f0: 74 65 6e 64 73 20 61 6e 64 20 74 72 75 6e 63 61  tends and trunca
9200: 74 65 73 20 74 68 65 20 64 61 74 61 62 61 73 65  tes the database
9210: 20 66 69 6c 65 20 69 6e 20 63 68 75 6e 6b 73 20   file in chunks 
9220: 6f 66 20 61 20 73 69 7a 65 20 73 70 65 63 69 66  of a size specif
9230: 69 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 75 73  ied.** by the us
9240: 65 72 2e 20 54 68 65 20 66 6f 75 72 74 68 20 61  er. The fourth a
9250: 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69  rgument to [sqli
9260: 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c  te3_file_control
9270: 28 29 5d 20 73 68 6f 75 6c 64 20 0a 2a 2a 20 70  ()] should .** p
9280: 6f 69 6e 74 20 74 6f 20 61 6e 20 69 6e 74 65 67  oint to an integ
9290: 65 72 20 28 74 79 70 65 20 69 6e 74 29 20 63 6f  er (type int) co
92a0: 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 6e 65 77  ntaining the new
92b0: 20 63 68 75 6e 6b 2d 73 69 7a 65 20 74 6f 20 75   chunk-size to u
92c0: 73 65 0a 2a 2a 20 66 6f 72 20 74 68 65 20 6e 6f  se.** for the no
92d0: 6d 69 6e 61 74 65 64 20 64 61 74 61 62 61 73 65  minated database
92e0: 2e 20 41 6c 6c 6f 63 61 74 69 6e 67 20 64 61 74  . Allocating dat
92f0: 61 62 61 73 65 20 66 69 6c 65 20 73 70 61 63 65  abase file space
9300: 20 69 6e 20 6c 61 72 67 65 0a 2a 2a 20 63 68 75   in large.** chu
9310: 6e 6b 73 20 28 73 61 79 20 31 4d 42 20 61 74 20  nks (say 1MB at 
9320: 61 20 74 69 6d 65 29 2c 20 6d 61 79 20 72 65 64  a time), may red
9330: 75 63 65 20 66 69 6c 65 2d 73 79 73 74 65 6d 20  uce file-system 
9340: 66 72 61 67 6d 65 6e 74 61 74 69 6f 6e 20 61 6e  fragmentation an
9350: 64 0a 2a 2a 20 69 6d 70 72 6f 76 65 20 70 65 72  d.** improve per
9360: 66 6f 72 6d 61 6e 63 65 20 6f 6e 20 73 6f 6d 65  formance on some
9370: 20 73 79 73 74 65 6d 73 2e 0a 2a 2a 0a 2a 2a 20   systems..**.** 
9380: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e  <li>[[SQLITE_FCN
9390: 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52 5d  TL_FILE_POINTER]
93a0: 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45  ].** The [SQLITE
93b0: 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e  _FCNTL_FILE_POIN
93c0: 54 45 52 5d 20 6f 70 63 6f 64 65 20 69 73 20 75  TER] opcode is u
93d0: 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 20 61 20  sed to obtain a 
93e0: 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68  pointer.** to th
93f0: 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d  e [sqlite3_file]
9400: 20 6f 62 6a 65 63 74 20 61 73 73 6f 63 69 61 74   object associat
9410: 65 64 20 77 69 74 68 20 61 20 70 61 72 74 69 63  ed with a partic
9420: 75 6c 61 72 20 64 61 74 61 62 61 73 65 0a 2a 2a  ular database.**
9430: 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 53 65   connection.  Se
9440: 65 20 61 6c 73 6f 20 5b 53 51 4c 49 54 45 5f 46  e also [SQLITE_F
9450: 43 4e 54 4c 5f 4a 4f 55 52 4e 41 4c 5f 50 4f 49  CNTL_JOURNAL_POI
9460: 4e 54 45 52 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69  NTER]..**.** <li
9470: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
9480: 4a 4f 55 52 4e 41 4c 5f 50 4f 49 4e 54 45 52 5d  JOURNAL_POINTER]
9490: 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45  ].** The [SQLITE
94a0: 5f 46 43 4e 54 4c 5f 4a 4f 55 52 4e 41 4c 5f 50  _FCNTL_JOURNAL_P
94b0: 4f 49 4e 54 45 52 5d 20 6f 70 63 6f 64 65 20 69  OINTER] opcode i
94c0: 73 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e  s used to obtain
94d0: 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f   a pointer.** to
94e0: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69   the [sqlite3_fi
94f0: 6c 65 5d 20 6f 62 6a 65 63 74 20 61 73 73 6f 63  le] object assoc
9500: 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20 6a  iated with the j
9510: 6f 75 72 6e 61 6c 20 66 69 6c 65 20 28 65 69 74  ournal file (eit
9520: 68 65 72 0a 2a 2a 20 74 68 65 20 5b 72 6f 6c 6c  her.** the [roll
9530: 62 61 63 6b 20 6a 6f 75 72 6e 61 6c 5d 20 6f 72  back journal] or
9540: 20 74 68 65 20 5b 77 72 69 74 65 2d 61 68 65 61   the [write-ahea
9550: 64 20 6c 6f 67 5d 29 20 66 6f 72 20 61 20 70 61  d log]) for a pa
9560: 72 74 69 63 75 6c 61 72 20 64 61 74 61 62 61 73  rticular databas
9570: 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e  e.** connection.
9580: 20 20 53 65 65 20 61 6c 73 6f 20 5b 53 51 4c 49    See also [SQLI
9590: 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f  TE_FCNTL_FILE_PO
95a0: 49 4e 54 45 52 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  INTER]..**.** <l
95b0: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
95c0: 5f 53 59 4e 43 5f 4f 4d 49 54 54 45 44 5d 5d 0a  _SYNC_OMITTED]].
95d0: 2a 2a 20 4e 6f 20 6c 6f 6e 67 65 72 20 69 6e 20  ** No longer in 
95e0: 75 73 65 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  use..**.** <li>[
95f0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59  [SQLITE_FCNTL_SY
9600: 4e 43 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  NC]].** The [SQL
9610: 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5d 20  ITE_FCNTL_SYNC] 
9620: 6f 70 63 6f 64 65 20 69 73 20 67 65 6e 65 72 61  opcode is genera
9630: 74 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 62  ted internally b
9640: 79 20 53 51 4c 69 74 65 20 61 6e 64 0a 2a 2a 20  y SQLite and.** 
9650: 73 65 6e 74 20 74 6f 20 74 68 65 20 56 46 53 20  sent to the VFS 
9660: 69 6d 6d 65 64 69 61 74 65 6c 79 20 62 65 66 6f  immediately befo
9670: 72 65 20 74 68 65 20 78 53 79 6e 63 20 6d 65 74  re the xSync met
9680: 68 6f 64 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f  hod is invoked o
9690: 6e 20 61 0a 2a 2a 20 64 61 74 61 62 61 73 65 20  n a.** database 
96a0: 66 69 6c 65 20 64 65 73 63 72 69 70 74 6f 72 2e  file descriptor.
96b0: 20 4f 72 2c 20 69 66 20 74 68 65 20 78 53 79 6e   Or, if the xSyn
96c0: 63 20 6d 65 74 68 6f 64 20 69 73 20 6e 6f 74 20  c method is not 
96d0: 69 6e 76 6f 6b 65 64 20 0a 2a 2a 20 62 65 63 61  invoked .** beca
96e0: 75 73 65 20 74 68 65 20 75 73 65 72 20 68 61 73  use the user has
96f0: 20 63 6f 6e 66 69 67 75 72 65 64 20 53 51 4c 69   configured SQLi
9700: 74 65 20 77 69 74 68 20 0a 2a 2a 20 5b 50 52 41  te with .** [PRA
9710: 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 20  GMA synchronous 
9720: 7c 20 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f  | PRAGMA synchro
9730: 6e 6f 75 73 3d 4f 46 46 5d 20 69 74 20 69 73 20  nous=OFF] it is 
9740: 69 6e 76 6f 6b 65 64 20 69 6e 20 70 6c 61 63 65  invoked in place
9750: 20 0a 2a 2a 20 6f 66 20 74 68 65 20 78 53 79 6e   .** of the xSyn
9760: 63 20 6d 65 74 68 6f 64 2e 20 49 6e 20 6d 6f 73  c method. In mos
9770: 74 20 63 61 73 65 73 2c 20 74 68 65 20 70 6f 69  t cases, the poi
9780: 6e 74 65 72 20 61 72 67 75 6d 65 6e 74 20 70 61  nter argument pa
9790: 73 73 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 69  ssed with.** thi
97a0: 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 69  s file-control i
97b0: 73 20 4e 55 4c 4c 2e 20 48 6f 77 65 76 65 72 2c  s NULL. However,
97c0: 20 69 66 20 74 68 65 20 64 61 74 61 62 61 73 65   if the database
97d0: 20 66 69 6c 65 20 69 73 20 62 65 69 6e 67 20 73   file is being s
97e0: 79 6e 63 65 64 0a 2a 2a 20 61 73 20 70 61 72 74  ynced.** as part
97f0: 20 6f 66 20 61 20 6d 75 6c 74 69 2d 64 61 74 61   of a multi-data
9800: 62 61 73 65 20 63 6f 6d 6d 69 74 2c 20 74 68 65  base commit, the
9810: 20 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e 74 73   argument points
9820: 20 74 6f 20 61 20 6e 75 6c 2d 74 65 72 6d 69 6e   to a nul-termin
9830: 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20 63  ated.** string c
9840: 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 74 72  ontaining the tr
9850: 61 6e 73 61 63 74 69 6f 6e 73 20 6d 61 73 74 65  ansactions maste
9860: 72 2d 6a 6f 75 72 6e 61 6c 20 66 69 6c 65 20 6e  r-journal file n
9870: 61 6d 65 2e 20 56 46 53 65 73 20 74 68 61 74 20  ame. VFSes that 
9880: 0a 2a 2a 20 64 6f 20 6e 6f 74 20 6e 65 65 64 20  .** do not need 
9890: 74 68 69 73 20 73 69 67 6e 61 6c 20 73 68 6f 75  this signal shou
98a0: 6c 64 20 73 69 6c 65 6e 74 6c 79 20 69 67 6e 6f  ld silently igno
98b0: 72 65 20 74 68 69 73 20 6f 70 63 6f 64 65 2e 20  re this opcode. 
98c0: 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 0a 2a 2a  Applications .**
98d0: 20 73 68 6f 75 6c 64 20 6e 6f 74 20 63 61 6c 6c   should not call
98e0: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63   [sqlite3_file_c
98f0: 6f 6e 74 72 6f 6c 28 29 5d 20 77 69 74 68 20 74  ontrol()] with t
9900: 68 69 73 20 6f 70 63 6f 64 65 20 61 73 20 64 6f  his opcode as do
9910: 69 6e 67 20 73 6f 20 6d 61 79 20 0a 2a 2a 20 64  ing so may .** d
9920: 69 73 72 75 70 74 20 74 68 65 20 6f 70 65 72 61  isrupt the opera
9930: 74 69 6f 6e 20 6f 66 20 74 68 65 20 73 70 65 63  tion of the spec
9940: 69 61 6c 69 7a 65 64 20 56 46 53 65 73 20 74 68  ialized VFSes th
9950: 61 74 20 64 6f 20 72 65 71 75 69 72 65 20 69 74  at do require it
9960: 2e 20 20 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  .  .**.** <li>[[
9970: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d  SQLITE_FCNTL_COM
9980: 4d 49 54 5f 50 48 41 53 45 54 57 4f 5d 5d 0a 2a  MIT_PHASETWO]].*
9990: 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43  * The [SQLITE_FC
99a0: 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 50 48 41 53 45  NTL_COMMIT_PHASE
99b0: 54 57 4f 5d 20 6f 70 63 6f 64 65 20 69 73 20 67  TWO] opcode is g
99c0: 65 6e 65 72 61 74 65 64 20 69 6e 74 65 72 6e 61  enerated interna
99d0: 6c 6c 79 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a  lly by SQLite.**
99e0: 20 61 6e 64 20 73 65 6e 74 20 74 6f 20 74 68 65   and sent to the
99f0: 20 56 46 53 20 61 66 74 65 72 20 61 20 74 72 61   VFS after a tra
9a00: 6e 73 61 63 74 69 6f 6e 20 68 61 73 20 62 65 65  nsaction has bee
9a10: 6e 20 63 6f 6d 6d 69 74 74 65 64 20 69 6d 6d 65  n committed imme
9a20: 64 69 61 74 65 6c 79 0a 2a 2a 20 62 75 74 20 62  diately.** but b
9a30: 65 66 6f 72 65 20 74 68 65 20 64 61 74 61 62 61  efore the databa
9a40: 73 65 20 69 73 20 75 6e 6c 6f 63 6b 65 64 2e 20  se is unlocked. 
9a50: 56 46 53 65 73 20 74 68 61 74 20 64 6f 20 6e 6f  VFSes that do no
9a60: 74 20 6e 65 65 64 20 74 68 69 73 20 73 69 67 6e  t need this sign
9a70: 61 6c 0a 2a 2a 20 73 68 6f 75 6c 64 20 73 69 6c  al.** should sil
9a80: 65 6e 74 6c 79 20 69 67 6e 6f 72 65 20 74 68 69  ently ignore thi
9a90: 73 20 6f 70 63 6f 64 65 2e 20 41 70 70 6c 69 63  s opcode. Applic
9aa0: 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 6e 6f  ations should no
9ab0: 74 20 63 61 6c 6c 0a 2a 2a 20 5b 73 71 6c 69 74  t call.** [sqlit
9ac0: 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28  e3_file_control(
9ad0: 29 5d 20 77 69 74 68 20 74 68 69 73 20 6f 70 63  )] with this opc
9ae0: 6f 64 65 20 61 73 20 64 6f 69 6e 67 20 73 6f 20  ode as doing so 
9af0: 6d 61 79 20 64 69 73 72 75 70 74 20 74 68 65 20  may disrupt the 
9b00: 0a 2a 2a 20 6f 70 65 72 61 74 69 6f 6e 20 6f 66  .** operation of
9b10: 20 74 68 65 20 73 70 65 63 69 61 6c 69 7a 65 64   the specialized
9b20: 20 56 46 53 65 73 20 74 68 61 74 20 64 6f 20 72   VFSes that do r
9b30: 65 71 75 69 72 65 20 69 74 2e 20 20 0a 2a 2a 0a  equire it.  .**.
9b40: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
9b50: 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 41 56 5f 52  FCNTL_WIN32_AV_R
9b60: 45 54 52 59 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b  ETRY]].** ^The [
9b70: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e  SQLITE_FCNTL_WIN
9b80: 33 32 5f 41 56 5f 52 45 54 52 59 5d 20 6f 70 63  32_AV_RETRY] opc
9b90: 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f 20 63  ode is used to c
9ba0: 6f 6e 66 69 67 75 72 65 20 61 75 74 6f 6d 61 74  onfigure automat
9bb0: 69 63 0a 2a 2a 20 72 65 74 72 79 20 63 6f 75 6e  ic.** retry coun
9bc0: 74 73 20 61 6e 64 20 69 6e 74 65 72 76 61 6c 73  ts and intervals
9bd0: 20 66 6f 72 20 63 65 72 74 61 69 6e 20 64 69 73   for certain dis
9be0: 6b 20 49 2f 4f 20 6f 70 65 72 61 74 69 6f 6e 73  k I/O operations
9bf0: 20 66 6f 72 20 74 68 65 0a 2a 2a 20 77 69 6e 64   for the.** wind
9c00: 6f 77 73 20 5b 56 46 53 5d 20 69 6e 20 6f 72 64  ows [VFS] in ord
9c10: 65 72 20 74 6f 20 70 72 6f 76 69 64 65 20 72 6f  er to provide ro
9c20: 62 75 73 74 6e 65 73 73 20 69 6e 20 74 68 65 20  bustness in the 
9c30: 70 72 65 73 65 6e 63 65 20 6f 66 0a 2a 2a 20 61  presence of.** a
9c40: 6e 74 69 2d 76 69 72 75 73 20 70 72 6f 67 72 61  nti-virus progra
9c50: 6d 73 2e 20 20 42 79 20 64 65 66 61 75 6c 74 2c  ms.  By default,
9c60: 20 74 68 65 20 77 69 6e 64 6f 77 73 20 56 46 53   the windows VFS
9c70: 20 77 69 6c 6c 20 72 65 74 72 79 20 66 69 6c 65   will retry file
9c80: 20 72 65 61 64 2c 0a 2a 2a 20 66 69 6c 65 20 77   read,.** file w
9c90: 72 69 74 65 2c 20 61 6e 64 20 66 69 6c 65 20 64  rite, and file d
9ca0: 65 6c 65 74 65 20 6f 70 65 72 61 74 69 6f 6e 73  elete operations
9cb0: 20 75 70 20 74 6f 20 31 30 20 74 69 6d 65 73 2c   up to 10 times,
9cc0: 20 77 69 74 68 20 61 20 64 65 6c 61 79 0a 2a 2a   with a delay.**
9cd0: 20 6f 66 20 32 35 20 6d 69 6c 6c 69 73 65 63 6f   of 25 milliseco
9ce0: 6e 64 73 20 62 65 66 6f 72 65 20 74 68 65 20 66  nds before the f
9cf0: 69 72 73 74 20 72 65 74 72 79 20 61 6e 64 20 77  irst retry and w
9d00: 69 74 68 20 74 68 65 20 64 65 6c 61 79 20 69 6e  ith the delay in
9d10: 63 72 65 61 73 69 6e 67 0a 2a 2a 20 62 79 20 61  creasing.** by a
9d20: 6e 20 61 64 64 69 74 69 6f 6e 61 6c 20 32 35 20  n additional 25 
9d30: 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 77 69 74  milliseconds wit
9d40: 68 20 65 61 63 68 20 73 75 62 73 65 71 75 65 6e  h each subsequen
9d50: 74 20 72 65 74 72 79 2e 20 20 54 68 69 73 0a 2a  t retry.  This.*
9d60: 2a 20 6f 70 63 6f 64 65 20 61 6c 6c 6f 77 73 20  * opcode allows 
9d70: 74 68 65 73 65 20 74 77 6f 20 76 61 6c 75 65 73  these two values
9d80: 20 28 31 30 20 72 65 74 72 69 65 73 20 61 6e 64   (10 retries and
9d90: 20 32 35 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73   25 milliseconds
9da0: 20 6f 66 20 64 65 6c 61 79 29 0a 2a 2a 20 74 6f   of delay).** to
9db0: 20 62 65 20 61 64 6a 75 73 74 65 64 2e 20 20 54   be adjusted.  T
9dc0: 68 65 20 76 61 6c 75 65 73 20 61 72 65 20 63 68  he values are ch
9dd0: 61 6e 67 65 64 20 66 6f 72 20 61 6c 6c 20 64 61  anged for all da
9de0: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
9df0: 6e 73 0a 2a 2a 20 77 69 74 68 69 6e 20 74 68 65  ns.** within the
9e00: 20 73 61 6d 65 20 70 72 6f 63 65 73 73 2e 20 20   same process.  
9e10: 54 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20  The argument is 
9e20: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  a pointer to an 
9e30: 61 72 72 61 79 20 6f 66 20 74 77 6f 0a 2a 2a 20  array of two.** 
9e40: 69 6e 74 65 67 65 72 73 20 77 68 65 72 65 20 74  integers where t
9e50: 68 65 20 66 69 72 73 74 20 69 6e 74 65 67 65 72  he first integer
9e60: 20 69 20 74 68 65 20 6e 65 77 20 72 65 74 72 79   i the new retry
9e70: 20 63 6f 75 6e 74 20 61 6e 64 20 74 68 65 20 73   count and the s
9e80: 65 63 6f 6e 64 0a 2a 2a 20 69 6e 74 65 67 65 72  econd.** integer
9e90: 20 69 73 20 74 68 65 20 64 65 6c 61 79 2e 20 20   is the delay.  
9ea0: 49 66 20 65 69 74 68 65 72 20 69 6e 74 65 67 65  If either intege
9eb0: 72 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74  r is negative, t
9ec0: 68 65 6e 20 74 68 65 20 73 65 74 74 69 6e 67 0a  hen the setting.
9ed0: 2a 2a 20 69 73 20 6e 6f 74 20 63 68 61 6e 67 65  ** is not change
9ee0: 64 20 62 75 74 20 69 6e 73 74 65 61 64 20 74 68  d but instead th
9ef0: 65 20 70 72 69 6f 72 20 76 61 6c 75 65 20 6f 66  e prior value of
9f00: 20 74 68 61 74 20 73 65 74 74 69 6e 67 20 69 73   that setting is
9f10: 20 77 72 69 74 74 65 6e 0a 2a 2a 20 69 6e 74 6f   written.** into
9f20: 20 74 68 65 20 61 72 72 61 79 20 65 6e 74 72 79   the array entry
9f30: 2c 20 61 6c 6c 6f 77 69 6e 67 20 74 68 65 20 63  , allowing the c
9f40: 75 72 72 65 6e 74 20 72 65 74 72 79 20 73 65 74  urrent retry set
9f50: 74 69 6e 67 73 20 74 6f 20 62 65 0a 2a 2a 20 69  tings to be.** i
9f60: 6e 74 65 72 72 6f 67 61 74 65 64 2e 20 20 54 68  nterrogated.  Th
9f70: 65 20 7a 44 62 4e 61 6d 65 20 70 61 72 61 6d 65  e zDbName parame
9f80: 74 65 72 20 69 73 20 69 67 6e 6f 72 65 64 2e 0a  ter is ignored..
9f90: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
9fa0: 54 45 5f 46 43 4e 54 4c 5f 50 45 52 53 49 53 54  TE_FCNTL_PERSIST
9fb0: 5f 57 41 4c 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b  _WAL]].** ^The [
9fc0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 45 52  SQLITE_FCNTL_PER
9fd0: 53 49 53 54 5f 57 41 4c 5d 20 6f 70 63 6f 64 65  SIST_WAL] opcode
9fe0: 20 69 73 20 75 73 65 64 20 74 6f 20 73 65 74 20   is used to set 
9ff0: 6f 72 20 71 75 65 72 79 20 74 68 65 0a 2a 2a 20  or query the.** 
a000: 70 65 72 73 69 73 74 65 6e 74 20 5b 57 41 4c 20  persistent [WAL 
a010: 7c 20 57 72 69 74 65 20 41 68 65 61 64 20 4c 6f  | Write Ahead Lo
a020: 67 5d 20 73 65 74 74 69 6e 67 2e 20 20 42 79 20  g] setting.  By 
a030: 64 65 66 61 75 6c 74 2c 20 74 68 65 20 61 75 78  default, the aux
a040: 69 6c 69 61 72 79 0a 2a 2a 20 77 72 69 74 65 20  iliary.** write 
a050: 61 68 65 61 64 20 6c 6f 67 20 61 6e 64 20 73 68  ahead log and sh
a060: 61 72 65 64 20 6d 65 6d 6f 72 79 20 66 69 6c 65  ared memory file
a070: 73 20 75 73 65 64 20 66 6f 72 20 74 72 61 6e 73  s used for trans
a080: 61 63 74 69 6f 6e 20 63 6f 6e 74 72 6f 6c 0a 2a  action control.*
a090: 2a 20 61 72 65 20 61 75 74 6f 6d 61 74 69 63 61  * are automatica
a0a0: 6c 6c 79 20 64 65 6c 65 74 65 64 20 77 68 65 6e  lly deleted when
a0b0: 20 74 68 65 20 6c 61 74 65 73 74 20 63 6f 6e 6e   the latest conn
a0c0: 65 63 74 69 6f 6e 20 74 6f 20 74 68 65 20 64 61  ection to the da
a0d0: 74 61 62 61 73 65 0a 2a 2a 20 63 6c 6f 73 65 73  tabase.** closes
a0e0: 2e 20 20 53 65 74 74 69 6e 67 20 70 65 72 73 69  .  Setting persi
a0f0: 73 74 65 6e 74 20 57 41 4c 20 6d 6f 64 65 20 63  stent WAL mode c
a100: 61 75 73 65 73 20 74 68 6f 73 65 20 66 69 6c 65  auses those file
a110: 73 20 74 6f 20 70 65 72 73 69 73 74 20 61 66 74  s to persist aft
a120: 65 72 0a 2a 2a 20 63 6c 6f 73 65 2e 20 20 50 65  er.** close.  Pe
a130: 72 73 69 73 74 69 6e 67 20 74 68 65 20 66 69 6c  rsisting the fil
a140: 65 73 20 69 73 20 75 73 65 66 75 6c 20 77 68 65  es is useful whe
a150: 6e 20 6f 74 68 65 72 20 70 72 6f 63 65 73 73 65  n other processe
a160: 73 20 74 68 61 74 20 64 6f 20 6e 6f 74 0a 2a 2a  s that do not.**
a170: 20 68 61 76 65 20 77 72 69 74 65 20 70 65 72 6d   have write perm
a180: 69 73 73 69 6f 6e 20 6f 6e 20 74 68 65 20 64 69  ission on the di
a190: 72 65 63 74 6f 72 79 20 63 6f 6e 74 61 69 6e 69  rectory containi
a1a0: 6e 67 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ng the database 
a1b0: 66 69 6c 65 20 77 61 6e 74 0a 2a 2a 20 74 6f 20  file want.** to 
a1c0: 72 65 61 64 20 74 68 65 20 64 61 74 61 62 61 73  read the databas
a1d0: 65 20 66 69 6c 65 2c 20 61 73 20 74 68 65 20 57  e file, as the W
a1e0: 41 4c 20 61 6e 64 20 73 68 61 72 65 64 20 6d 65  AL and shared me
a1f0: 6d 6f 72 79 20 66 69 6c 65 73 20 6d 75 73 74 20  mory files must 
a200: 65 78 69 73 74 0a 2a 2a 20 69 6e 20 6f 72 64 65  exist.** in orde
a210: 72 20 66 6f 72 20 74 68 65 20 64 61 74 61 62 61  r for the databa
a220: 73 65 20 74 6f 20 62 65 20 72 65 61 64 61 62 6c  se to be readabl
a230: 65 2e 20 20 54 68 65 20 66 6f 75 72 74 68 20 70  e.  The fourth p
a240: 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b  arameter to.** [
a250: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e  sqlite3_file_con
a260: 74 72 6f 6c 28 29 5d 20 66 6f 72 20 74 68 69 73  trol()] for this
a270: 20 6f 70 63 6f 64 65 20 73 68 6f 75 6c 64 20 62   opcode should b
a280: 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  e a pointer to a
a290: 6e 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 20 54 68  n integer..** Th
a2a0: 61 74 20 69 6e 74 65 67 65 72 20 69 73 20 30 20  at integer is 0 
a2b0: 74 6f 20 64 69 73 61 62 6c 65 20 70 65 72 73 69  to disable persi
a2c0: 73 74 65 6e 74 20 57 41 4c 20 6d 6f 64 65 20 6f  stent WAL mode o
a2d0: 72 20 31 20 74 6f 20 65 6e 61 62 6c 65 20 70 65  r 1 to enable pe
a2e0: 72 73 69 73 74 65 6e 74 0a 2a 2a 20 57 41 4c 20  rsistent.** WAL 
a2f0: 6d 6f 64 65 2e 20 20 49 66 20 74 68 65 20 69 6e  mode.  If the in
a300: 74 65 67 65 72 20 69 73 20 2d 31 2c 20 74 68 65  teger is -1, the
a310: 6e 20 69 74 20 69 73 20 6f 76 65 72 77 72 69 74  n it is overwrit
a320: 74 65 6e 20 77 69 74 68 20 74 68 65 20 63 75 72  ten with the cur
a330: 72 65 6e 74 0a 2a 2a 20 57 41 4c 20 70 65 72 73  rent.** WAL pers
a340: 69 73 74 65 6e 63 65 20 73 65 74 74 69 6e 67 2e  istence setting.
a350: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
a360: 49 54 45 5f 46 43 4e 54 4c 5f 50 4f 57 45 52 53  ITE_FCNTL_POWERS
a370: 41 46 45 5f 4f 56 45 52 57 52 49 54 45 5d 5d 0a  AFE_OVERWRITE]].
a380: 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f  ** ^The [SQLITE_
a390: 46 43 4e 54 4c 5f 50 4f 57 45 52 53 41 46 45 5f  FCNTL_POWERSAFE_
a3a0: 4f 56 45 52 57 52 49 54 45 5d 20 6f 70 63 6f 64  OVERWRITE] opcod
a3b0: 65 20 69 73 20 75 73 65 64 20 74 6f 20 73 65 74  e is used to set
a3c0: 20 6f 72 20 71 75 65 72 79 20 74 68 65 0a 2a 2a   or query the.**
a3d0: 20 70 65 72 73 69 73 74 65 6e 74 20 22 70 6f 77   persistent "pow
a3e0: 65 72 73 61 66 65 2d 6f 76 65 72 77 72 69 74 65  ersafe-overwrite
a3f0: 22 20 6f 72 20 22 50 53 4f 57 22 20 73 65 74 74  " or "PSOW" sett
a400: 69 6e 67 2e 20 20 54 68 65 20 50 53 4f 57 20 73  ing.  The PSOW s
a410: 65 74 74 69 6e 67 0a 2a 2a 20 64 65 74 65 72 6d  etting.** determ
a420: 69 6e 65 73 20 74 68 65 20 5b 53 51 4c 49 54 45  ines the [SQLITE
a430: 5f 49 4f 43 41 50 5f 50 4f 57 45 52 53 41 46 45  _IOCAP_POWERSAFE
a440: 5f 4f 56 45 52 57 52 49 54 45 5d 20 62 69 74 20  _OVERWRITE] bit 
a450: 6f 66 20 74 68 65 0a 2a 2a 20 78 44 65 76 69 63  of the.** xDevic
a460: 65 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73  eCharacteristics
a470: 20 6d 65 74 68 6f 64 73 2e 20 54 68 65 20 66 6f   methods. The fo
a480: 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74  urth parameter t
a490: 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69  o.** [sqlite3_fi
a4a0: 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 66 6f  le_control()] fo
a4b0: 72 20 74 68 69 73 20 6f 70 63 6f 64 65 20 73 68  r this opcode sh
a4c0: 6f 75 6c 64 20 62 65 20 61 20 70 6f 69 6e 74 65  ould be a pointe
a4d0: 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 2e  r to an integer.
a4e0: 0a 2a 2a 20 54 68 61 74 20 69 6e 74 65 67 65 72  .** That integer
a4f0: 20 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65   is 0 to disable
a500: 20 7a 65 72 6f 2d 64 61 6d 61 67 65 20 6d 6f 64   zero-damage mod
a510: 65 20 6f 72 20 31 20 74 6f 20 65 6e 61 62 6c 65  e or 1 to enable
a520: 20 7a 65 72 6f 2d 64 61 6d 61 67 65 0a 2a 2a 20   zero-damage.** 
a530: 6d 6f 64 65 2e 20 20 49 66 20 74 68 65 20 69 6e  mode.  If the in
a540: 74 65 67 65 72 20 69 73 20 2d 31 2c 20 74 68 65  teger is -1, the
a550: 6e 20 69 74 20 69 73 20 6f 76 65 72 77 72 69 74  n it is overwrit
a560: 74 65 6e 20 77 69 74 68 20 74 68 65 20 63 75 72  ten with the cur
a570: 72 65 6e 74 0a 2a 2a 20 7a 65 72 6f 2d 64 61 6d  rent.** zero-dam
a580: 61 67 65 20 6d 6f 64 65 20 73 65 74 74 69 6e 67  age mode setting
a590: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51  ..**.** <li>[[SQ
a5a0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 45 52 57  LITE_FCNTL_OVERW
a5b0: 52 49 54 45 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b  RITE]].** ^The [
a5c0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 45  SQLITE_FCNTL_OVE
a5d0: 52 57 52 49 54 45 5d 20 6f 70 63 6f 64 65 20 69  RWRITE] opcode i
a5e0: 73 20 69 6e 76 6f 6b 65 64 20 62 79 20 53 51 4c  s invoked by SQL
a5f0: 69 74 65 20 61 66 74 65 72 20 6f 70 65 6e 69 6e  ite after openin
a600: 67 0a 2a 2a 20 61 20 77 72 69 74 65 20 74 72 61  g.** a write tra
a610: 6e 73 61 63 74 69 6f 6e 20 74 6f 20 69 6e 64 69  nsaction to indi
a620: 63 61 74 65 20 74 68 61 74 2c 20 75 6e 6c 65 73  cate that, unles
a630: 73 20 69 74 20 69 73 20 72 6f 6c 6c 65 64 20 62  s it is rolled b
a640: 61 63 6b 20 66 6f 72 20 73 6f 6d 65 0a 2a 2a 20  ack for some.** 
a650: 72 65 61 73 6f 6e 2c 20 74 68 65 20 65 6e 74 69  reason, the enti
a660: 72 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  re database file
a670: 20 77 69 6c 6c 20 62 65 20 6f 76 65 72 77 72 69   will be overwri
a680: 74 74 65 6e 20 62 79 20 74 68 65 20 63 75 72 72  tten by the curr
a690: 65 6e 74 20 0a 2a 2a 20 74 72 61 6e 73 61 63 74  ent .** transact
a6a0: 69 6f 6e 2e 20 54 68 69 73 20 69 73 20 75 73 65  ion. This is use
a6b0: 64 20 62 79 20 56 41 43 55 55 4d 20 6f 70 65 72  d by VACUUM oper
a6c0: 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  ations..**.** <l
a6d0: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
a6e0: 5f 56 46 53 4e 41 4d 45 5d 5d 0a 2a 2a 20 5e 54  _VFSNAME]].** ^T
a6f0: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
a700: 5f 56 46 53 4e 41 4d 45 5d 20 6f 70 63 6f 64 65  _VFSNAME] opcode
a710: 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
a720: 6f 62 74 61 69 6e 20 74 68 65 20 6e 61 6d 65 73  obtain the names
a730: 20 6f 66 0a 2a 2a 20 61 6c 6c 20 5b 56 46 53 65   of.** all [VFSe
a740: 73 5d 20 69 6e 20 74 68 65 20 56 46 53 20 73 74  s] in the VFS st
a750: 61 63 6b 2e 20 20 54 68 65 20 6e 61 6d 65 73 20  ack.  The names 
a760: 61 72 65 20 6f 66 20 61 6c 6c 20 56 46 53 20 73  are of all VFS s
a770: 68 69 6d 73 20 61 6e 64 20 74 68 65 0a 2a 2a 20  hims and the.** 
a780: 66 69 6e 61 6c 20 62 6f 74 74 6f 6d 2d 6c 65 76  final bottom-lev
a790: 65 6c 20 56 46 53 20 61 72 65 20 77 72 69 74 74  el VFS are writt
a7a0: 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f  en into memory o
a7b0: 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 0a 2a 2a  btained from .**
a7c0: 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
a7d0: 28 29 5d 20 61 6e 64 20 74 68 65 20 72 65 73 75  ()] and the resu
a7e0: 6c 74 20 69 73 20 73 74 6f 72 65 64 20 69 6e 20  lt is stored in 
a7f0: 74 68 65 20 63 68 61 72 2a 20 76 61 72 69 61 62  the char* variab
a800: 6c 65 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 66  le.** that the f
a810: 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
a820: 6f 66 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  of [sqlite3_file
a830: 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 70 6f 69 6e  _control()] poin
a840: 74 73 20 74 6f 2e 0a 2a 2a 20 54 68 65 20 63 61  ts to..** The ca
a850: 6c 6c 65 72 20 69 73 20 72 65 73 70 6f 6e 73 69  ller is responsi
a860: 62 6c 65 20 66 6f 72 20 66 72 65 65 69 6e 67 20  ble for freeing 
a870: 74 68 65 20 6d 65 6d 6f 72 79 20 77 68 65 6e 20  the memory when 
a880: 64 6f 6e 65 2e 20 20 41 73 20 77 69 74 68 0a 2a  done.  As with.*
a890: 2a 20 61 6c 6c 20 66 69 6c 65 2d 63 6f 6e 74 72  * all file-contr
a8a0: 6f 6c 20 61 63 74 69 6f 6e 73 2c 20 74 68 65 72  ol actions, ther
a8b0: 65 20 69 73 20 6e 6f 20 67 75 61 72 61 6e 74 65  e is no guarante
a8c0: 65 20 74 68 61 74 20 74 68 69 73 20 77 69 6c 6c  e that this will
a8d0: 20 61 63 74 75 61 6c 6c 79 0a 2a 2a 20 64 6f 20   actually.** do 
a8e0: 61 6e 79 74 68 69 6e 67 2e 20 20 43 61 6c 6c 65  anything.  Calle
a8f0: 72 73 20 73 68 6f 75 6c 64 20 69 6e 69 74 69 61  rs should initia
a900: 6c 69 7a 65 20 74 68 65 20 63 68 61 72 2a 20 76  lize the char* v
a910: 61 72 69 61 62 6c 65 20 74 6f 20 61 20 4e 55 4c  ariable to a NUL
a920: 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 69 6e 20  L.** pointer in 
a930: 63 61 73 65 20 74 68 69 73 20 66 69 6c 65 2d 63  case this file-c
a940: 6f 6e 74 72 6f 6c 20 69 73 20 6e 6f 74 20 69 6d  ontrol is not im
a950: 70 6c 65 6d 65 6e 74 65 64 2e 20 20 54 68 69 73  plemented.  This
a960: 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 0a 2a 2a   file-control.**
a970: 20 69 73 20 69 6e 74 65 6e 64 65 64 20 66 6f 72   is intended for
a980: 20 64 69 61 67 6e 6f 73 74 69 63 20 75 73 65 20   diagnostic use 
a990: 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  only..**.** <li>
a9a0: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56  [[SQLITE_FCNTL_V
a9b0: 46 53 5f 50 4f 49 4e 54 45 52 5d 5d 0a 2a 2a 20  FS_POINTER]].** 
a9c0: 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e  ^The [SQLITE_FCN
a9d0: 54 4c 5f 56 46 53 5f 50 4f 49 4e 54 45 52 5d 20  TL_VFS_POINTER] 
a9e0: 6f 70 63 6f 64 65 20 66 69 6e 64 73 20 61 20 70  opcode finds a p
a9f0: 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 74 6f  ointer to the to
aa00: 70 2d 6c 65 76 65 6c 0a 2a 2a 20 5b 56 46 53 65  p-level.** [VFSe
aa10: 73 5d 20 63 75 72 72 65 6e 74 6c 79 20 69 6e 20  s] currently in 
aa20: 75 73 65 2e 20 20 5e 28 54 68 65 20 61 72 67 75  use.  ^(The argu
aa30: 6d 65 6e 74 20 58 20 69 6e 0a 2a 2a 20 73 71 6c  ment X in.** sql
aa40: 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f  ite3_file_contro
aa50: 6c 28 64 62 2c 53 51 4c 49 54 45 5f 46 43 4e 54  l(db,SQLITE_FCNT
aa60: 4c 5f 56 46 53 5f 50 4f 49 4e 54 45 52 2c 58 29  L_VFS_POINTER,X)
aa70: 20 6d 75 73 74 20 62 65 0a 2a 2a 20 6f 66 20 74   must be.** of t
aa80: 79 70 65 20 22 5b 73 71 6c 69 74 65 33 5f 76 66  ype "[sqlite3_vf
aa90: 73 5d 20 2a 2a 22 2e 20 20 54 68 69 73 20 6f 70  s] **".  This op
aaa0: 63 6f 64 65 73 20 77 69 6c 6c 20 73 65 74 20 2a  codes will set *
aab0: 58 0a 2a 2a 20 74 6f 20 61 20 70 6f 69 6e 74 65  X.** to a pointe
aac0: 72 20 74 6f 20 74 68 65 20 74 6f 70 2d 6c 65 76  r to the top-lev
aad0: 65 6c 20 56 46 53 2e 29 5e 0a 2a 2a 20 5e 57 68  el VFS.)^.** ^Wh
aae0: 65 6e 20 74 68 65 72 65 20 61 72 65 20 6d 75 6c  en there are mul
aaf0: 74 69 70 6c 65 20 56 46 53 20 73 68 69 6d 73 20  tiple VFS shims 
ab00: 69 6e 20 74 68 65 20 73 74 61 63 6b 2c 20 74 68  in the stack, th
ab10: 69 73 20 6f 70 63 6f 64 65 20 66 69 6e 64 73 20  is opcode finds 
ab20: 74 68 65 0a 2a 2a 20 75 70 70 65 72 2d 6d 6f 73  the.** upper-mos
ab30: 74 20 73 68 69 6d 20 6f 6e 6c 79 2e 0a 2a 2a 0a  t shim only..**.
ab40: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
ab50: 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 5d 0a 2a  FCNTL_PRAGMA]].*
ab60: 2a 20 5e 57 68 65 6e 65 76 65 72 20 61 20 5b 50  * ^Whenever a [P
ab70: 52 41 47 4d 41 5d 20 73 74 61 74 65 6d 65 6e 74  RAGMA] statement
ab80: 20 69 73 20 70 61 72 73 65 64 2c 20 61 6e 20 5b   is parsed, an [
ab90: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41  SQLITE_FCNTL_PRA
aba0: 47 4d 41 5d 20 0a 2a 2a 20 66 69 6c 65 20 63 6f  GMA] .** file co
abb0: 6e 74 72 6f 6c 20 69 73 20 73 65 6e 74 20 74 6f  ntrol is sent to
abc0: 20 74 68 65 20 6f 70 65 6e 20 5b 73 71 6c 69 74   the open [sqlit
abd0: 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20  e3_file] object 
abe0: 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 0a 2a 2a  corresponding.**
abf0: 20 74 6f 20 74 68 65 20 64 61 74 61 62 61 73 65   to the database
ac00: 20 66 69 6c 65 20 74 6f 20 77 68 69 63 68 20 74   file to which t
ac10: 68 65 20 70 72 61 67 6d 61 20 73 74 61 74 65 6d  he pragma statem
ac20: 65 6e 74 20 72 65 66 65 72 73 2e 20 5e 54 68 65  ent refers. ^The
ac30: 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20   argument.** to 
ac40: 74 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  the [SQLITE_FCNT
ac50: 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65 20 63  L_PRAGMA] file c
ac60: 6f 6e 74 72 6f 6c 20 69 73 20 61 6e 20 61 72 72  ontrol is an arr
ac70: 61 79 20 6f 66 0a 2a 2a 20 70 6f 69 6e 74 65 72  ay of.** pointer
ac80: 73 20 74 6f 20 73 74 72 69 6e 67 73 20 28 63 68  s to strings (ch
ac90: 61 72 2a 2a 29 20 69 6e 20 77 68 69 63 68 20 74  ar**) in which t
aca0: 68 65 20 73 65 63 6f 6e 64 20 65 6c 65 6d 65 6e  he second elemen
acb0: 74 20 6f 66 20 74 68 65 20 61 72 72 61 79 0a 2a  t of the array.*
acc0: 2a 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66  * is the name of
acd0: 20 74 68 65 20 70 72 61 67 6d 61 20 61 6e 64 20   the pragma and 
ace0: 74 68 65 20 74 68 69 72 64 20 65 6c 65 6d 65 6e  the third elemen
acf0: 74 20 69 73 20 74 68 65 20 61 72 67 75 6d 65 6e  t is the argumen
ad00: 74 20 74 6f 20 74 68 65 0a 2a 2a 20 70 72 61 67  t to the.** prag
ad10: 6d 61 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68  ma or NULL if th
ad20: 65 20 70 72 61 67 6d 61 20 68 61 73 20 6e 6f 20  e pragma has no 
ad30: 61 72 67 75 6d 65 6e 74 2e 20 20 5e 54 68 65 20  argument.  ^The 
ad40: 68 61 6e 64 6c 65 72 20 66 6f 72 20 61 6e 0a 2a  handler for an.*
ad50: 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  * [SQLITE_FCNTL_
ad60: 50 52 41 47 4d 41 5d 20 66 69 6c 65 20 63 6f 6e  PRAGMA] file con
ad70: 74 72 6f 6c 20 63 61 6e 20 6f 70 74 69 6f 6e 61  trol can optiona
ad80: 6c 6c 79 20 6d 61 6b 65 20 74 68 65 20 66 69 72  lly make the fir
ad90: 73 74 20 65 6c 65 6d 65 6e 74 0a 2a 2a 20 6f 66  st element.** of
ada0: 20 74 68 65 20 63 68 61 72 2a 2a 20 61 72 67 75   the char** argu
adb0: 6d 65 6e 74 20 70 6f 69 6e 74 20 74 6f 20 61 20  ment point to a 
adc0: 73 74 72 69 6e 67 20 6f 62 74 61 69 6e 65 64 20  string obtained 
add0: 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 70  from [sqlite3_mp
ade0: 72 69 6e 74 66 28 29 5d 0a 2a 2a 20 6f 72 20 74  rintf()].** or t
adf0: 68 65 20 65 71 75 69 76 61 6c 65 6e 74 20 61 6e  he equivalent an
ae00: 64 20 74 68 61 74 20 73 74 72 69 6e 67 20 77 69  d that string wi
ae10: 6c 6c 20 62 65 63 6f 6d 65 20 74 68 65 20 72 65  ll become the re
ae20: 73 75 6c 74 20 6f 66 20 74 68 65 20 70 72 61 67  sult of the prag
ae30: 6d 61 20 6f 72 0a 2a 2a 20 74 68 65 20 65 72 72  ma or.** the err
ae40: 6f 72 20 6d 65 73 73 61 67 65 20 69 66 20 74 68  or message if th
ae50: 65 20 70 72 61 67 6d 61 20 66 61 69 6c 73 2e 20  e pragma fails. 
ae60: 5e 49 66 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49  ^If the.** [SQLI
ae70: 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d  TE_FCNTL_PRAGMA]
ae80: 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 72 65   file control re
ae90: 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4e 4f  turns [SQLITE_NO
aea0: 54 46 4f 55 4e 44 5d 2c 20 74 68 65 6e 20 6e 6f  TFOUND], then no
aeb0: 72 6d 61 6c 20 0a 2a 2a 20 5b 50 52 41 47 4d 41  rmal .** [PRAGMA
aec0: 5d 20 70 72 6f 63 65 73 73 69 6e 67 20 63 6f 6e  ] processing con
aed0: 74 69 6e 75 65 73 2e 20 20 5e 49 66 20 74 68 65  tinues.  ^If the
aee0: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50   [SQLITE_FCNTL_P
aef0: 52 41 47 4d 41 5d 0a 2a 2a 20 66 69 6c 65 20 63  RAGMA].** file c
af00: 6f 6e 74 72 6f 6c 20 72 65 74 75 72 6e 73 20 5b  ontrol returns [
af10: 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74 68 65 6e  SQLITE_OK], then
af20: 20 74 68 65 20 70 61 72 73 65 72 20 61 73 73 75   the parser assu
af30: 6d 65 73 20 74 68 61 74 20 74 68 65 0a 2a 2a 20  mes that the.** 
af40: 56 46 53 20 68 61 73 20 68 61 6e 64 6c 65 64 20  VFS has handled 
af50: 74 68 65 20 50 52 41 47 4d 41 20 69 74 73 65 6c  the PRAGMA itsel
af60: 66 20 61 6e 64 20 74 68 65 20 70 61 72 73 65 72  f and the parser
af70: 20 67 65 6e 65 72 61 74 65 73 20 61 20 6e 6f 2d   generates a no-
af80: 6f 70 0a 2a 2a 20 70 72 65 70 61 72 65 64 20 73  op.** prepared s
af90: 74 61 74 65 6d 65 6e 74 20 69 66 20 72 65 73 75  tatement if resu
afa0: 6c 74 20 73 74 72 69 6e 67 20 69 73 20 4e 55 4c  lt string is NUL
afb0: 4c 2c 20 6f 72 20 74 68 61 74 20 72 65 74 75 72  L, or that retur
afc0: 6e 73 20 61 20 63 6f 70 79 0a 2a 2a 20 6f 66 20  ns a copy.** of 
afd0: 74 68 65 20 72 65 73 75 6c 74 20 73 74 72 69 6e  the result strin
afe0: 67 20 69 66 20 74 68 65 20 73 74 72 69 6e 67 20  g if the string 
aff0: 69 73 20 6e 6f 6e 2d 4e 55 4c 4c 2e 0a 2a 2a 20  is non-NULL..** 
b000: 5e 49 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  ^If the [SQLITE_
b010: 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69  FCNTL_PRAGMA] fi
b020: 6c 65 20 63 6f 6e 74 72 6f 6c 20 72 65 74 75 72  le control retur
b030: 6e 73 0a 2a 2a 20 61 6e 79 20 72 65 73 75 6c 74  ns.** any result
b040: 20 63 6f 64 65 20 6f 74 68 65 72 20 74 68 61 6e   code other than
b050: 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20   [SQLITE_OK] or 
b060: 5b 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44  [SQLITE_NOTFOUND
b070: 5d 2c 20 74 68 61 74 20 6d 65 61 6e 73 0a 2a 2a  ], that means.**
b080: 20 74 68 61 74 20 74 68 65 20 56 46 53 20 65 6e   that the VFS en
b090: 63 6f 75 6e 74 65 72 65 64 20 61 6e 20 65 72 72  countered an err
b0a0: 6f 72 20 77 68 69 6c 65 20 68 61 6e 64 6c 69 6e  or while handlin
b0b0: 67 20 74 68 65 20 5b 50 52 41 47 4d 41 5d 20 61  g the [PRAGMA] a
b0c0: 6e 64 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 69 6c  nd the.** compil
b0d0: 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 50 52 41  ation of the PRA
b0e0: 47 4d 41 20 66 61 69 6c 73 20 77 69 74 68 20 61  GMA fails with a
b0f0: 6e 20 65 72 72 6f 72 2e 20 20 5e 54 68 65 20 5b  n error.  ^The [
b100: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41  SQLITE_FCNTL_PRA
b110: 47 4d 41 5d 0a 2a 2a 20 66 69 6c 65 20 63 6f 6e  GMA].** file con
b120: 74 72 6f 6c 20 6f 63 63 75 72 73 20 61 74 20 74  trol occurs at t
b130: 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20  he beginning of 
b140: 70 72 61 67 6d 61 20 73 74 61 74 65 6d 65 6e 74  pragma statement
b150: 20 61 6e 61 6c 79 73 69 73 20 61 6e 64 20 73 6f   analysis and so
b160: 0a 2a 2a 20 69 74 20 69 73 20 61 62 6c 65 20 74  .** it is able t
b170: 6f 20 6f 76 65 72 72 69 64 65 20 62 75 69 6c 74  o override built
b180: 2d 69 6e 20 5b 50 52 41 47 4d 41 5d 20 73 74 61  -in [PRAGMA] sta
b190: 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 3c  tements..**.** <
b1a0: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
b1b0: 4c 5f 42 55 53 59 48 41 4e 44 4c 45 52 5d 5d 0a  L_BUSYHANDLER]].
b1c0: 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f  ** ^The [SQLITE_
b1d0: 46 43 4e 54 4c 5f 42 55 53 59 48 41 4e 44 4c 45  FCNTL_BUSYHANDLE
b1e0: 52 5d 0a 2a 2a 20 66 69 6c 65 2d 63 6f 6e 74 72  R].** file-contr
b1f0: 6f 6c 20 6d 61 79 20 62 65 20 69 6e 76 6f 6b 65  ol may be invoke
b200: 64 20 62 79 20 53 51 4c 69 74 65 20 6f 6e 20 74  d by SQLite on t
b210: 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
b220: 20 68 61 6e 64 6c 65 0a 2a 2a 20 73 68 6f 72 74   handle.** short
b230: 6c 79 20 61 66 74 65 72 20 69 74 20 69 73 20 6f  ly after it is o
b240: 70 65 6e 65 64 20 69 6e 20 6f 72 64 65 72 20 74  pened in order t
b250: 6f 20 70 72 6f 76 69 64 65 20 61 20 63 75 73 74  o provide a cust
b260: 6f 6d 20 56 46 53 20 77 69 74 68 20 61 63 63 65  om VFS with acce
b270: 73 73 0a 2a 2a 20 74 6f 20 74 68 65 20 63 6f 6e  ss.** to the con
b280: 6e 65 63 74 69 6f 6e 73 20 62 75 73 79 2d 68 61  nections busy-ha
b290: 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b 2e 20  ndler callback. 
b2a0: 54 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20  The argument is 
b2b0: 6f 66 20 74 79 70 65 20 28 76 6f 69 64 20 2a 2a  of type (void **
b2c0: 29 0a 2a 2a 20 2d 20 61 6e 20 61 72 72 61 79 20  ).** - an array 
b2d0: 6f 66 20 74 77 6f 20 28 76 6f 69 64 20 2a 29 20  of two (void *) 
b2e0: 76 61 6c 75 65 73 2e 20 54 68 65 20 66 69 72 73  values. The firs
b2f0: 74 20 28 76 6f 69 64 20 2a 29 20 61 63 74 75 61  t (void *) actua
b300: 6c 6c 79 20 70 6f 69 6e 74 73 0a 2a 2a 20 74 6f  lly points.** to
b310: 20 61 20 66 75 6e 63 74 69 6f 6e 20 6f 66 20 74   a function of t
b320: 79 70 65 20 28 69 6e 74 20 28 2a 29 28 76 6f 69  ype (int (*)(voi
b330: 64 20 2a 29 29 2e 20 49 6e 20 6f 72 64 65 72 20  d *)). In order 
b340: 74 6f 20 69 6e 76 6f 6b 65 20 74 68 65 20 63 6f  to invoke the co
b350: 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a 20 62 75 73  nnections.** bus
b360: 79 2d 68 61 6e 64 6c 65 72 2c 20 74 68 69 73 20  y-handler, this 
b370: 66 75 6e 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20  function should 
b380: 62 65 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20  be invoked with 
b390: 74 68 65 20 73 65 63 6f 6e 64 20 28 76 6f 69 64  the second (void
b3a0: 20 2a 29 20 69 6e 0a 2a 2a 20 74 68 65 20 61 72   *) in.** the ar
b3b0: 72 61 79 20 61 73 20 74 68 65 20 6f 6e 6c 79 20  ray as the only 
b3c0: 61 72 67 75 6d 65 6e 74 2e 20 49 66 20 69 74 20  argument. If it 
b3d0: 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f  returns non-zero
b3e0: 2c 20 74 68 65 6e 20 74 68 65 20 6f 70 65 72 61  , then the opera
b3f0: 74 69 6f 6e 0a 2a 2a 20 73 68 6f 75 6c 64 20 62  tion.** should b
b400: 65 20 72 65 74 72 69 65 64 2e 20 49 66 20 69 74  e retried. If it
b410: 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2c 20 74   returns zero, t
b420: 68 65 20 63 75 73 74 6f 6d 20 56 46 53 20 73 68  he custom VFS sh
b430: 6f 75 6c 64 20 61 62 61 6e 64 6f 6e 20 74 68 65  ould abandon the
b440: 0a 2a 2a 20 63 75 72 72 65 6e 74 20 6f 70 65 72  .** current oper
b450: 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69  ation..**.** <li
b460: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
b470: 54 45 4d 50 46 49 4c 45 4e 41 4d 45 5d 5d 0a 2a  TEMPFILENAME]].*
b480: 2a 20 5e 41 70 70 6c 69 63 61 74 69 6f 6e 20 63  * ^Application c
b490: 61 6e 20 69 6e 76 6f 6b 65 20 74 68 65 20 5b 53  an invoke the [S
b4a0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 45 4d 50  QLITE_FCNTL_TEMP
b4b0: 46 49 4c 45 4e 41 4d 45 5d 20 66 69 6c 65 2d 63  FILENAME] file-c
b4c0: 6f 6e 74 72 6f 6c 0a 2a 2a 20 74 6f 20 68 61 76  ontrol.** to hav
b4d0: 65 20 53 51 4c 69 74 65 20 67 65 6e 65 72 61 74  e SQLite generat
b4e0: 65 20 61 0a 2a 2a 20 74 65 6d 70 6f 72 61 72 79  e a.** temporary
b4f0: 20 66 69 6c 65 6e 61 6d 65 20 75 73 69 6e 67 20   filename using 
b500: 74 68 65 20 73 61 6d 65 20 61 6c 67 6f 72 69 74  the same algorit
b510: 68 6d 20 74 68 61 74 20 69 73 20 66 6f 6c 6c 6f  hm that is follo
b520: 77 65 64 20 74 6f 20 67 65 6e 65 72 61 74 65 0a  wed to generate.
b530: 2a 2a 20 74 65 6d 70 6f 72 61 72 79 20 66 69 6c  ** temporary fil
b540: 65 6e 61 6d 65 73 20 66 6f 72 20 54 45 4d 50 20  enames for TEMP 
b550: 74 61 62 6c 65 73 20 61 6e 64 20 6f 74 68 65 72  tables and other
b560: 20 69 6e 74 65 72 6e 61 6c 20 75 73 65 73 2e 20   internal uses. 
b570: 20 54 68 65 0a 2a 2a 20 61 72 67 75 6d 65 6e 74   The.** argument
b580: 20 73 68 6f 75 6c 64 20 62 65 20 61 20 63 68 61   should be a cha
b590: 72 2a 2a 20 77 68 69 63 68 20 77 69 6c 6c 20 62  r** which will b
b5a0: 65 20 66 69 6c 6c 65 64 20 77 69 74 68 20 74 68  e filled with th
b5b0: 65 20 66 69 6c 65 6e 61 6d 65 0a 2a 2a 20 77 72  e filename.** wr
b5c0: 69 74 74 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72  itten into memor
b5d0: 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  y obtained from 
b5e0: 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
b5f0: 29 5d 2e 20 20 54 68 65 20 63 61 6c 6c 65 72 20  )].  The caller 
b600: 73 68 6f 75 6c 64 0a 2a 2a 20 69 6e 76 6f 6b 65  should.** invoke
b610: 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
b620: 5d 20 6f 6e 20 74 68 65 20 72 65 73 75 6c 74 20  ] on the result 
b630: 74 6f 20 61 76 6f 69 64 20 61 20 6d 65 6d 6f 72  to avoid a memor
b640: 79 20 6c 65 61 6b 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  y leak..**.** <l
b650: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
b660: 5f 4d 4d 41 50 5f 53 49 5a 45 5d 5d 0a 2a 2a 20  _MMAP_SIZE]].** 
b670: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
b680: 4c 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20 66 69 6c  L_MMAP_SIZE] fil
b690: 65 20 63 6f 6e 74 72 6f 6c 20 69 73 20 75 73 65  e control is use
b6a0: 64 20 74 6f 20 71 75 65 72 79 20 6f 72 20 73 65  d to query or se
b6b0: 74 20 74 68 65 0a 2a 2a 20 6d 61 78 69 6d 75 6d  t the.** maximum
b6c0: 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
b6d0: 20 74 68 61 74 20 77 69 6c 6c 20 62 65 20 75 73   that will be us
b6e0: 65 64 20 66 6f 72 20 6d 65 6d 6f 72 79 2d 6d 61  ed for memory-ma
b6f0: 70 70 65 64 20 49 2f 4f 2e 0a 2a 2a 20 54 68 65  pped I/O..** The
b700: 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70   argument is a p
b710: 6f 69 6e 74 65 72 20 74 6f 20 61 20 76 61 6c 75  ointer to a valu
b720: 65 20 6f 66 20 74 79 70 65 20 73 71 6c 69 74 65  e of type sqlite
b730: 33 5f 69 6e 74 36 34 20 74 68 61 74 0a 2a 2a 20  3_int64 that.** 
b740: 69 73 20 61 6e 20 61 64 76 69 73 6f 72 79 20 6d  is an advisory m
b750: 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66  aximum number of
b760: 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 66 69   bytes in the fi
b770: 6c 65 20 74 6f 20 6d 65 6d 6f 72 79 20 6d 61 70  le to memory map
b780: 2e 20 20 54 68 65 0a 2a 2a 20 70 6f 69 6e 74 65  .  The.** pointe
b790: 72 20 69 73 20 6f 76 65 72 77 72 69 74 74 65 6e  r is overwritten
b7a0: 20 77 69 74 68 20 74 68 65 20 6f 6c 64 20 76 61   with the old va
b7b0: 6c 75 65 2e 20 20 54 68 65 20 6c 69 6d 69 74 20  lue.  The limit 
b7c0: 69 73 20 6e 6f 74 20 63 68 61 6e 67 65 64 20 69  is not changed i
b7d0: 66 0a 2a 2a 20 74 68 65 20 76 61 6c 75 65 20 6f  f.** the value o
b7e0: 72 69 67 69 6e 61 6c 6c 79 20 70 6f 69 6e 74 65  riginally pointe
b7f0: 64 20 74 6f 20 69 73 20 6e 65 67 61 74 69 76 65  d to is negative
b800: 2c 20 61 6e 64 20 73 6f 20 74 68 65 20 63 75 72  , and so the cur
b810: 72 65 6e 74 20 6c 69 6d 69 74 20 0a 2a 2a 20 63  rent limit .** c
b820: 61 6e 20 62 65 20 71 75 65 72 69 65 64 20 62 79  an be queried by
b830: 20 70 61 73 73 69 6e 67 20 69 6e 20 61 20 70 6f   passing in a po
b840: 69 6e 74 65 72 20 74 6f 20 61 20 6e 65 67 61 74  inter to a negat
b850: 69 76 65 20 6e 75 6d 62 65 72 2e 20 20 54 68 69  ive number.  Thi
b860: 73 0a 2a 2a 20 66 69 6c 65 2d 63 6f 6e 74 72 6f  s.** file-contro
b870: 6c 20 69 73 20 75 73 65 64 20 69 6e 74 65 72 6e  l is used intern
b880: 61 6c 6c 79 20 74 6f 20 69 6d 70 6c 65 6d 65 6e  ally to implemen
b890: 74 20 5b 50 52 41 47 4d 41 20 6d 6d 61 70 5f 73  t [PRAGMA mmap_s
b8a0: 69 7a 65 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  ize]..**.** <li>
b8b0: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54  [[SQLITE_FCNTL_T
b8c0: 52 41 43 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53  RACE]].** The [S
b8d0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 52 41 43  QLITE_FCNTL_TRAC
b8e0: 45 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20  E] file control 
b8f0: 70 72 6f 76 69 64 65 73 20 61 64 76 69 73 6f 72  provides advisor
b900: 79 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a  y information.**
b910: 20 74 6f 20 74 68 65 20 56 46 53 20 61 62 6f 75   to the VFS abou
b920: 74 20 77 68 61 74 20 74 68 65 20 68 69 67 68 65  t what the highe
b930: 72 20 6c 61 79 65 72 73 20 6f 66 20 74 68 65 20  r layers of the 
b940: 53 51 4c 69 74 65 20 73 74 61 63 6b 20 61 72 65  SQLite stack are
b950: 20 64 6f 69 6e 67 2e 0a 2a 2a 20 54 68 69 73 20   doing..** This 
b960: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73 20  file control is 
b970: 75 73 65 64 20 62 79 20 73 6f 6d 65 20 56 46 53  used by some VFS
b980: 20 61 63 74 69 76 69 74 79 20 74 72 61 63 69 6e   activity tracin
b990: 67 20 5b 73 68 69 6d 73 5d 2e 0a 2a 2a 20 54 68  g [shims]..** Th
b9a0: 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20  e argument is a 
b9b0: 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20  zero-terminated 
b9c0: 73 74 72 69 6e 67 2e 20 20 48 69 67 68 65 72 20  string.  Higher 
b9d0: 6c 61 79 65 72 73 20 69 6e 20 74 68 65 0a 2a 2a  layers in the.**
b9e0: 20 53 51 4c 69 74 65 20 73 74 61 63 6b 20 6d 61   SQLite stack ma
b9f0: 79 20 67 65 6e 65 72 61 74 65 20 69 6e 73 74 61  y generate insta
ba00: 6e 63 65 73 20 6f 66 20 74 68 69 73 20 66 69 6c  nces of this fil
ba10: 65 20 63 6f 6e 74 72 6f 6c 20 69 66 0a 2a 2a 20  e control if.** 
ba20: 74 68 65 20 5b 53 51 4c 49 54 45 5f 55 53 45 5f  the [SQLITE_USE_
ba30: 46 43 4e 54 4c 5f 54 52 41 43 45 5d 20 63 6f 6d  FCNTL_TRACE] com
ba40: 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
ba50: 20 69 73 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 0a   is enabled..**.
ba60: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
ba70: 46 43 4e 54 4c 5f 48 41 53 5f 4d 4f 56 45 44 5d  FCNTL_HAS_MOVED]
ba80: 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45  ].** The [SQLITE
ba90: 5f 46 43 4e 54 4c 5f 48 41 53 5f 4d 4f 56 45 44  _FCNTL_HAS_MOVED
baa0: 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69  ] file control i
bab0: 6e 74 65 72 70 72 65 74 73 20 69 74 73 20 61 72  nterprets its ar
bac0: 67 75 6d 65 6e 74 20 61 73 20 61 0a 2a 2a 20 70  gument as a.** p
bad0: 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74  ointer to an int
bae0: 65 67 65 72 20 61 6e 64 20 69 74 20 77 72 69 74  eger and it writ
baf0: 65 73 20 61 20 62 6f 6f 6c 65 61 6e 20 69 6e 74  es a boolean int
bb00: 6f 20 74 68 61 74 20 69 6e 74 65 67 65 72 20 64  o that integer d
bb10: 65 70 65 6e 64 69 6e 67 0a 2a 2a 20 6f 6e 20 77  epending.** on w
bb20: 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68  hether or not th
bb30: 65 20 66 69 6c 65 20 68 61 73 20 62 65 65 6e 20  e file has been 
bb40: 72 65 6e 61 6d 65 64 2c 20 6d 6f 76 65 64 2c 20  renamed, moved, 
bb50: 6f 72 20 64 65 6c 65 74 65 64 20 73 69 6e 63 65  or deleted since
bb60: 20 69 74 0a 2a 2a 20 77 61 73 20 66 69 72 73 74   it.** was first
bb70: 20 6f 70 65 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c   opened..**.** <
bb80: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
bb90: 4c 5f 57 49 4e 33 32 5f 47 45 54 5f 48 41 4e 44  L_WIN32_GET_HAND
bba0: 4c 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  LE]].** The [SQL
bbb0: 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f  ITE_FCNTL_WIN32_
bbc0: 47 45 54 5f 48 41 4e 44 4c 45 5d 20 6f 70 63 6f  GET_HANDLE] opco
bbd0: 64 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 74  de can be used t
bbe0: 6f 20 6f 62 74 61 69 6e 20 74 68 65 0a 2a 2a 20  o obtain the.** 
bbf0: 75 6e 64 65 72 6c 79 69 6e 67 20 6e 61 74 69 76  underlying nativ
bc00: 65 20 66 69 6c 65 20 68 61 6e 64 6c 65 20 61 73  e file handle as
bc10: 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 61 20  sociated with a 
bc20: 66 69 6c 65 20 68 61 6e 64 6c 65 2e 20 20 54 68  file handle.  Th
bc30: 69 73 20 66 69 6c 65 0a 2a 2a 20 63 6f 6e 74 72  is file.** contr
bc40: 6f 6c 20 69 6e 74 65 72 70 72 65 74 73 20 69 74  ol interprets it
bc50: 73 20 61 72 67 75 6d 65 6e 74 20 61 73 20 61 20  s argument as a 
bc60: 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 6e 61 74  pointer to a nat
bc70: 69 76 65 20 66 69 6c 65 20 68 61 6e 64 6c 65 20  ive file handle 
bc80: 61 6e 64 0a 2a 2a 20 77 72 69 74 65 73 20 74 68  and.** writes th
bc90: 65 20 72 65 73 75 6c 74 69 6e 67 20 76 61 6c 75  e resulting valu
bca0: 65 20 74 68 65 72 65 2e 0a 2a 2a 0a 2a 2a 20 3c  e there..**.** <
bcb0: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
bcc0: 4c 5f 57 49 4e 33 32 5f 53 45 54 5f 48 41 4e 44  L_WIN32_SET_HAND
bcd0: 4c 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  LE]].** The [SQL
bce0: 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f  ITE_FCNTL_WIN32_
bcf0: 53 45 54 5f 48 41 4e 44 4c 45 5d 20 6f 70 63 6f  SET_HANDLE] opco
bd00: 64 65 20 69 73 20 75 73 65 64 20 66 6f 72 20 64  de is used for d
bd10: 65 62 75 67 67 69 6e 67 2e 20 20 54 68 69 73 0a  ebugging.  This.
bd20: 2a 2a 20 6f 70 63 6f 64 65 20 63 61 75 73 65 73  ** opcode causes
bd30: 20 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f   the xFileContro
bd40: 6c 20 6d 65 74 68 6f 64 20 74 6f 20 73 77 61 70  l method to swap
bd50: 20 74 68 65 20 66 69 6c 65 20 68 61 6e 64 6c 65   the file handle
bd60: 20 77 69 74 68 20 74 68 65 20 6f 6e 65 0a 2a 2a   with the one.**
bd70: 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 74   pointed to by t
bd80: 68 65 20 70 41 72 67 20 61 72 67 75 6d 65 6e 74  he pArg argument
bd90: 2e 20 20 54 68 69 73 20 63 61 70 61 62 69 6c 69  .  This capabili
bda0: 74 79 20 69 73 20 75 73 65 64 20 64 75 72 69 6e  ty is used durin
bdb0: 67 20 74 65 73 74 69 6e 67 0a 2a 2a 20 61 6e 64  g testing.** and
bdc0: 20 6f 6e 6c 79 20 6e 65 65 64 73 20 74 6f 20 62   only needs to b
bdd0: 65 20 73 75 70 70 6f 72 74 65 64 20 77 68 65 6e  e supported when
bde0: 20 53 51 4c 49 54 45 5f 54 45 53 54 20 69 73 20   SQLITE_TEST is 
bdf0: 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c  defined..**.** <
be00: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
be10: 4c 5f 57 41 4c 5f 42 4c 4f 43 4b 5d 5d 0a 2a 2a  L_WAL_BLOCK]].**
be20: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e   The [SQLITE_FCN
be30: 54 4c 5f 57 41 4c 5f 42 4c 4f 43 4b 5d 20 69 73  TL_WAL_BLOCK] is
be40: 20 61 20 73 69 67 6e 61 6c 20 74 6f 20 74 68 65   a signal to the
be50: 20 56 46 53 20 6c 61 79 65 72 20 74 68 61 74 20   VFS layer that 
be60: 69 74 20 6d 69 67 68 74 0a 2a 2a 20 62 65 20 61  it might.** be a
be70: 64 76 61 6e 74 61 67 65 6f 75 73 20 74 6f 20 62  dvantageous to b
be80: 6c 6f 63 6b 20 6f 6e 20 74 68 65 20 6e 65 78 74  lock on the next
be90: 20 57 41 4c 20 6c 6f 63 6b 20 69 66 20 74 68 65   WAL lock if the
bea0: 20 6c 6f 63 6b 20 69 73 20 6e 6f 74 20 69 6d 6d   lock is not imm
beb0: 65 64 69 61 74 65 6c 79 0a 2a 2a 20 61 76 61 69  ediately.** avai
bec0: 6c 61 62 6c 65 2e 20 20 54 68 65 20 57 41 4c 20  lable.  The WAL 
bed0: 73 75 62 73 79 73 74 65 6d 20 69 73 73 75 65 73  subsystem issues
bee0: 20 74 68 69 73 20 73 69 67 6e 61 6c 20 64 75 72   this signal dur
bef0: 69 6e 67 20 72 61 72 65 0a 2a 2a 20 63 69 72 63  ing rare.** circ
bf00: 75 6d 73 74 61 6e 63 65 73 20 69 6e 20 6f 72 64  umstances in ord
bf10: 65 72 20 74 6f 20 66 69 78 20 61 20 70 72 6f 62  er to fix a prob
bf20: 6c 65 6d 20 77 69 74 68 20 70 72 69 6f 72 69 74  lem with priorit
bf30: 79 20 69 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 20  y inversion..** 
bf40: 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f  Applications sho
bf50: 75 6c 64 20 3c 65 6d 3e 6e 6f 74 3c 2f 65 6d 3e  uld <em>not</em>
bf60: 20 75 73 65 20 74 68 69 73 20 66 69 6c 65 2d 63   use this file-c
bf70: 6f 6e 74 72 6f 6c 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  ontrol..**.** <l
bf80: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
bf90: 5f 5a 49 50 56 46 53 5d 5d 0a 2a 2a 20 54 68 65  _ZIPVFS]].** The
bfa0: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 5a   [SQLITE_FCNTL_Z
bfb0: 49 50 56 46 53 5d 20 6f 70 63 6f 64 65 20 69 73  IPVFS] opcode is
bfc0: 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 62 79 20   implemented by 
bfd0: 7a 69 70 76 66 73 20 6f 6e 6c 79 2e 20 41 6c 6c  zipvfs only. All
bfe0: 20 6f 74 68 65 72 0a 2a 2a 20 56 46 53 20 73 68   other.** VFS sh
bff0: 6f 75 6c 64 20 72 65 74 75 72 6e 20 53 51 4c 49  ould return SQLI
c000: 54 45 5f 4e 4f 54 46 4f 55 4e 44 20 66 6f 72 20  TE_NOTFOUND for 
c010: 74 68 69 73 20 6f 70 63 6f 64 65 2e 0a 2a 2a 0a  this opcode..**.
c020: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
c030: 46 43 4e 54 4c 5f 52 42 55 5d 5d 0a 2a 2a 20 54  FCNTL_RBU]].** T
c040: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
c050: 5f 52 42 55 5d 20 6f 70 63 6f 64 65 20 69 73 20  _RBU] opcode is 
c060: 69 6d 70 6c 65 6d 65 6e 74 65 64 20 62 79 20 74  implemented by t
c070: 68 65 20 73 70 65 63 69 61 6c 20 56 46 53 20 75  he special VFS u
c080: 73 65 64 20 62 79 0a 2a 2a 20 74 68 65 20 52 42  sed by.** the RB
c090: 55 20 65 78 74 65 6e 73 69 6f 6e 20 6f 6e 6c 79  U extension only
c0a0: 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20 56 46 53  .  All other VFS
c0b0: 20 73 68 6f 75 6c 64 20 72 65 74 75 72 6e 20 53   should return S
c0c0: 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 20 66  QLITE_NOTFOUND f
c0d0: 6f 72 0a 2a 2a 20 74 68 69 73 20 6f 70 63 6f 64  or.** this opcod
c0e0: 65 2e 20 20 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2f  e.  .** </ul>.*/
c0f0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
c100: 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 20  FCNTL_LOCKSTATE 
c110: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31 0a                1.
c120: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
c130: 43 4e 54 4c 5f 47 45 54 5f 4c 4f 43 4b 50 52 4f  CNTL_GET_LOCKPRO
c140: 58 59 46 49 4c 45 20 20 20 20 20 20 20 32 0a 23  XYFILE       2.#
c150: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
c160: 4e 54 4c 5f 53 45 54 5f 4c 4f 43 4b 50 52 4f 58  NTL_SET_LOCKPROX
c170: 59 46 49 4c 45 20 20 20 20 20 20 20 33 0a 23 64  YFILE       3.#d
c180: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
c190: 54 4c 5f 4c 41 53 54 5f 45 52 52 4e 4f 20 20 20  TL_LAST_ERRNO   
c1a0: 20 20 20 20 20 20 20 20 20 20 20 34 0a 23 64 65             4.#de
c1b0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
c1c0: 4c 5f 53 49 5a 45 5f 48 49 4e 54 20 20 20 20 20  L_SIZE_HINT     
c1d0: 20 20 20 20 20 20 20 20 20 20 35 0a 23 64 65 66            5.#def
c1e0: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
c1f0: 5f 43 48 55 4e 4b 5f 53 49 5a 45 20 20 20 20 20  _CHUNK_SIZE     
c200: 20 20 20 20 20 20 20 20 20 36 0a 23 64 65 66 69           6.#defi
c210: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
c220: 46 49 4c 45 5f 50 4f 49 4e 54 45 52 20 20 20 20  FILE_POINTER    
c230: 20 20 20 20 20 20 20 20 37 0a 23 64 65 66 69 6e          7.#defin
c240: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53  e SQLITE_FCNTL_S
c250: 59 4e 43 5f 4f 4d 49 54 54 45 44 20 20 20 20 20  YNC_OMITTED     
c260: 20 20 20 20 20 20 20 38 0a 23 64 65 66 69 6e 65         8.#define
c270: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49   SQLITE_FCNTL_WI
c280: 4e 33 32 5f 41 56 5f 52 45 54 52 59 20 20 20 20  N32_AV_RETRY    
c290: 20 20 20 20 20 20 39 0a 23 64 65 66 69 6e 65 20        9.#define 
c2a0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 45 52  SQLITE_FCNTL_PER
c2b0: 53 49 53 54 5f 57 41 4c 20 20 20 20 20 20 20 20  SIST_WAL        
c2c0: 20 20 20 20 31 30 0a 23 64 65 66 69 6e 65 20 53      10.#define S
c2d0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 45 52  QLITE_FCNTL_OVER
c2e0: 57 52 49 54 45 20 20 20 20 20 20 20 20 20 20 20  WRITE           
c2f0: 20 20 20 31 31 0a 23 64 65 66 69 6e 65 20 53 51     11.#define SQ
c300: 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 4e 41  LITE_FCNTL_VFSNA
c310: 4d 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ME              
c320: 20 20 31 32 0a 23 64 65 66 69 6e 65 20 53 51 4c    12.#define SQL
c330: 49 54 45 5f 46 43 4e 54 4c 5f 50 4f 57 45 52 53  ITE_FCNTL_POWERS
c340: 41 46 45 5f 4f 56 45 52 57 52 49 54 45 20 20 20  AFE_OVERWRITE   
c350: 20 31 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   13.#define SQLI
c360: 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 20  TE_FCNTL_PRAGMA 
c370: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
c380: 31 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  14.#define SQLIT
c390: 45 5f 46 43 4e 54 4c 5f 42 55 53 59 48 41 4e 44  E_FCNTL_BUSYHAND
c3a0: 4c 45 52 20 20 20 20 20 20 20 20 20 20 20 20 31  LER            1
c3b0: 35 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  5.#define SQLITE
c3c0: 5f 46 43 4e 54 4c 5f 54 45 4d 50 46 49 4c 45 4e  _FCNTL_TEMPFILEN
c3d0: 41 4d 45 20 20 20 20 20 20 20 20 20 20 20 31 36  AME           16
c3e0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
c3f0: 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45 20  FCNTL_MMAP_SIZE 
c400: 20 20 20 20 20 20 20 20 20 20 20 20 20 31 38 0a               18.
c410: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
c420: 43 4e 54 4c 5f 54 52 41 43 45 20 20 20 20 20 20  CNTL_TRACE      
c430: 20 20 20 20 20 20 20 20 20 20 20 20 31 39 0a 23              19.#
c440: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
c450: 4e 54 4c 5f 48 41 53 5f 4d 4f 56 45 44 20 20 20  NTL_HAS_MOVED   
c460: 20 20 20 20 20 20 20 20 20 20 20 32 30 0a 23 64             20.#d
c470: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
c480: 54 4c 5f 53 59 4e 43 20 20 20 20 20 20 20 20 20  TL_SYNC         
c490: 20 20 20 20 20 20 20 20 20 20 32 31 0a 23 64 65            21.#de
c4a0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
c4b0: 4c 5f 43 4f 4d 4d 49 54 5f 50 48 41 53 45 54 57  L_COMMIT_PHASETW
c4c0: 4f 20 20 20 20 20 20 20 20 32 32 0a 23 64 65 66  O        22.#def
c4d0: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
c4e0: 5f 57 49 4e 33 32 5f 53 45 54 5f 48 41 4e 44 4c  _WIN32_SET_HANDL
c4f0: 45 20 20 20 20 20 20 20 32 33 0a 23 64 65 66 69  E       23.#defi
c500: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
c510: 57 41 4c 5f 42 4c 4f 43 4b 20 20 20 20 20 20 20  WAL_BLOCK       
c520: 20 20 20 20 20 20 20 32 34 0a 23 64 65 66 69 6e         24.#defin
c530: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 5a  e SQLITE_FCNTL_Z
c540: 49 50 56 46 53 20 20 20 20 20 20 20 20 20 20 20  IPVFS           
c550: 20 20 20 20 20 20 32 35 0a 23 64 65 66 69 6e 65        25.#define
c560: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 52 42   SQLITE_FCNTL_RB
c570: 55 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  U               
c580: 20 20 20 20 20 32 36 0a 23 64 65 66 69 6e 65 20       26.#define 
c590: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53  SQLITE_FCNTL_VFS
c5a0: 5f 50 4f 49 4e 54 45 52 20 20 20 20 20 20 20 20  _POINTER        
c5b0: 20 20 20 20 32 37 0a 23 64 65 66 69 6e 65 20 53      27.#define S
c5c0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4a 4f 55 52  QLITE_FCNTL_JOUR
c5d0: 4e 41 4c 5f 50 4f 49 4e 54 45 52 20 20 20 20 20  NAL_POINTER     
c5e0: 20 20 20 32 38 0a 23 64 65 66 69 6e 65 20 53 51     28.#define SQ
c5f0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32  LITE_FCNTL_WIN32
c600: 5f 47 45 54 5f 48 41 4e 44 4c 45 20 20 20 20 20  _GET_HANDLE     
c610: 20 20 32 39 0a 23 64 65 66 69 6e 65 20 53 51 4c    29.#define SQL
c620: 49 54 45 5f 46 43 4e 54 4c 5f 50 44 42 20 20 20  ITE_FCNTL_PDB   
c630: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
c640: 20 33 30 0a 0a 2f 2a 20 64 65 70 72 65 63 61 74   30../* deprecat
c650: 65 64 20 6e 61 6d 65 73 20 2a 2f 0a 23 64 65 66  ed names */.#def
c660: 69 6e 65 20 53 51 4c 49 54 45 5f 47 45 54 5f 4c  ine SQLITE_GET_L
c670: 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20 20 20 20  OCKPROXYFILE    
c680: 20 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 47    SQLITE_FCNTL_G
c690: 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45  ET_LOCKPROXYFILE
c6a0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
c6b0: 53 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c  SET_LOCKPROXYFIL
c6c0: 45 20 20 20 20 20 20 53 51 4c 49 54 45 5f 46 43  E      SQLITE_FC
c6d0: 4e 54 4c 5f 53 45 54 5f 4c 4f 43 4b 50 52 4f 58  NTL_SET_LOCKPROX
c6e0: 59 46 49 4c 45 0a 23 64 65 66 69 6e 65 20 53 51  YFILE.#define SQ
c6f0: 4c 49 54 45 5f 4c 41 53 54 5f 45 52 52 4e 4f 20  LITE_LAST_ERRNO 
c700: 20 20 20 20 20 20 20 20 20 20 20 20 53 51 4c 49              SQLI
c710: 54 45 5f 46 43 4e 54 4c 5f 4c 41 53 54 5f 45 52  TE_FCNTL_LAST_ER
c720: 52 4e 4f 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  RNO.../*.** CAPI
c730: 33 52 45 46 3a 20 4d 75 74 65 78 20 48 61 6e 64  3REF: Mutex Hand
c740: 6c 65 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6d 75 74  le.**.** The mut
c750: 65 78 20 6d 6f 64 75 6c 65 20 77 69 74 68 69 6e  ex module within
c760: 20 53 51 4c 69 74 65 20 64 65 66 69 6e 65 73 20   SQLite defines 
c770: 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 20  [sqlite3_mutex] 
c780: 74 6f 20 62 65 20 61 6e 0a 2a 2a 20 61 62 73 74  to be an.** abst
c790: 72 61 63 74 20 74 79 70 65 20 66 6f 72 20 61 20  ract type for a 
c7a0: 6d 75 74 65 78 20 6f 62 6a 65 63 74 2e 20 20 54  mutex object.  T
c7b0: 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 6e  he SQLite core n
c7c0: 65 76 65 72 20 6c 6f 6f 6b 73 0a 2a 2a 20 61 74  ever looks.** at
c7d0: 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 72 65   the internal re
c7e0: 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 6f 66 20  presentation of 
c7f0: 61 6e 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  an [sqlite3_mute
c800: 78 5d 2e 20 20 49 74 20 6f 6e 6c 79 0a 2a 2a 20  x].  It only.** 
c810: 64 65 61 6c 73 20 77 69 74 68 20 70 6f 69 6e 74  deals with point
c820: 65 72 73 20 74 6f 20 74 68 65 20 5b 73 71 6c 69  ers to the [sqli
c830: 74 65 33 5f 6d 75 74 65 78 5d 20 6f 62 6a 65 63  te3_mutex] objec
c840: 74 2e 0a 2a 2a 0a 2a 2a 20 4d 75 74 65 78 65 73  t..**.** Mutexes
c850: 20 61 72 65 20 63 72 65 61 74 65 64 20 75 73 69   are created usi
c860: 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  ng [sqlite3_mute
c870: 78 5f 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 74  x_alloc()]..*/.t
c880: 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71  ypedef struct sq
c890: 6c 69 74 65 33 5f 6d 75 74 65 78 20 73 71 6c 69  lite3_mutex sqli
c8a0: 74 65 33 5f 6d 75 74 65 78 3b 0a 0a 2f 2a 0a 2a  te3_mutex;../*.*
c8b0: 2a 20 43 41 50 49 33 52 45 46 3a 20 4c 6f 61 64  * CAPI3REF: Load
c8c0: 61 62 6c 65 20 45 78 74 65 6e 73 69 6f 6e 20 54  able Extension T
c8d0: 68 75 6e 6b 0a 2a 2a 0a 2a 2a 20 41 20 70 6f 69  hunk.**.** A poi
c8e0: 6e 74 65 72 20 74 6f 20 74 68 65 20 6f 70 61 71  nter to the opaq
c8f0: 75 65 20 73 71 6c 69 74 65 33 5f 61 70 69 5f 72  ue sqlite3_api_r
c900: 6f 75 74 69 6e 65 73 20 73 74 72 75 63 74 75 72  outines structur
c910: 65 20 69 73 20 70 61 73 73 65 64 20 61 73 0a 2a  e is passed as.*
c920: 2a 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61  * the third para
c930: 6d 65 74 65 72 20 74 6f 20 65 6e 74 72 79 20 70  meter to entry p
c940: 6f 69 6e 74 73 20 6f 66 20 5b 6c 6f 61 64 61 62  oints of [loadab
c950: 6c 65 20 65 78 74 65 6e 73 69 6f 6e 73 5d 2e 20  le extensions]. 
c960: 20 54 68 69 73 0a 2a 2a 20 73 74 72 75 63 74 75   This.** structu
c970: 72 65 20 6d 75 73 74 20 62 65 20 74 79 70 65 64  re must be typed
c980: 65 66 65 64 20 69 6e 20 6f 72 64 65 72 20 74 6f  efed in order to
c990: 20 77 6f 72 6b 20 61 72 6f 75 6e 64 20 63 6f 6d   work around com
c9a0: 70 69 6c 65 72 20 77 61 72 6e 69 6e 67 73 0a 2a  piler warnings.*
c9b0: 2a 20 6f 6e 20 73 6f 6d 65 20 70 6c 61 74 66 6f  * on some platfo
c9c0: 72 6d 73 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  rms..*/.typedef 
c9d0: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 61  struct sqlite3_a
c9e0: 70 69 5f 72 6f 75 74 69 6e 65 73 20 73 71 6c 69  pi_routines sqli
c9f0: 74 65 33 5f 61 70 69 5f 72 6f 75 74 69 6e 65 73  te3_api_routines
ca00: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
ca10: 46 3a 20 4f 53 20 49 6e 74 65 72 66 61 63 65 20  F: OS Interface 
ca20: 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 41 6e 20  Object.**.** An 
ca30: 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20  instance of the 
ca40: 73 71 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a 65  sqlite3_vfs obje
ca50: 63 74 20 64 65 66 69 6e 65 73 20 74 68 65 20 69  ct defines the i
ca60: 6e 74 65 72 66 61 63 65 20 62 65 74 77 65 65 6e  nterface between
ca70: 0a 2a 2a 20 74 68 65 20 53 51 4c 69 74 65 20 63  .** the SQLite c
ca80: 6f 72 65 20 61 6e 64 20 74 68 65 20 75 6e 64 65  ore and the unde
ca90: 72 6c 79 69 6e 67 20 6f 70 65 72 61 74 69 6e 67  rlying operating
caa0: 20 73 79 73 74 65 6d 2e 20 20 54 68 65 20 22 76   system.  The "v
cab0: 66 73 22 0a 2a 2a 20 69 6e 20 74 68 65 20 6e 61  fs".** in the na
cac0: 6d 65 20 6f 66 20 74 68 65 20 6f 62 6a 65 63 74  me of the object
cad0: 20 73 74 61 6e 64 73 20 66 6f 72 20 22 76 69 72   stands for "vir
cae0: 74 75 61 6c 20 66 69 6c 65 20 73 79 73 74 65 6d  tual file system
caf0: 22 2e 20 20 53 65 65 0a 2a 2a 20 74 68 65 20 5b  ".  See.** the [
cb00: 56 46 53 20 7c 20 56 46 53 20 64 6f 63 75 6d 65  VFS | VFS docume
cb10: 6e 74 61 74 69 6f 6e 5d 20 66 6f 72 20 66 75 72  ntation] for fur
cb20: 74 68 65 72 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  ther information
cb30: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 76 61 6c 75  ..**.** The valu
cb40: 65 20 6f 66 20 74 68 65 20 69 56 65 72 73 69 6f  e of the iVersio
cb50: 6e 20 66 69 65 6c 64 20 69 73 20 69 6e 69 74 69  n field is initi
cb60: 61 6c 6c 79 20 31 20 62 75 74 20 6d 61 79 20 62  ally 1 but may b
cb70: 65 20 6c 61 72 67 65 72 20 69 6e 0a 2a 2a 20 66  e larger in.** f
cb80: 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f  uture versions o
cb90: 66 20 53 51 4c 69 74 65 2e 20 20 41 64 64 69 74  f SQLite.  Addit
cba0: 69 6f 6e 61 6c 20 66 69 65 6c 64 73 20 6d 61 79  ional fields may
cbb0: 20 62 65 20 61 70 70 65 6e 64 65 64 20 74 6f 20   be appended to 
cbc0: 74 68 69 73 0a 2a 2a 20 6f 62 6a 65 63 74 20 77  this.** object w
cbd0: 68 65 6e 20 74 68 65 20 69 56 65 72 73 69 6f 6e  hen the iVersion
cbe0: 20 76 61 6c 75 65 20 69 73 20 69 6e 63 72 65 61   value is increa
cbf0: 73 65 64 2e 20 20 4e 6f 74 65 20 74 68 61 74 20  sed.  Note that 
cc00: 74 68 65 20 73 74 72 75 63 74 75 72 65 0a 2a 2a  the structure.**
cc10: 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f   of the sqlite3_
cc20: 76 66 73 20 6f 62 6a 65 63 74 20 63 68 61 6e 67  vfs object chang
cc30: 65 73 20 69 6e 20 74 68 65 20 74 72 61 6e 73 61  es in the transa
cc40: 63 74 69 6f 6e 20 62 65 74 77 65 65 6e 0a 2a 2a  ction between.**
cc50: 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20   SQLite version 
cc60: 33 2e 35 2e 39 20 61 6e 64 20 33 2e 36 2e 30 20  3.5.9 and 3.6.0 
cc70: 61 6e 64 20 79 65 74 20 74 68 65 20 69 56 65 72  and yet the iVer
cc80: 73 69 6f 6e 20 66 69 65 6c 64 20 77 61 73 20 6e  sion field was n
cc90: 6f 74 0a 2a 2a 20 6d 6f 64 69 66 69 65 64 2e 0a  ot.** modified..
cca0: 2a 2a 0a 2a 2a 20 54 68 65 20 73 7a 4f 73 46 69  **.** The szOsFi
ccb0: 6c 65 20 66 69 65 6c 64 20 69 73 20 74 68 65 20  le field is the 
ccc0: 73 69 7a 65 20 6f 66 20 74 68 65 20 73 75 62 63  size of the subc
ccd0: 6c 61 73 73 65 64 20 5b 73 71 6c 69 74 65 33 5f  lassed [sqlite3_
cce0: 66 69 6c 65 5d 0a 2a 2a 20 73 74 72 75 63 74 75  file].** structu
ccf0: 72 65 20 75 73 65 64 20 62 79 20 74 68 69 73 20  re used by this 
cd00: 56 46 53 2e 20 20 6d 78 50 61 74 68 6e 61 6d 65  VFS.  mxPathname
cd10: 20 69 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 20   is the maximum 
cd20: 6c 65 6e 67 74 68 20 6f 66 0a 2a 2a 20 61 20 70  length of.** a p
cd30: 61 74 68 6e 61 6d 65 20 69 6e 20 74 68 69 73 20  athname in this 
cd40: 56 46 53 2e 0a 2a 2a 0a 2a 2a 20 52 65 67 69 73  VFS..**.** Regis
cd50: 74 65 72 65 64 20 73 71 6c 69 74 65 33 5f 76 66  tered sqlite3_vf
cd60: 73 20 6f 62 6a 65 63 74 73 20 61 72 65 20 6b 65  s objects are ke
cd70: 70 74 20 6f 6e 20 61 20 6c 69 6e 6b 65 64 20 6c  pt on a linked l
cd80: 69 73 74 20 66 6f 72 6d 65 64 20 62 79 0a 2a 2a  ist formed by.**
cd90: 20 74 68 65 20 70 4e 65 78 74 20 70 6f 69 6e 74   the pNext point
cda0: 65 72 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65  er.  The [sqlite
cdb0: 33 5f 76 66 73 5f 72 65 67 69 73 74 65 72 28 29  3_vfs_register()
cdc0: 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65  ].** and [sqlite
cdd0: 33 5f 76 66 73 5f 75 6e 72 65 67 69 73 74 65 72  3_vfs_unregister
cde0: 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 20 6d  ()] interfaces m
cdf0: 61 6e 61 67 65 20 74 68 69 73 20 6c 69 73 74 0a  anage this list.
ce00: 2a 2a 20 69 6e 20 61 20 74 68 72 65 61 64 2d 73  ** in a thread-s
ce10: 61 66 65 20 77 61 79 2e 20 20 54 68 65 20 5b 73  afe way.  The [s
ce20: 71 6c 69 74 65 33 5f 76 66 73 5f 66 69 6e 64 28  qlite3_vfs_find(
ce30: 29 5d 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20  )] interface.** 
ce40: 73 65 61 72 63 68 65 73 20 74 68 65 20 6c 69 73  searches the lis
ce50: 74 2e 20 20 4e 65 69 74 68 65 72 20 74 68 65 20  t.  Neither the 
ce60: 61 70 70 6c 69 63 61 74 69 6f 6e 20 63 6f 64 65  application code
ce70: 20 6e 6f 72 20 74 68 65 20 56 46 53 0a 2a 2a 20   nor the VFS.** 
ce80: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 73  implementation s
ce90: 68 6f 75 6c 64 20 75 73 65 20 74 68 65 20 70 4e  hould use the pN
cea0: 65 78 74 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a  ext pointer..**.
ceb0: 2a 2a 20 54 68 65 20 70 4e 65 78 74 20 66 69 65  ** The pNext fie
cec0: 6c 64 20 69 73 20 74 68 65 20 6f 6e 6c 79 20 66  ld is the only f
ced0: 69 65 6c 64 20 69 6e 20 74 68 65 20 73 71 6c 69  ield in the sqli
cee0: 74 65 33 5f 76 66 73 0a 2a 2a 20 73 74 72 75 63  te3_vfs.** struc
cef0: 74 75 72 65 20 74 68 61 74 20 53 51 4c 69 74 65  ture that SQLite
cf00: 20 77 69 6c 6c 20 65 76 65 72 20 6d 6f 64 69 66   will ever modif
cf10: 79 2e 20 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  y.  SQLite will 
cf20: 6f 6e 6c 79 20 61 63 63 65 73 73 0a 2a 2a 20 6f  only access.** o
cf30: 72 20 6d 6f 64 69 66 79 20 74 68 69 73 20 66 69  r modify this fi
cf40: 65 6c 64 20 77 68 69 6c 65 20 68 6f 6c 64 69 6e  eld while holdin
cf50: 67 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 73  g a particular s
cf60: 74 61 74 69 63 20 6d 75 74 65 78 2e 0a 2a 2a 20  tatic mutex..** 
cf70: 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  The application 
cf80: 73 68 6f 75 6c 64 20 6e 65 76 65 72 20 6d 6f 64  should never mod
cf90: 69 66 79 20 61 6e 79 74 68 69 6e 67 20 77 69 74  ify anything wit
cfa0: 68 69 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f  hin the sqlite3_
cfb0: 76 66 73 0a 2a 2a 20 6f 62 6a 65 63 74 20 6f 6e  vfs.** object on
cfc0: 63 65 20 74 68 65 20 6f 62 6a 65 63 74 20 68 61  ce the object ha
cfd0: 73 20 62 65 65 6e 20 72 65 67 69 73 74 65 72 65  s been registere
cfe0: 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 7a 4e 61  d..**.** The zNa
cff0: 6d 65 20 66 69 65 6c 64 20 68 6f 6c 64 73 20 74  me field holds t
d000: 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 56  he name of the V
d010: 46 53 20 6d 6f 64 75 6c 65 2e 20 20 54 68 65 20  FS module.  The 
d020: 6e 61 6d 65 20 6d 75 73 74 0a 2a 2a 20 62 65 20  name must.** be 
d030: 75 6e 69 71 75 65 20 61 63 72 6f 73 73 20 61 6c  unique across al
d040: 6c 20 56 46 53 20 6d 6f 64 75 6c 65 73 2e 0a 2a  l VFS modules..*
d050: 2a 0a 2a 2a 20 5b 5b 73 71 6c 69 74 65 33 5f 76  *.** [[sqlite3_v
d060: 66 73 2e 78 4f 70 65 6e 5d 5d 0a 2a 2a 20 5e 53  fs.xOpen]].** ^S
d070: 51 4c 69 74 65 20 67 75 61 72 61 6e 74 65 65 73  QLite guarantees
d080: 20 74 68 61 74 20 74 68 65 20 7a 46 69 6c 65 6e   that the zFilen
d090: 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ame parameter to
d0a0: 20 78 4f 70 65 6e 0a 2a 2a 20 69 73 20 65 69 74   xOpen.** is eit
d0b0: 68 65 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  her a NULL point
d0c0: 65 72 20 6f 72 20 73 74 72 69 6e 67 20 6f 62 74  er or string obt
d0d0: 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 78 46  ained.** from xF
d0e0: 75 6c 6c 50 61 74 68 6e 61 6d 65 28 29 20 77 69  ullPathname() wi
d0f0: 74 68 20 61 6e 20 6f 70 74 69 6f 6e 61 6c 20 73  th an optional s
d100: 75 66 66 69 78 20 61 64 64 65 64 2e 0a 2a 2a 20  uffix added..** 
d110: 5e 49 66 20 61 20 73 75 66 66 69 78 20 69 73 20  ^If a suffix is 
d120: 61 64 64 65 64 20 74 6f 20 74 68 65 20 7a 46 69  added to the zFi
d130: 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72  lename parameter
d140: 2c 20 69 74 20 77 69 6c 6c 0a 2a 2a 20 63 6f 6e  , it will.** con
d150: 73 69 73 74 20 6f 66 20 61 20 73 69 6e 67 6c 65  sist of a single
d160: 20 22 2d 22 20 63 68 61 72 61 63 74 65 72 20 66   "-" character f
d170: 6f 6c 6c 6f 77 65 64 20 62 79 20 6e 6f 20 6d 6f  ollowed by no mo
d180: 72 65 20 74 68 61 6e 0a 2a 2a 20 31 31 20 61 6c  re than.** 11 al
d190: 70 68 61 6e 75 6d 65 72 69 63 20 61 6e 64 2f 6f  phanumeric and/o
d1a0: 72 20 22 2d 22 20 63 68 61 72 61 63 74 65 72 73  r "-" characters
d1b0: 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 66 75 72  ..** ^SQLite fur
d1c0: 74 68 65 72 20 67 75 61 72 61 6e 74 65 65 73 20  ther guarantees 
d1d0: 74 68 61 74 0a 2a 2a 20 74 68 65 20 73 74 72 69  that.** the stri
d1e0: 6e 67 20 77 69 6c 6c 20 62 65 20 76 61 6c 69 64  ng will be valid
d1f0: 20 61 6e 64 20 75 6e 63 68 61 6e 67 65 64 20 75   and unchanged u
d200: 6e 74 69 6c 20 78 43 6c 6f 73 65 28 29 20 69 73  ntil xClose() is
d210: 0a 2a 2a 20 63 61 6c 6c 65 64 2e 20 42 65 63 61  .** called. Beca
d220: 75 73 65 20 6f 66 20 74 68 65 20 70 72 65 76 69  use of the previ
d230: 6f 75 73 20 73 65 6e 74 65 6e 63 65 2c 0a 2a 2a  ous sentence,.**
d240: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69   the [sqlite3_fi
d250: 6c 65 5d 20 63 61 6e 20 73 61 66 65 6c 79 20 73  le] can safely s
d260: 74 6f 72 65 20 61 20 70 6f 69 6e 74 65 72 20 74  tore a pointer t
d270: 6f 20 74 68 65 0a 2a 2a 20 66 69 6c 65 6e 61 6d  o the.** filenam
d280: 65 20 69 66 20 69 74 20 6e 65 65 64 73 20 74 6f  e if it needs to
d290: 20 72 65 6d 65 6d 62 65 72 20 74 68 65 20 66 69   remember the fi
d2a0: 6c 65 6e 61 6d 65 20 66 6f 72 20 73 6f 6d 65 20  lename for some 
d2b0: 72 65 61 73 6f 6e 2e 0a 2a 2a 20 49 66 20 74 68  reason..** If th
d2c0: 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72 61  e zFilename para
d2d0: 6d 65 74 65 72 20 74 6f 20 78 4f 70 65 6e 20 69  meter to xOpen i
d2e0: 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
d2f0: 20 74 68 65 6e 20 78 4f 70 65 6e 0a 2a 2a 20 6d   then xOpen.** m
d300: 75 73 74 20 69 6e 76 65 6e 74 20 69 74 73 20 6f  ust invent its o
d310: 77 6e 20 74 65 6d 70 6f 72 61 72 79 20 6e 61 6d  wn temporary nam
d320: 65 20 66 6f 72 20 74 68 65 20 66 69 6c 65 2e 20  e for the file. 
d330: 20 5e 57 68 65 6e 65 76 65 72 20 74 68 65 20 0a   ^Whenever the .
d340: 2a 2a 20 78 46 69 6c 65 6e 61 6d 65 20 70 61 72  ** xFilename par
d350: 61 6d 65 74 65 72 20 69 73 20 4e 55 4c 4c 20 69  ameter is NULL i
d360: 74 20 77 69 6c 6c 20 61 6c 73 6f 20 62 65 20 74  t will also be t
d370: 68 65 20 63 61 73 65 20 74 68 61 74 20 74 68 65  he case that the
d380: 0a 2a 2a 20 66 6c 61 67 73 20 70 61 72 61 6d 65  .** flags parame
d390: 74 65 72 20 77 69 6c 6c 20 69 6e 63 6c 75 64 65  ter will include
d3a0: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45   [SQLITE_OPEN_DE
d3b0: 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 2e 0a 2a 2a  LETEONCLOSE]..**
d3c0: 0a 2a 2a 20 54 68 65 20 66 6c 61 67 73 20 61 72  .** The flags ar
d3d0: 67 75 6d 65 6e 74 20 74 6f 20 78 4f 70 65 6e 28  gument to xOpen(
d3e0: 29 20 69 6e 63 6c 75 64 65 73 20 61 6c 6c 20 62  ) includes all b
d3f0: 69 74 73 20 73 65 74 20 69 6e 0a 2a 2a 20 74 68  its set in.** th
d400: 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74  e flags argument
d410: 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65   to [sqlite3_ope
d420: 6e 5f 76 32 28 29 5d 2e 20 20 4f 72 20 69 66 20  n_v2()].  Or if 
d430: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d  [sqlite3_open()]
d440: 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  .** or [sqlite3_
d450: 6f 70 65 6e 31 36 28 29 5d 20 69 73 20 75 73 65  open16()] is use
d460: 64 2c 20 74 68 65 6e 20 66 6c 61 67 73 20 69 6e  d, then flags in
d470: 63 6c 75 64 65 73 20 61 74 20 6c 65 61 73 74 0a  cludes at least.
d480: 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ** [SQLITE_OPEN_
d490: 52 45 41 44 57 52 49 54 45 5d 20 7c 20 5b 53 51  READWRITE] | [SQ
d4a0: 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45  LITE_OPEN_CREATE
d4b0: 5d 2e 20 0a 2a 2a 20 49 66 20 78 4f 70 65 6e 28  ]. .** If xOpen(
d4c0: 29 20 6f 70 65 6e 73 20 61 20 66 69 6c 65 20 72  ) opens a file r
d4d0: 65 61 64 2d 6f 6e 6c 79 20 74 68 65 6e 20 69 74  ead-only then it
d4e0: 20 73 65 74 73 20 2a 70 4f 75 74 46 6c 61 67 73   sets *pOutFlags
d4f0: 20 74 6f 0a 2a 2a 20 69 6e 63 6c 75 64 65 20 5b   to.** include [
d500: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44  SQLITE_OPEN_READ
d510: 4f 4e 4c 59 5d 2e 20 20 4f 74 68 65 72 20 62 69  ONLY].  Other bi
d520: 74 73 20 69 6e 20 2a 70 4f 75 74 46 6c 61 67 73  ts in *pOutFlags
d530: 20 6d 61 79 20 62 65 20 73 65 74 2e 0a 2a 2a 0a   may be set..**.
d540: 2a 2a 20 5e 28 53 51 4c 69 74 65 20 77 69 6c 6c  ** ^(SQLite will
d550: 20 61 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66   also add one of
d560: 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66   the following f
d570: 6c 61 67 73 20 74 6f 20 74 68 65 20 78 4f 70 65  lags to the xOpe
d580: 6e 28 29 0a 2a 2a 20 63 61 6c 6c 2c 20 64 65 70  n().** call, dep
d590: 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 6f 62  ending on the ob
d5a0: 6a 65 63 74 20 62 65 69 6e 67 20 6f 70 65 6e 65  ject being opene
d5b0: 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  d:.**.** <ul>.**
d5c0: 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f   <li>  [SQLITE_O
d5d0: 50 45 4e 5f 4d 41 49 4e 5f 44 42 5d 0a 2a 2a 20  PEN_MAIN_DB].** 
d5e0: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50  <li>  [SQLITE_OP
d5f0: 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c 5d  EN_MAIN_JOURNAL]
d600: 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54  .** <li>  [SQLIT
d610: 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 5d 0a  E_OPEN_TEMP_DB].
d620: 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45  ** <li>  [SQLITE
d630: 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e  _OPEN_TEMP_JOURN
d640: 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51  AL].** <li>  [SQ
d650: 4c 49 54 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49  LITE_OPEN_TRANSI
d660: 45 4e 54 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20  ENT_DB].** <li> 
d670: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 55   [SQLITE_OPEN_SU
d680: 42 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69  BJOURNAL].** <li
d690: 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  >  [SQLITE_OPEN_
d6a0: 4d 41 53 54 45 52 5f 4a 4f 55 52 4e 41 4c 5d 0a  MASTER_JOURNAL].
d6b0: 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45  ** <li>  [SQLITE
d6c0: 5f 4f 50 45 4e 5f 57 41 4c 5d 0a 2a 2a 20 3c 2f  _OPEN_WAL].** </
d6d0: 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ul>)^.**.** The 
d6e0: 66 69 6c 65 20 49 2f 4f 20 69 6d 70 6c 65 6d 65  file I/O impleme
d6f0: 6e 74 61 74 69 6f 6e 20 63 61 6e 20 75 73 65 20  ntation can use 
d700: 74 68 65 20 6f 62 6a 65 63 74 20 74 79 70 65 20  the object type 
d710: 66 6c 61 67 73 20 74 6f 0a 2a 2a 20 63 68 61 6e  flags to.** chan
d720: 67 65 20 74 68 65 20 77 61 79 20 69 74 20 64 65  ge the way it de
d730: 61 6c 73 20 77 69 74 68 20 66 69 6c 65 73 2e 20  als with files. 
d740: 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 61 6e   For example, an
d750: 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20   application.** 
d760: 74 68 61 74 20 64 6f 65 73 20 6e 6f 74 20 63 61  that does not ca
d770: 72 65 20 61 62 6f 75 74 20 63 72 61 73 68 20 72  re about crash r
d780: 65 63 6f 76 65 72 79 20 6f 72 20 72 6f 6c 6c 62  ecovery or rollb
d790: 61 63 6b 20 6d 69 67 68 74 20 6d 61 6b 65 0a 2a  ack might make.*
d7a0: 2a 20 74 68 65 20 6f 70 65 6e 20 6f 66 20 61 20  * the open of a 
d7b0: 6a 6f 75 72 6e 61 6c 20 66 69 6c 65 20 61 20 6e  journal file a n
d7c0: 6f 2d 6f 70 2e 20 20 57 72 69 74 65 73 20 74 6f  o-op.  Writes to
d7d0: 20 74 68 69 73 20 6a 6f 75 72 6e 61 6c 20 77 6f   this journal wo
d7e0: 75 6c 64 0a 2a 2a 20 61 6c 73 6f 20 62 65 20 6e  uld.** also be n
d7f0: 6f 2d 6f 70 73 2c 20 61 6e 64 20 61 6e 79 20 61  o-ops, and any a
d800: 74 74 65 6d 70 74 20 74 6f 20 72 65 61 64 20 74  ttempt to read t
d810: 68 65 20 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c 64  he journal would
d820: 20 72 65 74 75 72 6e 0a 2a 2a 20 53 51 4c 49 54   return.** SQLIT
d830: 45 5f 49 4f 45 52 52 2e 20 20 4f 72 20 74 68 65  E_IOERR.  Or the
d840: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
d850: 6d 69 67 68 74 20 72 65 63 6f 67 6e 69 7a 65 20  might recognize 
d860: 74 68 61 74 20 61 20 64 61 74 61 62 61 73 65 0a  that a database.
d870: 2a 2a 20 66 69 6c 65 20 77 69 6c 6c 20 62 65 20  ** file will be 
d880: 64 6f 69 6e 67 20 70 61 67 65 2d 61 6c 69 67 6e  doing page-align
d890: 65 64 20 73 65 63 74 6f 72 20 72 65 61 64 73 20  ed sector reads 
d8a0: 61 6e 64 20 77 72 69 74 65 73 20 69 6e 20 61 20  and writes in a 
d8b0: 72 61 6e 64 6f 6d 0a 2a 2a 20 6f 72 64 65 72 20  random.** order 
d8c0: 61 6e 64 20 73 65 74 20 75 70 20 69 74 73 20 49  and set up its I
d8d0: 2f 4f 20 73 75 62 73 79 73 74 65 6d 20 61 63 63  /O subsystem acc
d8e0: 6f 72 64 69 6e 67 6c 79 2e 0a 2a 2a 0a 2a 2a 20  ordingly..**.** 
d8f0: 53 51 4c 69 74 65 20 6d 69 67 68 74 20 61 6c 73  SQLite might als
d900: 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20 74 68 65  o add one of the
d910: 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61 67 73   following flags
d920: 20 74 6f 20 74 68 65 20 78 4f 70 65 6e 20 6d 65   to the xOpen me
d930: 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  thod:.**.** <ul>
d940: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
d950: 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c  _OPEN_DELETEONCL
d960: 4f 53 45 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  OSE].** <li> [SQ
d970: 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53  LITE_OPEN_EXCLUS
d980: 49 56 45 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a  IVE].** </ul>.**
d990: 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  .** The [SQLITE_
d9a0: 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f  OPEN_DELETEONCLO
d9b0: 53 45 5d 20 66 6c 61 67 20 6d 65 61 6e 73 20 74  SE] flag means t
d9c0: 68 65 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 62  he file should b
d9d0: 65 0a 2a 2a 20 64 65 6c 65 74 65 64 20 77 68 65  e.** deleted whe
d9e0: 6e 20 69 74 20 69 73 20 63 6c 6f 73 65 64 2e 20  n it is closed. 
d9f0: 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50   ^The [SQLITE_OP
da00: 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45  EN_DELETEONCLOSE
da10: 5d 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 73 65 74  ].** will be set
da20: 20 66 6f 72 20 54 45 4d 50 20 64 61 74 61 62 61   for TEMP databa
da30: 73 65 73 20 61 6e 64 20 74 68 65 69 72 20 6a 6f  ses and their jo
da40: 75 72 6e 61 6c 73 2c 20 74 72 61 6e 73 69 65 6e  urnals, transien
da50: 74 0a 2a 2a 20 64 61 74 61 62 61 73 65 73 2c 20  t.** databases, 
da60: 61 6e 64 20 73 75 62 6a 6f 75 72 6e 61 6c 73 2e  and subjournals.
da70: 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c  .**.** ^The [SQL
da80: 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49  ITE_OPEN_EXCLUSI
da90: 56 45 5d 20 66 6c 61 67 20 69 73 20 61 6c 77 61  VE] flag is alwa
daa0: 79 73 20 75 73 65 64 20 69 6e 20 63 6f 6e 6a 75  ys used in conju
dab0: 6e 63 74 69 6f 6e 0a 2a 2a 20 77 69 74 68 20 74  nction.** with t
dac0: 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  he [SQLITE_OPEN_
dad0: 43 52 45 41 54 45 5d 20 66 6c 61 67 2c 20 77 68  CREATE] flag, wh
dae0: 69 63 68 20 61 72 65 20 62 6f 74 68 20 64 69 72  ich are both dir
daf0: 65 63 74 6c 79 0a 2a 2a 20 61 6e 61 6c 6f 67 6f  ectly.** analogo
db00: 75 73 20 74 6f 20 74 68 65 20 4f 5f 45 58 43 4c  us to the O_EXCL
db10: 20 61 6e 64 20 4f 5f 43 52 45 41 54 20 66 6c 61   and O_CREAT fla
db20: 67 73 20 6f 66 20 74 68 65 20 50 4f 53 49 58 20  gs of the POSIX 
db30: 6f 70 65 6e 28 29 0a 2a 2a 20 41 50 49 2e 20 20  open().** API.  
db40: 54 68 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  The SQLITE_OPEN_
db50: 45 58 43 4c 55 53 49 56 45 20 66 6c 61 67 2c 20  EXCLUSIVE flag, 
db60: 77 68 65 6e 20 70 61 69 72 65 64 20 77 69 74 68  when paired with
db70: 20 74 68 65 20 0a 2a 2a 20 53 51 4c 49 54 45 5f   the .** SQLITE_
db80: 4f 50 45 4e 5f 43 52 45 41 54 45 2c 20 69 73 20  OPEN_CREATE, is 
db90: 75 73 65 64 20 74 6f 20 69 6e 64 69 63 61 74 65  used to indicate
dba0: 20 74 68 61 74 20 66 69 6c 65 20 73 68 6f 75 6c   that file shoul
dbb0: 64 20 61 6c 77 61 79 73 0a 2a 2a 20 62 65 20 63  d always.** be c
dbc0: 72 65 61 74 65 64 2c 20 61 6e 64 20 74 68 61 74  reated, and that
dbd0: 20 69 74 20 69 73 20 61 6e 20 65 72 72 6f 72 20   it is an error 
dbe0: 69 66 20 69 74 20 61 6c 72 65 61 64 79 20 65 78  if it already ex
dbf0: 69 73 74 73 2e 0a 2a 2a 20 49 74 20 69 73 20 3c  ists..** It is <
dc00: 69 3e 6e 6f 74 3c 2f 69 3e 20 75 73 65 64 20 74  i>not</i> used t
dc10: 6f 20 69 6e 64 69 63 61 74 65 20 74 68 65 20 66  o indicate the f
dc20: 69 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 6f 70  ile should be op
dc30: 65 6e 65 64 20 0a 2a 2a 20 66 6f 72 20 65 78 63  ened .** for exc
dc40: 6c 75 73 69 76 65 20 61 63 63 65 73 73 2e 0a 2a  lusive access..*
dc50: 2a 0a 2a 2a 20 5e 41 74 20 6c 65 61 73 74 20 73  *.** ^At least s
dc60: 7a 4f 73 46 69 6c 65 20 62 79 74 65 73 20 6f 66  zOsFile bytes of
dc70: 20 6d 65 6d 6f 72 79 20 61 72 65 20 61 6c 6c 6f   memory are allo
dc80: 63 61 74 65 64 20 62 79 20 53 51 4c 69 74 65 0a  cated by SQLite.
dc90: 2a 2a 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 20  ** to hold the  
dca0: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 73  [sqlite3_file] s
dcb0: 74 72 75 63 74 75 72 65 20 70 61 73 73 65 64 20  tructure passed 
dcc0: 61 73 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20  as the third.** 
dcd0: 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 4f 70 65  argument to xOpe
dce0: 6e 2e 20 20 54 68 65 20 78 4f 70 65 6e 20 6d 65  n.  The xOpen me
dcf0: 74 68 6f 64 20 64 6f 65 73 20 6e 6f 74 20 68 61  thod does not ha
dd00: 76 65 20 74 6f 0a 2a 2a 20 61 6c 6c 6f 63 61 74  ve to.** allocat
dd10: 65 20 74 68 65 20 73 74 72 75 63 74 75 72 65 3b  e the structure;
dd20: 20 69 74 20 73 68 6f 75 6c 64 20 6a 75 73 74 20   it should just 
dd30: 66 69 6c 6c 20 69 74 20 69 6e 2e 20 20 4e 6f 74  fill it in.  Not
dd40: 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 78 4f  e that.** the xO
dd50: 70 65 6e 20 6d 65 74 68 6f 64 20 6d 75 73 74 20  pen method must 
dd60: 73 65 74 20 74 68 65 20 73 71 6c 69 74 65 33 5f  set the sqlite3_
dd70: 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20 74 6f  file.pMethods to
dd80: 20 65 69 74 68 65 72 0a 2a 2a 20 61 20 76 61 6c   either.** a val
dd90: 69 64 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  id [sqlite3_io_m
dda0: 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 6f  ethods] object o
ddb0: 72 20 74 6f 20 4e 55 4c 4c 2e 20 20 78 4f 70 65  r to NULL.  xOpe
ddc0: 6e 20 6d 75 73 74 20 64 6f 0a 2a 2a 20 74 68 69  n must do.** thi
ddd0: 73 20 65 76 65 6e 20 69 66 20 74 68 65 20 6f 70  s even if the op
dde0: 65 6e 20 66 61 69 6c 73 2e 20 20 53 51 4c 69 74  en fails.  SQLit
ddf0: 65 20 65 78 70 65 63 74 73 20 74 68 61 74 20 74  e expects that t
de00: 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e  he sqlite3_file.
de10: 70 4d 65 74 68 6f 64 73 0a 2a 2a 20 65 6c 65 6d  pMethods.** elem
de20: 65 6e 74 20 77 69 6c 6c 20 62 65 20 76 61 6c 69  ent will be vali
de30: 64 20 61 66 74 65 72 20 78 4f 70 65 6e 20 72 65  d after xOpen re
de40: 74 75 72 6e 73 20 72 65 67 61 72 64 6c 65 73 73  turns regardless
de50: 20 6f 66 20 74 68 65 20 73 75 63 63 65 73 73 0a   of the success.
de60: 2a 2a 20 6f 72 20 66 61 69 6c 75 72 65 20 6f 66  ** or failure of
de70: 20 74 68 65 20 78 4f 70 65 6e 20 63 61 6c 6c 2e   the xOpen call.
de80: 0a 2a 2a 0a 2a 2a 20 5b 5b 73 71 6c 69 74 65 33  .**.** [[sqlite3
de90: 5f 76 66 73 2e 78 41 63 63 65 73 73 5d 5d 0a 2a  _vfs.xAccess]].*
dea0: 2a 20 5e 54 68 65 20 66 6c 61 67 73 20 61 72 67  * ^The flags arg
deb0: 75 6d 65 6e 74 20 74 6f 20 78 41 63 63 65 73 73  ument to xAccess
dec0: 28 29 20 6d 61 79 20 62 65 20 5b 53 51 4c 49 54  () may be [SQLIT
ded0: 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53 5d  E_ACCESS_EXISTS]
dee0: 0a 2a 2a 20 74 6f 20 74 65 73 74 20 66 6f 72 20  .** to test for 
def0: 74 68 65 20 65 78 69 73 74 65 6e 63 65 20 6f 66  the existence of
df00: 20 61 20 66 69 6c 65 2c 20 6f 72 20 5b 53 51 4c   a file, or [SQL
df10: 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57  ITE_ACCESS_READW
df20: 52 49 54 45 5d 20 74 6f 0a 2a 2a 20 74 65 73 74  RITE] to.** test
df30: 20 77 68 65 74 68 65 72 20 61 20 66 69 6c 65 20   whether a file 
df40: 69 73 20 72 65 61 64 61 62 6c 65 20 61 6e 64 20  is readable and 
df50: 77 72 69 74 61 62 6c 65 2c 20 6f 72 20 5b 53 51  writable, or [SQ
df60: 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44  LITE_ACCESS_READ
df70: 5d 0a 2a 2a 20 74 6f 20 74 65 73 74 20 77 68 65  ].** to test whe
df80: 74 68 65 72 20 61 20 66 69 6c 65 20 69 73 20 61  ther a file is a
df90: 74 20 6c 65 61 73 74 20 72 65 61 64 61 62 6c 65  t least readable
dfa0: 2e 20 20 20 54 68 65 20 66 69 6c 65 20 63 61 6e  .   The file can
dfb0: 20 62 65 20 61 0a 2a 2a 20 64 69 72 65 63 74 6f   be a.** directo
dfc0: 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74  ry..**.** ^SQLit
dfd0: 65 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 61 6c  e will always al
dfe0: 6c 6f 63 61 74 65 20 61 74 20 6c 65 61 73 74 20  locate at least 
dff0: 6d 78 50 61 74 68 6e 61 6d 65 2b 31 20 62 79 74  mxPathname+1 byt
e000: 65 73 20 66 6f 72 20 74 68 65 0a 2a 2a 20 6f 75  es for the.** ou
e010: 74 70 75 74 20 62 75 66 66 65 72 20 78 46 75 6c  tput buffer xFul
e020: 6c 50 61 74 68 6e 61 6d 65 2e 20 20 54 68 65 20  lPathname.  The 
e030: 65 78 61 63 74 20 73 69 7a 65 20 6f 66 20 74 68  exact size of th
e040: 65 20 6f 75 74 70 75 74 20 62 75 66 66 65 72 0a  e output buffer.
e050: 2a 2a 20 69 73 20 61 6c 73 6f 20 70 61 73 73 65  ** is also passe
e060: 64 20 61 73 20 61 20 70 61 72 61 6d 65 74 65 72  d as a parameter
e070: 20 74 6f 20 62 6f 74 68 20 20 6d 65 74 68 6f 64   to both  method
e080: 73 2e 20 49 66 20 74 68 65 20 6f 75 74 70 75 74  s. If the output
e090: 20 62 75 66 66 65 72 0a 2a 2a 20 69 73 20 6e 6f   buffer.** is no
e0a0: 74 20 6c 61 72 67 65 20 65 6e 6f 75 67 68 2c 20  t large enough, 
e0b0: 5b 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e  [SQLITE_CANTOPEN
e0c0: 5d 20 73 68 6f 75 6c 64 20 62 65 20 72 65 74 75  ] should be retu
e0d0: 72 6e 65 64 2e 20 53 69 6e 63 65 20 74 68 69 73  rned. Since this
e0e0: 20 69 73 0a 2a 2a 20 68 61 6e 64 6c 65 64 20 61   is.** handled a
e0f0: 73 20 61 20 66 61 74 61 6c 20 65 72 72 6f 72 20  s a fatal error 
e100: 62 79 20 53 51 4c 69 74 65 2c 20 76 66 73 20 69  by SQLite, vfs i
e110: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 73  mplementations s
e120: 68 6f 75 6c 64 20 65 6e 64 65 61 76 6f 72 0a 2a  hould endeavor.*
e130: 2a 20 74 6f 20 70 72 65 76 65 6e 74 20 74 68 69  * to prevent thi
e140: 73 20 62 79 20 73 65 74 74 69 6e 67 20 6d 78 50  s by setting mxP
e150: 61 74 68 6e 61 6d 65 20 74 6f 20 61 20 73 75 66  athname to a suf
e160: 66 69 63 69 65 6e 74 6c 79 20 6c 61 72 67 65 20  ficiently large 
e170: 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  value..**.** The
e180: 20 78 52 61 6e 64 6f 6d 6e 65 73 73 28 29 2c 20   xRandomness(), 
e190: 78 53 6c 65 65 70 28 29 2c 20 78 43 75 72 72 65  xSleep(), xCurre
e1a0: 6e 74 54 69 6d 65 28 29 2c 20 61 6e 64 20 78 43  ntTime(), and xC
e1b0: 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28  urrentTimeInt64(
e1c0: 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20  ).** interfaces 
e1d0: 61 72 65 20 6e 6f 74 20 73 74 72 69 63 74 6c 79  are not strictly
e1e0: 20 61 20 70 61 72 74 20 6f 66 20 74 68 65 20 66   a part of the f
e1f0: 69 6c 65 73 79 73 74 65 6d 2c 20 62 75 74 20 74  ilesystem, but t
e200: 68 65 79 20 61 72 65 0a 2a 2a 20 69 6e 63 6c 75  hey are.** inclu
e210: 64 65 64 20 69 6e 20 74 68 65 20 56 46 53 20 73  ded in the VFS s
e220: 74 72 75 63 74 75 72 65 20 66 6f 72 20 63 6f 6d  tructure for com
e230: 70 6c 65 74 65 6e 65 73 73 2e 0a 2a 2a 20 54 68  pleteness..** Th
e240: 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 28 29 20  e xRandomness() 
e250: 66 75 6e 63 74 69 6f 6e 20 61 74 74 65 6d 70 74  function attempt
e260: 73 20 74 6f 20 72 65 74 75 72 6e 20 6e 42 79 74  s to return nByt
e270: 65 73 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 67  es bytes.** of g
e280: 6f 6f 64 2d 71 75 61 6c 69 74 79 20 72 61 6e 64  ood-quality rand
e290: 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 7a 4f 75 74  omness into zOut
e2a0: 2e 20 20 54 68 65 20 72 65 74 75 72 6e 20 76 61  .  The return va
e2b0: 6c 75 65 20 69 73 0a 2a 2a 20 74 68 65 20 61 63  lue is.** the ac
e2c0: 74 75 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20 62  tual number of b
e2d0: 79 74 65 73 20 6f 66 20 72 61 6e 64 6f 6d 6e 65  ytes of randomne
e2e0: 73 73 20 6f 62 74 61 69 6e 65 64 2e 0a 2a 2a 20  ss obtained..** 
e2f0: 54 68 65 20 78 53 6c 65 65 70 28 29 20 6d 65 74  The xSleep() met
e300: 68 6f 64 20 63 61 75 73 65 73 20 74 68 65 20 63  hod causes the c
e310: 61 6c 6c 69 6e 67 20 74 68 72 65 61 64 20 74 6f  alling thread to
e320: 20 73 6c 65 65 70 20 66 6f 72 20 61 74 0a 2a 2a   sleep for at.**
e330: 20 6c 65 61 73 74 20 74 68 65 20 6e 75 6d 62 65   least the numbe
e340: 72 20 6f 66 20 6d 69 63 72 6f 73 65 63 6f 6e 64  r of microsecond
e350: 73 20 67 69 76 65 6e 2e 20 20 5e 54 68 65 20 78  s given.  ^The x
e360: 43 75 72 72 65 6e 74 54 69 6d 65 28 29 0a 2a 2a  CurrentTime().**
e370: 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20   method returns 
e380: 61 20 4a 75 6c 69 61 6e 20 44 61 79 20 4e 75 6d  a Julian Day Num
e390: 62 65 72 20 66 6f 72 20 74 68 65 20 63 75 72 72  ber for the curr
e3a0: 65 6e 74 20 64 61 74 65 20 61 6e 64 20 74 69 6d  ent date and tim
e3b0: 65 20 61 73 0a 2a 2a 20 61 20 66 6c 6f 61 74 69  e as.** a floati
e3c0: 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 2e 0a  ng point value..
e3d0: 2a 2a 20 5e 54 68 65 20 78 43 75 72 72 65 6e 74  ** ^The xCurrent
e3e0: 54 69 6d 65 49 6e 74 36 34 28 29 20 6d 65 74 68  TimeInt64() meth
e3f0: 6f 64 20 72 65 74 75 72 6e 73 2c 20 61 73 20 61  od returns, as a
e400: 6e 20 69 6e 74 65 67 65 72 2c 20 74 68 65 20 4a  n integer, the J
e410: 75 6c 69 61 6e 0a 2a 2a 20 44 61 79 20 4e 75 6d  ulian.** Day Num
e420: 62 65 72 20 6d 75 6c 74 69 70 6c 69 65 64 20 62  ber multiplied b
e430: 79 20 38 36 34 30 30 30 30 30 20 28 74 68 65 20  y 86400000 (the 
e440: 6e 75 6d 62 65 72 20 6f 66 20 6d 69 6c 6c 69 73  number of millis
e450: 65 63 6f 6e 64 73 20 69 6e 20 0a 2a 2a 20 61 20  econds in .** a 
e460: 32 34 2d 68 6f 75 72 20 64 61 79 29 2e 20 20 0a  24-hour day).  .
e470: 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20  ** ^SQLite will 
e480: 75 73 65 20 74 68 65 20 78 43 75 72 72 65 6e 74  use the xCurrent
e490: 54 69 6d 65 49 6e 74 36 34 28 29 20 6d 65 74 68  TimeInt64() meth
e4a0: 6f 64 20 74 6f 20 67 65 74 20 74 68 65 20 63 75  od to get the cu
e4b0: 72 72 65 6e 74 0a 2a 2a 20 64 61 74 65 20 61 6e  rrent.** date an
e4c0: 64 20 74 69 6d 65 20 69 66 20 74 68 61 74 20 6d  d time if that m
e4d0: 65 74 68 6f 64 20 69 73 20 61 76 61 69 6c 61 62  ethod is availab
e4e0: 6c 65 20 28 69 66 20 69 56 65 72 73 69 6f 6e 20  le (if iVersion 
e4f0: 69 73 20 32 20 6f 72 20 0a 2a 2a 20 67 72 65 61  is 2 or .** grea
e500: 74 65 72 20 61 6e 64 20 74 68 65 20 66 75 6e 63  ter and the func
e510: 74 69 6f 6e 20 70 6f 69 6e 74 65 72 20 69 73 20  tion pointer is 
e520: 6e 6f 74 20 4e 55 4c 4c 29 20 61 6e 64 20 77 69  not NULL) and wi
e530: 6c 6c 20 66 61 6c 6c 20 62 61 63 6b 0a 2a 2a 20  ll fall back.** 
e540: 74 6f 20 78 43 75 72 72 65 6e 74 54 69 6d 65 28  to xCurrentTime(
e550: 29 20 69 66 20 78 43 75 72 72 65 6e 74 54 69 6d  ) if xCurrentTim
e560: 65 49 6e 74 36 34 28 29 20 69 73 20 75 6e 61 76  eInt64() is unav
e570: 61 69 6c 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e  ailable..**.** ^
e580: 54 68 65 20 78 53 65 74 53 79 73 74 65 6d 43 61  The xSetSystemCa
e590: 6c 6c 28 29 2c 20 78 47 65 74 53 79 73 74 65 6d  ll(), xGetSystem
e5a0: 43 61 6c 6c 28 29 2c 20 61 6e 64 20 78 4e 65 73  Call(), and xNes
e5b0: 74 53 79 73 74 65 6d 43 61 6c 6c 28 29 20 69 6e  tSystemCall() in
e5c0: 74 65 72 66 61 63 65 73 0a 2a 2a 20 61 72 65 20  terfaces.** are 
e5d0: 6e 6f 74 20 75 73 65 64 20 62 79 20 74 68 65 20  not used by the 
e5e0: 53 51 4c 69 74 65 20 63 6f 72 65 2e 20 20 54 68  SQLite core.  Th
e5f0: 65 73 65 20 6f 70 74 69 6f 6e 61 6c 20 69 6e 74  ese optional int
e600: 65 72 66 61 63 65 73 20 61 72 65 20 70 72 6f 76  erfaces are prov
e610: 69 64 65 64 0a 2a 2a 20 62 79 20 73 6f 6d 65 20  ided.** by some 
e620: 56 46 53 65 73 20 74 6f 20 66 61 63 69 6c 69 74  VFSes to facilit
e630: 61 74 65 20 74 65 73 74 69 6e 67 20 6f 66 20 74  ate testing of t
e640: 68 65 20 56 46 53 20 63 6f 64 65 2e 20 42 79 20  he VFS code. By 
e650: 6f 76 65 72 72 69 64 69 6e 67 20 0a 2a 2a 20 73  overriding .** s
e660: 79 73 74 65 6d 20 63 61 6c 6c 73 20 77 69 74 68  ystem calls with
e670: 20 66 75 6e 63 74 69 6f 6e 73 20 75 6e 64 65 72   functions under
e680: 20 69 74 73 20 63 6f 6e 74 72 6f 6c 2c 20 61 20   its control, a 
e690: 74 65 73 74 20 70 72 6f 67 72 61 6d 20 63 61 6e  test program can
e6a0: 0a 2a 2a 20 73 69 6d 75 6c 61 74 65 20 66 61 75  .** simulate fau
e6b0: 6c 74 73 20 61 6e 64 20 65 72 72 6f 72 20 63 6f  lts and error co
e6c0: 6e 64 69 74 69 6f 6e 73 20 74 68 61 74 20 77 6f  nditions that wo
e6d0: 75 6c 64 20 6f 74 68 65 72 77 69 73 65 20 62 65  uld otherwise be
e6e0: 20 64 69 66 66 69 63 75 6c 74 0a 2a 2a 20 6f 72   difficult.** or
e6f0: 20 69 6d 70 6f 73 73 69 62 6c 65 20 74 6f 20 69   impossible to i
e700: 6e 64 75 63 65 2e 20 20 54 68 65 20 73 65 74 20  nduce.  The set 
e710: 6f 66 20 73 79 73 74 65 6d 20 63 61 6c 6c 73 20  of system calls 
e720: 74 68 61 74 20 63 61 6e 20 62 65 20 6f 76 65 72  that can be over
e730: 72 69 64 64 65 6e 0a 2a 2a 20 76 61 72 69 65 73  ridden.** varies
e740: 20 66 72 6f 6d 20 6f 6e 65 20 56 46 53 20 74 6f   from one VFS to
e750: 20 61 6e 6f 74 68 65 72 2c 20 61 6e 64 20 66 72   another, and fr
e760: 6f 6d 20 6f 6e 65 20 76 65 72 73 69 6f 6e 20 6f  om one version o
e770: 66 20 74 68 65 20 73 61 6d 65 20 56 46 53 20 74  f the same VFS t
e780: 6f 20 74 68 65 0a 2a 2a 20 6e 65 78 74 2e 20 20  o the.** next.  
e790: 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61  Applications tha
e7a0: 74 20 75 73 65 20 74 68 65 73 65 20 69 6e 74 65  t use these inte
e7b0: 72 66 61 63 65 73 20 6d 75 73 74 20 62 65 20 70  rfaces must be p
e7c0: 72 65 70 61 72 65 64 20 66 6f 72 20 61 6e 79 0a  repared for any.
e7d0: 2a 2a 20 6f 72 20 61 6c 6c 20 6f 66 20 74 68 65  ** or all of the
e7e0: 73 65 20 69 6e 74 65 72 66 61 63 65 73 20 74 6f  se interfaces to
e7f0: 20 62 65 20 4e 55 4c 4c 20 6f 72 20 66 6f 72 20   be NULL or for 
e800: 74 68 65 69 72 20 62 65 68 61 76 69 6f 72 20 74  their behavior t
e810: 6f 20 63 68 61 6e 67 65 0a 2a 2a 20 66 72 6f 6d  o change.** from
e820: 20 6f 6e 65 20 72 65 6c 65 61 73 65 20 74 6f 20   one release to 
e830: 74 68 65 20 6e 65 78 74 2e 20 20 41 70 70 6c 69  the next.  Appli
e840: 63 61 74 69 6f 6e 73 20 6d 75 73 74 20 6e 6f 74  cations must not
e850: 20 61 74 74 65 6d 70 74 20 74 6f 20 61 63 63 65   attempt to acce
e860: 73 73 0a 2a 2a 20 61 6e 79 20 6f 66 20 74 68 65  ss.** any of the
e870: 73 65 20 6d 65 74 68 6f 64 73 20 69 66 20 74 68  se methods if th
e880: 65 20 69 56 65 72 73 69 6f 6e 20 6f 66 20 74 68  e iVersion of th
e890: 65 20 56 46 53 20 69 73 20 6c 65 73 73 20 74 68  e VFS is less th
e8a0: 61 6e 20 33 2e 0a 2a 2f 0a 74 79 70 65 64 65 66  an 3..*/.typedef
e8b0: 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
e8c0: 76 66 73 20 73 71 6c 69 74 65 33 5f 76 66 73 3b  vfs sqlite3_vfs;
e8d0: 0a 74 79 70 65 64 65 66 20 76 6f 69 64 20 28 2a  .typedef void (*
e8e0: 73 71 6c 69 74 65 33 5f 73 79 73 63 61 6c 6c 5f  sqlite3_syscall_
e8f0: 70 74 72 29 28 76 6f 69 64 29 3b 0a 73 74 72 75  ptr)(void);.stru
e900: 63 74 20 73 71 6c 69 74 65 33 5f 76 66 73 20 7b  ct sqlite3_vfs {
e910: 0a 20 20 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b  .  int iVersion;
e920: 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53              /* S
e930: 74 72 75 63 74 75 72 65 20 76 65 72 73 69 6f 6e  tructure version
e940: 20 6e 75 6d 62 65 72 20 28 63 75 72 72 65 6e 74   number (current
e950: 6c 79 20 33 29 20 2a 2f 0a 20 20 69 6e 74 20 73  ly 3) */.  int s
e960: 7a 4f 73 46 69 6c 65 3b 20 20 20 20 20 20 20 20  zOsFile;        
e970: 20 20 20 20 2f 2a 20 53 69 7a 65 20 6f 66 20 73      /* Size of s
e980: 75 62 63 6c 61 73 73 65 64 20 73 71 6c 69 74 65  ubclassed sqlite
e990: 33 5f 66 69 6c 65 20 2a 2f 0a 20 20 69 6e 74 20  3_file */.  int 
e9a0: 6d 78 50 61 74 68 6e 61 6d 65 3b 20 20 20 20 20  mxPathname;     
e9b0: 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20       /* Maximum 
e9c0: 66 69 6c 65 20 70 61 74 68 6e 61 6d 65 20 6c 65  file pathname le
e9d0: 6e 67 74 68 20 2a 2f 0a 20 20 73 71 6c 69 74 65  ngth */.  sqlite
e9e0: 33 5f 76 66 73 20 2a 70 4e 65 78 74 3b 20 20 20  3_vfs *pNext;   
e9f0: 20 20 20 2f 2a 20 4e 65 78 74 20 72 65 67 69 73     /* Next regis
ea00: 74 65 72 65 64 20 56 46 53 20 2a 2f 0a 20 20 63  tered VFS */.  c
ea10: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65  onst char *zName
ea20: 3b 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20  ;       /* Name 
ea30: 6f 66 20 74 68 69 73 20 76 69 72 74 75 61 6c 20  of this virtual 
ea40: 66 69 6c 65 20 73 79 73 74 65 6d 20 2a 2f 0a 20  file system */. 
ea50: 20 76 6f 69 64 20 2a 70 41 70 70 44 61 74 61 3b   void *pAppData;
ea60: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 50 6f 69            /* Poi
ea70: 6e 74 65 72 20 74 6f 20 61 70 70 6c 69 63 61 74  nter to applicat
ea80: 69 6f 6e 2d 73 70 65 63 69 66 69 63 20 64 61 74  ion-specific dat
ea90: 61 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 4f 70  a */.  int (*xOp
eaa0: 65 6e 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  en)(sqlite3_vfs*
eab0: 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e  , const char *zN
eac0: 61 6d 65 2c 20 73 71 6c 69 74 65 33 5f 66 69 6c  ame, sqlite3_fil
ead0: 65 2a 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20  e*,.            
eae0: 20 20 20 69 6e 74 20 66 6c 61 67 73 2c 20 69 6e     int flags, in
eaf0: 74 20 2a 70 4f 75 74 46 6c 61 67 73 29 3b 0a 20  t *pOutFlags);. 
eb00: 20 69 6e 74 20 28 2a 78 44 65 6c 65 74 65 29 28   int (*xDelete)(
eb10: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f  sqlite3_vfs*, co
eb20: 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c  nst char *zName,
eb30: 20 69 6e 74 20 73 79 6e 63 44 69 72 29 3b 0a 20   int syncDir);. 
eb40: 20 69 6e 74 20 28 2a 78 41 63 63 65 73 73 29 28   int (*xAccess)(
eb50: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f  sqlite3_vfs*, co
eb60: 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c  nst char *zName,
eb70: 20 69 6e 74 20 66 6c 61 67 73 2c 20 69 6e 74 20   int flags, int 
eb80: 2a 70 52 65 73 4f 75 74 29 3b 0a 20 20 69 6e 74  *pResOut);.  int
eb90: 20 28 2a 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65   (*xFullPathname
eba0: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
ebb0: 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
ebc0: 65 2c 20 69 6e 74 20 6e 4f 75 74 2c 20 63 68 61  e, int nOut, cha
ebd0: 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 76 6f 69 64  r *zOut);.  void
ebe0: 20 2a 28 2a 78 44 6c 4f 70 65 6e 29 28 73 71 6c   *(*xDlOpen)(sql
ebf0: 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74  ite3_vfs*, const
ec00: 20 63 68 61 72 20 2a 7a 46 69 6c 65 6e 61 6d 65   char *zFilename
ec10: 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 44 6c 45  );.  void (*xDlE
ec20: 72 72 6f 72 29 28 73 71 6c 69 74 65 33 5f 76 66  rror)(sqlite3_vf
ec30: 73 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 63  s*, int nByte, c
ec40: 68 61 72 20 2a 7a 45 72 72 4d 73 67 29 3b 0a 20  har *zErrMsg);. 
ec50: 20 76 6f 69 64 20 28 2a 28 2a 78 44 6c 53 79 6d   void (*(*xDlSym
ec60: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 76  )(sqlite3_vfs*,v
ec70: 6f 69 64 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  oid*, const char
ec80: 20 2a 7a 53 79 6d 62 6f 6c 29 29 28 76 6f 69 64   *zSymbol))(void
ec90: 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 44 6c 43  );.  void (*xDlC
eca0: 6c 6f 73 65 29 28 73 71 6c 69 74 65 33 5f 76 66  lose)(sqlite3_vf
ecb0: 73 2a 2c 20 76 6f 69 64 2a 29 3b 0a 20 20 69 6e  s*, void*);.  in
ecc0: 74 20 28 2a 78 52 61 6e 64 6f 6d 6e 65 73 73 29  t (*xRandomness)
ecd0: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69  (sqlite3_vfs*, i
ece0: 6e 74 20 6e 42 79 74 65 2c 20 63 68 61 72 20 2a  nt nByte, char *
ecf0: 7a 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78  zOut);.  int (*x
ed00: 53 6c 65 65 70 29 28 73 71 6c 69 74 65 33 5f 76  Sleep)(sqlite3_v
ed10: 66 73 2a 2c 20 69 6e 74 20 6d 69 63 72 6f 73 65  fs*, int microse
ed20: 63 6f 6e 64 73 29 3b 0a 20 20 69 6e 74 20 28 2a  conds);.  int (*
ed30: 78 43 75 72 72 65 6e 74 54 69 6d 65 29 28 73 71  xCurrentTime)(sq
ed40: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 64 6f 75 62  lite3_vfs*, doub
ed50: 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 47  le*);.  int (*xG
ed60: 65 74 4c 61 73 74 45 72 72 6f 72 29 28 73 71 6c  etLastError)(sql
ed70: 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 2c 20  ite3_vfs*, int, 
ed80: 63 68 61 72 20 2a 29 3b 0a 20 20 2f 2a 0a 20 20  char *);.  /*.  
ed90: 2a 2a 20 54 68 65 20 6d 65 74 68 6f 64 73 20 61  ** The methods a
eda0: 62 6f 76 65 20 61 72 65 20 69 6e 20 76 65 72 73  bove are in vers
edb0: 69 6f 6e 20 31 20 6f 66 20 74 68 65 20 73 71 6c  ion 1 of the sql
edc0: 69 74 65 5f 76 66 73 20 6f 62 6a 65 63 74 0a 20  ite_vfs object. 
edd0: 20 2a 2a 20 64 65 66 69 6e 69 74 69 6f 6e 2e 20   ** definition. 
ede0: 20 54 68 6f 73 65 20 74 68 61 74 20 66 6f 6c 6c   Those that foll
edf0: 6f 77 20 61 72 65 20 61 64 64 65 64 20 69 6e 20  ow are added in 
ee00: 76 65 72 73 69 6f 6e 20 32 20 6f 72 20 6c 61 74  version 2 or lat
ee10: 65 72 0a 20 20 2a 2f 0a 20 20 69 6e 74 20 28 2a  er.  */.  int (*
ee20: 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36  xCurrentTimeInt6
ee30: 34 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  4)(sqlite3_vfs*,
ee40: 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 2a 29   sqlite3_int64*)
ee50: 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54 68 65 20  ;.  /*.  ** The 
ee60: 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72  methods above ar
ee70: 65 20 69 6e 20 76 65 72 73 69 6f 6e 73 20 31 20  e in versions 1 
ee80: 61 6e 64 20 32 20 6f 66 20 74 68 65 20 73 71 6c  and 2 of the sql
ee90: 69 74 65 5f 76 66 73 20 6f 62 6a 65 63 74 2e 0a  ite_vfs object..
eea0: 20 20 2a 2a 20 54 68 6f 73 65 20 62 65 6c 6f 77    ** Those below
eeb0: 20 61 72 65 20 66 6f 72 20 76 65 72 73 69 6f 6e   are for version
eec0: 20 33 20 61 6e 64 20 67 72 65 61 74 65 72 2e 0a   3 and greater..
eed0: 20 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 53 65    */.  int (*xSe
eee0: 74 53 79 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c  tSystemCall)(sql
eef0: 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74  ite3_vfs*, const
ef00: 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 73 71   char *zName, sq
ef10: 6c 69 74 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74  lite3_syscall_pt
ef20: 72 29 3b 0a 20 20 73 71 6c 69 74 65 33 5f 73 79  r);.  sqlite3_sy
ef30: 73 63 61 6c 6c 5f 70 74 72 20 28 2a 78 47 65 74  scall_ptr (*xGet
ef40: 53 79 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69  SystemCall)(sqli
ef50: 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20  te3_vfs*, const 
ef60: 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 20 20  char *zName);.  
ef70: 63 6f 6e 73 74 20 63 68 61 72 20 2a 28 2a 78 4e  const char *(*xN
ef80: 65 78 74 53 79 73 74 65 6d 43 61 6c 6c 29 28 73  extSystemCall)(s
ef90: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e  qlite3_vfs*, con
efa0: 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b  st char *zName);
efb0: 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d  .  /*.  ** The m
efc0: 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65  ethods above are
efd0: 20 69 6e 20 76 65 72 73 69 6f 6e 73 20 31 20 74   in versions 1 t
efe0: 68 72 6f 75 67 68 20 33 20 6f 66 20 74 68 65 20  hrough 3 of the 
eff0: 73 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a 65 63  sqlite_vfs objec
f000: 74 2e 0a 20 20 2a 2a 20 4e 65 77 20 66 69 65 6c  t..  ** New fiel
f010: 64 73 20 6d 61 79 20 62 65 20 61 70 70 65 6e 64  ds may be append
f020: 65 64 20 69 6e 20 66 75 74 75 72 65 20 76 65 72  ed in future ver
f030: 73 69 6f 6e 73 2e 20 20 54 68 65 20 69 56 65 72  sions.  The iVer
f040: 73 69 6f 6e 0a 20 20 2a 2a 20 76 61 6c 75 65 20  sion.  ** value 
f050: 77 69 6c 6c 20 69 6e 63 72 65 6d 65 6e 74 20 77  will increment w
f060: 68 65 6e 65 76 65 72 20 74 68 69 73 20 68 61 70  henever this hap
f070: 70 65 6e 73 2e 20 0a 20 20 2a 2f 0a 7d 3b 0a 0a  pens. .  */.};..
f080: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
f090: 46 6c 61 67 73 20 66 6f 72 20 74 68 65 20 78 41  Flags for the xA
f0a0: 63 63 65 73 73 20 56 46 53 20 6d 65 74 68 6f 64  ccess VFS method
f0b0: 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74  .**.** These int
f0c0: 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 20 63  eger constants c
f0d0: 61 6e 20 62 65 20 75 73 65 64 20 61 73 20 74 68  an be used as th
f0e0: 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  e third paramete
f0f0: 72 20 74 6f 0a 2a 2a 20 74 68 65 20 78 41 63 63  r to.** the xAcc
f100: 65 73 73 20 6d 65 74 68 6f 64 20 6f 66 20 61 6e  ess method of an
f110: 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f   [sqlite3_vfs] o
f120: 62 6a 65 63 74 2e 20 20 54 68 65 79 20 64 65 74  bject.  They det
f130: 65 72 6d 69 6e 65 0a 2a 2a 20 77 68 61 74 20 6b  ermine.** what k
f140: 69 6e 64 20 6f 66 20 70 65 72 6d 69 73 73 69 6f  ind of permissio
f150: 6e 73 20 74 68 65 20 78 41 63 63 65 73 73 20 6d  ns the xAccess m
f160: 65 74 68 6f 64 20 69 73 20 6c 6f 6f 6b 69 6e 67  ethod is looking
f170: 20 66 6f 72 2e 0a 2a 2a 20 57 69 74 68 20 53 51   for..** With SQ
f180: 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49 53  LITE_ACCESS_EXIS
f190: 54 53 2c 20 74 68 65 20 78 41 63 63 65 73 73 20  TS, the xAccess 
f1a0: 6d 65 74 68 6f 64 0a 2a 2a 20 73 69 6d 70 6c 79  method.** simply
f1b0: 20 63 68 65 63 6b 73 20 77 68 65 74 68 65 72 20   checks whether 
f1c0: 74 68 65 20 66 69 6c 65 20 65 78 69 73 74 73 2e  the file exists.
f1d0: 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45 5f  .** With SQLITE_
f1e0: 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 45  ACCESS_READWRITE
f1f0: 2c 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65  , the xAccess me
f200: 74 68 6f 64 0a 2a 2a 20 63 68 65 63 6b 73 20 77  thod.** checks w
f210: 68 65 74 68 65 72 20 74 68 65 20 6e 61 6d 65 64  hether the named
f220: 20 64 69 72 65 63 74 6f 72 79 20 69 73 20 62 6f   directory is bo
f230: 74 68 20 72 65 61 64 61 62 6c 65 20 61 6e 64 20  th readable and 
f240: 77 72 69 74 61 62 6c 65 0a 2a 2a 20 28 69 6e 20  writable.** (in 
f250: 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 69 66 20  other words, if 
f260: 66 69 6c 65 73 20 63 61 6e 20 62 65 20 61 64 64  files can be add
f270: 65 64 2c 20 72 65 6d 6f 76 65 64 2c 20 61 6e 64  ed, removed, and
f280: 20 72 65 6e 61 6d 65 64 20 77 69 74 68 69 6e 0a   renamed within.
f290: 2a 2a 20 74 68 65 20 64 69 72 65 63 74 6f 72 79  ** the directory
f2a0: 29 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45  )..** The SQLITE
f2b0: 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 54  _ACCESS_READWRIT
f2c0: 45 20 63 6f 6e 73 74 61 6e 74 20 69 73 20 63 75  E constant is cu
f2d0: 72 72 65 6e 74 6c 79 20 75 73 65 64 20 6f 6e 6c  rrently used onl
f2e0: 79 20 62 79 20 74 68 65 0a 2a 2a 20 5b 74 65 6d  y by the.** [tem
f2f0: 70 5f 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72  p_store_director
f300: 79 20 70 72 61 67 6d 61 5d 2c 20 74 68 6f 75 67  y pragma], thoug
f310: 68 20 74 68 69 73 20 63 6f 75 6c 64 20 63 68 61  h this could cha
f320: 6e 67 65 20 69 6e 20 61 20 66 75 74 75 72 65 0a  nge in a future.
f330: 2a 2a 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51  ** release of SQ
f340: 4c 69 74 65 2e 0a 2a 2a 20 57 69 74 68 20 53 51  Lite..** With SQ
f350: 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44  LITE_ACCESS_READ
f360: 2c 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65  , the xAccess me
f370: 74 68 6f 64 0a 2a 2a 20 63 68 65 63 6b 73 20 77  thod.** checks w
f380: 68 65 74 68 65 72 20 74 68 65 20 66 69 6c 65 20  hether the file 
f390: 69 73 20 72 65 61 64 61 62 6c 65 2e 20 20 54 68  is readable.  Th
f3a0: 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f  e SQLITE_ACCESS_
f3b0: 52 45 41 44 20 63 6f 6e 73 74 61 6e 74 20 69 73  READ constant is
f3c0: 0a 2a 2a 20 63 75 72 72 65 6e 74 6c 79 20 75 6e  .** currently un
f3d0: 75 73 65 64 2c 20 74 68 6f 75 67 68 20 69 74 20  used, though it 
f3e0: 6d 69 67 68 74 20 62 65 20 75 73 65 64 20 69 6e  might be used in
f3f0: 20 61 20 66 75 74 75 72 65 20 72 65 6c 65 61 73   a future releas
f400: 65 20 6f 66 0a 2a 2a 20 53 51 4c 69 74 65 2e 0a  e of.** SQLite..
f410: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
f420: 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53 20  E_ACCESS_EXISTS 
f430: 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c     0.#define SQL
f440: 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57  ITE_ACCESS_READW
f450: 52 49 54 45 20 31 20 20 20 2f 2a 20 55 73 65 64  RITE 1   /* Used
f460: 20 62 79 20 50 52 41 47 4d 41 20 74 65 6d 70 5f   by PRAGMA temp_
f470: 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20  store_directory 
f480: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
f490: 45 5f 41 43 43 45 53 53 5f 52 45 41 44 20 20 20  E_ACCESS_READ   
f4a0: 20 20 20 32 20 20 20 2f 2a 20 55 6e 75 73 65 64     2   /* Unused
f4b0: 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33   */../*.** CAPI3
f4c0: 52 45 46 3a 20 46 6c 61 67 73 20 66 6f 72 20 74  REF: Flags for t
f4d0: 68 65 20 78 53 68 6d 4c 6f 63 6b 20 56 46 53 20  he xShmLock VFS 
f4e0: 6d 65 74 68 6f 64 0a 2a 2a 0a 2a 2a 20 54 68 65  method.**.** The
f4f0: 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74  se integer const
f500: 61 6e 74 73 20 64 65 66 69 6e 65 20 74 68 65 20  ants define the 
f510: 76 61 72 69 6f 75 73 20 6c 6f 63 6b 69 6e 67 20  various locking 
f520: 6f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 20 61 6c  operations.** al
f530: 6c 6f 77 65 64 20 62 79 20 74 68 65 20 78 53 68  lowed by the xSh
f540: 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 6f 66 20  mLock method of 
f550: 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68  [sqlite3_io_meth
f560: 6f 64 73 5d 2e 20 20 54 68 65 0a 2a 2a 20 66 6f  ods].  The.** fo
f570: 6c 6c 6f 77 69 6e 67 20 61 72 65 20 74 68 65 20  llowing are the 
f580: 6f 6e 6c 79 20 6c 65 67 61 6c 20 63 6f 6d 62 69  only legal combi
f590: 6e 61 74 69 6f 6e 73 20 6f 66 20 66 6c 61 67 73  nations of flags
f5a0: 20 74 6f 20 74 68 65 0a 2a 2a 20 78 53 68 6d 4c   to the.** xShmL
f5b0: 6f 63 6b 20 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a  ock method:.**.*
f5c0: 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20  * <ul>.** <li>  
f5d0: 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20  SQLITE_SHM_LOCK 
f5e0: 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41  | SQLITE_SHM_SHA
f5f0: 52 45 44 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c  RED.** <li>  SQL
f600: 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 7c 20 53  ITE_SHM_LOCK | S
f610: 51 4c 49 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53  QLITE_SHM_EXCLUS
f620: 49 56 45 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c  IVE.** <li>  SQL
f630: 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 7c  ITE_SHM_UNLOCK |
f640: 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52   SQLITE_SHM_SHAR
f650: 45 44 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49  ED.** <li>  SQLI
f660: 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 7c 20  TE_SHM_UNLOCK | 
f670: 53 51 4c 49 54 45 5f 53 48 4d 5f 45 58 43 4c 55  SQLITE_SHM_EXCLU
f680: 53 49 56 45 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a  SIVE.** </ul>.**
f690: 0a 2a 2a 20 57 68 65 6e 20 75 6e 6c 6f 63 6b 69  .** When unlocki
f6a0: 6e 67 2c 20 74 68 65 20 73 61 6d 65 20 53 48 41  ng, the same SHA
f6b0: 52 45 44 20 6f 72 20 45 58 43 4c 55 53 49 56 45  RED or EXCLUSIVE
f6c0: 20 66 6c 61 67 20 6d 75 73 74 20 62 65 20 73 75   flag must be su
f6d0: 70 70 6c 69 65 64 20 61 73 0a 2a 2a 20 77 61 73  pplied as.** was
f6e0: 20 67 69 76 65 6e 20 6f 6e 20 74 68 65 20 63 6f   given on the co
f6f0: 72 72 65 73 70 6f 6e 64 69 6e 67 20 6c 6f 63 6b  rresponding lock
f700: 2e 20 20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53  .  .**.** The xS
f710: 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 63 61  hmLock method ca
f720: 6e 20 74 72 61 6e 73 69 74 69 6f 6e 20 62 65 74  n transition bet
f730: 77 65 65 6e 20 75 6e 6c 6f 63 6b 65 64 20 61 6e  ween unlocked an
f740: 64 20 53 48 41 52 45 44 20 6f 72 0a 2a 2a 20 62  d SHARED or.** b
f750: 65 74 77 65 65 6e 20 75 6e 6c 6f 63 6b 65 64 20  etween unlocked 
f760: 61 6e 64 20 45 58 43 4c 55 53 49 56 45 2e 20 20  and EXCLUSIVE.  
f770: 49 74 20 63 61 6e 6e 6f 74 20 74 72 61 6e 73 69  It cannot transi
f780: 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 53 48 41  tion between SHA
f790: 52 45 44 0a 2a 2a 20 61 6e 64 20 45 58 43 4c 55  RED.** and EXCLU
f7a0: 53 49 56 45 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65  SIVE..*/.#define
f7b0: 20 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f   SQLITE_SHM_UNLO
f7c0: 43 4b 20 20 20 20 20 20 20 31 0a 23 64 65 66 69  CK       1.#defi
f7d0: 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f  ne SQLITE_SHM_LO
f7e0: 43 4b 20 20 20 20 20 20 20 20 20 32 0a 23 64 65  CK         2.#de
f7f0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f  fine SQLITE_SHM_
f800: 53 48 41 52 45 44 20 20 20 20 20 20 20 34 0a 23  SHARED       4.#
f810: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48  define SQLITE_SH
f820: 4d 5f 45 58 43 4c 55 53 49 56 45 20 20 20 20 38  M_EXCLUSIVE    8
f830: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
f840: 3a 20 4d 61 78 69 6d 75 6d 20 78 53 68 6d 4c 6f  : Maximum xShmLo
f850: 63 6b 20 69 6e 64 65 78 0a 2a 2a 0a 2a 2a 20 54  ck index.**.** T
f860: 68 65 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68  he xShmLock meth
f870: 6f 64 20 6f 6e 20 5b 73 71 6c 69 74 65 33 5f 69  od on [sqlite3_i
f880: 6f 5f 6d 65 74 68 6f 64 73 5d 20 6d 61 79 20 75  o_methods] may u
f890: 73 65 20 76 61 6c 75 65 73 0a 2a 2a 20 62 65 74  se values.** bet
f8a0: 77 65 65 6e 20 30 20 61 6e 64 20 74 68 69 73 20  ween 0 and this 
f8b0: 75 70 70 65 72 20 62 6f 75 6e 64 20 61 73 20 69  upper bound as i
f8c0: 74 73 20 22 6f 66 66 73 65 74 22 20 61 72 67 75  ts "offset" argu
f8d0: 6d 65 6e 74 2e 0a 2a 2a 20 54 68 65 20 53 51 4c  ment..** The SQL
f8e0: 69 74 65 20 63 6f 72 65 20 77 69 6c 6c 20 6e 65  ite core will ne
f8f0: 76 65 72 20 61 74 74 65 6d 70 74 20 74 6f 20 61  ver attempt to a
f900: 63 71 75 69 72 65 20 6f 72 20 72 65 6c 65 61 73  cquire or releas
f910: 65 20 61 0a 2a 2a 20 6c 6f 63 6b 20 6f 75 74 73  e a.** lock outs
f920: 69 64 65 20 6f 66 20 74 68 69 73 20 72 61 6e 67  ide of this rang
f930: 65 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  e.*/.#define SQL
f940: 49 54 45 5f 53 48 4d 5f 4e 4c 4f 43 4b 20 20 20  ITE_SHM_NLOCK   
f950: 20 20 20 20 20 38 0a 0a 0a 2f 2a 0a 2a 2a 20 43       8.../*.** C
f960: 41 50 49 33 52 45 46 3a 20 49 6e 69 74 69 61 6c  API3REF: Initial
f970: 69 7a 65 20 54 68 65 20 53 51 4c 69 74 65 20 4c  ize The SQLite L
f980: 69 62 72 61 72 79 0a 2a 2a 0a 2a 2a 20 5e 54 68  ibrary.**.** ^Th
f990: 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  e sqlite3_initia
f9a0: 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 69  lize() routine i
f9b0: 6e 69 74 69 61 6c 69 7a 65 73 20 74 68 65 0a 2a  nitializes the.*
f9c0: 2a 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79  * SQLite library
f9d0: 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  .  ^The sqlite3_
f9e0: 73 68 75 74 64 6f 77 6e 28 29 20 72 6f 75 74 69  shutdown() routi
f9f0: 6e 65 0a 2a 2a 20 64 65 61 6c 6c 6f 63 61 74 65  ne.** deallocate
fa00: 73 20 61 6e 79 20 72 65 73 6f 75 72 63 65 73 20  s any resources 
fa10: 74 68 61 74 20 77 65 72 65 20 61 6c 6c 6f 63 61  that were alloca
fa20: 74 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 69  ted by sqlite3_i
fa30: 6e 69 74 69 61 6c 69 7a 65 28 29 2e 0a 2a 2a 20  nitialize()..** 
fa40: 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  These routines a
fa50: 72 65 20 64 65 73 69 67 6e 65 64 20 74 6f 20 61  re designed to a
fa60: 69 64 20 69 6e 20 70 72 6f 63 65 73 73 20 69 6e  id in process in
fa70: 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 61 6e 64  itialization and
fa80: 0a 2a 2a 20 73 68 75 74 64 6f 77 6e 20 6f 6e 20  .** shutdown on 
fa90: 65 6d 62 65 64 64 65 64 20 73 79 73 74 65 6d 73  embedded systems
faa0: 2e 20 20 57 6f 72 6b 73 74 61 74 69 6f 6e 20 61  .  Workstation a
fab0: 70 70 6c 69 63 61 74 69 6f 6e 73 20 75 73 69 6e  pplications usin
fac0: 67 0a 2a 2a 20 53 51 4c 69 74 65 20 6e 6f 72 6d  g.** SQLite norm
fad0: 61 6c 6c 79 20 64 6f 20 6e 6f 74 20 6e 65 65 64  ally do not need
fae0: 20 74 6f 20 69 6e 76 6f 6b 65 20 65 69 74 68 65   to invoke eithe
faf0: 72 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69  r of these routi
fb00: 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c  nes..**.** A cal
fb10: 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e 69  l to sqlite3_ini
fb20: 74 69 61 6c 69 7a 65 28 29 20 69 73 20 61 6e 20  tialize() is an 
fb30: 22 65 66 66 65 63 74 69 76 65 22 20 63 61 6c 6c  "effective" call
fb40: 20 69 66 20 69 74 20 69 73 0a 2a 2a 20 74 68 65   if it is.** the
fb50: 20 66 69 72 73 74 20 74 69 6d 65 20 73 71 6c 69   first time sqli
fb60: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
fb70: 20 69 73 20 69 6e 76 6f 6b 65 64 20 64 75 72 69   is invoked duri
fb80: 6e 67 20 74 68 65 20 6c 69 66 65 74 69 6d 65 20  ng the lifetime 
fb90: 6f 66 0a 2a 2a 20 74 68 65 20 70 72 6f 63 65 73  of.** the proces
fba0: 73 2c 20 6f 72 20 69 66 20 69 74 20 69 73 20 74  s, or if it is t
fbb0: 68 65 20 66 69 72 73 74 20 74 69 6d 65 20 73 71  he first time sq
fbc0: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
fbd0: 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a  () is invoked.**
fbe0: 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 63 61 6c   following a cal
fbf0: 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75  l to sqlite3_shu
fc00: 74 64 6f 77 6e 28 29 2e 20 20 5e 28 4f 6e 6c 79  tdown().  ^(Only
fc10: 20 61 6e 20 65 66 66 65 63 74 69 76 65 20 63 61   an effective ca
fc20: 6c 6c 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33  ll.** of sqlite3
fc30: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 6f  _initialize() do
fc40: 65 73 20 61 6e 79 20 69 6e 69 74 69 61 6c 69 7a  es any initializ
fc50: 61 74 69 6f 6e 2e 20 20 41 6c 6c 20 6f 74 68 65  ation.  All othe
fc60: 72 20 63 61 6c 6c 73 0a 2a 2a 20 61 72 65 20 68  r calls.** are h
fc70: 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e 29  armless no-ops.)
fc80: 5e 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74  ^.**.** A call t
fc90: 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  o sqlite3_shutdo
fca0: 77 6e 28 29 20 69 73 20 61 6e 20 22 65 66 66 65  wn() is an "effe
fcb0: 63 74 69 76 65 22 20 63 61 6c 6c 20 69 66 20 69  ctive" call if i
fcc0: 74 20 69 73 20 74 68 65 20 66 69 72 73 74 0a 2a  t is the first.*
fcd0: 2a 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  * call to sqlite
fce0: 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 73 69 6e  3_shutdown() sin
fcf0: 63 65 20 74 68 65 20 6c 61 73 74 20 73 71 6c 69  ce the last sqli
fd00: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
fd10: 2e 20 20 5e 28 4f 6e 6c 79 0a 2a 2a 20 61 6e 20  .  ^(Only.** an 
fd20: 65 66 66 65 63 74 69 76 65 20 63 61 6c 6c 20 74  effective call t
fd30: 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  o sqlite3_shutdo
fd40: 77 6e 28 29 20 64 6f 65 73 20 61 6e 79 20 64 65  wn() does any de
fd50: 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a  initialization..
fd60: 2a 2a 20 41 6c 6c 20 6f 74 68 65 72 20 76 61 6c  ** All other val
fd70: 69 64 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69  id calls to sqli
fd80: 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 61  te3_shutdown() a
fd90: 72 65 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f  re harmless no-o
fda0: 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ps.)^.**.** The 
fdb0: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
fdc0: 7a 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 69  ze() interface i
fdd0: 73 20 74 68 72 65 61 64 73 61 66 65 2c 20 62 75  s threadsafe, bu
fde0: 74 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  t sqlite3_shutdo
fdf0: 77 6e 28 29 0a 2a 2a 20 69 73 20 6e 6f 74 2e 20  wn().** is not. 
fe00: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 73 68 75   The sqlite3_shu
fe10: 74 64 6f 77 6e 28 29 20 69 6e 74 65 72 66 61 63  tdown() interfac
fe20: 65 20 6d 75 73 74 20 6f 6e 6c 79 20 62 65 20 63  e must only be c
fe30: 61 6c 6c 65 64 20 66 72 6f 6d 20 61 0a 2a 2a 20  alled from a.** 
fe40: 73 69 6e 67 6c 65 20 74 68 72 65 61 64 2e 20 20  single thread.  
fe50: 41 6c 6c 20 6f 70 65 6e 20 5b 64 61 74 61 62 61  All open [databa
fe60: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20  se connections] 
fe70: 6d 75 73 74 20 62 65 20 63 6c 6f 73 65 64 20 61  must be closed a
fe80: 6e 64 20 61 6c 6c 0a 2a 2a 20 6f 74 68 65 72 20  nd all.** other 
fe90: 53 51 4c 69 74 65 20 72 65 73 6f 75 72 63 65 73  SQLite resources
fea0: 20 6d 75 73 74 20 62 65 20 64 65 61 6c 6c 6f 63   must be dealloc
feb0: 61 74 65 64 20 70 72 69 6f 72 20 74 6f 20 69 6e  ated prior to in
fec0: 76 6f 6b 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65  voking.** sqlite
fed0: 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 0a 2a 2a  3_shutdown()..**
fee0: 0a 2a 2a 20 41 6d 6f 6e 67 20 6f 74 68 65 72 20  .** Among other 
fef0: 74 68 69 6e 67 73 2c 20 5e 73 71 6c 69 74 65 33  things, ^sqlite3
ff00: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 77 69  _initialize() wi
ff10: 6c 6c 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c  ll invoke.** sql
ff20: 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 2e 20  ite3_os_init(). 
ff30: 20 53 69 6d 69 6c 61 72 6c 79 2c 20 5e 73 71 6c   Similarly, ^sql
ff40: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 0a  ite3_shutdown().
ff50: 2a 2a 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 73  ** will invoke s
ff60: 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 2e  qlite3_os_end().
ff70: 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
ff80: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
ff90: 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
ffa0: 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20   [SQLITE_OK] on 
ffb0: 73 75 63 63 65 73 73 2e 0a 2a 2a 20 5e 49 66 20  success..** ^If 
ffc0: 66 6f 72 20 73 6f 6d 65 20 72 65 61 73 6f 6e 2c  for some reason,
ffd0: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
ffe0: 69 7a 65 28 29 20 69 73 20 75 6e 61 62 6c 65 20  ize() is unable 
fff0: 74 6f 20 69 6e 69 74 69 61 6c 69 7a 65 0a 2a 2a  to initialize.**
10000 20 74 68 65 20 6c 69 62 72 61 72 79 20 28 70 65   the library (pe
10010 72 68 61 70 73 20 69 74 20 69 73 20 75 6e 61 62  rhaps it is unab
10020 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 61  le to allocate a
10030 20 6e 65 65 64 65 64 20 72 65 73 6f 75 72 63 65   needed resource
10040 20 73 75 63 68 0a 2a 2a 20 61 73 20 61 20 6d 75   such.** as a mu
10050 74 65 78 29 20 69 74 20 72 65 74 75 72 6e 73 20  tex) it returns 
10060 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20  an [error code] 
10070 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49  other than [SQLI
10080 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54  TE_OK]..**.** ^T
10090 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  he sqlite3_initi
100a0 61 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 20  alize() routine 
100b0 69 73 20 63 61 6c 6c 65 64 20 69 6e 74 65 72 6e  is called intern
100c0 61 6c 6c 79 20 62 79 20 6d 61 6e 79 20 6f 74 68  ally by many oth
100d0 65 72 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74  er.** SQLite int
100e0 65 72 66 61 63 65 73 20 73 6f 20 74 68 61 74 20  erfaces so that 
100f0 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 75  an application u
10100 73 75 61 6c 6c 79 20 64 6f 65 73 20 6e 6f 74 20  sually does not 
10110 6e 65 65 64 20 74 6f 0a 2a 2a 20 69 6e 76 6f 6b  need to.** invok
10120 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  e sqlite3_initia
10130 6c 69 7a 65 28 29 20 64 69 72 65 63 74 6c 79 2e  lize() directly.
10140 20 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 5b    For example, [
10150 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 0a  sqlite3_open()].
10160 2a 2a 20 63 61 6c 6c 73 20 73 71 6c 69 74 65 33  ** calls sqlite3
10170 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 73 6f  _initialize() so
10180 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72   the SQLite libr
10190 61 72 79 20 77 69 6c 6c 20 62 65 20 61 75 74 6f  ary will be auto
101a0 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 69 6e 69  matically.** ini
101b0 74 69 61 6c 69 7a 65 64 20 77 68 65 6e 20 5b 73  tialized when [s
101c0 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 20 69  qlite3_open()] i
101d0 73 20 63 61 6c 6c 65 64 20 69 66 20 69 74 20 68  s called if it h
101e0 61 73 20 6e 6f 74 20 62 65 20 69 6e 69 74 69 61  as not be initia
101f0 6c 69 7a 65 64 0a 2a 2a 20 61 6c 72 65 61 64 79  lized.** already
10200 2e 20 20 5e 48 6f 77 65 76 65 72 2c 20 69 66 20  .  ^However, if 
10210 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  SQLite is compil
10220 65 64 20 77 69 74 68 20 74 68 65 20 5b 53 51 4c  ed with the [SQL
10230 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e 49  ITE_OMIT_AUTOINI
10240 54 5d 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74 69  T].** compile-ti
10250 6d 65 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 20  me option, then 
10260 74 68 65 20 61 75 74 6f 6d 61 74 69 63 20 63 61  the automatic ca
10270 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 69  lls to sqlite3_i
10280 6e 69 74 69 61 6c 69 7a 65 28 29 0a 2a 2a 20 61  nitialize().** a
10290 72 65 20 6f 6d 69 74 74 65 64 20 61 6e 64 20 74  re omitted and t
102a0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d  he application m
102b0 75 73 74 20 63 61 6c 6c 20 73 71 6c 69 74 65 33  ust call sqlite3
102c0 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 69  _initialize() di
102d0 72 65 63 74 6c 79 0a 2a 2a 20 70 72 69 6f 72 20  rectly.** prior 
102e0 74 6f 20 75 73 69 6e 67 20 61 6e 79 20 6f 74 68  to using any oth
102f0 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66  er SQLite interf
10300 61 63 65 2e 20 20 46 6f 72 20 6d 61 78 69 6d 75  ace.  For maximu
10310 6d 20 70 6f 72 74 61 62 69 6c 69 74 79 2c 0a 2a  m portability,.*
10320 2a 20 69 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e  * it is recommen
10330 64 65 64 20 74 68 61 74 20 61 70 70 6c 69 63 61  ded that applica
10340 74 69 6f 6e 73 20 61 6c 77 61 79 73 20 69 6e 76  tions always inv
10350 6f 6b 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  oke sqlite3_init
10360 69 61 6c 69 7a 65 28 29 0a 2a 2a 20 64 69 72 65  ialize().** dire
10370 63 74 6c 79 20 70 72 69 6f 72 20 74 6f 20 75 73  ctly prior to us
10380 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 53 51  ing any other SQ
10390 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e 20  Lite interface. 
103a0 20 46 75 74 75 72 65 20 72 65 6c 65 61 73 65 73   Future releases
103b0 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65 20 6d 61  .** of SQLite ma
103c0 79 20 72 65 71 75 69 72 65 20 74 68 69 73 2e 20  y require this. 
103d0 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c   In other words,
103e0 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 65 78   the behavior ex
103f0 68 69 62 69 74 65 64 0a 2a 2a 20 77 68 65 6e 20  hibited.** when 
10400 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  SQLite is compil
10410 65 64 20 77 69 74 68 20 5b 53 51 4c 49 54 45 5f  ed with [SQLITE_
10420 4f 4d 49 54 5f 41 55 54 4f 49 4e 49 54 5d 20 6d  OMIT_AUTOINIT] m
10430 69 67 68 74 20 62 65 63 6f 6d 65 20 74 68 65 0a  ight become the.
10440 2a 2a 20 64 65 66 61 75 6c 74 20 62 65 68 61 76  ** default behav
10450 69 6f 72 20 69 6e 20 73 6f 6d 65 20 66 75 74 75  ior in some futu
10460 72 65 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51  re release of SQ
10470 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  Lite..**.** The 
10480 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28  sqlite3_os_init(
10490 29 20 72 6f 75 74 69 6e 65 20 64 6f 65 73 20 6f  ) routine does o
104a0 70 65 72 61 74 69 6e 67 2d 73 79 73 74 65 6d 20  perating-system 
104b0 73 70 65 63 69 66 69 63 0a 2a 2a 20 69 6e 69 74  specific.** init
104c0 69 61 6c 69 7a 61 74 69 6f 6e 20 6f 66 20 74 68  ialization of th
104d0 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79  e SQLite library
104e0 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f  .  The sqlite3_o
104f0 73 5f 65 6e 64 28 29 0a 2a 2a 20 72 6f 75 74 69  s_end().** routi
10500 6e 65 20 75 6e 64 6f 65 73 20 74 68 65 20 65 66  ne undoes the ef
10510 66 65 63 74 20 6f 66 20 73 71 6c 69 74 65 33 5f  fect of sqlite3_
10520 6f 73 5f 69 6e 69 74 28 29 2e 20 20 54 79 70 69  os_init().  Typi
10530 63 61 6c 20 74 61 73 6b 73 0a 2a 2a 20 70 65 72  cal tasks.** per
10540 66 6f 72 6d 65 64 20 62 79 20 74 68 65 73 65 20  formed by these 
10550 72 6f 75 74 69 6e 65 73 20 69 6e 63 6c 75 64 65  routines include
10560 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6f 72 20 64   allocation or d
10570 65 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f  eallocation.** o
10580 66 20 73 74 61 74 69 63 20 72 65 73 6f 75 72 63  f static resourc
10590 65 73 2c 20 69 6e 69 74 69 61 6c 69 7a 61 74 69  es, initializati
105a0 6f 6e 20 6f 66 20 67 6c 6f 62 61 6c 20 76 61 72  on of global var
105b0 69 61 62 6c 65 73 2c 0a 2a 2a 20 73 65 74 74 69  iables,.** setti
105c0 6e 67 20 75 70 20 61 20 64 65 66 61 75 6c 74 20  ng up a default 
105d0 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6d 6f  [sqlite3_vfs] mo
105e0 64 75 6c 65 2c 20 6f 72 20 73 65 74 74 69 6e 67  dule, or setting
105f0 20 75 70 0a 2a 2a 20 61 20 64 65 66 61 75 6c 74   up.** a default
10600 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 75   configuration u
10610 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63 6f  sing [sqlite3_co
10620 6e 66 69 67 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54  nfig()]..**.** T
10630 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73  he application s
10640 68 6f 75 6c 64 20 6e 65 76 65 72 20 69 6e 76 6f  hould never invo
10650 6b 65 20 65 69 74 68 65 72 20 73 71 6c 69 74 65  ke either sqlite
10660 33 5f 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a 20 6f  3_os_init().** o
10670 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64  r sqlite3_os_end
10680 28 29 20 64 69 72 65 63 74 6c 79 2e 20 20 54 68  () directly.  Th
10690 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68  e application sh
106a0 6f 75 6c 64 20 6f 6e 6c 79 20 69 6e 76 6f 6b 65  ould only invoke
106b0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  .** sqlite3_init
106c0 69 61 6c 69 7a 65 28 29 20 61 6e 64 20 73 71 6c  ialize() and sql
106d0 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e  ite3_shutdown().
106e0 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73    The sqlite3_os
106f0 5f 69 6e 69 74 28 29 0a 2a 2a 20 69 6e 74 65 72  _init().** inter
10700 66 61 63 65 20 69 73 20 63 61 6c 6c 65 64 20 61  face is called a
10710 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62 79 20  utomatically by 
10720 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
10730 7a 65 28 29 20 61 6e 64 0a 2a 2a 20 73 71 6c 69  ze() and.** sqli
10740 74 65 33 5f 6f 73 5f 65 6e 64 28 29 20 69 73 20  te3_os_end() is 
10750 63 61 6c 6c 65 64 20 62 79 20 73 71 6c 69 74 65  called by sqlite
10760 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 41  3_shutdown().  A
10770 70 70 72 6f 70 72 69 61 74 65 0a 2a 2a 20 69 6d  ppropriate.** im
10780 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 66 6f  plementations fo
10790 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69  r sqlite3_os_ini
107a0 74 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  t() and sqlite3_
107b0 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 61 72 65 20  os_end().** are 
107c0 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74  built into SQLit
107d0 65 20 77 68 65 6e 20 69 74 20 69 73 20 63 6f 6d  e when it is com
107e0 70 69 6c 65 64 20 66 6f 72 20 55 6e 69 78 2c 20  piled for Unix, 
107f0 57 69 6e 64 6f 77 73 2c 20 6f 72 20 4f 53 2f 32  Windows, or OS/2
10800 2e 0a 2a 2a 20 57 68 65 6e 20 5b 63 75 73 74 6f  ..** When [custo
10810 6d 20 62 75 69 6c 64 73 20 7c 20 62 75 69 6c 74  m builds | built
10820 20 66 6f 72 20 6f 74 68 65 72 20 70 6c 61 74 66   for other platf
10830 6f 72 6d 73 5d 0a 2a 2a 20 28 75 73 69 6e 67 20  orms].** (using 
10840 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 53 5f 4f  the [SQLITE_OS_O
10850 54 48 45 52 3d 31 5d 20 63 6f 6d 70 69 6c 65 2d  THER=1] compile-
10860 74 69 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e 29 20  time.** option) 
10870 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
10880 6d 75 73 74 20 73 75 70 70 6c 79 20 61 20 73 75  must supply a su
10890 69 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74  itable implement
108a0 61 74 69 6f 6e 20 66 6f 72 0a 2a 2a 20 73 71 6c  ation for.** sql
108b0 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 61  ite3_os_init() a
108c0 6e 64 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e  nd sqlite3_os_en
108d0 64 28 29 2e 20 20 41 6e 20 61 70 70 6c 69 63 61  d().  An applica
108e0 74 69 6f 6e 2d 73 75 70 70 6c 69 65 64 0a 2a 2a  tion-supplied.**
108f0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
10900 6f 66 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  of sqlite3_os_in
10910 69 74 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  it() or sqlite3_
10920 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 6d 75 73 74  os_end().** must
10930 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
10940 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 20 61  OK] on success a
10950 6e 64 20 73 6f 6d 65 20 6f 74 68 65 72 20 5b 65  nd some other [e
10960 72 72 6f 72 20 63 6f 64 65 5d 20 75 70 6f 6e 0a  rror code] upon.
10970 2a 2a 20 66 61 69 6c 75 72 65 2e 0a 2a 2f 0a 69  ** failure..*/.i
10980 6e 74 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  nt sqlite3_initi
10990 61 6c 69 7a 65 28 76 6f 69 64 29 3b 0a 69 6e 74  alize(void);.int
109a0 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77   sqlite3_shutdow
109b0 6e 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c  n(void);.int sql
109c0 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 76 6f 69  ite3_os_init(voi
109d0 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  d);.int sqlite3_
109e0 6f 73 5f 65 6e 64 28 76 6f 69 64 29 3b 0a 0a 2f  os_end(void);../
109f0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
10a00 6f 6e 66 69 67 75 72 69 6e 67 20 54 68 65 20 53  onfiguring The S
10a10 51 4c 69 74 65 20 4c 69 62 72 61 72 79 0a 2a 2a  QLite Library.**
10a20 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
10a30 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61  config() interfa
10a40 63 65 20 69 73 20 75 73 65 64 20 74 6f 20 6d 61  ce is used to ma
10a50 6b 65 20 67 6c 6f 62 61 6c 20 63 6f 6e 66 69 67  ke global config
10a60 75 72 61 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67  uration.** chang
10a70 65 73 20 74 6f 20 53 51 4c 69 74 65 20 69 6e 20  es to SQLite in 
10a80 6f 72 64 65 72 20 74 6f 20 74 75 6e 65 20 53 51  order to tune SQ
10a90 4c 69 74 65 20 74 6f 20 74 68 65 20 73 70 65 63  Lite to the spec
10aa0 69 66 69 63 20 6e 65 65 64 73 20 6f 66 0a 2a 2a  ific needs of.**
10ab0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
10ac0 2e 20 20 54 68 65 20 64 65 66 61 75 6c 74 20 63  .  The default c
10ad0 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 69 73 20  onfiguration is 
10ae0 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20  recommended for 
10af0 6d 6f 73 74 0a 2a 2a 20 61 70 70 6c 69 63 61 74  most.** applicat
10b00 69 6f 6e 73 20 61 6e 64 20 73 6f 20 74 68 69 73  ions and so this
10b10 20 72 6f 75 74 69 6e 65 20 69 73 20 75 73 75 61   routine is usua
10b20 6c 6c 79 20 6e 6f 74 20 6e 65 63 65 73 73 61 72  lly not necessar
10b30 79 2e 20 20 49 74 20 69 73 0a 2a 2a 20 70 72 6f  y.  It is.** pro
10b40 76 69 64 65 64 20 74 6f 20 73 75 70 70 6f 72 74  vided to support
10b50 20 72 61 72 65 20 61 70 70 6c 69 63 61 74 69 6f   rare applicatio
10b60 6e 73 20 77 69 74 68 20 75 6e 75 73 75 61 6c 20  ns with unusual 
10b70 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e  needs..**.** <b>
10b80 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66  The sqlite3_conf
10b90 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 20 69  ig() interface i
10ba0 73 20 6e 6f 74 20 74 68 72 65 61 64 73 61 66 65  s not threadsafe
10bb0 2e 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f  . The applicatio
10bc0 6e 0a 2a 2a 20 6d 75 73 74 20 65 6e 73 75 72 65  n.** must ensure
10bd0 20 74 68 61 74 20 6e 6f 20 6f 74 68 65 72 20 53   that no other S
10be0 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 73  QLite interfaces
10bf0 20 61 72 65 20 69 6e 76 6f 6b 65 64 20 62 79 20   are invoked by 
10c00 6f 74 68 65 72 0a 2a 2a 20 74 68 72 65 61 64 73  other.** threads
10c10 20 77 68 69 6c 65 20 73 71 6c 69 74 65 33 5f 63   while sqlite3_c
10c20 6f 6e 66 69 67 28 29 20 69 73 20 72 75 6e 6e 69  onfig() is runni
10c30 6e 67 2e 3c 2f 62 3e 0a 2a 2a 0a 2a 2a 20 54 68  ng.</b>.**.** Th
10c40 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67  e sqlite3_config
10c50 28 29 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20  () interface.** 
10c60 6d 61 79 20 6f 6e 6c 79 20 62 65 20 69 6e 76 6f  may only be invo
10c70 6b 65 64 20 70 72 69 6f 72 20 74 6f 20 6c 69 62  ked prior to lib
10c80 72 61 72 79 20 69 6e 69 74 69 61 6c 69 7a 61 74  rary initializat
10c90 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71  ion using.** [sq
10ca0 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
10cb0 28 29 5d 20 6f 72 20 61 66 74 65 72 20 73 68 75  ()] or after shu
10cc0 74 64 6f 77 6e 20 62 79 20 5b 73 71 6c 69 74 65  tdown by [sqlite
10cd0 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 2e 0a 2a  3_shutdown()]..*
10ce0 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 63 6f  * ^If sqlite3_co
10cf0 6e 66 69 67 28 29 20 69 73 20 63 61 6c 6c 65 64  nfig() is called
10d00 20 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f   after [sqlite3_
10d10 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20 61 6e  initialize()] an
10d20 64 20 62 65 66 6f 72 65 0a 2a 2a 20 5b 73 71 6c  d before.** [sql
10d30 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d  ite3_shutdown()]
10d40 20 74 68 65 6e 20 69 74 20 77 69 6c 6c 20 72 65   then it will re
10d50 74 75 72 6e 20 53 51 4c 49 54 45 5f 4d 49 53 55  turn SQLITE_MISU
10d60 53 45 2e 0a 2a 2a 20 4e 6f 74 65 2c 20 68 6f 77  SE..** Note, how
10d70 65 76 65 72 2c 20 74 68 61 74 20 5e 73 71 6c 69  ever, that ^sqli
10d80 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 63 61 6e  te3_config() can
10d90 20 62 65 20 63 61 6c 6c 65 64 20 61 73 20 70 61   be called as pa
10da0 72 74 20 6f 66 20 74 68 65 0a 2a 2a 20 69 6d 70  rt of the.** imp
10db0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61  lementation of a
10dc0 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  n application-de
10dd0 66 69 6e 65 64 20 5b 73 71 6c 69 74 65 33 5f 6f  fined [sqlite3_o
10de0 73 5f 69 6e 69 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a  s_init()]..**.**
10df0 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   The first argum
10e00 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  ent to sqlite3_c
10e10 6f 6e 66 69 67 28 29 20 69 73 20 61 6e 20 69 6e  onfig() is an in
10e20 74 65 67 65 72 0a 2a 2a 20 5b 63 6f 6e 66 69 67  teger.** [config
10e30 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d 20  uration option] 
10e40 74 68 61 74 20 64 65 74 65 72 6d 69 6e 65 73 0a  that determines.
10e50 2a 2a 20 77 68 61 74 20 70 72 6f 70 65 72 74 79  ** what property
10e60 20 6f 66 20 53 51 4c 69 74 65 20 69 73 20 74 6f   of SQLite is to
10e70 20 62 65 20 63 6f 6e 66 69 67 75 72 65 64 2e 20   be configured. 
10e80 20 53 75 62 73 65 71 75 65 6e 74 20 61 72 67 75   Subsequent argu
10e90 6d 65 6e 74 73 0a 2a 2a 20 76 61 72 79 20 64 65  ments.** vary de
10ea0 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 5b  pending on the [
10eb0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
10ec0 74 69 6f 6e 5d 0a 2a 2a 20 69 6e 20 74 68 65 20  tion].** in the 
10ed0 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a  first argument..
10ee0 2a 2a 0a 2a 2a 20 5e 57 68 65 6e 20 61 20 63 6f  **.** ^When a co
10ef0 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
10f00 6f 6e 20 69 73 20 73 65 74 2c 20 73 71 6c 69 74  on is set, sqlit
10f10 65 33 5f 63 6f 6e 66 69 67 28 29 20 72 65 74 75  e3_config() retu
10f20 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e  rns [SQLITE_OK].
10f30 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6f 70 74 69  .** ^If the opti
10f40 6f 6e 20 69 73 20 75 6e 6b 6e 6f 77 6e 20 6f 72  on is unknown or
10f50 20 53 51 4c 69 74 65 20 69 73 20 75 6e 61 62 6c   SQLite is unabl
10f60 65 20 74 6f 20 73 65 74 20 74 68 65 20 6f 70 74  e to set the opt
10f70 69 6f 6e 0a 2a 2a 20 74 68 65 6e 20 74 68 69 73  ion.** then this
10f80 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
10f90 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72   a non-zero [err
10fa0 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2f 0a 69 6e 74  or code]..*/.int
10fb0 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28   sqlite3_config(
10fc0 69 6e 74 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a  int, ...);../*.*
10fd0 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66  * CAPI3REF: Conf
10fe0 69 67 75 72 65 20 64 61 74 61 62 61 73 65 20 63  igure database c
10ff0 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a 20 4d 45  onnections.** ME
11000 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a  THOD: sqlite3.**
11010 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
11020 64 62 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65  db_config() inte
11030 72 66 61 63 65 20 69 73 20 75 73 65 64 20 74 6f  rface is used to
11040 20 6d 61 6b 65 20 63 6f 6e 66 69 67 75 72 61 74   make configurat
11050 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74  ion.** changes t
11060 6f 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f  o a [database co
11070 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 54 68 65 20  nnection].  The 
11080 69 6e 74 65 72 66 61 63 65 20 69 73 20 73 69 6d  interface is sim
11090 69 6c 61 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  ilar to.** [sqli
110a0 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 65 78  te3_config()] ex
110b0 63 65 70 74 20 74 68 61 74 20 74 68 65 20 63 68  cept that the ch
110c0 61 6e 67 65 73 20 61 70 70 6c 79 20 74 6f 20 61  anges apply to a
110d0 20 73 69 6e 67 6c 65 0a 2a 2a 20 5b 64 61 74 61   single.** [data
110e0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
110f0 20 28 73 70 65 63 69 66 69 65 64 20 69 6e 20 74   (specified in t
11100 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
11110 74 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65  t)..**.** The se
11120 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f  cond argument to
11130 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66   sqlite3_db_conf
11140 69 67 28 44 2c 56 2c 2e 2e 2e 29 20 20 69 73 20  ig(D,V,...)  is 
11150 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44  the.** [SQLITE_D
11160 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44  BCONFIG_LOOKASID
11170 45 20 7c 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  E | configuratio
11180 6e 20 76 65 72 62 5d 20 2d 20 61 6e 20 69 6e 74  n verb] - an int
11190 65 67 65 72 20 63 6f 64 65 20 0a 2a 2a 20 74 68  eger code .** th
111a0 61 74 20 69 6e 64 69 63 61 74 65 73 20 77 68 61  at indicates wha
111b0 74 20 61 73 70 65 63 74 20 6f 66 20 74 68 65 20  t aspect of the 
111c0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
111d0 74 69 6f 6e 5d 20 69 73 20 62 65 69 6e 67 20 63  tion] is being c
111e0 6f 6e 66 69 67 75 72 65 64 2e 0a 2a 2a 20 53 75  onfigured..** Su
111f0 62 73 65 71 75 65 6e 74 20 61 72 67 75 6d 65 6e  bsequent argumen
11200 74 73 20 76 61 72 79 20 64 65 70 65 6e 64 69 6e  ts vary dependin
11210 67 20 6f 6e 20 74 68 65 20 63 6f 6e 66 69 67 75  g on the configu
11220 72 61 74 69 6f 6e 20 76 65 72 62 2e 0a 2a 2a 0a  ration verb..**.
11230 2a 2a 20 5e 43 61 6c 6c 73 20 74 6f 20 73 71 6c  ** ^Calls to sql
11240 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29  ite3_db_config()
11250 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4f   return SQLITE_O
11260 4b 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66  K if and only if
11270 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20 69 73 20  .** the call is 
11280 63 6f 6e 73 69 64 65 72 65 64 20 73 75 63 63 65  considered succe
11290 73 73 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71  ssful..*/.int sq
112a0 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28  lite3_db_config(
112b0 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6f 70  sqlite3*, int op
112c0 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  , ...);../*.** C
112d0 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20  API3REF: Memory 
112e0 41 6c 6c 6f 63 61 74 69 6f 6e 20 52 6f 75 74 69  Allocation Routi
112f0 6e 65 73 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73  nes.**.** An ins
11300 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62  tance of this ob
11310 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74 68 65  ject defines the
11320 20 69 6e 74 65 72 66 61 63 65 20 62 65 74 77 65   interface betwe
11330 65 6e 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64  en SQLite.** and
11340 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72   low-level memor
11350 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75  y allocation rou
11360 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69  tines..**.** Thi
11370 73 20 6f 62 6a 65 63 74 20 69 73 20 75 73 65 64  s object is used
11380 20 69 6e 20 6f 6e 6c 79 20 6f 6e 65 20 70 6c 61   in only one pla
11390 63 65 20 69 6e 20 74 68 65 20 53 51 4c 69 74 65  ce in the SQLite
113a0 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20 41   interface..** A
113b0 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69   pointer to an i
113c0 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20  nstance of this 
113d0 6f 62 6a 65 63 74 20 69 73 20 74 68 65 20 61 72  object is the ar
113e0 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 5b 73 71  gument to.** [sq
113f0 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20  lite3_config()] 
11400 77 68 65 6e 20 74 68 65 20 63 6f 6e 66 69 67 75  when the configu
11410 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73  ration option is
11420 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  .** [SQLITE_CONF
11430 49 47 5f 4d 41 4c 4c 4f 43 5d 20 6f 72 20 5b 53  IG_MALLOC] or [S
11440 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
11450 4d 41 4c 4c 4f 43 5d 2e 20 20 0a 2a 2a 20 42 79  MALLOC].  .** By
11460 20 63 72 65 61 74 69 6e 67 20 61 6e 20 69 6e 73   creating an ins
11470 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62  tance of this ob
11480 6a 65 63 74 0a 2a 2a 20 61 6e 64 20 70 61 73 73  ject.** and pass
11490 69 6e 67 20 69 74 20 74 6f 20 5b 73 71 6c 69 74  ing it to [sqlit
114a0 65 33 5f 63 6f 6e 66 69 67 5d 28 5b 53 51 4c 49  e3_config]([SQLI
114b0 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43  TE_CONFIG_MALLOC
114c0 5d 29 0a 2a 2a 20 64 75 72 69 6e 67 20 63 6f 6e  ]).** during con
114d0 66 69 67 75 72 61 74 69 6f 6e 2c 20 61 6e 20 61  figuration, an a
114e0 70 70 6c 69 63 61 74 69 6f 6e 20 63 61 6e 20 73  pplication can s
114f0 70 65 63 69 66 79 20 61 6e 20 61 6c 74 65 72 6e  pecify an altern
11500 61 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20  ative.** memory 
11510 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73 79  allocation subsy
11520 73 74 65 6d 20 66 6f 72 20 53 51 4c 69 74 65 20  stem for SQLite 
11530 74 6f 20 75 73 65 20 66 6f 72 20 61 6c 6c 20 6f  to use for all o
11540 66 20 69 74 73 0a 2a 2a 20 64 79 6e 61 6d 69 63  f its.** dynamic
11550 20 6d 65 6d 6f 72 79 20 6e 65 65 64 73 2e 0a 2a   memory needs..*
11560 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 53  *.** Note that S
11570 51 4c 69 74 65 20 63 6f 6d 65 73 20 77 69 74 68  QLite comes with
11580 20 73 65 76 65 72 61 6c 20 5b 62 75 69 6c 74 2d   several [built-
11590 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  in memory alloca
115a0 74 6f 72 73 5d 0a 2a 2a 20 74 68 61 74 20 61 72  tors].** that ar
115b0 65 20 70 65 72 66 65 63 74 6c 79 20 61 64 65 71  e perfectly adeq
115c0 75 61 74 65 20 66 6f 72 20 74 68 65 20 6f 76 65  uate for the ove
115d0 72 77 68 65 6c 6d 69 6e 67 20 6d 61 6a 6f 72 69  rwhelming majori
115e0 74 79 20 6f 66 20 61 70 70 6c 69 63 61 74 69 6f  ty of applicatio
115f0 6e 73 0a 2a 2a 20 61 6e 64 20 74 68 61 74 20 74  ns.** and that t
11600 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20 6f 6e  his object is on
11610 6c 79 20 75 73 65 66 75 6c 20 74 6f 20 61 20 74  ly useful to a t
11620 69 6e 79 20 6d 69 6e 6f 72 69 74 79 20 6f 66 20  iny minority of 
11630 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20  applications.** 
11640 77 69 74 68 20 73 70 65 63 69 61 6c 69 7a 65 64  with specialized
11650 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
11660 6f 6e 20 72 65 71 75 69 72 65 6d 65 6e 74 73 2e  on requirements.
11670 20 20 54 68 69 73 20 6f 62 6a 65 63 74 20 69 73    This object is
11680 0a 2a 2a 20 61 6c 73 6f 20 75 73 65 64 20 64 75  .** also used du
11690 72 69 6e 67 20 74 65 73 74 69 6e 67 20 6f 66 20  ring testing of 
116a0 53 51 4c 69 74 65 20 69 6e 20 6f 72 64 65 72 20  SQLite in order 
116b0 74 6f 20 73 70 65 63 69 66 79 20 61 6e 20 61 6c  to specify an al
116c0 74 65 72 6e 61 74 69 76 65 0a 2a 2a 20 6d 65 6d  ternative.** mem
116d0 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 74 68  ory allocator th
116e0 61 74 20 73 69 6d 75 6c 61 74 65 73 20 6d 65 6d  at simulates mem
116f0 6f 72 79 20 6f 75 74 2d 6f 66 2d 6d 65 6d 6f 72  ory out-of-memor
11700 79 20 63 6f 6e 64 69 74 69 6f 6e 73 20 69 6e 0a  y conditions in.
11710 2a 2a 20 6f 72 64 65 72 20 74 6f 20 76 65 72 69  ** order to veri
11720 66 79 20 74 68 61 74 20 53 51 4c 69 74 65 20 72  fy that SQLite r
11730 65 63 6f 76 65 72 73 20 67 72 61 63 65 66 75 6c  ecovers graceful
11740 6c 79 20 66 72 6f 6d 20 73 75 63 68 0a 2a 2a 20  ly from such.** 
11750 63 6f 6e 64 69 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a  conditions..**.*
11760 2a 20 54 68 65 20 78 4d 61 6c 6c 6f 63 2c 20 78  * The xMalloc, x
11770 52 65 61 6c 6c 6f 63 2c 20 61 6e 64 20 78 46 72  Realloc, and xFr
11780 65 65 20 6d 65 74 68 6f 64 73 20 6d 75 73 74 20  ee methods must 
11790 77 6f 72 6b 20 6c 69 6b 65 20 74 68 65 0a 2a 2a  work like the.**
117a0 20 6d 61 6c 6c 6f 63 28 29 2c 20 72 65 61 6c 6c   malloc(), reall
117b0 6f 63 28 29 20 61 6e 64 20 66 72 65 65 28 29 20  oc() and free() 
117c0 66 75 6e 63 74 69 6f 6e 73 20 66 72 6f 6d 20 74  functions from t
117d0 68 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69  he standard C li
117e0 62 72 61 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74  brary..** ^SQLit
117f0 65 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 61  e guarantees tha
11800 74 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67  t the second arg
11810 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 78 52 65 61  ument to.** xRea
11820 6c 6c 6f 63 20 69 73 20 61 6c 77 61 79 73 20 61  lloc is always a
11830 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20   value returned 
11840 62 79 20 61 20 70 72 69 6f 72 20 63 61 6c 6c 20  by a prior call 
11850 74 6f 20 78 52 6f 75 6e 64 75 70 2e 0a 2a 2a 0a  to xRoundup..**.
11860 2a 2a 20 78 53 69 7a 65 20 73 68 6f 75 6c 64 20  ** xSize should 
11870 72 65 74 75 72 6e 20 74 68 65 20 61 6c 6c 6f 63  return the alloc
11880 61 74 65 64 20 73 69 7a 65 20 6f 66 20 61 20 6d  ated size of a m
11890 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
118a0 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 6f  .** previously o
118b0 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 78 4d 61  btained from xMa
118c0 6c 6c 6f 63 20 6f 72 20 78 52 65 61 6c 6c 6f 63  lloc or xRealloc
118d0 2e 20 20 54 68 65 20 61 6c 6c 6f 63 61 74 65 64  .  The allocated
118e0 20 73 69 7a 65 0a 2a 2a 20 69 73 20 61 6c 77 61   size.** is alwa
118f0 79 73 20 61 74 20 6c 65 61 73 74 20 61 73 20 62  ys at least as b
11900 69 67 20 61 73 20 74 68 65 20 72 65 71 75 65 73  ig as the reques
11910 74 65 64 20 73 69 7a 65 20 62 75 74 20 6d 61 79  ted size but may
11920 20 62 65 20 6c 61 72 67 65 72 2e 0a 2a 2a 0a 2a   be larger..**.*
11930 2a 20 54 68 65 20 78 52 6f 75 6e 64 75 70 20 6d  * The xRoundup m
11940 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 77 68  ethod returns wh
11950 61 74 20 77 6f 75 6c 64 20 62 65 20 74 68 65 20  at would be the 
11960 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65 20 6f  allocated size o
11970 66 0a 2a 2a 20 61 20 6d 65 6d 6f 72 79 20 61 6c  f.** a memory al
11980 6c 6f 63 61 74 69 6f 6e 20 67 69 76 65 6e 20 61  location given a
11990 20 70 61 72 74 69 63 75 6c 61 72 20 72 65 71 75   particular requ
119a0 65 73 74 65 64 20 73 69 7a 65 2e 20 20 4d 6f 73  ested size.  Mos
119b0 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f  t memory.** allo
119c0 63 61 74 6f 72 73 20 72 6f 75 6e 64 20 75 70 20  cators round up 
119d0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
119e0 6e 73 20 61 74 20 6c 65 61 73 74 20 74 6f 20 74  ns at least to t
119f0 68 65 20 6e 65 78 74 20 6d 75 6c 74 69 70 6c 65  he next multiple
11a00 0a 2a 2a 20 6f 66 20 38 2e 20 20 53 6f 6d 65 20  .** of 8.  Some 
11a10 61 6c 6c 6f 63 61 74 6f 72 73 20 72 6f 75 6e 64  allocators round
11a20 20 75 70 20 74 6f 20 61 20 6c 61 72 67 65 72 20   up to a larger 
11a30 6d 75 6c 74 69 70 6c 65 20 6f 72 20 74 6f 20 61  multiple or to a
11a40 20 70 6f 77 65 72 20 6f 66 20 32 2e 0a 2a 2a 20   power of 2..** 
11a50 45 76 65 72 79 20 6d 65 6d 6f 72 79 20 61 6c 6c  Every memory all
11a60 6f 63 61 74 69 6f 6e 20 72 65 71 75 65 73 74 20  ocation request 
11a70 63 6f 6d 69 6e 67 20 69 6e 20 74 68 72 6f 75 67  coming in throug
11a80 68 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  h [sqlite3_mallo
11a90 63 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69  c()].** or [sqli
11aa0 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 20 66  te3_realloc()] f
11ab0 69 72 73 74 20 63 61 6c 6c 73 20 78 52 6f 75 6e  irst calls xRoun
11ac0 64 75 70 2e 20 20 49 66 20 78 52 6f 75 6e 64 75  dup.  If xRoundu
11ad0 70 20 72 65 74 75 72 6e 73 20 30 2c 20 0a 2a 2a  p returns 0, .**
11ae0 20 74 68 61 74 20 63 61 75 73 65 73 20 74 68 65   that causes the
11af0 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 6d   corresponding m
11b00 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
11b10 20 74 6f 20 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20   to fail..**.** 
11b20 54 68 65 20 78 49 6e 69 74 20 6d 65 74 68 6f 64  The xInit method
11b30 20 69 6e 69 74 69 61 6c 69 7a 65 73 20 74 68 65   initializes the
11b40 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f   memory allocato
11b50 72 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c  r.  For example,
11b60 0a 2a 2a 20 69 74 20 6d 69 67 68 74 20 61 6c 6c  .** it might all
11b70 6f 63 61 74 65 20 61 6e 79 20 72 65 71 75 69 72  ocate any requir
11b80 65 20 6d 75 74 65 78 65 73 20 6f 72 20 69 6e 69  e mutexes or ini
11b90 74 69 61 6c 69 7a 65 20 69 6e 74 65 72 6e 61 6c  tialize internal
11ba0 20 64 61 74 61 0a 2a 2a 20 73 74 72 75 63 74 75   data.** structu
11bb0 72 65 73 2e 20 20 54 68 65 20 78 53 68 75 74 64  res.  The xShutd
11bc0 6f 77 6e 20 6d 65 74 68 6f 64 20 69 73 20 69 6e  own method is in
11bd0 76 6f 6b 65 64 20 28 69 6e 64 69 72 65 63 74 6c  voked (indirectl
11be0 79 29 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65  y) by.** [sqlite
11bf0 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20 61 6e  3_shutdown()] an
11c00 64 20 73 68 6f 75 6c 64 20 64 65 61 6c 6c 6f 63  d should dealloc
11c10 61 74 65 20 61 6e 79 20 72 65 73 6f 75 72 63 65  ate any resource
11c20 73 20 61 63 71 75 69 72 65 64 0a 2a 2a 20 62 79  s acquired.** by
11c30 20 78 49 6e 69 74 2e 20 20 54 68 65 20 70 41 70   xInit.  The pAp
11c40 70 44 61 74 61 20 70 6f 69 6e 74 65 72 20 69 73  pData pointer is
11c50 20 75 73 65 64 20 61 73 20 74 68 65 20 6f 6e 6c   used as the onl
11c60 79 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a  y parameter to.*
11c70 2a 20 78 49 6e 69 74 20 61 6e 64 20 78 53 68 75  * xInit and xShu
11c80 74 64 6f 77 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c  tdown..**.** SQL
11c90 69 74 65 20 68 6f 6c 64 73 20 74 68 65 20 5b 53  ite holds the [S
11ca0 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54  QLITE_MUTEX_STAT
11cb0 49 43 5f 4d 41 53 54 45 52 5d 20 6d 75 74 65 78  IC_MASTER] mutex
11cc0 20 77 68 65 6e 20 69 74 20 69 6e 76 6f 6b 65 73   when it invokes
11cd0 0a 2a 2a 20 74 68 65 20 78 49 6e 69 74 20 6d 65  .** the xInit me
11ce0 74 68 6f 64 2c 20 73 6f 20 74 68 65 20 78 49 6e  thod, so the xIn
11cf0 69 74 20 6d 65 74 68 6f 64 20 6e 65 65 64 20 6e  it method need n
11d00 6f 74 20 62 65 20 74 68 72 65 61 64 73 61 66 65  ot be threadsafe
11d10 2e 20 20 54 68 65 0a 2a 2a 20 78 53 68 75 74 64  .  The.** xShutd
11d20 6f 77 6e 20 6d 65 74 68 6f 64 20 69 73 20 6f 6e  own method is on
11d30 6c 79 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 5b  ly called from [
11d40 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
11d50 28 29 5d 20 73 6f 20 69 74 20 64 6f 65 73 0a 2a  ()] so it does.*
11d60 2a 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65  * not need to be
11d70 20 74 68 72 65 61 64 73 61 66 65 20 65 69 74 68   threadsafe eith
11d80 65 72 2e 20 20 46 6f 72 20 61 6c 6c 20 6f 74 68  er.  For all oth
11d90 65 72 20 6d 65 74 68 6f 64 73 2c 20 53 51 4c 69  er methods, SQLi
11da0 74 65 0a 2a 2a 20 68 6f 6c 64 73 20 74 68 65 20  te.** holds the 
11db0 5b 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54  [SQLITE_MUTEX_ST
11dc0 41 54 49 43 5f 4d 45 4d 5d 20 6d 75 74 65 78 20  ATIC_MEM] mutex 
11dd0 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 0a 2a  as long as the.*
11de0 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  * [SQLITE_CONFIG
11df0 5f 4d 45 4d 53 54 41 54 55 53 5d 20 63 6f 6e 66  _MEMSTATUS] conf
11e00 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
11e10 20 69 73 20 74 75 72 6e 65 64 20 6f 6e 20 28 77   is turned on (w
11e20 68 69 63 68 0a 2a 2a 20 69 74 20 69 73 20 62 79  hich.** it is by
11e30 20 64 65 66 61 75 6c 74 29 20 61 6e 64 20 73 6f   default) and so
11e40 20 74 68 65 20 6d 65 74 68 6f 64 73 20 61 72 65   the methods are
11e50 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 73   automatically s
11e60 65 72 69 61 6c 69 7a 65 64 2e 0a 2a 2a 20 48 6f  erialized..** Ho
11e70 77 65 76 65 72 2c 20 69 66 20 5b 53 51 4c 49 54  wever, if [SQLIT
11e80 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54  E_CONFIG_MEMSTAT
11e90 55 53 5d 20 69 73 20 64 69 73 61 62 6c 65 64 2c  US] is disabled,
11ea0 20 74 68 65 6e 20 74 68 65 20 6f 74 68 65 72 0a   then the other.
11eb0 2a 2a 20 6d 65 74 68 6f 64 73 20 6d 75 73 74 20  ** methods must 
11ec0 62 65 20 74 68 72 65 61 64 73 61 66 65 20 6f 72  be threadsafe or
11ed0 20 65 6c 73 65 20 6d 61 6b 65 20 74 68 65 69 72   else make their
11ee0 20 6f 77 6e 20 61 72 72 61 6e 67 65 6d 65 6e 74   own arrangement
11ef0 73 20 66 6f 72 0a 2a 2a 20 73 65 72 69 61 6c 69  s for.** seriali
11f00 7a 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51  zation..**.** SQ
11f10 4c 69 74 65 20 77 69 6c 6c 20 6e 65 76 65 72 20  Lite will never 
11f20 69 6e 76 6f 6b 65 20 78 49 6e 69 74 28 29 20 6d  invoke xInit() m
11f30 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65 20 77 69  ore than once wi
11f40 74 68 6f 75 74 20 61 6e 20 69 6e 74 65 72 76 65  thout an interve
11f50 6e 69 6e 67 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20  ning.** call to 
11f60 78 53 68 75 74 64 6f 77 6e 28 29 2e 0a 2a 2f 0a  xShutdown()..*/.
11f70 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73  typedef struct s
11f80 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f  qlite3_mem_metho
11f90 64 73 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d  ds sqlite3_mem_m
11fa0 65 74 68 6f 64 73 3b 0a 73 74 72 75 63 74 20 73  ethods;.struct s
11fb0 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f  qlite3_mem_metho
11fc0 64 73 20 7b 0a 20 20 76 6f 69 64 20 2a 28 2a 78  ds {.  void *(*x
11fd0 4d 61 6c 6c 6f 63 29 28 69 6e 74 29 3b 20 20 20  Malloc)(int);   
11fe0 20 20 20 20 20 20 2f 2a 20 4d 65 6d 6f 72 79 20        /* Memory 
11ff0 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 75 6e 63 74  allocation funct
12000 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 28 2a  ion */.  void (*
12010 78 46 72 65 65 29 28 76 6f 69 64 2a 29 3b 20 20  xFree)(void*);  
12020 20 20 20 20 20 20 20 20 2f 2a 20 46 72 65 65 20          /* Free 
12030 61 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69  a prior allocati
12040 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 28 2a  on */.  void *(*
12050 78 52 65 61 6c 6c 6f 63 29 28 76 6f 69 64 2a 2c  xRealloc)(void*,
12060 69 6e 74 29 3b 20 20 2f 2a 20 52 65 73 69 7a 65  int);  /* Resize
12070 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a   an allocation *
12080 2f 0a 20 20 69 6e 74 20 28 2a 78 53 69 7a 65 29  /.  int (*xSize)
12090 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 20  (void*);        
120a0 20 20 20 2f 2a 20 52 65 74 75 72 6e 20 74 68 65     /* Return the
120b0 20 73 69 7a 65 20 6f 66 20 61 6e 20 61 6c 6c 6f   size of an allo
120c0 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20  cation */.  int 
120d0 28 2a 78 52 6f 75 6e 64 75 70 29 28 69 6e 74 29  (*xRoundup)(int)
120e0 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20 52 6f  ;          /* Ro
120f0 75 6e 64 20 75 70 20 72 65 71 75 65 73 74 20 73  und up request s
12100 69 7a 65 20 74 6f 20 61 6c 6c 6f 63 61 74 69 6f  ize to allocatio
12110 6e 20 73 69 7a 65 20 2a 2f 0a 20 20 69 6e 74 20  n size */.  int 
12120 28 2a 78 49 6e 69 74 29 28 76 6f 69 64 2a 29 3b  (*xInit)(void*);
12130 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 49 6e             /* In
12140 69 74 69 61 6c 69 7a 65 20 74 68 65 20 6d 65 6d  itialize the mem
12150 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f  ory allocator */
12160 0a 20 20 76 6f 69 64 20 28 2a 78 53 68 75 74 64  .  void (*xShutd
12170 6f 77 6e 29 28 76 6f 69 64 2a 29 3b 20 20 20 20  own)(void*);    
12180 20 20 2f 2a 20 44 65 69 6e 69 74 69 61 6c 69 7a    /* Deinitializ
12190 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c  e the memory all
121a0 6f 63 61 74 6f 72 20 2a 2f 0a 20 20 76 6f 69 64  ocator */.  void
121b0 20 2a 70 41 70 70 44 61 74 61 3b 20 20 20 20 20   *pAppData;     
121c0 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 41 72             /* Ar
121d0 67 75 6d 65 6e 74 20 74 6f 20 78 49 6e 69 74 28  gument to xInit(
121e0 29 20 61 6e 64 20 78 53 68 75 74 64 6f 77 6e 28  ) and xShutdown(
121f0 29 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ) */.};../*.** C
12200 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 75  API3REF: Configu
12210 72 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 0a 2a  ration Options.*
12220 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 63 6f 6e  * KEYWORDS: {con
12230 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
12240 6e 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63  n}.**.** These c
12250 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 74 68 65  onstants are the
12260 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 74 65 67   available integ
12270 65 72 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  er configuration
12280 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 0a 2a 2a   options that.**
12290 20 63 61 6e 20 62 65 20 70 61 73 73 65 64 20 61   can be passed a
122a0 73 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  s the first argu
122b0 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b 73 71 6c  ment to the [sql
122c0 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 69  ite3_config()] i
122d0 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20  nterface..**.** 
122e0 4e 65 77 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  New configuratio
122f0 6e 20 6f 70 74 69 6f 6e 73 20 6d 61 79 20 62 65  n options may be
12300 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65   added in future
12310 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c   releases of SQL
12320 69 74 65 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67  ite..** Existing
12330 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
12340 70 74 69 6f 6e 73 20 6d 69 67 68 74 20 62 65 20  ptions might be 
12350 64 69 73 63 6f 6e 74 69 6e 75 65 64 2e 20 20 41  discontinued.  A
12360 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73  pplications.** s
12370 68 6f 75 6c 64 20 63 68 65 63 6b 20 74 68 65 20  hould check the 
12380 72 65 74 75 72 6e 20 63 6f 64 65 20 66 72 6f 6d  return code from
12390 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
123a0 28 29 5d 20 74 6f 20 6d 61 6b 65 20 73 75 72 65  ()] to make sure
123b0 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 63 61 6c   that.** the cal
123c0 6c 20 77 6f 72 6b 65 64 2e 20 20 54 68 65 20 5b  l worked.  The [
123d0 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
123e0 5d 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c  ] interface will
123f0 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e   return a.** non
12400 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64  -zero [error cod
12410 65 5d 20 69 66 20 61 20 64 69 73 63 6f 6e 74 69  e] if a disconti
12420 6e 75 65 64 20 6f 72 20 75 6e 73 75 70 70 6f 72  nued or unsuppor
12430 74 65 64 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ted configuratio
12440 6e 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73 20 69  n option.** is i
12450 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64  nvoked..**.** <d
12460 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  l>.** [[SQLITE_C
12470 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45  ONFIG_SINGLETHRE
12480 41 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  AD]] <dt>SQLITE_
12490 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52  CONFIG_SINGLETHR
124a0 45 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  EAD</dt>.** <dd>
124b0 54 68 65 72 65 20 61 72 65 20 6e 6f 20 61 72 67  There are no arg
124c0 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f  uments to this o
124d0 70 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70  ption.  ^This op
124e0 74 69 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a  tion sets the.**
124f0 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65   [threading mode
12500 5d 20 74 6f 20 53 69 6e 67 6c 65 2d 74 68 72 65  ] to Single-thre
12510 61 64 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f  ad.  In other wo
12520 72 64 73 2c 20 69 74 20 64 69 73 61 62 6c 65 73  rds, it disables
12530 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65 78 69 6e 67  .** all mutexing
12540 20 61 6e 64 20 70 75 74 73 20 53 51 4c 69 74 65   and puts SQLite
12550 20 69 6e 74 6f 20 61 20 6d 6f 64 65 20 77 68 65   into a mode whe
12560 72 65 20 69 74 20 63 61 6e 20 6f 6e 6c 79 20 62  re it can only b
12570 65 20 75 73 65 64 0a 2a 2a 20 62 79 20 61 20 73  e used.** by a s
12580 69 6e 67 6c 65 20 74 68 72 65 61 64 2e 20 20 20  ingle thread.   
12590 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f  ^If SQLite is co
125a0 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74  mpiled with.** t
125b0 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41  he [SQLITE_THREA
125c0 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54  DSAFE | SQLITE_T
125d0 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d  HREADSAFE=0] com
125e0 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
125f0 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e   then.** it is n
12600 6f 74 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 63  ot possible to c
12610 68 61 6e 67 65 20 74 68 65 20 5b 74 68 72 65 61  hange the [threa
12620 64 69 6e 67 20 6d 6f 64 65 5d 20 66 72 6f 6d 20  ding mode] from 
12630 69 74 73 20 64 65 66 61 75 6c 74 0a 2a 2a 20 76  its default.** v
12640 61 6c 75 65 20 6f 66 20 53 69 6e 67 6c 65 2d 74  alue of Single-t
12650 68 72 65 61 64 20 61 6e 64 20 73 6f 20 5b 73 71  hread and so [sq
12660 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20  lite3_config()] 
12670 77 69 6c 6c 20 72 65 74 75 72 6e 20 0a 2a 2a 20  will return .** 
12680 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69  [SQLITE_ERROR] i
12690 66 20 63 61 6c 6c 65 64 20 77 69 74 68 20 74 68  f called with th
126a0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
126b0 53 49 4e 47 4c 45 54 48 52 45 41 44 0a 2a 2a 20  SINGLETHREAD.** 
126c0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
126d0 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  tion.</dd>.**.**
126e0 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
126f0 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d 5d 20 3c  _MULTITHREAD]] <
12700 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
12710 5f 4d 55 4c 54 49 54 48 52 45 41 44 3c 2f 64 74  _MULTITHREAD</dt
12720 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 61  >.** <dd>There a
12730 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20  re no arguments 
12740 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20  to this option. 
12750 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 65   ^This option se
12760 74 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61  ts the.** [threa
12770 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 4d 75  ding mode] to Mu
12780 6c 74 69 2d 74 68 72 65 61 64 2e 20 20 49 6e 20  lti-thread.  In 
12790 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 69 74 20  other words, it 
127a0 64 69 73 61 62 6c 65 73 0a 2a 2a 20 6d 75 74 65  disables.** mute
127b0 78 69 6e 67 20 6f 6e 20 5b 64 61 74 61 62 61 73  xing on [databas
127c0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e  e connection] an
127d0 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  d [prepared stat
127e0 65 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 73 2e 0a  ement] objects..
127f0 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  ** The applicati
12800 6f 6e 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c  on is responsibl
12810 65 20 66 6f 72 20 73 65 72 69 61 6c 69 7a 69 6e  e for serializin
12820 67 20 61 63 63 65 73 73 20 74 6f 0a 2a 2a 20 5b  g access to.** [
12830 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
12840 69 6f 6e 73 5d 20 61 6e 64 20 5b 70 72 65 70 61  ions] and [prepa
12850 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 2e  red statements].
12860 20 20 42 75 74 20 6f 74 68 65 72 20 6d 75 74 65    But other mute
12870 78 65 73 0a 2a 2a 20 61 72 65 20 65 6e 61 62 6c  xes.** are enabl
12880 65 64 20 73 6f 20 74 68 61 74 20 53 51 4c 69 74  ed so that SQLit
12890 65 20 77 69 6c 6c 20 62 65 20 73 61 66 65 20 74  e will be safe t
128a0 6f 20 75 73 65 20 69 6e 20 61 20 6d 75 6c 74 69  o use in a multi
128b0 2d 74 68 72 65 61 64 65 64 0a 2a 2a 20 65 6e 76  -threaded.** env
128c0 69 72 6f 6e 6d 65 6e 74 20 61 73 20 6c 6f 6e 67  ironment as long
128d0 20 61 73 20 6e 6f 20 74 77 6f 20 74 68 72 65 61   as no two threa
128e0 64 73 20 61 74 74 65 6d 70 74 20 74 6f 20 75 73  ds attempt to us
128f0 65 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 5b 64  e the same.** [d
12900 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
12910 6f 6e 5d 20 61 74 20 74 68 65 20 73 61 6d 65 20  on] at the same 
12920 74 69 6d 65 2e 20 20 5e 49 66 20 53 51 4c 69 74  time.  ^If SQLit
12930 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69  e is compiled wi
12940 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54  th.** the [SQLIT
12950 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20 53  E_THREADSAFE | S
12960 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
12970 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  =0] compile-time
12980 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20   option then.** 
12990 69 74 20 69 73 20 6e 6f 74 20 70 6f 73 73 69 62  it is not possib
129a0 6c 65 20 74 6f 20 73 65 74 20 74 68 65 20 4d 75  le to set the Mu
129b0 6c 74 69 2d 74 68 72 65 61 64 20 5b 74 68 72 65  lti-thread [thre
129c0 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61 6e 64 0a  ading mode] and.
129d0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  ** [sqlite3_conf
129e0 69 67 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72  ig()] will retur
129f0 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d  n [SQLITE_ERROR]
12a00 20 69 66 20 63 61 6c 6c 65 64 20 77 69 74 68 20   if called with 
12a10 74 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 43 4f  the.** SQLITE_CO
12a20 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44  NFIG_MULTITHREAD
12a30 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
12a40 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  ption.</dd>.**.*
12a50 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
12a60 47 5f 53 45 52 49 41 4c 49 5a 45 44 5d 5d 20 3c  G_SERIALIZED]] <
12a70 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
12a80 5f 53 45 52 49 41 4c 49 5a 45 44 3c 2f 64 74 3e  _SERIALIZED</dt>
12a90 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72  .** <dd>There ar
12aa0 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74  e no arguments t
12ab0 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20  o this option.  
12ac0 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74  ^This option set
12ad0 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64  s the.** [thread
12ae0 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 53 65 72  ing mode] to Ser
12af0 69 61 6c 69 7a 65 64 2e 20 49 6e 20 6f 74 68 65  ialized. In othe
12b00 72 20 77 6f 72 64 73 2c 20 74 68 69 73 20 6f 70  r words, this op
12b10 74 69 6f 6e 20 65 6e 61 62 6c 65 73 0a 2a 2a 20  tion enables.** 
12b20 61 6c 6c 20 6d 75 74 65 78 65 73 20 69 6e 63 6c  all mutexes incl
12b30 75 64 69 6e 67 20 74 68 65 20 72 65 63 75 72 73  uding the recurs
12b40 69 76 65 0a 2a 2a 20 6d 75 74 65 78 65 73 20 6f  ive.** mutexes o
12b50 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  n [database conn
12b60 65 63 74 69 6f 6e 5d 20 61 6e 64 20 5b 70 72 65  ection] and [pre
12b70 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
12b80 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 49 6e 20   objects..** In 
12b90 74 68 69 73 20 6d 6f 64 65 20 28 77 68 69 63 68  this mode (which
12ba0 20 69 73 20 74 68 65 20 64 65 66 61 75 6c 74 20   is the default 
12bb0 77 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20 63  when SQLite is c
12bc0 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20  ompiled with.** 
12bd0 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41  [SQLITE_THREADSA
12be0 46 45 3d 31 5d 29 20 74 68 65 20 53 51 4c 69 74  FE=1]) the SQLit
12bf0 65 20 6c 69 62 72 61 72 79 20 77 69 6c 6c 20 69  e library will i
12c00 74 73 65 6c 66 20 73 65 72 69 61 6c 69 7a 65 20  tself serialize 
12c10 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20 5b 64 61  access.** to [da
12c20 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
12c30 6e 73 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65  ns] and [prepare
12c40 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 20 73 6f  d statements] so
12c50 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 61 70 70   that the.** app
12c60 6c 69 63 61 74 69 6f 6e 20 69 73 20 66 72 65 65  lication is free
12c70 20 74 6f 20 75 73 65 20 74 68 65 20 73 61 6d 65   to use the same
12c80 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
12c90 63 74 69 6f 6e 5d 20 6f 72 20 74 68 65 0a 2a 2a  ction] or the.**
12ca0 20 73 61 6d 65 20 5b 70 72 65 70 61 72 65 64 20   same [prepared 
12cb0 73 74 61 74 65 6d 65 6e 74 5d 20 69 6e 20 64 69  statement] in di
12cc0 66 66 65 72 65 6e 74 20 74 68 72 65 61 64 73 20  fferent threads 
12cd0 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65  at the same time
12ce0 2e 0a 2a 2a 20 5e 49 66 20 53 51 4c 69 74 65 20  ..** ^If SQLite 
12cf0 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  is compiled with
12d00 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  .** the [SQLITE_
12d10 54 48 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c  THREADSAFE | SQL
12d20 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30  ITE_THREADSAFE=0
12d30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
12d40 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74  ption then.** it
12d50 20 69 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65   is not possible
12d60 20 74 6f 20 73 65 74 20 74 68 65 20 53 65 72 69   to set the Seri
12d70 61 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e  alized [threadin
12d80 67 20 6d 6f 64 65 5d 20 61 6e 64 0a 2a 2a 20 5b  g mode] and.** [
12d90 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
12da0 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53  ] will return [S
12db0 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20  QLITE_ERROR] if 
12dc0 63 61 6c 6c 65 64 20 77 69 74 68 20 74 68 65 0a  called with the.
12dd0 2a 2a 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ** SQLITE_CONFIG
12de0 5f 53 45 52 49 41 4c 49 5a 45 44 20 63 6f 6e 66  _SERIALIZED conf
12df0 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
12e00 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  .</dd>.**.** [[S
12e10 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c  QLITE_CONFIG_MAL
12e20 4c 4f 43 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45  LOC]] <dt>SQLITE
12e30 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 3c 2f  _CONFIG_MALLOC</
12e40 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68  dt>.** <dd> ^(Th
12e50 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
12e60 4d 41 4c 4c 4f 43 20 6f 70 74 69 6f 6e 20 74 61  MALLOC option ta
12e70 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67  kes a single arg
12e80 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 0a  ument which is .
12e90 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ** a pointer to 
12ea0 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  an instance of t
12eb0 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f  he [sqlite3_mem_
12ec0 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75  methods] structu
12ed0 72 65 2e 0a 2a 2a 20 54 68 65 20 61 72 67 75 6d  re..** The argum
12ee0 65 6e 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a  ent specifies.**
12ef0 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6c 6f 77   alternative low
12f00 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72 79 20 61 6c  -level memory al
12f10 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65  location routine
12f20 73 20 74 6f 20 62 65 20 75 73 65 64 20 69 6e 20  s to be used in 
12f30 70 6c 61 63 65 20 6f 66 0a 2a 2a 20 74 68 65 20  place of.** the 
12f40 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
12f50 6e 20 72 6f 75 74 69 6e 65 73 20 62 75 69 6c 74  n routines built
12f60 20 69 6e 74 6f 20 53 51 4c 69 74 65 2e 29 5e 20   into SQLite.)^ 
12f70 5e 53 51 4c 69 74 65 20 6d 61 6b 65 73 0a 2a 2a  ^SQLite makes.**
12f80 20 69 74 73 20 6f 77 6e 20 70 72 69 76 61 74 65   its own private
12f90 20 63 6f 70 79 20 6f 66 20 74 68 65 20 63 6f 6e   copy of the con
12fa0 74 65 6e 74 20 6f 66 20 74 68 65 20 5b 73 71 6c  tent of the [sql
12fb0 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73  ite3_mem_methods
12fc0 5d 20 73 74 72 75 63 74 75 72 65 0a 2a 2a 20 62  ] structure.** b
12fd0 65 66 6f 72 65 20 74 68 65 20 5b 73 71 6c 69 74  efore the [sqlit
12fe0 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 63 61 6c  e3_config()] cal
12ff0 6c 20 72 65 74 75 72 6e 73 2e 3c 2f 64 64 3e 0a  l returns.</dd>.
13000 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
13010 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 5d  ONFIG_GETMALLOC]
13020 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
13030 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 3c 2f 64  FIG_GETMALLOC</d
13040 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65  t>.** <dd> ^(The
13050 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47   SQLITE_CONFIG_G
13060 45 54 4d 41 4c 4c 4f 43 20 6f 70 74 69 6f 6e 20  ETMALLOC option 
13070 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61  takes a single a
13080 72 67 75 6d 65 6e 74 20 77 68 69 63 68 0a 2a 2a  rgument which.**
13090 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
130a0 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20   an instance of 
130b0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  the [sqlite3_mem
130c0 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74  _methods] struct
130d0 75 72 65 2e 0a 2a 2a 20 54 68 65 20 5b 73 71 6c  ure..** The [sql
130e0 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73  ite3_mem_methods
130f0 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 69  ].** structure i
13100 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20 74 68  s filled with th
13110 65 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69  e currently defi
13120 6e 65 64 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ned memory alloc
13130 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 2e 29  ation routines.)
13140 5e 0a 2a 2a 20 54 68 69 73 20 6f 70 74 69 6f 6e  ^.** This option
13150 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
13160 6f 76 65 72 6c 6f 61 64 20 74 68 65 20 64 65 66  overload the def
13170 61 75 6c 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  ault memory allo
13180 63 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e  cation.** routin
13190 65 73 20 77 69 74 68 20 61 20 77 72 61 70 70 65  es with a wrappe
131a0 72 20 74 68 61 74 20 73 69 6d 75 6c 61 74 69 6f  r that simulatio
131b0 6e 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  ns memory alloca
131c0 74 69 6f 6e 20 66 61 69 6c 75 72 65 20 6f 72 0a  tion failure or.
131d0 2a 2a 20 74 72 61 63 6b 73 20 6d 65 6d 6f 72 79  ** tracks memory
131e0 20 75 73 61 67 65 2c 20 66 6f 72 20 65 78 61 6d   usage, for exam
131f0 70 6c 65 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  ple. </dd>.**.**
13200 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
13210 5f 4d 45 4d 53 54 41 54 55 53 5d 5d 20 3c 64 74  _MEMSTATUS]] <dt
13220 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  >SQLITE_CONFIG_M
13230 45 4d 53 54 41 54 55 53 3c 2f 64 74 3e 0a 2a 2a  EMSTATUS</dt>.**
13240 20 3c 64 64 3e 20 5e 54 68 65 20 53 51 4c 49 54   <dd> ^The SQLIT
13250 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54  E_CONFIG_MEMSTAT
13260 55 53 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  US option takes 
13270 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20  single argument 
13280 6f 66 20 74 79 70 65 20 69 6e 74 2c 0a 2a 2a 20  of type int,.** 
13290 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 61  interpreted as a
132a0 20 62 6f 6f 6c 65 61 6e 2c 20 77 68 69 63 68 20   boolean, which 
132b0 65 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62  enables or disab
132c0 6c 65 73 20 74 68 65 20 63 6f 6c 6c 65 63 74 69  les the collecti
132d0 6f 6e 20 6f 66 0a 2a 2a 20 6d 65 6d 6f 72 79 20  on of.** memory 
132e0 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 69  allocation stati
132f0 73 74 69 63 73 2e 20 5e 28 57 68 65 6e 20 6d 65  stics. ^(When me
13300 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
13310 73 74 61 74 69 73 74 69 63 73 20 61 72 65 0a 2a  statistics are.*
13320 2a 20 64 69 73 61 62 6c 65 64 2c 20 74 68 65 20  * disabled, the 
13330 66 6f 6c 6c 6f 77 69 6e 67 20 53 51 4c 69 74 65  following SQLite
13340 20 69 6e 74 65 72 66 61 63 65 73 20 62 65 63 6f   interfaces beco
13350 6d 65 20 6e 6f 6e 2d 6f 70 65 72 61 74 69 6f 6e  me non-operation
13360 61 6c 3a 0a 2a 2a 20 20 20 3c 75 6c 3e 0a 2a 2a  al:.**   <ul>.**
13370 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33     <li> [sqlite3
13380 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 0a  _memory_used()].
13390 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74  **   <li> [sqlit
133a0 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61  e3_memory_highwa
133b0 74 65 72 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e  ter()].**   <li>
133c0 20 5b 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68   [sqlite3_soft_h
133d0 65 61 70 5f 6c 69 6d 69 74 36 34 28 29 5d 0a 2a  eap_limit64()].*
133e0 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65  *   <li> [sqlite
133f0 33 5f 73 74 61 74 75 73 36 34 28 29 5d 0a 2a 2a  3_status64()].**
13400 20 20 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 20 5e 4d     </ul>)^.** ^M
13410 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
13420 20 73 74 61 74 69 73 74 69 63 73 20 61 72 65 20   statistics are 
13430 65 6e 61 62 6c 65 64 20 62 79 20 64 65 66 61 75  enabled by defau
13440 6c 74 20 75 6e 6c 65 73 73 20 53 51 4c 69 74 65  lt unless SQLite
13450 20 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20   is.** compiled 
13460 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 44 45 46  with [SQLITE_DEF
13470 41 55 4c 54 5f 4d 45 4d 53 54 41 54 55 53 5d 3d  AULT_MEMSTATUS]=
13480 30 20 69 6e 20 77 68 69 63 68 20 63 61 73 65 20  0 in which case 
13490 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61  memory.** alloca
134a0 74 69 6f 6e 20 73 74 61 74 69 73 74 69 63 73 20  tion statistics 
134b0 61 72 65 20 64 69 73 61 62 6c 65 64 20 62 79 20  are disabled by 
134c0 64 65 66 61 75 6c 74 2e 0a 2a 2a 20 3c 2f 64 64  default..** </dd
134d0 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
134e0 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 5d  _CONFIG_SCRATCH]
134f0 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
13500 46 49 47 5f 53 43 52 41 54 43 48 3c 2f 64 74 3e  FIG_SCRATCH</dt>
13510 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 65 20 53 51  .** <dd> ^The SQ
13520 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41  LITE_CONFIG_SCRA
13530 54 43 48 20 6f 70 74 69 6f 6e 20 73 70 65 63 69  TCH option speci
13540 66 69 65 73 20 61 20 73 74 61 74 69 63 20 6d 65  fies a static me
13550 6d 6f 72 79 20 62 75 66 66 65 72 0a 2a 2a 20 74  mory buffer.** t
13560 68 61 74 20 53 51 4c 69 74 65 20 63 61 6e 20 75  hat SQLite can u
13570 73 65 20 66 6f 72 20 73 63 72 61 74 63 68 20 6d  se for scratch m
13580 65 6d 6f 72 79 2e 20 20 5e 28 54 68 65 72 65 20  emory.  ^(There 
13590 61 72 65 20 74 68 72 65 65 20 61 72 67 75 6d 65  are three argume
135a0 6e 74 73 0a 2a 2a 20 74 6f 20 53 51 4c 49 54 45  nts.** to SQLITE
135b0 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 3a  _CONFIG_SCRATCH:
135c0 20 20 41 20 70 6f 69 6e 74 65 72 20 61 6e 20 38    A pointer an 8
135d0 2d 62 79 74 65 0a 2a 2a 20 61 6c 69 67 6e 65 64  -byte.** aligned
135e0 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 66   memory buffer f
135f0 72 6f 6d 20 77 68 69 63 68 20 74 68 65 20 73 63  rom which the sc
13600 72 61 74 63 68 20 61 6c 6c 6f 63 61 74 69 6f 6e  ratch allocation
13610 73 20 77 69 6c 6c 20 62 65 0a 2a 2a 20 64 72 61  s will be.** dra
13620 77 6e 2c 20 74 68 65 20 73 69 7a 65 20 6f 66 20  wn, the size of 
13630 65 61 63 68 20 73 63 72 61 74 63 68 20 61 6c 6c  each scratch all
13640 6f 63 61 74 69 6f 6e 20 28 73 7a 29 2c 0a 2a 2a  ocation (sz),.**
13650 20 61 6e 64 20 74 68 65 20 6d 61 78 69 6d 75 6d   and the maximum
13660 20 6e 75 6d 62 65 72 20 6f 66 20 73 63 72 61 74   number of scrat
13670 63 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 28  ch allocations (
13680 4e 29 2e 29 5e 0a 2a 2a 20 54 68 65 20 66 69 72  N).)^.** The fir
13690 73 74 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 74  st argument must
136a0 20 62 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   be a pointer to
136b0 20 61 6e 20 38 2d 62 79 74 65 20 61 6c 69 67 6e   an 8-byte align
136c0 65 64 20 62 75 66 66 65 72 0a 2a 2a 20 6f 66 20  ed buffer.** of 
136d0 61 74 20 6c 65 61 73 74 20 73 7a 2a 4e 20 62 79  at least sz*N by
136e0 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 2e 0a 2a  tes of memory..*
136f0 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 6e  * ^SQLite will n
13700 6f 74 20 75 73 65 20 6d 6f 72 65 20 74 68 61 6e  ot use more than
13710 20 6f 6e 65 20 73 63 72 61 74 63 68 20 62 75 66   one scratch buf
13720 66 65 72 73 20 70 65 72 20 74 68 72 65 61 64 2e  fers per thread.
13730 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c  .** ^SQLite will
13740 20 6e 65 76 65 72 20 72 65 71 75 65 73 74 20 61   never request a
13750 20 73 63 72 61 74 63 68 20 62 75 66 66 65 72 20   scratch buffer 
13760 74 68 61 74 20 69 73 20 6d 6f 72 65 20 74 68 61  that is more tha
13770 6e 20 36 0a 2a 2a 20 74 69 6d 65 73 20 74 68 65  n 6.** times the
13780 20 64 61 74 61 62 61 73 65 20 70 61 67 65 20 73   database page s
13790 69 7a 65 2e 0a 2a 2a 20 5e 49 66 20 53 51 4c 69  ize..** ^If SQLi
137a0 74 65 20 6e 65 65 64 73 20 6e 65 65 64 73 20 61  te needs needs a
137b0 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 73 63 72  dditional.** scr
137c0 61 74 63 68 20 6d 65 6d 6f 72 79 20 62 65 79 6f  atch memory beyo
137d0 6e 64 20 77 68 61 74 20 69 73 20 70 72 6f 76 69  nd what is provi
137e0 64 65 64 20 62 79 20 74 68 69 73 20 63 6f 6e 66  ded by this conf
137f0 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
13800 2c 20 74 68 65 6e 20 0a 2a 2a 20 5b 73 71 6c 69  , then .** [sqli
13810 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 77 69  te3_malloc()] wi
13820 6c 6c 20 62 65 20 75 73 65 64 20 74 6f 20 6f 62  ll be used to ob
13830 74 61 69 6e 20 74 68 65 20 6d 65 6d 6f 72 79 20  tain the memory 
13840 6e 65 65 64 65 64 2e 3c 70 3e 0a 2a 2a 20 5e 57  needed.<p>.** ^W
13850 68 65 6e 20 74 68 65 20 61 70 70 6c 69 63 61 74  hen the applicat
13860 69 6f 6e 20 70 72 6f 76 69 64 65 73 20 61 6e 79  ion provides any
13870 20 61 6d 6f 75 6e 74 20 6f 66 20 73 63 72 61 74   amount of scrat
13880 63 68 20 6d 65 6d 6f 72 79 20 75 73 69 6e 67 0a  ch memory using.
13890 2a 2a 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ** SQLITE_CONFIG
138a0 5f 53 43 52 41 54 43 48 2c 20 53 51 4c 69 74 65  _SCRATCH, SQLite
138b0 20 61 76 6f 69 64 73 20 75 6e 6e 65 63 65 73 73   avoids unnecess
138c0 61 72 79 20 6c 61 72 67 65 0a 2a 2a 20 5b 73 71  ary large.** [sq
138d0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 7c 68 65 61  lite3_malloc|hea
138e0 70 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 5d 2e 0a  p allocations]..
138f0 2a 2a 20 54 68 69 73 20 63 61 6e 20 68 65 6c 70  ** This can help
13900 20 5b 52 6f 62 73 6f 6e 20 70 72 6f 6f 66 7c 70   [Robson proof|p
13910 72 65 76 65 6e 74 20 6d 65 6d 6f 72 79 20 61 6c  revent memory al
13920 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 75 72 65  location failure
13930 73 5d 20 64 75 65 20 74 6f 20 68 65 61 70 0a 2a  s] due to heap.*
13940 2a 20 66 72 61 67 6d 65 6e 74 61 74 69 6f 6e 20  * fragmentation 
13950 69 6e 20 6c 6f 77 2d 6d 65 6d 6f 72 79 20 65 6d  in low-memory em
13960 62 65 64 64 65 64 20 73 79 73 74 65 6d 73 2e 0a  bedded systems..
13970 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  ** </dd>.**.** [
13980 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50  [SQLITE_CONFIG_P
13990 41 47 45 43 41 43 48 45 5d 5d 20 3c 64 74 3e 53  AGECACHE]] <dt>S
139a0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47  QLITE_CONFIG_PAG
139b0 45 43 41 43 48 45 3c 2f 64 74 3e 0a 2a 2a 20 3c  ECACHE</dt>.** <
139c0 64 64 3e 20 5e 54 68 65 20 53 51 4c 49 54 45 5f  dd> ^The SQLITE_
139d0 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45  CONFIG_PAGECACHE
139e0 20 6f 70 74 69 6f 6e 20 73 70 65 63 69 66 69 65   option specifie
139f0 73 20 61 20 6d 65 6d 6f 72 79 20 70 6f 6f 6c 0a  s a memory pool.
13a00 2a 2a 20 74 68 61 74 20 53 51 4c 69 74 65 20 63  ** that SQLite c
13a10 61 6e 20 75 73 65 20 66 6f 72 20 74 68 65 20 64  an use for the d
13a20 61 74 61 62 61 73 65 20 70 61 67 65 20 63 61 63  atabase page cac
13a30 68 65 20 77 69 74 68 20 74 68 65 20 64 65 66 61  he with the defa
13a40 75 6c 74 20 70 61 67 65 0a 2a 2a 20 63 61 63 68  ult page.** cach
13a50 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
13a60 2e 20 20 0a 2a 2a 20 54 68 69 73 20 63 6f 6e 66  .  .** This conf
13a70 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
13a80 20 69 73 20 61 20 6e 6f 2d 6f 70 20 69 66 20 61   is a no-op if a
13a90 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  n application-de
13aa0 66 69 6e 65 20 70 61 67 65 0a 2a 2a 20 63 61 63  fine page.** cac
13ab0 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
13ac0 6e 20 69 73 20 6c 6f 61 64 65 64 20 75 73 69 6e  n is loaded usin
13ad0 67 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 43 4f  g the [SQLITE_CO
13ae0 4e 46 49 47 5f 50 43 41 43 48 45 32 5d 2e 0a 2a  NFIG_PCACHE2]..*
13af0 2a 20 5e 54 68 65 72 65 20 61 72 65 20 74 68 72  * ^There are thr
13b00 65 65 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20  ee arguments to 
13b10 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41  SQLITE_CONFIG_PA
13b20 47 45 43 41 43 48 45 3a 20 41 20 70 6f 69 6e 74  GECACHE: A point
13b30 65 72 20 74 6f 0a 2a 2a 20 38 2d 62 79 74 65 20  er to.** 8-byte 
13b40 61 6c 69 67 6e 65 64 20 6d 65 6d 6f 72 79 20 28  aligned memory (
13b50 70 4d 65 6d 29 2c 20 74 68 65 20 73 69 7a 65 20  pMem), the size 
13b60 6f 66 20 65 61 63 68 20 70 61 67 65 20 63 61 63  of each page cac
13b70 68 65 20 6c 69 6e 65 20 28 73 7a 29 2c 0a 2a 2a  he line (sz),.**
13b80 20 61 6e 64 20 74 68 65 20 6e 75 6d 62 65 72 20   and the number 
13b90 6f 66 20 63 61 63 68 65 20 6c 69 6e 65 73 20 28  of cache lines (
13ba0 4e 29 2e 0a 2a 2a 20 54 68 65 20 73 7a 20 61 72  N)..** The sz ar
13bb0 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 62 65  gument should be
13bc0 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65   the size of the
13bd0 20 6c 61 72 67 65 73 74 20 64 61 74 61 62 61 73   largest databas
13be0 65 20 70 61 67 65 0a 2a 2a 20 28 61 20 70 6f 77  e page.** (a pow
13bf0 65 72 20 6f 66 20 74 77 6f 20 62 65 74 77 65 65  er of two betwee
13c00 6e 20 35 31 32 20 61 6e 64 20 36 35 35 33 36 29  n 512 and 65536)
13c10 20 70 6c 75 73 20 73 6f 6d 65 20 65 78 74 72 61   plus some extra
13c20 20 62 79 74 65 73 20 66 6f 72 20 65 61 63 68 0a   bytes for each.
13c30 2a 2a 20 70 61 67 65 20 68 65 61 64 65 72 2e 20  ** page header. 
13c40 20 5e 54 68 65 20 6e 75 6d 62 65 72 20 6f 66 20   ^The number of 
13c50 65 78 74 72 61 20 62 79 74 65 73 20 6e 65 65 64  extra bytes need
13c60 65 64 20 62 79 20 74 68 65 20 70 61 67 65 20 68  ed by the page h
13c70 65 61 64 65 72 0a 2a 2a 20 63 61 6e 20 62 65 20  eader.** can be 
13c80 64 65 74 65 72 6d 69 6e 65 64 20 75 73 69 6e 67  determined using
13c90 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
13ca0 50 43 41 43 48 45 5f 48 44 52 53 5a 5d 2e 0a 2a  PCACHE_HDRSZ]..*
13cb0 2a 20 5e 49 74 20 69 73 20 68 61 72 6d 6c 65 73  * ^It is harmles
13cc0 73 2c 20 61 70 61 72 74 20 66 72 6f 6d 20 74 68  s, apart from th
13cd0 65 20 77 61 73 74 65 64 20 6d 65 6d 6f 72 79 2c  e wasted memory,
13ce0 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73 7a 20 70  .** for the sz p
13cf0 61 72 61 6d 65 74 65 72 20 74 6f 20 62 65 20 6c  arameter to be l
13d00 61 72 67 65 72 20 74 68 61 6e 20 6e 65 63 65 73  arger than neces
13d10 73 61 72 79 2e 20 20 54 68 65 20 70 4d 65 6d 0a  sary.  The pMem.
13d20 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 74  ** argument must
13d30 20 62 65 20 65 69 74 68 65 72 20 61 20 4e 55 4c   be either a NUL
13d40 4c 20 70 6f 69 6e 74 65 72 20 6f 72 20 61 20 70  L pointer or a p
13d50 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 38 2d 62  ointer to an 8-b
13d60 79 74 65 0a 2a 2a 20 61 6c 69 67 6e 65 64 20 62  yte.** aligned b
13d70 6c 6f 63 6b 20 6f 66 20 6d 65 6d 6f 72 79 20 6f  lock of memory o
13d80 66 20 61 74 20 6c 65 61 73 74 20 73 7a 2a 4e 20  f at least sz*N 
13d90 62 79 74 65 73 2c 20 6f 74 68 65 72 77 69 73 65  bytes, otherwise
13da0 0a 2a 2a 20 73 75 62 73 65 71 75 65 6e 74 20 62  .** subsequent b
13db0 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66  ehavior is undef
13dc0 69 6e 65 64 2e 0a 2a 2a 20 5e 57 68 65 6e 20 70  ined..** ^When p
13dd0 4d 65 6d 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c  Mem is not NULL,
13de0 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 73 74 72   SQLite will str
13df0 69 76 65 20 74 6f 20 75 73 65 20 74 68 65 20 6d  ive to use the m
13e00 65 6d 6f 72 79 20 70 72 6f 76 69 64 65 64 0a 2a  emory provided.*
13e10 2a 20 74 6f 20 73 61 74 69 73 66 79 20 70 61 67  * to satisfy pag
13e20 65 20 63 61 63 68 65 20 6e 65 65 64 73 2c 20 66  e cache needs, f
13e30 61 6c 6c 69 6e 67 20 62 61 63 6b 20 74 6f 20 5b  alling back to [
13e40 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
13e50 5d 20 69 66 0a 2a 2a 20 61 20 70 61 67 65 20 63  ] if.** a page c
13e60 61 63 68 65 20 6c 69 6e 65 20 69 73 20 6c 61 72  ache line is lar
13e70 67 65 72 20 74 68 61 6e 20 73 7a 20 62 79 74 65  ger than sz byte
13e80 73 20 6f 72 20 69 66 20 61 6c 6c 20 6f 66 20 74  s or if all of t
13e90 68 65 20 70 4d 65 6d 20 62 75 66 66 65 72 0a 2a  he pMem buffer.*
13ea0 2a 20 69 73 20 65 78 68 61 75 73 74 65 64 2e 0a  * is exhausted..
13eb0 2a 2a 20 5e 49 66 20 70 4d 65 6d 20 69 73 20 4e  ** ^If pMem is N
13ec0 55 4c 4c 20 61 6e 64 20 4e 20 69 73 20 6e 6f 6e  ULL and N is non
13ed0 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 65 61 63 68  -zero, then each
13ee0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
13ef0 74 69 6f 6e 0a 2a 2a 20 64 6f 65 73 20 61 6e 20  tion.** does an 
13f00 69 6e 69 74 69 61 6c 20 62 75 6c 6b 20 61 6c 6c  initial bulk all
13f10 6f 63 61 74 69 6f 6e 20 66 6f 72 20 70 61 67 65  ocation for page
13f20 20 63 61 63 68 65 20 6d 65 6d 6f 72 79 0a 2a 2a   cache memory.**
13f30 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d   from [sqlite3_m
13f40 61 6c 6c 6f 63 28 29 5d 20 73 75 66 66 69 63 69  alloc()] suffici
13f50 65 6e 74 20 66 6f 72 20 4e 20 63 61 63 68 65 20  ent for N cache 
13f60 6c 69 6e 65 73 20 69 66 20 4e 20 69 73 20 70 6f  lines if N is po
13f70 73 69 74 69 76 65 20 6f 72 0a 2a 2a 20 6f 66 20  sitive or.** of 
13f80 2d 31 30 32 34 2a 4e 20 62 79 74 65 73 20 69 66  -1024*N bytes if
13f90 20 4e 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20   N is negative, 
13fa0 2e 20 5e 49 66 20 61 64 64 69 74 69 6f 6e 61 6c  . ^If additional
13fb0 0a 2a 2a 20 70 61 67 65 20 63 61 63 68 65 20 6d  .** page cache m
13fc0 65 6d 6f 72 79 20 69 73 20 6e 65 65 64 65 64 20  emory is needed 
13fd0 62 65 79 6f 6e 64 20 77 68 61 74 20 69 73 20 70  beyond what is p
13fe0 72 6f 76 69 64 65 64 20 62 79 20 74 68 65 20 69  rovided by the i
13ff0 6e 69 74 69 61 6c 0a 2a 2a 20 61 6c 6c 6f 63 61  nitial.** alloca
14000 74 69 6f 6e 2c 20 74 68 65 6e 20 53 51 4c 69 74  tion, then SQLit
14010 65 20 67 6f 65 73 20 74 6f 20 5b 73 71 6c 69 74  e goes to [sqlit
14020 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 73 65 70  e3_malloc()] sep
14030 61 72 61 74 65 6c 79 20 66 6f 72 20 65 61 63 68  arately for each
14040 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 61 6c 20 63  .** additional c
14050 61 63 68 65 20 6c 69 6e 65 2e 20 3c 2f 64 64 3e  ache line. </dd>
14060 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
14070 43 4f 4e 46 49 47 5f 48 45 41 50 5d 5d 20 3c 64  CONFIG_HEAP]] <d
14080 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
14090 48 45 41 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  HEAP</dt>.** <dd
140a0 3e 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f  > ^The SQLITE_CO
140b0 4e 46 49 47 5f 48 45 41 50 20 6f 70 74 69 6f 6e  NFIG_HEAP option
140c0 20 73 70 65 63 69 66 69 65 73 20 61 20 73 74 61   specifies a sta
140d0 74 69 63 20 6d 65 6d 6f 72 79 20 62 75 66 66 65  tic memory buffe
140e0 72 20 0a 2a 2a 20 74 68 61 74 20 53 51 4c 69 74  r .** that SQLit
140f0 65 20 77 69 6c 6c 20 75 73 65 20 66 6f 72 20 61  e will use for a
14100 6c 6c 20 6f 66 20 69 74 73 20 64 79 6e 61 6d 69  ll of its dynami
14110 63 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  c memory allocat
14120 69 6f 6e 20 6e 65 65 64 73 0a 2a 2a 20 62 65 79  ion needs.** bey
14130 6f 6e 64 20 74 68 6f 73 65 20 70 72 6f 76 69 64  ond those provid
14140 65 64 20 66 6f 72 20 62 79 20 5b 53 51 4c 49 54  ed for by [SQLIT
14150 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48  E_CONFIG_SCRATCH
14160 5d 20 61 6e 64 0a 2a 2a 20 5b 53 51 4c 49 54 45  ] and.** [SQLITE
14170 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48  _CONFIG_PAGECACH
14180 45 5d 2e 0a 2a 2a 20 5e 54 68 65 20 53 51 4c 49  E]..** ^The SQLI
14190 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 20 6f  TE_CONFIG_HEAP o
141a0 70 74 69 6f 6e 20 69 73 20 6f 6e 6c 79 20 61 76  ption is only av
141b0 61 69 6c 61 62 6c 65 20 69 66 20 53 51 4c 69 74  ailable if SQLit
141c0 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a  e is compiled.**
141d0 20 77 69 74 68 20 65 69 74 68 65 72 20 5b 53 51   with either [SQ
141e0 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53  LITE_ENABLE_MEMS
141f0 59 53 33 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f  YS3] or [SQLITE_
14200 45 4e 41 42 4c 45 5f 4d 45 4d 53 59 53 35 5d 20  ENABLE_MEMSYS5] 
14210 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a 2a 20 5b  and returns.** [
14220 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66  SQLITE_ERROR] if
14230 20 69 6e 76 6f 6b 65 64 20 6f 74 68 65 72 77 69   invoked otherwi
14240 73 65 2e 0a 2a 2a 20 5e 54 68 65 72 65 20 61 72  se..** ^There ar
14250 65 20 74 68 72 65 65 20 61 72 67 75 6d 65 6e 74  e three argument
14260 73 20 74 6f 20 53 51 4c 49 54 45 5f 43 4f 4e 46  s to SQLITE_CONF
14270 49 47 5f 48 45 41 50 3a 0a 2a 2a 20 41 6e 20 38  IG_HEAP:.** An 8
14280 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 20 70 6f  -byte aligned po
14290 69 6e 74 65 72 20 74 6f 20 74 68 65 20 6d 65 6d  inter to the mem
142a0 6f 72 79 2c 0a 2a 2a 20 74 68 65 20 6e 75 6d 62  ory,.** the numb
142b0 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74  er of bytes in t
142c0 68 65 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72  he memory buffer
142d0 2c 20 61 6e 64 20 74 68 65 20 6d 69 6e 69 6d 75  , and the minimu
142e0 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a  m allocation siz
142f0 65 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69  e..** ^If the fi
14300 72 73 74 20 70 6f 69 6e 74 65 72 20 28 74 68 65  rst pointer (the
14310 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72 29   memory pointer)
14320 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 53   is NULL, then S
14330 51 4c 69 74 65 20 72 65 76 65 72 74 73 0a 2a 2a  QLite reverts.**
14340 20 74 6f 20 75 73 69 6e 67 20 69 74 73 20 64 65   to using its de
14350 66 61 75 6c 74 20 6d 65 6d 6f 72 79 20 61 6c 6c  fault memory all
14360 6f 63 61 74 6f 72 20 28 74 68 65 20 73 79 73 74  ocator (the syst
14370 65 6d 20 6d 61 6c 6c 6f 63 28 29 20 69 6d 70 6c  em malloc() impl
14380 65 6d 65 6e 74 61 74 69 6f 6e 29 2c 0a 2a 2a 20  ementation),.** 
14390 75 6e 64 6f 69 6e 67 20 61 6e 79 20 70 72 69 6f  undoing any prio
143a0 72 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20  r invocation of 
143b0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
143c0 41 4c 4c 4f 43 5d 2e 20 20 5e 49 66 20 74 68 65  ALLOC].  ^If the
143d0 0a 2a 2a 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74  .** memory point
143e0 65 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 74  er is not NULL t
143f0 68 65 6e 20 74 68 65 20 61 6c 74 65 72 6e 61 74  hen the alternat
14400 69 76 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c  ive memory.** al
14410 6c 6f 63 61 74 6f 72 20 69 73 20 65 6e 67 61 67  locator is engag
14420 65 64 20 74 6f 20 68 61 6e 64 6c 65 20 61 6c 6c  ed to handle all
14430 20 6f 66 20 53 51 4c 69 74 65 73 20 6d 65 6d 6f   of SQLites memo
14440 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65  ry allocation ne
14450 65 64 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73  eds..** The firs
14460 74 20 70 6f 69 6e 74 65 72 20 28 74 68 65 20 6d  t pointer (the m
14470 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72 29 20 6d  emory pointer) m
14480 75 73 74 20 62 65 20 61 6c 69 67 6e 65 64 20 74  ust be aligned t
14490 6f 20 61 6e 20 38 2d 62 79 74 65 0a 2a 2a 20 62  o an 8-byte.** b
144a0 6f 75 6e 64 61 72 79 20 6f 72 20 73 75 62 73 65  oundary or subse
144b0 71 75 65 6e 74 20 62 65 68 61 76 69 6f 72 20 6f  quent behavior o
144c0 66 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 62 65  f SQLite will be
144d0 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 54   undefined..** T
144e0 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63  he minimum alloc
144f0 61 74 69 6f 6e 20 73 69 7a 65 20 69 73 20 63 61  ation size is ca
14500 70 70 65 64 20 61 74 20 32 2a 2a 31 32 2e 20 52  pped at 2**12. R
14510 65 61 73 6f 6e 61 62 6c 65 20 76 61 6c 75 65 73  easonable values
14520 0a 2a 2a 20 66 6f 72 20 74 68 65 20 6d 69 6e 69  .** for the mini
14530 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73  mum allocation s
14540 69 7a 65 20 61 72 65 20 32 2a 2a 35 20 74 68 72  ize are 2**5 thr
14550 6f 75 67 68 20 32 2a 2a 38 2e 3c 2f 64 64 3e 0a  ough 2**8.</dd>.
14560 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
14570 4f 4e 46 49 47 5f 4d 55 54 45 58 5d 5d 20 3c 64  ONFIG_MUTEX]] <d
14580 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
14590 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  MUTEX</dt>.** <d
145a0 64 3e 20 5e 28 54 68 65 20 53 51 4c 49 54 45 5f  d> ^(The SQLITE_
145b0 43 4f 4e 46 49 47 5f 4d 55 54 45 58 20 6f 70 74  CONFIG_MUTEX opt
145c0 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67  ion takes a sing
145d0 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63  le argument whic
145e0 68 20 69 73 20 61 0a 2a 2a 20 70 6f 69 6e 74 65  h is a.** pointe
145f0 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65  r to an instance
14600 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
14610 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20  _mutex_methods] 
14620 73 74 72 75 63 74 75 72 65 2e 0a 2a 2a 20 54 68  structure..** Th
14630 65 20 61 72 67 75 6d 65 6e 74 20 73 70 65 63 69  e argument speci
14640 66 69 65 73 20 61 6c 74 65 72 6e 61 74 69 76 65  fies alternative
14650 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 75 74 65 78   low-level mutex
14660 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20   routines to be 
14670 75 73 65 64 0a 2a 2a 20 69 6e 20 70 6c 61 63 65  used.** in place
14680 20 74 68 65 20 6d 75 74 65 78 20 72 6f 75 74 69   the mutex routi
14690 6e 65 73 20 62 75 69 6c 74 20 69 6e 74 6f 20 53  nes built into S
146a0 51 4c 69 74 65 2e 29 5e 20 20 5e 53 51 4c 69 74  QLite.)^  ^SQLit
146b0 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f  e makes a copy o
146c0 66 0a 2a 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74  f.** the content
146d0 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
146e0 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20  _mutex_methods] 
146f0 73 74 72 75 63 74 75 72 65 20 62 65 66 6f 72 65  structure before
14700 20 74 68 65 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20   the call to.** 
14710 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
14720 29 5d 20 72 65 74 75 72 6e 73 2e 20 5e 49 66 20  )] returns. ^If 
14730 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  SQLite is compil
14740 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b  ed with.** the [
14750 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
14760 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41  E | SQLITE_THREA
14770 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65  DSAFE=0] compile
14780 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65  -time option the
14790 6e 0a 2a 2a 20 74 68 65 20 65 6e 74 69 72 65 20  n.** the entire 
147a0 6d 75 74 65 78 69 6e 67 20 73 75 62 73 79 73 74  mutexing subsyst
147b0 65 6d 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72  em is omitted fr
147c0 6f 6d 20 74 68 65 20 62 75 69 6c 64 20 61 6e 64  om the build and
147d0 20 68 65 6e 63 65 20 63 61 6c 6c 73 20 74 6f 0a   hence calls to.
147e0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  ** [sqlite3_conf
147f0 69 67 28 29 5d 20 77 69 74 68 20 74 68 65 20 53  ig()] with the S
14800 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54  QLITE_CONFIG_MUT
14810 45 58 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  EX configuration
14820 20 6f 70 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20   option will.** 
14830 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45  return [SQLITE_E
14840 52 52 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  RROR].</dd>.**.*
14850 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
14860 47 5f 47 45 54 4d 55 54 45 58 5d 5d 20 3c 64 74  G_GETMUTEX]] <dt
14870 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47  >SQLITE_CONFIG_G
14880 45 54 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20  ETMUTEX</dt>.** 
14890 3c 64 64 3e 20 5e 28 54 68 65 20 53 51 4c 49 54  <dd> ^(The SQLIT
148a0 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45  E_CONFIG_GETMUTE
148b0 58 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61  X option takes a
148c0 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74   single argument
148d0 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 61 20 70   which.** is a p
148e0 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73  ointer to an ins
148f0 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71  tance of the [sq
14900 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68  lite3_mutex_meth
14910 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e 20  ods] structure. 
14920 20 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   The.** [sqlite3
14930 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 0a  _mutex_methods].
14940 2a 2a 20 73 74 72 75 63 74 75 72 65 20 69 73 20  ** structure is 
14950 66 69 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20  filled with the 
14960 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65  currently define
14970 64 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73  d mutex routines
14980 2e 29 5e 0a 2a 2a 20 54 68 69 73 20 6f 70 74 69  .)^.** This opti
14990 6f 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20 74  on can be used t
149a0 6f 20 6f 76 65 72 6c 6f 61 64 20 74 68 65 20 64  o overload the d
149b0 65 66 61 75 6c 74 20 6d 75 74 65 78 20 61 6c 6c  efault mutex all
149c0 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69  ocation.** routi
149d0 6e 65 73 20 77 69 74 68 20 61 20 77 72 61 70 70  nes with a wrapp
149e0 65 72 20 75 73 65 64 20 74 6f 20 74 72 61 63 6b  er used to track
149f0 20 6d 75 74 65 78 20 75 73 61 67 65 20 66 6f 72   mutex usage for
14a00 20 70 65 72 66 6f 72 6d 61 6e 63 65 0a 2a 2a 20   performance.** 
14a10 70 72 6f 66 69 6c 69 6e 67 20 6f 72 20 74 65 73  profiling or tes
14a20 74 69 6e 67 2c 20 66 6f 72 20 65 78 61 6d 70 6c  ting, for exampl
14a30 65 2e 20 20 20 5e 49 66 20 53 51 4c 69 74 65 20  e.   ^If SQLite 
14a40 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  is compiled with
14a50 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  .** the [SQLITE_
14a60 54 48 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c  THREADSAFE | SQL
14a70 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30  ITE_THREADSAFE=0
14a80 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
14a90 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 74 68  ption then.** th
14aa0 65 20 65 6e 74 69 72 65 20 6d 75 74 65 78 69 6e  e entire mutexin
14ab0 67 20 73 75 62 73 79 73 74 65 6d 20 69 73 20 6f  g subsystem is o
14ac0 6d 69 74 74 65 64 20 66 72 6f 6d 20 74 68 65 20  mitted from the 
14ad0 62 75 69 6c 64 20 61 6e 64 20 68 65 6e 63 65 20  build and hence 
14ae0 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c  calls to.** [sql
14af0 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77  ite3_config()] w
14b00 69 74 68 20 74 68 65 20 53 51 4c 49 54 45 5f 43  ith the SQLITE_C
14b10 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 20 63  ONFIG_GETMUTEX c
14b20 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
14b30 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 72 65 74 75  ion will.** retu
14b40 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  rn [SQLITE_ERROR
14b50 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  ].</dd>.**.** [[
14b60 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f  SQLITE_CONFIG_LO
14b70 4f 4b 41 53 49 44 45 5d 5d 20 3c 64 74 3e 53 51  OKASIDE]] <dt>SQ
14b80 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b  LITE_CONFIG_LOOK
14b90 41 53 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ASIDE</dt>.** <d
14ba0 64 3e 20 5e 28 54 68 65 20 53 51 4c 49 54 45 5f  d> ^(The SQLITE_
14bb0 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45  CONFIG_LOOKASIDE
14bc0 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 74 77   option takes tw
14bd0 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74  o arguments that
14be0 20 64 65 74 65 72 6d 69 6e 65 0a 2a 2a 20 74 68   determine.** th
14bf0 65 20 64 65 66 61 75 6c 74 20 73 69 7a 65 20 6f  e default size o
14c00 66 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f  f lookaside memo
14c10 72 79 20 6f 6e 20 65 61 63 68 20 5b 64 61 74 61  ry on each [data
14c20 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
14c30 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61  ..** The first a
14c40 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 0a 2a  rgument is the.*
14c50 2a 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20 6c  * size of each l
14c60 6f 6f 6b 61 73 69 64 65 20 62 75 66 66 65 72 20  ookaside buffer 
14c70 73 6c 6f 74 20 61 6e 64 20 74 68 65 20 73 65 63  slot and the sec
14c80 6f 6e 64 20 69 73 20 74 68 65 20 6e 75 6d 62 65  ond is the numbe
14c90 72 20 6f 66 0a 2a 2a 20 73 6c 6f 74 73 20 61 6c  r of.** slots al
14ca0 6c 6f 63 61 74 65 64 20 74 6f 20 65 61 63 68 20  located to each 
14cb0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
14cc0 69 6f 6e 2e 29 5e 20 20 5e 28 53 51 4c 49 54 45  ion.)^  ^(SQLITE
14cd0 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44  _CONFIG_LOOKASID
14ce0 45 0a 2a 2a 20 73 65 74 73 20 74 68 65 20 3c 69  E.** sets the <i
14cf0 3e 64 65 66 61 75 6c 74 3c 2f 69 3e 20 6c 6f 6f  >default</i> loo
14d00 6b 61 73 69 64 65 20 73 69 7a 65 2e 20 54 68 65  kaside size. The
14d10 20 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49   [SQLITE_DBCONFI
14d20 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 0a 2a 2a 20  G_LOOKASIDE].** 
14d30 6f 70 74 69 6f 6e 20 74 6f 20 5b 73 71 6c 69 74  option to [sqlit
14d40 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20  e3_db_config()] 
14d50 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 63  can be used to c
14d60 68 61 6e 67 65 20 74 68 65 20 6c 6f 6f 6b 61 73  hange the lookas
14d70 69 64 65 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61  ide.** configura
14d80 74 69 6f 6e 20 6f 6e 20 69 6e 64 69 76 69 64 75  tion on individu
14d90 61 6c 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 2e 29  al connections.)
14da0 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  ^ </dd>.**.** [[
14db0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43  SQLITE_CONFIG_PC
14dc0 41 43 48 45 32 5d 5d 20 3c 64 74 3e 53 51 4c 49  ACHE2]] <dt>SQLI
14dd0 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45  TE_CONFIG_PCACHE
14de0 32 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  2</dt>.** <dd> ^
14df0 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  (The SQLITE_CONF
14e00 49 47 5f 50 43 41 43 48 45 32 20 6f 70 74 69 6f  IG_PCACHE2 optio
14e10 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65  n takes a single
14e20 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20   argument which 
14e30 69 73 20 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72  is .** a pointer
14e40 20 74 6f 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f   to an [sqlite3_
14e50 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 32 5d  pcache_methods2]
14e60 20 6f 62 6a 65 63 74 2e 20 20 54 68 69 73 20 6f   object.  This o
14e70 62 6a 65 63 74 20 73 70 65 63 69 66 69 65 73 0a  bject specifies.
14e80 2a 2a 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  ** the interface
14e90 20 74 6f 20 61 20 63 75 73 74 6f 6d 20 70 61 67   to a custom pag
14ea0 65 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e  e cache implemen
14eb0 74 61 74 69 6f 6e 2e 29 5e 0a 2a 2a 20 5e 53 51  tation.)^.** ^SQ
14ec0 4c 69 74 65 20 6d 61 6b 65 73 20 61 20 63 6f 70  Lite makes a cop
14ed0 79 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  y of the [sqlite
14ee0 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73  3_pcache_methods
14ef0 32 5d 20 6f 62 6a 65 63 74 2e 3c 2f 64 64 3e 0a  2] object.</dd>.
14f00 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
14f10 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 32  ONFIG_GETPCACHE2
14f20 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
14f30 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 32 3c  NFIG_GETPCACHE2<
14f40 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54  /dt>.** <dd> ^(T
14f50 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
14f60 5f 47 45 54 50 43 41 43 48 45 32 20 6f 70 74 69  _GETPCACHE2 opti
14f70 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c  on takes a singl
14f80 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68  e argument which
14f90 0a 2a 2a 20 69 73 20 61 20 70 6f 69 6e 74 65 72  .** is a pointer
14fa0 20 74 6f 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f   to an [sqlite3_
14fb0 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 32 5d  pcache_methods2]
14fc0 20 6f 62 6a 65 63 74 2e 20 20 53 51 4c 69 74 65   object.  SQLite
14fd0 20 63 6f 70 69 65 73 20 6f 66 0a 2a 2a 20 74 68   copies of.** th
14fe0 65 20 63 75 72 72 65 6e 74 20 70 61 67 65 20 63  e current page c
14ff0 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  ache implementat
15000 69 6f 6e 20 69 6e 74 6f 20 74 68 61 74 20 6f 62  ion into that ob
15010 6a 65 63 74 2e 29 5e 20 3c 2f 64 64 3e 0a 2a 2a  ject.)^ </dd>.**
15020 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
15030 46 49 47 5f 4c 4f 47 5d 5d 20 3c 64 74 3e 53 51  FIG_LOG]] <dt>SQ
15040 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 3c  LITE_CONFIG_LOG<
15050 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 54 68 65  /dt>.** <dd> The
15060 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c   SQLITE_CONFIG_L
15070 4f 47 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65  OG option is use
15080 64 20 74 6f 20 63 6f 6e 66 69 67 75 72 65 20 74  d to configure t
15090 68 65 20 53 51 4c 69 74 65 0a 2a 2a 20 67 6c 6f  he SQLite.** glo
150a0 62 61 6c 20 5b 65 72 72 6f 72 20 6c 6f 67 5d 2e  bal [error log].
150b0 0a 2a 2a 20 28 5e 54 68 65 20 53 51 4c 49 54 45  .** (^The SQLITE
150c0 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 6f 70 74 69  _CONFIG_LOG opti
150d0 6f 6e 20 74 61 6b 65 73 20 74 77 6f 20 61 72 67  on takes two arg
150e0 75 6d 65 6e 74 73 3a 20 61 20 70 6f 69 6e 74 65  uments: a pointe
150f0 72 20 74 6f 20 61 0a 2a 2a 20 66 75 6e 63 74 69  r to a.** functi
15100 6f 6e 20 77 69 74 68 20 61 20 63 61 6c 6c 20 73  on with a call s
15110 69 67 6e 61 74 75 72 65 20 6f 66 20 76 6f 69 64  ignature of void
15120 28 2a 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f  (*)(void*,int,co
15130 6e 73 74 20 63 68 61 72 2a 29 2c 20 0a 2a 2a 20  nst char*), .** 
15140 61 6e 64 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  and a pointer to
15150 20 76 6f 69 64 2e 20 5e 49 66 20 74 68 65 20 66   void. ^If the f
15160 75 6e 63 74 69 6f 6e 20 70 6f 69 6e 74 65 72 20  unction pointer 
15170 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 69 74 20  is not NULL, it 
15180 69 73 0a 2a 2a 20 69 6e 76 6f 6b 65 64 20 62 79  is.** invoked by
15190 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d   [sqlite3_log()]
151a0 20 74 6f 20 70 72 6f 63 65 73 73 20 65 61 63 68   to process each
151b0 20 6c 6f 67 67 69 6e 67 20 65 76 65 6e 74 2e 20   logging event. 
151c0 20 5e 49 66 20 74 68 65 0a 2a 2a 20 66 75 6e 63   ^If the.** func
151d0 74 69 6f 6e 20 70 6f 69 6e 74 65 72 20 69 73 20  tion pointer is 
151e0 4e 55 4c 4c 2c 20 74 68 65 20 5b 73 71 6c 69 74  NULL, the [sqlit
151f0 65 33 5f 6c 6f 67 28 29 5d 20 69 6e 74 65 72 66  e3_log()] interf
15200 61 63 65 20 62 65 63 6f 6d 65 73 20 61 20 6e 6f  ace becomes a no
15210 2d 6f 70 2e 0a 2a 2a 20 5e 54 68 65 20 76 6f 69  -op..** ^The voi
15220 64 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20 69  d pointer that i
15230 73 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67  s the second arg
15240 75 6d 65 6e 74 20 74 6f 20 53 51 4c 49 54 45 5f  ument to SQLITE_
15250 43 4f 4e 46 49 47 5f 4c 4f 47 20 69 73 0a 2a 2a  CONFIG_LOG is.**
15260 20 70 61 73 73 65 64 20 74 68 72 6f 75 67 68 20   passed through 
15270 61 73 20 74 68 65 20 66 69 72 73 74 20 70 61 72  as the first par
15280 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61 70  ameter to the ap
15290 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
152a0 64 20 6c 6f 67 67 65 72 0a 2a 2a 20 66 75 6e 63  d logger.** func
152b0 74 69 6f 6e 20 77 68 65 6e 65 76 65 72 20 74 68  tion whenever th
152c0 61 74 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 69  at function is i
152d0 6e 76 6f 6b 65 64 2e 20 20 5e 54 68 65 20 73 65  nvoked.  ^The se
152e0 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74  cond parameter t
152f0 6f 0a 2a 2a 20 74 68 65 20 6c 6f 67 67 65 72 20  o.** the logger 
15300 66 75 6e 63 74 69 6f 6e 20 69 73 20 61 20 63 6f  function is a co
15310 70 79 20 6f 66 20 74 68 65 20 66 69 72 73 74 20  py of the first 
15320 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
15330 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 0a 2a   corresponding.*
15340 2a 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29  * [sqlite3_log()
15350 5d 20 63 61 6c 6c 20 61 6e 64 20 69 73 20 69 6e  ] call and is in
15360 74 65 6e 64 65 64 20 74 6f 20 62 65 20 61 20 5b  tended to be a [
15370 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 6f 72 20  result code] or 
15380 61 6e 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20  an.** [extended 
15390 72 65 73 75 6c 74 20 63 6f 64 65 5d 2e 20 20 5e  result code].  ^
153a0 54 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65  The third parame
153b0 74 65 72 20 70 61 73 73 65 64 20 74 6f 20 74 68  ter passed to th
153c0 65 20 6c 6f 67 67 65 72 20 69 73 0a 2a 2a 20 6c  e logger is.** l
153d0 6f 67 20 6d 65 73 73 61 67 65 20 61 66 74 65 72  og message after
153e0 20 66 6f 72 6d 61 74 74 69 6e 67 20 76 69 61 20   formatting via 
153f0 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74  [sqlite3_snprint
15400 66 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 53 51 4c  f()]..** The SQL
15410 69 74 65 20 6c 6f 67 67 69 6e 67 20 69 6e 74 65  ite logging inte
15420 72 66 61 63 65 20 69 73 20 6e 6f 74 20 72 65 65  rface is not ree
15430 6e 74 72 61 6e 74 3b 20 74 68 65 20 6c 6f 67 67  ntrant; the logg
15440 65 72 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 73  er function.** s
15450 75 70 70 6c 69 65 64 20 62 79 20 74 68 65 20 61  upplied by the a
15460 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20  pplication must 
15470 6e 6f 74 20 69 6e 76 6f 6b 65 20 61 6e 79 20 53  not invoke any S
15480 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e  QLite interface.
15490 0a 2a 2a 20 49 6e 20 61 20 6d 75 6c 74 69 2d 74  .** In a multi-t
154a0 68 72 65 61 64 65 64 20 61 70 70 6c 69 63 61 74  hreaded applicat
154b0 69 6f 6e 2c 20 74 68 65 20 61 70 70 6c 69 63 61  ion, the applica
154c0 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 6c 6f 67  tion-defined log
154d0 67 65 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  ger.** function 
154e0 6d 75 73 74 20 62 65 20 74 68 72 65 61 64 73 61  must be threadsa
154f0 66 65 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  fe. </dd>.**.** 
15500 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
15510 55 52 49 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45  URI]] <dt>SQLITE
15520 5f 43 4f 4e 46 49 47 5f 55 52 49 0a 2a 2a 20 3c  _CONFIG_URI.** <
15530 64 64 3e 5e 28 54 68 65 20 53 51 4c 49 54 45 5f  dd>^(The SQLITE_
15540 43 4f 4e 46 49 47 5f 55 52 49 20 6f 70 74 69 6f  CONFIG_URI optio
15550 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65  n takes a single
15560 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 79 70   argument of typ
15570 65 20 69 6e 74 2e 0a 2a 2a 20 49 66 20 6e 6f 6e  e int..** If non
15580 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 55 52 49 20  -zero, then URI 
15590 68 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62  handling is glob
155a0 61 6c 6c 79 20 65 6e 61 62 6c 65 64 2e 20 49 66  ally enabled. If
155b0 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 69   the parameter i
155c0 73 20 7a 65 72 6f 2c 0a 2a 2a 20 74 68 65 6e 20  s zero,.** then 
155d0 55 52 49 20 68 61 6e 64 6c 69 6e 67 20 69 73 20  URI handling is 
155e0 67 6c 6f 62 61 6c 6c 79 20 64 69 73 61 62 6c 65  globally disable
155f0 64 2e 29 5e 20 5e 49 66 20 55 52 49 20 68 61 6e  d.)^ ^If URI han
15600 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c  dling is globall
15610 79 0a 2a 2a 20 65 6e 61 62 6c 65 64 2c 20 61 6c  y.** enabled, al
15620 6c 20 66 69 6c 65 6e 61 6d 65 73 20 70 61 73 73  l filenames pass
15630 65 64 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f  ed to [sqlite3_o
15640 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  pen()], [sqlite3
15650 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c 0a 2a 2a 20  _open_v2()],.** 
15660 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28  [sqlite3_open16(
15670 29 5d 20 6f 72 0a 2a 2a 20 73 70 65 63 69 66 69  )] or.** specifi
15680 65 64 20 61 73 20 70 61 72 74 20 6f 66 20 5b 41  ed as part of [A
15690 54 54 41 43 48 5d 20 63 6f 6d 6d 61 6e 64 73 20  TTACH] commands 
156a0 61 72 65 20 69 6e 74 65 72 70 72 65 74 65 64 20  are interpreted 
156b0 61 73 20 55 52 49 73 2c 20 72 65 67 61 72 64 6c  as URIs, regardl
156c0 65 73 73 0a 2a 2a 20 6f 66 20 77 68 65 74 68 65  ess.** of whethe
156d0 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 5b 53 51  r or not the [SQ
156e0 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 66  LITE_OPEN_URI] f
156f0 6c 61 67 20 69 73 20 73 65 74 20 77 68 65 6e 20  lag is set when 
15700 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  the database.** 
15710 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 70  connection is op
15720 65 6e 65 64 2e 20 5e 49 66 20 69 74 20 69 73 20  ened. ^If it is 
15730 67 6c 6f 62 61 6c 6c 79 20 64 69 73 61 62 6c 65  globally disable
15740 64 2c 20 66 69 6c 65 6e 61 6d 65 73 20 61 72 65  d, filenames are
15750 0a 2a 2a 20 6f 6e 6c 79 20 69 6e 74 65 72 70 72  .** only interpr
15760 65 74 65 64 20 61 73 20 55 52 49 73 20 69 66 20  eted as URIs if 
15770 74 68 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  the SQLITE_OPEN_
15780 55 52 49 20 66 6c 61 67 20 69 73 20 73 65 74 20  URI flag is set 
15790 77 68 65 6e 20 74 68 65 0a 2a 2a 20 64 61 74 61  when the.** data
157a0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
157b0 69 73 20 6f 70 65 6e 65 64 2e 20 5e 28 42 79 20  is opened. ^(By 
157c0 64 65 66 61 75 6c 74 2c 20 55 52 49 20 68 61 6e  default, URI han
157d0 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c  dling is globall
157e0 79 0a 2a 2a 20 64 69 73 61 62 6c 65 64 2e 20 54  y.** disabled. T
157f0 68 65 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65  he default value
15800 20 6d 61 79 20 62 65 20 63 68 61 6e 67 65 64 20   may be changed 
15810 62 79 20 63 6f 6d 70 69 6c 69 6e 67 20 77 69 74  by compiling wit
15820 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45  h the.** [SQLITE
15830 5f 55 53 45 5f 55 52 49 5d 20 73 79 6d 62 6f 6c  _USE_URI] symbol
15840 20 64 65 66 69 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a   defined.)^.**.*
15850 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
15860 47 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45 58  G_COVERING_INDEX
15870 5f 53 43 41 4e 5d 5d 20 3c 64 74 3e 53 51 4c 49  _SCAN]] <dt>SQLI
15880 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56 45 52 49  TE_CONFIG_COVERI
15890 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 0a 2a 2a  NG_INDEX_SCAN.**
158a0 20 3c 64 64 3e 5e 54 68 65 20 53 51 4c 49 54 45   <dd>^The SQLITE
158b0 5f 43 4f 4e 46 49 47 5f 43 4f 56 45 52 49 4e 47  _CONFIG_COVERING
158c0 5f 49 4e 44 45 58 5f 53 43 41 4e 20 6f 70 74 69  _INDEX_SCAN opti
158d0 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c  on takes a singl
158e0 65 20 69 6e 74 65 67 65 72 0a 2a 2a 20 61 72 67  e integer.** arg
158f0 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 69  ument which is i
15900 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 61 20  nterpreted as a 
15910 62 6f 6f 6c 65 61 6e 20 69 6e 20 6f 72 64 65 72  boolean in order
15920 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64 69   to enable or di
15930 73 61 62 6c 65 0a 2a 2a 20 74 68 65 20 75 73 65  sable.** the use
15940 20 6f 66 20 63 6f 76 65 72 69 6e 67 20 69 6e 64   of covering ind
15950 69 63 65 73 20 66 6f 72 20 66 75 6c 6c 20 74 61  ices for full ta
15960 62 6c 65 20 73 63 61 6e 73 20 69 6e 20 74 68 65  ble scans in the
15970 20 71 75 65 72 79 20 6f 70 74 69 6d 69 7a 65 72   query optimizer
15980 2e 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c  ..** ^The defaul
15990 74 20 73 65 74 74 69 6e 67 20 69 73 20 64 65 74  t setting is det
159a0 65 72 6d 69 6e 65 64 0a 2a 2a 20 62 79 20 74 68  ermined.** by th
159b0 65 20 5b 53 51 4c 49 54 45 5f 41 4c 4c 4f 57 5f  e [SQLITE_ALLOW_
159c0 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53  COVERING_INDEX_S
159d0 43 41 4e 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  CAN] compile-tim
159e0 65 20 6f 70 74 69 6f 6e 2c 20 6f 72 20 69 73 20  e option, or is 
159f0 22 6f 6e 22 0a 2a 2a 20 69 66 20 74 68 61 74 20  "on".** if that 
15a00 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
15a10 69 6f 6e 20 69 73 20 6f 6d 69 74 74 65 64 2e 0a  ion is omitted..
15a20 2a 2a 20 54 68 65 20 61 62 69 6c 69 74 79 20 74  ** The ability t
15a30 6f 20 64 69 73 61 62 6c 65 20 74 68 65 20 75 73  o disable the us
15a40 65 20 6f 66 20 63 6f 76 65 72 69 6e 67 20 69 6e  e of covering in
15a50 64 69 63 65 73 20 66 6f 72 20 66 75 6c 6c 20 74  dices for full t
15a60 61 62 6c 65 20 73 63 61 6e 73 0a 2a 2a 20 69 73  able scans.** is
15a70 20 62 65 63 61 75 73 65 20 73 6f 6d 65 20 69 6e   because some in
15a80 63 6f 72 72 65 63 74 6c 79 20 63 6f 64 65 64 20  correctly coded 
15a90 6c 65 67 61 63 79 20 61 70 70 6c 69 63 61 74 69  legacy applicati
15aa0 6f 6e 73 20 6d 69 67 68 74 20 6d 61 6c 66 75 6e  ons might malfun
15ab0 63 74 69 6f 6e 0a 2a 2a 20 77 68 65 6e 20 74 68  ction.** when th
15ac0 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 20 69  e optimization i
15ad0 73 20 65 6e 61 62 6c 65 64 2e 20 20 50 72 6f 76  s enabled.  Prov
15ae0 69 64 69 6e 67 20 74 68 65 20 61 62 69 6c 69 74  iding the abilit
15af0 79 20 74 6f 0a 2a 2a 20 64 69 73 61 62 6c 65 20  y to.** disable 
15b00 74 68 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e  the optimization
15b10 20 61 6c 6c 6f 77 73 20 74 68 65 20 6f 6c 64 65   allows the olde
15b20 72 2c 20 62 75 67 67 79 20 61 70 70 6c 69 63 61  r, buggy applica
15b30 74 69 6f 6e 20 63 6f 64 65 20 74 6f 20 77 6f 72  tion code to wor
15b40 6b 0a 2a 2a 20 77 69 74 68 6f 75 74 20 63 68 61  k.** without cha
15b50 6e 67 65 20 65 76 65 6e 20 77 69 74 68 20 6e 65  nge even with ne
15b60 77 65 72 20 76 65 72 73 69 6f 6e 73 20 6f 66 20  wer versions of 
15b70 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 5b 5b  SQLite..**.** [[
15b80 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43  SQLITE_CONFIG_PC
15b90 41 43 48 45 5d 5d 20 5b 5b 53 51 4c 49 54 45 5f  ACHE]] [[SQLITE_
15ba0 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45  CONFIG_GETPCACHE
15bb0 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  ]].** <dt>SQLITE
15bc0 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 20 61  _CONFIG_PCACHE a
15bd0 6e 64 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  nd SQLITE_CONFIG
15be0 5f 47 45 54 50 43 41 43 48 45 0a 2a 2a 20 3c 64  _GETPCACHE.** <d
15bf0 64 3e 20 54 68 65 73 65 20 6f 70 74 69 6f 6e 73  d> These options
15c00 20 61 72 65 20 6f 62 73 6f 6c 65 74 65 20 61 6e   are obsolete an
15c10 64 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20  d should not be 
15c20 75 73 65 64 20 62 79 20 6e 65 77 20 63 6f 64 65  used by new code
15c30 2e 0a 2a 2a 20 54 68 65 79 20 61 72 65 20 72 65  ..** They are re
15c40 74 61 69 6e 65 64 20 66 6f 72 20 62 61 63 6b 77  tained for backw
15c50 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69  ards compatibili
15c60 74 79 20 62 75 74 20 61 72 65 20 6e 6f 77 20 6e  ty but are now n
15c70 6f 2d 6f 70 73 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a  o-ops..** </dd>.
15c80 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
15c90 4f 4e 46 49 47 5f 53 51 4c 4c 4f 47 5d 5d 0a 2a  ONFIG_SQLLOG]].*
15ca0 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  * <dt>SQLITE_CON
15cb0 46 49 47 5f 53 51 4c 4c 4f 47 0a 2a 2a 20 3c 64  FIG_SQLLOG.** <d
15cc0 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20 69 73  d>This option is
15cd0 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20   only available 
15ce0 69 66 20 73 71 6c 69 74 65 20 69 73 20 63 6f 6d  if sqlite is com
15cf0 70 69 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a  piled with the.*
15d00 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45  * [SQLITE_ENABLE
15d10 5f 53 51 4c 4c 4f 47 5d 20 70 72 65 2d 70 72 6f  _SQLLOG] pre-pro
15d20 63 65 73 73 6f 72 20 6d 61 63 72 6f 20 64 65 66  cessor macro def
15d30 69 6e 65 64 2e 20 54 68 65 20 66 69 72 73 74 20  ined. The first 
15d40 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 0a  argument should.
15d50 2a 2a 20 62 65 20 61 20 70 6f 69 6e 74 65 72 20  ** be a pointer 
15d60 74 6f 20 61 20 66 75 6e 63 74 69 6f 6e 20 6f 66  to a function of
15d70 20 74 79 70 65 20 76 6f 69 64 28 2a 29 28 76 6f   type void(*)(vo
15d80 69 64 2a 2c 73 71 6c 69 74 65 33 2a 2c 63 6f 6e  id*,sqlite3*,con
15d90 73 74 20 63 68 61 72 2a 2c 20 69 6e 74 29 2e 0a  st char*, int)..
15da0 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 73 68  ** The second sh
15db0 6f 75 6c 64 20 62 65 20 6f 66 20 74 79 70 65 20  ould be of type 
15dc0 28 76 6f 69 64 2a 29 2e 20 54 68 65 20 63 61 6c  (void*). The cal
15dd0 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64  lback is invoked
15de0 20 62 79 20 74 68 65 20 6c 69 62 72 61 72 79 0a   by the library.
15df0 2a 2a 20 69 6e 20 74 68 72 65 65 20 73 65 70 61  ** in three sepa
15e00 72 61 74 65 20 63 69 72 63 75 6d 73 74 61 6e 63  rate circumstanc
15e10 65 73 2c 20 69 64 65 6e 74 69 66 69 65 64 20 62  es, identified b
15e20 79 20 74 68 65 20 76 61 6c 75 65 20 70 61 73 73  y the value pass
15e30 65 64 20 61 73 20 74 68 65 0a 2a 2a 20 66 6f 75  ed as the.** fou
15e40 72 74 68 20 70 61 72 61 6d 65 74 65 72 2e 20 49  rth parameter. I
15e50 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72  f the fourth par
15e60 61 6d 65 74 65 72 20 69 73 20 30 2c 20 74 68 65  ameter is 0, the
15e70 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  n the database c
15e80 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 70 61 73  onnection.** pas
15e90 73 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e  sed as the secon
15ea0 64 20 61 72 67 75 6d 65 6e 74 20 68 61 73 20 6a  d argument has j
15eb0 75 73 74 20 62 65 65 6e 20 6f 70 65 6e 65 64 2e  ust been opened.
15ec0 20 54 68 65 20 74 68 69 72 64 20 61 72 67 75 6d   The third argum
15ed0 65 6e 74 0a 2a 2a 20 70 6f 69 6e 74 73 20 74 6f  ent.** points to
15ee0 20 61 20 62 75 66 66 65 72 20 63 6f 6e 74 61 69   a buffer contai
15ef0 6e 69 6e 67 20 74 68 65 20 6e 61 6d 65 20 6f 66  ning the name of
15f00 20 74 68 65 20 6d 61 69 6e 20 64 61 74 61 62 61   the main databa
15f10 73 65 20 66 69 6c 65 2e 20 49 66 20 74 68 65 0a  se file. If the.
15f20 2a 2a 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  ** fourth parame
15f30 74 65 72 20 69 73 20 31 2c 20 74 68 65 6e 20 74  ter is 1, then t
15f40 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
15f50 20 74 68 61 74 20 74 68 65 20 74 68 69 72 64 20   that the third 
15f60 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 70 6f 69  parameter.** poi
15f70 6e 74 73 20 74 6f 20 68 61 73 20 6a 75 73 74 20  nts to has just 
15f80 62 65 65 6e 20 65 78 65 63 75 74 65 64 2e 20 4f  been executed. O
15f90 72 2c 20 69 66 20 74 68 65 20 66 6f 75 72 74 68  r, if the fourth
15fa0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 32 2c   parameter is 2,
15fb0 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 63 6f 6e   then.** the con
15fc0 6e 65 63 74 69 6f 6e 20 62 65 69 6e 67 20 70 61  nection being pa
15fd0 73 73 65 64 20 61 73 20 74 68 65 20 73 65 63 6f  ssed as the seco
15fe0 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  nd parameter is 
15ff0 62 65 69 6e 67 20 63 6c 6f 73 65 64 2e 20 54 68  being closed. Th
16000 65 0a 2a 2a 20 74 68 69 72 64 20 70 61 72 61 6d  e.** third param
16010 65 74 65 72 20 69 73 20 70 61 73 73 65 64 20 4e  eter is passed N
16020 55 4c 4c 20 49 6e 20 74 68 69 73 20 63 61 73 65  ULL In this case
16030 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65 20 6f 66  .  An example of
16040 20 75 73 69 6e 67 20 74 68 69 73 0a 2a 2a 20 63   using this.** c
16050 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
16060 69 6f 6e 20 63 61 6e 20 62 65 20 73 65 65 6e 20  ion can be seen 
16070 69 6e 20 74 68 65 20 22 74 65 73 74 5f 73 71 6c  in the "test_sql
16080 6c 6f 67 2e 63 22 20 73 6f 75 72 63 65 20 66 69  log.c" source fi
16090 6c 65 20 69 6e 0a 2a 2a 20 74 68 65 20 63 61 6e  le in.** the can
160a0 6f 6e 69 63 61 6c 20 53 51 4c 69 74 65 20 73 6f  onical SQLite so
160b0 75 72 63 65 20 74 72 65 65 2e 3c 2f 64 64 3e 0a  urce tree.</dd>.
160c0 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
160d0 4f 4e 46 49 47 5f 4d 4d 41 50 5f 53 49 5a 45 5d  ONFIG_MMAP_SIZE]
160e0 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  ].** <dt>SQLITE_
160f0 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f 53 49 5a 45  CONFIG_MMAP_SIZE
16100 0a 2a 2a 20 3c 64 64 3e 5e 53 51 4c 49 54 45 5f  .** <dd>^SQLITE_
16110 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f 53 49 5a 45  CONFIG_MMAP_SIZE
16120 20 74 61 6b 65 73 20 74 77 6f 20 36 34 2d 62 69   takes two 64-bi
16130 74 20 69 6e 74 65 67 65 72 20 28 73 71 6c 69 74  t integer (sqlit
16140 65 33 5f 69 6e 74 36 34 29 20 76 61 6c 75 65 73  e3_int64) values
16150 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 74 68 65  .** that are the
16160 20 64 65 66 61 75 6c 74 20 6d 6d 61 70 20 73 69   default mmap si
16170 7a 65 20 6c 69 6d 69 74 20 28 74 68 65 20 64 65  ze limit (the de
16180 66 61 75 6c 74 20 73 65 74 74 69 6e 67 20 66 6f  fault setting fo
16190 72 0a 2a 2a 20 5b 50 52 41 47 4d 41 20 6d 6d 61  r.** [PRAGMA mma
161a0 70 5f 73 69 7a 65 5d 29 20 61 6e 64 20 74 68 65  p_size]) and the
161b0 20 6d 61 78 69 6d 75 6d 20 61 6c 6c 6f 77 65 64   maximum allowed
161c0 20 6d 6d 61 70 20 73 69 7a 65 20 6c 69 6d 69 74   mmap size limit
161d0 2e 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c  ..** ^The defaul
161e0 74 20 73 65 74 74 69 6e 67 20 63 61 6e 20 62 65  t setting can be
161f0 20 6f 76 65 72 72 69 64 64 65 6e 20 62 79 20 65   overridden by e
16200 61 63 68 20 64 61 74 61 62 61 73 65 20 63 6f 6e  ach database con
16210 6e 65 63 74 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a  nection using.**
16220 20 65 69 74 68 65 72 20 74 68 65 20 5b 50 52 41   either the [PRA
16230 47 4d 41 20 6d 6d 61 70 5f 73 69 7a 65 5d 20 63  GMA mmap_size] c
16240 6f 6d 6d 61 6e 64 2c 20 6f 72 20 62 79 20 75 73  ommand, or by us
16250 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49  ing the.** [SQLI
16260 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49  TE_FCNTL_MMAP_SI
16270 5a 45 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c  ZE] file control
16280 2e 20 20 5e 28 54 68 65 20 6d 61 78 69 6d 75 6d  .  ^(The maximum
16290 20 61 6c 6c 6f 77 65 64 20 6d 6d 61 70 20 73 69   allowed mmap si
162a0 7a 65 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 73 69  ze.** will be si
162b0 6c 65 6e 74 6c 79 20 74 72 75 6e 63 61 74 65 64  lently truncated
162c0 20 69 66 20 6e 65 63 65 73 73 61 72 79 20 73 6f   if necessary so
162d0 20 74 68 61 74 20 69 74 20 64 6f 65 73 20 6e 6f   that it does no
162e0 74 20 65 78 63 65 65 64 20 74 68 65 0a 2a 2a 20  t exceed the.** 
162f0 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6d 61 78  compile-time max
16300 69 6d 75 6d 20 6d 6d 61 70 20 73 69 7a 65 20 73  imum mmap size s
16310 65 74 20 62 79 20 74 68 65 0a 2a 2a 20 5b 53 51  et by the.** [SQ
16320 4c 49 54 45 5f 4d 41 58 5f 4d 4d 41 50 5f 53 49  LITE_MAX_MMAP_SI
16330 5a 45 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  ZE] compile-time
16340 20 6f 70 74 69 6f 6e 2e 29 5e 0a 2a 2a 20 5e 49   option.)^.** ^I
16350 66 20 65 69 74 68 65 72 20 61 72 67 75 6d 65 6e  f either argumen
16360 74 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e  t to this option
16370 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68   is negative, th
16380 65 6e 20 74 68 61 74 20 61 72 67 75 6d 65 6e 74  en that argument
16390 20 69 73 0a 2a 2a 20 63 68 61 6e 67 65 64 20 74   is.** changed t
163a0 6f 20 69 74 73 20 63 6f 6d 70 69 6c 65 2d 74 69  o its compile-ti
163b0 6d 65 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 0a 2a  me default..**.*
163c0 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
163d0 47 5f 57 49 4e 33 32 5f 48 45 41 50 53 49 5a 45  G_WIN32_HEAPSIZE
163e0 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  ]].** <dt>SQLITE
163f0 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f 48 45  _CONFIG_WIN32_HE
16400 41 50 53 49 5a 45 0a 2a 2a 20 3c 64 64 3e 5e 54  APSIZE.** <dd>^T
16410 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
16420 5f 57 49 4e 33 32 5f 48 45 41 50 53 49 5a 45 20  _WIN32_HEAPSIZE 
16430 6f 70 74 69 6f 6e 20 69 73 20 6f 6e 6c 79 20 61  option is only a
16440 76 61 69 6c 61 62 6c 65 20 69 66 20 53 51 4c 69  vailable if SQLi
16450 74 65 20 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65  te is.** compile
16460 64 20 66 6f 72 20 57 69 6e 64 6f 77 73 20 77 69  d for Windows wi
16470 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 57  th the [SQLITE_W
16480 49 4e 33 32 5f 4d 41 4c 4c 4f 43 5d 20 70 72 65  IN32_MALLOC] pre
16490 2d 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f  -processor macro
164a0 0a 2a 2a 20 64 65 66 69 6e 65 64 2e 20 5e 53 51  .** defined. ^SQ
164b0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33  LITE_CONFIG_WIN3
164c0 32 5f 48 45 41 50 53 49 5a 45 20 74 61 6b 65 73  2_HEAPSIZE takes
164d0 20 61 20 33 32 2d 62 69 74 20 75 6e 73 69 67 6e   a 32-bit unsign
164e0 65 64 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65  ed integer value
164f0 0a 2a 2a 20 74 68 61 74 20 73 70 65 63 69 66 69  .** that specifi
16500 65 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 73  es the maximum s
16510 69 7a 65 20 6f 66 20 74 68 65 20 63 72 65 61 74  ize of the creat
16520 65 64 20 68 65 61 70 2e 0a 2a 2a 0a 2a 2a 20 5b  ed heap..**.** [
16530 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50  [SQLITE_CONFIG_P
16540 43 41 43 48 45 5f 48 44 52 53 5a 5d 5d 0a 2a 2a  CACHE_HDRSZ]].**
16550 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
16560 49 47 5f 50 43 41 43 48 45 5f 48 44 52 53 5a 0a  IG_PCACHE_HDRSZ.
16570 2a 2a 20 3c 64 64 3e 5e 54 68 65 20 53 51 4c 49  ** <dd>^The SQLI
16580 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45  TE_CONFIG_PCACHE
16590 5f 48 44 52 53 5a 20 6f 70 74 69 6f 6e 20 74 61  _HDRSZ option ta
165a0 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 70 61 72  kes a single par
165b0 61 6d 65 74 65 72 20 77 68 69 63 68 0a 2a 2a 20  ameter which.** 
165c0 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
165d0 61 6e 20 69 6e 74 65 67 65 72 20 61 6e 64 20 77  an integer and w
165e0 72 69 74 65 73 20 69 6e 74 6f 20 74 68 61 74 20  rites into that 
165f0 69 6e 74 65 67 65 72 20 74 68 65 20 6e 75 6d 62  integer the numb
16600 65 72 20 6f 66 20 65 78 74 72 61 0a 2a 2a 20 62  er of extra.** b
16610 79 74 65 73 20 70 65 72 20 70 61 67 65 20 72 65  ytes per page re
16620 71 75 69 72 65 64 20 66 6f 72 20 65 61 63 68 20  quired for each 
16630 70 61 67 65 20 69 6e 20 5b 53 51 4c 49 54 45 5f  page in [SQLITE_
16640 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45  CONFIG_PAGECACHE
16650 5d 2e 0a 2a 2a 20 54 68 65 20 61 6d 6f 75 6e 74  ]..** The amount
16660 20 6f 66 20 65 78 74 72 61 20 73 70 61 63 65 20   of extra space 
16670 72 65 71 75 69 72 65 64 20 63 61 6e 20 63 68 61  required can cha
16680 6e 67 65 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e  nge depending on
16690 20 74 68 65 20 63 6f 6d 70 69 6c 65 72 2c 0a 2a   the compiler,.*
166a0 2a 20 74 61 72 67 65 74 20 70 6c 61 74 66 6f 72  * target platfor
166b0 6d 2c 20 61 6e 64 20 53 51 4c 69 74 65 20 76 65  m, and SQLite ve
166c0 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  rsion..**.** [[S
166d0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 4d 41  QLITE_CONFIG_PMA
166e0 53 5a 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  SZ]].** <dt>SQLI
166f0 54 45 5f 43 4f 4e 46 49 47 5f 50 4d 41 53 5a 0a  TE_CONFIG_PMASZ.
16700 2a 2a 20 3c 64 64 3e 5e 54 68 65 20 53 51 4c 49  ** <dd>^The SQLI
16710 54 45 5f 43 4f 4e 46 49 47 5f 50 4d 41 53 5a 20  TE_CONFIG_PMASZ 
16720 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73  option takes a s
16730 69 6e 67 6c 65 20 70 61 72 61 6d 65 74 65 72 20  ingle parameter 
16740 77 68 69 63 68 0a 2a 2a 20 69 73 20 61 6e 20 75  which.** is an u
16750 6e 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 20  nsigned integer 
16760 61 6e 64 20 73 65 74 73 20 74 68 65 20 22 4d 69  and sets the "Mi
16770 6e 69 6d 75 6d 20 50 4d 41 20 53 69 7a 65 22 20  nimum PMA Size" 
16780 66 6f 72 20 74 68 65 20 6d 75 6c 74 69 74 68 72  for the multithr
16790 65 61 64 65 64 0a 2a 2a 20 73 6f 72 74 65 72 20  eaded.** sorter 
167a0 74 6f 20 74 68 61 74 20 69 6e 74 65 67 65 72 2e  to that integer.
167b0 20 20 54 68 65 20 64 65 66 61 75 6c 74 20 6d 69    The default mi
167c0 6e 69 6d 75 6d 20 50 4d 41 20 53 69 7a 65 20 69  nimum PMA Size i
167d0 73 20 73 65 74 20 62 79 20 74 68 65 0a 2a 2a 20  s set by the.** 
167e0 5b 53 51 4c 49 54 45 5f 53 4f 52 54 45 52 5f 50  [SQLITE_SORTER_P
167f0 4d 41 53 5a 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  MASZ] compile-ti
16800 6d 65 20 6f 70 74 69 6f 6e 2e 20 20 4e 65 77 20  me option.  New 
16810 74 68 72 65 61 64 73 20 61 72 65 20 6c 61 75 6e  threads are laun
16820 63 68 65 64 0a 2a 2a 20 74 6f 20 68 65 6c 70 20  ched.** to help 
16830 77 69 74 68 20 73 6f 72 74 20 6f 70 65 72 61 74  with sort operat
16840 69 6f 6e 73 20 77 68 65 6e 20 6d 75 6c 74 69 74  ions when multit
16850 68 72 65 61 64 65 64 20 73 6f 72 74 69 6e 67 0a  hreaded sorting.
16860 2a 2a 20 69 73 20 65 6e 61 62 6c 65 64 20 28 75  ** is enabled (u
16870 73 69 6e 67 20 74 68 65 20 5b 50 52 41 47 4d 41  sing the [PRAGMA
16880 20 74 68 72 65 61 64 73 5d 20 63 6f 6d 6d 61 6e   threads] comman
16890 64 29 20 61 6e 64 20 74 68 65 20 61 6d 6f 75 6e  d) and the amoun
168a0 74 20 6f 66 20 63 6f 6e 74 65 6e 74 0a 2a 2a 20  t of content.** 
168b0 74 6f 20 62 65 20 73 6f 72 74 65 64 20 65 78 63  to be sorted exc
168c0 65 65 64 73 20 74 68 65 20 70 61 67 65 20 73 69  eeds the page si
168d0 7a 65 20 74 69 6d 65 73 20 74 68 65 20 6d 69 6e  ze times the min
168e0 69 6d 75 6d 20 6f 66 20 74 68 65 0a 2a 2a 20 5b  imum of the.** [
168f0 50 52 41 47 4d 41 20 63 61 63 68 65 5f 73 69 7a  PRAGMA cache_siz
16900 65 5d 20 73 65 74 74 69 6e 67 20 61 6e 64 20 74  e] setting and t
16910 68 69 73 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a  his value..**.**
16920 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
16930 5f 53 54 4d 54 4a 52 4e 4c 5f 53 50 49 4c 4c 5d  _STMTJRNL_SPILL]
16940 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  ].** <dt>SQLITE_
16950 43 4f 4e 46 49 47 5f 53 54 4d 54 4a 52 4e 4c 5f  CONFIG_STMTJRNL_
16960 53 50 49 4c 4c 0a 2a 2a 20 3c 64 64 3e 5e 54 68  SPILL.** <dd>^Th
16970 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
16980 53 54 4d 54 4a 52 4e 4c 5f 53 50 49 4c 4c 20 6f  STMTJRNL_SPILL o
16990 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69  ption takes a si
169a0 6e 67 6c 65 20 70 61 72 61 6d 65 74 65 72 20 77  ngle parameter w
169b0 68 69 63 68 0a 2a 2a 20 62 65 63 6f 6d 65 73 20  hich.** becomes 
169c0 74 68 65 20 5b 73 74 61 74 65 6d 65 6e 74 20 6a  the [statement j
169d0 6f 75 72 6e 61 6c 5d 20 73 70 69 6c 6c 2d 74 6f  ournal] spill-to
169e0 2d 64 69 73 6b 20 74 68 72 65 73 68 6f 6c 64 2e  -disk threshold.
169f0 20 20 0a 2a 2a 20 5b 53 74 61 74 65 6d 65 6e 74    .** [Statement
16a00 20 6a 6f 75 72 6e 61 6c 73 5d 20 61 72 65 20 68   journals] are h
16a10 65 6c 64 20 69 6e 20 6d 65 6d 6f 72 79 20 75 6e  eld in memory un
16a20 74 69 6c 20 74 68 65 69 72 20 73 69 7a 65 20 28  til their size (
16a30 69 6e 20 62 79 74 65 73 29 0a 2a 2a 20 65 78 63  in bytes).** exc
16a40 65 65 64 73 20 74 68 69 73 20 74 68 72 65 73 68  eeds this thresh
16a50 6f 6c 64 2c 20 61 74 20 77 68 69 63 68 20 70 6f  old, at which po
16a60 69 6e 74 20 74 68 65 79 20 61 72 65 20 77 72 69  int they are wri
16a70 74 74 65 6e 20 74 6f 20 64 69 73 6b 2e 0a 2a 2a  tten to disk..**
16a80 20 4f 72 20 69 66 20 74 68 65 20 74 68 72 65 73   Or if the thres
16a90 68 6f 6c 64 20 69 73 20 2d 31 2c 20 73 74 61 74  hold is -1, stat
16aa0 65 6d 65 6e 74 20 6a 6f 75 72 6e 61 6c 73 20 61  ement journals a
16ab0 72 65 20 61 6c 77 61 79 73 20 68 65 6c 64 0a 2a  re always held.*
16ac0 2a 20 65 78 63 6c 75 73 69 76 65 6c 79 20 69 6e  * exclusively in
16ad0 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 53 69 6e 63   memory..** Sinc
16ae0 65 20 6d 61 6e 79 20 73 74 61 74 65 6d 65 6e 74  e many statement
16af0 20 6a 6f 75 72 6e 61 6c 73 20 6e 65 76 65 72 20   journals never 
16b00 62 65 63 6f 6d 65 20 6c 61 72 67 65 2c 20 73 65  become large, se
16b10 74 74 69 6e 67 20 74 68 65 20 73 70 69 6c 6c 0a  tting the spill.
16b20 2a 2a 20 74 68 72 65 73 68 6f 6c 64 20 74 6f 20  ** threshold to 
16b30 61 20 76 61 6c 75 65 20 73 75 63 68 20 61 73 20  a value such as 
16b40 36 34 4b 69 42 20 63 61 6e 20 67 72 65 61 74 6c  64KiB can greatl
16b50 79 20 72 65 64 75 63 65 20 74 68 65 20 61 6d 6f  y reduce the amo
16b60 75 6e 74 20 6f 66 0a 2a 2a 20 49 2f 4f 20 72 65  unt of.** I/O re
16b70 71 75 69 72 65 64 20 74 6f 20 73 75 70 70 6f 72  quired to suppor
16b80 74 20 73 74 61 74 65 6d 65 6e 74 20 72 6f 6c 6c  t statement roll
16b90 62 61 63 6b 2e 0a 2a 2a 20 54 68 65 20 64 65 66  back..** The def
16ba0 61 75 6c 74 20 76 61 6c 75 65 20 66 6f 72 20 74  ault value for t
16bb0 68 69 73 20 73 65 74 74 69 6e 67 20 69 73 20 63  his setting is c
16bc0 6f 6e 74 72 6f 6c 6c 65 64 20 62 79 20 74 68 65  ontrolled by the
16bd0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 53 54 4d 54  .** [SQLITE_STMT
16be0 4a 52 4e 4c 5f 53 50 49 4c 4c 5d 20 63 6f 6d 70  JRNL_SPILL] comp
16bf0 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2e  ile-time option.
16c00 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65  .** </dl>.*/.#de
16c10 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
16c20 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 20  IG_SINGLETHREAD 
16c30 20 31 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64   1  /* nil */.#d
16c40 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
16c50 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 20  FIG_MULTITHREAD 
16c60 20 20 32 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23    2  /* nil */.#
16c70 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
16c80 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 20  NFIG_SERIALIZED 
16c90 20 20 20 33 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a     3  /* nil */.
16ca0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
16cb0 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 20 20 20 20  ONFIG_MALLOC    
16cc0 20 20 20 20 34 20 20 2f 2a 20 73 71 6c 69 74 65      4  /* sqlite
16cd0 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a  3_mem_methods* *
16ce0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
16cf0 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f  _CONFIG_GETMALLO
16d00 43 20 20 20 20 20 35 20 20 2f 2a 20 73 71 6c 69  C     5  /* sqli
16d10 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a  te3_mem_methods*
16d20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
16d30 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43  TE_CONFIG_SCRATC
16d40 48 20 20 20 20 20 20 20 36 20 20 2f 2a 20 76 6f  H       6  /* vo
16d50 69 64 2a 2c 20 69 6e 74 20 73 7a 2c 20 69 6e 74  id*, int sz, int
16d60 20 4e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51   N */.#define SQ
16d70 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45  LITE_CONFIG_PAGE
16d80 43 41 43 48 45 20 20 20 20 20 37 20 20 2f 2a 20  CACHE     7  /* 
16d90 76 6f 69 64 2a 2c 20 69 6e 74 20 73 7a 2c 20 69  void*, int sz, i
16da0 6e 74 20 4e 20 2a 2f 0a 23 64 65 66 69 6e 65 20  nt N */.#define 
16db0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45  SQLITE_CONFIG_HE
16dc0 41 50 20 20 20 20 20 20 20 20 20 20 38 20 20 2f  AP          8  /
16dd0 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 6e 42 79  * void*, int nBy
16de0 74 65 2c 20 69 6e 74 20 6d 69 6e 20 2a 2f 0a 23  te, int min */.#
16df0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
16e00 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 20 20  NFIG_MEMSTATUS  
16e10 20 20 20 39 20 20 2f 2a 20 62 6f 6f 6c 65 61 6e     9  /* boolean
16e20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
16e30 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 20  TE_CONFIG_MUTEX 
16e40 20 20 20 20 20 20 20 31 30 20 20 2f 2a 20 73 71         10  /* sq
16e50 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68  lite3_mutex_meth
16e60 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20  ods* */.#define 
16e70 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
16e80 54 4d 55 54 45 58 20 20 20 20 20 31 31 20 20 2f  TMUTEX     11  /
16e90 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f  * sqlite3_mutex_
16ea0 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 2f 2a 20 70  methods* */./* p
16eb0 72 65 76 69 6f 75 73 6c 79 20 53 51 4c 49 54 45  reviously SQLITE
16ec0 5f 43 4f 4e 46 49 47 5f 43 48 55 4e 4b 41 4c 4c  _CONFIG_CHUNKALL
16ed0 4f 43 20 31 32 20 77 68 69 63 68 20 69 73 20 6e  OC 12 which is n
16ee0 6f 77 20 75 6e 75 73 65 64 2e 20 2a 2f 20 0a 23  ow unused. */ .#
16ef0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
16f00 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 20  NFIG_LOOKASIDE  
16f10 20 20 31 33 20 20 2f 2a 20 69 6e 74 20 69 6e 74    13  /* int int
16f20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
16f30 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45  TE_CONFIG_PCACHE
16f40 20 20 20 20 20 20 20 31 34 20 20 2f 2a 20 6e 6f         14  /* no
16f50 2d 6f 70 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  -op */.#define S
16f60 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
16f70 50 43 41 43 48 45 20 20 20 20 31 35 20 20 2f 2a  PCACHE    15  /*
16f80 20 6e 6f 2d 6f 70 20 2a 2f 0a 23 64 65 66 69 6e   no-op */.#defin
16f90 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
16fa0 4c 4f 47 20 20 20 20 20 20 20 20 20 20 31 36 20  LOG          16 
16fb0 20 2f 2a 20 78 46 75 6e 63 2c 20 76 6f 69 64 2a   /* xFunc, void*
16fc0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
16fd0 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 20 20 20  TE_CONFIG_URI   
16fe0 20 20 20 20 20 20 20 31 37 20 20 2f 2a 20 69 6e         17  /* in
16ff0 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  t */.#define SQL
17000 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48  ITE_CONFIG_PCACH
17010 45 32 20 20 20 20 20 20 31 38 20 20 2f 2a 20 73  E2      18  /* s
17020 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65  qlite3_pcache_me
17030 74 68 6f 64 73 32 2a 20 2a 2f 0a 23 64 65 66 69  thods2* */.#defi
17040 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
17050 5f 47 45 54 50 43 41 43 48 45 32 20 20 20 31 39  _GETPCACHE2   19
17060 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 70 63 61    /* sqlite3_pca
17070 63 68 65 5f 6d 65 74 68 6f 64 73 32 2a 20 2a 2f  che_methods2* */
17080 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
17090 43 4f 4e 46 49 47 5f 43 4f 56 45 52 49 4e 47 5f  CONFIG_COVERING_
170a0 49 4e 44 45 58 5f 53 43 41 4e 20 32 30 20 20 2f  INDEX_SCAN 20  /
170b0 2a 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65  * int */.#define
170c0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53   SQLITE_CONFIG_S
170d0 51 4c 4c 4f 47 20 20 20 20 20 20 20 32 31 20 20  QLLOG       21  
170e0 2f 2a 20 78 53 71 6c 6c 6f 67 2c 20 76 6f 69 64  /* xSqllog, void
170f0 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  * */.#define SQL
17100 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f  ITE_CONFIG_MMAP_
17110 53 49 5a 45 20 20 20 20 32 32 20 20 2f 2a 20 73  SIZE    22  /* s
17120 71 6c 69 74 65 33 5f 69 6e 74 36 34 2c 20 73 71  qlite3_int64, sq
17130 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a 2f 0a 23  lite3_int64 */.#
17140 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
17150 4e 46 49 47 5f 57 49 4e 33 32 5f 48 45 41 50 53  NFIG_WIN32_HEAPS
17160 49 5a 45 20 20 20 20 20 20 32 33 20 20 2f 2a 20  IZE      23  /* 
17170 69 6e 74 20 6e 42 79 74 65 20 2a 2f 0a 23 64 65  int nByte */.#de
17180 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
17190 49 47 5f 50 43 41 43 48 45 5f 48 44 52 53 5a 20  IG_PCACHE_HDRSZ 
171a0 20 20 20 20 20 20 20 32 34 20 20 2f 2a 20 69 6e         24  /* in
171b0 74 20 2a 70 73 7a 20 2a 2f 0a 23 64 65 66 69 6e  t *psz */.#defin
171c0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
171d0 50 4d 41 53 5a 20 20 20 20 20 20 20 20 20 20 20  PMASZ           
171e0 20 20 20 20 32 35 20 20 2f 2a 20 75 6e 73 69 67      25  /* unsig
171f0 6e 65 64 20 69 6e 74 20 73 7a 50 6d 61 20 2a 2f  ned int szPma */
17200 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
17210 43 4f 4e 46 49 47 5f 53 54 4d 54 4a 52 4e 4c 5f  CONFIG_STMTJRNL_
17220 53 50 49 4c 4c 20 20 20 20 20 20 32 36 20 20 2f  SPILL      26  /
17230 2a 20 69 6e 74 20 6e 42 79 74 65 20 2a 2f 0a 0a  * int nByte */..
17240 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
17250 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74  Database Connect
17260 69 6f 6e 20 43 6f 6e 66 69 67 75 72 61 74 69 6f  ion Configuratio
17270 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20  n Options.**.** 
17280 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20  These constants 
17290 61 72 65 20 74 68 65 20 61 76 61 69 6c 61 62 6c  are the availabl
172a0 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 66 69 67  e integer config
172b0 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20  uration options 
172c0 74 68 61 74 0a 2a 2a 20 63 61 6e 20 62 65 20 70  that.** can be p
172d0 61 73 73 65 64 20 61 73 20 74 68 65 20 73 65 63  assed as the sec
172e0 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ond argument to 
172f0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f  the [sqlite3_db_
17300 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66  config()] interf
17310 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63  ace..**.** New c
17320 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
17330 69 6f 6e 73 20 6d 61 79 20 62 65 20 61 64 64 65  ions may be adde
17340 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65  d in future rele
17350 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a  ases of SQLite..
17360 2a 2a 20 45 78 69 73 74 69 6e 67 20 63 6f 6e 66  ** Existing conf
17370 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
17380 73 20 6d 69 67 68 74 20 62 65 20 64 69 73 63 6f  s might be disco
17390 6e 74 69 6e 75 65 64 2e 20 20 41 70 70 6c 69 63  ntinued.  Applic
173a0 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64  ations.** should
173b0 20 63 68 65 63 6b 20 74 68 65 20 72 65 74 75 72   check the retur
173c0 6e 20 63 6f 64 65 20 66 72 6f 6d 20 5b 73 71 6c  n code from [sql
173d0 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29  ite3_db_config()
173e0 5d 20 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 74  ] to make sure t
173f0 68 61 74 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20  hat.** the call 
17400 77 6f 72 6b 65 64 2e 20 20 5e 54 68 65 20 5b 73  worked.  ^The [s
17410 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67  qlite3_db_config
17420 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 77 69  ()] interface wi
17430 6c 6c 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 6e  ll return a.** n
17440 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63  on-zero [error c
17450 6f 64 65 5d 20 69 66 20 61 20 64 69 73 63 6f 6e  ode] if a discon
17460 74 69 6e 75 65 64 20 6f 72 20 75 6e 73 75 70 70  tinued or unsupp
17470 6f 72 74 65 64 20 63 6f 6e 66 69 67 75 72 61 74  orted configurat
17480 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73  ion option.** is
17490 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20   invoked..**.** 
174a0 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  <dl>.** <dt>SQLI
174b0 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b  TE_DBCONFIG_LOOK
174c0 41 53 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ASIDE</dt>.** <d
174d0 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20  d> ^This option 
174e0 74 61 6b 65 73 20 74 68 72 65 65 20 61 64 64 69  takes three addi
174f0 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73  tional arguments
17500 20 74 68 61 74 20 64 65 74 65 72 6d 69 6e 65 20   that determine 
17510 74 68 65 20 0a 2a 2a 20 5b 6c 6f 6f 6b 61 73 69  the .** [lookasi
17520 64 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  de memory alloca
17530 74 6f 72 5d 20 63 6f 6e 66 69 67 75 72 61 74 69  tor] configurati
17540 6f 6e 20 66 6f 72 20 74 68 65 20 5b 64 61 74 61  on for the [data
17550 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
17560 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20  ..** ^The first 
17570 61 72 67 75 6d 65 6e 74 20 28 74 68 65 20 74 68  argument (the th
17580 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ird parameter to
17590 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e   [sqlite3_db_con
175a0 66 69 67 28 29 5d 20 69 73 20 61 0a 2a 2a 20 70  fig()] is a.** p
175b0 6f 69 6e 74 65 72 20 74 6f 20 61 20 6d 65 6d 6f  ointer to a memo
175c0 72 79 20 62 75 66 66 65 72 20 74 6f 20 75 73 65  ry buffer to use
175d0 20 66 6f 72 20 6c 6f 6f 6b 61 73 69 64 65 20 6d   for lookaside m
175e0 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 54 68 65 20 66  emory..** ^The f
175f0 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 61 66  irst argument af
17600 74 65 72 20 74 68 65 20 53 51 4c 49 54 45 5f 44  ter the SQLITE_D
17610 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44  BCONFIG_LOOKASID
17620 45 20 76 65 72 62 0a 2a 2a 20 6d 61 79 20 62 65  E verb.** may be
17630 20 4e 55 4c 4c 20 69 6e 20 77 68 69 63 68 20 63   NULL in which c
17640 61 73 65 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  ase SQLite will 
17650 61 6c 6c 6f 63 61 74 65 20 74 68 65 0a 2a 2a 20  allocate the.** 
17660 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66 66 65 72  lookaside buffer
17670 20 69 74 73 65 6c 66 20 75 73 69 6e 67 20 5b 73   itself using [s
17680 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
17690 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 61 72  . ^The second ar
176a0 67 75 6d 65 6e 74 20 69 73 20 74 68 65 0a 2a 2a  gument is the.**
176b0 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20 6c 6f   size of each lo
176c0 6f 6b 61 73 69 64 65 20 62 75 66 66 65 72 20 73  okaside buffer s
176d0 6c 6f 74 2e 20 20 5e 54 68 65 20 74 68 69 72 64  lot.  ^The third
176e0 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65   argument is the
176f0 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 73 6c   number of.** sl
17700 6f 74 73 2e 20 20 54 68 65 20 73 69 7a 65 20 6f  ots.  The size o
17710 66 20 74 68 65 20 62 75 66 66 65 72 20 69 6e 20  f the buffer in 
17720 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
17730 6e 74 20 6d 75 73 74 20 62 65 20 67 72 65 61 74  nt must be great
17740 65 72 20 74 68 61 6e 0a 2a 2a 20 6f 72 20 65 71  er than.** or eq
17750 75 61 6c 20 74 6f 20 74 68 65 20 70 72 6f 64 75  ual to the produ
17760 63 74 20 6f 66 20 74 68 65 20 73 65 63 6f 6e 64  ct of the second
17770 20 61 6e 64 20 74 68 69 72 64 20 61 72 67 75 6d   and third argum
17780 65 6e 74 73 2e 20 20 54 68 65 20 62 75 66 66 65  ents.  The buffe
17790 72 0a 2a 2a 20 6d 75 73 74 20 62 65 20 61 6c 69  r.** must be ali
177a0 67 6e 65 64 20 74 6f 20 61 6e 20 38 2d 62 79 74  gned to an 8-byt
177b0 65 20 62 6f 75 6e 64 61 72 79 2e 20 20 5e 49 66  e boundary.  ^If
177c0 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   the second argu
177d0 6d 65 6e 74 20 74 6f 0a 2a 2a 20 53 51 4c 49 54  ment to.** SQLIT
177e0 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41  E_DBCONFIG_LOOKA
177f0 53 49 44 45 20 69 73 20 6e 6f 74 20 61 20 6d 75  SIDE is not a mu
17800 6c 74 69 70 6c 65 20 6f 66 20 38 2c 20 69 74 20  ltiple of 8, it 
17810 69 73 20 69 6e 74 65 72 6e 61 6c 6c 79 0a 2a 2a  is internally.**
17820 20 72 6f 75 6e 64 65 64 20 64 6f 77 6e 20 74 6f   rounded down to
17830 20 74 68 65 20 6e 65 78 74 20 73 6d 61 6c 6c 65   the next smalle
17840 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20 38 2e  r multiple of 8.
17850 20 20 5e 28 54 68 65 20 6c 6f 6f 6b 61 73 69 64    ^(The lookasid
17860 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 63 6f 6e 66  e memory.** conf
17870 69 67 75 72 61 74 69 6f 6e 20 66 6f 72 20 61 20  iguration for a 
17880 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
17890 69 6f 6e 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20  ion can only be 
178a0 63 68 61 6e 67 65 64 20 77 68 65 6e 20 74 68 61  changed when tha
178b0 74 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  t.** connection 
178c0 69 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79  is not currently
178d0 20 75 73 69 6e 67 20 6c 6f 6f 6b 61 73 69 64 65   using lookaside
178e0 20 6d 65 6d 6f 72 79 2c 20 6f 72 20 69 6e 20 6f   memory, or in o
178f0 74 68 65 72 20 77 6f 72 64 73 0a 2a 2a 20 77 68  ther words.** wh
17900 65 6e 20 74 68 65 20 22 63 75 72 72 65 6e 74 20  en the "current 
17910 76 61 6c 75 65 22 20 72 65 74 75 72 6e 65 64 20  value" returned 
17920 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 64  by.** [sqlite3_d
17930 62 5f 73 74 61 74 75 73 5d 28 44 2c 5b 53 51 4c  b_status](D,[SQL
17940 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41  ITE_CONFIG_LOOKA
17950 53 49 44 45 5d 2c 2e 2e 2e 29 20 69 73 20 7a 65  SIDE],...) is ze
17960 72 6f 2e 0a 2a 2a 20 41 6e 79 20 61 74 74 65 6d  ro..** Any attem
17970 70 74 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65  pt to change the
17980 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72   lookaside memor
17990 79 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  y configuration 
179a0 77 68 65 6e 20 6c 6f 6f 6b 61 73 69 64 65 0a 2a  when lookaside.*
179b0 2a 20 6d 65 6d 6f 72 79 20 69 73 20 69 6e 20 75  * memory is in u
179c0 73 65 20 6c 65 61 76 65 73 20 74 68 65 20 63 6f  se leaves the co
179d0 6e 66 69 67 75 72 61 74 69 6f 6e 20 75 6e 63 68  nfiguration unch
179e0 61 6e 67 65 64 20 61 6e 64 20 72 65 74 75 72 6e  anged and return
179f0 73 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 42 55  s .** [SQLITE_BU
17a00 53 59 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  SY].)^</dd>.**.*
17a10 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43  * <dt>SQLITE_DBC
17a20 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 46 4b 45  ONFIG_ENABLE_FKE
17a30 59 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  Y</dt>.** <dd> ^
17a40 54 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 75  This option is u
17a50 73 65 64 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72  sed to enable or
17a60 20 64 69 73 61 62 6c 65 20 74 68 65 20 65 6e 66   disable the enf
17a70 6f 72 63 65 6d 65 6e 74 20 6f 66 0a 2a 2a 20 5b  orcement of.** [
17a80 66 6f 72 65 69 67 6e 20 6b 65 79 20 63 6f 6e 73  foreign key cons
17a90 74 72 61 69 6e 74 73 5d 2e 20 20 54 68 65 72 65  traints].  There
17aa0 20 73 68 6f 75 6c 64 20 62 65 20 74 77 6f 20 61   should be two a
17ab0 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65  dditional argume
17ac0 6e 74 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73  nts..** The firs
17ad0 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 6e  t argument is an
17ae0 20 69 6e 74 65 67 65 72 20 77 68 69 63 68 20 69   integer which i
17af0 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65 20 46  s 0 to disable F
17b00 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 2c 0a 2a  K enforcement,.*
17b10 2a 20 70 6f 73 69 74 69 76 65 20 74 6f 20 65 6e  * positive to en
17b20 61 62 6c 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d  able FK enforcem
17b30 65 6e 74 20 6f 72 20 6e 65 67 61 74 69 76 65 20  ent or negative 
17b40 74 6f 20 6c 65 61 76 65 20 46 4b 20 65 6e 66 6f  to leave FK enfo
17b50 72 63 65 6d 65 6e 74 0a 2a 2a 20 75 6e 63 68 61  rcement.** uncha
17b60 6e 67 65 64 2e 20 20 54 68 65 20 73 65 63 6f 6e  nged.  The secon
17b70 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61  d parameter is a
17b80 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69   pointer to an i
17b90 6e 74 65 67 65 72 20 69 6e 74 6f 20 77 68 69 63  nteger into whic
17ba0 68 0a 2a 2a 20 69 73 20 77 72 69 74 74 65 6e 20  h.** is written 
17bb0 30 20 6f 72 20 31 20 74 6f 20 69 6e 64 69 63 61  0 or 1 to indica
17bc0 74 65 20 77 68 65 74 68 65 72 20 46 4b 20 65 6e  te whether FK en
17bd0 66 6f 72 63 65 6d 65 6e 74 20 69 73 20 6f 66 66  forcement is off
17be0 20 6f 72 20 6f 6e 0a 2a 2a 20 66 6f 6c 6c 6f 77   or on.** follow
17bf0 69 6e 67 20 74 68 69 73 20 63 61 6c 6c 2e 20 20  ing this call.  
17c00 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  The second param
17c10 65 74 65 72 20 6d 61 79 20 62 65 20 61 20 4e 55  eter may be a NU
17c20 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69 6e 0a 2a  LL pointer, in.*
17c30 2a 20 77 68 69 63 68 20 63 61 73 65 20 74 68 65  * which case the
17c40 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20   FK enforcement 
17c50 73 65 74 74 69 6e 67 20 69 73 20 6e 6f 74 20 72  setting is not r
17c60 65 70 6f 72 74 65 64 20 62 61 63 6b 2e 20 3c 2f  eported back. </
17c70 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51  dd>.**.** <dt>SQ
17c80 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e  LITE_DBCONFIG_EN
17c90 41 42 4c 45 5f 54 52 49 47 47 45 52 3c 2f 64 74  ABLE_TRIGGER</dt
17ca0 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20  >.** <dd> ^This 
17cb0 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64 20 74  option is used t
17cc0 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64 69 73 61  o enable or disa
17cd0 62 6c 65 20 5b 43 52 45 41 54 45 20 54 52 49 47  ble [CREATE TRIG
17ce0 47 45 52 20 7c 20 74 72 69 67 67 65 72 73 5d 2e  GER | triggers].
17cf0 0a 2a 2a 20 54 68 65 72 65 20 73 68 6f 75 6c 64  .** There should
17d00 20 62 65 20 74 77 6f 20 61 64 64 69 74 69 6f 6e   be two addition
17d10 61 6c 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a  al arguments..**
17d20 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   The first argum
17d30 65 6e 74 20 69 73 20 61 6e 20 69 6e 74 65 67 65  ent is an intege
17d40 72 20 77 68 69 63 68 20 69 73 20 30 20 74 6f 20  r which is 0 to 
17d50 64 69 73 61 62 6c 65 20 74 72 69 67 67 65 72 73  disable triggers
17d60 2c 0a 2a 2a 20 70 6f 73 69 74 69 76 65 20 74 6f  ,.** positive to
17d70 20 65 6e 61 62 6c 65 20 74 72 69 67 67 65 72 73   enable triggers
17d80 20 6f 72 20 6e 65 67 61 74 69 76 65 20 74 6f 20   or negative to 
17d90 6c 65 61 76 65 20 74 68 65 20 73 65 74 74 69 6e  leave the settin
17da0 67 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 20  g unchanged..** 
17db0 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  The second param
17dc0 65 74 65 72 20 69 73 20 61 20 70 6f 69 6e 74 65  eter is a pointe
17dd0 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20  r to an integer 
17de0 69 6e 74 6f 20 77 68 69 63 68 0a 2a 2a 20 69 73  into which.** is
17df0 20 77 72 69 74 74 65 6e 20 30 20 6f 72 20 31 20   written 0 or 1 
17e00 74 6f 20 69 6e 64 69 63 61 74 65 20 77 68 65 74  to indicate whet
17e10 68 65 72 20 74 72 69 67 67 65 72 73 20 61 72 65  her triggers are
17e20 20 64 69 73 61 62 6c 65 64 20 6f 72 20 65 6e 61   disabled or ena
17e30 62 6c 65 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e  bled.** followin
17e40 67 20 74 68 69 73 20 63 61 6c 6c 2e 20 20 54 68  g this call.  Th
17e50 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
17e60 65 72 20 6d 61 79 20 62 65 20 61 20 4e 55 4c 4c  er may be a NULL
17e70 20 70 6f 69 6e 74 65 72 2c 20 69 6e 0a 2a 2a 20   pointer, in.** 
17e80 77 68 69 63 68 20 63 61 73 65 20 74 68 65 20 74  which case the t
17e90 72 69 67 67 65 72 20 73 65 74 74 69 6e 67 20 69  rigger setting i
17ea0 73 20 6e 6f 74 20 72 65 70 6f 72 74 65 64 20 62  s not reported b
17eb0 61 63 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  ack. </dd>.**.**
17ec0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f   <dt>SQLITE_DBCO
17ed0 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 46 54 53 33  NFIG_ENABLE_FTS3
17ee0 5f 54 4f 4b 45 4e 49 5a 45 52 3c 2f 64 74 3e 0a  _TOKENIZER</dt>.
17ef0 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70  ** <dd> ^This op
17f00 74 69 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20  tion is used to 
17f10 65 6e 61 62 6c 65 20 6f 72 20 64 69 73 61 62 6c  enable or disabl
17f20 65 20 74 68 65 20 74 77 6f 2d 61 72 67 75 6d 65  e the two-argume
17f30 6e 74 0a 2a 2a 20 76 65 72 73 69 6f 6e 20 6f 66  nt.** version of
17f40 20 74 68 65 20 5b 66 74 73 33 5f 74 6f 6b 65 6e   the [fts3_token
17f50 69 7a 65 72 28 29 5d 20 66 75 6e 63 74 69 6f 6e  izer()] function
17f60 20 77 68 69 63 68 20 69 73 20 70 61 72 74 20 6f   which is part o
17f70 66 20 74 68 65 0a 2a 2a 20 5b 46 54 53 33 5d 20  f the.** [FTS3] 
17f80 66 75 6c 6c 2d 74 65 78 74 20 73 65 61 72 63 68  full-text search
17f90 20 65 6e 67 69 6e 65 20 65 78 74 65 6e 73 69 6f   engine extensio
17fa0 6e 2e 0a 2a 2a 20 54 68 65 72 65 20 73 68 6f 75  n..** There shou
17fb0 6c 64 20 62 65 20 74 77 6f 20 61 64 64 69 74 69  ld be two additi
17fc0 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 2e 0a  onal arguments..
17fd0 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67  ** The first arg
17fe0 75 6d 65 6e 74 20 69 73 20 61 6e 20 69 6e 74 65  ument is an inte
17ff0 67 65 72 20 77 68 69 63 68 20 69 73 20 30 20 74  ger which is 0 t
18000 6f 20 64 69 73 61 62 6c 65 20 66 74 73 33 5f 74  o disable fts3_t
18010 6f 6b 65 6e 69 7a 65 72 28 29 20 6f 72 0a 2a 2a  okenizer() or.**
18020 20 70 6f 73 69 74 69 76 65 20 74 6f 20 65 6e 61   positive to ena
18030 62 6c 65 20 66 74 73 33 5f 74 6f 6b 65 6e 69 7a  ble fts3_tokeniz
18040 65 72 28 29 20 6f 72 20 6e 65 67 61 74 69 76 65  er() or negative
18050 20 74 6f 20 6c 65 61 76 65 20 74 68 65 20 73 65   to leave the se
18060 74 74 69 6e 67 0a 2a 2a 20 75 6e 63 68 61 6e 67  tting.** unchang
18070 65 64 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e  ed..** The secon
18080 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61  d parameter is a
18090 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69   pointer to an i
180a0 6e 74 65 67 65 72 20 69 6e 74 6f 20 77 68 69 63  nteger into whic
180b0 68 0a 2a 2a 20 69 73 20 77 72 69 74 74 65 6e 20  h.** is written 
180c0 30 20 6f 72 20 31 20 74 6f 20 69 6e 64 69 63 61  0 or 1 to indica
180d0 74 65 20 77 68 65 74 68 65 72 20 66 74 73 33 5f  te whether fts3_
180e0 74 6f 6b 65 6e 69 7a 65 72 20 69 73 20 64 69 73  tokenizer is dis
180f0 61 62 6c 65 64 20 6f 72 20 65 6e 61 62 6c 65 64  abled or enabled
18100 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68  .** following th
18110 69 73 20 63 61 6c 6c 2e 20 20 54 68 65 20 73 65  is call.  The se
18120 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6d  cond parameter m
18130 61 79 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69  ay be a NULL poi
18140 6e 74 65 72 2c 20 69 6e 0a 2a 2a 20 77 68 69 63  nter, in.** whic
18150 68 20 63 61 73 65 20 74 68 65 20 6e 65 77 20 73  h case the new s
18160 65 74 74 69 6e 67 20 69 73 20 6e 6f 74 20 72 65  etting is not re
18170 70 6f 72 74 65 64 20 62 61 63 6b 2e 20 3c 2f 64  ported back. </d
18180 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c  d>.**.** <dt>SQL
18190 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41  ITE_DBCONFIG_ENA
181a0 42 4c 45 5f 4c 4f 41 44 5f 45 58 54 45 4e 53 49  BLE_LOAD_EXTENSI
181b0 4f 4e 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  ON</dt>.** <dd> 
181c0 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20  ^This option is 
181d0 75 73 65 64 20 74 6f 20 65 6e 61 62 6c 65 20 6f  used to enable o
181e0 72 20 64 69 73 61 62 6c 65 20 74 68 65 20 5b 73  r disable the [s
181f0 71 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65  qlite3_load_exte
18200 6e 73 69 6f 6e 28 29 5d 0a 2a 2a 20 69 6e 74 65  nsion()].** inte
18210 72 66 61 63 65 20 69 6e 64 65 70 65 6e 64 65 6e  rface independen
18220 74 6c 79 20 6f 66 20 74 68 65 20 5b 6c 6f 61 64  tly of the [load
18230 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d 20 53 51  _extension()] SQ
18240 4c 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 54  L function..** T
18250 68 65 20 5b 73 71 6c 69 74 65 33 5f 65 6e 61 62  he [sqlite3_enab
18260 6c 65 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f  le_load_extensio
18270 6e 28 29 5d 20 41 50 49 20 65 6e 61 62 6c 65 73  n()] API enables
18280 20 6f 72 20 64 69 73 61 62 6c 65 73 20 62 6f 74   or disables bot
18290 68 20 74 68 65 0a 2a 2a 20 43 2d 41 50 49 20 5b  h the.** C-API [
182a0 73 71 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74  sqlite3_load_ext
182b0 65 6e 73 69 6f 6e 28 29 5d 20 61 6e 64 20 74 68  ension()] and th
182c0 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 5b  e SQL function [
182d0 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29  load_extension()
182e0 5d 2e 0a 2a 2a 20 54 68 65 72 65 20 73 68 6f 75  ]..** There shou
182f0 6c 64 20 62 65 20 74 77 6f 20 61 64 64 69 74 69  ld be two additi
18300 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 2e 0a  onal arguments..
18310 2a 2a 20 57 68 65 6e 20 74 68 65 20 66 69 72 73  ** When the firs
18320 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  t argument to th
18330 69 73 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  is interface is 
18340 31 2c 20 74 68 65 6e 20 6f 6e 6c 79 20 74 68 65  1, then only the
18350 20 43 2d 41 50 49 20 69 73 0a 2a 2a 20 65 6e 61   C-API is.** ena
18360 62 6c 65 64 20 61 6e 64 20 74 68 65 20 53 51 4c  bled and the SQL
18370 20 66 75 6e 63 74 69 6f 6e 20 72 65 6d 61 69 6e   function remain
18380 73 20 64 69 73 61 62 6c 65 64 2e 20 20 49 66 20  s disabled.  If 
18390 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
183a0 6e 74 20 74 6f 0a 2a 2a 20 74 68 69 73 20 69 6e  nt to.** this in
183b0 74 65 72 66 61 63 65 20 69 73 20 30 2c 20 74 68  terface is 0, th
183c0 65 6e 20 62 6f 74 68 20 74 68 65 20 43 2d 41 50  en both the C-AP
183d0 49 20 61 6e 64 20 74 68 65 20 53 51 4c 20 66 75  I and the SQL fu
183e0 6e 63 74 69 6f 6e 20 61 72 65 20 64 69 73 61 62  nction are disab
183f0 6c 65 64 2e 0a 2a 2a 20 49 66 20 74 68 65 20 66  led..** If the f
18400 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73  irst argument is
18410 20 2d 31 2c 20 74 68 65 6e 20 6e 6f 20 63 68 61   -1, then no cha
18420 6e 67 65 73 20 61 72 65 20 6d 61 64 65 20 74 6f  nges are made to
18430 20 73 74 61 74 65 20 6f 66 20 65 69 74 68 65 72   state of either
18440 20 74 68 65 0a 2a 2a 20 43 2d 41 50 49 20 6f 72   the.** C-API or
18450 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f   the SQL functio
18460 6e 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64  n..** The second
18470 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20   parameter is a 
18480 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e  pointer to an in
18490 74 65 67 65 72 20 69 6e 74 6f 20 77 68 69 63 68  teger into which
184a0 0a 2a 2a 20 69 73 20 77 72 69 74 74 65 6e 20 30  .** is written 0
184b0 20 6f 72 20 31 20 74 6f 20 69 6e 64 69 63 61 74   or 1 to indicat
184c0 65 20 77 68 65 74 68 65 72 20 5b 73 71 6c 69 74  e whether [sqlit
184d0 65 33 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f  e3_load_extensio
184e0 6e 28 29 5d 20 69 6e 74 65 72 66 61 63 65 0a 2a  n()] interface.*
184f0 2a 20 69 73 20 64 69 73 61 62 6c 65 64 20 6f 72  * is disabled or
18500 20 65 6e 61 62 6c 65 64 20 66 6f 6c 6c 6f 77 69   enabled followi
18510 6e 67 20 74 68 69 73 20 63 61 6c 6c 2e 20 20 54  ng this call.  T
18520 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
18530 74 65 72 20 6d 61 79 0a 2a 2a 20 62 65 20 61 20  ter may.** be a 
18540 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69 6e  NULL pointer, in
18550 20 77 68 69 63 68 20 63 61 73 65 20 74 68 65 20   which case the 
18560 6e 65 77 20 73 65 74 74 69 6e 67 20 69 73 20 6e  new setting is n
18570 6f 74 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b  ot reported back
18580 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  ..** </dd>.**.**
18590 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f   <dt>SQLITE_DBCO
185a0 4e 46 49 47 5f 4d 41 49 4e 44 42 4e 41 4d 45 3c  NFIG_MAINDBNAME<
185b0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68  /dt>.** <dd> ^Th
185c0 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65  is option is use
185d0 64 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65 20  d to change the 
185e0 6e 61 6d 65 20 6f 66 20 74 68 65 20 22 6d 61 69  name of the "mai
185f0 6e 22 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 73  n" database.** s
18600 63 68 65 6d 61 2e 20 20 5e 54 68 65 20 73 6f 6c  chema.  ^The sol
18610 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20  e argument is a 
18620 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 63 6f 6e  pointer to a con
18630 73 74 61 6e 74 20 55 54 46 38 20 73 74 72 69 6e  stant UTF8 strin
18640 67 0a 2a 2a 20 77 68 69 63 68 20 77 69 6c 6c 20  g.** which will 
18650 62 65 63 6f 6d 65 20 74 68 65 20 6e 65 77 20 73  become the new s
18660 63 68 65 6d 61 20 6e 61 6d 65 20 69 6e 20 70 6c  chema name in pl
18670 61 63 65 20 6f 66 20 22 6d 61 69 6e 22 2e 20 20  ace of "main".  
18680 5e 53 51 4c 69 74 65 0a 2a 2a 20 64 6f 65 73 20  ^SQLite.** does 
18690 6e 6f 74 20 6d 61 6b 65 20 61 20 63 6f 70 79 20  not make a copy 
186a0 6f 66 20 74 68 65 20 6e 65 77 20 6d 61 69 6e 20  of the new main 
186b0 73 63 68 65 6d 61 20 6e 61 6d 65 20 73 74 72 69  schema name stri
186c0 6e 67 2c 20 73 6f 20 74 68 65 20 61 70 70 6c 69  ng, so the appli
186d0 63 61 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 65  cation.** must e
186e0 6e 73 75 72 65 20 74 68 61 74 20 74 68 65 20 61  nsure that the a
186f0 72 67 75 6d 65 6e 74 20 70 61 73 73 65 64 20 69  rgument passed i
18700 6e 74 6f 20 74 68 69 73 20 44 42 43 4f 4e 46 49  nto this DBCONFI
18710 47 20 6f 70 74 69 6f 6e 20 69 73 20 75 6e 63 68  G option is unch
18720 61 6e 67 65 64 0a 2a 2a 20 75 6e 74 69 6c 20 61  anged.** until a
18730 66 74 65 72 20 74 68 65 20 64 61 74 61 62 61 73  fter the databas
18740 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f  e connection clo
18750 73 65 73 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a  ses..** </dd>.**
18760 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44  .** <dt>SQLITE_D
18770 42 43 4f 4e 46 49 47 5f 4e 4f 5f 43 4b 50 54 5f  BCONFIG_NO_CKPT_
18780 4f 4e 5f 43 4c 4f 53 45 3c 2f 64 74 3e 0a 2a 2a  ON_CLOSE</dt>.**
18790 20 3c 64 64 3e 20 55 73 75 61 6c 6c 79 2c 20 77   <dd> Usually, w
187a0 68 65 6e 20 61 20 64 61 74 61 62 61 73 65 20 69  hen a database i
187b0 6e 20 77 61 6c 20 6d 6f 64 65 20 69 73 20 63 6c  n wal mode is cl
187c0 6f 73 65 64 20 6f 72 20 64 65 74 61 63 68 65 64  osed or detached
187d0 20 66 72 6f 6d 20 61 20 0a 2a 2a 20 64 61 74 61   from a .** data
187e0 62 61 73 65 20 68 61 6e 64 6c 65 2c 20 53 51 4c  base handle, SQL
187f0 69 74 65 20 63 68 65 63 6b 73 20 69 66 20 74 68  ite checks if th
18800 69 73 20 77 69 6c 6c 20 6d 65 61 6e 20 74 68 61  is will mean tha
18810 74 20 74 68 65 72 65 20 61 72 65 20 6e 6f 77 20  t there are now 
18820 6e 6f 20 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f  no .** connectio
18830 6e 73 20 61 74 20 61 6c 6c 20 74 6f 20 74 68 65  ns at all to the
18840 20 64 61 74 61 62 61 73 65 2e 20 49 66 20 73 6f   database. If so
18850 2c 20 69 74 20 70 65 72 66 6f 72 6d 73 20 61 20  , it performs a 
18860 63 68 65 63 6b 70 6f 69 6e 74 20 0a 2a 2a 20 6f  checkpoint .** o
18870 70 65 72 61 74 69 6f 6e 20 62 65 66 6f 72 65 20  peration before 
18880 63 6c 6f 73 69 6e 67 20 74 68 65 20 63 6f 6e 6e  closing the conn
18890 65 63 74 69 6f 6e 2e 20 54 68 69 73 20 6f 70 74  ection. This opt
188a0 69 6f 6e 20 6d 61 79 20 62 65 20 75 73 65 64 20  ion may be used 
188b0 74 6f 0a 2a 2a 20 6f 76 65 72 72 69 64 65 20 74  to.** override t
188c0 68 69 73 20 62 65 68 61 76 69 6f 75 72 2e 20 54  his behaviour. T
188d0 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
188e0 65 72 20 70 61 73 73 65 64 20 74 6f 20 74 68 69  er passed to thi
188f0 73 20 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 69  s operation.** i
18900 73 20 61 6e 20 69 6e 74 65 67 65 72 20 2d 20 6e  s an integer - n
18910 6f 6e 2d 7a 65 72 6f 20 74 6f 20 64 69 73 61 62  on-zero to disab
18920 6c 65 20 63 68 65 63 6b 70 6f 69 6e 74 73 2d 6f  le checkpoints-o
18930 6e 2d 63 6c 6f 73 65 2c 20 6f 72 20 7a 65 72 6f  n-close, or zero
18940 20 28 74 68 65 0a 2a 2a 20 64 65 66 61 75 6c 74   (the.** default
18950 29 20 74 6f 20 65 6e 61 62 6c 65 20 74 68 65 6d  ) to enable them
18960 2e 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72  . The second par
18970 61 6d 65 74 65 72 20 69 73 20 61 20 70 6f 69 6e  ameter is a poin
18980 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65  ter to an intege
18990 72 0a 2a 2a 20 69 6e 74 6f 20 77 68 69 63 68 20  r.** into which 
189a0 69 73 20 77 72 69 74 74 65 6e 20 30 20 6f 72 20  is written 0 or 
189b0 31 20 74 6f 20 69 6e 64 69 63 61 74 65 20 77 68  1 to indicate wh
189c0 65 74 68 65 72 20 63 68 65 63 6b 70 6f 69 6e 74  ether checkpoint
189d0 73 2d 6f 6e 2d 63 6c 6f 73 65 0a 2a 2a 20 68 61  s-on-close.** ha
189e0 76 65 20 62 65 65 6e 20 64 69 73 61 62 6c 65 64  ve been disabled
189f0 20 2d 20 30 20 69 66 20 74 68 65 79 20 61 72 65   - 0 if they are
18a00 20 6e 6f 74 20 64 69 73 61 62 6c 65 64 2c 20 31   not disabled, 1
18a10 20 69 66 20 74 68 65 79 20 61 72 65 2e 0a 2a 2a   if they are..**
18a20 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 2f 64   </dd>.**.** </d
18a30 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  l>.*/.#define SQ
18a40 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4d 41  LITE_DBCONFIG_MA
18a50 49 4e 44 42 4e 41 4d 45 20 20 20 20 20 20 20 20  INDBNAME        
18a60 20 20 20 20 31 30 30 30 20 2f 2a 20 63 6f 6e 73      1000 /* cons
18a70 74 20 63 68 61 72 2a 20 2a 2f 0a 23 64 65 66 69  t char* */.#defi
18a80 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46  ne SQLITE_DBCONF
18a90 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 20 20 20  IG_LOOKASIDE    
18aa0 20 20 20 20 20 20 20 20 20 31 30 30 31 20 2f 2a           1001 /*
18ab0 20 76 6f 69 64 2a 20 69 6e 74 20 69 6e 74 20 2a   void* int int *
18ac0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
18ad0 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45  _DBCONFIG_ENABLE
18ae0 5f 46 4b 45 59 20 20 20 20 20 20 20 20 20 20 20  _FKEY           
18af0 31 30 30 32 20 2f 2a 20 69 6e 74 20 69 6e 74 2a  1002 /* int int*
18b00 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
18b10 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42  TE_DBCONFIG_ENAB
18b20 4c 45 5f 54 52 49 47 47 45 52 20 20 20 20 20 20  LE_TRIGGER      
18b30 20 20 31 30 30 33 20 2f 2a 20 69 6e 74 20 69 6e    1003 /* int in
18b40 74 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  t* */.#define SQ
18b50 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e  LITE_DBCONFIG_EN
18b60 41 42 4c 45 5f 46 54 53 33 5f 54 4f 4b 45 4e 49  ABLE_FTS3_TOKENI
18b70 5a 45 52 20 31 30 30 34 20 2f 2a 20 69 6e 74 20  ZER 1004 /* int 
18b80 69 6e 74 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20  int* */.#define 
18b90 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
18ba0 45 4e 41 42 4c 45 5f 4c 4f 41 44 5f 45 58 54 45  ENABLE_LOAD_EXTE
18bb0 4e 53 49 4f 4e 20 31 30 30 35 20 2f 2a 20 69 6e  NSION 1005 /* in
18bc0 74 20 69 6e 74 2a 20 2a 2f 0a 23 64 65 66 69 6e  t int* */.#defin
18bd0 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49  e SQLITE_DBCONFI
18be0 47 5f 4e 4f 5f 43 4b 50 54 5f 4f 4e 5f 43 4c 4f  G_NO_CKPT_ON_CLO
18bf0 53 45 20 20 20 20 20 20 31 30 30 36 20 2f 2a 20  SE      1006 /* 
18c00 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 0a 0a 2f 2a  int int* */.../*
18c10 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 6e  .** CAPI3REF: En
18c20 61 62 6c 65 20 4f 72 20 44 69 73 61 62 6c 65 20  able Or Disable 
18c30 45 78 74 65 6e 64 65 64 20 52 65 73 75 6c 74 20  Extended Result 
18c40 43 6f 64 65 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a  Codes.** METHOD:
18c50 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e   sqlite3.**.** ^
18c60 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 74 65  The sqlite3_exte
18c70 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65  nded_result_code
18c80 73 28 29 20 72 6f 75 74 69 6e 65 20 65 6e 61 62  s() routine enab
18c90 6c 65 73 20 6f 72 20 64 69 73 61 62 6c 65 73 20  les or disables 
18ca0 74 68 65 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64  the.** [extended
18cb0 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 66   result codes] f
18cc0 65 61 74 75 72 65 20 6f 66 20 53 51 4c 69 74 65  eature of SQLite
18cd0 2e 20 5e 54 68 65 20 65 78 74 65 6e 64 65 64 20  . ^The extended 
18ce0 72 65 73 75 6c 74 0a 2a 2a 20 63 6f 64 65 73 20  result.** codes 
18cf0 61 72 65 20 64 69 73 61 62 6c 65 64 20 62 79 20  are disabled by 
18d00 64 65 66 61 75 6c 74 20 66 6f 72 20 68 69 73 74  default for hist
18d10 6f 72 69 63 61 6c 20 63 6f 6d 70 61 74 69 62 69  orical compatibi
18d20 6c 69 74 79 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  lity..*/.int sql
18d30 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65  ite3_extended_re
18d40 73 75 6c 74 5f 63 6f 64 65 73 28 73 71 6c 69 74  sult_codes(sqlit
18d50 65 33 2a 2c 20 69 6e 74 20 6f 6e 6f 66 66 29 3b  e3*, int onoff);
18d60 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
18d70 3a 20 4c 61 73 74 20 49 6e 73 65 72 74 20 52 6f  : Last Insert Ro
18d80 77 69 64 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  wid.** METHOD: s
18d90 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 45 61  qlite3.**.** ^Ea
18da0 63 68 20 65 6e 74 72 79 20 69 6e 20 6d 6f 73 74  ch entry in most
18db0 20 53 51 4c 69 74 65 20 74 61 62 6c 65 73 20 28   SQLite tables (
18dc0 65 78 63 65 70 74 20 66 6f 72 20 5b 57 49 54 48  except for [WITH
18dd0 4f 55 54 20 52 4f 57 49 44 5d 20 74 61 62 6c 65  OUT ROWID] table
18de0 73 29 0a 2a 2a 20 68 61 73 20 61 20 75 6e 69 71  s).** has a uniq
18df0 75 65 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64  ue 64-bit signed
18e00 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6b 65 79 20  .** integer key 
18e10 63 61 6c 6c 65 64 20 74 68 65 20 5b 52 4f 57 49  called the [ROWI
18e20 44 20 7c 20 22 72 6f 77 69 64 22 5d 2e 20 5e 54  D | "rowid"]. ^T
18e30 68 65 20 72 6f 77 69 64 20 69 73 20 61 6c 77 61  he rowid is alwa
18e40 79 73 20 61 76 61 69 6c 61 62 6c 65 0a 2a 2a 20  ys available.** 
18e50 61 73 20 61 6e 20 75 6e 64 65 63 6c 61 72 65 64  as an undeclared
18e60 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 64 20 52 4f   column named RO
18e70 57 49 44 2c 20 4f 49 44 2c 20 6f 72 20 5f 52 4f  WID, OID, or _RO
18e80 57 49 44 5f 20 61 73 20 6c 6f 6e 67 20 61 73 20  WID_ as long as 
18e90 74 68 6f 73 65 0a 2a 2a 20 6e 61 6d 65 73 20 61  those.** names a
18ea0 72 65 20 6e 6f 74 20 61 6c 73 6f 20 75 73 65 64  re not also used
18eb0 20 62 79 20 65 78 70 6c 69 63 69 74 6c 79 20 64   by explicitly d
18ec0 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 73 2e  eclared columns.
18ed0 20 5e 49 66 0a 2a 2a 20 74 68 65 20 74 61 62 6c   ^If.** the tabl
18ee0 65 20 68 61 73 20 61 20 63 6f 6c 75 6d 6e 20 6f  e has a column o
18ef0 66 20 74 79 70 65 20 5b 49 4e 54 45 47 45 52 20  f type [INTEGER 
18f00 50 52 49 4d 41 52 59 20 4b 45 59 5d 20 74 68 65  PRIMARY KEY] the
18f10 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e 0a 2a 2a  n that column.**
18f20 20 69 73 20 61 6e 6f 74 68 65 72 20 61 6c 69 61   is another alia
18f30 73 20 66 6f 72 20 74 68 65 20 72 6f 77 69 64 2e  s for the rowid.
18f40 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
18f50 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f  te3_last_insert_
18f60 72 6f 77 69 64 28 44 29 20 69 6e 74 65 72 66 61  rowid(D) interfa
18f70 63 65 20 75 73 75 61 6c 6c 79 20 72 65 74 75 72  ce usually retur
18f80 6e 73 20 74 68 65 20 5b 72 6f 77 69 64 5d 20 6f  ns the [rowid] o
18f90 66 0a 2a 2a 20 74 68 65 20 6d 6f 73 74 20 72 65  f.** the most re
18fa0 63 65 6e 74 20 73 75 63 63 65 73 73 66 75 6c 20  cent successful 
18fb0 5b 49 4e 53 45 52 54 5d 20 69 6e 74 6f 20 61 20  [INSERT] into a 
18fc0 72 6f 77 69 64 20 74 61 62 6c 65 20 6f 72 20 5b  rowid table or [
18fd0 76 69 72 74 75 61 6c 20 74 61 62 6c 65 5d 0a 2a  virtual table].*
18fe0 2a 20 6f 6e 20 64 61 74 61 62 61 73 65 20 63 6f  * on database co
18ff0 6e 6e 65 63 74 69 6f 6e 20 44 2e 20 5e 49 6e 73  nnection D. ^Ins
19000 65 72 74 73 20 69 6e 74 6f 20 5b 57 49 54 48 4f  erts into [WITHO
19010 55 54 20 52 4f 57 49 44 5d 20 74 61 62 6c 65 73  UT ROWID] tables
19020 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 72 65 63 6f   are not.** reco
19030 72 64 65 64 2e 20 5e 49 66 20 6e 6f 20 73 75 63  rded. ^If no suc
19040 63 65 73 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d  cessful [INSERT]
19050 73 20 69 6e 74 6f 20 72 6f 77 69 64 20 74 61 62  s into rowid tab
19060 6c 65 73 20 68 61 76 65 20 65 76 65 72 20 6f 63  les have ever oc
19070 63 75 72 72 65 64 20 0a 2a 2a 20 6f 6e 20 74 68  curred .** on th
19080 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
19090 63 74 69 6f 6e 20 44 2c 20 74 68 65 6e 20 73 71  ction D, then sq
190a0 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72  lite3_last_inser
190b0 74 5f 72 6f 77 69 64 28 44 29 20 72 65 74 75 72  t_rowid(D) retur
190c0 6e 73 20 0a 2a 2a 20 7a 65 72 6f 2e 0a 2a 2a 0a  ns .** zero..**.
190d0 2a 2a 20 41 73 20 77 65 6c 6c 20 61 73 20 62 65  ** As well as be
190e0 69 6e 67 20 73 65 74 20 61 75 74 6f 6d 61 74 69  ing set automati
190f0 63 61 6c 6c 79 20 61 73 20 72 6f 77 73 20 61 72  cally as rows ar
19100 65 20 69 6e 73 65 72 74 65 64 20 69 6e 74 6f 20  e inserted into 
19110 64 61 74 61 62 61 73 65 0a 2a 2a 20 74 61 62 6c  database.** tabl
19120 65 73 2c 20 74 68 65 20 76 61 6c 75 65 20 72 65  es, the value re
19130 74 75 72 6e 65 64 20 62 79 20 74 68 69 73 20 66  turned by this f
19140 75 6e 63 74 69 6f 6e 20 6d 61 79 20 62 65 20 73  unction may be s
19150 65 74 20 65 78 70 6c 69 63 69 74 6c 79 20 62 79  et explicitly by
19160 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 65 74  .** [sqlite3_set
19170 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77  _last_insert_row
19180 69 64 28 29 5d 0a 2a 2a 0a 2a 2a 20 53 6f 6d 65  id()].**.** Some
19190 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 69   virtual table i
191a0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6d  mplementations m
191b0 61 79 20 49 4e 53 45 52 54 20 72 6f 77 73 20 69  ay INSERT rows i
191c0 6e 74 6f 20 72 6f 77 69 64 20 74 61 62 6c 65 73  nto rowid tables
191d0 20 61 73 0a 2a 2a 20 70 61 72 74 20 6f 66 20 63   as.** part of c
191e0 6f 6d 6d 69 74 74 69 6e 67 20 61 20 74 72 61 6e  ommitting a tran
191f0 73 61 63 74 69 6f 6e 20 28 65 2e 67 2e 20 74 6f  saction (e.g. to
19200 20 66 6c 75 73 68 20 64 61 74 61 20 61 63 63 75   flush data accu
19210 6d 75 6c 61 74 65 64 20 69 6e 20 6d 65 6d 6f 72  mulated in memor
19220 79 0a 2a 2a 20 74 6f 20 64 69 73 6b 29 2e 20 49  y.** to disk). I
19230 6e 20 74 68 69 73 20 63 61 73 65 20 73 75 62 73  n this case subs
19240 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20  equent calls to 
19250 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65  this function re
19260 74 75 72 6e 20 74 68 65 20 72 6f 77 69 64 0a 2a  turn the rowid.*
19270 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74  * associated wit
19280 68 20 74 68 65 73 65 20 69 6e 74 65 72 6e 61 6c  h these internal
19290 20 49 4e 53 45 52 54 20 6f 70 65 72 61 74 69 6f   INSERT operatio
192a0 6e 73 2c 20 77 68 69 63 68 20 6c 65 61 64 73 20  ns, which leads 
192b0 74 6f 20 0a 2a 2a 20 75 6e 69 6e 74 75 69 74 69  to .** unintuiti
192c0 76 65 20 72 65 73 75 6c 74 73 2e 20 56 69 72 74  ve results. Virt
192d0 75 61 6c 20 74 61 62 6c 65 20 69 6d 70 6c 65 6d  ual table implem
192e0 65 6e 74 61 74 69 6f 6e 73 20 74 68 61 74 20 64  entations that d
192f0 6f 20 77 72 69 74 65 20 74 6f 20 72 6f 77 69 64  o write to rowid
19300 0a 2a 2a 20 74 61 62 6c 65 73 20 69 6e 20 74 68  .** tables in th
19310 69 73 20 77 61 79 20 63 61 6e 20 61 76 6f 69 64  is way can avoid
19320 20 74 68 69 73 20 70 72 6f 62 6c 65 6d 20 62 79   this problem by
19330 20 72 65 73 74 6f 72 69 6e 67 20 74 68 65 20 6f   restoring the o
19340 72 69 67 69 6e 61 6c 20 0a 2a 2a 20 72 6f 77 69  riginal .** rowi
19350 64 20 76 61 6c 75 65 20 75 73 69 6e 67 20 5b 73  d value using [s
19360 71 6c 69 74 65 33 5f 73 65 74 5f 6c 61 73 74 5f  qlite3_set_last_
19370 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 5d 20  insert_rowid()] 
19380 62 65 66 6f 72 65 20 72 65 74 75 72 6e 69 6e 67  before returning
19390 20 0a 2a 2a 20 63 6f 6e 74 72 6f 6c 20 74 6f 20   .** control to 
193a0 74 68 65 20 75 73 65 72 2e 0a 2a 2a 0a 2a 2a 20  the user..**.** 
193b0 5e 28 49 66 20 61 6e 20 5b 49 4e 53 45 52 54 5d  ^(If an [INSERT]
193c0 20 6f 63 63 75 72 73 20 77 69 74 68 69 6e 20 61   occurs within a
193d0 20 74 72 69 67 67 65 72 20 74 68 65 6e 20 74 68   trigger then th
193e0 69 73 20 72 6f 75 74 69 6e 65 20 77 69 6c 6c 20  is routine will 
193f0 0a 2a 2a 20 72 65 74 75 72 6e 20 74 68 65 20 5b  .** return the [
19400 72 6f 77 69 64 5d 20 6f 66 20 74 68 65 20 69 6e  rowid] of the in
19410 73 65 72 74 65 64 20 72 6f 77 20 61 73 20 6c 6f  serted row as lo
19420 6e 67 20 61 73 20 74 68 65 20 74 72 69 67 67 65  ng as the trigge
19430 72 20 69 73 20 0a 2a 2a 20 72 75 6e 6e 69 6e 67  r is .** running
19440 2e 20 4f 6e 63 65 20 74 68 65 20 74 72 69 67 67  . Once the trigg
19450 65 72 20 70 72 6f 67 72 61 6d 20 65 6e 64 73 2c  er program ends,
19460 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72   the value retur
19470 6e 65 64 20 0a 2a 2a 20 62 79 20 74 68 69 73 20  ned .** by this 
19480 72 6f 75 74 69 6e 65 20 72 65 76 65 72 74 73 20  routine reverts 
19490 74 6f 20 77 68 61 74 20 69 74 20 77 61 73 20 62  to what it was b
194a0 65 66 6f 72 65 20 74 68 65 20 74 72 69 67 67 65  efore the trigge
194b0 72 20 77 61 73 20 66 69 72 65 64 2e 29 5e 0a 2a  r was fired.)^.*
194c0 2a 0a 2a 2a 20 5e 41 6e 20 5b 49 4e 53 45 52 54  *.** ^An [INSERT
194d0 5d 20 74 68 61 74 20 66 61 69 6c 73 20 64 75 65  ] that fails due
194e0 20 74 6f 20 61 20 63 6f 6e 73 74 72 61 69 6e 74   to a constraint
194f0 20 76 69 6f 6c 61 74 69 6f 6e 20 69 73 20 6e 6f   violation is no
19500 74 20 61 0a 2a 2a 20 73 75 63 63 65 73 73 66 75  t a.** successfu
19510 6c 20 5b 49 4e 53 45 52 54 5d 20 61 6e 64 20 64  l [INSERT] and d
19520 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 74  oes not change t
19530 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65  he value returne
19540 64 20 62 79 20 74 68 69 73 0a 2a 2a 20 72 6f 75  d by this.** rou
19550 74 69 6e 65 2e 20 20 5e 54 68 75 73 20 49 4e 53  tine.  ^Thus INS
19560 45 52 54 20 4f 52 20 46 41 49 4c 2c 20 49 4e 53  ERT OR FAIL, INS
19570 45 52 54 20 4f 52 20 49 47 4e 4f 52 45 2c 20 49  ERT OR IGNORE, I
19580 4e 53 45 52 54 20 4f 52 20 52 4f 4c 4c 42 41 43  NSERT OR ROLLBAC
19590 4b 2c 0a 2a 2a 20 61 6e 64 20 49 4e 53 45 52 54  K,.** and INSERT
195a0 20 4f 52 20 41 42 4f 52 54 20 6d 61 6b 65 20 6e   OR ABORT make n
195b0 6f 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65  o changes to the
195c0 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66   return value of
195d0 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65   this.** routine
195e0 20 77 68 65 6e 20 74 68 65 69 72 20 69 6e 73 65   when their inse
195f0 72 74 69 6f 6e 20 66 61 69 6c 73 2e 20 20 5e 28  rtion fails.  ^(
19600 57 68 65 6e 20 49 4e 53 45 52 54 20 4f 52 20 52  When INSERT OR R
19610 45 50 4c 41 43 45 0a 2a 2a 20 65 6e 63 6f 75 6e  EPLACE.** encoun
19620 74 65 72 73 20 61 20 63 6f 6e 73 74 72 61 69 6e  ters a constrain
19630 74 20 76 69 6f 6c 61 74 69 6f 6e 2c 20 69 74 20  t violation, it 
19640 64 6f 65 73 20 6e 6f 74 20 66 61 69 6c 2e 20 20  does not fail.  
19650 54 68 65 0a 2a 2a 20 49 4e 53 45 52 54 20 63 6f  The.** INSERT co
19660 6e 74 69 6e 75 65 73 20 74 6f 20 63 6f 6d 70 6c  ntinues to compl
19670 65 74 69 6f 6e 20 61 66 74 65 72 20 64 65 6c 65  etion after dele
19680 74 69 6e 67 20 72 6f 77 73 20 74 68 61 74 20 63  ting rows that c
19690 61 75 73 65 64 0a 2a 2a 20 74 68 65 20 63 6f 6e  aused.** the con
196a0 73 74 72 61 69 6e 74 20 70 72 6f 62 6c 65 6d 20  straint problem 
196b0 73 6f 20 49 4e 53 45 52 54 20 4f 52 20 52 45 50  so INSERT OR REP
196c0 4c 41 43 45 20 77 69 6c 6c 20 61 6c 77 61 79 73  LACE will always
196d0 20 63 68 61 6e 67 65 0a 2a 2a 20 74 68 65 20 72   change.** the r
196e0 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74  eturn value of t
196f0 68 69 73 20 69 6e 74 65 72 66 61 63 65 2e 29 5e  his interface.)^
19700 0a 2a 2a 0a 2a 2a 20 5e 46 6f 72 20 74 68 65 20  .**.** ^For the 
19710 70 75 72 70 6f 73 65 73 20 6f 66 20 74 68 69 73  purposes of this
19720 20 72 6f 75 74 69 6e 65 2c 20 61 6e 20 5b 49 4e   routine, an [IN
19730 53 45 52 54 5d 20 69 73 20 63 6f 6e 73 69 64 65  SERT] is conside
19740 72 65 64 20 74 6f 0a 2a 2a 20 62 65 20 73 75 63  red to.** be suc
19750 63 65 73 73 66 75 6c 20 65 76 65 6e 20 69 66 20  cessful even if 
19760 69 74 20 69 73 20 73 75 62 73 65 71 75 65 6e 74  it is subsequent
19770 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a  ly rolled back..
19780 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 74  **.** This funct
19790 69 6f 6e 20 69 73 20 61 63 63 65 73 73 69 62 6c  ion is accessibl
197a0 65 20 74 6f 20 53 51 4c 20 73 74 61 74 65 6d 65  e to SQL stateme
197b0 6e 74 73 20 76 69 61 20 74 68 65 0a 2a 2a 20 5b  nts via the.** [
197c0 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69  last_insert_rowi
197d0 64 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  d() SQL function
197e0 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65  ]..**.** If a se
197f0 70 61 72 61 74 65 20 74 68 72 65 61 64 20 70 65  parate thread pe
19800 72 66 6f 72 6d 73 20 61 20 6e 65 77 20 5b 49 4e  rforms a new [IN
19810 53 45 52 54 5d 20 6f 6e 20 74 68 65 20 73 61 6d  SERT] on the sam
19820 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f  e.** database co
19830 6e 6e 65 63 74 69 6f 6e 20 77 68 69 6c 65 20 74  nnection while t
19840 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74  he [sqlite3_last
19850 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 5d  _insert_rowid()]
19860 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  .** function is 
19870 72 75 6e 6e 69 6e 67 20 61 6e 64 20 74 68 75 73  running and thus
19880 20 63 68 61 6e 67 65 73 20 74 68 65 20 6c 61 73   changes the las
19890 74 20 69 6e 73 65 72 74 20 5b 72 6f 77 69 64 5d  t insert [rowid]
198a0 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 76 61  ,.** then the va
198b0 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20  lue returned by 
198c0 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e  [sqlite3_last_in
198d0 73 65 72 74 5f 72 6f 77 69 64 28 29 5d 20 69 73  sert_rowid()] is
198e0 0a 2a 2a 20 75 6e 70 72 65 64 69 63 74 61 62 6c  .** unpredictabl
198f0 65 20 61 6e 64 20 6d 69 67 68 74 20 6e 6f 74 20  e and might not 
19900 65 71 75 61 6c 20 65 69 74 68 65 72 20 74 68 65  equal either the
19910 20 6f 6c 64 20 6f 72 20 74 68 65 20 6e 65 77 0a   old or the new.
19920 2a 2a 20 6c 61 73 74 20 69 6e 73 65 72 74 20 5b  ** last insert [
19930 72 6f 77 69 64 5d 2e 0a 2a 2f 0a 73 71 6c 69 74  rowid]..*/.sqlit
19940 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33  e3_int64 sqlite3
19950 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77  _last_insert_row
19960 69 64 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f  id(sqlite3*);../
19970 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53  *.** CAPI3REF: S
19980 65 74 20 74 68 65 20 4c 61 73 74 20 49 6e 73 65  et the Last Inse
19990 72 74 20 52 6f 77 69 64 20 76 61 6c 75 65 2e 0a  rt Rowid value..
199a0 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
199b0 65 33 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  e3.**.** The sql
199c0 69 74 65 33 5f 73 65 74 5f 6c 61 73 74 5f 69 6e  ite3_set_last_in
199d0 73 65 72 74 5f 72 6f 77 69 64 28 44 2c 20 52 29  sert_rowid(D, R)
199e0 20 6d 65 74 68 6f 64 20 61 6c 6c 6f 77 73 20 74   method allows t
199f0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74  he application t
19a00 6f 0a 2a 2a 20 73 65 74 20 74 68 65 20 76 61 6c  o.** set the val
19a10 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 63  ue returned by c
19a20 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 6c  alling sqlite3_l
19a30 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64  ast_insert_rowid
19a40 28 44 29 20 74 6f 20 52 20 0a 2a 2a 20 77 69 74  (D) to R .** wit
19a50 68 6f 75 74 20 69 6e 73 65 72 74 69 6e 67 20 61  hout inserting a
19a60 20 72 6f 77 20 69 6e 74 6f 20 74 68 65 20 64 61   row into the da
19a70 74 61 62 61 73 65 2e 0a 2a 2f 0a 76 6f 69 64 20  tabase..*/.void 
19a80 73 71 6c 69 74 65 33 5f 73 65 74 5f 6c 61 73 74  sqlite3_set_last
19a90 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 73 71  _insert_rowid(sq
19aa0 6c 69 74 65 33 2a 2c 73 71 6c 69 74 65 33 5f 69  lite3*,sqlite3_i
19ab0 6e 74 36 34 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  nt64);../*.** CA
19ac0 50 49 33 52 45 46 3a 20 43 6f 75 6e 74 20 54 68  PI3REF: Count Th
19ad0 65 20 4e 75 6d 62 65 72 20 4f 66 20 52 6f 77 73  e Number Of Rows
19ae0 20 4d 6f 64 69 66 69 65 64 0a 2a 2a 20 4d 45 54   Modified.** MET
19af0 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a  HOD: sqlite3.**.
19b00 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f  ** ^This functio
19b10 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75  n returns the nu
19b20 6d 62 65 72 20 6f 66 20 72 6f 77 73 20 6d 6f 64  mber of rows mod
19b30 69 66 69 65 64 2c 20 69 6e 73 65 72 74 65 64 20  ified, inserted 
19b40 6f 72 0a 2a 2a 20 64 65 6c 65 74 65 64 20 62 79  or.** deleted by
19b50 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
19b60 6c 79 20 63 6f 6d 70 6c 65 74 65 64 20 49 4e 53  ly completed INS
19b70 45 52 54 2c 20 55 50 44 41 54 45 20 6f 72 20 44  ERT, UPDATE or D
19b80 45 4c 45 54 45 0a 2a 2a 20 73 74 61 74 65 6d 65  ELETE.** stateme
19b90 6e 74 20 6f 6e 20 74 68 65 20 64 61 74 61 62 61  nt on the databa
19ba0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 70  se connection sp
19bb0 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20 6f  ecified by the o
19bc0 6e 6c 79 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a  nly parameter..*
19bd0 2a 20 5e 45 78 65 63 75 74 69 6e 67 20 61 6e 79  * ^Executing any
19be0 20 6f 74 68 65 72 20 74 79 70 65 20 6f 66 20 53   other type of S
19bf0 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 64 6f 65  QL statement doe
19c00 73 20 6e 6f 74 20 6d 6f 64 69 66 79 20 74 68 65  s not modify the
19c10 20 76 61 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e   value.** return
19c20 65 64 20 62 79 20 74 68 69 73 20 66 75 6e 63 74  ed by this funct
19c30 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 6c 79  ion..**.** ^Only
19c40 20 63 68 61 6e 67 65 73 20 6d 61 64 65 20 64 69   changes made di
19c50 72 65 63 74 6c 79 20 62 79 20 74 68 65 20 49 4e  rectly by the IN
19c60 53 45 52 54 2c 20 55 50 44 41 54 45 20 6f 72 20  SERT, UPDATE or 
19c70 44 45 4c 45 54 45 20 73 74 61 74 65 6d 65 6e 74  DELETE statement
19c80 20 61 72 65 0a 2a 2a 20 63 6f 6e 73 69 64 65 72   are.** consider
19c90 65 64 20 2d 20 61 75 78 69 6c 69 61 72 79 20 63  ed - auxiliary c
19ca0 68 61 6e 67 65 73 20 63 61 75 73 65 64 20 62 79  hanges caused by
19cb0 20 5b 43 52 45 41 54 45 20 54 52 49 47 47 45 52   [CREATE TRIGGER
19cc0 20 7c 20 74 72 69 67 67 65 72 73 5d 2c 20 0a 2a   | triggers], .*
19cd0 2a 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20 61  * [foreign key a
19ce0 63 74 69 6f 6e 73 5d 20 6f 72 20 5b 52 45 50 4c  ctions] or [REPL
19cf0 41 43 45 5d 20 63 6f 6e 73 74 72 61 69 6e 74 20  ACE] constraint 
19d00 72 65 73 6f 6c 75 74 69 6f 6e 20 61 72 65 20 6e  resolution are n
19d10 6f 74 20 63 6f 75 6e 74 65 64 2e 0a 2a 2a 20 0a  ot counted..** .
19d20 2a 2a 20 43 68 61 6e 67 65 73 20 74 6f 20 61 20  ** Changes to a 
19d30 76 69 65 77 20 74 68 61 74 20 61 72 65 20 69 6e  view that are in
19d40 74 65 72 63 65 70 74 65 64 20 62 79 20 0a 2a 2a  tercepted by .**
19d50 20 5b 49 4e 53 54 45 41 44 20 4f 46 20 74 72 69   [INSTEAD OF tri
19d60 67 67 65 72 20 7c 20 49 4e 53 54 45 41 44 20 4f  gger | INSTEAD O
19d70 46 20 74 72 69 67 67 65 72 73 5d 20 61 72 65 20  F triggers] are 
19d80 6e 6f 74 20 63 6f 75 6e 74 65 64 2e 20 5e 54 68  not counted. ^Th
19d90 65 20 76 61 6c 75 65 20 0a 2a 2a 20 72 65 74 75  e value .** retu
19da0 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  rned by sqlite3_
19db0 63 68 61 6e 67 65 73 28 29 20 69 6d 6d 65 64 69  changes() immedi
19dc0 61 74 65 6c 79 20 61 66 74 65 72 20 61 6e 20 49  ately after an I
19dd0 4e 53 45 52 54 2c 20 55 50 44 41 54 45 20 6f 72  NSERT, UPDATE or
19de0 20 0a 2a 2a 20 44 45 4c 45 54 45 20 73 74 61 74   .** DELETE stat
19df0 65 6d 65 6e 74 20 72 75 6e 20 6f 6e 20 61 20 76  ement run on a v
19e00 69 65 77 20 69 73 20 61 6c 77 61 79 73 20 7a 65  iew is always ze
19e10 72 6f 2e 20 4f 6e 6c 79 20 63 68 61 6e 67 65 73  ro. Only changes
19e20 20 6d 61 64 65 20 74 6f 20 72 65 61 6c 20 0a 2a   made to real .*
19e30 2a 20 74 61 62 6c 65 73 20 61 72 65 20 63 6f 75  * tables are cou
19e40 6e 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 6e  nted..**.** Thin
19e50 67 73 20 61 72 65 20 6d 6f 72 65 20 63 6f 6d 70  gs are more comp
19e60 6c 69 63 61 74 65 64 20 69 66 20 74 68 65 20 73  licated if the s
19e70 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29  qlite3_changes()
19e80 20 66 75 6e 63 74 69 6f 6e 20 69 73 0a 2a 2a 20   function is.** 
19e90 65 78 65 63 75 74 65 64 20 77 68 69 6c 65 20 61  executed while a
19ea0 20 74 72 69 67 67 65 72 20 70 72 6f 67 72 61 6d   trigger program
19eb0 20 69 73 20 72 75 6e 6e 69 6e 67 2e 20 54 68 69   is running. Thi
19ec0 73 20 6d 61 79 20 68 61 70 70 65 6e 20 69 66 20  s may happen if 
19ed0 74 68 65 0a 2a 2a 20 70 72 6f 67 72 61 6d 20 75  the.** program u
19ee0 73 65 73 20 74 68 65 20 5b 63 68 61 6e 67 65 73  ses the [changes
19ef0 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d  () SQL function]
19f00 2c 20 6f 72 20 69 66 20 73 6f 6d 65 20 6f 74 68  , or if some oth
19f10 65 72 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66  er callback.** f
19f20 75 6e 63 74 69 6f 6e 20 69 6e 76 6f 6b 65 73 20  unction invokes 
19f30 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28  sqlite3_changes(
19f40 29 20 64 69 72 65 63 74 6c 79 2e 20 45 73 73 65  ) directly. Esse
19f50 6e 74 69 61 6c 6c 79 3a 0a 2a 2a 20 0a 2a 2a 20  ntially:.** .** 
19f60 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5e  <ul>.**   <li> ^
19f70 28 42 65 66 6f 72 65 20 65 6e 74 65 72 69 6e 67  (Before entering
19f80 20 61 20 74 72 69 67 67 65 72 20 70 72 6f 67 72   a trigger progr
19f90 61 6d 20 74 68 65 20 76 61 6c 75 65 20 72 65 74  am the value ret
19fa0 75 72 6e 65 64 20 62 79 0a 2a 2a 20 20 20 20 20  urned by.**     
19fb0 20 20 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67     sqlite3_chang
19fc0 65 73 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73  es() function is
19fd0 20 73 61 76 65 64 2e 20 41 66 74 65 72 20 74 68   saved. After th
19fe0 65 20 74 72 69 67 67 65 72 20 70 72 6f 67 72 61  e trigger progra
19ff0 6d 20 0a 2a 2a 20 20 20 20 20 20 20 20 68 61 73  m .**        has
1a000 20 66 69 6e 69 73 68 65 64 2c 20 74 68 65 20 6f   finished, the o
1a010 72 69 67 69 6e 61 6c 20 76 61 6c 75 65 20 69 73  riginal value is
1a020 20 72 65 73 74 6f 72 65 64 2e 29 5e 0a 2a 2a 20   restored.)^.** 
1a030 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5e 28 57 69 74  .**   <li> ^(Wit
1a040 68 69 6e 20 61 20 74 72 69 67 67 65 72 20 70 72  hin a trigger pr
1a050 6f 67 72 61 6d 20 65 61 63 68 20 49 4e 53 45 52  ogram each INSER
1a060 54 2c 20 55 50 44 41 54 45 20 61 6e 64 20 44 45  T, UPDATE and DE
1a070 4c 45 54 45 20 0a 2a 2a 20 20 20 20 20 20 20 20  LETE .**        
1a080 73 74 61 74 65 6d 65 6e 74 20 73 65 74 73 20 74  statement sets t
1a090 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65  he value returne
1a0a0 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 68 61  d by sqlite3_cha
1a0b0 6e 67 65 73 28 29 20 0a 2a 2a 20 20 20 20 20 20  nges() .**      
1a0c0 20 20 75 70 6f 6e 20 63 6f 6d 70 6c 65 74 69 6f    upon completio
1a0d0 6e 20 61 73 20 6e 6f 72 6d 61 6c 2e 20 4f 66 20  n as normal. Of 
1a0e0 63 6f 75 72 73 65 2c 20 74 68 69 73 20 76 61 6c  course, this val
1a0f0 75 65 20 77 69 6c 6c 20 6e 6f 74 20 69 6e 63 6c  ue will not incl
1a100 75 64 65 20 0a 2a 2a 20 20 20 20 20 20 20 20 61  ude .**        a
1a110 6e 79 20 63 68 61 6e 67 65 73 20 70 65 72 66 6f  ny changes perfo
1a120 72 6d 65 64 20 62 79 20 73 75 62 2d 74 72 69 67  rmed by sub-trig
1a130 67 65 72 73 2c 20 61 73 20 74 68 65 20 73 71 6c  gers, as the sql
1a140 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20 0a  ite3_changes() .
1a150 2a 2a 20 20 20 20 20 20 20 20 76 61 6c 75 65 20  **        value 
1a160 77 69 6c 6c 20 62 65 20 73 61 76 65 64 20 61 6e  will be saved an
1a170 64 20 72 65 73 74 6f 72 65 64 20 61 66 74 65 72  d restored after
1a180 20 65 61 63 68 20 73 75 62 2d 74 72 69 67 67 65   each sub-trigge
1a190 72 20 68 61 73 20 72 75 6e 2e 29 5e 0a 2a 2a 20  r has run.)^.** 
1a1a0 3c 2f 75 6c 3e 0a 2a 2a 20 0a 2a 2a 20 5e 54 68  </ul>.** .** ^Th
1a1b0 69 73 20 6d 65 61 6e 73 20 74 68 61 74 20 69 66  is means that if
1a1c0 20 74 68 65 20 63 68 61 6e 67 65 73 28 29 20 53   the changes() S
1a1d0 51 4c 20 66 75 6e 63 74 69 6f 6e 20 28 6f 72 20  QL function (or 
1a1e0 73 69 6d 69 6c 61 72 29 20 69 73 20 75 73 65 64  similar) is used
1a1f0 0a 2a 2a 20 62 79 20 74 68 65 20 66 69 72 73 74  .** by the first
1a200 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 20   INSERT, UPDATE 
1a210 6f 72 20 44 45 4c 45 54 45 20 73 74 61 74 65 6d  or DELETE statem
1a220 65 6e 74 20 77 69 74 68 69 6e 20 61 20 74 72 69  ent within a tri
1a230 67 67 65 72 2c 20 69 74 20 0a 2a 2a 20 72 65 74  gger, it .** ret
1a240 75 72 6e 73 20 74 68 65 20 76 61 6c 75 65 20 61  urns the value a
1a250 73 20 73 65 74 20 77 68 65 6e 20 74 68 65 20 63  s set when the c
1a260 61 6c 6c 69 6e 67 20 73 74 61 74 65 6d 65 6e 74  alling statement
1a270 20 62 65 67 61 6e 20 65 78 65 63 75 74 69 6e 67   began executing
1a280 2e 0a 2a 2a 20 5e 49 66 20 69 74 20 69 73 20 75  ..** ^If it is u
1a290 73 65 64 20 62 79 20 74 68 65 20 73 65 63 6f 6e  sed by the secon
1a2a0 64 20 6f 72 20 73 75 62 73 65 71 75 65 6e 74 20  d or subsequent 
1a2b0 73 75 63 68 20 73 74 61 74 65 6d 65 6e 74 20 77  such statement w
1a2c0 69 74 68 69 6e 20 61 20 74 72 69 67 67 65 72 20  ithin a trigger 
1a2d0 0a 2a 2a 20 70 72 6f 67 72 61 6d 2c 20 74 68 65  .** program, the
1a2e0 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20   value returned 
1a2f0 72 65 66 6c 65 63 74 73 20 74 68 65 20 6e 75 6d  reflects the num
1a300 62 65 72 20 6f 66 20 72 6f 77 73 20 6d 6f 64 69  ber of rows modi
1a310 66 69 65 64 20 62 79 20 74 68 65 20 0a 2a 2a 20  fied by the .** 
1a320 70 72 65 76 69 6f 75 73 20 49 4e 53 45 52 54 2c  previous INSERT,
1a330 20 55 50 44 41 54 45 20 6f 72 20 44 45 4c 45 54   UPDATE or DELET
1a340 45 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68  E statement with
1a350 69 6e 20 74 68 65 20 73 61 6d 65 20 74 72 69 67  in the same trig
1a360 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  ger..**.** See a
1a370 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33  lso the [sqlite3
1a380 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29  _total_changes()
1a390 5d 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65  ] interface, the
1a3a0 0a 2a 2a 20 5b 63 6f 75 6e 74 5f 63 68 61 6e 67  .** [count_chang
1a3b0 65 73 20 70 72 61 67 6d 61 5d 2c 20 61 6e 64 20  es pragma], and 
1a3c0 74 68 65 20 5b 63 68 61 6e 67 65 73 28 29 20 53  the [changes() S
1a3d0 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a  QL function]..**
1a3e0 0a 2a 2a 20 49 66 20 61 20 73 65 70 61 72 61 74  .** If a separat
1a3f0 65 20 74 68 72 65 61 64 20 6d 61 6b 65 73 20 63  e thread makes c
1a400 68 61 6e 67 65 73 20 6f 6e 20 74 68 65 20 73 61  hanges on the sa
1a410 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  me database conn
1a420 65 63 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20  ection.** while 
1a430 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73  [sqlite3_changes
1a440 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20 74  ()] is running t
1a450 68 65 6e 20 74 68 65 20 76 61 6c 75 65 20 72 65  hen the value re
1a460 74 75 72 6e 65 64 0a 2a 2a 20 69 73 20 75 6e 70  turned.** is unp
1a470 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6e  redictable and n
1a480 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a  ot meaningful..*
1a490 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 68  /.int sqlite3_ch
1a4a0 61 6e 67 65 73 28 73 71 6c 69 74 65 33 2a 29 3b  anges(sqlite3*);
1a4b0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1a4c0 3a 20 54 6f 74 61 6c 20 4e 75 6d 62 65 72 20 4f  : Total Number O
1a4d0 66 20 52 6f 77 73 20 4d 6f 64 69 66 69 65 64 0a  f Rows Modified.
1a4e0 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
1a4f0 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66  e3.**.** ^This f
1a500 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20  unction returns 
1a510 74 68 65 20 74 6f 74 61 6c 20 6e 75 6d 62 65 72  the total number
1a520 20 6f 66 20 72 6f 77 73 20 69 6e 73 65 72 74 65   of rows inserte
1a530 64 2c 20 6d 6f 64 69 66 69 65 64 20 6f 72 0a 2a  d, modified or.*
1a540 2a 20 64 65 6c 65 74 65 64 20 62 79 20 61 6c 6c  * deleted by all
1a550 20 5b 49 4e 53 45 52 54 5d 2c 20 5b 55 50 44 41   [INSERT], [UPDA
1a560 54 45 5d 20 6f 72 20 5b 44 45 4c 45 54 45 5d 20  TE] or [DELETE] 
1a570 73 74 61 74 65 6d 65 6e 74 73 20 63 6f 6d 70 6c  statements compl
1a580 65 74 65 64 0a 2a 2a 20 73 69 6e 63 65 20 74 68  eted.** since th
1a590 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
1a5a0 63 74 69 6f 6e 20 77 61 73 20 6f 70 65 6e 65 64  ction was opened
1a5b0 2c 20 69 6e 63 6c 75 64 69 6e 67 20 74 68 6f 73  , including thos
1a5c0 65 20 65 78 65 63 75 74 65 64 20 61 73 0a 2a 2a  e executed as.**
1a5d0 20 70 61 72 74 20 6f 66 20 74 72 69 67 67 65 72   part of trigger
1a5e0 20 70 72 6f 67 72 61 6d 73 2e 20 5e 45 78 65 63   programs. ^Exec
1a5f0 75 74 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20  uting any other 
1a600 74 79 70 65 20 6f 66 20 53 51 4c 20 73 74 61 74  type of SQL stat
1a610 65 6d 65 6e 74 0a 2a 2a 20 64 6f 65 73 20 6e 6f  ement.** does no
1a620 74 20 61 66 66 65 63 74 20 74 68 65 20 76 61 6c  t affect the val
1a630 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 73  ue returned by s
1a640 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61  qlite3_total_cha
1a650 6e 67 65 73 28 29 2e 0a 2a 2a 20 0a 2a 2a 20 5e  nges()..** .** ^
1a660 43 68 61 6e 67 65 73 20 6d 61 64 65 20 61 73 20  Changes made as 
1a670 70 61 72 74 20 6f 66 20 5b 66 6f 72 65 69 67 6e  part of [foreign
1a680 20 6b 65 79 20 61 63 74 69 6f 6e 73 5d 20 61 72   key actions] ar
1a690 65 20 69 6e 63 6c 75 64 65 64 20 69 6e 20 74 68  e included in th
1a6a0 65 0a 2a 2a 20 63 6f 75 6e 74 2c 20 62 75 74 20  e.** count, but 
1a6b0 74 68 6f 73 65 20 6d 61 64 65 20 61 73 20 70 61  those made as pa
1a6c0 72 74 20 6f 66 20 52 45 50 4c 41 43 45 20 63 6f  rt of REPLACE co
1a6d0 6e 73 74 72 61 69 6e 74 20 72 65 73 6f 6c 75 74  nstraint resolut
1a6e0 69 6f 6e 20 61 72 65 0a 2a 2a 20 6e 6f 74 2e 20  ion are.** not. 
1a6f0 5e 43 68 61 6e 67 65 73 20 74 6f 20 61 20 76 69  ^Changes to a vi
1a700 65 77 20 74 68 61 74 20 61 72 65 20 69 6e 74 65  ew that are inte
1a710 72 63 65 70 74 65 64 20 62 79 20 49 4e 53 54 45  rcepted by INSTE
1a720 41 44 20 4f 46 20 74 72 69 67 67 65 72 73 20 0a  AD OF triggers .
1a730 2a 2a 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74  ** are not count
1a740 65 64 2e 0a 2a 2a 20 0a 2a 2a 20 53 65 65 20 61  ed..** .** See a
1a750 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33  lso the [sqlite3
1a760 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 6e 74 65  _changes()] inte
1a770 72 66 61 63 65 2c 20 74 68 65 0a 2a 2a 20 5b 63  rface, the.** [c
1a780 6f 75 6e 74 5f 63 68 61 6e 67 65 73 20 70 72 61  ount_changes pra
1a790 67 6d 61 5d 2c 20 61 6e 64 20 74 68 65 20 5b 74  gma], and the [t
1a7a0 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 20 53  otal_changes() S
1a7b0 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a  QL function]..**
1a7c0 0a 2a 2a 20 49 66 20 61 20 73 65 70 61 72 61 74  .** If a separat
1a7d0 65 20 74 68 72 65 61 64 20 6d 61 6b 65 73 20 63  e thread makes c
1a7e0 68 61 6e 67 65 73 20 6f 6e 20 74 68 65 20 73 61  hanges on the sa
1a7f0 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  me database conn
1a800 65 63 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20  ection.** while 
1a810 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63  [sqlite3_total_c
1a820 68 61 6e 67 65 73 28 29 5d 20 69 73 20 72 75 6e  hanges()] is run
1a830 6e 69 6e 67 20 74 68 65 6e 20 74 68 65 20 76 61  ning then the va
1a840 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20  lue.** returned 
1a850 69 73 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65  is unpredictable
1a860 20 61 6e 64 20 6e 6f 74 20 6d 65 61 6e 69 6e 67   and not meaning
1a870 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ful..*/.int sqli
1a880 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65  te3_total_change
1a890 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a  s(sqlite3*);../*
1a8a0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e  .** CAPI3REF: In
1a8b0 74 65 72 72 75 70 74 20 41 20 4c 6f 6e 67 2d 52  terrupt A Long-R
1a8c0 75 6e 6e 69 6e 67 20 51 75 65 72 79 0a 2a 2a 20  unning Query.** 
1a8d0 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a  METHOD: sqlite3.
1a8e0 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63  **.** ^This func
1a8f0 74 69 6f 6e 20 63 61 75 73 65 73 20 61 6e 79 20  tion causes any 
1a900 70 65 6e 64 69 6e 67 20 64 61 74 61 62 61 73 65  pending database
1a910 20 6f 70 65 72 61 74 69 6f 6e 20 74 6f 20 61 62   operation to ab
1a920 6f 72 74 20 61 6e 64 0a 2a 2a 20 72 65 74 75 72  ort and.** retur
1a930 6e 20 61 74 20 69 74 73 20 65 61 72 6c 69 65 73  n at its earlies
1a940 74 20 6f 70 70 6f 72 74 75 6e 69 74 79 2e 20 54  t opportunity. T
1a950 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 74  his routine is t
1a960 79 70 69 63 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c  ypically.** call
1a970 65 64 20 69 6e 20 72 65 73 70 6f 6e 73 65 20 74  ed in response t
1a980 6f 20 61 20 75 73 65 72 20 61 63 74 69 6f 6e 20  o a user action 
1a990 73 75 63 68 20 61 73 20 70 72 65 73 73 69 6e 67  such as pressing
1a9a0 20 22 43 61 6e 63 65 6c 22 0a 2a 2a 20 6f 72 20   "Cancel".** or 
1a9b0 43 74 72 6c 2d 43 20 77 68 65 72 65 20 74 68 65  Ctrl-C where the
1a9c0 20 75 73 65 72 20 77 61 6e 74 73 20 61 20 6c 6f   user wants a lo
1a9d0 6e 67 20 71 75 65 72 79 20 6f 70 65 72 61 74 69  ng query operati
1a9e0 6f 6e 20 74 6f 20 68 61 6c 74 0a 2a 2a 20 69 6d  on to halt.** im
1a9f0 6d 65 64 69 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a  mediately..**.**
1aa00 20 5e 49 74 20 69 73 20 73 61 66 65 20 74 6f 20   ^It is safe to 
1aa10 63 61 6c 6c 20 74 68 69 73 20 72 6f 75 74 69 6e  call this routin
1aa20 65 20 66 72 6f 6d 20 61 20 74 68 72 65 61 64 20  e from a thread 
1aa30 64 69 66 66 65 72 65 6e 74 20 66 72 6f 6d 20 74  different from t
1aa40 68 65 0a 2a 2a 20 74 68 72 65 61 64 20 74 68 61  he.** thread tha
1aa50 74 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20 72  t is currently r
1aa60 75 6e 6e 69 6e 67 20 74 68 65 20 64 61 74 61 62  unning the datab
1aa70 61 73 65 20 6f 70 65 72 61 74 69 6f 6e 2e 20 20  ase operation.  
1aa80 42 75 74 20 69 74 0a 2a 2a 20 69 73 20 6e 6f 74  But it.** is not
1aa90 20 73 61 66 65 20 74 6f 20 63 61 6c 6c 20 74 68   safe to call th
1aaa0 69 73 20 72 6f 75 74 69 6e 65 20 77 69 74 68 20  is routine with 
1aab0 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  a [database conn
1aac0 65 63 74 69 6f 6e 5d 20 74 68 61 74 0a 2a 2a 20  ection] that.** 
1aad0 69 73 20 63 6c 6f 73 65 64 20 6f 72 20 6d 69 67  is closed or mig
1aae0 68 74 20 63 6c 6f 73 65 20 62 65 66 6f 72 65 20  ht close before 
1aaf0 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
1ab00 74 28 29 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a  t() returns..**.
1ab10 2a 2a 20 5e 49 66 20 61 6e 20 53 51 4c 20 6f 70  ** ^If an SQL op
1ab20 65 72 61 74 69 6f 6e 20 69 73 20 76 65 72 79 20  eration is very 
1ab30 6e 65 61 72 6c 79 20 66 69 6e 69 73 68 65 64 20  nearly finished 
1ab40 61 74 20 74 68 65 20 74 69 6d 65 20 77 68 65 6e  at the time when
1ab50 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 69 6e 74 65  .** sqlite3_inte
1ab60 72 72 75 70 74 28 29 20 69 73 20 63 61 6c 6c 65  rrupt() is calle
1ab70 64 2c 20 74 68 65 6e 20 69 74 20 6d 69 67 68 74  d, then it might
1ab80 20 6e 6f 74 20 68 61 76 65 20 61 6e 20 6f 70 70   not have an opp
1ab90 6f 72 74 75 6e 69 74 79 0a 2a 2a 20 74 6f 20 62  ortunity.** to b
1aba0 65 20 69 6e 74 65 72 72 75 70 74 65 64 20 61 6e  e interrupted an
1abb0 64 20 6d 69 67 68 74 20 63 6f 6e 74 69 6e 75 65  d might continue
1abc0 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 2e 0a   to completion..
1abd0 2a 2a 0a 2a 2a 20 5e 41 6e 20 53 51 4c 20 6f 70  **.** ^An SQL op
1abe0 65 72 61 74 69 6f 6e 20 74 68 61 74 20 69 73 20  eration that is 
1abf0 69 6e 74 65 72 72 75 70 74 65 64 20 77 69 6c 6c  interrupted will
1ac00 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
1ac10 49 4e 54 45 52 52 55 50 54 5d 2e 0a 2a 2a 20 5e  INTERRUPT]..** ^
1ac20 49 66 20 74 68 65 20 69 6e 74 65 72 72 75 70 74  If the interrupt
1ac30 65 64 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e  ed SQL operation
1ac40 20 69 73 20 61 6e 20 49 4e 53 45 52 54 2c 20 55   is an INSERT, U
1ac50 50 44 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 45  PDATE, or DELETE
1ac60 0a 2a 2a 20 74 68 61 74 20 69 73 20 69 6e 73 69  .** that is insi
1ac70 64 65 20 61 6e 20 65 78 70 6c 69 63 69 74 20 74  de an explicit t
1ac80 72 61 6e 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e  ransaction, then
1ac90 20 74 68 65 20 65 6e 74 69 72 65 20 74 72 61 6e   the entire tran
1aca0 73 61 63 74 69 6f 6e 0a 2a 2a 20 77 69 6c 6c 20  saction.** will 
1acb0 62 65 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 61  be rolled back a
1acc0 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 0a 2a 2a  utomatically..**
1acd0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
1ace0 5f 69 6e 74 65 72 72 75 70 74 28 44 29 20 63 61  _interrupt(D) ca
1acf0 6c 6c 20 69 73 20 69 6e 20 65 66 66 65 63 74 20  ll is in effect 
1ad00 75 6e 74 69 6c 20 61 6c 6c 20 63 75 72 72 65 6e  until all curren
1ad10 74 6c 79 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53  tly running.** S
1ad20 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 6f 6e  QL statements on
1ad30 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
1ad40 63 74 69 6f 6e 5d 20 44 20 63 6f 6d 70 6c 65 74  ction] D complet
1ad50 65 2e 20 20 5e 41 6e 79 20 6e 65 77 20 53 51 4c  e.  ^Any new SQL
1ad60 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74   statements.** t
1ad70 68 61 74 20 61 72 65 20 73 74 61 72 74 65 64 20  hat are started 
1ad80 61 66 74 65 72 20 74 68 65 20 73 71 6c 69 74 65  after the sqlite
1ad90 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 63 61  3_interrupt() ca
1ada0 6c 6c 20 61 6e 64 20 62 65 66 6f 72 65 20 74 68  ll and before th
1adb0 65 20 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20 73 74  e .** running st
1adc0 61 74 65 6d 65 6e 74 73 20 72 65 61 63 68 65 73  atements reaches
1add0 20 7a 65 72 6f 20 61 72 65 20 69 6e 74 65 72 72   zero are interr
1ade0 75 70 74 65 64 20 61 73 20 69 66 20 74 68 65 79  upted as if they
1adf0 20 68 61 64 20 62 65 65 6e 0a 2a 2a 20 72 75 6e   had been.** run
1ae00 6e 69 6e 67 20 70 72 69 6f 72 20 74 6f 20 74 68  ning prior to th
1ae10 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72  e sqlite3_interr
1ae20 75 70 74 28 29 20 63 61 6c 6c 2e 20 20 5e 4e 65  upt() call.  ^Ne
1ae30 77 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  w SQL statements
1ae40 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 73 74 61  .** that are sta
1ae50 72 74 65 64 20 61 66 74 65 72 20 74 68 65 20 72  rted after the r
1ae60 75 6e 6e 69 6e 67 20 73 74 61 74 65 6d 65 6e 74  unning statement
1ae70 20 63 6f 75 6e 74 20 72 65 61 63 68 65 73 20 7a   count reaches z
1ae80 65 72 6f 20 61 72 65 0a 2a 2a 20 6e 6f 74 20 65  ero are.** not e
1ae90 66 66 65 63 74 65 64 20 62 79 20 74 68 65 20 73  ffected by the s
1aea0 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
1aeb0 28 29 2e 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20 74  ()..** ^A call t
1aec0 6f 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72  o sqlite3_interr
1aed0 75 70 74 28 44 29 20 74 68 61 74 20 6f 63 63 75  upt(D) that occu
1aee0 72 73 20 77 68 65 6e 20 74 68 65 72 65 20 61 72  rs when there ar
1aef0 65 20 6e 6f 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20  e no running.** 
1af00 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 69  SQL statements i
1af10 73 20 61 20 6e 6f 2d 6f 70 20 61 6e 64 20 68 61  s a no-op and ha
1af20 73 20 6e 6f 20 65 66 66 65 63 74 20 6f 6e 20 53  s no effect on S
1af30 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a  QL statements.**
1af40 20 74 68 61 74 20 61 72 65 20 73 74 61 72 74 65   that are starte
1af50 64 20 61 66 74 65 72 20 74 68 65 20 73 71 6c 69  d after the sqli
1af60 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20  te3_interrupt() 
1af70 63 61 6c 6c 20 72 65 74 75 72 6e 73 2e 0a 2a 2a  call returns..**
1af80 0a 2a 2a 20 49 66 20 74 68 65 20 64 61 74 61 62  .** If the datab
1af90 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63  ase connection c
1afa0 6c 6f 73 65 73 20 77 68 69 6c 65 20 5b 73 71 6c  loses while [sql
1afb0 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29  ite3_interrupt()
1afc0 5d 0a 2a 2a 20 69 73 20 72 75 6e 6e 69 6e 67 20  ].** is running 
1afd0 74 68 65 6e 20 62 61 64 20 74 68 69 6e 67 73 20  then bad things 
1afe0 77 69 6c 6c 20 6c 69 6b 65 6c 79 20 68 61 70 70  will likely happ
1aff0 65 6e 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69  en..*/.void sqli
1b000 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 73 71  te3_interrupt(sq
1b010 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  lite3*);../*.** 
1b020 43 41 50 49 33 52 45 46 3a 20 44 65 74 65 72 6d  CAPI3REF: Determ
1b030 69 6e 65 20 49 66 20 41 6e 20 53 51 4c 20 53 74  ine If An SQL St
1b040 61 74 65 6d 65 6e 74 20 49 73 20 43 6f 6d 70 6c  atement Is Compl
1b050 65 74 65 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ete.**.** These 
1b060 72 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73 65  routines are use
1b070 66 75 6c 20 64 75 72 69 6e 67 20 63 6f 6d 6d 61  ful during comma
1b080 6e 64 2d 6c 69 6e 65 20 69 6e 70 75 74 20 74 6f  nd-line input to
1b090 20 64 65 74 65 72 6d 69 6e 65 20 69 66 20 74 68   determine if th
1b0a0 65 0a 2a 2a 20 63 75 72 72 65 6e 74 6c 79 20 65  e.** currently e
1b0b0 6e 74 65 72 65 64 20 74 65 78 74 20 73 65 65 6d  ntered text seem
1b0c0 73 20 74 6f 20 66 6f 72 6d 20 61 20 63 6f 6d 70  s to form a comp
1b0d0 6c 65 74 65 20 53 51 4c 20 73 74 61 74 65 6d 65  lete SQL stateme
1b0e0 6e 74 20 6f 72 0a 2a 2a 20 69 66 20 61 64 64 69  nt or.** if addi
1b0f0 74 69 6f 6e 61 6c 20 69 6e 70 75 74 20 69 73 20  tional input is 
1b100 6e 65 65 64 65 64 20 62 65 66 6f 72 65 20 73 65  needed before se
1b110 6e 64 69 6e 67 20 74 68 65 20 74 65 78 74 20 69  nding the text i
1b120 6e 74 6f 0a 2a 2a 20 53 51 4c 69 74 65 20 66 6f  nto.** SQLite fo
1b130 72 20 70 61 72 73 69 6e 67 2e 20 20 5e 54 68 65  r parsing.  ^The
1b140 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  se routines retu
1b150 72 6e 20 31 20 69 66 20 74 68 65 20 69 6e 70 75  rn 1 if the inpu
1b160 74 20 73 74 72 69 6e 67 0a 2a 2a 20 61 70 70 65  t string.** appe
1b170 61 72 73 20 74 6f 20 62 65 20 61 20 63 6f 6d 70  ars to be a comp
1b180 6c 65 74 65 20 53 51 4c 20 73 74 61 74 65 6d 65  lete SQL stateme
1b190 6e 74 2e 20 20 5e 41 20 73 74 61 74 65 6d 65 6e  nt.  ^A statemen
1b1a0 74 20 69 73 20 6a 75 64 67 65 64 20 74 6f 20 62  t is judged to b
1b1b0 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 20 69 66  e.** complete if
1b1c0 20 69 74 20 65 6e 64 73 20 77 69 74 68 20 61 20   it ends with a 
1b1d0 73 65 6d 69 63 6f 6c 6f 6e 20 74 6f 6b 65 6e 20  semicolon token 
1b1e0 61 6e 64 20 69 73 20 6e 6f 74 20 61 20 70 72 65  and is not a pre
1b1f0 66 69 78 20 6f 66 20 61 0a 2a 2a 20 77 65 6c 6c  fix of a.** well
1b200 2d 66 6f 72 6d 65 64 20 43 52 45 41 54 45 20 54  -formed CREATE T
1b210 52 49 47 47 45 52 20 73 74 61 74 65 6d 65 6e 74  RIGGER statement
1b220 2e 20 20 5e 53 65 6d 69 63 6f 6c 6f 6e 73 20 74  .  ^Semicolons t
1b230 68 61 74 20 61 72 65 20 65 6d 62 65 64 64 65 64  hat are embedded
1b240 20 77 69 74 68 69 6e 0a 2a 2a 20 73 74 72 69 6e   within.** strin
1b250 67 20 6c 69 74 65 72 61 6c 73 20 6f 72 20 71 75  g literals or qu
1b260 6f 74 65 64 20 69 64 65 6e 74 69 66 69 65 72 20  oted identifier 
1b270 6e 61 6d 65 73 20 6f 72 20 63 6f 6d 6d 65 6e 74  names or comment
1b280 73 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 69 6e 64  s are not.** ind
1b290 65 70 65 6e 64 65 6e 74 20 74 6f 6b 65 6e 73 20  ependent tokens 
1b2a0 28 74 68 65 79 20 61 72 65 20 70 61 72 74 20 6f  (they are part o
1b2b0 66 20 74 68 65 20 74 6f 6b 65 6e 20 69 6e 20 77  f the token in w
1b2c0 68 69 63 68 20 74 68 65 79 20 61 72 65 0a 2a 2a  hich they are.**
1b2d0 20 65 6d 62 65 64 64 65 64 29 20 61 6e 64 20 74   embedded) and t
1b2e0 68 75 73 20 64 6f 20 6e 6f 74 20 63 6f 75 6e 74  hus do not count
1b2f0 20 61 73 20 61 20 73 74 61 74 65 6d 65 6e 74 20   as a statement 
1b300 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20 5e 57 68  terminator.  ^Wh
1b310 69 74 65 73 70 61 63 65 0a 2a 2a 20 61 6e 64 20  itespace.** and 
1b320 63 6f 6d 6d 65 6e 74 73 20 74 68 61 74 20 66 6f  comments that fo
1b330 6c 6c 6f 77 20 74 68 65 20 66 69 6e 61 6c 20 73  llow the final s
1b340 65 6d 69 63 6f 6c 6f 6e 20 61 72 65 20 69 67 6e  emicolon are ign
1b350 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ored..**.** ^The
1b360 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  se routines retu
1b370 72 6e 20 30 20 69 66 20 74 68 65 20 73 74 61 74  rn 0 if the stat
1b380 65 6d 65 6e 74 20 69 73 20 69 6e 63 6f 6d 70 6c  ement is incompl
1b390 65 74 65 2e 20 20 5e 49 66 20 61 0a 2a 2a 20 6d  ete.  ^If a.** m
1b3a0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
1b3b0 20 66 61 69 6c 73 2c 20 74 68 65 6e 20 53 51 4c   fails, then SQL
1b3c0 49 54 45 5f 4e 4f 4d 45 4d 20 69 73 20 72 65 74  ITE_NOMEM is ret
1b3d0 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  urned..**.** ^Th
1b3e0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 64 6f 20  ese routines do 
1b3f0 6e 6f 74 20 70 61 72 73 65 20 74 68 65 20 53 51  not parse the SQ
1b400 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 74 68 75  L statements thu
1b410 73 0a 2a 2a 20 77 69 6c 6c 20 6e 6f 74 20 64 65  s.** will not de
1b420 74 65 63 74 20 73 79 6e 74 61 63 74 69 63 61 6c  tect syntactical
1b430 6c 79 20 69 6e 63 6f 72 72 65 63 74 20 53 51 4c  ly incorrect SQL
1b440 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 53 51 4c  ..**.** ^(If SQL
1b450 69 74 65 20 68 61 73 20 6e 6f 74 20 62 65 65 6e  ite has not been
1b460 20 69 6e 69 74 69 61 6c 69 7a 65 64 20 75 73 69   initialized usi
1b470 6e 67 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74  ng [sqlite3_init
1b480 69 61 6c 69 7a 65 28 29 5d 20 70 72 69 6f 72 20  ialize()] prior 
1b490 0a 2a 2a 20 74 6f 20 69 6e 76 6f 6b 69 6e 67 20  .** to invoking 
1b4a0 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65  sqlite3_complete
1b4b0 31 36 28 29 20 74 68 65 6e 20 73 71 6c 69 74 65  16() then sqlite
1b4c0 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69  3_initialize() i
1b4d0 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61 75 74  s invoked.** aut
1b4e0 6f 6d 61 74 69 63 61 6c 6c 79 20 62 79 20 73 71  omatically by sq
1b4f0 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36  lite3_complete16
1b500 28 29 2e 20 20 49 66 20 74 68 61 74 20 69 6e 69  ().  If that ini
1b510 74 69 61 6c 69 7a 61 74 69 6f 6e 20 66 61 69 6c  tialization fail
1b520 73 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 72  s,.** then the r
1b530 65 74 75 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d  eturn value from
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 20 77 69 6c 6c 20 62 65 20 6e 6f  e16() will be no
1b560 6e 2d 7a 65 72 6f 0a 2a 2a 20 72 65 67 61 72 64  n-zero.** regard
1b570 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65 72 20  less of whether 
1b580 6f 72 20 6e 6f 74 20 74 68 65 20 69 6e 70 75 74  or not the input
1b590 20 53 51 4c 20 69 73 20 63 6f 6d 70 6c 65 74 65   SQL is complete
1b5a0 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e  .)^.**.** The in
1b5b0 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  put to [sqlite3_
1b5c0 63 6f 6d 70 6c 65 74 65 28 29 5d 20 6d 75 73 74  complete()] must
1b5d0 20 62 65 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69   be a zero-termi
1b5e0 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d 38 20 73  nated.** UTF-8 s
1b5f0 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  tring..**.** 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 31 36 28 29 5d  e3_complete16()]
1b620 20 6d 75 73 74 20 62 65 20 61 20 7a 65 72 6f 2d   must be a zero-
1b630 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54  terminated.** UT
1b640 46 2d 31 36 20 73 74 72 69 6e 67 20 69 6e 20 6e  F-16 string in n
1b650 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72  ative byte order
1b660 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
1b670 5f 63 6f 6d 70 6c 65 74 65 28 63 6f 6e 73 74 20  _complete(const 
1b680 63 68 61 72 20 2a 73 71 6c 29 3b 0a 69 6e 74 20  char *sql);.int 
1b690 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65  sqlite3_complete
1b6a0 31 36 28 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  16(const void *s
1b6b0 71 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ql);../*.** CAPI
1b6c0 33 52 45 46 3a 20 52 65 67 69 73 74 65 72 20 41  3REF: Register A
1b6d0 20 43 61 6c 6c 62 61 63 6b 20 54 6f 20 48 61 6e   Callback To Han
1b6e0 64 6c 65 20 53 51 4c 49 54 45 5f 42 55 53 59 20  dle SQLITE_BUSY 
1b6f0 45 72 72 6f 72 73 0a 2a 2a 20 4b 45 59 57 4f 52  Errors.** KEYWOR
1b700 44 53 3a 20 7b 62 75 73 79 2d 68 61 6e 64 6c 65  DS: {busy-handle
1b710 72 20 63 61 6c 6c 62 61 63 6b 7d 20 7b 62 75 73  r callback} {bus
1b720 79 20 68 61 6e 64 6c 65 72 7d 0a 2a 2a 20 4d 45  y handler}.** ME
1b730 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a  THOD: sqlite3.**
1b740 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
1b750 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 44 2c  _busy_handler(D,
1b760 58 2c 50 29 20 72 6f 75 74 69 6e 65 20 73 65 74  X,P) routine set
1b770 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  s a callback fun
1b780 63 74 69 6f 6e 20 58 0a 2a 2a 20 74 68 61 74 20  ction X.** that 
1b790 6d 69 67 68 74 20 62 65 20 69 6e 76 6f 6b 65 64  might be invoked
1b7a0 20 77 69 74 68 20 61 72 67 75 6d 65 6e 74 20 50   with argument P
1b7b0 20 77 68 65 6e 65 76 65 72 0a 2a 2a 20 61 6e 20   whenever.** an 
1b7c0 61 74 74 65 6d 70 74 20 69 73 20 6d 61 64 65 20  attempt is made 
1b7d0 74 6f 20 61 63 63 65 73 73 20 61 20 64 61 74 61  to access a data
1b7e0 62 61 73 65 20 74 61 62 6c 65 20 61 73 73 6f 63  base table assoc
1b7f0 69 61 74 65 64 20 77 69 74 68 0a 2a 2a 20 5b 64  iated with.** [d
1b800 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1b810 6f 6e 5d 20 44 20 77 68 65 6e 20 61 6e 6f 74 68  on] D when anoth
1b820 65 72 20 74 68 72 65 61 64 0a 2a 2a 20 6f 72 20  er thread.** or 
1b830 70 72 6f 63 65 73 73 20 68 61 73 20 74 68 65 20  process has the 
1b840 74 61 62 6c 65 20 6c 6f 63 6b 65 64 2e 0a 2a 2a  table locked..**
1b850 20 54 68 65 20 73 71 6c 69 74 65 33 5f 62 75 73   The sqlite3_bus
1b860 79 5f 68 61 6e 64 6c 65 72 28 29 20 69 6e 74 65  y_handler() inte
1b870 72 66 61 63 65 20 69 73 20 75 73 65 64 20 74 6f  rface is used to
1b880 20 69 6d 70 6c 65 6d 65 6e 74 0a 2a 2a 20 5b 73   implement.** [s
1b890 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65  qlite3_busy_time
1b8a0 6f 75 74 28 29 5d 20 61 6e 64 20 5b 50 52 41 47  out()] and [PRAG
1b8b0 4d 41 20 62 75 73 79 5f 74 69 6d 65 6f 75 74 5d  MA busy_timeout]
1b8c0 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
1b8d0 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 69 73  busy callback is
1b8e0 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 5b 53 51 4c   NULL, then [SQL
1b8f0 49 54 45 5f 42 55 53 59 5d 0a 2a 2a 20 69 73 20  ITE_BUSY].** is 
1b900 72 65 74 75 72 6e 65 64 20 69 6d 6d 65 64 69 61  returned immedia
1b910 74 65 6c 79 20 75 70 6f 6e 20 65 6e 63 6f 75 6e  tely upon encoun
1b920 74 65 72 69 6e 67 20 74 68 65 20 6c 6f 63 6b 2e  tering the lock.
1b930 20 20 5e 49 66 20 74 68 65 20 62 75 73 79 20 63    ^If the busy c
1b940 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 6e 6f  allback.** is no
1b950 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 74 68 65  t NULL, then the
1b960 20 63 61 6c 6c 62 61 63 6b 20 6d 69 67 68 74 20   callback might 
1b970 62 65 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20  be invoked with 
1b980 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a  two arguments..*
1b990 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20  *.** ^The first 
1b9a0 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20  argument to the 
1b9b0 62 75 73 79 20 68 61 6e 64 6c 65 72 20 69 73 20  busy handler is 
1b9c0 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 76 6f  a copy of the vo
1b9d0 69 64 2a 20 70 6f 69 6e 74 65 72 20 77 68 69 63  id* pointer whic
1b9e0 68 0a 2a 2a 20 69 73 20 74 68 65 20 74 68 69 72  h.** is the thir
1b9f0 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71  d argument to sq
1ba00 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c  lite3_busy_handl
1ba10 65 72 28 29 2e 20 20 5e 54 68 65 20 73 65 63 6f  er().  ^The seco
1ba20 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a  nd argument to.*
1ba30 2a 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c  * the busy handl
1ba40 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 74  er callback is t
1ba50 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 74 69 6d  he number of tim
1ba60 65 73 20 74 68 61 74 20 74 68 65 20 62 75 73 79  es that the busy
1ba70 20 68 61 6e 64 6c 65 72 20 68 61 73 0a 2a 2a 20   handler has.** 
1ba80 62 65 65 6e 20 69 6e 76 6f 6b 65 64 20 70 72 65  been invoked pre
1ba90 76 69 6f 75 73 6c 79 20 66 6f 72 20 74 68 65 20  viously for the 
1baa0 73 61 6d 65 20 6c 6f 63 6b 69 6e 67 20 65 76 65  same locking eve
1bab0 6e 74 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20  nt.  ^If the.** 
1bac0 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 72 65  busy callback re
1bad0 74 75 72 6e 73 20 30 2c 20 74 68 65 6e 20 6e 6f  turns 0, then no
1bae0 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 74 74 65   additional atte
1baf0 6d 70 74 73 20 61 72 65 20 6d 61 64 65 20 74 6f  mpts are made to
1bb00 0a 2a 2a 20 61 63 63 65 73 73 20 74 68 65 20 64  .** access the d
1bb10 61 74 61 62 61 73 65 20 61 6e 64 20 5b 53 51 4c  atabase and [SQL
1bb20 49 54 45 5f 42 55 53 59 5d 20 69 73 20 72 65 74  ITE_BUSY] is ret
1bb30 75 72 6e 65 64 0a 2a 2a 20 74 6f 20 74 68 65 20  urned.** to the 
1bb40 61 70 70 6c 69 63 61 74 69 6f 6e 2e 0a 2a 2a 20  application..** 
1bb50 5e 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  ^If the callback
1bb60 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72   returns non-zer
1bb70 6f 2c 20 74 68 65 6e 20 61 6e 6f 74 68 65 72 20  o, then another 
1bb80 61 74 74 65 6d 70 74 0a 2a 2a 20 69 73 20 6d 61  attempt.** is ma
1bb90 64 65 20 74 6f 20 61 63 63 65 73 73 20 74 68 65  de to access the
1bba0 20 64 61 74 61 62 61 73 65 20 61 6e 64 20 74 68   database and th
1bbb0 65 20 63 79 63 6c 65 20 72 65 70 65 61 74 73 2e  e cycle repeats.
1bbc0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 65 73 65  .**.** The prese
1bbd0 6e 63 65 20 6f 66 20 61 20 62 75 73 79 20 68 61  nce of a busy ha
1bbe0 6e 64 6c 65 72 20 64 6f 65 73 20 6e 6f 74 20 67  ndler does not g
1bbf0 75 61 72 61 6e 74 65 65 20 74 68 61 74 20 69 74  uarantee that it
1bc00 20 77 69 6c 6c 20 62 65 20 69 6e 76 6f 6b 65 64   will be invoked
1bc10 0a 2a 2a 20 77 68 65 6e 20 74 68 65 72 65 20 69  .** when there i
1bc20 73 20 6c 6f 63 6b 20 63 6f 6e 74 65 6e 74 69 6f  s lock contentio
1bc30 6e 2e 20 5e 49 66 20 53 51 4c 69 74 65 20 64 65  n. ^If SQLite de
1bc40 74 65 72 6d 69 6e 65 73 20 74 68 61 74 20 69 6e  termines that in
1bc50 76 6f 6b 69 6e 67 20 74 68 65 20 62 75 73 79 0a  voking the busy.
1bc60 2a 2a 20 68 61 6e 64 6c 65 72 20 63 6f 75 6c 64  ** handler could
1bc70 20 72 65 73 75 6c 74 20 69 6e 20 61 20 64 65 61   result in a dea
1bc80 64 6c 6f 63 6b 2c 20 69 74 20 77 69 6c 6c 20 67  dlock, it will g
1bc90 6f 20 61 68 65 61 64 20 61 6e 64 20 72 65 74 75  o ahead and retu
1bca0 72 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  rn [SQLITE_BUSY]
1bcb0 0a 2a 2a 20 74 6f 20 74 68 65 20 61 70 70 6c 69  .** to the appli
1bcc0 63 61 74 69 6f 6e 20 69 6e 73 74 65 61 64 20 6f  cation instead o
1bcd0 66 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20 0a  f invoking the .
1bce0 2a 2a 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e  ** busy handler.
1bcf0 0a 2a 2a 20 43 6f 6e 73 69 64 65 72 20 61 20 73  .** Consider a s
1bd00 63 65 6e 61 72 69 6f 20 77 68 65 72 65 20 6f 6e  cenario where on
1bd10 65 20 70 72 6f 63 65 73 73 20 69 73 20 68 6f 6c  e process is hol
1bd20 64 69 6e 67 20 61 20 72 65 61 64 20 6c 6f 63 6b  ding a read lock
1bd30 20 74 68 61 74 0a 2a 2a 20 69 74 20 69 73 20 74   that.** it is t
1bd40 72 79 69 6e 67 20 74 6f 20 70 72 6f 6d 6f 74 65  rying to promote
1bd50 20 74 6f 20 61 20 72 65 73 65 72 76 65 64 20 6c   to a reserved l
1bd60 6f 63 6b 20 61 6e 64 0a 2a 2a 20 61 20 73 65 63  ock and.** a sec
1bd70 6f 6e 64 20 70 72 6f 63 65 73 73 20 69 73 20 68  ond process is h
1bd80 6f 6c 64 69 6e 67 20 61 20 72 65 73 65 72 76 65  olding a reserve
1bd90 64 20 6c 6f 63 6b 20 74 68 61 74 20 69 74 20 69  d lock that it i
1bda0 73 20 74 72 79 69 6e 67 0a 2a 2a 20 74 6f 20 70  s trying.** to p
1bdb0 72 6f 6d 6f 74 65 20 74 6f 20 61 6e 20 65 78 63  romote to an exc
1bdc0 6c 75 73 69 76 65 20 6c 6f 63 6b 2e 20 20 54 68  lusive lock.  Th
1bdd0 65 20 66 69 72 73 74 20 70 72 6f 63 65 73 73 20  e first process 
1bde0 63 61 6e 6e 6f 74 20 70 72 6f 63 65 65 64 0a 2a  cannot proceed.*
1bdf0 2a 20 62 65 63 61 75 73 65 20 69 74 20 69 73 20  * because it is 
1be00 62 6c 6f 63 6b 65 64 20 62 79 20 74 68 65 20 73  blocked by the s
1be10 65 63 6f 6e 64 20 61 6e 64 20 74 68 65 20 73 65  econd and the se
1be20 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 63 61 6e  cond process can
1be30 6e 6f 74 0a 2a 2a 20 70 72 6f 63 65 65 64 20 62  not.** proceed b
1be40 65 63 61 75 73 65 20 69 74 20 69 73 20 62 6c 6f  ecause it is blo
1be50 63 6b 65 64 20 62 79 20 74 68 65 20 66 69 72 73  cked by the firs
1be60 74 2e 20 20 49 66 20 62 6f 74 68 20 70 72 6f 63  t.  If both proc
1be70 65 73 73 65 73 0a 2a 2a 20 69 6e 76 6f 6b 65 20  esses.** invoke 
1be80 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72  the busy handler
1be90 73 2c 20 6e 65 69 74 68 65 72 20 77 69 6c 6c 20  s, neither will 
1bea0 6d 61 6b 65 20 61 6e 79 20 70 72 6f 67 72 65 73  make any progres
1beb0 73 2e 20 20 54 68 65 72 65 66 6f 72 65 2c 0a 2a  s.  Therefore,.*
1bec0 2a 20 53 51 4c 69 74 65 20 72 65 74 75 72 6e 73  * SQLite returns
1bed0 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 66   [SQLITE_BUSY] f
1bee0 6f 72 20 74 68 65 20 66 69 72 73 74 20 70 72 6f  or the first pro
1bef0 63 65 73 73 2c 20 68 6f 70 69 6e 67 20 74 68 61  cess, hoping tha
1bf00 74 20 74 68 69 73 0a 2a 2a 20 77 69 6c 6c 20 69  t this.** will i
1bf10 6e 64 75 63 65 20 74 68 65 20 66 69 72 73 74 20  nduce the first 
1bf20 70 72 6f 63 65 73 73 20 74 6f 20 72 65 6c 65 61  process to relea
1bf30 73 65 20 69 74 73 20 72 65 61 64 20 6c 6f 63 6b  se its read lock
1bf40 20 61 6e 64 20 61 6c 6c 6f 77 0a 2a 2a 20 74 68   and allow.** th
1bf50 65 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73  e second process
1bf60 20 74 6f 20 70 72 6f 63 65 65 64 2e 0a 2a 2a 0a   to proceed..**.
1bf70 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20  ** ^The default 
1bf80 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 69 73  busy callback is
1bf90 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54   NULL..**.** ^(T
1bfa0 68 65 72 65 20 63 61 6e 20 6f 6e 6c 79 20 62 65  here can only be
1bfb0 20 61 20 73 69 6e 67 6c 65 20 62 75 73 79 20 68   a single busy h
1bfc0 61 6e 64 6c 65 72 20 64 65 66 69 6e 65 64 20 66  andler defined f
1bfd0 6f 72 20 65 61 63 68 0a 2a 2a 20 5b 64 61 74 61  or each.** [data
1bfe0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
1bff0 2e 20 20 53 65 74 74 69 6e 67 20 61 20 6e 65 77  .  Setting a new
1c000 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 63 6c   busy handler cl
1c010 65 61 72 73 20 61 6e 79 0a 2a 2a 20 70 72 65 76  ears any.** prev
1c020 69 6f 75 73 6c 79 20 73 65 74 20 68 61 6e 64 6c  iously set handl
1c030 65 72 2e 29 5e 20 20 5e 4e 6f 74 65 20 74 68 61  er.)^  ^Note tha
1c040 74 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74  t calling [sqlit
1c050 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28  e3_busy_timeout(
1c060 29 5d 0a 2a 2a 20 6f 72 20 65 76 61 6c 75 61 74  )].** or evaluat
1c070 69 6e 67 20 5b 50 52 41 47 4d 41 20 62 75 73 79  ing [PRAGMA busy
1c080 5f 74 69 6d 65 6f 75 74 3d 4e 5d 20 77 69 6c 6c  _timeout=N] will
1c090 20 63 68 61 6e 67 65 20 74 68 65 0a 2a 2a 20 62   change the.** b
1c0a0 75 73 79 20 68 61 6e 64 6c 65 72 20 61 6e 64 20  usy handler and 
1c0b0 74 68 75 73 20 63 6c 65 61 72 20 61 6e 79 20 70  thus clear any p
1c0c0 72 65 76 69 6f 75 73 6c 79 20 73 65 74 20 62 75  reviously set bu
1c0d0 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 0a 2a  sy handler..**.*
1c0e0 2a 20 54 68 65 20 62 75 73 79 20 63 61 6c 6c 62  * The busy callb
1c0f0 61 63 6b 20 73 68 6f 75 6c 64 20 6e 6f 74 20 74  ack should not t
1c100 61 6b 65 20 61 6e 79 20 61 63 74 69 6f 6e 73 20  ake any actions 
1c110 77 68 69 63 68 20 6d 6f 64 69 66 79 20 74 68 65  which modify the
1c120 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e  .** database con
1c130 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76  nection that inv
1c140 6f 6b 65 64 20 74 68 65 20 62 75 73 79 20 68 61  oked the busy ha
1c150 6e 64 6c 65 72 2e 20 20 49 6e 20 6f 74 68 65 72  ndler.  In other
1c160 20 77 6f 72 64 73 2c 0a 2a 2a 20 74 68 65 20 62   words,.** the b
1c170 75 73 79 20 68 61 6e 64 6c 65 72 20 69 73 20 6e  usy handler is n
1c180 6f 74 20 72 65 65 6e 74 72 61 6e 74 2e 20 20 41  ot reentrant.  A
1c190 6e 79 20 73 75 63 68 20 61 63 74 69 6f 6e 73 0a  ny such actions.
1c1a0 2a 2a 20 72 65 73 75 6c 74 20 69 6e 20 75 6e 64  ** result in und
1c1b0 65 66 69 6e 65 64 20 62 65 68 61 76 69 6f 72 2e  efined behavior.
1c1c0 0a 2a 2a 20 0a 2a 2a 20 41 20 62 75 73 79 20 68  .** .** A busy h
1c1d0 61 6e 64 6c 65 72 20 6d 75 73 74 20 6e 6f 74 20  andler must not 
1c1e0 63 6c 6f 73 65 20 74 68 65 20 64 61 74 61 62 61  close the databa
1c1f0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a  se connection.**
1c200 20 6f 72 20 5b 70 72 65 70 61 72 65 64 20 73 74   or [prepared st
1c210 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 69 6e  atement] that in
1c220 76 6f 6b 65 64 20 74 68 65 20 62 75 73 79 20 68  voked the busy h
1c230 61 6e 64 6c 65 72 2e 0a 2a 2f 0a 69 6e 74 20 73  andler..*/.int s
1c240 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64  qlite3_busy_hand
1c250 6c 65 72 28 73 71 6c 69 74 65 33 2a 2c 69 6e 74  ler(sqlite3*,int
1c260 28 2a 29 28 76 6f 69 64 2a 2c 69 6e 74 29 2c 76  (*)(void*,int),v
1c270 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  oid*);../*.** CA
1c280 50 49 33 52 45 46 3a 20 53 65 74 20 41 20 42 75  PI3REF: Set A Bu
1c290 73 79 20 54 69 6d 65 6f 75 74 0a 2a 2a 20 4d 45  sy Timeout.** ME
1c2a0 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a  THOD: sqlite3.**
1c2b0 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e  .** ^This routin
1c2c0 65 20 73 65 74 73 20 61 20 5b 73 71 6c 69 74 65  e sets a [sqlite
1c2d0 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 20 7c  3_busy_handler |
1c2e0 20 62 75 73 79 20 68 61 6e 64 6c 65 72 5d 20 74   busy handler] t
1c2f0 68 61 74 20 73 6c 65 65 70 73 0a 2a 2a 20 66 6f  hat sleeps.** fo
1c300 72 20 61 20 73 70 65 63 69 66 69 65 64 20 61 6d  r a specified am
1c310 6f 75 6e 74 20 6f 66 20 74 69 6d 65 20 77 68 65  ount of time whe
1c320 6e 20 61 20 74 61 62 6c 65 20 69 73 20 6c 6f 63  n a table is loc
1c330 6b 65 64 2e 20 20 5e 54 68 65 20 68 61 6e 64 6c  ked.  ^The handl
1c340 65 72 0a 2a 2a 20 77 69 6c 6c 20 73 6c 65 65 70  er.** will sleep
1c350 20 6d 75 6c 74 69 70 6c 65 20 74 69 6d 65 73 20   multiple times 
1c360 75 6e 74 69 6c 20 61 74 20 6c 65 61 73 74 20 22  until at least "
1c370 6d 73 22 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73  ms" milliseconds
1c380 20 6f 66 20 73 6c 65 65 70 69 6e 67 0a 2a 2a 20   of sleeping.** 
1c390 68 61 76 65 20 61 63 63 75 6d 75 6c 61 74 65 64  have accumulated
1c3a0 2e 20 20 5e 41 66 74 65 72 20 61 74 20 6c 65 61  .  ^After at lea
1c3b0 73 74 20 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63  st "ms" millisec
1c3c0 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 69 6e 67  onds of sleeping
1c3d0 2c 0a 2a 2a 20 74 68 65 20 68 61 6e 64 6c 65 72  ,.** the handler
1c3e0 20 72 65 74 75 72 6e 73 20 30 20 77 68 69 63 68   returns 0 which
1c3f0 20 63 61 75 73 65 73 20 5b 73 71 6c 69 74 65 33   causes [sqlite3
1c400 5f 73 74 65 70 28 29 5d 20 74 6f 20 72 65 74 75  _step()] to retu
1c410 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 42 55  rn.** [SQLITE_BU
1c420 53 59 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c  SY]..**.** ^Call
1c430 69 6e 67 20 74 68 69 73 20 72 6f 75 74 69 6e 65  ing this routine
1c440 20 77 69 74 68 20 61 6e 20 61 72 67 75 6d 65 6e   with an argumen
1c450 74 20 6c 65 73 73 20 74 68 61 6e 20 6f 72 20 65  t less than or e
1c460 71 75 61 6c 20 74 6f 20 7a 65 72 6f 0a 2a 2a 20  qual to zero.** 
1c470 74 75 72 6e 73 20 6f 66 66 20 61 6c 6c 20 62 75  turns off all bu
1c480 73 79 20 68 61 6e 64 6c 65 72 73 2e 0a 2a 2a 0a  sy handlers..**.
1c490 2a 2a 20 5e 28 54 68 65 72 65 20 63 61 6e 20 6f  ** ^(There can o
1c4a0 6e 6c 79 20 62 65 20 61 20 73 69 6e 67 6c 65 20  nly be a single 
1c4b0 62 75 73 79 20 68 61 6e 64 6c 65 72 20 66 6f 72  busy handler for
1c4c0 20 61 20 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a   a particular.**
1c4d0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
1c4e0 63 74 69 6f 6e 5d 20 61 74 20 61 6e 79 20 67 69  ction] at any gi
1c4f0 76 65 6e 20 6d 6f 6d 65 6e 74 2e 20 20 49 66 20  ven moment.  If 
1c500 61 6e 6f 74 68 65 72 20 62 75 73 79 20 68 61 6e  another busy han
1c510 64 6c 65 72 0a 2a 2a 20 77 61 73 20 64 65 66 69  dler.** was defi
1c520 6e 65 64 20 20 28 75 73 69 6e 67 20 5b 73 71 6c  ned  (using [sql
1c530 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65  ite3_busy_handle
1c540 72 28 29 5d 29 20 70 72 69 6f 72 20 74 6f 20 63  r()]) prior to c
1c550 61 6c 6c 69 6e 67 0a 2a 2a 20 74 68 69 73 20 72  alling.** this r
1c560 6f 75 74 69 6e 65 2c 20 74 68 61 74 20 6f 74 68  outine, that oth
1c570 65 72 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20  er busy handler 
1c580 69 73 20 63 6c 65 61 72 65 64 2e 29 5e 0a 2a 2a  is cleared.)^.**
1c590 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 20 5b  .** See also:  [
1c5a0 50 52 41 47 4d 41 20 62 75 73 79 5f 74 69 6d 65  PRAGMA busy_time
1c5b0 6f 75 74 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  out].*/.int sqli
1c5c0 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74  te3_busy_timeout
1c5d0 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6d  (sqlite3*, int m
1c5e0 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  s);../*.** CAPI3
1c5f0 52 45 46 3a 20 43 6f 6e 76 65 6e 69 65 6e 63 65  REF: Convenience
1c600 20 52 6f 75 74 69 6e 65 73 20 46 6f 72 20 52 75   Routines For Ru
1c610 6e 6e 69 6e 67 20 51 75 65 72 69 65 73 0a 2a 2a  nning Queries.**
1c620 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
1c630 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 73 20 61  .**.** This is a
1c640 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 63   legacy interfac
1c650 65 20 74 68 61 74 20 69 73 20 70 72 65 73 65 72  e that is preser
1c660 76 65 64 20 66 6f 72 20 62 61 63 6b 77 61 72 64  ved for backward
1c670 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e  s compatibility.
1c680 0a 2a 2a 20 55 73 65 20 6f 66 20 74 68 69 73 20  .** Use of this 
1c690 69 6e 74 65 72 66 61 63 65 20 69 73 20 6e 6f 74  interface is not
1c6a0 20 72 65 63 6f 6d 6d 65 6e 64 65 64 2e 0a 2a 2a   recommended..**
1c6b0 0a 2a 2a 20 44 65 66 69 6e 69 74 69 6f 6e 3a 20  .** Definition: 
1c6c0 41 20 3c 62 3e 72 65 73 75 6c 74 20 74 61 62 6c  A <b>result tabl
1c6d0 65 3c 2f 62 3e 20 69 73 20 6d 65 6d 6f 72 79 20  e</b> is memory 
1c6e0 64 61 74 61 20 73 74 72 75 63 74 75 72 65 20 63  data structure c
1c6f0 72 65 61 74 65 64 20 62 79 20 74 68 65 0a 2a 2a  reated by the.**
1c700 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61   [sqlite3_get_ta
1c710 62 6c 65 28 29 5d 20 69 6e 74 65 72 66 61 63 65  ble()] interface
1c720 2e 20 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c  .  A result tabl
1c730 65 20 72 65 63 6f 72 64 73 20 74 68 65 0a 2a 2a  e records the.**
1c740 20 63 6f 6d 70 6c 65 74 65 20 71 75 65 72 79 20   complete query 
1c750 72 65 73 75 6c 74 73 20 66 72 6f 6d 20 6f 6e 65  results from one
1c760 20 6f 72 20 6d 6f 72 65 20 71 75 65 72 69 65 73   or more queries
1c770 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 61 62 6c  ..**.** The tabl
1c780 65 20 63 6f 6e 63 65 70 74 75 61 6c 6c 79 20 68  e conceptually h
1c790 61 73 20 61 20 6e 75 6d 62 65 72 20 6f 66 20 72  as a number of r
1c7a0 6f 77 73 20 61 6e 64 20 63 6f 6c 75 6d 6e 73 2e  ows and columns.
1c7b0 20 20 42 75 74 0a 2a 2a 20 74 68 65 73 65 20 6e    But.** these n
1c7c0 75 6d 62 65 72 73 20 61 72 65 20 6e 6f 74 20 70  umbers are not p
1c7d0 61 72 74 20 6f 66 20 74 68 65 20 72 65 73 75 6c  art of the resul
1c7e0 74 20 74 61 62 6c 65 20 69 74 73 65 6c 66 2e 20  t table itself. 
1c7f0 20 54 68 65 73 65 0a 2a 2a 20 6e 75 6d 62 65 72   These.** number
1c800 73 20 61 72 65 20 6f 62 74 61 69 6e 65 64 20 73  s are obtained s
1c810 65 70 61 72 61 74 65 6c 79 2e 20 20 4c 65 74 20  eparately.  Let 
1c820 4e 20 62 65 20 74 68 65 20 6e 75 6d 62 65 72 20  N be the number 
1c830 6f 66 20 72 6f 77 73 0a 2a 2a 20 61 6e 64 20 4d  of rows.** and M
1c840 20 62 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   be the number o
1c850 66 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 0a 2a 2a  f columns..**.**
1c860 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20   A result table 
1c870 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70  is an array of p
1c880 6f 69 6e 74 65 72 73 20 74 6f 20 7a 65 72 6f 2d  ointers to zero-
1c890 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38  terminated UTF-8
1c8a0 20 73 74 72 69 6e 67 73 2e 0a 2a 2a 20 54 68 65   strings..** The
1c8b0 72 65 20 61 72 65 20 28 4e 2b 31 29 2a 4d 20 65  re are (N+1)*M e
1c8c0 6c 65 6d 65 6e 74 73 20 69 6e 20 74 68 65 20 61  lements in the a
1c8d0 72 72 61 79 2e 20 20 54 68 65 20 66 69 72 73 74  rray.  The first
1c8e0 20 4d 20 70 6f 69 6e 74 65 72 73 20 70 6f 69 6e   M pointers poin
1c8f0 74 0a 2a 2a 20 74 6f 20 7a 65 72 6f 2d 74 65 72  t.** to zero-ter
1c900 6d 69 6e 61 74 65 64 20 73 74 72 69 6e 67 73 20  minated strings 
1c910 74 68 61 74 20 20 63 6f 6e 74 61 69 6e 20 74 68  that  contain th
1c920 65 20 6e 61 6d 65 73 20 6f 66 20 74 68 65 20 63  e names of the c
1c930 6f 6c 75 6d 6e 73 2e 0a 2a 2a 20 54 68 65 20 72  olumns..** The r
1c940 65 6d 61 69 6e 69 6e 67 20 65 6e 74 72 69 65 73  emaining entries
1c950 20 61 6c 6c 20 70 6f 69 6e 74 20 74 6f 20 71 75   all point to qu
1c960 65 72 79 20 72 65 73 75 6c 74 73 2e 20 20 4e 55  ery results.  NU
1c970 4c 4c 20 76 61 6c 75 65 73 20 72 65 73 75 6c 74  LL values result
1c980 0a 2a 2a 20 69 6e 20 4e 55 4c 4c 20 70 6f 69 6e  .** in NULL poin
1c990 74 65 72 73 2e 20 20 41 6c 6c 20 6f 74 68 65 72  ters.  All other
1c9a0 20 76 61 6c 75 65 73 20 61 72 65 20 69 6e 20 74   values are in t
1c9b0 68 65 69 72 20 55 54 46 2d 38 20 7a 65 72 6f 2d  heir UTF-8 zero-
1c9c0 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74  terminated.** st
1c9d0 72 69 6e 67 20 72 65 70 72 65 73 65 6e 74 61 74  ring representat
1c9e0 69 6f 6e 20 61 73 20 72 65 74 75 72 6e 65 64 20  ion as returned 
1c9f0 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  by [sqlite3_colu
1ca00 6d 6e 5f 74 65 78 74 28 29 5d 2e 0a 2a 2a 0a 2a  mn_text()]..**.*
1ca10 2a 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65  * A result table
1ca20 20 6d 69 67 68 74 20 63 6f 6e 73 69 73 74 20 6f   might consist o
1ca30 66 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6d 65  f one or more me
1ca40 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73  mory allocations
1ca50 2e 0a 2a 2a 20 49 74 20 69 73 20 6e 6f 74 20 73  ..** It is not s
1ca60 61 66 65 20 74 6f 20 70 61 73 73 20 61 20 72 65  afe to pass a re
1ca70 73 75 6c 74 20 74 61 62 6c 65 20 64 69 72 65 63  sult table direc
1ca80 74 6c 79 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  tly to [sqlite3_
1ca90 66 72 65 65 28 29 5d 2e 0a 2a 2a 20 41 20 72 65  free()]..** A re
1caa0 73 75 6c 74 20 74 61 62 6c 65 20 73 68 6f 75 6c  sult table shoul
1cab0 64 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64  d be deallocated
1cac0 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
1cad0 66 72 65 65 5f 74 61 62 6c 65 28 29 5d 2e 0a 2a  free_table()]..*
1cae0 2a 0a 2a 2a 20 5e 28 41 73 20 61 6e 20 65 78 61  *.** ^(As an exa
1caf0 6d 70 6c 65 20 6f 66 20 74 68 65 20 72 65 73 75  mple of the resu
1cb00 6c 74 20 74 61 62 6c 65 20 66 6f 72 6d 61 74 2c  lt table format,
1cb10 20 73 75 70 70 6f 73 65 20 61 20 71 75 65 72 79   suppose a query
1cb20 20 72 65 73 75 6c 74 0a 2a 2a 20 69 73 20 61 73   result.** is as
1cb30 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20   follows:.**.** 
1cb40 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65  <blockquote><pre
1cb50 3e 0a 2a 2a 20 20 20 20 20 20 20 20 4e 61 6d 65  >.**        Name
1cb60 20 20 20 20 20 20 20 20 7c 20 41 67 65 0a 2a 2a          | Age.**
1cb70 20 20 20 20 20 20 20 20 2d 2d 2d 2d 2d 2d 2d 2d          --------
1cb80 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 0a  ---------------.
1cb90 2a 2a 20 20 20 20 20 20 20 20 41 6c 69 63 65 20  **        Alice 
1cba0 20 20 20 20 20 20 7c 20 34 33 0a 2a 2a 20 20 20        | 43.**   
1cbb0 20 20 20 20 20 42 6f 62 20 20 20 20 20 20 20 20       Bob        
1cbc0 20 7c 20 32 38 0a 2a 2a 20 20 20 20 20 20 20 20   | 28.**        
1cbd0 43 69 6e 64 79 20 20 20 20 20 20 20 7c 20 32 31  Cindy       | 21
1cbe0 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63  .** </pre></bloc
1cbf0 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68  kquote>.**.** Th
1cc00 65 72 65 20 61 72 65 20 74 77 6f 20 63 6f 6c 75  ere are two colu
1cc10 6d 6e 20 28 4d 3d 3d 32 29 20 61 6e 64 20 74 68  mn (M==2) and th
1cc20 72 65 65 20 72 6f 77 73 20 28 4e 3d 3d 33 29 2e  ree rows (N==3).
1cc30 20 20 54 68 75 73 20 74 68 65 0a 2a 2a 20 72 65    Thus the.** re
1cc40 73 75 6c 74 20 74 61 62 6c 65 20 68 61 73 20 38  sult table has 8
1cc50 20 65 6e 74 72 69 65 73 2e 20 20 53 75 70 70 6f   entries.  Suppo
1cc60 73 65 20 74 68 65 20 72 65 73 75 6c 74 20 74 61  se the result ta
1cc70 62 6c 65 20 69 73 20 73 74 6f 72 65 64 0a 2a 2a  ble is stored.**
1cc80 20 69 6e 20 61 6e 20 61 72 72 61 79 20 6e 61 6d   in an array nam
1cc90 65 73 20 61 7a 52 65 73 75 6c 74 2e 20 20 54 68  es azResult.  Th
1cca0 65 6e 20 61 7a 52 65 73 75 6c 74 20 68 6f 6c 64  en azResult hold
1ccb0 73 20 74 68 69 73 20 63 6f 6e 74 65 6e 74 3a 0a  s this content:.
1ccc0 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74  **.** <blockquot
1ccd0 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20  e><pre>.**      
1cce0 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 30    azResult&#91;0
1ccf0 5d 20 3d 20 22 4e 61 6d 65 22 3b 0a 2a 2a 20 20  ] = "Name";.**  
1cd00 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23        azResult&#
1cd10 39 31 3b 31 5d 20 3d 20 22 41 67 65 22 3b 0a 2a  91;1] = "Age";.*
1cd20 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c  *        azResul
1cd30 74 26 23 39 31 3b 32 5d 20 3d 20 22 41 6c 69 63  t&#91;2] = "Alic
1cd40 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a  e";.**        az
1cd50 52 65 73 75 6c 74 26 23 39 31 3b 33 5d 20 3d 20  Result&#91;3] = 
1cd60 22 34 33 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20  "43";.**        
1cd70 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 34 5d 20  azResult&#91;4] 
1cd80 3d 20 22 42 6f 62 22 3b 0a 2a 2a 20 20 20 20 20  = "Bob";.**     
1cd90 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b     azResult&#91;
1cda0 35 5d 20 3d 20 22 32 38 22 3b 0a 2a 2a 20 20 20  5] = "28";.**   
1cdb0 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39       azResult&#9
1cdc0 31 3b 36 5d 20 3d 20 22 43 69 6e 64 79 22 3b 0a  1;6] = "Cindy";.
1cdd0 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75  **        azResu
1cde0 6c 74 26 23 39 31 3b 37 5d 20 3d 20 22 32 31 22  lt&#91;7] = "21"
1cdf0 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f  ;.** </pre></blo
1ce00 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a  ckquote>)^.**.**
1ce10 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65   ^The sqlite3_ge
1ce20 74 5f 74 61 62 6c 65 28 29 20 66 75 6e 63 74 69  t_table() functi
1ce30 6f 6e 20 65 76 61 6c 75 61 74 65 73 20 6f 6e 65  on evaluates one
1ce40 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 73 65 6d 69   or more.** semi
1ce50 63 6f 6c 6f 6e 2d 73 65 70 61 72 61 74 65 64 20  colon-separated 
1ce60 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 69  SQL statements i
1ce70 6e 20 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d 69  n the zero-termi
1ce80 6e 61 74 65 64 20 55 54 46 2d 38 0a 2a 2a 20 73  nated UTF-8.** s
1ce90 74 72 69 6e 67 20 6f 66 20 69 74 73 20 32 6e 64  tring of its 2nd
1cea0 20 70 61 72 61 6d 65 74 65 72 20 61 6e 64 20 72   parameter and r
1ceb0 65 74 75 72 6e 73 20 61 20 72 65 73 75 6c 74 20  eturns a result 
1cec0 74 61 62 6c 65 20 74 6f 20 74 68 65 0a 2a 2a 20  table to the.** 
1ced0 70 6f 69 6e 74 65 72 20 67 69 76 65 6e 20 69 6e  pointer given in
1cee0 20 69 74 73 20 33 72 64 20 70 61 72 61 6d 65 74   its 3rd paramet
1cef0 65 72 2e 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20  er..**.** After 
1cf00 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
1cf10 68 61 73 20 66 69 6e 69 73 68 65 64 20 77 69 74  has finished wit
1cf20 68 20 74 68 65 20 72 65 73 75 6c 74 20 66 72 6f  h the result fro
1cf30 6d 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61  m sqlite3_get_ta
1cf40 62 6c 65 28 29 2c 0a 2a 2a 20 69 74 20 6d 75 73  ble(),.** it mus
1cf50 74 20 70 61 73 73 20 74 68 65 20 72 65 73 75 6c  t pass the resul
1cf60 74 20 74 61 62 6c 65 20 70 6f 69 6e 74 65 72 20  t table pointer 
1cf70 74 6f 20 73 71 6c 69 74 65 33 5f 66 72 65 65 5f  to sqlite3_free_
1cf80 74 61 62 6c 65 28 29 20 69 6e 20 6f 72 64 65 72  table() in order
1cf90 20 74 6f 0a 2a 2a 20 72 65 6c 65 61 73 65 20 74   to.** release t
1cfa0 68 65 20 6d 65 6d 6f 72 79 20 74 68 61 74 20 77  he memory that w
1cfb0 61 73 20 6d 61 6c 6c 6f 63 65 64 2e 20 20 42 65  as malloced.  Be
1cfc0 63 61 75 73 65 20 6f 66 20 74 68 65 20 77 61 79  cause of the way
1cfd0 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
1cfe0 5f 6d 61 6c 6c 6f 63 28 29 5d 20 68 61 70 70 65  _malloc()] happe
1cff0 6e 73 20 77 69 74 68 69 6e 20 73 71 6c 69 74 65  ns within sqlite
1d000 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 2c 20 74  3_get_table(), t
1d010 68 65 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 66 75  he calling.** fu
1d020 6e 63 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20  nction must not 
1d030 74 72 79 20 74 6f 20 63 61 6c 6c 20 5b 73 71 6c  try to call [sql
1d040 69 74 65 33 5f 66 72 65 65 28 29 5d 20 64 69 72  ite3_free()] dir
1d050 65 63 74 6c 79 2e 20 20 4f 6e 6c 79 0a 2a 2a 20  ectly.  Only.** 
1d060 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61  [sqlite3_free_ta
1d070 62 6c 65 28 29 5d 20 69 73 20 61 62 6c 65 20 74  ble()] is able t
1d080 6f 20 72 65 6c 65 61 73 65 20 74 68 65 20 6d 65  o release the me
1d090 6d 6f 72 79 20 70 72 6f 70 65 72 6c 79 20 61 6e  mory properly an
1d0a0 64 20 73 61 66 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20  d safely..**.** 
1d0b0 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f  The sqlite3_get_
1d0c0 74 61 62 6c 65 28 29 20 69 6e 74 65 72 66 61 63  table() interfac
1d0d0 65 20 69 73 20 69 6d 70 6c 65 6d 65 6e 74 65 64  e is implemented
1d0e0 20 61 73 20 61 20 77 72 61 70 70 65 72 20 61 72   as a wrapper ar
1d0f0 6f 75 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ound.** [sqlite3
1d100 5f 65 78 65 63 28 29 5d 2e 20 20 54 68 65 20 73  _exec()].  The s
1d110 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65  qlite3_get_table
1d120 28 29 20 72 6f 75 74 69 6e 65 20 64 6f 65 73 20  () routine does 
1d130 6e 6f 74 20 68 61 76 65 20 61 63 63 65 73 73 0a  not have access.
1d140 2a 2a 20 74 6f 20 61 6e 79 20 69 6e 74 65 72 6e  ** to any intern
1d150 61 6c 20 64 61 74 61 20 73 74 72 75 63 74 75 72  al data structur
1d160 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 49  es of SQLite.  I
1d170 74 20 75 73 65 73 20 6f 6e 6c 79 20 74 68 65 20  t uses only the 
1d180 70 75 62 6c 69 63 0a 2a 2a 20 69 6e 74 65 72 66  public.** interf
1d190 61 63 65 20 64 65 66 69 6e 65 64 20 68 65 72 65  ace defined here
1d1a0 2e 20 20 41 73 20 61 20 63 6f 6e 73 65 71 75 65  .  As a conseque
1d1b0 6e 63 65 2c 20 65 72 72 6f 72 73 20 74 68 61 74  nce, errors that
1d1c0 20 6f 63 63 75 72 20 69 6e 20 74 68 65 0a 2a 2a   occur in the.**
1d1d0 20 77 72 61 70 70 65 72 20 6c 61 79 65 72 20 6f   wrapper layer o
1d1e0 75 74 73 69 64 65 20 6f 66 20 74 68 65 20 69 6e  utside of the in
1d1f0 74 65 72 6e 61 6c 20 5b 73 71 6c 69 74 65 33 5f  ternal [sqlite3_
1d200 65 78 65 63 28 29 5d 20 63 61 6c 6c 20 61 72 65  exec()] call are
1d210 20 6e 6f 74 0a 2a 2a 20 72 65 66 6c 65 63 74 65   not.** reflecte
1d220 64 20 69 6e 20 73 75 62 73 65 71 75 65 6e 74 20  d in subsequent 
1d230 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65  calls to [sqlite
1d240 33 5f 65 72 72 63 6f 64 65 28 29 5d 20 6f 72 0a  3_errcode()] or.
1d250 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d  ** [sqlite3_errm
1d260 73 67 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71  sg()]..*/.int sq
1d270 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28  lite3_get_table(
1d280 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20  .  sqlite3 *db, 
1d290 20 20 20 20 20 20 20 20 20 2f 2a 20 41 6e 20 6f           /* An o
1d2a0 70 65 6e 20 64 61 74 61 62 61 73 65 20 2a 2f 0a  pen database */.
1d2b0 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53    const char *zS
1d2c0 71 6c 2c 20 20 20 20 20 2f 2a 20 53 51 4c 20 74  ql,     /* SQL t
1d2d0 6f 20 62 65 20 65 76 61 6c 75 61 74 65 64 20 2a  o be evaluated *
1d2e0 2f 0a 20 20 63 68 61 72 20 2a 2a 2a 70 61 7a 52  /.  char ***pazR
1d2f0 65 73 75 6c 74 2c 20 20 20 20 2f 2a 20 52 65 73  esult,    /* Res
1d300 75 6c 74 73 20 6f 66 20 74 68 65 20 71 75 65 72  ults of the quer
1d310 79 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e 52 6f  y */.  int *pnRo
1d320 77 2c 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20  w,           /* 
1d330 4e 75 6d 62 65 72 20 6f 66 20 72 65 73 75 6c 74  Number of result
1d340 20 72 6f 77 73 20 77 72 69 74 74 65 6e 20 68 65   rows written he
1d350 72 65 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e 43  re */.  int *pnC
1d360 6f 6c 75 6d 6e 2c 20 20 20 20 20 20 20 20 2f 2a  olumn,        /*
1d370 20 4e 75 6d 62 65 72 20 6f 66 20 72 65 73 75 6c   Number of resul
1d380 74 20 63 6f 6c 75 6d 6e 73 20 77 72 69 74 74 65  t columns writte
1d390 6e 20 68 65 72 65 20 2a 2f 0a 20 20 63 68 61 72  n here */.  char
1d3a0 20 2a 2a 70 7a 45 72 72 6d 73 67 20 20 20 20 20   **pzErrmsg     
1d3b0 20 20 2f 2a 20 45 72 72 6f 72 20 6d 73 67 20 77    /* Error msg w
1d3c0 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29  ritten here */.)
1d3d0 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 66  ;.void sqlite3_f
1d3e0 72 65 65 5f 74 61 62 6c 65 28 63 68 61 72 20 2a  ree_table(char *
1d3f0 2a 72 65 73 75 6c 74 29 3b 0a 0a 2f 2a 0a 2a 2a  *result);../*.**
1d400 20 43 41 50 49 33 52 45 46 3a 20 46 6f 72 6d 61   CAPI3REF: Forma
1d410 74 74 65 64 20 53 74 72 69 6e 67 20 50 72 69 6e  tted String Prin
1d420 74 69 6e 67 20 46 75 6e 63 74 69 6f 6e 73 0a 2a  ting Functions.*
1d430 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
1d440 6e 65 73 20 61 72 65 20 77 6f 72 6b 2d 61 6c 69  nes are work-ali
1d450 6b 65 73 20 6f 66 20 74 68 65 20 22 70 72 69 6e  kes of the "prin
1d460 74 66 28 29 22 20 66 61 6d 69 6c 79 20 6f 66 20  tf()" family of 
1d470 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 66 72 6f  functions.** fro
1d480 6d 20 74 68 65 20 73 74 61 6e 64 61 72 64 20 43  m the standard C
1d490 20 6c 69 62 72 61 72 79 2e 0a 2a 2a 20 54 68 65   library..** The
1d4a0 73 65 20 72 6f 75 74 69 6e 65 73 20 75 6e 64 65  se routines unde
1d4b0 72 73 74 61 6e 64 20 6d 6f 73 74 20 6f 66 20 74  rstand most of t
1d4c0 68 65 20 63 6f 6d 6d 6f 6e 20 4b 26 52 20 66 6f  he common K&R fo
1d4d0 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 73  rmatting options
1d4e0 2c 0a 2a 2a 20 70 6c 75 73 20 73 6f 6d 65 20 61  ,.** plus some a
1d4f0 64 64 69 74 69 6f 6e 61 6c 20 6e 6f 6e 2d 73 74  dditional non-st
1d500 61 6e 64 61 72 64 20 66 6f 72 6d 61 74 73 2c 20  andard formats, 
1d510 64 65 74 61 69 6c 65 64 20 62 65 6c 6f 77 2e 0a  detailed below..
1d520 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 73 6f 6d  ** Note that som
1d530 65 20 6f 66 20 74 68 65 20 6d 6f 72 65 20 6f 62  e of the more ob
1d540 73 63 75 72 65 20 66 6f 72 6d 61 74 74 69 6e 67  scure formatting
1d550 20 6f 70 74 69 6f 6e 73 20 66 72 6f 6d 20 72 65   options from re
1d560 63 65 6e 74 0a 2a 2a 20 43 2d 6c 69 62 72 61 72  cent.** C-librar
1d570 79 20 73 74 61 6e 64 61 72 64 73 20 61 72 65 20  y standards are 
1d580 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 74 68 69  omitted from thi
1d590 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  s implementation
1d5a0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
1d5b0 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 20 61  ite3_mprintf() a
1d5c0 6e 64 20 73 71 6c 69 74 65 33 5f 76 6d 70 72 69  nd sqlite3_vmpri
1d5d0 6e 74 66 28 29 20 72 6f 75 74 69 6e 65 73 20 77  ntf() routines w
1d5e0 72 69 74 65 20 74 68 65 69 72 0a 2a 2a 20 72 65  rite their.** re
1d5f0 73 75 6c 74 73 20 69 6e 74 6f 20 6d 65 6d 6f 72  sults into memor
1d600 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  y obtained from 
1d610 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
1d620 29 5d 2e 0a 2a 2a 20 54 68 65 20 73 74 72 69 6e  )]..** The strin
1d630 67 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 74  gs returned by t
1d640 68 65 73 65 20 74 77 6f 20 72 6f 75 74 69 6e 65  hese two routine
1d650 73 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 72  s should be.** r
1d660 65 6c 65 61 73 65 64 20 62 79 20 5b 73 71 6c 69  eleased by [sqli
1d670 74 65 33 5f 66 72 65 65 28 29 5d 2e 20 20 5e 42  te3_free()].  ^B
1d680 6f 74 68 20 72 6f 75 74 69 6e 65 73 20 72 65 74  oth routines ret
1d690 75 72 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f  urn a.** NULL po
1d6a0 69 6e 74 65 72 20 69 66 20 5b 73 71 6c 69 74 65  inter if [sqlite
1d6b0 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 69 73 20 75  3_malloc()] is u
1d6c0 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74  nable to allocat
1d6d0 65 20 65 6e 6f 75 67 68 0a 2a 2a 20 6d 65 6d 6f  e enough.** memo
1d6e0 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 72  ry to hold the r
1d6f0 65 73 75 6c 74 69 6e 67 20 73 74 72 69 6e 67 2e  esulting string.
1d700 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 73 71 6c  .**.** ^(The sql
1d710 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 20  ite3_snprintf() 
1d720 72 6f 75 74 69 6e 65 20 69 73 20 73 69 6d 69 6c  routine is simil
1d730 61 72 20 74 6f 20 22 73 6e 70 72 69 6e 74 66 28  ar to "snprintf(
1d740 29 22 20 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 73  )" from.** the s
1d750 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72  tandard C librar
1d760 79 2e 20 20 54 68 65 20 72 65 73 75 6c 74 20 69  y.  The result i
1d770 73 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 74  s written into t
1d780 68 65 0a 2a 2a 20 62 75 66 66 65 72 20 73 75 70  he.** buffer sup
1d790 70 6c 69 65 64 20 61 73 20 74 68 65 20 73 65 63  plied as the sec
1d7a0 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 77 68  ond parameter wh
1d7b0 6f 73 65 20 73 69 7a 65 20 69 73 20 67 69 76 65  ose size is give
1d7c0 6e 20 62 79 0a 2a 2a 20 74 68 65 20 66 69 72 73  n by.** the firs
1d7d0 74 20 70 61 72 61 6d 65 74 65 72 2e 20 4e 6f 74  t parameter. Not
1d7e0 65 20 74 68 61 74 20 74 68 65 20 6f 72 64 65 72  e that the order
1d7f0 20 6f 66 20 74 68 65 0a 2a 2a 20 66 69 72 73 74   of the.** first
1d800 20 74 77 6f 20 70 61 72 61 6d 65 74 65 72 73 20   two parameters 
1d810 69 73 20 72 65 76 65 72 73 65 64 20 66 72 6f 6d  is reversed from
1d820 20 73 6e 70 72 69 6e 74 66 28 29 2e 29 5e 20 20   snprintf().)^  
1d830 54 68 69 73 20 69 73 20 61 6e 0a 2a 2a 20 68 69  This is an.** hi
1d840 73 74 6f 72 69 63 61 6c 20 61 63 63 69 64 65 6e  storical acciden
1d850 74 20 74 68 61 74 20 63 61 6e 6e 6f 74 20 62 65  t that cannot be
1d860 20 66 69 78 65 64 20 77 69 74 68 6f 75 74 20 62   fixed without b
1d870 72 65 61 6b 69 6e 67 0a 2a 2a 20 62 61 63 6b 77  reaking.** backw
1d880 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69  ards compatibili
1d890 74 79 2e 20 20 5e 28 4e 6f 74 65 20 61 6c 73 6f  ty.  ^(Note also
1d8a0 20 74 68 61 74 20 73 71 6c 69 74 65 33 5f 73 6e   that sqlite3_sn
1d8b0 70 72 69 6e 74 66 28 29 0a 2a 2a 20 72 65 74 75  printf().** retu
1d8c0 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
1d8d0 20 69 74 73 20 62 75 66 66 65 72 20 69 6e 73 74   its buffer inst
1d8e0 65 61 64 20 6f 66 20 74 68 65 20 6e 75 6d 62 65  ead of the numbe
1d8f0 72 20 6f 66 0a 2a 2a 20 63 68 61 72 61 63 74 65  r of.** characte
1d900 72 73 20 61 63 74 75 61 6c 6c 79 20 77 72 69 74  rs actually writ
1d910 74 65 6e 20 69 6e 74 6f 20 74 68 65 20 62 75 66  ten into the buf
1d920 66 65 72 2e 29 5e 20 20 57 65 20 61 64 6d 69 74  fer.)^  We admit
1d930 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 6e 75 6d   that.** the num
1d940 62 65 72 20 6f 66 20 63 68 61 72 61 63 74 65 72  ber of character
1d950 73 20 77 72 69 74 74 65 6e 20 77 6f 75 6c 64 20  s written would 
1d960 62 65 20 61 20 6d 6f 72 65 20 75 73 65 66 75 6c  be a more useful
1d970 20 72 65 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 65   return.** value
1d980 20 62 75 74 20 77 65 20 63 61 6e 6e 6f 74 20 63   but we cannot c
1d990 68 61 6e 67 65 20 74 68 65 20 69 6d 70 6c 65 6d  hange the implem
1d9a0 65 6e 74 61 74 69 6f 6e 20 6f 66 20 73 71 6c 69  entation of sqli
1d9b0 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a  te3_snprintf().*
1d9c0 2a 20 6e 6f 77 20 77 69 74 68 6f 75 74 20 62 72  * now without br
1d9d0 65 61 6b 69 6e 67 20 63 6f 6d 70 61 74 69 62 69  eaking compatibi
1d9e0 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73 20  lity..**.** ^As 
1d9f0 6c 6f 6e 67 20 61 73 20 74 68 65 20 62 75 66 66  long as the buff
1da00 65 72 20 73 69 7a 65 20 69 73 20 67 72 65 61 74  er size is great
1da10 65 72 20 74 68 61 6e 20 7a 65 72 6f 2c 20 73 71  er than zero, sq
1da20 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29  lite3_snprintf()
1da30 0a 2a 2a 20 67 75 61 72 61 6e 74 65 65 73 20 74  .** guarantees t
1da40 68 61 74 20 74 68 65 20 62 75 66 66 65 72 20 69  hat the buffer i
1da50 73 20 61 6c 77 61 79 73 20 7a 65 72 6f 2d 74 65  s always zero-te
1da60 72 6d 69 6e 61 74 65 64 2e 20 20 5e 54 68 65 20  rminated.  ^The 
1da70 66 69 72 73 74 0a 2a 2a 20 70 61 72 61 6d 65 74  first.** paramet
1da80 65 72 20 22 6e 22 20 69 73 20 74 68 65 20 74 6f  er "n" is the to
1da90 74 61 6c 20 73 69 7a 65 20 6f 66 20 74 68 65 20  tal size of the 
1daa0 62 75 66 66 65 72 2c 20 69 6e 63 6c 75 64 69 6e  buffer, includin
1dab0 67 20 73 70 61 63 65 20 66 6f 72 0a 2a 2a 20 74  g space for.** t
1dac0 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74  he zero terminat
1dad0 6f 72 2e 20 20 53 6f 20 74 68 65 20 6c 6f 6e 67  or.  So the long
1dae0 65 73 74 20 73 74 72 69 6e 67 20 74 68 61 74 20  est string that 
1daf0 63 61 6e 20 62 65 20 63 6f 6d 70 6c 65 74 65 6c  can be completel
1db00 79 0a 2a 2a 20 77 72 69 74 74 65 6e 20 77 69 6c  y.** written wil
1db10 6c 20 62 65 20 6e 2d 31 20 63 68 61 72 61 63 74  l be n-1 charact
1db20 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ers..**.** ^The 
1db30 73 71 6c 69 74 65 33 5f 76 73 6e 70 72 69 6e 74  sqlite3_vsnprint
1db40 66 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20 61  f() routine is a
1db50 20 76 61 72 61 72 67 73 20 76 65 72 73 69 6f 6e   varargs version
1db60 20 6f 66 20 73 71 6c 69 74 65 33 5f 73 6e 70 72   of sqlite3_snpr
1db70 69 6e 74 66 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68  intf()..**.** Th
1db80 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 6c 6c  ese routines all
1db90 20 69 6d 70 6c 65 6d 65 6e 74 20 73 6f 6d 65 20   implement some 
1dba0 61 64 64 69 74 69 6f 6e 61 6c 20 66 6f 72 6d 61  additional forma
1dbb0 74 74 69 6e 67 0a 2a 2a 20 6f 70 74 69 6f 6e 73  tting.** options
1dbc0 20 74 68 61 74 20 61 72 65 20 75 73 65 66 75 6c   that are useful
1dbd0 20 66 6f 72 20 63 6f 6e 73 74 72 75 63 74 69 6e   for constructin
1dbe0 67 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  g SQL statements
1dbf0 2e 0a 2a 2a 20 41 6c 6c 20 6f 66 20 74 68 65 20  ..** All of the 
1dc00 75 73 75 61 6c 20 70 72 69 6e 74 66 28 29 20 66  usual printf() f
1dc10 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e  ormatting option
1dc20 73 20 61 70 70 6c 79 2e 20 20 49 6e 20 61 64 64  s apply.  In add
1dc30 69 74 69 6f 6e 2c 20 74 68 65 72 65 0a 2a 2a 20  ition, there.** 
1dc40 69 73 20 61 72 65 20 22 25 71 22 2c 20 22 25 51  is are "%q", "%Q
1dc50 22 2c 20 22 25 77 22 20 61 6e 64 20 22 25 7a 22  ", "%w" and "%z"
1dc60 20 6f 70 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20   options..**.** 
1dc70 5e 28 54 68 65 20 25 71 20 6f 70 74 69 6f 6e 20  ^(The %q option 
1dc80 77 6f 72 6b 73 20 6c 69 6b 65 20 25 73 20 69 6e  works like %s in
1dc90 20 74 68 61 74 20 69 74 20 73 75 62 73 74 69 74   that it substit
1dca0 75 74 65 73 20 61 20 6e 75 6c 2d 74 65 72 6d 69  utes a nul-termi
1dcb0 6e 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20  nated.** string 
1dcc0 66 72 6f 6d 20 74 68 65 20 61 72 67 75 6d 65 6e  from the argumen
1dcd0 74 20 6c 69 73 74 2e 20 20 42 75 74 20 25 71 20  t list.  But %q 
1dce0 61 6c 73 6f 20 64 6f 75 62 6c 65 73 20 65 76 65  also doubles eve
1dcf0 72 79 20 27 5c 27 27 20 63 68 61 72 61 63 74 65  ry '\'' characte
1dd00 72 2e 0a 2a 2a 20 25 71 20 69 73 20 64 65 73 69  r..** %q is desi
1dd10 67 6e 65 64 20 66 6f 72 20 75 73 65 20 69 6e 73  gned for use ins
1dd20 69 64 65 20 61 20 73 74 72 69 6e 67 20 6c 69 74  ide a string lit
1dd30 65 72 61 6c 2e 29 5e 20 20 42 79 20 64 6f 75 62  eral.)^  By doub
1dd40 6c 69 6e 67 20 65 61 63 68 20 27 5c 27 27 0a 2a  ling each '\''.*
1dd50 2a 20 63 68 61 72 61 63 74 65 72 20 69 74 20 65  * character it e
1dd60 73 63 61 70 65 73 20 74 68 61 74 20 63 68 61 72  scapes that char
1dd70 61 63 74 65 72 20 61 6e 64 20 61 6c 6c 6f 77 73  acter and allows
1dd80 20 69 74 20 74 6f 20 62 65 20 69 6e 73 65 72 74   it to be insert
1dd90 65 64 20 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 73  ed into.** the s
1dda0 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72  tring..**.** For
1ddb0 20 65 78 61 6d 70 6c 65 2c 20 61 73 73 75 6d 65   example, assume
1ddc0 20 74 68 65 20 73 74 72 69 6e 67 20 76 61 72 69   the string vari
1ddd0 61 62 6c 65 20 7a 54 65 78 74 20 63 6f 6e 74 61  able zText conta
1dde0 69 6e 73 20 74 65 78 74 20 61 73 20 66 6f 6c 6c  ins text as foll
1ddf0 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63  ows:.**.** <bloc
1de00 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20  kquote><pre>.** 
1de10 20 63 68 61 72 20 2a 7a 54 65 78 74 20 3d 20 22   char *zText = "
1de20 49 74 27 73 20 61 20 68 61 70 70 79 20 64 61 79  It's a happy day
1de30 21 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62  !";.** </pre></b
1de40 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a  lockquote>.**.**
1de50 20 4f 6e 65 20 63 61 6e 20 75 73 65 20 74 68 69   One can use thi
1de60 73 20 74 65 78 74 20 69 6e 20 61 6e 20 53 51 4c  s text in an SQL
1de70 20 73 74 61 74 65 6d 65 6e 74 20 61 73 20 66 6f   statement as fo
1de80 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c  llows:.**.** <bl
1de90 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a  ockquote><pre>.*
1dea0 2a 20 20 63 68 61 72 20 2a 7a 53 51 4c 20 3d 20  *  char *zSQL = 
1deb0 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28  sqlite3_mprintf(
1dec0 22 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62  "INSERT INTO tab
1ded0 6c 65 20 56 41 4c 55 45 53 28 27 25 71 27 29 22  le VALUES('%q')"
1dee0 2c 20 7a 54 65 78 74 29 3b 0a 2a 2a 20 20 73 71  , zText);.**  sq
1def0 6c 69 74 65 33 5f 65 78 65 63 28 64 62 2c 20 7a  lite3_exec(db, z
1df00 53 51 4c 2c 20 30 2c 20 30 2c 20 30 29 3b 0a 2a  SQL, 0, 0, 0);.*
1df10 2a 20 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28  *  sqlite3_free(
1df20 7a 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e  zSQL);.** </pre>
1df30 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a  </blockquote>.**
1df40 0a 2a 2a 20 42 65 63 61 75 73 65 20 74 68 65 20  .** Because the 
1df50 25 71 20 66 6f 72 6d 61 74 20 73 74 72 69 6e 67  %q format string
1df60 20 69 73 20 75 73 65 64 2c 20 74 68 65 20 27 5c   is used, the '\
1df70 27 27 20 63 68 61 72 61 63 74 65 72 20 69 6e 20  '' character in 
1df80 7a 54 65 78 74 0a 2a 2a 20 69 73 20 65 73 63 61  zText.** is esca
1df90 70 65 64 20 61 6e 64 20 74 68 65 20 53 51 4c 20  ped and the SQL 
1dfa0 67 65 6e 65 72 61 74 65 64 20 69 73 20 61 73 20  generated is as 
1dfb0 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c  follows:.**.** <
1dfc0 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e  blockquote><pre>
1dfd0 0a 2a 2a 20 20 49 4e 53 45 52 54 20 49 4e 54 4f  .**  INSERT INTO
1dfe0 20 74 61 62 6c 65 31 20 56 41 4c 55 45 53 28 27   table1 VALUES('
1dff0 49 74 27 27 73 20 61 20 68 61 70 70 79 20 64 61  It''s a happy da
1e000 79 21 27 29 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f  y!').** </pre></
1e010 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a  blockquote>.**.*
1e020 2a 20 54 68 69 73 20 69 73 20 63 6f 72 72 65 63  * This is correc
1e030 74 2e 20 20 48 61 64 20 77 65 20 75 73 65 64 20  t.  Had we used 
1e040 25 73 20 69 6e 73 74 65 61 64 20 6f 66 20 25 71  %s instead of %q
1e050 2c 20 74 68 65 20 67 65 6e 65 72 61 74 65 64 20  , the generated 
1e060 53 51 4c 0a 2a 2a 20 77 6f 75 6c 64 20 68 61 76  SQL.** would hav
1e070 65 20 6c 6f 6f 6b 65 64 20 6c 69 6b 65 20 74 68  e looked like th
1e080 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  is:.**.** <block
1e090 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20  quote><pre>.**  
1e0a0 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c  INSERT INTO tabl
1e0b0 65 31 20 56 41 4c 55 45 53 28 27 49 74 27 73 20  e1 VALUES('It's 
1e0c0 61 20 68 61 70 70 79 20 64 61 79 21 27 29 3b 0a  a happy day!');.
1e0d0 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b  ** </pre></block
1e0e0 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69  quote>.**.** Thi
1e0f0 73 20 73 65 63 6f 6e 64 20 65 78 61 6d 70 6c 65  s second example
1e100 20 69 73 20 61 6e 20 53 51 4c 20 73 79 6e 74 61   is an SQL synta
1e110 78 20 65 72 72 6f 72 2e 20 20 41 73 20 61 20 67  x error.  As a g
1e120 65 6e 65 72 61 6c 20 72 75 6c 65 20 79 6f 75 20  eneral rule you 
1e130 73 68 6f 75 6c 64 0a 2a 2a 20 61 6c 77 61 79 73  should.** always
1e140 20 75 73 65 20 25 71 20 69 6e 73 74 65 61 64 20   use %q instead 
1e150 6f 66 20 25 73 20 77 68 65 6e 20 69 6e 73 65 72  of %s when inser
1e160 74 69 6e 67 20 74 65 78 74 20 69 6e 74 6f 20 61  ting text into a
1e170 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 2e   string literal.
1e180 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 25 51 20  .**.** ^(The %Q 
1e190 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b  option works lik
1e1a0 65 20 25 71 20 65 78 63 65 70 74 20 69 74 20 61  e %q except it a
1e1b0 6c 73 6f 20 61 64 64 73 20 73 69 6e 67 6c 65 20  lso adds single 
1e1c0 71 75 6f 74 65 73 20 61 72 6f 75 6e 64 0a 2a 2a  quotes around.**
1e1d0 20 74 68 65 20 6f 75 74 73 69 64 65 20 6f 66 20   the outside of 
1e1e0 74 68 65 20 74 6f 74 61 6c 20 73 74 72 69 6e 67  the total string
1e1f0 2e 20 20 41 64 64 69 74 69 6f 6e 61 6c 6c 79 2c  .  Additionally,
1e200 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65   if the paramete
1e210 72 20 69 6e 20 74 68 65 0a 2a 2a 20 61 72 67 75  r in the.** argu
1e220 6d 65 6e 74 20 6c 69 73 74 20 69 73 20 61 20 4e  ment list is a N
1e230 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 25 51 20  ULL pointer, %Q 
1e240 73 75 62 73 74 69 74 75 74 65 73 20 74 68 65 20  substitutes the 
1e250 74 65 78 74 20 22 4e 55 4c 4c 22 20 28 77 69 74  text "NULL" (wit
1e260 68 6f 75 74 0a 2a 2a 20 73 69 6e 67 6c 65 20 71  hout.** single q
1e270 75 6f 74 65 73 29 2e 29 5e 20 20 53 6f 2c 20 66  uotes).)^  So, f
1e280 6f 72 20 65 78 61 6d 70 6c 65 2c 20 6f 6e 65 20  or example, one 
1e290 63 6f 75 6c 64 20 73 61 79 3a 0a 2a 2a 0a 2a 2a  could say:.**.**
1e2a0 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72   <blockquote><pr
1e2b0 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 53 51  e>.**  char *zSQ
1e2c0 4c 20 3d 20 73 71 6c 69 74 65 33 5f 6d 70 72 69  L = sqlite3_mpri
1e2d0 6e 74 66 28 22 49 4e 53 45 52 54 20 49 4e 54 4f  ntf("INSERT INTO
1e2e0 20 74 61 62 6c 65 20 56 41 4c 55 45 53 28 25 51   table VALUES(%Q
1e2f0 29 22 2c 20 7a 54 65 78 74 29 3b 0a 2a 2a 20 20  )", zText);.**  
1e300 73 71 6c 69 74 65 33 5f 65 78 65 63 28 64 62 2c  sqlite3_exec(db,
1e310 20 7a 53 51 4c 2c 20 30 2c 20 30 2c 20 30 29 3b   zSQL, 0, 0, 0);
1e320 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 66 72 65  .**  sqlite3_fre
1e330 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72  e(zSQL);.** </pr
1e340 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a  e></blockquote>.
1e350 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20 61  **.** The code a
1e360 62 6f 76 65 20 77 69 6c 6c 20 72 65 6e 64 65 72  bove will render
1e370 20 61 20 63 6f 72 72 65 63 74 20 53 51 4c 20 73   a correct SQL s
1e380 74 61 74 65 6d 65 6e 74 20 69 6e 20 74 68 65 20  tatement in the 
1e390 7a 53 51 4c 0a 2a 2a 20 76 61 72 69 61 62 6c 65  zSQL.** variable
1e3a0 20 65 76 65 6e 20 69 66 20 74 68 65 20 7a 54 65   even if the zTe
1e3b0 78 74 20 76 61 72 69 61 62 6c 65 20 69 73 20 61  xt variable is a
1e3c0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a   NULL pointer..*
1e3d0 2a 0a 2a 2a 20 5e 28 54 68 65 20 22 25 77 22 20  *.** ^(The "%w" 
1e3e0 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f  formatting optio
1e3f0 6e 20 69 73 20 6c 69 6b 65 20 22 25 71 22 20 65  n is like "%q" e
1e400 78 63 65 70 74 20 74 68 61 74 20 69 74 20 65 78  xcept that it ex
1e410 70 65 63 74 73 20 74 6f 0a 2a 2a 20 62 65 20 63  pects to.** be c
1e420 6f 6e 74 61 69 6e 65 64 20 77 69 74 68 69 6e 20  ontained within 
1e430 64 6f 75 62 6c 65 2d 71 75 6f 74 65 73 20 69 6e  double-quotes in
1e440 73 74 65 61 64 20 6f 66 20 73 69 6e 67 6c 65 20  stead of single 
1e450 71 75 6f 74 65 73 2c 20 61 6e 64 20 69 74 0a 2a  quotes, and it.*
1e460 2a 20 65 73 63 61 70 65 73 20 74 68 65 20 64 6f  * escapes the do
1e470 75 62 6c 65 2d 71 75 6f 74 65 20 63 68 61 72 61  uble-quote chara
1e480 63 74 65 72 20 69 6e 73 74 65 61 64 20 6f 66 20  cter instead of 
1e490 74 68 65 20 73 69 6e 67 6c 65 2d 71 75 6f 74 65  the single-quote
1e4a0 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 2e 29 5e  .** character.)^
1e4b0 20 20 54 68 65 20 22 25 77 22 20 66 6f 72 6d 61    The "%w" forma
1e4c0 74 74 69 6e 67 20 6f 70 74 69 6f 6e 20 69 73 20  tting option is 
1e4d0 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 73 61 66  intended for saf
1e4e0 65 6c 79 20 69 6e 73 65 72 74 69 6e 67 0a 2a 2a  ely inserting.**
1e4f0 20 74 61 62 6c 65 20 61 6e 64 20 63 6f 6c 75 6d   table and colum
1e500 6e 20 6e 61 6d 65 73 20 69 6e 74 6f 20 61 20 63  n names into a c
1e510 6f 6e 73 74 72 75 63 74 65 64 20 53 51 4c 20 73  onstructed SQL s
1e520 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20  tatement..**.** 
1e530 5e 28 54 68 65 20 22 25 7a 22 20 66 6f 72 6d 61  ^(The "%z" forma
1e540 74 74 69 6e 67 20 6f 70 74 69 6f 6e 20 77 6f 72  tting option wor
1e550 6b 73 20 6c 69 6b 65 20 22 25 73 22 20 62 75 74  ks like "%s" but
1e560 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 61 64 64   with the.** add
1e570 69 74 69 6f 6e 20 74 68 61 74 20 61 66 74 65 72  ition that after
1e580 20 74 68 65 20 73 74 72 69 6e 67 20 68 61 73 20   the string has 
1e590 62 65 65 6e 20 72 65 61 64 20 61 6e 64 20 63 6f  been read and co
1e5a0 70 69 65 64 20 69 6e 74 6f 0a 2a 2a 20 74 68 65  pied into.** the
1e5b0 20 72 65 73 75 6c 74 2c 20 5b 73 71 6c 69 74 65   result, [sqlite
1e5c0 33 5f 66 72 65 65 28 29 5d 20 69 73 20 63 61 6c  3_free()] is cal
1e5d0 6c 65 64 20 6f 6e 20 74 68 65 20 69 6e 70 75 74  led on the input
1e5e0 20 73 74 72 69 6e 67 2e 29 5e 0a 2a 2f 0a 63 68   string.)^.*/.ch
1e5f0 61 72 20 2a 73 71 6c 69 74 65 33 5f 6d 70 72 69  ar *sqlite3_mpri
1e600 6e 74 66 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c  ntf(const char*,
1e610 2e 2e 2e 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69  ...);.char *sqli
1e620 74 65 33 5f 76 6d 70 72 69 6e 74 66 28 63 6f 6e  te3_vmprintf(con
1e630 73 74 20 63 68 61 72 2a 2c 20 76 61 5f 6c 69 73  st char*, va_lis
1e640 74 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74 65  t);.char *sqlite
1e650 33 5f 73 6e 70 72 69 6e 74 66 28 69 6e 74 2c 63  3_snprintf(int,c
1e660 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a  har*,const char*
1e670 2c 20 2e 2e 2e 29 3b 0a 63 68 61 72 20 2a 73 71  , ...);.char *sq
1e680 6c 69 74 65 33 5f 76 73 6e 70 72 69 6e 74 66 28  lite3_vsnprintf(
1e690 69 6e 74 2c 63 68 61 72 2a 2c 63 6f 6e 73 74 20  int,char*,const 
1e6a0 63 68 61 72 2a 2c 20 76 61 5f 6c 69 73 74 29 3b  char*, va_list);
1e6b0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1e6c0 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74  : Memory Allocat
1e6d0 69 6f 6e 20 53 75 62 73 79 73 74 65 6d 0a 2a 2a  ion Subsystem.**
1e6e0 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20 63  .** The SQLite c
1e6f0 6f 72 65 20 75 73 65 73 20 74 68 65 73 65 20 74  ore uses these t
1e700 68 72 65 65 20 72 6f 75 74 69 6e 65 73 20 66 6f  hree routines fo
1e710 72 20 61 6c 6c 20 6f 66 20 69 74 73 20 6f 77 6e  r all of its own
1e720 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c 20 6d 65 6d  .** internal mem
1e730 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e  ory allocation n
1e740 65 65 64 73 2e 20 22 43 6f 72 65 22 20 69 6e 20  eeds. "Core" in 
1e750 74 68 65 20 70 72 65 76 69 6f 75 73 20 73 65 6e  the previous sen
1e760 74 65 6e 63 65 0a 2a 2a 20 64 6f 65 73 20 6e 6f  tence.** does no
1e770 74 20 69 6e 63 6c 75 64 65 20 6f 70 65 72 61 74  t include operat
1e780 69 6e 67 2d 73 79 73 74 65 6d 20 73 70 65 63 69  ing-system speci
1e790 66 69 63 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e  fic VFS implemen
1e7a0 74 61 74 69 6f 6e 2e 20 20 54 68 65 0a 2a 2a 20  tation.  The.** 
1e7b0 57 69 6e 64 6f 77 73 20 56 46 53 20 75 73 65 73  Windows VFS uses
1e7c0 20 6e 61 74 69 76 65 20 6d 61 6c 6c 6f 63 28 29   native malloc()
1e7d0 20 61 6e 64 20 66 72 65 65 28 29 20 66 6f 72 20   and free() for 
1e7e0 73 6f 6d 65 20 6f 70 65 72 61 74 69 6f 6e 73 2e  some operations.
1e7f0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
1e800 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 72 6f 75  te3_malloc() rou
1e810 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20 70  tine returns a p
1e820 6f 69 6e 74 65 72 20 74 6f 20 61 20 62 6c 6f 63  ointer to a bloc
1e830 6b 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79 20 61  k.** of memory a
1e840 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73 20  t least N bytes 
1e850 69 6e 20 6c 65 6e 67 74 68 2c 20 77 68 65 72 65  in length, where
1e860 20 4e 20 69 73 20 74 68 65 20 70 61 72 61 6d 65   N is the parame
1e870 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69  ter..** ^If sqli
1e880 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 69 73 20  te3_malloc() is 
1e890 75 6e 61 62 6c 65 20 74 6f 20 6f 62 74 61 69 6e  unable to obtain
1e8a0 20 73 75 66 66 69 63 69 65 6e 74 20 66 72 65 65   sufficient free
1e8b0 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20 69 74 20 72  .** memory, it r
1e8c0 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f  eturns a NULL po
1e8d0 69 6e 74 65 72 2e 20 20 5e 49 66 20 74 68 65 20  inter.  ^If the 
1e8e0 70 61 72 61 6d 65 74 65 72 20 4e 20 74 6f 0a 2a  parameter N to.*
1e8f0 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  * sqlite3_malloc
1e900 28 29 20 69 73 20 7a 65 72 6f 20 6f 72 20 6e 65  () is zero or ne
1e910 67 61 74 69 76 65 20 74 68 65 6e 20 73 71 6c 69  gative then sqli
1e920 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 72 65 74  te3_malloc() ret
1e930 75 72 6e 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70  urns.** a NULL p
1e940 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ointer..**.** ^T
1e950 68 65 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  he sqlite3_mallo
1e960 63 36 34 28 4e 29 20 72 6f 75 74 69 6e 65 20 77  c64(N) routine w
1e970 6f 72 6b 73 20 6a 75 73 74 20 6c 69 6b 65 0a 2a  orks just like.*
1e980 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  * sqlite3_malloc
1e990 28 4e 29 20 65 78 63 65 70 74 20 74 68 61 74 20  (N) except that 
1e9a0 4e 20 69 73 20 61 6e 20 75 6e 73 69 67 6e 65 64  N is an unsigned
1e9b0 20 36 34 2d 62 69 74 20 69 6e 74 65 67 65 72 20   64-bit integer 
1e9c0 69 6e 73 74 65 61 64 0a 2a 2a 20 6f 66 20 61 20  instead.** of a 
1e9d0 73 69 67 6e 65 64 20 33 32 2d 62 69 74 20 69 6e  signed 32-bit in
1e9e0 74 65 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61  teger..**.** ^Ca
1e9f0 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 66 72  lling sqlite3_fr
1ea00 65 65 28 29 20 77 69 74 68 20 61 20 70 6f 69 6e  ee() with a poin
1ea10 74 65 72 20 70 72 65 76 69 6f 75 73 6c 79 20 72  ter previously r
1ea20 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71  eturned.** by sq
1ea30 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f  lite3_malloc() o
1ea40 72 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  r sqlite3_reallo
1ea50 63 28 29 20 72 65 6c 65 61 73 65 73 20 74 68 61  c() releases tha
1ea60 74 20 6d 65 6d 6f 72 79 20 73 6f 0a 2a 2a 20 74  t memory so.** t
1ea70 68 61 74 20 69 74 20 6d 69 67 68 74 20 62 65 20  hat it might be 
1ea80 72 65 75 73 65 64 2e 20 20 5e 54 68 65 20 73 71  reused.  ^The sq
1ea90 6c 69 74 65 33 5f 66 72 65 65 28 29 20 72 6f 75  lite3_free() rou
1eaa0 74 69 6e 65 20 69 73 0a 2a 2a 20 61 20 6e 6f 2d  tine is.** a no-
1eab0 6f 70 20 69 66 20 69 73 20 63 61 6c 6c 65 64 20  op if is called 
1eac0 77 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  with a NULL poin
1ead0 74 65 72 2e 20 20 50 61 73 73 69 6e 67 20 61 20  ter.  Passing a 
1eae0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20  NULL pointer.** 
1eaf0 74 6f 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28  to sqlite3_free(
1eb00 29 20 69 73 20 68 61 72 6d 6c 65 73 73 2e 20 20  ) is harmless.  
1eb10 41 66 74 65 72 20 62 65 69 6e 67 20 66 72 65 65  After being free
1eb20 64 2c 20 6d 65 6d 6f 72 79 0a 2a 2a 20 73 68 6f  d, memory.** sho
1eb30 75 6c 64 20 6e 65 69 74 68 65 72 20 62 65 20 72  uld neither be r
1eb40 65 61 64 20 6e 6f 72 20 77 72 69 74 74 65 6e 2e  ead nor written.
1eb50 20 20 45 76 65 6e 20 72 65 61 64 69 6e 67 20 70    Even reading p
1eb60 72 65 76 69 6f 75 73 6c 79 20 66 72 65 65 64 0a  reviously freed.
1eb70 2a 2a 20 6d 65 6d 6f 72 79 20 6d 69 67 68 74 20  ** memory might 
1eb80 72 65 73 75 6c 74 20 69 6e 20 61 20 73 65 67 6d  result in a segm
1eb90 65 6e 74 61 74 69 6f 6e 20 66 61 75 6c 74 20 6f  entation fault o
1eba0 72 20 6f 74 68 65 72 20 73 65 76 65 72 65 20 65  r other severe e
1ebb0 72 72 6f 72 2e 0a 2a 2a 20 4d 65 6d 6f 72 79 20  rror..** Memory 
1ebc0 63 6f 72 72 75 70 74 69 6f 6e 2c 20 61 20 73 65  corruption, a se
1ebd0 67 6d 65 6e 74 61 74 69 6f 6e 20 66 61 75 6c 74  gmentation fault
1ebe0 2c 20 6f 72 20 6f 74 68 65 72 20 73 65 76 65 72  , or other sever
1ebf0 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 69 67 68 74  e error.** might
1ec00 20 72 65 73 75 6c 74 20 69 66 20 73 71 6c 69 74   result if sqlit
1ec10 65 33 5f 66 72 65 65 28 29 20 69 73 20 63 61 6c  e3_free() is cal
1ec20 6c 65 64 20 77 69 74 68 20 61 20 6e 6f 6e 2d 4e  led with a non-N
1ec30 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 61 74  ULL pointer that
1ec40 0a 2a 2a 20 77 61 73 20 6e 6f 74 20 6f 62 74 61  .** was not obta
1ec50 69 6e 65 64 20 66 72 6f 6d 20 73 71 6c 69 74 65  ined from sqlite
1ec60 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 20 73 71  3_malloc() or sq
1ec70 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e  lite3_realloc().
1ec80 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
1ec90 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29  te3_realloc(X,N)
1eca0 20 69 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d   interface attem
1ecb0 70 74 73 20 74 6f 20 72 65 73 69 7a 65 20 61 0a  pts to resize a.
1ecc0 2a 2a 20 70 72 69 6f 72 20 6d 65 6d 6f 72 79 20  ** prior memory 
1ecd0 61 6c 6c 6f 63 61 74 69 6f 6e 20 58 20 74 6f 20  allocation X to 
1ece0 62 65 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79  be at least N by
1ecf0 74 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  tes..** ^If the 
1ed00 58 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  X parameter to s
1ed10 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58  qlite3_realloc(X
1ed20 2c 4e 29 0a 2a 2a 20 69 73 20 61 20 4e 55 4c 4c  ,N).** is a NULL
1ed30 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 69 74   pointer then it
1ed40 73 20 62 65 68 61 76 69 6f 72 20 69 73 20 69 64  s behavior is id
1ed50 65 6e 74 69 63 61 6c 20 74 6f 20 63 61 6c 6c 69  entical to calli
1ed60 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61  ng.** sqlite3_ma
1ed70 6c 6c 6f 63 28 4e 29 2e 0a 2a 2a 20 5e 49 66 20  lloc(N)..** ^If 
1ed80 74 68 65 20 4e 20 70 61 72 61 6d 65 74 65 72 20  the N parameter 
1ed90 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  to sqlite3_reall
1eda0 6f 63 28 58 2c 4e 29 20 69 73 20 7a 65 72 6f 20  oc(X,N) is zero 
1edb0 6f 72 0a 2a 2a 20 6e 65 67 61 74 69 76 65 20 74  or.** negative t
1edc0 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72  hen the behavior
1edd0 20 69 73 20 65 78 61 63 74 6c 79 20 74 68 65 20   is exactly the 
1ede0 73 61 6d 65 20 61 73 20 63 61 6c 6c 69 6e 67 0a  same as calling.
1edf0 2a 2a 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28  ** sqlite3_free(
1ee00 58 29 2e 0a 2a 2a 20 5e 73 71 6c 69 74 65 33 5f  X)..** ^sqlite3_
1ee10 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 20 72 65 74  realloc(X,N) ret
1ee20 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
1ee30 6f 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  o a memory alloc
1ee40 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 61 74 20 6c  ation.** of at l
1ee50 65 61 73 74 20 4e 20 62 79 74 65 73 20 69 6e 20  east N bytes in 
1ee60 73 69 7a 65 20 6f 72 20 4e 55 4c 4c 20 69 66 20  size or NULL if 
1ee70 69 6e 73 75 66 66 69 63 69 65 6e 74 20 6d 65 6d  insufficient mem
1ee80 6f 72 79 20 69 73 20 61 76 61 69 6c 61 62 6c 65  ory is available
1ee90 2e 0a 2a 2a 20 5e 49 66 20 4d 20 69 73 20 74 68  ..** ^If M is th
1eea0 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 70 72  e size of the pr
1eeb0 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20  ior allocation, 
1eec0 74 68 65 6e 20 6d 69 6e 28 4e 2c 4d 29 20 62 79  then min(N,M) by
1eed0 74 65 73 0a 2a 2a 20 6f 66 20 74 68 65 20 70 72  tes.** of the pr
1eee0 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 61  ior allocation a
1eef0 72 65 20 63 6f 70 69 65 64 20 69 6e 74 6f 20 74  re copied into t
1ef00 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20  he beginning of 
1ef10 62 75 66 66 65 72 20 72 65 74 75 72 6e 65 64 0a  buffer returned.
1ef20 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 72 65  ** by sqlite3_re
1ef30 61 6c 6c 6f 63 28 58 2c 4e 29 20 61 6e 64 20 74  alloc(X,N) and t
1ef40 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74  he prior allocat
1ef50 69 6f 6e 20 69 73 20 66 72 65 65 64 2e 0a 2a 2a  ion is freed..**
1ef60 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 72 65 61   ^If sqlite3_rea
1ef70 6c 6c 6f 63 28 58 2c 4e 29 20 72 65 74 75 72 6e  lloc(X,N) return
1ef80 73 20 4e 55 4c 4c 20 61 6e 64 20 4e 20 69 73 20  s NULL and N is 
1ef90 70 6f 73 69 74 69 76 65 2c 20 74 68 65 6e 20 74  positive, then t
1efa0 68 65 0a 2a 2a 20 70 72 69 6f 72 20 61 6c 6c 6f  he.** prior allo
1efb0 63 61 74 69 6f 6e 20 69 73 20 6e 6f 74 20 66 72  cation is not fr
1efc0 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  eed..**.** ^The 
1efd0 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 36  sqlite3_realloc6
1efe0 34 28 58 2c 4e 29 20 69 6e 74 65 72 66 61 63 65  4(X,N) interface
1eff0 73 20 77 6f 72 6b 73 20 74 68 65 20 73 61 6d 65  s works the same
1f000 20 61 73 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72   as.** sqlite3_r
1f010 65 61 6c 6c 6f 63 28 58 2c 4e 29 20 65 78 63 65  ealloc(X,N) exce
1f020 70 74 20 74 68 61 74 20 4e 20 69 73 20 61 20 36  pt that N is a 6
1f030 34 2d 62 69 74 20 75 6e 73 69 67 6e 65 64 20 69  4-bit unsigned i
1f040 6e 74 65 67 65 72 20 69 6e 73 74 65 61 64 0a 2a  nteger instead.*
1f050 2a 20 6f 66 20 61 20 33 32 2d 62 69 74 20 73 69  * of a 32-bit si
1f060 67 6e 65 64 20 69 6e 74 65 67 65 72 2e 0a 2a 2a  gned integer..**
1f070 0a 2a 2a 20 5e 49 66 20 58 20 69 73 20 61 20 6d  .** ^If X is a m
1f080 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
1f090 20 70 72 65 76 69 6f 75 73 6c 79 20 6f 62 74 61   previously obta
1f0a0 69 6e 65 64 20 66 72 6f 6d 20 73 71 6c 69 74 65  ined from sqlite
1f0b0 33 5f 6d 61 6c 6c 6f 63 28 29 2c 0a 2a 2a 20 73  3_malloc(),.** s
1f0c0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 36 34 28  qlite3_malloc64(
1f0d0 29 2c 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  ), sqlite3_reall
1f0e0 6f 63 28 29 2c 20 6f 72 20 73 71 6c 69 74 65 33  oc(), or sqlite3
1f0f0 5f 72 65 61 6c 6c 6f 63 36 34 28 29 2c 20 74 68  _realloc64(), th
1f100 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 73  en.** sqlite3_ms
1f110 69 7a 65 28 58 29 20 72 65 74 75 72 6e 73 20 74  ize(X) returns t
1f120 68 65 20 73 69 7a 65 20 6f 66 20 74 68 61 74 20  he size of that 
1f130 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
1f140 6e 20 69 6e 20 62 79 74 65 73 2e 0a 2a 2a 20 5e  n in bytes..** ^
1f150 54 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e  The value return
1f160 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 6d 73  ed by sqlite3_ms
1f170 69 7a 65 28 58 29 20 6d 69 67 68 74 20 62 65 20  ize(X) might be 
1f180 6c 61 72 67 65 72 20 74 68 61 6e 20 74 68 65 20  larger than the 
1f190 6e 75 6d 62 65 72 0a 2a 2a 20 6f 66 20 62 79 74  number.** of byt
1f1a0 65 73 20 72 65 71 75 65 73 74 65 64 20 77 68 65  es requested whe
1f1b0 6e 20 58 20 77 61 73 20 61 6c 6c 6f 63 61 74 65  n X was allocate
1f1c0 64 2e 20 20 5e 49 66 20 58 20 69 73 20 61 20 4e  d.  ^If X is a N
1f1d0 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e  ULL pointer then
1f1e0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 73 69 7a  .** sqlite3_msiz
1f1f0 65 28 58 29 20 72 65 74 75 72 6e 73 20 7a 65 72  e(X) returns zer
1f200 6f 2e 20 20 49 66 20 58 20 70 6f 69 6e 74 73 20  o.  If X points 
1f210 74 6f 20 73 6f 6d 65 74 68 69 6e 67 20 74 68 61  to something tha
1f220 74 20 69 73 20 6e 6f 74 0a 2a 2a 20 74 68 65 20  t is not.** the 
1f230 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 6d 65 6d  beginning of mem
1f240 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20  ory allocation, 
1f250 6f 72 20 69 66 20 69 74 20 70 6f 69 6e 74 73 20  or if it points 
1f260 74 6f 20 61 20 66 6f 72 6d 65 72 6c 79 0a 2a 2a  to a formerly.**
1f270 20 76 61 6c 69 64 20 6d 65 6d 6f 72 79 20 61 6c   valid memory al
1f280 6c 6f 63 61 74 69 6f 6e 20 74 68 61 74 20 68 61  location that ha
1f290 73 20 6e 6f 77 20 62 65 65 6e 20 66 72 65 65 64  s now been freed
1f2a0 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76  , then the behav
1f2b0 69 6f 72 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65  ior.** of sqlite
1f2c0 33 5f 6d 73 69 7a 65 28 58 29 20 69 73 20 75 6e  3_msize(X) is un
1f2d0 64 65 66 69 6e 65 64 20 61 6e 64 20 70 6f 73 73  defined and poss
1f2e0 69 62 6c 79 20 68 61 72 6d 66 75 6c 2e 0a 2a 2a  ibly harmful..**
1f2f0 0a 2a 2a 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20  .** ^The memory 
1f300 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69  returned by sqli
1f310 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 2c 20 73 71  te3_malloc(), sq
1f320 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2c  lite3_realloc(),
1f330 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  .** sqlite3_mall
1f340 6f 63 36 34 28 29 2c 20 61 6e 64 20 73 71 6c 69  oc64(), and sqli
1f350 74 65 33 5f 72 65 61 6c 6c 6f 63 36 34 28 29 0a  te3_realloc64().
1f360 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 61 6c 69  ** is always ali
1f370 67 6e 65 64 20 74 6f 20 61 74 20 6c 65 61 73 74  gned to at least
1f380 20 61 6e 20 38 20 62 79 74 65 20 62 6f 75 6e 64   an 8 byte bound
1f390 61 72 79 2c 20 6f 72 20 74 6f 20 61 0a 2a 2a 20  ary, or to a.** 
1f3a0 34 20 62 79 74 65 20 62 6f 75 6e 64 61 72 79 20  4 byte boundary 
1f3b0 69 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 34  if the [SQLITE_4
1f3c0 5f 42 59 54 45 5f 41 4c 49 47 4e 45 44 5f 4d 41  _BYTE_ALIGNED_MA
1f3d0 4c 4c 4f 43 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  LLOC] compile-ti
1f3e0 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e 20 69 73 20  me.** option is 
1f3f0 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 53  used..**.** In S
1f400 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e  QLite version 3.
1f410 35 2e 30 20 61 6e 64 20 33 2e 35 2e 31 2c 20 69  5.0 and 3.5.1, i
1f420 74 20 77 61 73 20 70 6f 73 73 69 62 6c 65 20 74  t was possible t
1f430 6f 20 64 65 66 69 6e 65 0a 2a 2a 20 74 68 65 20  o define.** the 
1f440 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 4d 45 4d 4f  SQLITE_OMIT_MEMO
1f450 52 59 5f 41 4c 4c 4f 43 41 54 49 4f 4e 20 77 68  RY_ALLOCATION wh
1f460 69 63 68 20 77 6f 75 6c 64 20 63 61 75 73 65 20  ich would cause 
1f470 74 68 65 20 62 75 69 6c 74 2d 69 6e 0a 2a 2a 20  the built-in.** 
1f480 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f  implementation o
1f490 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  f these routines
1f4a0 20 74 6f 20 62 65 20 6f 6d 69 74 74 65 64 2e 20   to be omitted. 
1f4b0 20 54 68 61 74 20 63 61 70 61 62 69 6c 69 74 79   That capability
1f4c0 0a 2a 2a 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72  .** is no longer
1f4d0 20 70 72 6f 76 69 64 65 64 2e 20 20 4f 6e 6c 79   provided.  Only
1f4e0 20 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79   built-in memory
1f4f0 20 61 6c 6c 6f 63 61 74 6f 72 73 20 63 61 6e 20   allocators can 
1f500 62 65 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 50  be used..**.** P
1f510 72 69 6f 72 20 74 6f 20 53 51 4c 69 74 65 20 76  rior to SQLite v
1f520 65 72 73 69 6f 6e 20 33 2e 37 2e 31 30 2c 20 74  ersion 3.7.10, t
1f530 68 65 20 57 69 6e 64 6f 77 73 20 4f 53 20 69 6e  he Windows OS in
1f540 74 65 72 66 61 63 65 20 6c 61 79 65 72 20 63 61  terface layer ca
1f550 6c 6c 65 64 0a 2a 2a 20 74 68 65 20 73 79 73 74  lled.** the syst
1f560 65 6d 20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20  em malloc() and 
1f570 66 72 65 65 28 29 20 64 69 72 65 63 74 6c 79 20  free() directly 
1f580 77 68 65 6e 20 63 6f 6e 76 65 72 74 69 6e 67 0a  when converting.
1f590 2a 2a 20 66 69 6c 65 6e 61 6d 65 73 20 62 65 74  ** filenames bet
1f5a0 77 65 65 6e 20 74 68 65 20 55 54 46 2d 38 20 65  ween the UTF-8 e
1f5b0 6e 63 6f 64 69 6e 67 20 75 73 65 64 20 62 79 20  ncoding used by 
1f5c0 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 77 68  SQLite.** and wh
1f5d0 61 74 65 76 65 72 20 66 69 6c 65 6e 61 6d 65 20  atever filename 
1f5e0 65 6e 63 6f 64 69 6e 67 20 69 73 20 75 73 65 64  encoding is used
1f5f0 20 62 79 20 74 68 65 20 70 61 72 74 69 63 75 6c   by the particul
1f600 61 72 20 57 69 6e 64 6f 77 73 0a 2a 2a 20 69 6e  ar Windows.** in
1f610 73 74 61 6c 6c 61 74 69 6f 6e 2e 20 20 4d 65 6d  stallation.  Mem
1f620 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65  ory allocation e
1f630 72 72 6f 72 73 20 77 65 72 65 20 64 65 74 65 63  rrors were detec
1f640 74 65 64 2c 20 62 75 74 0a 2a 2a 20 74 68 65 79  ted, but.** they
1f650 20 77 65 72 65 20 72 65 70 6f 72 74 65 64 20 62   were reported b
1f660 61 63 6b 20 61 73 20 5b 53 51 4c 49 54 45 5f 43  ack as [SQLITE_C
1f670 41 4e 54 4f 50 45 4e 5d 20 6f 72 0a 2a 2a 20 5b  ANTOPEN] or.** [
1f680 53 51 4c 49 54 45 5f 49 4f 45 52 52 5d 20 72 61  SQLITE_IOERR] ra
1f690 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54  ther than [SQLIT
1f6a0 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20  E_NOMEM]..**.** 
1f6b0 54 68 65 20 70 6f 69 6e 74 65 72 20 61 72 67 75  The pointer argu
1f6c0 6d 65 6e 74 73 20 74 6f 20 5b 73 71 6c 69 74 65  ments to [sqlite
1f6d0 33 5f 66 72 65 65 28 29 5d 20 61 6e 64 20 5b 73  3_free()] and [s
1f6e0 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
1f6f0 5d 0a 2a 2a 20 6d 75 73 74 20 62 65 20 65 69 74  ].** must be eit
1f700 68 65 72 20 4e 55 4c 4c 20 6f 72 20 65 6c 73 65  her NULL or else
1f710 20 70 6f 69 6e 74 65 72 73 20 6f 62 74 61 69 6e   pointers obtain
1f720 65 64 20 66 72 6f 6d 20 61 20 70 72 69 6f 72 0a  ed from a prior.
1f730 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66  ** invocation of
1f740 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
1f750 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
1f760 72 65 61 6c 6c 6f 63 28 29 5d 20 74 68 61 74 20  realloc()] that 
1f770 68 61 76 65 0a 2a 2a 20 6e 6f 74 20 79 65 74 20  have.** not yet 
1f780 62 65 65 6e 20 72 65 6c 65 61 73 65 64 2e 0a 2a  been released..*
1f790 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61  *.** The applica
1f7a0 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 72 65  tion must not re
1f7b0 61 64 20 6f 72 20 77 72 69 74 65 20 61 6e 79 20  ad or write any 
1f7c0 70 61 72 74 20 6f 66 0a 2a 2a 20 61 20 62 6c 6f  part of.** a blo
1f7d0 63 6b 20 6f 66 20 6d 65 6d 6f 72 79 20 61 66 74  ck of memory aft
1f7e0 65 72 20 69 74 20 68 61 73 20 62 65 65 6e 20 72  er it has been r
1f7f0 65 6c 65 61 73 65 64 20 75 73 69 6e 67 0a 2a 2a  eleased using.**
1f800 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
1f810 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65  ] or [sqlite3_re
1f820 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 76 6f 69  alloc()]..*/.voi
1f830 64 20 2a 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  d *sqlite3_mallo
1f840 63 28 69 6e 74 29 3b 0a 76 6f 69 64 20 2a 73 71  c(int);.void *sq
1f850 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 36 34 28 73  lite3_malloc64(s
1f860 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 29 3b 0a  qlite3_uint64);.
1f870 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 72 65  void *sqlite3_re
1f880 61 6c 6c 6f 63 28 76 6f 69 64 2a 2c 20 69 6e 74  alloc(void*, int
1f890 29 3b 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  );.void *sqlite3
1f8a0 5f 72 65 61 6c 6c 6f 63 36 34 28 76 6f 69 64 2a  _realloc64(void*
1f8b0 2c 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34  , sqlite3_uint64
1f8c0 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
1f8d0 66 72 65 65 28 76 6f 69 64 2a 29 3b 0a 73 71 6c  free(void*);.sql
1f8e0 69 74 65 33 5f 75 69 6e 74 36 34 20 73 71 6c 69  ite3_uint64 sqli
1f8f0 74 65 33 5f 6d 73 69 7a 65 28 76 6f 69 64 2a 29  te3_msize(void*)
1f900 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
1f910 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61  F: Memory Alloca
1f920 74 6f 72 20 53 74 61 74 69 73 74 69 63 73 0a 2a  tor Statistics.*
1f930 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 70 72 6f 76  *.** SQLite prov
1f940 69 64 65 73 20 74 68 65 73 65 20 74 77 6f 20 69  ides these two i
1f950 6e 74 65 72 66 61 63 65 73 20 66 6f 72 20 72 65  nterfaces for re
1f960 70 6f 72 74 69 6e 67 20 6f 6e 20 74 68 65 20 73  porting on the s
1f970 74 61 74 75 73 0a 2a 2a 20 6f 66 20 74 68 65 20  tatus.** of the 
1f980 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
1f990 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  )], [sqlite3_fre
1f9a0 65 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74  e()], and [sqlit
1f9b0 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a  e3_realloc()].**
1f9c0 20 72 6f 75 74 69 6e 65 73 2c 20 77 68 69 63 68   routines, which
1f9d0 20 66 6f 72 6d 20 74 68 65 20 62 75 69 6c 74 2d   form the built-
1f9e0 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  in memory alloca
1f9f0 74 69 6f 6e 20 73 75 62 73 79 73 74 65 6d 2e 0a  tion subsystem..
1fa00 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69  **.** ^The [sqli
1fa10 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28  te3_memory_used(
1fa20 29 5d 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  )] routine retur
1fa30 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ns the number of
1fa40 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 6d 65 6d   bytes.** of mem
1fa50 6f 72 79 20 63 75 72 72 65 6e 74 6c 79 20 6f 75  ory currently ou
1fa60 74 73 74 61 6e 64 69 6e 67 20 28 6d 61 6c 6c 6f  tstanding (mallo
1fa70 63 65 64 20 62 75 74 20 6e 6f 74 20 66 72 65 65  ced but not free
1fa80 64 29 2e 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c  d)..** ^The [sql
1fa90 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68  ite3_memory_high
1faa0 77 61 74 65 72 28 29 5d 20 72 6f 75 74 69 6e 65  water()] routine
1fab0 20 72 65 74 75 72 6e 73 20 74 68 65 20 6d 61 78   returns the max
1fac0 69 6d 75 6d 0a 2a 2a 20 76 61 6c 75 65 20 6f 66  imum.** value of
1fad0 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79   [sqlite3_memory
1fae0 5f 75 73 65 64 28 29 5d 20 73 69 6e 63 65 20 74  _used()] since t
1faf0 68 65 20 68 69 67 68 2d 77 61 74 65 72 20 6d 61  he high-water ma
1fb00 72 6b 0a 2a 2a 20 77 61 73 20 6c 61 73 74 20 72  rk.** was last r
1fb10 65 73 65 74 2e 20 20 5e 54 68 65 20 76 61 6c 75  eset.  ^The valu
1fb20 65 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b  es returned by [
1fb30 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75  sqlite3_memory_u
1fb40 73 65 64 28 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73  sed()] and.** [s
1fb50 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69  qlite3_memory_hi
1fb60 67 68 77 61 74 65 72 28 29 5d 20 69 6e 63 6c 75  ghwater()] inclu
1fb70 64 65 20 61 6e 79 20 6f 76 65 72 68 65 61 64 0a  de any overhead.
1fb80 2a 2a 20 61 64 64 65 64 20 62 79 20 53 51 4c 69  ** added by SQLi
1fb90 74 65 20 69 6e 20 69 74 73 20 69 6d 70 6c 65 6d  te in its implem
1fba0 65 6e 74 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c  entation of [sql
1fbb0 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 0a  ite3_malloc()],.
1fbc0 2a 2a 20 62 75 74 20 6e 6f 74 20 6f 76 65 72 68  ** but not overh
1fbd0 65 61 64 20 61 64 64 65 64 20 62 79 20 74 68 65  ead added by the
1fbe0 20 61 6e 79 20 75 6e 64 65 72 6c 79 69 6e 67 20   any underlying 
1fbf0 73 79 73 74 65 6d 20 6c 69 62 72 61 72 79 0a 2a  system library.*
1fc00 2a 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20  * routines that 
1fc10 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
1fc20 29 5d 20 6d 61 79 20 63 61 6c 6c 2e 0a 2a 2a 0a  )] may call..**.
1fc30 2a 2a 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20 68  ** ^The memory h
1fc40 69 67 68 2d 77 61 74 65 72 20 6d 61 72 6b 20 69  igh-water mark i
1fc50 73 20 72 65 73 65 74 20 74 6f 20 74 68 65 20 63  s reset to the c
1fc60 75 72 72 65 6e 74 20 76 61 6c 75 65 20 6f 66 0a  urrent value of.
1fc70 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  ** [sqlite3_memo
1fc80 72 79 5f 75 73 65 64 28 29 5d 20 69 66 20 61 6e  ry_used()] if an
1fc90 64 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 70 61  d only if the pa
1fca0 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 73  rameter to.** [s
1fcb0 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69  qlite3_memory_hi
1fcc0 67 68 77 61 74 65 72 28 29 5d 20 69 73 20 74 72  ghwater()] is tr
1fcd0 75 65 2e 20 20 5e 54 68 65 20 76 61 6c 75 65 20  ue.  ^The value 
1fce0 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 5b  returned.** by [
1fcf0 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68  sqlite3_memory_h
1fd00 69 67 68 77 61 74 65 72 28 31 29 5d 20 69 73 20  ighwater(1)] is 
1fd10 74 68 65 20 68 69 67 68 2d 77 61 74 65 72 20 6d  the high-water m
1fd20 61 72 6b 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20  ark.** prior to 
1fd30 74 68 65 20 72 65 73 65 74 2e 0a 2a 2f 0a 73 71  the reset..*/.sq
1fd40 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69  lite3_int64 sqli
1fd50 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28  te3_memory_used(
1fd60 76 6f 69 64 29 3b 0a 73 71 6c 69 74 65 33 5f 69  void);.sqlite3_i
1fd70 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6d 65 6d  nt64 sqlite3_mem
1fd80 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 69 6e  ory_highwater(in
1fd90 74 20 72 65 73 65 74 46 6c 61 67 29 3b 0a 0a 2f  t resetFlag);../
1fda0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 50  *.** CAPI3REF: P
1fdb0 73 65 75 64 6f 2d 52 61 6e 64 6f 6d 20 4e 75 6d  seudo-Random Num
1fdc0 62 65 72 20 47 65 6e 65 72 61 74 6f 72 0a 2a 2a  ber Generator.**
1fdd0 0a 2a 2a 20 53 51 4c 69 74 65 20 63 6f 6e 74 61  .** SQLite conta
1fde0 69 6e 73 20 61 20 68 69 67 68 2d 71 75 61 6c 69  ins a high-quali
1fdf0 74 79 20 70 73 65 75 64 6f 2d 72 61 6e 64 6f 6d  ty pseudo-random
1fe00 20 6e 75 6d 62 65 72 20 67 65 6e 65 72 61 74 6f   number generato
1fe10 72 20 28 50 52 4e 47 29 20 75 73 65 64 20 74 6f  r (PRNG) used to
1fe20 0a 2a 2a 20 73 65 6c 65 63 74 20 72 61 6e 64 6f  .** select rando
1fe30 6d 20 5b 52 4f 57 49 44 20 7c 20 52 4f 57 49 44  m [ROWID | ROWID
1fe40 73 5d 20 77 68 65 6e 20 69 6e 73 65 72 74 69 6e  s] when insertin
1fe50 67 20 6e 65 77 20 72 65 63 6f 72 64 73 20 69 6e  g new records in
1fe60 74 6f 20 61 20 74 61 62 6c 65 20 74 68 61 74 0a  to a table that.
1fe70 2a 2a 20 61 6c 72 65 61 64 79 20 75 73 65 73 20  ** already uses 
1fe80 74 68 65 20 6c 61 72 67 65 73 74 20 70 6f 73 73  the largest poss
1fe90 69 62 6c 65 20 5b 52 4f 57 49 44 5d 2e 20 20 54  ible [ROWID].  T
1fea0 68 65 20 50 52 4e 47 20 69 73 20 61 6c 73 6f 20  he PRNG is also 
1feb0 75 73 65 64 20 66 6f 72 0a 2a 2a 20 74 68 65 20  used for.** the 
1fec0 62 75 69 6c 64 2d 69 6e 20 72 61 6e 64 6f 6d 28  build-in random(
1fed0 29 20 61 6e 64 20 72 61 6e 64 6f 6d 62 6c 6f 62  ) and randomblob
1fee0 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  () SQL functions
1fef0 2e 20 20 54 68 69 73 20 69 6e 74 65 72 66 61 63  .  This interfac
1ff00 65 20 61 6c 6c 6f 77 73 0a 2a 2a 20 61 70 70 6c  e allows.** appl
1ff10 69 63 61 74 69 6f 6e 73 20 74 6f 20 61 63 63 65  ications to acce
1ff20 73 73 20 74 68 65 20 73 61 6d 65 20 50 52 4e 47  ss the same PRNG
1ff30 20 66 6f 72 20 6f 74 68 65 72 20 70 75 72 70 6f   for other purpo
1ff40 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 20 63 61  ses..**.** ^A ca
1ff50 6c 6c 20 74 6f 20 74 68 69 73 20 72 6f 75 74 69  ll to this routi
1ff60 6e 65 20 73 74 6f 72 65 73 20 4e 20 62 79 74 65  ne stores N byte
1ff70 73 20 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20  s of randomness 
1ff80 69 6e 74 6f 20 62 75 66 66 65 72 20 50 2e 0a 2a  into buffer P..*
1ff90 2a 20 5e 54 68 65 20 50 20 70 61 72 61 6d 65 74  * ^The P paramet
1ffa0 65 72 20 63 61 6e 20 62 65 20 61 20 4e 55 4c 4c  er can be a NULL
1ffb0 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20   pointer..**.** 
1ffc0 5e 49 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65  ^If this routine
1ffd0 20 68 61 73 20 6e 6f 74 20 62 65 65 6e 20 70 72   has not been pr
1ffe0 65 76 69 6f 75 73 6c 79 20 63 61 6c 6c 65 64 20  eviously called 
1fff0 6f 72 20 69 66 20 74 68 65 20 70 72 65 76 69 6f  or if the previo
20000 75 73 0a 2a 2a 20 63 61 6c 6c 20 68 61 64 20 4e  us.** call had N
20010 20 6c 65 73 73 20 74 68 61 6e 20 6f 6e 65 20 6f   less than one o
20020 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  r a NULL pointer
20030 20 66 6f 72 20 50 2c 20 74 68 65 6e 20 74 68 65   for P, then the
20040 20 50 52 4e 47 20 69 73 0a 2a 2a 20 73 65 65 64   PRNG is.** seed
20050 65 64 20 75 73 69 6e 67 20 72 61 6e 64 6f 6d 6e  ed using randomn
20060 65 73 73 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  ess obtained fro
20070 6d 20 74 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73  m the xRandomnes
20080 73 20 6d 65 74 68 6f 64 20 6f 66 0a 2a 2a 20 74  s method of.** t
20090 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69  he default [sqli
200a0 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e  te3_vfs] object.
200b0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 70 72 65 76  .** ^If the prev
200c0 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20 74 68 69  ious call to thi
200d0 73 20 72 6f 75 74 69 6e 65 20 68 61 64 20 61 6e  s routine had an
200e0 20 4e 20 6f 66 20 31 20 6f 72 20 6d 6f 72 65 20   N of 1 or more 
200f0 61 6e 64 20 61 0a 2a 2a 20 6e 6f 6e 2d 4e 55 4c  and a.** non-NUL
20100 4c 20 50 20 74 68 65 6e 20 74 68 65 20 70 73 65  L P then the pse
20110 75 64 6f 2d 72 61 6e 64 6f 6d 6e 65 73 73 20 69  udo-randomness i
20120 73 20 67 65 6e 65 72 61 74 65 64 0a 2a 2a 20 69  s generated.** i
20130 6e 74 65 72 6e 61 6c 6c 79 20 61 6e 64 20 77 69  nternally and wi
20140 74 68 6f 75 74 20 72 65 63 6f 75 72 73 65 20 74  thout recourse t
20150 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  o the [sqlite3_v
20160 66 73 5d 20 78 52 61 6e 64 6f 6d 6e 65 73 73 0a  fs] xRandomness.
20170 2a 2a 20 6d 65 74 68 6f 64 2e 0a 2a 2f 0a 76 6f  ** method..*/.vo
20180 69 64 20 73 71 6c 69 74 65 33 5f 72 61 6e 64 6f  id sqlite3_rando
20190 6d 6e 65 73 73 28 69 6e 74 20 4e 2c 20 76 6f 69  mness(int N, voi
201a0 64 20 2a 50 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  d *P);../*.** CA
201b0 50 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c 65 2d  PI3REF: Compile-
201c0 54 69 6d 65 20 41 75 74 68 6f 72 69 7a 61 74 69  Time Authorizati
201d0 6f 6e 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 20  on Callbacks.** 
201e0 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a  METHOD: sqlite3.
201f0 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74  **.** ^This rout
20200 69 6e 65 20 72 65 67 69 73 74 65 72 73 20 61 6e  ine registers an
20210 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
20220 62 61 63 6b 20 77 69 74 68 20 61 20 70 61 72 74  back with a part
20230 69 63 75 6c 61 72 0a 2a 2a 20 5b 64 61 74 61 62  icular.** [datab
20240 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2c  ase connection],
20250 20 73 75 70 70 6c 69 65 64 20 69 6e 20 74 68 65   supplied in the
20260 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e   first argument.
20270 0a 2a 2a 20 5e 54 68 65 20 61 75 74 68 6f 72 69  .** ^The authori
20280 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  zer callback is 
20290 69 6e 76 6f 6b 65 64 20 61 73 20 53 51 4c 20 73  invoked as SQL s
202a0 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20 62 65  tatements are be
202b0 69 6e 67 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20  ing compiled.** 
202c0 62 79 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  by [sqlite3_prep
202d0 61 72 65 28 29 5d 20 6f 72 20 69 74 73 20 76 61  are()] or its va
202e0 72 69 61 6e 74 73 20 5b 73 71 6c 69 74 65 33 5f  riants [sqlite3_
202f0 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 0a 2a  prepare_v2()],.*
20300 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  * [sqlite3_prepa
20310 72 65 31 36 28 29 5d 20 61 6e 64 20 5b 73 71 6c  re16()] and [sql
20320 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
20330 32 28 29 5d 2e 20 20 5e 41 74 20 76 61 72 69 6f  2()].  ^At vario
20340 75 73 0a 2a 2a 20 70 6f 69 6e 74 73 20 64 75 72  us.** points dur
20350 69 6e 67 20 74 68 65 20 63 6f 6d 70 69 6c 61 74  ing the compilat
20360 69 6f 6e 20 70 72 6f 63 65 73 73 2c 20 61 73 20  ion process, as 
20370 6c 6f 67 69 63 20 69 73 20 62 65 69 6e 67 20 63  logic is being c
20380 72 65 61 74 65 64 0a 2a 2a 20 74 6f 20 70 65 72  reated.** to per
20390 66 6f 72 6d 20 76 61 72 69 6f 75 73 20 61 63 74  form various act
203a0 69 6f 6e 73 2c 20 74 68 65 20 61 75 74 68 6f 72  ions, the author
203b0 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73  izer callback is
203c0 20 69 6e 76 6f 6b 65 64 20 74 6f 0a 2a 2a 20 73   invoked to.** s
203d0 65 65 20 69 66 20 74 68 6f 73 65 20 61 63 74 69  ee if those acti
203e0 6f 6e 73 20 61 72 65 20 61 6c 6c 6f 77 65 64 2e  ons are allowed.
203f0 20 20 5e 54 68 65 20 61 75 74 68 6f 72 69 7a 65    ^The authorize
20400 72 20 63 61 6c 6c 62 61 63 6b 20 73 68 6f 75 6c  r callback shoul
20410 64 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c  d.** return [SQL
20420 49 54 45 5f 4f 4b 5d 20 74 6f 20 61 6c 6c 6f 77  ITE_OK] to allow
20430 20 74 68 65 20 61 63 74 69 6f 6e 2c 20 5b 53 51   the action, [SQ
20440 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 6f 20  LITE_IGNORE] to 
20450 64 69 73 61 6c 6c 6f 77 20 74 68 65 0a 2a 2a 20  disallow the.** 
20460 73 70 65 63 69 66 69 63 20 61 63 74 69 6f 6e 20  specific action 
20470 62 75 74 20 61 6c 6c 6f 77 20 74 68 65 20 53 51  but allow the SQ
20480 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 63  L statement to c
20490 6f 6e 74 69 6e 75 65 20 74 6f 20 62 65 0a 2a 2a  ontinue to be.**
204a0 20 63 6f 6d 70 69 6c 65 64 2c 20 6f 72 20 5b 53   compiled, or [S
204b0 51 4c 49 54 45 5f 44 45 4e 59 5d 20 74 6f 20 63  QLITE_DENY] to c
204c0 61 75 73 65 20 74 68 65 20 65 6e 74 69 72 65 20  ause the entire 
204d0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 6f  SQL statement to
204e0 20 62 65 0a 2a 2a 20 72 65 6a 65 63 74 65 64 20   be.** rejected 
204f0 77 69 74 68 20 61 6e 20 65 72 72 6f 72 2e 20 20  with an error.  
20500 5e 49 66 20 74 68 65 20 61 75 74 68 6f 72 69 7a  ^If the authoriz
20510 65 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  er callback retu
20520 72 6e 73 0a 2a 2a 20 61 6e 79 20 76 61 6c 75 65  rns.** any value
20530 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c   other than [SQL
20540 49 54 45 5f 49 47 4e 4f 52 45 5d 2c 20 5b 53 51  ITE_IGNORE], [SQ
20550 4c 49 54 45 5f 4f 4b 5d 2c 20 6f 72 20 5b 53 51  LITE_OK], or [SQ
20560 4c 49 54 45 5f 44 45 4e 59 5d 0a 2a 2a 20 74 68  LITE_DENY].** th
20570 65 6e 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  en the [sqlite3_
20580 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72  prepare_v2()] or
20590 20 65 71 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c   equivalent call
205a0 20 74 68 61 74 20 74 72 69 67 67 65 72 65 64 0a   that triggered.
205b0 2a 2a 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65  ** the authorize
205c0 72 20 77 69 6c 6c 20 66 61 69 6c 20 77 69 74 68  r will fail with
205d0 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67   an error messag
205e0 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68  e..**.** When th
205f0 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  e callback retur
20600 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20  ns [SQLITE_OK], 
20610 74 68 61 74 20 6d 65 61 6e 73 20 74 68 65 20 6f  that means the o
20620 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 72 65 71 75  peration.** requ
20630 65 73 74 65 64 20 69 73 20 6f 6b 2e 20 20 5e 57  ested is ok.  ^W
20640 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  hen the callback
20650 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
20660 5f 44 45 4e 59 5d 2c 20 74 68 65 0a 2a 2a 20 5b  _DENY], the.** [
20670 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
20680 76 32 28 29 5d 20 6f 72 20 65 71 75 69 76 61 6c  v2()] or equival
20690 65 6e 74 20 63 61 6c 6c 20 74 68 61 74 20 74 72  ent call that tr
206a0 69 67 67 65 72 65 64 20 74 68 65 0a 2a 2a 20 61  iggered the.** a
206b0 75 74 68 6f 72 69 7a 65 72 20 77 69 6c 6c 20 66  uthorizer will f
206c0 61 69 6c 20 77 69 74 68 20 61 6e 20 65 72 72 6f  ail with an erro
206d0 72 20 6d 65 73 73 61 67 65 20 65 78 70 6c 61 69  r message explai
206e0 6e 69 6e 67 20 74 68 61 74 0a 2a 2a 20 61 63 63  ning that.** acc
206f0 65 73 73 20 69 73 20 64 65 6e 69 65 64 2e 20 0a  ess is denied. .
20700 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74  **.** ^The first
20710 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
20720 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
20730 6c 62 61 63 6b 20 69 73 20 61 20 63 6f 70 79 20  lback is a copy 
20740 6f 66 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20  of the third.** 
20750 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
20760 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74   sqlite3_set_aut
20770 68 6f 72 69 7a 65 72 28 29 20 69 6e 74 65 72 66  horizer() interf
20780 61 63 65 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64  ace. ^The second
20790 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74 6f   parameter.** to
207a0 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73   the callback is
207b0 20 61 6e 20 69 6e 74 65 67 65 72 20 5b 53 51 4c   an integer [SQL
207c0 49 54 45 5f 43 4f 50 59 20 7c 20 61 63 74 69 6f  ITE_COPY | actio
207d0 6e 20 63 6f 64 65 5d 20 74 68 61 74 20 73 70 65  n code] that spe
207e0 63 69 66 69 65 73 0a 2a 2a 20 74 68 65 20 70 61  cifies.** the pa
207f0 72 74 69 63 75 6c 61 72 20 61 63 74 69 6f 6e 20  rticular action 
20800 74 6f 20 62 65 20 61 75 74 68 6f 72 69 7a 65 64  to be authorized
20810 2e 20 5e 54 68 65 20 74 68 69 72 64 20 74 68 72  . ^The third thr
20820 6f 75 67 68 20 73 69 78 74 68 20 70 61 72 61 6d  ough sixth param
20830 65 74 65 72 73 0a 2a 2a 20 74 6f 20 74 68 65 20  eters.** to the 
20840 63 61 6c 6c 62 61 63 6b 20 61 72 65 20 7a 65 72  callback are zer
20850 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72  o-terminated str
20860 69 6e 67 73 20 74 68 61 74 20 63 6f 6e 74 61 69  ings that contai
20870 6e 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20  n additional.** 
20880 64 65 74 61 69 6c 73 20 61 62 6f 75 74 20 74 68  details about th
20890 65 20 61 63 74 69 6f 6e 20 74 6f 20 62 65 20 61  e action to be a
208a0 75 74 68 6f 72 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a  uthorized..**.**
208b0 20 5e 49 66 20 74 68 65 20 61 63 74 69 6f 6e 20   ^If the action 
208c0 63 6f 64 65 20 69 73 20 5b 53 51 4c 49 54 45 5f  code is [SQLITE_
208d0 52 45 41 44 5d 0a 2a 2a 20 61 6e 64 20 74 68 65  READ].** and the
208e0 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e   callback return
208f0 73 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45  s [SQLITE_IGNORE
20900 5d 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 70  ] then the.** [p
20910 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
20920 74 5d 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  t] statement is 
20930 63 6f 6e 73 74 72 75 63 74 65 64 20 74 6f 20 73  constructed to s
20940 75 62 73 74 69 74 75 74 65 0a 2a 2a 20 61 20 4e  ubstitute.** a N
20950 55 4c 4c 20 76 61 6c 75 65 20 69 6e 20 70 6c 61  ULL value in pla
20960 63 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65 20  ce of the table 
20970 63 6f 6c 75 6d 6e 20 74 68 61 74 20 77 6f 75 6c  column that woul
20980 64 20 68 61 76 65 0a 2a 2a 20 62 65 65 6e 20 72  d have.** been r
20990 65 61 64 20 69 66 20 5b 53 51 4c 49 54 45 5f 4f  ead if [SQLITE_O
209a0 4b 5d 20 68 61 64 20 62 65 65 6e 20 72 65 74 75  K] had been retu
209b0 72 6e 65 64 2e 20 20 54 68 65 20 5b 53 51 4c 49  rned.  The [SQLI
209c0 54 45 5f 49 47 4e 4f 52 45 5d 0a 2a 2a 20 72 65  TE_IGNORE].** re
209d0 74 75 72 6e 20 63 61 6e 20 62 65 20 75 73 65 64  turn can be used
209e0 20 74 6f 20 64 65 6e 79 20 61 6e 20 75 6e 74 72   to deny an untr
209f0 75 73 74 65 64 20 75 73 65 72 20 61 63 63 65 73  usted user acces
20a00 73 20 74 6f 20 69 6e 64 69 76 69 64 75 61 6c 0a  s to individual.
20a10 2a 2a 20 63 6f 6c 75 6d 6e 73 20 6f 66 20 61 20  ** columns of a 
20a20 74 61 62 6c 65 2e 0a 2a 2a 20 5e 49 66 20 74 68  table..** ^If th
20a30 65 20 61 63 74 69 6f 6e 20 63 6f 64 65 20 69 73  e action code is
20a40 20 5b 53 51 4c 49 54 45 5f 44 45 4c 45 54 45 5d   [SQLITE_DELETE]
20a50 20 61 6e 64 20 74 68 65 20 63 61 6c 6c 62 61 63   and the callbac
20a60 6b 20 72 65 74 75 72 6e 73 0a 2a 2a 20 5b 53 51  k returns.** [SQ
20a70 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 68 65  LITE_IGNORE] the
20a80 6e 20 74 68 65 20 5b 44 45 4c 45 54 45 5d 20 6f  n the [DELETE] o
20a90 70 65 72 61 74 69 6f 6e 20 70 72 6f 63 65 65 64  peration proceed
20aa0 73 20 62 75 74 20 74 68 65 0a 2a 2a 20 5b 74 72  s but the.** [tr
20ab0 75 6e 63 61 74 65 20 6f 70 74 69 6d 69 7a 61 74  uncate optimizat
20ac0 69 6f 6e 5d 20 69 73 20 64 69 73 61 62 6c 65 64  ion] is disabled
20ad0 20 61 6e 64 20 61 6c 6c 20 72 6f 77 73 20 61 72   and all rows ar
20ae0 65 20 64 65 6c 65 74 65 64 20 69 6e 64 69 76 69  e deleted indivi
20af0 64 75 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 41 6e  dually..**.** An
20b00 20 61 75 74 68 6f 72 69 7a 65 72 20 69 73 20 75   authorizer is u
20b10 73 65 64 20 77 68 65 6e 20 5b 73 71 6c 69 74 65  sed when [sqlite
20b20 33 5f 70 72 65 70 61 72 65 20 7c 20 70 72 65 70  3_prepare | prep
20b30 61 72 69 6e 67 5d 0a 2a 2a 20 53 51 4c 20 73 74  aring].** SQL st
20b40 61 74 65 6d 65 6e 74 73 20 66 72 6f 6d 20 61 6e  atements from an
20b50 20 75 6e 74 72 75 73 74 65 64 20 73 6f 75 72 63   untrusted sourc
20b60 65 2c 20 74 6f 20 65 6e 73 75 72 65 20 74 68 61  e, to ensure tha
20b70 74 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  t the SQL statem
20b80 65 6e 74 73 0a 2a 2a 20 64 6f 20 6e 6f 74 20 74  ents.** do not t
20b90 72 79 20 74 6f 20 61 63 63 65 73 73 20 64 61 74  ry to access dat
20ba0 61 20 74 68 65 79 20 61 72 65 20 6e 6f 74 20 61  a they are not a
20bb0 6c 6c 6f 77 65 64 20 74 6f 20 73 65 65 2c 20 6f  llowed to see, o
20bc0 72 20 74 68 61 74 20 74 68 65 79 20 64 6f 20 6e  r that they do n
20bd0 6f 74 0a 2a 2a 20 74 72 79 20 74 6f 20 65 78 65  ot.** try to exe
20be0 63 75 74 65 20 6d 61 6c 69 63 69 6f 75 73 20 73  cute malicious s
20bf0 74 61 74 65 6d 65 6e 74 73 20 74 68 61 74 20 64  tatements that d
20c00 61 6d 61 67 65 20 74 68 65 20 64 61 74 61 62 61  amage the databa
20c10 73 65 2e 20 20 46 6f 72 0a 2a 2a 20 65 78 61 6d  se.  For.** exam
20c20 70 6c 65 2c 20 61 6e 20 61 70 70 6c 69 63 61 74  ple, an applicat
20c30 69 6f 6e 20 6d 61 79 20 61 6c 6c 6f 77 20 61 20  ion may allow a 
20c40 75 73 65 72 20 74 6f 20 65 6e 74 65 72 20 61 72  user to enter ar
20c50 62 69 74 72 61 72 79 0a 2a 2a 20 53 51 4c 20 71  bitrary.** SQL q
20c60 75 65 72 69 65 73 20 66 6f 72 20 65 76 61 6c 75  ueries for evalu
20c70 61 74 69 6f 6e 20 62 79 20 61 20 64 61 74 61 62  ation by a datab
20c80 61 73 65 2e 20 20 42 75 74 20 74 68 65 20 61 70  ase.  But the ap
20c90 70 6c 69 63 61 74 69 6f 6e 20 64 6f 65 73 0a 2a  plication does.*
20ca0 2a 20 6e 6f 74 20 77 61 6e 74 20 74 68 65 20 75  * not want the u
20cb0 73 65 72 20 74 6f 20 62 65 20 61 62 6c 65 20 74  ser to be able t
20cc0 6f 20 6d 61 6b 65 20 61 72 62 69 74 72 61 72 79  o make arbitrary
20cd0 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65 0a   changes to the.
20ce0 2a 2a 20 64 61 74 61 62 61 73 65 2e 20 20 41 6e  ** database.  An
20cf0 20 61 75 74 68 6f 72 69 7a 65 72 20 63 6f 75 6c   authorizer coul
20d00 64 20 74 68 65 6e 20 62 65 20 70 75 74 20 69 6e  d then be put in
20d10 20 70 6c 61 63 65 20 77 68 69 6c 65 20 74 68 65   place while the
20d20 0a 2a 2a 20 75 73 65 72 2d 65 6e 74 65 72 65 64  .** user-entered
20d30 20 53 51 4c 20 69 73 20 62 65 69 6e 67 20 5b 73   SQL is being [s
20d40 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 20 7c  qlite3_prepare |
20d50 20 70 72 65 70 61 72 65 64 5d 20 74 68 61 74 0a   prepared] that.
20d60 2a 2a 20 64 69 73 61 6c 6c 6f 77 73 20 65 76 65  ** disallows eve
20d70 72 79 74 68 69 6e 67 20 65 78 63 65 70 74 20 5b  rything except [
20d80 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e  SELECT] statemen
20d90 74 73 2e 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63  ts..**.** Applic
20da0 61 74 69 6f 6e 73 20 74 68 61 74 20 6e 65 65 64  ations that need
20db0 20 74 6f 20 70 72 6f 63 65 73 73 20 53 51 4c 20   to process SQL 
20dc0 66 72 6f 6d 20 75 6e 74 72 75 73 74 65 64 20 73  from untrusted s
20dd0 6f 75 72 63 65 73 0a 2a 2a 20 6d 69 67 68 74 20  ources.** might 
20de0 61 6c 73 6f 20 63 6f 6e 73 69 64 65 72 20 6c 6f  also consider lo
20df0 77 65 72 69 6e 67 20 72 65 73 6f 75 72 63 65 20  wering resource 
20e00 6c 69 6d 69 74 73 20 75 73 69 6e 67 20 5b 73 71  limits using [sq
20e10 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a  lite3_limit()].*
20e20 2a 20 61 6e 64 20 6c 69 6d 69 74 69 6e 67 20 64  * and limiting d
20e30 61 74 61 62 61 73 65 20 73 69 7a 65 20 75 73 69  atabase size usi
20e40 6e 67 20 74 68 65 20 5b 6d 61 78 5f 70 61 67 65  ng the [max_page
20e50 5f 63 6f 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d  _count] [PRAGMA]
20e60 0a 2a 2a 20 69 6e 20 61 64 64 69 74 69 6f 6e 20  .** in addition 
20e70 74 6f 20 75 73 69 6e 67 20 61 6e 20 61 75 74 68  to using an auth
20e80 6f 72 69 7a 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28  orizer..**.** ^(
20e90 4f 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20 61 75  Only a single au
20ea0 74 68 6f 72 69 7a 65 72 20 63 61 6e 20 62 65 20  thorizer can be 
20eb0 69 6e 20 70 6c 61 63 65 20 6f 6e 20 61 20 64 61  in place on a da
20ec0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
20ed0 6e 0a 2a 2a 20 61 74 20 61 20 74 69 6d 65 2e 20  n.** at a time. 
20ee0 20 45 61 63 68 20 63 61 6c 6c 20 74 6f 20 73 71   Each call to sq
20ef0 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72  lite3_set_author
20f00 69 7a 65 72 20 6f 76 65 72 72 69 64 65 73 20 74  izer overrides t
20f10 68 65 0a 2a 2a 20 70 72 65 76 69 6f 75 73 20 63  he.** previous c
20f20 61 6c 6c 2e 29 5e 20 20 5e 44 69 73 61 62 6c 65  all.)^  ^Disable
20f30 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   the authorizer 
20f40 62 79 20 69 6e 73 74 61 6c 6c 69 6e 67 20 61 20  by installing a 
20f50 4e 55 4c 4c 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a  NULL callback..*
20f60 2a 20 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72  * The authorizer
20f70 20 69 73 20 64 69 73 61 62 6c 65 64 20 62 79 20   is disabled by 
20f80 64 65 66 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 54  default..**.** T
20f90 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
20fa0 6c 6c 62 61 63 6b 20 6d 75 73 74 20 6e 6f 74 20  llback must not 
20fb0 64 6f 20 61 6e 79 74 68 69 6e 67 20 74 68 61 74  do anything that
20fc0 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20   will modify.** 
20fd0 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
20fe0 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76  nection that inv
20ff0 6f 6b 65 64 20 74 68 65 20 61 75 74 68 6f 72 69  oked the authori
21000 7a 65 72 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a  zer callback..**
21010 20 4e 6f 74 65 20 74 68 61 74 20 5b 73 71 6c 69   Note that [sqli
21020 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
21030 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73  ] and [sqlite3_s
21040 74 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69  tep()] both modi
21050 66 79 20 74 68 65 69 72 0a 2a 2a 20 64 61 74 61  fy their.** data
21060 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  base connections
21070 20 66 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e 67   for the meaning
21080 20 6f 66 20 22 6d 6f 64 69 66 79 22 20 69 6e 20   of "modify" in 
21090 74 68 69 73 20 70 61 72 61 67 72 61 70 68 2e 0a  this paragraph..
210a0 2a 2a 0a 2a 2a 20 5e 57 68 65 6e 20 5b 73 71 6c  **.** ^When [sql
210b0 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
210c0 29 5d 20 69 73 20 75 73 65 64 20 74 6f 20 70 72  )] is used to pr
210d0 65 70 61 72 65 20 61 20 73 74 61 74 65 6d 65 6e  epare a statemen
210e0 74 2c 20 74 68 65 0a 2a 2a 20 73 74 61 74 65 6d  t, the.** statem
210f0 65 6e 74 20 6d 69 67 68 74 20 62 65 20 72 65 2d  ent might be re-
21100 70 72 65 70 61 72 65 64 20 64 75 72 69 6e 67 20  prepared during 
21110 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
21120 20 64 75 65 20 74 6f 20 61 20 0a 2a 2a 20 73 63   due to a .** sc
21130 68 65 6d 61 20 63 68 61 6e 67 65 2e 20 20 48 65  hema change.  He
21140 6e 63 65 2c 20 74 68 65 20 61 70 70 6c 69 63 61  nce, the applica
21150 74 69 6f 6e 20 73 68 6f 75 6c 64 20 65 6e 73 75  tion should ensu
21160 72 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 63  re that the.** c
21170 6f 72 72 65 63 74 20 61 75 74 68 6f 72 69 7a 65  orrect authorize
21180 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 6d 61 69  r callback remai
21190 6e 73 20 69 6e 20 70 6c 61 63 65 20 64 75 72 69  ns in place duri
211a0 6e 67 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  ng the [sqlite3_
211b0 73 74 65 70 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e  step()]..**.** ^
211c0 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 61 75  Note that the au
211d0 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
211e0 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 6c  k is invoked onl
211f0 79 20 64 75 72 69 6e 67 0a 2a 2a 20 5b 73 71 6c  y during.** [sql
21200 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20  ite3_prepare()] 
21210 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74 73 2e  or its variants.
21220 20 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20    Authorization 
21230 69 73 20 6e 6f 74 0a 2a 2a 20 70 65 72 66 6f 72  is not.** perfor
21240 6d 65 64 20 64 75 72 69 6e 67 20 73 74 61 74 65  med during state
21250 6d 65 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e 20  ment evaluation 
21260 69 6e 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  in [sqlite3_step
21270 28 29 5d 2c 20 75 6e 6c 65 73 73 0a 2a 2a 20 61  ()], unless.** a
21280 73 20 73 74 61 74 65 64 20 69 6e 20 74 68 65 20  s stated in the 
21290 70 72 65 76 69 6f 75 73 20 70 61 72 61 67 72 61  previous paragra
212a0 70 68 2c 20 73 71 6c 69 74 65 33 5f 73 74 65 70  ph, sqlite3_step
212b0 28 29 20 69 6e 76 6f 6b 65 73 0a 2a 2a 20 73 71  () invokes.** sq
212c0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
212d0 28 29 20 74 6f 20 72 65 70 72 65 70 61 72 65 20  () to reprepare 
212e0 61 20 73 74 61 74 65 6d 65 6e 74 20 61 66 74 65  a statement afte
212f0 72 20 61 20 73 63 68 65 6d 61 20 63 68 61 6e 67  r a schema chang
21300 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  e..*/.int sqlite
21310 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72  3_set_authorizer
21320 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 0a 20 20  (.  sqlite3*,.  
21330 69 6e 74 20 28 2a 78 41 75 74 68 29 28 76 6f 69  int (*xAuth)(voi
21340 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61  d*,int,const cha
21350 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63  r*,const char*,c
21360 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74  onst char*,const
21370 20 63 68 61 72 2a 29 2c 0a 20 20 76 6f 69 64 20   char*),.  void 
21380 2a 70 55 73 65 72 44 61 74 61 0a 29 3b 0a 0a 2f  *pUserData.);../
21390 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41  *.** CAPI3REF: A
213a0 75 74 68 6f 72 69 7a 65 72 20 52 65 74 75 72 6e  uthorizer Return
213b0 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65   Codes.**.** The
213c0 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75   [sqlite3_set_au
213d0 74 68 6f 72 69 7a 65 72 20 7c 20 61 75 74 68 6f  thorizer | autho
213e0 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 66  rizer callback f
213f0 75 6e 63 74 69 6f 6e 5d 20 6d 75 73 74 0a 2a 2a  unction] must.**
21400 20 72 65 74 75 72 6e 20 65 69 74 68 65 72 20 5b   return either [
21410 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20 6f 6e  SQLITE_OK] or on
21420 65 20 6f 66 20 74 68 65 73 65 20 74 77 6f 20 63  e of these two c
21430 6f 6e 73 74 61 6e 74 73 20 69 6e 20 6f 72 64 65  onstants in orde
21440 72 0a 2a 2a 20 74 6f 20 73 69 67 6e 61 6c 20 53  r.** to signal S
21450 51 4c 69 74 65 20 77 68 65 74 68 65 72 20 6f 72  QLite whether or
21460 20 6e 6f 74 20 74 68 65 20 61 63 74 69 6f 6e 20   not the action 
21470 69 73 20 70 65 72 6d 69 74 74 65 64 2e 20 20 53  is permitted.  S
21480 65 65 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  ee the.** [sqlit
21490 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65  e3_set_authorize
214a0 72 20 7c 20 61 75 74 68 6f 72 69 7a 65 72 20 64  r | authorizer d
214b0 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 5d 20 66 6f  ocumentation] fo
214c0 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20  r additional.** 
214d0 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a  information..**.
214e0 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 53 51 4c  ** Note that SQL
214f0 49 54 45 5f 49 47 4e 4f 52 45 20 69 73 20 61 6c  ITE_IGNORE is al
21500 73 6f 20 75 73 65 64 20 61 73 20 61 20 5b 63 6f  so used as a [co
21510 6e 66 6c 69 63 74 20 72 65 73 6f 6c 75 74 69 6f  nflict resolutio
21520 6e 20 6d 6f 64 65 5d 0a 2a 2a 20 72 65 74 75 72  n mode].** retur
21530 6e 65 64 20 66 72 6f 6d 20 74 68 65 20 5b 73 71  ned from the [sq
21540 6c 69 74 65 33 5f 76 74 61 62 5f 6f 6e 5f 63 6f  lite3_vtab_on_co
21550 6e 66 6c 69 63 74 28 29 5d 20 69 6e 74 65 72 66  nflict()] interf
21560 61 63 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  ace..*/.#define 
21570 53 51 4c 49 54 45 5f 44 45 4e 59 20 20 20 31 20  SQLITE_DENY   1 
21580 20 20 2f 2a 20 41 62 6f 72 74 20 74 68 65 20 53    /* Abort the S
21590 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74  QL statement wit
215a0 68 20 61 6e 20 65 72 72 6f 72 20 2a 2f 0a 23 64  h an error */.#d
215b0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 47 4e  efine SQLITE_IGN
215c0 4f 52 45 20 32 20 20 20 2f 2a 20 44 6f 6e 27 74  ORE 2   /* Don't
215d0 20 61 6c 6c 6f 77 20 61 63 63 65 73 73 2c 20 62   allow access, b
215e0 75 74 20 64 6f 6e 27 74 20 67 65 6e 65 72 61 74  ut don't generat
215f0 65 20 61 6e 20 65 72 72 6f 72 20 2a 2f 0a 0a 2f  e an error */../
21600 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41  *.** CAPI3REF: A
21610 75 74 68 6f 72 69 7a 65 72 20 41 63 74 69 6f 6e  uthorizer Action
21620 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65   Codes.**.** The
21630 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75   [sqlite3_set_au
21640 74 68 6f 72 69 7a 65 72 28 29 5d 20 69 6e 74 65  thorizer()] inte
21650 72 66 61 63 65 20 72 65 67 69 73 74 65 72 73 20  rface registers 
21660 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  a callback funct
21670 69 6f 6e 0a 2a 2a 20 74 68 61 74 20 69 73 20 69  ion.** that is i
21680 6e 76 6f 6b 65 64 20 74 6f 20 61 75 74 68 6f 72  nvoked to author
21690 69 7a 65 20 63 65 72 74 61 69 6e 20 53 51 4c 20  ize certain SQL 
216a0 73 74 61 74 65 6d 65 6e 74 20 61 63 74 69 6f 6e  statement action
216b0 73 2e 20 20 54 68 65 0a 2a 2a 20 73 65 63 6f 6e  s.  The.** secon
216c0 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  d parameter to t
216d0 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61  he callback is a
216e0 6e 20 69 6e 74 65 67 65 72 20 63 6f 64 65 20 74  n integer code t
216f0 68 61 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a  hat specifies.**
21700 20 77 68 61 74 20 61 63 74 69 6f 6e 20 69 73 20   what action is 
21710 62 65 69 6e 67 20 61 75 74 68 6f 72 69 7a 65 64  being authorized
21720 2e 20 20 54 68 65 73 65 20 61 72 65 20 74 68 65  .  These are the
21730 20 69 6e 74 65 67 65 72 20 61 63 74 69 6f 6e 20   integer action 
21740 63 6f 64 65 73 20 74 68 61 74 0a 2a 2a 20 74 68  codes that.** th
21750 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
21760 6c 62 61 63 6b 20 6d 61 79 20 62 65 20 70 61 73  lback may be pas
21770 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  sed..**.** These
21780 20 61 63 74 69 6f 6e 20 63 6f 64 65 20 76 61 6c   action code val
21790 75 65 73 20 73 69 67 6e 69 66 79 20 77 68 61 74  ues signify what
217a0 20 6b 69 6e 64 20 6f 66 20 6f 70 65 72 61 74 69   kind of operati
217b0 6f 6e 20 69 73 20 74 6f 20 62 65 0a 2a 2a 20 61  on is to be.** a
217c0 75 74 68 6f 72 69 7a 65 64 2e 20 20 54 68 65 20  uthorized.  The 
217d0 33 72 64 20 61 6e 64 20 34 74 68 20 70 61 72 61  3rd and 4th para
217e0 6d 65 74 65 72 73 20 74 6f 20 74 68 65 20 61 75  meters to the au
217f0 74 68 6f 72 69 7a 61 74 69 6f 6e 0a 2a 2a 20 63  thorization.** c
21800 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
21810 20 77 69 6c 6c 20 62 65 20 70 61 72 61 6d 65 74   will be paramet
21820 65 72 73 20 6f 72 20 4e 55 4c 4c 20 64 65 70 65  ers or NULL depe
21830 6e 64 69 6e 67 20 6f 6e 20 77 68 69 63 68 20 6f  nding on which o
21840 66 20 74 68 65 73 65 0a 2a 2a 20 63 6f 64 65 73  f these.** codes
21850 20 69 73 20 75 73 65 64 20 61 73 20 74 68 65 20   is used as the 
21860 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
21870 2e 20 20 5e 28 54 68 65 20 35 74 68 20 70 61 72  .  ^(The 5th par
21880 61 6d 65 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a  ameter to the.**
21890 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
218a0 62 61 63 6b 20 69 73 20 74 68 65 20 6e 61 6d 65  back is the name
218b0 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65   of the database
218c0 20 28 22 6d 61 69 6e 22 2c 20 22 74 65 6d 70 22   ("main", "temp"
218d0 2c 0a 2a 2a 20 65 74 63 2e 29 20 69 66 20 61 70  ,.** etc.) if ap
218e0 70 6c 69 63 61 62 6c 65 2e 29 5e 20 20 5e 54 68  plicable.)^  ^Th
218f0 65 20 36 74 68 20 70 61 72 61 6d 65 74 65 72 20  e 6th parameter 
21900 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65  to the authorize
21910 72 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73  r callback.** is
21920 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
21930 20 69 6e 6e 65 72 2d 6d 6f 73 74 20 74 72 69 67   inner-most trig
21940 67 65 72 20 6f 72 20 76 69 65 77 20 74 68 61 74  ger or view that
21950 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20   is responsible 
21960 66 6f 72 0a 2a 2a 20 74 68 65 20 61 63 63 65 73  for.** the acces
21970 73 20 61 74 74 65 6d 70 74 20 6f 72 20 4e 55 4c  s attempt or NUL
21980 4c 20 69 66 20 74 68 69 73 20 61 63 63 65 73 73  L if this access
21990 20 61 74 74 65 6d 70 74 20 69 73 20 64 69 72 65   attempt is dire
219a0 63 74 6c 79 20 66 72 6f 6d 0a 2a 2a 20 74 6f 70  ctly from.** top
219b0 2d 6c 65 76 65 6c 20 53 51 4c 20 63 6f 64 65 2e  -level SQL code.
219c0 0a 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  .*/./***********
219d0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
219e0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
219f0 20 33 72 64 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a   3rd ***********
21a00 2a 20 34 74 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  * 4th **********
21a10 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
21a20 45 5f 43 52 45 41 54 45 5f 49 4e 44 45 58 20 20  E_CREATE_INDEX  
21a30 20 20 20 20 20 20 20 20 31 20 20 20 2f 2a 20 49          1   /* I
21a40 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54  ndex Name      T
21a50 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a  able Name      *
21a60 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
21a70 5f 43 52 45 41 54 45 5f 54 41 42 4c 45 20 20 20  _CREATE_TABLE   
21a80 20 20 20 20 20 20 20 32 20 20 20 2f 2a 20 54 61         2   /* Ta
21a90 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55  ble Name      NU
21aa0 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
21ab0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
21ac0 43 52 45 41 54 45 5f 54 45 4d 50 5f 49 4e 44 45  CREATE_TEMP_INDE
21ad0 58 20 20 20 20 20 33 20 20 20 2f 2a 20 49 6e 64  X     3   /* Ind
21ae0 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62  ex Name      Tab
21af0 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a  le Name      */.
21b00 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
21b10 52 45 41 54 45 5f 54 45 4d 50 5f 54 41 42 4c 45  REATE_TEMP_TABLE
21b20 20 20 20 20 20 34 20 20 20 2f 2a 20 54 61 62 6c       4   /* Tabl
21b30 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c  e Name      NULL
21b40 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
21b50 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52  define SQLITE_CR
21b60 45 41 54 45 5f 54 45 4d 50 5f 54 52 49 47 47 45  EATE_TEMP_TRIGGE
21b70 52 20 20 20 35 20 20 20 2f 2a 20 54 72 69 67 67  R   5   /* Trigg
21b80 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65  er Name    Table
21b90 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64   Name      */.#d
21ba0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45  efine SQLITE_CRE
21bb0 41 54 45 5f 54 45 4d 50 5f 56 49 45 57 20 20 20  ATE_TEMP_VIEW   
21bc0 20 20 20 36 20 20 20 2f 2a 20 56 69 65 77 20 4e     6   /* View N
21bd0 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20  ame       NULL  
21be0 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
21bf0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41  fine SQLITE_CREA
21c00 54 45 5f 54 52 49 47 47 45 52 20 20 20 20 20 20  TE_TRIGGER      
21c10 20 20 37 20 20 20 2f 2a 20 54 72 69 67 67 65 72    7   /* Trigger
21c20 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e   Name    Table N
21c30 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66  ame      */.#def
21c40 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54  ine SQLITE_CREAT
21c50 45 5f 56 49 45 57 20 20 20 20 20 20 20 20 20 20  E_VIEW          
21c60 20 38 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d   8   /* View Nam
21c70 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  e       NULL    
21c80 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
21c90 6e 65 20 53 51 4c 49 54 45 5f 44 45 4c 45 54 45  ne SQLITE_DELETE
21ca0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
21cb0 39 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  9   /* Table Nam
21cc0 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20  e      NULL     
21cd0 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
21ce0 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 49 4e  e SQLITE_DROP_IN
21cf0 44 45 58 20 20 20 20 20 20 20 20 20 20 20 31 30  DEX           10
21d00 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65     /* Index Name
21d10 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65        Table Name
21d20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
21d30 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 41 42   SQLITE_DROP_TAB
21d40 4c 45 20 20 20 20 20 20 20 20 20 20 20 31 31 20  LE           11 
21d50 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20    /* Table Name 
21d60 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
21d70 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
21d80 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50  SQLITE_DROP_TEMP
21d90 5f 49 4e 44 45 58 20 20 20 20 20 20 31 32 20 20  _INDEX      12  
21da0 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20   /* Index Name  
21db0 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20      Table Name  
21dc0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
21dd0 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f  QLITE_DROP_TEMP_
21de0 54 41 42 4c 45 20 20 20 20 20 20 31 33 20 20 20  TABLE      13   
21df0 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
21e00 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
21e10 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
21e20 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 54  LITE_DROP_TEMP_T
21e30 52 49 47 47 45 52 20 20 20 20 31 34 20 20 20 2f  RIGGER    14   /
21e40 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20  * Trigger Name  
21e50 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20    Table Name    
21e60 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
21e70 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 56 49  ITE_DROP_TEMP_VI
21e80 45 57 20 20 20 20 20 20 20 31 35 20 20 20 2f 2a  EW       15   /*
21e90 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20   View Name      
21ea0 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
21eb0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
21ec0 54 45 5f 44 52 4f 50 5f 54 52 49 47 47 45 52 20  TE_DROP_TRIGGER 
21ed0 20 20 20 20 20 20 20 20 31 36 20 20 20 2f 2a 20          16   /* 
21ee0 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20  Trigger Name    
21ef0 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
21f00 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
21f10 45 5f 44 52 4f 50 5f 56 49 45 57 20 20 20 20 20  E_DROP_VIEW     
21f20 20 20 20 20 20 20 20 31 37 20 20 20 2f 2a 20 56         17   /* V
21f30 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e  iew Name       N
21f40 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
21f50 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
21f60 5f 49 4e 53 45 52 54 20 20 20 20 20 20 20 20 20  _INSERT         
21f70 20 20 20 20 20 20 31 38 20 20 20 2f 2a 20 54 61        18   /* Ta
21f80 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55  ble Name      NU
21f90 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
21fa0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
21fb0 50 52 41 47 4d 41 20 20 20 20 20 20 20 20 20 20  PRAGMA          
21fc0 20 20 20 20 20 31 39 20 20 20 2f 2a 20 50 72 61       19   /* Pra
21fd0 67 6d 61 20 4e 61 6d 65 20 20 20 20 20 31 73 74  gma Name     1st
21fe0 20 61 72 67 20 6f 72 20 4e 55 4c 4c 20 2a 2f 0a   arg or NULL */.
21ff0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52  #define SQLITE_R
22000 45 41 44 20 20 20 20 20 20 20 20 20 20 20 20 20  EAD             
22010 20 20 20 20 32 30 20 20 20 2f 2a 20 54 61 62 6c      20   /* Tabl
22020 65 20 4e 61 6d 65 20 20 20 20 20 20 43 6f 6c 75  e Name      Colu
22030 6d 6e 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23  mn Name     */.#
22040 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 45  define SQLITE_SE
22050 4c 45 43 54 20 20 20 20 20 20 20 20 20 20 20 20  LECT            
22060 20 20 20 32 31 20 20 20 2f 2a 20 4e 55 4c 4c 20     21   /* NULL 
22070 20 20 20 20 20 20 20 20 20 20 20 4e 55 4c 4c 20             NULL 
22080 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
22090 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 52 41  efine SQLITE_TRA
220a0 4e 53 41 43 54 49 4f 4e 20 20 20 20 20 20 20 20  NSACTION        
220b0 20 20 32 32 20 20 20 2f 2a 20 4f 70 65 72 61 74    22   /* Operat
220c0 69 6f 6e 20 20 20 20 20 20 20 4e 55 4c 4c 20 20  ion       NULL  
220d0 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
220e0 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 50 44 41  fine SQLITE_UPDA
220f0 54 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20  TE              
22100 20 32 33 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e   23   /* Table N
22110 61 6d 65 20 20 20 20 20 20 43 6f 6c 75 6d 6e 20  ame      Column 
22120 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66  Name     */.#def
22130 69 6e 65 20 53 51 4c 49 54 45 5f 41 54 54 41 43  ine SQLITE_ATTAC
22140 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  H               
22150 32 34 20 20 20 2f 2a 20 46 69 6c 65 6e 61 6d 65  24   /* Filename
22160 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20          NULL    
22170 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
22180 6e 65 20 53 51 4c 49 54 45 5f 44 45 54 41 43 48  ne SQLITE_DETACH
22190 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32                 2
221a0 35 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20  5   /* Database 
221b0 4e 61 6d 65 20 20 20 4e 55 4c 4c 20 20 20 20 20  Name   NULL     
221c0 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
221d0 65 20 53 51 4c 49 54 45 5f 41 4c 54 45 52 5f 54  e SQLITE_ALTER_T
221e0 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 32 36  ABLE          26
221f0 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 4e     /* Database N
22200 61 6d 65 20 20 20 54 61 62 6c 65 20 4e 61 6d 65  ame   Table Name
22210 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
22220 20 53 51 4c 49 54 45 5f 52 45 49 4e 44 45 58 20   SQLITE_REINDEX 
22230 20 20 20 20 20 20 20 20 20 20 20 20 20 32 37 20               27 
22240 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20    /* Index Name 
22250 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
22260 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
22270 53 51 4c 49 54 45 5f 41 4e 41 4c 59 5a 45 20 20  SQLITE_ANALYZE  
22280 20 20 20 20 20 20 20 20 20 20 20 20 32 38 20 20              28  
22290 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
222a0 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
222b0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
222c0 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 56 54 41  QLITE_CREATE_VTA
222d0 42 4c 45 20 20 20 20 20 20 20 20 32 39 20 20 20  BLE        29   
222e0 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
222f0 20 20 20 4d 6f 64 75 6c 65 20 4e 61 6d 65 20 20     Module Name  
22300 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
22310 4c 49 54 45 5f 44 52 4f 50 5f 56 54 41 42 4c 45  LITE_DROP_VTABLE
22320 20 20 20 20 20 20 20 20 20 20 33 30 20 20 20 2f            30   /
22330 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
22340 20 20 4d 6f 64 75 6c 65 20 4e 61 6d 65 20 20 20    Module Name   
22350 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
22360 49 54 45 5f 46 55 4e 43 54 49 4f 4e 20 20 20 20  ITE_FUNCTION    
22370 20 20 20 20 20 20 20 20 20 33 31 20 20 20 2f 2a           31   /*
22380 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
22390 20 46 75 6e 63 74 69 6f 6e 20 4e 61 6d 65 20 20   Function Name  
223a0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
223b0 54 45 5f 53 41 56 45 50 4f 49 4e 54 20 20 20 20  TE_SAVEPOINT    
223c0 20 20 20 20 20 20 20 20 33 32 20 20 20 2f 2a 20          32   /* 
223d0 4f 70 65 72 61 74 69 6f 6e 20 20 20 20 20 20 20  Operation       
223e0 53 61 76 65 70 6f 69 6e 74 20 4e 61 6d 65 20 20  Savepoint Name  
223f0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
22400 45 5f 43 4f 50 59 20 20 20 20 20 20 20 20 20 20  E_COPY          
22410 20 20 20 20 20 20 20 20 30 20 20 20 2f 2a 20 4e          0   /* N
22420 6f 20 6c 6f 6e 67 65 72 20 75 73 65 64 20 2a 2f  o longer used */
22430 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
22440 52 45 43 55 52 53 49 56 45 20 20 20 20 20 20 20  RECURSIVE       
22450 20 20 20 20 20 33 33 20 20 20 2f 2a 20 4e 55 4c       33   /* NUL
22460 4c 20 20 20 20 20 20 20 20 20 20 20 20 4e 55 4c  L            NUL
22470 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
22480 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
22490 20 54 72 61 63 69 6e 67 20 41 6e 64 20 50 72 6f   Tracing And Pro
224a0 66 69 6c 69 6e 67 20 46 75 6e 63 74 69 6f 6e 73  filing Functions
224b0 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
224c0 74 65 33 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  te3.**.** These 
224d0 72 6f 75 74 69 6e 65 73 20 61 72 65 20 64 65 70  routines are dep
224e0 72 65 63 61 74 65 64 2e 20 55 73 65 20 74 68 65  recated. Use the
224f0 20 5b 73 71 6c 69 74 65 33 5f 74 72 61 63 65 5f   [sqlite3_trace_
22500 76 32 28 29 5d 20 69 6e 74 65 72 66 61 63 65 0a  v2()] interface.
22510 2a 2a 20 69 6e 73 74 65 61 64 20 6f 66 20 74 68  ** instead of th
22520 65 20 72 6f 75 74 69 6e 65 73 20 64 65 73 63 72  e routines descr
22530 69 62 65 64 20 68 65 72 65 2e 0a 2a 2a 0a 2a 2a  ibed here..**.**
22540 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
22550 72 65 67 69 73 74 65 72 20 63 61 6c 6c 62 61 63  register callbac
22560 6b 20 66 75 6e 63 74 69 6f 6e 73 20 74 68 61 74  k functions that
22570 20 63 61 6e 20 62 65 20 75 73 65 64 20 66 6f 72   can be used for
22580 0a 2a 2a 20 74 72 61 63 69 6e 67 20 61 6e 64 20  .** tracing and 
22590 70 72 6f 66 69 6c 69 6e 67 20 74 68 65 20 65 78  profiling the ex
225a0 65 63 75 74 69 6f 6e 20 6f 66 20 53 51 4c 20 73  ecution of SQL s
225b0 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a  tatements..**.**
225c0 20 5e 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66   ^The callback f
225d0 75 6e 63 74 69 6f 6e 20 72 65 67 69 73 74 65 72  unction register
225e0 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 74 72  ed by sqlite3_tr
225f0 61 63 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64  ace() is invoked
22600 20 61 74 0a 2a 2a 20 76 61 72 69 6f 75 73 20 74   at.** various t
22610 69 6d 65 73 20 77 68 65 6e 20 61 6e 20 53 51 4c  imes when an SQL
22620 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 62 65   statement is be
22630 69 6e 67 20 72 75 6e 20 62 79 20 5b 73 71 6c 69  ing run by [sqli
22640 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 20  te3_step()]..** 
22650 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 74 72 61  ^The sqlite3_tra
22660 63 65 28 29 20 63 61 6c 6c 62 61 63 6b 20 69 73  ce() callback is
22670 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 61 20   invoked with a 
22680 55 54 46 2d 38 20 72 65 6e 64 65 72 69 6e 67 20  UTF-8 rendering 
22690 6f 66 20 74 68 65 0a 2a 2a 20 53 51 4c 20 73 74  of the.** SQL st
226a0 61 74 65 6d 65 6e 74 20 74 65 78 74 20 61 73 20  atement text as 
226b0 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 66 69  the statement fi
226c0 72 73 74 20 62 65 67 69 6e 73 20 65 78 65 63 75  rst begins execu
226d0 74 69 6e 67 2e 0a 2a 2a 20 5e 28 41 64 64 69 74  ting..** ^(Addit
226e0 69 6f 6e 61 6c 20 73 71 6c 69 74 65 33 5f 74 72  ional sqlite3_tr
226f0 61 63 65 28 29 20 63 61 6c 6c 62 61 63 6b 73 20  ace() callbacks 
22700 6d 69 67 68 74 20 6f 63 63 75 72 0a 2a 2a 20 61  might occur.** a
22710 73 20 65 61 63 68 20 74 72 69 67 67 65 72 65 64  s each triggered
22720 20 73 75 62 70 72 6f 67 72 61 6d 20 69 73 20 65   subprogram is e
22730 6e 74 65 72 65 64 2e 20 20 54 68 65 20 63 61 6c  ntered.  The cal
22740 6c 62 61 63 6b 73 20 66 6f 72 20 74 72 69 67 67  lbacks for trigg
22750 65 72 73 0a 2a 2a 20 63 6f 6e 74 61 69 6e 20 61  ers.** contain a
22760 20 55 54 46 2d 38 20 53 51 4c 20 63 6f 6d 6d 65   UTF-8 SQL comme
22770 6e 74 20 74 68 61 74 20 69 64 65 6e 74 69 66 69  nt that identifi
22780 65 73 20 74 68 65 20 74 72 69 67 67 65 72 2e 29  es the trigger.)
22790 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  ^.**.** The [SQL
227a0 49 54 45 5f 54 52 41 43 45 5f 53 49 5a 45 5f 4c  ITE_TRACE_SIZE_L
227b0 49 4d 49 54 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  IMIT] compile-ti
227c0 6d 65 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65  me option can be
227d0 20 75 73 65 64 20 74 6f 20 6c 69 6d 69 74 0a 2a   used to limit.*
227e0 2a 20 74 68 65 20 6c 65 6e 67 74 68 20 6f 66 20  * the length of 
227f0 5b 62 6f 75 6e 64 20 70 61 72 61 6d 65 74 65 72  [bound parameter
22800 5d 20 65 78 70 61 6e 73 69 6f 6e 20 69 6e 20 74  ] expansion in t
22810 68 65 20 6f 75 74 70 75 74 20 6f 66 20 73 71 6c  he output of sql
22820 69 74 65 33 5f 74 72 61 63 65 28 29 2e 0a 2a 2a  ite3_trace()..**
22830 0a 2a 2a 20 5e 54 68 65 20 63 61 6c 6c 62 61 63  .** ^The callbac
22840 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 67 69 73  k function regis
22850 74 65 72 65 64 20 62 79 20 73 71 6c 69 74 65 33  tered by sqlite3
22860 5f 70 72 6f 66 69 6c 65 28 29 20 69 73 20 69 6e  _profile() is in
22870 76 6f 6b 65 64 0a 2a 2a 20 61 73 20 65 61 63 68  voked.** as each
22880 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 66   SQL statement f
22890 69 6e 69 73 68 65 73 2e 20 20 5e 54 68 65 20 70  inishes.  ^The p
228a0 72 6f 66 69 6c 65 20 63 61 6c 6c 62 61 63 6b 20  rofile callback 
228b0 63 6f 6e 74 61 69 6e 73 0a 2a 2a 20 74 68 65 20  contains.** the 
228c0 6f 72 69 67 69 6e 61 6c 20 73 74 61 74 65 6d 65  original stateme
228d0 6e 74 20 74 65 78 74 20 61 6e 64 20 61 6e 20 65  nt text and an e
228e0 73 74 69 6d 61 74 65 20 6f 66 20 77 61 6c 6c 2d  stimate of wall-
228f0 63 6c 6f 63 6b 20 74 69 6d 65 0a 2a 2a 20 6f 66  clock time.** of
22900 20 68 6f 77 20 6c 6f 6e 67 20 74 68 61 74 20 73   how long that s
22910 74 61 74 65 6d 65 6e 74 20 74 6f 6f 6b 20 74 6f  tatement took to
22920 20 72 75 6e 2e 20 20 5e 54 68 65 20 70 72 6f 66   run.  ^The prof
22930 69 6c 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20  ile callback.** 
22940 74 69 6d 65 20 69 73 20 69 6e 20 75 6e 69 74 73  time is in units
22950 20 6f 66 20 6e 61 6e 6f 73 65 63 6f 6e 64 73 2c   of nanoseconds,
22960 20 68 6f 77 65 76 65 72 20 74 68 65 20 63 75 72   however the cur
22970 72 65 6e 74 20 69 6d 70 6c 65 6d 65 6e 74 61 74  rent implementat
22980 69 6f 6e 0a 2a 2a 20 69 73 20 6f 6e 6c 79 20 63  ion.** is only c
22990 61 70 61 62 6c 65 20 6f 66 20 6d 69 6c 6c 69 73  apable of millis
229a0 65 63 6f 6e 64 20 72 65 73 6f 6c 75 74 69 6f 6e  econd resolution
229b0 20 73 6f 20 74 68 65 20 73 69 78 20 6c 65 61 73   so the six leas
229c0 74 20 73 69 67 6e 69 66 69 63 61 6e 74 0a 2a 2a  t significant.**
229d0 20 64 69 67 69 74 73 20 69 6e 20 74 68 65 20 74   digits in the t
229e0 69 6d 65 20 61 72 65 20 6d 65 61 6e 69 6e 67 6c  ime are meaningl
229f0 65 73 73 2e 20 20 46 75 74 75 72 65 20 76 65 72  ess.  Future ver
22a00 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 0a  sions of SQLite.
22a10 2a 2a 20 6d 69 67 68 74 20 70 72 6f 76 69 64 65  ** might provide
22a20 20 67 72 65 61 74 65 72 20 72 65 73 6f 6c 75 74   greater resolut
22a30 69 6f 6e 20 6f 6e 20 74 68 65 20 70 72 6f 66 69  ion on the profi
22a40 6c 65 72 20 63 61 6c 6c 62 61 63 6b 2e 20 20 54  ler callback.  T
22a50 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 70 72  he.** sqlite3_pr
22a60 6f 66 69 6c 65 28 29 20 66 75 6e 63 74 69 6f 6e  ofile() function
22a70 20 69 73 20 63 6f 6e 73 69 64 65 72 65 64 20 65   is considered e
22a80 78 70 65 72 69 6d 65 6e 74 61 6c 20 61 6e 64 20  xperimental and 
22a90 69 73 0a 2a 2a 20 73 75 62 6a 65 63 74 20 74 6f  is.** subject to
22aa0 20 63 68 61 6e 67 65 20 69 6e 20 66 75 74 75 72   change in futur
22ab0 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51  e versions of SQ
22ac0 4c 69 74 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  Lite..*/.SQLITE_
22ad0 44 45 50 52 45 43 41 54 45 44 20 76 6f 69 64 20  DEPRECATED void 
22ae0 2a 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 73  *sqlite3_trace(s
22af0 71 6c 69 74 65 33 2a 2c 0a 20 20 20 76 6f 69 64  qlite3*,.   void
22b00 28 2a 78 54 72 61 63 65 29 28 76 6f 69 64 2a 2c  (*xTrace)(void*,
22b10 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c 20 76 6f  const char*), vo
22b20 69 64 2a 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50  id*);.SQLITE_DEP
22b30 52 45 43 41 54 45 44 20 76 6f 69 64 20 2a 73 71  RECATED void *sq
22b40 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 73 71  lite3_profile(sq
22b50 6c 69 74 65 33 2a 2c 0a 20 20 20 76 6f 69 64 28  lite3*,.   void(
22b60 2a 78 50 72 6f 66 69 6c 65 29 28 76 6f 69 64 2a  *xProfile)(void*
22b70 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 73 71 6c  ,const char*,sql
22b80 69 74 65 33 5f 75 69 6e 74 36 34 29 2c 20 76 6f  ite3_uint64), vo
22b90 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  id*);../*.** CAP
22ba0 49 33 52 45 46 3a 20 53 51 4c 20 54 72 61 63 65  I3REF: SQL Trace
22bb0 20 45 76 65 6e 74 20 43 6f 64 65 73 0a 2a 2a 20   Event Codes.** 
22bc0 4b 45 59 57 4f 52 44 53 3a 20 53 51 4c 49 54 45  KEYWORDS: SQLITE
22bd0 5f 54 52 41 43 45 0a 2a 2a 0a 2a 2a 20 54 68 65  _TRACE.**.** The
22be0 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 69 64 65  se constants ide
22bf0 6e 74 69 66 79 20 63 6c 61 73 73 65 73 20 6f 66  ntify classes of
22c00 20 65 76 65 6e 74 73 20 74 68 61 74 20 63 61 6e   events that can
22c10 20 62 65 20 6d 6f 6e 69 74 6f 72 65 64 0a 2a 2a   be monitored.**
22c20 20 75 73 69 6e 67 20 74 68 65 20 5b 73 71 6c 69   using the [sqli
22c30 74 65 33 5f 74 72 61 63 65 5f 76 32 28 29 5d 20  te3_trace_v2()] 
22c40 74 72 61 63 69 6e 67 20 6c 6f 67 69 63 2e 20 20  tracing logic.  
22c50 54 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65  The third argume
22c60 6e 74 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65  nt.** to [sqlite
22c70 33 5f 74 72 61 63 65 5f 76 32 28 29 5d 20 69 73  3_trace_v2()] is
22c80 20 61 6e 20 4f 52 2d 65 64 20 63 6f 6d 62 69 6e   an OR-ed combin
22c90 61 74 69 6f 6e 20 6f 66 20 6f 6e 65 20 6f 72 20  ation of one or 
22ca0 6d 6f 72 65 20 6f 66 0a 2a 2a 20 74 68 65 20 66  more of.** the f
22cb0 6f 6c 6c 6f 77 69 6e 67 20 63 6f 6e 73 74 61 6e  ollowing constan
22cc0 74 73 2e 20 20 5e 54 68 65 20 66 69 72 73 74 20  ts.  ^The first 
22cd0 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20  argument to the 
22ce0 74 72 61 63 65 20 63 61 6c 6c 62 61 63 6b 0a 2a  trace callback.*
22cf0 2a 20 69 73 20 6f 6e 65 20 6f 66 20 74 68 65 20  * is one of the 
22d00 66 6f 6c 6c 6f 77 69 6e 67 20 63 6f 6e 73 74 61  following consta
22d10 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 74  nts..**.** New t
22d20 72 61 63 69 6e 67 20 63 6f 6e 73 74 61 6e 74 73  racing constants
22d30 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e   may be added in
22d40 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73   future releases
22d50 2e 0a 2a 2a 0a 2a 2a 20 5e 41 20 74 72 61 63 65  ..**.** ^A trace
22d60 20 63 61 6c 6c 62 61 63 6b 20 68 61 73 20 66 6f   callback has fo
22d70 75 72 20 61 72 67 75 6d 65 6e 74 73 3a 20 78 43  ur arguments: xC
22d80 61 6c 6c 62 61 63 6b 28 54 2c 43 2c 50 2c 58 29  allback(T,C,P,X)
22d90 2e 0a 2a 2a 20 5e 54 68 65 20 54 20 61 72 67 75  ..** ^The T argu
22da0 6d 65 6e 74 20 69 73 20 6f 6e 65 20 6f 66 20 74  ment is one of t
22db0 68 65 20 69 6e 74 65 67 65 72 20 74 79 70 65 20  he integer type 
22dc0 63 6f 64 65 73 20 61 62 6f 76 65 2e 0a 2a 2a 20  codes above..** 
22dd0 5e 54 68 65 20 43 20 61 72 67 75 6d 65 6e 74 20  ^The C argument 
22de0 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  is a copy of the
22df0 20 63 6f 6e 74 65 78 74 20 70 6f 69 6e 74 65 72   context pointer
22e00 20 70 61 73 73 65 64 20 69 6e 20 61 73 20 74 68   passed in as th
22e10 65 0a 2a 2a 20 66 6f 75 72 74 68 20 61 72 67 75  e.** fourth argu
22e20 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33  ment to [sqlite3
22e30 5f 74 72 61 63 65 5f 76 32 28 29 5d 2e 0a 2a 2a  _trace_v2()]..**
22e40 20 54 68 65 20 50 20 61 6e 64 20 58 20 61 72 67   The P and X arg
22e50 75 6d 65 6e 74 73 20 61 72 65 20 70 6f 69 6e 74  uments are point
22e60 65 72 73 20 77 68 6f 73 65 20 6d 65 61 6e 69 6e  ers whose meanin
22e70 67 73 20 64 65 70 65 6e 64 20 6f 6e 20 54 2e 0a  gs depend on T..
22e80 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b  **.** <dl>.** [[
22e90 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 53 54 4d  SQLITE_TRACE_STM
22ea0 54 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 54  T]] <dt>SQLITE_T
22eb0 52 41 43 45 5f 53 54 4d 54 3c 2f 64 74 3e 0a 2a  RACE_STMT</dt>.*
22ec0 2a 20 3c 64 64 3e 5e 41 6e 20 53 51 4c 49 54 45  * <dd>^An SQLITE
22ed0 5f 54 52 41 43 45 5f 53 54 4d 54 20 63 61 6c 6c  _TRACE_STMT call
22ee0 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20  back is invoked 
22ef0 77 68 65 6e 20 61 20 70 72 65 70 61 72 65 64 20  when a prepared 
22f00 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 66 69 72  statement.** fir
22f10 73 74 20 62 65 67 69 6e 73 20 72 75 6e 6e 69 6e  st begins runnin
22f20 67 20 61 6e 64 20 70 6f 73 73 69 62 6c 79 20 61  g and possibly a
22f30 74 20 6f 74 68 65 72 20 74 69 6d 65 73 20 64 75  t other times du
22f40 72 69 6e 67 20 74 68 65 0a 2a 2a 20 65 78 65 63  ring the.** exec
22f50 75 74 69 6f 6e 20 6f 66 20 74 68 65 20 70 72 65  ution of the pre
22f60 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 2c  pared statement,
22f70 20 73 75 63 68 20 61 73 20 61 74 20 74 68 65 20   such as at the 
22f80 73 74 61 72 74 20 6f 66 20 65 61 63 68 0a 2a 2a  start of each.**
22f90 20 74 72 69 67 67 65 72 20 73 75 62 70 72 6f 67   trigger subprog
22fa0 72 61 6d 2e 20 5e 54 68 65 20 50 20 61 72 67 75  ram. ^The P argu
22fb0 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65  ment is a pointe
22fc0 72 20 74 6f 20 74 68 65 0a 2a 2a 20 5b 70 72 65  r to the.** [pre
22fd0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
22fe0 2e 20 5e 54 68 65 20 58 20 61 72 67 75 6d 65 6e  . ^The X argumen
22ff0 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  t is a pointer t
23000 6f 20 61 20 73 74 72 69 6e 67 20 77 68 69 63 68  o a string which
23010 0a 2a 2a 20 69 73 20 74 68 65 20 75 6e 65 78 70  .** is the unexp
23020 61 6e 64 65 64 20 53 51 4c 20 74 65 78 74 20 6f  anded SQL text o
23030 66 20 74 68 65 20 70 72 65 70 61 72 65 64 20 73  f the prepared s
23040 74 61 74 65 6d 65 6e 74 20 6f 72 20 61 6e 20 53  tatement or an S
23050 51 4c 20 63 6f 6d 6d 65 6e 74 20 0a 2a 2a 20 74  QL comment .** t
23060 68 61 74 20 69 6e 64 69 63 61 74 65 73 20 74 68  hat indicates th
23070 65 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20  e invocation of 
23080 61 20 74 72 69 67 67 65 72 2e 20 20 5e 54 68 65  a trigger.  ^The
23090 20 63 61 6c 6c 62 61 63 6b 20 63 61 6e 20 63 6f   callback can co
230a0 6d 70 75 74 65 0a 2a 2a 20 74 68 65 20 73 61 6d  mpute.** the sam
230b0 65 20 74 65 78 74 20 74 68 61 74 20 77 6f 75 6c  e text that woul
230c0 64 20 68 61 76 65 20 62 65 65 6e 20 72 65 74 75  d have been retu
230d0 72 6e 65 64 20 62 79 20 74 68 65 20 6c 65 67 61  rned by the lega
230e0 63 79 20 5b 73 71 6c 69 74 65 33 5f 74 72 61 63  cy [sqlite3_trac
230f0 65 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63  e()].** interfac
23100 65 20 62 79 20 75 73 69 6e 67 20 74 68 65 20 58  e by using the X
23110 20 61 72 67 75 6d 65 6e 74 20 77 68 65 6e 20 58   argument when X
23120 20 62 65 67 69 6e 73 20 77 69 74 68 20 22 2d 2d   begins with "--
23130 22 20 61 6e 64 20 69 6e 76 6f 6b 69 6e 67 0a 2a  " and invoking.*
23140 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 70 61 6e  * [sqlite3_expan
23150 64 65 64 5f 73 71 6c 28 50 29 5d 20 6f 74 68 65  ded_sql(P)] othe
23160 72 77 69 73 65 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  rwise..**.** [[S
23170 51 4c 49 54 45 5f 54 52 41 43 45 5f 50 52 4f 46  QLITE_TRACE_PROF
23180 49 4c 45 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45  ILE]] <dt>SQLITE
23190 5f 54 52 41 43 45 5f 50 52 4f 46 49 4c 45 3c 2f  _TRACE_PROFILE</
231a0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 5e 41 6e 20 53  dt>.** <dd>^An S
231b0 51 4c 49 54 45 5f 54 52 41 43 45 5f 50 52 4f 46  QLITE_TRACE_PROF
231c0 49 4c 45 20 63 61 6c 6c 62 61 63 6b 20 70 72 6f  ILE callback pro
231d0 76 69 64 65 73 20 61 70 70 72 6f 78 69 6d 61 74  vides approximat
231e0 65 6c 79 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20  ely the same.** 
231f0 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 73 20 69  information as i
23200 73 20 70 72 6f 76 69 64 65 64 20 62 79 20 74 68  s provided by th
23210 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 6f 66 69  e [sqlite3_profi
23220 6c 65 28 29 5d 20 63 61 6c 6c 62 61 63 6b 2e 0a  le()] callback..
23230 2a 2a 20 5e 54 68 65 20 50 20 61 72 67 75 6d 65  ** ^The P argume
23240 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20  nt is a pointer 
23250 74 6f 20 74 68 65 20 5b 70 72 65 70 61 72 65 64  to the [prepared
23260 20 73 74 61 74 65 6d 65 6e 74 5d 20 61 6e 64 20   statement] and 
23270 74 68 65 0a 2a 2a 20 58 20 61 72 67 75 6d 65 6e  the.** X argumen
23280 74 20 70 6f 69 6e 74 73 20 74 6f 20 61 20 36 34  t points to a 64
23290 2d 62 69 74 20 69 6e 74 65 67 65 72 20 77 68 69  -bit integer whi
232a0 63 68 20 69 73 20 74 68 65 20 65 73 74 69 6d 61  ch is the estima
232b0 74 65 64 20 6f 66 0a 2a 2a 20 74 68 65 20 6e 75  ted of.** the nu
232c0 6d 62 65 72 20 6f 66 20 6e 61 6e 6f 73 65 63 6f  mber of nanoseco
232d0 6e 64 20 74 68 61 74 20 74 68 65 20 70 72 65 70  nd that the prep
232e0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 74  ared statement t
232f0 6f 6f 6b 20 74 6f 20 72 75 6e 2e 0a 2a 2a 20 5e  ook to run..** ^
23300 54 68 65 20 53 51 4c 49 54 45 5f 54 52 41 43 45  The SQLITE_TRACE
23310 5f 50 52 4f 46 49 4c 45 20 63 61 6c 6c 62 61 63  _PROFILE callbac
23320 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 68 65  k is invoked whe
23330 6e 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  n the statement 
23340 66 69 6e 69 73 68 65 73 2e 0a 2a 2a 0a 2a 2a 20  finishes..**.** 
23350 5b 5b 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 52  [[SQLITE_TRACE_R
23360 4f 57 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  OW]] <dt>SQLITE_
23370 54 52 41 43 45 5f 52 4f 57 3c 2f 64 74 3e 0a 2a  TRACE_ROW</dt>.*
23380 2a 20 3c 64 64 3e 5e 41 6e 20 53 51 4c 49 54 45  * <dd>^An SQLITE
23390 5f 54 52 41 43 45 5f 52 4f 57 20 63 61 6c 6c 62  _TRACE_ROW callb
233a0 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 77  ack is invoked w
233b0 68 65 6e 65 76 65 72 20 61 20 70 72 65 70 61 72  henever a prepar
233c0 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20  ed.** statement 
233d0 67 65 6e 65 72 61 74 65 73 20 61 20 73 69 6e 67  generates a sing
233e0 6c 65 20 72 6f 77 20 6f 66 20 72 65 73 75 6c 74  le row of result
233f0 2e 20 20 0a 2a 2a 20 5e 54 68 65 20 50 20 61 72  .  .** ^The P ar
23400 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e  gument is a poin
23410 74 65 72 20 74 6f 20 74 68 65 20 5b 70 72 65 70  ter to the [prep
23420 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
23430 61 6e 64 20 74 68 65 0a 2a 2a 20 58 20 61 72 67  and the.** X arg
23440 75 6d 65 6e 74 20 69 73 20 75 6e 75 73 65 64 2e  ument is unused.
23450 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
23460 54 52 41 43 45 5f 43 4c 4f 53 45 5d 5d 20 3c 64  TRACE_CLOSE]] <d
23470 74 3e 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 43  t>SQLITE_TRACE_C
23480 4c 4f 53 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  LOSE</dt>.** <dd
23490 3e 5e 41 6e 20 53 51 4c 49 54 45 5f 54 52 41 43  >^An SQLITE_TRAC
234a0 45 5f 43 4c 4f 53 45 20 63 61 6c 6c 62 61 63 6b  E_CLOSE callback
234b0 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e   is invoked when
234c0 20 61 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63   a database.** c
234d0 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f 73 65 73  onnection closes
234e0 2e 0a 2a 2a 20 5e 54 68 65 20 50 20 61 72 67 75  ..** ^The P argu
234f0 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65  ment is a pointe
23500 72 20 74 6f 20 74 68 65 20 5b 64 61 74 61 62 61  r to the [databa
23510 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f  se connection] o
23520 62 6a 65 63 74 0a 2a 2a 20 61 6e 64 20 74 68 65  bject.** and the
23530 20 58 20 61 72 67 75 6d 65 6e 74 20 69 73 20 75   X argument is u
23540 6e 75 73 65 64 2e 0a 2a 2a 20 3c 2f 64 6c 3e 0a  nused..** </dl>.
23550 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
23560 45 5f 54 52 41 43 45 5f 53 54 4d 54 20 20 20 20  E_TRACE_STMT    
23570 20 20 20 30 78 30 31 0a 23 64 65 66 69 6e 65 20     0x01.#define 
23580 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 50 52 4f  SQLITE_TRACE_PRO
23590 46 49 4c 45 20 20 20 20 30 78 30 32 0a 23 64 65  FILE    0x02.#de
235a0 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 52 41 43  fine SQLITE_TRAC
235b0 45 5f 52 4f 57 20 20 20 20 20 20 20 20 30 78 30  E_ROW        0x0
235c0 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  4.#define SQLITE
235d0 5f 54 52 41 43 45 5f 43 4c 4f 53 45 20 20 20 20  _TRACE_CLOSE    
235e0 20 20 30 78 30 38 0a 0a 2f 2a 0a 2a 2a 20 43 41    0x08../*.** CA
235f0 50 49 33 52 45 46 3a 20 53 51 4c 20 54 72 61 63  PI3REF: SQL Trac
23600 65 20 48 6f 6f 6b 0a 2a 2a 20 4d 45 54 48 4f 44  e Hook.** METHOD
23610 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20  : sqlite3.**.** 
23620 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 74 72 61  ^The sqlite3_tra
23630 63 65 5f 76 32 28 44 2c 4d 2c 58 2c 50 29 20 69  ce_v2(D,M,X,P) i
23640 6e 74 65 72 66 61 63 65 20 72 65 67 69 73 74 65  nterface registe
23650 72 73 20 61 20 74 72 61 63 65 20 63 61 6c 6c 62  rs a trace callb
23660 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  ack.** function 
23670 58 20 61 67 61 69 6e 73 74 20 5b 64 61 74 61 62  X against [datab
23680 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
23690 44 2c 20 75 73 69 6e 67 20 70 72 6f 70 65 72 74  D, using propert
236a0 79 20 6d 61 73 6b 20 4d 0a 2a 2a 20 61 6e 64 20  y mask M.** and 
236b0 63 6f 6e 74 65 78 74 20 70 6f 69 6e 74 65 72 20  context pointer 
236c0 50 2e 20 20 5e 49 66 20 74 68 65 20 58 20 63 61  P.  ^If the X ca
236d0 6c 6c 62 61 63 6b 20 69 73 0a 2a 2a 20 4e 55 4c  llback is.** NUL
236e0 4c 20 6f 72 20 69 66 20 74 68 65 20 4d 20 6d 61  L or if the M ma
236f0 73 6b 20 69 73 20 7a 65 72 6f 2c 20 74 68 65 6e  sk is zero, then
23700 20 74 72 61 63 69 6e 67 20 69 73 20 64 69 73 61   tracing is disa
23710 62 6c 65 64 2e 20 20 54 68 65 0a 2a 2a 20 4d 20  bled.  The.** M 
23720 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20  argument should 
23730 62 65 20 74 68 65 20 62 69 74 77 69 73 65 20 4f  be the bitwise O
23740 52 2d 65 64 20 63 6f 6d 62 69 6e 61 74 69 6f 6e  R-ed combination
23750 20 6f 66 0a 2a 2a 20 7a 65 72 6f 20 6f 72 20 6d   of.** zero or m
23760 6f 72 65 20 5b 53 51 4c 49 54 45 5f 54 52 41 43  ore [SQLITE_TRAC
23770 45 5d 20 63 6f 6e 73 74 61 6e 74 73 2e 0a 2a 2a  E] constants..**
23780 0a 2a 2a 20 5e 45 61 63 68 20 63 61 6c 6c 20 74  .** ^Each call t
23790 6f 20 65 69 74 68 65 72 20 73 71 6c 69 74 65 33  o either sqlite3
237a0 5f 74 72 61 63 65 28 29 20 6f 72 20 73 71 6c 69  _trace() or sqli
237b0 74 65 33 5f 74 72 61 63 65 5f 76 32 28 29 20 6f  te3_trace_v2() o
237c0 76 65 72 72 69 64 65 73 20 0a 2a 2a 20 28 63 61  verrides .** (ca
237d0 6e 63 65 6c 73 29 20 61 6e 79 20 70 72 69 6f 72  ncels) any prior
237e0 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65   calls to sqlite
237f0 33 5f 74 72 61 63 65 28 29 20 6f 72 20 73 71 6c  3_trace() or sql
23800 69 74 65 33 5f 74 72 61 63 65 5f 76 32 28 29 2e  ite3_trace_v2().
23810 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 58 20 63 61  .**.** ^The X ca
23820 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65  llback is invoke
23830 64 20 77 68 65 6e 65 76 65 72 20 61 6e 79 20 6f  d whenever any o
23840 66 20 74 68 65 20 65 76 65 6e 74 73 20 69 64 65  f the events ide
23850 6e 74 69 66 69 65 64 20 62 79 20 0a 2a 2a 20 6d  ntified by .** m
23860 61 73 6b 20 4d 20 6f 63 63 75 72 2e 20 20 5e 54  ask M occur.  ^T
23870 68 65 20 69 6e 74 65 67 65 72 20 72 65 74 75 72  he integer retur
23880 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20 74 68 65  n value from the
23890 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 63 75 72   callback is cur
238a0 72 65 6e 74 6c 79 0a 2a 2a 20 69 67 6e 6f 72 65  rently.** ignore
238b0 64 2c 20 74 68 6f 75 67 68 20 74 68 69 73 20 6d  d, though this m
238c0 61 79 20 63 68 61 6e 67 65 20 69 6e 20 66 75 74  ay change in fut
238d0 75 72 65 20 72 65 6c 65 61 73 65 73 2e 20 20 43  ure releases.  C
238e0 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 6d 70 6c 65  allback.** imple
238f0 6d 65 6e 74 61 74 69 6f 6e 73 20 73 68 6f 75 6c  mentations shoul
23900 64 20 72 65 74 75 72 6e 20 7a 65 72 6f 20 74 6f  d return zero to
23910 20 65 6e 73 75 72 65 20 66 75 74 75 72 65 20 63   ensure future c
23920 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a  ompatibility..**
23930 0a 2a 2a 20 5e 41 20 74 72 61 63 65 20 63 61 6c  .** ^A trace cal
23940 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64  lback is invoked
23950 20 77 69 74 68 20 66 6f 75 72 20 61 72 67 75 6d   with four argum
23960 65 6e 74 73 3a 20 63 61 6c 6c 62 61 63 6b 28 54  ents: callback(T
23970 2c 43 2c 50 2c 58 29 2e 0a 2a 2a 20 5e 54 68 65  ,C,P,X)..** ^The
23980 20 54 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6f   T argument is o
23990 6e 65 20 6f 66 20 74 68 65 20 5b 53 51 4c 49 54  ne of the [SQLIT
239a0 45 5f 54 52 41 43 45 5d 0a 2a 2a 20 63 6f 6e 73  E_TRACE].** cons
239b0 74 61 6e 74 73 20 74 6f 20 69 6e 64 69 63 61 74  tants to indicat
239c0 65 20 77 68 79 20 74 68 65 20 63 61 6c 6c 62 61  e why the callba
239d0 63 6b 20 77 61 73 20 69 6e 76 6f 6b 65 64 2e 0a  ck was invoked..
239e0 2a 2a 20 5e 54 68 65 20 43 20 61 72 67 75 6d 65  ** ^The C argume
239f0 6e 74 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20  nt is a copy of 
23a00 74 68 65 20 63 6f 6e 74 65 78 74 20 70 6f 69 6e  the context poin
23a10 74 65 72 2e 0a 2a 2a 20 54 68 65 20 50 20 61 6e  ter..** The P an
23a20 64 20 58 20 61 72 67 75 6d 65 6e 74 73 20 61 72  d X arguments ar
23a30 65 20 70 6f 69 6e 74 65 72 73 20 77 68 6f 73 65  e pointers whose
23a40 20 6d 65 61 6e 69 6e 67 73 20 64 65 70 65 6e 64   meanings depend
23a50 20 6f 6e 20 54 2e 0a 2a 2a 0a 2a 2a 20 54 68 65   on T..**.** The
23a60 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 5f 76   sqlite3_trace_v
23a70 32 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73  2() interface is
23a80 20 69 6e 74 65 6e 64 65 64 20 74 6f 20 72 65 70   intended to rep
23a90 6c 61 63 65 20 74 68 65 20 6c 65 67 61 63 79 0a  lace the legacy.
23aa0 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 5b 73  ** interfaces [s
23ab0 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 5d 20  qlite3_trace()] 
23ac0 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 6f  and [sqlite3_pro
23ad0 66 69 6c 65 28 29 5d 2c 20 62 6f 74 68 20 6f 66  file()], both of
23ae0 20 77 68 69 63 68 0a 2a 2a 20 61 72 65 20 64 65   which.** are de
23af0 70 72 65 63 61 74 65 64 2e 0a 2a 2f 0a 69 6e 74  precated..*/.int
23b00 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 5f 76   sqlite3_trace_v
23b10 32 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 0a 20  2(.  sqlite3*,. 
23b20 20 75 6e 73 69 67 6e 65 64 20 75 4d 61 73 6b 2c   unsigned uMask,
23b30 0a 20 20 69 6e 74 28 2a 78 43 61 6c 6c 62 61 63  .  int(*xCallbac
23b40 6b 29 28 75 6e 73 69 67 6e 65 64 2c 76 6f 69 64  k)(unsigned,void
23b50 2a 2c 76 6f 69 64 2a 2c 76 6f 69 64 2a 29 2c 0a  *,void*,void*),.
23b60 20 20 76 6f 69 64 20 2a 70 43 74 78 0a 29 3b 0a    void *pCtx.);.
23b70 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
23b80 20 51 75 65 72 79 20 50 72 6f 67 72 65 73 73 20   Query Progress 
23b90 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 20 4d 45 54  Callbacks.** MET
23ba0 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a  HOD: sqlite3.**.
23bb0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
23bc0 70 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65 72  progress_handler
23bd0 28 44 2c 4e 2c 58 2c 50 29 20 69 6e 74 65 72 66  (D,N,X,P) interf
23be0 61 63 65 20 63 61 75 73 65 73 20 74 68 65 20 63  ace causes the c
23bf0 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 74  allback.** funct
23c00 69 6f 6e 20 58 20 74 6f 20 62 65 20 69 6e 76 6f  ion X to be invo
23c10 6b 65 64 20 70 65 72 69 6f 64 69 63 61 6c 6c 79  ked periodically
23c20 20 64 75 72 69 6e 67 20 6c 6f 6e 67 20 72 75 6e   during long run
23c30 6e 69 6e 67 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a  ning calls to.**
23c40 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29   [sqlite3_exec()
23c50 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  ], [sqlite3_step
23c60 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
23c70 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 20 66 6f  _get_table()] fo
23c80 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f  r.** database co
23c90 6e 6e 65 63 74 69 6f 6e 20 44 2e 20 20 41 6e 20  nnection D.  An 
23ca0 65 78 61 6d 70 6c 65 20 75 73 65 20 66 6f 72 20  example use for 
23cb0 74 68 69 73 0a 2a 2a 20 69 6e 74 65 72 66 61 63  this.** interfac
23cc0 65 20 69 73 20 74 6f 20 6b 65 65 70 20 61 20 47  e is to keep a G
23cd0 55 49 20 75 70 64 61 74 65 64 20 64 75 72 69 6e  UI updated durin
23ce0 67 20 61 20 6c 61 72 67 65 20 71 75 65 72 79 2e  g a large query.
23cf0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 70 61 72 61  .**.** ^The para
23d00 6d 65 74 65 72 20 50 20 69 73 20 70 61 73 73 65  meter P is passe
23d10 64 20 74 68 72 6f 75 67 68 20 61 73 20 74 68 65  d through as the
23d20 20 6f 6e 6c 79 20 70 61 72 61 6d 65 74 65 72 20   only parameter 
23d30 74 6f 20 74 68 65 20 0a 2a 2a 20 63 61 6c 6c 62  to the .** callb
23d40 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 58 2e 20  ack function X. 
23d50 20 5e 54 68 65 20 70 61 72 61 6d 65 74 65 72 20   ^The parameter 
23d60 4e 20 69 73 20 74 68 65 20 61 70 70 72 6f 78 69  N is the approxi
23d70 6d 61 74 65 20 6e 75 6d 62 65 72 20 6f 66 20 0a  mate number of .
23d80 2a 2a 20 5b 76 69 72 74 75 61 6c 20 6d 61 63 68  ** [virtual mach
23d90 69 6e 65 20 69 6e 73 74 72 75 63 74 69 6f 6e 73  ine instructions
23da0 5d 20 74 68 61 74 20 61 72 65 20 65 76 61 6c 75  ] that are evalu
23db0 61 74 65 64 20 62 65 74 77 65 65 6e 20 73 75 63  ated between suc
23dc0 63 65 73 73 69 76 65 0a 2a 2a 20 69 6e 76 6f 63  cessive.** invoc
23dd0 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 63 61  ations of the ca
23de0 6c 6c 62 61 63 6b 20 58 2e 20 20 5e 49 66 20 4e  llback X.  ^If N
23df0 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 6f 6e   is less than on
23e00 65 20 74 68 65 6e 20 74 68 65 20 70 72 6f 67 72  e then the progr
23e10 65 73 73 0a 2a 2a 20 68 61 6e 64 6c 65 72 20 69  ess.** handler i
23e20 73 20 64 69 73 61 62 6c 65 64 2e 0a 2a 2a 0a 2a  s disabled..**.*
23e30 2a 20 5e 4f 6e 6c 79 20 61 20 73 69 6e 67 6c 65  * ^Only a single
23e40 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65   progress handle
23e50 72 20 6d 61 79 20 62 65 20 64 65 66 69 6e 65 64  r may be defined
23e60 20 61 74 20 6f 6e 65 20 74 69 6d 65 20 70 65 72   at one time per
23e70 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f  .** [database co
23e80 6e 6e 65 63 74 69 6f 6e 5d 3b 20 73 65 74 74 69  nnection]; setti
23e90 6e 67 20 61 20 6e 65 77 20 70 72 6f 67 72 65 73  ng a new progres
23ea0 73 20 68 61 6e 64 6c 65 72 20 63 61 6e 63 65 6c  s handler cancel
23eb0 73 20 74 68 65 0a 2a 2a 20 6f 6c 64 20 6f 6e 65  s the.** old one
23ec0 2e 20 20 5e 53 65 74 74 69 6e 67 20 70 61 72 61  .  ^Setting para
23ed0 6d 65 74 65 72 20 58 20 74 6f 20 4e 55 4c 4c 20  meter X to NULL 
23ee0 64 69 73 61 62 6c 65 73 20 74 68 65 20 70 72 6f  disables the pro
23ef0 67 72 65 73 73 20 68 61 6e 64 6c 65 72 2e 0a 2a  gress handler..*
23f00 2a 20 5e 54 68 65 20 70 72 6f 67 72 65 73 73 20  * ^The progress 
23f10 68 61 6e 64 6c 65 72 20 69 73 20 61 6c 73 6f 20  handler is also 
23f20 64 69 73 61 62 6c 65 64 20 62 79 20 73 65 74 74  disabled by sett
23f30 69 6e 67 20 4e 20 74 6f 20 61 20 76 61 6c 75 65  ing N to a value
23f40 20 6c 65 73 73 0a 2a 2a 20 74 68 61 6e 20 31 2e   less.** than 1.
23f50 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 70  .**.** ^If the p
23f60 72 6f 67 72 65 73 73 20 63 61 6c 6c 62 61 63 6b  rogress callback
23f70 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72   returns non-zer
23f80 6f 2c 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e  o, the operation
23f90 20 69 73 0a 2a 2a 20 69 6e 74 65 72 72 75 70 74   is.** interrupt
23fa0 65 64 2e 20 20 54 68 69 73 20 66 65 61 74 75 72  ed.  This featur
23fb0 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  e can be used to
23fc0 20 69 6d 70 6c 65 6d 65 6e 74 20 61 0a 2a 2a 20   implement a.** 
23fd0 22 43 61 6e 63 65 6c 22 20 62 75 74 74 6f 6e 20  "Cancel" button 
23fe0 6f 6e 20 61 20 47 55 49 20 70 72 6f 67 72 65 73  on a GUI progres
23ff0 73 20 64 69 61 6c 6f 67 20 62 6f 78 2e 0a 2a 2a  s dialog box..**
24000 0a 2a 2a 20 54 68 65 20 70 72 6f 67 72 65 73 73  .** The progress
24010 20 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63   handler callbac
24020 6b 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e  k must not do an
24030 79 74 68 69 6e 67 20 74 68 61 74 20 77 69 6c 6c  ything that will
24040 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64   modify.** the d
24050 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
24060 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20  on that invoked 
24070 74 68 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e  the progress han
24080 64 6c 65 72 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68  dler..** Note th
24090 61 74 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  at [sqlite3_prep
240a0 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73  are_v2()] and [s
240b0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 62  qlite3_step()] b
240c0 6f 74 68 20 6d 6f 64 69 66 79 20 74 68 65 69 72  oth modify their
240d0 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e  .** database con
240e0 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20 74 68 65  nections for the
240f0 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64   meaning of "mod
24100 69 66 79 22 20 69 6e 20 74 68 69 73 20 70 61 72  ify" in this par
24110 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2f 0a 76 6f  agraph..**.*/.vo
24120 69 64 20 73 71 6c 69 74 65 33 5f 70 72 6f 67 72  id sqlite3_progr
24130 65 73 73 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69  ess_handler(sqli
24140 74 65 33 2a 2c 20 69 6e 74 2c 20 69 6e 74 28 2a  te3*, int, int(*
24150 29 28 76 6f 69 64 2a 29 2c 20 76 6f 69 64 2a 29  )(void*), void*)
24160 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
24170 46 3a 20 4f 70 65 6e 69 6e 67 20 41 20 4e 65 77  F: Opening A New
24180 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63   Database Connec
24190 74 69 6f 6e 0a 2a 2a 20 43 4f 4e 53 54 52 55 43  tion.** CONSTRUC
241a0 54 4f 52 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a  TOR: sqlite3.**.
241b0 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e  ** ^These routin
241c0 65 73 20 6f 70 65 6e 20 61 6e 20 53 51 4c 69 74  es open an SQLit
241d0 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
241e0 61 73 20 73 70 65 63 69 66 69 65 64 20 62 79 20  as specified by 
241f0 74 68 65 20 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65  the .** filename
24200 20 61 72 67 75 6d 65 6e 74 2e 20 5e 54 68 65 20   argument. ^The 
24210 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e  filename argumen
24220 74 20 69 73 20 69 6e 74 65 72 70 72 65 74 65 64  t is interpreted
24230 20 61 73 20 55 54 46 2d 38 20 66 6f 72 0a 2a 2a   as UTF-8 for.**
24240 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20   sqlite3_open() 
24250 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  and sqlite3_open
24260 5f 76 32 28 29 20 61 6e 64 20 61 73 20 55 54 46  _v2() and as UTF
24270 2d 31 36 20 69 6e 20 74 68 65 20 6e 61 74 69 76  -16 in the nativ
24280 65 20 62 79 74 65 0a 2a 2a 20 6f 72 64 65 72 20  e byte.** order 
24290 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  for sqlite3_open
242a0 31 36 28 29 2e 20 5e 28 41 20 5b 64 61 74 61 62  16(). ^(A [datab
242b0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
242c0 68 61 6e 64 6c 65 20 69 73 20 75 73 75 61 6c 6c  handle is usuall
242d0 79 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 69 6e  y.** returned in
242e0 20 2a 70 70 44 62 2c 20 65 76 65 6e 20 69 66 20   *ppDb, even if 
242f0 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2e  an error occurs.
24300 20 20 54 68 65 20 6f 6e 6c 79 20 65 78 63 65 70    The only excep
24310 74 69 6f 6e 20 69 73 20 74 68 61 74 0a 2a 2a 20  tion is that.** 
24320 69 66 20 53 51 4c 69 74 65 20 69 73 20 75 6e 61  if SQLite is una
24330 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20  ble to allocate 
24340 6d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74  memory to hold t
24350 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a  he [sqlite3] obj
24360 65 63 74 2c 0a 2a 2a 20 61 20 4e 55 4c 4c 20 77  ect,.** a NULL w
24370 69 6c 6c 20 62 65 20 77 72 69 74 74 65 6e 20 69  ill be written i
24380 6e 74 6f 20 2a 70 70 44 62 20 69 6e 73 74 65 61  nto *ppDb instea
24390 64 20 6f 66 20 61 20 70 6f 69 6e 74 65 72 20 74  d of a pointer t
243a0 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 0a  o the [sqlite3].
243b0 2a 2a 20 6f 62 6a 65 63 74 2e 29 5e 20 5e 28 49  ** object.)^ ^(I
243c0 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69  f the database i
243d0 73 20 6f 70 65 6e 65 64 20 28 61 6e 64 2f 6f 72  s opened (and/or
243e0 20 63 72 65 61 74 65 64 29 20 73 75 63 63 65 73   created) succes
243f0 73 66 75 6c 6c 79 2c 20 74 68 65 6e 0a 2a 2a 20  sfully, then.** 
24400 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 73 20 72  [SQLITE_OK] is r
24410 65 74 75 72 6e 65 64 2e 20 20 4f 74 68 65 72 77  eturned.  Otherw
24420 69 73 65 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f  ise an [error co
24430 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e  de] is returned.
24440 29 5e 20 5e 54 68 65 0a 2a 2a 20 5b 73 71 6c 69  )^ ^The.** [sqli
24450 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 20 6f 72  te3_errmsg()] or
24460 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67   [sqlite3_errmsg
24470 31 36 28 29 5d 20 72 6f 75 74 69 6e 65 73 20 63  16()] routines c
24480 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f 62  an be used to ob
24490 74 61 69 6e 0a 2a 2a 20 61 6e 20 45 6e 67 6c 69  tain.** an Engli
244a0 73 68 20 6c 61 6e 67 75 61 67 65 20 64 65 73 63  sh language desc
244b0 72 69 70 74 69 6f 6e 20 6f 66 20 74 68 65 20 65  ription of the e
244c0 72 72 6f 72 20 66 6f 6c 6c 6f 77 69 6e 67 20 61  rror following a
244d0 20 66 61 69 6c 75 72 65 20 6f 66 20 61 6e 79 0a   failure of any.
244e0 2a 2a 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65  ** of the sqlite
244f0 33 5f 6f 70 65 6e 28 29 20 72 6f 75 74 69 6e 65  3_open() routine
24500 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 64 65  s..**.** ^The de
24510 66 61 75 6c 74 20 65 6e 63 6f 64 69 6e 67 20 77  fault encoding w
24520 69 6c 6c 20 62 65 20 55 54 46 2d 38 20 66 6f 72  ill be UTF-8 for
24530 20 64 61 74 61 62 61 73 65 73 20 63 72 65 61 74   databases creat
24540 65 64 20 75 73 69 6e 67 0a 2a 2a 20 73 71 6c 69  ed using.** sqli
24550 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71  te3_open() or sq
24560 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e  lite3_open_v2().
24570 20 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20 65    ^The default e
24580 6e 63 6f 64 69 6e 67 20 66 6f 72 20 64 61 74 61  ncoding for data
24590 62 61 73 65 73 0a 2a 2a 20 63 72 65 61 74 65 64  bases.** created
245a0 20 75 73 69 6e 67 20 73 71 6c 69 74 65 33 5f 6f   using sqlite3_o
245b0 70 65 6e 31 36 28 29 20 77 69 6c 6c 20 62 65 20  pen16() will be 
245c0 55 54 46 2d 31 36 20 69 6e 20 74 68 65 20 6e 61  UTF-16 in the na
245d0 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e  tive byte order.
245e0 0a 2a 2a 0a 2a 2a 20 57 68 65 74 68 65 72 20 6f  .**.** Whether o
245f0 72 20 6e 6f 74 20 61 6e 20 65 72 72 6f 72 20 6f  r not an error o
24600 63 63 75 72 73 20 77 68 65 6e 20 69 74 20 69 73  ccurs when it is
24610 20 6f 70 65 6e 65 64 2c 20 72 65 73 6f 75 72 63   opened, resourc
24620 65 73 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64  es.** associated
24630 20 77 69 74 68 20 74 68 65 20 5b 64 61 74 61 62   with the [datab
24640 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
24650 68 61 6e 64 6c 65 20 73 68 6f 75 6c 64 20 62 65  handle should be
24660 20 72 65 6c 65 61 73 65 64 20 62 79 0a 2a 2a 20   released by.** 
24670 70 61 73 73 69 6e 67 20 69 74 20 74 6f 20 5b 73  passing it to [s
24680 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 20  qlite3_close()] 
24690 77 68 65 6e 20 69 74 20 69 73 20 6e 6f 20 6c 6f  when it is no lo
246a0 6e 67 65 72 20 72 65 71 75 69 72 65 64 2e 0a 2a  nger required..*
246b0 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
246c0 5f 6f 70 65 6e 5f 76 32 28 29 20 69 6e 74 65 72  _open_v2() inter
246d0 66 61 63 65 20 77 6f 72 6b 73 20 6c 69 6b 65 20  face works like 
246e0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 0a 2a  sqlite3_open().*
246f0 2a 20 65 78 63 65 70 74 20 74 68 61 74 20 69 74  * except that it
24700 20 61 63 63 65 70 74 73 20 74 77 6f 20 61 64 64   accepts two add
24710 69 74 69 6f 6e 61 6c 20 70 61 72 61 6d 65 74 65  itional paramete
24720 72 73 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61  rs for additiona
24730 6c 20 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 6f 76 65  l control.** ove
24740 72 20 74 68 65 20 6e 65 77 20 64 61 74 61 62 61  r the new databa
24750 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20  se connection.  
24760 5e 28 54 68 65 20 66 6c 61 67 73 20 70 61 72 61  ^(The flags para
24770 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 73 71 6c 69  meter to.** sqli
24780 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 63 61  te3_open_v2() ca
24790 6e 20 74 61 6b 65 20 6f 6e 65 20 6f 66 0a 2a 2a  n take one of.**
247a0 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74   the following t
247b0 68 72 65 65 20 76 61 6c 75 65 73 2c 20 6f 70 74  hree values, opt
247c0 69 6f 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e 65 64  ionally combined
247d0 20 77 69 74 68 20 74 68 65 20 0a 2a 2a 20 5b 53   with the .** [S
247e0 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54  QLITE_OPEN_NOMUT
247f0 45 58 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 50 45  EX], [SQLITE_OPE
24800 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d 2c 20 5b 53  N_FULLMUTEX], [S
24810 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45  QLITE_OPEN_SHARE
24820 44 43 41 43 48 45 5d 2c 0a 2a 2a 20 5b 53 51 4c  DCACHE],.** [SQL
24830 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45  ITE_OPEN_PRIVATE
24840 43 41 43 48 45 5d 2c 20 61 6e 64 2f 6f 72 20 5b  CACHE], and/or [
24850 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d  SQLITE_OPEN_URI]
24860 20 66 6c 61 67 73 3a 29 5e 0a 2a 2a 0a 2a 2a 20   flags:)^.**.** 
24870 3c 64 6c 3e 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53  <dl>.** ^(<dt>[S
24880 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f  QLITE_OPEN_READO
24890 4e 4c 59 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  NLY]</dt>.** <dd
248a0 3e 54 68 65 20 64 61 74 61 62 61 73 65 20 69 73  >The database is
248b0 20 6f 70 65 6e 65 64 20 69 6e 20 72 65 61 64 2d   opened in read-
248c0 6f 6e 6c 79 20 6d 6f 64 65 2e 20 20 49 66 20 74  only mode.  If t
248d0 68 65 20 64 61 74 61 62 61 73 65 20 64 6f 65 73  he database does
248e0 20 6e 6f 74 0a 2a 2a 20 61 6c 72 65 61 64 79 20   not.** already 
248f0 65 78 69 73 74 2c 20 61 6e 20 65 72 72 6f 72 20  exist, an error 
24900 69 73 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64  is returned.</dd
24910 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e  >)^.**.** ^(<dt>
24920 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41  [SQLITE_OPEN_REA
24930 44 57 52 49 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20  DWRITE]</dt>.** 
24940 3c 64 64 3e 54 68 65 20 64 61 74 61 62 61 73 65  <dd>The database
24950 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72   is opened for r
24960 65 61 64 69 6e 67 20 61 6e 64 20 77 72 69 74 69  eading and writi
24970 6e 67 20 69 66 20 70 6f 73 73 69 62 6c 65 2c 20  ng if possible, 
24980 6f 72 20 72 65 61 64 69 6e 67 0a 2a 2a 20 6f 6e  or reading.** on
24990 6c 79 20 69 66 20 74 68 65 20 66 69 6c 65 20 69  ly if the file i
249a0 73 20 77 72 69 74 65 20 70 72 6f 74 65 63 74 65  s write protecte
249b0 64 20 62 79 20 74 68 65 20 6f 70 65 72 61 74 69  d by the operati
249c0 6e 67 20 73 79 73 74 65 6d 2e 20 20 49 6e 20 65  ng system.  In e
249d0 69 74 68 65 72 0a 2a 2a 20 63 61 73 65 20 74 68  ither.** case th
249e0 65 20 64 61 74 61 62 61 73 65 20 6d 75 73 74 20  e database must 
249f0 61 6c 72 65 61 64 79 20 65 78 69 73 74 2c 20 6f  already exist, o
24a00 74 68 65 72 77 69 73 65 20 61 6e 20 65 72 72 6f  therwise an erro
24a10 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 3c 2f  r is returned.</
24a20 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64  dd>)^.**.** ^(<d
24a30 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52  t>[SQLITE_OPEN_R
24a40 45 41 44 57 52 49 54 45 5d 20 7c 20 5b 53 51 4c  EADWRITE] | [SQL
24a50 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d  ITE_OPEN_CREATE]
24a60 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
24a70 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65   database is ope
24a80 6e 65 64 20 66 6f 72 20 72 65 61 64 69 6e 67 20  ned for reading 
24a90 61 6e 64 20 77 72 69 74 69 6e 67 2c 20 61 6e 64  and writing, and
24aa0 20 69 73 20 63 72 65 61 74 65 64 20 69 66 0a 2a   is created if.*
24ab0 2a 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 61 6c  * it does not al
24ac0 72 65 61 64 79 20 65 78 69 73 74 2e 20 54 68 69  ready exist. Thi
24ad0 73 20 69 73 20 74 68 65 20 62 65 68 61 76 69 6f  s is the behavio
24ae0 72 20 74 68 61 74 20 69 73 20 61 6c 77 61 79 73  r that is always
24af0 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20 73 71 6c   used for.** sql
24b00 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20  ite3_open() and 
24b10 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29  sqlite3_open16()
24b20 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c  .</dd>)^.** </dl
24b30 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 33  >.**.** If the 3
24b40 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  rd parameter to 
24b50 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
24b60 29 20 69 73 20 6e 6f 74 20 6f 6e 65 20 6f 66 20  ) is not one of 
24b70 74 68 65 0a 2a 2a 20 63 6f 6d 62 69 6e 61 74 69  the.** combinati
24b80 6f 6e 73 20 73 68 6f 77 6e 20 61 62 6f 76 65 20  ons shown above 
24b90 6f 70 74 69 6f 6e 61 6c 6c 79 20 63 6f 6d 62 69  optionally combi
24ba0 6e 65 64 20 77 69 74 68 20 6f 74 68 65 72 0a 2a  ned with other.*
24bb0 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52  * [SQLITE_OPEN_R
24bc0 45 41 44 4f 4e 4c 59 20 7c 20 53 51 4c 49 54 45  EADONLY | SQLITE
24bd0 5f 4f 50 45 4e 5f 2a 20 62 69 74 73 5d 0a 2a 2a  _OPEN_* bits].**
24be0 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69   then the behavi
24bf0 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e  or is undefined.
24c00 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 5b  .**.** ^If the [
24c10 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55  SQLITE_OPEN_NOMU
24c20 54 45 58 5d 20 66 6c 61 67 20 69 73 20 73 65 74  TEX] flag is set
24c30 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62  , then the datab
24c40 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a  ase connection.*
24c50 2a 20 6f 70 65 6e 73 20 69 6e 20 74 68 65 20 6d  * opens in the m
24c60 75 6c 74 69 2d 74 68 72 65 61 64 20 5b 74 68 72  ulti-thread [thr
24c70 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61 73 20  eading mode] as 
24c80 6c 6f 6e 67 20 61 73 20 74 68 65 20 73 69 6e 67  long as the sing
24c90 6c 65 2d 74 68 72 65 61 64 0a 2a 2a 20 6d 6f 64  le-thread.** mod
24ca0 65 20 68 61 73 20 6e 6f 74 20 62 65 65 6e 20 73  e has not been s
24cb0 65 74 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69  et at compile-ti
24cc0 6d 65 20 6f 72 20 73 74 61 72 74 2d 74 69 6d 65  me or start-time
24cd0 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 5b 53  .  ^If the.** [S
24ce0 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d  QLITE_OPEN_FULLM
24cf0 55 54 45 58 5d 20 66 6c 61 67 20 69 73 20 73 65  UTEX] flag is se
24d00 74 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62  t then the datab
24d10 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6f  ase connection o
24d20 70 65 6e 73 0a 2a 2a 20 69 6e 20 74 68 65 20 73  pens.** in the s
24d30 65 72 69 61 6c 69 7a 65 64 20 5b 74 68 72 65 61  erialized [threa
24d40 64 69 6e 67 20 6d 6f 64 65 5d 20 75 6e 6c 65 73  ding mode] unles
24d50 73 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 20  s single-thread 
24d60 77 61 73 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c  was.** previousl
24d70 79 20 73 65 6c 65 63 74 65 64 20 61 74 20 63 6f  y selected at co
24d80 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 72 20 73 74  mpile-time or st
24d90 61 72 74 2d 74 69 6d 65 2e 0a 2a 2a 20 5e 54 68  art-time..** ^Th
24da0 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53  e [SQLITE_OPEN_S
24db0 48 41 52 45 44 43 41 43 48 45 5d 20 66 6c 61 67  HAREDCACHE] flag
24dc0 20 63 61 75 73 65 73 20 74 68 65 20 64 61 74 61   causes the data
24dd0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
24de0 74 6f 20 62 65 0a 2a 2a 20 65 6c 69 67 69 62 6c  to be.** eligibl
24df0 65 20 74 6f 20 75 73 65 20 5b 73 68 61 72 65 64  e to use [shared
24e00 20 63 61 63 68 65 20 6d 6f 64 65 5d 2c 20 72 65   cache mode], re
24e10 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74  gardless of whet
24e20 68 65 72 20 6f 72 20 6e 6f 74 20 73 68 61 72 65  her or not share
24e30 64 0a 2a 2a 20 63 61 63 68 65 20 69 73 20 65 6e  d.** cache is en
24e40 61 62 6c 65 64 20 75 73 69 6e 67 20 5b 73 71 6c  abled using [sql
24e50 69 74 65 33 5f 65 6e 61 62 6c 65 5f 73 68 61 72  ite3_enable_shar
24e60 65 64 5f 63 61 63 68 65 28 29 5d 2e 20 20 5e 54  ed_cache()].  ^T
24e70 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50  he.** [SQLITE_OP
24e80 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45 5d  EN_PRIVATECACHE]
24e90 20 66 6c 61 67 20 63 61 75 73 65 73 20 74 68 65   flag causes the
24ea0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
24eb0 74 69 6f 6e 20 74 6f 20 6e 6f 74 0a 2a 2a 20 70  tion to not.** p
24ec0 61 72 74 69 63 69 70 61 74 65 20 69 6e 20 5b 73  articipate in [s
24ed0 68 61 72 65 64 20 63 61 63 68 65 20 6d 6f 64 65  hared cache mode
24ee0 5d 20 65 76 65 6e 20 69 66 20 69 74 20 69 73 20  ] even if it is 
24ef0 65 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  enabled..**.** ^
24f00 54 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  The fourth param
24f10 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
24f20 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 74 68 65  open_v2() is the
24f30 20 6e 61 6d 65 20 6f 66 20 74 68 65 0a 2a 2a 20   name of the.** 
24f40 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62  [sqlite3_vfs] ob
24f50 6a 65 63 74 20 74 68 61 74 20 64 65 66 69 6e 65  ject that define
24f60 73 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20  s the operating 
24f70 73 79 73 74 65 6d 20 69 6e 74 65 72 66 61 63 65  system interface
24f80 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 6e 65 77   that.** the new
24f90 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
24fa0 74 69 6f 6e 20 73 68 6f 75 6c 64 20 75 73 65 2e  tion should use.
24fb0 20 20 5e 49 66 20 74 68 65 20 66 6f 75 72 74 68    ^If the fourth
24fc0 20 70 61 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a   parameter is.**
24fd0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
24fe0 74 68 65 6e 20 74 68 65 20 64 65 66 61 75 6c 74  then the default
24ff0 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f   [sqlite3_vfs] o
25000 62 6a 65 63 74 20 69 73 20 75 73 65 64 2e 0a 2a  bject is used..*
25010 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 6c  *.** ^If the fil
25020 65 6e 61 6d 65 20 69 73 20 22 3a 6d 65 6d 6f 72  ename is ":memor
25030 79 3a 22 2c 20 74 68 65 6e 20 61 20 70 72 69 76  y:", then a priv
25040 61 74 65 2c 20 74 65 6d 70 6f 72 61 72 79 20 69  ate, temporary i
25050 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73  n-memory databas
25060 65 0a 2a 2a 20 69 73 20 63 72 65 61 74 65 64 20  e.** is created 
25070 66 6f 72 20 74 68 65 20 63 6f 6e 6e 65 63 74 69  for the connecti
25080 6f 6e 2e 20 20 5e 54 68 69 73 20 69 6e 2d 6d 65  on.  ^This in-me
25090 6d 6f 72 79 20 64 61 74 61 62 61 73 65 20 77 69  mory database wi
250a0 6c 6c 20 76 61 6e 69 73 68 20 77 68 65 6e 0a 2a  ll vanish when.*
250b0 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  * the database c
250c0 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f  onnection is clo
250d0 73 65 64 2e 20 20 46 75 74 75 72 65 20 76 65 72  sed.  Future ver
250e0 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20  sions of SQLite 
250f0 6d 69 67 68 74 0a 2a 2a 20 6d 61 6b 65 20 75 73  might.** make us
25100 65 20 6f 66 20 61 64 64 69 74 69 6f 6e 61 6c 20  e of additional 
25110 73 70 65 63 69 61 6c 20 66 69 6c 65 6e 61 6d 65  special filename
25120 73 20 74 68 61 74 20 62 65 67 69 6e 20 77 69 74  s that begin wit
25130 68 20 74 68 65 20 22 3a 22 20 63 68 61 72 61 63  h the ":" charac
25140 74 65 72 2e 0a 2a 2a 20 49 74 20 69 73 20 72 65  ter..** It is re
25150 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 77  commended that w
25160 68 65 6e 20 61 20 64 61 74 61 62 61 73 65 20 66  hen a database f
25170 69 6c 65 6e 61 6d 65 20 61 63 74 75 61 6c 6c 79  ilename actually
25180 20 64 6f 65 73 20 62 65 67 69 6e 20 77 69 74 68   does begin with
25190 0a 2a 2a 20 61 20 22 3a 22 20 63 68 61 72 61 63  .** a ":" charac
251a0 74 65 72 20 79 6f 75 20 73 68 6f 75 6c 64 20 70  ter you should p
251b0 72 65 66 69 78 20 74 68 65 20 66 69 6c 65 6e 61  refix the filena
251c0 6d 65 20 77 69 74 68 20 61 20 70 61 74 68 6e 61  me with a pathna
251d0 6d 65 20 73 75 63 68 20 61 73 0a 2a 2a 20 22 2e  me such as.** ".
251e0 2f 22 20 74 6f 20 61 76 6f 69 64 20 61 6d 62 69  /" to avoid ambi
251f0 67 75 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  guity..**.** ^If
25200 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73   the filename is
25210 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67   an empty string
25220 2c 20 74 68 65 6e 20 61 20 70 72 69 76 61 74 65  , then a private
25230 2c 20 74 65 6d 70 6f 72 61 72 79 0a 2a 2a 20 6f  , temporary.** o
25240 6e 2d 64 69 73 6b 20 64 61 74 61 62 61 73 65 20  n-disk database 
25250 77 69 6c 6c 20 62 65 20 63 72 65 61 74 65 64 2e  will be created.
25260 20 20 5e 54 68 69 73 20 70 72 69 76 61 74 65 20    ^This private 
25270 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62 65  database will be
25280 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  .** automaticall
25290 79 20 64 65 6c 65 74 65 64 20 61 73 20 73 6f 6f  y deleted as soo
252a0 6e 20 61 73 20 74 68 65 20 64 61 74 61 62 61 73  n as the databas
252b0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20  e connection is 
252c0 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 5b 5b  closed..**.** [[
252d0 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 20 69 6e  URI filenames in
252e0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d   sqlite3_open()]
252f0 5d 20 3c 68 33 3e 55 52 49 20 46 69 6c 65 6e 61  ] <h3>URI Filena
25300 6d 65 73 3c 2f 68 33 3e 0a 2a 2a 0a 2a 2a 20 5e  mes</h3>.**.** ^
25310 49 66 20 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65  If [URI filename
25320 5d 20 69 6e 74 65 72 70 72 65 74 61 74 69 6f 6e  ] interpretation
25330 20 69 73 20 65 6e 61 62 6c 65 64 2c 20 61 6e 64   is enabled, and
25340 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72   the filename ar
25350 67 75 6d 65 6e 74 0a 2a 2a 20 62 65 67 69 6e 73  gument.** begins
25360 20 77 69 74 68 20 22 66 69 6c 65 3a 22 2c 20 74   with "file:", t
25370 68 65 6e 20 74 68 65 20 66 69 6c 65 6e 61 6d 65  hen the filename
25380 20 69 73 20 69 6e 74 65 72 70 72 65 74 65 64 20   is interpreted 
25390 61 73 20 61 20 55 52 49 2e 20 5e 55 52 49 0a 2a  as a URI. ^URI.*
253a0 2a 20 66 69 6c 65 6e 61 6d 65 20 69 6e 74 65 72  * filename inter
253b0 70 72 65 74 61 74 69 6f 6e 20 69 73 20 65 6e 61  pretation is ena
253c0 62 6c 65 64 20 69 66 20 74 68 65 20 5b 53 51 4c  bled if the [SQL
253d0 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 66 6c  ITE_OPEN_URI] fl
253e0 61 67 20 69 73 0a 2a 2a 20 73 65 74 20 69 6e 20  ag is.** set in 
253f0 74 68 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d  the fourth argum
25400 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f  ent to sqlite3_o
25410 70 65 6e 5f 76 32 28 29 2c 20 6f 72 20 69 66 20  pen_v2(), or if 
25420 69 74 20 68 61 73 0a 2a 2a 20 62 65 65 6e 20 65  it has.** been e
25430 6e 61 62 6c 65 64 20 67 6c 6f 62 61 6c 6c 79 20  nabled globally 
25440 75 73 69 6e 67 20 74 68 65 20 5b 53 51 4c 49 54  using the [SQLIT
25450 45 5f 43 4f 4e 46 49 47 5f 55 52 49 5d 20 6f 70  E_CONFIG_URI] op
25460 74 69 6f 6e 20 77 69 74 68 20 74 68 65 0a 2a 2a  tion with the.**
25470 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
25480 28 29 5d 20 6d 65 74 68 6f 64 20 6f 72 20 62 79  ()] method or by
25490 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 55 53 45   the [SQLITE_USE
254a0 5f 55 52 49 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  _URI] compile-ti
254b0 6d 65 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 41 73  me option..** As
254c0 20 6f 66 20 53 51 4c 69 74 65 20 76 65 72 73 69   of SQLite versi
254d0 6f 6e 20 33 2e 37 2e 37 2c 20 55 52 49 20 66 69  on 3.7.7, URI fi
254e0 6c 65 6e 61 6d 65 20 69 6e 74 65 72 70 72 65 74  lename interpret
254f0 61 74 69 6f 6e 20 69 73 20 74 75 72 6e 65 64 20  ation is turned 
25500 6f 66 66 0a 2a 2a 20 62 79 20 64 65 66 61 75 6c  off.** by defaul
25510 74 2c 20 62 75 74 20 66 75 74 75 72 65 20 72 65  t, but future re
25520 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65  leases of SQLite
25530 20 6d 69 67 68 74 20 65 6e 61 62 6c 65 20 55 52   might enable UR
25540 49 20 66 69 6c 65 6e 61 6d 65 0a 2a 2a 20 69 6e  I filename.** in
25550 74 65 72 70 72 65 74 61 74 69 6f 6e 20 62 79 20  terpretation by 
25560 64 65 66 61 75 6c 74 2e 20 20 53 65 65 20 22 5b  default.  See "[
25570 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 5d 22 20  URI filenames]" 
25580 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a  for additional.*
25590 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a  * information..*
255a0 2a 0a 2a 2a 20 55 52 49 20 66 69 6c 65 6e 61 6d  *.** URI filenam
255b0 65 73 20 61 72 65 20 70 61 72 73 65 64 20 61 63  es are parsed ac
255c0 63 6f 72 64 69 6e 67 20 74 6f 20 52 46 43 20 33  cording to RFC 3
255d0 39 38 36 2e 20 5e 49 66 20 74 68 65 20 55 52 49  986. ^If the URI
255e0 20 63 6f 6e 74 61 69 6e 73 20 61 6e 0a 2a 2a 20   contains an.** 
255f0 61 75 74 68 6f 72 69 74 79 2c 20 74 68 65 6e 20  authority, then 
25600 69 74 20 6d 75 73 74 20 62 65 20 65 69 74 68 65  it must be eithe
25610 72 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e  r an empty strin
25620 67 20 6f 72 20 74 68 65 20 73 74 72 69 6e 67 20  g or the string 
25630 0a 2a 2a 20 22 6c 6f 63 61 6c 68 6f 73 74 22 2e  .** "localhost".
25640 20 5e 49 66 20 74 68 65 20 61 75 74 68 6f 72 69   ^If the authori
25650 74 79 20 69 73 20 6e 6f 74 20 61 6e 20 65 6d 70  ty is not an emp
25660 74 79 20 73 74 72 69 6e 67 20 6f 72 20 22 6c 6f  ty string or "lo
25670 63 61 6c 68 6f 73 74 22 2c 20 61 6e 20 0a 2a 2a  calhost", an .**
25680 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e   error is return
25690 65 64 20 74 6f 20 74 68 65 20 63 61 6c 6c 65 72  ed to the caller
256a0 2e 20 5e 54 68 65 20 66 72 61 67 6d 65 6e 74 20  . ^The fragment 
256b0 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 20 55  component of a U
256c0 52 49 2c 20 69 66 20 0a 2a 2a 20 70 72 65 73 65  RI, if .** prese
256d0 6e 74 2c 20 69 73 20 69 67 6e 6f 72 65 64 2e 0a  nt, is ignored..
256e0 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 75 73  **.** ^SQLite us
256f0 65 73 20 74 68 65 20 70 61 74 68 20 63 6f 6d 70  es the path comp
25700 6f 6e 65 6e 74 20 6f 66 20 74 68 65 20 55 52 49  onent of the URI
25710 20 61 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20   as the name of 
25720 74 68 65 20 64 69 73 6b 20 66 69 6c 65 0a 2a 2a  the disk file.**
25730 20 77 68 69 63 68 20 63 6f 6e 74 61 69 6e 73 20   which contains 
25740 74 68 65 20 64 61 74 61 62 61 73 65 2e 20 5e 49  the database. ^I
25750 66 20 74 68 65 20 70 61 74 68 20 62 65 67 69 6e  f the path begin
25760 73 20 77 69 74 68 20 61 20 27 2f 27 20 63 68 61  s with a '/' cha
25770 72 61 63 74 65 72 2c 20 0a 2a 2a 20 74 68 65 6e  racter, .** then
25780 20 69 74 20 69 73 20 69 6e 74 65 72 70 72 65 74   it is interpret
25790 65 64 20 61 73 20 61 6e 20 61 62 73 6f 6c 75 74  ed as an absolut
257a0 65 20 70 61 74 68 2e 20 5e 49 66 20 74 68 65 20  e path. ^If the 
257b0 70 61 74 68 20 64 6f 65 73 20 6e 6f 74 20 62 65  path does not be
257c0 67 69 6e 20 0a 2a 2a 20 77 69 74 68 20 61 20 27  gin .** with a '
257d0 2f 27 20 28 6d 65 61 6e 69 6e 67 20 74 68 61 74  /' (meaning that
257e0 20 74 68 65 20 61 75 74 68 6f 72 69 74 79 20 73   the authority s
257f0 65 63 74 69 6f 6e 20 69 73 20 6f 6d 69 74 74 65  ection is omitte
25800 64 20 66 72 6f 6d 20 74 68 65 20 55 52 49 29 0a  d from the URI).
25810 2a 2a 20 74 68 65 6e 20 74 68 65 20 70 61 74 68  ** then the path
25820 20 69 73 20 69 6e 74 65 72 70 72 65 74 65 64 20   is interpreted 
25830 61 73 20 61 20 72 65 6c 61 74 69 76 65 20 70 61  as a relative pa
25840 74 68 2e 20 0a 2a 2a 20 5e 28 4f 6e 20 77 69 6e  th. .** ^(On win
25850 64 6f 77 73 2c 20 74 68 65 20 66 69 72 73 74 20  dows, the first 
25860 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 6e 20  component of an 
25870 61 62 73 6f 6c 75 74 65 20 70 61 74 68 20 0a 2a  absolute path .*
25880 2a 20 69 73 20 61 20 64 72 69 76 65 20 73 70 65  * is a drive spe
25890 63 69 66 69 63 61 74 69 6f 6e 20 28 65 2e 67 2e  cification (e.g.
258a0 20 22 43 3a 22 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20   "C:").)^.**.** 
258b0 5b 5b 63 6f 72 65 20 55 52 49 20 71 75 65 72 79  [[core URI query
258c0 20 70 61 72 61 6d 65 74 65 72 73 5d 5d 0a 2a 2a   parameters]].**
258d0 20 54 68 65 20 71 75 65 72 79 20 63 6f 6d 70 6f   The query compo
258e0 6e 65 6e 74 20 6f 66 20 61 20 55 52 49 20 6d 61  nent of a URI ma
258f0 79 20 63 6f 6e 74 61 69 6e 20 70 61 72 61 6d 65  y contain parame
25900 74 65 72 73 20 74 68 61 74 20 61 72 65 20 69 6e  ters that are in
25910 74 65 72 70 72 65 74 65 64 0a 2a 2a 20 65 69 74  terpreted.** eit
25920 68 65 72 20 62 79 20 53 51 4c 69 74 65 20 69 74  her by SQLite it
25930 73 65 6c 66 2c 20 6f 72 20 62 79 20 61 20 5b 56  self, or by a [V
25940 46 53 20 7c 20 63 75 73 74 6f 6d 20 56 46 53 20  FS | custom VFS 
25950 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 5d 2e  implementation].
25960 0a 2a 2a 20 53 51 4c 69 74 65 20 61 6e 64 20 69  .** SQLite and i
25970 74 73 20 62 75 69 6c 74 2d 69 6e 20 5b 56 46 53  ts built-in [VFS
25980 65 73 5d 20 69 6e 74 65 72 70 72 65 74 20 74 68  es] interpret th
25990 65 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 71  e.** following q
259a0 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 73 3a  uery parameters:
259b0 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20  .**.** <ul>.**  
259c0 20 3c 6c 69 3e 20 3c 62 3e 76 66 73 3c 2f 62 3e   <li> <b>vfs</b>
259d0 3a 20 5e 54 68 65 20 22 76 66 73 22 20 70 61 72  : ^The "vfs" par
259e0 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20 75 73  ameter may be us
259f0 65 64 20 74 6f 20 73 70 65 63 69 66 79 20 74 68  ed to specify th
25a00 65 20 6e 61 6d 65 20 6f 66 0a 2a 2a 20 20 20 20  e name of.**    
25a10 20 61 20 56 46 53 20 6f 62 6a 65 63 74 20 74 68   a VFS object th
25a20 61 74 20 70 72 6f 76 69 64 65 73 20 74 68 65 20  at provides the 
25a30 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d  operating system
25a40 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 20   interface that 
25a50 73 68 6f 75 6c 64 0a 2a 2a 20 20 20 20 20 62 65  should.**     be
25a60 20 75 73 65 64 20 74 6f 20 61 63 63 65 73 73 20   used to access 
25a70 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
25a80 65 20 6f 6e 20 64 69 73 6b 2e 20 5e 49 66 20 74  e on disk. ^If t
25a90 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 73 65  his option is se
25aa0 74 20 74 6f 0a 2a 2a 20 20 20 20 20 61 6e 20 65  t to.**     an e
25ab0 6d 70 74 79 20 73 74 72 69 6e 67 20 74 68 65 20  mpty string the 
25ac0 64 65 66 61 75 6c 74 20 56 46 53 20 6f 62 6a 65  default VFS obje
25ad0 63 74 20 69 73 20 75 73 65 64 2e 20 5e 53 70 65  ct is used. ^Spe
25ae0 63 69 66 79 69 6e 67 20 61 6e 20 75 6e 6b 6e 6f  cifying an unkno
25af0 77 6e 0a 2a 2a 20 20 20 20 20 56 46 53 20 69 73  wn.**     VFS is
25b00 20 61 6e 20 65 72 72 6f 72 2e 20 5e 49 66 20 73   an error. ^If s
25b10 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
25b20 20 69 73 20 75 73 65 64 20 61 6e 64 20 74 68 65   is used and the
25b30 20 76 66 73 20 6f 70 74 69 6f 6e 20 69 73 0a 2a   vfs option is.*
25b40 2a 20 20 20 20 20 70 72 65 73 65 6e 74 2c 20 74  *     present, t
25b50 68 65 6e 20 74 68 65 20 56 46 53 20 73 70 65 63  hen the VFS spec
25b60 69 66 69 65 64 20 62 79 20 74 68 65 20 6f 70 74  ified by the opt
25b70 69 6f 6e 20 74 61 6b 65 73 20 70 72 65 63 65 64  ion takes preced
25b80 65 6e 63 65 20 6f 76 65 72 0a 2a 2a 20 20 20 20  ence over.**    
25b90 20 74 68 65 20 76 61 6c 75 65 20 70 61 73 73 65   the value passe
25ba0 64 20 61 73 20 74 68 65 20 66 6f 75 72 74 68 20  d as the fourth 
25bb0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
25bc0 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a  ite3_open_v2()..
25bd0 2a 2a 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e  **.**   <li> <b>
25be0 6d 6f 64 65 3c 2f 62 3e 3a 20 5e 28 54 68 65 20  mode</b>: ^(The 
25bf0 6d 6f 64 65 20 70 61 72 61 6d 65 74 65 72 20 6d  mode parameter m
25c00 61 79 20 62 65 20 73 65 74 20 74 6f 20 65 69 74  ay be set to eit
25c10 68 65 72 20 22 72 6f 22 2c 20 22 72 77 22 2c 0a  her "ro", "rw",.
25c20 2a 2a 20 20 20 20 20 22 72 77 63 22 2c 20 6f 72  **     "rwc", or
25c30 20 22 6d 65 6d 6f 72 79 22 2e 20 41 74 74 65 6d   "memory". Attem
25c40 70 74 69 6e 67 20 74 6f 20 73 65 74 20 69 74 20  pting to set it 
25c50 74 6f 20 61 6e 79 20 6f 74 68 65 72 20 76 61 6c  to any other val
25c60 75 65 20 69 73 0a 2a 2a 20 20 20 20 20 61 6e 20  ue is.**     an 
25c70 65 72 72 6f 72 29 5e 2e 20 0a 2a 2a 20 20 20 20  error)^. .**    
25c80 20 5e 49 66 20 22 72 6f 22 20 69 73 20 73 70 65   ^If "ro" is spe
25c90 63 69 66 69 65 64 2c 20 74 68 65 6e 20 74 68 65  cified, then the
25ca0 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65   database is ope
25cb0 6e 65 64 20 66 6f 72 20 72 65 61 64 2d 6f 6e 6c  ned for read-onl
25cc0 79 20 0a 2a 2a 20 20 20 20 20 61 63 63 65 73 73  y .**     access
25cd0 2c 20 6a 75 73 74 20 61 73 20 69 66 20 74 68 65  , just as if the
25ce0 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45   [SQLITE_OPEN_RE
25cf0 41 44 4f 4e 4c 59 5d 20 66 6c 61 67 20 68 61 64  ADONLY] flag had
25d00 20 62 65 65 6e 20 73 65 74 20 69 6e 20 74 68 65   been set in the
25d10 20 0a 2a 2a 20 20 20 20 20 74 68 69 72 64 20 61   .**     third a
25d20 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74  rgument to sqlit
25d30 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 5e 49  e3_open_v2(). ^I
25d40 66 20 74 68 65 20 6d 6f 64 65 20 6f 70 74 69 6f  f the mode optio
25d50 6e 20 69 73 20 73 65 74 20 74 6f 20 0a 2a 2a 20  n is set to .** 
25d60 20 20 20 20 22 72 77 22 2c 20 74 68 65 6e 20 74      "rw", then t
25d70 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f  he database is o
25d80 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64 2d 77  pened for read-w
25d90 72 69 74 65 20 28 62 75 74 20 6e 6f 74 20 63 72  rite (but not cr
25da0 65 61 74 65 29 20 0a 2a 2a 20 20 20 20 20 61 63  eate) .**     ac
25db0 63 65 73 73 2c 20 61 73 20 69 66 20 53 51 4c 49  cess, as if SQLI
25dc0 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54  TE_OPEN_READWRIT
25dd0 45 20 28 62 75 74 20 6e 6f 74 20 53 51 4c 49 54  E (but not SQLIT
25de0 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 29 20 68  E_OPEN_CREATE) h
25df0 61 64 20 0a 2a 2a 20 20 20 20 20 62 65 65 6e 20  ad .**     been 
25e00 73 65 74 2e 20 5e 56 61 6c 75 65 20 22 72 77 63  set. ^Value "rwc
25e10 22 20 69 73 20 65 71 75 69 76 61 6c 65 6e 74 20  " is equivalent 
25e20 74 6f 20 73 65 74 74 69 6e 67 20 62 6f 74 68 20  to setting both 
25e30 0a 2a 2a 20 20 20 20 20 53 51 4c 49 54 45 5f 4f  .**     SQLITE_O
25e40 50 45 4e 5f 52 45 41 44 57 52 49 54 45 20 61 6e  PEN_READWRITE an
25e50 64 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52  d SQLITE_OPEN_CR
25e60 45 41 54 45 2e 20 20 5e 49 66 20 74 68 65 20 6d  EATE.  ^If the m
25e70 6f 64 65 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a  ode option is.**
25e80 20 20 20 20 20 73 65 74 20 74 6f 20 22 6d 65 6d       set to "mem
25e90 6f 72 79 22 20 74 68 65 6e 20 61 20 70 75 72 65  ory" then a pure
25ea0 20 5b 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61   [in-memory data
25eb0 62 61 73 65 5d 20 74 68 61 74 20 6e 65 76 65 72  base] that never
25ec0 20 72 65 61 64 73 0a 2a 2a 20 20 20 20 20 6f 72   reads.**     or
25ed0 20 77 72 69 74 65 73 20 66 72 6f 6d 20 64 69 73   writes from dis
25ee0 6b 20 69 73 20 75 73 65 64 2e 20 5e 49 74 20 69  k is used. ^It i
25ef0 73 20 61 6e 20 65 72 72 6f 72 20 74 6f 20 73 70  s an error to sp
25f00 65 63 69 66 79 20 61 20 76 61 6c 75 65 20 66 6f  ecify a value fo
25f10 72 0a 2a 2a 20 20 20 20 20 74 68 65 20 6d 6f 64  r.**     the mod
25f20 65 20 70 61 72 61 6d 65 74 65 72 20 74 68 61 74  e parameter that
25f30 20 69 73 20 6c 65 73 73 20 72 65 73 74 72 69 63   is less restric
25f40 74 69 76 65 20 74 68 61 6e 20 74 68 61 74 20 73  tive than that s
25f50 70 65 63 69 66 69 65 64 20 62 79 0a 2a 2a 20 20  pecified by.**  
25f60 20 20 20 74 68 65 20 66 6c 61 67 73 20 70 61 73     the flags pas
25f70 73 65 64 20 69 6e 20 74 68 65 20 74 68 69 72 64  sed in the third
25f80 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
25f90 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e  lite3_open_v2().
25fa0 0a 2a 2a 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62  .**.**   <li> <b
25fb0 3e 63 61 63 68 65 3c 2f 62 3e 3a 20 5e 54 68 65  >cache</b>: ^The
25fc0 20 63 61 63 68 65 20 70 61 72 61 6d 65 74 65 72   cache parameter
25fd0 20 6d 61 79 20 62 65 20 73 65 74 20 74 6f 20 65   may be set to e
25fe0 69 74 68 65 72 20 22 73 68 61 72 65 64 22 20 6f  ither "shared" o
25ff0 72 0a 2a 2a 20 20 20 20 20 22 70 72 69 76 61 74  r.**     "privat
26000 65 22 2e 20 5e 53 65 74 74 69 6e 67 20 69 74 20  e". ^Setting it 
26010 74 6f 20 22 73 68 61 72 65 64 22 20 69 73 20 65  to "shared" is e
26020 71 75 69 76 61 6c 65 6e 74 20 74 6f 20 73 65 74  quivalent to set
26030 74 69 6e 67 20 74 68 65 0a 2a 2a 20 20 20 20 20  ting the.**     
26040 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52  SQLITE_OPEN_SHAR
26050 45 44 43 41 43 48 45 20 62 69 74 20 69 6e 20 74  EDCACHE bit in t
26060 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e  he flags argumen
26070 74 20 70 61 73 73 65 64 20 74 6f 0a 2a 2a 20 20  t passed to.**  
26080 20 20 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f     sqlite3_open_
26090 76 32 28 29 2e 20 5e 53 65 74 74 69 6e 67 20 74  v2(). ^Setting t
260a0 68 65 20 63 61 63 68 65 20 70 61 72 61 6d 65 74  he cache paramet
260b0 65 72 20 74 6f 20 22 70 72 69 76 61 74 65 22 20  er to "private" 
260c0 69 73 20 0a 2a 2a 20 20 20 20 20 65 71 75 69 76  is .**     equiv
260d0 61 6c 65 6e 74 20 74 6f 20 73 65 74 74 69 6e 67  alent to setting
260e0 20 74 68 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e   the SQLITE_OPEN
260f0 5f 50 52 49 56 41 54 45 43 41 43 48 45 20 62 69  _PRIVATECACHE bi
26100 74 2e 0a 2a 2a 20 20 20 20 20 5e 49 66 20 73 71  t..**     ^If sq
26110 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
26120 69 73 20 75 73 65 64 20 61 6e 64 20 74 68 65 20  is used and the 
26130 22 63 61 63 68 65 22 20 70 61 72 61 6d 65 74 65  "cache" paramete
26140 72 20 69 73 20 70 72 65 73 65 6e 74 20 69 6e 0a  r is present in.
26150 2a 2a 20 20 20 20 20 61 20 55 52 49 20 66 69 6c  **     a URI fil
26160 65 6e 61 6d 65 2c 20 69 74 73 20 76 61 6c 75 65  ename, its value
26170 20 6f 76 65 72 72 69 64 65 73 20 61 6e 79 20 62   overrides any b
26180 65 68 61 76 69 6f 72 20 72 65 71 75 65 73 74 65  ehavior requeste
26190 64 20 62 79 20 73 65 74 74 69 6e 67 0a 2a 2a 20  d by setting.** 
261a0 20 20 20 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f      SQLITE_OPEN_
261b0 50 52 49 56 41 54 45 43 41 43 48 45 20 6f 72 20  PRIVATECACHE or 
261c0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52  SQLITE_OPEN_SHAR
261d0 45 44 43 41 43 48 45 20 66 6c 61 67 2e 0a 2a 2a  EDCACHE flag..**
261e0 0a 2a 2a 20 20 3c 6c 69 3e 20 3c 62 3e 70 73 6f  .**  <li> <b>pso
261f0 77 3c 2f 62 3e 3a 20 5e 54 68 65 20 70 73 6f 77  w</b>: ^The psow
26200 20 70 61 72 61 6d 65 74 65 72 20 69 6e 64 69 63   parameter indic
26210 61 74 65 73 20 77 68 65 74 68 65 72 20 6f 72 20  ates whether or 
26220 6e 6f 74 20 74 68 65 0a 2a 2a 20 20 20 20 20 5b  not the.**     [
26230 70 6f 77 65 72 73 61 66 65 20 6f 76 65 72 77 72  powersafe overwr
26240 69 74 65 5d 20 70 72 6f 70 65 72 74 79 20 64 6f  ite] property do
26250 65 73 20 6f 72 20 64 6f 65 73 20 6e 6f 74 20 61  es or does not a
26260 70 70 6c 79 20 74 6f 20 74 68 65 0a 2a 2a 20 20  pply to the.**  
26270 20 20 20 73 74 6f 72 61 67 65 20 6d 65 64 69 61     storage media
26280 20 6f 6e 20 77 68 69 63 68 20 74 68 65 20 64 61   on which the da
26290 74 61 62 61 73 65 20 66 69 6c 65 20 72 65 73 69  tabase file resi
262a0 64 65 73 2e 0a 2a 2a 0a 2a 2a 20 20 3c 6c 69 3e  des..**.**  <li>
262b0 20 3c 62 3e 6e 6f 6c 6f 63 6b 3c 2f 62 3e 3a 20   <b>nolock</b>: 
262c0 5e 54 68 65 20 6e 6f 6c 6f 63 6b 20 70 61 72 61  ^The nolock para
262d0 6d 65 74 65 72 20 69 73 20 61 20 62 6f 6f 6c 65  meter is a boole
262e0 61 6e 20 71 75 65 72 79 20 70 61 72 61 6d 65 74  an query paramet
262f0 65 72 0a 2a 2a 20 20 20 20 20 77 68 69 63 68 20  er.**     which 
26300 69 66 20 73 65 74 20 64 69 73 61 62 6c 65 73 20  if set disables 
26310 66 69 6c 65 20 6c 6f 63 6b 69 6e 67 20 69 6e 20  file locking in 
26320 72 6f 6c 6c 62 61 63 6b 20 6a 6f 75 72 6e 61 6c  rollback journal
26330 20 6d 6f 64 65 73 2e 20 20 54 68 69 73 0a 2a 2a   modes.  This.**
26340 20 20 20 20 20 69 73 20 75 73 65 66 75 6c 20 66       is useful f
26350 6f 72 20 61 63 63 65 73 73 69 6e 67 20 61 20 64  or accessing a d
26360 61 74 61 62 61 73 65 20 6f 6e 20 61 20 66 69 6c  atabase on a fil
26370 65 73 79 73 74 65 6d 20 74 68 61 74 20 64 6f 65  esystem that doe
26380 73 20 6e 6f 74 0a 2a 2a 20 20 20 20 20 73 75 70  s not.**     sup
26390 70 6f 72 74 20 6c 6f 63 6b 69 6e 67 2e 20 20 43  port locking.  C
263a0 61 75 74 69 6f 6e 3a 20 20 44 61 74 61 62 61 73  aution:  Databas
263b0 65 20 63 6f 72 72 75 70 74 69 6f 6e 20 6d 69 67  e corruption mig
263c0 68 74 20 72 65 73 75 6c 74 20 69 66 20 74 77 6f  ht result if two
263d0 0a 2a 2a 20 20 20 20 20 6f 72 20 6d 6f 72 65 20  .**     or more 
263e0 70 72 6f 63 65 73 73 65 73 20 77 72 69 74 65 20  processes write 
263f0 74 6f 20 74 68 65 20 73 61 6d 65 20 64 61 74 61  to the same data
26400 62 61 73 65 20 61 6e 64 20 61 6e 79 20 6f 6e 65  base and any one
26410 20 6f 66 20 74 68 6f 73 65 0a 2a 2a 20 20 20 20   of those.**    
26420 20 70 72 6f 63 65 73 73 65 73 20 75 73 65 73 20   processes uses 
26430 6e 6f 6c 6f 63 6b 3d 31 2e 0a 2a 2a 0a 2a 2a 20  nolock=1..**.** 
26440 20 3c 6c 69 3e 20 3c 62 3e 69 6d 6d 75 74 61 62   <li> <b>immutab
26450 6c 65 3c 2f 62 3e 3a 20 5e 54 68 65 20 69 6d 6d  le</b>: ^The imm
26460 75 74 61 62 6c 65 20 70 61 72 61 6d 65 74 65 72  utable parameter
26470 20 69 73 20 61 20 62 6f 6f 6c 65 61 6e 20 71 75   is a boolean qu
26480 65 72 79 0a 2a 2a 20 20 20 20 20 70 61 72 61 6d  ery.**     param
26490 65 74 65 72 20 74 68 61 74 20 69 6e 64 69 63 61  eter that indica
264a0 74 65 73 20 74 68 61 74 20 74 68 65 20 64 61 74  tes that the dat
264b0 61 62 61 73 65 20 66 69 6c 65 20 69 73 20 73 74  abase file is st
264c0 6f 72 65 64 20 6f 6e 0a 2a 2a 20 20 20 20 20 72  ored on.**     r
264d0 65 61 64 2d 6f 6e 6c 79 20 6d 65 64 69 61 2e 20  ead-only media. 
264e0 20 5e 57 68 65 6e 20 69 6d 6d 75 74 61 62 6c 65   ^When immutable
264f0 20 69 73 20 73 65 74 2c 20 53 51 4c 69 74 65 20   is set, SQLite 
26500 61 73 73 75 6d 65 73 20 74 68 61 74 20 74 68 65  assumes that the
26510 0a 2a 2a 20 20 20 20 20 64 61 74 61 62 61 73 65  .**     database
26520 20 66 69 6c 65 20 63 61 6e 6e 6f 74 20 62 65 20   file cannot be 
26530 63 68 61 6e 67 65 64 2c 20 65 76 65 6e 20 62 79  changed, even by
26540 20 61 20 70 72 6f 63 65 73 73 20 77 69 74 68 20   a process with 
26550 68 69 67 68 65 72 0a 2a 2a 20 20 20 20 20 70 72  higher.**     pr
26560 69 76 69 6c 65 67 65 2c 20 61 6e 64 20 73 6f 20  ivilege, and so 
26570 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20  the database is 
26580 6f 70 65 6e 65 64 20 72 65 61 64 2d 6f 6e 6c 79  opened read-only
26590 20 61 6e 64 20 61 6c 6c 20 6c 6f 63 6b 69 6e 67   and all locking
265a0 0a 2a 2a 20 20 20 20 20 61 6e 64 20 63 68 61 6e  .**     and chan
265b0 67 65 20 64 65 74 65 63 74 69 6f 6e 20 69 73 20  ge detection is 
265c0 64 69 73 61 62 6c 65 64 2e 20 20 43 61 75 74 69  disabled.  Cauti
265d0 6f 6e 3a 20 53 65 74 74 69 6e 67 20 74 68 65 20  on: Setting the 
265e0 69 6d 6d 75 74 61 62 6c 65 0a 2a 2a 20 20 20 20  immutable.**    
265f0 20 70 72 6f 70 65 72 74 79 20 6f 6e 20 61 20 64   property on a d
26600 61 74 61 62 61 73 65 20 66 69 6c 65 20 74 68 61  atabase file tha
26610 74 20 64 6f 65 73 20 69 6e 20 66 61 63 74 20 63  t does in fact c
26620 68 61 6e 67 65 20 63 61 6e 20 72 65 73 75 6c 74  hange can result
26630 0a 2a 2a 20 20 20 20 20 69 6e 20 69 6e 63 6f 72  .**     in incor
26640 72 65 63 74 20 71 75 65 72 79 20 72 65 73 75 6c  rect query resul
26650 74 73 20 61 6e 64 2f 6f 72 20 5b 53 51 4c 49 54  ts and/or [SQLIT
26660 45 5f 43 4f 52 52 55 50 54 5d 20 65 72 72 6f 72  E_CORRUPT] error
26670 73 2e 0a 2a 2a 20 20 20 20 20 53 65 65 20 61 6c  s..**     See al
26680 73 6f 3a 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41  so: [SQLITE_IOCA
26690 50 5f 49 4d 4d 55 54 41 42 4c 45 5d 2e 0a 2a 2a  P_IMMUTABLE]..**
266a0 20 20 20 20 20 20 20 0a 2a 2a 20 3c 2f 75 6c 3e         .** </ul>
266b0 0a 2a 2a 0a 2a 2a 20 5e 53 70 65 63 69 66 79 69  .**.** ^Specifyi
266c0 6e 67 20 61 6e 20 75 6e 6b 6e 6f 77 6e 20 70 61  ng an unknown pa
266d0 72 61 6d 65 74 65 72 20 69 6e 20 74 68 65 20 71  rameter in the q
266e0 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f  uery component o
266f0 66 20 61 20 55 52 49 20 69 73 20 6e 6f 74 20 61  f a URI is not a
26700 6e 0a 2a 2a 20 65 72 72 6f 72 2e 20 20 46 75 74  n.** error.  Fut
26710 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20  ure versions of 
26720 53 51 4c 69 74 65 20 6d 69 67 68 74 20 75 6e 64  SQLite might und
26730 65 72 73 74 61 6e 64 20 61 64 64 69 74 69 6f 6e  erstand addition
26740 61 6c 20 71 75 65 72 79 0a 2a 2a 20 70 61 72 61  al query.** para
26750 6d 65 74 65 72 73 2e 20 20 53 65 65 20 22 5b 71  meters.  See "[q
26760 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 73 20  uery parameters 
26770 77 69 74 68 20 73 70 65 63 69 61 6c 20 6d 65 61  with special mea
26780 6e 69 6e 67 20 74 6f 20 53 51 4c 69 74 65 5d 22  ning to SQLite]"
26790 20 66 6f 72 0a 2a 2a 20 61 64 64 69 74 69 6f 6e   for.** addition
267a0 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a  al information..
267b0 2a 2a 0a 2a 2a 20 5b 5b 55 52 49 20 66 69 6c 65  **.** [[URI file
267c0 6e 61 6d 65 20 65 78 61 6d 70 6c 65 73 5d 5d 20  name examples]] 
267d0 3c 68 33 3e 55 52 49 20 66 69 6c 65 6e 61 6d 65  <h3>URI filename
267e0 20 65 78 61 6d 70 6c 65 73 3c 2f 68 33 3e 0a 2a   examples</h3>.*
267f0 2a 0a 2a 2a 20 3c 74 61 62 6c 65 20 62 6f 72 64  *.** <table bord
26800 65 72 3d 22 31 22 20 61 6c 69 67 6e 3d 63 65 6e  er="1" align=cen
26810 74 65 72 20 63 65 6c 6c 70 61 64 64 69 6e 67 3d  ter cellpadding=
26820 35 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20 55  5>.** <tr><th> U
26830 52 49 20 66 69 6c 65 6e 61 6d 65 73 20 3c 74 68  RI filenames <th
26840 3e 20 52 65 73 75 6c 74 73 0a 2a 2a 20 3c 74 72  > Results.** <tr
26850 3e 3c 74 64 3e 20 66 69 6c 65 3a 64 61 74 61 2e  ><td> file:data.
26860 64 62 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20  db <td> .**     
26870 20 20 20 20 20 4f 70 65 6e 20 74 68 65 20 66 69       Open the fi
26880 6c 65 20 22 64 61 74 61 2e 64 62 22 20 69 6e 20  le "data.db" in 
26890 74 68 65 20 63 75 72 72 65 6e 74 20 64 69 72 65  the current dire
268a0 63 74 6f 72 79 2e 0a 2a 2a 20 3c 74 72 3e 3c 74  ctory..** <tr><t
268b0 64 3e 20 66 69 6c 65 3a 2f 68 6f 6d 65 2f 66 72  d> file:/home/fr
268c0 65 64 2f 64 61 74 61 2e 64 62 3c 62 72 3e 0a 2a  ed/data.db<br>.*
268d0 2a 20 20 20 20 20 20 20 20 20 20 66 69 6c 65 3a  *          file:
268e0 2f 2f 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74  ///home/fred/dat
268f0 61 2e 64 62 20 3c 62 72 3e 20 0a 2a 2a 20 20 20  a.db <br> .**   
26900 20 20 20 20 20 20 20 66 69 6c 65 3a 2f 2f 6c 6f         file://lo
26910 63 61 6c 68 6f 73 74 2f 68 6f 6d 65 2f 66 72 65  calhost/home/fre
26920 64 2f 64 61 74 61 2e 64 62 20 3c 62 72 3e 20 3c  d/data.db <br> <
26930 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20  td> .**         
26940 20 4f 70 65 6e 20 74 68 65 20 64 61 74 61 62 61   Open the databa
26950 73 65 20 66 69 6c 65 20 22 2f 68 6f 6d 65 2f 66  se file "/home/f
26960 72 65 64 2f 64 61 74 61 2e 64 62 22 2e 0a 2a 2a  red/data.db"..**
26970 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f   <tr><td> file:/
26980 2f 64 61 72 6b 73 74 61 72 2f 68 6f 6d 65 2f 66  /darkstar/home/f
26990 72 65 64 2f 64 61 74 61 2e 64 62 20 3c 74 64 3e  red/data.db <td>
269a0 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 41 6e   .**          An
269b0 20 65 72 72 6f 72 2e 20 22 64 61 72 6b 73 74 61   error. "darksta
269c0 72 22 20 69 73 20 6e 6f 74 20 61 20 72 65 63 6f  r" is not a reco
269d0 67 6e 69 7a 65 64 20 61 75 74 68 6f 72 69 74 79  gnized authority
269e0 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 20 73 74 79  ..** <tr><td sty
269f0 6c 65 3d 22 77 68 69 74 65 2d 73 70 61 63 65 3a  le="white-space:
26a00 6e 6f 77 72 61 70 22 3e 20 0a 2a 2a 20 20 20 20  nowrap"> .**    
26a10 20 20 20 20 20 20 66 69 6c 65 3a 2f 2f 2f 43 3a        file:///C:
26a20 2f 44 6f 63 75 6d 65 6e 74 73 25 32 30 61 6e 64  /Documents%20and
26a30 25 32 30 53 65 74 74 69 6e 67 73 2f 66 72 65 64  %20Settings/fred
26a40 2f 44 65 73 6b 74 6f 70 2f 64 61 74 61 2e 64 62  /Desktop/data.db
26a50 0a 2a 2a 20 20 20 20 20 3c 74 64 3e 20 57 69 6e  .**     <td> Win
26a60 64 6f 77 73 20 6f 6e 6c 79 3a 20 4f 70 65 6e 20  dows only: Open 
26a70 74 68 65 20 66 69 6c 65 20 22 64 61 74 61 2e 64  the file "data.d
26a80 62 22 20 6f 6e 20 66 72 65 64 27 73 20 64 65 73  b" on fred's des
26a90 6b 74 6f 70 20 6f 6e 20 64 72 69 76 65 0a 2a 2a  ktop on drive.**
26aa0 20 20 20 20 20 20 20 20 20 20 43 3a 2e 20 4e 6f            C:. No
26ab0 74 65 20 74 68 61 74 20 74 68 65 20 25 32 30 20  te that the %20 
26ac0 65 73 63 61 70 69 6e 67 20 69 6e 20 74 68 69 73  escaping in this
26ad0 20 65 78 61 6d 70 6c 65 20 69 73 20 6e 6f 74 20   example is not 
26ae0 73 74 72 69 63 74 6c 79 20 0a 2a 2a 20 20 20 20  strictly .**    
26af0 20 20 20 20 20 20 6e 65 63 65 73 73 61 72 79 20        necessary 
26b00 2d 20 73 70 61 63 65 20 63 68 61 72 61 63 74 65  - space characte
26b10 72 73 20 63 61 6e 20 62 65 20 75 73 65 64 20 6c  rs can be used l
26b20 69 74 65 72 61 6c 6c 79 0a 2a 2a 20 20 20 20 20  iterally.**     
26b30 20 20 20 20 20 69 6e 20 55 52 49 20 66 69 6c 65       in URI file
26b40 6e 61 6d 65 73 2e 0a 2a 2a 20 3c 74 72 3e 3c 74  names..** <tr><t
26b50 64 3e 20 66 69 6c 65 3a 64 61 74 61 2e 64 62 3f  d> file:data.db?
26b60 6d 6f 64 65 3d 72 6f 26 63 61 63 68 65 3d 70 72  mode=ro&cache=pr
26b70 69 76 61 74 65 20 3c 74 64 3e 20 0a 2a 2a 20 20  ivate <td> .**  
26b80 20 20 20 20 20 20 20 20 4f 70 65 6e 20 66 69 6c          Open fil
26b90 65 20 22 64 61 74 61 2e 64 62 22 20 69 6e 20 74  e "data.db" in t
26ba0 68 65 20 63 75 72 72 65 6e 74 20 64 69 72 65 63  he current direc
26bb0 74 6f 72 79 20 66 6f 72 20 72 65 61 64 2d 6f 6e  tory for read-on
26bc0 6c 79 20 61 63 63 65 73 73 2e 0a 2a 2a 20 20 20  ly access..**   
26bd0 20 20 20 20 20 20 20 52 65 67 61 72 64 6c 65 73         Regardles
26be0 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20  s of whether or 
26bf0 6e 6f 74 20 73 68 61 72 65 64 2d 63 61 63 68 65  not shared-cache
26c00 20 6d 6f 64 65 20 69 73 20 65 6e 61 62 6c 65 64   mode is enabled
26c10 20 62 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   by.**          
26c20 64 65 66 61 75 6c 74 2c 20 75 73 65 20 61 20 70  default, use a p
26c30 72 69 76 61 74 65 20 63 61 63 68 65 2e 0a 2a 2a  rivate cache..**
26c40 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f   <tr><td> file:/
26c50 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64  home/fred/data.d
26c60 62 3f 76 66 73 3d 75 6e 69 78 2d 64 6f 74 66 69  b?vfs=unix-dotfi
26c70 6c 65 20 3c 74 64 3e 0a 2a 2a 20 20 20 20 20 20  le <td>.**      
26c80 20 20 20 20 4f 70 65 6e 20 66 69 6c 65 20 22 2f      Open file "/
26c90 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64  home/fred/data.d
26ca0 62 22 2e 20 55 73 65 20 74 68 65 20 73 70 65 63  b". Use the spec
26cb0 69 61 6c 20 56 46 53 20 22 75 6e 69 78 2d 64 6f  ial VFS "unix-do
26cc0 74 66 69 6c 65 22 0a 2a 2a 20 20 20 20 20 20 20  tfile".**       
26cd0 20 20 20 74 68 61 74 20 75 73 65 73 20 64 6f 74     that uses dot
26ce0 2d 66 69 6c 65 73 20 69 6e 20 70 6c 61 63 65 20  -files in place 
26cf0 6f 66 20 70 6f 73 69 78 20 61 64 76 69 73 6f 72  of posix advisor
26d00 79 20 6c 6f 63 6b 69 6e 67 2e 0a 2a 2a 20 3c 74  y locking..** <t
26d10 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 64 61 74 61  r><td> file:data
26d20 2e 64 62 3f 6d 6f 64 65 3d 72 65 61 64 6f 6e 6c  .db?mode=readonl
26d30 79 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20  y <td> .**      
26d40 20 20 20 20 41 6e 20 65 72 72 6f 72 2e 20 22 72      An error. "r
26d50 65 61 64 6f 6e 6c 79 22 20 69 73 20 6e 6f 74 20  eadonly" is not 
26d60 61 20 76 61 6c 69 64 20 6f 70 74 69 6f 6e 20 66  a valid option f
26d70 6f 72 20 74 68 65 20 22 6d 6f 64 65 22 20 70 61  or the "mode" pa
26d80 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 3c 2f 74 61  rameter..** </ta
26d90 62 6c 65 3e 0a 2a 2a 0a 2a 2a 20 5e 55 52 49 20  ble>.**.** ^URI 
26da0 68 65 78 61 64 65 63 69 6d 61 6c 20 65 73 63 61  hexadecimal esca
26db0 70 65 20 73 65 71 75 65 6e 63 65 73 20 28 25 48  pe sequences (%H
26dc0 48 29 20 61 72 65 20 73 75 70 70 6f 72 74 65 64  H) are supported
26dd0 20 77 69 74 68 69 6e 20 74 68 65 20 70 61 74 68   within the path
26de0 20 61 6e 64 0a 2a 2a 20 71 75 65 72 79 20 63 6f   and.** query co
26df0 6d 70 6f 6e 65 6e 74 73 20 6f 66 20 61 20 55 52  mponents of a UR
26e00 49 2e 20 41 20 68 65 78 61 64 65 63 69 6d 61 6c  I. A hexadecimal
26e10 20 65 73 63 61 70 65 20 73 65 71 75 65 6e 63 65   escape sequence
26e20 20 63 6f 6e 73 69 73 74 73 20 6f 66 20 61 0a 2a   consists of a.*
26e30 2a 20 70 65 72 63 65 6e 74 20 73 69 67 6e 20 2d  * percent sign -
26e40 20 22 25 22 20 2d 20 66 6f 6c 6c 6f 77 65 64 20   "%" - followed 
26e50 62 79 20 65 78 61 63 74 6c 79 20 74 77 6f 20 68  by exactly two h
26e60 65 78 61 64 65 63 69 6d 61 6c 20 64 69 67 69 74  exadecimal digit
26e70 73 20 0a 2a 2a 20 73 70 65 63 69 66 79 69 6e 67  s .** specifying
26e80 20 61 6e 20 6f 63 74 65 74 20 76 61 6c 75 65 2e   an octet value.
26e90 20 5e 42 65 66 6f 72 65 20 74 68 65 20 70 61 74   ^Before the pat
26ea0 68 20 6f 72 20 71 75 65 72 79 20 63 6f 6d 70 6f  h or query compo
26eb0 6e 65 6e 74 73 20 6f 66 20 61 0a 2a 2a 20 55 52  nents of a.** UR
26ec0 49 20 66 69 6c 65 6e 61 6d 65 20 61 72 65 20 69  I filename are i
26ed0 6e 74 65 72 70 72 65 74 65 64 2c 20 74 68 65 79  nterpreted, they
26ee0 20 61 72 65 20 65 6e 63 6f 64 65 64 20 75 73 69   are encoded usi
26ef0 6e 67 20 55 54 46 2d 38 20 61 6e 64 20 61 6c 6c  ng UTF-8 and all
26f00 20 0a 2a 2a 20 68 65 78 61 64 65 63 69 6d 61 6c   .** hexadecimal
26f10 20 65 73 63 61 70 65 20 73 65 71 75 65 6e 63 65   escape sequence
26f20 73 20 72 65 70 6c 61 63 65 64 20 62 79 20 61 20  s replaced by a 
26f30 73 69 6e 67 6c 65 20 62 79 74 65 20 63 6f 6e 74  single byte cont
26f40 61 69 6e 69 6e 67 20 74 68 65 0a 2a 2a 20 63 6f  aining the.** co
26f50 72 72 65 73 70 6f 6e 64 69 6e 67 20 6f 63 74 65  rresponding octe
26f60 74 2e 20 49 66 20 74 68 69 73 20 70 72 6f 63 65  t. If this proce
26f70 73 73 20 67 65 6e 65 72 61 74 65 73 20 61 6e 20  ss generates an 
26f80 69 6e 76 61 6c 69 64 20 55 54 46 2d 38 20 65 6e  invalid UTF-8 en
26f90 63 6f 64 69 6e 67 2c 0a 2a 2a 20 74 68 65 20 72  coding,.** the r
26fa0 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66  esults are undef
26fb0 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e  ined..**.** <b>N
26fc0 6f 74 65 20 74 6f 20 57 69 6e 64 6f 77 73 20 75  ote to Windows u
26fd0 73 65 72 73 3a 3c 2f 62 3e 20 20 54 68 65 20 65  sers:</b>  The e
26fe0 6e 63 6f 64 69 6e 67 20 75 73 65 64 20 66 6f 72  ncoding used for
26ff0 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72   the filename ar
27000 67 75 6d 65 6e 74 0a 2a 2a 20 6f 66 20 73 71 6c  gument.** of sql
27010 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20  ite3_open() and 
27020 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
27030 29 20 6d 75 73 74 20 62 65 20 55 54 46 2d 38 2c  ) must be UTF-8,
27040 20 6e 6f 74 20 77 68 61 74 65 76 65 72 0a 2a 2a   not whatever.**
27050 20 63 6f 64 65 70 61 67 65 20 69 73 20 63 75 72   codepage is cur
27060 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 2e 20  rently defined. 
27070 20 46 69 6c 65 6e 61 6d 65 73 20 63 6f 6e 74 61   Filenames conta
27080 69 6e 69 6e 67 20 69 6e 74 65 72 6e 61 74 69 6f  ining internatio
27090 6e 61 6c 0a 2a 2a 20 63 68 61 72 61 63 74 65 72  nal.** character
270a0 73 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72  s must be conver
270b0 74 65 64 20 74 6f 20 55 54 46 2d 38 20 70 72 69  ted to UTF-8 pri
270c0 6f 72 20 74 6f 20 70 61 73 73 69 6e 67 20 74 68  or to passing th
270d0 65 6d 20 69 6e 74 6f 0a 2a 2a 20 73 71 6c 69 74  em into.** sqlit
270e0 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c  e3_open() or sql
270f0 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a  ite3_open_v2()..
27100 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74 6f  **.** <b>Note to
27110 20 57 69 6e 64 6f 77 73 20 52 75 6e 74 69 6d 65   Windows Runtime
27120 20 75 73 65 72 73 3a 3c 2f 62 3e 20 20 54 68 65   users:</b>  The
27130 20 74 65 6d 70 6f 72 61 72 79 20 64 69 72 65 63   temporary direc
27140 74 6f 72 79 20 6d 75 73 74 20 62 65 20 73 65 74  tory must be set
27150 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 63 61 6c  .** prior to cal
27160 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 6f 70 65  ling sqlite3_ope
27170 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f  n() or sqlite3_o
27180 70 65 6e 5f 76 32 28 29 2e 20 20 4f 74 68 65 72  pen_v2().  Other
27190 77 69 73 65 2c 20 76 61 72 69 6f 75 73 0a 2a 2a  wise, various.**
271a0 20 66 65 61 74 75 72 65 73 20 74 68 61 74 20 72   features that r
271b0 65 71 75 69 72 65 20 74 68 65 20 75 73 65 20 6f  equire the use o
271c0 66 20 74 65 6d 70 6f 72 61 72 79 20 66 69 6c 65  f temporary file
271d0 73 20 6d 61 79 20 66 61 69 6c 2e 0a 2a 2a 0a 2a  s may fail..**.*
271e0 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c  * See also: [sql
271f0 69 74 65 33 5f 74 65 6d 70 5f 64 69 72 65 63 74  ite3_temp_direct
27200 6f 72 79 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ory].*/.int sqli
27210 74 65 33 5f 6f 70 65 6e 28 0a 20 20 63 6f 6e 73  te3_open(.  cons
27220 74 20 63 68 61 72 20 2a 66 69 6c 65 6e 61 6d 65  t char *filename
27230 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20  ,   /* Database 
27240 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 38 29  filename (UTF-8)
27250 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a   */.  sqlite3 **
27260 70 70 44 62 20 20 20 20 20 20 20 20 20 20 2f 2a  ppDb          /*
27270 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20   OUT: SQLite db 
27280 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 69 6e 74  handle */.);.int
27290 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28   sqlite3_open16(
272a0 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 66  .  const void *f
272b0 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61  ilename,   /* Da
272c0 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20  tabase filename 
272d0 28 55 54 46 2d 31 36 29 20 2a 2f 0a 20 20 73 71  (UTF-16) */.  sq
272e0 6c 69 74 65 33 20 2a 2a 70 70 44 62 20 20 20 20  lite3 **ppDb    
272f0 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51        /* OUT: SQ
27300 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a  Lite db handle *
27310 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  /.);.int sqlite3
27320 5f 6f 70 65 6e 5f 76 32 28 0a 20 20 63 6f 6e 73  _open_v2(.  cons
27330 74 20 63 68 61 72 20 2a 66 69 6c 65 6e 61 6d 65  t char *filename
27340 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20  ,   /* Database 
27350 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 38 29  filename (UTF-8)
27360 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a   */.  sqlite3 **
27370 70 70 44 62 2c 20 20 20 20 20 20 20 20 20 2f 2a  ppDb,         /*
27380 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20   OUT: SQLite db 
27390 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 69 6e 74 20  handle */.  int 
273a0 66 6c 61 67 73 2c 20 20 20 20 20 20 20 20 20 20  flags,          
273b0 20 20 20 20 2f 2a 20 46 6c 61 67 73 20 2a 2f 0a      /* Flags */.
273c0 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 56    const char *zV
273d0 66 73 20 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d  fs        /* Nam
273e0 65 20 6f 66 20 56 46 53 20 6d 6f 64 75 6c 65 20  e of VFS module 
273f0 74 6f 20 75 73 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a  to use */.);../*
27400 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 62  .** CAPI3REF: Ob
27410 74 61 69 6e 20 56 61 6c 75 65 73 20 46 6f 72 20  tain Values For 
27420 55 52 49 20 50 61 72 61 6d 65 74 65 72 73 0a 2a  URI Parameters.*
27430 2a 0a 2a 2a 20 54 68 65 73 65 20 61 72 65 20 75  *.** These are u
27440 74 69 6c 69 74 79 20 72 6f 75 74 69 6e 65 73 2c  tility routines,
27450 20 75 73 65 66 75 6c 20 74 6f 20 56 46 53 20 69   useful to VFS i
27460 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 2c 20  mplementations, 
27470 74 68 61 74 20 63 68 65 63 6b 0a 2a 2a 20 74 6f  that check.** to
27480 20 73 65 65 20 69 66 20 61 20 64 61 74 61 62 61   see if a databa
27490 73 65 20 66 69 6c 65 20 77 61 73 20 61 20 55 52  se file was a UR
274a0 49 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 65 64  I that contained
274b0 20 61 20 73 70 65 63 69 66 69 63 20 71 75 65 72   a specific quer
274c0 79 20 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 2c  y .** parameter,
274d0 20 61 6e 64 20 69 66 20 73 6f 20 6f 62 74 61 69   and if so obtai
274e0 6e 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20  ns the value of 
274f0 74 68 61 74 20 71 75 65 72 79 20 70 61 72 61 6d  that query param
27500 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 46  eter..**.** If F
27510 20 69 73 20 74 68 65 20 64 61 74 61 62 61 73 65   is the database
27520 20 66 69 6c 65 6e 61 6d 65 20 70 6f 69 6e 74 65   filename pointe
27530 72 20 70 61 73 73 65 64 20 69 6e 74 6f 20 74 68  r passed into th
27540 65 20 78 4f 70 65 6e 28 29 20 6d 65 74 68 6f 64  e xOpen() method
27550 20 6f 66 20 0a 2a 2a 20 61 20 56 46 53 20 69 6d   of .** a VFS im
27560 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 68 65  plementation whe
27570 6e 20 74 68 65 20 66 6c 61 67 73 20 70 61 72 61  n the flags para
27580 6d 65 74 65 72 20 74 6f 20 78 4f 70 65 6e 28 29  meter to xOpen()
27590 20 68 61 73 20 6f 6e 65 20 6f 72 20 0a 2a 2a 20   has one or .** 
275a0 6d 6f 72 65 20 6f 66 20 74 68 65 20 5b 53 51 4c  more of the [SQL
275b0 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 6f 72  ITE_OPEN_URI] or
275c0 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41   [SQLITE_OPEN_MA
275d0 49 4e 5f 44 42 5d 20 62 69 74 73 20 73 65 74 20  IN_DB] bits set 
275e0 61 6e 64 0a 2a 2a 20 50 20 69 73 20 74 68 65 20  and.** P is the 
275f0 6e 61 6d 65 20 6f 66 20 74 68 65 20 71 75 65 72  name of the quer
27600 79 20 70 61 72 61 6d 65 74 65 72 2c 20 74 68 65  y parameter, the
27610 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75 72 69  n.** sqlite3_uri
27620 5f 70 61 72 61 6d 65 74 65 72 28 46 2c 50 29 20  _parameter(F,P) 
27630 72 65 74 75 72 6e 73 20 74 68 65 20 76 61 6c 75  returns the valu
27640 65 20 6f 66 20 74 68 65 20 50 0a 2a 2a 20 70 61  e of the P.** pa
27650 72 61 6d 65 74 65 72 20 69 66 20 69 74 20 65 78  rameter if it ex
27660 69 73 74 73 20 6f 72 20 61 20 4e 55 4c 4c 20 70  ists or a NULL p
27670 6f 69 6e 74 65 72 20 69 66 20 50 20 64 6f 65 73  ointer if P does
27680 20 6e 6f 74 20 61 70 70 65 61 72 20 61 73 20 61   not appear as a
27690 20 0a 2a 2a 20 71 75 65 72 79 20 70 61 72 61 6d   .** query param
276a0 65 74 65 72 20 6f 6e 20 46 2e 20 20 49 66 20 50  eter on F.  If P
276b0 20 69 73 20 61 20 71 75 65 72 79 20 70 61 72 61   is a query para
276c0 6d 65 74 65 72 20 6f 66 20 46 0a 2a 2a 20 68 61  meter of F.** ha
276d0 73 20 6e 6f 20 65 78 70 6c 69 63 69 74 20 76 61  s no explicit va
276e0 6c 75 65 2c 20 74 68 65 6e 20 73 71 6c 69 74 65  lue, then sqlite
276f0 33 5f 75 72 69 5f 70 61 72 61 6d 65 74 65 72 28  3_uri_parameter(
27700 46 2c 50 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20  F,P) returns.** 
27710 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  a pointer to an 
27720 65 6d 70 74 79 20 73 74 72 69 6e 67 2e 0a 2a 2a  empty string..**
27730 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
27740 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c  uri_boolean(F,P,
27750 42 29 20 72 6f 75 74 69 6e 65 20 61 73 73 75 6d  B) routine assum
27760 65 73 20 74 68 61 74 20 50 20 69 73 20 61 20 62  es that P is a b
27770 6f 6f 6c 65 61 6e 0a 2a 2a 20 70 61 72 61 6d 65  oolean.** parame
27780 74 65 72 20 61 6e 64 20 72 65 74 75 72 6e 73 20  ter and returns 
27790 74 72 75 65 20 28 31 29 20 6f 72 20 66 61 6c 73  true (1) or fals
277a0 65 20 28 30 29 20 61 63 63 6f 72 64 69 6e 67 20  e (0) according 
277b0 74 6f 20 74 68 65 20 76 61 6c 75 65 0a 2a 2a 20  to the value.** 
277c0 6f 66 20 50 2e 20 20 54 68 65 20 73 71 6c 69 74  of P.  The sqlit
277d0 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46  e3_uri_boolean(F
277e0 2c 50 2c 42 29 20 72 6f 75 74 69 6e 65 20 72 65  ,P,B) routine re
277f0 74 75 72 6e 73 20 74 72 75 65 20 28 31 29 20 69  turns true (1) i
27800 66 20 74 68 65 0a 2a 2a 20 76 61 6c 75 65 20 6f  f the.** value o
27810 66 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65  f query paramete
27820 72 20 50 20 69 73 20 6f 6e 65 20 6f 66 20 22 79  r P is one of "y
27830 65 73 22 2c 20 22 74 72 75 65 22 2c 20 6f 72 20  es", "true", or 
27840 22 6f 6e 22 20 69 6e 20 61 6e 79 0a 2a 2a 20 63  "on" in any.** c
27850 61 73 65 20 6f 72 20 69 66 20 74 68 65 20 76 61  ase or if the va
27860 6c 75 65 20 62 65 67 69 6e 73 20 77 69 74 68 20  lue begins with 
27870 61 20 6e 6f 6e 2d 7a 65 72 6f 20 6e 75 6d 62 65  a non-zero numbe
27880 72 2e 20 20 54 68 65 20 0a 2a 2a 20 73 71 6c 69  r.  The .** sqli
27890 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28  te3_uri_boolean(
278a0 46 2c 50 2c 42 29 20 72 6f 75 74 69 6e 65 73 20  F,P,B) routines 
278b0 72 65 74 75 72 6e 73 20 66 61 6c 73 65 20 28 30  returns false (0
278c0 29 20 69 66 20 74 68 65 20 76 61 6c 75 65 20 6f  ) if the value o
278d0 66 0a 2a 2a 20 71 75 65 72 79 20 70 61 72 61 6d  f.** query param
278e0 65 74 65 72 20 50 20 69 73 20 6f 6e 65 20 6f 66  eter P is one of
278f0 20 22 6e 6f 22 2c 20 22 66 61 6c 73 65 22 2c 20   "no", "false", 
27900 6f 72 20 22 6f 66 66 22 20 69 6e 20 61 6e 79 20  or "off" in any 
27910 63 61 73 65 20 6f 72 0a 2a 2a 20 69 66 20 74 68  case or.** if th
27920 65 20 76 61 6c 75 65 20 62 65 67 69 6e 73 20 77  e value begins w
27930 69 74 68 20 61 20 6e 75 6d 65 72 69 63 20 7a 65  ith a numeric ze
27940 72 6f 2e 20 20 49 66 20 50 20 69 73 20 6e 6f 74  ro.  If P is not
27950 20 61 20 71 75 65 72 79 0a 2a 2a 20 70 61 72 61   a query.** para
27960 6d 65 74 65 72 20 6f 6e 20 46 20 6f 72 20 69 66  meter on F or if
27970 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 50 20   the value of P 
27980 69 73 20 64 6f 65 73 20 6e 6f 74 20 6d 61 74 63  is does not matc
27990 68 20 61 6e 79 20 6f 66 20 74 68 65 0a 2a 2a 20  h any of the.** 
279a0 61 62 6f 76 65 2c 20 74 68 65 6e 20 73 71 6c 69  above, then sqli
279b0 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28  te3_uri_boolean(
279c0 46 2c 50 2c 42 29 20 72 65 74 75 72 6e 73 20 28  F,P,B) returns (
279d0 42 21 3d 30 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  B!=0)..**.** The
279e0 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 69 6e 74   sqlite3_uri_int
279f0 36 34 28 46 2c 50 2c 44 29 20 72 6f 75 74 69 6e  64(F,P,D) routin
27a00 65 20 63 6f 6e 76 65 72 74 73 20 74 68 65 20 76  e converts the v
27a10 61 6c 75 65 20 6f 66 20 50 20 69 6e 74 6f 20 61  alue of P into a
27a20 0a 2a 2a 20 36 34 2d 62 69 74 20 73 69 67 6e 65  .** 64-bit signe
27a30 64 20 69 6e 74 65 67 65 72 20 61 6e 64 20 72 65  d integer and re
27a40 74 75 72 6e 73 20 74 68 61 74 20 69 6e 74 65 67  turns that integ
27a50 65 72 2c 20 6f 72 20 44 20 69 66 20 50 20 64 6f  er, or D if P do
27a60 65 73 20 6e 6f 74 0a 2a 2a 20 65 78 69 73 74 2e  es not.** exist.
27a70 20 20 49 66 20 74 68 65 20 76 61 6c 75 65 20 6f    If the value o
27a80 66 20 50 20 69 73 20 73 6f 6d 65 74 68 69 6e 67  f P is something
27a90 20 6f 74 68 65 72 20 74 68 61 6e 20 61 6e 20 69   other than an i
27aa0 6e 74 65 67 65 72 2c 20 74 68 65 6e 0a 2a 2a 20  nteger, then.** 
27ab0 7a 65 72 6f 20 69 73 20 72 65 74 75 72 6e 65 64  zero is returned
27ac0 2e 0a 2a 2a 20 0a 2a 2a 20 49 66 20 46 20 69 73  ..** .** If F is
27ad0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c   a NULL pointer,
27ae0 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 75 72   then sqlite3_ur
27af0 69 5f 70 61 72 61 6d 65 74 65 72 28 46 2c 50 29  i_parameter(F,P)
27b00 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 20 61 6e   returns NULL an
27b10 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75 72 69  d.** sqlite3_uri
27b20 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20  _boolean(F,P,B) 
27b30 72 65 74 75 72 6e 73 20 42 2e 20 20 49 66 20 46  returns B.  If F
27b40 20 69 73 20 6e 6f 74 20 61 20 4e 55 4c 4c 20 70   is not a NULL p
27b50 6f 69 6e 74 65 72 20 61 6e 64 0a 2a 2a 20 69 73  ointer and.** is
27b60 20 6e 6f 74 20 61 20 64 61 74 61 62 61 73 65 20   not a database 
27b70 66 69 6c 65 20 70 61 74 68 6e 61 6d 65 20 70 6f  file pathname po
27b80 69 6e 74 65 72 20 74 68 61 74 20 53 51 4c 69 74  inter that SQLit
27b90 65 20 70 61 73 73 65 64 20 69 6e 74 6f 20 74 68  e passed into th
27ba0 65 20 78 4f 70 65 6e 0a 2a 2a 20 56 46 53 20 6d  e xOpen.** VFS m
27bb0 65 74 68 6f 64 2c 20 74 68 65 6e 20 74 68 65 20  ethod, then the 
27bc0 62 65 68 61 76 69 6f 72 20 6f 66 20 74 68 69 73  behavior of this
27bd0 20 72 6f 75 74 69 6e 65 20 69 73 20 75 6e 64 65   routine is unde
27be0 66 69 6e 65 64 20 61 6e 64 20 70 72 6f 62 61 62  fined and probab
27bf0 6c 79 0a 2a 2a 20 75 6e 64 65 73 69 72 61 62 6c  ly.** undesirabl
27c00 65 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72  e..*/.const char
27c10 20 2a 73 71 6c 69 74 65 33 5f 75 72 69 5f 70 61   *sqlite3_uri_pa
27c20 72 61 6d 65 74 65 72 28 63 6f 6e 73 74 20 63 68  rameter(const ch
27c30 61 72 20 2a 7a 46 69 6c 65 6e 61 6d 65 2c 20 63  ar *zFilename, c
27c40 6f 6e 73 74 20 63 68 61 72 20 2a 7a 50 61 72 61  onst char *zPara
27c50 6d 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  m);.int sqlite3_
27c60 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 63 6f 6e 73  uri_boolean(cons
27c70 74 20 63 68 61 72 20 2a 7a 46 69 6c 65 2c 20 63  t char *zFile, c
27c80 6f 6e 73 74 20 63 68 61 72 20 2a 7a 50 61 72 61  onst char *zPara
27c90 6d 2c 20 69 6e 74 20 62 44 65 66 61 75 6c 74 29  m, int bDefault)
27ca0 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  ;.sqlite3_int64 
27cb0 73 71 6c 69 74 65 33 5f 75 72 69 5f 69 6e 74 36  sqlite3_uri_int6
27cc0 34 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 63  4(const char*, c
27cd0 6f 6e 73 74 20 63 68 61 72 2a 2c 20 73 71 6c 69  onst char*, sqli
27ce0 74 65 33 5f 69 6e 74 36 34 29 3b 0a 0a 0a 2f 2a  te3_int64);.../*
27cf0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 72  .** CAPI3REF: Er
27d00 72 6f 72 20 43 6f 64 65 73 20 41 6e 64 20 4d 65  ror Codes And Me
27d10 73 73 61 67 65 73 0a 2a 2a 20 4d 45 54 48 4f 44  ssages.** METHOD
27d20 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20  : sqlite3.**.** 
27d30 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63  ^If the most rec
27d40 65 6e 74 20 73 71 6c 69 74 65 33 5f 2a 20 41 50  ent sqlite3_* AP
27d50 49 20 63 61 6c 6c 20 61 73 73 6f 63 69 61 74 65  I call associate
27d60 64 20 77 69 74 68 20 0a 2a 2a 20 5b 64 61 74 61  d with .** [data
27d70 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
27d80 20 44 20 66 61 69 6c 65 64 2c 20 74 68 65 6e 20   D failed, then 
27d90 74 68 65 20 73 71 6c 69 74 65 33 5f 65 72 72 63  the sqlite3_errc
27da0 6f 64 65 28 44 29 20 69 6e 74 65 72 66 61 63 65  ode(D) interface
27db0 0a 2a 2a 20 72 65 74 75 72 6e 73 20 74 68 65 20  .** returns the 
27dc0 6e 75 6d 65 72 69 63 20 5b 72 65 73 75 6c 74 20  numeric [result 
27dd0 63 6f 64 65 5d 20 6f 72 20 5b 65 78 74 65 6e 64  code] or [extend
27de0 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 5d 20  ed result code] 
27df0 66 6f 72 20 74 68 61 74 0a 2a 2a 20 41 50 49 20  for that.** API 
27e00 63 61 6c 6c 2e 0a 2a 2a 20 49 66 20 74 68 65 20  call..** If the 
27e10 6d 6f 73 74 20 72 65 63 65 6e 74 20 41 50 49 20  most recent API 
27e20 63 61 6c 6c 20 77 61 73 20 73 75 63 63 65 73 73  call was success
27e30 66 75 6c 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65  ful,.** then the
27e40 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66 72   return value fr
27e50 6f 6d 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f  om sqlite3_errco
27e60 64 65 28 29 20 69 73 20 75 6e 64 65 66 69 6e 65  de() is undefine
27e70 64 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  d..** ^The sqlit
27e80 65 33 5f 65 78 74 65 6e 64 65 64 5f 65 72 72 63  e3_extended_errc
27e90 6f 64 65 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61  ode().** interfa
27ea0 63 65 20 69 73 20 74 68 65 20 73 61 6d 65 20 65  ce is the same e
27eb0 78 63 65 70 74 20 74 68 61 74 20 69 74 20 61 6c  xcept that it al
27ec0 77 61 79 73 20 72 65 74 75 72 6e 73 20 74 68 65  ways returns the
27ed0 20 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72   .** [extended r
27ee0 65 73 75 6c 74 20 63 6f 64 65 5d 20 65 76 65 6e  esult code] even
27ef0 20 77 68 65 6e 20 65 78 74 65 6e 64 65 64 20 72   when extended r
27f00 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65 0a  esult codes are.
27f10 2a 2a 20 64 69 73 61 62 6c 65 64 2e 0a 2a 2a 0a  ** disabled..**.
27f20 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
27f30 65 72 72 6d 73 67 28 29 20 61 6e 64 20 73 71 6c  errmsg() and sql
27f40 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29 20  ite3_errmsg16() 
27f50 72 65 74 75 72 6e 20 45 6e 67 6c 69 73 68 2d 6c  return English-l
27f60 61 6e 67 75 61 67 65 0a 2a 2a 20 74 65 78 74 20  anguage.** text 
27f70 74 68 61 74 20 64 65 73 63 72 69 62 65 73 20 74  that describes t
27f80 68 65 20 65 72 72 6f 72 2c 20 61 73 20 65 69 74  he error, as eit
27f90 68 65 72 20 55 54 46 2d 38 20 6f 72 20 55 54 46  her UTF-8 or UTF
27fa0 2d 31 36 20 72 65 73 70 65 63 74 69 76 65 6c 79  -16 respectively
27fb0 2e 0a 2a 2a 20 5e 28 4d 65 6d 6f 72 79 20 74 6f  ..** ^(Memory to
27fc0 20 68 6f 6c 64 20 74 68 65 20 65 72 72 6f 72 20   hold the error 
27fd0 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67 20 69  message string i
27fe0 73 20 6d 61 6e 61 67 65 64 20 69 6e 74 65 72 6e  s managed intern
27ff0 61 6c 6c 79 2e 0a 2a 2a 20 54 68 65 20 61 70 70  ally..** The app
28000 6c 69 63 61 74 69 6f 6e 20 64 6f 65 73 20 6e 6f  lication does no
28010 74 20 6e 65 65 64 20 74 6f 20 77 6f 72 72 79 20  t need to worry 
28020 61 62 6f 75 74 20 66 72 65 65 69 6e 67 20 74 68  about freeing th
28030 65 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 48 6f 77  e result..** How
28040 65 76 65 72 2c 20 74 68 65 20 65 72 72 6f 72 20  ever, the error 
28050 73 74 72 69 6e 67 20 6d 69 67 68 74 20 62 65 20  string might be 
28060 6f 76 65 72 77 72 69 74 74 65 6e 20 6f 72 20 64  overwritten or d
28070 65 61 6c 6c 6f 63 61 74 65 64 20 62 79 0a 2a 2a  eallocated by.**
28080 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c   subsequent call
28090 73 20 74 6f 20 6f 74 68 65 72 20 53 51 4c 69 74  s to other SQLit
280a0 65 20 69 6e 74 65 72 66 61 63 65 20 66 75 6e 63  e interface func
280b0 74 69 6f 6e 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  tions.)^.**.** ^
280c0 54 68 65 20 73 71 6c 69 74 65 33 5f 65 72 72 73  The sqlite3_errs
280d0 74 72 28 29 20 69 6e 74 65 72 66 61 63 65 20 72  tr() interface r
280e0 65 74 75 72 6e 73 20 74 68 65 20 45 6e 67 6c 69  eturns the Engli
280f0 73 68 2d 6c 61 6e 67 75 61 67 65 20 74 65 78 74  sh-language text
28100 0a 2a 2a 20 74 68 61 74 20 64 65 73 63 72 69 62  .** that describ
28110 65 73 20 74 68 65 20 5b 72 65 73 75 6c 74 20 63  es the [result c
28120 6f 64 65 5d 2c 20 61 73 20 55 54 46 2d 38 2e 0a  ode], as UTF-8..
28130 2a 2a 20 5e 28 4d 65 6d 6f 72 79 20 74 6f 20 68  ** ^(Memory to h
28140 6f 6c 64 20 74 68 65 20 65 72 72 6f 72 20 6d 65  old the error me
28150 73 73 61 67 65 20 73 74 72 69 6e 67 20 69 73 20  ssage string is 
28160 6d 61 6e 61 67 65 64 20 69 6e 74 65 72 6e 61 6c  managed internal
28170 6c 79 0a 2a 2a 20 61 6e 64 20 6d 75 73 74 20 6e  ly.** and must n
28180 6f 74 20 62 65 20 66 72 65 65 64 20 62 79 20 74  ot be freed by t
28190 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 29 5e  he application)^
281a0 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65  ..**.** When the
281b0 20 73 65 72 69 61 6c 69 7a 65 64 20 5b 74 68 72   serialized [thr
281c0 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 69 73 20  eading mode] is 
281d0 69 6e 20 75 73 65 2c 20 69 74 20 6d 69 67 68 74  in use, it might
281e0 20 62 65 20 74 68 65 0a 2a 2a 20 63 61 73 65 20   be the.** case 
281f0 74 68 61 74 20 61 20 73 65 63 6f 6e 64 20 65 72  that a second er
28200 72 6f 72 20 6f 63 63 75 72 73 20 6f 6e 20 61 20  ror occurs on a 
28210 73 65 70 61 72 61 74 65 20 74 68 72 65 61 64 20  separate thread 
28220 69 6e 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68  in between.** th
28230 65 20 74 69 6d 65 20 6f 66 20 74 68 65 20 66 69  e time of the fi
28240 72 73 74 20 65 72 72 6f 72 20 61 6e 64 20 74 68  rst error and th
28250 65 20 63 61 6c 6c 20 74 6f 20 74 68 65 73 65 20  e call to these 
28260 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20 57  interfaces..** W
28270 68 65 6e 20 74 68 61 74 20 68 61 70 70 65 6e 73  hen that happens
28280 2c 20 74 68 65 20 73 65 63 6f 6e 64 20 65 72 72  , the second err
28290 6f 72 20 77 69 6c 6c 20 62 65 20 72 65 70 6f 72  or will be repor
282a0 74 65 64 20 73 69 6e 63 65 20 74 68 65 73 65 0a  ted since these.
282b0 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 61 6c  ** interfaces al
282c0 77 61 79 73 20 72 65 70 6f 72 74 20 74 68 65 20  ways report the 
282d0 6d 6f 73 74 20 72 65 63 65 6e 74 20 72 65 73 75  most recent resu
282e0 6c 74 2e 20 20 54 6f 20 61 76 6f 69 64 0a 2a 2a  lt.  To avoid.**
282f0 20 74 68 69 73 2c 20 65 61 63 68 20 74 68 72 65   this, each thre
28300 61 64 20 63 61 6e 20 6f 62 74 61 69 6e 20 65 78  ad can obtain ex
28310 63 6c 75 73 69 76 65 20 75 73 65 20 6f 66 20 74  clusive use of t
28320 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
28330 6e 65 63 74 69 6f 6e 5d 20 44 0a 2a 2a 20 62 79  nection] D.** by
28340 20 69 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c 69 74   invoking [sqlit
28350 65 33 5f 6d 75 74 65 78 5f 65 6e 74 65 72 5d 28  e3_mutex_enter](
28360 5b 73 71 6c 69 74 65 33 5f 64 62 5f 6d 75 74 65  [sqlite3_db_mute
28370 78 5d 28 44 29 29 20 62 65 66 6f 72 65 20 62 65  x](D)) before be
28380 67 69 6e 6e 69 6e 67 0a 2a 2a 20 74 6f 20 75 73  ginning.** to us
28390 65 20 44 20 61 6e 64 20 69 6e 76 6f 6b 69 6e 67  e D and invoking
283a0 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f   [sqlite3_mutex_
283b0 6c 65 61 76 65 5d 28 5b 73 71 6c 69 74 65 33 5f  leave]([sqlite3_
283c0 64 62 5f 6d 75 74 65 78 5d 28 44 29 29 20 61 66  db_mutex](D)) af
283d0 74 65 72 0a 2a 2a 20 61 6c 6c 20 63 61 6c 6c 73  ter.** all calls
283e0 20 74 6f 20 74 68 65 20 69 6e 74 65 72 66 61 63   to the interfac
283f0 65 73 20 6c 69 73 74 65 64 20 68 65 72 65 20 61  es listed here a
28400 72 65 20 63 6f 6d 70 6c 65 74 65 64 2e 0a 2a 2a  re completed..**
28410 0a 2a 2a 20 49 66 20 61 6e 20 69 6e 74 65 72 66  .** If an interf
28420 61 63 65 20 66 61 69 6c 73 20 77 69 74 68 20 53  ace fails with S
28430 51 4c 49 54 45 5f 4d 49 53 55 53 45 2c 20 74 68  QLITE_MISUSE, th
28440 61 74 20 6d 65 61 6e 73 20 74 68 65 20 69 6e 74  at means the int
28450 65 72 66 61 63 65 0a 2a 2a 20 77 61 73 20 69 6e  erface.** was in
28460 76 6f 6b 65 64 20 69 6e 63 6f 72 72 65 63 74 6c  voked incorrectl
28470 79 20 62 79 20 74 68 65 20 61 70 70 6c 69 63 61  y by the applica
28480 74 69 6f 6e 2e 20 20 49 6e 20 74 68 61 74 20 63  tion.  In that c
28490 61 73 65 2c 20 74 68 65 0a 2a 2a 20 65 72 72 6f  ase, the.** erro
284a0 72 20 63 6f 64 65 20 61 6e 64 20 6d 65 73 73 61  r code and messa
284b0 67 65 20 6d 61 79 20 6f 72 20 6d 61 79 20 6e 6f  ge may or may no
284c0 74 20 62 65 20 73 65 74 2e 0a 2a 2f 0a 69 6e 74  t be set..*/.int
284d0 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65   sqlite3_errcode
284e0 28 73 71 6c 69 74 65 33 20 2a 64 62 29 3b 0a 69  (sqlite3 *db);.i
284f0 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e  nt sqlite3_exten
28500 64 65 64 5f 65 72 72 63 6f 64 65 28 73 71 6c 69  ded_errcode(sqli
28510 74 65 33 20 2a 64 62 29 3b 0a 63 6f 6e 73 74 20  te3 *db);.const 
28520 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 65 72  char *sqlite3_er
28530 72 6d 73 67 28 73 71 6c 69 74 65 33 2a 29 3b 0a  rmsg(sqlite3*);.
28540 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
28550 74 65 33 5f 65 72 72 6d 73 67 31 36 28 73 71 6c  te3_errmsg16(sql
28560 69 74 65 33 2a 29 3b 0a 63 6f 6e 73 74 20 63 68  ite3*);.const ch
28570 61 72 20 2a 73 71 6c 69 74 65 33 5f 65 72 72 73  ar *sqlite3_errs
28580 74 72 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  tr(int);../*.** 
28590 43 41 50 49 33 52 45 46 3a 20 50 72 65 70 61 72  CAPI3REF: Prepar
285a0 65 64 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a  ed Statement Obj
285b0 65 63 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  ect.** KEYWORDS:
285c0 20 7b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   {prepared state
285d0 6d 65 6e 74 7d 20 7b 70 72 65 70 61 72 65 64 20  ment} {prepared 
285e0 73 74 61 74 65 6d 65 6e 74 73 7d 0a 2a 2a 0a 2a  statements}.**.*
285f0 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66  * An instance of
28600 20 74 68 69 73 20 6f 62 6a 65 63 74 20 72 65 70   this object rep
28610 72 65 73 65 6e 74 73 20 61 20 73 69 6e 67 6c 65  resents a single
28620 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74   SQL statement t
28630 68 61 74 0a 2a 2a 20 68 61 73 20 62 65 65 6e 20  hat.** has been 
28640 63 6f 6d 70 69 6c 65 64 20 69 6e 74 6f 20 62 69  compiled into bi
28650 6e 61 72 79 20 66 6f 72 6d 20 61 6e 64 20 69 73  nary form and is
28660 20 72 65 61 64 79 20 74 6f 20 62 65 20 65 76 61   ready to be eva
28670 6c 75 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  luated..**.** Th
28680 69 6e 6b 20 6f 66 20 65 61 63 68 20 53 51 4c 20  ink of each SQL 
28690 73 74 61 74 65 6d 65 6e 74 20 61 73 20 61 20 73  statement as a s
286a0 65 70 61 72 61 74 65 20 63 6f 6d 70 75 74 65 72  eparate computer
286b0 20 70 72 6f 67 72 61 6d 2e 20 20 54 68 65 0a 2a   program.  The.*
286c0 2a 20 6f 72 69 67 69 6e 61 6c 20 53 51 4c 20 74  * original SQL t
286d0 65 78 74 20 69 73 20 73 6f 75 72 63 65 20 63 6f  ext is source co
286e0 64 65 2e 20 20 41 20 70 72 65 70 61 72 65 64 20  de.  A prepared 
286f0 73 74 61 74 65 6d 65 6e 74 20 6f 62 6a 65 63 74  statement object
28700 20 0a 2a 2a 20 69 73 20 74 68 65 20 63 6f 6d 70   .** is the comp
28710 69 6c 65 64 20 6f 62 6a 65 63 74 20 63 6f 64 65  iled object code
28720 2e 20 20 41 6c 6c 20 53 51 4c 20 6d 75 73 74 20  .  All SQL must 
28730 62 65 20 63 6f 6e 76 65 72 74 65 64 20 69 6e 74  be converted int
28740 6f 20 61 0a 2a 2a 20 70 72 65 70 61 72 65 64 20  o a.** prepared 
28750 73 74 61 74 65 6d 65 6e 74 20 62 65 66 6f 72 65  statement before
28760 20 69 74 20 63 61 6e 20 62 65 20 72 75 6e 2e 0a   it can be run..
28770 2a 2a 0a 2a 2a 20 54 68 65 20 6c 69 66 65 2d 63  **.** The life-c
28780 79 63 6c 65 20 6f 66 20 61 20 70 72 65 70 61 72  ycle of a prepar
28790 65 64 20 73 74 61 74 65 6d 65 6e 74 20 6f 62 6a  ed statement obj
287a0 65 63 74 20 75 73 75 61 6c 6c 79 20 67 6f 65 73  ect usually goes
287b0 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a   like this:.**.*
287c0 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 43  * <ol>.** <li> C
287d0 72 65 61 74 65 20 74 68 65 20 70 72 65 70 61 72  reate the prepar
287e0 65 64 20 73 74 61 74 65 6d 65 6e 74 20 6f 62 6a  ed statement obj
287f0 65 63 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ect using [sqlit
28800 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
28810 2e 0a 2a 2a 20 3c 6c 69 3e 20 42 69 6e 64 20 76  ..** <li> Bind v
28820 61 6c 75 65 73 20 74 6f 20 5b 70 61 72 61 6d 65  alues to [parame
28830 74 65 72 73 5d 20 75 73 69 6e 67 20 74 68 65 20  ters] using the 
28840 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29  sqlite3_bind_*()
28850 0a 2a 2a 20 20 20 20 20 20 69 6e 74 65 72 66 61  .**      interfa
28860 63 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 75 6e  ces..** <li> Run
28870 20 74 68 65 20 53 51 4c 20 62 79 20 63 61 6c 6c   the SQL by call
28880 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  ing [sqlite3_ste
28890 70 28 29 5d 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  p()] one or more
288a0 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20   times..** <li> 
288b0 52 65 73 65 74 20 74 68 65 20 70 72 65 70 61 72  Reset the prepar
288c0 65 64 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69  ed statement usi
288d0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  ng [sqlite3_rese
288e0 74 28 29 5d 20 74 68 65 6e 20 67 6f 20 62 61 63  t()] then go bac
288f0 6b 0a 2a 2a 20 20 20 20 20 20 74 6f 20 73 74 65  k.**      to ste
28900 70 20 32 2e 20 20 44 6f 20 74 68 69 73 20 7a 65  p 2.  Do this ze
28910 72 6f 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73  ro or more times
28920 2e 0a 2a 2a 20 3c 6c 69 3e 20 44 65 73 74 72 6f  ..** <li> Destro
28930 79 20 74 68 65 20 6f 62 6a 65 63 74 20 75 73 69  y the object usi
28940 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  ng [sqlite3_fina
28950 6c 69 7a 65 28 29 5d 2e 0a 2a 2a 20 3c 2f 6f 6c  lize()]..** </ol
28960 3e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72  >.*/.typedef str
28970 75 63 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  uct sqlite3_stmt
28980 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 3b 0a 0a   sqlite3_stmt;..
28990 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
289a0 52 75 6e 2d 74 69 6d 65 20 4c 69 6d 69 74 73 0a  Run-time Limits.
289b0 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
289c0 65 33 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20  e3.**.** ^(This 
289d0 69 6e 74 65 72 66 61 63 65 20 61 6c 6c 6f 77 73  interface allows
289e0 20 74 68 65 20 73 69 7a 65 20 6f 66 20 76 61 72   the size of var
289f0 69 6f 75 73 20 63 6f 6e 73 74 72 75 63 74 73 20  ious constructs 
28a00 74 6f 20 62 65 20 6c 69 6d 69 74 65 64 0a 2a 2a  to be limited.**
28a10 20 6f 6e 20 61 20 63 6f 6e 6e 65 63 74 69 6f 6e   on a connection
28a20 20 62 79 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62   by connection b
28a30 61 73 69 73 2e 20 20 54 68 65 20 66 69 72 73 74  asis.  The first
28a40 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68   parameter is th
28a50 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63  e.** [database c
28a60 6f 6e 6e 65 63 74 69 6f 6e 5d 20 77 68 6f 73 65  onnection] whose
28a70 20 6c 69 6d 69 74 20 69 73 20 74 6f 20 62 65 20   limit is to be 
28a80 73 65 74 20 6f 72 20 71 75 65 72 69 65 64 2e 20  set or queried. 
28a90 20 54 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70   The.** second p
28aa0 61 72 61 6d 65 74 65 72 20 69 73 20 6f 6e 65 20  arameter is one 
28ab0 6f 66 20 74 68 65 20 5b 6c 69 6d 69 74 20 63 61  of the [limit ca
28ac0 74 65 67 6f 72 69 65 73 5d 20 74 68 61 74 20 64  tegories] that d
28ad0 65 66 69 6e 65 20 61 0a 2a 2a 20 63 6c 61 73 73  efine a.** class
28ae0 20 6f 66 20 63 6f 6e 73 74 72 75 63 74 73 20 74   of constructs t
28af0 6f 20 62 65 20 73 69 7a 65 20 6c 69 6d 69 74 65  o be size limite
28b00 64 2e 20 20 54 68 65 20 74 68 69 72 64 20 70 61  d.  The third pa
28b10 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a  rameter is the.*
28b20 2a 20 6e 65 77 20 6c 69 6d 69 74 20 66 6f 72 20  * new limit for 
28b30 74 68 61 74 20 63 6f 6e 73 74 72 75 63 74 2e 29  that construct.)
28b40 5e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ^.**.** ^If the 
28b50 6e 65 77 20 6c 69 6d 69 74 20 69 73 20 61 20 6e  new limit is a n
28b60 65 67 61 74 69 76 65 20 6e 75 6d 62 65 72 2c 20  egative number, 
28b70 74 68 65 20 6c 69 6d 69 74 20 69 73 20 75 6e 63  the limit is unc
28b80 68 61 6e 67 65 64 2e 0a 2a 2a 20 5e 28 46 6f 72  hanged..** ^(For
28b90 20 65 61 63 68 20 6c 69 6d 69 74 20 63 61 74 65   each limit cate
28ba0 67 6f 72 79 20 53 51 4c 49 54 45 5f 4c 49 4d 49  gory SQLITE_LIMI
28bb0 54 5f 3c 69 3e 4e 41 4d 45 3c 2f 69 3e 20 74 68  T_<i>NAME</i> th
28bc0 65 72 65 20 69 73 20 61 20 0a 2a 2a 20 5b 6c 69  ere is a .** [li
28bd0 6d 69 74 73 20 7c 20 68 61 72 64 20 75 70 70 65  mits | hard uppe
28be0 72 20 62 6f 75 6e 64 5d 0a 2a 2a 20 73 65 74 20  r bound].** set 
28bf0 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  at compile-time 
28c00 62 79 20 61 20 43 20 70 72 65 70 72 6f 63 65 73  by a C preproces
28c10 73 6f 72 20 6d 61 63 72 6f 20 63 61 6c 6c 65 64  sor macro called
28c20 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c 20 53 51  .** [limits | SQ
28c30 4c 49 54 45 5f 4d 41 58 5f 3c 69 3e 4e 41 4d 45  LITE_MAX_<i>NAME
28c40 3c 2f 69 3e 5d 2e 0a 2a 2a 20 28 54 68 65 20 22  </i>]..** (The "
28c50 5f 4c 49 4d 49 54 5f 22 20 69 6e 20 74 68 65 20  _LIMIT_" in the 
28c60 6e 61 6d 65 20 69 73 20 63 68 61 6e 67 65 64 20  name is changed 
28c70 74 6f 20 22 5f 4d 41 58 5f 22 2e 29 29 5e 0a 2a  to "_MAX_".))^.*
28c80 2a 20 5e 41 74 74 65 6d 70 74 73 20 74 6f 20 69  * ^Attempts to i
28c90 6e 63 72 65 61 73 65 20 61 20 6c 69 6d 69 74 20  ncrease a limit 
28ca0 61 62 6f 76 65 20 69 74 73 20 68 61 72 64 20 75  above its hard u
28cb0 70 70 65 72 20 62 6f 75 6e 64 20 61 72 65 0a 2a  pper bound are.*
28cc0 2a 20 73 69 6c 65 6e 74 6c 79 20 74 72 75 6e 63  * silently trunc
28cd0 61 74 65 64 20 74 6f 20 74 68 65 20 68 61 72 64  ated to the hard
28ce0 20 75 70 70 65 72 20 62 6f 75 6e 64 2e 0a 2a 2a   upper bound..**
28cf0 0a 2a 2a 20 5e 52 65 67 61 72 64 6c 65 73 73 20  .** ^Regardless 
28d00 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f  of whether or no
28d10 74 20 74 68 65 20 6c 69 6d 69 74 20 77 61 73 20  t the limit was 
28d20 63 68 61 6e 67 65 64 2c 20 74 68 65 20 0a 2a 2a  changed, the .**
28d30 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28   [sqlite3_limit(
28d40 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  )] interface ret
28d50 75 72 6e 73 20 74 68 65 20 70 72 69 6f 72 20 76  urns the prior v
28d60 61 6c 75 65 20 6f 66 20 74 68 65 20 6c 69 6d 69  alue of the limi
28d70 74 2e 0a 2a 2a 20 5e 48 65 6e 63 65 2c 20 74 6f  t..** ^Hence, to
28d80 20 66 69 6e 64 20 74 68 65 20 63 75 72 72 65 6e   find the curren
28d90 74 20 76 61 6c 75 65 20 6f 66 20 61 20 6c 69 6d  t value of a lim
28da0 69 74 20 77 69 74 68 6f 75 74 20 63 68 61 6e 67  it without chang
28db0 69 6e 67 20 69 74 2c 0a 2a 2a 20 73 69 6d 70 6c  ing it,.** simpl
28dc0 79 20 69 6e 76 6f 6b 65 20 74 68 69 73 20 69 6e  y invoke this in
28dd0 74 65 72 66 61 63 65 20 77 69 74 68 20 74 68 65  terface with the
28de0 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
28df0 20 73 65 74 20 74 6f 20 2d 31 2e 0a 2a 2a 0a 2a   set to -1..**.*
28e00 2a 20 52 75 6e 2d 74 69 6d 65 20 6c 69 6d 69 74  * Run-time limit
28e10 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20 66  s are intended f
28e20 6f 72 20 75 73 65 20 69 6e 20 61 70 70 6c 69 63  or use in applic
28e30 61 74 69 6f 6e 73 20 74 68 61 74 20 6d 61 6e 61  ations that mana
28e40 67 65 0a 2a 2a 20 62 6f 74 68 20 74 68 65 69 72  ge.** both their
28e50 20 6f 77 6e 20 69 6e 74 65 72 6e 61 6c 20 64 61   own internal da
28e60 74 61 62 61 73 65 20 61 6e 64 20 61 6c 73 6f 20  tabase and also 
28e70 64 61 74 61 62 61 73 65 73 20 74 68 61 74 20 61  databases that a
28e80 72 65 20 63 6f 6e 74 72 6f 6c 6c 65 64 0a 2a 2a  re controlled.**
28e90 20 62 79 20 75 6e 74 72 75 73 74 65 64 20 65 78   by untrusted ex
28ea0 74 65 72 6e 61 6c 20 73 6f 75 72 63 65 73 2e 20  ternal sources. 
28eb0 20 41 6e 20 65 78 61 6d 70 6c 65 20 61 70 70 6c   An example appl
28ec0 69 63 61 74 69 6f 6e 20 6d 69 67 68 74 20 62 65  ication might be
28ed0 20 61 0a 2a 2a 20 77 65 62 20 62 72 6f 77 73 65   a.** web browse
28ee0 72 20 74 68 61 74 20 68 61 73 20 69 74 73 20 6f  r that has its o
28ef0 77 6e 20 64 61 74 61 62 61 73 65 73 20 66 6f 72  wn databases for
28f00 20 73 74 6f 72 69 6e 67 20 68 69 73 74 6f 72 79   storing history
28f10 20 61 6e 64 0a 2a 2a 20 73 65 70 61 72 61 74 65   and.** separate
28f20 20 64 61 74 61 62 61 73 65 73 20 63 6f 6e 74 72   databases contr
28f30 6f 6c 6c 65 64 20 62 79 20 4a 61 76 61 53 63 72  olled by JavaScr
28f40 69 70 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  ipt applications
28f50 20 64 6f 77 6e 6c 6f 61 64 65 64 0a 2a 2a 20 6f   downloaded.** o
28f60 66 66 20 74 68 65 20 49 6e 74 65 72 6e 65 74 2e  ff the Internet.
28f70 20 20 54 68 65 20 69 6e 74 65 72 6e 61 6c 20 64    The internal d
28f80 61 74 61 62 61 73 65 73 20 63 61 6e 20 62 65 20  atabases can be 
28f90 67 69 76 65 6e 20 74 68 65 0a 2a 2a 20 6c 61 72  given the.** lar
28fa0 67 65 2c 20 64 65 66 61 75 6c 74 20 6c 69 6d 69  ge, default limi
28fb0 74 73 2e 20 20 44 61 74 61 62 61 73 65 73 20 6d  ts.  Databases m
28fc0 61 6e 61 67 65 64 20 62 79 20 65 78 74 65 72 6e  anaged by extern
28fd0 61 6c 20 73 6f 75 72 63 65 73 20 63 61 6e 0a 2a  al sources can.*
28fe0 2a 20 62 65 20 67 69 76 65 6e 20 6d 75 63 68 20  * be given much 
28ff0 73 6d 61 6c 6c 65 72 20 6c 69 6d 69 74 73 20 64  smaller limits d
29000 65 73 69 67 6e 65 64 20 74 6f 20 70 72 65 76 65  esigned to preve
29010 6e 74 20 61 20 64 65 6e 69 61 6c 20 6f 66 20 73  nt a denial of s
29020 65 72 76 69 63 65 0a 2a 2a 20 61 74 74 61 63 6b  ervice.** attack
29030 2e 20 20 44 65 76 65 6c 6f 70 65 72 73 20 6d 69  .  Developers mi
29040 67 68 74 20 61 6c 73 6f 20 77 61 6e 74 20 74 6f  ght also want to
29050 20 75 73 65 20 74 68 65 20 5b 73 71 6c 69 74 65   use the [sqlite
29060 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72  3_set_authorizer
29070 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  ()].** interface
29080 20 74 6f 20 66 75 72 74 68 65 72 20 63 6f 6e 74   to further cont
29090 72 6f 6c 20 75 6e 74 72 75 73 74 65 64 20 53 51  rol untrusted SQ
290a0 4c 2e 20 20 54 68 65 20 73 69 7a 65 20 6f 66 20  L.  The size of 
290b0 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  the database.** 
290c0 63 72 65 61 74 65 64 20 62 79 20 61 6e 20 75 6e  created by an un
290d0 74 72 75 73 74 65 64 20 73 63 72 69 70 74 20 63  trusted script c
290e0 61 6e 20 62 65 20 63 6f 6e 74 61 69 6e 65 64 20  an be contained 
290f0 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 6d 61  using the.** [ma
29100 78 5f 70 61 67 65 5f 63 6f 75 6e 74 5d 20 5b 50  x_page_count] [P
29110 52 41 47 4d 41 5d 2e 0a 2a 2a 0a 2a 2a 20 4e 65  RAGMA]..**.** Ne
29120 77 20 72 75 6e 2d 74 69 6d 65 20 6c 69 6d 69 74  w run-time limit
29130 20 63 61 74 65 67 6f 72 69 65 73 20 6d 61 79 20   categories may 
29140 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75  be added in futu
29150 72 65 20 72 65 6c 65 61 73 65 73 2e 0a 2a 2f 0a  re releases..*/.
29160 69 6e 74 20 73 71 6c 69 74 65 33 5f 6c 69 6d 69  int sqlite3_limi
29170 74 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20  t(sqlite3*, int 
29180 69 64 2c 20 69 6e 74 20 6e 65 77 56 61 6c 29 3b  id, int newVal);
29190 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
291a0 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69 6d 69 74  : Run-Time Limit
291b0 20 43 61 74 65 67 6f 72 69 65 73 0a 2a 2a 20 4b   Categories.** K
291c0 45 59 57 4f 52 44 53 3a 20 7b 6c 69 6d 69 74 20  EYWORDS: {limit 
291d0 63 61 74 65 67 6f 72 79 7d 20 7b 2a 6c 69 6d 69  category} {*limi
291e0 74 20 63 61 74 65 67 6f 72 69 65 73 7d 0a 2a 2a  t categories}.**
291f0 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61  .** These consta
29200 6e 74 73 20 64 65 66 69 6e 65 20 76 61 72 69 6f  nts define vario
29210 75 73 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 6c  us performance l
29220 69 6d 69 74 73 0a 2a 2a 20 74 68 61 74 20 63 61  imits.** that ca
29230 6e 20 62 65 20 6c 6f 77 65 72 65 64 20 61 74 20  n be lowered at 
29240 72 75 6e 2d 74 69 6d 65 20 75 73 69 6e 67 20 5b  run-time using [
29250 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d  sqlite3_limit()]
29260 2e 0a 2a 2a 20 54 68 65 20 73 79 6e 6f 70 73 69  ..** The synopsi
29270 73 20 6f 66 20 74 68 65 20 6d 65 61 6e 69 6e 67  s of the meaning
29280 73 20 6f 66 20 74 68 65 20 76 61 72 69 6f 75 73  s of the various
29290 20 6c 69 6d 69 74 73 20 69 73 20 73 68 6f 77 6e   limits is shown
292a0 20 62 65 6c 6f 77 2e 0a 2a 2a 20 41 64 64 69 74   below..** Addit
292b0 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f  ional informatio
292c0 6e 20 69 73 20 61 76 61 69 6c 61 62 6c 65 20 61  n is available a
292d0 74 20 5b 6c 69 6d 69 74 73 20 7c 20 4c 69 6d 69  t [limits | Limi
292e0 74 73 20 69 6e 20 53 51 4c 69 74 65 5d 2e 0a 2a  ts in SQLite]..*
292f0 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53  *.** <dl>.** [[S
29300 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47  QLITE_LIMIT_LENG
29310 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54  TH]] ^(<dt>SQLIT
29320 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 3c 2f  E_LIMIT_LENGTH</
29330 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
29340 61 78 69 6d 75 6d 20 73 69 7a 65 20 6f 66 20 61  aximum size of a
29350 6e 79 20 73 74 72 69 6e 67 20 6f 72 20 42 4c 4f  ny string or BLO
29360 42 20 6f 72 20 74 61 62 6c 65 20 72 6f 77 2c 20  B or table row, 
29370 69 6e 20 62 79 74 65 73 2e 3c 64 64 3e 29 5e 0a  in bytes.<dd>)^.
29380 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c  **.** [[SQLITE_L
29390 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 5d  IMIT_SQL_LENGTH]
293a0 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c  ] ^(<dt>SQLITE_L
293b0 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 3c  IMIT_SQL_LENGTH<
293c0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
293d0 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f  maximum length o
293e0 66 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65  f an SQL stateme
293f0 6e 74 2c 20 69 6e 20 62 79 74 65 73 2e 3c 2f 64  nt, in bytes.</d
29400 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  d>)^.**.** [[SQL
29410 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e  ITE_LIMIT_COLUMN
29420 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f  ]] ^(<dt>SQLITE_
29430 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 3c 2f 64 74  LIMIT_COLUMN</dt
29440 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78  >.** <dd>The max
29450 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 63  imum number of c
29460 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 74 61 62 6c  olumns in a tabl
29470 65 20 64 65 66 69 6e 69 74 69 6f 6e 20 6f 72 20  e definition or 
29480 69 6e 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74  in the.** result
29490 20 73 65 74 20 6f 66 20 61 20 5b 53 45 4c 45 43   set of a [SELEC
294a0 54 5d 20 6f 72 20 74 68 65 20 6d 61 78 69 6d 75  T] or the maximu
294b0 6d 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75  m number of colu
294c0 6d 6e 73 20 69 6e 20 61 6e 20 69 6e 64 65 78 0a  mns in an index.
294d0 2a 2a 20 6f 72 20 69 6e 20 61 6e 20 4f 52 44 45  ** or in an ORDE
294e0 52 20 42 59 20 6f 72 20 47 52 4f 55 50 20 42 59  R BY or GROUP BY
294f0 20 63 6c 61 75 73 65 2e 3c 2f 64 64 3e 29 5e 0a   clause.</dd>)^.
29500 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c  **.** [[SQLITE_L
29510 49 4d 49 54 5f 45 58 50 52 5f 44 45 50 54 48 5d  IMIT_EXPR_DEPTH]
29520 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c  ] ^(<dt>SQLITE_L
29530 49 4d 49 54 5f 45 58 50 52 5f 44 45 50 54 48 3c  IMIT_EXPR_DEPTH<
29540 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
29550 6d 61 78 69 6d 75 6d 20 64 65 70 74 68 20 6f 66  maximum depth of
29560 20 74 68 65 20 70 61 72 73 65 20 74 72 65 65 20   the parse tree 
29570 6f 6e 20 61 6e 79 20 65 78 70 72 65 73 73 69 6f  on any expressio
29580 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20  n.</dd>)^.**.** 
29590 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43  [[SQLITE_LIMIT_C
295a0 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 5d 5d  OMPOUND_SELECT]]
295b0 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49   ^(<dt>SQLITE_LI
295c0 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c  MIT_COMPOUND_SEL
295d0 45 43 54 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  ECT</dt>.** <dd>
295e0 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62  The maximum numb
295f0 65 72 20 6f 66 20 74 65 72 6d 73 20 69 6e 20 61  er of terms in a
29600 20 63 6f 6d 70 6f 75 6e 64 20 53 45 4c 45 43 54   compound SELECT
29610 20 73 74 61 74 65 6d 65 6e 74 2e 3c 2f 64 64 3e   statement.</dd>
29620 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  )^.**.** [[SQLIT
29630 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50 5d  E_LIMIT_VDBE_OP]
29640 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c  ] ^(<dt>SQLITE_L
29650 49 4d 49 54 5f 56 44 42 45 5f 4f 50 3c 2f 64 74  IMIT_VDBE_OP</dt
29660 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78  >.** <dd>The max
29670 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 69  imum number of i
29680 6e 73 74 72 75 63 74 69 6f 6e 73 20 69 6e 20 61  nstructions in a
29690 20 76 69 72 74 75 61 6c 20 6d 61 63 68 69 6e 65   virtual machine
296a0 20 70 72 6f 67 72 61 6d 0a 2a 2a 20 75 73 65 64   program.** used
296b0 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 61 6e   to implement an
296c0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 20   SQL statement. 
296d0 20 49 66 20 5b 73 71 6c 69 74 65 33 5f 70 72 65   If [sqlite3_pre
296e0 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 0a 2a 2a  pare_v2()] or.**
296f0 20 74 68 65 20 65 71 75 69 76 61 6c 65 6e 74 20   the equivalent 
29700 74 72 69 65 73 20 74 6f 20 61 6c 6c 6f 63 61 74  tries to allocat
29710 65 20 73 70 61 63 65 20 66 6f 72 20 6d 6f 72 65  e space for more
29720 20 74 68 61 6e 20 74 68 69 73 20 6d 61 6e 79 20   than this many 
29730 6f 70 63 6f 64 65 73 0a 2a 2a 20 69 6e 20 61 20  opcodes.** in a 
29740 73 69 6e 67 6c 65 20 70 72 65 70 61 72 65 64 20  single prepared 
29750 73 74 61 74 65 6d 65 6e 74 2c 20 61 6e 20 53 51  statement, an SQ
29760 4c 49 54 45 5f 4e 4f 4d 45 4d 20 65 72 72 6f 72  LITE_NOMEM error
29770 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a   is returned..**
29780 20 41 20 76 61 6c 75 65 20 6f 66 20 30 20 6d 65   A value of 0 me
29790 61 6e 73 20 22 75 6e 6c 69 6d 69 74 65 64 22 2e  ans "unlimited".
297a0 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b  </dd>)^.**.** [[
297b0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e  SQLITE_LIMIT_FUN
297c0 43 54 49 4f 4e 5f 41 52 47 5d 5d 20 5e 28 3c 64  CTION_ARG]] ^(<d
297d0 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46  t>SQLITE_LIMIT_F
297e0 55 4e 43 54 49 4f 4e 5f 41 52 47 3c 2f 64 74 3e  UNCTION_ARG</dt>
297f0 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
29800 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 61 72  mum number of ar
29810 67 75 6d 65 6e 74 73 20 6f 6e 20 61 20 66 75 6e  guments on a fun
29820 63 74 69 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a  ction.</dd>)^.**
29830 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d  .** [[SQLITE_LIM
29840 49 54 5f 41 54 54 41 43 48 45 44 5d 5d 20 5e 28  IT_ATTACHED]] ^(
29850 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54  <dt>SQLITE_LIMIT
29860 5f 41 54 54 41 43 48 45 44 3c 2f 64 74 3e 0a 2a  _ATTACHED</dt>.*
29870 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
29880 6d 20 6e 75 6d 62 65 72 20 6f 66 20 5b 41 54 54  m number of [ATT
29890 41 43 48 20 7c 20 61 74 74 61 63 68 65 64 20 64  ACH | attached d
298a0 61 74 61 62 61 73 65 73 5d 2e 29 5e 3c 2f 64 64  atabases].)^</dd
298b0 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
298c0 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54  _LIMIT_LIKE_PATT
298d0 45 52 4e 5f 4c 45 4e 47 54 48 5d 5d 0a 2a 2a 20  ERN_LENGTH]].** 
298e0 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d  ^(<dt>SQLITE_LIM
298f0 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f  IT_LIKE_PATTERN_
29900 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c  LENGTH</dt>.** <
29910 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c  dd>The maximum l
29920 65 6e 67 74 68 20 6f 66 20 74 68 65 20 70 61 74  ength of the pat
29930 74 65 72 6e 20 61 72 67 75 6d 65 6e 74 20 74 6f  tern argument to
29940 20 74 68 65 20 5b 4c 49 4b 45 5d 20 6f 72 0a 2a   the [LIKE] or.*
29950 2a 20 5b 47 4c 4f 42 5d 20 6f 70 65 72 61 74 6f  * [GLOB] operato
29960 72 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a  rs.</dd>)^.**.**
29970 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f   [[SQLITE_LIMIT_
29980 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 5d  VARIABLE_NUMBER]
29990 5d 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54  ].** ^(<dt>SQLIT
299a0 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45  E_LIMIT_VARIABLE
299b0 5f 4e 55 4d 42 45 52 3c 2f 64 74 3e 0a 2a 2a 20  _NUMBER</dt>.** 
299c0 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
299d0 69 6e 64 65 78 20 6e 75 6d 62 65 72 20 6f 66 20  index number of 
299e0 61 6e 79 20 5b 70 61 72 61 6d 65 74 65 72 5d 20  any [parameter] 
299f0 69 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d  in an SQL statem
29a00 65 6e 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  ent.)^.**.** [[S
29a10 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47  QLITE_LIMIT_TRIG
29a20 47 45 52 5f 44 45 50 54 48 5d 5d 20 5e 28 3c 64  GER_DEPTH]] ^(<d
29a30 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54  t>SQLITE_LIMIT_T
29a40 52 49 47 47 45 52 5f 44 45 50 54 48 3c 2f 64 74  RIGGER_DEPTH</dt
29a50 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78  >.** <dd>The max
29a60 69 6d 75 6d 20 64 65 70 74 68 20 6f 66 20 72 65  imum depth of re
29a70 63 75 72 73 69 6f 6e 20 66 6f 72 20 74 72 69 67  cursion for trig
29a80 67 65 72 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a  gers.</dd>)^.**.
29a90 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49  ** [[SQLITE_LIMI
29aa0 54 5f 57 4f 52 4b 45 52 5f 54 48 52 45 41 44 53  T_WORKER_THREADS
29ab0 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f  ]] ^(<dt>SQLITE_
29ac0 4c 49 4d 49 54 5f 57 4f 52 4b 45 52 5f 54 48 52  LIMIT_WORKER_THR
29ad0 45 41 44 53 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  EADS</dt>.** <dd
29ae0 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d  >The maximum num
29af0 62 65 72 20 6f 66 20 61 75 78 69 6c 69 61 72 79  ber of auxiliary
29b00 20 77 6f 72 6b 65 72 20 74 68 72 65 61 64 73 20   worker threads 
29b10 74 68 61 74 20 61 20 73 69 6e 67 6c 65 0a 2a 2a  that a single.**
29b20 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
29b30 6d 65 6e 74 5d 20 6d 61 79 20 73 74 61 72 74 2e  ment] may start.
29b40 3c 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e  </dd>)^.** </dl>
29b50 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
29b60 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 20  TE_LIMIT_LENGTH 
29b70 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
29b80 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c     0.#define SQL
29b90 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45  ITE_LIMIT_SQL_LE
29ba0 4e 47 54 48 20 20 20 20 20 20 20 20 20 20 20 20  NGTH            
29bb0 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51      1.#define SQ
29bc0 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d  LITE_LIMIT_COLUM
29bd0 4e 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  N               
29be0 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53       2.#define S
29bf0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52  QLITE_LIMIT_EXPR
29c00 5f 44 45 50 54 48 20 20 20 20 20 20 20 20 20 20  _DEPTH          
29c10 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20        3.#define 
29c20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d  SQLITE_LIMIT_COM
29c30 50 4f 55 4e 44 5f 53 45 4c 45 43 54 20 20 20 20  POUND_SELECT    
29c40 20 20 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65         4.#define
29c50 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44   SQLITE_LIMIT_VD
29c60 42 45 5f 4f 50 20 20 20 20 20 20 20 20 20 20 20  BE_OP           
29c70 20 20 20 20 20 20 20 20 35 0a 23 64 65 66 69 6e          5.#defin
29c80 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46  e SQLITE_LIMIT_F
29c90 55 4e 43 54 49 4f 4e 5f 41 52 47 20 20 20 20 20  UNCTION_ARG     
29ca0 20 20 20 20 20 20 20 20 20 36 0a 23 64 65 66 69           6.#defi
29cb0 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
29cc0 41 54 54 41 43 48 45 44 20 20 20 20 20 20 20 20  ATTACHED        
29cd0 20 20 20 20 20 20 20 20 20 20 37 0a 23 64 65 66            7.#def
29ce0 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
29cf0 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45  _LIKE_PATTERN_LE
29d00 4e 47 54 48 20 20 20 20 20 20 20 38 0a 23 64 65  NGTH       8.#de
29d10 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
29d20 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45  T_VARIABLE_NUMBE
29d30 52 20 20 20 20 20 20 20 20 20 20 20 39 0a 23 64  R           9.#d
29d40 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
29d50 49 54 5f 54 52 49 47 47 45 52 5f 44 45 50 54 48  IT_TRIGGER_DEPTH
29d60 20 20 20 20 20 20 20 20 20 20 20 20 31 30 0a 23              10.#
29d70 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
29d80 4d 49 54 5f 57 4f 52 4b 45 52 5f 54 48 52 45 41  MIT_WORKER_THREA
29d90 44 53 20 20 20 20 20 20 20 20 20 20 20 31 31 0a  DS           11.
29da0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
29db0 3a 20 43 6f 6d 70 69 6c 69 6e 67 20 41 6e 20 53  : Compiling An S
29dc0 51 4c 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 20  QL Statement.** 
29dd0 4b 45 59 57 4f 52 44 53 3a 20 7b 53 51 4c 20 73  KEYWORDS: {SQL s
29de0 74 61 74 65 6d 65 6e 74 20 63 6f 6d 70 69 6c 65  tatement compile
29df0 72 7d 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  r}.** METHOD: sq
29e00 6c 69 74 65 33 0a 2a 2a 20 43 4f 4e 53 54 52 55  lite3.** CONSTRU
29e10 43 54 4f 52 3a 20 73 71 6c 69 74 65 33 5f 73 74  CTOR: sqlite3_st
29e20 6d 74 0a 2a 2a 0a 2a 2a 20 54 6f 20 65 78 65 63  mt.**.** To exec
29e30 75 74 65 20 61 6e 20 53 51 4c 20 71 75 65 72 79  ute an SQL query
29e40 2c 20 69 74 20 6d 75 73 74 20 66 69 72 73 74 20  , it must first 
29e50 62 65 20 63 6f 6d 70 69 6c 65 64 20 69 6e 74 6f  be compiled into
29e60 20 61 20 62 79 74 65 2d 63 6f 64 65 0a 2a 2a 20   a byte-code.** 
29e70 70 72 6f 67 72 61 6d 20 75 73 69 6e 67 20 6f 6e  program using on
29e80 65 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69  e of these routi
29e90 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66  nes..**.** The f
29ea0 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2c 20 22  irst argument, "
29eb0 64 62 22 2c 20 69 73 20 61 20 5b 64 61 74 61 62  db", is a [datab
29ec0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
29ed0 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 61 0a  obtained from a.
29ee0 2a 2a 20 70 72 69 6f 72 20 73 75 63 63 65 73 73  ** prior success
29ef0 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  ful call to [sql
29f00 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73  ite3_open()], [s
29f10 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
29f20 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ] or.** [sqlite3
29f30 5f 6f 70 65 6e 31 36 28 29 5d 2e 20 20 54 68 65  _open16()].  The
29f40 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
29f50 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 68 61  tion must not ha
29f60 76 65 20 62 65 65 6e 20 63 6c 6f 73 65 64 2e 0a  ve been closed..
29f70 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64  **.** The second
29f80 20 61 72 67 75 6d 65 6e 74 2c 20 22 7a 53 71 6c   argument, "zSql
29f90 22 2c 20 69 73 20 74 68 65 20 73 74 61 74 65 6d  ", is the statem
29fa0 65 6e 74 20 74 6f 20 62 65 20 63 6f 6d 70 69 6c  ent to be compil
29fb0 65 64 2c 20 65 6e 63 6f 64 65 64 0a 2a 2a 20 61  ed, encoded.** a
29fc0 73 20 65 69 74 68 65 72 20 55 54 46 2d 38 20 6f  s either UTF-8 o
29fd0 72 20 55 54 46 2d 31 36 2e 20 20 54 68 65 20 73  r UTF-16.  The s
29fe0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29  qlite3_prepare()
29ff0 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65   and sqlite3_pre
2a000 70 61 72 65 5f 76 32 28 29 0a 2a 2a 20 69 6e 74  pare_v2().** int
2a010 65 72 66 61 63 65 73 20 75 73 65 20 55 54 46 2d  erfaces use UTF-
2a020 38 2c 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70  8, and sqlite3_p
2a030 72 65 70 61 72 65 31 36 28 29 20 61 6e 64 20 73  repare16() and s
2a040 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
2a050 5f 76 32 28 29 0a 2a 2a 20 75 73 65 20 55 54 46  _v2().** use UTF
2a060 2d 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  -16..**.** ^If t
2a070 68 65 20 6e 42 79 74 65 20 61 72 67 75 6d 65 6e  he nByte argumen
2a080 74 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74  t is negative, t
2a090 68 65 6e 20 7a 53 71 6c 20 69 73 20 72 65 61 64  hen zSql is read
2a0a0 20 75 70 20 74 6f 20 74 68 65 0a 2a 2a 20 66 69   up to the.** fi
2a0b0 72 73 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61  rst zero termina
2a0c0 74 6f 72 2e 20 5e 49 66 20 6e 42 79 74 65 20 69  tor. ^If nByte i
2a0d0 73 20 70 6f 73 69 74 69 76 65 2c 20 74 68 65 6e  s positive, then
2a0e0 20 69 74 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75   it is the.** nu
2a0f0 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 72 65  mber of bytes re
2a100 61 64 20 66 72 6f 6d 20 7a 53 71 6c 2e 20 20 5e  ad from zSql.  ^
2a110 49 66 20 6e 42 79 74 65 20 69 73 20 7a 65 72 6f  If nByte is zero
2a120 2c 20 74 68 65 6e 20 6e 6f 20 70 72 65 70 61 72  , then no prepar
2a130 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20  ed.** statement 
2a140 69 73 20 67 65 6e 65 72 61 74 65 64 2e 0a 2a 2a  is generated..**
2a150 20 49 66 20 74 68 65 20 63 61 6c 6c 65 72 20 6b   If the caller k
2a160 6e 6f 77 73 20 74 68 61 74 20 74 68 65 20 73 75  nows that the su
2a170 70 70 6c 69 65 64 20 73 74 72 69 6e 67 20 69 73  pplied string is
2a180 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 65 64 2c   nul-terminated,
2a190 20 74 68 65 6e 0a 2a 2a 20 74 68 65 72 65 20 69   then.** there i
2a1a0 73 20 61 20 73 6d 61 6c 6c 20 70 65 72 66 6f 72  s a small perfor
2a1b0 6d 61 6e 63 65 20 61 64 76 61 6e 74 61 67 65 20  mance advantage 
2a1c0 74 6f 20 70 61 73 73 69 6e 67 20 61 6e 20 6e 42  to passing an nB
2a1d0 79 74 65 20 70 61 72 61 6d 65 74 65 72 20 74 68  yte parameter th
2a1e0 61 74 0a 2a 2a 20 69 73 20 74 68 65 20 6e 75 6d  at.** is the num
2a1f0 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20  ber of bytes in 
2a200 74 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67  the input string
2a210 20 3c 69 3e 69 6e 63 6c 75 64 69 6e 67 3c 2f 69   <i>including</i
2a220 3e 0a 2a 2a 20 74 68 65 20 6e 75 6c 2d 74 65 72  >.** the nul-ter
2a230 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 0a 2a 2a 20 5e  minator..**.** ^
2a240 49 66 20 70 7a 54 61 69 6c 20 69 73 20 6e 6f 74  If pzTail is not
2a250 20 4e 55 4c 4c 20 74 68 65 6e 20 2a 70 7a 54 61   NULL then *pzTa
2a260 69 6c 20 69 73 20 6d 61 64 65 20 74 6f 20 70 6f  il is made to po
2a270 69 6e 74 20 74 6f 20 74 68 65 20 66 69 72 73 74  int to the first
2a280 20 62 79 74 65 0a 2a 2a 20 70 61 73 74 20 74 68   byte.** past th
2a290 65 20 65 6e 64 20 6f 66 20 74 68 65 20 66 69 72  e end of the fir
2a2a0 73 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  st SQL statement
2a2b0 20 69 6e 20 7a 53 71 6c 2e 20 20 54 68 65 73 65   in zSql.  These
2a2c0 20 72 6f 75 74 69 6e 65 73 20 6f 6e 6c 79 0a 2a   routines only.*
2a2d0 2a 20 63 6f 6d 70 69 6c 65 20 74 68 65 20 66 69  * compile the fi
2a2e0 72 73 74 20 73 74 61 74 65 6d 65 6e 74 20 69 6e  rst statement in
2a2f0 20 7a 53 71 6c 2c 20 73 6f 20 2a 70 7a 54 61 69   zSql, so *pzTai
2a300 6c 20 69 73 20 6c 65 66 74 20 70 6f 69 6e 74 69  l is left pointi
2a310 6e 67 20 74 6f 0a 2a 2a 20 77 68 61 74 20 72 65  ng to.** what re
2a320 6d 61 69 6e 73 20 75 6e 63 6f 6d 70 69 6c 65 64  mains uncompiled
2a330 2e 0a 2a 2a 0a 2a 2a 20 5e 2a 70 70 53 74 6d 74  ..**.** ^*ppStmt
2a340 20 69 73 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e   is left pointin
2a350 67 20 74 6f 20 61 20 63 6f 6d 70 69 6c 65 64 20  g to a compiled 
2a360 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2a370 65 6e 74 5d 20 74 68 61 74 20 63 61 6e 20 62 65  ent] that can be
2a380 0a 2a 2a 20 65 78 65 63 75 74 65 64 20 75 73 69  .** executed usi
2a390 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  ng [sqlite3_step
2a3a0 28 29 5d 2e 20 20 5e 49 66 20 74 68 65 72 65 20  ()].  ^If there 
2a3b0 69 73 20 61 6e 20 65 72 72 6f 72 2c 20 2a 70 70  is an error, *pp
2a3c0 53 74 6d 74 20 69 73 20 73 65 74 0a 2a 2a 20 74  Stmt is set.** t
2a3d0 6f 20 4e 55 4c 4c 2e 20 20 5e 49 66 20 74 68 65  o NULL.  ^If the
2a3e0 20 69 6e 70 75 74 20 74 65 78 74 20 63 6f 6e 74   input text cont
2a3f0 61 69 6e 73 20 6e 6f 20 53 51 4c 20 28 69 66 20  ains no SQL (if 
2a400 74 68 65 20 69 6e 70 75 74 20 69 73 20 61 6e 20  the input is an 
2a410 65 6d 70 74 79 0a 2a 2a 20 73 74 72 69 6e 67 20  empty.** string 
2a420 6f 72 20 61 20 63 6f 6d 6d 65 6e 74 29 20 74 68  or a comment) th
2a430 65 6e 20 2a 70 70 53 74 6d 74 20 69 73 20 73 65  en *ppStmt is se
2a440 74 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 20 54 68  t to NULL..** Th
2a450 65 20 63 61 6c 6c 69 6e 67 20 70 72 6f 63 65 64  e calling proced
2a460 75 72 65 20 69 73 20 72 65 73 70 6f 6e 73 69 62  ure is responsib
2a470 6c 65 20 66 6f 72 20 64 65 6c 65 74 69 6e 67 20  le for deleting 
2a480 74 68 65 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20  the compiled.** 
2a490 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 75 73  SQL statement us
2a4a0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e  ing [sqlite3_fin
2a4b0 61 6c 69 7a 65 28 29 5d 20 61 66 74 65 72 20 69  alize()] after i
2a4c0 74 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 77  t has finished w
2a4d0 69 74 68 20 69 74 2e 0a 2a 2a 20 70 70 53 74 6d  ith it..** ppStm
2a4e0 74 20 6d 61 79 20 6e 6f 74 20 62 65 20 4e 55 4c  t may not be NUL
2a4f0 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 20 73 75 63  L..**.** ^On suc
2a500 63 65 73 73 2c 20 74 68 65 20 73 71 6c 69 74 65  cess, the sqlite
2a510 33 5f 70 72 65 70 61 72 65 28 29 20 66 61 6d 69  3_prepare() fami
2a520 6c 79 20 6f 66 20 72 6f 75 74 69 6e 65 73 20 72  ly of routines r
2a530 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b  eturn [SQLITE_OK
2a540 5d 3b 0a 2a 2a 20 6f 74 68 65 72 77 69 73 65 20  ];.** otherwise 
2a550 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20  an [error code] 
2a560 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a  is returned..**.
2a570 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 70  ** The sqlite3_p
2a580 72 65 70 61 72 65 5f 76 32 28 29 20 61 6e 64 20  repare_v2() and 
2a590 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
2a5a0 36 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63 65  6_v2() interface
2a5b0 73 20 61 72 65 0a 2a 2a 20 72 65 63 6f 6d 6d 65  s are.** recomme
2a5c0 6e 64 65 64 20 66 6f 72 20 61 6c 6c 20 6e 65 77  nded for all new
2a5d0 20 70 72 6f 67 72 61 6d 73 2e 20 54 68 65 20 74   programs. The t
2a5e0 77 6f 20 6f 6c 64 65 72 20 69 6e 74 65 72 66 61  wo older interfa
2a5f0 63 65 73 20 61 72 65 20 72 65 74 61 69 6e 65 64  ces are retained
2a600 0a 2a 2a 20 66 6f 72 20 62 61 63 6b 77 61 72 64  .** for backward
2a610 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2c  s compatibility,
2a620 20 62 75 74 20 74 68 65 69 72 20 75 73 65 20 69   but their use i
2a630 73 20 64 69 73 63 6f 75 72 61 67 65 64 2e 0a 2a  s discouraged..*
2a640 2a 20 5e 49 6e 20 74 68 65 20 22 76 32 22 20 69  * ^In the "v2" i
2a650 6e 74 65 72 66 61 63 65 73 2c 20 74 68 65 20 70  nterfaces, the p
2a660 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2a670 74 0a 2a 2a 20 74 68 61 74 20 69 73 20 72 65 74  t.** that is ret
2a680 75 72 6e 65 64 20 28 74 68 65 20 5b 73 71 6c 69  urned (the [sqli
2a690 74 65 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74  te3_stmt] object
2a6a0 29 20 63 6f 6e 74 61 69 6e 73 20 61 20 63 6f 70  ) contains a cop
2a6b0 79 20 6f 66 20 74 68 65 0a 2a 2a 20 6f 72 69 67  y of the.** orig
2a6c0 69 6e 61 6c 20 53 51 4c 20 74 65 78 74 2e 20 54  inal SQL text. T
2a6d0 68 69 73 20 63 61 75 73 65 73 20 74 68 65 20 5b  his causes the [
2a6e0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
2a6f0 69 6e 74 65 72 66 61 63 65 20 74 6f 0a 2a 2a 20  interface to.** 
2a700 62 65 68 61 76 65 20 64 69 66 66 65 72 65 6e 74  behave different
2a710 6c 79 20 69 6e 20 74 68 72 65 65 20 77 61 79 73  ly in three ways
2a720 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20  :.**.** <ol>.** 
2a730 3c 6c 69 3e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  <li>.** ^If the 
2a740 64 61 74 61 62 61 73 65 20 73 63 68 65 6d 61 20  database schema 
2a750 63 68 61 6e 67 65 73 2c 20 69 6e 73 74 65 61 64  changes, instead
2a760 20 6f 66 20 72 65 74 75 72 6e 69 6e 67 20 5b 53   of returning [S
2a770 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 20 61 73  QLITE_SCHEMA] as
2a780 20 69 74 0a 2a 2a 20 61 6c 77 61 79 73 20 75 73   it.** always us
2a790 65 64 20 74 6f 20 64 6f 2c 20 5b 73 71 6c 69 74  ed to do, [sqlit
2a7a0 65 33 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c 20  e3_step()] will 
2a7b0 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 65  automatically re
2a7c0 63 6f 6d 70 69 6c 65 20 74 68 65 20 53 51 4c 0a  compile the SQL.
2a7d0 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64  ** statement and
2a7e0 20 74 72 79 20 74 6f 20 72 75 6e 20 69 74 20 61   try to run it a
2a7f0 67 61 69 6e 2e 20 41 73 20 6d 61 6e 79 20 61 73  gain. As many as
2a800 20 5b 53 51 4c 49 54 45 5f 4d 41 58 5f 53 43 48   [SQLITE_MAX_SCH
2a810 45 4d 41 5f 52 45 54 52 59 5d 0a 2a 2a 20 72 65  EMA_RETRY].** re
2a820 74 72 69 65 73 20 77 69 6c 6c 20 6f 63 63 75 72  tries will occur
2a830 20 62 65 66 6f 72 65 20 73 71 6c 69 74 65 33 5f   before sqlite3_
2a840 73 74 65 70 28 29 20 67 69 76 65 73 20 75 70 20  step() gives up 
2a850 61 6e 64 20 72 65 74 75 72 6e 73 20 61 6e 20 65  and returns an e
2a860 72 72 6f 72 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a  rror..** </li>.*
2a870 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 57 68  *.** <li>.** ^Wh
2a880 65 6e 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75  en an error occu
2a890 72 73 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  rs, [sqlite3_ste
2a8a0 70 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e  p()] will return
2a8b0 20 6f 6e 65 20 6f 66 20 74 68 65 20 64 65 74 61   one of the deta
2a8c0 69 6c 65 64 0a 2a 2a 20 5b 65 72 72 6f 72 20 63  iled.** [error c
2a8d0 6f 64 65 73 5d 20 6f 72 20 5b 65 78 74 65 6e 64  odes] or [extend
2a8e0 65 64 20 65 72 72 6f 72 20 63 6f 64 65 73 5d 2e  ed error codes].
2a8f0 20 20 5e 54 68 65 20 6c 65 67 61 63 79 20 62 65    ^The legacy be
2a900 68 61 76 69 6f 72 20 77 61 73 20 74 68 61 74 0a  havior was that.
2a910 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  ** [sqlite3_step
2a920 28 29 5d 20 77 6f 75 6c 64 20 6f 6e 6c 79 20 72  ()] would only r
2a930 65 74 75 72 6e 20 61 20 67 65 6e 65 72 69 63 20  eturn a generic 
2a940 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 72  [SQLITE_ERROR] r
2a950 65 73 75 6c 74 20 63 6f 64 65 0a 2a 2a 20 61 6e  esult code.** an
2a960 64 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  d the applicatio
2a970 6e 20 77 6f 75 6c 64 20 68 61 76 65 20 74 6f 20  n would have to 
2a980 6d 61 6b 65 20 61 20 73 65 63 6f 6e 64 20 63 61  make a second ca
2a990 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72  ll to [sqlite3_r
2a9a0 65 73 65 74 28 29 5d 0a 2a 2a 20 69 6e 20 6f 72  eset()].** in or
2a9b0 64 65 72 20 74 6f 20 66 69 6e 64 20 74 68 65 20  der to find the 
2a9c0 75 6e 64 65 72 6c 79 69 6e 67 20 63 61 75 73 65  underlying cause
2a9d0 20 6f 66 20 74 68 65 20 70 72 6f 62 6c 65 6d 2e   of the problem.
2a9e0 20 57 69 74 68 20 74 68 65 20 22 76 32 22 20 70   With the "v2" p
2a9f0 72 65 70 61 72 65 0a 2a 2a 20 69 6e 74 65 72 66  repare.** interf
2aa00 61 63 65 73 2c 20 74 68 65 20 75 6e 64 65 72 6c  aces, the underl
2aa10 79 69 6e 67 20 72 65 61 73 6f 6e 20 66 6f 72 20  ying reason for 
2aa20 74 68 65 20 65 72 72 6f 72 20 69 73 20 72 65 74  the error is ret
2aa30 75 72 6e 65 64 20 69 6d 6d 65 64 69 61 74 65 6c  urned immediatel
2aa40 79 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a  y..** </li>.**.*
2aa50 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 49 66 20 74 68  * <li>.** ^If th
2aa60 65 20 73 70 65 63 69 66 69 63 20 76 61 6c 75 65  e specific value
2aa70 20 62 6f 75 6e 64 20 74 6f 20 5b 70 61 72 61 6d   bound to [param
2aa80 65 74 65 72 20 7c 20 68 6f 73 74 20 70 61 72 61  eter | host para
2aa90 6d 65 74 65 72 5d 20 69 6e 20 74 68 65 20 0a 2a  meter] in the .*
2aaa0 2a 20 57 48 45 52 45 20 63 6c 61 75 73 65 20 6d  * WHERE clause m
2aab0 69 67 68 74 20 69 6e 66 6c 75 65 6e 63 65 20 74  ight influence t
2aac0 68 65 20 63 68 6f 69 63 65 20 6f 66 20 71 75 65  he choice of que
2aad0 72 79 20 70 6c 61 6e 20 66 6f 72 20 61 20 73 74  ry plan for a st
2aae0 61 74 65 6d 65 6e 74 2c 0a 2a 2a 20 74 68 65 6e  atement,.** then
2aaf0 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 77   the statement w
2ab00 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61 74 69 63  ill be automatic
2ab10 61 6c 6c 79 20 72 65 63 6f 6d 70 69 6c 65 64 2c  ally recompiled,
2ab20 20 61 73 20 69 66 20 74 68 65 72 65 20 68 61 64   as if there had
2ab30 20 62 65 65 6e 20 0a 2a 2a 20 61 20 73 63 68 65   been .** a sche
2ab40 6d 61 20 63 68 61 6e 67 65 2c 20 6f 6e 20 74 68  ma change, on th
2ab50 65 20 66 69 72 73 74 20 20 5b 73 71 6c 69 74 65  e first  [sqlite
2ab60 33 5f 73 74 65 70 28 29 5d 20 63 61 6c 6c 20 66  3_step()] call f
2ab70 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79 20 63 68 61  ollowing any cha
2ab80 6e 67 65 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73  nge.** to the [s
2ab90 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
2aba0 20 7c 20 62 69 6e 64 69 6e 67 73 5d 20 6f 66 20   | bindings] of 
2abb0 74 68 61 74 20 5b 70 61 72 61 6d 65 74 65 72 5d  that [parameter]
2abc0 2e 20 0a 2a 2a 20 5e 54 68 65 20 73 70 65 63 69  . .** ^The speci
2abd0 66 69 63 20 76 61 6c 75 65 20 6f 66 20 57 48 45  fic value of WHE
2abe0 52 45 2d 63 6c 61 75 73 65 20 5b 70 61 72 61 6d  RE-clause [param
2abf0 65 74 65 72 5d 20 6d 69 67 68 74 20 69 6e 66 6c  eter] might infl
2ac00 75 65 6e 63 65 20 74 68 65 20 0a 2a 2a 20 63 68  uence the .** ch
2ac10 6f 69 63 65 20 6f 66 20 71 75 65 72 79 20 70 6c  oice of query pl
2ac20 61 6e 20 69 66 20 74 68 65 20 70 61 72 61 6d 65  an if the parame
2ac30 74 65 72 20 69 73 20 74 68 65 20 6c 65 66 74 2d  ter is the left-
2ac40 68 61 6e 64 20 73 69 64 65 20 6f 66 20 61 20 5b  hand side of a [
2ac50 4c 49 4b 45 5d 0a 2a 2a 20 6f 72 20 5b 47 4c 4f  LIKE].** or [GLO
2ac60 42 5d 20 6f 70 65 72 61 74 6f 72 20 6f 72 20 69  B] operator or i
2ac70 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20  f the parameter 
2ac80 69 73 20 63 6f 6d 70 61 72 65 64 20 74 6f 20 61  is compared to a
2ac90 6e 20 69 6e 64 65 78 65 64 20 63 6f 6c 75 6d 6e  n indexed column
2aca0 0a 2a 2a 20 61 6e 64 20 74 68 65 20 5b 53 51 4c  .** and the [SQL
2acb0 49 54 45 5f 45 4e 41 42 4c 45 5f 53 54 41 54 33  ITE_ENABLE_STAT3
2acc0 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
2acd0 70 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64  ption is enabled
2ace0 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f  ..** </li>.** </
2acf0 6f 6c 3e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  ol>.*/.int sqlit
2ad00 65 33 5f 70 72 65 70 61 72 65 28 0a 20 20 73 71  e3_prepare(.  sq
2ad10 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20  lite3 *db,      
2ad20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73        /* Databas
2ad30 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f  e handle */.  co
2ad40 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20  nst char *zSql, 
2ad50 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61        /* SQL sta
2ad60 74 65 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e  tement, UTF-8 en
2ad70 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e  coded */.  int n
2ad80 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 20  Byte,           
2ad90 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65     /* Maximum le
2ada0 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20  ngth of zSql in 
2adb0 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69  bytes. */.  sqli
2adc0 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d  te3_stmt **ppStm
2add0 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74  t,  /* OUT: Stat
2ade0 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a  ement handle */.
2adf0 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70    const char **p
2ae00 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54  zTail     /* OUT
2ae10 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75  : Pointer to unu
2ae20 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a  sed portion of z
2ae30 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71  Sql */.);.int sq
2ae40 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
2ae50 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
2ae60 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44              /* D
2ae70 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a  atabase handle *
2ae80 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  /.  const char *
2ae90 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53  zSql,       /* S
2aea0 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54  QL statement, UT
2aeb0 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20  F-8 encoded */. 
2aec0 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20   int nByte,     
2aed0 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69           /* Maxi
2aee0 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53  mum length of zS
2aef0 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a  ql in bytes. */.
2af00 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a    sqlite3_stmt *
2af10 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54  *ppStmt,  /* OUT
2af20 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64  : Statement hand
2af30 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68  le */.  const ch
2af40 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20  ar **pzTail     
2af50 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20  /* OUT: Pointer 
2af60 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f  to unused portio
2af70 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a  n of zSql */.);.
2af80 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70  int sqlite3_prep
2af90 61 72 65 31 36 28 0a 20 20 73 71 6c 69 74 65 33  are16(.  sqlite3
2afa0 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20   *db,           
2afb0 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e   /* Database han
2afc0 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76  dle */.  const v
2afd0 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20  oid *zSql,      
2afe0 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   /* SQL statemen
2aff0 74 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65  t, UTF-16 encode
2b000 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65  d */.  int nByte
2b010 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f  ,              /
2b020 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68  * Maximum length
2b030 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65   of zSql in byte
2b040 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f  s. */.  sqlite3_
2b050 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20  stmt **ppStmt,  
2b060 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e  /* OUT: Statemen
2b070 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f  t handle */.  co
2b080 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69  nst void **pzTai
2b090 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f  l     /* OUT: Po
2b0a0 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20  inter to unused 
2b0b0 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20  portion of zSql 
2b0c0 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  */.);.int sqlite
2b0d0 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 0a  3_prepare16_v2(.
2b0e0 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20    sqlite3 *db,  
2b0f0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74            /* Dat
2b100 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a  abase handle */.
2b110 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53    const void *zS
2b120 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c  ql,       /* SQL
2b130 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d   statement, UTF-
2b140 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20  16 encoded */.  
2b150 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20  int nByte,      
2b160 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d          /* Maxim
2b170 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71  um length of zSq
2b180 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20  l in bytes. */. 
2b190 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a   sqlite3_stmt **
2b1a0 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a  ppStmt,  /* OUT:
2b1b0 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c   Statement handl
2b1c0 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69  e */.  const voi
2b1d0 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f  d **pzTail     /
2b1e0 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74  * OUT: Pointer t
2b1f0 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e  o unused portion
2b200 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 0a   of zSql */.);..
2b210 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
2b220 52 65 74 72 69 65 76 69 6e 67 20 53 74 61 74 65  Retrieving State
2b230 6d 65 6e 74 20 53 51 4c 0a 2a 2a 20 4d 45 54 48  ment SQL.** METH
2b240 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  OD: sqlite3_stmt
2b250 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
2b260 74 65 33 5f 73 71 6c 28 50 29 20 69 6e 74 65 72  te3_sql(P) inter
2b270 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 70  face returns a p
2b280 6f 69 6e 74 65 72 20 74 6f 20 61 20 63 6f 70 79  ointer to a copy
2b290 20 6f 66 20 74 68 65 20 55 54 46 2d 38 0a 2a 2a   of the UTF-8.**
2b2a0 20 53 51 4c 20 74 65 78 74 20 75 73 65 64 20 74   SQL text used t
2b2b0 6f 20 63 72 65 61 74 65 20 5b 70 72 65 70 61 72  o create [prepar
2b2c0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 50 20  ed statement] P 
2b2d0 69 66 20 50 20 77 61 73 0a 2a 2a 20 63 72 65 61  if P was.** crea
2b2e0 74 65 64 20 62 79 20 65 69 74 68 65 72 20 5b 73  ted by either [s
2b2f0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
2b300 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  2()] or [sqlite3
2b310 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d  _prepare16_v2()]
2b320 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  ..** ^The sqlite
2b330 33 5f 65 78 70 61 6e 64 65 64 5f 73 71 6c 28 50  3_expanded_sql(P
2b340 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ) interface retu
2b350 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
2b360 20 61 20 55 54 46 2d 38 0a 2a 2a 20 73 74 72 69   a UTF-8.** stri
2b370 6e 67 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68  ng containing th
2b380 65 20 53 51 4c 20 74 65 78 74 20 6f 66 20 70 72  e SQL text of pr
2b390 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2b3a0 20 50 20 77 69 74 68 0a 2a 2a 20 5b 62 6f 75 6e   P with.** [boun
2b3b0 64 20 70 61 72 61 6d 65 74 65 72 73 5d 20 65 78  d parameters] ex
2b3c0 70 61 6e 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28  panded..**.** ^(
2b3d0 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 69 66 20  For example, if 
2b3e0 61 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  a prepared state
2b3f0 6d 65 6e 74 20 69 73 20 63 72 65 61 74 65 64 20  ment is created 
2b400 75 73 69 6e 67 20 74 68 65 20 53 51 4c 0a 2a 2a  using the SQL.**
2b410 20 74 65 78 74 20 22 53 45 4c 45 43 54 20 24 61   text "SELECT $a
2b420 62 63 2c 3a 78 79 7a 22 20 61 6e 64 20 69 66 20  bc,:xyz" and if 
2b430 70 61 72 61 6d 65 74 65 72 20 24 61 62 63 20 69  parameter $abc i
2b440 73 20 62 6f 75 6e 64 20 74 6f 20 69 6e 74 65 67  s bound to integ
2b450 65 72 20 32 33 34 35 0a 2a 2a 20 61 6e 64 20 70  er 2345.** and p
2b460 61 72 61 6d 65 74 65 72 20 3a 78 79 7a 20 69 73  arameter :xyz is
2b470 20 75 6e 62 6f 75 6e 64 2c 20 74 68 65 6e 20 73   unbound, then s
2b480 71 6c 69 74 65 33 5f 73 71 6c 28 29 20 77 69 6c  qlite3_sql() wil
2b490 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 74 68 65 20  l return.** the 
2b4a0 6f 72 69 67 69 6e 61 6c 20 73 74 72 69 6e 67 2c  original string,
2b4b0 20 22 53 45 4c 45 43 54 20 24 61 62 63 2c 3a 78   "SELECT $abc,:x
2b4c0 79 7a 22 20 62 75 74 20 73 71 6c 69 74 65 33 5f  yz" but sqlite3_
2b4d0 65 78 70 61 6e 64 65 64 5f 73 71 6c 28 29 0a 2a  expanded_sql().*
2b4e0 2a 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 22 53  * will return "S
2b4f0 45 4c 45 43 54 20 32 33 34 35 2c 4e 55 4c 4c 22  ELECT 2345,NULL"
2b500 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  .)^.**.** ^The s
2b510 71 6c 69 74 65 33 5f 65 78 70 61 6e 64 65 64 5f  qlite3_expanded_
2b520 73 71 6c 28 29 20 69 6e 74 65 72 66 61 63 65 20  sql() interface 
2b530 72 65 74 75 72 6e 73 20 4e 55 4c 4c 20 69 66 20  returns NULL if 
2b540 69 6e 73 75 66 66 69 63 69 65 6e 74 20 6d 65 6d  insufficient mem
2b550 6f 72 79 0a 2a 2a 20 69 73 20 61 76 61 69 6c 61  ory.** is availa
2b560 62 6c 65 20 74 6f 20 68 6f 6c 64 20 74 68 65 20  ble to hold the 
2b570 72 65 73 75 6c 74 2c 20 6f 72 20 69 66 20 74 68  result, or if th
2b580 65 20 72 65 73 75 6c 74 20 77 6f 75 6c 64 20 65  e result would e
2b590 78 63 65 65 64 20 74 68 65 0a 2a 2a 20 74 68 65  xceed the.** the
2b5a0 20 6d 61 78 69 6d 75 6d 20 73 74 72 69 6e 67 20   maximum string 
2b5b0 6c 65 6e 67 74 68 20 64 65 74 65 72 6d 69 6e 65  length determine
2b5c0 64 20 62 79 20 74 68 65 20 5b 53 51 4c 49 54 45  d by the [SQLITE
2b5d0 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 5d 2e 0a  _LIMIT_LENGTH]..
2b5e0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49  **.** ^The [SQLI
2b5f0 54 45 5f 54 52 41 43 45 5f 53 49 5a 45 5f 4c 49  TE_TRACE_SIZE_LI
2b600 4d 49 54 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  MIT] compile-tim
2b610 65 20 6f 70 74 69 6f 6e 20 6c 69 6d 69 74 73 20  e option limits 
2b620 74 68 65 20 73 69 7a 65 20 6f 66 0a 2a 2a 20 62  the size of.** b
2b630 6f 75 6e 64 20 70 61 72 61 6d 65 74 65 72 20 65  ound parameter e
2b640 78 70 61 6e 73 69 6f 6e 73 2e 20 20 5e 54 68 65  xpansions.  ^The
2b650 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 54 52   [SQLITE_OMIT_TR
2b660 41 43 45 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  ACE] compile-tim
2b670 65 0a 2a 2a 20 6f 70 74 69 6f 6e 20 63 61 75 73  e.** option caus
2b680 65 73 20 73 71 6c 69 74 65 33 5f 65 78 70 61 6e  es sqlite3_expan
2b690 64 65 64 5f 73 71 6c 28 29 20 74 6f 20 61 6c 77  ded_sql() to alw
2b6a0 61 79 73 20 72 65 74 75 72 6e 20 4e 55 4c 4c 2e  ays return NULL.
2b6b0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 74 72 69  .**.** ^The stri
2b6c0 6e 67 20 72 65 74 75 72 6e 65 64 20 62 79 20 73  ng returned by s
2b6d0 71 6c 69 74 65 33 5f 73 71 6c 28 50 29 20 69 73  qlite3_sql(P) is
2b6e0 20 6d 61 6e 61 67 65 64 20 62 79 20 53 51 4c 69   managed by SQLi
2b6f0 74 65 20 61 6e 64 20 69 73 0a 2a 2a 20 61 75 74  te and is.** aut
2b700 6f 6d 61 74 69 63 61 6c 6c 79 20 66 72 65 65 64  omatically freed
2b710 20 77 68 65 6e 20 74 68 65 20 70 72 65 70 61 72   when the prepar
2b720 65 64 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  ed statement is 
2b730 66 69 6e 61 6c 69 7a 65 64 2e 0a 2a 2a 20 5e 54  finalized..** ^T
2b740 68 65 20 73 74 72 69 6e 67 20 72 65 74 75 72 6e  he string return
2b750 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 65 78  ed by sqlite3_ex
2b760 70 61 6e 64 65 64 5f 73 71 6c 28 50 29 2c 20 6f  panded_sql(P), o
2b770 6e 20 74 68 65 20 6f 74 68 65 72 20 68 61 6e 64  n the other hand
2b780 2c 0a 2a 2a 20 69 73 20 6f 62 74 61 69 6e 65 64  ,.** is obtained
2b790 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d   from [sqlite3_m
2b7a0 61 6c 6c 6f 63 28 29 5d 20 61 6e 64 20 6d 75 73  alloc()] and mus
2b7b0 74 20 62 65 20 66 72 65 65 20 62 79 20 74 68 65  t be free by the
2b7c0 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20   application.** 
2b7d0 62 79 20 70 61 73 73 69 6e 67 20 69 74 20 74 6f  by passing it to
2b7e0 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
2b7f0 5d 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72  ]..*/.const char
2b800 20 2a 73 71 6c 69 74 65 33 5f 73 71 6c 28 73 71   *sqlite3_sql(sq
2b810 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d  lite3_stmt *pStm
2b820 74 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74 65  t);.char *sqlite
2b830 33 5f 65 78 70 61 6e 64 65 64 5f 73 71 6c 28 73  3_expanded_sql(s
2b840 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74  qlite3_stmt *pSt
2b850 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  mt);../*.** CAPI
2b860 33 52 45 46 3a 20 44 65 74 65 72 6d 69 6e 65 20  3REF: Determine 
2b870 49 66 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d  If An SQL Statem
2b880 65 6e 74 20 57 72 69 74 65 73 20 54 68 65 20 44  ent Writes The D
2b890 61 74 61 62 61 73 65 0a 2a 2a 20 4d 45 54 48 4f  atabase.** METHO
2b8a0 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a  D: sqlite3_stmt.
2b8b0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
2b8c0 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79  e3_stmt_readonly
2b8d0 28 58 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  (X) interface re
2b8e0 74 75 72 6e 73 20 74 72 75 65 20 28 6e 6f 6e 2d  turns true (non-
2b8f0 7a 65 72 6f 29 20 69 66 0a 2a 2a 20 61 6e 64 20  zero) if.** and 
2b900 6f 6e 6c 79 20 69 66 20 74 68 65 20 5b 70 72 65  only if the [pre
2b910 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2b920 20 58 20 6d 61 6b 65 73 20 6e 6f 20 64 69 72 65   X makes no dire
2b930 63 74 20 63 68 61 6e 67 65 73 20 74 6f 0a 2a 2a  ct changes to.**
2b940 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20   the content of 
2b950 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
2b960 65 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68  e..**.** Note th
2b970 61 74 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d  at [application-
2b980 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63  defined SQL func
2b990 74 69 6f 6e 73 5d 20 6f 72 0a 2a 2a 20 5b 76 69  tions] or.** [vi
2b9a0 72 74 75 61 6c 20 74 61 62 6c 65 73 5d 20 6d 69  rtual tables] mi
2b9b0 67 68 74 20 63 68 61 6e 67 65 20 74 68 65 20 64  ght change the d
2b9c0 61 74 61 62 61 73 65 20 69 6e 64 69 72 65 63 74  atabase indirect
2b9d0 6c 79 20 61 73 20 61 20 73 69 64 65 20 65 66 66  ly as a side eff
2b9e0 65 63 74 2e 20 20 0a 2a 2a 20 5e 28 46 6f 72 20  ect.  .** ^(For 
2b9f0 65 78 61 6d 70 6c 65 2c 20 69 66 20 61 6e 20 61  example, if an a
2ba00 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 6e  pplication defin
2ba10 65 73 20 61 20 66 75 6e 63 74 69 6f 6e 20 22 65  es a function "e
2ba20 76 61 6c 28 29 22 20 74 68 61 74 20 0a 2a 2a 20  val()" that .** 
2ba30 63 61 6c 6c 73 20 5b 73 71 6c 69 74 65 33 5f 65  calls [sqlite3_e
2ba40 78 65 63 28 29 5d 2c 20 74 68 65 6e 20 74 68 65  xec()], then the
2ba50 20 66 6f 6c 6c 6f 77 69 6e 67 20 53 51 4c 20 73   following SQL s
2ba60 74 61 74 65 6d 65 6e 74 20 77 6f 75 6c 64 0a 2a  tatement would.*
2ba70 2a 20 63 68 61 6e 67 65 20 74 68 65 20 64 61 74  * change the dat
2ba80 61 62 61 73 65 20 66 69 6c 65 20 74 68 72 6f 75  abase file throu
2ba90 67 68 20 73 69 64 65 2d 65 66 66 65 63 74 73 3a  gh side-effects:
2baa0 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f  .**.** <blockquo
2bab0 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 53  te><pre>.**    S
2bac0 45 4c 45 43 54 20 65 76 61 6c 28 27 44 45 4c 45  ELECT eval('DELE
2bad0 54 45 20 46 52 4f 4d 20 74 31 27 29 20 46 52 4f  TE FROM t1') FRO
2bae0 4d 20 74 32 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c  M t2;.** </pre><
2baf0 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a  /blockquote>.**.
2bb00 2a 2a 20 42 75 74 20 62 65 63 61 75 73 65 20 74  ** But because t
2bb10 68 65 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74  he [SELECT] stat
2bb20 65 6d 65 6e 74 20 64 6f 65 73 20 6e 6f 74 20 63  ement does not c
2bb30 68 61 6e 67 65 20 74 68 65 20 64 61 74 61 62 61  hange the databa
2bb40 73 65 20 66 69 6c 65 0a 2a 2a 20 64 69 72 65 63  se file.** direc
2bb50 74 6c 79 2c 20 73 71 6c 69 74 65 33 5f 73 74 6d  tly, sqlite3_stm
2bb60 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20 77 6f 75  t_readonly() wou
2bb70 6c 64 20 73 74 69 6c 6c 20 72 65 74 75 72 6e 20  ld still return 
2bb80 74 72 75 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54  true.)^.**.** ^T
2bb90 72 61 6e 73 61 63 74 69 6f 6e 20 63 6f 6e 74 72  ransaction contr
2bba0 6f 6c 20 73 74 61 74 65 6d 65 6e 74 73 20 73 75  ol statements su
2bbb0 63 68 20 61 73 20 5b 42 45 47 49 4e 5d 2c 20 5b  ch as [BEGIN], [
2bbc0 43 4f 4d 4d 49 54 5d 2c 20 5b 52 4f 4c 4c 42 41  COMMIT], [ROLLBA
2bbd0 43 4b 5d 2c 0a 2a 2a 20 5b 53 41 56 45 50 4f 49  CK],.** [SAVEPOI
2bbe0 4e 54 5d 2c 20 61 6e 64 20 5b 52 45 4c 45 41 53  NT], and [RELEAS
2bbf0 45 5d 20 63 61 75 73 65 20 73 71 6c 69 74 65 33  E] cause sqlite3
2bc00 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29  _stmt_readonly()
2bc10 20 74 6f 20 72 65 74 75 72 6e 20 74 72 75 65 2c   to return true,
2bc20 0a 2a 2a 20 73 69 6e 63 65 20 74 68 65 20 73 74  .** since the st
2bc30 61 74 65 6d 65 6e 74 73 20 74 68 65 6d 73 65 6c  atements themsel
2bc40 76 65 73 20 64 6f 20 6e 6f 74 20 61 63 74 75 61  ves do not actua
2bc50 6c 6c 79 20 6d 6f 64 69 66 79 20 74 68 65 20 64  lly modify the d
2bc60 61 74 61 62 61 73 65 20 62 75 74 0a 2a 2a 20 72  atabase but.** r
2bc70 61 74 68 65 72 20 74 68 65 79 20 63 6f 6e 74 72  ather they contr
2bc80 6f 6c 20 74 68 65 20 74 69 6d 69 6e 67 20 6f 66  ol the timing of
2bc90 20 77 68 65 6e 20 6f 74 68 65 72 20 73 74 61 74   when other stat
2bca0 65 6d 65 6e 74 73 20 6d 6f 64 69 66 79 20 74 68  ements modify th
2bcb0 65 20 0a 2a 2a 20 64 61 74 61 62 61 73 65 2e 20  e .** database. 
2bcc0 20 5e 54 68 65 20 5b 41 54 54 41 43 48 5d 20 61   ^The [ATTACH] a
2bcd0 6e 64 20 5b 44 45 54 41 43 48 5d 20 73 74 61 74  nd [DETACH] stat
2bce0 65 6d 65 6e 74 73 20 61 6c 73 6f 20 63 61 75 73  ements also caus
2bcf0 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 6d  e.** sqlite3_stm
2bd00 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20 74 6f 20  t_readonly() to 
2bd10 72 65 74 75 72 6e 20 74 72 75 65 20 73 69 6e 63  return true sinc
2bd20 65 2c 20 77 68 69 6c 65 20 74 68 6f 73 65 20 73  e, while those s
2bd30 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 63 68 61  tatements.** cha
2bd40 6e 67 65 20 74 68 65 20 63 6f 6e 66 69 67 75 72  nge the configur
2bd50 61 74 69 6f 6e 20 6f 66 20 61 20 64 61 74 61 62  ation of a datab
2bd60 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 20  ase connection, 
2bd70 74 68 65 79 20 64 6f 20 6e 6f 74 20 6d 61 6b 65  they do not make
2bd80 20 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f 20   .** changes to 
2bd90 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74  the content of t
2bda0 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
2bdb0 73 20 6f 6e 20 64 69 73 6b 2e 0a 2a 2a 20 5e 54  s on disk..** ^T
2bdc0 68 65 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f  he sqlite3_stmt_
2bdd0 72 65 61 64 6f 6e 6c 79 28 29 20 69 6e 74 65 72  readonly() inter
2bde0 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 72 75  face returns tru
2bdf0 65 20 66 6f 72 20 5b 42 45 47 49 4e 5d 20 73 69  e for [BEGIN] si
2be00 6e 63 65 0a 2a 2a 20 5b 42 45 47 49 4e 5d 20 6d  nce.** [BEGIN] m
2be10 65 72 65 6c 79 20 73 65 74 73 20 69 6e 74 65 72  erely sets inter
2be20 6e 61 6c 20 66 6c 61 67 73 2c 20 62 75 74 20 74  nal flags, but t
2be30 68 65 20 5b 42 45 47 49 4e 7c 42 45 47 49 4e 20  he [BEGIN|BEGIN 
2be40 49 4d 4d 45 44 49 41 54 45 5d 20 61 6e 64 0a 2a  IMMEDIATE] and.*
2be50 2a 20 5b 42 45 47 49 4e 7c 42 45 47 49 4e 20 45  * [BEGIN|BEGIN E
2be60 58 43 4c 55 53 49 56 45 5d 20 63 6f 6d 6d 61 6e  XCLUSIVE] comman
2be70 64 73 20 64 6f 20 74 6f 75 63 68 20 74 68 65 20  ds do touch the 
2be80 64 61 74 61 62 61 73 65 20 61 6e 64 20 73 6f 0a  database and so.
2be90 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f  ** sqlite3_stmt_
2bea0 72 65 61 64 6f 6e 6c 79 28 29 20 72 65 74 75 72  readonly() retur
2beb0 6e 73 20 66 61 6c 73 65 20 66 6f 72 20 74 68 6f  ns false for tho
2bec0 73 65 20 63 6f 6d 6d 61 6e 64 73 2e 0a 2a 2f 0a  se commands..*/.
2bed0 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  int sqlite3_stmt
2bee0 5f 72 65 61 64 6f 6e 6c 79 28 73 71 6c 69 74 65  _readonly(sqlite
2bef0 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a  3_stmt *pStmt);.
2bf00 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2bf10 20 44 65 74 65 72 6d 69 6e 65 20 49 66 20 41 20   Determine If A 
2bf20 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65  Prepared Stateme
2bf30 6e 74 20 48 61 73 20 42 65 65 6e 20 52 65 73 65  nt Has Been Rese
2bf40 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  t.** METHOD: sql
2bf50 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20  ite3_stmt.**.** 
2bf60 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 74 6d  ^The sqlite3_stm
2bf70 74 5f 62 75 73 79 28 53 29 20 69 6e 74 65 72 66  t_busy(S) interf
2bf80 61 63 65 20 72 65 74 75 72 6e 73 20 74 72 75 65  ace returns true
2bf90 20 28 6e 6f 6e 2d 7a 65 72 6f 29 20 69 66 20 74   (non-zero) if t
2bfa0 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20  he.** [prepared 
2bfb0 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 68 61 73  statement] S has
2bfc0 20 62 65 65 6e 20 73 74 65 70 70 65 64 20 61 74   been stepped at
2bfd0 20 6c 65 61 73 74 20 6f 6e 63 65 20 75 73 69 6e   least once usin
2bfe0 67 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73  g .** [sqlite3_s
2bff0 74 65 70 28 53 29 5d 20 62 75 74 20 68 61 73 20  tep(S)] but has 
2c000 6e 65 69 74 68 65 72 20 72 75 6e 20 74 6f 20 63  neither run to c
2c010 6f 6d 70 6c 65 74 69 6f 6e 20 28 72 65 74 75 72  ompletion (retur
2c020 6e 65 64 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44  ned.** [SQLITE_D
2c030 4f 4e 45 5d 20 66 72 6f 6d 20 5b 73 71 6c 69 74  ONE] from [sqlit
2c040 65 33 5f 73 74 65 70 28 53 29 5d 29 20 6e 6f 72  e3_step(S)]) nor
2c050 0a 2a 2a 20 62 65 65 6e 20 72 65 73 65 74 20 75  .** been reset u
2c060 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65  sing [sqlite3_re
2c070 73 65 74 28 53 29 5d 2e 20 20 5e 54 68 65 20 73  set(S)].  ^The s
2c080 71 6c 69 74 65 33 5f 73 74 6d 74 5f 62 75 73 79  qlite3_stmt_busy
2c090 28 53 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  (S).** interface
2c0a0 20 72 65 74 75 72 6e 73 20 66 61 6c 73 65 20 69   returns false i
2c0b0 66 20 53 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  f S is a NULL po
2c0c0 69 6e 74 65 72 2e 20 20 49 66 20 53 20 69 73 20  inter.  If S is 
2c0d0 6e 6f 74 20 61 20 0a 2a 2a 20 4e 55 4c 4c 20 70  not a .** NULL p
2c0e0 6f 69 6e 74 65 72 20 61 6e 64 20 69 73 20 6e 6f  ointer and is no
2c0f0 74 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  t a pointer to a
2c100 20 76 61 6c 69 64 20 5b 70 72 65 70 61 72 65 64   valid [prepared
2c110 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f   statement].** o
2c120 62 6a 65 63 74 2c 20 74 68 65 6e 20 74 68 65 20  bject, then the 
2c130 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65  behavior is unde
2c140 66 69 6e 65 64 20 61 6e 64 20 70 72 6f 62 61 62  fined and probab
2c150 6c 79 20 75 6e 64 65 73 69 72 61 62 6c 65 2e 0a  ly undesirable..
2c160 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72  **.** This inter
2c170 66 61 63 65 20 63 61 6e 20 62 65 20 75 73 65 64  face can be used
2c180 20 69 6e 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20   in combination 
2c190 5b 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73 74  [sqlite3_next_st
2c1a0 6d 74 28 29 5d 0a 2a 2a 20 74 6f 20 6c 6f 63 61  mt()].** to loca
2c1b0 74 65 20 61 6c 6c 20 70 72 65 70 61 72 65 64 20  te all prepared 
2c1c0 73 74 61 74 65 6d 65 6e 74 73 20 61 73 73 6f 63  statements assoc
2c1d0 69 61 74 65 64 20 77 69 74 68 20 61 20 64 61 74  iated with a dat
2c1e0 61 62 61 73 65 20 0a 2a 2a 20 63 6f 6e 6e 65 63  abase .** connec
2c1f0 74 69 6f 6e 20 74 68 61 74 20 61 72 65 20 69 6e  tion that are in
2c200 20 6e 65 65 64 20 6f 66 20 62 65 69 6e 67 20 72   need of being r
2c210 65 73 65 74 2e 20 20 54 68 69 73 20 63 61 6e 20  eset.  This can 
2c220 62 65 20 75 73 65 64 2c 0a 2a 2a 20 66 6f 72 20  be used,.** for 
2c230 65 78 61 6d 70 6c 65 2c 20 69 6e 20 64 69 61 67  example, in diag
2c240 6e 6f 73 74 69 63 20 72 6f 75 74 69 6e 65 73 20  nostic routines 
2c250 74 6f 20 73 65 61 72 63 68 20 66 6f 72 20 70 72  to search for pr
2c260 65 70 61 72 65 64 20 0a 2a 2a 20 73 74 61 74 65  epared .** state
2c270 6d 65 6e 74 73 20 74 68 61 74 20 61 72 65 20 68  ments that are h
2c280 6f 6c 64 69 6e 67 20 61 20 74 72 61 6e 73 61 63  olding a transac
2c290 74 69 6f 6e 20 6f 70 65 6e 2e 0a 2a 2f 0a 69 6e  tion open..*/.in
2c2a0 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 62  t sqlite3_stmt_b
2c2b0 75 73 79 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  usy(sqlite3_stmt
2c2c0 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
2c2d0 52 45 46 3a 20 44 79 6e 61 6d 69 63 61 6c 6c 79  REF: Dynamically
2c2e0 20 54 79 70 65 64 20 56 61 6c 75 65 20 4f 62 6a   Typed Value Obj
2c2f0 65 63 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  ect.** KEYWORDS:
2c300 20 7b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69   {protected sqli
2c310 74 65 33 5f 76 61 6c 75 65 7d 20 7b 75 6e 70 72  te3_value} {unpr
2c320 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
2c330 76 61 6c 75 65 7d 0a 2a 2a 0a 2a 2a 20 53 51 4c  value}.**.** SQL
2c340 69 74 65 20 75 73 65 73 20 74 68 65 20 73 71 6c  ite uses the sql
2c350 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
2c360 74 20 74 6f 20 72 65 70 72 65 73 65 6e 74 20 61  t to represent a
2c370 6c 6c 20 76 61 6c 75 65 73 0a 2a 2a 20 74 68 61  ll values.** tha
2c380 74 20 63 61 6e 20 62 65 20 73 74 6f 72 65 64 20  t can be stored 
2c390 69 6e 20 61 20 64 61 74 61 62 61 73 65 20 74 61  in a database ta
2c3a0 62 6c 65 2e 20 53 51 4c 69 74 65 20 75 73 65 73  ble. SQLite uses
2c3b0 20 64 79 6e 61 6d 69 63 20 74 79 70 69 6e 67 0a   dynamic typing.
2c3c0 2a 2a 20 66 6f 72 20 74 68 65 20 76 61 6c 75 65  ** for the value
2c3d0 73 20 69 74 20 73 74 6f 72 65 73 2e 20 20 5e 56  s it stores.  ^V
2c3e0 61 6c 75 65 73 20 73 74 6f 72 65 64 20 69 6e 20  alues stored in 
2c3f0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
2c400 6a 65 63 74 73 0a 2a 2a 20 63 61 6e 20 62 65 20  jects.** can be 
2c410 69 6e 74 65 67 65 72 73 2c 20 66 6c 6f 61 74 69  integers, floati
2c420 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 73 2c  ng point values,
2c430 20 73 74 72 69 6e 67 73 2c 20 42 4c 4f 42 73 2c   strings, BLOBs,
2c440 20 6f 72 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20   or NULL..**.** 
2c450 41 6e 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  An sqlite3_value
2c460 20 6f 62 6a 65 63 74 20 6d 61 79 20 62 65 20 65   object may be e
2c470 69 74 68 65 72 20 22 70 72 6f 74 65 63 74 65 64  ither "protected
2c480 22 20 6f 72 20 22 75 6e 70 72 6f 74 65 63 74 65  " or "unprotecte
2c490 64 22 2e 0a 2a 2a 20 53 6f 6d 65 20 69 6e 74 65  d"..** Some inte
2c4a0 72 66 61 63 65 73 20 72 65 71 75 69 72 65 20 61  rfaces require a
2c4b0 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74   protected sqlit
2c4c0 65 33 5f 76 61 6c 75 65 2e 20 20 4f 74 68 65 72  e3_value.  Other
2c4d0 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 77   interfaces.** w
2c4e0 69 6c 6c 20 61 63 63 65 70 74 20 65 69 74 68 65  ill accept eithe
2c4f0 72 20 61 20 70 72 6f 74 65 63 74 65 64 20 6f 72  r a protected or
2c500 20 61 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 20   an unprotected 
2c510 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 0a 2a  sqlite3_value..*
2c520 2a 20 45 76 65 72 79 20 69 6e 74 65 72 66 61 63  * Every interfac
2c530 65 20 74 68 61 74 20 61 63 63 65 70 74 73 20 73  e that accepts s
2c540 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 61 72 67  qlite3_value arg
2c550 75 6d 65 6e 74 73 20 73 70 65 63 69 66 69 65 73  uments specifies
2c560 0a 2a 2a 20 77 68 65 74 68 65 72 20 6f 72 20 6e  .** whether or n
2c570 6f 74 20 69 74 20 72 65 71 75 69 72 65 73 20 61  ot it requires a
2c580 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74   protected sqlit
2c590 65 33 5f 76 61 6c 75 65 2e 20 20 54 68 65 0a 2a  e3_value.  The.*
2c5a0 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  * [sqlite3_value
2c5b0 5f 64 75 70 28 29 5d 20 69 6e 74 65 72 66 61 63  _dup()] interfac
2c5c0 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  e can be used to
2c5d0 20 63 6f 6e 73 74 72 75 63 74 20 61 20 6e 65 77   construct a new
2c5e0 20 0a 2a 2a 20 70 72 6f 74 65 63 74 65 64 20 73   .** protected s
2c5f0 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 66 72 6f  qlite3_value fro
2c600 6d 20 61 6e 20 75 6e 70 72 6f 74 65 63 74 65 64  m an unprotected
2c610 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 0a   sqlite3_value..
2c620 2a 2a 0a 2a 2a 20 54 68 65 20 74 65 72 6d 73 20  **.** The terms 
2c630 22 70 72 6f 74 65 63 74 65 64 22 20 61 6e 64 20  "protected" and 
2c640 22 75 6e 70 72 6f 74 65 63 74 65 64 22 20 72 65  "unprotected" re
2c650 66 65 72 20 74 6f 20 77 68 65 74 68 65 72 20 6f  fer to whether o
2c660 72 20 6e 6f 74 0a 2a 2a 20 61 20 6d 75 74 65 78  r not.** a mutex
2c670 20 69 73 20 68 65 6c 64 2e 20 20 41 6e 20 69 6e   is held.  An in
2c680 74 65 72 6e 61 6c 20 6d 75 74 65 78 20 69 73 20  ternal mutex is 
2c690 68 65 6c 64 20 66 6f 72 20 61 20 70 72 6f 74 65  held for a prote
2c6a0 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  cted.** sqlite3_
2c6b0 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 62 75 74  value object but
2c6c0 20 6e 6f 20 6d 75 74 65 78 20 69 73 20 68 65 6c   no mutex is hel
2c6d0 64 20 66 6f 72 20 61 6e 20 75 6e 70 72 6f 74 65  d for an unprote
2c6e0 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  cted.** sqlite3_
2c6f0 76 61 6c 75 65 20 6f 62 6a 65 63 74 2e 20 20 49  value object.  I
2c700 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70  f SQLite is comp
2c710 69 6c 65 64 20 74 6f 20 62 65 20 73 69 6e 67 6c  iled to be singl
2c720 65 2d 74 68 72 65 61 64 65 64 0a 2a 2a 20 28 77  e-threaded.** (w
2c730 69 74 68 20 5b 53 51 4c 49 54 45 5f 54 48 52 45  ith [SQLITE_THRE
2c740 41 44 53 41 46 45 3d 30 5d 20 61 6e 64 20 77 69  ADSAFE=0] and wi
2c750 74 68 20 5b 73 71 6c 69 74 65 33 5f 74 68 72 65  th [sqlite3_thre
2c760 61 64 73 61 66 65 28 29 5d 20 72 65 74 75 72 6e  adsafe()] return
2c770 69 6e 67 20 30 29 0a 2a 2a 20 6f 72 20 69 66 20  ing 0).** or if 
2c780 53 51 4c 69 74 65 20 69 73 20 72 75 6e 20 69 6e  SQLite is run in
2c790 20 6f 6e 65 20 6f 66 20 72 65 64 75 63 65 64 20   one of reduced 
2c7a0 6d 75 74 65 78 20 6d 6f 64 65 73 20 0a 2a 2a 20  mutex modes .** 
2c7b0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53  [SQLITE_CONFIG_S
2c7c0 49 4e 47 4c 45 54 48 52 45 41 44 5d 20 6f 72 20  INGLETHREAD] or 
2c7d0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
2c7e0 55 4c 54 49 54 48 52 45 41 44 5d 0a 2a 2a 20 74  ULTITHREAD].** t
2c7f0 68 65 6e 20 74 68 65 72 65 20 69 73 20 6e 6f 20  hen there is no 
2c800 64 69 73 74 69 6e 63 74 69 6f 6e 20 62 65 74 77  distinction betw
2c810 65 65 6e 20 70 72 6f 74 65 63 74 65 64 20 61 6e  een protected an
2c820 64 20 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a  d unprotected.**
2c830 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
2c840 62 6a 65 63 74 73 20 61 6e 64 20 74 68 65 79 20  bjects and they 
2c850 63 61 6e 20 62 65 20 75 73 65 64 20 69 6e 74 65  can be used inte
2c860 72 63 68 61 6e 67 65 61 62 6c 79 2e 20 20 48 6f  rchangeably.  Ho
2c870 77 65 76 65 72 2c 0a 2a 2a 20 66 6f 72 20 6d 61  wever,.** for ma
2c880 78 69 6d 75 6d 20 63 6f 64 65 20 70 6f 72 74 61  ximum code porta
2c890 62 69 6c 69 74 79 20 69 74 20 69 73 20 72 65 63  bility it is rec
2c8a0 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 61 70  ommended that ap
2c8b0 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 74  plications.** st
2c8c0 69 6c 6c 20 6d 61 6b 65 20 74 68 65 20 64 69 73  ill make the dis
2c8d0 74 69 6e 63 74 69 6f 6e 20 62 65 74 77 65 65 6e  tinction between
2c8e0 20 70 72 6f 74 65 63 74 65 64 20 61 6e 64 20 75   protected and u
2c8f0 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71  nprotected.** sq
2c900 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
2c910 63 74 73 20 65 76 65 6e 20 77 68 65 6e 20 6e 6f  cts even when no
2c920 74 20 73 74 72 69 63 74 6c 79 20 72 65 71 75 69  t strictly requi
2c930 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  red..**.** ^The 
2c940 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
2c950 6a 65 63 74 73 20 74 68 61 74 20 61 72 65 20 70  jects that are p
2c960 61 73 73 65 64 20 61 73 20 70 61 72 61 6d 65 74  assed as paramet
2c970 65 72 73 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20  ers into the.** 
2c980 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f  implementation o
2c990 66 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  f [application-d
2c9a0 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74  efined SQL funct
2c9b0 69 6f 6e 73 5d 20 61 72 65 20 70 72 6f 74 65 63  ions] are protec
2c9c0 74 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ted..** ^The sql
2c9d0 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
2c9e0 74 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a  t returned by.**
2c9f0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
2ca00 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 75 6e 70  _value()] is unp
2ca10 72 6f 74 65 63 74 65 64 2e 0a 2a 2a 20 55 6e 70  rotected..** Unp
2ca20 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
2ca30 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 6d  _value objects m
2ca40 61 79 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 20  ay only be used 
2ca50 77 69 74 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  with.** [sqlite3
2ca60 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 5d  _result_value()]
2ca70 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 69   and [sqlite3_bi
2ca80 6e 64 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20  nd_value()]..** 
2ca90 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  The [sqlite3_val
2caa0 75 65 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65  ue_blob | sqlite
2cab0 33 5f 76 61 6c 75 65 5f 74 79 70 65 28 29 5d 20  3_value_type()] 
2cac0 66 61 6d 69 6c 79 20 6f 66 0a 2a 2a 20 69 6e 74  family of.** int
2cad0 65 72 66 61 63 65 73 20 72 65 71 75 69 72 65 20  erfaces require 
2cae0 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
2caf0 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 2e  3_value objects.
2cb00 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75  .*/.typedef stru
2cb10 63 74 20 4d 65 6d 20 73 71 6c 69 74 65 33 5f 76  ct Mem sqlite3_v
2cb20 61 6c 75 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  alue;../*.** CAP
2cb30 49 33 52 45 46 3a 20 53 51 4c 20 46 75 6e 63 74  I3REF: SQL Funct
2cb40 69 6f 6e 20 43 6f 6e 74 65 78 74 20 4f 62 6a 65  ion Context Obje
2cb50 63 74 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 6e  ct.**.** The con
2cb60 74 65 78 74 20 69 6e 20 77 68 69 63 68 20 61 6e  text in which an
2cb70 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 65 78   SQL function ex
2cb80 65 63 75 74 65 73 20 69 73 20 73 74 6f 72 65 64  ecutes is stored
2cb90 20 69 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69 74 65   in an.** sqlite
2cba0 33 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65 63 74  3_context object
2cbb0 2e 20 20 5e 41 20 70 6f 69 6e 74 65 72 20 74 6f  .  ^A pointer to
2cbc0 20 61 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74   an sqlite3_cont
2cbd0 65 78 74 20 6f 62 6a 65 63 74 0a 2a 2a 20 69 73  ext object.** is
2cbe0 20 61 6c 77 61 79 73 20 66 69 72 73 74 20 70 61   always first pa
2cbf0 72 61 6d 65 74 65 72 20 74 6f 20 5b 61 70 70 6c  rameter to [appl
2cc00 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
2cc10 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a  SQL functions]..
2cc20 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  ** The applicati
2cc30 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66  on-defined SQL f
2cc40 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e  unction implemen
2cc50 74 61 74 69 6f 6e 20 77 69 6c 6c 20 70 61 73 73  tation will pass
2cc60 20 74 68 69 73 0a 2a 2a 20 70 6f 69 6e 74 65 72   this.** pointer
2cc70 20 74 68 72 6f 75 67 68 20 69 6e 74 6f 20 63 61   through into ca
2cc80 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  lls to [sqlite3_
2cc90 72 65 73 75 6c 74 5f 69 6e 74 20 7c 20 73 71 6c  result_int | sql
2cca0 69 74 65 33 5f 72 65 73 75 6c 74 28 29 5d 2c 0a  ite3_result()],.
2ccb0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 61 67 67 72  ** [sqlite3_aggr
2ccc0 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 5d  egate_context()]
2ccd0 2c 20 5b 73 71 6c 69 74 65 33 5f 75 73 65 72 5f  , [sqlite3_user_
2cce0 64 61 74 61 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c  data()],.** [sql
2ccf0 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f  ite3_context_db_
2cd00 68 61 6e 64 6c 65 28 29 5d 2c 20 5b 73 71 6c 69  handle()], [sqli
2cd10 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28  te3_get_auxdata(
2cd20 29 5d 2c 0a 2a 2a 20 61 6e 64 2f 6f 72 20 5b 73  )],.** and/or [s
2cd30 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61  qlite3_set_auxda
2cd40 74 61 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65  ta()]..*/.typede
2cd50 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  f struct sqlite3
2cd60 5f 63 6f 6e 74 65 78 74 20 73 71 6c 69 74 65 33  _context sqlite3
2cd70 5f 63 6f 6e 74 65 78 74 3b 0a 0a 2f 2a 0a 2a 2a  _context;../*.**
2cd80 20 43 41 50 49 33 52 45 46 3a 20 42 69 6e 64 69   CAPI3REF: Bindi
2cd90 6e 67 20 56 61 6c 75 65 73 20 54 6f 20 50 72 65  ng Values To Pre
2cda0 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 73  pared Statements
2cdb0 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 68  .** KEYWORDS: {h
2cdc0 6f 73 74 20 70 61 72 61 6d 65 74 65 72 7d 20 7b  ost parameter} {
2cdd0 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73 7d  host parameters}
2cde0 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72   {host parameter
2cdf0 20 6e 61 6d 65 7d 0a 2a 2a 20 4b 45 59 57 4f 52   name}.** KEYWOR
2ce00 44 53 3a 20 7b 53 51 4c 20 70 61 72 61 6d 65 74  DS: {SQL paramet
2ce10 65 72 7d 20 7b 53 51 4c 20 70 61 72 61 6d 65 74  er} {SQL paramet
2ce20 65 72 73 7d 20 7b 70 61 72 61 6d 65 74 65 72 20  ers} {parameter 
2ce30 62 69 6e 64 69 6e 67 7d 0a 2a 2a 20 4d 45 54 48  binding}.** METH
2ce40 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  OD: sqlite3_stmt
2ce50 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 74 68 65 20  .**.** ^(In the 
2ce60 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 65  SQL statement te
2ce70 78 74 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c  xt input to [sql
2ce80 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
2ce90 29 5d 20 61 6e 64 20 69 74 73 20 76 61 72 69 61  )] and its varia
2cea0 6e 74 73 2c 0a 2a 2a 20 6c 69 74 65 72 61 6c 73  nts,.** literals
2ceb0 20 6d 61 79 20 62 65 20 72 65 70 6c 61 63 65 64   may be replaced
2cec0 20 62 79 20 61 20 5b 70 61 72 61 6d 65 74 65 72   by a [parameter
2ced0 5d 20 74 68 61 74 20 6d 61 74 63 68 65 73 20 6f  ] that matches o
2cee0 6e 65 20 6f 66 20 66 6f 6c 6c 6f 77 69 6e 67 0a  ne of following.
2cef0 2a 2a 20 74 65 6d 70 6c 61 74 65 73 3a 0a 2a 2a  ** templates:.**
2cf00 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
2cf10 20 20 3f 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 4e 4e    ?.** <li>  ?NN
2cf20 4e 0a 2a 2a 20 3c 6c 69 3e 20 20 3a 56 56 56 0a  N.** <li>  :VVV.
2cf30 2a 2a 20 3c 6c 69 3e 20 20 40 56 56 56 0a 2a 2a  ** <li>  @VVV.**
2cf40 20 3c 6c 69 3e 20 20 24 56 56 56 0a 2a 2a 20 3c   <li>  $VVV.** <
2cf50 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68  /ul>.**.** In th
2cf60 65 20 74 65 6d 70 6c 61 74 65 73 20 61 62 6f 76  e templates abov
2cf70 65 2c 20 4e 4e 4e 20 72 65 70 72 65 73 65 6e 74  e, NNN represent
2cf80 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6c 69 74  s an integer lit
2cf90 65 72 61 6c 2c 0a 2a 2a 20 61 6e 64 20 56 56 56  eral,.** and VVV
2cfa0 20 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20 61   represents an a
2cfb0 6c 70 68 61 6e 75 6d 65 72 69 63 20 69 64 65 6e  lphanumeric iden
2cfc0 74 69 66 69 65 72 2e 29 5e 20 20 5e 54 68 65 20  tifier.)^  ^The 
2cfd0 76 61 6c 75 65 73 20 6f 66 20 74 68 65 73 65 0a  values of these.
2cfe0 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 20 28 61  ** parameters (a
2cff0 6c 73 6f 20 63 61 6c 6c 65 64 20 22 68 6f 73 74  lso called "host
2d000 20 70 61 72 61 6d 65 74 65 72 20 6e 61 6d 65 73   parameter names
2d010 22 20 6f 72 20 22 53 51 4c 20 70 61 72 61 6d 65  " or "SQL parame
2d020 74 65 72 73 22 29 0a 2a 2a 20 63 61 6e 20 62 65  ters").** can be
2d030 20 73 65 74 20 75 73 69 6e 67 20 74 68 65 20 73   set using the s
2d040 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20  qlite3_bind_*() 
2d050 72 6f 75 74 69 6e 65 73 20 64 65 66 69 6e 65 64  routines defined
2d060 20 68 65 72 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68   here..**.** ^Th
2d070 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
2d080 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f   to the sqlite3_
2d090 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65  bind_*() routine
2d0a0 73 20 69 73 20 61 6c 77 61 79 73 0a 2a 2a 20 61  s is always.** a
2d0b0 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20   pointer to the 
2d0c0 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f  [sqlite3_stmt] o
2d0d0 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20 66  bject returned f
2d0e0 72 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  rom.** [sqlite3_
2d0f0 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72  prepare_v2()] or
2d100 20 69 74 73 20 76 61 72 69 61 6e 74 73 2e 0a 2a   its variants..*
2d110 2a 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64  *.** ^The second
2d120 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65   argument is the
2d130 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20 53 51   index of the SQ
2d140 4c 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 62  L parameter to b
2d150 65 20 73 65 74 2e 0a 2a 2a 20 5e 54 68 65 20 6c  e set..** ^The l
2d160 65 66 74 6d 6f 73 74 20 53 51 4c 20 70 61 72 61  eftmost SQL para
2d170 6d 65 74 65 72 20 68 61 73 20 61 6e 20 69 6e 64  meter has an ind
2d180 65 78 20 6f 66 20 31 2e 20 20 5e 57 68 65 6e 20  ex of 1.  ^When 
2d190 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 64 0a 2a  the same named.*
2d1a0 2a 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20  * SQL parameter 
2d1b0 69 73 20 75 73 65 64 20 6d 6f 72 65 20 74 68 61  is used more tha
2d1c0 6e 20 6f 6e 63 65 2c 20 73 65 63 6f 6e 64 20 61  n once, second a
2d1d0 6e 64 20 73 75 62 73 65 71 75 65 6e 74 0a 2a 2a  nd subsequent.**
2d1e0 20 6f 63 63 75 72 72 65 6e 63 65 73 20 68 61 76   occurrences hav
2d1f0 65 20 74 68 65 20 73 61 6d 65 20 69 6e 64 65 78  e the same index
2d200 20 61 73 20 74 68 65 20 66 69 72 73 74 20 6f 63   as the first oc
2d210 63 75 72 72 65 6e 63 65 2e 0a 2a 2a 20 5e 54 68  currence..** ^Th
2d220 65 20 69 6e 64 65 78 20 66 6f 72 20 6e 61 6d 65  e index for name
2d230 64 20 70 61 72 61 6d 65 74 65 72 73 20 63 61 6e  d parameters can
2d240 20 62 65 20 6c 6f 6f 6b 65 64 20 75 70 20 75 73   be looked up us
2d250 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69  ing the.** [sqli
2d260 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
2d270 65 72 5f 69 6e 64 65 78 28 29 5d 20 41 50 49 20  er_index()] API 
2d280 69 66 20 64 65 73 69 72 65 64 2e 20 20 5e 54 68  if desired.  ^Th
2d290 65 20 69 6e 64 65 78 0a 2a 2a 20 66 6f 72 20 22  e index.** for "
2d2a0 3f 4e 4e 4e 22 20 70 61 72 61 6d 65 74 65 72 73  ?NNN" parameters
2d2b0 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66   is the value of
2d2c0 20 4e 4e 4e 2e 0a 2a 2a 20 5e 54 68 65 20 4e 4e   NNN..** ^The NN
2d2d0 4e 20 76 61 6c 75 65 20 6d 75 73 74 20 62 65 20  N value must be 
2d2e0 62 65 74 77 65 65 6e 20 31 20 61 6e 64 20 74 68  between 1 and th
2d2f0 65 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74  e [sqlite3_limit
2d300 28 29 5d 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  ()].** parameter
2d310 20 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56   [SQLITE_LIMIT_V
2d320 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 5d 20  ARIABLE_NUMBER] 
2d330 28 64 65 66 61 75 6c 74 20 76 61 6c 75 65 3a 20  (default value: 
2d340 39 39 39 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  999)..**.** ^The
2d350 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20   third argument 
2d360 69 73 20 74 68 65 20 76 61 6c 75 65 20 74 6f 20  is the value to 
2d370 62 69 6e 64 20 74 6f 20 74 68 65 20 70 61 72 61  bind to the para
2d380 6d 65 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 74 68  meter..** ^If th
2d390 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  e third paramete
2d3a0 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e  r to sqlite3_bin
2d3b0 64 5f 74 65 78 74 28 29 20 6f 72 20 73 71 6c 69  d_text() or sqli
2d3c0 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28  te3_bind_text16(
2d3d0 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f  ).** or sqlite3_
2d3e0 62 69 6e 64 5f 62 6c 6f 62 28 29 20 69 73 20 61  bind_blob() is a
2d3f0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68   NULL pointer th
2d400 65 6e 20 74 68 65 20 66 6f 75 72 74 68 20 70 61  en the fourth pa
2d410 72 61 6d 65 74 65 72 0a 2a 2a 20 69 73 20 69 67  rameter.** is ig
2d420 6e 6f 72 65 64 20 61 6e 64 20 74 68 65 20 65 6e  nored and the en
2d430 64 20 72 65 73 75 6c 74 20 69 73 20 74 68 65 20  d result is the 
2d440 73 61 6d 65 20 61 73 20 73 71 6c 69 74 65 33 5f  same as sqlite3_
2d450 62 69 6e 64 5f 6e 75 6c 6c 28 29 2e 0a 2a 2a 0a  bind_null()..**.
2d460 2a 2a 20 5e 28 49 6e 20 74 68 6f 73 65 20 72 6f  ** ^(In those ro
2d470 75 74 69 6e 65 73 20 74 68 61 74 20 68 61 76 65  utines that have
2d480 20 61 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65   a fourth argume
2d490 6e 74 2c 20 69 74 73 20 76 61 6c 75 65 20 69 73  nt, its value is
2d4a0 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f   the.** number o
2d4b0 66 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 70  f bytes in the p
2d4c0 61 72 61 6d 65 74 65 72 2e 20 20 54 6f 20 62 65  arameter.  To be
2d4d0 20 63 6c 65 61 72 3a 20 74 68 65 20 76 61 6c 75   clear: the valu
2d4e0 65 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62  e is the.** numb
2d4f0 65 72 20 6f 66 20 3c 75 3e 62 79 74 65 73 3c 2f  er of <u>bytes</
2d500 75 3e 20 69 6e 20 74 68 65 20 76 61 6c 75 65 2c  u> in the value,
2d510 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62 65 72 20   not the number 
2d520 6f 66 20 63 68 61 72 61 63 74 65 72 73 2e 29 5e  of characters.)^
2d530 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 6f 75 72  .** ^If the four
2d540 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
2d550 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
2d560 74 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 62  t() or sqlite3_b
2d570 69 6e 64 5f 74 65 78 74 31 36 28 29 0a 2a 2a 20  ind_text16().** 
2d580 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65  is negative, the
2d590 6e 20 74 68 65 20 6c 65 6e 67 74 68 20 6f 66 20  n the length of 
2d5a0 74 68 65 20 73 74 72 69 6e 67 20 69 73 0a 2a 2a  the string is.**
2d5b0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62   the number of b
2d5c0 79 74 65 73 20 75 70 20 74 6f 20 74 68 65 20 66  ytes up to the f
2d5d0 69 72 73 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e  irst zero termin
2d5e0 61 74 6f 72 2e 0a 2a 2a 20 49 66 20 74 68 65 20  ator..** If the 
2d5f0 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
2d600 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64   to sqlite3_bind
2d610 5f 62 6c 6f 62 28 29 20 69 73 20 6e 65 67 61 74  _blob() is negat
2d620 69 76 65 2c 20 74 68 65 6e 0a 2a 2a 20 74 68 65  ive, then.** the
2d630 20 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64   behavior is und
2d640 65 66 69 6e 65 64 2e 0a 2a 2a 20 49 66 20 61 20  efined..** If a 
2d650 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 20 66 6f 75  non-negative fou
2d660 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73  rth parameter is
2d670 20 70 72 6f 76 69 64 65 64 20 74 6f 20 73 71 6c   provided to sql
2d680 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 29  ite3_bind_text()
2d690 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 62  .** or sqlite3_b
2d6a0 69 6e 64 5f 74 65 78 74 31 36 28 29 20 6f 72 20  ind_text16() or 
2d6b0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
2d6c0 74 36 34 28 29 20 74 68 65 6e 0a 2a 2a 20 74 68  t64() then.** th
2d6d0 61 74 20 70 61 72 61 6d 65 74 65 72 20 6d 75 73  at parameter mus
2d6e0 74 20 62 65 20 74 68 65 20 62 79 74 65 20 6f 66  t be the byte of
2d6f0 66 73 65 74 0a 2a 2a 20 77 68 65 72 65 20 74 68  fset.** where th
2d700 65 20 4e 55 4c 20 74 65 72 6d 69 6e 61 74 6f 72  e NUL terminator
2d710 20 77 6f 75 6c 64 20 6f 63 63 75 72 20 61 73 73   would occur ass
2d720 75 6d 69 6e 67 20 74 68 65 20 73 74 72 69 6e 67  uming the string
2d730 20 77 65 72 65 20 4e 55 4c 0a 2a 2a 20 74 65 72   were NUL.** ter
2d740 6d 69 6e 61 74 65 64 2e 20 20 49 66 20 61 6e 79  minated.  If any
2d750 20 4e 55 4c 20 63 68 61 72 61 63 74 65 72 73 20   NUL characters 
2d760 6f 63 63 75 72 20 61 74 20 62 79 74 65 20 6f 66  occur at byte of
2d770 66 73 65 74 73 20 6c 65 73 73 20 74 68 61 6e 20  fsets less than 
2d780 0a 2a 2a 20 74 68 65 20 76 61 6c 75 65 20 6f 66  .** the value of
2d790 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61   the fourth para
2d7a0 6d 65 74 65 72 20 74 68 65 6e 20 74 68 65 20 72  meter then the r
2d7b0 65 73 75 6c 74 69 6e 67 20 73 74 72 69 6e 67 20  esulting string 
2d7c0 76 61 6c 75 65 20 77 69 6c 6c 0a 2a 2a 20 63 6f  value will.** co
2d7d0 6e 74 61 69 6e 20 65 6d 62 65 64 64 65 64 20 4e  ntain embedded N
2d7e0 55 4c 73 2e 20 20 54 68 65 20 72 65 73 75 6c 74  ULs.  The result
2d7f0 20 6f 66 20 65 78 70 72 65 73 73 69 6f 6e 73 20   of expressions 
2d800 69 6e 76 6f 6c 76 69 6e 67 20 73 74 72 69 6e 67  involving string
2d810 73 0a 2a 2a 20 77 69 74 68 20 65 6d 62 65 64 64  s.** with embedd
2d820 65 64 20 4e 55 4c 73 20 69 73 20 75 6e 64 65 66  ed NULs is undef
2d830 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ined..**.** ^The
2d840 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20   fifth argument 
2d850 74 6f 20 74 68 65 20 42 4c 4f 42 20 61 6e 64 20  to the BLOB and 
2d860 73 74 72 69 6e 67 20 62 69 6e 64 69 6e 67 20 69  string binding i
2d870 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 69 73 20  nterfaces.** is 
2d880 61 20 64 65 73 74 72 75 63 74 6f 72 20 75 73 65  a destructor use
2d890 64 20 74 6f 20 64 69 73 70 6f 73 65 20 6f 66 20  d to dispose of 
2d8a0 74 68 65 20 42 4c 4f 42 20 6f 72 0a 2a 2a 20 73  the BLOB or.** s
2d8b0 74 72 69 6e 67 20 61 66 74 65 72 20 53 51 4c 69  tring after SQLi
2d8c0 74 65 20 68 61 73 20 66 69 6e 69 73 68 65 64 20  te has finished 
2d8d0 77 69 74 68 20 69 74 2e 20 20 5e 54 68 65 20 64  with it.  ^The d
2d8e0 65 73 74 72 75 63 74 6f 72 20 69 73 20 63 61 6c  estructor is cal
2d8f0 6c 65 64 0a 2a 2a 20 74 6f 20 64 69 73 70 6f 73  led.** to dispos
2d900 65 20 6f 66 20 74 68 65 20 42 4c 4f 42 20 6f 72  e of the BLOB or
2d910 20 73 74 72 69 6e 67 20 65 76 65 6e 20 69 66 20   string even if 
2d920 74 68 65 20 63 61 6c 6c 20 74 6f 20 62 69 6e 64  the call to bind
2d930 20 41 50 49 20 66 61 69 6c 73 2e 0a 2a 2a 20 5e   API fails..** ^
2d940 49 66 20 74 68 65 20 66 69 66 74 68 20 61 72 67  If the fifth arg
2d950 75 6d 65 6e 74 20 69 73 0a 2a 2a 20 74 68 65 20  ument is.** the 
2d960 73 70 65 63 69 61 6c 20 76 61 6c 75 65 20 5b 53  special value [S
2d970 51 4c 49 54 45 5f 53 54 41 54 49 43 5d 2c 20 74  QLITE_STATIC], t
2d980 68 65 6e 20 53 51 4c 69 74 65 20 61 73 73 75 6d  hen SQLite assum
2d990 65 73 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 69  es that the.** i
2d9a0 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 69 6e  nformation is in
2d9b0 20 73 74 61 74 69 63 2c 20 75 6e 6d 61 6e 61 67   static, unmanag
2d9c0 65 64 20 73 70 61 63 65 20 61 6e 64 20 64 6f 65  ed space and doe
2d9d0 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65  s not need to be
2d9e0 20 66 72 65 65 64 2e 0a 2a 2a 20 5e 49 66 20 74   freed..** ^If t
2d9f0 68 65 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e  he fifth argumen
2da00 74 20 68 61 73 20 74 68 65 20 76 61 6c 75 65 20  t has the value 
2da10 5b 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e  [SQLITE_TRANSIEN
2da20 54 5d 2c 20 74 68 65 6e 0a 2a 2a 20 53 51 4c 69  T], then.** SQLi
2da30 74 65 20 6d 61 6b 65 73 20 69 74 73 20 6f 77 6e  te makes its own
2da40 20 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66   private copy of
2da50 20 74 68 65 20 64 61 74 61 20 69 6d 6d 65 64 69   the data immedi
2da60 61 74 65 6c 79 2c 20 62 65 66 6f 72 65 0a 2a 2a  ately, before.**
2da70 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e   the sqlite3_bin
2da80 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 20 72 65  d_*() routine re
2da90 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  turns..**.** ^Th
2daa0 65 20 73 69 78 74 68 20 61 72 67 75 6d 65 6e 74  e sixth argument
2dab0 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64   to sqlite3_bind
2dac0 5f 74 65 78 74 36 34 28 29 20 6d 75 73 74 20 62  _text64() must b
2dad0 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 5b 53 51 4c  e one of.** [SQL
2dae0 49 54 45 5f 55 54 46 38 5d 2c 20 5b 53 51 4c 49  ITE_UTF8], [SQLI
2daf0 54 45 5f 55 54 46 31 36 5d 2c 20 5b 53 51 4c 49  TE_UTF16], [SQLI
2db00 54 45 5f 55 54 46 31 36 42 45 5d 2c 20 6f 72 20  TE_UTF16BE], or 
2db10 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d  [SQLITE_UTF16LE]
2db20 0a 2a 2a 20 74 6f 20 73 70 65 63 69 66 79 20 74  .** to specify t
2db30 68 65 20 65 6e 63 6f 64 69 6e 67 20 6f 66 20 74  he encoding of t
2db40 68 65 20 74 65 78 74 20 69 6e 20 74 68 65 20 74  he text in the t
2db50 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 2e 20  hird parameter. 
2db60 20 49 66 0a 2a 2a 20 74 68 65 20 73 69 78 74 68   If.** the sixth
2db70 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c   argument to sql
2db80 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 36 34  ite3_bind_text64
2db90 28 29 20 69 73 20 6e 6f 74 20 6f 6e 65 20 6f 66  () is not one of
2dba0 20 74 68 65 0a 2a 2a 20 61 6c 6c 6f 77 65 64 20   the.** allowed 
2dbb0 76 61 6c 75 65 73 20 73 68 6f 77 6e 20 61 62 6f  values shown abo
2dbc0 76 65 2c 20 6f 72 20 69 66 20 74 68 65 20 74 65  ve, or if the te
2dbd0 78 74 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 64  xt encoding is d
2dbe0 69 66 66 65 72 65 6e 74 0a 2a 2a 20 66 72 6f 6d  ifferent.** from
2dbf0 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 73 70   the encoding sp
2dc00 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20 73  ecified by the s
2dc10 69 78 74 68 20 70 61 72 61 6d 65 74 65 72 2c 20  ixth parameter, 
2dc20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f  then the behavio
2dc30 72 0a 2a 2a 20 69 73 20 75 6e 64 65 66 69 6e 65  r.** is undefine
2dc40 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  d..**.** ^The sq
2dc50 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62  lite3_bind_zerob
2dc60 6c 6f 62 28 29 20 72 6f 75 74 69 6e 65 20 62 69  lob() routine bi
2dc70 6e 64 73 20 61 20 42 4c 4f 42 20 6f 66 20 6c 65  nds a BLOB of le
2dc80 6e 67 74 68 20 4e 20 74 68 61 74 0a 2a 2a 20 69  ngth N that.** i
2dc90 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20 7a 65  s filled with ze
2dca0 72 6f 65 73 2e 20 20 5e 41 20 7a 65 72 6f 62 6c  roes.  ^A zerobl
2dcb0 6f 62 20 75 73 65 73 20 61 20 66 69 78 65 64 20  ob uses a fixed 
2dcc0 61 6d 6f 75 6e 74 20 6f 66 20 6d 65 6d 6f 72 79  amount of memory
2dcd0 0a 2a 2a 20 28 6a 75 73 74 20 61 6e 20 69 6e 74  .** (just an int
2dce0 65 67 65 72 20 74 6f 20 68 6f 6c 64 20 69 74 73  eger to hold its
2dcf0 20 73 69 7a 65 29 20 77 68 69 6c 65 20 69 74 20   size) while it 
2dd00 69 73 20 62 65 69 6e 67 20 70 72 6f 63 65 73 73  is being process
2dd10 65 64 2e 0a 2a 2a 20 5a 65 72 6f 62 6c 6f 62 73  ed..** Zeroblobs
2dd20 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20 74 6f   are intended to
2dd30 20 73 65 72 76 65 20 61 73 20 70 6c 61 63 65 68   serve as placeh
2dd40 6f 6c 64 65 72 73 20 66 6f 72 20 42 4c 4f 42 73  olders for BLOBs
2dd50 20 77 68 6f 73 65 0a 2a 2a 20 63 6f 6e 74 65 6e   whose.** conten
2dd60 74 20 69 73 20 6c 61 74 65 72 20 77 72 69 74 74  t is later writt
2dd70 65 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c  en using.** [sql
2dd80 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 20 7c  ite3_blob_open |
2dd90 20 69 6e 63 72 65 6d 65 6e 74 61 6c 20 42 4c 4f   incremental BLO
2dda0 42 20 49 2f 4f 5d 20 72 6f 75 74 69 6e 65 73 2e  B I/O] routines.
2ddb0 0a 2a 2a 20 5e 41 20 6e 65 67 61 74 69 76 65 20  .** ^A negative 
2ddc0 76 61 6c 75 65 20 66 6f 72 20 74 68 65 20 7a 65  value for the ze
2ddd0 72 6f 62 6c 6f 62 20 72 65 73 75 6c 74 73 20 69  roblob results i
2dde0 6e 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20  n a zero-length 
2ddf0 42 4c 4f 42 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  BLOB..**.** ^If 
2de00 61 6e 79 20 6f 66 20 74 68 65 20 73 71 6c 69 74  any of the sqlit
2de10 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74  e3_bind_*() rout
2de20 69 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20  ines are called 
2de30 77 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  with a NULL poin
2de40 74 65 72 0a 2a 2a 20 66 6f 72 20 74 68 65 20 5b  ter.** for the [
2de50 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2de60 6e 74 5d 20 6f 72 20 77 69 74 68 20 61 20 70 72  nt] or with a pr
2de70 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2de80 20 66 6f 72 20 77 68 69 63 68 0a 2a 2a 20 5b 73   for which.** [s
2de90 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 68  qlite3_step()] h
2dea0 61 73 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 6d  as been called m
2deb0 6f 72 65 20 72 65 63 65 6e 74 6c 79 20 74 68 61  ore recently tha
2dec0 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  n [sqlite3_reset
2ded0 28 29 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65  ()],.** then the
2dee0 20 63 61 6c 6c 20 77 69 6c 6c 20 72 65 74 75 72   call will retur
2def0 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  n [SQLITE_MISUSE
2df00 5d 2e 20 20 49 66 20 61 6e 79 20 73 71 6c 69 74  ].  If any sqlit
2df10 65 33 5f 62 69 6e 64 5f 28 29 0a 2a 2a 20 72 6f  e3_bind_().** ro
2df20 75 74 69 6e 65 20 69 73 20 70 61 73 73 65 64 20  utine is passed 
2df30 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  a [prepared stat
2df40 65 6d 65 6e 74 5d 20 74 68 61 74 20 68 61 73 20  ement] that has 
2df50 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64 2c 20  been finalized, 
2df60 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 69 73  the.** result is
2df70 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 20 70   undefined and p
2df80 72 6f 62 61 62 6c 79 20 68 61 72 6d 66 75 6c 2e  robably harmful.
2df90 0a 2a 2a 0a 2a 2a 20 5e 42 69 6e 64 69 6e 67 73  .**.** ^Bindings
2dfa0 20 61 72 65 20 6e 6f 74 20 63 6c 65 61 72 65 64   are not cleared
2dfb0 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33   by the [sqlite3
2dfc0 5f 72 65 73 65 74 28 29 5d 20 72 6f 75 74 69 6e  _reset()] routin
2dfd0 65 2e 0a 2a 2a 20 5e 55 6e 62 6f 75 6e 64 20 70  e..** ^Unbound p
2dfe0 61 72 61 6d 65 74 65 72 73 20 61 72 65 20 69 6e  arameters are in
2dff0 74 65 72 70 72 65 74 65 64 20 61 73 20 4e 55 4c  terpreted as NUL
2e000 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  L..**.** ^The sq
2e010 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 20 72 6f 75  lite3_bind_* rou
2e020 74 69 6e 65 73 20 72 65 74 75 72 6e 20 5b 53 51  tines return [SQ
2e030 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63  LITE_OK] on succ
2e040 65 73 73 20 6f 72 20 61 6e 0a 2a 2a 20 5b 65 72  ess or an.** [er
2e050 72 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 6e 79  ror code] if any
2e060 74 68 69 6e 67 20 67 6f 65 73 20 77 72 6f 6e 67  thing goes wrong
2e070 2e 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 54 4f  ..** ^[SQLITE_TO
2e080 4f 42 49 47 5d 20 6d 69 67 68 74 20 62 65 20 72  OBIG] might be r
2e090 65 74 75 72 6e 65 64 20 69 66 20 74 68 65 20 73  eturned if the s
2e0a0 69 7a 65 20 6f 66 20 61 20 73 74 72 69 6e 67 20  ize of a string 
2e0b0 6f 72 20 42 4c 4f 42 0a 2a 2a 20 65 78 63 65 65  or BLOB.** excee
2e0c0 64 73 20 6c 69 6d 69 74 73 20 69 6d 70 6f 73 65  ds limits impose
2e0d0 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c 69  d by [sqlite3_li
2e0e0 6d 69 74 5d 28 5b 53 51 4c 49 54 45 5f 4c 49 4d  mit]([SQLITE_LIM
2e0f0 49 54 5f 4c 45 4e 47 54 48 5d 29 20 6f 72 0a 2a  IT_LENGTH]) or.*
2e100 2a 20 5b 53 51 4c 49 54 45 5f 4d 41 58 5f 4c 45  * [SQLITE_MAX_LE
2e110 4e 47 54 48 5d 2e 0a 2a 2a 20 5e 5b 53 51 4c 49  NGTH]..** ^[SQLI
2e120 54 45 5f 52 41 4e 47 45 5d 20 69 73 20 72 65 74  TE_RANGE] is ret
2e130 75 72 6e 65 64 20 69 66 20 74 68 65 20 70 61 72  urned if the par
2e140 61 6d 65 74 65 72 0a 2a 2a 20 69 6e 64 65 78 20  ameter.** index 
2e150 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 2e  is out of range.
2e160 20 20 5e 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d    ^[SQLITE_NOMEM
2e170 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 66  ] is returned if
2e180 20 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 73 2e   malloc() fails.
2e190 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a  .**.** See also:
2e1a0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
2e1b0 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29  arameter_count()
2e1c0 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  ],.** [sqlite3_b
2e1d0 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61  ind_parameter_na
2e1e0 6d 65 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69  me()], and [sqli
2e1f0 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
2e200 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a  er_index()]..*/.
2e210 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
2e220 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74  _blob(sqlite3_st
2e230 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20  mt*, int, const 
2e240 76 6f 69 64 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f  void*, int n, vo
2e250 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69  id(*)(void*));.i
2e260 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
2e270 62 6c 6f 62 36 34 28 73 71 6c 69 74 65 33 5f 73  blob64(sqlite3_s
2e280 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74  tmt*, int, const
2e290 20 76 6f 69 64 2a 2c 20 73 71 6c 69 74 65 33 5f   void*, sqlite3_
2e2a0 75 69 6e 74 36 34 2c 0a 20 20 20 20 20 20 20 20  uint64,.        
2e2b0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2e2c0 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b  void(*)(void*));
2e2d0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e  .int sqlite3_bin
2e2e0 64 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33  d_double(sqlite3
2e2f0 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 64 6f 75  _stmt*, int, dou
2e300 62 6c 65 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  ble);.int sqlite
2e310 33 5f 62 69 6e 64 5f 69 6e 74 28 73 71 6c 69 74  3_bind_int(sqlit
2e320 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 69  e3_stmt*, int, i
2e330 6e 74 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  nt);.int sqlite3
2e340 5f 62 69 6e 64 5f 69 6e 74 36 34 28 73 71 6c 69  _bind_int64(sqli
2e350 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20  te3_stmt*, int, 
2e360 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a  sqlite3_int64);.
2e370 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
2e380 5f 6e 75 6c 6c 28 73 71 6c 69 74 65 33 5f 73 74  _null(sqlite3_st
2e390 6d 74 2a 2c 20 69 6e 74 29 3b 0a 69 6e 74 20 73  mt*, int);.int s
2e3a0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
2e3b0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69  (sqlite3_stmt*,i
2e3c0 6e 74 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 69  nt,const char*,i
2e3d0 6e 74 2c 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a  nt,void(*)(void*
2e3e0 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  ));.int sqlite3_
2e3f0 62 69 6e 64 5f 74 65 78 74 31 36 28 73 71 6c 69  bind_text16(sqli
2e400 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20  te3_stmt*, int, 
2e410 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74  const void*, int
2e420 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29  , void(*)(void*)
2e430 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  );.int sqlite3_b
2e440 69 6e 64 5f 74 65 78 74 36 34 28 73 71 6c 69 74  ind_text64(sqlit
2e450 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63  e3_stmt*, int, c
2e460 6f 6e 73 74 20 63 68 61 72 2a 2c 20 73 71 6c 69  onst char*, sqli
2e470 74 65 33 5f 75 69 6e 74 36 34 2c 0a 20 20 20 20  te3_uint64,.    
2e480 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2e490 20 20 20 20 20 76 6f 69 64 28 2a 29 28 76 6f 69       void(*)(voi
2e4a0 64 2a 29 2c 20 75 6e 73 69 67 6e 65 64 20 63 68  d*), unsigned ch
2e4b0 61 72 20 65 6e 63 6f 64 69 6e 67 29 3b 0a 69 6e  ar encoding);.in
2e4c0 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76  t sqlite3_bind_v
2e4d0 61 6c 75 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  alue(sqlite3_stm
2e4e0 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 73  t*, int, const s
2e4f0 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
2e500 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
2e510 5f 7a 65 72 6f 62 6c 6f 62 28 73 71 6c 69 74 65  _zeroblob(sqlite
2e520 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e  3_stmt*, int, in
2e530 74 20 6e 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  t n);.int sqlite
2e540 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 36  3_bind_zeroblob6
2e550 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  4(sqlite3_stmt*,
2e560 20 69 6e 74 2c 20 73 71 6c 69 74 65 33 5f 75 69   int, sqlite3_ui
2e570 6e 74 36 34 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  nt64);../*.** CA
2e580 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 4f  PI3REF: Number O
2e590 66 20 53 51 4c 20 50 61 72 61 6d 65 74 65 72 73  f SQL Parameters
2e5a0 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
2e5b0 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e  te3_stmt.**.** ^
2e5c0 54 68 69 73 20 72 6f 75 74 69 6e 65 20 63 61 6e  This routine can
2e5d0 20 62 65 20 75 73 65 64 20 74 6f 20 66 69 6e 64   be used to find
2e5e0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 5b   the number of [
2e5f0 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 5d 0a  SQL parameters].
2e600 2a 2a 20 69 6e 20 61 20 5b 70 72 65 70 61 72 65  ** in a [prepare
2e610 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20 53  d statement].  S
2e620 51 4c 20 70 61 72 61 6d 65 74 65 72 73 20 61 72  QL parameters ar
2e630 65 20 74 6f 6b 65 6e 73 20 6f 66 20 74 68 65 0a  e tokens of the.
2e640 2a 2a 20 66 6f 72 6d 20 22 3f 22 2c 20 22 3f 4e  ** form "?", "?N
2e650 4e 4e 22 2c 20 22 3a 41 41 41 22 2c 20 22 24 41  NN", ":AAA", "$A
2e660 41 41 22 2c 20 6f 72 20 22 40 41 41 41 22 20 74  AA", or "@AAA" t
2e670 68 61 74 20 73 65 72 76 65 20 61 73 0a 2a 2a 20  hat serve as.** 
2e680 70 6c 61 63 65 68 6f 6c 64 65 72 73 20 66 6f 72  placeholders for
2e690 20 76 61 6c 75 65 73 20 74 68 61 74 20 61 72 65   values that are
2e6a0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62   [sqlite3_bind_b
2e6b0 6c 6f 62 20 7c 20 62 6f 75 6e 64 5d 0a 2a 2a 20  lob | bound].** 
2e6c0 74 6f 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  to the parameter
2e6d0 73 20 61 74 20 61 20 6c 61 74 65 72 20 74 69 6d  s at a later tim
2e6e0 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20  e..**.** ^(This 
2e6f0 72 6f 75 74 69 6e 65 20 61 63 74 75 61 6c 6c 79  routine actually
2e700 20 72 65 74 75 72 6e 73 20 74 68 65 20 69 6e 64   returns the ind
2e710 65 78 20 6f 66 20 74 68 65 20 6c 61 72 67 65 73  ex of the larges
2e720 74 20 28 72 69 67 68 74 6d 6f 73 74 29 0a 2a 2a  t (rightmost).**
2e730 20 70 61 72 61 6d 65 74 65 72 2e 20 46 6f 72 20   parameter. For 
2e740 61 6c 6c 20 66 6f 72 6d 73 20 65 78 63 65 70 74  all forms except
2e750 20 3f 4e 4e 4e 2c 20 74 68 69 73 20 77 69 6c 6c   ?NNN, this will
2e760 20 63 6f 72 72 65 73 70 6f 6e 64 20 74 6f 20 74   correspond to t
2e770 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20  he.** number of 
2e780 75 6e 69 71 75 65 20 70 61 72 61 6d 65 74 65 72  unique parameter
2e790 73 2e 20 20 49 66 20 70 61 72 61 6d 65 74 65 72  s.  If parameter
2e7a0 73 20 6f 66 20 74 68 65 20 3f 4e 4e 4e 20 66 6f  s of the ?NNN fo
2e7b0 72 6d 20 61 72 65 20 75 73 65 64 2c 0a 2a 2a 20  rm are used,.** 
2e7c0 74 68 65 72 65 20 6d 61 79 20 62 65 20 67 61 70  there may be gap
2e7d0 73 20 69 6e 20 74 68 65 20 6c 69 73 74 2e 29 5e  s in the list.)^
2e7e0 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a  .**.** See also:
2e7f0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62   [sqlite3_bind_b
2e800 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64  lob|sqlite3_bind
2e810 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ()],.** [sqlite3
2e820 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
2e830 6e 61 6d 65 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20  name()], and.** 
2e840 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  [sqlite3_bind_pa
2e850 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d  rameter_index()]
2e860 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
2e870 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
2e880 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74  count(sqlite3_st
2e890 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  mt*);../*.** CAP
2e8a0 49 33 52 45 46 3a 20 4e 61 6d 65 20 4f 66 20 41  I3REF: Name Of A
2e8b0 20 48 6f 73 74 20 50 61 72 61 6d 65 74 65 72 0a   Host Parameter.
2e8c0 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
2e8d0 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54  e3_stmt.**.** ^T
2e8e0 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  he sqlite3_bind_
2e8f0 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 50  parameter_name(P
2e900 2c 4e 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  ,N) interface re
2e910 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 61 6d  turns.** the nam
2e920 65 20 6f 66 20 74 68 65 20 4e 2d 74 68 20 5b 53  e of the N-th [S
2e930 51 4c 20 70 61 72 61 6d 65 74 65 72 5d 20 69 6e  QL parameter] in
2e940 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
2e950 74 61 74 65 6d 65 6e 74 5d 20 50 2e 0a 2a 2a 20  tatement] P..** 
2e960 5e 28 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73  ^(SQL parameters
2e970 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 3f 4e   of the form "?N
2e980 4e 4e 22 20 6f 72 20 22 3a 41 41 41 22 20 6f 72  NN" or ":AAA" or
2e990 20 22 40 41 41 41 22 20 6f 72 20 22 24 41 41 41   "@AAA" or "$AAA
2e9a0 22 0a 2a 2a 20 68 61 76 65 20 61 20 6e 61 6d 65  ".** have a name
2e9b0 20 77 68 69 63 68 20 69 73 20 74 68 65 20 73 74   which is the st
2e9c0 72 69 6e 67 20 22 3f 4e 4e 4e 22 20 6f 72 20 22  ring "?NNN" or "
2e9d0 3a 41 41 41 22 20 6f 72 20 22 40 41 41 41 22 20  :AAA" or "@AAA" 
2e9e0 6f 72 20 22 24 41 41 41 22 0a 2a 2a 20 72 65 73  or "$AAA".** res
2e9f0 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 49 6e  pectively..** In
2ea00 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68   other words, th
2ea10 65 20 69 6e 69 74 69 61 6c 20 22 3a 22 20 6f 72  e initial ":" or
2ea20 20 22 24 22 20 6f 72 20 22 40 22 20 6f 72 20 22   "$" or "@" or "
2ea30 3f 22 0a 2a 2a 20 69 73 20 69 6e 63 6c 75 64 65  ?".** is include
2ea40 64 20 61 73 20 70 61 72 74 20 6f 66 20 74 68 65  d as part of the
2ea50 20 6e 61 6d 65 2e 29 5e 0a 2a 2a 20 5e 50 61 72   name.)^.** ^Par
2ea60 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20 66  ameters of the f
2ea70 6f 72 6d 20 22 3f 22 20 77 69 74 68 6f 75 74 20  orm "?" without 
2ea80 61 20 66 6f 6c 6c 6f 77 69 6e 67 20 69 6e 74 65  a following inte
2ea90 67 65 72 20 68 61 76 65 20 6e 6f 20 6e 61 6d 65  ger have no name
2eaa0 0a 2a 2a 20 61 6e 64 20 61 72 65 20 72 65 66 65  .** and are refe
2eab0 72 72 65 64 20 74 6f 20 61 73 20 22 6e 61 6d 65  rred to as "name
2eac0 6c 65 73 73 22 20 6f 72 20 22 61 6e 6f 6e 79 6d  less" or "anonym
2ead0 6f 75 73 20 70 61 72 61 6d 65 74 65 72 73 22 2e  ous parameters".
2eae0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73  .**.** ^The firs
2eaf0 74 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72  t host parameter
2eb00 20 68 61 73 20 61 6e 20 69 6e 64 65 78 20 6f 66   has an index of
2eb10 20 31 2c 20 6e 6f 74 20 30 2e 0a 2a 2a 0a 2a 2a   1, not 0..**.**
2eb20 20 5e 49 66 20 74 68 65 20 76 61 6c 75 65 20 4e   ^If the value N
2eb30 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65   is out of range
2eb40 20 6f 72 20 69 66 20 74 68 65 20 4e 2d 74 68 20   or if the N-th 
2eb50 70 61 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20  parameter is.** 
2eb60 6e 61 6d 65 6c 65 73 73 2c 20 74 68 65 6e 20 4e  nameless, then N
2eb70 55 4c 4c 20 69 73 20 72 65 74 75 72 6e 65 64 2e  ULL is returned.
2eb80 20 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20    ^The returned 
2eb90 73 74 72 69 6e 67 20 69 73 0a 2a 2a 20 61 6c 77  string is.** alw
2eba0 61 79 73 20 69 6e 20 55 54 46 2d 38 20 65 6e 63  ays in UTF-8 enc
2ebb0 6f 64 69 6e 67 20 65 76 65 6e 20 69 66 20 74 68  oding even if th
2ebc0 65 20 6e 61 6d 65 64 20 70 61 72 61 6d 65 74 65  e named paramete
2ebd0 72 20 77 61 73 0a 2a 2a 20 6f 72 69 67 69 6e 61  r was.** origina
2ebe0 6c 6c 79 20 73 70 65 63 69 66 69 65 64 20 61 73  lly specified as
2ebf0 20 55 54 46 2d 31 36 20 69 6e 20 5b 73 71 6c 69   UTF-16 in [sqli
2ec00 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d  te3_prepare16()]
2ec10 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   or.** [sqlite3_
2ec20 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e  prepare16_v2()].
2ec30 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a  .**.** See also:
2ec40 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62   [sqlite3_bind_b
2ec50 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64  lob|sqlite3_bind
2ec60 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ()],.** [sqlite3
2ec70 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
2ec80 63 6f 75 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a  count()], and.**
2ec90 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
2eca0 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29  arameter_index()
2ecb0 5d 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72  ]..*/.const char
2ecc0 20 2a 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   *sqlite3_bind_p
2ecd0 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 73 71  arameter_name(sq
2ece0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
2ecf0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2ed00 45 46 3a 20 49 6e 64 65 78 20 4f 66 20 41 20 50  EF: Index Of A P
2ed10 61 72 61 6d 65 74 65 72 20 57 69 74 68 20 41 20  arameter With A 
2ed20 47 69 76 65 6e 20 4e 61 6d 65 0a 2a 2a 20 4d 45  Given Name.** ME
2ed30 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74  THOD: sqlite3_st
2ed40 6d 74 0a 2a 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e  mt.**.** ^Return
2ed50 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 61 6e   the index of an
2ed60 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 67   SQL parameter g
2ed70 69 76 65 6e 20 69 74 73 20 6e 61 6d 65 2e 20 20  iven its name.  
2ed80 5e 54 68 65 0a 2a 2a 20 69 6e 64 65 78 20 76 61  ^The.** index va
2ed90 6c 75 65 20 72 65 74 75 72 6e 65 64 20 69 73 20  lue returned is 
2eda0 73 75 69 74 61 62 6c 65 20 66 6f 72 20 75 73 65  suitable for use
2edb0 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a   as the second.*
2edc0 2a 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b  * parameter to [
2edd0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
2ede0 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29  b|sqlite3_bind()
2edf0 5d 2e 20 20 5e 41 20 7a 65 72 6f 0a 2a 2a 20 69  ].  ^A zero.** i
2ee00 73 20 72 65 74 75 72 6e 65 64 20 69 66 20 6e 6f  s returned if no
2ee10 20 6d 61 74 63 68 69 6e 67 20 70 61 72 61 6d 65   matching parame
2ee20 74 65 72 20 69 73 20 66 6f 75 6e 64 2e 20 20 5e  ter is found.  ^
2ee30 54 68 65 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a  The parameter.**
2ee40 20 6e 61 6d 65 20 6d 75 73 74 20 62 65 20 67 69   name must be gi
2ee50 76 65 6e 20 69 6e 20 55 54 46 2d 38 20 65 76 65  ven in UTF-8 eve
2ee60 6e 20 69 66 20 74 68 65 20 6f 72 69 67 69 6e 61  n if the origina
2ee70 6c 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 77  l statement.** w
2ee80 61 73 20 70 72 65 70 61 72 65 64 20 66 72 6f 6d  as prepared from
2ee90 20 55 54 46 2d 31 36 20 74 65 78 74 20 75 73 69   UTF-16 text usi
2eea0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ng [sqlite3_prep
2eeb0 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a  are16_v2()]..**.
2eec0 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71  ** See also: [sq
2eed0 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c  lite3_bind_blob|
2eee0 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c  sqlite3_bind()],
2eef0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  .** [sqlite3_bin
2ef00 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e  d_parameter_coun
2ef10 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71  t()], and.** [sq
2ef20 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
2ef30 65 74 65 72 5f 6e 61 6d 65 28 29 5d 2e 0a 2a 2f  eter_name()]..*/
2ef40 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e  .int sqlite3_bin
2ef50 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65  d_parameter_inde
2ef60 78 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  x(sqlite3_stmt*,
2ef70 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61   const char *zNa
2ef80 6d 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  me);../*.** CAPI
2ef90 33 52 45 46 3a 20 52 65 73 65 74 20 41 6c 6c 20  3REF: Reset All 
2efa0 42 69 6e 64 69 6e 67 73 20 4f 6e 20 41 20 50 72  Bindings On A Pr
2efb0 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74  epared Statement
2efc0 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
2efd0 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e  te3_stmt.**.** ^
2efe0 43 6f 6e 74 72 61 72 79 20 74 6f 20 74 68 65 20  Contrary to the 
2eff0 69 6e 74 75 69 74 69 6f 6e 20 6f 66 20 6d 61 6e  intuition of man
2f000 79 2c 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  y, [sqlite3_rese
2f010 74 28 29 5d 20 64 6f 65 73 20 6e 6f 74 20 72 65  t()] does not re
2f020 73 65 74 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69  set.** the [sqli
2f030 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20  te3_bind_blob | 
2f040 62 69 6e 64 69 6e 67 73 5d 20 6f 6e 20 61 20 5b  bindings] on a [
2f050 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2f060 6e 74 5d 2e 0a 2a 2a 20 5e 55 73 65 20 74 68 69  nt]..** ^Use thi
2f070 73 20 72 6f 75 74 69 6e 65 20 74 6f 20 72 65 73  s routine to res
2f080 65 74 20 61 6c 6c 20 68 6f 73 74 20 70 61 72 61  et all host para
2f090 6d 65 74 65 72 73 20 74 6f 20 4e 55 4c 4c 2e 0a  meters to NULL..
2f0a0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  */.int sqlite3_c
2f0b0 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73 28 73 71  lear_bindings(sq
2f0c0 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f  lite3_stmt*);../
2f0d0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e  *.** CAPI3REF: N
2f0e0 75 6d 62 65 72 20 4f 66 20 43 6f 6c 75 6d 6e 73  umber Of Columns
2f0f0 20 49 6e 20 41 20 52 65 73 75 6c 74 20 53 65 74   In A Result Set
2f100 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
2f110 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e  te3_stmt.**.** ^
2f120 52 65 74 75 72 6e 20 74 68 65 20 6e 75 6d 62 65  Return the numbe
2f130 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20  r of columns in 
2f140 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 72  the result set r
2f150 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 0a 2a  eturned by the.*
2f160 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  * [prepared stat
2f170 65 6d 65 6e 74 5d 2e 20 5e 49 66 20 74 68 69 73  ement]. ^If this
2f180 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
2f190 20 30 2c 20 74 68 61 74 20 6d 65 61 6e 73 20 74   0, that means t
2f1a0 68 65 20 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64  he .** [prepared
2f1b0 20 73 74 61 74 65 6d 65 6e 74 5d 20 72 65 74 75   statement] retu
2f1c0 72 6e 73 20 6e 6f 20 64 61 74 61 20 28 66 6f 72  rns no data (for
2f1d0 20 65 78 61 6d 70 6c 65 20 61 6e 20 5b 55 50 44   example an [UPD
2f1e0 41 54 45 5d 29 2e 0a 2a 2a 20 5e 48 6f 77 65 76  ATE])..** ^Howev
2f1f0 65 72 2c 20 6a 75 73 74 20 62 65 63 61 75 73 65  er, just because
2f200 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65   this routine re
2f210 74 75 72 6e 73 20 61 20 70 6f 73 69 74 69 76 65  turns a positive
2f220 20 6e 75 6d 62 65 72 20 64 6f 65 73 20 6e 6f 74   number does not
2f230 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20 6f 6e  .** mean that on
2f240 65 20 6f 72 20 6d 6f 72 65 20 72 6f 77 73 20 6f  e or more rows o
2f250 66 20 64 61 74 61 20 77 69 6c 6c 20 62 65 20 72  f data will be r
2f260 65 74 75 72 6e 65 64 2e 20 20 5e 41 20 53 45 4c  eturned.  ^A SEL
2f270 45 43 54 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a  ECT statement.**
2f280 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 68 61 76   will always hav
2f290 65 20 61 20 70 6f 73 69 74 69 76 65 20 73 71 6c  e a positive sql
2f2a0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e  ite3_column_coun
2f2b0 74 28 29 20 62 75 74 20 64 65 70 65 6e 64 69 6e  t() but dependin
2f2c0 67 20 6f 6e 20 74 68 65 0a 2a 2a 20 57 48 45 52  g on the.** WHER
2f2d0 45 20 63 6c 61 75 73 65 20 63 6f 6e 73 74 72 61  E clause constra
2f2e0 69 6e 74 73 20 61 6e 64 20 74 68 65 20 74 61 62  ints and the tab
2f2f0 6c 65 20 63 6f 6e 74 65 6e 74 2c 20 69 74 20 6d  le content, it m
2f300 69 67 68 74 20 72 65 74 75 72 6e 20 6e 6f 20 72  ight return no r
2f310 6f 77 73 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  ows..**.** See a
2f320 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 64 61  lso: [sqlite3_da
2f330 74 61 5f 63 6f 75 6e 74 28 29 5d 0a 2a 2f 0a 69  ta_count()].*/.i
2f340 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nt sqlite3_colum
2f350 6e 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f  n_count(sqlite3_
2f360 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f  stmt *pStmt);../
2f370 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
2f380 6f 6c 75 6d 6e 20 4e 61 6d 65 73 20 49 6e 20 41  olumn Names In A
2f390 20 52 65 73 75 6c 74 20 53 65 74 0a 2a 2a 20 4d   Result Set.** M
2f3a0 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73  ETHOD: sqlite3_s
2f3b0 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65  tmt.**.** ^These
2f3c0 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
2f3d0 20 74 68 65 20 6e 61 6d 65 20 61 73 73 69 67 6e   the name assign
2f3e0 65 64 20 74 6f 20 61 20 70 61 72 74 69 63 75 6c  ed to a particul
2f3f0 61 72 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 6e 20  ar column.** in 
2f400 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 6f  the result set o
2f410 66 20 61 20 5b 53 45 4c 45 43 54 5d 20 73 74 61  f a [SELECT] sta
2f420 74 65 6d 65 6e 74 2e 20 20 5e 54 68 65 20 73 71  tement.  ^The sq
2f430 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d  lite3_column_nam
2f440 65 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  e().** interface
2f450 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
2f460 65 72 20 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72  er to a zero-ter
2f470 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74  minated UTF-8 st
2f480 72 69 6e 67 0a 2a 2a 20 61 6e 64 20 73 71 6c 69  ring.** and sqli
2f490 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31  te3_column_name1
2f4a0 36 28 29 20 72 65 74 75 72 6e 73 20 61 20 70 6f  6() returns a po
2f4b0 69 6e 74 65 72 20 74 6f 20 61 20 7a 65 72 6f 2d  inter to a zero-
2f4c0 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54  terminated.** UT
2f4d0 46 2d 31 36 20 73 74 72 69 6e 67 2e 20 20 5e 54  F-16 string.  ^T
2f4e0 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
2f4f0 65 72 20 69 73 20 74 68 65 20 5b 70 72 65 70 61  er is the [prepa
2f500 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a  red statement].*
2f510 2a 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74  * that implement
2f520 73 20 74 68 65 20 5b 53 45 4c 45 43 54 5d 20 73  s the [SELECT] s
2f530 74 61 74 65 6d 65 6e 74 2e 20 5e 54 68 65 20 73  tatement. ^The s
2f540 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
2f550 69 73 20 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e  is the.** column
2f560 20 6e 75 6d 62 65 72 2e 20 20 5e 54 68 65 20 6c   number.  ^The l
2f570 65 66 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 69  eftmost column i
2f580 73 20 6e 75 6d 62 65 72 20 30 2e 0a 2a 2a 0a 2a  s number 0..**.*
2f590 2a 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20  * ^The returned 
2f5a0 73 74 72 69 6e 67 20 70 6f 69 6e 74 65 72 20 69  string pointer i
2f5b0 73 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 65 69  s valid until ei
2f5c0 74 68 65 72 20 74 68 65 20 5b 70 72 65 70 61 72  ther the [prepar
2f5d0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a  ed statement].**
2f5e0 20 69 73 20 64 65 73 74 72 6f 79 65 64 20 62 79   is destroyed by
2f5f0 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
2f600 7a 65 28 29 5d 20 6f 72 20 75 6e 74 69 6c 20 74  ze()] or until t
2f610 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  he statement is 
2f620 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a  automatically.**
2f630 20 72 65 70 72 65 70 61 72 65 64 20 62 79 20 74   reprepared by t
2f640 68 65 20 66 69 72 73 74 20 63 61 6c 6c 20 74 6f  he first call to
2f650 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
2f660 5d 20 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c  ] for a particul
2f670 61 72 20 72 75 6e 0a 2a 2a 20 6f 72 20 75 6e 74  ar run.** or unt
2f680 69 6c 20 74 68 65 20 6e 65 78 74 20 63 61 6c 6c  il the next call
2f690 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63   to.** sqlite3_c
2f6a0 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 20 6f 72 20  olumn_name() or 
2f6b0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e  sqlite3_column_n
2f6c0 61 6d 65 31 36 28 29 20 6f 6e 20 74 68 65 20 73  ame16() on the s
2f6d0 61 6d 65 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a  ame column..**.*
2f6e0 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6d 61  * ^If sqlite3_ma
2f6f0 6c 6c 6f 63 28 29 20 66 61 69 6c 73 20 64 75 72  lloc() fails dur
2f700 69 6e 67 20 74 68 65 20 70 72 6f 63 65 73 73 69  ing the processi
2f710 6e 67 20 6f 66 20 65 69 74 68 65 72 20 72 6f 75  ng of either rou
2f720 74 69 6e 65 0a 2a 2a 20 28 66 6f 72 20 65 78 61  tine.** (for exa
2f730 6d 70 6c 65 20 64 75 72 69 6e 67 20 61 20 63 6f  mple during a co
2f740 6e 76 65 72 73 69 6f 6e 20 66 72 6f 6d 20 55 54  nversion from UT
2f750 46 2d 38 20 74 6f 20 55 54 46 2d 31 36 29 20 74  F-8 to UTF-16) t
2f760 68 65 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f  hen a.** NULL po
2f770 69 6e 74 65 72 20 69 73 20 72 65 74 75 72 6e 65  inter is returne
2f780 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61  d..**.** ^The na
2f790 6d 65 20 6f 66 20 61 20 72 65 73 75 6c 74 20 63  me of a result c
2f7a0 6f 6c 75 6d 6e 20 69 73 20 74 68 65 20 76 61 6c  olumn is the val
2f7b0 75 65 20 6f 66 20 74 68 65 20 22 41 53 22 20 63  ue of the "AS" c
2f7c0 6c 61 75 73 65 20 66 6f 72 0a 2a 2a 20 74 68 61  lause for.** tha
2f7d0 74 20 63 6f 6c 75 6d 6e 2c 20 69 66 20 74 68 65  t column, if the
2f7e0 72 65 20 69 73 20 61 6e 20 41 53 20 63 6c 61 75  re is an AS clau
2f7f0 73 65 2e 20 20 49 66 20 74 68 65 72 65 20 69 73  se.  If there is
2f800 20 6e 6f 20 41 53 20 63 6c 61 75 73 65 0a 2a 2a   no AS clause.**
2f810 20 74 68 65 6e 20 74 68 65 20 6e 61 6d 65 20 6f   then the name o
2f820 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20 69 73 20  f the column is 
2f830 75 6e 73 70 65 63 69 66 69 65 64 20 61 6e 64 20  unspecified and 
2f840 6d 61 79 20 63 68 61 6e 67 65 20 66 72 6f 6d 0a  may change from.
2f850 2a 2a 20 6f 6e 65 20 72 65 6c 65 61 73 65 20 6f  ** one release o
2f860 66 20 53 51 4c 69 74 65 20 74 6f 20 74 68 65 20  f SQLite to the 
2f870 6e 65 78 74 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63  next..*/.const c
2f880 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  har *sqlite3_col
2f890 75 6d 6e 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33  umn_name(sqlite3
2f8a0 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a  _stmt*, int N);.
2f8b0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
2f8c0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31  te3_column_name1
2f8d0 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  6(sqlite3_stmt*,
2f8e0 20 69 6e 74 20 4e 29 3b 0a 0a 2f 2a 0a 2a 2a 20   int N);../*.** 
2f8f0 43 41 50 49 33 52 45 46 3a 20 53 6f 75 72 63 65  CAPI3REF: Source
2f900 20 4f 66 20 44 61 74 61 20 49 6e 20 41 20 51 75   Of Data In A Qu
2f910 65 72 79 20 52 65 73 75 6c 74 0a 2a 2a 20 4d 45  ery Result.** ME
2f920 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74  THOD: sqlite3_st
2f930 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20  mt.**.** ^These 
2f940 72 6f 75 74 69 6e 65 73 20 70 72 6f 76 69 64 65  routines provide
2f950 20 61 20 6d 65 61 6e 73 20 74 6f 20 64 65 74 65   a means to dete
2f960 72 6d 69 6e 65 20 74 68 65 20 64 61 74 61 62 61  rmine the databa
2f970 73 65 2c 20 74 61 62 6c 65 2c 20 61 6e 64 0a 2a  se, table, and.*
2f980 2a 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74  * table column t
2f990 68 61 74 20 69 73 20 74 68 65 20 6f 72 69 67 69  hat is the origi
2f9a0 6e 20 6f 66 20 61 20 70 61 72 74 69 63 75 6c 61  n of a particula
2f9b0 72 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20  r result column 
2f9c0 69 6e 0a 2a 2a 20 5b 53 45 4c 45 43 54 5d 20 73  in.** [SELECT] s
2f9d0 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68  tatement..** ^Th
2f9e0 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61  e name of the da
2f9f0 74 61 62 61 73 65 20 6f 72 20 74 61 62 6c 65 20  tabase or table 
2fa00 6f 72 20 63 6f 6c 75 6d 6e 20 63 61 6e 20 62 65  or column can be
2fa10 20 72 65 74 75 72 6e 65 64 20 61 73 0a 2a 2a 20   returned as.** 
2fa20 65 69 74 68 65 72 20 61 20 55 54 46 2d 38 20 6f  either a UTF-8 o
2fa30 72 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 2e  r UTF-16 string.
2fa40 20 20 5e 54 68 65 20 5f 64 61 74 61 62 61 73 65    ^The _database
2fa50 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  _ routines retur
2fa60 6e 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73  n.** the databas
2fa70 65 20 6e 61 6d 65 2c 20 74 68 65 20 5f 74 61 62  e name, the _tab
2fa80 6c 65 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74  le_ routines ret
2fa90 75 72 6e 20 74 68 65 20 74 61 62 6c 65 20 6e 61  urn the table na
2faa0 6d 65 2c 20 61 6e 64 0a 2a 2a 20 74 68 65 20 6f  me, and.** the o
2fab0 72 69 67 69 6e 5f 20 72 6f 75 74 69 6e 65 73 20  rigin_ routines 
2fac0 72 65 74 75 72 6e 20 74 68 65 20 63 6f 6c 75 6d  return the colum
2fad0 6e 20 6e 61 6d 65 2e 0a 2a 2a 20 5e 54 68 65 20  n name..** ^The 
2fae0 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20  returned string 
2faf0 69 73 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 74  is valid until t
2fb00 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
2fb10 74 65 6d 65 6e 74 5d 20 69 73 20 64 65 73 74 72  tement] is destr
2fb20 6f 79 65 64 0a 2a 2a 20 75 73 69 6e 67 20 5b 73  oyed.** using [s
2fb30 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
2fb40 29 5d 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20  )] or until the 
2fb50 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 75 74  statement is aut
2fb60 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 72 65  omatically.** re
2fb70 70 72 65 70 61 72 65 64 20 62 79 20 74 68 65 20  prepared by the 
2fb80 66 69 72 73 74 20 63 61 6c 6c 20 74 6f 20 5b 73  first call to [s
2fb90 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 66  qlite3_step()] f
2fba0 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61 72 20  or a particular 
2fbb0 72 75 6e 0a 2a 2a 20 6f 72 20 75 6e 74 69 6c 20  run.** or until 
2fbc0 74 68 65 20 73 61 6d 65 20 69 6e 66 6f 72 6d 61  the same informa
2fbd0 74 69 6f 6e 20 69 73 20 72 65 71 75 65 73 74 65  tion is requeste
2fbe0 64 0a 2a 2a 20 61 67 61 69 6e 20 69 6e 20 61 20  d.** again in a 
2fbf0 64 69 66 66 65 72 65 6e 74 20 65 6e 63 6f 64 69  different encodi
2fc00 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e  ng..**.** ^The n
2fc10 61 6d 65 73 20 72 65 74 75 72 6e 65 64 20 61 72  ames returned ar
2fc20 65 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 75  e the original u
2fc30 6e 2d 61 6c 69 61 73 65 64 20 6e 61 6d 65 73 20  n-aliased names 
2fc40 6f 66 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61  of the.** databa
2fc50 73 65 2c 20 74 61 62 6c 65 2c 20 61 6e 64 20 63  se, table, and c
2fc60 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  olumn..**.** ^Th
2fc70 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
2fc80 20 74 6f 20 74 68 65 73 65 20 69 6e 74 65 72 66   to these interf
2fc90 61 63 65 73 20 69 73 20 61 20 5b 70 72 65 70 61  aces is a [prepa
2fca0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a  red statement]..
2fcb0 2a 2a 20 5e 54 68 65 73 65 20 66 75 6e 63 74 69  ** ^These functi
2fcc0 6f 6e 73 20 72 65 74 75 72 6e 20 69 6e 66 6f 72  ons return infor
2fcd0 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 74 68 65  mation about the
2fce0 20 4e 74 68 20 72 65 73 75 6c 74 20 63 6f 6c 75   Nth result colu
2fcf0 6d 6e 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a  mn returned by.*
2fd00 2a 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 2c  * the statement,
2fd10 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 20   where N is the 
2fd20 73 65 63 6f 6e 64 20 66 75 6e 63 74 69 6f 6e 20  second function 
2fd30 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68  argument..** ^Th
2fd40 65 20 6c 65 66 74 2d 6d 6f 73 74 20 63 6f 6c 75  e left-most colu
2fd50 6d 6e 20 69 73 20 63 6f 6c 75 6d 6e 20 30 20 66  mn is column 0 f
2fd60 6f 72 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  or these routine
2fd70 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  s..**.** ^If the
2fd80 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 72 65 74 75   Nth column retu
2fd90 72 6e 65 64 20 62 79 20 74 68 65 20 73 74 61 74  rned by the stat
2fda0 65 6d 65 6e 74 20 69 73 20 61 6e 20 65 78 70 72  ement is an expr
2fdb0 65 73 73 69 6f 6e 20 6f 72 0a 2a 2a 20 73 75 62  ession or.** sub
2fdc0 71 75 65 72 79 20 61 6e 64 20 69 73 20 6e 6f 74  query and is not
2fdd0 20 61 20 63 6f 6c 75 6d 6e 20 76 61 6c 75 65 2c   a column value,
2fde0 20 74 68 65 6e 20 61 6c 6c 20 6f 66 20 74 68 65   then all of the
2fdf0 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74  se functions ret
2fe00 75 72 6e 0a 2a 2a 20 4e 55 4c 4c 2e 20 20 5e 54  urn.** NULL.  ^T
2fe10 68 65 73 65 20 72 6f 75 74 69 6e 65 20 6d 69 67  hese routine mig
2fe20 68 74 20 61 6c 73 6f 20 72 65 74 75 72 6e 20 4e  ht also return N
2fe30 55 4c 4c 20 69 66 20 61 20 6d 65 6d 6f 72 79 20  ULL if a memory 
2fe40 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72  allocation error
2fe50 0a 2a 2a 20 6f 63 63 75 72 73 2e 20 20 5e 4f 74  .** occurs.  ^Ot
2fe60 68 65 72 77 69 73 65 2c 20 74 68 65 79 20 72 65  herwise, they re
2fe70 74 75 72 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66  turn the name of
2fe80 20 74 68 65 20 61 74 74 61 63 68 65 64 20 64 61   the attached da
2fe90 74 61 62 61 73 65 2c 20 74 61 62 6c 65 2c 0a 2a  tabase, table,.*
2fea0 2a 20 6f 72 20 63 6f 6c 75 6d 6e 20 74 68 61 74  * or column that
2feb0 20 71 75 65 72 79 20 72 65 73 75 6c 74 20 63 6f   query result co
2fec0 6c 75 6d 6e 20 77 61 73 20 65 78 74 72 61 63 74  lumn was extract
2fed0 65 64 20 66 72 6f 6d 2e 0a 2a 2a 0a 2a 2a 20 5e  ed from..**.** ^
2fee0 41 73 20 77 69 74 68 20 61 6c 6c 20 6f 74 68 65  As with all othe
2fef0 72 20 53 51 4c 69 74 65 20 41 50 49 73 2c 20 74  r SQLite APIs, t
2ff00 68 6f 73 65 20 77 68 6f 73 65 20 6e 61 6d 65 73  hose whose names
2ff10 20 65 6e 64 20 77 69 74 68 20 22 31 36 22 20 72   end with "16" r
2ff20 65 74 75 72 6e 0a 2a 2a 20 55 54 46 2d 31 36 20  eturn.** UTF-16 
2ff30 65 6e 63 6f 64 65 64 20 73 74 72 69 6e 67 73 20  encoded strings 
2ff40 61 6e 64 20 74 68 65 20 6f 74 68 65 72 20 66 75  and the other fu
2ff50 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 55  nctions return U
2ff60 54 46 2d 38 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  TF-8..**.** ^The
2ff70 73 65 20 41 50 49 73 20 61 72 65 20 6f 6e 6c 79  se APIs are only
2ff80 20 61 76 61 69 6c 61 62 6c 65 20 69 66 20 74 68   available if th
2ff90 65 20 6c 69 62 72 61 72 79 20 77 61 73 20 63 6f  e library was co
2ffa0 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68 65 0a  mpiled with the.
2ffb0 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c  ** [SQLITE_ENABL
2ffc0 45 5f 43 4f 4c 55 4d 4e 5f 4d 45 54 41 44 41 54  E_COLUMN_METADAT
2ffd0 41 5d 20 43 2d 70 72 65 70 72 6f 63 65 73 73 6f  A] C-preprocesso
2ffe0 72 20 73 79 6d 62 6f 6c 2e 0a 2a 2a 0a 2a 2a 20  r symbol..**.** 
2fff0 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 74  If two or more t
30000 68 72 65 61 64 73 20 63 61 6c 6c 20 6f 6e 65 20  hreads call one 
30010 6f 72 20 6d 6f 72 65 20 6f 66 20 74 68 65 73 65  or more of these
30020 20 72 6f 75 74 69 6e 65 73 20 61 67 61 69 6e 73   routines agains
30030 74 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 70 72  t the same.** pr
30040 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
30050 20 61 6e 64 20 63 6f 6c 75 6d 6e 20 61 74 20 74   and column at t
30060 68 65 20 73 61 6d 65 20 74 69 6d 65 20 74 68 65  he same time the
30070 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72  n the results ar
30080 65 0a 2a 2a 20 75 6e 64 65 66 69 6e 65 64 2e 0a  e.** undefined..
30090 2a 2a 0a 2a 2a 20 49 66 20 74 77 6f 20 6f 72 20  **.** If two or 
300a0 6d 6f 72 65 20 74 68 72 65 61 64 73 20 63 61 6c  more threads cal
300b0 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a  l one or more.**
300c0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
300d0 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 20 7c  _database_name |
300e0 20 63 6f 6c 75 6d 6e 20 6d 65 74 61 64 61 74 61   column metadata
300f0 20 69 6e 74 65 72 66 61 63 65 73 5d 0a 2a 2a 20   interfaces].** 
30100 66 6f 72 20 74 68 65 20 73 61 6d 65 20 5b 70 72  for the same [pr
30110 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
30120 5d 20 61 6e 64 20 72 65 73 75 6c 74 20 63 6f 6c  ] and result col
30130 75 6d 6e 0a 2a 2a 20 61 74 20 74 68 65 20 73 61  umn.** at the sa
30140 6d 65 20 74 69 6d 65 20 74 68 65 6e 20 74 68 65  me time then the
30150 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64   results are und
30160 65 66 69 6e 65 64 2e 0a 2a 2f 0a 63 6f 6e 73 74  efined..*/.const
30170 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63   char *sqlite3_c
30180 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e  olumn_database_n
30190 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ame(sqlite3_stmt
301a0 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f  *,int);.const vo
301b0 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  id *sqlite3_colu
301c0 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65  mn_database_name
301d0 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  16(sqlite3_stmt*
301e0 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 63 68 61  ,int);.const cha
301f0 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  r *sqlite3_colum
30200 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 28 73 71 6c  n_table_name(sql
30210 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b  ite3_stmt*,int);
30220 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  .const void *sql
30230 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c  ite3_column_tabl
30240 65 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33  e_name16(sqlite3
30250 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e  _stmt*,int);.con
30260 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
30270 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e  _column_origin_n
30280 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ame(sqlite3_stmt
30290 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f  *,int);.const vo
302a0 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  id *sqlite3_colu
302b0 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 31 36  mn_origin_name16
302c0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69  (sqlite3_stmt*,i
302d0 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  nt);../*.** CAPI
302e0 33 52 45 46 3a 20 44 65 63 6c 61 72 65 64 20 44  3REF: Declared D
302f0 61 74 61 74 79 70 65 20 4f 66 20 41 20 51 75 65  atatype Of A Que
30300 72 79 20 52 65 73 75 6c 74 0a 2a 2a 20 4d 45 54  ry Result.** MET
30310 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d  HOD: sqlite3_stm
30320 74 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 66 69  t.**.** ^(The fi
30330 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73  rst parameter is
30340 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
30350 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 49 66 20 74  tement]..** If t
30360 68 69 73 20 73 74 61 74 65 6d 65 6e 74 20 69 73  his statement is
30370 20 61 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74   a [SELECT] stat
30380 65 6d 65 6e 74 20 61 6e 64 20 74 68 65 20 4e 74  ement and the Nt
30390 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 0a  h column of the.
303a0 2a 2a 20 72 65 74 75 72 6e 65 64 20 72 65 73 75  ** returned resu
303b0 6c 74 20 73 65 74 20 6f 66 20 74 68 61 74 20 5b  lt set of that [
303c0 53 45 4c 45 43 54 5d 20 69 73 20 61 20 74 61 62  SELECT] is a tab
303d0 6c 65 20 63 6f 6c 75 6d 6e 20 28 6e 6f 74 20 61  le column (not a
303e0 6e 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e 20  n.** expression 
303f0 6f 72 20 73 75 62 71 75 65 72 79 29 20 74 68 65  or subquery) the
30400 6e 20 74 68 65 20 64 65 63 6c 61 72 65 64 20 74  n the declared t
30410 79 70 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65  ype of the table
30420 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69 73 20 72 65  .** column is re
30430 74 75 72 6e 65 64 2e 29 5e 20 20 5e 49 66 20 74  turned.)^  ^If t
30440 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66  he Nth column of
30450 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20   the result set 
30460 69 73 20 61 6e 0a 2a 2a 20 65 78 70 72 65 73 73  is an.** express
30470 69 6f 6e 20 6f 72 20 73 75 62 71 75 65 72 79 2c  ion or subquery,
30480 20 74 68 65 6e 20 61 20 4e 55 4c 4c 20 70 6f 69   then a NULL poi
30490 6e 74 65 72 20 69 73 20 72 65 74 75 72 6e 65 64  nter is returned
304a0 2e 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75 72 6e  ..** ^The return
304b0 65 64 20 73 74 72 69 6e 67 20 69 73 20 61 6c 77  ed string is alw
304c0 61 79 73 20 55 54 46 2d 38 20 65 6e 63 6f 64 65  ays UTF-8 encode
304d0 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 46 6f 72 20 65  d..**.** ^(For e
304e0 78 61 6d 70 6c 65 2c 20 67 69 76 65 6e 20 74 68  xample, given th
304f0 65 20 64 61 74 61 62 61 73 65 20 73 63 68 65 6d  e database schem
30500 61 3a 0a 2a 2a 0a 2a 2a 20 43 52 45 41 54 45 20  a:.**.** CREATE 
30510 54 41 42 4c 45 20 74 31 28 63 31 20 56 41 52 49  TABLE t1(c1 VARI
30520 41 4e 54 29 3b 0a 2a 2a 0a 2a 2a 20 61 6e 64 20  ANT);.**.** and 
30530 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 73 74  the following st
30540 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 20 63 6f  atement to be co
30550 6d 70 69 6c 65 64 3a 0a 2a 2a 0a 2a 2a 20 53 45  mpiled:.**.** SE
30560 4c 45 43 54 20 63 31 20 2b 20 31 2c 20 63 31 20  LECT c1 + 1, c1 
30570 46 52 4f 4d 20 74 31 3b 0a 2a 2a 0a 2a 2a 20 74  FROM t1;.**.** t
30580 68 69 73 20 72 6f 75 74 69 6e 65 20 77 6f 75 6c  his routine woul
30590 64 20 72 65 74 75 72 6e 20 74 68 65 20 73 74 72  d return the str
305a0 69 6e 67 20 22 56 41 52 49 41 4e 54 22 20 66 6f  ing "VARIANT" fo
305b0 72 20 74 68 65 20 73 65 63 6f 6e 64 20 72 65 73  r the second res
305c0 75 6c 74 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 28 69  ult.** column (i
305d0 3d 3d 31 29 2c 20 61 6e 64 20 61 20 4e 55 4c 4c  ==1), and a NULL
305e0 20 70 6f 69 6e 74 65 72 20 66 6f 72 20 74 68 65   pointer for the
305f0 20 66 69 72 73 74 20 72 65 73 75 6c 74 20 63 6f   first result co
30600 6c 75 6d 6e 20 28 69 3d 3d 30 29 2e 29 5e 0a 2a  lumn (i==0).)^.*
30610 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 75 73 65  *.** ^SQLite use
30620 73 20 64 79 6e 61 6d 69 63 20 72 75 6e 2d 74 69  s dynamic run-ti
30630 6d 65 20 74 79 70 69 6e 67 2e 20 20 5e 53 6f 20  me typing.  ^So 
30640 6a 75 73 74 20 62 65 63 61 75 73 65 20 61 20 63  just because a c
30650 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20 64 65 63 6c  olumn.** is decl
30660 61 72 65 64 20 74 6f 20 63 6f 6e 74 61 69 6e 20  ared to contain 
30670 61 20 70 61 72 74 69 63 75 6c 61 72 20 74 79 70  a particular typ
30680 65 20 64 6f 65 73 20 6e 6f 74 20 6d 65 61 6e 20  e does not mean 
30690 74 68 61 74 20 74 68 65 0a 2a 2a 20 64 61 74 61  that the.** data
306a0 20 73 74 6f 72 65 64 20 69 6e 20 74 68 61 74 20   stored in that 
306b0 63 6f 6c 75 6d 6e 20 69 73 20 6f 66 20 74 68 65  column is of the
306c0 20 64 65 63 6c 61 72 65 64 20 74 79 70 65 2e 20   declared type. 
306d0 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20 73 74   SQLite is.** st
306e0 72 6f 6e 67 6c 79 20 74 79 70 65 64 2c 20 62 75  rongly typed, bu
306f0 74 20 74 68 65 20 74 79 70 69 6e 67 20 69 73 20  t the typing is 
30700 64 79 6e 61 6d 69 63 20 6e 6f 74 20 73 74 61 74  dynamic not stat
30710 69 63 2e 20 20 5e 54 79 70 65 0a 2a 2a 20 69 73  ic.  ^Type.** is
30720 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
30730 20 69 6e 64 69 76 69 64 75 61 6c 20 76 61 6c 75   individual valu
30740 65 73 2c 20 6e 6f 74 20 77 69 74 68 20 74 68 65  es, not with the
30750 20 63 6f 6e 74 61 69 6e 65 72 73 0a 2a 2a 20 75   containers.** u
30760 73 65 64 20 74 6f 20 68 6f 6c 64 20 74 68 6f 73  sed to hold thos
30770 65 20 76 61 6c 75 65 73 2e 0a 2a 2f 0a 63 6f 6e  e values..*/.con
30780 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
30790 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65  _column_decltype
307a0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69  (sqlite3_stmt*,i
307b0 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20  nt);.const void 
307c0 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
307d0 64 65 63 6c 74 79 70 65 31 36 28 73 71 6c 69 74  decltype16(sqlit
307e0 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a  e3_stmt*,int);..
307f0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
30800 45 76 61 6c 75 61 74 65 20 41 6e 20 53 51 4c 20  Evaluate An SQL 
30810 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 4d 45 54  Statement.** MET
30820 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d  HOD: sqlite3_stm
30830 74 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 61 20  t.**.** After a 
30840 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
30850 65 6e 74 5d 20 68 61 73 20 62 65 65 6e 20 70 72  ent] has been pr
30860 65 70 61 72 65 64 20 75 73 69 6e 67 20 65 69 74  epared using eit
30870 68 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  her.** [sqlite3_
30880 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72  prepare_v2()] or
30890 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
308a0 65 31 36 5f 76 32 28 29 5d 20 6f 72 20 6f 6e 65  e16_v2()] or one
308b0 20 6f 66 20 74 68 65 20 6c 65 67 61 63 79 0a 2a   of the legacy.*
308c0 2a 20 69 6e 74 65 72 66 61 63 65 73 20 5b 73 71  * interfaces [sq
308d0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d  lite3_prepare()]
308e0 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65   or [sqlite3_pre
308f0 70 61 72 65 31 36 28 29 5d 2c 20 74 68 69 73 20  pare16()], this 
30900 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74  function.** must
30910 20 62 65 20 63 61 6c 6c 65 64 20 6f 6e 65 20 6f   be called one o
30920 72 20 6d 6f 72 65 20 74 69 6d 65 73 20 74 6f 20  r more times to 
30930 65 76 61 6c 75 61 74 65 20 74 68 65 20 73 74 61  evaluate the sta
30940 74 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68  tement..**.** Th
30950 65 20 64 65 74 61 69 6c 73 20 6f 66 20 74 68 65  e details of the
30960 20 62 65 68 61 76 69 6f 72 20 6f 66 20 74 68 65   behavior of the
30970 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20   sqlite3_step() 
30980 69 6e 74 65 72 66 61 63 65 20 64 65 70 65 6e 64  interface depend
30990 0a 2a 2a 20 6f 6e 20 77 68 65 74 68 65 72 20 74  .** on whether t
309a0 68 65 20 73 74 61 74 65 6d 65 6e 74 20 77 61 73  he statement was
309b0 20 70 72 65 70 61 72 65 64 20 75 73 69 6e 67 20   prepared using 
309c0 74 68 65 20 6e 65 77 65 72 20 22 76 32 22 20 69  the newer "v2" i
309d0 6e 74 65 72 66 61 63 65 0a 2a 2a 20 5b 73 71 6c  nterface.** [sql
309e0 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
309f0 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
30a00 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20  prepare16_v2()] 
30a10 6f 72 20 74 68 65 20 6f 6c 64 65 72 20 6c 65 67  or the older leg
30a20 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  acy.** interface
30a30 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
30a40 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  e()] and [sqlite
30a50 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2e 20  3_prepare16()]. 
30a60 20 54 68 65 20 75 73 65 20 6f 66 20 74 68 65 0a   The use of the.
30a70 2a 2a 20 6e 65 77 20 22 76 32 22 20 69 6e 74 65  ** new "v2" inte
30a80 72 66 61 63 65 20 69 73 20 72 65 63 6f 6d 6d 65  rface is recomme
30a90 6e 64 65 64 20 66 6f 72 20 6e 65 77 20 61 70 70  nded for new app
30aa0 6c 69 63 61 74 69 6f 6e 73 20 62 75 74 20 74 68  lications but th
30ab0 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65  e legacy.** inte
30ac0 72 66 61 63 65 20 77 69 6c 6c 20 63 6f 6e 74 69  rface will conti
30ad0 6e 75 65 20 74 6f 20 62 65 20 73 75 70 70 6f 72  nue to be suppor
30ae0 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 20 74  ted..**.** ^In t
30af0 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66  he legacy interf
30b00 61 63 65 2c 20 74 68 65 20 72 65 74 75 72 6e 20  ace, the return 
30b10 76 61 6c 75 65 20 77 69 6c 6c 20 62 65 20 65 69  value will be ei
30b20 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 42 55 53  ther [SQLITE_BUS
30b30 59 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44  Y],.** [SQLITE_D
30b40 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 52 4f  ONE], [SQLITE_RO
30b50 57 5d 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  W], [SQLITE_ERRO
30b60 52 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4d  R], or [SQLITE_M
30b70 49 53 55 53 45 5d 2e 0a 2a 2a 20 5e 57 69 74 68  ISUSE]..** ^With
30b80 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66   the "v2" interf
30b90 61 63 65 2c 20 61 6e 79 20 6f 66 20 74 68 65 20  ace, any of the 
30ba0 6f 74 68 65 72 20 5b 72 65 73 75 6c 74 20 63 6f  other [result co
30bb0 64 65 73 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65  des] or.** [exte
30bc0 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65  nded result code
30bd0 73 5d 20 6d 69 67 68 74 20 62 65 20 72 65 74 75  s] might be retu
30be0 72 6e 65 64 20 61 73 20 77 65 6c 6c 2e 0a 2a 2a  rned as well..**
30bf0 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 42 55 53  .** ^[SQLITE_BUS
30c00 59 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68  Y] means that th
30c10 65 20 64 61 74 61 62 61 73 65 20 65 6e 67 69 6e  e database engin
30c20 65 20 77 61 73 20 75 6e 61 62 6c 65 20 74 6f 20  e was unable to 
30c30 61 63 71 75 69 72 65 20 74 68 65 0a 2a 2a 20 64  acquire the.** d
30c40 61 74 61 62 61 73 65 20 6c 6f 63 6b 73 20 69 74  atabase locks it
30c50 20 6e 65 65 64 73 20 74 6f 20 64 6f 20 69 74 73   needs to do its
30c60 20 6a 6f 62 2e 20 20 5e 49 66 20 74 68 65 20 73   job.  ^If the s
30c70 74 61 74 65 6d 65 6e 74 20 69 73 20 61 20 5b 43  tatement is a [C
30c80 4f 4d 4d 49 54 5d 0a 2a 2a 20 6f 72 20 6f 63 63  OMMIT].** or occ
30c90 75 72 73 20 6f 75 74 73 69 64 65 20 6f 66 20 61  urs outside of a
30ca0 6e 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73  n explicit trans
30cb0 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20 79 6f 75  action, then you
30cc0 20 63 61 6e 20 72 65 74 72 79 20 74 68 65 0a 2a   can retry the.*
30cd0 2a 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 49 66  * statement.  If
30ce0 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69   the statement i
30cf0 73 20 6e 6f 74 20 61 20 5b 43 4f 4d 4d 49 54 5d  s not a [COMMIT]
30d00 20 61 6e 64 20 6f 63 63 75 72 73 20 77 69 74 68   and occurs with
30d10 69 6e 20 61 6e 0a 2a 2a 20 65 78 70 6c 69 63 69  in an.** explici
30d20 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 74 68  t transaction th
30d30 65 6e 20 79 6f 75 20 73 68 6f 75 6c 64 20 72 6f  en you should ro
30d40 6c 6c 62 61 63 6b 20 74 68 65 20 74 72 61 6e 73  llback the trans
30d50 61 63 74 69 6f 6e 20 62 65 66 6f 72 65 0a 2a 2a  action before.**
30d60 20 63 6f 6e 74 69 6e 75 69 6e 67 2e 0a 2a 2a 0a   continuing..**.
30d70 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 44 4f 4e 45  ** ^[SQLITE_DONE
30d80 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65  ] means that the
30d90 20 73 74 61 74 65 6d 65 6e 74 20 68 61 73 20 66   statement has f
30da0 69 6e 69 73 68 65 64 20 65 78 65 63 75 74 69 6e  inished executin
30db0 67 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 6c  g.** successfull
30dc0 79 2e 20 20 73 71 6c 69 74 65 33 5f 73 74 65 70  y.  sqlite3_step
30dd0 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65  () should not be
30de0 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e   called again on
30df0 20 74 68 69 73 20 76 69 72 74 75 61 6c 0a 2a 2a   this virtual.**
30e00 20 6d 61 63 68 69 6e 65 20 77 69 74 68 6f 75 74   machine without
30e10 20 66 69 72 73 74 20 63 61 6c 6c 69 6e 67 20 5b   first calling [
30e20 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
30e30 20 74 6f 20 72 65 73 65 74 20 74 68 65 20 76 69   to reset the vi
30e40 72 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65  rtual.** machine
30e50 20 62 61 63 6b 20 74 6f 20 69 74 73 20 69 6e 69   back to its ini
30e60 74 69 61 6c 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a  tial state..**.*
30e70 2a 20 5e 49 66 20 74 68 65 20 53 51 4c 20 73 74  * ^If the SQL st
30e80 61 74 65 6d 65 6e 74 20 62 65 69 6e 67 20 65 78  atement being ex
30e90 65 63 75 74 65 64 20 72 65 74 75 72 6e 73 20 61  ecuted returns a
30ea0 6e 79 20 64 61 74 61 2c 20 74 68 65 6e 20 5b 53  ny data, then [S
30eb0 51 4c 49 54 45 5f 52 4f 57 5d 0a 2a 2a 20 69 73  QLITE_ROW].** is
30ec0 20 72 65 74 75 72 6e 65 64 20 65 61 63 68 20 74   returned each t
30ed0 69 6d 65 20 61 20 6e 65 77 20 72 6f 77 20 6f 66  ime a new row of
30ee0 20 64 61 74 61 20 69 73 20 72 65 61 64 79 20 66   data is ready f
30ef0 6f 72 20 70 72 6f 63 65 73 73 69 6e 67 20 62 79  or processing by
30f00 20 74 68 65 0a 2a 2a 20 63 61 6c 6c 65 72 2e 20   the.** caller. 
30f10 54 68 65 20 76 61 6c 75 65 73 20 6d 61 79 20 62  The values may b
30f20 65 20 61 63 63 65 73 73 65 64 20 75 73 69 6e 67  e accessed using
30f30 20 74 68 65 20 5b 63 6f 6c 75 6d 6e 20 61 63 63   the [column acc
30f40 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a  ess functions]..
30f50 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  ** sqlite3_step(
30f60 29 20 69 73 20 63 61 6c 6c 65 64 20 61 67 61 69  ) is called agai
30f70 6e 20 74 6f 20 72 65 74 72 69 65 76 65 20 74 68  n to retrieve th
30f80 65 20 6e 65 78 74 20 72 6f 77 20 6f 66 20 64 61  e next row of da
30f90 74 61 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49  ta..**.** ^[SQLI
30fa0 54 45 5f 45 52 52 4f 52 5d 20 6d 65 61 6e 73 20  TE_ERROR] means 
30fb0 74 68 61 74 20 61 20 72 75 6e 2d 74 69 6d 65 20  that a run-time 
30fc0 65 72 72 6f 72 20 28 73 75 63 68 20 61 73 20 61  error (such as a
30fd0 20 63 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a 20 76   constraint.** v
30fe0 69 6f 6c 61 74 69 6f 6e 29 20 68 61 73 20 6f 63  iolation) has oc
30ff0 63 75 72 72 65 64 2e 20 20 73 71 6c 69 74 65 33  curred.  sqlite3
31000 5f 73 74 65 70 28 29 20 73 68 6f 75 6c 64 20 6e  _step() should n
31010 6f 74 20 62 65 20 63 61 6c 6c 65 64 20 61 67 61  ot be called aga
31020 69 6e 20 6f 6e 0a 2a 2a 20 74 68 65 20 56 4d 2e  in on.** the VM.
31030 20 4d 6f 72 65 20 69 6e 66 6f 72 6d 61 74 69 6f   More informatio
31040 6e 20 6d 61 79 20 62 65 20 66 6f 75 6e 64 20 62  n may be found b
31050 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74  y calling [sqlit
31060 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2a  e3_errmsg()]..**
31070 20 5e 57 69 74 68 20 74 68 65 20 6c 65 67 61 63   ^With the legac
31080 79 20 69 6e 74 65 72 66 61 63 65 2c 20 61 20 6d  y interface, a m
31090 6f 72 65 20 73 70 65 63 69 66 69 63 20 65 72 72  ore specific err
310a0 6f 72 20 63 6f 64 65 20 28 66 6f 72 20 65 78 61  or code (for exa
310b0 6d 70 6c 65 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45  mple,.** [SQLITE
310c0 5f 49 4e 54 45 52 52 55 50 54 5d 2c 20 5b 53 51  _INTERRUPT], [SQ
310d0 4c 49 54 45 5f 53 43 48 45 4d 41 5d 2c 20 5b 53  LITE_SCHEMA], [S
310e0 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 5d 2c 20  QLITE_CORRUPT], 
310f0 61 6e 64 20 73 6f 20 66 6f 72 74 68 29 0a 2a 2a  and so forth).**
31100 20 63 61 6e 20 62 65 20 6f 62 74 61 69 6e 65 64   can be obtained
31110 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c   by calling [sql
31120 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 6e  ite3_reset()] on
31130 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65   the.** [prepare
31140 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20 5e  d statement].  ^
31150 49 6e 20 74 68 65 20 22 76 32 22 20 69 6e 74 65  In the "v2" inte
31160 72 66 61 63 65 2c 0a 2a 2a 20 74 68 65 20 6d 6f  rface,.** the mo
31170 72 65 20 73 70 65 63 69 66 69 63 20 65 72 72 6f  re specific erro
31180 72 20 63 6f 64 65 20 69 73 20 72 65 74 75 72 6e  r code is return
31190 65 64 20 64 69 72 65 63 74 6c 79 20 62 79 20 73  ed directly by s
311a0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 0a 2a  qlite3_step()..*
311b0 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 49 53  *.** [SQLITE_MIS
311c0 55 53 45 5d 20 6d 65 61 6e 73 20 74 68 61 74 20  USE] means that 
311d0 74 68 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65  the this routine
311e0 20 77 61 73 20 63 61 6c 6c 65 64 20 69 6e 61 70   was called inap
311f0 70 72 6f 70 72 69 61 74 65 6c 79 2e 0a 2a 2a 20  propriately..** 
31200 50 65 72 68 61 70 73 20 69 74 20 77 61 73 20 63  Perhaps it was c
31210 61 6c 6c 65 64 20 6f 6e 20 61 20 5b 70 72 65 70  alled on a [prep
31220 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
31230 74 68 61 74 20 68 61 73 0a 2a 2a 20 61 6c 72 65  that has.** alre
31240 61 64 79 20 62 65 65 6e 20 5b 73 71 6c 69 74 65  ady been [sqlite
31250 33 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 66 69 6e  3_finalize | fin
31260 61 6c 69 7a 65 64 5d 20 6f 72 20 6f 6e 20 6f 6e  alized] or on on
31270 65 20 74 68 61 74 20 68 61 64 0a 2a 2a 20 70 72  e that had.** pr
31280 65 76 69 6f 75 73 6c 79 20 72 65 74 75 72 6e 65  eviously returne
31290 64 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d  d [SQLITE_ERROR]
312a0 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45   or [SQLITE_DONE
312b0 5d 2e 20 20 4f 72 20 69 74 20 63 6f 75 6c 64 0a  ].  Or it could.
312c0 2a 2a 20 62 65 20 74 68 65 20 63 61 73 65 20 74  ** be the case t
312d0 68 61 74 20 74 68 65 20 73 61 6d 65 20 64 61 74  hat the same dat
312e0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
312f0 20 69 73 20 62 65 69 6e 67 20 75 73 65 64 20 62   is being used b
31300 79 20 74 77 6f 20 6f 72 0a 2a 2a 20 6d 6f 72 65  y two or.** more
31310 20 74 68 72 65 61 64 73 20 61 74 20 74 68 65 20   threads at the 
31320 73 61 6d 65 20 6d 6f 6d 65 6e 74 20 69 6e 20 74  same moment in t
31330 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 61  ime..**.** For a
31340 6c 6c 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53  ll versions of S
31350 51 4c 69 74 65 20 75 70 20 74 6f 20 61 6e 64 20  QLite up to and 
31360 69 6e 63 6c 75 64 69 6e 67 20 33 2e 36 2e 32 33  including 3.6.23
31370 2e 31 2c 20 61 20 63 61 6c 6c 20 74 6f 0a 2a 2a  .1, a call to.**
31380 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
31390 29 5d 20 77 61 73 20 72 65 71 75 69 72 65 64 20  )] was required 
313a0 61 66 74 65 72 20 73 71 6c 69 74 65 33 5f 73 74  after sqlite3_st
313b0 65 70 28 29 20 72 65 74 75 72 6e 65 64 20 61 6e  ep() returned an
313c0 79 74 68 69 6e 67 0a 2a 2a 20 6f 74 68 65 72 20  ything.** other 
313d0 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57  than [SQLITE_ROW
313e0 5d 20 62 65 66 6f 72 65 20 61 6e 79 20 73 75 62  ] before any sub
313f0 73 65 71 75 65 6e 74 20 69 6e 76 6f 63 61 74 69  sequent invocati
31400 6f 6e 20 6f 66 0a 2a 2a 20 73 71 6c 69 74 65 33  on of.** sqlite3
31410 5f 73 74 65 70 28 29 2e 20 20 46 61 69 6c 75 72  _step().  Failur
31420 65 20 74 6f 20 72 65 73 65 74 20 74 68 65 20 70  e to reset the p
31430 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
31440 74 20 75 73 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c  t using .** [sql
31450 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 77 6f  ite3_reset()] wo
31460 75 6c 64 20 72 65 73 75 6c 74 20 69 6e 20 61 6e  uld result in an
31470 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d   [SQLITE_MISUSE]
31480 20 72 65 74 75 72 6e 20 66 72 6f 6d 0a 2a 2a 20   return from.** 
31490 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 20  sqlite3_step(). 
314a0 20 42 75 74 20 61 66 74 65 72 20 5b 76 65 72 73   But after [vers
314b0 69 6f 6e 20 33 2e 36 2e 32 33 2e 31 5d 20 28 5b  ion 3.6.23.1] ([
314c0 64 61 74 65 6f 66 3a 33 2e 36 2e 32 33 2e 31 5d  dateof:3.6.23.1]
314d0 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 65  ,.** sqlite3_ste
314e0 70 28 29 20 62 65 67 61 6e 0a 2a 2a 20 63 61 6c  p() began.** cal
314f0 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65  ling [sqlite3_re
31500 73 65 74 28 29 5d 20 61 75 74 6f 6d 61 74 69 63  set()] automatic
31510 61 6c 6c 79 20 69 6e 20 74 68 69 73 20 63 69 72  ally in this cir
31520 63 75 6d 73 74 61 6e 63 65 20 72 61 74 68 65 72  cumstance rather
31530 0a 2a 2a 20 74 68 61 6e 20 72 65 74 75 72 6e 69  .** than returni
31540 6e 67 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53  ng [SQLITE_MISUS
31550 45 5d 2e 20 20 54 68 69 73 20 69 73 20 6e 6f 74  E].  This is not
31560 20 63 6f 6e 73 69 64 65 72 65 64 20 61 20 63 6f   considered a co
31570 6d 70 61 74 69 62 69 6c 69 74 79 0a 2a 2a 20 62  mpatibility.** b
31580 72 65 61 6b 20 62 65 63 61 75 73 65 20 61 6e 79  reak because any
31590 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 68 61   application tha
315a0 74 20 65 76 65 72 20 72 65 63 65 69 76 65 73 20  t ever receives 
315b0 61 6e 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  an SQLITE_MISUSE
315c0 20 65 72 72 6f 72 0a 2a 2a 20 69 73 20 62 72 6f   error.** is bro
315d0 6b 65 6e 20 62 79 20 64 65 66 69 6e 69 74 69 6f  ken by definitio
315e0 6e 2e 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  n.  The [SQLITE_
315f0 4f 4d 49 54 5f 41 55 54 4f 52 45 53 45 54 5d 20  OMIT_AUTORESET] 
31600 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
31610 69 6f 6e 0a 2a 2a 20 63 61 6e 20 62 65 20 75 73  ion.** can be us
31620 65 64 20 74 6f 20 72 65 73 74 6f 72 65 20 74 68  ed to restore th
31630 65 20 6c 65 67 61 63 79 20 62 65 68 61 76 69 6f  e legacy behavio
31640 72 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 47 6f 6f 66  r..**.** <b>Goof
31650 79 20 49 6e 74 65 72 66 61 63 65 20 41 6c 65 72  y Interface Aler
31660 74 3a 3c 2f 62 3e 20 49 6e 20 74 68 65 20 6c 65  t:</b> In the le
31670 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20  gacy interface, 
31680 74 68 65 20 73 71 6c 69 74 65 33 5f 73 74 65 70  the sqlite3_step
31690 28 29 0a 2a 2a 20 41 50 49 20 61 6c 77 61 79 73  ().** API always
316a0 20 72 65 74 75 72 6e 73 20 61 20 67 65 6e 65 72   returns a gener
316b0 69 63 20 65 72 72 6f 72 20 63 6f 64 65 2c 20 5b  ic error code, [
316c0 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c 20 66  SQLITE_ERROR], f
316d0 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79 0a 2a 2a 20  ollowing any.** 
316e0 65 72 72 6f 72 20 6f 74 68 65 72 20 74 68 61 6e  error other than
316f0 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 61   [SQLITE_BUSY] a
31700 6e 64 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53  nd [SQLITE_MISUS
31710 45 5d 2e 20 20 59 6f 75 20 6d 75 73 74 20 63 61  E].  You must ca
31720 6c 6c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72  ll.** [sqlite3_r
31730 65 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69  eset()] or [sqli
31740 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20  te3_finalize()] 
31750 69 6e 20 6f 72 64 65 72 20 74 6f 20 66 69 6e 64  in order to find
31760 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20 73   one of the.** s
31770 70 65 63 69 66 69 63 20 5b 65 72 72 6f 72 20 63  pecific [error c
31780 6f 64 65 73 5d 20 74 68 61 74 20 62 65 74 74 65  odes] that bette
31790 72 20 64 65 73 63 72 69 62 65 73 20 74 68 65 20  r describes the 
317a0 65 72 72 6f 72 2e 0a 2a 2a 20 57 65 20 61 64 6d  error..** We adm
317b0 69 74 20 74 68 61 74 20 74 68 69 73 20 69 73 20  it that this is 
317c0 61 20 67 6f 6f 66 79 20 64 65 73 69 67 6e 2e 20  a goofy design. 
317d0 20 54 68 65 20 70 72 6f 62 6c 65 6d 20 68 61 73   The problem has
317e0 20 62 65 65 6e 20 66 69 78 65 64 0a 2a 2a 20 77   been fixed.** w
317f0 69 74 68 20 74 68 65 20 22 76 32 22 20 69 6e 74  ith the "v2" int
31800 65 72 66 61 63 65 2e 20 20 49 66 20 79 6f 75 20  erface.  If you 
31810 70 72 65 70 61 72 65 20 61 6c 6c 20 6f 66 20 79  prepare all of y
31820 6f 75 72 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  our SQL statemen
31830 74 73 0a 2a 2a 20 75 73 69 6e 67 20 65 69 74 68  ts.** using eith
31840 65 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  er [sqlite3_prep
31850 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71  are_v2()] or [sq
31860 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
31870 76 32 28 29 5d 20 69 6e 73 74 65 61 64 0a 2a 2a  v2()] instead.**
31880 20 6f 66 20 74 68 65 20 6c 65 67 61 63 79 20 5b   of the legacy [
31890 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28  sqlite3_prepare(
318a0 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
318b0 70 72 65 70 61 72 65 31 36 28 29 5d 20 69 6e 74  prepare16()] int
318c0 65 72 66 61 63 65 73 2c 0a 2a 2a 20 74 68 65 6e  erfaces,.** then
318d0 20 74 68 65 20 6d 6f 72 65 20 73 70 65 63 69 66   the more specif
318e0 69 63 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d  ic [error codes]
318f0 20 61 72 65 20 72 65 74 75 72 6e 65 64 20 64 69   are returned di
31900 72 65 63 74 6c 79 0a 2a 2a 20 62 79 20 73 71 6c  rectly.** by sql
31910 69 74 65 33 5f 73 74 65 70 28 29 2e 20 20 54 68  ite3_step().  Th
31920 65 20 75 73 65 20 6f 66 20 74 68 65 20 22 76 32  e use of the "v2
31930 22 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 72  " interface is r
31940 65 63 6f 6d 6d 65 6e 64 65 64 2e 0a 2a 2f 0a 69  ecommended..*/.i
31950 6e 74 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  nt sqlite3_step(
31960 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a  sqlite3_stmt*);.
31970 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
31980 20 4e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d   Number of colum
31990 6e 73 20 69 6e 20 61 20 72 65 73 75 6c 74 20 73  ns in a result s
319a0 65 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  et.** METHOD: sq
319b0 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a  lite3_stmt.**.**
319c0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61   ^The sqlite3_da
319d0 74 61 5f 63 6f 75 6e 74 28 50 29 20 69 6e 74 65  ta_count(P) inte
319e0 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68  rface returns th
319f0 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75  e number of colu
31a00 6d 6e 73 20 69 6e 20 74 68 65 0a 2a 2a 20 63 75  mns in the.** cu
31a10 72 72 65 6e 74 20 72 6f 77 20 6f 66 20 74 68 65  rrent row of the
31a20 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 5b   result set of [
31a30 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
31a40 6e 74 5d 20 50 2e 0a 2a 2a 20 5e 49 66 20 70 72  nt] P..** ^If pr
31a50 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
31a60 20 50 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 65   P does not have
31a70 20 72 65 73 75 6c 74 73 20 72 65 61 64 79 20 74   results ready t
31a80 6f 20 72 65 74 75 72 6e 0a 2a 2a 20 28 76 69 61  o return.** (via
31a90 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 20 5b 73   calls to the [s
31aa0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e  qlite3_column_in
31ab0 74 20 7c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  t | sqlite3_colu
31ac0 6d 6e 5f 2a 28 29 5d 20 6f 66 0a 2a 2a 20 69 6e  mn_*()] of.** in
31ad0 74 65 72 66 61 63 65 73 29 20 74 68 65 6e 20 73  terfaces) then s
31ae0 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e  qlite3_data_coun
31af0 74 28 50 29 20 72 65 74 75 72 6e 73 20 30 2e 0a  t(P) returns 0..
31b00 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
31b10 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 20 72 6f  data_count(P) ro
31b20 75 74 69 6e 65 20 61 6c 73 6f 20 72 65 74 75 72  utine also retur
31b30 6e 73 20 30 20 69 66 20 50 20 69 73 20 61 20 4e  ns 0 if P is a N
31b40 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 20  ULL pointer..** 
31b50 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74  ^The sqlite3_dat
31b60 61 5f 63 6f 75 6e 74 28 50 29 20 72 6f 75 74 69  a_count(P) routi
31b70 6e 65 20 72 65 74 75 72 6e 73 20 30 20 69 66 20  ne returns 0 if 
31b80 74 68 65 20 70 72 65 76 69 6f 75 73 20 63 61 6c  the previous cal
31b90 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  l to.** [sqlite3
31ba0 5f 73 74 65 70 5d 28 50 29 20 72 65 74 75 72 6e  _step](P) return
31bb0 65 64 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d  ed [SQLITE_DONE]
31bc0 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  .  ^The sqlite3_
31bd0 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 0a 2a 2a  data_count(P).**
31be0 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 6e 6f 6e   will return non
31bf0 2d 7a 65 72 6f 20 69 66 20 70 72 65 76 69 6f 75  -zero if previou
31c00 73 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  s call to [sqlit
31c10 65 33 5f 73 74 65 70 5d 28 50 29 20 72 65 74 75  e3_step](P) retu
31c20 72 6e 65 64 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  rned.** [SQLITE_
31c30 52 4f 57 5d 2c 20 65 78 63 65 70 74 20 69 6e 20  ROW], except in 
31c40 74 68 65 20 63 61 73 65 20 6f 66 20 74 68 65 20  the case of the 
31c50 5b 50 52 41 47 4d 41 20 69 6e 63 72 65 6d 65 6e  [PRAGMA incremen
31c60 74 61 6c 5f 76 61 63 75 75 6d 5d 0a 2a 2a 20 77  tal_vacuum].** w
31c70 68 65 72 65 20 69 74 20 61 6c 77 61 79 73 20 72  here it always r
31c80 65 74 75 72 6e 73 20 7a 65 72 6f 20 73 69 6e 63  eturns zero sinc
31c90 65 20 65 61 63 68 20 73 74 65 70 20 6f 66 20 74  e each step of t
31ca0 68 61 74 20 6d 75 6c 74 69 2d 73 74 65 70 0a 2a  hat multi-step.*
31cb0 2a 20 70 72 61 67 6d 61 20 72 65 74 75 72 6e 73  * pragma returns
31cc0 20 30 20 63 6f 6c 75 6d 6e 73 20 6f 66 20 64 61   0 columns of da
31cd0 74 61 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  ta..**.** See al
31ce0 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  so: [sqlite3_col
31cf0 75 6d 6e 5f 63 6f 75 6e 74 28 29 5d 0a 2a 2f 0a  umn_count()].*/.
31d00 69 6e 74 20 73 71 6c 69 74 65 33 5f 64 61 74 61  int sqlite3_data
31d10 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73  _count(sqlite3_s
31d20 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a  tmt *pStmt);../*
31d30 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 75  .** CAPI3REF: Fu
31d40 6e 64 61 6d 65 6e 74 61 6c 20 44 61 74 61 74 79  ndamental Dataty
31d50 70 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  pes.** KEYWORDS:
31d60 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 2a 2a 0a   SQLITE_TEXT.**.
31d70 2a 2a 20 5e 28 45 76 65 72 79 20 76 61 6c 75 65  ** ^(Every value
31d80 20 69 6e 20 53 51 4c 69 74 65 20 68 61 73 20 6f   in SQLite has o
31d90 6e 65 20 6f 66 20 66 69 76 65 20 66 75 6e 64 61  ne of five funda
31da0 6d 65 6e 74 61 6c 20 64 61 74 61 74 79 70 65 73  mental datatypes
31db0 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  :.**.** <ul>.** 
31dc0 3c 6c 69 3e 20 36 34 2d 62 69 74 20 73 69 67 6e  <li> 64-bit sign
31dd0 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 6c  ed integer.** <l
31de0 69 3e 20 36 34 2d 62 69 74 20 49 45 45 45 20 66  i> 64-bit IEEE f
31df0 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 6e 75  loating point nu
31e00 6d 62 65 72 0a 2a 2a 20 3c 6c 69 3e 20 73 74 72  mber.** <li> str
31e10 69 6e 67 0a 2a 2a 20 3c 6c 69 3e 20 42 4c 4f 42  ing.** <li> BLOB
31e20 0a 2a 2a 20 3c 6c 69 3e 20 4e 55 4c 4c 0a 2a 2a  .** <li> NULL.**
31e30 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54   </ul>)^.**.** T
31e40 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61  hese constants a
31e50 72 65 20 63 6f 64 65 73 20 66 6f 72 20 65 61 63  re codes for eac
31e60 68 20 6f 66 20 74 68 6f 73 65 20 74 79 70 65 73  h of those types
31e70 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61  ..**.** Note tha
31e80 74 20 74 68 65 20 53 51 4c 49 54 45 5f 54 45 58  t the SQLITE_TEX
31e90 54 20 63 6f 6e 73 74 61 6e 74 20 77 61 73 20 61  T constant was a
31ea0 6c 73 6f 20 75 73 65 64 20 69 6e 20 53 51 4c 69  lso used in SQLi
31eb0 74 65 20 76 65 72 73 69 6f 6e 20 32 0a 2a 2a 20  te version 2.** 
31ec0 66 6f 72 20 61 20 63 6f 6d 70 6c 65 74 65 6c 79  for a completely
31ed0 20 64 69 66 66 65 72 65 6e 74 20 6d 65 61 6e 69   different meani
31ee0 6e 67 2e 20 20 53 6f 66 74 77 61 72 65 20 74 68  ng.  Software th
31ef0 61 74 20 6c 69 6e 6b 73 20 61 67 61 69 6e 73 74  at links against
31f00 20 62 6f 74 68 0a 2a 2a 20 53 51 4c 69 74 65 20   both.** SQLite 
31f10 76 65 72 73 69 6f 6e 20 32 20 61 6e 64 20 53 51  version 2 and SQ
31f20 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 20 73  Lite version 3 s
31f30 68 6f 75 6c 64 20 75 73 65 20 53 51 4c 49 54 45  hould use SQLITE
31f40 33 5f 54 45 58 54 2c 20 6e 6f 74 0a 2a 2a 20 53  3_TEXT, not.** S
31f50 51 4c 49 54 45 5f 54 45 58 54 2e 0a 2a 2f 0a 23  QLITE_TEXT..*/.#
31f60 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e  define SQLITE_IN
31f70 54 45 47 45 52 20 20 31 0a 23 64 65 66 69 6e 65  TEGER  1.#define
31f80 20 53 51 4c 49 54 45 5f 46 4c 4f 41 54 20 20 20   SQLITE_FLOAT   
31f90 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   2.#define SQLIT
31fa0 45 5f 42 4c 4f 42 20 20 20 20 20 34 0a 23 64 65  E_BLOB     4.#de
31fb0 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 55 4c 4c  fine SQLITE_NULL
31fc0 20 20 20 20 20 35 0a 23 69 66 64 65 66 20 53 51       5.#ifdef SQ
31fd0 4c 49 54 45 5f 54 45 58 54 0a 23 20 75 6e 64 65  LITE_TEXT.# unde
31fe0 66 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 23 65  f SQLITE_TEXT.#e
31ff0 6c 73 65 0a 23 20 64 65 66 69 6e 65 20 53 51 4c  lse.# define SQL
32000 49 54 45 5f 54 45 58 54 20 20 20 20 20 33 0a 23  ITE_TEXT     3.#
32010 65 6e 64 69 66 0a 23 64 65 66 69 6e 65 20 53 51  endif.#define SQ
32020 4c 49 54 45 33 5f 54 45 58 54 20 20 20 20 20 33  LITE3_TEXT     3
32030 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
32040 3a 20 52 65 73 75 6c 74 20 56 61 6c 75 65 73 20  : Result Values 
32050 46 72 6f 6d 20 41 20 51 75 65 72 79 0a 2a 2a 20  From A Query.** 
32060 4b 45 59 57 4f 52 44 53 3a 20 7b 63 6f 6c 75 6d  KEYWORDS: {colum
32070 6e 20 61 63 63 65 73 73 20 66 75 6e 63 74 69 6f  n access functio
32080 6e 73 7d 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  ns}.** METHOD: s
32090 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a  qlite3_stmt.**.*
320a0 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65  * ^These routine
320b0 73 20 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d 61  s return informa
320c0 74 69 6f 6e 20 61 62 6f 75 74 20 61 20 73 69 6e  tion about a sin
320d0 67 6c 65 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68  gle column of th
320e0 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 72 65 73  e current.** res
320f0 75 6c 74 20 72 6f 77 20 6f 66 20 61 20 71 75 65  ult row of a que
32100 72 79 2e 20 20 5e 49 6e 20 65 76 65 72 79 20 63  ry.  ^In every c
32110 61 73 65 20 74 68 65 20 66 69 72 73 74 20 61 72  ase the first ar
32120 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e  gument is a poin
32130 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 70  ter.** to the [p
32140 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
32150 74 5d 20 74 68 61 74 20 69 73 20 62 65 69 6e 67  t] that is being
32160 20 65 76 61 6c 75 61 74 65 64 20 28 74 68 65 20   evaluated (the 
32170 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 5d 0a  [sqlite3_stmt*].
32180 2a 2a 20 74 68 61 74 20 77 61 73 20 72 65 74 75  ** that was retu
32190 72 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74  rned from [sqlit
321a0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
321b0 20 6f 72 20 6f 6e 65 20 6f 66 20 69 74 73 20 76   or one of its v
321c0 61 72 69 61 6e 74 73 29 0a 2a 2a 20 61 6e 64 20  ariants).** and 
321d0 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  the second argum
321e0 65 6e 74 20 69 73 20 74 68 65 20 69 6e 64 65 78  ent is the index
321f0 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20 66   of the column f
32200 6f 72 20 77 68 69 63 68 20 69 6e 66 6f 72 6d 61  or which informa
32210 74 69 6f 6e 0a 2a 2a 20 73 68 6f 75 6c 64 20 62  tion.** should b
32220 65 20 72 65 74 75 72 6e 65 64 2e 20 5e 54 68 65  e returned. ^The
32230 20 6c 65 66 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e   leftmost column
32240 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73   of the result s
32250 65 74 20 68 61 73 20 74 68 65 20 69 6e 64 65 78  et has the index
32260 20 30 2e 0a 2a 2a 20 5e 54 68 65 20 6e 75 6d 62   0..** ^The numb
32270 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e  er of columns in
32280 20 74 68 65 20 72 65 73 75 6c 74 20 63 61 6e 20   the result can 
32290 62 65 20 64 65 74 65 72 6d 69 6e 65 64 20 75 73  be determined us
322a0 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ing.** [sqlite3_
322b0 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 29 5d 2e  column_count()].
322c0 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 53 51  .**.** If the SQ
322d0 4c 20 73 74 61 74 65 6d 65 6e 74 20 64 6f 65 73  L statement does
322e0 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79 20 70   not currently p
322f0 6f 69 6e 74 20 74 6f 20 61 20 76 61 6c 69 64 20  oint to a valid 
32300 72 6f 77 2c 20 6f 72 20 69 66 20 74 68 65 0a 2a  row, or if the.*
32310 2a 20 63 6f 6c 75 6d 6e 20 69 6e 64 65 78 20 69  * column index i
32320 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 2c 20  s out of range, 
32330 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 75 6e  the result is un
32340 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 73  defined..** Thes
32350 65 20 72 6f 75 74 69 6e 65 73 20 6d 61 79 20 6f  e routines may o
32360 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64 20 77 68  nly be called wh
32370 65 6e 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  en the most rece
32380 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73  nt call to.** [s
32390 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 68  qlite3_step()] h
323a0 61 73 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c  as returned [SQL
323b0 49 54 45 5f 52 4f 57 5d 20 61 6e 64 20 6e 65 69  ITE_ROW] and nei
323c0 74 68 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ther.** [sqlite3
323d0 5f 72 65 73 65 74 28 29 5d 20 6e 6f 72 20 5b 73  _reset()] nor [s
323e0 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
323f0 29 5d 20 68 61 76 65 20 62 65 65 6e 20 63 61 6c  )] have been cal
32400 6c 65 64 20 73 75 62 73 65 71 75 65 6e 74 6c 79  led subsequently
32410 2e 0a 2a 2a 20 49 66 20 61 6e 79 20 6f 66 20 74  ..** If any of t
32420 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72  hese routines ar
32430 65 20 63 61 6c 6c 65 64 20 61 66 74 65 72 20 5b  e called after [
32440 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
32450 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   or.** [sqlite3_
32460 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 61  finalize()] or a
32470 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 73 74  fter [sqlite3_st
32480 65 70 28 29 5d 20 68 61 73 20 72 65 74 75 72 6e  ep()] has return
32490 65 64 0a 2a 2a 20 73 6f 6d 65 74 68 69 6e 67 20  ed.** something 
324a0 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49  other than [SQLI
324b0 54 45 5f 52 4f 57 5d 2c 20 74 68 65 20 72 65 73  TE_ROW], the res
324c0 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e  ults are undefin
324d0 65 64 2e 0a 2a 2a 20 49 66 20 5b 73 71 6c 69 74  ed..** If [sqlit
324e0 65 33 5f 73 74 65 70 28 29 5d 20 6f 72 20 5b 73  e3_step()] or [s
324f0 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
32500 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  or [sqlite3_fina
32510 6c 69 7a 65 28 29 5d 0a 2a 2a 20 61 72 65 20 63  lize()].** are c
32520 61 6c 6c 65 64 20 66 72 6f 6d 20 61 20 64 69 66  alled from a dif
32530 66 65 72 65 6e 74 20 74 68 72 65 61 64 20 77 68  ferent thread wh
32540 69 6c 65 20 61 6e 79 20 6f 66 20 74 68 65 73 65  ile any of these
32550 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 61 72 65   routines.** are
32560 20 70 65 6e 64 69 6e 67 2c 20 74 68 65 6e 20 74   pending, then t
32570 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 75  he results are u
32580 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  ndefined..**.** 
32590 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c  ^The sqlite3_col
325a0 75 6d 6e 5f 74 79 70 65 28 29 20 72 6f 75 74 69  umn_type() routi
325b0 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 0a 2a  ne returns the.*
325c0 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45  * [SQLITE_INTEGE
325d0 52 20 7c 20 64 61 74 61 74 79 70 65 20 63 6f 64  R | datatype cod
325e0 65 5d 20 66 6f 72 20 74 68 65 20 69 6e 69 74 69  e] for the initi
325f0 61 6c 20 64 61 74 61 20 74 79 70 65 0a 2a 2a 20  al data type.** 
32600 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 63 6f  of the result co
32610 6c 75 6d 6e 2e 20 20 5e 54 68 65 20 72 65 74 75  lumn.  ^The retu
32620 72 6e 65 64 20 76 61 6c 75 65 20 69 73 20 6f 6e  rned value is on
32630 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 49 4e 54  e of [SQLITE_INT
32640 45 47 45 52 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54  EGER],.** [SQLIT
32650 45 5f 46 4c 4f 41 54 5d 2c 20 5b 53 51 4c 49 54  E_FLOAT], [SQLIT
32660 45 5f 54 45 58 54 5d 2c 20 5b 53 51 4c 49 54 45  E_TEXT], [SQLITE
32670 5f 42 4c 4f 42 5d 2c 20 6f 72 20 5b 53 51 4c 49  _BLOB], or [SQLI
32680 54 45 5f 4e 55 4c 4c 5d 2e 20 20 54 68 65 20 76  TE_NULL].  The v
32690 61 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64  alue.** returned
326a0 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   by sqlite3_colu
326b0 6d 6e 5f 74 79 70 65 28 29 20 69 73 20 6f 6e 6c  mn_type() is onl
326c0 79 20 6d 65 61 6e 69 6e 67 66 75 6c 20 69 66 20  y meaningful if 
326d0 6e 6f 20 74 79 70 65 0a 2a 2a 20 63 6f 6e 76 65  no type.** conve
326e0 72 73 69 6f 6e 73 20 68 61 76 65 20 6f 63 63 75  rsions have occu
326f0 72 72 65 64 20 61 73 20 64 65 73 63 72 69 62 65  rred as describe
32700 64 20 62 65 6c 6f 77 2e 20 20 41 66 74 65 72 20  d below.  After 
32710 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f  a type conversio
32720 6e 2c 0a 2a 2a 20 74 68 65 20 76 61 6c 75 65 20  n,.** the value 
32730 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69  returned by sqli
32740 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28  te3_column_type(
32750 29 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 20  ) is undefined. 
32760 20 46 75 74 75 72 65 0a 2a 2a 20 76 65 72 73 69   Future.** versi
32770 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 61  ons of SQLite ma
32780 79 20 63 68 61 6e 67 65 20 74 68 65 20 62 65 68  y change the beh
32790 61 76 69 6f 72 20 6f 66 20 73 71 6c 69 74 65 33  avior of sqlite3
327a0 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 0a 2a  _column_type().*
327b0 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 74 79  * following a ty
327c0 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a  pe conversion..*
327d0 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73  *.** ^If the res
327e0 75 6c 74 20 69 73 20 61 20 42 4c 4f 42 20 6f 72  ult is a BLOB or
327f0 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20 74 68   UTF-8 string th
32800 65 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63  en the sqlite3_c
32810 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 0a 2a 2a  olumn_bytes().**
32820 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
32830 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62   the number of b
32840 79 74 65 73 20 69 6e 20 74 68 61 74 20 42 4c 4f  ytes in that BLO
32850 42 20 6f 72 20 73 74 72 69 6e 67 2e 0a 2a 2a 20  B or string..** 
32860 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69  ^If the result i
32870 73 20 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e  s a UTF-16 strin
32880 67 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  g, then sqlite3_
32890 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 63  column_bytes() c
328a0 6f 6e 76 65 72 74 73 0a 2a 2a 20 74 68 65 20 73  onverts.** the s
328b0 74 72 69 6e 67 20 74 6f 20 55 54 46 2d 38 20 61  tring to UTF-8 a
328c0 6e 64 20 74 68 65 6e 20 72 65 74 75 72 6e 73 20  nd then returns 
328d0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  the number of by
328e0 74 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  tes..** ^If the 
328f0 72 65 73 75 6c 74 20 69 73 20 61 20 6e 75 6d 65  result is a nume
32900 72 69 63 20 76 61 6c 75 65 20 74 68 65 6e 20 73  ric value then s
32910 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
32920 74 65 73 28 29 20 75 73 65 73 0a 2a 2a 20 5b 73  tes() uses.** [s
32930 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28  qlite3_snprintf(
32940 29 5d 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68  )] to convert th
32950 61 74 20 76 61 6c 75 65 20 74 6f 20 61 20 55 54  at value to a UT
32960 46 2d 38 20 73 74 72 69 6e 67 20 61 6e 64 20 72  F-8 string and r
32970 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 75  eturns.** the nu
32980 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e  mber of bytes in
32990 20 74 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a   that string..**
329a0 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20   ^If the result 
329b0 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 73 71  is NULL, then sq
329c0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
329d0 65 73 28 29 20 72 65 74 75 72 6e 73 20 7a 65 72  es() returns zer
329e0 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  o..**.** ^If the
329f0 20 72 65 73 75 6c 74 20 69 73 20 61 20 42 4c 4f   result is a BLO
32a00 42 20 6f 72 20 55 54 46 2d 31 36 20 73 74 72 69  B or UTF-16 stri
32a10 6e 67 20 74 68 65 6e 20 74 68 65 20 73 71 6c 69  ng then the sqli
32a20 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
32a30 31 36 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20  16().** routine 
32a40 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62  returns the numb
32a50 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74  er of bytes in t
32a60 68 61 74 20 42 4c 4f 42 20 6f 72 20 73 74 72 69  hat BLOB or stri
32a70 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72  ng..** ^If the r
32a80 65 73 75 6c 74 20 69 73 20 61 20 55 54 46 2d 38  esult is a UTF-8
32a90 20 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 73 71   string, then sq
32aa0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
32ab0 65 73 31 36 28 29 20 63 6f 6e 76 65 72 74 73 0a  es16() converts.
32ac0 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 20 74 6f  ** the string to
32ad0 20 55 54 46 2d 31 36 20 61 6e 64 20 74 68 65 6e   UTF-16 and then
32ae0 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d   returns the num
32af0 62 65 72 20 6f 66 20 62 79 74 65 73 2e 0a 2a 2a  ber of bytes..**
32b00 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20   ^If the result 
32b10 69 73 20 61 20 6e 75 6d 65 72 69 63 20 76 61 6c  is a numeric val
32b20 75 65 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  ue then sqlite3_
32b30 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29  column_bytes16()
32b40 20 75 73 65 73 0a 2a 2a 20 5b 73 71 6c 69 74 65   uses.** [sqlite
32b50 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 74 6f  3_snprintf()] to
32b60 20 63 6f 6e 76 65 72 74 20 74 68 61 74 20 76 61   convert that va
32b70 6c 75 65 20 74 6f 20 61 20 55 54 46 2d 31 36 20  lue to a UTF-16 
32b80 73 74 72 69 6e 67 20 61 6e 64 20 72 65 74 75 72  string and retur
32b90 6e 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72  ns.** the number
32ba0 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 61   of bytes in tha
32bb0 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66  t string..** ^If
32bc0 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 4e   the result is N
32bd0 55 4c 4c 2c 20 74 68 65 6e 20 73 71 6c 69 74 65  ULL, then sqlite
32be0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36  3_column_bytes16
32bf0 28 29 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e  () returns zero.
32c00 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 76 61 6c 75  .**.** ^The valu
32c10 65 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b  es returned by [
32c20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
32c30 79 74 65 73 28 29 5d 20 61 6e 64 20 0a 2a 2a 20  ytes()] and .** 
32c40 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
32c50 62 79 74 65 73 31 36 28 29 5d 20 64 6f 20 6e 6f  bytes16()] do no
32c60 74 20 69 6e 63 6c 75 64 65 20 74 68 65 20 7a 65  t include the ze
32c70 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 73 20 61  ro terminators a
32c80 74 20 74 68 65 20 65 6e 64 0a 2a 2a 20 6f 66 20  t the end.** of 
32c90 74 68 65 20 73 74 72 69 6e 67 2e 20 20 5e 46 6f  the string.  ^Fo
32ca0 72 20 63 6c 61 72 69 74 79 3a 20 74 68 65 20 76  r clarity: the v
32cb0 61 6c 75 65 73 20 72 65 74 75 72 6e 65 64 20 62  alues returned b
32cc0 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  y.** [sqlite3_co
32cd0 6c 75 6d 6e 5f 62 79 74 65 73 28 29 5d 20 61 6e  lumn_bytes()] an
32ce0 64 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  d [sqlite3_colum
32cf0 6e 5f 62 79 74 65 73 31 36 28 29 5d 20 61 72 65  n_bytes16()] are
32d00 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a   the number of.*
32d10 2a 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 73  * bytes in the s
32d20 74 72 69 6e 67 2c 20 6e 6f 74 20 74 68 65 20 6e  tring, not the n
32d30 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63 74  umber of charact
32d40 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 53 74 72 69  ers..**.** ^Stri
32d50 6e 67 73 20 72 65 74 75 72 6e 65 64 20 62 79 20  ngs returned by 
32d60 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
32d70 65 78 74 28 29 20 61 6e 64 20 73 71 6c 69 74 65  ext() and sqlite
32d80 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28  3_column_text16(
32d90 29 2c 0a 2a 2a 20 65 76 65 6e 20 65 6d 70 74 79  ),.** even empty
32da0 20 73 74 72 69 6e 67 73 2c 20 61 72 65 20 61 6c   strings, are al
32db0 77 61 79 73 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  ways zero-termin
32dc0 61 74 65 64 2e 20 20 5e 54 68 65 20 72 65 74 75  ated.  ^The retu
32dd0 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 66 72 6f 6d  rn.** value from
32de0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
32df0 62 6c 6f 62 28 29 20 66 6f 72 20 61 20 7a 65 72  blob() for a zer
32e00 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f 42 20 69 73  o-length BLOB is
32e10 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e   a NULL pointer.
32e20 0a 2a 2a 0a 2a 2a 20 3c 62 3e 57 61 72 6e 69 6e  .**.** <b>Warnin
32e30 67 3a 3c 2f 62 3e 20 5e 54 68 65 20 6f 62 6a 65  g:</b> ^The obje
32e40 63 74 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b  ct returned by [
32e50 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76  sqlite3_column_v
32e60 61 6c 75 65 28 29 5d 20 69 73 20 61 6e 0a 2a 2a  alue()] is an.**
32e70 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71   [unprotected sq
32e80 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
32e90 65 63 74 2e 20 20 49 6e 20 61 20 6d 75 6c 74 69  ect.  In a multi
32ea0 74 68 72 65 61 64 65 64 20 65 6e 76 69 72 6f 6e  threaded environ
32eb0 6d 65 6e 74 2c 0a 2a 2a 20 61 6e 20 75 6e 70 72  ment,.** an unpr
32ec0 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
32ed0 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 6d 61 79  value object may
32ee0 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 20 73 61   only be used sa
32ef0 66 65 6c 79 20 77 69 74 68 0a 2a 2a 20 5b 73 71  fely with.** [sq
32f00 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65  lite3_bind_value
32f10 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
32f20 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 5d  _result_value()]
32f30 2e 0a 2a 2a 20 49 66 20 74 68 65 20 5b 75 6e 70  ..** If the [unp
32f40 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
32f50 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 72  _value] object r
32f60 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73  eturned by.** [s
32f70 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61  qlite3_column_va
32f80 6c 75 65 28 29 5d 20 69 73 20 75 73 65 64 20 69  lue()] is used i
32f90 6e 20 61 6e 79 20 6f 74 68 65 72 20 77 61 79 2c  n any other way,
32fa0 20 69 6e 63 6c 75 64 69 6e 67 20 63 61 6c 6c 73   including calls
32fb0 0a 2a 2a 20 74 6f 20 72 6f 75 74 69 6e 65 73 20  .** to routines 
32fc0 6c 69 6b 65 20 5b 73 71 6c 69 74 65 33 5f 76 61  like [sqlite3_va
32fd0 6c 75 65 5f 69 6e 74 28 29 5d 2c 20 5b 73 71 6c  lue_int()], [sql
32fe0 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28  ite3_value_text(
32ff0 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74  )],.** or [sqlit
33000 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 29  e3_value_bytes()
33010 5d 2c 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  ], the behavior 
33020 69 73 20 6e 6f 74 20 74 68 72 65 61 64 73 61 66  is not threadsaf
33030 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  e..**.** These r
33040 6f 75 74 69 6e 65 73 20 61 74 74 65 6d 70 74 20  outines attempt 
33050 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 65 20 76  to convert the v
33060 61 6c 75 65 20 77 68 65 72 65 20 61 70 70 72 6f  alue where appro
33070 70 72 69 61 74 65 2e 20 20 5e 46 6f 72 0a 2a 2a  priate.  ^For.**
33080 20 65 78 61 6d 70 6c 65 2c 20 69 66 20 74 68 65   example, if the
33090 20 69 6e 74 65 72 6e 61 6c 20 72 65 70 72 65 73   internal repres
330a0 65 6e 74 61 74 69 6f 6e 20 69 73 20 46 4c 4f 41  entation is FLOA
330b0 54 20 61 6e 64 20 61 20 74 65 78 74 20 72 65 73  T and a text res
330c0 75 6c 74 0a 2a 2a 20 69 73 20 72 65 71 75 65 73  ult.** is reques
330d0 74 65 64 2c 20 5b 73 71 6c 69 74 65 33 5f 73 6e  ted, [sqlite3_sn
330e0 70 72 69 6e 74 66 28 29 5d 20 69 73 20 75 73 65  printf()] is use
330f0 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 74 6f 20  d internally to 
33100 70 65 72 66 6f 72 6d 20 74 68 65 0a 2a 2a 20 63  perform the.** c
33110 6f 6e 76 65 72 73 69 6f 6e 20 61 75 74 6f 6d 61  onversion automa
33120 74 69 63 61 6c 6c 79 2e 20 20 5e 28 54 68 65 20  tically.  ^(The 
33130 66 6f 6c 6c 6f 77 69 6e 67 20 74 61 62 6c 65 20  following table 
33140 64 65 74 61 69 6c 73 20 74 68 65 20 63 6f 6e 76  details the conv
33150 65 72 73 69 6f 6e 73 0a 2a 2a 20 74 68 61 74 20  ersions.** that 
33160 61 72 65 20 61 70 70 6c 69 65 64 3a 0a 2a 2a 0a  are applied:.**.
33170 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a  ** <blockquote>.
33180 2a 2a 20 3c 74 61 62 6c 65 20 62 6f 72 64 65 72  ** <table border
33190 3d 22 31 22 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68  ="1">.** <tr><th
331a0 3e 20 49 6e 74 65 72 6e 61 6c 3c 62 72 3e 54 79  > Internal<br>Ty
331b0 70 65 20 3c 74 68 3e 20 52 65 71 75 65 73 74 65  pe <th> Requeste
331c0 64 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e 20 20  d<br>Type <th>  
331d0 43 6f 6e 76 65 72 73 69 6f 6e 0a 2a 2a 0a 2a 2a  Conversion.**.**
331e0 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20   <tr><td>  NULL 
331f0 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20     <td> INTEGER 
33200 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73    <td> Result is
33210 20 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20   0.** <tr><td>  
33220 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 46 4c  NULL    <td>  FL
33230 4f 41 54 20 20 20 20 3c 74 64 3e 20 52 65 73 75  OAT    <td> Resu
33240 6c 74 20 69 73 20 30 2e 30 0a 2a 2a 20 3c 74 72  lt is 0.0.** <tr
33250 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c  ><td>  NULL    <
33260 74 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74  td>   TEXT    <t
33270 64 3e 20 52 65 73 75 6c 74 20 69 73 20 61 20 4e  d> Result is a N
33280 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c  ULL pointer.** <
33290 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20  tr><td>  NULL   
332a0 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20   <td>   BLOB    
332b0 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 61  <td> Result is a
332c0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a   NULL pointer.**
332d0 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45   <tr><td> INTEGE
332e0 52 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20  R  <td>  FLOAT  
332f0 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 66    <td> Convert f
33300 72 6f 6d 20 69 6e 74 65 67 65 72 20 74 6f 20 66  rom integer to f
33310 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  loat.** <tr><td>
33320 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20   INTEGER  <td>  
33330 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41 53   TEXT    <td> AS
33340 43 49 49 20 72 65 6e 64 65 72 69 6e 67 20 6f 66  CII rendering of
33350 20 74 68 65 20 69 6e 74 65 67 65 72 0a 2a 2a 20   the integer.** 
33360 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52  <tr><td> INTEGER
33370 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20    <td>   BLOB   
33380 20 3c 74 64 3e 20 53 61 6d 65 20 61 73 20 49 4e   <td> Same as IN
33390 54 45 47 45 52 2d 3e 54 45 58 54 0a 2a 2a 20 3c  TEGER->TEXT.** <
333a0 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20  tr><td>  FLOAT  
333b0 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20   <td> INTEGER   
333c0 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20 49  <td> [CAST] to I
333d0 4e 54 45 47 45 52 0a 2a 2a 20 3c 74 72 3e 3c 74  NTEGER.** <tr><t
333e0 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e  d>  FLOAT   <td>
333f0 20 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20     TEXT    <td> 
33400 41 53 43 49 49 20 72 65 6e 64 65 72 69 6e 67 20  ASCII rendering 
33410 6f 66 20 74 68 65 20 66 6c 6f 61 74 0a 2a 2a 20  of the float.** 
33420 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20  <tr><td>  FLOAT 
33430 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20    <td>   BLOB   
33440 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20   <td> [CAST] to 
33450 42 4c 4f 42 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  BLOB.** <tr><td>
33460 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 49    TEXT    <td> I
33470 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 5b 43  NTEGER   <td> [C
33480 41 53 54 5d 20 74 6f 20 49 4e 54 45 47 45 52 0a  AST] to INTEGER.
33490 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58  ** <tr><td>  TEX
334a0 54 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54  T    <td>  FLOAT
334b0 20 20 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20      <td> [CAST] 
334c0 74 6f 20 52 45 41 4c 0a 2a 2a 20 3c 74 72 3e 3c  to REAL.** <tr><
334d0 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64  td>  TEXT    <td
334e0 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e  >   BLOB    <td>
334f0 20 4e 6f 20 63 68 61 6e 67 65 0a 2a 2a 20 3c 74   No change.** <t
33500 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20  r><td>  BLOB    
33510 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c  <td> INTEGER   <
33520 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20 49 4e  td> [CAST] to IN
33530 54 45 47 45 52 0a 2a 2a 20 3c 74 72 3e 3c 74 64  TEGER.** <tr><td
33540 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20  >  BLOB    <td> 
33550 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 5b   FLOAT    <td> [
33560 43 41 53 54 5d 20 74 6f 20 52 45 41 4c 0a 2a 2a  CAST] to REAL.**
33570 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20   <tr><td>  BLOB 
33580 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20     <td>   TEXT  
33590 20 20 3c 74 64 3e 20 41 64 64 20 61 20 7a 65 72    <td> Add a zer
335a0 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20 69 66 20  o terminator if 
335b0 6e 65 65 64 65 64 0a 2a 2a 20 3c 2f 74 61 62 6c  needed.** </tabl
335c0 65 3e 0a 2a 2a 20 3c 2f 62 6c 6f 63 6b 71 75 6f  e>.** </blockquo
335d0 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65  te>)^.**.** Note
335e0 20 74 68 61 74 20 77 68 65 6e 20 74 79 70 65 20   that when type 
335f0 63 6f 6e 76 65 72 73 69 6f 6e 73 20 6f 63 63 75  conversions occu
33600 72 2c 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75  r, pointers retu
33610 72 6e 65 64 20 62 79 20 70 72 69 6f 72 0a 2a 2a  rned by prior.**
33620 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65   calls to sqlite
33630 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c  3_column_blob(),
33640 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
33650 74 65 78 74 28 29 2c 20 61 6e 64 2f 6f 72 0a 2a  text(), and/or.*
33660 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  * sqlite3_column
33670 5f 74 65 78 74 31 36 28 29 20 6d 61 79 20 62 65  _text16() may be
33680 20 69 6e 76 61 6c 69 64 61 74 65 64 2e 0a 2a 2a   invalidated..**
33690 20 54 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e   Type conversion
336a0 73 20 61 6e 64 20 70 6f 69 6e 74 65 72 20 69 6e  s and pointer in
336b0 76 61 6c 69 64 61 74 69 6f 6e 73 20 6d 69 67 68  validations migh
336c0 74 20 6f 63 63 75 72 0a 2a 2a 20 69 6e 20 74 68  t occur.** in th
336d0 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 63 61 73 65  e following case
336e0 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  s:.**.** <ul>.**
336f0 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74 69 61   <li> The initia
33700 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 61 20 42  l content is a B
33710 4c 4f 42 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  LOB and sqlite3_
33720 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 6f 72  column_text() or
33730 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 74 65 33  .**      sqlite3
33740 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29  _column_text16()
33750 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 41 20 7a   is called.  A z
33760 65 72 6f 2d 74 65 72 6d 69 6e 61 74 6f 72 20 6d  ero-terminator m
33770 69 67 68 74 0a 2a 2a 20 20 20 20 20 20 6e 65 65  ight.**      nee
33780 64 20 74 6f 20 62 65 20 61 64 64 65 64 20 74 6f  d to be added to
33790 20 74 68 65 20 73 74 72 69 6e 67 2e 3c 2f 6c 69   the string.</li
337a0 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e  >.** <li> The in
337b0 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73  itial content is
337c0 20 55 54 46 2d 38 20 74 65 78 74 20 61 6e 64 20   UTF-8 text and 
337d0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
337e0 79 74 65 73 31 36 28 29 20 6f 72 0a 2a 2a 20 20  ytes16() or.**  
337f0 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75      sqlite3_colu
33800 6d 6e 5f 74 65 78 74 31 36 28 29 20 69 73 20 63  mn_text16() is c
33810 61 6c 6c 65 64 2e 20 20 54 68 65 20 63 6f 6e 74  alled.  The cont
33820 65 6e 74 20 6d 75 73 74 20 62 65 20 63 6f 6e 76  ent must be conv
33830 65 72 74 65 64 0a 2a 2a 20 20 20 20 20 20 74 6f  erted.**      to
33840 20 55 54 46 2d 31 36 2e 3c 2f 6c 69 3e 0a 2a 2a   UTF-16.</li>.**
33850 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74 69 61   <li> The initia
33860 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 55 54 46  l content is UTF
33870 2d 31 36 20 74 65 78 74 20 61 6e 64 20 73 71 6c  -16 text and sql
33880 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
33890 73 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73  s() or.**      s
338a0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
338b0 78 74 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20  xt() is called. 
338c0 20 54 68 65 20 63 6f 6e 74 65 6e 74 20 6d 75 73   The content mus
338d0 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64 0a 2a  t be converted.*
338e0 2a 20 20 20 20 20 20 74 6f 20 55 54 46 2d 38 2e  *      to UTF-8.
338f0 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a  </li>.** </ul>.*
33900 2a 0a 2a 2a 20 5e 43 6f 6e 76 65 72 73 69 6f 6e  *.** ^Conversion
33910 73 20 62 65 74 77 65 65 6e 20 55 54 46 2d 31 36  s between UTF-16
33920 62 65 20 61 6e 64 20 55 54 46 2d 31 36 6c 65 20  be and UTF-16le 
33930 61 72 65 20 61 6c 77 61 79 73 20 64 6f 6e 65 20  are always done 
33940 69 6e 20 70 6c 61 63 65 20 61 6e 64 20 64 6f 0a  in place and do.
33950 2a 2a 20 6e 6f 74 20 69 6e 76 61 6c 69 64 61 74  ** not invalidat
33960 65 20 61 20 70 72 69 6f 72 20 70 6f 69 6e 74 65  e a prior pointe
33970 72 2c 20 74 68 6f 75 67 68 20 6f 66 20 63 6f 75  r, though of cou
33980 72 73 65 20 74 68 65 20 63 6f 6e 74 65 6e 74 20  rse the content 
33990 6f 66 20 74 68 65 20 62 75 66 66 65 72 0a 2a 2a  of the buffer.**
339a0 20 74 68 61 74 20 74 68 65 20 70 72 69 6f 72 20   that the prior 
339b0 70 6f 69 6e 74 65 72 20 72 65 66 65 72 65 6e 63  pointer referenc
339c0 65 73 20 77 69 6c 6c 20 68 61 76 65 20 62 65 65  es will have bee
339d0 6e 20 6d 6f 64 69 66 69 65 64 2e 20 20 4f 74 68  n modified.  Oth
339e0 65 72 20 6b 69 6e 64 73 0a 2a 2a 20 6f 66 20 63  er kinds.** of c
339f0 6f 6e 76 65 72 73 69 6f 6e 20 61 72 65 20 64 6f  onversion are do
33a00 6e 65 20 69 6e 20 70 6c 61 63 65 20 77 68 65 6e  ne in place when
33a10 20 69 74 20 69 73 20 70 6f 73 73 69 62 6c 65 2c   it is possible,
33a20 20 62 75 74 20 73 6f 6d 65 74 69 6d 65 73 20 74   but sometimes t
33a30 68 65 79 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 70  hey.** are not p
33a40 6f 73 73 69 62 6c 65 20 61 6e 64 20 69 6e 20 74  ossible and in t
33a50 68 6f 73 65 20 63 61 73 65 73 20 70 72 69 6f 72  hose cases prior
33a60 20 70 6f 69 6e 74 65 72 73 20 61 72 65 20 69 6e   pointers are in
33a70 76 61 6c 69 64 61 74 65 64 2e 0a 2a 2a 0a 2a 2a  validated..**.**
33a80 20 54 68 65 20 73 61 66 65 73 74 20 70 6f 6c 69   The safest poli
33a90 63 79 20 69 73 20 74 6f 20 69 6e 76 6f 6b 65 20  cy is to invoke 
33aa0 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a  these routines.*
33ab0 2a 20 69 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20  * in one of the 
33ac0 66 6f 6c 6c 6f 77 69 6e 67 20 77 61 79 73 3a 0a  following ways:.
33ad0 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 3c  **.** <ul>.**  <
33ae0 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  li>sqlite3_colum
33af0 6e 5f 74 65 78 74 28 29 20 66 6f 6c 6c 6f 77 65  n_text() followe
33b00 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c  d by sqlite3_col
33b10 75 6d 6e 5f 62 79 74 65 73 28 29 3c 2f 6c 69 3e  umn_bytes()</li>
33b20 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33  .**  <li>sqlite3
33b30 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66  _column_blob() f
33b40 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74  ollowed by sqlit
33b50 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
33b60 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73  )</li>.**  <li>s
33b70 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
33b80 78 74 31 36 28 29 20 66 6f 6c 6c 6f 77 65 64 20  xt16() followed 
33b90 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  by sqlite3_colum
33ba0 6e 5f 62 79 74 65 73 31 36 28 29 3c 2f 6c 69 3e  n_bytes16()</li>
33bb0 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20  .** </ul>.**.** 
33bc0 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20  In other words, 
33bd0 79 6f 75 20 73 68 6f 75 6c 64 20 63 61 6c 6c 20  you should call 
33be0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
33bf0 65 78 74 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65  ext(),.** sqlite
33c00 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c  3_column_blob(),
33c10 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   or sqlite3_colu
33c20 6d 6e 5f 74 65 78 74 31 36 28 29 20 66 69 72 73  mn_text16() firs
33c30 74 20 74 6f 20 66 6f 72 63 65 20 74 68 65 20 72  t to force the r
33c40 65 73 75 6c 74 0a 2a 2a 20 69 6e 74 6f 20 74 68  esult.** into th
33c50 65 20 64 65 73 69 72 65 64 20 66 6f 72 6d 61 74  e desired format
33c60 2c 20 74 68 65 6e 20 69 6e 76 6f 6b 65 20 73 71  , then invoke sq
33c70 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
33c80 65 73 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74  es() or.** sqlit
33c90 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
33ca0 36 28 29 20 74 6f 20 66 69 6e 64 20 74 68 65 20  6() to find the 
33cb0 73 69 7a 65 20 6f 66 20 74 68 65 20 72 65 73 75  size of the resu
33cc0 6c 74 2e 20 20 44 6f 20 6e 6f 74 20 6d 69 78 20  lt.  Do not mix 
33cd0 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 73 71 6c 69  calls.** to sqli
33ce0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
33cf0 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c  ) or sqlite3_col
33d00 75 6d 6e 5f 62 6c 6f 62 28 29 20 77 69 74 68 20  umn_blob() with 
33d10 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 73 71 6c 69  calls to.** sqli
33d20 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
33d30 31 36 28 29 2c 20 61 6e 64 20 64 6f 20 6e 6f 74  16(), and do not
33d40 20 6d 69 78 20 63 61 6c 6c 73 20 74 6f 20 73 71   mix calls to sq
33d50 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
33d60 74 31 36 28 29 0a 2a 2a 20 77 69 74 68 20 63 61  t16().** with ca
33d70 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  lls to sqlite3_c
33d80 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 2e 0a 2a  olumn_bytes()..*
33d90 2a 0a 2a 2a 20 5e 54 68 65 20 70 6f 69 6e 74 65  *.** ^The pointe
33da0 72 73 20 72 65 74 75 72 6e 65 64 20 61 72 65 20  rs returned are 
33db0 76 61 6c 69 64 20 75 6e 74 69 6c 20 61 20 74 79  valid until a ty
33dc0 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20 6f 63  pe conversion oc
33dd0 63 75 72 73 20 61 73 0a 2a 2a 20 64 65 73 63 72  curs as.** descr
33de0 69 62 65 64 20 61 62 6f 76 65 2c 20 6f 72 20 75  ibed above, or u
33df0 6e 74 69 6c 20 5b 73 71 6c 69 74 65 33 5f 73 74  ntil [sqlite3_st
33e00 65 70 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  ep()] or [sqlite
33e10 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a  3_reset()] or.**
33e20 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
33e30 7a 65 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 2e  ze()] is called.
33e40 20 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20 73 70    ^The memory sp
33e50 61 63 65 20 75 73 65 64 20 74 6f 20 68 6f 6c 64  ace used to hold
33e60 20 73 74 72 69 6e 67 73 0a 2a 2a 20 61 6e 64 20   strings.** and 
33e70 42 4c 4f 42 73 20 69 73 20 66 72 65 65 64 20 61  BLOBs is freed a
33e80 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20 44  utomatically.  D
33e90 6f 20 3c 65 6d 3e 6e 6f 74 3c 2f 65 6d 3e 20 70  o <em>not</em> p
33ea0 61 73 73 20 74 68 65 20 70 6f 69 6e 74 65 72 73  ass the pointers
33eb0 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 66 72 6f   returned.** fro
33ec0 6d 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  m [sqlite3_colum
33ed0 6e 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c 69  n_blob()], [sqli
33ee0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
33ef0 29 5d 2c 20 65 74 63 2e 20 69 6e 74 6f 0a 2a 2a  )], etc. into.**
33f00 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
33f10 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 61 20  ]..**.** ^(If a 
33f20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
33f30 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 64  n error occurs d
33f40 75 72 69 6e 67 20 74 68 65 20 65 76 61 6c 75 61  uring the evalua
33f50 74 69 6f 6e 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f  tion of any.** o
33f60 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  f these routines
33f70 2c 20 61 20 64 65 66 61 75 6c 74 20 76 61 6c 75  , a default valu
33f80 65 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20  e is returned.  
33f90 54 68 65 20 64 65 66 61 75 6c 74 20 76 61 6c 75  The default valu
33fa0 65 0a 2a 2a 20 69 73 20 65 69 74 68 65 72 20 74  e.** is either t
33fb0 68 65 20 69 6e 74 65 67 65 72 20 30 2c 20 74 68  he integer 0, th
33fc0 65 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74  e floating point
33fd0 20 6e 75 6d 62 65 72 20 30 2e 30 2c 20 6f 72 20   number 0.0, or 
33fe0 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65  a NULL.** pointe
33ff0 72 2e 20 20 53 75 62 73 65 71 75 65 6e 74 20 63  r.  Subsequent c
34000 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33  alls to [sqlite3
34010 5f 65 72 72 63 6f 64 65 28 29 5d 20 77 69 6c 6c  _errcode()] will
34020 20 72 65 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49   return.** [SQLI
34030 54 45 5f 4e 4f 4d 45 4d 5d 2e 29 5e 0a 2a 2f 0a  TE_NOMEM].)^.*/.
34040 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
34050 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28  te3_column_blob(
34060 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
34070 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71  nt iCol);.int sq
34080 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
34090 65 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  es(sqlite3_stmt*
340a0 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74  , int iCol);.int
340b0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
340c0 62 79 74 65 73 31 36 28 73 71 6c 69 74 65 33 5f  bytes16(sqlite3_
340d0 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
340e0 3b 0a 64 6f 75 62 6c 65 20 73 71 6c 69 74 65 33  ;.double sqlite3
340f0 5f 63 6f 6c 75 6d 6e 5f 64 6f 75 62 6c 65 28 73  _column_double(s
34100 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
34110 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c  t iCol);.int sql
34120 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 28  ite3_column_int(
34130 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
34140 6e 74 20 69 43 6f 6c 29 3b 0a 73 71 6c 69 74 65  nt iCol);.sqlite
34150 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f  3_int64 sqlite3_
34160 63 6f 6c 75 6d 6e 5f 69 6e 74 36 34 28 73 71 6c  column_int64(sql
34170 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
34180 69 43 6f 6c 29 3b 0a 63 6f 6e 73 74 20 75 6e 73  iCol);.const uns
34190 69 67 6e 65 64 20 63 68 61 72 20 2a 73 71 6c 69  igned char *sqli
341a0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
341b0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
341c0 6e 74 20 69 43 6f 6c 29 3b 0a 63 6f 6e 73 74 20  nt iCol);.const 
341d0 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f  void *sqlite3_co
341e0 6c 75 6d 6e 5f 74 65 78 74 31 36 28 73 71 6c 69  lumn_text16(sqli
341f0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69  te3_stmt*, int i
34200 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  Col);.int sqlite
34210 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 73 71  3_column_type(sq
34220 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
34230 20 69 43 6f 6c 29 3b 0a 73 71 6c 69 74 65 33 5f   iCol);.sqlite3_
34240 76 61 6c 75 65 20 2a 73 71 6c 69 74 65 33 5f 63  value *sqlite3_c
34250 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 73 71 6c 69  olumn_value(sqli
34260 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69  te3_stmt*, int i
34270 43 6f 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  Col);../*.** CAP
34280 49 33 52 45 46 3a 20 44 65 73 74 72 6f 79 20 41  I3REF: Destroy A
34290 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d   Prepared Statem
342a0 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 20 44 45  ent Object.** DE
342b0 53 54 52 55 43 54 4f 52 3a 20 73 71 6c 69 74 65  STRUCTOR: sqlite
342c0 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68  3_stmt.**.** ^Th
342d0 65 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69  e sqlite3_finali
342e0 7a 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73  ze() function is
342f0 20 63 61 6c 6c 65 64 20 74 6f 20 64 65 6c 65 74   called to delet
34300 65 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74  e a [prepared st
34310 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 49 66  atement]..** ^If
34320 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
34330 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20 74   evaluation of t
34340 68 65 20 73 74 61 74 65 6d 65 6e 74 20 65 6e 63  he statement enc
34350 6f 75 6e 74 65 72 65 64 20 6e 6f 20 65 72 72 6f  ountered no erro
34360 72 73 0a 2a 2a 20 6f 72 20 69 66 20 74 68 65 20  rs.** or if the 
34370 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6e 65 76  statement is nev
34380 65 72 20 62 65 65 6e 20 65 76 61 6c 75 61 74 65  er been evaluate
34390 64 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  d, then sqlite3_
343a0 66 69 6e 61 6c 69 7a 65 28 29 20 72 65 74 75 72  finalize() retur
343b0 6e 73 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f 4b 2e  ns.** SQLITE_OK.
343c0 20 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72    ^If the most r
343d0 65 63 65 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e  ecent evaluation
343e0 20 6f 66 20 73 74 61 74 65 6d 65 6e 74 20 53 20   of statement S 
343f0 66 61 69 6c 65 64 2c 20 74 68 65 6e 0a 2a 2a 20  failed, then.** 
34400 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
34410 28 53 29 20 72 65 74 75 72 6e 73 20 74 68 65 20  (S) returns the 
34420 61 70 70 72 6f 70 72 69 61 74 65 20 5b 65 72 72  appropriate [err
34430 6f 72 20 63 6f 64 65 5d 20 6f 72 0a 2a 2a 20 5b  or code] or.** [
34440 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63  extended error c
34450 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ode]..**.** ^The
34460 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a   sqlite3_finaliz
34470 65 28 53 29 20 72 6f 75 74 69 6e 65 20 63 61 6e  e(S) routine can
34480 20 62 65 20 63 61 6c 6c 65 64 20 61 74 20 61 6e   be called at an
34490 79 20 70 6f 69 6e 74 20 64 75 72 69 6e 67 0a 2a  y point during.*
344a0 2a 20 74 68 65 20 6c 69 66 65 20 63 79 63 6c 65  * the life cycle
344b0 20 6f 66 20 5b 70 72 65 70 61 72 65 64 20 73 74   of [prepared st
344c0 61 74 65 6d 65 6e 74 5d 20 53 3a 0a 2a 2a 20 62  atement] S:.** b
344d0 65 66 6f 72 65 20 73 74 61 74 65 6d 65 6e 74 20  efore statement 
344e0 53 20 69 73 20 65 76 65 72 20 65 76 61 6c 75 61  S is ever evalua
344f0 74 65 64 2c 20 61 66 74 65 72 0a 2a 2a 20 6f 6e  ted, after.** on
34500 65 20 6f 72 20 6d 6f 72 65 20 63 61 6c 6c 73 20  e or more calls 
34510 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  to [sqlite3_rese
34520 74 28 29 5d 2c 20 6f 72 20 61 66 74 65 72 20 61  t()], or after a
34530 6e 79 20 63 61 6c 6c 0a 2a 2a 20 74 6f 20 5b 73  ny call.** to [s
34540 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 72  qlite3_step()] r
34550 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65  egardless of whe
34560 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20  ther or not the 
34570 73 74 61 74 65 6d 65 6e 74 20 68 61 73 0a 2a 2a  statement has.**
34580 20 63 6f 6d 70 6c 65 74 65 64 20 65 78 65 63 75   completed execu
34590 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 76  tion..**.** ^Inv
345a0 6f 6b 69 6e 67 20 73 71 6c 69 74 65 33 5f 66 69  oking sqlite3_fi
345b0 6e 61 6c 69 7a 65 28 29 20 6f 6e 20 61 20 4e 55  nalize() on a NU
345c0 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 61 20  LL pointer is a 
345d0 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a  harmless no-op..
345e0 2a 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63  **.** The applic
345f0 61 74 69 6f 6e 20 6d 75 73 74 20 66 69 6e 61 6c  ation must final
34600 69 7a 65 20 65 76 65 72 79 20 5b 70 72 65 70 61  ize every [prepa
34610 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69  red statement] i
34620 6e 20 6f 72 64 65 72 20 74 6f 20 61 76 6f 69 64  n order to avoid
34630 0a 2a 2a 20 72 65 73 6f 75 72 63 65 20 6c 65 61  .** resource lea
34640 6b 73 2e 20 20 49 74 20 69 73 20 61 20 67 72 69  ks.  It is a gri
34650 65 76 6f 75 73 20 65 72 72 6f 72 20 66 6f 72 20  evous error for 
34660 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
34670 74 6f 20 74 72 79 20 74 6f 20 75 73 65 0a 2a 2a  to try to use.**
34680 20 61 20 70 72 65 70 61 72 65 64 20 73 74 61 74   a prepared stat
34690 65 6d 65 6e 74 20 61 66 74 65 72 20 69 74 20 68  ement after it h
346a0 61 73 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65  as been finalize
346b0 64 2e 20 20 41 6e 79 20 75 73 65 20 6f 66 20 61  d.  Any use of a
346c0 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74 61   prepared.** sta
346d0 74 65 6d 65 6e 74 20 61 66 74 65 72 20 69 74 20  tement after it 
346e0 68 61 73 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a  has been finaliz
346f0 65 64 20 63 61 6e 20 72 65 73 75 6c 74 20 69 6e  ed can result in
34700 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 0a 2a   undefined and.*
34710 2a 20 75 6e 64 65 73 69 72 61 62 6c 65 20 62 65  * undesirable be
34720 68 61 76 69 6f 72 20 73 75 63 68 20 61 73 20 73  havior such as s
34730 65 67 66 61 75 6c 74 73 20 61 6e 64 20 68 65 61  egfaults and hea
34740 70 20 63 6f 72 72 75 70 74 69 6f 6e 2e 0a 2a 2f  p corruption..*/
34750 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 66 69 6e  .int sqlite3_fin
34760 61 6c 69 7a 65 28 73 71 6c 69 74 65 33 5f 73 74  alize(sqlite3_st
34770 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a  mt *pStmt);../*.
34780 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73  ** CAPI3REF: Res
34790 65 74 20 41 20 50 72 65 70 61 72 65 64 20 53 74  et A Prepared St
347a0 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a  atement Object.*
347b0 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65  * METHOD: sqlite
347c0 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 54 68 65  3_stmt.**.** The
347d0 20 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29   sqlite3_reset()
347e0 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 61 6c   function is cal
347f0 6c 65 64 20 74 6f 20 72 65 73 65 74 20 61 20 5b  led to reset a [
34800 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
34810 6e 74 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 62 61  nt].** object ba
34820 63 6b 20 74 6f 20 69 74 73 20 69 6e 69 74 69 61  ck to its initia
34830 6c 20 73 74 61 74 65 2c 20 72 65 61 64 79 20 74  l state, ready t
34840 6f 20 62 65 20 72 65 2d 65 78 65 63 75 74 65 64  o be re-executed
34850 2e 0a 2a 2a 20 5e 41 6e 79 20 53 51 4c 20 73 74  ..** ^Any SQL st
34860 61 74 65 6d 65 6e 74 20 76 61 72 69 61 62 6c 65  atement variable
34870 73 20 74 68 61 74 20 68 61 64 20 76 61 6c 75 65  s that had value
34880 73 20 62 6f 75 6e 64 20 74 6f 20 74 68 65 6d 20  s bound to them 
34890 75 73 69 6e 67 0a 2a 2a 20 74 68 65 20 5b 73 71  using.** the [sq
348a0 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20  lite3_bind_blob 
348b0 7c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a  | sqlite3_bind_*
348c0 28 29 20 41 50 49 5d 20 72 65 74 61 69 6e 20 74  () API] retain t
348d0 68 65 69 72 20 76 61 6c 75 65 73 2e 0a 2a 2a 20  heir values..** 
348e0 55 73 65 20 5b 73 71 6c 69 74 65 33 5f 63 6c 65  Use [sqlite3_cle
348f0 61 72 5f 62 69 6e 64 69 6e 67 73 28 29 5d 20 74  ar_bindings()] t
34900 6f 20 72 65 73 65 74 20 74 68 65 20 62 69 6e 64  o reset the bind
34910 69 6e 67 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ings..**.** ^The
34920 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
34930 53 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65  S)] interface re
34940 73 65 74 73 20 74 68 65 20 5b 70 72 65 70 61 72  sets the [prepar
34950 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 0a  ed statement] S.
34960 2a 2a 20 62 61 63 6b 20 74 6f 20 74 68 65 20 62  ** back to the b
34970 65 67 69 6e 6e 69 6e 67 20 6f 66 20 69 74 73 20  eginning of its 
34980 70 72 6f 67 72 61 6d 2e 0a 2a 2a 0a 2a 2a 20 5e  program..**.** ^
34990 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  If the most rece
349a0 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  nt call to [sqli
349b0 74 65 33 5f 73 74 65 70 28 53 29 5d 20 66 6f 72  te3_step(S)] for
349c0 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65   the.** [prepare
349d0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 72  d statement] S r
349e0 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f  eturned [SQLITE_
349f0 52 4f 57 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f  ROW] or [SQLITE_
34a00 44 4f 4e 45 5d 2c 0a 2a 2a 20 6f 72 20 69 66 20  DONE],.** or if 
34a10 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29  [sqlite3_step(S)
34a20 5d 20 68 61 73 20 6e 65 76 65 72 20 62 65 66 6f  ] has never befo
34a30 72 65 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 6f  re been called o
34a40 6e 20 53 2c 0a 2a 2a 20 74 68 65 6e 20 5b 73 71  n S,.** then [sq
34a50 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20  lite3_reset(S)] 
34a60 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f  returns [SQLITE_
34a70 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  OK]..**.** ^If t
34a80 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63  he most recent c
34a90 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
34aa0 73 74 65 70 28 53 29 5d 20 66 6f 72 20 74 68 65  step(S)] for the
34ab0 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74  .** [prepared st
34ac0 61 74 65 6d 65 6e 74 5d 20 53 20 69 6e 64 69 63  atement] S indic
34ad0 61 74 65 64 20 61 6e 20 65 72 72 6f 72 2c 20 74  ated an error, t
34ae0 68 65 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  hen.** [sqlite3_
34af0 72 65 73 65 74 28 53 29 5d 20 72 65 74 75 72 6e  reset(S)] return
34b00 73 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65  s an appropriate
34b10 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a   [error code]..*
34b20 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74  *.** ^The [sqlit
34b30 65 33 5f 72 65 73 65 74 28 53 29 5d 20 69 6e 74  e3_reset(S)] int
34b40 65 72 66 61 63 65 20 64 6f 65 73 20 6e 6f 74 20  erface does not 
34b50 63 68 61 6e 67 65 20 74 68 65 20 76 61 6c 75 65  change the value
34b60 73 0a 2a 2a 20 6f 66 20 61 6e 79 20 5b 73 71 6c  s.** of any [sql
34b70 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 62  ite3_bind_blob|b
34b80 69 6e 64 69 6e 67 73 5d 20 6f 6e 20 74 68 65 20  indings] on the 
34b90 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
34ba0 65 6e 74 5d 20 53 2e 0a 2a 2f 0a 69 6e 74 20 73  ent] S..*/.int s
34bb0 71 6c 69 74 65 33 5f 72 65 73 65 74 28 73 71 6c  qlite3_reset(sql
34bc0 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74  ite3_stmt *pStmt
34bd0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
34be0 45 46 3a 20 43 72 65 61 74 65 20 4f 72 20 52 65  EF: Create Or Re
34bf0 64 65 66 69 6e 65 20 53 51 4c 20 46 75 6e 63 74  define SQL Funct
34c00 69 6f 6e 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  ions.** KEYWORDS
34c10 3a 20 7b 66 75 6e 63 74 69 6f 6e 20 63 72 65 61  : {function crea
34c20 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 7d 0a 2a  tion routines}.*
34c30 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61 70 70  * KEYWORDS: {app
34c40 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
34c50 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 7d 0a 2a   SQL function}.*
34c60 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61 70 70  * KEYWORDS: {app
34c70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
34c80 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 7d 0a   SQL functions}.
34c90 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
34ca0 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20  e3.**.** ^These 
34cb0 66 75 6e 63 74 69 6f 6e 73 20 28 63 6f 6c 6c 65  functions (colle
34cc0 63 74 69 76 65 6c 79 20 6b 6e 6f 77 6e 20 61 73  ctively known as
34cd0 20 22 66 75 6e 63 74 69 6f 6e 20 63 72 65 61 74   "function creat
34ce0 69 6f 6e 20 72 6f 75 74 69 6e 65 73 22 29 0a 2a  ion routines").*
34cf0 2a 20 61 72 65 20 75 73 65 64 20 74 6f 20 61 64  * are used to ad
34d00 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20  d SQL functions 
34d10 6f 72 20 61 67 67 72 65 67 61 74 65 73 20 6f 72  or aggregates or
34d20 20 74 6f 20 72 65 64 65 66 69 6e 65 20 74 68 65   to redefine the
34d30 20 62 65 68 61 76 69 6f 72 0a 2a 2a 20 6f 66 20   behavior.** of 
34d40 65 78 69 73 74 69 6e 67 20 53 51 4c 20 66 75 6e  existing SQL fun
34d50 63 74 69 6f 6e 73 20 6f 72 20 61 67 67 72 65 67  ctions or aggreg
34d60 61 74 65 73 2e 20 20 54 68 65 20 6f 6e 6c 79 20  ates.  The only 
34d70 64 69 66 66 65 72 65 6e 63 65 73 20 62 65 74 77  differences betw
34d80 65 65 6e 0a 2a 2a 20 74 68 65 73 65 20 72 6f 75  een.** these rou
34d90 74 69 6e 65 73 20 61 72 65 20 74 68 65 20 74 65  tines are the te
34da0 78 74 20 65 6e 63 6f 64 69 6e 67 20 65 78 70 65  xt encoding expe
34db0 63 74 65 64 20 66 6f 72 0a 2a 2a 20 74 68 65 20  cted for.** the 
34dc0 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
34dd0 20 28 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68   (the name of th
34de0 65 20 66 75 6e 63 74 69 6f 6e 20 62 65 69 6e 67  e function being
34df0 20 63 72 65 61 74 65 64 29 0a 2a 2a 20 61 6e 64   created).** and
34e00 20 74 68 65 20 70 72 65 73 65 6e 63 65 20 6f 72   the presence or
34e10 20 61 62 73 65 6e 63 65 20 6f 66 20 61 20 64 65   absence of a de
34e20 73 74 72 75 63 74 6f 72 20 63 61 6c 6c 62 61 63  structor callbac
34e30 6b 20 66 6f 72 0a 2a 2a 20 74 68 65 20 61 70 70  k for.** the app
34e40 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20 70 6f  lication data po
34e50 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  inter..**.** ^Th
34e60 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
34e70 72 20 69 73 20 74 68 65 20 5b 64 61 74 61 62 61  r is the [databa
34e80 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74  se connection] t
34e90 6f 20 77 68 69 63 68 20 74 68 65 20 53 51 4c 0a  o which the SQL.
34ea0 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 74  ** function is t
34eb0 6f 20 62 65 20 61 64 64 65 64 2e 20 20 5e 49 66  o be added.  ^If
34ec0 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20   an application 
34ed0 75 73 65 73 20 6d 6f 72 65 20 74 68 61 6e 20 6f  uses more than o
34ee0 6e 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63  ne database.** c
34ef0 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 65 6e 20 61  onnection then a
34f00 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
34f10 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  ed SQL functions
34f20 20 6d 75 73 74 20 62 65 20 61 64 64 65 64 0a 2a   must be added.*
34f30 2a 20 74 6f 20 65 61 63 68 20 64 61 74 61 62 61  * to each databa
34f40 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 65  se connection se
34f50 70 61 72 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20  parately..**.** 
34f60 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61  ^The second para
34f70 6d 65 74 65 72 20 69 73 20 74 68 65 20 6e 61 6d  meter is the nam
34f80 65 20 6f 66 20 74 68 65 20 53 51 4c 20 66 75 6e  e of the SQL fun
34f90 63 74 69 6f 6e 20 74 6f 20 62 65 20 63 72 65 61  ction to be crea
34fa0 74 65 64 20 6f 72 0a 2a 2a 20 72 65 64 65 66 69  ted or.** redefi
34fb0 6e 65 64 2e 20 20 5e 54 68 65 20 6c 65 6e 67 74  ned.  ^The lengt
34fc0 68 20 6f 66 20 74 68 65 20 6e 61 6d 65 20 69 73  h of the name is
34fd0 20 6c 69 6d 69 74 65 64 20 74 6f 20 32 35 35 20   limited to 255 
34fe0 62 79 74 65 73 20 69 6e 20 61 20 55 54 46 2d 38  bytes in a UTF-8
34ff0 0a 2a 2a 20 72 65 70 72 65 73 65 6e 74 61 74 69  .** representati
35000 6f 6e 2c 20 65 78 63 6c 75 73 69 76 65 20 6f 66  on, exclusive of
35010 20 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e   the zero-termin
35020 61 74 6f 72 2e 20 20 5e 4e 6f 74 65 20 74 68 61  ator.  ^Note tha
35030 74 20 74 68 65 20 6e 61 6d 65 0a 2a 2a 20 6c 65  t the name.** le
35040 6e 67 74 68 20 6c 69 6d 69 74 20 69 73 20 69 6e  ngth limit is in
35050 20 55 54 46 2d 38 20 62 79 74 65 73 2c 20 6e 6f   UTF-8 bytes, no
35060 74 20 63 68 61 72 61 63 74 65 72 73 20 6e 6f 72  t characters nor
35070 20 55 54 46 2d 31 36 20 62 79 74 65 73 2e 20 20   UTF-16 bytes.  
35080 0a 2a 2a 20 5e 41 6e 79 20 61 74 74 65 6d 70 74  .** ^Any attempt
35090 20 74 6f 20 63 72 65 61 74 65 20 61 20 66 75 6e   to create a fun
350a0 63 74 69 6f 6e 20 77 69 74 68 20 61 20 6c 6f 6e  ction with a lon
350b0 67 65 72 20 6e 61 6d 65 0a 2a 2a 20 77 69 6c 6c  ger name.** will
350c0 20 72 65 73 75 6c 74 20 69 6e 20 5b 53 51 4c 49   result in [SQLI
350d0 54 45 5f 4d 49 53 55 53 45 5d 20 62 65 69 6e 67  TE_MISUSE] being
350e0 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a   returned..**.**
350f0 20 5e 54 68 65 20 74 68 69 72 64 20 70 61 72 61   ^The third para
35100 6d 65 74 65 72 20 28 6e 41 72 67 29 0a 2a 2a 20  meter (nArg).** 
35110 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  is the number of
35120 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74 20   arguments that 
35130 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  the SQL function
35140 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65   or.** aggregate
35150 20 74 61 6b 65 73 2e 20 5e 49 66 20 74 68 69 73   takes. ^If this
35160 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 2d 31   parameter is -1
35170 2c 20 74 68 65 6e 20 74 68 65 20 53 51 4c 20 66  , then the SQL f
35180 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67  unction or.** ag
35190 67 72 65 67 61 74 65 20 6d 61 79 20 74 61 6b 65  gregate may take
351a0 20 61 6e 79 20 6e 75 6d 62 65 72 20 6f 66 20 61   any number of a
351b0 72 67 75 6d 65 6e 74 73 20 62 65 74 77 65 65 6e  rguments between
351c0 20 30 20 61 6e 64 20 74 68 65 20 6c 69 6d 69 74   0 and the limit
351d0 0a 2a 2a 20 73 65 74 20 62 79 20 5b 73 71 6c 69  .** set by [sqli
351e0 74 65 33 5f 6c 69 6d 69 74 5d 28 5b 53 51 4c 49  te3_limit]([SQLI
351f0 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f  TE_LIMIT_FUNCTIO
35200 4e 5f 41 52 47 5d 29 2e 20 20 49 66 20 74 68 65  N_ARG]).  If the
35210 20 74 68 69 72 64 0a 2a 2a 20 70 61 72 61 6d 65   third.** parame
35220 74 65 72 20 69 73 20 6c 65 73 73 20 74 68 61 6e  ter is less than
35230 20 2d 31 20 6f 72 20 67 72 65 61 74 65 72 20 74   -1 or greater t
35240 68 61 6e 20 31 32 37 20 74 68 65 6e 20 74 68 65  han 127 then the
35250 20 62 65 68 61 76 69 6f 72 20 69 73 0a 2a 2a 20   behavior is.** 
35260 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a  undefined..**.**
35270 20 5e 54 68 65 20 66 6f 75 72 74 68 20 70 61 72   ^The fourth par
35280 61 6d 65 74 65 72 2c 20 65 54 65 78 74 52 65 70  ameter, eTextRep
35290 2c 20 73 70 65 63 69 66 69 65 73 20 77 68 61 74  , specifies what
352a0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46 38  .** [SQLITE_UTF8
352b0 20 7c 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67   | text encoding
352c0 5d 20 74 68 69 73 20 53 51 4c 20 66 75 6e 63 74  ] this SQL funct
352d0 69 6f 6e 20 70 72 65 66 65 72 73 20 66 6f 72 0a  ion prefers for.
352e0 2a 2a 20 69 74 73 20 70 61 72 61 6d 65 74 65 72  ** its parameter
352f0 73 2e 20 20 54 68 65 20 61 70 70 6c 69 63 61 74  s.  The applicat
35300 69 6f 6e 20 73 68 6f 75 6c 64 20 73 65 74 20 74  ion should set t
35310 68 69 73 20 70 61 72 61 6d 65 74 65 72 20 74 6f  his parameter to
35320 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46 31  .** [SQLITE_UTF1
35330 36 4c 45 5d 20 69 66 20 74 68 65 20 66 75 6e 63  6LE] if the func
35340 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74  tion implementat
35350 69 6f 6e 20 69 6e 76 6f 6b 65 73 20 0a 2a 2a 20  ion invokes .** 
35360 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  [sqlite3_value_t
35370 65 78 74 31 36 6c 65 28 29 5d 20 6f 6e 20 61 6e  ext16le()] on an
35380 20 69 6e 70 75 74 2c 20 6f 72 20 5b 53 51 4c 49   input, or [SQLI
35390 54 45 5f 55 54 46 31 36 42 45 5d 20 69 66 20 74  TE_UTF16BE] if t
353a0 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61  he.** implementa
353b0 74 69 6f 6e 20 69 6e 76 6f 6b 65 73 20 5b 73 71  tion invokes [sq
353c0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
353d0 31 36 62 65 28 29 5d 20 6f 6e 20 61 6e 20 69 6e  16be()] on an in
353e0 70 75 74 2c 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49  put, or.** [SQLI
353f0 54 45 5f 55 54 46 31 36 5d 20 69 66 20 5b 73 71  TE_UTF16] if [sq
35400 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
35410 31 36 28 29 5d 20 69 73 20 75 73 65 64 2c 20 6f  16()] is used, o
35420 72 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d 0a  r [SQLITE_UTF8].
35430 2a 2a 20 6f 74 68 65 72 77 69 73 65 2e 20 20 5e  ** otherwise.  ^
35440 54 68 65 20 73 61 6d 65 20 53 51 4c 20 66 75 6e  The same SQL fun
35450 63 74 69 6f 6e 20 6d 61 79 20 62 65 20 72 65 67  ction may be reg
35460 69 73 74 65 72 65 64 20 6d 75 6c 74 69 70 6c 65  istered multiple
35470 20 74 69 6d 65 73 20 75 73 69 6e 67 0a 2a 2a 20   times using.** 
35480 64 69 66 66 65 72 65 6e 74 20 70 72 65 66 65 72  different prefer
35490 72 65 64 20 74 65 78 74 20 65 6e 63 6f 64 69 6e  red text encodin
354a0 67 73 2c 20 77 69 74 68 20 64 69 66 66 65 72 65  gs, with differe
354b0 6e 74 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  nt implementatio
354c0 6e 73 20 66 6f 72 0a 2a 2a 20 65 61 63 68 20 65  ns for.** each e
354d0 6e 63 6f 64 69 6e 67 2e 0a 2a 2a 20 5e 57 68 65  ncoding..** ^Whe
354e0 6e 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65  n multiple imple
354f0 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74 68  mentations of th
35500 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20  e same function 
35510 61 72 65 20 61 76 61 69 6c 61 62 6c 65 2c 20 53  are available, S
35520 51 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c 20 70 69  QLite.** will pi
35530 63 6b 20 74 68 65 20 6f 6e 65 20 74 68 61 74 20  ck the one that 
35540 69 6e 76 6f 6c 76 65 73 20 74 68 65 20 6c 65 61  involves the lea
35550 73 74 20 61 6d 6f 75 6e 74 20 6f 66 20 64 61 74  st amount of dat
35560 61 20 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a  a conversion..**
35570 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 72 74 68 20  .** ^The fourth 
35580 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 6f 70  parameter may op
35590 74 69 6f 6e 61 6c 6c 79 20 62 65 20 4f 52 65 64  tionally be ORed
355a0 20 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 44 45   with [SQLITE_DE
355b0 54 45 52 4d 49 4e 49 53 54 49 43 5d 0a 2a 2a 20  TERMINISTIC].** 
355c0 74 6f 20 73 69 67 6e 61 6c 20 74 68 61 74 20 74  to signal that t
355d0 68 65 20 66 75 6e 63 74 69 6f 6e 20 77 69 6c 6c  he function will
355e0 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 20 74   always return t
355f0 68 65 20 73 61 6d 65 20 72 65 73 75 6c 74 20 67  he same result g
35600 69 76 65 6e 0a 2a 2a 20 74 68 65 20 73 61 6d 65  iven.** the same
35610 20 69 6e 70 75 74 73 20 77 69 74 68 69 6e 20 61   inputs within a
35620 20 73 69 6e 67 6c 65 20 53 51 4c 20 73 74 61 74   single SQL stat
35630 65 6d 65 6e 74 2e 20 20 4d 6f 73 74 20 53 51 4c  ement.  Most SQL
35640 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 0a 2a   functions are.*
35650 2a 20 64 65 74 65 72 6d 69 6e 69 73 74 69 63 2e  * deterministic.
35660 20 20 54 68 65 20 62 75 69 6c 74 2d 69 6e 20 5b    The built-in [
35670 72 61 6e 64 6f 6d 28 29 5d 20 53 51 4c 20 66 75  random()] SQL fu
35680 6e 63 74 69 6f 6e 20 69 73 20 61 6e 20 65 78 61  nction is an exa
35690 6d 70 6c 65 20 6f 66 20 61 0a 2a 2a 20 66 75 6e  mple of a.** fun
356a0 63 74 69 6f 6e 20 74 68 61 74 20 69 73 20 6e 6f  ction that is no
356b0 74 20 64 65 74 65 72 6d 69 6e 69 73 74 69 63 2e  t deterministic.
356c0 20 20 54 68 65 20 53 51 4c 69 74 65 20 71 75 65    The SQLite que
356d0 72 79 20 70 6c 61 6e 6e 65 72 20 69 73 20 61 62  ry planner is ab
356e0 6c 65 20 74 6f 0a 2a 2a 20 70 65 72 66 6f 72 6d  le to.** perform
356f0 20 61 64 64 69 74 69 6f 6e 61 6c 20 6f 70 74 69   additional opti
35700 6d 69 7a 61 74 69 6f 6e 73 20 6f 6e 20 64 65 74  mizations on det
35710 65 72 6d 69 6e 69 73 74 69 63 20 66 75 6e 63 74  erministic funct
35720 69 6f 6e 73 2c 20 73 6f 20 75 73 65 0a 2a 2a 20  ions, so use.** 
35730 6f 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 44  of the [SQLITE_D
35740 45 54 45 52 4d 49 4e 49 53 54 49 43 5d 20 66 6c  ETERMINISTIC] fl
35750 61 67 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65  ag is recommende
35760 64 20 77 68 65 72 65 20 70 6f 73 73 69 62 6c 65  d where possible
35770 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 66 69  ..**.** ^(The fi
35780 66 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73  fth parameter is
35790 20 61 6e 20 61 72 62 69 74 72 61 72 79 20 70 6f   an arbitrary po
357a0 69 6e 74 65 72 2e 20 20 54 68 65 20 69 6d 70 6c  inter.  The impl
357b0 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68  ementation of th
357c0 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 63 61  e.** function ca
357d0 6e 20 67 61 69 6e 20 61 63 63 65 73 73 20 74 6f  n gain access to
357e0 20 74 68 69 73 20 70 6f 69 6e 74 65 72 20 75 73   this pointer us
357f0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 75 73 65  ing [sqlite3_use
35800 72 5f 64 61 74 61 28 29 5d 2e 29 5e 0a 2a 2a 0a  r_data()].)^.**.
35810 2a 2a 20 5e 54 68 65 20 73 69 78 74 68 2c 20 73  ** ^The sixth, s
35820 65 76 65 6e 74 68 20 61 6e 64 20 65 69 67 68 74  eventh and eight
35830 68 20 70 61 72 61 6d 65 74 65 72 73 2c 20 78 46  h parameters, xF
35840 75 6e 63 2c 20 78 53 74 65 70 20 61 6e 64 20 78  unc, xStep and x
35850 46 69 6e 61 6c 2c 20 61 72 65 0a 2a 2a 20 70 6f  Final, are.** po
35860 69 6e 74 65 72 73 20 74 6f 20 43 2d 6c 61 6e 67  inters to C-lang
35870 75 61 67 65 20 66 75 6e 63 74 69 6f 6e 73 20 74  uage functions t
35880 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68  hat implement th
35890 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f  e SQL function o
358a0 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 2e 20  r.** aggregate. 
358b0 5e 41 20 73 63 61 6c 61 72 20 53 51 4c 20 66 75  ^A scalar SQL fu
358c0 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65 73 20  nction requires 
358d0 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  an implementatio
358e0 6e 20 6f 66 20 74 68 65 20 78 46 75 6e 63 0a 2a  n of the xFunc.*
358f0 2a 20 63 61 6c 6c 62 61 63 6b 20 6f 6e 6c 79 3b  * callback only;
35900 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73 20 6d   NULL pointers m
35910 75 73 74 20 62 65 20 70 61 73 73 65 64 20 61 73  ust be passed as
35920 20 74 68 65 20 78 53 74 65 70 20 61 6e 64 20 78   the xStep and x
35930 46 69 6e 61 6c 0a 2a 2a 20 70 61 72 61 6d 65 74  Final.** paramet
35940 65 72 73 2e 20 5e 41 6e 20 61 67 67 72 65 67 61  ers. ^An aggrega
35950 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  te SQL function 
35960 72 65 71 75 69 72 65 73 20 61 6e 20 69 6d 70 6c  requires an impl
35970 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 78 53  ementation of xS
35980 74 65 70 0a 2a 2a 20 61 6e 64 20 78 46 69 6e 61  tep.** and xFina
35990 6c 20 61 6e 64 20 4e 55 4c 4c 20 70 6f 69 6e 74  l and NULL point
359a0 65 72 20 6d 75 73 74 20 62 65 20 70 61 73 73 65  er must be passe
359b0 64 20 66 6f 72 20 78 46 75 6e 63 2e 20 5e 54 6f  d for xFunc. ^To
359c0 20 64 65 6c 65 74 65 20 61 6e 20 65 78 69 73 74   delete an exist
359d0 69 6e 67 0a 2a 2a 20 53 51 4c 20 66 75 6e 63 74  ing.** SQL funct
359e0 69 6f 6e 20 6f 72 20 61 67 67 72 65 67 61 74 65  ion or aggregate
359f0 2c 20 70 61 73 73 20 4e 55 4c 4c 20 70 6f 69 6e  , pass NULL poin
35a00 74 65 72 73 20 66 6f 72 20 61 6c 6c 20 74 68 72  ters for all thr
35a10 65 65 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 63  ee function.** c
35a20 61 6c 6c 62 61 63 6b 73 2e 0a 2a 2a 0a 2a 2a 20  allbacks..**.** 
35a30 5e 28 49 66 20 74 68 65 20 6e 69 6e 74 68 20 70  ^(If the ninth p
35a40 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
35a50 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
35a60 69 6f 6e 5f 76 32 28 29 20 69 73 20 6e 6f 74 20  ion_v2() is not 
35a70 4e 55 4c 4c 2c 0a 2a 2a 20 74 68 65 6e 20 69 74  NULL,.** then it
35a80 20 69 73 20 64 65 73 74 72 75 63 74 6f 72 20 66   is destructor f
35a90 6f 72 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  or the applicati
35aa0 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74 65 72 2e  on data pointer.
35ab0 20 0a 2a 2a 20 54 68 65 20 64 65 73 74 72 75 63   .** The destruc
35ac0 74 6f 72 20 69 73 20 69 6e 76 6f 6b 65 64 20 77  tor is invoked w
35ad0 68 65 6e 20 74 68 65 20 66 75 6e 63 74 69 6f 6e  hen the function
35ae0 20 69 73 20 64 65 6c 65 74 65 64 2c 20 65 69 74   is deleted, eit
35af0 68 65 72 20 62 79 20 62 65 69 6e 67 0a 2a 2a 20  her by being.** 
35b00 6f 76 65 72 6c 6f 61 64 65 64 20 6f 72 20 77 68  overloaded or wh
35b10 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  en the database 
35b20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f 73 65  connection close
35b30 73 2e 29 5e 0a 2a 2a 20 5e 54 68 65 20 64 65 73  s.)^.** ^The des
35b40 74 72 75 63 74 6f 72 20 69 73 20 61 6c 73 6f 20  tructor is also 
35b50 69 6e 76 6f 6b 65 64 20 69 66 20 74 68 65 20 63  invoked if the c
35b60 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65  all to.** sqlite
35b70 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
35b80 6e 5f 76 32 28 29 20 66 61 69 6c 73 2e 0a 2a 2a  n_v2() fails..**
35b90 20 5e 57 68 65 6e 20 74 68 65 20 64 65 73 74 72   ^When the destr
35ba0 75 63 74 6f 72 20 63 61 6c 6c 62 61 63 6b 20 6f  uctor callback o
35bb0 66 20 74 68 65 20 74 65 6e 74 68 20 70 61 72 61  f the tenth para
35bc0 6d 65 74 65 72 20 69 73 20 69 6e 76 6f 6b 65 64  meter is invoked
35bd0 2c 20 69 74 0a 2a 2a 20 69 73 20 70 61 73 73 65  , it.** is passe
35be0 64 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d  d a single argum
35bf0 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 63  ent which is a c
35c00 6f 70 79 20 6f 66 20 74 68 65 20 61 70 70 6c 69  opy of the appli
35c10 63 61 74 69 6f 6e 20 64 61 74 61 20 0a 2a 2a 20  cation data .** 
35c20 70 6f 69 6e 74 65 72 20 77 68 69 63 68 20 77 61  pointer which wa
35c30 73 20 74 68 65 20 66 69 66 74 68 20 70 61 72 61  s the fifth para
35c40 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
35c50 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
35c60 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74  _v2()..**.** ^It
35c70 20 69 73 20 70 65 72 6d 69 74 74 65 64 20 74 6f   is permitted to
35c80 20 72 65 67 69 73 74 65 72 20 6d 75 6c 74 69 70   register multip
35c90 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  le implementatio
35ca0 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65 0a 2a  ns of the same.*
35cb0 2a 20 66 75 6e 63 74 69 6f 6e 73 20 77 69 74 68  * functions with
35cc0 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 20 62   the same name b
35cd0 75 74 20 77 69 74 68 20 65 69 74 68 65 72 20 64  ut with either d
35ce0 69 66 66 65 72 69 6e 67 20 6e 75 6d 62 65 72 73  iffering numbers
35cf0 20 6f 66 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 73   of.** arguments
35d00 20 6f 72 20 64 69 66 66 65 72 69 6e 67 20 70 72   or differing pr
35d10 65 66 65 72 72 65 64 20 74 65 78 74 20 65 6e 63  eferred text enc
35d20 6f 64 69 6e 67 73 2e 20 20 5e 53 51 4c 69 74 65  odings.  ^SQLite
35d30 20 77 69 6c 6c 20 75 73 65 0a 2a 2a 20 74 68 65   will use.** the
35d40 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
35d50 74 68 61 74 20 6d 6f 73 74 20 63 6c 6f 73 65 6c  that most closel
35d60 79 20 6d 61 74 63 68 65 73 20 74 68 65 20 77 61  y matches the wa
35d70 79 20 69 6e 20 77 68 69 63 68 20 74 68 65 0a 2a  y in which the.*
35d80 2a 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69  * SQL function i
35d90 73 20 75 73 65 64 2e 20 20 5e 41 20 66 75 6e 63  s used.  ^A func
35da0 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74  tion implementat
35db0 69 6f 6e 20 77 69 74 68 20 61 20 6e 6f 6e 2d 6e  ion with a non-n
35dc0 65 67 61 74 69 76 65 0a 2a 2a 20 6e 41 72 67 20  egative.** nArg 
35dd0 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 62  parameter is a b
35de0 65 74 74 65 72 20 6d 61 74 63 68 20 74 68 61 6e  etter match than
35df0 20 61 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c   a function impl
35e00 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 74 68 0a  ementation with.
35e10 2a 2a 20 61 20 6e 65 67 61 74 69 76 65 20 6e 41  ** a negative nA
35e20 72 67 2e 20 20 5e 41 20 66 75 6e 63 74 69 6f 6e  rg.  ^A function
35e30 20 77 68 65 72 65 20 74 68 65 20 70 72 65 66 65   where the prefe
35e40 72 72 65 64 20 74 65 78 74 20 65 6e 63 6f 64 69  rred text encodi
35e50 6e 67 0a 2a 2a 20 6d 61 74 63 68 65 73 20 74 68  ng.** matches th
35e60 65 20 64 61 74 61 62 61 73 65 20 65 6e 63 6f 64  e database encod
35e70 69 6e 67 20 69 73 20 61 20 62 65 74 74 65 72 0a  ing is a better.
35e80 2a 2a 20 6d 61 74 63 68 20 74 68 61 6e 20 61 20  ** match than a 
35e90 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74  function where t
35ea0 68 65 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 64  he encoding is d
35eb0 69 66 66 65 72 65 6e 74 2e 20 20 0a 2a 2a 20 5e  ifferent.  .** ^
35ec0 41 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65  A function where
35ed0 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 64 69   the encoding di
35ee0 66 66 65 72 65 6e 63 65 20 69 73 20 62 65 74 77  fference is betw
35ef0 65 65 6e 20 55 54 46 31 36 6c 65 20 61 6e 64 20  een UTF16le and 
35f00 55 54 46 31 36 62 65 0a 2a 2a 20 69 73 20 61 20  UTF16be.** is a 
35f10 63 6c 6f 73 65 72 20 6d 61 74 63 68 20 74 68 61  closer match tha
35f20 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 68 65  n a function whe
35f30 72 65 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20  re the encoding 
35f40 64 69 66 66 65 72 65 6e 63 65 20 69 73 0a 2a 2a  difference is.**
35f50 20 62 65 74 77 65 65 6e 20 55 54 46 38 20 61 6e   between UTF8 an
35f60 64 20 55 54 46 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e  d UTF16..**.** ^
35f70 42 75 69 6c 74 2d 69 6e 20 66 75 6e 63 74 69 6f  Built-in functio
35f80 6e 73 20 6d 61 79 20 62 65 20 6f 76 65 72 6c 6f  ns may be overlo
35f90 61 64 65 64 20 62 79 20 6e 65 77 20 61 70 70 6c  aded by new appl
35fa0 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
35fb0 66 75 6e 63 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a  functions..**.**
35fc0 20 5e 41 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e   ^An application
35fd0 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
35fe0 6e 20 69 73 20 70 65 72 6d 69 74 74 65 64 20 74  n is permitted t
35ff0 6f 20 63 61 6c 6c 20 6f 74 68 65 72 0a 2a 2a 20  o call other.** 
36000 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65  SQLite interface
36010 73 2e 20 20 48 6f 77 65 76 65 72 2c 20 73 75 63  s.  However, suc
36020 68 20 63 61 6c 6c 73 20 6d 75 73 74 20 6e 6f 74  h calls must not
36030 0a 2a 2a 20 63 6c 6f 73 65 20 74 68 65 20 64 61  .** close the da
36040 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
36050 6e 20 6e 6f 72 20 66 69 6e 61 6c 69 7a 65 20 6f  n nor finalize o
36060 72 20 72 65 73 65 74 20 74 68 65 20 70 72 65 70  r reset the prep
36070 61 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e  ared.** statemen
36080 74 20 69 6e 20 77 68 69 63 68 20 74 68 65 20 66  t in which the f
36090 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69  unction is runni
360a0 6e 67 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  ng..*/.int sqlit
360b0 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
360c0 6f 6e 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64  on(.  sqlite3 *d
360d0 62 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  b,.  const char 
360e0 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a  *zFunctionName,.
360f0 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e    int nArg,.  in
36100 74 20 65 54 65 78 74 52 65 70 2c 0a 20 20 76 6f  t eTextRep,.  vo
36110 69 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64  id *pApp,.  void
36120 20 28 2a 78 46 75 6e 63 29 28 73 71 6c 69 74 65   (*xFunc)(sqlite
36130 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73  3_context*,int,s
36140 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c  qlite3_value**),
36150 0a 20 20 76 6f 69 64 20 28 2a 78 53 74 65 70 29  .  void (*xStep)
36160 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
36170 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61  *,int,sqlite3_va
36180 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28  lue**),.  void (
36190 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69 74 65 33  *xFinal)(sqlite3
361a0 5f 63 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a 69 6e  _context*).);.in
361b0 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  t sqlite3_create
361c0 5f 66 75 6e 63 74 69 6f 6e 31 36 28 0a 20 20 73  _function16(.  s
361d0 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f  qlite3 *db,.  co
361e0 6e 73 74 20 76 6f 69 64 20 2a 7a 46 75 6e 63 74  nst void *zFunct
361f0 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e  ionName,.  int n
36200 41 72 67 2c 0a 20 20 69 6e 74 20 65 54 65 78 74  Arg,.  int eText
36210 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70  Rep,.  void *pAp
36220 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 75 6e  p,.  void (*xFun
36230 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  c)(sqlite3_conte
36240 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f  xt*,int,sqlite3_
36250 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64  value**),.  void
36260 20 28 2a 78 53 74 65 70 29 28 73 71 6c 69 74 65   (*xStep)(sqlite
36270 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73  3_context*,int,s
36280 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c  qlite3_value**),
36290 0a 20 20 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c  .  void (*xFinal
362a0 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  )(sqlite3_contex
362b0 74 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74  t*).);.int sqlit
362c0 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
362d0 6f 6e 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33  on_v2(.  sqlite3
362e0 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20 63 68   *db,.  const ch
362f0 61 72 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d  ar *zFunctionNam
36300 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20  e,.  int nArg,. 
36310 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 0a 20   int eTextRep,. 
36320 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20 76   void *pApp,.  v
36330 6f 69 64 20 28 2a 78 46 75 6e 63 29 28 73 71 6c  oid (*xFunc)(sql
36340 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e  ite3_context*,in
36350 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  t,sqlite3_value*
36360 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53 74  *),.  void (*xSt
36370 65 70 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ep)(sqlite3_cont
36380 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33  ext*,int,sqlite3
36390 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69  _value**),.  voi
363a0 64 20 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69  d (*xFinal)(sqli
363b0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 2c 0a 20  te3_context*),. 
363c0 20 76 6f 69 64 28 2a 78 44 65 73 74 72 6f 79 29   void(*xDestroy)
363d0 28 76 6f 69 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a  (void*).);../*.*
363e0 2a 20 43 41 50 49 33 52 45 46 3a 20 54 65 78 74  * CAPI3REF: Text
363f0 20 45 6e 63 6f 64 69 6e 67 73 0a 2a 2a 0a 2a 2a   Encodings.**.**
36400 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 20   These constant 
36410 64 65 66 69 6e 65 20 69 6e 74 65 67 65 72 20 63  define integer c
36420 6f 64 65 73 20 74 68 61 74 20 72 65 70 72 65 73  odes that repres
36430 65 6e 74 20 74 68 65 20 76 61 72 69 6f 75 73 0a  ent the various.
36440 2a 2a 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67  ** text encoding
36450 73 20 73 75 70 70 6f 72 74 65 64 20 62 79 20 53  s supported by S
36460 51 4c 69 74 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e  QLite..*/.#defin
36470 65 20 53 51 4c 49 54 45 5f 55 54 46 38 20 20 20  e SQLITE_UTF8   
36480 20 20 20 20 20 20 20 20 31 20 20 20 20 2f 2a 20          1    /* 
36490 49 4d 50 3a 20 52 2d 33 37 35 31 34 2d 33 35 35  IMP: R-37514-355
364a0 36 36 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  66 */.#define SQ
364b0 4c 49 54 45 5f 55 54 46 31 36 4c 45 20 20 20 20  LITE_UTF16LE    
364c0 20 20 20 20 32 20 20 20 20 2f 2a 20 49 4d 50 3a      2    /* IMP:
364d0 20 52 2d 30 33 33 37 31 2d 33 37 36 33 37 20 2a   R-03371-37637 *
364e0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
364f0 5f 55 54 46 31 36 42 45 20 20 20 20 20 20 20 20  _UTF16BE        
36500 33 20 20 20 20 2f 2a 20 49 4d 50 3a 20 52 2d 35  3    /* IMP: R-5
36510 31 39 37 31 2d 33 34 31 35 34 20 2a 2f 0a 23 64  1971-34154 */.#d
36520 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46  efine SQLITE_UTF
36530 31 36 20 20 20 20 20 20 20 20 20 20 34 20 20 20  16          4   
36540 20 2f 2a 20 55 73 65 20 6e 61 74 69 76 65 20 62   /* Use native b
36550 79 74 65 20 6f 72 64 65 72 20 2a 2f 0a 23 64 65  yte order */.#de
36560 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4e 59 20  fine SQLITE_ANY 
36570 20 20 20 20 20 20 20 20 20 20 20 35 20 20 20 20             5    
36580 2f 2a 20 44 65 70 72 65 63 61 74 65 64 20 2a 2f  /* Deprecated */
36590 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
365a0 55 54 46 31 36 5f 41 4c 49 47 4e 45 44 20 20 38  UTF16_ALIGNED  8
365b0 20 20 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 63      /* sqlite3_c
365c0 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 20  reate_collation 
365d0 6f 6e 6c 79 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43  only */../*.** C
365e0 41 50 49 33 52 45 46 3a 20 46 75 6e 63 74 69 6f  API3REF: Functio
365f0 6e 20 46 6c 61 67 73 0a 2a 2a 0a 2a 2a 20 54 68  n Flags.**.** Th
36600 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 6d 61  ese constants ma
36610 79 20 62 65 20 4f 52 65 64 20 74 6f 67 65 74 68  y be ORed togeth
36620 65 72 20 77 69 74 68 20 74 68 65 20 0a 2a 2a 20  er with the .** 
36630 5b 53 51 4c 49 54 45 5f 55 54 46 38 20 7c 20 70  [SQLITE_UTF8 | p
36640 72 65 66 65 72 72 65 64 20 74 65 78 74 20 65 6e  referred text en
36650 63 6f 64 69 6e 67 5d 20 61 73 20 74 68 65 20 66  coding] as the f
36660 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 0a 2a  ourth argument.*
36670 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72  * to [sqlite3_cr
36680 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d  eate_function()]
36690 2c 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  , [sqlite3_creat
366a0 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 2c  e_function16()],
366b0 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   or.** [sqlite3_
366c0 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f  create_function_
366d0 76 32 28 29 5d 2e 0a 2a 2f 0a 23 64 65 66 69 6e  v2()]..*/.#defin
366e0 65 20 53 51 4c 49 54 45 5f 44 45 54 45 52 4d 49  e SQLITE_DETERMI
366f0 4e 49 53 54 49 43 20 20 20 20 30 78 38 30 30 0a  NISTIC    0x800.
36700 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
36710 20 44 65 70 72 65 63 61 74 65 64 20 46 75 6e 63   Deprecated Func
36720 74 69 6f 6e 73 0a 2a 2a 20 44 45 50 52 45 43 41  tions.** DEPRECA
36730 54 45 44 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  TED.**.** These 
36740 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 20 5b 64  functions are [d
36750 65 70 72 65 63 61 74 65 64 5d 2e 20 20 49 6e 20  eprecated].  In 
36760 6f 72 64 65 72 20 74 6f 20 6d 61 69 6e 74 61 69  order to maintai
36770 6e 0a 2a 2a 20 62 61 63 6b 77 61 72 64 73 20 63  n.** backwards c
36780 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 77 69 74  ompatibility wit
36790 68 20 6f 6c 64 65 72 20 63 6f 64 65 2c 20 74 68  h older code, th
367a0 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 63 6f  ese functions co
367b0 6e 74 69 6e 75 65 20 0a 2a 2a 20 74 6f 20 62 65  ntinue .** to be
367c0 20 73 75 70 70 6f 72 74 65 64 2e 20 20 48 6f 77   supported.  How
367d0 65 76 65 72 2c 20 6e 65 77 20 61 70 70 6c 69 63  ever, new applic
367e0 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 61 76  ations should av
367f0 6f 69 64 0a 2a 2a 20 74 68 65 20 75 73 65 20 6f  oid.** the use o
36800 66 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e  f these function
36810 73 2e 20 20 54 6f 20 65 6e 63 6f 75 72 61 67 65  s.  To encourage
36820 20 70 72 6f 67 72 61 6d 6d 65 72 73 20 74 6f 20   programmers to 
36830 61 76 6f 69 64 0a 2a 2a 20 74 68 65 73 65 20 66  avoid.** these f
36840 75 6e 63 74 69 6f 6e 73 2c 20 77 65 20 77 69 6c  unctions, we wil
36850 6c 20 6e 6f 74 20 65 78 70 6c 61 69 6e 20 77 68  l not explain wh
36860 61 74 20 74 68 65 79 20 64 6f 2e 0a 2a 2f 0a 23  at they do..*/.#
36870 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d  ifndef SQLITE_OM
36880 49 54 5f 44 45 50 52 45 43 41 54 45 44 0a 53 51  IT_DEPRECATED.SQ
36890 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20  LITE_DEPRECATED 
368a0 69 6e 74 20 73 71 6c 69 74 65 33 5f 61 67 67 72  int sqlite3_aggr
368b0 65 67 61 74 65 5f 63 6f 75 6e 74 28 73 71 6c 69  egate_count(sqli
368c0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 53  te3_context*);.S
368d0 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44  QLITE_DEPRECATED
368e0 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 70   int sqlite3_exp
368f0 69 72 65 64 28 73 71 6c 69 74 65 33 5f 73 74 6d  ired(sqlite3_stm
36900 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52  t*);.SQLITE_DEPR
36910 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74  ECATED int sqlit
36920 65 33 5f 74 72 61 6e 73 66 65 72 5f 62 69 6e 64  e3_transfer_bind
36930 69 6e 67 73 28 73 71 6c 69 74 65 33 5f 73 74 6d  ings(sqlite3_stm
36940 74 2a 2c 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  t*, sqlite3_stmt
36950 2a 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 45  *);.SQLITE_DEPRE
36960 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65  CATED int sqlite
36970 33 5f 67 6c 6f 62 61 6c 5f 72 65 63 6f 76 65 72  3_global_recover
36980 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f 44  (void);.SQLITE_D
36990 45 50 52 45 43 41 54 45 44 20 76 6f 69 64 20 73  EPRECATED void s
369a0 71 6c 69 74 65 33 5f 74 68 72 65 61 64 5f 63 6c  qlite3_thread_cl
369b0 65 61 6e 75 70 28 76 6f 69 64 29 3b 0a 53 51 4c  eanup(void);.SQL
369c0 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 69  ITE_DEPRECATED i
369d0 6e 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  nt sqlite3_memor
369e0 79 5f 61 6c 61 72 6d 28 76 6f 69 64 28 2a 29 28  y_alarm(void(*)(
369f0 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 5f 69 6e  void*,sqlite3_in
36a00 74 36 34 2c 69 6e 74 29 2c 0a 20 20 20 20 20 20  t64,int),.      
36a10 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
36a20 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 5f 69 6e  void*,sqlite3_in
36a30 74 36 34 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f 2a  t64);.#endif../*
36a40 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 62  .** CAPI3REF: Ob
36a50 74 61 69 6e 69 6e 67 20 53 51 4c 20 56 61 6c 75  taining SQL Valu
36a60 65 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  es.** METHOD: sq
36a70 6c 69 74 65 33 5f 76 61 6c 75 65 0a 2a 2a 0a 2a  lite3_value.**.*
36a80 2a 20 54 68 65 20 43 2d 6c 61 6e 67 75 61 67 65  * The C-language
36a90 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
36aa0 6f 66 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  of SQL functions
36ab0 20 61 6e 64 20 61 67 67 72 65 67 61 74 65 73 20   and aggregates 
36ac0 75 73 65 73 0a 2a 2a 20 74 68 69 73 20 73 65 74  uses.** this set
36ad0 20 6f 66 20 69 6e 74 65 72 66 61 63 65 20 72 6f   of interface ro
36ae0 75 74 69 6e 65 73 20 74 6f 20 61 63 63 65 73 73  utines to access
36af0 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 76   the parameter v
36b00 61 6c 75 65 73 20 6f 6e 0a 2a 2a 20 74 68 65 20  alues on.** the 
36b10 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67 72  function or aggr
36b20 65 67 61 74 65 2e 20 20 0a 2a 2a 0a 2a 2a 20 54  egate.  .**.** T
36b30 68 65 20 78 46 75 6e 63 20 28 66 6f 72 20 73 63  he xFunc (for sc
36b40 61 6c 61 72 20 66 75 6e 63 74 69 6f 6e 73 29 20  alar functions) 
36b50 6f 72 20 78 53 74 65 70 20 28 66 6f 72 20 61 67  or xStep (for ag
36b60 67 72 65 67 61 74 65 73 29 20 70 61 72 61 6d 65  gregates) parame
36b70 74 65 72 73 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69  ters.** to [sqli
36b80 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
36b90 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  ion()] and [sqli
36ba0 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
36bb0 69 6f 6e 31 36 28 29 5d 0a 2a 2a 20 64 65 66 69  ion16()].** defi
36bc0 6e 65 20 63 61 6c 6c 62 61 63 6b 73 20 74 68 61  ne callbacks tha
36bd0 74 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65 20  t implement the 
36be0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e  SQL functions an
36bf0 64 20 61 67 67 72 65 67 61 74 65 73 2e 0a 2a 2a  d aggregates..**
36c00 20 54 68 65 20 33 72 64 20 70 61 72 61 6d 65 74   The 3rd paramet
36c10 65 72 20 74 6f 20 74 68 65 73 65 20 63 61 6c 6c  er to these call
36c20 62 61 63 6b 73 20 69 73 20 61 6e 20 61 72 72 61  backs is an arra
36c30 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f  y of pointers to
36c40 0a 2a 2a 20 5b 70 72 6f 74 65 63 74 65 64 20 73  .** [protected s
36c50 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
36c60 6a 65 63 74 73 2e 20 20 54 68 65 72 65 20 69 73  jects.  There is
36c70 20 6f 6e 65 20 5b 73 71 6c 69 74 65 33 5f 76 61   one [sqlite3_va
36c80 6c 75 65 5d 20 6f 62 6a 65 63 74 20 66 6f 72 0a  lue] object for.
36c90 2a 2a 20 65 61 63 68 20 70 61 72 61 6d 65 74 65  ** each paramete
36ca0 72 20 74 6f 20 74 68 65 20 53 51 4c 20 66 75 6e  r to the SQL fun
36cb0 63 74 69 6f 6e 2e 20 20 54 68 65 73 65 20 72 6f  ction.  These ro
36cc0 75 74 69 6e 65 73 20 61 72 65 20 75 73 65 64 20  utines are used 
36cd0 74 6f 0a 2a 2a 20 65 78 74 72 61 63 74 20 76 61  to.** extract va
36ce0 6c 75 65 73 20 66 72 6f 6d 20 74 68 65 20 5b 73  lues from the [s
36cf0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
36d00 6a 65 63 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  jects..**.** The
36d10 73 65 20 72 6f 75 74 69 6e 65 73 20 77 6f 72 6b  se routines work
36d20 20 6f 6e 6c 79 20 77 69 74 68 20 5b 70 72 6f 74   only with [prot
36d30 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
36d40 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a  lue] objects..**
36d50 20 41 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20   Any attempt to 
36d60 75 73 65 20 74 68 65 73 65 20 72 6f 75 74 69 6e  use these routin
36d70 65 73 20 6f 6e 20 61 6e 20 5b 75 6e 70 72 6f 74  es on an [unprot
36d80 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
36d90 6c 75 65 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 72  lue].** object r
36da0 65 73 75 6c 74 73 20 69 6e 20 75 6e 64 65 66 69  esults in undefi
36db0 6e 65 64 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a  ned behavior..**
36dc0 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69  .** ^These routi
36dd0 6e 65 73 20 77 6f 72 6b 20 6a 75 73 74 20 6c 69  nes work just li
36de0 6b 65 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e  ke the correspon
36df0 64 69 6e 67 20 5b 63 6f 6c 75 6d 6e 20 61 63 63  ding [column acc
36e00 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 5d 0a 2a  ess functions].*
36e10 2a 20 65 78 63 65 70 74 20 74 68 61 74 20 74 68  * except that th
36e20 65 73 65 20 72 6f 75 74 69 6e 65 73 20 74 61 6b  ese routines tak
36e30 65 20 61 20 73 69 6e 67 6c 65 20 5b 70 72 6f 74  e a single [prot
36e40 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
36e50 6c 75 65 5d 20 6f 62 6a 65 63 74 0a 2a 2a 20 70  lue] object.** p
36e60 6f 69 6e 74 65 72 20 69 6e 73 74 65 61 64 20 6f  ointer instead o
36e70 66 20 61 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d  f a [sqlite3_stm
36e80 74 2a 5d 20 70 6f 69 6e 74 65 72 20 61 6e 64 20  t*] pointer and 
36e90 61 6e 20 69 6e 74 65 67 65 72 20 63 6f 6c 75 6d  an integer colum
36ea0 6e 20 6e 75 6d 62 65 72 2e 0a 2a 2a 0a 2a 2a 20  n number..**.** 
36eb0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c  ^The sqlite3_val
36ec0 75 65 5f 74 65 78 74 31 36 28 29 20 69 6e 74 65  ue_text16() inte
36ed0 72 66 61 63 65 20 65 78 74 72 61 63 74 73 20 61  rface extracts a
36ee0 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 0a 2a   UTF-16 string.*
36ef0 2a 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20  * in the native 
36f00 62 79 74 65 2d 6f 72 64 65 72 20 6f 66 20 74 68  byte-order of th
36f10 65 20 68 6f 73 74 20 6d 61 63 68 69 6e 65 2e 20  e host machine. 
36f20 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33   ^The.** sqlite3
36f30 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 62 65 28  _value_text16be(
36f40 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 76 61  ) and sqlite3_va
36f50 6c 75 65 5f 74 65 78 74 31 36 6c 65 28 29 20 69  lue_text16le() i
36f60 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 65 78 74  nterfaces.** ext
36f70 72 61 63 74 20 55 54 46 2d 31 36 20 73 74 72 69  ract UTF-16 stri
36f80 6e 67 73 20 61 73 20 62 69 67 2d 65 6e 64 69 61  ngs as big-endia
36f90 6e 20 61 6e 64 20 6c 69 74 74 6c 65 2d 65 6e 64  n and little-end
36fa0 69 61 6e 20 72 65 73 70 65 63 74 69 76 65 6c 79  ian respectively
36fb0 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 73 71  ..**.** ^(The sq
36fc0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 6e 75 6d 65  lite3_value_nume
36fd0 72 69 63 5f 74 79 70 65 28 29 20 69 6e 74 65 72  ric_type() inter
36fe0 66 61 63 65 20 61 74 74 65 6d 70 74 73 20 74 6f  face attempts to
36ff0 20 61 70 70 6c 79 0a 2a 2a 20 6e 75 6d 65 72 69   apply.** numeri
37000 63 20 61 66 66 69 6e 69 74 79 20 74 6f 20 74 68  c affinity to th
37010 65 20 76 61 6c 75 65 2e 20 20 54 68 69 73 20 6d  e value.  This m
37020 65 61 6e 73 20 74 68 61 74 20 61 6e 20 61 74 74  eans that an att
37030 65 6d 70 74 20 69 73 0a 2a 2a 20 6d 61 64 65 20  empt is.** made 
37040 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 65 20 76  to convert the v
37050 61 6c 75 65 20 74 6f 20 61 6e 20 69 6e 74 65 67  alue to an integ
37060 65 72 20 6f 72 20 66 6c 6f 61 74 69 6e 67 20 70  er or floating p
37070 6f 69 6e 74 2e 20 20 49 66 0a 2a 2a 20 73 75 63  oint.  If.** suc
37080 68 20 61 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69  h a conversion i
37090 73 20 70 6f 73 73 69 62 6c 65 20 77 69 74 68 6f  s possible witho
370a0 75 74 20 6c 6f 73 73 20 6f 66 20 69 6e 66 6f 72  ut loss of infor
370b0 6d 61 74 69 6f 6e 20 28 69 6e 20 6f 74 68 65 72  mation (in other
370c0 0a 2a 2a 20 77 6f 72 64 73 2c 20 69 66 20 74 68  .** words, if th
370d0 65 20 76 61 6c 75 65 20 69 73 20 61 20 73 74 72  e value is a str
370e0 69 6e 67 20 74 68 61 74 20 6c 6f 6f 6b 73 20 6c  ing that looks l
370f0 69 6b 65 20 61 20 6e 75 6d 62 65 72 29 0a 2a 2a  ike a number).**
37100 20 74 68 65 6e 20 74 68 65 20 63 6f 6e 76 65 72   then the conver
37110 73 69 6f 6e 20 69 73 20 70 65 72 66 6f 72 6d 65  sion is performe
37120 64 2e 20 20 4f 74 68 65 72 77 69 73 65 20 6e 6f  d.  Otherwise no
37130 20 63 6f 6e 76 65 72 73 69 6f 6e 20 6f 63 63 75   conversion occu
37140 72 73 2e 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49  rs..** The [SQLI
37150 54 45 5f 49 4e 54 45 47 45 52 20 7c 20 64 61 74  TE_INTEGER | dat
37160 61 74 79 70 65 5d 20 61 66 74 65 72 20 63 6f 6e  atype] after con
37170 76 65 72 73 69 6f 6e 20 69 73 20 72 65 74 75 72  version is retur
37180 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 50 6c 65  ned.)^.**.** Ple
37190 61 73 65 20 70 61 79 20 70 61 72 74 69 63 75 6c  ase pay particul
371a0 61 72 20 61 74 74 65 6e 74 69 6f 6e 20 74 6f 20  ar attention to 
371b0 74 68 65 20 66 61 63 74 20 74 68 61 74 20 74 68  the fact that th
371c0 65 20 70 6f 69 6e 74 65 72 20 72 65 74 75 72 6e  e pointer return
371d0 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69  ed.** from [sqli
371e0 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 29  te3_value_blob()
371f0 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  ], [sqlite3_valu
37200 65 5f 74 65 78 74 28 29 5d 2c 20 6f 72 0a 2a 2a  e_text()], or.**
37210 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
37220 74 65 78 74 31 36 28 29 5d 20 63 61 6e 20 62 65  text16()] can be
37230 20 69 6e 76 61 6c 69 64 61 74 65 64 20 62 79 20   invalidated by 
37240 61 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c  a subsequent cal
37250 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  l to.** [sqlite3
37260 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 29 5d 2c  _value_bytes()],
37270 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
37280 62 79 74 65 73 31 36 28 29 5d 2c 20 5b 73 71 6c  bytes16()], [sql
37290 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28  ite3_value_text(
372a0 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74  )],.** or [sqlit
372b0 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28  e3_value_text16(
372c0 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  )]..**.** These 
372d0 72 6f 75 74 69 6e 65 73 20 6d 75 73 74 20 62 65  routines must be
372e0 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65   called from the
372f0 20 73 61 6d 65 20 74 68 72 65 61 64 20 61 73 0a   same thread as.
37300 2a 2a 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74  ** the SQL funct
37310 69 6f 6e 20 74 68 61 74 20 73 75 70 70 6c 69 65  ion that supplie
37320 64 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  d the [sqlite3_v
37330 61 6c 75 65 2a 5d 20 70 61 72 61 6d 65 74 65 72  alue*] parameter
37340 73 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 76 6f 69 64  s..*/.const void
37350 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   *sqlite3_value_
37360 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 76 61 6c  blob(sqlite3_val
37370 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  ue*);.int sqlite
37380 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 73 71  3_value_bytes(sq
37390 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69  lite3_value*);.i
373a0 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt sqlite3_value
373b0 5f 62 79 74 65 73 31 36 28 73 71 6c 69 74 65 33  _bytes16(sqlite3
373c0 5f 76 61 6c 75 65 2a 29 3b 0a 64 6f 75 62 6c 65  _value*);.double
373d0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 64   sqlite3_value_d
373e0 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 76 61  ouble(sqlite3_va
373f0 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74  lue*);.int sqlit
37400 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28 73 71 6c  e3_value_int(sql
37410 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 73 71  ite3_value*);.sq
37420 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69  lite3_int64 sqli
37430 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 36 34 28  te3_value_int64(
37440 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
37450 0a 63 6f 6e 73 74 20 75 6e 73 69 67 6e 65 64 20  .const unsigned 
37460 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 76 61  char *sqlite3_va
37470 6c 75 65 5f 74 65 78 74 28 73 71 6c 69 74 65 33  lue_text(sqlite3
37480 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20  _value*);.const 
37490 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61  void *sqlite3_va
374a0 6c 75 65 5f 74 65 78 74 31 36 28 73 71 6c 69 74  lue_text16(sqlit
374b0 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73  e3_value*);.cons
374c0 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
374d0 76 61 6c 75 65 5f 74 65 78 74 31 36 6c 65 28 73  value_text16le(s
374e0 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
374f0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
37500 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36  te3_value_text16
37510 62 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  be(sqlite3_value
37520 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  *);.int sqlite3_
37530 76 61 6c 75 65 5f 74 79 70 65 28 73 71 6c 69 74  value_type(sqlit
37540 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20  e3_value*);.int 
37550 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 6e 75  sqlite3_value_nu
37560 6d 65 72 69 63 5f 74 79 70 65 28 73 71 6c 69 74  meric_type(sqlit
37570 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 0a 2f 2a 0a  e3_value*);../*.
37580 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 69 6e  ** CAPI3REF: Fin
37590 64 69 6e 67 20 54 68 65 20 53 75 62 74 79 70 65  ding The Subtype
375a0 20 4f 66 20 53 51 4c 20 56 61 6c 75 65 73 0a 2a   Of SQL Values.*
375b0 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65  * METHOD: sqlite
375c0 33 5f 76 61 6c 75 65 0a 2a 2a 0a 2a 2a 20 54 68  3_value.**.** Th
375d0 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  e sqlite3_value_
375e0 73 75 62 74 79 70 65 28 56 29 20 66 75 6e 63 74  subtype(V) funct
375f0 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20  ion returns the 
37600 73 75 62 74 79 70 65 20 66 6f 72 0a 2a 2a 20 61  subtype for.** a
37610 6e 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  n [application-d
37620 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74  efined SQL funct
37630 69 6f 6e 5d 20 61 72 67 75 6d 65 6e 74 20 56 2e  ion] argument V.
37640 20 20 54 68 65 20 73 75 62 74 79 70 65 0a 2a 2a    The subtype.**
37650 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 63 61 6e   information can
37660 20 62 65 20 75 73 65 64 20 74 6f 20 70 61 73 73   be used to pass
37670 20 61 20 6c 69 6d 69 74 65 64 20 61 6d 6f 75 6e   a limited amoun
37680 74 20 6f 66 20 63 6f 6e 74 65 78 74 20 66 72 6f  t of context fro
37690 6d 0a 2a 2a 20 6f 6e 65 20 53 51 4c 20 66 75 6e  m.** one SQL fun
376a0 63 74 69 6f 6e 20 74 6f 20 61 6e 6f 74 68 65 72  ction to another
376b0 2e 20 20 55 73 65 20 74 68 65 20 5b 73 71 6c 69  .  Use the [sqli
376c0 74 65 33 5f 72 65 73 75 6c 74 5f 73 75 62 74 79  te3_result_subty
376d0 70 65 28 29 5d 0a 2a 2a 20 72 6f 75 74 69 6e 65  pe()].** routine
376e0 20 74 6f 20 73 65 74 20 74 68 65 20 73 75 62 74   to set the subt
376f0 79 70 65 20 66 6f 72 20 74 68 65 20 72 65 74 75  ype for the retu
37700 72 6e 20 76 61 6c 75 65 20 6f 66 20 61 6e 20 53  rn value of an S
37710 51 4c 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a  QL function..**.
37720 2a 2a 20 53 51 4c 69 74 65 20 6d 61 6b 65 73 20  ** SQLite makes 
37730 6e 6f 20 75 73 65 20 6f 66 20 73 75 62 74 79 70  no use of subtyp
37740 65 20 69 74 73 65 6c 66 2e 20 20 49 74 20 6d 65  e itself.  It me
37750 72 65 6c 79 20 70 61 73 73 65 73 20 74 68 65 20  rely passes the 
37760 73 75 62 74 79 70 65 0a 2a 2a 20 66 72 6f 6d 20  subtype.** from 
37770 74 68 65 20 72 65 73 75 6c 74 20 6f 66 20 6f 6e  the result of on
37780 65 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  e [application-d
37790 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74  efined SQL funct
377a0 69 6f 6e 5d 20 69 6e 74 6f 20 74 68 65 0a 2a 2a  ion] into the.**
377b0 20 69 6e 70 75 74 20 6f 66 20 61 6e 6f 74 68 65   input of anothe
377c0 72 2e 0a 2a 2f 0a 75 6e 73 69 67 6e 65 64 20 69  r..*/.unsigned i
377d0 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt sqlite3_value
377e0 5f 73 75 62 74 79 70 65 28 73 71 6c 69 74 65 33  _subtype(sqlite3
377f0 5f 76 61 6c 75 65 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  _value*);../*.**
37800 20 43 41 50 49 33 52 45 46 3a 20 43 6f 70 79 20   CAPI3REF: Copy 
37810 41 6e 64 20 46 72 65 65 20 53 51 4c 20 56 61 6c  And Free SQL Val
37820 75 65 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  ues.** METHOD: s
37830 71 6c 69 74 65 33 5f 76 61 6c 75 65 0a 2a 2a 0a  qlite3_value.**.
37840 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
37850 76 61 6c 75 65 5f 64 75 70 28 56 29 20 69 6e 74  value_dup(V) int
37860 65 72 66 61 63 65 20 6d 61 6b 65 73 20 61 20 63  erface makes a c
37870 6f 70 79 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  opy of the [sqli
37880 74 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20 6f 62  te3_value].** ob
37890 6a 65 63 74 20 44 20 61 6e 64 20 72 65 74 75 72  ject D and retur
378a0 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ns a pointer to 
378b0 74 68 61 74 20 63 6f 70 79 2e 20 20 5e 54 68 65  that copy.  ^The
378c0 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d   [sqlite3_value]
378d0 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 69 73 20   returned.** is 
378e0 61 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c  a [protected sql
378f0 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
37900 63 74 20 65 76 65 6e 20 69 66 20 74 68 65 20 69  ct even if the i
37910 6e 70 75 74 20 69 73 20 6e 6f 74 2e 0a 2a 2a 20  nput is not..** 
37920 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c  ^The sqlite3_val
37930 75 65 5f 64 75 70 28 56 29 20 69 6e 74 65 72 66  ue_dup(V) interf
37940 61 63 65 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c  ace returns NULL
37950 20 69 66 20 56 20 69 73 20 4e 55 4c 4c 20 6f 72   if V is NULL or
37960 20 69 66 20 61 0a 2a 2a 20 6d 65 6d 6f 72 79 20   if a.** memory 
37970 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 73  allocation fails
37980 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
37990 69 74 65 33 5f 76 61 6c 75 65 5f 66 72 65 65 28  ite3_value_free(
379a0 56 29 20 69 6e 74 65 72 66 61 63 65 20 66 72 65  V) interface fre
379b0 65 73 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 76  es an [sqlite3_v
379c0 61 6c 75 65 5d 20 6f 62 6a 65 63 74 0a 2a 2a 20  alue] object.** 
379d0 70 72 65 76 69 6f 75 73 6c 79 20 6f 62 74 61 69  previously obtai
379e0 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  ned from [sqlite
379f0 33 5f 76 61 6c 75 65 5f 64 75 70 28 29 5d 2e 20  3_value_dup()]. 
37a00 20 5e 49 66 20 56 20 69 73 20 61 20 4e 55 4c 4c   ^If V is a NULL
37a10 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 68 65 6e   pointer.** then
37a20 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 66   sqlite3_value_f
37a30 72 65 65 28 56 29 20 69 73 20 61 20 68 61 72 6d  ree(V) is a harm
37a40 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2f 0a 73  less no-op..*/.s
37a50 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 2a 73 71  qlite3_value *sq
37a60 6c 69 74 65 33 5f 76 61 6c 75 65 5f 64 75 70 28  lite3_value_dup(
37a70 63 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f 76 61  const sqlite3_va
37a80 6c 75 65 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69  lue*);.void sqli
37a90 74 65 33 5f 76 61 6c 75 65 5f 66 72 65 65 28 73  te3_value_free(s
37aa0 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
37ab0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
37ac0 20 4f 62 74 61 69 6e 20 41 67 67 72 65 67 61 74   Obtain Aggregat
37ad0 65 20 46 75 6e 63 74 69 6f 6e 20 43 6f 6e 74 65  e Function Conte
37ae0 78 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  xt.** METHOD: sq
37af0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 0a 2a 2a  lite3_context.**
37b00 0a 2a 2a 20 49 6d 70 6c 65 6d 65 6e 74 61 74 69  .** Implementati
37b10 6f 6e 73 20 6f 66 20 61 67 67 72 65 67 61 74 65  ons of aggregate
37b20 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 75   SQL functions u
37b30 73 65 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69  se this.** routi
37b40 6e 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d  ne to allocate m
37b50 65 6d 6f 72 79 20 66 6f 72 20 73 74 6f 72 69 6e  emory for storin
37b60 67 20 74 68 65 69 72 20 73 74 61 74 65 2e 0a 2a  g their state..*
37b70 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20  *.** ^The first 
37b80 74 69 6d 65 20 74 68 65 20 73 71 6c 69 74 65 33  time the sqlite3
37b90 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65  _aggregate_conte
37ba0 78 74 28 43 2c 4e 29 20 72 6f 75 74 69 6e 65 20  xt(C,N) routine 
37bb0 69 73 20 63 61 6c 6c 65 64 20 0a 2a 2a 20 66 6f  is called .** fo
37bc0 72 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 61  r a particular a
37bd0 67 67 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f  ggregate functio
37be0 6e 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6c 6c  n, SQLite.** all
37bf0 6f 63 61 74 65 73 20 4e 20 6f 66 20 6d 65 6d 6f  ocates N of memo
37c00 72 79 2c 20 7a 65 72 6f 65 73 20 6f 75 74 20 74  ry, zeroes out t
37c10 68 61 74 20 6d 65 6d 6f 72 79 2c 20 61 6e 64 20  hat memory, and 
37c20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65  returns a pointe
37c30 72 0a 2a 2a 20 74 6f 20 74 68 65 20 6e 65 77 20  r.** to the new 
37c40 6d 65 6d 6f 72 79 2e 20 5e 4f 6e 20 73 65 63 6f  memory. ^On seco
37c50 6e 64 20 61 6e 64 20 73 75 62 73 65 71 75 65 6e  nd and subsequen
37c60 74 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 73 71  t calls to.** sq
37c70 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f  lite3_aggregate_
37c80 63 6f 6e 74 65 78 74 28 29 20 66 6f 72 20 74 68  context() for th
37c90 65 20 73 61 6d 65 20 61 67 67 72 65 67 61 74 65  e same aggregate
37ca0 20 66 75 6e 63 74 69 6f 6e 20 69 6e 73 74 61 6e   function instan
37cb0 63 65 2c 0a 2a 2a 20 74 68 65 20 73 61 6d 65 20  ce,.** the same 
37cc0 62 75 66 66 65 72 20 69 73 20 72 65 74 75 72 6e  buffer is return
37cd0 65 64 2e 20 20 53 71 6c 69 74 65 33 5f 61 67 67  ed.  Sqlite3_agg
37ce0 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29  regate_context()
37cf0 20 69 73 20 6e 6f 72 6d 61 6c 6c 79 0a 2a 2a 20   is normally.** 
37d00 63 61 6c 6c 65 64 20 6f 6e 63 65 20 66 6f 72 20  called once for 
37d10 65 61 63 68 20 69 6e 76 6f 63 61 74 69 6f 6e 20  each invocation 
37d20 6f 66 20 74 68 65 20 78 53 74 65 70 20 63 61 6c  of the xStep cal
37d30 6c 62 61 63 6b 20 61 6e 64 20 74 68 65 6e 20 6f  lback and then o
37d40 6e 65 0a 2a 2a 20 6c 61 73 74 20 74 69 6d 65 20  ne.** last time 
37d50 77 68 65 6e 20 74 68 65 20 78 46 69 6e 61 6c 20  when the xFinal 
37d60 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f  callback is invo
37d70 6b 65 64 2e 20 20 5e 28 57 68 65 6e 20 6e 6f 20  ked.  ^(When no 
37d80 72 6f 77 73 20 6d 61 74 63 68 0a 2a 2a 20 61 6e  rows match.** an
37d90 20 61 67 67 72 65 67 61 74 65 20 71 75 65 72 79   aggregate query
37da0 2c 20 74 68 65 20 78 53 74 65 70 28 29 20 63 61  , the xStep() ca
37db0 6c 6c 62 61 63 6b 20 6f 66 20 74 68 65 20 61 67  llback of the ag
37dc0 67 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e  gregate function
37dd0 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  .** implementati
37de0 6f 6e 20 69 73 20 6e 65 76 65 72 20 63 61 6c 6c  on is never call
37df0 65 64 20 61 6e 64 20 78 46 69 6e 61 6c 28 29 20  ed and xFinal() 
37e00 69 73 20 63 61 6c 6c 65 64 20 65 78 61 63 74 6c  is called exactl
37e10 79 20 6f 6e 63 65 2e 0a 2a 2a 20 49 6e 20 74 68  y once..** In th
37e20 6f 73 65 20 63 61 73 65 73 2c 20 73 71 6c 69 74  ose cases, sqlit
37e30 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e  e3_aggregate_con
37e40 74 65 78 74 28 29 20 6d 69 67 68 74 20 62 65 20  text() might be 
37e50 63 61 6c 6c 65 64 20 66 6f 72 20 74 68 65 0a 2a  called for the.*
37e60 2a 20 66 69 72 73 74 20 74 69 6d 65 20 66 72 6f  * first time fro
37e70 6d 20 77 69 74 68 69 6e 20 78 46 69 6e 61 6c 28  m within xFinal(
37e80 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ).)^.**.** ^The 
37e90 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74  sqlite3_aggregat
37ea0 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20 72  e_context(C,N) r
37eb0 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61  outine returns a
37ec0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 0a 2a   NULL pointer .*
37ed0 2a 20 77 68 65 6e 20 66 69 72 73 74 20 63 61 6c  * when first cal
37ee0 6c 65 64 20 69 66 20 4e 20 69 73 20 6c 65 73 73  led if N is less
37ef0 20 74 68 61 6e 20 6f 72 20 65 71 75 61 6c 20 74   than or equal t
37f00 6f 20 7a 65 72 6f 20 6f 72 20 69 66 20 61 20 6d  o zero or if a m
37f10 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74  emory.** allocat
37f20 65 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2e 0a  e error occurs..
37f30 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 61 6d 6f 75  **.** ^(The amou
37f40 6e 74 20 6f 66 20 73 70 61 63 65 20 61 6c 6c 6f  nt of space allo
37f50 63 61 74 65 64 20 62 79 20 73 71 6c 69 74 65 33  cated by sqlite3
37f60 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65  _aggregate_conte
37f70 78 74 28 43 2c 4e 29 20 69 73 0a 2a 2a 20 64 65  xt(C,N) is.** de
37f80 74 65 72 6d 69 6e 65 64 20 62 79 20 74 68 65 20  termined by the 
37f90 4e 20 70 61 72 61 6d 65 74 65 72 20 6f 6e 20 66  N parameter on f
37fa0 69 72 73 74 20 73 75 63 63 65 73 73 66 75 6c 20  irst successful 
37fb0 63 61 6c 6c 2e 20 20 43 68 61 6e 67 69 6e 67 20  call.  Changing 
37fc0 74 68 65 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20  the.** value of 
37fd0 4e 20 69 6e 20 73 75 62 73 65 71 75 65 6e 74 20  N in subsequent 
37fe0 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f  call to sqlite3_
37ff0 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78  aggregate_contex
38000 74 28 29 20 77 69 74 68 69 6e 0a 2a 2a 20 74 68  t() within.** th
38010 65 20 73 61 6d 65 20 61 67 67 72 65 67 61 74 65  e same aggregate
38020 20 66 75 6e 63 74 69 6f 6e 20 69 6e 73 74 61 6e   function instan
38030 63 65 20 77 69 6c 6c 20 6e 6f 74 20 72 65 73 69  ce will not resi
38040 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79 0a 2a 2a  ze the memory.**
38050 20 61 6c 6c 6f 63 61 74 69 6f 6e 2e 29 5e 20 20   allocation.)^  
38060 57 69 74 68 69 6e 20 74 68 65 20 78 46 69 6e 61  Within the xFina
38070 6c 20 63 61 6c 6c 62 61 63 6b 2c 20 69 74 20 69  l callback, it i
38080 73 20 63 75 73 74 6f 6d 61 72 79 20 74 6f 20 73  s customary to s
38090 65 74 0a 2a 2a 20 4e 3d 30 20 69 6e 20 63 61 6c  et.** N=0 in cal
380a0 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 61 67  ls to sqlite3_ag
380b0 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28  gregate_context(
380c0 43 2c 4e 29 20 73 6f 20 74 68 61 74 20 6e 6f 20  C,N) so that no 
380d0 0a 2a 2a 20 70 6f 69 6e 74 6c 65 73 73 20 6d 65  .** pointless me
380e0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73  mory allocations
380f0 20 6f 63 63 75 72 2e 0a 2a 2a 0a 2a 2a 20 5e 53   occur..**.** ^S
38100 51 4c 69 74 65 20 61 75 74 6f 6d 61 74 69 63 61  QLite automatica
38110 6c 6c 79 20 66 72 65 65 73 20 74 68 65 20 6d 65  lly frees the me
38120 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 65 64 20 62  mory allocated b
38130 79 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 61 67  y .** sqlite3_ag
38140 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28  gregate_context(
38150 29 20 77 68 65 6e 20 74 68 65 20 61 67 67 72 65  ) when the aggre
38160 67 61 74 65 20 71 75 65 72 79 20 63 6f 6e 63 6c  gate query concl
38170 75 64 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  udes..**.** The 
38180 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
38190 6d 75 73 74 20 62 65 20 61 20 63 6f 70 79 20 6f  must be a copy o
381a0 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  f the.** [sqlite
381b0 33 5f 63 6f 6e 74 65 78 74 20 7c 20 53 51 4c 20  3_context | SQL 
381c0 66 75 6e 63 74 69 6f 6e 20 63 6f 6e 74 65 78 74  function context
381d0 5d 20 74 68 61 74 20 69 73 20 74 68 65 20 66 69  ] that is the fi
381e0 72 73 74 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a  rst parameter.**
381f0 20 74 6f 20 74 68 65 20 78 53 74 65 70 20 6f 72   to the xStep or
38200 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b   xFinal callback
38210 20 72 6f 75 74 69 6e 65 20 74 68 61 74 20 69 6d   routine that im
38220 70 6c 65 6d 65 6e 74 73 20 74 68 65 20 61 67 67  plements the agg
38230 72 65 67 61 74 65 0a 2a 2a 20 66 75 6e 63 74 69  regate.** functi
38240 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72  on..**.** This r
38250 6f 75 74 69 6e 65 20 6d 75 73 74 20 62 65 20 63  outine must be c
38260 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73  alled from the s
38270 61 6d 65 20 74 68 72 65 61 64 20 69 6e 20 77 68  ame thread in wh
38280 69 63 68 0a 2a 2a 20 74 68 65 20 61 67 67 72 65  ich.** the aggre
38290 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f  gate SQL functio
382a0 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f  n is running..*/
382b0 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 61  .void *sqlite3_a
382c0 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74  ggregate_context
382d0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
382e0 2a 2c 20 69 6e 74 20 6e 42 79 74 65 73 29 3b 0a  *, int nBytes);.
382f0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
38300 20 55 73 65 72 20 44 61 74 61 20 46 6f 72 20 46   User Data For F
38310 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 4d 45 54 48  unctions.** METH
38320 4f 44 3a 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74  OD: sqlite3_cont
38330 65 78 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ext.**.** ^The s
38340 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61  qlite3_user_data
38350 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  () interface ret
38360 75 72 6e 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a  urns a copy of.*
38370 2a 20 74 68 65 20 70 6f 69 6e 74 65 72 20 74 68  * the pointer th
38380 61 74 20 77 61 73 20 74 68 65 20 70 55 73 65 72  at was the pUser
38390 44 61 74 61 20 70 61 72 61 6d 65 74 65 72 20 28  Data parameter (
383a0 74 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65  the 5th paramete
383b0 72 29 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71  r).** of the [sq
383c0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
383d0 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20  ction()].** and 
383e0 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
383f0 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 20 72 6f  function16()] ro
38400 75 74 69 6e 65 73 20 74 68 61 74 20 6f 72 69 67  utines that orig
38410 69 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67 69 73 74  inally.** regist
38420 65 72 65 64 20 74 68 65 20 61 70 70 6c 69 63 61  ered the applica
38430 74 69 6f 6e 20 64 65 66 69 6e 65 64 20 66 75 6e  tion defined fun
38440 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 69  ction..**.** Thi
38450 73 20 72 6f 75 74 69 6e 65 20 6d 75 73 74 20 62  s routine must b
38460 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68  e called from th
38470 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e  e same thread in
38480 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 20 61 70   which.** the ap
38490 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
384a0 64 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75  d function is ru
384b0 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76 6f 69 64 20 2a  nning..*/.void *
384c0 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74  sqlite3_user_dat
384d0 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  a(sqlite3_contex
384e0 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  t*);../*.** CAPI
384f0 33 52 45 46 3a 20 44 61 74 61 62 61 73 65 20 43  3REF: Database C
38500 6f 6e 6e 65 63 74 69 6f 6e 20 46 6f 72 20 46 75  onnection For Fu
38510 6e 63 74 69 6f 6e 73 0a 2a 2a 20 4d 45 54 48 4f  nctions.** METHO
38520 44 3a 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  D: sqlite3_conte
38530 78 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  xt.**.** ^The sq
38540 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62  lite3_context_db
38550 5f 68 61 6e 64 6c 65 28 29 20 69 6e 74 65 72 66  _handle() interf
38560 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 63 6f  ace returns a co
38570 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 70 6f 69  py of.** the poi
38580 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 64 61 74  nter to the [dat
38590 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
385a0 5d 20 28 74 68 65 20 31 73 74 20 70 61 72 61 6d  ] (the 1st param
385b0 65 74 65 72 29 0a 2a 2a 20 6f 66 20 74 68 65 20  eter).** of the 
385c0 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
385d0 66 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61  function()].** a
385e0 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  nd [sqlite3_crea
385f0 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d  te_function16()]
38600 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 6f   routines that o
38610 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67  riginally.** reg
38620 69 73 74 65 72 65 64 20 74 68 65 20 61 70 70 6c  istered the appl
38630 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 64 20  ication defined 
38640 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2f 0a 73 71 6c  function..*/.sql
38650 69 74 65 33 20 2a 73 71 6c 69 74 65 33 5f 63 6f  ite3 *sqlite3_co
38660 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28  ntext_db_handle(
38670 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
38680 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
38690 45 46 3a 20 46 75 6e 63 74 69 6f 6e 20 41 75 78  EF: Function Aux
386a0 69 6c 69 61 72 79 20 44 61 74 61 0a 2a 2a 20 4d  iliary Data.** M
386b0 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 63  ETHOD: sqlite3_c
386c0 6f 6e 74 65 78 74 0a 2a 2a 0a 2a 2a 20 54 68 65  ontext.**.** The
386d0 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 6d 61 79  se functions may
386e0 20 62 65 20 75 73 65 64 20 62 79 20 28 6e 6f 6e   be used by (non
386f0 2d 61 67 67 72 65 67 61 74 65 29 20 53 51 4c 20  -aggregate) SQL 
38700 66 75 6e 63 74 69 6f 6e 73 20 74 6f 0a 2a 2a 20  functions to.** 
38710 61 73 73 6f 63 69 61 74 65 20 6d 65 74 61 64 61  associate metada
38720 74 61 20 77 69 74 68 20 61 72 67 75 6d 65 6e 74  ta with argument
38730 20 76 61 6c 75 65 73 2e 20 49 66 20 74 68 65 20   values. If the 
38740 73 61 6d 65 20 76 61 6c 75 65 20 69 73 20 70 61  same value is pa
38750 73 73 65 64 20 74 6f 0a 2a 2a 20 6d 75 6c 74 69  ssed to.** multi
38760 70 6c 65 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20  ple invocations 
38770 6f 66 20 74 68 65 20 73 61 6d 65 20 53 51 4c 20  of the same SQL 
38780 66 75 6e 63 74 69 6f 6e 20 64 75 72 69 6e 67 20  function during 
38790 71 75 65 72 79 20 65 78 65 63 75 74 69 6f 6e 2c  query execution,
387a0 20 75 6e 64 65 72 0a 2a 2a 20 73 6f 6d 65 20 63   under.** some c
387b0 69 72 63 75 6d 73 74 61 6e 63 65 73 20 74 68 65  ircumstances the
387c0 20 61 73 73 6f 63 69 61 74 65 64 20 6d 65 74 61   associated meta
387d0 64 61 74 61 20 6d 61 79 20 62 65 20 70 72 65 73  data may be pres
387e0 65 72 76 65 64 2e 20 20 41 6e 20 65 78 61 6d 70  erved.  An examp
387f0 6c 65 0a 2a 2a 20 6f 66 20 77 68 65 72 65 20 74  le.** of where t
38800 68 69 73 20 6d 69 67 68 74 20 62 65 20 75 73 65