/ Hex Artifact Content
Login

Artifact 8078d183ab1bbe1263365fbc1bcd2f31fc46a6ef:


0000: 2f 2a 0a 2a 2a 20 32 30 30 31 20 53 65 70 74 65  /*.** 2001 Septe
0010: 6d 62 65 72 20 31 35 0a 2a 2a 0a 2a 2a 20 54 68  mber 15.**.** Th
0020: 65 20 61 75 74 68 6f 72 20 64 69 73 63 6c 61 69  e author disclai
0030: 6d 73 20 63 6f 70 79 72 69 67 68 74 20 74 6f 20  ms copyright to 
0040: 74 68 69 73 20 73 6f 75 72 63 65 20 63 6f 64 65  this source code
0050: 2e 20 20 49 6e 20 70 6c 61 63 65 20 6f 66 0a 2a  .  In place of.*
0060: 2a 20 61 20 6c 65 67 61 6c 20 6e 6f 74 69 63 65  * a legal notice
0070: 2c 20 68 65 72 65 20 69 73 20 61 20 62 6c 65 73  , here is a bles
0080: 73 69 6e 67 3a 0a 2a 2a 0a 2a 2a 20 20 20 20 4d  sing:.**.**    M
0090: 61 79 20 79 6f 75 20 64 6f 20 67 6f 6f 64 20 61  ay you do good a
00a0: 6e 64 20 6e 6f 74 20 65 76 69 6c 2e 0a 2a 2a 20  nd not evil..** 
00b0: 20 20 20 4d 61 79 20 79 6f 75 20 66 69 6e 64 20     May you find 
00c0: 66 6f 72 67 69 76 65 6e 65 73 73 20 66 6f 72 20  forgiveness for 
00d0: 79 6f 75 72 73 65 6c 66 20 61 6e 64 20 66 6f 72  yourself and for
00e0: 67 69 76 65 20 6f 74 68 65 72 73 2e 0a 2a 2a 20  give others..** 
00f0: 20 20 20 4d 61 79 20 79 6f 75 20 73 68 61 72 65     May you share
0100: 20 66 72 65 65 6c 79 2c 20 6e 65 76 65 72 20 74   freely, never t
0110: 61 6b 69 6e 67 20 6d 6f 72 65 20 74 68 61 6e 20  aking more than 
0120: 79 6f 75 20 67 69 76 65 2e 0a 2a 2a 0a 2a 2a 2a  you give..**.***
0130: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0140: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0150: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0160: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0170: 2a 2a 2a 2a 2a 2a 0a 2a 2a 20 54 68 69 73 20 68  ******.** This h
0180: 65 61 64 65 72 20 66 69 6c 65 20 64 65 66 69 6e  eader file defin
0190: 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  es the interface
01a0: 20 74 68 61 74 20 74 68 65 20 53 51 4c 69 74 65   that the SQLite
01b0: 20 6c 69 62 72 61 72 79 0a 2a 2a 20 70 72 65 73   library.** pres
01c0: 65 6e 74 73 20 74 6f 20 63 6c 69 65 6e 74 20 70  ents to client p
01d0: 72 6f 67 72 61 6d 73 2e 20 20 49 66 20 61 20 43  rograms.  If a C
01e0: 2d 66 75 6e 63 74 69 6f 6e 2c 20 73 74 72 75 63  -function, struc
01f0: 74 75 72 65 2c 20 64 61 74 61 74 79 70 65 2c 0a  ture, datatype,.
0200: 2a 2a 20 6f 72 20 63 6f 6e 73 74 61 6e 74 20 64  ** or constant d
0210: 65 66 69 6e 69 74 69 6f 6e 20 64 6f 65 73 20 6e  efinition does n
0220: 6f 74 20 61 70 70 65 61 72 20 69 6e 20 74 68 69  ot appear in thi
0230: 73 20 66 69 6c 65 2c 20 74 68 65 6e 20 69 74 20  s file, then it 
0240: 69 73 0a 2a 2a 20 6e 6f 74 20 61 20 70 75 62 6c  is.** not a publ
0250: 69 73 68 65 64 20 41 50 49 20 6f 66 20 53 51 4c  ished API of SQL
0260: 69 74 65 2c 20 69 73 20 73 75 62 6a 65 63 74 20  ite, is subject 
0270: 74 6f 20 63 68 61 6e 67 65 20 77 69 74 68 6f 75  to change withou
0280: 74 0a 2a 2a 20 6e 6f 74 69 63 65 2c 20 61 6e 64  t.** notice, and
0290: 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 72   should not be r
02a0: 65 66 65 72 65 6e 63 65 64 20 62 79 20 70 72 6f  eferenced by pro
02b0: 67 72 61 6d 73 20 74 68 61 74 20 75 73 65 20 53  grams that use S
02c0: 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 53 6f 6d  QLite..**.** Som
02d0: 65 20 6f 66 20 74 68 65 20 64 65 66 69 6e 69 74  e of the definit
02e0: 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20 69 6e  ions that are in
02f0: 20 74 68 69 73 20 66 69 6c 65 20 61 72 65 20 6d   this file are m
0300: 61 72 6b 65 64 20 61 73 0a 2a 2a 20 22 65 78 70  arked as.** "exp
0310: 65 72 69 6d 65 6e 74 61 6c 22 2e 20 20 45 78 70  erimental".  Exp
0320: 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74 65 72 66  erimental interf
0330: 61 63 65 73 20 61 72 65 20 6e 6f 72 6d 61 6c 6c  aces are normall
0340: 79 20 6e 65 77 0a 2a 2a 20 66 65 61 74 75 72 65  y new.** feature
0350: 73 20 72 65 63 65 6e 74 6c 79 20 61 64 64 65 64  s recently added
0360: 20 74 6f 20 53 51 4c 69 74 65 2e 20 20 57 65 20   to SQLite.  We 
0370: 64 6f 20 6e 6f 74 20 61 6e 74 69 63 69 70 61 74  do not anticipat
0380: 65 20 63 68 61 6e 67 65 73 0a 2a 2a 20 74 6f 20  e changes.** to 
0390: 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74  experimental int
03a0: 65 72 66 61 63 65 73 20 62 75 74 20 72 65 73 65  erfaces but rese
03b0: 72 76 65 20 74 68 65 20 72 69 67 68 74 20 74 6f  rve the right to
03c0: 20 6d 61 6b 65 20 6d 69 6e 6f 72 20 63 68 61 6e   make minor chan
03d0: 67 65 73 0a 2a 2a 20 69 66 20 65 78 70 65 72 69  ges.** if experi
03e0: 65 6e 63 65 20 66 72 6f 6d 20 75 73 65 20 22 69  ence from use "i
03f0: 6e 20 74 68 65 20 77 69 6c 64 22 20 73 75 67 67  n the wild" sugg
0400: 65 73 74 20 73 75 63 68 20 63 68 61 6e 67 65 73  est such changes
0410: 20 61 72 65 20 70 72 75 64 65 6e 74 2e 0a 2a 2a   are prudent..**
0420: 0a 2a 2a 20 54 68 65 20 6f 66 66 69 63 69 61 6c  .** The official
0430: 20 43 2d 6c 61 6e 67 75 61 67 65 20 41 50 49 20   C-language API 
0440: 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f  documentation fo
0450: 72 20 53 51 4c 69 74 65 20 69 73 20 64 65 72 69  r SQLite is deri
0460: 76 65 64 0a 2a 2a 20 66 72 6f 6d 20 63 6f 6d 6d  ved.** from comm
0470: 65 6e 74 73 20 69 6e 20 74 68 69 73 20 66 69 6c  ents in this fil
0480: 65 2e 20 20 54 68 69 73 20 66 69 6c 65 20 69 73  e.  This file is
0490: 20 74 68 65 20 61 75 74 68 6f 72 69 74 61 74 69   the authoritati
04a0: 76 65 20 73 6f 75 72 63 65 0a 2a 2a 20 6f 6e 20  ve source.** on 
04b0: 68 6f 77 20 53 51 4c 69 74 65 20 69 6e 74 65 72  how SQLite inter
04c0: 66 61 63 65 73 20 61 72 65 20 73 75 70 70 6f 73  faces are suppos
04d0: 65 64 20 74 6f 20 6f 70 65 72 61 74 65 2e 0a 2a  ed to operate..*
04e0: 2a 0a 2a 2a 20 54 68 65 20 6e 61 6d 65 20 6f 66  *.** The name of
04f0: 20 74 68 69 73 20 66 69 6c 65 20 75 6e 64 65 72   this file under
0500: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6d   configuration m
0510: 61 6e 61 67 65 6d 65 6e 74 20 69 73 20 22 73 71  anagement is "sq
0520: 6c 69 74 65 2e 68 2e 69 6e 22 2e 0a 2a 2a 20 54  lite.h.in"..** T
0530: 68 65 20 6d 61 6b 65 66 69 6c 65 20 6d 61 6b 65  he makefile make
0540: 73 20 73 6f 6d 65 20 6d 69 6e 6f 72 20 63 68 61  s some minor cha
0550: 6e 67 65 73 20 74 6f 20 74 68 69 73 20 66 69 6c  nges to this fil
0560: 65 20 28 73 75 63 68 20 61 73 20 69 6e 73 65 72  e (such as inser
0570: 74 69 6e 67 0a 2a 2a 20 74 68 65 20 76 65 72 73  ting.** the vers
0580: 69 6f 6e 20 6e 75 6d 62 65 72 29 20 61 6e 64 20  ion number) and 
0590: 63 68 61 6e 67 65 73 20 69 74 73 20 6e 61 6d 65  changes its name
05a0: 20 74 6f 20 22 73 71 6c 69 74 65 33 2e 68 22 20   to "sqlite3.h" 
05b0: 61 73 0a 2a 2a 20 70 61 72 74 20 6f 66 20 74 68  as.** part of th
05c0: 65 20 62 75 69 6c 64 20 70 72 6f 63 65 73 73 2e  e build process.
05d0: 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c 49  .*/.#ifndef SQLI
05e0: 54 45 33 5f 48 0a 23 64 65 66 69 6e 65 20 53 51  TE3_H.#define SQ
05f0: 4c 49 54 45 33 5f 48 0a 23 69 6e 63 6c 75 64 65  LITE3_H.#include
0600: 20 3c 73 74 64 61 72 67 2e 68 3e 20 20 20 20 20   <stdarg.h>     
0610: 2f 2a 20 4e 65 65 64 65 64 20 66 6f 72 20 74 68  /* Needed for th
0620: 65 20 64 65 66 69 6e 69 74 69 6f 6e 20 6f 66 20  e definition of 
0630: 76 61 5f 6c 69 73 74 20 2a 2f 0a 0a 2f 2a 0a 2a  va_list */../*.*
0640: 2a 20 4d 61 6b 65 20 73 75 72 65 20 77 65 20 63  * Make sure we c
0650: 61 6e 20 63 61 6c 6c 20 74 68 69 73 20 73 74 75  an call this stu
0660: 66 66 20 66 72 6f 6d 20 43 2b 2b 2e 0a 2a 2f 0a  ff from C++..*/.
0670: 23 69 66 64 65 66 20 5f 5f 63 70 6c 75 73 70 6c  #ifdef __cpluspl
0680: 75 73 0a 65 78 74 65 72 6e 20 22 43 22 20 7b 0a  us.extern "C" {.
0690: 23 65 6e 64 69 66 0a 0a 0a 2f 2a 0a 2a 2a 20 50  #endif.../*.** P
06a0: 72 6f 76 69 64 65 20 74 68 65 20 61 62 69 6c 69  rovide the abili
06b0: 74 79 20 74 6f 20 6f 76 65 72 72 69 64 65 20 6c  ty to override l
06c0: 69 6e 6b 61 67 65 20 66 65 61 74 75 72 65 73 20  inkage features 
06d0: 6f 66 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  of the interface
06e0: 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c  ..*/.#ifndef SQL
06f0: 49 54 45 5f 45 58 54 45 52 4e 0a 23 20 64 65 66  ITE_EXTERN.# def
0700: 69 6e 65 20 53 51 4c 49 54 45 5f 45 58 54 45 52  ine SQLITE_EXTER
0710: 4e 20 65 78 74 65 72 6e 0a 23 65 6e 64 69 66 0a  N extern.#endif.
0720: 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 41  #ifndef SQLITE_A
0730: 50 49 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49  PI.# define SQLI
0740: 54 45 5f 41 50 49 0a 23 65 6e 64 69 66 0a 23 69  TE_API.#endif.#i
0750: 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 43 44 45  fndef SQLITE_CDE
0760: 43 4c 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49  CL.# define SQLI
0770: 54 45 5f 43 44 45 43 4c 0a 23 65 6e 64 69 66 0a  TE_CDECL.#endif.
0780: 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 41  #ifndef SQLITE_A
0790: 50 49 43 41 4c 4c 0a 23 20 64 65 66 69 6e 65 20  PICALL.# define 
07a0: 53 51 4c 49 54 45 5f 41 50 49 43 41 4c 4c 0a 23  SQLITE_APICALL.#
07b0: 65 6e 64 69 66 0a 23 69 66 6e 64 65 66 20 53 51  endif.#ifndef SQ
07c0: 4c 49 54 45 5f 53 54 44 43 41 4c 4c 0a 23 20 64  LITE_STDCALL.# d
07d0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 54 44  efine SQLITE_STD
07e0: 43 41 4c 4c 20 53 51 4c 49 54 45 5f 41 50 49 43  CALL SQLITE_APIC
07f0: 41 4c 4c 0a 23 65 6e 64 69 66 0a 23 69 66 6e 64  ALL.#endif.#ifnd
0800: 65 66 20 53 51 4c 49 54 45 5f 43 41 4c 4c 42 41  ef SQLITE_CALLBA
0810: 43 4b 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49  CK.# define SQLI
0820: 54 45 5f 43 41 4c 4c 42 41 43 4b 0a 23 65 6e 64  TE_CALLBACK.#end
0830: 69 66 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54  if.#ifndef SQLIT
0840: 45 5f 53 59 53 41 50 49 0a 23 20 64 65 66 69 6e  E_SYSAPI.# defin
0850: 65 20 53 51 4c 49 54 45 5f 53 59 53 41 50 49 0a  e SQLITE_SYSAPI.
0860: 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 54 68  #endif../*.** Th
0870: 65 73 65 20 6e 6f 2d 6f 70 20 6d 61 63 72 6f 73  ese no-op macros
0880: 20 61 72 65 20 75 73 65 64 20 69 6e 20 66 72 6f   are used in fro
0890: 6e 74 20 6f 66 20 69 6e 74 65 72 66 61 63 65 73  nt of interfaces
08a0: 20 74 6f 20 6d 61 72 6b 20 74 68 6f 73 65 0a 2a   to mark those.*
08b0: 2a 20 69 6e 74 65 72 66 61 63 65 73 20 61 73 20  * interfaces as 
08c0: 65 69 74 68 65 72 20 64 65 70 72 65 63 61 74 65  either deprecate
08d0: 64 20 6f 72 20 65 78 70 65 72 69 6d 65 6e 74 61  d or experimenta
08e0: 6c 2e 20 20 4e 65 77 20 61 70 70 6c 69 63 61 74  l.  New applicat
08f0: 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e  ions.** should n
0900: 6f 74 20 75 73 65 20 64 65 70 72 65 63 61 74 65  ot use deprecate
0910: 64 20 69 6e 74 65 72 66 61 63 65 73 20 2d 20 74  d interfaces - t
0920: 68 65 79 20 61 72 65 20 73 75 70 70 6f 72 74 65  hey are supporte
0930: 64 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73 0a  d for backwards.
0940: 2a 2a 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79  ** compatibility
0950: 20 6f 6e 6c 79 2e 20 20 41 70 70 6c 69 63 61 74   only.  Applicat
0960: 69 6f 6e 20 77 72 69 74 65 72 73 20 73 68 6f 75  ion writers shou
0970: 6c 64 20 62 65 20 61 77 61 72 65 20 74 68 61 74  ld be aware that
0980: 0a 2a 2a 20 65 78 70 65 72 69 6d 65 6e 74 61 6c  .** experimental
0990: 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20   interfaces are 
09a0: 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67  subject to chang
09b0: 65 20 69 6e 20 70 6f 69 6e 74 20 72 65 6c 65 61  e in point relea
09c0: 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ses..**.** These
09d0: 20 6d 61 63 72 6f 73 20 75 73 65 64 20 74 6f 20   macros used to 
09e0: 72 65 73 6f 6c 76 65 20 74 6f 20 76 61 72 69 6f  resolve to vario
09f0: 75 73 20 6b 69 6e 64 73 20 6f 66 20 63 6f 6d 70  us kinds of comp
0a00: 69 6c 65 72 20 6d 61 67 69 63 20 74 68 61 74 0a  iler magic that.
0a10: 2a 2a 20 77 6f 75 6c 64 20 67 65 6e 65 72 61 74  ** would generat
0a20: 65 20 77 61 72 6e 69 6e 67 20 6d 65 73 73 61 67  e warning messag
0a30: 65 73 20 77 68 65 6e 20 74 68 65 79 20 77 65 72  es when they wer
0a40: 65 20 75 73 65 64 2e 20 20 42 75 74 20 74 68 61  e used.  But tha
0a50: 74 0a 2a 2a 20 63 6f 6d 70 69 6c 65 72 20 6d 61  t.** compiler ma
0a60: 67 69 63 20 65 6e 64 65 64 20 75 70 20 67 65 6e  gic ended up gen
0a70: 65 72 61 74 69 6e 67 20 73 75 63 68 20 61 20 66  erating such a f
0a80: 6c 75 72 72 79 20 6f 66 20 62 75 67 20 72 65 70  lurry of bug rep
0a90: 6f 72 74 73 0a 2a 2a 20 74 68 61 74 20 77 65 20  orts.** that we 
0aa0: 68 61 76 65 20 74 61 6b 65 6e 20 69 74 20 61 6c  have taken it al
0ab0: 6c 20 6f 75 74 20 61 6e 64 20 67 6f 6e 65 20 62  l out and gone b
0ac0: 61 63 6b 20 74 6f 20 75 73 69 6e 67 20 73 69 6d  ack to using sim
0ad0: 70 6c 65 0a 2a 2a 20 6e 6f 6f 70 20 6d 61 63 72  ple.** noop macr
0ae0: 6f 73 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  os..*/.#define S
0af0: 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44  QLITE_DEPRECATED
0b00: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
0b10: 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a 0a 2f 2a  EXPERIMENTAL../*
0b20: 0a 2a 2a 20 45 6e 73 75 72 65 20 74 68 65 73 65  .** Ensure these
0b30: 20 73 79 6d 62 6f 6c 73 20 77 65 72 65 20 6e 6f   symbols were no
0b40: 74 20 64 65 66 69 6e 65 64 20 62 79 20 73 6f 6d  t defined by som
0b50: 65 20 70 72 65 76 69 6f 75 73 20 68 65 61 64 65  e previous heade
0b60: 72 20 66 69 6c 65 2e 0a 2a 2f 0a 23 69 66 64 65  r file..*/.#ifde
0b70: 66 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e  f SQLITE_VERSION
0b80: 0a 23 20 75 6e 64 65 66 20 53 51 4c 49 54 45 5f  .# undef SQLITE_
0b90: 56 45 52 53 49 4f 4e 0a 23 65 6e 64 69 66 0a 23  VERSION.#endif.#
0ba0: 69 66 64 65 66 20 53 51 4c 49 54 45 5f 56 45 52  ifdef SQLITE_VER
0bb0: 53 49 4f 4e 5f 4e 55 4d 42 45 52 0a 23 20 75 6e  SION_NUMBER.# un
0bc0: 64 65 66 20 53 51 4c 49 54 45 5f 56 45 52 53 49  def SQLITE_VERSI
0bd0: 4f 4e 5f 4e 55 4d 42 45 52 0a 23 65 6e 64 69 66  ON_NUMBER.#endif
0be0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
0bf0: 3a 20 43 6f 6d 70 69 6c 65 2d 54 69 6d 65 20 4c  : Compile-Time L
0c00: 69 62 72 61 72 79 20 56 65 72 73 69 6f 6e 20 4e  ibrary Version N
0c10: 75 6d 62 65 72 73 0a 2a 2a 0a 2a 2a 20 5e 28 54  umbers.**.** ^(T
0c20: 68 65 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49  he [SQLITE_VERSI
0c30: 4f 4e 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73  ON] C preprocess
0c40: 6f 72 20 6d 61 63 72 6f 20 69 6e 20 74 68 65 20  or macro in the 
0c50: 73 71 6c 69 74 65 33 2e 68 20 68 65 61 64 65 72  sqlite3.h header
0c60: 0a 2a 2a 20 65 76 61 6c 75 61 74 65 73 20 74 6f  .** evaluates to
0c70: 20 61 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61   a string litera
0c80: 6c 20 74 68 61 74 20 69 73 20 74 68 65 20 53 51  l that is the SQ
0c90: 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 69 6e 20  Lite version in 
0ca0: 74 68 65 0a 2a 2a 20 66 6f 72 6d 61 74 20 22 58  the.** format "X
0cb0: 2e 59 2e 5a 22 20 77 68 65 72 65 20 58 20 69 73  .Y.Z" where X is
0cc0: 20 74 68 65 20 6d 61 6a 6f 72 20 76 65 72 73 69   the major versi
0cd0: 6f 6e 20 6e 75 6d 62 65 72 20 28 61 6c 77 61 79  on number (alway
0ce0: 73 20 33 20 66 6f 72 0a 2a 2a 20 53 51 4c 69 74  s 3 for.** SQLit
0cf0: 65 33 29 20 61 6e 64 20 59 20 69 73 20 74 68 65  e3) and Y is the
0d00: 20 6d 69 6e 6f 72 20 76 65 72 73 69 6f 6e 20 6e   minor version n
0d10: 75 6d 62 65 72 20 61 6e 64 20 5a 20 69 73 20 74  umber and Z is t
0d20: 68 65 20 72 65 6c 65 61 73 65 20 6e 75 6d 62 65  he release numbe
0d30: 72 2e 29 5e 0a 2a 2a 20 5e 28 54 68 65 20 5b 53  r.)^.** ^(The [S
0d40: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55  QLITE_VERSION_NU
0d50: 4d 42 45 52 5d 20 43 20 70 72 65 70 72 6f 63 65  MBER] C preproce
0d60: 73 73 6f 72 20 6d 61 63 72 6f 20 72 65 73 6f 6c  ssor macro resol
0d70: 76 65 73 20 74 6f 20 61 6e 20 69 6e 74 65 67 65  ves to an intege
0d80: 72 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 76 61  r.** with the va
0d90: 6c 75 65 20 28 58 2a 31 30 30 30 30 30 30 20 2b  lue (X*1000000 +
0da0: 20 59 2a 31 30 30 30 20 2b 20 5a 29 20 77 68 65   Y*1000 + Z) whe
0db0: 72 65 20 58 2c 20 59 2c 20 61 6e 64 20 5a 20 61  re X, Y, and Z a
0dc0: 72 65 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 6e  re the same.** n
0dd0: 75 6d 62 65 72 73 20 75 73 65 64 20 69 6e 20 5b  umbers used in [
0de0: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d 2e  SQLITE_VERSION].
0df0: 29 5e 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45  )^.** The SQLITE
0e00: 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20  _VERSION_NUMBER 
0e10: 66 6f 72 20 61 6e 79 20 67 69 76 65 6e 20 72 65  for any given re
0e20: 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65 20  lease of SQLite 
0e30: 77 69 6c 6c 20 61 6c 73 6f 0a 2a 2a 20 62 65 20  will also.** be 
0e40: 6c 61 72 67 65 72 20 74 68 61 6e 20 74 68 65 20  larger than the 
0e50: 72 65 6c 65 61 73 65 20 66 72 6f 6d 20 77 68 69  release from whi
0e60: 63 68 20 69 74 20 69 73 20 64 65 72 69 76 65 64  ch it is derived
0e70: 2e 20 20 45 69 74 68 65 72 20 59 20 77 69 6c 6c  .  Either Y will
0e80: 0a 2a 2a 20 62 65 20 68 65 6c 64 20 63 6f 6e 73  .** be held cons
0e90: 74 61 6e 74 20 61 6e 64 20 5a 20 77 69 6c 6c 20  tant and Z will 
0ea0: 62 65 20 69 6e 63 72 65 6d 65 6e 74 65 64 20 6f  be incremented o
0eb0: 72 20 65 6c 73 65 20 59 20 77 69 6c 6c 20 62 65  r else Y will be
0ec0: 20 69 6e 63 72 65 6d 65 6e 74 65 64 0a 2a 2a 20   incremented.** 
0ed0: 61 6e 64 20 5a 20 77 69 6c 6c 20 62 65 20 72 65  and Z will be re
0ee0: 73 65 74 20 74 6f 20 7a 65 72 6f 2e 0a 2a 2a 0a  set to zero..**.
0ef0: 2a 2a 20 53 69 6e 63 65 20 5b 76 65 72 73 69 6f  ** Since [versio
0f00: 6e 20 33 2e 36 2e 31 38 5d 20 28 5b 64 61 74 65  n 3.6.18] ([date
0f10: 6f 66 3a 33 2e 36 2e 31 38 5d 29 2c 20 0a 2a 2a  of:3.6.18]), .**
0f20: 20 53 51 4c 69 74 65 20 73 6f 75 72 63 65 20 63   SQLite source c
0f30: 6f 64 65 20 68 61 73 20 62 65 65 6e 20 73 74 6f  ode has been sto
0f40: 72 65 64 20 69 6e 20 74 68 65 0a 2a 2a 20 3c 61  red in the.** <a
0f50: 20 68 72 65 66 3d 22 68 74 74 70 3a 2f 2f 77 77   href="http://ww
0f60: 77 2e 66 6f 73 73 69 6c 2d 73 63 6d 2e 6f 72 67  w.fossil-scm.org
0f70: 2f 22 3e 46 6f 73 73 69 6c 20 63 6f 6e 66 69 67  /">Fossil config
0f80: 75 72 61 74 69 6f 6e 20 6d 61 6e 61 67 65 6d 65  uration manageme
0f90: 6e 74 0a 2a 2a 20 73 79 73 74 65 6d 3c 2f 61 3e  nt.** system</a>
0fa0: 2e 20 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 53  .  ^The SQLITE_S
0fb0: 4f 55 52 43 45 5f 49 44 20 6d 61 63 72 6f 20 65  OURCE_ID macro e
0fc0: 76 61 6c 75 61 74 65 73 20 74 6f 0a 2a 2a 20 61  valuates to.** a
0fd0: 20 73 74 72 69 6e 67 20 77 68 69 63 68 20 69 64   string which id
0fe0: 65 6e 74 69 66 69 65 73 20 61 20 70 61 72 74 69  entifies a parti
0ff0: 63 75 6c 61 72 20 63 68 65 63 6b 2d 69 6e 20 6f  cular check-in o
1000: 66 20 53 51 4c 69 74 65 0a 2a 2a 20 77 69 74 68  f SQLite.** with
1010: 69 6e 20 69 74 73 20 63 6f 6e 66 69 67 75 72 61  in its configura
1020: 74 69 6f 6e 20 6d 61 6e 61 67 65 6d 65 6e 74 20  tion management 
1030: 73 79 73 74 65 6d 2e 20 20 5e 54 68 65 20 53 51  system.  ^The SQ
1040: 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 0a 2a  LITE_SOURCE_ID.*
1050: 2a 20 73 74 72 69 6e 67 20 63 6f 6e 74 61 69 6e  * string contain
1060: 73 20 74 68 65 20 64 61 74 65 20 61 6e 64 20 74  s the date and t
1070: 69 6d 65 20 6f 66 20 74 68 65 20 63 68 65 63 6b  ime of the check
1080: 2d 69 6e 20 28 55 54 43 29 20 61 6e 64 20 61 6e  -in (UTC) and an
1090: 20 53 48 41 31 0a 2a 2a 20 68 61 73 68 20 6f 66   SHA1.** hash of
10a0: 20 74 68 65 20 65 6e 74 69 72 65 20 73 6f 75 72   the entire sour
10b0: 63 65 20 74 72 65 65 2e 0a 2a 2a 0a 2a 2a 20 53  ce tree..**.** S
10c0: 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65  ee also: [sqlite
10d0: 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29 5d 2c  3_libversion()],
10e0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6c 69 62  .** [sqlite3_lib
10f0: 76 65 72 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 29  version_number()
1100: 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73 6f 75 72  ], [sqlite3_sour
1110: 63 65 69 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c  ceid()],.** [sql
1120: 69 74 65 5f 76 65 72 73 69 6f 6e 28 29 5d 20 61  ite_version()] a
1130: 6e 64 20 5b 73 71 6c 69 74 65 5f 73 6f 75 72 63  nd [sqlite_sourc
1140: 65 5f 69 64 28 29 5d 2e 0a 2a 2f 0a 23 64 65 66  e_id()]..*/.#def
1150: 69 6e 65 20 53 51 4c 49 54 45 5f 56 45 52 53 49  ine SQLITE_VERSI
1160: 4f 4e 20 20 20 20 20 20 20 20 22 2d 2d 56 45 52  ON        "--VER
1170: 53 2d 2d 22 0a 23 64 65 66 69 6e 65 20 53 51 4c  S--".#define SQL
1180: 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42  ITE_VERSION_NUMB
1190: 45 52 20 2d 2d 56 45 52 53 49 4f 4e 2d 4e 55 4d  ER --VERSION-NUM
11a0: 42 45 52 2d 2d 0a 23 64 65 66 69 6e 65 20 53 51  BER--.#define SQ
11b0: 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 20 20  LITE_SOURCE_ID  
11c0: 20 20 20 20 22 2d 2d 53 4f 55 52 43 45 2d 49 44      "--SOURCE-ID
11d0: 2d 2d 22 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  --"../*.** CAPI3
11e0: 52 45 46 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69  REF: Run-Time Li
11f0: 62 72 61 72 79 20 56 65 72 73 69 6f 6e 20 4e 75  brary Version Nu
1200: 6d 62 65 72 73 0a 2a 2a 20 4b 45 59 57 4f 52 44  mbers.** KEYWORD
1210: 53 3a 20 73 71 6c 69 74 65 33 5f 76 65 72 73 69  S: sqlite3_versi
1220: 6f 6e 2c 20 73 71 6c 69 74 65 33 5f 73 6f 75 72  on, sqlite3_sour
1230: 63 65 69 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ceid.**.** These
1240: 20 69 6e 74 65 72 66 61 63 65 73 20 70 72 6f 76   interfaces prov
1250: 69 64 65 20 74 68 65 20 73 61 6d 65 20 69 6e 66  ide the same inf
1260: 6f 72 6d 61 74 69 6f 6e 20 61 73 20 74 68 65 20  ormation as the 
1270: 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d  [SQLITE_VERSION]
1280: 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 56 45 52  ,.** [SQLITE_VER
1290: 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d 2c 20 61 6e  SION_NUMBER], an
12a0: 64 20 5b 53 51 4c 49 54 45 5f 53 4f 55 52 43 45  d [SQLITE_SOURCE
12b0: 5f 49 44 5d 20 43 20 70 72 65 70 72 6f 63 65 73  _ID] C preproces
12c0: 73 6f 72 20 6d 61 63 72 6f 73 0a 2a 2a 20 62 75  sor macros.** bu
12d0: 74 20 61 72 65 20 61 73 73 6f 63 69 61 74 65 64  t are associated
12e0: 20 77 69 74 68 20 74 68 65 20 6c 69 62 72 61 72   with the librar
12f0: 79 20 69 6e 73 74 65 61 64 20 6f 66 20 74 68 65  y instead of the
1300: 20 68 65 61 64 65 72 20 66 69 6c 65 2e 20 20 5e   header file.  ^
1310: 28 43 61 75 74 69 6f 75 73 0a 2a 2a 20 70 72 6f  (Cautious.** pro
1320: 67 72 61 6d 6d 65 72 73 20 6d 69 67 68 74 20 69  grammers might i
1330: 6e 63 6c 75 64 65 20 61 73 73 65 72 74 28 29 20  nclude assert() 
1340: 73 74 61 74 65 6d 65 6e 74 73 20 69 6e 20 74 68  statements in th
1350: 65 69 72 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  eir application 
1360: 74 6f 0a 2a 2a 20 76 65 72 69 66 79 20 74 68 61  to.** verify tha
1370: 74 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e 65  t values returne
1380: 64 20 62 79 20 74 68 65 73 65 20 69 6e 74 65 72  d by these inter
1390: 66 61 63 65 73 20 6d 61 74 63 68 20 74 68 65 20  faces match the 
13a0: 6d 61 63 72 6f 73 20 69 6e 0a 2a 2a 20 74 68 65  macros in.** the
13b0: 20 68 65 61 64 65 72 2c 20 61 6e 64 20 74 68 75   header, and thu
13c0: 73 20 65 6e 73 75 72 65 20 74 68 61 74 20 74 68  s ensure that th
13d0: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 73  e application is
13e0: 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 77 69 74  .** compiled wit
13f0: 68 20 6d 61 74 63 68 69 6e 67 20 6c 69 62 72 61  h matching libra
1400: 72 79 20 61 6e 64 20 68 65 61 64 65 72 20 66 69  ry and header fi
1410: 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63  les..**.** <bloc
1420: 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20  kquote><pre>.** 
1430: 61 73 73 65 72 74 28 20 73 71 6c 69 74 65 33 5f  assert( sqlite3_
1440: 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62 65  libversion_numbe
1450: 72 28 29 3d 3d 53 51 4c 49 54 45 5f 56 45 52 53  r()==SQLITE_VERS
1460: 49 4f 4e 5f 4e 55 4d 42 45 52 20 29 3b 0a 2a 2a  ION_NUMBER );.**
1470: 20 61 73 73 65 72 74 28 20 73 74 72 63 6d 70 28   assert( strcmp(
1480: 73 71 6c 69 74 65 33 5f 73 6f 75 72 63 65 69 64  sqlite3_sourceid
1490: 28 29 2c 53 51 4c 49 54 45 5f 53 4f 55 52 43 45  (),SQLITE_SOURCE
14a0: 5f 49 44 29 3d 3d 30 20 29 3b 0a 2a 2a 20 61 73  _ID)==0 );.** as
14b0: 73 65 72 74 28 20 73 74 72 63 6d 70 28 73 71 6c  sert( strcmp(sql
14c0: 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28  ite3_libversion(
14d0: 29 2c 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e  ),SQLITE_VERSION
14e0: 29 3d 3d 30 20 29 3b 0a 2a 2a 20 3c 2f 70 72 65  )==0 );.** </pre
14f0: 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e  ></blockquote>)^
1500: 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
1510: 74 65 33 5f 76 65 72 73 69 6f 6e 5b 5d 20 73 74  te3_version[] st
1520: 72 69 6e 67 20 63 6f 6e 73 74 61 6e 74 20 63 6f  ring constant co
1530: 6e 74 61 69 6e 73 20 74 68 65 20 74 65 78 74 20  ntains the text 
1540: 6f 66 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49  of [SQLITE_VERSI
1550: 4f 4e 5d 0a 2a 2a 20 6d 61 63 72 6f 2e 20 20 5e  ON].** macro.  ^
1560: 54 68 65 20 73 71 6c 69 74 65 33 5f 6c 69 62 76  The sqlite3_libv
1570: 65 72 73 69 6f 6e 28 29 20 66 75 6e 63 74 69 6f  ersion() functio
1580: 6e 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  n returns a poin
1590: 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 74 6f  ter to the.** to
15a0: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 65 72   the sqlite3_ver
15b0: 73 69 6f 6e 5b 5d 20 73 74 72 69 6e 67 20 63 6f  sion[] string co
15c0: 6e 73 74 61 6e 74 2e 20 20 54 68 65 20 73 71 6c  nstant.  The sql
15d0: 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28  ite3_libversion(
15e0: 29 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73  ).** function is
15f0: 20 70 72 6f 76 69 64 65 64 20 66 6f 72 20 75 73   provided for us
1600: 65 20 69 6e 20 44 4c 4c 73 20 73 69 6e 63 65 20  e in DLLs since 
1610: 44 4c 4c 20 75 73 65 72 73 20 75 73 75 61 6c 6c  DLL users usuall
1620: 79 20 64 6f 20 6e 6f 74 20 68 61 76 65 0a 2a 2a  y do not have.**
1630: 20 64 69 72 65 63 74 20 61 63 63 65 73 73 20 74   direct access t
1640: 6f 20 73 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e  o string constan
1650: 74 73 20 77 69 74 68 69 6e 20 74 68 65 20 44 4c  ts within the DL
1660: 4c 2e 20 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69  L.  ^The.** sqli
1670: 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e  te3_libversion_n
1680: 75 6d 62 65 72 28 29 20 66 75 6e 63 74 69 6f 6e  umber() function
1690: 20 72 65 74 75 72 6e 73 20 61 6e 20 69 6e 74 65   returns an inte
16a0: 67 65 72 20 65 71 75 61 6c 20 74 6f 0a 2a 2a 20  ger equal to.** 
16b0: 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f  [SQLITE_VERSION_
16c0: 4e 55 4d 42 45 52 5d 2e 20 20 5e 54 68 65 20 73  NUMBER].  ^The s
16d0: 71 6c 69 74 65 33 5f 73 6f 75 72 63 65 69 64 28  qlite3_sourceid(
16e0: 29 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72  ) function retur
16f0: 6e 73 20 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72  ns .** a pointer
1700: 20 74 6f 20 61 20 73 74 72 69 6e 67 20 63 6f 6e   to a string con
1710: 73 74 61 6e 74 20 77 68 6f 73 65 20 76 61 6c 75  stant whose valu
1720: 65 20 69 73 20 74 68 65 20 73 61 6d 65 20 61 73  e is the same as
1730: 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45   the .** [SQLITE
1740: 5f 53 4f 55 52 43 45 5f 49 44 5d 20 43 20 70 72  _SOURCE_ID] C pr
1750: 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f  eprocessor macro
1760: 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
1770: 3a 20 5b 73 71 6c 69 74 65 5f 76 65 72 73 69 6f  : [sqlite_versio
1780: 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  n()] and [sqlite
1790: 5f 73 6f 75 72 63 65 5f 69 64 28 29 5d 2e 0a 2a  _source_id()]..*
17a0: 2f 0a 53 51 4c 49 54 45 5f 45 58 54 45 52 4e 20  /.SQLITE_EXTERN 
17b0: 63 6f 6e 73 74 20 63 68 61 72 20 73 71 6c 69 74  const char sqlit
17c0: 65 33 5f 76 65 72 73 69 6f 6e 5b 5d 3b 0a 63 6f  e3_version[];.co
17d0: 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65  nst char *sqlite
17e0: 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 76 6f 69  3_libversion(voi
17f0: 64 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a  d);.const char *
1800: 73 71 6c 69 74 65 33 5f 73 6f 75 72 63 65 69 64  sqlite3_sourceid
1810: 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c 69  (void);.int sqli
1820: 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e  te3_libversion_n
1830: 75 6d 62 65 72 28 76 6f 69 64 29 3b 0a 0a 2f 2a  umber(void);../*
1840: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 75  .** CAPI3REF: Ru
1850: 6e 2d 54 69 6d 65 20 4c 69 62 72 61 72 79 20 43  n-Time Library C
1860: 6f 6d 70 69 6c 61 74 69 6f 6e 20 4f 70 74 69 6f  ompilation Optio
1870: 6e 73 20 44 69 61 67 6e 6f 73 74 69 63 73 0a 2a  ns Diagnostics.*
1880: 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
1890: 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f  3_compileoption_
18a0: 75 73 65 64 28 29 20 66 75 6e 63 74 69 6f 6e 20  used() function 
18b0: 72 65 74 75 72 6e 73 20 30 20 6f 72 20 31 20 0a  returns 0 or 1 .
18c0: 2a 2a 20 69 6e 64 69 63 61 74 69 6e 67 20 77 68  ** indicating wh
18d0: 65 74 68 65 72 20 74 68 65 20 73 70 65 63 69 66  ether the specif
18e0: 69 65 64 20 6f 70 74 69 6f 6e 20 77 61 73 20 64  ied option was d
18f0: 65 66 69 6e 65 64 20 61 74 20 0a 2a 2a 20 63 6f  efined at .** co
1900: 6d 70 69 6c 65 20 74 69 6d 65 2e 20 20 5e 54 68  mpile time.  ^Th
1910: 65 20 53 51 4c 49 54 45 5f 20 70 72 65 66 69 78  e SQLITE_ prefix
1920: 20 6d 61 79 20 62 65 20 6f 6d 69 74 74 65 64 20   may be omitted 
1930: 66 72 6f 6d 20 74 68 65 20 0a 2a 2a 20 6f 70 74  from the .** opt
1940: 69 6f 6e 20 6e 61 6d 65 20 70 61 73 73 65 64 20  ion name passed 
1950: 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69  to sqlite3_compi
1960: 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28 29 2e  leoption_used().
1970: 20 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71    .**.** ^The sq
1980: 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74  lite3_compileopt
1990: 69 6f 6e 5f 67 65 74 28 29 20 66 75 6e 63 74 69  ion_get() functi
19a0: 6f 6e 20 61 6c 6c 6f 77 73 20 69 74 65 72 61 74  on allows iterat
19b0: 69 6e 67 0a 2a 2a 20 6f 76 65 72 20 74 68 65 20  ing.** over the 
19c0: 6c 69 73 74 20 6f 66 20 6f 70 74 69 6f 6e 73 20  list of options 
19d0: 74 68 61 74 20 77 65 72 65 20 64 65 66 69 6e 65  that were define
19e0: 64 20 61 74 20 63 6f 6d 70 69 6c 65 20 74 69 6d  d at compile tim
19f0: 65 20 62 79 0a 2a 2a 20 72 65 74 75 72 6e 69 6e  e by.** returnin
1a00: 67 20 74 68 65 20 4e 2d 74 68 20 63 6f 6d 70 69  g the N-th compi
1a10: 6c 65 20 74 69 6d 65 20 6f 70 74 69 6f 6e 20 73  le time option s
1a20: 74 72 69 6e 67 2e 20 20 5e 49 66 20 4e 20 69 73  tring.  ^If N is
1a30: 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 2c 0a 2a   out of range,.*
1a40: 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c  * sqlite3_compil
1a50: 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29 20 72 65  eoption_get() re
1a60: 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69  turns a NULL poi
1a70: 6e 74 65 72 2e 20 20 5e 54 68 65 20 53 51 4c 49  nter.  ^The SQLI
1a80: 54 45 5f 20 0a 2a 2a 20 70 72 65 66 69 78 20 69  TE_ .** prefix i
1a90: 73 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 61  s omitted from a
1aa0: 6e 79 20 73 74 72 69 6e 67 73 20 72 65 74 75 72  ny strings retur
1ab0: 6e 65 64 20 62 79 20 0a 2a 2a 20 73 71 6c 69 74  ned by .** sqlit
1ac0: 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e  e3_compileoption
1ad0: 5f 67 65 74 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 53  _get()..**.** ^S
1ae0: 75 70 70 6f 72 74 20 66 6f 72 20 74 68 65 20 64  upport for the d
1af0: 69 61 67 6e 6f 73 74 69 63 20 66 75 6e 63 74 69  iagnostic functi
1b00: 6f 6e 73 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70  ons sqlite3_comp
1b10: 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28 29  ileoption_used()
1b20: 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  .** and sqlite3_
1b30: 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65  compileoption_ge
1b40: 74 28 29 20 6d 61 79 20 62 65 20 6f 6d 69 74 74  t() may be omitt
1b50: 65 64 20 62 79 20 73 70 65 63 69 66 79 69 6e 67  ed by specifying
1b60: 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45   the .** [SQLITE
1b70: 5f 4f 4d 49 54 5f 43 4f 4d 50 49 4c 45 4f 50 54  _OMIT_COMPILEOPT
1b80: 49 4f 4e 5f 44 49 41 47 53 5d 20 6f 70 74 69 6f  ION_DIAGS] optio
1b90: 6e 20 61 74 20 63 6f 6d 70 69 6c 65 20 74 69 6d  n at compile tim
1ba0: 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  e..**.** See als
1bb0: 6f 3a 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  o: SQL functions
1bc0: 20 5b 73 71 6c 69 74 65 5f 63 6f 6d 70 69 6c 65   [sqlite_compile
1bd0: 6f 70 74 69 6f 6e 5f 75 73 65 64 28 29 5d 20 61  option_used()] a
1be0: 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 5f 63 6f  nd.** [sqlite_co
1bf0: 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28  mpileoption_get(
1c00: 29 5d 20 61 6e 64 20 74 68 65 20 5b 63 6f 6d 70  )] and the [comp
1c10: 69 6c 65 5f 6f 70 74 69 6f 6e 73 20 70 72 61 67  ile_options prag
1c20: 6d 61 5d 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 20  ma]..*/.#ifndef 
1c30: 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 43 4f 4d 50  SQLITE_OMIT_COMP
1c40: 49 4c 45 4f 50 54 49 4f 4e 5f 44 49 41 47 53 0a  ILEOPTION_DIAGS.
1c50: 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70  int sqlite3_comp
1c60: 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28 63  ileoption_used(c
1c70: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4f 70 74 4e  onst char *zOptN
1c80: 61 6d 65 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72  ame);.const char
1c90: 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c   *sqlite3_compil
1ca0: 65 6f 70 74 69 6f 6e 5f 67 65 74 28 69 6e 74 20  eoption_get(int 
1cb0: 4e 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a  N);.#endif../*.*
1cc0: 2a 20 43 41 50 49 33 52 45 46 3a 20 54 65 73 74  * CAPI3REF: Test
1cd0: 20 54 6f 20 53 65 65 20 49 66 20 54 68 65 20 4c   To See If The L
1ce0: 69 62 72 61 72 79 20 49 73 20 54 68 72 65 61 64  ibrary Is Thread
1cf0: 73 61 66 65 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  safe.**.** ^The 
1d00: 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73 61  sqlite3_threadsa
1d10: 66 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 72 65  fe() function re
1d20: 74 75 72 6e 73 20 7a 65 72 6f 20 69 66 20 61 6e  turns zero if an
1d30: 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a 20 53 51 4c  d only if.** SQL
1d40: 69 74 65 20 77 61 73 20 63 6f 6d 70 69 6c 65 64  ite was compiled
1d50: 20 77 69 74 68 20 6d 75 74 65 78 69 6e 67 20 63   with mutexing c
1d60: 6f 64 65 20 6f 6d 69 74 74 65 64 20 64 75 65 20  ode omitted due 
1d70: 74 6f 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54  to the.** [SQLIT
1d80: 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20 63 6f  E_THREADSAFE] co
1d90: 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
1da0: 6e 20 62 65 69 6e 67 20 73 65 74 20 74 6f 20 30  n being set to 0
1db0: 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 63  ..**.** SQLite c
1dc0: 61 6e 20 62 65 20 63 6f 6d 70 69 6c 65 64 20 77  an be compiled w
1dd0: 69 74 68 20 6f 72 20 77 69 74 68 6f 75 74 20 6d  ith or without m
1de0: 75 74 65 78 65 73 2e 20 20 57 68 65 6e 0a 2a 2a  utexes.  When.**
1df0: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52   the [SQLITE_THR
1e00: 45 41 44 53 41 46 45 5d 20 43 20 70 72 65 70 72  EADSAFE] C prepr
1e10: 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 20 69 73  ocessor macro is
1e20: 20 31 20 6f 72 20 32 2c 20 6d 75 74 65 78 65 73   1 or 2, mutexes
1e30: 0a 2a 2a 20 61 72 65 20 65 6e 61 62 6c 65 64 20  .** are enabled 
1e40: 61 6e 64 20 53 51 4c 69 74 65 20 69 73 20 74 68  and SQLite is th
1e50: 72 65 61 64 73 61 66 65 2e 20 20 57 68 65 6e 20  readsafe.  When 
1e60: 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 54  the.** [SQLITE_T
1e70: 48 52 45 41 44 53 41 46 45 5d 20 6d 61 63 72 6f  HREADSAFE] macro
1e80: 20 69 73 20 30 2c 20 0a 2a 2a 20 74 68 65 20 6d   is 0, .** the m
1e90: 75 74 65 78 65 73 20 61 72 65 20 6f 6d 69 74 74  utexes are omitt
1ea0: 65 64 2e 20 20 57 69 74 68 6f 75 74 20 74 68 65  ed.  Without the
1eb0: 20 6d 75 74 65 78 65 73 2c 20 69 74 20 69 73 20   mutexes, it is 
1ec0: 6e 6f 74 20 73 61 66 65 0a 2a 2a 20 74 6f 20 75  not safe.** to u
1ed0: 73 65 20 53 51 4c 69 74 65 20 63 6f 6e 63 75 72  se SQLite concur
1ee0: 72 65 6e 74 6c 79 20 66 72 6f 6d 20 6d 6f 72 65  rently from more
1ef0: 20 74 68 61 6e 20 6f 6e 65 20 74 68 72 65 61 64   than one thread
1f00: 2e 0a 2a 2a 0a 2a 2a 20 45 6e 61 62 6c 69 6e 67  ..**.** Enabling
1f10: 20 6d 75 74 65 78 65 73 20 69 6e 63 75 72 73 20   mutexes incurs 
1f20: 61 20 6d 65 61 73 75 72 61 62 6c 65 20 70 65 72  a measurable per
1f30: 66 6f 72 6d 61 6e 63 65 20 70 65 6e 61 6c 74 79  formance penalty
1f40: 2e 0a 2a 2a 20 53 6f 20 69 66 20 73 70 65 65 64  ..** So if speed
1f50: 20 69 73 20 6f 66 20 75 74 6d 6f 73 74 20 69 6d   is of utmost im
1f60: 70 6f 72 74 61 6e 63 65 2c 20 69 74 20 6d 61 6b  portance, it mak
1f70: 65 73 20 73 65 6e 73 65 20 74 6f 20 64 69 73 61  es sense to disa
1f80: 62 6c 65 0a 2a 2a 20 74 68 65 20 6d 75 74 65 78  ble.** the mutex
1f90: 65 73 2e 20 20 42 75 74 20 66 6f 72 20 6d 61 78  es.  But for max
1fa0: 69 6d 75 6d 20 73 61 66 65 74 79 2c 20 6d 75 74  imum safety, mut
1fb0: 65 78 65 73 20 73 68 6f 75 6c 64 20 62 65 20 65  exes should be e
1fc0: 6e 61 62 6c 65 64 2e 0a 2a 2a 20 5e 54 68 65 20  nabled..** ^The 
1fd0: 64 65 66 61 75 6c 74 20 62 65 68 61 76 69 6f 72  default behavior
1fe0: 20 69 73 20 66 6f 72 20 6d 75 74 65 78 65 73 20   is for mutexes 
1ff0: 74 6f 20 62 65 20 65 6e 61 62 6c 65 64 2e 0a 2a  to be enabled..*
2000: 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66  *.** This interf
2010: 61 63 65 20 63 61 6e 20 62 65 20 75 73 65 64 20  ace can be used 
2020: 62 79 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f  by an applicatio
2030: 6e 20 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 74  n to make sure t
2040: 68 61 74 20 74 68 65 0a 2a 2a 20 76 65 72 73 69  hat the.** versi
2050: 6f 6e 20 6f 66 20 53 51 4c 69 74 65 20 74 68 61  on of SQLite tha
2060: 74 20 69 74 20 69 73 20 6c 69 6e 6b 69 6e 67 20  t it is linking 
2070: 61 67 61 69 6e 73 74 20 77 61 73 20 63 6f 6d 70  against was comp
2080: 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65  iled with.** the
2090: 20 64 65 73 69 72 65 64 20 73 65 74 74 69 6e 67   desired setting
20a0: 20 6f 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f   of the [SQLITE_
20b0: 54 48 52 45 41 44 53 41 46 45 5d 20 6d 61 63 72  THREADSAFE] macr
20c0: 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e  o..**.** This in
20d0: 74 65 72 66 61 63 65 20 6f 6e 6c 79 20 72 65 70  terface only rep
20e0: 6f 72 74 73 20 6f 6e 20 74 68 65 20 63 6f 6d 70  orts on the comp
20f0: 69 6c 65 2d 74 69 6d 65 20 6d 75 74 65 78 20 73  ile-time mutex s
2100: 65 74 74 69 6e 67 0a 2a 2a 20 6f 66 20 74 68 65  etting.** of the
2110: 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53   [SQLITE_THREADS
2120: 41 46 45 5d 20 66 6c 61 67 2e 20 20 49 66 20 53  AFE] flag.  If S
2130: 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65  QLite is compile
2140: 64 20 77 69 74 68 0a 2a 2a 20 53 51 4c 49 54 45  d with.** SQLITE
2150: 5f 54 48 52 45 41 44 53 41 46 45 3d 31 20 6f 72  _THREADSAFE=1 or
2160: 20 3d 32 20 74 68 65 6e 20 6d 75 74 65 78 65 73   =2 then mutexes
2170: 20 61 72 65 20 65 6e 61 62 6c 65 64 20 62 79 20   are enabled by 
2180: 64 65 66 61 75 6c 74 20 62 75 74 0a 2a 2a 20 63  default but.** c
2190: 61 6e 20 62 65 20 66 75 6c 6c 79 20 6f 72 20 70  an be fully or p
21a0: 61 72 74 69 61 6c 6c 79 20 64 69 73 61 62 6c 65  artially disable
21b0: 64 20 75 73 69 6e 67 20 61 20 63 61 6c 6c 20 74  d using a call t
21c0: 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  o [sqlite3_confi
21d0: 67 28 29 5d 0a 2a 2a 20 77 69 74 68 20 74 68 65  g()].** with the
21e0: 20 76 65 72 62 73 20 5b 53 51 4c 49 54 45 5f 43   verbs [SQLITE_C
21f0: 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45  ONFIG_SINGLETHRE
2200: 41 44 5d 2c 20 5b 53 51 4c 49 54 45 5f 43 4f 4e  AD], [SQLITE_CON
2210: 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d  FIG_MULTITHREAD]
2220: 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f  ,.** or [SQLITE_
2230: 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45  CONFIG_SERIALIZE
2240: 44 5d 2e 20 20 5e 28 54 68 65 20 72 65 74 75 72  D].  ^(The retur
2250: 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 65 0a 2a  n value of the.*
2260: 2a 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64  * sqlite3_thread
2270: 73 61 66 65 28 29 20 66 75 6e 63 74 69 6f 6e 20  safe() function 
2280: 73 68 6f 77 73 20 6f 6e 6c 79 20 74 68 65 20 63  shows only the c
2290: 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 73 65 74 74  ompile-time sett
22a0: 69 6e 67 20 6f 66 0a 2a 2a 20 74 68 72 65 61 64  ing of.** thread
22b0: 20 73 61 66 65 74 79 2c 20 6e 6f 74 20 61 6e 79   safety, not any
22c0: 20 72 75 6e 2d 74 69 6d 65 20 63 68 61 6e 67 65   run-time change
22d0: 73 20 74 6f 20 74 68 61 74 20 73 65 74 74 69 6e  s to that settin
22e0: 67 20 6d 61 64 65 20 62 79 0a 2a 2a 20 73 71 6c  g made by.** sql
22f0: 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 2e 20 49  ite3_config(). I
2300: 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74  n other words, t
2310: 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20  he return value 
2320: 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 74 68 72  from sqlite3_thr
2330: 65 61 64 73 61 66 65 28 29 0a 2a 2a 20 69 73 20  eadsafe().** is 
2340: 75 6e 63 68 61 6e 67 65 64 20 62 79 20 63 61 6c  unchanged by cal
2350: 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f  ls to sqlite3_co
2360: 6e 66 69 67 28 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20  nfig().)^.**.** 
2370: 53 65 65 20 74 68 65 20 5b 74 68 72 65 61 64 69  See the [threadi
2380: 6e 67 20 6d 6f 64 65 5d 20 64 6f 63 75 6d 65 6e  ng mode] documen
2390: 74 61 74 69 6f 6e 20 66 6f 72 20 61 64 64 69 74  tation for addit
23a0: 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f  ional informatio
23b0: 6e 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  n..*/.int sqlite
23c0: 33 5f 74 68 72 65 61 64 73 61 66 65 28 76 6f 69  3_threadsafe(voi
23d0: 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  d);../*.** CAPI3
23e0: 52 45 46 3a 20 44 61 74 61 62 61 73 65 20 43 6f  REF: Database Co
23f0: 6e 6e 65 63 74 69 6f 6e 20 48 61 6e 64 6c 65 0a  nnection Handle.
2400: 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 64 61  ** KEYWORDS: {da
2410: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
2420: 6e 7d 20 7b 64 61 74 61 62 61 73 65 20 63 6f 6e  n} {database con
2430: 6e 65 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20  nections}.**.** 
2440: 45 61 63 68 20 6f 70 65 6e 20 53 51 4c 69 74 65  Each open SQLite
2450: 20 64 61 74 61 62 61 73 65 20 69 73 20 72 65 70   database is rep
2460: 72 65 73 65 6e 74 65 64 20 62 79 20 61 20 70 6f  resented by a po
2470: 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74  inter to an inst
2480: 61 6e 63 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6f  ance of.** the o
2490: 70 61 71 75 65 20 73 74 72 75 63 74 75 72 65 20  paque structure 
24a0: 6e 61 6d 65 64 20 22 73 71 6c 69 74 65 33 22 2e  named "sqlite3".
24b0: 20 20 49 74 20 69 73 20 75 73 65 66 75 6c 20 74    It is useful t
24c0: 6f 20 74 68 69 6e 6b 20 6f 66 20 61 6e 20 73 71  o think of an sq
24d0: 6c 69 74 65 33 0a 2a 2a 20 70 6f 69 6e 74 65 72  lite3.** pointer
24e0: 20 61 73 20 61 6e 20 6f 62 6a 65 63 74 2e 20 20   as an object.  
24f0: 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  The [sqlite3_ope
2500: 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f  n()], [sqlite3_o
2510: 70 65 6e 31 36 28 29 5d 2c 20 61 6e 64 0a 2a 2a  pen16()], and.**
2520: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76   [sqlite3_open_v
2530: 32 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 20  2()] interfaces 
2540: 61 72 65 20 69 74 73 20 63 6f 6e 73 74 72 75 63  are its construc
2550: 74 6f 72 73 2c 20 61 6e 64 20 5b 73 71 6c 69 74  tors, and [sqlit
2560: 65 33 5f 63 6c 6f 73 65 28 29 5d 0a 2a 2a 20 61  e3_close()].** a
2570: 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73  nd [sqlite3_clos
2580: 65 5f 76 32 28 29 5d 20 61 72 65 20 69 74 73 20  e_v2()] are its 
2590: 64 65 73 74 72 75 63 74 6f 72 73 2e 20 20 54 68  destructors.  Th
25a0: 65 72 65 20 61 72 65 20 6d 61 6e 79 20 6f 74 68  ere are many oth
25b0: 65 72 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73  er.** interfaces
25c0: 20 28 73 75 63 68 20 61 73 0a 2a 2a 20 5b 73 71   (such as.** [sq
25d0: 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
25e0: 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 72  ()], [sqlite3_cr
25f0: 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d  eate_function()]
2600: 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  , and.** [sqlite
2610: 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29  3_busy_timeout()
2620: 5d 20 74 6f 20 6e 61 6d 65 20 62 75 74 20 74 68  ] to name but th
2630: 72 65 65 29 20 74 68 61 74 20 61 72 65 20 6d 65  ree) that are me
2640: 74 68 6f 64 73 20 6f 6e 20 61 6e 0a 2a 2a 20 73  thods on an.** s
2650: 71 6c 69 74 65 33 20 6f 62 6a 65 63 74 2e 0a 2a  qlite3 object..*
2660: 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74  /.typedef struct
2670: 20 73 71 6c 69 74 65 33 20 73 71 6c 69 74 65 33   sqlite3 sqlite3
2680: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2690: 46 3a 20 36 34 2d 42 69 74 20 49 6e 74 65 67 65  F: 64-Bit Intege
26a0: 72 20 54 79 70 65 73 0a 2a 2a 20 4b 45 59 57 4f  r Types.** KEYWO
26b0: 52 44 53 3a 20 73 71 6c 69 74 65 5f 69 6e 74 36  RDS: sqlite_int6
26c0: 34 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 0a  4 sqlite_uint64.
26d0: 2a 2a 0a 2a 2a 20 42 65 63 61 75 73 65 20 74 68  **.** Because th
26e0: 65 72 65 20 69 73 20 6e 6f 20 63 72 6f 73 73 2d  ere is no cross-
26f0: 70 6c 61 74 66 6f 72 6d 20 77 61 79 20 74 6f 20  platform way to 
2700: 73 70 65 63 69 66 79 20 36 34 2d 62 69 74 20 69  specify 64-bit i
2710: 6e 74 65 67 65 72 20 74 79 70 65 73 0a 2a 2a 20  nteger types.** 
2720: 53 51 4c 69 74 65 20 69 6e 63 6c 75 64 65 73 20  SQLite includes 
2730: 74 79 70 65 64 65 66 73 20 66 6f 72 20 36 34 2d  typedefs for 64-
2740: 62 69 74 20 73 69 67 6e 65 64 20 61 6e 64 20 75  bit signed and u
2750: 6e 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 73  nsigned integers
2760: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
2770: 74 65 33 5f 69 6e 74 36 34 20 61 6e 64 20 73 71  te3_int64 and sq
2780: 6c 69 74 65 33 5f 75 69 6e 74 36 34 20 61 72 65  lite3_uint64 are
2790: 20 74 68 65 20 70 72 65 66 65 72 72 65 64 20 74   the preferred t
27a0: 79 70 65 20 64 65 66 69 6e 69 74 69 6f 6e 73 2e  ype definitions.
27b0: 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 5f 69  .** The sqlite_i
27c0: 6e 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 5f  nt64 and sqlite_
27d0: 75 69 6e 74 36 34 20 74 79 70 65 73 20 61 72 65  uint64 types are
27e0: 20 73 75 70 70 6f 72 74 65 64 20 66 6f 72 20 62   supported for b
27f0: 61 63 6b 77 61 72 64 73 0a 2a 2a 20 63 6f 6d 70  ackwards.** comp
2800: 61 74 69 62 69 6c 69 74 79 20 6f 6e 6c 79 2e 0a  atibility only..
2810: 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
2820: 65 33 5f 69 6e 74 36 34 20 61 6e 64 20 73 71 6c  e3_int64 and sql
2830: 69 74 65 5f 69 6e 74 36 34 20 74 79 70 65 73 20  ite_int64 types 
2840: 63 61 6e 20 73 74 6f 72 65 20 69 6e 74 65 67 65  can store intege
2850: 72 20 76 61 6c 75 65 73 0a 2a 2a 20 62 65 74 77  r values.** betw
2860: 65 65 6e 20 2d 39 32 32 33 33 37 32 30 33 36 38  een -92233720368
2870: 35 34 37 37 35 38 30 38 20 61 6e 64 20 2b 39 32  54775808 and +92
2880: 32 33 33 37 32 30 33 36 38 35 34 37 37 35 38 30  2337203685477580
2890: 37 20 69 6e 63 6c 75 73 69 76 65 2e 20 20 5e 54  7 inclusive.  ^T
28a0: 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75 69  he.** sqlite3_ui
28b0: 6e 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 5f  nt64 and sqlite_
28c0: 75 69 6e 74 36 34 20 74 79 70 65 73 20 63 61 6e  uint64 types can
28d0: 20 73 74 6f 72 65 20 69 6e 74 65 67 65 72 20 76   store integer v
28e0: 61 6c 75 65 73 20 0a 2a 2a 20 62 65 74 77 65 65  alues .** betwee
28f0: 6e 20 30 20 61 6e 64 20 2b 31 38 34 34 36 37 34  n 0 and +1844674
2900: 34 30 37 33 37 30 39 35 35 31 36 31 35 20 69 6e  4073709551615 in
2910: 63 6c 75 73 69 76 65 2e 0a 2a 2f 0a 23 69 66 64  clusive..*/.#ifd
2920: 65 66 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f  ef SQLITE_INT64_
2930: 54 59 50 45 0a 20 20 74 79 70 65 64 65 66 20 53  TYPE.  typedef S
2940: 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 45  QLITE_INT64_TYPE
2950: 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a 20   sqlite_int64;. 
2960: 20 74 79 70 65 64 65 66 20 75 6e 73 69 67 6e 65   typedef unsigne
2970: 64 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54  d SQLITE_INT64_T
2980: 59 50 45 20 73 71 6c 69 74 65 5f 75 69 6e 74 36  YPE sqlite_uint6
2990: 34 3b 0a 23 65 6c 69 66 20 64 65 66 69 6e 65 64  4;.#elif defined
29a0: 28 5f 4d 53 43 5f 56 45 52 29 20 7c 7c 20 64 65  (_MSC_VER) || de
29b0: 66 69 6e 65 64 28 5f 5f 42 4f 52 4c 41 4e 44 43  fined(__BORLANDC
29c0: 5f 5f 29 0a 20 20 74 79 70 65 64 65 66 20 5f 5f  __).  typedef __
29d0: 69 6e 74 36 34 20 73 71 6c 69 74 65 5f 69 6e 74  int64 sqlite_int
29e0: 36 34 3b 0a 20 20 74 79 70 65 64 65 66 20 75 6e  64;.  typedef un
29f0: 73 69 67 6e 65 64 20 5f 5f 69 6e 74 36 34 20 73  signed __int64 s
2a00: 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65  qlite_uint64;.#e
2a10: 6c 73 65 0a 20 20 74 79 70 65 64 65 66 20 6c 6f  lse.  typedef lo
2a20: 6e 67 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69  ng long int sqli
2a30: 74 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70 65  te_int64;.  type
2a40: 64 65 66 20 75 6e 73 69 67 6e 65 64 20 6c 6f 6e  def unsigned lon
2a50: 67 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69 74  g long int sqlit
2a60: 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6e 64 69 66  e_uint64;.#endif
2a70: 0a 74 79 70 65 64 65 66 20 73 71 6c 69 74 65 5f  .typedef sqlite_
2a80: 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 69 6e  int64 sqlite3_in
2a90: 74 36 34 3b 0a 74 79 70 65 64 65 66 20 73 71 6c  t64;.typedef sql
2aa0: 69 74 65 5f 75 69 6e 74 36 34 20 73 71 6c 69 74  ite_uint64 sqlit
2ab0: 65 33 5f 75 69 6e 74 36 34 3b 0a 0a 2f 2a 0a 2a  e3_uint64;../*.*
2ac0: 2a 20 49 66 20 63 6f 6d 70 69 6c 69 6e 67 20 66  * If compiling f
2ad0: 6f 72 20 61 20 70 72 6f 63 65 73 73 6f 72 20 74  or a processor t
2ae0: 68 61 74 20 6c 61 63 6b 73 20 66 6c 6f 61 74 69  hat lacks floati
2af0: 6e 67 20 70 6f 69 6e 74 20 73 75 70 70 6f 72 74  ng point support
2b00: 2c 0a 2a 2a 20 73 75 62 73 74 69 74 75 74 65 20  ,.** substitute 
2b10: 69 6e 74 65 67 65 72 20 66 6f 72 20 66 6c 6f 61  integer for floa
2b20: 74 69 6e 67 2d 70 6f 69 6e 74 2e 0a 2a 2f 0a 23  ting-point..*/.#
2b30: 69 66 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49  ifdef SQLITE_OMI
2b40: 54 5f 46 4c 4f 41 54 49 4e 47 5f 50 4f 49 4e 54  T_FLOATING_POINT
2b50: 0a 23 20 64 65 66 69 6e 65 20 64 6f 75 62 6c 65  .# define double
2b60: 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 0a 23   sqlite3_int64.#
2b70: 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  endif../*.** CAP
2b80: 49 33 52 45 46 3a 20 43 6c 6f 73 69 6e 67 20 41  I3REF: Closing A
2b90: 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63   Database Connec
2ba0: 74 69 6f 6e 0a 2a 2a 20 44 45 53 54 52 55 43 54  tion.** DESTRUCT
2bb0: 4f 52 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a  OR: sqlite3.**.*
2bc0: 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63  * ^The sqlite3_c
2bd0: 6c 6f 73 65 28 29 20 61 6e 64 20 73 71 6c 69 74  lose() and sqlit
2be0: 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 72 6f  e3_close_v2() ro
2bf0: 75 74 69 6e 65 73 20 61 72 65 20 64 65 73 74 72  utines are destr
2c00: 75 63 74 6f 72 73 0a 2a 2a 20 66 6f 72 20 74 68  uctors.** for th
2c10: 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65  e [sqlite3] obje
2c20: 63 74 2e 0a 2a 2a 20 5e 43 61 6c 6c 73 20 74 6f  ct..** ^Calls to
2c30: 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29   sqlite3_close()
2c40: 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6c 6f   and sqlite3_clo
2c50: 73 65 5f 76 32 28 29 20 72 65 74 75 72 6e 20 5b  se_v2() return [
2c60: 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 66 0a 2a 2a  SQLITE_OK] if.**
2c70: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f   the [sqlite3] o
2c80: 62 6a 65 63 74 20 69 73 20 73 75 63 63 65 73 73  bject is success
2c90: 66 75 6c 6c 79 20 64 65 73 74 72 6f 79 65 64 20  fully destroyed 
2ca0: 61 6e 64 20 61 6c 6c 20 61 73 73 6f 63 69 61 74  and all associat
2cb0: 65 64 0a 2a 2a 20 72 65 73 6f 75 72 63 65 73 20  ed.** resources 
2cc0: 61 72 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 2e  are deallocated.
2cd0: 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 64  .**.** ^If the d
2ce0: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
2cf0: 6f 6e 20 69 73 20 61 73 73 6f 63 69 61 74 65 64  on is associated
2d00: 20 77 69 74 68 20 75 6e 66 69 6e 61 6c 69 7a 65   with unfinalize
2d10: 64 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74  d prepared.** st
2d20: 61 74 65 6d 65 6e 74 73 20 6f 72 20 75 6e 66 69  atements or unfi
2d30: 6e 69 73 68 65 64 20 73 71 6c 69 74 65 33 5f 62  nished sqlite3_b
2d40: 61 63 6b 75 70 20 6f 62 6a 65 63 74 73 20 74 68  ackup objects th
2d50: 65 6e 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  en sqlite3_close
2d60: 28 29 0a 2a 2a 20 77 69 6c 6c 20 6c 65 61 76 65  ().** will leave
2d70: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
2d80: 6e 6e 65 63 74 69 6f 6e 20 6f 70 65 6e 20 61 6e  nnection open an
2d90: 64 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  d return [SQLITE
2da0: 5f 42 55 53 59 5d 2e 0a 2a 2a 20 5e 49 66 20 73  _BUSY]..** ^If s
2db0: 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28  qlite3_close_v2(
2dc0: 29 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74 68  ) is called with
2dd0: 20 75 6e 66 69 6e 61 6c 69 7a 65 64 20 70 72 65   unfinalized pre
2de0: 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73  pared statements
2df0: 0a 2a 2a 20 61 6e 64 2f 6f 72 20 75 6e 66 69 6e  .** and/or unfin
2e00: 69 73 68 65 64 20 73 71 6c 69 74 65 33 5f 62 61  ished sqlite3_ba
2e10: 63 6b 75 70 73 2c 20 74 68 65 6e 20 74 68 65 20  ckups, then the 
2e20: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
2e30: 69 6f 6e 20 62 65 63 6f 6d 65 73 0a 2a 2a 20 61  ion becomes.** a
2e40: 6e 20 75 6e 75 73 61 62 6c 65 20 22 7a 6f 6d 62  n unusable "zomb
2e50: 69 65 22 20 77 68 69 63 68 20 77 69 6c 6c 20 61  ie" which will a
2e60: 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62 65 20  utomatically be 
2e70: 64 65 61 6c 6c 6f 63 61 74 65 64 20 77 68 65 6e  deallocated when
2e80: 20 74 68 65 0a 2a 2a 20 6c 61 73 74 20 70 72 65   the.** last pre
2e90: 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20  pared statement 
2ea0: 69 73 20 66 69 6e 61 6c 69 7a 65 64 20 6f 72 20  is finalized or 
2eb0: 74 68 65 20 6c 61 73 74 20 73 71 6c 69 74 65 33  the last sqlite3
2ec0: 5f 62 61 63 6b 75 70 20 69 73 0a 2a 2a 20 66 69  _backup is.** fi
2ed0: 6e 69 73 68 65 64 2e 20 20 54 68 65 20 73 71 6c  nished.  The sql
2ee0: 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20  ite3_close_v2() 
2ef0: 69 6e 74 65 72 66 61 63 65 20 69 73 20 69 6e 74  interface is int
2f00: 65 6e 64 65 64 20 66 6f 72 20 75 73 65 20 77 69  ended for use wi
2f10: 74 68 0a 2a 2a 20 68 6f 73 74 20 6c 61 6e 67 75  th.** host langu
2f20: 61 67 65 73 20 74 68 61 74 20 61 72 65 20 67 61  ages that are ga
2f30: 72 62 61 67 65 20 63 6f 6c 6c 65 63 74 65 64 2c  rbage collected,
2f40: 20 61 6e 64 20 77 68 65 72 65 20 74 68 65 20 6f   and where the o
2f50: 72 64 65 72 20 69 6e 20 77 68 69 63 68 0a 2a 2a  rder in which.**
2f60: 20 64 65 73 74 72 75 63 74 6f 72 73 20 61 72 65   destructors are
2f70: 20 63 61 6c 6c 65 64 20 69 73 20 61 72 62 69 74   called is arbit
2f80: 72 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 41 70 70 6c  rary..**.** Appl
2f90: 69 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20  ications should 
2fa0: 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
2fb0: 65 20 7c 20 66 69 6e 61 6c 69 7a 65 5d 20 61 6c  e | finalize] al
2fc0: 6c 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  l [prepared stat
2fd0: 65 6d 65 6e 74 73 5d 2c 0a 2a 2a 20 5b 73 71 6c  ements],.** [sql
2fe0: 69 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 20  ite3_blob_close 
2ff0: 7c 20 63 6c 6f 73 65 5d 20 61 6c 6c 20 5b 42 4c  | close] all [BL
3000: 4f 42 20 68 61 6e 64 6c 65 73 5d 2c 20 61 6e 64  OB handles], and
3010: 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 61   .** [sqlite3_ba
3020: 63 6b 75 70 5f 66 69 6e 69 73 68 20 7c 20 66 69  ckup_finish | fi
3030: 6e 69 73 68 5d 20 61 6c 6c 20 5b 73 71 6c 69 74  nish] all [sqlit
3040: 65 33 5f 62 61 63 6b 75 70 5d 20 6f 62 6a 65 63  e3_backup] objec
3050: 74 73 20 61 73 73 6f 63 69 61 74 65 64 0a 2a 2a  ts associated.**
3060: 20 77 69 74 68 20 74 68 65 20 5b 73 71 6c 69 74   with the [sqlit
3070: 65 33 5d 20 6f 62 6a 65 63 74 20 70 72 69 6f 72  e3] object prior
3080: 20 74 6f 20 61 74 74 65 6d 70 74 69 6e 67 20 74   to attempting t
3090: 6f 20 63 6c 6f 73 65 20 74 68 65 20 6f 62 6a 65  o close the obje
30a0: 63 74 2e 20 20 5e 49 66 0a 2a 2a 20 73 71 6c 69  ct.  ^If.** sqli
30b0: 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 69  te3_close_v2() i
30c0: 73 20 63 61 6c 6c 65 64 20 6f 6e 20 61 20 5b 64  s called on a [d
30d0: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
30e0: 6f 6e 5d 20 74 68 61 74 20 73 74 69 6c 6c 20 68  on] that still h
30f0: 61 73 0a 2a 2a 20 6f 75 74 73 74 61 6e 64 69 6e  as.** outstandin
3100: 67 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  g [prepared stat
3110: 65 6d 65 6e 74 73 5d 2c 20 5b 42 4c 4f 42 20 68  ements], [BLOB h
3120: 61 6e 64 6c 65 73 5d 2c 20 61 6e 64 2f 6f 72 0a  andles], and/or.
3130: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b  ** [sqlite3_back
3140: 75 70 5d 20 6f 62 6a 65 63 74 73 20 74 68 65 6e  up] objects then
3150: 20 69 74 20 72 65 74 75 72 6e 73 20 5b 53 51 4c   it returns [SQL
3160: 49 54 45 5f 4f 4b 5d 20 61 6e 64 20 74 68 65 20  ITE_OK] and the 
3170: 64 65 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20  deallocation.** 
3180: 6f 66 20 72 65 73 6f 75 72 63 65 73 20 69 73 20  of resources is 
3190: 64 65 66 65 72 72 65 64 20 75 6e 74 69 6c 20 61  deferred until a
31a0: 6c 6c 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  ll [prepared sta
31b0: 74 65 6d 65 6e 74 73 5d 2c 20 5b 42 4c 4f 42 20  tements], [BLOB 
31c0: 68 61 6e 64 6c 65 73 5d 2c 0a 2a 2a 20 61 6e 64  handles],.** and
31d0: 20 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70   [sqlite3_backup
31e0: 5d 20 6f 62 6a 65 63 74 73 20 61 72 65 20 61 6c  ] objects are al
31f0: 73 6f 20 64 65 73 74 72 6f 79 65 64 2e 0a 2a 2a  so destroyed..**
3200: 0a 2a 2a 20 5e 49 66 20 61 6e 20 5b 73 71 6c 69  .** ^If an [sqli
3210: 74 65 33 5d 20 6f 62 6a 65 63 74 20 69 73 20 64  te3] object is d
3220: 65 73 74 72 6f 79 65 64 20 77 68 69 6c 65 20 61  estroyed while a
3230: 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20   transaction is 
3240: 6f 70 65 6e 2c 0a 2a 2a 20 74 68 65 20 74 72 61  open,.** the tra
3250: 6e 73 61 63 74 69 6f 6e 20 69 73 20 61 75 74 6f  nsaction is auto
3260: 6d 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64  matically rolled
3270: 20 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68 65   back..**.** The
3280: 20 43 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20   C parameter to 
3290: 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 43  [sqlite3_close(C
32a0: 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
32b0: 63 6c 6f 73 65 5f 76 32 28 43 29 5d 0a 2a 2a 20  close_v2(C)].** 
32c0: 6d 75 73 74 20 62 65 20 65 69 74 68 65 72 20 61  must be either a
32d0: 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72   NULL.** pointer
32e0: 20 6f 72 20 61 6e 20 5b 73 71 6c 69 74 65 33 5d   or an [sqlite3]
32f0: 20 6f 62 6a 65 63 74 20 70 6f 69 6e 74 65 72 20   object pointer 
3300: 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d  obtained.** from
3310: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29   [sqlite3_open()
3320: 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ], [sqlite3_open
3330: 31 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71  16()], or.** [sq
3340: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d  lite3_open_v2()]
3350: 2c 20 61 6e 64 20 6e 6f 74 20 70 72 65 76 69 6f  , and not previo
3360: 75 73 6c 79 20 63 6c 6f 73 65 64 2e 0a 2a 2a 20  usly closed..** 
3370: 5e 43 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33  ^Calling sqlite3
3380: 5f 63 6c 6f 73 65 28 29 20 6f 72 20 73 71 6c 69  _close() or sqli
3390: 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 77  te3_close_v2() w
33a0: 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  ith a NULL point
33b0: 65 72 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 69  er.** argument i
33c0: 73 20 61 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d  s a harmless no-
33d0: 6f 70 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  op..*/.int sqlit
33e0: 65 33 5f 63 6c 6f 73 65 28 73 71 6c 69 74 65 33  e3_close(sqlite3
33f0: 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  *);.int sqlite3_
3400: 63 6c 6f 73 65 5f 76 32 28 73 71 6c 69 74 65 33  close_v2(sqlite3
3410: 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20 74  *);../*.** The t
3420: 79 70 65 20 66 6f 72 20 61 20 63 61 6c 6c 62 61  ype for a callba
3430: 63 6b 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20  ck function..** 
3440: 54 68 69 73 20 69 73 20 6c 65 67 61 63 79 20 61  This is legacy a
3450: 6e 64 20 64 65 70 72 65 63 61 74 65 64 2e 20 20  nd deprecated.  
3460: 49 74 20 69 73 20 69 6e 63 6c 75 64 65 64 20 66  It is included f
3470: 6f 72 20 68 69 73 74 6f 72 69 63 61 6c 0a 2a 2a  or historical.**
3480: 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 61   compatibility a
3490: 6e 64 20 69 73 20 6e 6f 74 20 64 6f 63 75 6d 65  nd is not docume
34a0: 6e 74 65 64 2e 0a 2a 2f 0a 74 79 70 65 64 65 66  nted..*/.typedef
34b0: 20 69 6e 74 20 28 2a 73 71 6c 69 74 65 33 5f 63   int (*sqlite3_c
34c0: 61 6c 6c 62 61 63 6b 29 28 76 6f 69 64 2a 2c 69  allback)(void*,i
34d0: 6e 74 2c 63 68 61 72 2a 2a 2c 20 63 68 61 72 2a  nt,char**, char*
34e0: 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
34f0: 52 45 46 3a 20 4f 6e 65 2d 53 74 65 70 20 51 75  REF: One-Step Qu
3500: 65 72 79 20 45 78 65 63 75 74 69 6f 6e 20 49 6e  ery Execution In
3510: 74 65 72 66 61 63 65 0a 2a 2a 20 4d 45 54 48 4f  terface.** METHO
3520: 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a  D: sqlite3.**.**
3530: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65   The sqlite3_exe
3540: 63 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73  c() interface is
3550: 20 61 20 63 6f 6e 76 65 6e 69 65 6e 63 65 20 77   a convenience w
3560: 72 61 70 70 65 72 20 61 72 6f 75 6e 64 0a 2a 2a  rapper around.**
3570: 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
3580: 65 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65  e_v2()], [sqlite
3590: 33 5f 73 74 65 70 28 29 5d 2c 20 61 6e 64 20 5b  3_step()], and [
35a0: 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
35b0: 28 29 5d 2c 0a 2a 2a 20 74 68 61 74 20 61 6c 6c  ()],.** that all
35c0: 6f 77 73 20 61 6e 20 61 70 70 6c 69 63 61 74 69  ows an applicati
35d0: 6f 6e 20 74 6f 20 72 75 6e 20 6d 75 6c 74 69 70  on to run multip
35e0: 6c 65 20 73 74 61 74 65 6d 65 6e 74 73 20 6f 66  le statements of
35f0: 20 53 51 4c 0a 2a 2a 20 77 69 74 68 6f 75 74 20   SQL.** without 
3600: 68 61 76 69 6e 67 20 74 6f 20 75 73 65 20 61 20  having to use a 
3610: 6c 6f 74 20 6f 66 20 43 20 63 6f 64 65 2e 20 0a  lot of C code. .
3620: 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
3630: 65 33 5f 65 78 65 63 28 29 20 69 6e 74 65 72 66  e3_exec() interf
3640: 61 63 65 20 72 75 6e 73 20 7a 65 72 6f 20 6f 72  ace runs zero or
3650: 20 6d 6f 72 65 20 55 54 46 2d 38 20 65 6e 63 6f   more UTF-8 enco
3660: 64 65 64 2c 0a 2a 2a 20 73 65 6d 69 63 6f 6c 6f  ded,.** semicolo
3670: 6e 2d 73 65 70 61 72 61 74 65 20 53 51 4c 20 73  n-separate SQL s
3680: 74 61 74 65 6d 65 6e 74 73 20 70 61 73 73 65 64  tatements passed
3690: 20 69 6e 74 6f 20 69 74 73 20 32 6e 64 20 61 72   into its 2nd ar
36a0: 67 75 6d 65 6e 74 2c 0a 2a 2a 20 69 6e 20 74 68  gument,.** in th
36b0: 65 20 63 6f 6e 74 65 78 74 20 6f 66 20 74 68 65  e context of the
36c0: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
36d0: 63 74 69 6f 6e 5d 20 70 61 73 73 65 64 20 69 6e  ction] passed in
36e0: 20 61 73 20 69 74 73 20 31 73 74 0a 2a 2a 20 61   as its 1st.** a
36f0: 72 67 75 6d 65 6e 74 2e 20 20 5e 49 66 20 74 68  rgument.  ^If th
3700: 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  e callback funct
3710: 69 6f 6e 20 6f 66 20 74 68 65 20 33 72 64 20 61  ion of the 3rd a
3720: 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 73 71  rgument to.** sq
3730: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20  lite3_exec() is 
3740: 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 69  not NULL, then i
3750: 74 20 69 73 20 69 6e 76 6f 6b 65 64 20 66 6f 72  t is invoked for
3760: 20 65 61 63 68 20 72 65 73 75 6c 74 20 72 6f 77   each result row
3770: 0a 2a 2a 20 63 6f 6d 69 6e 67 20 6f 75 74 20 6f  .** coming out o
3780: 66 20 74 68 65 20 65 76 61 6c 75 61 74 65 64 20  f the evaluated 
3790: 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 20  SQL statements. 
37a0: 20 5e 54 68 65 20 34 74 68 20 61 72 67 75 6d 65   ^The 4th argume
37b0: 6e 74 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33  nt to.** sqlite3
37c0: 5f 65 78 65 63 28 29 20 69 73 20 72 65 6c 61 79  _exec() is relay
37d0: 65 64 20 74 68 72 6f 75 67 68 20 74 6f 20 74 68  ed through to th
37e0: 65 20 31 73 74 20 61 72 67 75 6d 65 6e 74 20 6f  e 1st argument o
37f0: 66 20 65 61 63 68 0a 2a 2a 20 63 61 6c 6c 62 61  f each.** callba
3800: 63 6b 20 69 6e 76 6f 63 61 74 69 6f 6e 2e 20 20  ck invocation.  
3810: 5e 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  ^If the callback
3820: 20 70 6f 69 6e 74 65 72 20 74 6f 20 73 71 6c 69   pointer to sqli
3830: 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20 69 73  te3_exec().** is
3840: 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 6e 6f 20 63   NULL, then no c
3850: 61 6c 6c 62 61 63 6b 20 69 73 20 65 76 65 72 20  allback is ever 
3860: 69 6e 76 6f 6b 65 64 20 61 6e 64 20 72 65 73 75  invoked and resu
3870: 6c 74 20 72 6f 77 73 20 61 72 65 0a 2a 2a 20 69  lt rows are.** i
3880: 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49  gnored..**.** ^I
3890: 66 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72  f an error occur
38a0: 73 20 77 68 69 6c 65 20 65 76 61 6c 75 61 74 69  s while evaluati
38b0: 6e 67 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  ng the SQL state
38c0: 6d 65 6e 74 73 20 70 61 73 73 65 64 20 69 6e 74  ments passed int
38d0: 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65  o.** sqlite3_exe
38e0: 63 28 29 2c 20 74 68 65 6e 20 65 78 65 63 75 74  c(), then execut
38f0: 69 6f 6e 20 6f 66 20 74 68 65 20 63 75 72 72 65  ion of the curre
3900: 6e 74 20 73 74 61 74 65 6d 65 6e 74 20 73 74 6f  nt statement sto
3910: 70 73 20 61 6e 64 0a 2a 2a 20 73 75 62 73 65 71  ps and.** subseq
3920: 75 65 6e 74 20 73 74 61 74 65 6d 65 6e 74 73 20  uent statements 
3930: 61 72 65 20 73 6b 69 70 70 65 64 2e 20 20 5e 49  are skipped.  ^I
3940: 66 20 74 68 65 20 35 74 68 20 70 61 72 61 6d 65  f the 5th parame
3950: 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65  ter to sqlite3_e
3960: 78 65 63 28 29 0a 2a 2a 20 69 73 20 6e 6f 74 20  xec().** is not 
3970: 4e 55 4c 4c 20 74 68 65 6e 20 61 6e 79 20 65 72  NULL then any er
3980: 72 6f 72 20 6d 65 73 73 61 67 65 20 69 73 20 77  ror message is w
3990: 72 69 74 74 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f  ritten into memo
39a0: 72 79 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66  ry obtained.** f
39b0: 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  rom [sqlite3_mal
39c0: 6c 6f 63 28 29 5d 20 61 6e 64 20 70 61 73 73 65  loc()] and passe
39d0: 64 20 62 61 63 6b 20 74 68 72 6f 75 67 68 20 74  d back through t
39e0: 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72  he 5th parameter
39f0: 2e 0a 2a 2a 20 54 6f 20 61 76 6f 69 64 20 6d 65  ..** To avoid me
3a00: 6d 6f 72 79 20 6c 65 61 6b 73 2c 20 74 68 65 20  mory leaks, the 
3a10: 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75  application shou
3a20: 6c 64 20 69 6e 76 6f 6b 65 20 5b 73 71 6c 69 74  ld invoke [sqlit
3a30: 65 33 5f 66 72 65 65 28 29 5d 0a 2a 2a 20 6f 6e  e3_free()].** on
3a40: 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73   error message s
3a50: 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20  trings returned 
3a60: 74 68 72 6f 75 67 68 20 74 68 65 20 35 74 68 20  through the 5th 
3a70: 70 61 72 61 6d 65 74 65 72 20 6f 66 0a 2a 2a 20  parameter of.** 
3a80: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 61  sqlite3_exec() a
3a90: 66 74 65 72 20 74 68 65 20 65 72 72 6f 72 20 6d  fter the error m
3aa0: 65 73 73 61 67 65 20 73 74 72 69 6e 67 20 69 73  essage string is
3ab0: 20 6e 6f 20 6c 6f 6e 67 65 72 20 6e 65 65 64 65   no longer neede
3ac0: 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 35 74  d..** ^If the 5t
3ad0: 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  h parameter to s
3ae0: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 73  qlite3_exec() is
3af0: 20 6e 6f 74 20 4e 55 4c 4c 20 61 6e 64 20 6e 6f   not NULL and no
3b00: 20 65 72 72 6f 72 73 0a 2a 2a 20 6f 63 63 75 72   errors.** occur
3b10: 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 65  , then sqlite3_e
3b20: 78 65 63 28 29 20 73 65 74 73 20 74 68 65 20 70  xec() sets the p
3b30: 6f 69 6e 74 65 72 20 69 6e 20 69 74 73 20 35 74  ointer in its 5t
3b40: 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a  h parameter to.*
3b50: 2a 20 4e 55 4c 4c 20 62 65 66 6f 72 65 20 72 65  * NULL before re
3b60: 74 75 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e  turning..**.** ^
3b70: 49 66 20 61 6e 20 73 71 6c 69 74 65 33 5f 65 78  If an sqlite3_ex
3b80: 65 63 28 29 20 63 61 6c 6c 62 61 63 6b 20 72 65  ec() callback re
3b90: 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20  turns non-zero, 
3ba0: 74 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63  the sqlite3_exec
3bb0: 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65  ().** routine re
3bc0: 74 75 72 6e 73 20 53 51 4c 49 54 45 5f 41 42 4f  turns SQLITE_ABO
3bd0: 52 54 20 77 69 74 68 6f 75 74 20 69 6e 76 6f 6b  RT without invok
3be0: 69 6e 67 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  ing the callback
3bf0: 20 61 67 61 69 6e 20 61 6e 64 0a 2a 2a 20 77 69   again and.** wi
3c00: 74 68 6f 75 74 20 72 75 6e 6e 69 6e 67 20 61 6e  thout running an
3c10: 79 20 73 75 62 73 65 71 75 65 6e 74 20 53 51 4c  y subsequent SQL
3c20: 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a   statements..**.
3c30: 2a 2a 20 5e 54 68 65 20 32 6e 64 20 61 72 67 75  ** ^The 2nd argu
3c40: 6d 65 6e 74 20 74 6f 20 74 68 65 20 73 71 6c 69  ment to the sqli
3c50: 74 65 33 5f 65 78 65 63 28 29 20 63 61 6c 6c 62  te3_exec() callb
3c60: 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  ack function is 
3c70: 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66  the.** number of
3c80: 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20   columns in the 
3c90: 72 65 73 75 6c 74 2e 20 20 5e 54 68 65 20 33 72  result.  ^The 3r
3ca0: 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  d argument to th
3cb0: 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  e sqlite3_exec()
3cc0: 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  .** callback is 
3cd0: 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e  an array of poin
3ce0: 74 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73 20  ters to strings 
3cf0: 6f 62 74 61 69 6e 65 64 20 61 73 20 69 66 20 66  obtained as if f
3d00: 72 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  rom.** [sqlite3_
3d10: 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2c 20  column_text()], 
3d20: 6f 6e 65 20 66 6f 72 20 65 61 63 68 20 63 6f 6c  one for each col
3d30: 75 6d 6e 2e 20 20 5e 49 66 20 61 6e 20 65 6c 65  umn.  ^If an ele
3d40: 6d 65 6e 74 20 6f 66 20 61 0a 2a 2a 20 72 65 73  ment of a.** res
3d50: 75 6c 74 20 72 6f 77 20 69 73 20 4e 55 4c 4c 20  ult row is NULL 
3d60: 74 68 65 6e 20 74 68 65 20 63 6f 72 72 65 73 70  then the corresp
3d70: 6f 6e 64 69 6e 67 20 73 74 72 69 6e 67 20 70 6f  onding string po
3d80: 69 6e 74 65 72 20 66 6f 72 20 74 68 65 0a 2a 2a  inter for the.**
3d90: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20   sqlite3_exec() 
3da0: 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 20 4e 55  callback is a NU
3db0: 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 5e 54 68  LL pointer.  ^Th
3dc0: 65 20 34 74 68 20 61 72 67 75 6d 65 6e 74 20 74  e 4th argument t
3dd0: 6f 20 74 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33  o the.** sqlite3
3de0: 5f 65 78 65 63 28 29 20 63 61 6c 6c 62 61 63 6b  _exec() callback
3df0: 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20   is an array of 
3e00: 70 6f 69 6e 74 65 72 73 20 74 6f 20 73 74 72 69  pointers to stri
3e10: 6e 67 73 20 77 68 65 72 65 20 65 61 63 68 0a 2a  ngs where each.*
3e20: 2a 20 65 6e 74 72 79 20 72 65 70 72 65 73 65 6e  * entry represen
3e30: 74 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 63  ts the name of c
3e40: 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 72 65 73  orresponding res
3e50: 75 6c 74 20 63 6f 6c 75 6d 6e 20 61 73 20 6f 62  ult column as ob
3e60: 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b  tained.** from [
3e70: 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e  sqlite3_column_n
3e80: 61 6d 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49  ame()]..**.** ^I
3e90: 66 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65  f the 2nd parame
3ea0: 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65  ter to sqlite3_e
3eb0: 78 65 63 28 29 20 69 73 20 61 20 4e 55 4c 4c 20  xec() is a NULL 
3ec0: 70 6f 69 6e 74 65 72 2c 20 61 20 70 6f 69 6e 74  pointer, a point
3ed0: 65 72 0a 2a 2a 20 74 6f 20 61 6e 20 65 6d 70 74  er.** to an empt
3ee0: 79 20 73 74 72 69 6e 67 2c 20 6f 72 20 61 20 70  y string, or a p
3ef0: 6f 69 6e 74 65 72 20 74 68 61 74 20 63 6f 6e 74  ointer that cont
3f00: 61 69 6e 73 20 6f 6e 6c 79 20 77 68 69 74 65 73  ains only whites
3f10: 70 61 63 65 20 61 6e 64 2f 6f 72 20 0a 2a 2a 20  pace and/or .** 
3f20: 53 51 4c 20 63 6f 6d 6d 65 6e 74 73 2c 20 74 68  SQL comments, th
3f30: 65 6e 20 6e 6f 20 53 51 4c 20 73 74 61 74 65 6d  en no SQL statem
3f40: 65 6e 74 73 20 61 72 65 20 65 76 61 6c 75 61 74  ents are evaluat
3f50: 65 64 20 61 6e 64 20 74 68 65 20 64 61 74 61 62  ed and the datab
3f60: 61 73 65 0a 2a 2a 20 69 73 20 6e 6f 74 20 63 68  ase.** is not ch
3f70: 61 6e 67 65 64 2e 0a 2a 2a 0a 2a 2a 20 52 65 73  anged..**.** Res
3f80: 74 72 69 63 74 69 6f 6e 73 3a 0a 2a 2a 0a 2a 2a  trictions:.**.**
3f90: 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68   <ul>.** <li> Th
3fa0: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75  e application mu
3fb0: 73 74 20 65 6e 73 75 72 65 20 74 68 61 74 20 74  st ensure that t
3fc0: 68 65 20 31 73 74 20 70 61 72 61 6d 65 74 65 72  he 1st parameter
3fd0: 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63   to sqlite3_exec
3fe0: 28 29 0a 2a 2a 20 20 20 20 20 20 69 73 20 61 20  ().**      is a 
3ff0: 76 61 6c 69 64 20 61 6e 64 20 6f 70 65 6e 20 5b  valid and open [
4000: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
4010: 69 6f 6e 5d 2e 0a 2a 2a 20 3c 6c 69 3e 20 54 68  ion]..** <li> Th
4020: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75  e application mu
4030: 73 74 20 6e 6f 74 20 63 6c 6f 73 65 20 74 68 65  st not close the
4040: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
4050: 63 74 69 6f 6e 5d 20 73 70 65 63 69 66 69 65 64  ction] specified
4060: 20 62 79 0a 2a 2a 20 20 20 20 20 20 74 68 65 20   by.**      the 
4070: 31 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f  1st parameter to
4080: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20   sqlite3_exec() 
4090: 77 68 69 6c 65 20 73 71 6c 69 74 65 33 5f 65 78  while sqlite3_ex
40a0: 65 63 28 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e  ec() is running.
40b0: 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 61 70 70  .** <li> The app
40c0: 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f  lication must no
40d0: 74 20 6d 6f 64 69 66 79 20 74 68 65 20 53 51 4c  t modify the SQL
40e0: 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20   statement text 
40f0: 70 61 73 73 65 64 20 69 6e 74 6f 0a 2a 2a 20 20  passed into.**  
4100: 20 20 20 20 74 68 65 20 32 6e 64 20 70 61 72 61      the 2nd para
4110: 6d 65 74 65 72 20 6f 66 20 73 71 6c 69 74 65 33  meter of sqlite3
4120: 5f 65 78 65 63 28 29 20 77 68 69 6c 65 20 73 71  _exec() while sq
4130: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20  lite3_exec() is 
4140: 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 3c 2f 75 6c  running..** </ul
4150: 3e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  >.*/.int sqlite3
4160: 5f 65 78 65 63 28 0a 20 20 73 71 6c 69 74 65 33  _exec(.  sqlite3
4170: 2a 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20  *,              
4180: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4190: 20 20 20 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64      /* An open d
41a0: 61 74 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e  atabase */.  con
41b0: 73 74 20 63 68 61 72 20 2a 73 71 6c 2c 20 20 20  st char *sql,   
41c0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
41d0: 20 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 74          /* SQL t
41e0: 6f 20 62 65 20 65 76 61 6c 75 61 74 65 64 20 2a  o be evaluated *
41f0: 2f 0a 20 20 69 6e 74 20 28 2a 63 61 6c 6c 62 61  /.  int (*callba
4200: 63 6b 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68  ck)(void*,int,ch
4210: 61 72 2a 2a 2c 63 68 61 72 2a 2a 29 2c 20 20 2f  ar**,char**),  /
4220: 2a 20 43 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  * Callback funct
4230: 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 2c  ion */.  void *,
4240: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4250: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4260: 20 20 20 20 2f 2a 20 31 73 74 20 61 72 67 75 6d      /* 1st argum
4270: 65 6e 74 20 74 6f 20 63 61 6c 6c 62 61 63 6b 20  ent to callback 
4280: 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 65 72 72 6d  */.  char **errm
4290: 73 67 20 20 20 20 20 20 20 20 20 20 20 20 20 20  sg              
42a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
42b0: 2f 2a 20 45 72 72 6f 72 20 6d 73 67 20 77 72 69  /* Error msg wri
42c0: 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a  tten here */.);.
42d0: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
42e0: 20 52 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a   Result Codes.**
42f0: 20 4b 45 59 57 4f 52 44 53 3a 20 7b 72 65 73 75   KEYWORDS: {resu
4300: 6c 74 20 63 6f 64 65 20 64 65 66 69 6e 69 74 69  lt code definiti
4310: 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 4d 61 6e 79 20  ons}.**.** Many 
4320: 53 51 4c 69 74 65 20 66 75 6e 63 74 69 6f 6e 73  SQLite functions
4330: 20 72 65 74 75 72 6e 20 61 6e 20 69 6e 74 65 67   return an integ
4340: 65 72 20 72 65 73 75 6c 74 20 63 6f 64 65 20 66  er result code f
4350: 72 6f 6d 20 74 68 65 20 73 65 74 20 73 68 6f 77  rom the set show
4360: 6e 0a 2a 2a 20 68 65 72 65 20 69 6e 20 6f 72 64  n.** here in ord
4370: 65 72 20 74 6f 20 69 6e 64 69 63 61 74 65 20 73  er to indicate s
4380: 75 63 63 65 73 73 20 6f 72 20 66 61 69 6c 75 72  uccess or failur
4390: 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 65 72 72  e..**.** New err
43a0: 6f 72 20 63 6f 64 65 73 20 6d 61 79 20 62 65 20  or codes may be 
43b0: 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20  added in future 
43c0: 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69  versions of SQLi
43d0: 74 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  te..**.** See al
43e0: 73 6f 3a 20 5b 65 78 74 65 6e 64 65 64 20 72 65  so: [extended re
43f0: 73 75 6c 74 20 63 6f 64 65 20 64 65 66 69 6e 69  sult code defini
4400: 74 69 6f 6e 73 5d 0a 2a 2f 0a 23 64 65 66 69 6e  tions].*/.#defin
4410: 65 20 53 51 4c 49 54 45 5f 4f 4b 20 20 20 20 20  e SQLITE_OK     
4420: 20 20 20 20 20 20 30 20 20 20 2f 2a 20 53 75 63        0   /* Suc
4430: 63 65 73 73 66 75 6c 20 72 65 73 75 6c 74 20 2a  cessful result *
4440: 2f 0a 2f 2a 20 62 65 67 69 6e 6e 69 6e 67 2d 6f  /./* beginning-o
4450: 66 2d 65 72 72 6f 72 2d 63 6f 64 65 73 20 2a 2f  f-error-codes */
4460: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4470: 45 52 52 4f 52 20 20 20 20 20 20 20 20 31 20 20  ERROR        1  
4480: 20 2f 2a 20 53 51 4c 20 65 72 72 6f 72 20 6f 72   /* SQL error or
4490: 20 6d 69 73 73 69 6e 67 20 64 61 74 61 62 61 73   missing databas
44a0: 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  e */.#define SQL
44b0: 49 54 45 5f 49 4e 54 45 52 4e 41 4c 20 20 20 20  ITE_INTERNAL    
44c0: 20 32 20 20 20 2f 2a 20 49 6e 74 65 72 6e 61 6c   2   /* Internal
44d0: 20 6c 6f 67 69 63 20 65 72 72 6f 72 20 69 6e 20   logic error in 
44e0: 53 51 4c 69 74 65 20 2a 2f 0a 23 64 65 66 69 6e  SQLite */.#defin
44f0: 65 20 53 51 4c 49 54 45 5f 50 45 52 4d 20 20 20  e SQLITE_PERM   
4500: 20 20 20 20 20 20 33 20 20 20 2f 2a 20 41 63 63        3   /* Acc
4510: 65 73 73 20 70 65 72 6d 69 73 73 69 6f 6e 20 64  ess permission d
4520: 65 6e 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65  enied */.#define
4530: 20 53 51 4c 49 54 45 5f 41 42 4f 52 54 20 20 20   SQLITE_ABORT   
4540: 20 20 20 20 20 34 20 20 20 2f 2a 20 43 61 6c 6c       4   /* Call
4550: 62 61 63 6b 20 72 6f 75 74 69 6e 65 20 72 65 71  back routine req
4560: 75 65 73 74 65 64 20 61 6e 20 61 62 6f 72 74 20  uested an abort 
4570: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
4580: 45 5f 42 55 53 59 20 20 20 20 20 20 20 20 20 35  E_BUSY         5
4590: 20 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62 61     /* The databa
45a0: 73 65 20 66 69 6c 65 20 69 73 20 6c 6f 63 6b 65  se file is locke
45b0: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  d */.#define SQL
45c0: 49 54 45 5f 4c 4f 43 4b 45 44 20 20 20 20 20 20  ITE_LOCKED      
45d0: 20 36 20 20 20 2f 2a 20 41 20 74 61 62 6c 65 20   6   /* A table 
45e0: 69 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  in the database 
45f0: 69 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64 65  is locked */.#de
4600: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 4d 45  fine SQLITE_NOME
4610: 4d 20 20 20 20 20 20 20 20 37 20 20 20 2f 2a 20  M        7   /* 
4620: 41 20 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 65  A malloc() faile
4630: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  d */.#define SQL
4640: 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 20 20 20  ITE_READONLY    
4650: 20 38 20 20 20 2f 2a 20 41 74 74 65 6d 70 74 20   8   /* Attempt 
4660: 74 6f 20 77 72 69 74 65 20 61 20 72 65 61 64 6f  to write a reado
4670: 6e 6c 79 20 64 61 74 61 62 61 73 65 20 2a 2f 0a  nly database */.
4680: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
4690: 4e 54 45 52 52 55 50 54 20 20 20 20 39 20 20 20  NTERRUPT    9   
46a0: 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20 74 65 72  /* Operation ter
46b0: 6d 69 6e 61 74 65 64 20 62 79 20 73 71 6c 69 74  minated by sqlit
46c0: 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 2a 2f  e3_interrupt()*/
46d0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
46e0: 49 4f 45 52 52 20 20 20 20 20 20 20 31 30 20 20  IOERR       10  
46f0: 20 2f 2a 20 53 6f 6d 65 20 6b 69 6e 64 20 6f 66   /* Some kind of
4700: 20 64 69 73 6b 20 49 2f 4f 20 65 72 72 6f 72 20   disk I/O error 
4710: 6f 63 63 75 72 72 65 64 20 2a 2f 0a 23 64 65 66  occurred */.#def
4720: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 52 52 55  ine SQLITE_CORRU
4730: 50 54 20 20 20 20 20 31 31 20 20 20 2f 2a 20 54  PT     11   /* T
4740: 68 65 20 64 61 74 61 62 61 73 65 20 64 69 73 6b  he database disk
4750: 20 69 6d 61 67 65 20 69 73 20 6d 61 6c 66 6f 72   image is malfor
4760: 6d 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  med */.#define S
4770: 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 20 20  QLITE_NOTFOUND  
4780: 20 20 31 32 20 20 20 2f 2a 20 55 6e 6b 6e 6f 77    12   /* Unknow
4790: 6e 20 6f 70 63 6f 64 65 20 69 6e 20 73 71 6c 69  n opcode in sqli
47a0: 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c  te3_file_control
47b0: 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  () */.#define SQ
47c0: 4c 49 54 45 5f 46 55 4c 4c 20 20 20 20 20 20 20  LITE_FULL       
47d0: 20 31 33 20 20 20 2f 2a 20 49 6e 73 65 72 74 69   13   /* Inserti
47e0: 6f 6e 20 66 61 69 6c 65 64 20 62 65 63 61 75 73  on failed becaus
47f0: 65 20 64 61 74 61 62 61 73 65 20 69 73 20 66 75  e database is fu
4800: 6c 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ll */.#define SQ
4810: 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 20 20  LITE_CANTOPEN   
4820: 20 31 34 20 20 20 2f 2a 20 55 6e 61 62 6c 65 20   14   /* Unable 
4830: 74 6f 20 6f 70 65 6e 20 74 68 65 20 64 61 74 61  to open the data
4840: 62 61 73 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65  base file */.#de
4850: 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 52 4f 54  fine SQLITE_PROT
4860: 4f 43 4f 4c 20 20 20 20 31 35 20 20 20 2f 2a 20  OCOL    15   /* 
4870: 44 61 74 61 62 61 73 65 20 6c 6f 63 6b 20 70 72  Database lock pr
4880: 6f 74 6f 63 6f 6c 20 65 72 72 6f 72 20 2a 2f 0a  otocol error */.
4890: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45  #define SQLITE_E
48a0: 4d 50 54 59 20 20 20 20 20 20 20 31 36 20 20 20  MPTY       16   
48b0: 2f 2a 20 44 61 74 61 62 61 73 65 20 69 73 20 65  /* Database is e
48c0: 6d 70 74 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20  mpty */.#define 
48d0: 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 20 20 20  SQLITE_SCHEMA   
48e0: 20 20 20 31 37 20 20 20 2f 2a 20 54 68 65 20 64     17   /* The d
48f0: 61 74 61 62 61 73 65 20 73 63 68 65 6d 61 20 63  atabase schema c
4900: 68 61 6e 67 65 64 20 2a 2f 0a 23 64 65 66 69 6e  hanged */.#defin
4910: 65 20 53 51 4c 49 54 45 5f 54 4f 4f 42 49 47 20  e SQLITE_TOOBIG 
4920: 20 20 20 20 20 31 38 20 20 20 2f 2a 20 53 74 72       18   /* Str
4930: 69 6e 67 20 6f 72 20 42 4c 4f 42 20 65 78 63 65  ing or BLOB exce
4940: 65 64 73 20 73 69 7a 65 20 6c 69 6d 69 74 20 2a  eds size limit *
4950: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4960: 5f 43 4f 4e 53 54 52 41 49 4e 54 20 20 31 39 20  _CONSTRAINT  19 
4970: 20 20 2f 2a 20 41 62 6f 72 74 20 64 75 65 20 74    /* Abort due t
4980: 6f 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f  o constraint vio
4990: 6c 61 74 69 6f 6e 20 2a 2f 0a 23 64 65 66 69 6e  lation */.#defin
49a0: 65 20 53 51 4c 49 54 45 5f 4d 49 53 4d 41 54 43  e SQLITE_MISMATC
49b0: 48 20 20 20 20 32 30 20 20 20 2f 2a 20 44 61 74  H    20   /* Dat
49c0: 61 20 74 79 70 65 20 6d 69 73 6d 61 74 63 68 20  a type mismatch 
49d0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
49e0: 45 5f 4d 49 53 55 53 45 20 20 20 20 20 20 32 31  E_MISUSE      21
49f0: 20 20 20 2f 2a 20 4c 69 62 72 61 72 79 20 75 73     /* Library us
4a00: 65 64 20 69 6e 63 6f 72 72 65 63 74 6c 79 20 2a  ed incorrectly *
4a10: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4a20: 5f 4e 4f 4c 46 53 20 20 20 20 20 20 20 32 32 20  _NOLFS       22 
4a30: 20 20 2f 2a 20 55 73 65 73 20 4f 53 20 66 65 61    /* Uses OS fea
4a40: 74 75 72 65 73 20 6e 6f 74 20 73 75 70 70 6f 72  tures not suppor
4a50: 74 65 64 20 6f 6e 20 68 6f 73 74 20 2a 2f 0a 23  ted on host */.#
4a60: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 55  define SQLITE_AU
4a70: 54 48 20 20 20 20 20 20 20 20 32 33 20 20 20 2f  TH        23   /
4a80: 2a 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20  * Authorization 
4a90: 64 65 6e 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e  denied */.#defin
4aa0: 65 20 53 51 4c 49 54 45 5f 46 4f 52 4d 41 54 20  e SQLITE_FORMAT 
4ab0: 20 20 20 20 20 32 34 20 20 20 2f 2a 20 41 75 78       24   /* Aux
4ac0: 69 6c 69 61 72 79 20 64 61 74 61 62 61 73 65 20  iliary database 
4ad0: 66 6f 72 6d 61 74 20 65 72 72 6f 72 20 2a 2f 0a  format error */.
4ae0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52  #define SQLITE_R
4af0: 41 4e 47 45 20 20 20 20 20 20 20 32 35 20 20 20  ANGE       25   
4b00: 2f 2a 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  /* 2nd parameter
4b10: 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64   to sqlite3_bind
4b20: 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 20 2a 2f   out of range */
4b30: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4b40: 4e 4f 54 41 44 42 20 20 20 20 20 20 32 36 20 20  NOTADB      26  
4b50: 20 2f 2a 20 46 69 6c 65 20 6f 70 65 6e 65 64 20   /* File opened 
4b60: 74 68 61 74 20 69 73 20 6e 6f 74 20 61 20 64 61  that is not a da
4b70: 74 61 62 61 73 65 20 66 69 6c 65 20 2a 2f 0a 23  tabase file */.#
4b80: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f  define SQLITE_NO
4b90: 54 49 43 45 20 20 20 20 20 20 32 37 20 20 20 2f  TICE      27   /
4ba0: 2a 20 4e 6f 74 69 66 69 63 61 74 69 6f 6e 73 20  * Notifications 
4bb0: 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6c 6f 67  from sqlite3_log
4bc0: 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  () */.#define SQ
4bd0: 4c 49 54 45 5f 57 41 52 4e 49 4e 47 20 20 20 20  LITE_WARNING    
4be0: 20 32 38 20 20 20 2f 2a 20 57 61 72 6e 69 6e 67   28   /* Warning
4bf0: 73 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6c  s from sqlite3_l
4c00: 6f 67 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20  og() */.#define 
4c10: 53 51 4c 49 54 45 5f 52 4f 57 20 20 20 20 20 20  SQLITE_ROW      
4c20: 20 20 20 31 30 30 20 20 2f 2a 20 73 71 6c 69 74     100  /* sqlit
4c30: 65 33 5f 73 74 65 70 28 29 20 68 61 73 20 61 6e  e3_step() has an
4c40: 6f 74 68 65 72 20 72 6f 77 20 72 65 61 64 79 20  other row ready 
4c50: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
4c60: 45 5f 44 4f 4e 45 20 20 20 20 20 20 20 20 31 30  E_DONE        10
4c70: 31 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 73 74  1  /* sqlite3_st
4c80: 65 70 28 29 20 68 61 73 20 66 69 6e 69 73 68 65  ep() has finishe
4c90: 64 20 65 78 65 63 75 74 69 6e 67 20 2a 2f 0a 2f  d executing */./
4ca0: 2a 20 65 6e 64 2d 6f 66 2d 65 72 72 6f 72 2d 63  * end-of-error-c
4cb0: 6f 64 65 73 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43  odes */../*.** C
4cc0: 41 50 49 33 52 45 46 3a 20 45 78 74 65 6e 64 65  API3REF: Extende
4cd0: 64 20 52 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a  d Result Codes.*
4ce0: 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 65 78 74  * KEYWORDS: {ext
4cf0: 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
4d00: 65 20 64 65 66 69 6e 69 74 69 6f 6e 73 7d 0a 2a  e definitions}.*
4d10: 2a 0a 2a 2a 20 49 6e 20 69 74 73 20 64 65 66 61  *.** In its defa
4d20: 75 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ult configuratio
4d30: 6e 2c 20 53 51 4c 69 74 65 20 41 50 49 20 72 6f  n, SQLite API ro
4d40: 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 6f 6e  utines return on
4d50: 65 20 6f 66 20 33 30 20 69 6e 74 65 67 65 72 0a  e of 30 integer.
4d60: 2a 2a 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 73  ** [result codes
4d70: 5d 2e 20 20 48 6f 77 65 76 65 72 2c 20 65 78 70  ].  However, exp
4d80: 65 72 69 65 6e 63 65 20 68 61 73 20 73 68 6f 77  erience has show
4d90: 6e 20 74 68 61 74 20 6d 61 6e 79 20 6f 66 0a 2a  n that many of.*
4da0: 2a 20 74 68 65 73 65 20 72 65 73 75 6c 74 20 63  * these result c
4db0: 6f 64 65 73 20 61 72 65 20 74 6f 6f 20 63 6f 61  odes are too coa
4dc0: 72 73 65 2d 67 72 61 69 6e 65 64 2e 20 20 54 68  rse-grained.  Th
4dd0: 65 79 20 64 6f 20 6e 6f 74 20 70 72 6f 76 69 64  ey do not provid
4de0: 65 20 61 73 0a 2a 2a 20 6d 75 63 68 20 69 6e 66  e as.** much inf
4df0: 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 70  ormation about p
4e00: 72 6f 62 6c 65 6d 73 20 61 73 20 70 72 6f 67 72  roblems as progr
4e10: 61 6d 6d 65 72 73 20 6d 69 67 68 74 20 6c 69 6b  ammers might lik
4e20: 65 2e 20 20 49 6e 20 61 6e 20 65 66 66 6f 72 74  e.  In an effort
4e30: 20 74 6f 0a 2a 2a 20 61 64 64 72 65 73 73 20 74   to.** address t
4e40: 68 69 73 2c 20 6e 65 77 65 72 20 76 65 72 73 69  his, newer versi
4e50: 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 28 76  ons of SQLite (v
4e60: 65 72 73 69 6f 6e 20 33 2e 33 2e 38 20 5b 64 61  ersion 3.3.8 [da
4e70: 74 65 6f 66 3a 33 2e 33 2e 38 5d 0a 2a 2a 20 61  teof:3.3.8].** a
4e80: 6e 64 20 6c 61 74 65 72 29 20 69 6e 63 6c 75 64  nd later) includ
4e90: 65 0a 2a 2a 20 73 75 70 70 6f 72 74 20 66 6f 72  e.** support for
4ea0: 20 61 64 64 69 74 69 6f 6e 61 6c 20 72 65 73 75   additional resu
4eb0: 6c 74 20 63 6f 64 65 73 20 74 68 61 74 20 70 72  lt codes that pr
4ec0: 6f 76 69 64 65 20 6d 6f 72 65 20 64 65 74 61 69  ovide more detai
4ed0: 6c 65 64 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a  led information.
4ee0: 2a 2a 20 61 62 6f 75 74 20 65 72 72 6f 72 73 2e  ** about errors.
4ef0: 20 54 68 65 73 65 20 5b 65 78 74 65 6e 64 65 64   These [extended
4f00: 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 61   result codes] a
4f10: 72 65 20 65 6e 61 62 6c 65 64 20 6f 72 20 64 69  re enabled or di
4f20: 73 61 62 6c 65 64 0a 2a 2a 20 6f 6e 20 61 20 70  sabled.** on a p
4f30: 65 72 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  er database conn
4f40: 65 63 74 69 6f 6e 20 62 61 73 69 73 20 75 73 69  ection basis usi
4f50: 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  ng the.** [sqlit
4f60: 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75  e3_extended_resu
4f70: 6c 74 5f 63 6f 64 65 73 28 29 5d 20 41 50 49 2e  lt_codes()] API.
4f80: 20 20 4f 72 2c 20 74 68 65 20 65 78 74 65 6e 64    Or, the extend
4f90: 65 64 20 63 6f 64 65 20 66 6f 72 0a 2a 2a 20 74  ed code for.** t
4fa0: 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 65  he most recent e
4fb0: 72 72 6f 72 20 63 61 6e 20 62 65 20 6f 62 74 61  rror can be obta
4fc0: 69 6e 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73  ined using.** [s
4fd0: 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f  qlite3_extended_
4fe0: 65 72 72 63 6f 64 65 28 29 5d 2e 0a 2a 2f 0a 23  errcode()]..*/.#
4ff0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5000: 45 52 52 5f 52 45 41 44 20 20 20 20 20 20 20 20  ERR_READ        
5010: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
5020: 45 52 52 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64  ERR | (1<<8)).#d
5030: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
5040: 52 52 5f 53 48 4f 52 54 5f 52 45 41 44 20 20 20  RR_SHORT_READ   
5050: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
5060: 52 52 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65  RR | (2<<8)).#de
5070: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
5080: 52 5f 57 52 49 54 45 20 20 20 20 20 20 20 20 20  R_WRITE         
5090: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
50a0: 52 20 7c 20 28 33 3c 3c 38 29 29 0a 23 64 65 66  R | (3<<8)).#def
50b0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
50c0: 5f 46 53 59 4e 43 20 20 20 20 20 20 20 20 20 20  _FSYNC          
50d0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
50e0: 20 7c 20 28 34 3c 3c 38 29 29 0a 23 64 65 66 69   | (4<<8)).#defi
50f0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5100: 44 49 52 5f 46 53 59 4e 43 20 20 20 20 20 20 20  DIR_FSYNC       
5110: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
5120: 7c 20 28 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (5<<8)).#defin
5130: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 54  e SQLITE_IOERR_T
5140: 52 55 4e 43 41 54 45 20 20 20 20 20 20 20 20 20  RUNCATE         
5150: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c   (SQLITE_IOERR |
5160: 20 28 36 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (6<<8)).#define
5170: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 46 53   SQLITE_IOERR_FS
5180: 54 41 54 20 20 20 20 20 20 20 20 20 20 20 20 20  TAT             
5190: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
51a0: 28 37 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (7<<8)).#define 
51b0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 55 4e 4c  SQLITE_IOERR_UNL
51c0: 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20 20 28  OCK            (
51d0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
51e0: 38 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  8<<8)).#define S
51f0: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52 44 4c 4f  QLITE_IOERR_RDLO
5200: 43 4b 20 20 20 20 20 20 20 20 20 20 20 20 28 53  CK            (S
5210: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 39  QLITE_IOERR | (9
5220: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5230: 4c 49 54 45 5f 49 4f 45 52 52 5f 44 45 4c 45 54  LITE_IOERR_DELET
5240: 45 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51  E            (SQ
5250: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 30  LITE_IOERR | (10
5260: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5270: 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b  LITE_IOERR_BLOCK
5280: 45 44 20 20 20 20 20 20 20 20 20 20 20 28 53 51  ED           (SQ
5290: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 31  LITE_IOERR | (11
52a0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
52b0: 4c 49 54 45 5f 49 4f 45 52 52 5f 4e 4f 4d 45 4d  LITE_IOERR_NOMEM
52c0: 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51               (SQ
52d0: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 32  LITE_IOERR | (12
52e0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
52f0: 4c 49 54 45 5f 49 4f 45 52 52 5f 41 43 43 45 53  LITE_IOERR_ACCES
5300: 53 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51  S            (SQ
5310: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 33  LITE_IOERR | (13
5320: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5330: 4c 49 54 45 5f 49 4f 45 52 52 5f 43 48 45 43 4b  LITE_IOERR_CHECK
5340: 52 45 53 45 52 56 45 44 4c 4f 43 4b 20 28 53 51  RESERVEDLOCK (SQ
5350: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 34  LITE_IOERR | (14
5360: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5370: 4c 49 54 45 5f 49 4f 45 52 52 5f 4c 4f 43 4b 20  LITE_IOERR_LOCK 
5380: 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51               (SQ
5390: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 35  LITE_IOERR | (15
53a0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
53b0: 4c 49 54 45 5f 49 4f 45 52 52 5f 43 4c 4f 53 45  LITE_IOERR_CLOSE
53c0: 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51               (SQ
53d0: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 36  LITE_IOERR | (16
53e0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
53f0: 4c 49 54 45 5f 49 4f 45 52 52 5f 44 49 52 5f 43  LITE_IOERR_DIR_C
5400: 4c 4f 53 45 20 20 20 20 20 20 20 20 20 28 53 51  LOSE         (SQ
5410: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 37  LITE_IOERR | (17
5420: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5430: 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4d 4f 50  LITE_IOERR_SHMOP
5440: 45 4e 20 20 20 20 20 20 20 20 20 20 20 28 53 51  EN           (SQ
5450: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 38  LITE_IOERR | (18
5460: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5470: 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4d 53 49  LITE_IOERR_SHMSI
5480: 5a 45 20 20 20 20 20 20 20 20 20 20 20 28 53 51  ZE           (SQ
5490: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 39  LITE_IOERR | (19
54a0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
54b0: 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4d 4c 4f  LITE_IOERR_SHMLO
54c0: 43 4b 20 20 20 20 20 20 20 20 20 20 20 28 53 51  CK           (SQ
54d0: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 30  LITE_IOERR | (20
54e0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
54f0: 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4d 4d 41  LITE_IOERR_SHMMA
5500: 50 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51  P            (SQ
5510: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 31  LITE_IOERR | (21
5520: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5530: 4c 49 54 45 5f 49 4f 45 52 52 5f 53 45 45 4b 20  LITE_IOERR_SEEK 
5540: 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51               (SQ
5550: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 32  LITE_IOERR | (22
5560: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5570: 4c 49 54 45 5f 49 4f 45 52 52 5f 44 45 4c 45 54  LITE_IOERR_DELET
5580: 45 5f 4e 4f 45 4e 54 20 20 20 20 20 20 28 53 51  E_NOENT      (SQ
5590: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 33  LITE_IOERR | (23
55a0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
55b0: 4c 49 54 45 5f 49 4f 45 52 52 5f 4d 4d 41 50 20  LITE_IOERR_MMAP 
55c0: 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51               (SQ
55d0: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 34  LITE_IOERR | (24
55e0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
55f0: 4c 49 54 45 5f 49 4f 45 52 52 5f 47 45 54 54 45  LITE_IOERR_GETTE
5600: 4d 50 50 41 54 48 20 20 20 20 20 20 20 28 53 51  MPPATH       (SQ
5610: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 35  LITE_IOERR | (25
5620: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5630: 4c 49 54 45 5f 49 4f 45 52 52 5f 43 4f 4e 56 50  LITE_IOERR_CONVP
5640: 41 54 48 20 20 20 20 20 20 20 20 20 20 28 53 51  ATH          (SQ
5650: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 36  LITE_IOERR | (26
5660: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5670: 4c 49 54 45 5f 49 4f 45 52 52 5f 56 4e 4f 44 45  LITE_IOERR_VNODE
5680: 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51               (SQ
5690: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 37  LITE_IOERR | (27
56a0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
56b0: 4c 49 54 45 5f 49 4f 45 52 52 5f 41 55 54 48 20  LITE_IOERR_AUTH 
56c0: 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51               (SQ
56d0: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 38  LITE_IOERR | (28
56e0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
56f0: 4c 49 54 45 5f 4c 4f 43 4b 45 44 5f 53 48 41 52  LITE_LOCKED_SHAR
5700: 45 44 43 41 43 48 45 20 20 20 20 20 20 28 53 51  EDCACHE      (SQ
5710: 4c 49 54 45 5f 4c 4f 43 4b 45 44 20 7c 20 20 28  LITE_LOCKED |  (
5720: 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  1<<8)).#define S
5730: 51 4c 49 54 45 5f 42 55 53 59 5f 52 45 43 4f 56  QLITE_BUSY_RECOV
5740: 45 52 59 20 20 20 20 20 20 20 20 20 20 20 28 53  ERY           (S
5750: 51 4c 49 54 45 5f 42 55 53 59 20 20 20 7c 20 20  QLITE_BUSY   |  
5760: 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (1<<8)).#define 
5770: 53 51 4c 49 54 45 5f 42 55 53 59 5f 53 4e 41 50  SQLITE_BUSY_SNAP
5780: 53 48 4f 54 20 20 20 20 20 20 20 20 20 20 20 28  SHOT           (
5790: 53 51 4c 49 54 45 5f 42 55 53 59 20 20 20 7c 20  SQLITE_BUSY   | 
57a0: 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (2<<8)).#define
57b0: 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e   SQLITE_CANTOPEN
57c0: 5f 4e 4f 54 45 4d 50 44 49 52 20 20 20 20 20 20  _NOTEMPDIR      
57d0: 28 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e  (SQLITE_CANTOPEN
57e0: 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69   | (1<<8)).#defi
57f0: 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50  ne SQLITE_CANTOP
5800: 45 4e 5f 49 53 44 49 52 20 20 20 20 20 20 20 20  EN_ISDIR        
5810: 20 20 28 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50    (SQLITE_CANTOP
5820: 45 4e 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65  EN | (2<<8)).#de
5830: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e 54  fine SQLITE_CANT
5840: 4f 50 45 4e 5f 46 55 4c 4c 50 41 54 48 20 20 20  OPEN_FULLPATH   
5850: 20 20 20 20 28 53 51 4c 49 54 45 5f 43 41 4e 54      (SQLITE_CANT
5860: 4f 50 45 4e 20 7c 20 28 33 3c 3c 38 29 29 0a 23  OPEN | (3<<8)).#
5870: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41  define SQLITE_CA
5880: 4e 54 4f 50 45 4e 5f 43 4f 4e 56 50 41 54 48 20  NTOPEN_CONVPATH 
5890: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 41        (SQLITE_CA
58a0: 4e 54 4f 50 45 4e 20 7c 20 28 34 3c 3c 38 29 29  NTOPEN | (4<<8))
58b0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
58c0: 43 4f 52 52 55 50 54 5f 56 54 41 42 20 20 20 20  CORRUPT_VTAB    
58d0: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
58e0: 43 4f 52 52 55 50 54 20 7c 20 28 31 3c 3c 38 29  CORRUPT | (1<<8)
58f0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5900: 5f 52 45 41 44 4f 4e 4c 59 5f 52 45 43 4f 56 45  _READONLY_RECOVE
5910: 52 59 20 20 20 20 20 20 20 28 53 51 4c 49 54 45  RY       (SQLITE
5920: 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28 31 3c 3c  _READONLY | (1<<
5930: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5940: 54 45 5f 52 45 41 44 4f 4e 4c 59 5f 43 41 4e 54  TE_READONLY_CANT
5950: 4c 4f 43 4b 20 20 20 20 20 20 20 28 53 51 4c 49  LOCK       (SQLI
5960: 54 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28 32  TE_READONLY | (2
5970: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5980: 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5f 52 4f  LITE_READONLY_RO
5990: 4c 4c 42 41 43 4b 20 20 20 20 20 20 20 28 53 51  LLBACK       (SQ
59a0: 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20  LITE_READONLY | 
59b0: 28 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (3<<8)).#define 
59c0: 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5f  SQLITE_READONLY_
59d0: 44 42 4d 4f 56 45 44 20 20 20 20 20 20 20 20 28  DBMOVED        (
59e0: 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20  SQLITE_READONLY 
59f0: 7c 20 28 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (4<<8)).#defin
5a00: 65 20 53 51 4c 49 54 45 5f 41 42 4f 52 54 5f 52  e SQLITE_ABORT_R
5a10: 4f 4c 4c 42 41 43 4b 20 20 20 20 20 20 20 20 20  OLLBACK         
5a20: 20 28 53 51 4c 49 54 45 5f 41 42 4f 52 54 20 7c   (SQLITE_ABORT |
5a30: 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (2<<8)).#define
5a40: 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49   SQLITE_CONSTRAI
5a50: 4e 54 5f 43 48 45 43 4b 20 20 20 20 20 20 20 20  NT_CHECK        
5a60: 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49  (SQLITE_CONSTRAI
5a70: 4e 54 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65  NT | (1<<8)).#de
5a80: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53  fine SQLITE_CONS
5a90: 54 52 41 49 4e 54 5f 43 4f 4d 4d 49 54 48 4f 4f  TRAINT_COMMITHOO
5aa0: 4b 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53  K   (SQLITE_CONS
5ab0: 54 52 41 49 4e 54 20 7c 20 28 32 3c 3c 38 29 29  TRAINT | (2<<8))
5ac0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5ad0: 43 4f 4e 53 54 52 41 49 4e 54 5f 46 4f 52 45 49  CONSTRAINT_FOREI
5ae0: 47 4e 4b 45 59 20 20 20 28 53 51 4c 49 54 45 5f  GNKEY   (SQLITE_
5af0: 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 33 3c  CONSTRAINT | (3<
5b00: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5b10: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 46  ITE_CONSTRAINT_F
5b20: 55 4e 43 54 49 4f 4e 20 20 20 20 20 28 53 51 4c  UNCTION     (SQL
5b30: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c  ITE_CONSTRAINT |
5b40: 20 28 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (4<<8)).#define
5b50: 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49   SQLITE_CONSTRAI
5b60: 4e 54 5f 4e 4f 54 4e 55 4c 4c 20 20 20 20 20 20  NT_NOTNULL      
5b70: 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49  (SQLITE_CONSTRAI
5b80: 4e 54 20 7c 20 28 35 3c 3c 38 29 29 0a 23 64 65  NT | (5<<8)).#de
5b90: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53  fine SQLITE_CONS
5ba0: 54 52 41 49 4e 54 5f 50 52 49 4d 41 52 59 4b 45  TRAINT_PRIMARYKE
5bb0: 59 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53  Y   (SQLITE_CONS
5bc0: 54 52 41 49 4e 54 20 7c 20 28 36 3c 3c 38 29 29  TRAINT | (6<<8))
5bd0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5be0: 43 4f 4e 53 54 52 41 49 4e 54 5f 54 52 49 47 47  CONSTRAINT_TRIGG
5bf0: 45 52 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f  ER      (SQLITE_
5c00: 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 37 3c  CONSTRAINT | (7<
5c10: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5c20: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 55  ITE_CONSTRAINT_U
5c30: 4e 49 51 55 45 20 20 20 20 20 20 20 28 53 51 4c  NIQUE       (SQL
5c40: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c  ITE_CONSTRAINT |
5c50: 20 28 38 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (8<<8)).#define
5c60: 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49   SQLITE_CONSTRAI
5c70: 4e 54 5f 56 54 41 42 20 20 20 20 20 20 20 20 20  NT_VTAB         
5c80: 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49  (SQLITE_CONSTRAI
5c90: 4e 54 20 7c 20 28 39 3c 3c 38 29 29 0a 23 64 65  NT | (9<<8)).#de
5ca0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53  fine SQLITE_CONS
5cb0: 54 52 41 49 4e 54 5f 52 4f 57 49 44 20 20 20 20  TRAINT_ROWID    
5cc0: 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53      (SQLITE_CONS
5cd0: 54 52 41 49 4e 54 20 7c 28 31 30 3c 3c 38 29 29  TRAINT |(10<<8))
5ce0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5cf0: 4e 4f 54 49 43 45 5f 52 45 43 4f 56 45 52 5f 57  NOTICE_RECOVER_W
5d00: 41 4c 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f  AL      (SQLITE_
5d10: 4e 4f 54 49 43 45 20 7c 20 28 31 3c 3c 38 29 29  NOTICE | (1<<8))
5d20: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5d30: 4e 4f 54 49 43 45 5f 52 45 43 4f 56 45 52 5f 52  NOTICE_RECOVER_R
5d40: 4f 4c 4c 42 41 43 4b 20 28 53 51 4c 49 54 45 5f  OLLBACK (SQLITE_
5d50: 4e 4f 54 49 43 45 20 7c 20 28 32 3c 3c 38 29 29  NOTICE | (2<<8))
5d60: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5d70: 57 41 52 4e 49 4e 47 5f 41 55 54 4f 49 4e 44 45  WARNING_AUTOINDE
5d80: 58 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f  X       (SQLITE_
5d90: 57 41 52 4e 49 4e 47 20 7c 20 28 31 3c 3c 38 29  WARNING | (1<<8)
5da0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5db0: 5f 41 55 54 48 5f 55 53 45 52 20 20 20 20 20 20  _AUTH_USER      
5dc0: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
5dd0: 5f 41 55 54 48 20 7c 20 28 31 3c 3c 38 29 29 0a  _AUTH | (1<<8)).
5de0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
5df0: 4b 5f 4c 4f 41 44 5f 50 45 52 4d 41 4e 45 4e 54  K_LOAD_PERMANENT
5e00: 4c 59 20 20 20 20 20 28 53 51 4c 49 54 45 5f 4f  LY     (SQLITE_O
5e10: 4b 20 7c 20 28 31 3c 3c 38 29 29 0a 0a 2f 2a 0a  K | (1<<8))../*.
5e20: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6c 61  ** CAPI3REF: Fla
5e30: 67 73 20 46 6f 72 20 46 69 6c 65 20 4f 70 65 6e  gs For File Open
5e40: 20 4f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 0a 2a   Operations.**.*
5e50: 2a 20 54 68 65 73 65 20 62 69 74 20 76 61 6c 75  * These bit valu
5e60: 65 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20  es are intended 
5e70: 66 6f 72 20 75 73 65 20 69 6e 20 74 68 65 0a 2a  for use in the.*
5e80: 2a 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20  * 3rd parameter 
5e90: 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
5ea0: 6f 70 65 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72  open_v2()] inter
5eb0: 66 61 63 65 20 61 6e 64 0a 2a 2a 20 69 6e 20 74  face and.** in t
5ec0: 68 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 72  he 4th parameter
5ed0: 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
5ee0: 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 6d 65 74 68  _vfs.xOpen] meth
5ef0: 6f 64 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  od..*/.#define S
5f00: 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f  QLITE_OPEN_READO
5f10: 4e 4c 59 20 20 20 20 20 20 20 20 20 30 78 30 30  NLY         0x00
5f20: 30 30 30 30 30 31 20 20 2f 2a 20 4f 6b 20 66 6f  000001  /* Ok fo
5f30: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
5f40: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  2() */.#define S
5f50: 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57  QLITE_OPEN_READW
5f60: 52 49 54 45 20 20 20 20 20 20 20 20 30 78 30 30  RITE        0x00
5f70: 30 30 30 30 30 32 20 20 2f 2a 20 4f 6b 20 66 6f  000002  /* Ok fo
5f80: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
5f90: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  2() */.#define S
5fa0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54  QLITE_OPEN_CREAT
5fb0: 45 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30  E           0x00
5fc0: 30 30 30 30 30 34 20 20 2f 2a 20 4f 6b 20 66 6f  000004  /* Ok fo
5fd0: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
5fe0: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  2() */.#define S
5ff0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54  QLITE_OPEN_DELET
6000: 45 4f 4e 43 4c 4f 53 45 20 20 20 20 30 78 30 30  EONCLOSE    0x00
6010: 30 30 30 30 30 38 20 20 2f 2a 20 56 46 53 20 6f  000008  /* VFS o
6020: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
6030: 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55  QLITE_OPEN_EXCLU
6040: 53 49 56 45 20 20 20 20 20 20 20 20 30 78 30 30  SIVE        0x00
6050: 30 30 30 30 31 30 20 20 2f 2a 20 56 46 53 20 6f  000010  /* VFS o
6060: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
6070: 51 4c 49 54 45 5f 4f 50 45 4e 5f 41 55 54 4f 50  QLITE_OPEN_AUTOP
6080: 52 4f 58 59 20 20 20 20 20 20 20 20 30 78 30 30  ROXY        0x00
6090: 30 30 30 30 32 30 20 20 2f 2a 20 56 46 53 20 6f  000020  /* VFS o
60a0: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
60b0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 20 20  QLITE_OPEN_URI  
60c0: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30              0x00
60d0: 30 30 30 30 34 30 20 20 2f 2a 20 4f 6b 20 66 6f  000040  /* Ok fo
60e0: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
60f0: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  2() */.#define S
6100: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 45 4d 4f 52  QLITE_OPEN_MEMOR
6110: 59 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30  Y           0x00
6120: 30 30 30 30 38 30 20 20 2f 2a 20 4f 6b 20 66 6f  000080  /* Ok fo
6130: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
6140: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  2() */.#define S
6150: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f  QLITE_OPEN_MAIN_
6160: 44 42 20 20 20 20 20 20 20 20 20 20 30 78 30 30  DB          0x00
6170: 30 30 30 31 30 30 20 20 2f 2a 20 56 46 53 20 6f  000100  /* VFS o
6180: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
6190: 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f  QLITE_OPEN_TEMP_
61a0: 44 42 20 20 20 20 20 20 20 20 20 20 30 78 30 30  DB          0x00
61b0: 30 30 30 32 30 30 20 20 2f 2a 20 56 46 53 20 6f  000200  /* VFS o
61c0: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
61d0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 52 41 4e 53  QLITE_OPEN_TRANS
61e0: 49 45 4e 54 5f 44 42 20 20 20 20 20 30 78 30 30  IENT_DB     0x00
61f0: 30 30 30 34 30 30 20 20 2f 2a 20 56 46 53 20 6f  000400  /* VFS o
6200: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
6210: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f  QLITE_OPEN_MAIN_
6220: 4a 4f 55 52 4e 41 4c 20 20 20 20 20 30 78 30 30  JOURNAL     0x00
6230: 30 30 30 38 30 30 20 20 2f 2a 20 56 46 53 20 6f  000800  /* VFS o
6240: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
6250: 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f  QLITE_OPEN_TEMP_
6260: 4a 4f 55 52 4e 41 4c 20 20 20 20 20 30 78 30 30  JOURNAL     0x00
6270: 30 30 31 30 30 30 20 20 2f 2a 20 56 46 53 20 6f  001000  /* VFS o
6280: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
6290: 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f  QLITE_OPEN_SUBJO
62a0: 55 52 4e 41 4c 20 20 20 20 20 20 20 30 78 30 30  URNAL       0x00
62b0: 30 30 32 30 30 30 20 20 2f 2a 20 56 46 53 20 6f  002000  /* VFS o
62c0: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
62d0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 53 54 45  QLITE_OPEN_MASTE
62e0: 52 5f 4a 4f 55 52 4e 41 4c 20 20 20 30 78 30 30  R_JOURNAL   0x00
62f0: 30 30 34 30 30 30 20 20 2f 2a 20 56 46 53 20 6f  004000  /* VFS o
6300: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
6310: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54  QLITE_OPEN_NOMUT
6320: 45 58 20 20 20 20 20 20 20 20 20 20 30 78 30 30  EX          0x00
6330: 30 30 38 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f  008000  /* Ok fo
6340: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
6350: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  2() */.#define S
6360: 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d  QLITE_OPEN_FULLM
6370: 55 54 45 58 20 20 20 20 20 20 20 20 30 78 30 30  UTEX        0x00
6380: 30 31 30 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f  010000  /* Ok fo
6390: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
63a0: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  2() */.#define S
63b0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45  QLITE_OPEN_SHARE
63c0: 44 43 41 43 48 45 20 20 20 20 20 20 30 78 30 30  DCACHE      0x00
63d0: 30 32 30 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f  020000  /* Ok fo
63e0: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
63f0: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  2() */.#define S
6400: 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41  QLITE_OPEN_PRIVA
6410: 54 45 43 41 43 48 45 20 20 20 20 20 30 78 30 30  TECACHE     0x00
6420: 30 34 30 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f  040000  /* Ok fo
6430: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
6440: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  2() */.#define S
6450: 51 4c 49 54 45 5f 4f 50 45 4e 5f 57 41 4c 20 20  QLITE_OPEN_WAL  
6460: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30              0x00
6470: 30 38 30 30 30 30 20 20 2f 2a 20 56 46 53 20 6f  080000  /* VFS o
6480: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
6490: 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 49 4c 45 50  QLITE_OPEN_FILEP
64a0: 52 4f 54 45 43 54 49 4f 4e 5f 4d 41 53 4b 20 20  ROTECTION_MASK  
64b0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
64c0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30                 0
64d0: 78 30 30 37 30 30 30 30 30 0a 0a 2f 2a 20 52 65  x00700000../* Re
64e0: 73 65 72 76 65 64 3a 20 20 20 20 20 20 20 20 20  served:         
64f0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
6500: 30 78 30 30 46 30 30 30 30 30 20 2a 2f 0a 0a 2f  0x00F00000 */../
6510: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
6520: 65 76 69 63 65 20 43 68 61 72 61 63 74 65 72 69  evice Characteri
6530: 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20  stics.**.** The 
6540: 78 44 65 76 69 63 65 43 68 61 72 61 63 74 65 72  xDeviceCharacter
6550: 69 73 74 69 63 73 20 6d 65 74 68 6f 64 20 6f 66  istics method of
6560: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f   the [sqlite3_io
6570: 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 6f 62 6a  _methods].** obj
6580: 65 63 74 20 72 65 74 75 72 6e 73 20 61 6e 20 69  ect returns an i
6590: 6e 74 65 67 65 72 20 77 68 69 63 68 20 69 73 20  nteger which is 
65a0: 61 20 76 65 63 74 6f 72 20 6f 66 20 74 68 65 73  a vector of thes
65b0: 65 0a 2a 2a 20 62 69 74 20 76 61 6c 75 65 73 20  e.** bit values 
65c0: 65 78 70 72 65 73 73 69 6e 67 20 49 2f 4f 20 63  expressing I/O c
65d0: 68 61 72 61 63 74 65 72 69 73 74 69 63 73 20 6f  haracteristics o
65e0: 66 20 74 68 65 20 6d 61 73 73 20 73 74 6f 72 61  f the mass stora
65f0: 67 65 0a 2a 2a 20 64 65 76 69 63 65 20 74 68 61  ge.** device tha
6600: 74 20 68 6f 6c 64 73 20 74 68 65 20 66 69 6c 65  t holds the file
6610: 20 74 68 61 74 20 74 68 65 20 5b 73 71 6c 69 74   that the [sqlit
6620: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a 2a  e3_io_methods].*
6630: 2a 20 72 65 66 65 72 73 20 74 6f 2e 0a 2a 2a 0a  * refers to..**.
6640: 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f  ** The SQLITE_IO
6650: 43 41 50 5f 41 54 4f 4d 49 43 20 70 72 6f 70 65  CAP_ATOMIC prope
6660: 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74 20 61  rty means that a
6670: 6c 6c 20 77 72 69 74 65 73 20 6f 66 0a 2a 2a 20  ll writes of.** 
6680: 61 6e 79 20 73 69 7a 65 20 61 72 65 20 61 74 6f  any size are ato
6690: 6d 69 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45  mic.  The SQLITE
66a0: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e  _IOCAP_ATOMICnnn
66b0: 20 76 61 6c 75 65 73 0a 2a 2a 20 6d 65 61 6e 20   values.** mean 
66c0: 74 68 61 74 20 77 72 69 74 65 73 20 6f 66 20 62  that writes of b
66d0: 6c 6f 63 6b 73 20 74 68 61 74 20 61 72 65 20 6e  locks that are n
66e0: 6e 6e 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65  nn bytes in size
66f0: 20 61 6e 64 0a 2a 2a 20 61 72 65 20 61 6c 69 67   and.** are alig
6700: 6e 65 64 20 74 6f 20 61 6e 20 61 64 64 72 65 73  ned to an addres
6710: 73 20 77 68 69 63 68 20 69 73 20 61 6e 20 69 6e  s which is an in
6720: 74 65 67 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f  teger multiple o
6730: 66 0a 2a 2a 20 6e 6e 6e 20 61 72 65 20 61 74 6f  f.** nnn are ato
6740: 6d 69 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45  mic.  The SQLITE
6750: 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45  _IOCAP_SAFE_APPE
6760: 4e 44 20 76 61 6c 75 65 20 6d 65 61 6e 73 0a 2a  ND value means.*
6770: 2a 20 74 68 61 74 20 77 68 65 6e 20 64 61 74 61  * that when data
6780: 20 69 73 20 61 70 70 65 6e 64 65 64 20 74 6f 20   is appended to 
6790: 61 20 66 69 6c 65 2c 20 74 68 65 20 64 61 74 61  a file, the data
67a0: 20 69 73 20 61 70 70 65 6e 64 65 64 0a 2a 2a 20   is appended.** 
67b0: 66 69 72 73 74 20 74 68 65 6e 20 74 68 65 20 73  first then the s
67c0: 69 7a 65 20 6f 66 20 74 68 65 20 66 69 6c 65 20  ize of the file 
67d0: 69 73 20 65 78 74 65 6e 64 65 64 2c 20 6e 65 76  is extended, nev
67e0: 65 72 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20  er the other.** 
67f0: 77 61 79 20 61 72 6f 75 6e 64 2e 20 20 54 68 65  way around.  The
6800: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45   SQLITE_IOCAP_SE
6810: 51 55 45 4e 54 49 41 4c 20 70 72 6f 70 65 72 74  QUENTIAL propert
6820: 79 20 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20  y means that.** 
6830: 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 77  information is w
6840: 72 69 74 74 65 6e 20 74 6f 20 64 69 73 6b 20 69  ritten to disk i
6850: 6e 20 74 68 65 20 73 61 6d 65 20 6f 72 64 65 72  n the same order
6860: 20 61 73 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20   as calls.** to 
6870: 78 57 72 69 74 65 28 29 2e 20 20 54 68 65 20 53  xWrite().  The S
6880: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 50 4f 57 45  QLITE_IOCAP_POWE
6890: 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45 20  RSAFE_OVERWRITE 
68a0: 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74  property means t
68b0: 68 61 74 0a 2a 2a 20 61 66 74 65 72 20 72 65 62  hat.** after reb
68c0: 6f 6f 74 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20  oot following a 
68d0: 63 72 61 73 68 20 6f 72 20 70 6f 77 65 72 20 6c  crash or power l
68e0: 6f 73 73 2c 20 74 68 65 20 6f 6e 6c 79 20 62 79  oss, the only by
68f0: 74 65 73 20 69 6e 20 61 0a 2a 2a 20 66 69 6c 65  tes in a.** file
6900: 20 74 68 61 74 20 77 65 72 65 20 77 72 69 74 74   that were writt
6910: 65 6e 20 61 74 20 74 68 65 20 61 70 70 6c 69 63  en at the applic
6920: 61 74 69 6f 6e 20 6c 65 76 65 6c 20 6d 69 67 68  ation level migh
6930: 74 20 68 61 76 65 20 63 68 61 6e 67 65 64 0a 2a  t have changed.*
6940: 2a 20 61 6e 64 20 74 68 61 74 20 61 64 6a 61 63  * and that adjac
6950: 65 6e 74 20 62 79 74 65 73 2c 20 65 76 65 6e 20  ent bytes, even 
6960: 62 79 74 65 73 20 77 69 74 68 69 6e 20 74 68 65  bytes within the
6970: 20 73 61 6d 65 20 73 65 63 74 6f 72 20 61 72 65   same sector are
6980: 0a 2a 2a 20 67 75 61 72 61 6e 74 65 65 64 20 74  .** guaranteed t
6990: 6f 20 62 65 20 75 6e 63 68 61 6e 67 65 64 2e 20  o be unchanged. 
69a0: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41   The SQLITE_IOCA
69b0: 50 5f 55 4e 44 45 4c 45 54 41 42 4c 45 5f 57 48  P_UNDELETABLE_WH
69c0: 45 4e 5f 4f 50 45 4e 0a 2a 2a 20 66 6c 61 67 20  EN_OPEN.** flag 
69d0: 69 6e 64 69 63 61 74 65 20 74 68 61 74 20 61 20  indicate that a 
69e0: 66 69 6c 65 20 63 61 6e 6e 6f 74 20 62 65 20 64  file cannot be d
69f0: 65 6c 65 74 65 64 20 77 68 65 6e 20 6f 70 65 6e  eleted when open
6a00: 2e 20 20 54 68 65 0a 2a 2a 20 53 51 4c 49 54 45  .  The.** SQLITE
6a10: 5f 49 4f 43 41 50 5f 49 4d 4d 55 54 41 42 4c 45  _IOCAP_IMMUTABLE
6a20: 20 66 6c 61 67 20 69 6e 64 69 63 61 74 65 73 20   flag indicates 
6a30: 74 68 61 74 20 74 68 65 20 66 69 6c 65 20 69 73  that the file is
6a40: 20 6f 6e 0a 2a 2a 20 72 65 61 64 2d 6f 6e 6c 79   on.** read-only
6a50: 20 6d 65 64 69 61 20 61 6e 64 20 63 61 6e 6e 6f   media and canno
6a60: 74 20 62 65 20 63 68 61 6e 67 65 64 20 65 76 65  t be changed eve
6a70: 6e 20 62 79 20 70 72 6f 63 65 73 73 65 73 20 77  n by processes w
6a80: 69 74 68 0a 2a 2a 20 65 6c 65 76 61 74 65 64 20  ith.** elevated 
6a90: 70 72 69 76 69 6c 65 67 65 73 2e 0a 2a 2f 0a 23  privileges..*/.#
6aa0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
6ab0: 43 41 50 5f 41 54 4f 4d 49 43 20 20 20 20 20 20  CAP_ATOMIC      
6ac0: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
6ad0: 30 30 30 30 31 0a 23 64 65 66 69 6e 65 20 53 51  00001.#define SQ
6ae0: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
6af0: 43 35 31 32 20 20 20 20 20 20 20 20 20 20 20 20  C512            
6b00: 20 20 30 78 30 30 30 30 30 30 30 32 0a 23 64 65    0x00000002.#de
6b10: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
6b20: 50 5f 41 54 4f 4d 49 43 31 4b 20 20 20 20 20 20  P_ATOMIC1K      
6b30: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
6b40: 30 30 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  004.#define SQLI
6b50: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 32  TE_IOCAP_ATOMIC2
6b60: 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  K               
6b70: 30 78 30 30 30 30 30 30 30 38 0a 23 64 65 66 69  0x00000008.#defi
6b80: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
6b90: 41 54 4f 4d 49 43 34 4b 20 20 20 20 20 20 20 20  ATOMIC4K        
6ba0: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 31         0x0000001
6bb0: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
6bc0: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 38 4b 20  _IOCAP_ATOMIC8K 
6bd0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78                0x
6be0: 30 30 30 30 30 30 32 30 0a 23 64 65 66 69 6e 65  00000020.#define
6bf0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
6c00: 4f 4d 49 43 31 36 4b 20 20 20 20 20 20 20 20 20  OMIC16K         
6c10: 20 20 20 20 20 30 78 30 30 30 30 30 30 34 30 0a       0x00000040.
6c20: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
6c30: 4f 43 41 50 5f 41 54 4f 4d 49 43 33 32 4b 20 20  OCAP_ATOMIC32K  
6c40: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30              0x00
6c50: 30 30 30 30 38 30 0a 23 64 65 66 69 6e 65 20 53  000080.#define S
6c60: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
6c70: 49 43 36 34 4b 20 20 20 20 20 20 20 20 20 20 20  IC64K           
6c80: 20 20 20 30 78 30 30 30 30 30 31 30 30 0a 23 64     0x00000100.#d
6c90: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
6ca0: 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 20  AP_SAFE_APPEND  
6cb0: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
6cc0: 30 32 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c  0200.#define SQL
6cd0: 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e  ITE_IOCAP_SEQUEN
6ce0: 54 49 41 4c 20 20 20 20 20 20 20 20 20 20 20 20  TIAL            
6cf0: 20 30 78 30 30 30 30 30 34 30 30 0a 23 64 65 66   0x00000400.#def
6d00: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
6d10: 5f 55 4e 44 45 4c 45 54 41 42 4c 45 5f 57 48 45  _UNDELETABLE_WHE
6d20: 4e 5f 4f 50 45 4e 20 20 30 78 30 30 30 30 30 38  N_OPEN  0x000008
6d30: 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  00.#define SQLIT
6d40: 45 5f 49 4f 43 41 50 5f 50 4f 57 45 52 53 41 46  E_IOCAP_POWERSAF
6d50: 45 5f 4f 56 45 52 57 52 49 54 45 20 20 20 20 30  E_OVERWRITE    0
6d60: 78 30 30 30 30 31 30 30 30 0a 23 64 65 66 69 6e  x00001000.#defin
6d70: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 49  e SQLITE_IOCAP_I
6d80: 4d 4d 55 54 41 42 4c 45 20 20 20 20 20 20 20 20  MMUTABLE        
6d90: 20 20 20 20 20 20 30 78 30 30 30 30 32 30 30 30        0x00002000
6da0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
6db0: 3a 20 46 69 6c 65 20 4c 6f 63 6b 69 6e 67 20 4c  : File Locking L
6dc0: 65 76 65 6c 73 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  evels.**.** SQLi
6dd0: 74 65 20 75 73 65 73 20 6f 6e 65 20 6f 66 20 74  te uses one of t
6de0: 68 65 73 65 20 69 6e 74 65 67 65 72 20 76 61 6c  hese integer val
6df0: 75 65 73 20 61 73 20 74 68 65 20 73 65 63 6f 6e  ues as the secon
6e00: 64 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 74 6f  d.** argument to
6e10: 20 63 61 6c 6c 73 20 69 74 20 6d 61 6b 65 73 20   calls it makes 
6e20: 74 6f 20 74 68 65 20 78 4c 6f 63 6b 28 29 20 61  to the xLock() a
6e30: 6e 64 20 78 55 6e 6c 6f 63 6b 28 29 20 6d 65 74  nd xUnlock() met
6e40: 68 6f 64 73 0a 2a 2a 20 6f 66 20 61 6e 20 5b 73  hods.** of an [s
6e50: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
6e60: 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 23 64  s] object..*/.#d
6e70: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43  efine SQLITE_LOC
6e80: 4b 5f 4e 4f 4e 45 20 20 20 20 20 20 20 20 20 20  K_NONE          
6e90: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
6ea0: 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 20 20 20 20  _LOCK_SHARED    
6eb0: 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51      1.#define SQ
6ec0: 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56  LITE_LOCK_RESERV
6ed0: 45 44 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e  ED      2.#defin
6ee0: 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45  e SQLITE_LOCK_PE
6ef0: 4e 44 49 4e 47 20 20 20 20 20 20 20 33 0a 23 64  NDING       3.#d
6f00: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43  efine SQLITE_LOC
6f10: 4b 5f 45 58 43 4c 55 53 49 56 45 20 20 20 20 20  K_EXCLUSIVE     
6f20: 34 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  4../*.** CAPI3RE
6f30: 46 3a 20 53 79 6e 63 68 72 6f 6e 69 7a 61 74 69  F: Synchronizati
6f40: 6f 6e 20 54 79 70 65 20 46 6c 61 67 73 0a 2a 2a  on Type Flags.**
6f50: 0a 2a 2a 20 57 68 65 6e 20 53 51 4c 69 74 65 20  .** When SQLite 
6f60: 69 6e 76 6f 6b 65 73 20 74 68 65 20 78 53 79 6e  invokes the xSyn
6f70: 63 28 29 20 6d 65 74 68 6f 64 20 6f 66 20 61 6e  c() method of an
6f80: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f  .** [sqlite3_io_
6f90: 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20  methods] object 
6fa0: 69 74 20 75 73 65 73 20 61 20 63 6f 6d 62 69 6e  it uses a combin
6fb0: 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20 74 68 65 73  ation of.** thes
6fc0: 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73  e integer values
6fd0: 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 61   as the second a
6fe0: 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 57  rgument..**.** W
6ff0: 68 65 6e 20 74 68 65 20 53 51 4c 49 54 45 5f 53  hen the SQLITE_S
7000: 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 20 66 6c 61  YNC_DATAONLY fla
7010: 67 20 69 73 20 75 73 65 64 2c 20 69 74 20 6d 65  g is used, it me
7020: 61 6e 73 20 74 68 61 74 20 74 68 65 0a 2a 2a 20  ans that the.** 
7030: 73 79 6e 63 20 6f 70 65 72 61 74 69 6f 6e 20 6f  sync operation o
7040: 6e 6c 79 20 6e 65 65 64 73 20 74 6f 20 66 6c 75  nly needs to flu
7050: 73 68 20 64 61 74 61 20 74 6f 20 6d 61 73 73 20  sh data to mass 
7060: 73 74 6f 72 61 67 65 2e 20 20 49 6e 6f 64 65 0a  storage.  Inode.
7070: 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 6e  ** information n
7080: 65 65 64 20 6e 6f 74 20 62 65 20 66 6c 75 73 68  eed not be flush
7090: 65 64 2e 20 49 66 20 74 68 65 20 6c 6f 77 65 72  ed. If the lower
70a0: 20 66 6f 75 72 20 62 69 74 73 20 6f 66 20 74 68   four bits of th
70b0: 65 20 66 6c 61 67 0a 2a 2a 20 65 71 75 61 6c 20  e flag.** equal 
70c0: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d  SQLITE_SYNC_NORM
70d0: 41 4c 2c 20 74 68 61 74 20 6d 65 61 6e 73 20 74  AL, that means t
70e0: 6f 20 75 73 65 20 6e 6f 72 6d 61 6c 20 66 73 79  o use normal fsy
70f0: 6e 63 28 29 20 73 65 6d 61 6e 74 69 63 73 2e 0a  nc() semantics..
7100: 2a 2a 20 49 66 20 74 68 65 20 6c 6f 77 65 72 20  ** If the lower 
7110: 66 6f 75 72 20 62 69 74 73 20 65 71 75 61 6c 20  four bits equal 
7120: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c  SQLITE_SYNC_FULL
7130: 2c 20 74 68 61 74 20 6d 65 61 6e 73 0a 2a 2a 20  , that means.** 
7140: 74 6f 20 75 73 65 20 4d 61 63 20 4f 53 20 58 20  to use Mac OS X 
7150: 73 74 79 6c 65 20 66 75 6c 6c 73 79 6e 63 20 69  style fullsync i
7160: 6e 73 74 65 61 64 20 6f 66 20 66 73 79 6e 63 28  nstead of fsync(
7170: 29 2e 0a 2a 2a 0a 2a 2a 20 44 6f 20 6e 6f 74 20  )..**.** Do not 
7180: 63 6f 6e 66 75 73 65 20 74 68 65 20 53 51 4c 49  confuse the SQLI
7190: 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61  TE_SYNC_NORMAL a
71a0: 6e 64 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46  nd SQLITE_SYNC_F
71b0: 55 4c 4c 20 66 6c 61 67 73 0a 2a 2a 20 77 69 74  ULL flags.** wit
71c0: 68 20 74 68 65 20 5b 50 52 41 47 4d 41 20 73 79  h the [PRAGMA sy
71d0: 6e 63 68 72 6f 6e 6f 75 73 5d 3d 4e 4f 52 4d 41  nchronous]=NORMA
71e0: 4c 20 61 6e 64 20 5b 50 52 41 47 4d 41 20 73 79  L and [PRAGMA sy
71f0: 6e 63 68 72 6f 6e 6f 75 73 5d 3d 46 55 4c 4c 0a  nchronous]=FULL.
7200: 2a 2a 20 73 65 74 74 69 6e 67 73 2e 20 20 54 68  ** settings.  Th
7210: 65 20 5b 73 79 6e 63 68 72 6f 6e 6f 75 73 20 70  e [synchronous p
7220: 72 61 67 6d 61 5d 20 64 65 74 65 72 6d 69 6e 65  ragma] determine
7230: 73 20 77 68 65 6e 20 63 61 6c 6c 73 20 74 6f 20  s when calls to 
7240: 74 68 65 0a 2a 2a 20 78 53 79 6e 63 20 56 46 53  the.** xSync VFS
7250: 20 6d 65 74 68 6f 64 20 6f 63 63 75 72 20 61 6e   method occur an
7260: 64 20 61 70 70 6c 69 65 73 20 75 6e 69 66 6f 72  d applies unifor
7270: 6d 6c 79 20 61 63 72 6f 73 73 20 61 6c 6c 20 70  mly across all p
7280: 6c 61 74 66 6f 72 6d 73 2e 0a 2a 2a 20 54 68 65  latforms..** The
7290: 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52   SQLITE_SYNC_NOR
72a0: 4d 41 4c 20 61 6e 64 20 53 51 4c 49 54 45 5f 53  MAL and SQLITE_S
72b0: 59 4e 43 5f 46 55 4c 4c 20 66 6c 61 67 73 20 64  YNC_FULL flags d
72c0: 65 74 65 72 6d 69 6e 65 20 68 6f 77 0a 2a 2a 20  etermine how.** 
72d0: 65 6e 65 72 67 65 74 69 63 20 6f 72 20 72 69 67  energetic or rig
72e0: 6f 72 6f 75 73 20 6f 72 20 66 6f 72 63 65 66 75  orous or forcefu
72f0: 6c 20 74 68 65 20 73 79 6e 63 20 6f 70 65 72 61  l the sync opera
7300: 74 69 6f 6e 73 20 61 72 65 20 61 6e 64 0a 2a 2a  tions are and.**
7310: 20 6f 6e 6c 79 20 6d 61 6b 65 20 61 20 64 69 66   only make a dif
7320: 66 65 72 65 6e 63 65 20 6f 6e 20 4d 61 63 20 4f  ference on Mac O
7330: 53 58 20 66 6f 72 20 74 68 65 20 64 65 66 61 75  SX for the defau
7340: 6c 74 20 53 51 4c 69 74 65 20 63 6f 64 65 2e 0a  lt SQLite code..
7350: 2a 2a 20 28 54 68 69 72 64 2d 70 61 72 74 79 20  ** (Third-party 
7360: 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  VFS implementati
7370: 6f 6e 73 20 6d 69 67 68 74 20 61 6c 73 6f 20 6d  ons might also m
7380: 61 6b 65 20 74 68 65 20 64 69 73 74 69 6e 63 74  ake the distinct
7390: 69 6f 6e 0a 2a 2a 20 62 65 74 77 65 65 6e 20 53  ion.** between S
73a0: 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41  QLITE_SYNC_NORMA
73b0: 4c 20 61 6e 64 20 53 51 4c 49 54 45 5f 53 59 4e  L and SQLITE_SYN
73c0: 43 5f 46 55 4c 4c 2c 20 62 75 74 20 61 6d 6f 6e  C_FULL, but amon
73d0: 67 20 74 68 65 0a 2a 2a 20 6f 70 65 72 61 74 69  g the.** operati
73e0: 6e 67 20 73 79 73 74 65 6d 73 20 6e 61 74 69 76  ng systems nativ
73f0: 65 6c 79 20 73 75 70 70 6f 72 74 65 64 20 62 79  ely supported by
7400: 20 53 51 4c 69 74 65 2c 20 6f 6e 6c 79 20 4d 61   SQLite, only Ma
7410: 63 20 4f 53 58 0a 2a 2a 20 63 61 72 65 73 20 61  c OSX.** cares a
7420: 62 6f 75 74 20 74 68 65 20 64 69 66 66 65 72 65  bout the differe
7430: 6e 63 65 2e 29 0a 2a 2f 0a 23 64 65 66 69 6e 65  nce.).*/.#define
7440: 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52   SQLITE_SYNC_NOR
7450: 4d 41 4c 20 20 20 20 20 20 20 20 30 78 30 30 30  MAL        0x000
7460: 30 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  02.#define SQLIT
7470: 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 20 20 20 20  E_SYNC_FULL     
7480: 20 20 20 20 20 30 78 30 30 30 30 33 0a 23 64 65       0x00003.#de
7490: 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e 43  fine SQLITE_SYNC
74a0: 5f 44 41 54 41 4f 4e 4c 59 20 20 20 20 20 20 30  _DATAONLY      0
74b0: 78 30 30 30 31 30 0a 0a 2f 2a 0a 2a 2a 20 43 41  x00010../*.** CA
74c0: 50 49 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 72  PI3REF: OS Inter
74d0: 66 61 63 65 20 4f 70 65 6e 20 46 69 6c 65 20 48  face Open File H
74e0: 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20 41 6e 20 5b  andle.**.** An [
74f0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62  sqlite3_file] ob
7500: 6a 65 63 74 20 72 65 70 72 65 73 65 6e 74 73 20  ject represents 
7510: 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20 69 6e 20  an open file in 
7520: 74 68 65 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  the .** [sqlite3
7530: 5f 76 66 73 20 7c 20 4f 53 20 69 6e 74 65 72 66  _vfs | OS interf
7540: 61 63 65 20 6c 61 79 65 72 5d 2e 20 20 49 6e 64  ace layer].  Ind
7550: 69 76 69 64 75 61 6c 20 4f 53 20 69 6e 74 65 72  ividual OS inter
7560: 66 61 63 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e  face.** implemen
7570: 74 61 74 69 6f 6e 73 20 77 69 6c 6c 0a 2a 2a 20  tations will.** 
7580: 77 61 6e 74 20 74 6f 20 73 75 62 63 6c 61 73 73  want to subclass
7590: 20 74 68 69 73 20 6f 62 6a 65 63 74 20 62 79 20   this object by 
75a0: 61 70 70 65 6e 64 69 6e 67 20 61 64 64 69 74 69  appending additi
75b0: 6f 6e 61 6c 20 66 69 65 6c 64 73 0a 2a 2a 20 66  onal fields.** f
75c0: 6f 72 20 74 68 65 69 72 20 6f 77 6e 20 75 73 65  or their own use
75d0: 2e 20 20 54 68 65 20 70 4d 65 74 68 6f 64 73 20  .  The pMethods 
75e0: 65 6e 74 72 79 20 69 73 20 61 20 70 6f 69 6e 74  entry is a point
75f0: 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 5b 73 71 6c  er to an.** [sql
7600: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d  ite3_io_methods]
7610: 20 6f 62 6a 65 63 74 20 74 68 61 74 20 64 65 66   object that def
7620: 69 6e 65 73 20 6d 65 74 68 6f 64 73 20 66 6f 72  ines methods for
7630: 20 70 65 72 66 6f 72 6d 69 6e 67 0a 2a 2a 20 49   performing.** I
7640: 2f 4f 20 6f 70 65 72 61 74 69 6f 6e 73 20 6f 6e  /O operations on
7650: 20 74 68 65 20 6f 70 65 6e 20 66 69 6c 65 2e 0a   the open file..
7660: 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63  */.typedef struc
7670: 74 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 20 73  t sqlite3_file s
7680: 71 6c 69 74 65 33 5f 66 69 6c 65 3b 0a 73 74 72  qlite3_file;.str
7690: 75 63 74 20 73 71 6c 69 74 65 33 5f 66 69 6c 65  uct sqlite3_file
76a0: 20 7b 0a 20 20 63 6f 6e 73 74 20 73 74 72 75 63   {.  const struc
76b0: 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74  t sqlite3_io_met
76c0: 68 6f 64 73 20 2a 70 4d 65 74 68 6f 64 73 3b 20  hods *pMethods; 
76d0: 20 2f 2a 20 4d 65 74 68 6f 64 73 20 66 6f 72 20   /* Methods for 
76e0: 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20 2a 2f 0a  an open file */.
76f0: 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  };../*.** CAPI3R
7700: 45 46 3a 20 4f 53 20 49 6e 74 65 72 66 61 63 65  EF: OS Interface
7710: 20 46 69 6c 65 20 56 69 72 74 75 61 6c 20 4d 65   File Virtual Me
7720: 74 68 6f 64 73 20 4f 62 6a 65 63 74 0a 2a 2a 0a  thods Object.**.
7730: 2a 2a 20 45 76 65 72 79 20 66 69 6c 65 20 6f 70  ** Every file op
7740: 65 6e 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c  ened by the [sql
7750: 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20  ite3_vfs.xOpen] 
7760: 6d 65 74 68 6f 64 20 70 6f 70 75 6c 61 74 65 73  method populates
7770: 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   an.** [sqlite3_
7780: 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 28 6f 72  file] object (or
7790: 2c 20 6d 6f 72 65 20 63 6f 6d 6d 6f 6e 6c 79 2c  , more commonly,
77a0: 20 61 20 73 75 62 63 6c 61 73 73 20 6f 66 20 74   a subclass of t
77b0: 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66  he.** [sqlite3_f
77c0: 69 6c 65 5d 20 6f 62 6a 65 63 74 29 20 77 69 74  ile] object) wit
77d0: 68 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  h a pointer to a
77e0: 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  n instance of th
77f0: 69 73 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 54 68  is object..** Th
7800: 69 73 20 6f 62 6a 65 63 74 20 64 65 66 69 6e 65  is object define
7810: 73 20 74 68 65 20 6d 65 74 68 6f 64 73 20 75 73  s the methods us
7820: 65 64 20 74 6f 20 70 65 72 66 6f 72 6d 20 76 61  ed to perform va
7830: 72 69 6f 75 73 20 6f 70 65 72 61 74 69 6f 6e 73  rious operations
7840: 0a 2a 2a 20 61 67 61 69 6e 73 74 20 74 68 65 20  .** against the 
7850: 6f 70 65 6e 20 66 69 6c 65 20 72 65 70 72 65 73  open file repres
7860: 65 6e 74 65 64 20 62 79 20 74 68 65 20 5b 73 71  ented by the [sq
7870: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65  lite3_file] obje
7880: 63 74 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65  ct..**.** If the
7890: 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f   [sqlite3_vfs.xO
78a0: 70 65 6e 5d 20 6d 65 74 68 6f 64 20 73 65 74 73  pen] method sets
78b0: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c   the sqlite3_fil
78c0: 65 2e 70 4d 65 74 68 6f 64 73 20 65 6c 65 6d 65  e.pMethods eleme
78d0: 6e 74 20 0a 2a 2a 20 74 6f 20 61 20 6e 6f 6e 2d  nt .** to a non-
78e0: 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68  NULL pointer, th
78f0: 65 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69  en the sqlite3_i
7900: 6f 5f 6d 65 74 68 6f 64 73 2e 78 43 6c 6f 73 65  o_methods.xClose
7910: 20 6d 65 74 68 6f 64 0a 2a 2a 20 6d 61 79 20 62   method.** may b
7920: 65 20 69 6e 76 6f 6b 65 64 20 65 76 65 6e 20 69  e invoked even i
7930: 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  f the [sqlite3_v
7940: 66 73 2e 78 4f 70 65 6e 5d 20 72 65 70 6f 72 74  fs.xOpen] report
7950: 65 64 20 74 68 61 74 20 69 74 20 66 61 69 6c 65  ed that it faile
7960: 64 2e 20 20 54 68 65 0a 2a 2a 20 6f 6e 6c 79 20  d.  The.** only 
7970: 77 61 79 20 74 6f 20 70 72 65 76 65 6e 74 20 61  way to prevent a
7980: 20 63 61 6c 6c 20 74 6f 20 78 43 6c 6f 73 65 20   call to xClose 
7990: 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 66 61 69 6c  following a fail
79a0: 65 64 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e  ed [sqlite3_vfs.
79b0: 78 4f 70 65 6e 5d 0a 2a 2a 20 69 73 20 66 6f 72  xOpen].** is for
79c0: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66   the [sqlite3_vf
79d0: 73 2e 78 4f 70 65 6e 5d 20 74 6f 20 73 65 74 20  s.xOpen] to set 
79e0: 74 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65  the sqlite3_file
79f0: 2e 70 4d 65 74 68 6f 64 73 20 65 6c 65 6d 65 6e  .pMethods elemen
7a00: 74 0a 2a 2a 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a  t.** to NULL..**
7a10: 0a 2a 2a 20 54 68 65 20 66 6c 61 67 73 20 61 72  .** The flags ar
7a20: 67 75 6d 65 6e 74 20 74 6f 20 78 53 79 6e 63 20  gument to xSync 
7a30: 6d 61 79 20 62 65 20 6f 6e 65 20 6f 66 20 5b 53  may be one of [S
7a40: 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41  QLITE_SYNC_NORMA
7a50: 4c 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45  L] or.** [SQLITE
7a60: 5f 53 59 4e 43 5f 46 55 4c 4c 5d 2e 20 20 54 68  _SYNC_FULL].  Th
7a70: 65 20 66 69 72 73 74 20 63 68 6f 69 63 65 20 69  e first choice i
7a80: 73 20 74 68 65 20 6e 6f 72 6d 61 6c 20 66 73 79  s the normal fsy
7a90: 6e 63 28 29 2e 0a 2a 2a 20 54 68 65 20 73 65 63  nc()..** The sec
7aa0: 6f 6e 64 20 63 68 6f 69 63 65 20 69 73 20 61 20  ond choice is a 
7ab0: 4d 61 63 20 4f 53 20 58 20 73 74 79 6c 65 20 66  Mac OS X style f
7ac0: 75 6c 6c 73 79 6e 63 2e 20 20 54 68 65 20 5b 53  ullsync.  The [S
7ad0: 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f  QLITE_SYNC_DATAO
7ae0: 4e 4c 59 5d 0a 2a 2a 20 66 6c 61 67 20 6d 61 79  NLY].** flag may
7af0: 20 62 65 20 4f 52 65 64 20 69 6e 20 74 6f 20 69   be ORed in to i
7b00: 6e 64 69 63 61 74 65 20 74 68 61 74 20 6f 6e 6c  ndicate that onl
7b10: 79 20 74 68 65 20 64 61 74 61 20 6f 66 20 74 68  y the data of th
7b20: 65 20 66 69 6c 65 0a 2a 2a 20 61 6e 64 20 6e 6f  e file.** and no
7b30: 74 20 69 74 73 20 69 6e 6f 64 65 20 6e 65 65 64  t its inode need
7b40: 73 20 74 6f 20 62 65 20 73 79 6e 63 65 64 2e 0a  s to be synced..
7b50: 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 74 65 67 65  **.** The intege
7b60: 72 20 76 61 6c 75 65 73 20 74 6f 20 78 4c 6f 63  r values to xLoc
7b70: 6b 28 29 20 61 6e 64 20 78 55 6e 6c 6f 63 6b 28  k() and xUnlock(
7b80: 29 20 61 72 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20  ) are one of.** 
7b90: 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  <ul>.** <li> [SQ
7ba0: 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c  LITE_LOCK_NONE],
7bb0: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
7bc0: 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a  _LOCK_SHARED],.*
7bd0: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c  * <li> [SQLITE_L
7be0: 4f 43 4b 5f 52 45 53 45 52 56 45 44 5d 2c 0a 2a  OCK_RESERVED],.*
7bf0: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c  * <li> [SQLITE_L
7c00: 4f 43 4b 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f 72  OCK_PENDING], or
7c10: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
7c20: 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 5d  _LOCK_EXCLUSIVE]
7c30: 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 20 78 4c  ..** </ul>.** xL
7c40: 6f 63 6b 28 29 20 69 6e 63 72 65 61 73 65 73 20  ock() increases 
7c50: 74 68 65 20 6c 6f 63 6b 2e 20 78 55 6e 6c 6f 63  the lock. xUnloc
7c60: 6b 28 29 20 64 65 63 72 65 61 73 65 73 20 74 68  k() decreases th
7c70: 65 20 6c 6f 63 6b 2e 0a 2a 2a 20 54 68 65 20 78  e lock..** The x
7c80: 43 68 65 63 6b 52 65 73 65 72 76 65 64 4c 6f 63  CheckReservedLoc
7c90: 6b 28 29 20 6d 65 74 68 6f 64 20 63 68 65 63 6b  k() method check
7ca0: 73 20 77 68 65 74 68 65 72 20 61 6e 79 20 64 61  s whether any da
7cb0: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
7cc0: 6e 2c 0a 2a 2a 20 65 69 74 68 65 72 20 69 6e 20  n,.** either in 
7cd0: 74 68 69 73 20 70 72 6f 63 65 73 73 20 6f 72 20  this process or 
7ce0: 69 6e 20 73 6f 6d 65 20 6f 74 68 65 72 20 70 72  in some other pr
7cf0: 6f 63 65 73 73 2c 20 69 73 20 68 6f 6c 64 69 6e  ocess, is holdin
7d00: 67 20 61 20 52 45 53 45 52 56 45 44 2c 0a 2a 2a  g a RESERVED,.**
7d10: 20 50 45 4e 44 49 4e 47 2c 20 6f 72 20 45 58 43   PENDING, or EXC
7d20: 4c 55 53 49 56 45 20 6c 6f 63 6b 20 6f 6e 20 74  LUSIVE lock on t
7d30: 68 65 20 66 69 6c 65 2e 20 20 49 74 20 72 65 74  he file.  It ret
7d40: 75 72 6e 73 20 74 72 75 65 0a 2a 2a 20 69 66 20  urns true.** if 
7d50: 73 75 63 68 20 61 20 6c 6f 63 6b 20 65 78 69 73  such a lock exis
7d60: 74 73 20 61 6e 64 20 66 61 6c 73 65 20 6f 74 68  ts and false oth
7d70: 65 72 77 69 73 65 2e 0a 2a 2a 0a 2a 2a 20 54 68  erwise..**.** Th
7d80: 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 28 29  e xFileControl()
7d90: 20 6d 65 74 68 6f 64 20 69 73 20 61 20 67 65 6e   method is a gen
7da0: 65 72 69 63 20 69 6e 74 65 72 66 61 63 65 20 74  eric interface t
7db0: 68 61 74 20 61 6c 6c 6f 77 73 20 63 75 73 74 6f  hat allows custo
7dc0: 6d 0a 2a 2a 20 56 46 53 20 69 6d 70 6c 65 6d 65  m.** VFS impleme
7dd0: 6e 74 61 74 69 6f 6e 73 20 74 6f 20 64 69 72 65  ntations to dire
7de0: 63 74 6c 79 20 63 6f 6e 74 72 6f 6c 20 61 6e 20  ctly control an 
7df0: 6f 70 65 6e 20 66 69 6c 65 20 75 73 69 6e 67 20  open file using 
7e00: 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
7e10: 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20  file_control()] 
7e20: 69 6e 74 65 72 66 61 63 65 2e 20 20 54 68 65 20  interface.  The 
7e30: 73 65 63 6f 6e 64 20 22 6f 70 22 20 61 72 67 75  second "op" argu
7e40: 6d 65 6e 74 20 69 73 20 61 6e 0a 2a 2a 20 69 6e  ment is an.** in
7e50: 74 65 67 65 72 20 6f 70 63 6f 64 65 2e 20 20 54  teger opcode.  T
7e60: 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e  he third argumen
7e70: 74 20 69 73 20 61 20 67 65 6e 65 72 69 63 20 70  t is a generic p
7e80: 6f 69 6e 74 65 72 20 69 6e 74 65 6e 64 65 64 20  ointer intended 
7e90: 74 6f 0a 2a 2a 20 70 6f 69 6e 74 20 74 6f 20 61  to.** point to a
7ea0: 20 73 74 72 75 63 74 75 72 65 20 74 68 61 74 20   structure that 
7eb0: 6d 61 79 20 63 6f 6e 74 61 69 6e 20 61 72 67 75  may contain argu
7ec0: 6d 65 6e 74 73 20 6f 72 20 73 70 61 63 65 20 69  ments or space i
7ed0: 6e 20 77 68 69 63 68 20 74 6f 0a 2a 2a 20 77 72  n which to.** wr
7ee0: 69 74 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  ite return value
7ef0: 73 2e 20 20 50 6f 74 65 6e 74 69 61 6c 20 75 73  s.  Potential us
7f00: 65 73 20 66 6f 72 20 78 46 69 6c 65 43 6f 6e 74  es for xFileCont
7f10: 72 6f 6c 28 29 20 6d 69 67 68 74 20 62 65 0a 2a  rol() might be.*
7f20: 2a 20 66 75 6e 63 74 69 6f 6e 73 20 74 6f 20 65  * functions to e
7f30: 6e 61 62 6c 65 20 62 6c 6f 63 6b 69 6e 67 20 6c  nable blocking l
7f40: 6f 63 6b 73 20 77 69 74 68 20 74 69 6d 65 6f 75  ocks with timeou
7f50: 74 73 2c 20 74 6f 20 63 68 61 6e 67 65 20 74 68  ts, to change th
7f60: 65 0a 2a 2a 20 6c 6f 63 6b 69 6e 67 20 73 74 72  e.** locking str
7f70: 61 74 65 67 79 20 28 66 6f 72 20 65 78 61 6d 70  ategy (for examp
7f80: 6c 65 20 74 6f 20 75 73 65 20 64 6f 74 2d 66 69  le to use dot-fi
7f90: 6c 65 20 6c 6f 63 6b 73 29 2c 20 74 6f 20 69 6e  le locks), to in
7fa0: 71 75 69 72 65 0a 2a 2a 20 61 62 6f 75 74 20 74  quire.** about t
7fb0: 68 65 20 73 74 61 74 75 73 20 6f 66 20 61 20 6c  he status of a l
7fc0: 6f 63 6b 2c 20 6f 72 20 74 6f 20 62 72 65 61 6b  ock, or to break
7fd0: 20 73 74 61 6c 65 20 6c 6f 63 6b 73 2e 20 20 54   stale locks.  T
7fe0: 68 65 20 53 51 4c 69 74 65 0a 2a 2a 20 63 6f 72  he SQLite.** cor
7ff0: 65 20 72 65 73 65 72 76 65 73 20 61 6c 6c 20 6f  e reserves all o
8000: 70 63 6f 64 65 73 20 6c 65 73 73 20 74 68 61 6e  pcodes less than
8010: 20 31 30 30 20 66 6f 72 20 69 74 73 20 6f 77 6e   100 for its own
8020: 20 75 73 65 2e 0a 2a 2a 20 41 20 5b 66 69 6c 65   use..** A [file
8030: 20 63 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64 65 73   control opcodes
8040: 20 7c 20 6c 69 73 74 20 6f 66 20 6f 70 63 6f 64   | list of opcod
8050: 65 73 5d 20 6c 65 73 73 20 74 68 61 6e 20 31 30  es] less than 10
8060: 30 20 69 73 20 61 76 61 69 6c 61 62 6c 65 2e 0a  0 is available..
8070: 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20  ** Applications 
8080: 74 68 61 74 20 64 65 66 69 6e 65 20 61 20 63 75  that define a cu
8090: 73 74 6f 6d 20 78 46 69 6c 65 43 6f 6e 74 72 6f  stom xFileContro
80a0: 6c 20 6d 65 74 68 6f 64 20 73 68 6f 75 6c 64 20  l method should 
80b0: 75 73 65 20 6f 70 63 6f 64 65 73 0a 2a 2a 20 67  use opcodes.** g
80c0: 72 65 61 74 65 72 20 74 68 61 6e 20 31 30 30 20  reater than 100 
80d0: 74 6f 20 61 76 6f 69 64 20 63 6f 6e 66 6c 69 63  to avoid conflic
80e0: 74 73 2e 20 20 56 46 53 20 69 6d 70 6c 65 6d 65  ts.  VFS impleme
80f0: 6e 74 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 0a  ntations should.
8100: 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  ** return [SQLIT
8110: 45 5f 4e 4f 54 46 4f 55 4e 44 5d 20 66 6f 72 20  E_NOTFOUND] for 
8120: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f 70 63  file control opc
8130: 6f 64 65 73 20 74 68 61 74 20 74 68 65 79 20 64  odes that they d
8140: 6f 20 6e 6f 74 0a 2a 2a 20 72 65 63 6f 67 6e 69  o not.** recogni
8150: 7a 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53  ze..**.** The xS
8160: 65 63 74 6f 72 53 69 7a 65 28 29 20 6d 65 74 68  ectorSize() meth
8170: 6f 64 20 72 65 74 75 72 6e 73 20 74 68 65 20 73  od returns the s
8180: 65 63 74 6f 72 20 73 69 7a 65 20 6f 66 20 74 68  ector size of th
8190: 65 0a 2a 2a 20 64 65 76 69 63 65 20 74 68 61 74  e.** device that
81a0: 20 75 6e 64 65 72 6c 69 65 73 20 74 68 65 20 66   underlies the f
81b0: 69 6c 65 2e 20 20 54 68 65 20 73 65 63 74 6f 72  ile.  The sector
81c0: 20 73 69 7a 65 20 69 73 20 74 68 65 0a 2a 2a 20   size is the.** 
81d0: 6d 69 6e 69 6d 75 6d 20 77 72 69 74 65 20 74 68  minimum write th
81e0: 61 74 20 63 61 6e 20 62 65 20 70 65 72 66 6f 72  at can be perfor
81f0: 6d 65 64 20 77 69 74 68 6f 75 74 20 64 69 73 74  med without dist
8200: 75 72 62 69 6e 67 0a 2a 2a 20 6f 74 68 65 72 20  urbing.** other 
8210: 62 79 74 65 73 20 69 6e 20 74 68 65 20 66 69 6c  bytes in the fil
8220: 65 2e 20 20 54 68 65 20 78 44 65 76 69 63 65 43  e.  The xDeviceC
8230: 68 61 72 61 63 74 65 72 69 73 74 69 63 73 28 29  haracteristics()
8240: 0a 2a 2a 20 6d 65 74 68 6f 64 20 72 65 74 75 72  .** method retur
8250: 6e 73 20 61 20 62 69 74 20 76 65 63 74 6f 72 20  ns a bit vector 
8260: 64 65 73 63 72 69 62 69 6e 67 20 62 65 68 61 76  describing behav
8270: 69 6f 72 73 20 6f 66 20 74 68 65 0a 2a 2a 20 75  iors of the.** u
8280: 6e 64 65 72 6c 79 69 6e 67 20 64 65 76 69 63 65  nderlying device
8290: 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  :.**.** <ul>.** 
82a0: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43  <li> [SQLITE_IOC
82b0: 41 50 5f 41 54 4f 4d 49 43 5d 0a 2a 2a 20 3c 6c  AP_ATOMIC].** <l
82c0: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  i> [SQLITE_IOCAP
82d0: 5f 41 54 4f 4d 49 43 35 31 32 5d 0a 2a 2a 20 3c  _ATOMIC512].** <
82e0: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41  li> [SQLITE_IOCA
82f0: 50 5f 41 54 4f 4d 49 43 31 4b 5d 0a 2a 2a 20 3c  P_ATOMIC1K].** <
8300: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41  li> [SQLITE_IOCA
8310: 50 5f 41 54 4f 4d 49 43 32 4b 5d 0a 2a 2a 20 3c  P_ATOMIC2K].** <
8320: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41  li> [SQLITE_IOCA
8330: 50 5f 41 54 4f 4d 49 43 34 4b 5d 0a 2a 2a 20 3c  P_ATOMIC4K].** <
8340: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41  li> [SQLITE_IOCA
8350: 50 5f 41 54 4f 4d 49 43 38 4b 5d 0a 2a 2a 20 3c  P_ATOMIC8K].** <
8360: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41  li> [SQLITE_IOCA
8370: 50 5f 41 54 4f 4d 49 43 31 36 4b 5d 0a 2a 2a 20  P_ATOMIC16K].** 
8380: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43  <li> [SQLITE_IOC
8390: 41 50 5f 41 54 4f 4d 49 43 33 32 4b 5d 0a 2a 2a  AP_ATOMIC32K].**
83a0: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f   <li> [SQLITE_IO
83b0: 43 41 50 5f 41 54 4f 4d 49 43 36 34 4b 5d 0a 2a  CAP_ATOMIC64K].*
83c0: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49  * <li> [SQLITE_I
83d0: 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44  OCAP_SAFE_APPEND
83e0: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ].** <li> [SQLIT
83f0: 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49  E_IOCAP_SEQUENTI
8400: 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a  AL].** </ul>.**.
8410: 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f  ** The SQLITE_IO
8420: 43 41 50 5f 41 54 4f 4d 49 43 20 70 72 6f 70 65  CAP_ATOMIC prope
8430: 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74 20 61  rty means that a
8440: 6c 6c 20 77 72 69 74 65 73 20 6f 66 0a 2a 2a 20  ll writes of.** 
8450: 61 6e 79 20 73 69 7a 65 20 61 72 65 20 61 74 6f  any size are ato
8460: 6d 69 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45  mic.  The SQLITE
8470: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e  _IOCAP_ATOMICnnn
8480: 20 76 61 6c 75 65 73 0a 2a 2a 20 6d 65 61 6e 20   values.** mean 
8490: 74 68 61 74 20 77 72 69 74 65 73 20 6f 66 20 62  that writes of b
84a0: 6c 6f 63 6b 73 20 74 68 61 74 20 61 72 65 20 6e  locks that are n
84b0: 6e 6e 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65  nn bytes in size
84c0: 20 61 6e 64 0a 2a 2a 20 61 72 65 20 61 6c 69 67   and.** are alig
84d0: 6e 65 64 20 74 6f 20 61 6e 20 61 64 64 72 65 73  ned to an addres
84e0: 73 20 77 68 69 63 68 20 69 73 20 61 6e 20 69 6e  s which is an in
84f0: 74 65 67 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f  teger multiple o
8500: 66 0a 2a 2a 20 6e 6e 6e 20 61 72 65 20 61 74 6f  f.** nnn are ato
8510: 6d 69 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45  mic.  The SQLITE
8520: 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45  _IOCAP_SAFE_APPE
8530: 4e 44 20 76 61 6c 75 65 20 6d 65 61 6e 73 0a 2a  ND value means.*
8540: 2a 20 74 68 61 74 20 77 68 65 6e 20 64 61 74 61  * that when data
8550: 20 69 73 20 61 70 70 65 6e 64 65 64 20 74 6f 20   is appended to 
8560: 61 20 66 69 6c 65 2c 20 74 68 65 20 64 61 74 61  a file, the data
8570: 20 69 73 20 61 70 70 65 6e 64 65 64 0a 2a 2a 20   is appended.** 
8580: 66 69 72 73 74 20 74 68 65 6e 20 74 68 65 20 73  first then the s
8590: 69 7a 65 20 6f 66 20 74 68 65 20 66 69 6c 65 20  ize of the file 
85a0: 69 73 20 65 78 74 65 6e 64 65 64 2c 20 6e 65 76  is extended, nev
85b0: 65 72 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20  er the other.** 
85c0: 77 61 79 20 61 72 6f 75 6e 64 2e 20 20 54 68 65  way around.  The
85d0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45   SQLITE_IOCAP_SE
85e0: 51 55 45 4e 54 49 41 4c 20 70 72 6f 70 65 72 74  QUENTIAL propert
85f0: 79 20 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20  y means that.** 
8600: 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 77  information is w
8610: 72 69 74 74 65 6e 20 74 6f 20 64 69 73 6b 20 69  ritten to disk i
8620: 6e 20 74 68 65 20 73 61 6d 65 20 6f 72 64 65 72  n the same order
8630: 20 61 73 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20   as calls.** to 
8640: 78 57 72 69 74 65 28 29 2e 0a 2a 2a 0a 2a 2a 20  xWrite()..**.** 
8650: 49 66 20 78 52 65 61 64 28 29 20 72 65 74 75 72  If xRead() retur
8660: 6e 73 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ns SQLITE_IOERR_
8670: 53 48 4f 52 54 5f 52 45 41 44 20 69 74 20 6d 75  SHORT_READ it mu
8680: 73 74 20 61 6c 73 6f 20 66 69 6c 6c 0a 2a 2a 20  st also fill.** 
8690: 69 6e 20 74 68 65 20 75 6e 72 65 61 64 20 70 6f  in the unread po
86a0: 72 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 62 75  rtions of the bu
86b0: 66 66 65 72 20 77 69 74 68 20 7a 65 72 6f 73 2e  ffer with zeros.
86c0: 20 20 41 20 56 46 53 20 74 68 61 74 0a 2a 2a 20    A VFS that.** 
86d0: 66 61 69 6c 73 20 74 6f 20 7a 65 72 6f 2d 66 69  fails to zero-fi
86e0: 6c 6c 20 73 68 6f 72 74 20 72 65 61 64 73 20 6d  ll short reads m
86f0: 69 67 68 74 20 73 65 65 6d 20 74 6f 20 77 6f 72  ight seem to wor
8700: 6b 2e 20 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20  k.  However,.** 
8710: 66 61 69 6c 75 72 65 20 74 6f 20 7a 65 72 6f 2d  failure to zero-
8720: 66 69 6c 6c 20 73 68 6f 72 74 20 72 65 61 64 73  fill short reads
8730: 20 77 69 6c 6c 20 65 76 65 6e 74 75 61 6c 6c 79   will eventually
8740: 20 6c 65 61 64 20 74 6f 0a 2a 2a 20 64 61 74 61   lead to.** data
8750: 62 61 73 65 20 63 6f 72 72 75 70 74 69 6f 6e 2e  base corruption.
8760: 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75  .*/.typedef stru
8770: 63 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  ct sqlite3_io_me
8780: 74 68 6f 64 73 20 73 71 6c 69 74 65 33 5f 69 6f  thods sqlite3_io
8790: 5f 6d 65 74 68 6f 64 73 3b 0a 73 74 72 75 63 74  _methods;.struct
87a0: 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68   sqlite3_io_meth
87b0: 6f 64 73 20 7b 0a 20 20 69 6e 74 20 69 56 65 72  ods {.  int iVer
87c0: 73 69 6f 6e 3b 0a 20 20 69 6e 74 20 28 2a 78 43  sion;.  int (*xC
87d0: 6c 6f 73 65 29 28 73 71 6c 69 74 65 33 5f 66 69  lose)(sqlite3_fi
87e0: 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52  le*);.  int (*xR
87f0: 65 61 64 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ead)(sqlite3_fil
8800: 65 2a 2c 20 76 6f 69 64 2a 2c 20 69 6e 74 20 69  e*, void*, int i
8810: 41 6d 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74  Amt, sqlite3_int
8820: 36 34 20 69 4f 66 73 74 29 3b 0a 20 20 69 6e 74  64 iOfst);.  int
8830: 20 28 2a 78 57 72 69 74 65 29 28 73 71 6c 69 74   (*xWrite)(sqlit
8840: 65 33 5f 66 69 6c 65 2a 2c 20 63 6f 6e 73 74 20  e3_file*, const 
8850: 76 6f 69 64 2a 2c 20 69 6e 74 20 69 41 6d 74 2c  void*, int iAmt,
8860: 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69   sqlite3_int64 i
8870: 4f 66 73 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78  Ofst);.  int (*x
8880: 54 72 75 6e 63 61 74 65 29 28 73 71 6c 69 74 65  Truncate)(sqlite
8890: 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33  3_file*, sqlite3
88a0: 5f 69 6e 74 36 34 20 73 69 7a 65 29 3b 0a 20 20  _int64 size);.  
88b0: 69 6e 74 20 28 2a 78 53 79 6e 63 29 28 73 71 6c  int (*xSync)(sql
88c0: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20  ite3_file*, int 
88d0: 66 6c 61 67 73 29 3b 0a 20 20 69 6e 74 20 28 2a  flags);.  int (*
88e0: 78 46 69 6c 65 53 69 7a 65 29 28 73 71 6c 69 74  xFileSize)(sqlit
88f0: 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65  e3_file*, sqlite
8900: 33 5f 69 6e 74 36 34 20 2a 70 53 69 7a 65 29 3b  3_int64 *pSize);
8910: 0a 20 20 69 6e 74 20 28 2a 78 4c 6f 63 6b 29 28  .  int (*xLock)(
8920: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69  sqlite3_file*, i
8930: 6e 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 55 6e  nt);.  int (*xUn
8940: 6c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69  lock)(sqlite3_fi
8950: 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74  le*, int);.  int
8960: 20 28 2a 78 43 68 65 63 6b 52 65 73 65 72 76 65   (*xCheckReserve
8970: 64 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66  dLock)(sqlite3_f
8980: 69 6c 65 2a 2c 20 69 6e 74 20 2a 70 52 65 73 4f  ile*, int *pResO
8990: 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69  ut);.  int (*xFi
89a0: 6c 65 43 6f 6e 74 72 6f 6c 29 28 73 71 6c 69 74  leControl)(sqlit
89b0: 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 6f 70  e3_file*, int op
89c0: 2c 20 76 6f 69 64 20 2a 70 41 72 67 29 3b 0a 20  , void *pArg);. 
89d0: 20 69 6e 74 20 28 2a 78 53 65 63 74 6f 72 53 69   int (*xSectorSi
89e0: 7a 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ze)(sqlite3_file
89f0: 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65 76  *);.  int (*xDev
8a00: 69 63 65 43 68 61 72 61 63 74 65 72 69 73 74 69  iceCharacteristi
8a10: 63 73 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  cs)(sqlite3_file
8a20: 2a 29 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f 64 73  *);.  /* Methods
8a30: 20 61 62 6f 76 65 20 61 72 65 20 76 61 6c 69 64   above are valid
8a40: 20 66 6f 72 20 76 65 72 73 69 6f 6e 20 31 20 2a   for version 1 *
8a50: 2f 0a 20 20 69 6e 74 20 28 2a 78 53 68 6d 4d 61  /.  int (*xShmMa
8a60: 70 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  p)(sqlite3_file*
8a70: 2c 20 69 6e 74 20 69 50 67 2c 20 69 6e 74 20 70  , int iPg, int p
8a80: 67 73 7a 2c 20 69 6e 74 2c 20 76 6f 69 64 20 76  gsz, int, void v
8a90: 6f 6c 61 74 69 6c 65 2a 2a 29 3b 0a 20 20 69 6e  olatile**);.  in
8aa0: 74 20 28 2a 78 53 68 6d 4c 6f 63 6b 29 28 73 71  t (*xShmLock)(sq
8ab0: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74  lite3_file*, int
8ac0: 20 6f 66 66 73 65 74 2c 20 69 6e 74 20 6e 2c 20   offset, int n, 
8ad0: 69 6e 74 20 66 6c 61 67 73 29 3b 0a 20 20 76 6f  int flags);.  vo
8ae0: 69 64 20 28 2a 78 53 68 6d 42 61 72 72 69 65 72  id (*xShmBarrier
8af0: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29  )(sqlite3_file*)
8b00: 3b 0a 20 20 69 6e 74 20 28 2a 78 53 68 6d 55 6e  ;.  int (*xShmUn
8b10: 6d 61 70 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  map)(sqlite3_fil
8b20: 65 2a 2c 20 69 6e 74 20 64 65 6c 65 74 65 46 6c  e*, int deleteFl
8b30: 61 67 29 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f 64  ag);.  /* Method
8b40: 73 20 61 62 6f 76 65 20 61 72 65 20 76 61 6c 69  s above are vali
8b50: 64 20 66 6f 72 20 76 65 72 73 69 6f 6e 20 32 20  d for version 2 
8b60: 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 46 65 74 63  */.  int (*xFetc
8b70: 68 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  h)(sqlite3_file*
8b80: 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  , sqlite3_int64 
8b90: 69 4f 66 73 74 2c 20 69 6e 74 20 69 41 6d 74 2c  iOfst, int iAmt,
8ba0: 20 76 6f 69 64 20 2a 2a 70 70 29 3b 0a 20 20 69   void **pp);.  i
8bb0: 6e 74 20 28 2a 78 55 6e 66 65 74 63 68 29 28 73  nt (*xUnfetch)(s
8bc0: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71  qlite3_file*, sq
8bd0: 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66 73  lite3_int64 iOfs
8be0: 74 2c 20 76 6f 69 64 20 2a 70 29 3b 0a 20 20 2f  t, void *p);.  /
8bf0: 2a 20 4d 65 74 68 6f 64 73 20 61 62 6f 76 65 20  * Methods above 
8c00: 61 72 65 20 76 61 6c 69 64 20 66 6f 72 20 76 65  are valid for ve
8c10: 72 73 69 6f 6e 20 33 20 2a 2f 0a 20 20 2f 2a 20  rsion 3 */.  /* 
8c20: 41 64 64 69 74 69 6f 6e 61 6c 20 6d 65 74 68 6f  Additional metho
8c30: 64 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 20  ds may be added 
8c40: 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73  in future releas
8c50: 65 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20  es */.};../*.** 
8c60: 43 41 50 49 33 52 45 46 3a 20 53 74 61 6e 64 61  CAPI3REF: Standa
8c70: 72 64 20 46 69 6c 65 20 43 6f 6e 74 72 6f 6c 20  rd File Control 
8c80: 4f 70 63 6f 64 65 73 0a 2a 2a 20 4b 45 59 57 4f  Opcodes.** KEYWO
8c90: 52 44 53 3a 20 7b 66 69 6c 65 20 63 6f 6e 74 72  RDS: {file contr
8ca0: 6f 6c 20 6f 70 63 6f 64 65 73 7d 20 7b 66 69 6c  ol opcodes} {fil
8cb0: 65 20 63 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64 65  e control opcode
8cc0: 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e  }.**.** These in
8cd0: 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 20  teger constants 
8ce0: 61 72 65 20 6f 70 63 6f 64 65 73 20 66 6f 72 20  are opcodes for 
8cf0: 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c  the xFileControl
8d00: 20 6d 65 74 68 6f 64 0a 2a 2a 20 6f 66 20 74 68   method.** of th
8d10: 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  e [sqlite3_io_me
8d20: 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 61 6e  thods] object an
8d30: 64 20 66 6f 72 20 74 68 65 20 5b 73 71 6c 69 74  d for the [sqlit
8d40: 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28  e3_file_control(
8d50: 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 2e  )].** interface.
8d60: 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c  .**.** <ul>.** <
8d70: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
8d80: 4c 5f 4c 4f 43 4b 53 54 41 54 45 5d 5d 0a 2a 2a  L_LOCKSTATE]].**
8d90: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e   The [SQLITE_FCN
8da0: 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 5d 20 6f 70  TL_LOCKSTATE] op
8db0: 63 6f 64 65 20 69 73 20 75 73 65 64 20 66 6f 72  code is used for
8dc0: 20 64 65 62 75 67 67 69 6e 67 2e 20 20 54 68 69   debugging.  Thi
8dd0: 73 0a 2a 2a 20 6f 70 63 6f 64 65 20 63 61 75 73  s.** opcode caus
8de0: 65 73 20 74 68 65 20 78 46 69 6c 65 43 6f 6e 74  es the xFileCont
8df0: 72 6f 6c 20 6d 65 74 68 6f 64 20 74 6f 20 77 72  rol method to wr
8e00: 69 74 65 20 74 68 65 20 63 75 72 72 65 6e 74 20  ite the current 
8e10: 73 74 61 74 65 20 6f 66 0a 2a 2a 20 74 68 65 20  state of.** the 
8e20: 6c 6f 63 6b 20 28 6f 6e 65 20 6f 66 20 5b 53 51  lock (one of [SQ
8e30: 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c  LITE_LOCK_NONE],
8e40: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48   [SQLITE_LOCK_SH
8e50: 41 52 45 44 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54  ARED],.** [SQLIT
8e60: 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44 5d  E_LOCK_RESERVED]
8e70: 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50  , [SQLITE_LOCK_P
8e80: 45 4e 44 49 4e 47 5d 2c 20 6f 72 20 5b 53 51 4c  ENDING], or [SQL
8e90: 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49  ITE_LOCK_EXCLUSI
8ea0: 56 45 5d 29 0a 2a 2a 20 69 6e 74 6f 20 61 6e 20  VE]).** into an 
8eb0: 69 6e 74 65 67 65 72 20 74 68 61 74 20 74 68 65  integer that the
8ec0: 20 70 41 72 67 20 61 72 67 75 6d 65 6e 74 20 70   pArg argument p
8ed0: 6f 69 6e 74 73 20 74 6f 2e 20 54 68 69 73 20 63  oints to. This c
8ee0: 61 70 61 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20  apability.** is 
8ef0: 75 73 65 64 20 64 75 72 69 6e 67 20 74 65 73 74  used during test
8f00: 69 6e 67 20 61 6e 64 20 69 73 20 6f 6e 6c 79 20  ing and is only 
8f10: 61 76 61 69 6c 61 62 6c 65 20 77 68 65 6e 20 74  available when t
8f20: 68 65 20 53 51 4c 49 54 45 5f 54 45 53 54 0a 2a  he SQLITE_TEST.*
8f30: 2a 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  * compile-time o
8f40: 70 74 69 6f 6e 20 69 73 20 75 73 65 64 2e 0a 2a  ption is used..*
8f50: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
8f60: 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e  E_FCNTL_SIZE_HIN
8f70: 54 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49  T]].** The [SQLI
8f80: 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 49  TE_FCNTL_SIZE_HI
8f90: 4e 54 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73  NT] opcode is us
8fa0: 65 64 20 62 79 20 53 51 4c 69 74 65 20 74 6f 20  ed by SQLite to 
8fb0: 67 69 76 65 20 74 68 65 20 56 46 53 0a 2a 2a 20  give the VFS.** 
8fc0: 6c 61 79 65 72 20 61 20 68 69 6e 74 20 6f 66 20  layer a hint of 
8fd0: 68 6f 77 20 6c 61 72 67 65 20 74 68 65 20 64 61  how large the da
8fe0: 74 61 62 61 73 65 20 66 69 6c 65 20 77 69 6c 6c  tabase file will
8ff0: 20 67 72 6f 77 20 74 6f 20 62 65 20 64 75 72 69   grow to be duri
9000: 6e 67 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e  ng the.** curren
9010: 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 2e 20 20  t transaction.  
9020: 54 68 69 73 20 68 69 6e 74 20 69 73 20 6e 6f 74  This hint is not
9030: 20 67 75 61 72 61 6e 74 65 65 64 20 74 6f 20 62   guaranteed to b
9040: 65 20 61 63 63 75 72 61 74 65 20 62 75 74 20 69  e accurate but i
9050: 74 0a 2a 2a 20 69 73 20 6f 66 74 65 6e 20 63 6c  t.** is often cl
9060: 6f 73 65 2e 20 20 54 68 65 20 75 6e 64 65 72 6c  ose.  The underl
9070: 79 69 6e 67 20 56 46 53 20 6d 69 67 68 74 20 63  ying VFS might c
9080: 68 6f 6f 73 65 20 74 6f 20 70 72 65 61 6c 6c 6f  hoose to preallo
9090: 63 61 74 65 20 64 61 74 61 62 61 73 65 0a 2a 2a  cate database.**
90a0: 20 66 69 6c 65 20 73 70 61 63 65 20 62 61 73 65   file space base
90b0: 64 20 6f 6e 20 74 68 69 73 20 68 69 6e 74 20 69  d on this hint i
90c0: 6e 20 6f 72 64 65 72 20 74 6f 20 68 65 6c 70 20  n order to help 
90d0: 77 72 69 74 65 73 20 74 6f 20 74 68 65 20 64 61  writes to the da
90e0: 74 61 62 61 73 65 0a 2a 2a 20 66 69 6c 65 20 72  tabase.** file r
90f0: 75 6e 20 66 61 73 74 65 72 2e 0a 2a 2a 0a 2a 2a  un faster..**.**
9100: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
9110: 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45 5d 5d  NTL_CHUNK_SIZE]]
9120: 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  .** The [SQLITE_
9130: 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45  FCNTL_CHUNK_SIZE
9140: 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64  ] opcode is used
9150: 20 74 6f 20 72 65 71 75 65 73 74 20 74 68 61 74   to request that
9160: 20 74 68 65 20 56 46 53 0a 2a 2a 20 65 78 74 65   the VFS.** exte
9170: 6e 64 73 20 61 6e 64 20 74 72 75 6e 63 61 74 65  nds and truncate
9180: 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  s the database f
9190: 69 6c 65 20 69 6e 20 63 68 75 6e 6b 73 20 6f 66  ile in chunks of
91a0: 20 61 20 73 69 7a 65 20 73 70 65 63 69 66 69 65   a size specifie
91b0: 64 0a 2a 2a 20 62 79 20 74 68 65 20 75 73 65 72  d.** by the user
91c0: 2e 20 54 68 65 20 66 6f 75 72 74 68 20 61 72 67  . The fourth arg
91d0: 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65  ument to [sqlite
91e0: 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29  3_file_control()
91f0: 5d 20 73 68 6f 75 6c 64 20 0a 2a 2a 20 70 6f 69  ] should .** poi
9200: 6e 74 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72  nt to an integer
9210: 20 28 74 79 70 65 20 69 6e 74 29 20 63 6f 6e 74   (type int) cont
9220: 61 69 6e 69 6e 67 20 74 68 65 20 6e 65 77 20 63  aining the new c
9230: 68 75 6e 6b 2d 73 69 7a 65 20 74 6f 20 75 73 65  hunk-size to use
9240: 0a 2a 2a 20 66 6f 72 20 74 68 65 20 6e 6f 6d 69  .** for the nomi
9250: 6e 61 74 65 64 20 64 61 74 61 62 61 73 65 2e 20  nated database. 
9260: 41 6c 6c 6f 63 61 74 69 6e 67 20 64 61 74 61 62  Allocating datab
9270: 61 73 65 20 66 69 6c 65 20 73 70 61 63 65 20 69  ase file space i
9280: 6e 20 6c 61 72 67 65 0a 2a 2a 20 63 68 75 6e 6b  n large.** chunk
9290: 73 20 28 73 61 79 20 31 4d 42 20 61 74 20 61 20  s (say 1MB at a 
92a0: 74 69 6d 65 29 2c 20 6d 61 79 20 72 65 64 75 63  time), may reduc
92b0: 65 20 66 69 6c 65 2d 73 79 73 74 65 6d 20 66 72  e file-system fr
92c0: 61 67 6d 65 6e 74 61 74 69 6f 6e 20 61 6e 64 0a  agmentation and.
92d0: 2a 2a 20 69 6d 70 72 6f 76 65 20 70 65 72 66 6f  ** improve perfo
92e0: 72 6d 61 6e 63 65 20 6f 6e 20 73 6f 6d 65 20 73  rmance on some s
92f0: 79 73 74 65 6d 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  ystems..**.** <l
9300: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
9310: 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52 5d 5d 0a  _FILE_POINTER]].
9320: 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  ** The [SQLITE_F
9330: 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 45  CNTL_FILE_POINTE
9340: 52 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65  R] opcode is use
9350: 64 20 74 6f 20 6f 62 74 61 69 6e 20 61 20 70 6f  d to obtain a po
9360: 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20  inter.** to the 
9370: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f  [sqlite3_file] o
9380: 62 6a 65 63 74 20 61 73 73 6f 63 69 61 74 65 64  bject associated
9390: 20 77 69 74 68 20 61 20 70 61 72 74 69 63 75 6c   with a particul
93a0: 61 72 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63  ar database.** c
93b0: 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 53 65 65 20  onnection.  See 
93c0: 61 6c 73 6f 20 5b 53 51 4c 49 54 45 5f 46 43 4e  also [SQLITE_FCN
93d0: 54 4c 5f 4a 4f 55 52 4e 41 4c 5f 50 4f 49 4e 54  TL_JOURNAL_POINT
93e0: 45 52 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  ER]..**.** <li>[
93f0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4a 4f  [SQLITE_FCNTL_JO
9400: 55 52 4e 41 4c 5f 50 4f 49 4e 54 45 52 5d 5d 0a  URNAL_POINTER]].
9410: 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  ** The [SQLITE_F
9420: 43 4e 54 4c 5f 4a 4f 55 52 4e 41 4c 5f 50 4f 49  CNTL_JOURNAL_POI
9430: 4e 54 45 52 5d 20 6f 70 63 6f 64 65 20 69 73 20  NTER] opcode is 
9440: 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 20 61  used to obtain a
9450: 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74   pointer.** to t
9460: 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  he [sqlite3_file
9470: 5d 20 6f 62 6a 65 63 74 20 61 73 73 6f 63 69 61  ] object associa
9480: 74 65 64 20 77 69 74 68 20 74 68 65 20 6a 6f 75  ted with the jou
9490: 72 6e 61 6c 20 66 69 6c 65 20 28 65 69 74 68 65  rnal file (eithe
94a0: 72 0a 2a 2a 20 74 68 65 20 5b 72 6f 6c 6c 62 61  r.** the [rollba
94b0: 63 6b 20 6a 6f 75 72 6e 61 6c 5d 20 6f 72 20 74  ck journal] or t
94c0: 68 65 20 5b 77 72 69 74 65 2d 61 68 65 61 64 20  he [write-ahead 
94d0: 6c 6f 67 5d 29 20 66 6f 72 20 61 20 70 61 72 74  log]) for a part
94e0: 69 63 75 6c 61 72 20 64 61 74 61 62 61 73 65 0a  icular database.
94f0: 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20  ** connection.  
9500: 53 65 65 20 61 6c 73 6f 20 5b 53 51 4c 49 54 45  See also [SQLITE
9510: 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e  _FCNTL_FILE_POIN
9520: 54 45 52 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  TER]..**.** <li>
9530: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53  [[SQLITE_FCNTL_S
9540: 59 4e 43 5f 4f 4d 49 54 54 45 44 5d 5d 0a 2a 2a  YNC_OMITTED]].**
9550: 20 4e 6f 20 6c 6f 6e 67 65 72 20 69 6e 20 75 73   No longer in us
9560: 65 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53  e..**.** <li>[[S
9570: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43  QLITE_FCNTL_SYNC
9580: 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54  ]].** The [SQLIT
9590: 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5d 20 6f 70  E_FCNTL_SYNC] op
95a0: 63 6f 64 65 20 69 73 20 67 65 6e 65 72 61 74 65  code is generate
95b0: 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 62 79 20  d internally by 
95c0: 53 51 4c 69 74 65 20 61 6e 64 0a 2a 2a 20 73 65  SQLite and.** se
95d0: 6e 74 20 74 6f 20 74 68 65 20 56 46 53 20 69 6d  nt to the VFS im
95e0: 6d 65 64 69 61 74 65 6c 79 20 62 65 66 6f 72 65  mediately before
95f0: 20 74 68 65 20 78 53 79 6e 63 20 6d 65 74 68 6f   the xSync metho
9600: 64 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 20  d is invoked on 
9610: 61 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 66 69  a.** database fi
9620: 6c 65 20 64 65 73 63 72 69 70 74 6f 72 2e 20 4f  le descriptor. O
9630: 72 2c 20 69 66 20 74 68 65 20 78 53 79 6e 63 20  r, if the xSync 
9640: 6d 65 74 68 6f 64 20 69 73 20 6e 6f 74 20 69 6e  method is not in
9650: 76 6f 6b 65 64 20 0a 2a 2a 20 62 65 63 61 75 73  voked .** becaus
9660: 65 20 74 68 65 20 75 73 65 72 20 68 61 73 20 63  e the user has c
9670: 6f 6e 66 69 67 75 72 65 64 20 53 51 4c 69 74 65  onfigured SQLite
9680: 20 77 69 74 68 20 0a 2a 2a 20 5b 50 52 41 47 4d   with .** [PRAGM
9690: 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 20 7c 20  A synchronous | 
96a0: 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f  PRAGMA synchrono
96b0: 75 73 3d 4f 46 46 5d 20 69 74 20 69 73 20 69 6e  us=OFF] it is in
96c0: 76 6f 6b 65 64 20 69 6e 20 70 6c 61 63 65 20 0a  voked in place .
96d0: 2a 2a 20 6f 66 20 74 68 65 20 78 53 79 6e 63 20  ** of the xSync 
96e0: 6d 65 74 68 6f 64 2e 20 49 6e 20 6d 6f 73 74 20  method. In most 
96f0: 63 61 73 65 73 2c 20 74 68 65 20 70 6f 69 6e 74  cases, the point
9700: 65 72 20 61 72 67 75 6d 65 6e 74 20 70 61 73 73  er argument pass
9710: 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 69 73 20  ed with.** this 
9720: 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 69 73 20  file-control is 
9730: 4e 55 4c 4c 2e 20 48 6f 77 65 76 65 72 2c 20 69  NULL. However, i
9740: 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  f the database f
9750: 69 6c 65 20 69 73 20 62 65 69 6e 67 20 73 79 6e  ile is being syn
9760: 63 65 64 0a 2a 2a 20 61 73 20 70 61 72 74 20 6f  ced.** as part o
9770: 66 20 61 20 6d 75 6c 74 69 2d 64 61 74 61 62 61  f a multi-databa
9780: 73 65 20 63 6f 6d 6d 69 74 2c 20 74 68 65 20 61  se commit, the a
9790: 72 67 75 6d 65 6e 74 20 70 6f 69 6e 74 73 20 74  rgument points t
97a0: 6f 20 61 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74  o a nul-terminat
97b0: 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20 63 6f 6e  ed.** string con
97c0: 74 61 69 6e 69 6e 67 20 74 68 65 20 74 72 61 6e  taining the tran
97d0: 73 61 63 74 69 6f 6e 73 20 6d 61 73 74 65 72 2d  sactions master-
97e0: 6a 6f 75 72 6e 61 6c 20 66 69 6c 65 20 6e 61 6d  journal file nam
97f0: 65 2e 20 56 46 53 65 73 20 74 68 61 74 20 0a 2a  e. VFSes that .*
9800: 2a 20 64 6f 20 6e 6f 74 20 6e 65 65 64 20 74 68  * do not need th
9810: 69 73 20 73 69 67 6e 61 6c 20 73 68 6f 75 6c 64  is signal should
9820: 20 73 69 6c 65 6e 74 6c 79 20 69 67 6e 6f 72 65   silently ignore
9830: 20 74 68 69 73 20 6f 70 63 6f 64 65 2e 20 41 70   this opcode. Ap
9840: 70 6c 69 63 61 74 69 6f 6e 73 20 0a 2a 2a 20 73  plications .** s
9850: 68 6f 75 6c 64 20 6e 6f 74 20 63 61 6c 6c 20 5b  hould not call [
9860: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e  sqlite3_file_con
9870: 74 72 6f 6c 28 29 5d 20 77 69 74 68 20 74 68 69  trol()] with thi
9880: 73 20 6f 70 63 6f 64 65 20 61 73 20 64 6f 69 6e  s opcode as doin
9890: 67 20 73 6f 20 6d 61 79 20 0a 2a 2a 20 64 69 73  g so may .** dis
98a0: 72 75 70 74 20 74 68 65 20 6f 70 65 72 61 74 69  rupt the operati
98b0: 6f 6e 20 6f 66 20 74 68 65 20 73 70 65 63 69 61  on of the specia
98c0: 6c 69 7a 65 64 20 56 46 53 65 73 20 74 68 61 74  lized VFSes that
98d0: 20 64 6f 20 72 65 71 75 69 72 65 20 69 74 2e 20   do require it. 
98e0: 20 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51   .**.** <li>[[SQ
98f0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49  LITE_FCNTL_COMMI
9900: 54 5f 50 48 41 53 45 54 57 4f 5d 5d 0a 2a 2a 20  T_PHASETWO]].** 
9910: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
9920: 4c 5f 43 4f 4d 4d 49 54 5f 50 48 41 53 45 54 57  L_COMMIT_PHASETW
9930: 4f 5d 20 6f 70 63 6f 64 65 20 69 73 20 67 65 6e  O] opcode is gen
9940: 65 72 61 74 65 64 20 69 6e 74 65 72 6e 61 6c 6c  erated internall
9950: 79 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20 61  y by SQLite.** a
9960: 6e 64 20 73 65 6e 74 20 74 6f 20 74 68 65 20 56  nd sent to the V
9970: 46 53 20 61 66 74 65 72 20 61 20 74 72 61 6e 73  FS after a trans
9980: 61 63 74 69 6f 6e 20 68 61 73 20 62 65 65 6e 20  action has been 
9990: 63 6f 6d 6d 69 74 74 65 64 20 69 6d 6d 65 64 69  committed immedi
99a0: 61 74 65 6c 79 0a 2a 2a 20 62 75 74 20 62 65 66  ately.** but bef
99b0: 6f 72 65 20 74 68 65 20 64 61 74 61 62 61 73 65  ore the database
99c0: 20 69 73 20 75 6e 6c 6f 63 6b 65 64 2e 20 56 46   is unlocked. VF
99d0: 53 65 73 20 74 68 61 74 20 64 6f 20 6e 6f 74 20  Ses that do not 
99e0: 6e 65 65 64 20 74 68 69 73 20 73 69 67 6e 61 6c  need this signal
99f0: 0a 2a 2a 20 73 68 6f 75 6c 64 20 73 69 6c 65 6e  .** should silen
9a00: 74 6c 79 20 69 67 6e 6f 72 65 20 74 68 69 73 20  tly ignore this 
9a10: 6f 70 63 6f 64 65 2e 20 41 70 70 6c 69 63 61 74  opcode. Applicat
9a20: 69 6f 6e 73 20 73 68 6f 75 6c 64 20 6e 6f 74 20  ions should not 
9a30: 63 61 6c 6c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  call.** [sqlite3
9a40: 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d  _file_control()]
9a50: 20 77 69 74 68 20 74 68 69 73 20 6f 70 63 6f 64   with this opcod
9a60: 65 20 61 73 20 64 6f 69 6e 67 20 73 6f 20 6d 61  e as doing so ma
9a70: 79 20 64 69 73 72 75 70 74 20 74 68 65 20 0a 2a  y disrupt the .*
9a80: 2a 20 6f 70 65 72 61 74 69 6f 6e 20 6f 66 20 74  * operation of t
9a90: 68 65 20 73 70 65 63 69 61 6c 69 7a 65 64 20 56  he specialized V
9aa0: 46 53 65 73 20 74 68 61 74 20 64 6f 20 72 65 71  FSes that do req
9ab0: 75 69 72 65 20 69 74 2e 20 20 0a 2a 2a 0a 2a 2a  uire it.  .**.**
9ac0: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
9ad0: 4e 54 4c 5f 57 49 4e 33 32 5f 41 56 5f 52 45 54  NTL_WIN32_AV_RET
9ae0: 52 59 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51  RY]].** ^The [SQ
9af0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32  LITE_FCNTL_WIN32
9b00: 5f 41 56 5f 52 45 54 52 59 5d 20 6f 70 63 6f 64  _AV_RETRY] opcod
9b10: 65 20 69 73 20 75 73 65 64 20 74 6f 20 63 6f 6e  e is used to con
9b20: 66 69 67 75 72 65 20 61 75 74 6f 6d 61 74 69 63  figure automatic
9b30: 0a 2a 2a 20 72 65 74 72 79 20 63 6f 75 6e 74 73  .** retry counts
9b40: 20 61 6e 64 20 69 6e 74 65 72 76 61 6c 73 20 66   and intervals f
9b50: 6f 72 20 63 65 72 74 61 69 6e 20 64 69 73 6b 20  or certain disk 
9b60: 49 2f 4f 20 6f 70 65 72 61 74 69 6f 6e 73 20 66  I/O operations f
9b70: 6f 72 20 74 68 65 0a 2a 2a 20 77 69 6e 64 6f 77  or the.** window
9b80: 73 20 5b 56 46 53 5d 20 69 6e 20 6f 72 64 65 72  s [VFS] in order
9b90: 20 74 6f 20 70 72 6f 76 69 64 65 20 72 6f 62 75   to provide robu
9ba0: 73 74 6e 65 73 73 20 69 6e 20 74 68 65 20 70 72  stness in the pr
9bb0: 65 73 65 6e 63 65 20 6f 66 0a 2a 2a 20 61 6e 74  esence of.** ant
9bc0: 69 2d 76 69 72 75 73 20 70 72 6f 67 72 61 6d 73  i-virus programs
9bd0: 2e 20 20 42 79 20 64 65 66 61 75 6c 74 2c 20 74  .  By default, t
9be0: 68 65 20 77 69 6e 64 6f 77 73 20 56 46 53 20 77  he windows VFS w
9bf0: 69 6c 6c 20 72 65 74 72 79 20 66 69 6c 65 20 72  ill retry file r
9c00: 65 61 64 2c 0a 2a 2a 20 66 69 6c 65 20 77 72 69  ead,.** file wri
9c10: 74 65 2c 20 61 6e 64 20 66 69 6c 65 20 64 65 6c  te, and file del
9c20: 65 74 65 20 6f 70 65 72 61 74 69 6f 6e 73 20 75  ete operations u
9c30: 70 20 74 6f 20 31 30 20 74 69 6d 65 73 2c 20 77  p to 10 times, w
9c40: 69 74 68 20 61 20 64 65 6c 61 79 0a 2a 2a 20 6f  ith a delay.** o
9c50: 66 20 32 35 20 6d 69 6c 6c 69 73 65 63 6f 6e 64  f 25 millisecond
9c60: 73 20 62 65 66 6f 72 65 20 74 68 65 20 66 69 72  s before the fir
9c70: 73 74 20 72 65 74 72 79 20 61 6e 64 20 77 69 74  st retry and wit
9c80: 68 20 74 68 65 20 64 65 6c 61 79 20 69 6e 63 72  h the delay incr
9c90: 65 61 73 69 6e 67 0a 2a 2a 20 62 79 20 61 6e 20  easing.** by an 
9ca0: 61 64 64 69 74 69 6f 6e 61 6c 20 32 35 20 6d 69  additional 25 mi
9cb0: 6c 6c 69 73 65 63 6f 6e 64 73 20 77 69 74 68 20  lliseconds with 
9cc0: 65 61 63 68 20 73 75 62 73 65 71 75 65 6e 74 20  each subsequent 
9cd0: 72 65 74 72 79 2e 20 20 54 68 69 73 0a 2a 2a 20  retry.  This.** 
9ce0: 6f 70 63 6f 64 65 20 61 6c 6c 6f 77 73 20 74 68  opcode allows th
9cf0: 65 73 65 20 74 77 6f 20 76 61 6c 75 65 73 20 28  ese two values (
9d00: 31 30 20 72 65 74 72 69 65 73 20 61 6e 64 20 32  10 retries and 2
9d10: 35 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f  5 milliseconds o
9d20: 66 20 64 65 6c 61 79 29 0a 2a 2a 20 74 6f 20 62  f delay).** to b
9d30: 65 20 61 64 6a 75 73 74 65 64 2e 20 20 54 68 65  e adjusted.  The
9d40: 20 76 61 6c 75 65 73 20 61 72 65 20 63 68 61 6e   values are chan
9d50: 67 65 64 20 66 6f 72 20 61 6c 6c 20 64 61 74 61  ged for all data
9d60: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  base connections
9d70: 0a 2a 2a 20 77 69 74 68 69 6e 20 74 68 65 20 73  .** within the s
9d80: 61 6d 65 20 70 72 6f 63 65 73 73 2e 20 20 54 68  ame process.  Th
9d90: 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20  e argument is a 
9da0: 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 61 72  pointer to an ar
9db0: 72 61 79 20 6f 66 20 74 77 6f 0a 2a 2a 20 69 6e  ray of two.** in
9dc0: 74 65 67 65 72 73 20 77 68 65 72 65 20 74 68 65  tegers where the
9dd0: 20 66 69 72 73 74 20 69 6e 74 65 67 65 72 20 69   first integer i
9de0: 20 74 68 65 20 6e 65 77 20 72 65 74 72 79 20 63   the new retry c
9df0: 6f 75 6e 74 20 61 6e 64 20 74 68 65 20 73 65 63  ount and the sec
9e00: 6f 6e 64 0a 2a 2a 20 69 6e 74 65 67 65 72 20 69  ond.** integer i
9e10: 73 20 74 68 65 20 64 65 6c 61 79 2e 20 20 49 66  s the delay.  If
9e20: 20 65 69 74 68 65 72 20 69 6e 74 65 67 65 72 20   either integer 
9e30: 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65  is negative, the
9e40: 6e 20 74 68 65 20 73 65 74 74 69 6e 67 0a 2a 2a  n the setting.**
9e50: 20 69 73 20 6e 6f 74 20 63 68 61 6e 67 65 64 20   is not changed 
9e60: 62 75 74 20 69 6e 73 74 65 61 64 20 74 68 65 20  but instead the 
9e70: 70 72 69 6f 72 20 76 61 6c 75 65 20 6f 66 20 74  prior value of t
9e80: 68 61 74 20 73 65 74 74 69 6e 67 20 69 73 20 77  hat setting is w
9e90: 72 69 74 74 65 6e 0a 2a 2a 20 69 6e 74 6f 20 74  ritten.** into t
9ea0: 68 65 20 61 72 72 61 79 20 65 6e 74 72 79 2c 20  he array entry, 
9eb0: 61 6c 6c 6f 77 69 6e 67 20 74 68 65 20 63 75 72  allowing the cur
9ec0: 72 65 6e 74 20 72 65 74 72 79 20 73 65 74 74 69  rent retry setti
9ed0: 6e 67 73 20 74 6f 20 62 65 0a 2a 2a 20 69 6e 74  ngs to be.** int
9ee0: 65 72 72 6f 67 61 74 65 64 2e 20 20 54 68 65 20  errogated.  The 
9ef0: 7a 44 62 4e 61 6d 65 20 70 61 72 61 6d 65 74 65  zDbName paramete
9f00: 72 20 69 73 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a  r is ignored..**
9f10: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
9f20: 5f 46 43 4e 54 4c 5f 50 45 52 53 49 53 54 5f 57  _FCNTL_PERSIST_W
9f30: 41 4c 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51  AL]].** ^The [SQ
9f40: 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 45 52 53 49  LITE_FCNTL_PERSI
9f50: 53 54 5f 57 41 4c 5d 20 6f 70 63 6f 64 65 20 69  ST_WAL] opcode i
9f60: 73 20 75 73 65 64 20 74 6f 20 73 65 74 20 6f 72  s used to set or
9f70: 20 71 75 65 72 79 20 74 68 65 0a 2a 2a 20 70 65   query the.** pe
9f80: 72 73 69 73 74 65 6e 74 20 5b 57 41 4c 20 7c 20  rsistent [WAL | 
9f90: 57 72 69 74 65 20 41 68 65 61 64 20 4c 6f 67 5d  Write Ahead Log]
9fa0: 20 73 65 74 74 69 6e 67 2e 20 20 42 79 20 64 65   setting.  By de
9fb0: 66 61 75 6c 74 2c 20 74 68 65 20 61 75 78 69 6c  fault, the auxil
9fc0: 69 61 72 79 0a 2a 2a 20 77 72 69 74 65 20 61 68  iary.** write ah
9fd0: 65 61 64 20 6c 6f 67 20 61 6e 64 20 73 68 61 72  ead log and shar
9fe0: 65 64 20 6d 65 6d 6f 72 79 20 66 69 6c 65 73 20  ed memory files 
9ff0: 75 73 65 64 20 66 6f 72 20 74 72 61 6e 73 61 63  used for transac
a000: 74 69 6f 6e 20 63 6f 6e 74 72 6f 6c 0a 2a 2a 20  tion control.** 
a010: 61 72 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  are automaticall
a020: 79 20 64 65 6c 65 74 65 64 20 77 68 65 6e 20 74  y deleted when t
a030: 68 65 20 6c 61 74 65 73 74 20 63 6f 6e 6e 65 63  he latest connec
a040: 74 69 6f 6e 20 74 6f 20 74 68 65 20 64 61 74 61  tion to the data
a050: 62 61 73 65 0a 2a 2a 20 63 6c 6f 73 65 73 2e 20  base.** closes. 
a060: 20 53 65 74 74 69 6e 67 20 70 65 72 73 69 73 74   Setting persist
a070: 65 6e 74 20 57 41 4c 20 6d 6f 64 65 20 63 61 75  ent WAL mode cau
a080: 73 65 73 20 74 68 6f 73 65 20 66 69 6c 65 73 20  ses those files 
a090: 74 6f 20 70 65 72 73 69 73 74 20 61 66 74 65 72  to persist after
a0a0: 0a 2a 2a 20 63 6c 6f 73 65 2e 20 20 50 65 72 73  .** close.  Pers
a0b0: 69 73 74 69 6e 67 20 74 68 65 20 66 69 6c 65 73  isting the files
a0c0: 20 69 73 20 75 73 65 66 75 6c 20 77 68 65 6e 20   is useful when 
a0d0: 6f 74 68 65 72 20 70 72 6f 63 65 73 73 65 73 20  other processes 
a0e0: 74 68 61 74 20 64 6f 20 6e 6f 74 0a 2a 2a 20 68  that do not.** h
a0f0: 61 76 65 20 77 72 69 74 65 20 70 65 72 6d 69 73  ave write permis
a100: 73 69 6f 6e 20 6f 6e 20 74 68 65 20 64 69 72 65  sion on the dire
a110: 63 74 6f 72 79 20 63 6f 6e 74 61 69 6e 69 6e 67  ctory containing
a120: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
a130: 6c 65 20 77 61 6e 74 0a 2a 2a 20 74 6f 20 72 65  le want.** to re
a140: 61 64 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ad the database 
a150: 66 69 6c 65 2c 20 61 73 20 74 68 65 20 57 41 4c  file, as the WAL
a160: 20 61 6e 64 20 73 68 61 72 65 64 20 6d 65 6d 6f   and shared memo
a170: 72 79 20 66 69 6c 65 73 20 6d 75 73 74 20 65 78  ry files must ex
a180: 69 73 74 0a 2a 2a 20 69 6e 20 6f 72 64 65 72 20  ist.** in order 
a190: 66 6f 72 20 74 68 65 20 64 61 74 61 62 61 73 65  for the database
a1a0: 20 74 6f 20 62 65 20 72 65 61 64 61 62 6c 65 2e   to be readable.
a1b0: 20 20 54 68 65 20 66 6f 75 72 74 68 20 70 61 72    The fourth par
a1c0: 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 73 71  ameter to.** [sq
a1d0: 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72  lite3_file_contr
a1e0: 6f 6c 28 29 5d 20 66 6f 72 20 74 68 69 73 20 6f  ol()] for this o
a1f0: 70 63 6f 64 65 20 73 68 6f 75 6c 64 20 62 65 20  pcode should be 
a200: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  a pointer to an 
a210: 69 6e 74 65 67 65 72 2e 0a 2a 2a 20 54 68 61 74  integer..** That
a220: 20 69 6e 74 65 67 65 72 20 69 73 20 30 20 74 6f   integer is 0 to
a230: 20 64 69 73 61 62 6c 65 20 70 65 72 73 69 73 74   disable persist
a240: 65 6e 74 20 57 41 4c 20 6d 6f 64 65 20 6f 72 20  ent WAL mode or 
a250: 31 20 74 6f 20 65 6e 61 62 6c 65 20 70 65 72 73  1 to enable pers
a260: 69 73 74 65 6e 74 0a 2a 2a 20 57 41 4c 20 6d 6f  istent.** WAL mo
a270: 64 65 2e 20 20 49 66 20 74 68 65 20 69 6e 74 65  de.  If the inte
a280: 67 65 72 20 69 73 20 2d 31 2c 20 74 68 65 6e 20  ger is -1, then 
a290: 69 74 20 69 73 20 6f 76 65 72 77 72 69 74 74 65  it is overwritte
a2a0: 6e 20 77 69 74 68 20 74 68 65 20 63 75 72 72 65  n with the curre
a2b0: 6e 74 0a 2a 2a 20 57 41 4c 20 70 65 72 73 69 73  nt.** WAL persis
a2c0: 74 65 6e 63 65 20 73 65 74 74 69 6e 67 2e 0a 2a  tence setting..*
a2d0: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
a2e0: 45 5f 46 43 4e 54 4c 5f 50 4f 57 45 52 53 41 46  E_FCNTL_POWERSAF
a2f0: 45 5f 4f 56 45 52 57 52 49 54 45 5d 5d 0a 2a 2a  E_OVERWRITE]].**
a300: 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43   ^The [SQLITE_FC
a310: 4e 54 4c 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56  NTL_POWERSAFE_OV
a320: 45 52 57 52 49 54 45 5d 20 6f 70 63 6f 64 65 20  ERWRITE] opcode 
a330: 69 73 20 75 73 65 64 20 74 6f 20 73 65 74 20 6f  is used to set o
a340: 72 20 71 75 65 72 79 20 74 68 65 0a 2a 2a 20 70  r query the.** p
a350: 65 72 73 69 73 74 65 6e 74 20 22 70 6f 77 65 72  ersistent "power
a360: 73 61 66 65 2d 6f 76 65 72 77 72 69 74 65 22 20  safe-overwrite" 
a370: 6f 72 20 22 50 53 4f 57 22 20 73 65 74 74 69 6e  or "PSOW" settin
a380: 67 2e 20 20 54 68 65 20 50 53 4f 57 20 73 65 74  g.  The PSOW set
a390: 74 69 6e 67 0a 2a 2a 20 64 65 74 65 72 6d 69 6e  ting.** determin
a3a0: 65 73 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 49  es the [SQLITE_I
a3b0: 4f 43 41 50 5f 50 4f 57 45 52 53 41 46 45 5f 4f  OCAP_POWERSAFE_O
a3c0: 56 45 52 57 52 49 54 45 5d 20 62 69 74 20 6f 66  VERWRITE] bit of
a3d0: 20 74 68 65 0a 2a 2a 20 78 44 65 76 69 63 65 43   the.** xDeviceC
a3e0: 68 61 72 61 63 74 65 72 69 73 74 69 63 73 20 6d  haracteristics m
a3f0: 65 74 68 6f 64 73 2e 20 54 68 65 20 66 6f 75 72  ethods. The four
a400: 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a  th parameter to.
a410: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  ** [sqlite3_file
a420: 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 66 6f 72 20  _control()] for 
a430: 74 68 69 73 20 6f 70 63 6f 64 65 20 73 68 6f 75  this opcode shou
a440: 6c 64 20 62 65 20 61 20 70 6f 69 6e 74 65 72 20  ld be a pointer 
a450: 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 2e 0a 2a  to an integer..*
a460: 2a 20 54 68 61 74 20 69 6e 74 65 67 65 72 20 69  * That integer i
a470: 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65 20 7a  s 0 to disable z
a480: 65 72 6f 2d 64 61 6d 61 67 65 20 6d 6f 64 65 20  ero-damage mode 
a490: 6f 72 20 31 20 74 6f 20 65 6e 61 62 6c 65 20 7a  or 1 to enable z
a4a0: 65 72 6f 2d 64 61 6d 61 67 65 0a 2a 2a 20 6d 6f  ero-damage.** mo
a4b0: 64 65 2e 20 20 49 66 20 74 68 65 20 69 6e 74 65  de.  If the inte
a4c0: 67 65 72 20 69 73 20 2d 31 2c 20 74 68 65 6e 20  ger is -1, then 
a4d0: 69 74 20 69 73 20 6f 76 65 72 77 72 69 74 74 65  it is overwritte
a4e0: 6e 20 77 69 74 68 20 74 68 65 20 63 75 72 72 65  n with the curre
a4f0: 6e 74 0a 2a 2a 20 7a 65 72 6f 2d 64 61 6d 61 67  nt.** zero-damag
a500: 65 20 6d 6f 64 65 20 73 65 74 74 69 6e 67 2e 0a  e mode setting..
a510: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
a520: 54 45 5f 46 43 4e 54 4c 5f 4f 56 45 52 57 52 49  TE_FCNTL_OVERWRI
a530: 54 45 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51  TE]].** ^The [SQ
a540: 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 45 52 57  LITE_FCNTL_OVERW
a550: 52 49 54 45 5d 20 6f 70 63 6f 64 65 20 69 73 20  RITE] opcode is 
a560: 69 6e 76 6f 6b 65 64 20 62 79 20 53 51 4c 69 74  invoked by SQLit
a570: 65 20 61 66 74 65 72 20 6f 70 65 6e 69 6e 67 0a  e after opening.
a580: 2a 2a 20 61 20 77 72 69 74 65 20 74 72 61 6e 73  ** a write trans
a590: 61 63 74 69 6f 6e 20 74 6f 20 69 6e 64 69 63 61  action to indica
a5a0: 74 65 20 74 68 61 74 2c 20 75 6e 6c 65 73 73 20  te that, unless 
a5b0: 69 74 20 69 73 20 72 6f 6c 6c 65 64 20 62 61 63  it is rolled bac
a5c0: 6b 20 66 6f 72 20 73 6f 6d 65 0a 2a 2a 20 72 65  k for some.** re
a5d0: 61 73 6f 6e 2c 20 74 68 65 20 65 6e 74 69 72 65  ason, the entire
a5e0: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 77   database file w
a5f0: 69 6c 6c 20 62 65 20 6f 76 65 72 77 72 69 74 74  ill be overwritt
a600: 65 6e 20 62 79 20 74 68 65 20 63 75 72 72 65 6e  en by the curren
a610: 74 20 0a 2a 2a 20 74 72 61 6e 73 61 63 74 69 6f  t .** transactio
a620: 6e 2e 20 54 68 69 73 20 69 73 20 75 73 65 64 20  n. This is used 
a630: 62 79 20 56 41 43 55 55 4d 20 6f 70 65 72 61 74  by VACUUM operat
a640: 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  ions..**.** <li>
a650: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56  [[SQLITE_FCNTL_V
a660: 46 53 4e 41 4d 45 5d 5d 0a 2a 2a 20 5e 54 68 65  FSNAME]].** ^The
a670: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56   [SQLITE_FCNTL_V
a680: 46 53 4e 41 4d 45 5d 20 6f 70 63 6f 64 65 20 63  FSNAME] opcode c
a690: 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f 62  an be used to ob
a6a0: 74 61 69 6e 20 74 68 65 20 6e 61 6d 65 73 20 6f  tain the names o
a6b0: 66 0a 2a 2a 20 61 6c 6c 20 5b 56 46 53 65 73 5d  f.** all [VFSes]
a6c0: 20 69 6e 20 74 68 65 20 56 46 53 20 73 74 61 63   in the VFS stac
a6d0: 6b 2e 20 20 54 68 65 20 6e 61 6d 65 73 20 61 72  k.  The names ar
a6e0: 65 20 6f 66 20 61 6c 6c 20 56 46 53 20 73 68 69  e of all VFS shi
a6f0: 6d 73 20 61 6e 64 20 74 68 65 0a 2a 2a 20 66 69  ms and the.** fi
a700: 6e 61 6c 20 62 6f 74 74 6f 6d 2d 6c 65 76 65 6c  nal bottom-level
a710: 20 56 46 53 20 61 72 65 20 77 72 69 74 74 65 6e   VFS are written
a720: 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74   into memory obt
a730: 61 69 6e 65 64 20 66 72 6f 6d 20 0a 2a 2a 20 5b  ained from .** [
a740: 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
a750: 5d 20 61 6e 64 20 74 68 65 20 72 65 73 75 6c 74  ] and the result
a760: 20 69 73 20 73 74 6f 72 65 64 20 69 6e 20 74 68   is stored in th
a770: 65 20 63 68 61 72 2a 20 76 61 72 69 61 62 6c 65  e char* variable
a780: 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 66 6f 75  .** that the fou
a790: 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 6f 66  rth parameter of
a7a0: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63   [sqlite3_file_c
a7b0: 6f 6e 74 72 6f 6c 28 29 5d 20 70 6f 69 6e 74 73  ontrol()] points
a7c0: 20 74 6f 2e 0a 2a 2a 20 54 68 65 20 63 61 6c 6c   to..** The call
a7d0: 65 72 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c  er is responsibl
a7e0: 65 20 66 6f 72 20 66 72 65 65 69 6e 67 20 74 68  e for freeing th
a7f0: 65 20 6d 65 6d 6f 72 79 20 77 68 65 6e 20 64 6f  e memory when do
a800: 6e 65 2e 20 20 41 73 20 77 69 74 68 0a 2a 2a 20  ne.  As with.** 
a810: 61 6c 6c 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c  all file-control
a820: 20 61 63 74 69 6f 6e 73 2c 20 74 68 65 72 65 20   actions, there 
a830: 69 73 20 6e 6f 20 67 75 61 72 61 6e 74 65 65 20  is no guarantee 
a840: 74 68 61 74 20 74 68 69 73 20 77 69 6c 6c 20 61  that this will a
a850: 63 74 75 61 6c 6c 79 0a 2a 2a 20 64 6f 20 61 6e  ctually.** do an
a860: 79 74 68 69 6e 67 2e 20 20 43 61 6c 6c 65 72 73  ything.  Callers
a870: 20 73 68 6f 75 6c 64 20 69 6e 69 74 69 61 6c 69   should initiali
a880: 7a 65 20 74 68 65 20 63 68 61 72 2a 20 76 61 72  ze the char* var
a890: 69 61 62 6c 65 20 74 6f 20 61 20 4e 55 4c 4c 0a  iable to a NULL.
a8a0: 2a 2a 20 70 6f 69 6e 74 65 72 20 69 6e 20 63 61  ** pointer in ca
a8b0: 73 65 20 74 68 69 73 20 66 69 6c 65 2d 63 6f 6e  se this file-con
a8c0: 74 72 6f 6c 20 69 73 20 6e 6f 74 20 69 6d 70 6c  trol is not impl
a8d0: 65 6d 65 6e 74 65 64 2e 20 20 54 68 69 73 20 66  emented.  This f
a8e0: 69 6c 65 2d 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 69  ile-control.** i
a8f0: 73 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 64  s intended for d
a900: 69 61 67 6e 6f 73 74 69 63 20 75 73 65 20 6f 6e  iagnostic use on
a910: 6c 79 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  ly..**.** <li>[[
a920: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53  SQLITE_FCNTL_VFS
a930: 5f 50 4f 49 4e 54 45 52 5d 5d 0a 2a 2a 20 5e 54  _POINTER]].** ^T
a940: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
a950: 5f 56 46 53 5f 50 4f 49 4e 54 45 52 5d 20 6f 70  _VFS_POINTER] op
a960: 63 6f 64 65 20 66 69 6e 64 73 20 61 20 70 6f 69  code finds a poi
a970: 6e 74 65 72 20 74 6f 20 74 68 65 20 74 6f 70 2d  nter to the top-
a980: 6c 65 76 65 6c 0a 2a 2a 20 5b 56 46 53 65 73 5d  level.** [VFSes]
a990: 20 63 75 72 72 65 6e 74 6c 79 20 69 6e 20 75 73   currently in us
a9a0: 65 2e 20 20 5e 28 54 68 65 20 61 72 67 75 6d 65  e.  ^(The argume
a9b0: 6e 74 20 58 20 69 6e 0a 2a 2a 20 73 71 6c 69 74  nt X in.** sqlit
a9c0: 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28  e3_file_control(
a9d0: 64 62 2c 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  db,SQLITE_FCNTL_
a9e0: 56 46 53 5f 50 4f 49 4e 54 45 52 2c 58 29 20 6d  VFS_POINTER,X) m
a9f0: 75 73 74 20 62 65 0a 2a 2a 20 6f 66 20 74 79 70  ust be.** of typ
aa00: 65 20 22 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d  e "[sqlite3_vfs]
aa10: 20 2a 2a 22 2e 20 20 54 68 69 73 20 6f 70 63 6f   **".  This opco
aa20: 64 65 73 20 77 69 6c 6c 20 73 65 74 20 2a 58 0a  des will set *X.
aa30: 2a 2a 20 74 6f 20 61 20 70 6f 69 6e 74 65 72 20  ** to a pointer 
aa40: 74 6f 20 74 68 65 20 74 6f 70 2d 6c 65 76 65 6c  to the top-level
aa50: 20 56 46 53 2e 29 5e 0a 2a 2a 20 5e 57 68 65 6e   VFS.)^.** ^When
aa60: 20 74 68 65 72 65 20 61 72 65 20 6d 75 6c 74 69   there are multi
aa70: 70 6c 65 20 56 46 53 20 73 68 69 6d 73 20 69 6e  ple VFS shims in
aa80: 20 74 68 65 20 73 74 61 63 6b 2c 20 74 68 69 73   the stack, this
aa90: 20 6f 70 63 6f 64 65 20 66 69 6e 64 73 20 74 68   opcode finds th
aaa0: 65 0a 2a 2a 20 75 70 70 65 72 2d 6d 6f 73 74 20  e.** upper-most 
aab0: 73 68 69 6d 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a  shim only..**.**
aac0: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
aad0: 4e 54 4c 5f 50 52 41 47 4d 41 5d 5d 0a 2a 2a 20  NTL_PRAGMA]].** 
aae0: 5e 57 68 65 6e 65 76 65 72 20 61 20 5b 50 52 41  ^Whenever a [PRA
aaf0: 47 4d 41 5d 20 73 74 61 74 65 6d 65 6e 74 20 69  GMA] statement i
ab00: 73 20 70 61 72 73 65 64 2c 20 61 6e 20 5b 53 51  s parsed, an [SQ
ab10: 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d  LITE_FCNTL_PRAGM
ab20: 41 5d 20 0a 2a 2a 20 66 69 6c 65 20 63 6f 6e 74  A] .** file cont
ab30: 72 6f 6c 20 69 73 20 73 65 6e 74 20 74 6f 20 74  rol is sent to t
ab40: 68 65 20 6f 70 65 6e 20 5b 73 71 6c 69 74 65 33  he open [sqlite3
ab50: 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 63 6f  _file] object co
ab60: 72 72 65 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20 74  rresponding.** t
ab70: 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  o the database f
ab80: 69 6c 65 20 74 6f 20 77 68 69 63 68 20 74 68 65  ile to which the
ab90: 20 70 72 61 67 6d 61 20 73 74 61 74 65 6d 65 6e   pragma statemen
aba0: 74 20 72 65 66 65 72 73 2e 20 5e 54 68 65 20 61  t refers. ^The a
abb0: 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 74 68  rgument.** to th
abc0: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
abd0: 50 52 41 47 4d 41 5d 20 66 69 6c 65 20 63 6f 6e  PRAGMA] file con
abe0: 74 72 6f 6c 20 69 73 20 61 6e 20 61 72 72 61 79  trol is an array
abf0: 20 6f 66 0a 2a 2a 20 70 6f 69 6e 74 65 72 73 20   of.** pointers 
ac00: 74 6f 20 73 74 72 69 6e 67 73 20 28 63 68 61 72  to strings (char
ac10: 2a 2a 29 20 69 6e 20 77 68 69 63 68 20 74 68 65  **) in which the
ac20: 20 73 65 63 6f 6e 64 20 65 6c 65 6d 65 6e 74 20   second element 
ac30: 6f 66 20 74 68 65 20 61 72 72 61 79 0a 2a 2a 20  of the array.** 
ac40: 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  is the name of t
ac50: 68 65 20 70 72 61 67 6d 61 20 61 6e 64 20 74 68  he pragma and th
ac60: 65 20 74 68 69 72 64 20 65 6c 65 6d 65 6e 74 20  e third element 
ac70: 69 73 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20  is the argument 
ac80: 74 6f 20 74 68 65 0a 2a 2a 20 70 72 61 67 6d 61  to the.** pragma
ac90: 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 65 20   or NULL if the 
aca0: 70 72 61 67 6d 61 20 68 61 73 20 6e 6f 20 61 72  pragma has no ar
acb0: 67 75 6d 65 6e 74 2e 20 20 5e 54 68 65 20 68 61  gument.  ^The ha
acc0: 6e 64 6c 65 72 20 66 6f 72 20 61 6e 0a 2a 2a 20  ndler for an.** 
acd0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52  [SQLITE_FCNTL_PR
ace0: 41 47 4d 41 5d 20 66 69 6c 65 20 63 6f 6e 74 72  AGMA] file contr
acf0: 6f 6c 20 63 61 6e 20 6f 70 74 69 6f 6e 61 6c 6c  ol can optionall
ad00: 79 20 6d 61 6b 65 20 74 68 65 20 66 69 72 73 74  y make the first
ad10: 20 65 6c 65 6d 65 6e 74 0a 2a 2a 20 6f 66 20 74   element.** of t
ad20: 68 65 20 63 68 61 72 2a 2a 20 61 72 67 75 6d 65  he char** argume
ad30: 6e 74 20 70 6f 69 6e 74 20 74 6f 20 61 20 73 74  nt point to a st
ad40: 72 69 6e 67 20 6f 62 74 61 69 6e 65 64 20 66 72  ring obtained fr
ad50: 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 70 72 69  om [sqlite3_mpri
ad60: 6e 74 66 28 29 5d 0a 2a 2a 20 6f 72 20 74 68 65  ntf()].** or the
ad70: 20 65 71 75 69 76 61 6c 65 6e 74 20 61 6e 64 20   equivalent and 
ad80: 74 68 61 74 20 73 74 72 69 6e 67 20 77 69 6c 6c  that string will
ad90: 20 62 65 63 6f 6d 65 20 74 68 65 20 72 65 73 75   become the resu
ada0: 6c 74 20 6f 66 20 74 68 65 20 70 72 61 67 6d 61  lt of the pragma
adb0: 20 6f 72 0a 2a 2a 20 74 68 65 20 65 72 72 6f 72   or.** the error
adc0: 20 6d 65 73 73 61 67 65 20 69 66 20 74 68 65 20   message if the 
add0: 70 72 61 67 6d 61 20 66 61 69 6c 73 2e 20 5e 49  pragma fails. ^I
ade0: 66 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45  f the.** [SQLITE
adf0: 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 66  _FCNTL_PRAGMA] f
ae00: 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 72 65 74 75  ile control retu
ae10: 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4e 4f 54 46  rns [SQLITE_NOTF
ae20: 4f 55 4e 44 5d 2c 20 74 68 65 6e 20 6e 6f 72 6d  OUND], then norm
ae30: 61 6c 20 0a 2a 2a 20 5b 50 52 41 47 4d 41 5d 20  al .** [PRAGMA] 
ae40: 70 72 6f 63 65 73 73 69 6e 67 20 63 6f 6e 74 69  processing conti
ae50: 6e 75 65 73 2e 20 20 5e 49 66 20 74 68 65 20 5b  nues.  ^If the [
ae60: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41  SQLITE_FCNTL_PRA
ae70: 47 4d 41 5d 0a 2a 2a 20 66 69 6c 65 20 63 6f 6e  GMA].** file con
ae80: 74 72 6f 6c 20 72 65 74 75 72 6e 73 20 5b 53 51  trol returns [SQ
ae90: 4c 49 54 45 5f 4f 4b 5d 2c 20 74 68 65 6e 20 74  LITE_OK], then t
aea0: 68 65 20 70 61 72 73 65 72 20 61 73 73 75 6d 65  he parser assume
aeb0: 73 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 56 46  s that the.** VF
aec0: 53 20 68 61 73 20 68 61 6e 64 6c 65 64 20 74 68  S has handled th
aed0: 65 20 50 52 41 47 4d 41 20 69 74 73 65 6c 66 20  e PRAGMA itself 
aee0: 61 6e 64 20 74 68 65 20 70 61 72 73 65 72 20 67  and the parser g
aef0: 65 6e 65 72 61 74 65 73 20 61 20 6e 6f 2d 6f 70  enerates a no-op
af00: 0a 2a 2a 20 70 72 65 70 61 72 65 64 20 73 74 61  .** prepared sta
af10: 74 65 6d 65 6e 74 20 69 66 20 72 65 73 75 6c 74  tement if result
af20: 20 73 74 72 69 6e 67 20 69 73 20 4e 55 4c 4c 2c   string is NULL,
af30: 20 6f 72 20 74 68 61 74 20 72 65 74 75 72 6e 73   or that returns
af40: 20 61 20 63 6f 70 79 0a 2a 2a 20 6f 66 20 74 68   a copy.** of th
af50: 65 20 72 65 73 75 6c 74 20 73 74 72 69 6e 67 20  e result string 
af60: 69 66 20 74 68 65 20 73 74 72 69 6e 67 20 69 73  if the string is
af70: 20 6e 6f 6e 2d 4e 55 4c 4c 2e 0a 2a 2a 20 5e 49   non-NULL..** ^I
af80: 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 46 43  f the [SQLITE_FC
af90: 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65  NTL_PRAGMA] file
afa0: 20 63 6f 6e 74 72 6f 6c 20 72 65 74 75 72 6e 73   control returns
afb0: 0a 2a 2a 20 61 6e 79 20 72 65 73 75 6c 74 20 63  .** any result c
afc0: 6f 64 65 20 6f 74 68 65 72 20 74 68 61 6e 20 5b  ode other than [
afd0: 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20 5b 53  SQLITE_OK] or [S
afe0: 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d 2c  QLITE_NOTFOUND],
aff0: 20 74 68 61 74 20 6d 65 61 6e 73 0a 2a 2a 20 74   that means.** t
b000: 68 61 74 20 74 68 65 20 56 46 53 20 65 6e 63 6f  hat the VFS enco
b010: 75 6e 74 65 72 65 64 20 61 6e 20 65 72 72 6f 72  untered an error
b020: 20 77 68 69 6c 65 20 68 61 6e 64 6c 69 6e 67 20   while handling 
b030: 74 68 65 20 5b 50 52 41 47 4d 41 5d 20 61 6e 64  the [PRAGMA] and
b040: 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 69 6c 61 74   the.** compilat
b050: 69 6f 6e 20 6f 66 20 74 68 65 20 50 52 41 47 4d  ion of the PRAGM
b060: 41 20 66 61 69 6c 73 20 77 69 74 68 20 61 6e 20  A fails with an 
b070: 65 72 72 6f 72 2e 20 20 5e 54 68 65 20 5b 53 51  error.  ^The [SQ
b080: 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d  LITE_FCNTL_PRAGM
b090: 41 5d 0a 2a 2a 20 66 69 6c 65 20 63 6f 6e 74 72  A].** file contr
b0a0: 6f 6c 20 6f 63 63 75 72 73 20 61 74 20 74 68 65  ol occurs at the
b0b0: 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 70 72   beginning of pr
b0c0: 61 67 6d 61 20 73 74 61 74 65 6d 65 6e 74 20 61  agma statement a
b0d0: 6e 61 6c 79 73 69 73 20 61 6e 64 20 73 6f 0a 2a  nalysis and so.*
b0e0: 2a 20 69 74 20 69 73 20 61 62 6c 65 20 74 6f 20  * it is able to 
b0f0: 6f 76 65 72 72 69 64 65 20 62 75 69 6c 74 2d 69  override built-i
b100: 6e 20 5b 50 52 41 47 4d 41 5d 20 73 74 61 74 65  n [PRAGMA] state
b110: 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69  ments..**.** <li
b120: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
b130: 42 55 53 59 48 41 4e 44 4c 45 52 5d 5d 0a 2a 2a  BUSYHANDLER]].**
b140: 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43   ^The [SQLITE_FC
b150: 4e 54 4c 5f 42 55 53 59 48 41 4e 44 4c 45 52 5d  NTL_BUSYHANDLER]
b160: 0a 2a 2a 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c  .** file-control
b170: 20 6d 61 79 20 62 65 20 69 6e 76 6f 6b 65 64 20   may be invoked 
b180: 62 79 20 53 51 4c 69 74 65 20 6f 6e 20 74 68 65  by SQLite on the
b190: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 68   database file h
b1a0: 61 6e 64 6c 65 0a 2a 2a 20 73 68 6f 72 74 6c 79  andle.** shortly
b1b0: 20 61 66 74 65 72 20 69 74 20 69 73 20 6f 70 65   after it is ope
b1c0: 6e 65 64 20 69 6e 20 6f 72 64 65 72 20 74 6f 20  ned in order to 
b1d0: 70 72 6f 76 69 64 65 20 61 20 63 75 73 74 6f 6d  provide a custom
b1e0: 20 56 46 53 20 77 69 74 68 20 61 63 63 65 73 73   VFS with access
b1f0: 0a 2a 2a 20 74 6f 20 74 68 65 20 63 6f 6e 6e 65  .** to the conne
b200: 63 74 69 6f 6e 73 20 62 75 73 79 2d 68 61 6e 64  ctions busy-hand
b210: 6c 65 72 20 63 61 6c 6c 62 61 63 6b 2e 20 54 68  ler callback. Th
b220: 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6f 66  e argument is of
b230: 20 74 79 70 65 20 28 76 6f 69 64 20 2a 2a 29 0a   type (void **).
b240: 2a 2a 20 2d 20 61 6e 20 61 72 72 61 79 20 6f 66  ** - an array of
b250: 20 74 77 6f 20 28 76 6f 69 64 20 2a 29 20 76 61   two (void *) va
b260: 6c 75 65 73 2e 20 54 68 65 20 66 69 72 73 74 20  lues. The first 
b270: 28 76 6f 69 64 20 2a 29 20 61 63 74 75 61 6c 6c  (void *) actuall
b280: 79 20 70 6f 69 6e 74 73 0a 2a 2a 20 74 6f 20 61  y points.** to a
b290: 20 66 75 6e 63 74 69 6f 6e 20 6f 66 20 74 79 70   function of typ
b2a0: 65 20 28 69 6e 74 20 28 2a 29 28 76 6f 69 64 20  e (int (*)(void 
b2b0: 2a 29 29 2e 20 49 6e 20 6f 72 64 65 72 20 74 6f  *)). In order to
b2c0: 20 69 6e 76 6f 6b 65 20 74 68 65 20 63 6f 6e 6e   invoke the conn
b2d0: 65 63 74 69 6f 6e 73 0a 2a 2a 20 62 75 73 79 2d  ections.** busy-
b2e0: 68 61 6e 64 6c 65 72 2c 20 74 68 69 73 20 66 75  handler, this fu
b2f0: 6e 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20 62 65  nction should be
b300: 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 74 68   invoked with th
b310: 65 20 73 65 63 6f 6e 64 20 28 76 6f 69 64 20 2a  e second (void *
b320: 29 20 69 6e 0a 2a 2a 20 74 68 65 20 61 72 72 61  ) in.** the arra
b330: 79 20 61 73 20 74 68 65 20 6f 6e 6c 79 20 61 72  y as the only ar
b340: 67 75 6d 65 6e 74 2e 20 49 66 20 69 74 20 72 65  gument. If it re
b350: 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20  turns non-zero, 
b360: 74 68 65 6e 20 74 68 65 20 6f 70 65 72 61 74 69  then the operati
b370: 6f 6e 0a 2a 2a 20 73 68 6f 75 6c 64 20 62 65 20  on.** should be 
b380: 72 65 74 72 69 65 64 2e 20 49 66 20 69 74 20 72  retried. If it r
b390: 65 74 75 72 6e 73 20 7a 65 72 6f 2c 20 74 68 65  eturns zero, the
b3a0: 20 63 75 73 74 6f 6d 20 56 46 53 20 73 68 6f 75   custom VFS shou
b3b0: 6c 64 20 61 62 61 6e 64 6f 6e 20 74 68 65 0a 2a  ld abandon the.*
b3c0: 2a 20 63 75 72 72 65 6e 74 20 6f 70 65 72 61 74  * current operat
b3d0: 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  ion..**.** <li>[
b3e0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 45  [SQLITE_FCNTL_TE
b3f0: 4d 50 46 49 4c 45 4e 41 4d 45 5d 5d 0a 2a 2a 20  MPFILENAME]].** 
b400: 5e 41 70 70 6c 69 63 61 74 69 6f 6e 20 63 61 6e  ^Application can
b410: 20 69 6e 76 6f 6b 65 20 74 68 65 20 5b 53 51 4c   invoke the [SQL
b420: 49 54 45 5f 46 43 4e 54 4c 5f 54 45 4d 50 46 49  ITE_FCNTL_TEMPFI
b430: 4c 45 4e 41 4d 45 5d 20 66 69 6c 65 2d 63 6f 6e  LENAME] file-con
b440: 74 72 6f 6c 0a 2a 2a 20 74 6f 20 68 61 76 65 20  trol.** to have 
b450: 53 51 4c 69 74 65 20 67 65 6e 65 72 61 74 65 20  SQLite generate 
b460: 61 0a 2a 2a 20 74 65 6d 70 6f 72 61 72 79 20 66  a.** temporary f
b470: 69 6c 65 6e 61 6d 65 20 75 73 69 6e 67 20 74 68  ilename using th
b480: 65 20 73 61 6d 65 20 61 6c 67 6f 72 69 74 68 6d  e same algorithm
b490: 20 74 68 61 74 20 69 73 20 66 6f 6c 6c 6f 77 65   that is followe
b4a0: 64 20 74 6f 20 67 65 6e 65 72 61 74 65 0a 2a 2a  d to generate.**
b4b0: 20 74 65 6d 70 6f 72 61 72 79 20 66 69 6c 65 6e   temporary filen
b4c0: 61 6d 65 73 20 66 6f 72 20 54 45 4d 50 20 74 61  ames for TEMP ta
b4d0: 62 6c 65 73 20 61 6e 64 20 6f 74 68 65 72 20 69  bles and other i
b4e0: 6e 74 65 72 6e 61 6c 20 75 73 65 73 2e 20 20 54  nternal uses.  T
b4f0: 68 65 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 73  he.** argument s
b500: 68 6f 75 6c 64 20 62 65 20 61 20 63 68 61 72 2a  hould be a char*
b510: 2a 20 77 68 69 63 68 20 77 69 6c 6c 20 62 65 20  * which will be 
b520: 66 69 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20  filled with the 
b530: 66 69 6c 65 6e 61 6d 65 0a 2a 2a 20 77 72 69 74  filename.** writ
b540: 74 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20  ten into memory 
b550: 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73  obtained from [s
b560: 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
b570: 2e 20 20 54 68 65 20 63 61 6c 6c 65 72 20 73 68  .  The caller sh
b580: 6f 75 6c 64 0a 2a 2a 20 69 6e 76 6f 6b 65 20 5b  ould.** invoke [
b590: 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20  sqlite3_free()] 
b5a0: 6f 6e 20 74 68 65 20 72 65 73 75 6c 74 20 74 6f  on the result to
b5b0: 20 61 76 6f 69 64 20 61 20 6d 65 6d 6f 72 79 20   avoid a memory 
b5c0: 6c 65 61 6b 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  leak..**.** <li>
b5d0: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4d  [[SQLITE_FCNTL_M
b5e0: 4d 41 50 5f 53 49 5a 45 5d 5d 0a 2a 2a 20 54 68  MAP_SIZE]].** Th
b5f0: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
b600: 4d 4d 41 50 5f 53 49 5a 45 5d 20 66 69 6c 65 20  MMAP_SIZE] file 
b610: 63 6f 6e 74 72 6f 6c 20 69 73 20 75 73 65 64 20  control is used 
b620: 74 6f 20 71 75 65 72 79 20 6f 72 20 73 65 74 20  to query or set 
b630: 74 68 65 0a 2a 2a 20 6d 61 78 69 6d 75 6d 20 6e  the.** maximum n
b640: 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 74  umber of bytes t
b650: 68 61 74 20 77 69 6c 6c 20 62 65 20 75 73 65 64  hat will be used
b660: 20 66 6f 72 20 6d 65 6d 6f 72 79 2d 6d 61 70 70   for memory-mapp
b670: 65 64 20 49 2f 4f 2e 0a 2a 2a 20 54 68 65 20 61  ed I/O..** The a
b680: 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69  rgument is a poi
b690: 6e 74 65 72 20 74 6f 20 61 20 76 61 6c 75 65 20  nter to a value 
b6a0: 6f 66 20 74 79 70 65 20 73 71 6c 69 74 65 33 5f  of type sqlite3_
b6b0: 69 6e 74 36 34 20 74 68 61 74 0a 2a 2a 20 69 73  int64 that.** is
b6c0: 20 61 6e 20 61 64 76 69 73 6f 72 79 20 6d 61 78   an advisory max
b6d0: 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 62  imum number of b
b6e0: 79 74 65 73 20 69 6e 20 74 68 65 20 66 69 6c 65  ytes in the file
b6f0: 20 74 6f 20 6d 65 6d 6f 72 79 20 6d 61 70 2e 20   to memory map. 
b700: 20 54 68 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 20   The.** pointer 
b710: 69 73 20 6f 76 65 72 77 72 69 74 74 65 6e 20 77  is overwritten w
b720: 69 74 68 20 74 68 65 20 6f 6c 64 20 76 61 6c 75  ith the old valu
b730: 65 2e 20 20 54 68 65 20 6c 69 6d 69 74 20 69 73  e.  The limit is
b740: 20 6e 6f 74 20 63 68 61 6e 67 65 64 20 69 66 0a   not changed if.
b750: 2a 2a 20 74 68 65 20 76 61 6c 75 65 20 6f 72 69  ** the value ori
b760: 67 69 6e 61 6c 6c 79 20 70 6f 69 6e 74 65 64 20  ginally pointed 
b770: 74 6f 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20  to is negative, 
b780: 61 6e 64 20 73 6f 20 74 68 65 20 63 75 72 72 65  and so the curre
b790: 6e 74 20 6c 69 6d 69 74 20 0a 2a 2a 20 63 61 6e  nt limit .** can
b7a0: 20 62 65 20 71 75 65 72 69 65 64 20 62 79 20 70   be queried by p
b7b0: 61 73 73 69 6e 67 20 69 6e 20 61 20 70 6f 69 6e  assing in a poin
b7c0: 74 65 72 20 74 6f 20 61 20 6e 65 67 61 74 69 76  ter to a negativ
b7d0: 65 20 6e 75 6d 62 65 72 2e 20 20 54 68 69 73 0a  e number.  This.
b7e0: 2a 2a 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20  ** file-control 
b7f0: 69 73 20 75 73 65 64 20 69 6e 74 65 72 6e 61 6c  is used internal
b800: 6c 79 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20  ly to implement 
b810: 5b 50 52 41 47 4d 41 20 6d 6d 61 70 5f 73 69 7a  [PRAGMA mmap_siz
b820: 65 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  e]..**.** <li>[[
b830: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 52 41  SQLITE_FCNTL_TRA
b840: 43 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  CE]].** The [SQL
b850: 49 54 45 5f 46 43 4e 54 4c 5f 54 52 41 43 45 5d  ITE_FCNTL_TRACE]
b860: 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 70 72   file control pr
b870: 6f 76 69 64 65 73 20 61 64 76 69 73 6f 72 79 20  ovides advisory 
b880: 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 74  information.** t
b890: 6f 20 74 68 65 20 56 46 53 20 61 62 6f 75 74 20  o the VFS about 
b8a0: 77 68 61 74 20 74 68 65 20 68 69 67 68 65 72 20  what the higher 
b8b0: 6c 61 79 65 72 73 20 6f 66 20 74 68 65 20 53 51  layers of the SQ
b8c0: 4c 69 74 65 20 73 74 61 63 6b 20 61 72 65 20 64  Lite stack are d
b8d0: 6f 69 6e 67 2e 0a 2a 2a 20 54 68 69 73 20 66 69  oing..** This fi
b8e0: 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73 20 75 73  le control is us
b8f0: 65 64 20 62 79 20 73 6f 6d 65 20 56 46 53 20 61  ed by some VFS a
b900: 63 74 69 76 69 74 79 20 74 72 61 63 69 6e 67 20  ctivity tracing 
b910: 5b 73 68 69 6d 73 5d 2e 0a 2a 2a 20 54 68 65 20  [shims]..** The 
b920: 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 7a 65  argument is a ze
b930: 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74  ro-terminated st
b940: 72 69 6e 67 2e 20 20 48 69 67 68 65 72 20 6c 61  ring.  Higher la
b950: 79 65 72 73 20 69 6e 20 74 68 65 0a 2a 2a 20 53  yers in the.** S
b960: 51 4c 69 74 65 20 73 74 61 63 6b 20 6d 61 79 20  QLite stack may 
b970: 67 65 6e 65 72 61 74 65 20 69 6e 73 74 61 6e 63  generate instanc
b980: 65 73 20 6f 66 20 74 68 69 73 20 66 69 6c 65 20  es of this file 
b990: 63 6f 6e 74 72 6f 6c 20 69 66 0a 2a 2a 20 74 68  control if.** th
b9a0: 65 20 5b 53 51 4c 49 54 45 5f 55 53 45 5f 46 43  e [SQLITE_USE_FC
b9b0: 4e 54 4c 5f 54 52 41 43 45 5d 20 63 6f 6d 70 69  NTL_TRACE] compi
b9c0: 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 69  le-time option i
b9d0: 73 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a  s enabled..**.**
b9e0: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
b9f0: 4e 54 4c 5f 48 41 53 5f 4d 4f 56 45 44 5d 5d 0a  NTL_HAS_MOVED]].
ba00: 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  ** The [SQLITE_F
ba10: 43 4e 54 4c 5f 48 41 53 5f 4d 4f 56 45 44 5d 20  CNTL_HAS_MOVED] 
ba20: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 6e 74  file control int
ba30: 65 72 70 72 65 74 73 20 69 74 73 20 61 72 67 75  erprets its argu
ba40: 6d 65 6e 74 20 61 73 20 61 0a 2a 2a 20 70 6f 69  ment as a.** poi
ba50: 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67  nter to an integ
ba60: 65 72 20 61 6e 64 20 69 74 20 77 72 69 74 65 73  er and it writes
ba70: 20 61 20 62 6f 6f 6c 65 61 6e 20 69 6e 74 6f 20   a boolean into 
ba80: 74 68 61 74 20 69 6e 74 65 67 65 72 20 64 65 70  that integer dep
ba90: 65 6e 64 69 6e 67 0a 2a 2a 20 6f 6e 20 77 68 65  ending.** on whe
baa0: 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20  ther or not the 
bab0: 66 69 6c 65 20 68 61 73 20 62 65 65 6e 20 72 65  file has been re
bac0: 6e 61 6d 65 64 2c 20 6d 6f 76 65 64 2c 20 6f 72  named, moved, or
bad0: 20 64 65 6c 65 74 65 64 20 73 69 6e 63 65 20 69   deleted since i
bae0: 74 0a 2a 2a 20 77 61 73 20 66 69 72 73 74 20 6f  t.** was first o
baf0: 70 65 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69  pened..**.** <li
bb00: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
bb10: 57 49 4e 33 32 5f 47 45 54 5f 48 41 4e 44 4c 45  WIN32_GET_HANDLE
bb20: 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54  ]].** The [SQLIT
bb30: 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 47 45  E_FCNTL_WIN32_GE
bb40: 54 5f 48 41 4e 44 4c 45 5d 20 6f 70 63 6f 64 65  T_HANDLE] opcode
bb50: 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
bb60: 6f 62 74 61 69 6e 20 74 68 65 0a 2a 2a 20 75 6e  obtain the.** un
bb70: 64 65 72 6c 79 69 6e 67 20 6e 61 74 69 76 65 20  derlying native 
bb80: 66 69 6c 65 20 68 61 6e 64 6c 65 20 61 73 73 6f  file handle asso
bb90: 63 69 61 74 65 64 20 77 69 74 68 20 61 20 66 69  ciated with a fi
bba0: 6c 65 20 68 61 6e 64 6c 65 2e 20 20 54 68 69 73  le handle.  This
bbb0: 20 66 69 6c 65 0a 2a 2a 20 63 6f 6e 74 72 6f 6c   file.** control
bbc0: 20 69 6e 74 65 72 70 72 65 74 73 20 69 74 73 20   interprets its 
bbd0: 61 72 67 75 6d 65 6e 74 20 61 73 20 61 20 70 6f  argument as a po
bbe0: 69 6e 74 65 72 20 74 6f 20 61 20 6e 61 74 69 76  inter to a nativ
bbf0: 65 20 66 69 6c 65 20 68 61 6e 64 6c 65 20 61 6e  e file handle an
bc00: 64 0a 2a 2a 20 77 72 69 74 65 73 20 74 68 65 20  d.** writes the 
bc10: 72 65 73 75 6c 74 69 6e 67 20 76 61 6c 75 65 20  resulting value 
bc20: 74 68 65 72 65 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69  there..**.** <li
bc30: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
bc40: 57 49 4e 33 32 5f 53 45 54 5f 48 41 4e 44 4c 45  WIN32_SET_HANDLE
bc50: 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54  ]].** The [SQLIT
bc60: 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 53 45  E_FCNTL_WIN32_SE
bc70: 54 5f 48 41 4e 44 4c 45 5d 20 6f 70 63 6f 64 65  T_HANDLE] opcode
bc80: 20 69 73 20 75 73 65 64 20 66 6f 72 20 64 65 62   is used for deb
bc90: 75 67 67 69 6e 67 2e 20 20 54 68 69 73 0a 2a 2a  ugging.  This.**
bca0: 20 6f 70 63 6f 64 65 20 63 61 75 73 65 73 20 74   opcode causes t
bcb0: 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20  he xFileControl 
bcc0: 6d 65 74 68 6f 64 20 74 6f 20 73 77 61 70 20 74  method to swap t
bcd0: 68 65 20 66 69 6c 65 20 68 61 6e 64 6c 65 20 77  he file handle w
bce0: 69 74 68 20 74 68 65 20 6f 6e 65 0a 2a 2a 20 70  ith the one.** p
bcf0: 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 74 68 65  ointed to by the
bd00: 20 70 41 72 67 20 61 72 67 75 6d 65 6e 74 2e 20   pArg argument. 
bd10: 20 54 68 69 73 20 63 61 70 61 62 69 6c 69 74 79   This capability
bd20: 20 69 73 20 75 73 65 64 20 64 75 72 69 6e 67 20   is used during 
bd30: 74 65 73 74 69 6e 67 0a 2a 2a 20 61 6e 64 20 6f  testing.** and o
bd40: 6e 6c 79 20 6e 65 65 64 73 20 74 6f 20 62 65 20  nly needs to be 
bd50: 73 75 70 70 6f 72 74 65 64 20 77 68 65 6e 20 53  supported when S
bd60: 51 4c 49 54 45 5f 54 45 53 54 20 69 73 20 64 65  QLITE_TEST is de
bd70: 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69  fined..**.** <li
bd80: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
bd90: 57 41 4c 5f 42 4c 4f 43 4b 5d 5d 0a 2a 2a 20 54  WAL_BLOCK]].** T
bda0: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
bdb0: 5f 57 41 4c 5f 42 4c 4f 43 4b 5d 20 69 73 20 61  _WAL_BLOCK] is a
bdc0: 20 73 69 67 6e 61 6c 20 74 6f 20 74 68 65 20 56   signal to the V
bdd0: 46 53 20 6c 61 79 65 72 20 74 68 61 74 20 69 74  FS layer that it
bde0: 20 6d 69 67 68 74 0a 2a 2a 20 62 65 20 61 64 76   might.** be adv
bdf0: 61 6e 74 61 67 65 6f 75 73 20 74 6f 20 62 6c 6f  antageous to blo
be00: 63 6b 20 6f 6e 20 74 68 65 20 6e 65 78 74 20 57  ck on the next W
be10: 41 4c 20 6c 6f 63 6b 20 69 66 20 74 68 65 20 6c  AL lock if the l
be20: 6f 63 6b 20 69 73 20 6e 6f 74 20 69 6d 6d 65 64  ock is not immed
be30: 69 61 74 65 6c 79 0a 2a 2a 20 61 76 61 69 6c 61  iately.** availa
be40: 62 6c 65 2e 20 20 54 68 65 20 57 41 4c 20 73 75  ble.  The WAL su
be50: 62 73 79 73 74 65 6d 20 69 73 73 75 65 73 20 74  bsystem issues t
be60: 68 69 73 20 73 69 67 6e 61 6c 20 64 75 72 69 6e  his signal durin
be70: 67 20 72 61 72 65 0a 2a 2a 20 63 69 72 63 75 6d  g rare.** circum
be80: 73 74 61 6e 63 65 73 20 69 6e 20 6f 72 64 65 72  stances in order
be90: 20 74 6f 20 66 69 78 20 61 20 70 72 6f 62 6c 65   to fix a proble
bea0: 6d 20 77 69 74 68 20 70 72 69 6f 72 69 74 79 20  m with priority 
beb0: 69 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 20 41 70  inversion..** Ap
bec0: 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c  plications shoul
bed0: 64 20 3c 65 6d 3e 6e 6f 74 3c 2f 65 6d 3e 20 75  d <em>not</em> u
bee0: 73 65 20 74 68 69 73 20 66 69 6c 65 2d 63 6f 6e  se this file-con
bef0: 74 72 6f 6c 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  trol..**.** <li>
bf00: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 5a  [[SQLITE_FCNTL_Z
bf10: 49 50 56 46 53 5d 5d 0a 2a 2a 20 54 68 65 20 5b  IPVFS]].** The [
bf20: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 5a 49 50  SQLITE_FCNTL_ZIP
bf30: 56 46 53 5d 20 6f 70 63 6f 64 65 20 69 73 20 69  VFS] opcode is i
bf40: 6d 70 6c 65 6d 65 6e 74 65 64 20 62 79 20 7a 69  mplemented by zi
bf50: 70 76 66 73 20 6f 6e 6c 79 2e 20 41 6c 6c 20 6f  pvfs only. All o
bf60: 74 68 65 72 0a 2a 2a 20 56 46 53 20 73 68 6f 75  ther.** VFS shou
bf70: 6c 64 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45  ld return SQLITE
bf80: 5f 4e 4f 54 46 4f 55 4e 44 20 66 6f 72 20 74 68  _NOTFOUND for th
bf90: 69 73 20 6f 70 63 6f 64 65 2e 0a 2a 2a 0a 2a 2a  is opcode..**.**
bfa0: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
bfb0: 4e 54 4c 5f 52 42 55 5d 5d 0a 2a 2a 20 54 68 65  NTL_RBU]].** The
bfc0: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 52   [SQLITE_FCNTL_R
bfd0: 42 55 5d 20 6f 70 63 6f 64 65 20 69 73 20 69 6d  BU] opcode is im
bfe0: 70 6c 65 6d 65 6e 74 65 64 20 62 79 20 74 68 65  plemented by the
bff0: 20 73 70 65 63 69 61 6c 20 56 46 53 20 75 73 65   special VFS use
c000: 64 20 62 79 0a 2a 2a 20 74 68 65 20 52 42 55 20  d by.** the RBU 
c010: 65 78 74 65 6e 73 69 6f 6e 20 6f 6e 6c 79 2e 20  extension only. 
c020: 20 41 6c 6c 20 6f 74 68 65 72 20 56 46 53 20 73   All other VFS s
c030: 68 6f 75 6c 64 20 72 65 74 75 72 6e 20 53 51 4c  hould return SQL
c040: 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 20 66 6f 72  ITE_NOTFOUND for
c050: 0a 2a 2a 20 74 68 69 73 20 6f 70 63 6f 64 65 2e  .** this opcode.
c060: 20 20 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2f 0a 23    .** </ul>.*/.#
c070: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
c080: 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 20 20 20  NTL_LOCKSTATE   
c090: 20 20 20 20 20 20 20 20 20 20 20 20 31 0a 23 64              1.#d
c0a0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
c0b0: 54 4c 5f 47 45 54 5f 4c 4f 43 4b 50 52 4f 58 59  TL_GET_LOCKPROXY
c0c0: 46 49 4c 45 20 20 20 20 20 20 20 32 0a 23 64 65  FILE       2.#de
c0d0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
c0e0: 4c 5f 53 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46  L_SET_LOCKPROXYF
c0f0: 49 4c 45 20 20 20 20 20 20 20 33 0a 23 64 65 66  ILE       3.#def
c100: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
c110: 5f 4c 41 53 54 5f 45 52 52 4e 4f 20 20 20 20 20  _LAST_ERRNO     
c120: 20 20 20 20 20 20 20 20 20 34 0a 23 64 65 66 69           4.#defi
c130: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
c140: 53 49 5a 45 5f 48 49 4e 54 20 20 20 20 20 20 20  SIZE_HINT       
c150: 20 20 20 20 20 20 20 20 35 0a 23 64 65 66 69 6e          5.#defin
c160: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43  e SQLITE_FCNTL_C
c170: 48 55 4e 4b 5f 53 49 5a 45 20 20 20 20 20 20 20  HUNK_SIZE       
c180: 20 20 20 20 20 20 20 36 0a 23 64 65 66 69 6e 65         6.#define
c190: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49   SQLITE_FCNTL_FI
c1a0: 4c 45 5f 50 4f 49 4e 54 45 52 20 20 20 20 20 20  LE_POINTER      
c1b0: 20 20 20 20 20 20 37 0a 23 64 65 66 69 6e 65 20        7.#define 
c1c0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e  SQLITE_FCNTL_SYN
c1d0: 43 5f 4f 4d 49 54 54 45 44 20 20 20 20 20 20 20  C_OMITTED       
c1e0: 20 20 20 20 20 38 0a 23 64 65 66 69 6e 65 20 53       8.#define S
c1f0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33  QLITE_FCNTL_WIN3
c200: 32 5f 41 56 5f 52 45 54 52 59 20 20 20 20 20 20  2_AV_RETRY      
c210: 20 20 20 20 39 0a 23 64 65 66 69 6e 65 20 53 51      9.#define SQ
c220: 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 45 52 53 49  LITE_FCNTL_PERSI
c230: 53 54 5f 57 41 4c 20 20 20 20 20 20 20 20 20 20  ST_WAL          
c240: 20 20 31 30 0a 23 64 65 66 69 6e 65 20 53 51 4c    10.#define SQL
c250: 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 45 52 57 52  ITE_FCNTL_OVERWR
c260: 49 54 45 20 20 20 20 20 20 20 20 20 20 20 20 20  ITE             
c270: 20 31 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   11.#define SQLI
c280: 54 45 5f 46 43 4e 54 4c 5f 56 46 53 4e 41 4d 45  TE_FCNTL_VFSNAME
c290: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
c2a0: 31 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  12.#define SQLIT
c2b0: 45 5f 46 43 4e 54 4c 5f 50 4f 57 45 52 53 41 46  E_FCNTL_POWERSAF
c2c0: 45 5f 4f 56 45 52 57 52 49 54 45 20 20 20 20 31  E_OVERWRITE    1
c2d0: 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  3.#define SQLITE
c2e0: 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 20 20 20  _FCNTL_PRAGMA   
c2f0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31 34                14
c300: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
c310: 46 43 4e 54 4c 5f 42 55 53 59 48 41 4e 44 4c 45  FCNTL_BUSYHANDLE
c320: 52 20 20 20 20 20 20 20 20 20 20 20 20 31 35 0a  R            15.
c330: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
c340: 43 4e 54 4c 5f 54 45 4d 50 46 49 4c 45 4e 41 4d  CNTL_TEMPFILENAM
c350: 45 20 20 20 20 20 20 20 20 20 20 20 31 36 0a 23  E           16.#
c360: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
c370: 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45 20 20 20  NTL_MMAP_SIZE   
c380: 20 20 20 20 20 20 20 20 20 20 20 31 38 0a 23 64             18.#d
c390: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
c3a0: 54 4c 5f 54 52 41 43 45 20 20 20 20 20 20 20 20  TL_TRACE        
c3b0: 20 20 20 20 20 20 20 20 20 20 31 39 0a 23 64 65            19.#de
c3c0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
c3d0: 4c 5f 48 41 53 5f 4d 4f 56 45 44 20 20 20 20 20  L_HAS_MOVED     
c3e0: 20 20 20 20 20 20 20 20 20 32 30 0a 23 64 65 66           20.#def
c3f0: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
c400: 5f 53 59 4e 43 20 20 20 20 20 20 20 20 20 20 20  _SYNC           
c410: 20 20 20 20 20 20 20 20 32 31 0a 23 64 65 66 69          21.#defi
c420: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
c430: 43 4f 4d 4d 49 54 5f 50 48 41 53 45 54 57 4f 20  COMMIT_PHASETWO 
c440: 20 20 20 20 20 20 20 32 32 0a 23 64 65 66 69 6e         22.#defin
c450: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57  e SQLITE_FCNTL_W
c460: 49 4e 33 32 5f 53 45 54 5f 48 41 4e 44 4c 45 20  IN32_SET_HANDLE 
c470: 20 20 20 20 20 20 32 33 0a 23 64 65 66 69 6e 65        23.#define
c480: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 41   SQLITE_FCNTL_WA
c490: 4c 5f 42 4c 4f 43 4b 20 20 20 20 20 20 20 20 20  L_BLOCK         
c4a0: 20 20 20 20 20 32 34 0a 23 64 65 66 69 6e 65 20       24.#define 
c4b0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 5a 49 50  SQLITE_FCNTL_ZIP
c4c0: 56 46 53 20 20 20 20 20 20 20 20 20 20 20 20 20  VFS             
c4d0: 20 20 20 20 32 35 0a 23 64 65 66 69 6e 65 20 53      25.#define S
c4e0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 52 42 55 20  QLITE_FCNTL_RBU 
c4f0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
c500: 20 20 20 32 36 0a 23 64 65 66 69 6e 65 20 53 51     26.#define SQ
c510: 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 5f 50  LITE_FCNTL_VFS_P
c520: 4f 49 4e 54 45 52 20 20 20 20 20 20 20 20 20 20  OINTER          
c530: 20 20 32 37 0a 23 64 65 66 69 6e 65 20 53 51 4c    27.#define SQL
c540: 49 54 45 5f 46 43 4e 54 4c 5f 4a 4f 55 52 4e 41  ITE_FCNTL_JOURNA
c550: 4c 5f 50 4f 49 4e 54 45 52 20 20 20 20 20 20 20  L_POINTER       
c560: 20 32 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   28.#define SQLI
c570: 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 47  TE_FCNTL_WIN32_G
c580: 45 54 5f 48 41 4e 44 4c 45 20 20 20 20 20 20 20  ET_HANDLE       
c590: 32 39 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  29.#define SQLIT
c5a0: 45 5f 46 43 4e 54 4c 5f 50 44 42 20 20 20 20 20  E_FCNTL_PDB     
c5b0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 33                 3
c5c0: 30 0a 0a 2f 2a 20 64 65 70 72 65 63 61 74 65 64  0../* deprecated
c5d0: 20 6e 61 6d 65 73 20 2a 2f 0a 23 64 65 66 69 6e   names */.#defin
c5e0: 65 20 53 51 4c 49 54 45 5f 47 45 54 5f 4c 4f 43  e SQLITE_GET_LOC
c5f0: 4b 50 52 4f 58 59 46 49 4c 45 20 20 20 20 20 20  KPROXYFILE      
c600: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 47 45 54  SQLITE_FCNTL_GET
c610: 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 0a 23  _LOCKPROXYFILE.#
c620: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 45  define SQLITE_SE
c630: 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20  T_LOCKPROXYFILE 
c640: 20 20 20 20 20 53 51 4c 49 54 45 5f 46 43 4e 54       SQLITE_FCNT
c650: 4c 5f 53 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46  L_SET_LOCKPROXYF
c660: 49 4c 45 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  ILE.#define SQLI
c670: 54 45 5f 4c 41 53 54 5f 45 52 52 4e 4f 20 20 20  TE_LAST_ERRNO   
c680: 20 20 20 20 20 20 20 20 20 20 53 51 4c 49 54 45            SQLITE
c690: 5f 46 43 4e 54 4c 5f 4c 41 53 54 5f 45 52 52 4e  _FCNTL_LAST_ERRN
c6a0: 4f 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  O.../*.** CAPI3R
c6b0: 45 46 3a 20 4d 75 74 65 78 20 48 61 6e 64 6c 65  EF: Mutex Handle
c6c0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6d 75 74 65 78  .**.** The mutex
c6d0: 20 6d 6f 64 75 6c 65 20 77 69 74 68 69 6e 20 53   module within S
c6e0: 51 4c 69 74 65 20 64 65 66 69 6e 65 73 20 5b 73  QLite defines [s
c6f0: 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 20 74 6f  qlite3_mutex] to
c700: 20 62 65 20 61 6e 0a 2a 2a 20 61 62 73 74 72 61   be an.** abstra
c710: 63 74 20 74 79 70 65 20 66 6f 72 20 61 20 6d 75  ct type for a mu
c720: 74 65 78 20 6f 62 6a 65 63 74 2e 20 20 54 68 65  tex object.  The
c730: 20 53 51 4c 69 74 65 20 63 6f 72 65 20 6e 65 76   SQLite core nev
c740: 65 72 20 6c 6f 6f 6b 73 0a 2a 2a 20 61 74 20 74  er looks.** at t
c750: 68 65 20 69 6e 74 65 72 6e 61 6c 20 72 65 70 72  he internal repr
c760: 65 73 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61 6e  esentation of an
c770: 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d   [sqlite3_mutex]
c780: 2e 20 20 49 74 20 6f 6e 6c 79 0a 2a 2a 20 64 65  .  It only.** de
c790: 61 6c 73 20 77 69 74 68 20 70 6f 69 6e 74 65 72  als with pointer
c7a0: 73 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  s to the [sqlite
c7b0: 33 5f 6d 75 74 65 78 5d 20 6f 62 6a 65 63 74 2e  3_mutex] object.
c7c0: 0a 2a 2a 0a 2a 2a 20 4d 75 74 65 78 65 73 20 61  .**.** Mutexes a
c7d0: 72 65 20 63 72 65 61 74 65 64 20 75 73 69 6e 67  re created using
c7e0: 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f   [sqlite3_mutex_
c7f0: 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 74 79 70  alloc()]..*/.typ
c800: 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69  edef struct sqli
c810: 74 65 33 5f 6d 75 74 65 78 20 73 71 6c 69 74 65  te3_mutex sqlite
c820: 33 5f 6d 75 74 65 78 3b 0a 0a 2f 2a 0a 2a 2a 20  3_mutex;../*.** 
c830: 43 41 50 49 33 52 45 46 3a 20 4c 6f 61 64 61 62  CAPI3REF: Loadab
c840: 6c 65 20 45 78 74 65 6e 73 69 6f 6e 20 54 68 75  le Extension Thu
c850: 6e 6b 0a 2a 2a 0a 2a 2a 20 41 20 70 6f 69 6e 74  nk.**.** A point
c860: 65 72 20 74 6f 20 74 68 65 20 6f 70 61 71 75 65  er to the opaque
c870: 20 73 71 6c 69 74 65 33 5f 61 70 69 5f 72 6f 75   sqlite3_api_rou
c880: 74 69 6e 65 73 20 73 74 72 75 63 74 75 72 65 20  tines structure 
c890: 69 73 20 70 61 73 73 65 64 20 61 73 0a 2a 2a 20  is passed as.** 
c8a0: 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65  the third parame
c8b0: 74 65 72 20 74 6f 20 65 6e 74 72 79 20 70 6f 69  ter to entry poi
c8c0: 6e 74 73 20 6f 66 20 5b 6c 6f 61 64 61 62 6c 65  nts of [loadable
c8d0: 20 65 78 74 65 6e 73 69 6f 6e 73 5d 2e 20 20 54   extensions].  T
c8e0: 68 69 73 0a 2a 2a 20 73 74 72 75 63 74 75 72 65  his.** structure
c8f0: 20 6d 75 73 74 20 62 65 20 74 79 70 65 64 65 66   must be typedef
c900: 65 64 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 77  ed in order to w
c910: 6f 72 6b 20 61 72 6f 75 6e 64 20 63 6f 6d 70 69  ork around compi
c920: 6c 65 72 20 77 61 72 6e 69 6e 67 73 0a 2a 2a 20  ler warnings.** 
c930: 6f 6e 20 73 6f 6d 65 20 70 6c 61 74 66 6f 72 6d  on some platform
c940: 73 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74  s..*/.typedef st
c950: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 61 70 69  ruct sqlite3_api
c960: 5f 72 6f 75 74 69 6e 65 73 20 73 71 6c 69 74 65  _routines sqlite
c970: 33 5f 61 70 69 5f 72 6f 75 74 69 6e 65 73 3b 0a  3_api_routines;.
c980: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
c990: 20 4f 53 20 49 6e 74 65 72 66 61 63 65 20 4f 62   OS Interface Ob
c9a0: 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e  ject.**.** An in
c9b0: 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 73 71  stance of the sq
c9c0: 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74  lite3_vfs object
c9d0: 20 64 65 66 69 6e 65 73 20 74 68 65 20 69 6e 74   defines the int
c9e0: 65 72 66 61 63 65 20 62 65 74 77 65 65 6e 0a 2a  erface between.*
c9f0: 2a 20 74 68 65 20 53 51 4c 69 74 65 20 63 6f 72  * the SQLite cor
ca00: 65 20 61 6e 64 20 74 68 65 20 75 6e 64 65 72 6c  e and the underl
ca10: 79 69 6e 67 20 6f 70 65 72 61 74 69 6e 67 20 73  ying operating s
ca20: 79 73 74 65 6d 2e 20 20 54 68 65 20 22 76 66 73  ystem.  The "vfs
ca30: 22 0a 2a 2a 20 69 6e 20 74 68 65 20 6e 61 6d 65  ".** in the name
ca40: 20 6f 66 20 74 68 65 20 6f 62 6a 65 63 74 20 73   of the object s
ca50: 74 61 6e 64 73 20 66 6f 72 20 22 76 69 72 74 75  tands for "virtu
ca60: 61 6c 20 66 69 6c 65 20 73 79 73 74 65 6d 22 2e  al file system".
ca70: 20 20 53 65 65 0a 2a 2a 20 74 68 65 20 5b 56 46    See.** the [VF
ca80: 53 20 7c 20 56 46 53 20 64 6f 63 75 6d 65 6e 74  S | VFS document
ca90: 61 74 69 6f 6e 5d 20 66 6f 72 20 66 75 72 74 68  ation] for furth
caa0: 65 72 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a  er information..
cab0: 2a 2a 0a 2a 2a 20 54 68 65 20 76 61 6c 75 65 20  **.** The value 
cac0: 6f 66 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20  of the iVersion 
cad0: 66 69 65 6c 64 20 69 73 20 69 6e 69 74 69 61 6c  field is initial
cae0: 6c 79 20 31 20 62 75 74 20 6d 61 79 20 62 65 20  ly 1 but may be 
caf0: 6c 61 72 67 65 72 20 69 6e 0a 2a 2a 20 66 75 74  larger in.** fut
cb00: 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20  ure versions of 
cb10: 53 51 4c 69 74 65 2e 20 20 41 64 64 69 74 69 6f  SQLite.  Additio
cb20: 6e 61 6c 20 66 69 65 6c 64 73 20 6d 61 79 20 62  nal fields may b
cb30: 65 20 61 70 70 65 6e 64 65 64 20 74 6f 20 74 68  e appended to th
cb40: 69 73 0a 2a 2a 20 6f 62 6a 65 63 74 20 77 68 65  is.** object whe
cb50: 6e 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20 76  n the iVersion v
cb60: 61 6c 75 65 20 69 73 20 69 6e 63 72 65 61 73 65  alue is increase
cb70: 64 2e 20 20 4e 6f 74 65 20 74 68 61 74 20 74 68  d.  Note that th
cb80: 65 20 73 74 72 75 63 74 75 72 65 0a 2a 2a 20 6f  e structure.** o
cb90: 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66  f the sqlite3_vf
cba0: 73 20 6f 62 6a 65 63 74 20 63 68 61 6e 67 65 73  s object changes
cbb0: 20 69 6e 20 74 68 65 20 74 72 61 6e 73 61 63 74   in the transact
cbc0: 69 6f 6e 20 62 65 74 77 65 65 6e 0a 2a 2a 20 53  ion between.** S
cbd0: 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e  QLite version 3.
cbe0: 35 2e 39 20 61 6e 64 20 33 2e 36 2e 30 20 61 6e  5.9 and 3.6.0 an
cbf0: 64 20 79 65 74 20 74 68 65 20 69 56 65 72 73 69  d yet the iVersi
cc00: 6f 6e 20 66 69 65 6c 64 20 77 61 73 20 6e 6f 74  on field was not
cc10: 0a 2a 2a 20 6d 6f 64 69 66 69 65 64 2e 0a 2a 2a  .** modified..**
cc20: 0a 2a 2a 20 54 68 65 20 73 7a 4f 73 46 69 6c 65  .** The szOsFile
cc30: 20 66 69 65 6c 64 20 69 73 20 74 68 65 20 73 69   field is the si
cc40: 7a 65 20 6f 66 20 74 68 65 20 73 75 62 63 6c 61  ze of the subcla
cc50: 73 73 65 64 20 5b 73 71 6c 69 74 65 33 5f 66 69  ssed [sqlite3_fi
cc60: 6c 65 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65  le].** structure
cc70: 20 75 73 65 64 20 62 79 20 74 68 69 73 20 56 46   used by this VF
cc80: 53 2e 20 20 6d 78 50 61 74 68 6e 61 6d 65 20 69  S.  mxPathname i
cc90: 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65  s the maximum le
cca0: 6e 67 74 68 20 6f 66 0a 2a 2a 20 61 20 70 61 74  ngth of.** a pat
ccb0: 68 6e 61 6d 65 20 69 6e 20 74 68 69 73 20 56 46  hname in this VF
ccc0: 53 2e 0a 2a 2a 0a 2a 2a 20 52 65 67 69 73 74 65  S..**.** Registe
ccd0: 72 65 64 20 73 71 6c 69 74 65 33 5f 76 66 73 20  red sqlite3_vfs 
cce0: 6f 62 6a 65 63 74 73 20 61 72 65 20 6b 65 70 74  objects are kept
ccf0: 20 6f 6e 20 61 20 6c 69 6e 6b 65 64 20 6c 69 73   on a linked lis
cd00: 74 20 66 6f 72 6d 65 64 20 62 79 0a 2a 2a 20 74  t formed by.** t
cd10: 68 65 20 70 4e 65 78 74 20 70 6f 69 6e 74 65 72  he pNext pointer
cd20: 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  .  The [sqlite3_
cd30: 76 66 73 5f 72 65 67 69 73 74 65 72 28 29 5d 0a  vfs_register()].
cd40: 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  ** and [sqlite3_
cd50: 76 66 73 5f 75 6e 72 65 67 69 73 74 65 72 28 29  vfs_unregister()
cd60: 5d 20 69 6e 74 65 72 66 61 63 65 73 20 6d 61 6e  ] interfaces man
cd70: 61 67 65 20 74 68 69 73 20 6c 69 73 74 0a 2a 2a  age this list.**
cd80: 20 69 6e 20 61 20 74 68 72 65 61 64 2d 73 61 66   in a thread-saf
cd90: 65 20 77 61 79 2e 20 20 54 68 65 20 5b 73 71 6c  e way.  The [sql
cda0: 69 74 65 33 5f 76 66 73 5f 66 69 6e 64 28 29 5d  ite3_vfs_find()]
cdb0: 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 73 65   interface.** se
cdc0: 61 72 63 68 65 73 20 74 68 65 20 6c 69 73 74 2e  arches the list.
cdd0: 20 20 4e 65 69 74 68 65 72 20 74 68 65 20 61 70    Neither the ap
cde0: 70 6c 69 63 61 74 69 6f 6e 20 63 6f 64 65 20 6e  plication code n
cdf0: 6f 72 20 74 68 65 20 56 46 53 0a 2a 2a 20 69 6d  or the VFS.** im
ce00: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 73 68 6f  plementation sho
ce10: 75 6c 64 20 75 73 65 20 74 68 65 20 70 4e 65 78  uld use the pNex
ce20: 74 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a  t pointer..**.**
ce30: 20 54 68 65 20 70 4e 65 78 74 20 66 69 65 6c 64   The pNext field
ce40: 20 69 73 20 74 68 65 20 6f 6e 6c 79 20 66 69 65   is the only fie
ce50: 6c 64 20 69 6e 20 74 68 65 20 73 71 6c 69 74 65  ld in the sqlite
ce60: 33 5f 76 66 73 0a 2a 2a 20 73 74 72 75 63 74 75  3_vfs.** structu
ce70: 72 65 20 74 68 61 74 20 53 51 4c 69 74 65 20 77  re that SQLite w
ce80: 69 6c 6c 20 65 76 65 72 20 6d 6f 64 69 66 79 2e  ill ever modify.
ce90: 20 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 6f 6e    SQLite will on
cea0: 6c 79 20 61 63 63 65 73 73 0a 2a 2a 20 6f 72 20  ly access.** or 
ceb0: 6d 6f 64 69 66 79 20 74 68 69 73 20 66 69 65 6c  modify this fiel
cec0: 64 20 77 68 69 6c 65 20 68 6f 6c 64 69 6e 67 20  d while holding 
ced0: 61 20 70 61 72 74 69 63 75 6c 61 72 20 73 74 61  a particular sta
cee0: 74 69 63 20 6d 75 74 65 78 2e 0a 2a 2a 20 54 68  tic mutex..** Th
cef0: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68  e application sh
cf00: 6f 75 6c 64 20 6e 65 76 65 72 20 6d 6f 64 69 66  ould never modif
cf10: 79 20 61 6e 79 74 68 69 6e 67 20 77 69 74 68 69  y anything withi
cf20: 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66  n the sqlite3_vf
cf30: 73 0a 2a 2a 20 6f 62 6a 65 63 74 20 6f 6e 63 65  s.** object once
cf40: 20 74 68 65 20 6f 62 6a 65 63 74 20 68 61 73 20   the object has 
cf50: 62 65 65 6e 20 72 65 67 69 73 74 65 72 65 64 2e  been registered.
cf60: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 7a 4e 61 6d 65  .**.** The zName
cf70: 20 66 69 65 6c 64 20 68 6f 6c 64 73 20 74 68 65   field holds the
cf80: 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 56 46 53   name of the VFS
cf90: 20 6d 6f 64 75 6c 65 2e 20 20 54 68 65 20 6e 61   module.  The na
cfa0: 6d 65 20 6d 75 73 74 0a 2a 2a 20 62 65 20 75 6e  me must.** be un
cfb0: 69 71 75 65 20 61 63 72 6f 73 73 20 61 6c 6c 20  ique across all 
cfc0: 56 46 53 20 6d 6f 64 75 6c 65 73 2e 0a 2a 2a 0a  VFS modules..**.
cfd0: 2a 2a 20 5b 5b 73 71 6c 69 74 65 33 5f 76 66 73  ** [[sqlite3_vfs
cfe0: 2e 78 4f 70 65 6e 5d 5d 0a 2a 2a 20 5e 53 51 4c  .xOpen]].** ^SQL
cff0: 69 74 65 20 67 75 61 72 61 6e 74 65 65 73 20 74  ite guarantees t
d000: 68 61 74 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d  hat the zFilenam
d010: 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 78  e parameter to x
d020: 4f 70 65 6e 0a 2a 2a 20 69 73 20 65 69 74 68 65  Open.** is eithe
d030: 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  r a NULL pointer
d040: 20 6f 72 20 73 74 72 69 6e 67 20 6f 62 74 61 69   or string obtai
d050: 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 78 46 75 6c  ned.** from xFul
d060: 6c 50 61 74 68 6e 61 6d 65 28 29 20 77 69 74 68  lPathname() with
d070: 20 61 6e 20 6f 70 74 69 6f 6e 61 6c 20 73 75 66   an optional suf
d080: 66 69 78 20 61 64 64 65 64 2e 0a 2a 2a 20 5e 49  fix added..** ^I
d090: 66 20 61 20 73 75 66 66 69 78 20 69 73 20 61 64  f a suffix is ad
d0a0: 64 65 64 20 74 6f 20 74 68 65 20 7a 46 69 6c 65  ded to the zFile
d0b0: 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72 2c 20  name parameter, 
d0c0: 69 74 20 77 69 6c 6c 0a 2a 2a 20 63 6f 6e 73 69  it will.** consi
d0d0: 73 74 20 6f 66 20 61 20 73 69 6e 67 6c 65 20 22  st of a single "
d0e0: 2d 22 20 63 68 61 72 61 63 74 65 72 20 66 6f 6c  -" character fol
d0f0: 6c 6f 77 65 64 20 62 79 20 6e 6f 20 6d 6f 72 65  lowed by no more
d100: 20 74 68 61 6e 0a 2a 2a 20 31 31 20 61 6c 70 68   than.** 11 alph
d110: 61 6e 75 6d 65 72 69 63 20 61 6e 64 2f 6f 72 20  anumeric and/or 
d120: 22 2d 22 20 63 68 61 72 61 63 74 65 72 73 2e 0a  "-" characters..
d130: 2a 2a 20 5e 53 51 4c 69 74 65 20 66 75 72 74 68  ** ^SQLite furth
d140: 65 72 20 67 75 61 72 61 6e 74 65 65 73 20 74 68  er guarantees th
d150: 61 74 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67  at.** the string
d160: 20 77 69 6c 6c 20 62 65 20 76 61 6c 69 64 20 61   will be valid a
d170: 6e 64 20 75 6e 63 68 61 6e 67 65 64 20 75 6e 74  nd unchanged unt
d180: 69 6c 20 78 43 6c 6f 73 65 28 29 20 69 73 0a 2a  il xClose() is.*
d190: 2a 20 63 61 6c 6c 65 64 2e 20 42 65 63 61 75 73  * called. Becaus
d1a0: 65 20 6f 66 20 74 68 65 20 70 72 65 76 69 6f 75  e of the previou
d1b0: 73 20 73 65 6e 74 65 6e 63 65 2c 0a 2a 2a 20 74  s sentence,.** t
d1c0: 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  he [sqlite3_file
d1d0: 5d 20 63 61 6e 20 73 61 66 65 6c 79 20 73 74 6f  ] can safely sto
d1e0: 72 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  re a pointer to 
d1f0: 74 68 65 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20  the.** filename 
d200: 69 66 20 69 74 20 6e 65 65 64 73 20 74 6f 20 72  if it needs to r
d210: 65 6d 65 6d 62 65 72 20 74 68 65 20 66 69 6c 65  emember the file
d220: 6e 61 6d 65 20 66 6f 72 20 73 6f 6d 65 20 72 65  name for some re
d230: 61 73 6f 6e 2e 0a 2a 2a 20 49 66 20 74 68 65 20  ason..** If the 
d240: 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65  zFilename parame
d250: 74 65 72 20 74 6f 20 78 4f 70 65 6e 20 69 73 20  ter to xOpen is 
d260: 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74  a NULL pointer t
d270: 68 65 6e 20 78 4f 70 65 6e 0a 2a 2a 20 6d 75 73  hen xOpen.** mus
d280: 74 20 69 6e 76 65 6e 74 20 69 74 73 20 6f 77 6e  t invent its own
d290: 20 74 65 6d 70 6f 72 61 72 79 20 6e 61 6d 65 20   temporary name 
d2a0: 66 6f 72 20 74 68 65 20 66 69 6c 65 2e 20 20 5e  for the file.  ^
d2b0: 57 68 65 6e 65 76 65 72 20 74 68 65 20 0a 2a 2a  Whenever the .**
d2c0: 20 78 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d   xFilename param
d2d0: 65 74 65 72 20 69 73 20 4e 55 4c 4c 20 69 74 20  eter is NULL it 
d2e0: 77 69 6c 6c 20 61 6c 73 6f 20 62 65 20 74 68 65  will also be the
d2f0: 20 63 61 73 65 20 74 68 61 74 20 74 68 65 0a 2a   case that the.*
d300: 2a 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65  * flags paramete
d310: 72 20 77 69 6c 6c 20 69 6e 63 6c 75 64 65 20 5b  r will include [
d320: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45  SQLITE_OPEN_DELE
d330: 54 45 4f 4e 43 4c 4f 53 45 5d 2e 0a 2a 2a 0a 2a  TEONCLOSE]..**.*
d340: 2a 20 54 68 65 20 66 6c 61 67 73 20 61 72 67 75  * The flags argu
d350: 6d 65 6e 74 20 74 6f 20 78 4f 70 65 6e 28 29 20  ment to xOpen() 
d360: 69 6e 63 6c 75 64 65 73 20 61 6c 6c 20 62 69 74  includes all bit
d370: 73 20 73 65 74 20 69 6e 0a 2a 2a 20 74 68 65 20  s set in.** the 
d380: 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74  flags argument t
d390: 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  o [sqlite3_open_
d3a0: 76 32 28 29 5d 2e 20 20 4f 72 20 69 66 20 5b 73  v2()].  Or if [s
d3b0: 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a  qlite3_open()].*
d3c0: 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70  * or [sqlite3_op
d3d0: 65 6e 31 36 28 29 5d 20 69 73 20 75 73 65 64 2c  en16()] is used,
d3e0: 20 74 68 65 6e 20 66 6c 61 67 73 20 69 6e 63 6c   then flags incl
d3f0: 75 64 65 73 20 61 74 20 6c 65 61 73 74 0a 2a 2a  udes at least.**
d400: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45   [SQLITE_OPEN_RE
d410: 41 44 57 52 49 54 45 5d 20 7c 20 5b 53 51 4c 49  ADWRITE] | [SQLI
d420: 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 2e  TE_OPEN_CREATE].
d430: 20 0a 2a 2a 20 49 66 20 78 4f 70 65 6e 28 29 20   .** If xOpen() 
d440: 6f 70 65 6e 73 20 61 20 66 69 6c 65 20 72 65 61  opens a file rea
d450: 64 2d 6f 6e 6c 79 20 74 68 65 6e 20 69 74 20 73  d-only then it s
d460: 65 74 73 20 2a 70 4f 75 74 46 6c 61 67 73 20 74  ets *pOutFlags t
d470: 6f 0a 2a 2a 20 69 6e 63 6c 75 64 65 20 5b 53 51  o.** include [SQ
d480: 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e  LITE_OPEN_READON
d490: 4c 59 5d 2e 20 20 4f 74 68 65 72 20 62 69 74 73  LY].  Other bits
d4a0: 20 69 6e 20 2a 70 4f 75 74 46 6c 61 67 73 20 6d   in *pOutFlags m
d4b0: 61 79 20 62 65 20 73 65 74 2e 0a 2a 2a 0a 2a 2a  ay be set..**.**
d4c0: 20 5e 28 53 51 4c 69 74 65 20 77 69 6c 6c 20 61   ^(SQLite will a
d4d0: 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20 74  lso add one of t
d4e0: 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61  he following fla
d4f0: 67 73 20 74 6f 20 74 68 65 20 78 4f 70 65 6e 28  gs to the xOpen(
d500: 29 0a 2a 2a 20 63 61 6c 6c 2c 20 64 65 70 65 6e  ).** call, depen
d510: 64 69 6e 67 20 6f 6e 20 74 68 65 20 6f 62 6a 65  ding on the obje
d520: 63 74 20 62 65 69 6e 67 20 6f 70 65 6e 65 64 3a  ct being opened:
d530: 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c  .**.** <ul>.** <
d540: 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45  li>  [SQLITE_OPE
d550: 4e 5f 4d 41 49 4e 5f 44 42 5d 0a 2a 2a 20 3c 6c  N_MAIN_DB].** <l
d560: 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  i>  [SQLITE_OPEN
d570: 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a  _MAIN_JOURNAL].*
d580: 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f  * <li>  [SQLITE_
d590: 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 5d 0a 2a 2a  OPEN_TEMP_DB].**
d5a0: 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f   <li>  [SQLITE_O
d5b0: 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41 4c  PEN_TEMP_JOURNAL
d5c0: 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49  ].** <li>  [SQLI
d5d0: 54 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e  TE_OPEN_TRANSIEN
d5e0: 54 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b  T_DB].** <li>  [
d5f0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 55 42 4a  SQLITE_OPEN_SUBJ
d600: 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20  OURNAL].** <li> 
d610: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41   [SQLITE_OPEN_MA
d620: 53 54 45 52 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a  STER_JOURNAL].**
d630: 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f   <li>  [SQLITE_O
d640: 50 45 4e 5f 57 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c  PEN_WAL].** </ul
d650: 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69  >)^.**.** The fi
d660: 6c 65 20 49 2f 4f 20 69 6d 70 6c 65 6d 65 6e 74  le I/O implement
d670: 61 74 69 6f 6e 20 63 61 6e 20 75 73 65 20 74 68  ation can use th
d680: 65 20 6f 62 6a 65 63 74 20 74 79 70 65 20 66 6c  e object type fl
d690: 61 67 73 20 74 6f 0a 2a 2a 20 63 68 61 6e 67 65  ags to.** change
d6a0: 20 74 68 65 20 77 61 79 20 69 74 20 64 65 61 6c   the way it deal
d6b0: 73 20 77 69 74 68 20 66 69 6c 65 73 2e 20 20 46  s with files.  F
d6c0: 6f 72 20 65 78 61 6d 70 6c 65 2c 20 61 6e 20 61  or example, an a
d6d0: 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 74 68  pplication.** th
d6e0: 61 74 20 64 6f 65 73 20 6e 6f 74 20 63 61 72 65  at does not care
d6f0: 20 61 62 6f 75 74 20 63 72 61 73 68 20 72 65 63   about crash rec
d700: 6f 76 65 72 79 20 6f 72 20 72 6f 6c 6c 62 61 63  overy or rollbac
d710: 6b 20 6d 69 67 68 74 20 6d 61 6b 65 0a 2a 2a 20  k might make.** 
d720: 74 68 65 20 6f 70 65 6e 20 6f 66 20 61 20 6a 6f  the open of a jo
d730: 75 72 6e 61 6c 20 66 69 6c 65 20 61 20 6e 6f 2d  urnal file a no-
d740: 6f 70 2e 20 20 57 72 69 74 65 73 20 74 6f 20 74  op.  Writes to t
d750: 68 69 73 20 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c  his journal woul
d760: 64 0a 2a 2a 20 61 6c 73 6f 20 62 65 20 6e 6f 2d  d.** also be no-
d770: 6f 70 73 2c 20 61 6e 64 20 61 6e 79 20 61 74 74  ops, and any att
d780: 65 6d 70 74 20 74 6f 20 72 65 61 64 20 74 68 65  empt to read the
d790: 20 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c 64 20 72   journal would r
d7a0: 65 74 75 72 6e 0a 2a 2a 20 53 51 4c 49 54 45 5f  eturn.** SQLITE_
d7b0: 49 4f 45 52 52 2e 20 20 4f 72 20 74 68 65 20 69  IOERR.  Or the i
d7c0: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 69  mplementation mi
d7d0: 67 68 74 20 72 65 63 6f 67 6e 69 7a 65 20 74 68  ght recognize th
d7e0: 61 74 20 61 20 64 61 74 61 62 61 73 65 0a 2a 2a  at a database.**
d7f0: 20 66 69 6c 65 20 77 69 6c 6c 20 62 65 20 64 6f   file will be do
d800: 69 6e 67 20 70 61 67 65 2d 61 6c 69 67 6e 65 64  ing page-aligned
d810: 20 73 65 63 74 6f 72 20 72 65 61 64 73 20 61 6e   sector reads an
d820: 64 20 77 72 69 74 65 73 20 69 6e 20 61 20 72 61  d writes in a ra
d830: 6e 64 6f 6d 0a 2a 2a 20 6f 72 64 65 72 20 61 6e  ndom.** order an
d840: 64 20 73 65 74 20 75 70 20 69 74 73 20 49 2f 4f  d set up its I/O
d850: 20 73 75 62 73 79 73 74 65 6d 20 61 63 63 6f 72   subsystem accor
d860: 64 69 6e 67 6c 79 2e 0a 2a 2a 0a 2a 2a 20 53 51  dingly..**.** SQ
d870: 4c 69 74 65 20 6d 69 67 68 74 20 61 6c 73 6f 20  Lite might also 
d880: 61 64 64 20 6f 6e 65 20 6f 66 20 74 68 65 20 66  add one of the f
d890: 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61 67 73 20 74  ollowing flags t
d8a0: 6f 20 74 68 65 20 78 4f 70 65 6e 20 6d 65 74 68  o the xOpen meth
d8b0: 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a  od:.**.** <ul>.*
d8c0: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4f  * <li> [SQLITE_O
d8d0: 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53  PEN_DELETEONCLOS
d8e0: 45 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  E].** <li> [SQLI
d8f0: 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56  TE_OPEN_EXCLUSIV
d900: 45 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a  E].** </ul>.**.*
d910: 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50  * The [SQLITE_OP
d920: 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45  EN_DELETEONCLOSE
d930: 5d 20 66 6c 61 67 20 6d 65 61 6e 73 20 74 68 65  ] flag means the
d940: 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 62 65 0a   file should be.
d950: 2a 2a 20 64 65 6c 65 74 65 64 20 77 68 65 6e 20  ** deleted when 
d960: 69 74 20 69 73 20 63 6c 6f 73 65 64 2e 20 20 5e  it is closed.  ^
d970: 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  The [SQLITE_OPEN
d980: 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 0a  _DELETEONCLOSE].
d990: 2a 2a 20 77 69 6c 6c 20 62 65 20 73 65 74 20 66  ** will be set f
d9a0: 6f 72 20 54 45 4d 50 20 64 61 74 61 62 61 73 65  or TEMP database
d9b0: 73 20 61 6e 64 20 74 68 65 69 72 20 6a 6f 75 72  s and their jour
d9c0: 6e 61 6c 73 2c 20 74 72 61 6e 73 69 65 6e 74 0a  nals, transient.
d9d0: 2a 2a 20 64 61 74 61 62 61 73 65 73 2c 20 61 6e  ** databases, an
d9e0: 64 20 73 75 62 6a 6f 75 72 6e 61 6c 73 2e 0a 2a  d subjournals..*
d9f0: 2a 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54  *.** ^The [SQLIT
da00: 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45  E_OPEN_EXCLUSIVE
da10: 5d 20 66 6c 61 67 20 69 73 20 61 6c 77 61 79 73  ] flag is always
da20: 20 75 73 65 64 20 69 6e 20 63 6f 6e 6a 75 6e 63   used in conjunc
da30: 74 69 6f 6e 0a 2a 2a 20 77 69 74 68 20 74 68 65  tion.** with the
da40: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52   [SQLITE_OPEN_CR
da50: 45 41 54 45 5d 20 66 6c 61 67 2c 20 77 68 69 63  EATE] flag, whic
da60: 68 20 61 72 65 20 62 6f 74 68 20 64 69 72 65 63  h are both direc
da70: 74 6c 79 0a 2a 2a 20 61 6e 61 6c 6f 67 6f 75 73  tly.** analogous
da80: 20 74 6f 20 74 68 65 20 4f 5f 45 58 43 4c 20 61   to the O_EXCL a
da90: 6e 64 20 4f 5f 43 52 45 41 54 20 66 6c 61 67 73  nd O_CREAT flags
daa0: 20 6f 66 20 74 68 65 20 50 4f 53 49 58 20 6f 70   of the POSIX op
dab0: 65 6e 28 29 0a 2a 2a 20 41 50 49 2e 20 20 54 68  en().** API.  Th
dac0: 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58  e SQLITE_OPEN_EX
dad0: 43 4c 55 53 49 56 45 20 66 6c 61 67 2c 20 77 68  CLUSIVE flag, wh
dae0: 65 6e 20 70 61 69 72 65 64 20 77 69 74 68 20 74  en paired with t
daf0: 68 65 20 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f 50  he .** SQLITE_OP
db00: 45 4e 5f 43 52 45 41 54 45 2c 20 69 73 20 75 73  EN_CREATE, is us
db10: 65 64 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74  ed to indicate t
db20: 68 61 74 20 66 69 6c 65 20 73 68 6f 75 6c 64 20  hat file should 
db30: 61 6c 77 61 79 73 0a 2a 2a 20 62 65 20 63 72 65  always.** be cre
db40: 61 74 65 64 2c 20 61 6e 64 20 74 68 61 74 20 69  ated, and that i
db50: 74 20 69 73 20 61 6e 20 65 72 72 6f 72 20 69 66  t is an error if
db60: 20 69 74 20 61 6c 72 65 61 64 79 20 65 78 69 73   it already exis
db70: 74 73 2e 0a 2a 2a 20 49 74 20 69 73 20 3c 69 3e  ts..** It is <i>
db80: 6e 6f 74 3c 2f 69 3e 20 75 73 65 64 20 74 6f 20  not</i> used to 
db90: 69 6e 64 69 63 61 74 65 20 74 68 65 20 66 69 6c  indicate the fil
dba0: 65 20 73 68 6f 75 6c 64 20 62 65 20 6f 70 65 6e  e should be open
dbb0: 65 64 20 0a 2a 2a 20 66 6f 72 20 65 78 63 6c 75  ed .** for exclu
dbc0: 73 69 76 65 20 61 63 63 65 73 73 2e 0a 2a 2a 0a  sive access..**.
dbd0: 2a 2a 20 5e 41 74 20 6c 65 61 73 74 20 73 7a 4f  ** ^At least szO
dbe0: 73 46 69 6c 65 20 62 79 74 65 73 20 6f 66 20 6d  sFile bytes of m
dbf0: 65 6d 6f 72 79 20 61 72 65 20 61 6c 6c 6f 63 61  emory are alloca
dc00: 74 65 64 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a  ted by SQLite.**
dc10: 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 20 5b 73   to hold the  [s
dc20: 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 73 74 72  qlite3_file] str
dc30: 75 63 74 75 72 65 20 70 61 73 73 65 64 20 61 73  ucture passed as
dc40: 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 61 72   the third.** ar
dc50: 67 75 6d 65 6e 74 20 74 6f 20 78 4f 70 65 6e 2e  gument to xOpen.
dc60: 20 20 54 68 65 20 78 4f 70 65 6e 20 6d 65 74 68    The xOpen meth
dc70: 6f 64 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 65  od does not have
dc80: 20 74 6f 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 20   to.** allocate 
dc90: 74 68 65 20 73 74 72 75 63 74 75 72 65 3b 20 69  the structure; i
dca0: 74 20 73 68 6f 75 6c 64 20 6a 75 73 74 20 66 69  t should just fi
dcb0: 6c 6c 20 69 74 20 69 6e 2e 20 20 4e 6f 74 65 20  ll it in.  Note 
dcc0: 74 68 61 74 0a 2a 2a 20 74 68 65 20 78 4f 70 65  that.** the xOpe
dcd0: 6e 20 6d 65 74 68 6f 64 20 6d 75 73 74 20 73 65  n method must se
dce0: 74 20 74 68 65 20 73 71 6c 69 74 65 33 5f 66 69  t the sqlite3_fi
dcf0: 6c 65 2e 70 4d 65 74 68 6f 64 73 20 74 6f 20 65  le.pMethods to e
dd00: 69 74 68 65 72 0a 2a 2a 20 61 20 76 61 6c 69 64  ither.** a valid
dd10: 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74   [sqlite3_io_met
dd20: 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 6f 72 20  hods] object or 
dd30: 74 6f 20 4e 55 4c 4c 2e 20 20 78 4f 70 65 6e 20  to NULL.  xOpen 
dd40: 6d 75 73 74 20 64 6f 0a 2a 2a 20 74 68 69 73 20  must do.** this 
dd50: 65 76 65 6e 20 69 66 20 74 68 65 20 6f 70 65 6e  even if the open
dd60: 20 66 61 69 6c 73 2e 20 20 53 51 4c 69 74 65 20   fails.  SQLite 
dd70: 65 78 70 65 63 74 73 20 74 68 61 74 20 74 68 65  expects that the
dd80: 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d   sqlite3_file.pM
dd90: 65 74 68 6f 64 73 0a 2a 2a 20 65 6c 65 6d 65 6e  ethods.** elemen
dda0: 74 20 77 69 6c 6c 20 62 65 20 76 61 6c 69 64 20  t will be valid 
ddb0: 61 66 74 65 72 20 78 4f 70 65 6e 20 72 65 74 75  after xOpen retu
ddc0: 72 6e 73 20 72 65 67 61 72 64 6c 65 73 73 20 6f  rns regardless o
ddd0: 66 20 74 68 65 20 73 75 63 63 65 73 73 0a 2a 2a  f the success.**
dde0: 20 6f 72 20 66 61 69 6c 75 72 65 20 6f 66 20 74   or failure of t
ddf0: 68 65 20 78 4f 70 65 6e 20 63 61 6c 6c 2e 0a 2a  he xOpen call..*
de00: 2a 0a 2a 2a 20 5b 5b 73 71 6c 69 74 65 33 5f 76  *.** [[sqlite3_v
de10: 66 73 2e 78 41 63 63 65 73 73 5d 5d 0a 2a 2a 20  fs.xAccess]].** 
de20: 5e 54 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d  ^The flags argum
de30: 65 6e 74 20 74 6f 20 78 41 63 63 65 73 73 28 29  ent to xAccess()
de40: 20 6d 61 79 20 62 65 20 5b 53 51 4c 49 54 45 5f   may be [SQLITE_
de50: 41 43 43 45 53 53 5f 45 58 49 53 54 53 5d 0a 2a  ACCESS_EXISTS].*
de60: 2a 20 74 6f 20 74 65 73 74 20 66 6f 72 20 74 68  * to test for th
de70: 65 20 65 78 69 73 74 65 6e 63 65 20 6f 66 20 61  e existence of a
de80: 20 66 69 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 54   file, or [SQLIT
de90: 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52 49  E_ACCESS_READWRI
dea0: 54 45 5d 20 74 6f 0a 2a 2a 20 74 65 73 74 20 77  TE] to.** test w
deb0: 68 65 74 68 65 72 20 61 20 66 69 6c 65 20 69 73  hether a file is
dec0: 20 72 65 61 64 61 62 6c 65 20 61 6e 64 20 77 72   readable and wr
ded0: 69 74 61 62 6c 65 2c 20 6f 72 20 5b 53 51 4c 49  itable, or [SQLI
dee0: 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 5d 0a  TE_ACCESS_READ].
def0: 2a 2a 20 74 6f 20 74 65 73 74 20 77 68 65 74 68  ** to test wheth
df00: 65 72 20 61 20 66 69 6c 65 20 69 73 20 61 74 20  er a file is at 
df10: 6c 65 61 73 74 20 72 65 61 64 61 62 6c 65 2e 20  least readable. 
df20: 20 20 54 68 65 20 66 69 6c 65 20 63 61 6e 20 62    The file can b
df30: 65 20 61 0a 2a 2a 20 64 69 72 65 63 74 6f 72 79  e a.** directory
df40: 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20  ..**.** ^SQLite 
df50: 77 69 6c 6c 20 61 6c 77 61 79 73 20 61 6c 6c 6f  will always allo
df60: 63 61 74 65 20 61 74 20 6c 65 61 73 74 20 6d 78  cate at least mx
df70: 50 61 74 68 6e 61 6d 65 2b 31 20 62 79 74 65 73  Pathname+1 bytes
df80: 20 66 6f 72 20 74 68 65 0a 2a 2a 20 6f 75 74 70   for the.** outp
df90: 75 74 20 62 75 66 66 65 72 20 78 46 75 6c 6c 50  ut buffer xFullP
dfa0: 61 74 68 6e 61 6d 65 2e 20 20 54 68 65 20 65 78  athname.  The ex
dfb0: 61 63 74 20 73 69 7a 65 20 6f 66 20 74 68 65 20  act size of the 
dfc0: 6f 75 74 70 75 74 20 62 75 66 66 65 72 0a 2a 2a  output buffer.**
dfd0: 20 69 73 20 61 6c 73 6f 20 70 61 73 73 65 64 20   is also passed 
dfe0: 61 73 20 61 20 70 61 72 61 6d 65 74 65 72 20 74  as a parameter t
dff0: 6f 20 62 6f 74 68 20 20 6d 65 74 68 6f 64 73 2e  o both  methods.
e000: 20 49 66 20 74 68 65 20 6f 75 74 70 75 74 20 62   If the output b
e010: 75 66 66 65 72 0a 2a 2a 20 69 73 20 6e 6f 74 20  uffer.** is not 
e020: 6c 61 72 67 65 20 65 6e 6f 75 67 68 2c 20 5b 53  large enough, [S
e030: 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20  QLITE_CANTOPEN] 
e040: 73 68 6f 75 6c 64 20 62 65 20 72 65 74 75 72 6e  should be return
e050: 65 64 2e 20 53 69 6e 63 65 20 74 68 69 73 20 69  ed. Since this i
e060: 73 0a 2a 2a 20 68 61 6e 64 6c 65 64 20 61 73 20  s.** handled as 
e070: 61 20 66 61 74 61 6c 20 65 72 72 6f 72 20 62 79  a fatal error by
e080: 20 53 51 4c 69 74 65 2c 20 76 66 73 20 69 6d 70   SQLite, vfs imp
e090: 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 73 68 6f  lementations sho
e0a0: 75 6c 64 20 65 6e 64 65 61 76 6f 72 0a 2a 2a 20  uld endeavor.** 
e0b0: 74 6f 20 70 72 65 76 65 6e 74 20 74 68 69 73 20  to prevent this 
e0c0: 62 79 20 73 65 74 74 69 6e 67 20 6d 78 50 61 74  by setting mxPat
e0d0: 68 6e 61 6d 65 20 74 6f 20 61 20 73 75 66 66 69  hname to a suffi
e0e0: 63 69 65 6e 74 6c 79 20 6c 61 72 67 65 20 76 61  ciently large va
e0f0: 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78  lue..**.** The x
e100: 52 61 6e 64 6f 6d 6e 65 73 73 28 29 2c 20 78 53  Randomness(), xS
e110: 6c 65 65 70 28 29 2c 20 78 43 75 72 72 65 6e 74  leep(), xCurrent
e120: 54 69 6d 65 28 29 2c 20 61 6e 64 20 78 43 75 72  Time(), and xCur
e130: 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 0a  rentTimeInt64().
e140: 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 61 72  ** interfaces ar
e150: 65 20 6e 6f 74 20 73 74 72 69 63 74 6c 79 20 61  e not strictly a
e160: 20 70 61 72 74 20 6f 66 20 74 68 65 20 66 69 6c   part of the fil
e170: 65 73 79 73 74 65 6d 2c 20 62 75 74 20 74 68 65  esystem, but the
e180: 79 20 61 72 65 0a 2a 2a 20 69 6e 63 6c 75 64 65  y are.** include
e190: 64 20 69 6e 20 74 68 65 20 56 46 53 20 73 74 72  d in the VFS str
e1a0: 75 63 74 75 72 65 20 66 6f 72 20 63 6f 6d 70 6c  ucture for compl
e1b0: 65 74 65 6e 65 73 73 2e 0a 2a 2a 20 54 68 65 20  eteness..** The 
e1c0: 78 52 61 6e 64 6f 6d 6e 65 73 73 28 29 20 66 75  xRandomness() fu
e1d0: 6e 63 74 69 6f 6e 20 61 74 74 65 6d 70 74 73 20  nction attempts 
e1e0: 74 6f 20 72 65 74 75 72 6e 20 6e 42 79 74 65 73  to return nBytes
e1f0: 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 67 6f 6f   bytes.** of goo
e200: 64 2d 71 75 61 6c 69 74 79 20 72 61 6e 64 6f 6d  d-quality random
e210: 6e 65 73 73 20 69 6e 74 6f 20 7a 4f 75 74 2e 20  ness into zOut. 
e220: 20 54 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   The return valu
e230: 65 20 69 73 0a 2a 2a 20 74 68 65 20 61 63 74 75  e is.** the actu
e240: 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  al number of byt
e250: 65 73 20 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73  es of randomness
e260: 20 6f 62 74 61 69 6e 65 64 2e 0a 2a 2a 20 54 68   obtained..** Th
e270: 65 20 78 53 6c 65 65 70 28 29 20 6d 65 74 68 6f  e xSleep() metho
e280: 64 20 63 61 75 73 65 73 20 74 68 65 20 63 61 6c  d causes the cal
e290: 6c 69 6e 67 20 74 68 72 65 61 64 20 74 6f 20 73  ling thread to s
e2a0: 6c 65 65 70 20 66 6f 72 20 61 74 0a 2a 2a 20 6c  leep for at.** l
e2b0: 65 61 73 74 20 74 68 65 20 6e 75 6d 62 65 72 20  east the number 
e2c0: 6f 66 20 6d 69 63 72 6f 73 65 63 6f 6e 64 73 20  of microseconds 
e2d0: 67 69 76 65 6e 2e 20 20 5e 54 68 65 20 78 43 75  given.  ^The xCu
e2e0: 72 72 65 6e 74 54 69 6d 65 28 29 0a 2a 2a 20 6d  rrentTime().** m
e2f0: 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 61 20  ethod returns a 
e300: 4a 75 6c 69 61 6e 20 44 61 79 20 4e 75 6d 62 65  Julian Day Numbe
e310: 72 20 66 6f 72 20 74 68 65 20 63 75 72 72 65 6e  r for the curren
e320: 74 20 64 61 74 65 20 61 6e 64 20 74 69 6d 65 20  t date and time 
e330: 61 73 0a 2a 2a 20 61 20 66 6c 6f 61 74 69 6e 67  as.** a floating
e340: 20 70 6f 69 6e 74 20 76 61 6c 75 65 2e 0a 2a 2a   point value..**
e350: 20 5e 54 68 65 20 78 43 75 72 72 65 6e 74 54 69   ^The xCurrentTi
e360: 6d 65 49 6e 74 36 34 28 29 20 6d 65 74 68 6f 64  meInt64() method
e370: 20 72 65 74 75 72 6e 73 2c 20 61 73 20 61 6e 20   returns, as an 
e380: 69 6e 74 65 67 65 72 2c 20 74 68 65 20 4a 75 6c  integer, the Jul
e390: 69 61 6e 0a 2a 2a 20 44 61 79 20 4e 75 6d 62 65  ian.** Day Numbe
e3a0: 72 20 6d 75 6c 74 69 70 6c 69 65 64 20 62 79 20  r multiplied by 
e3b0: 38 36 34 30 30 30 30 30 20 28 74 68 65 20 6e 75  86400000 (the nu
e3c0: 6d 62 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63  mber of millisec
e3d0: 6f 6e 64 73 20 69 6e 20 0a 2a 2a 20 61 20 32 34  onds in .** a 24
e3e0: 2d 68 6f 75 72 20 64 61 79 29 2e 20 20 0a 2a 2a  -hour day).  .**
e3f0: 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73   ^SQLite will us
e400: 65 20 74 68 65 20 78 43 75 72 72 65 6e 74 54 69  e the xCurrentTi
e410: 6d 65 49 6e 74 36 34 28 29 20 6d 65 74 68 6f 64  meInt64() method
e420: 20 74 6f 20 67 65 74 20 74 68 65 20 63 75 72 72   to get the curr
e430: 65 6e 74 0a 2a 2a 20 64 61 74 65 20 61 6e 64 20  ent.** date and 
e440: 74 69 6d 65 20 69 66 20 74 68 61 74 20 6d 65 74  time if that met
e450: 68 6f 64 20 69 73 20 61 76 61 69 6c 61 62 6c 65  hod is available
e460: 20 28 69 66 20 69 56 65 72 73 69 6f 6e 20 69 73   (if iVersion is
e470: 20 32 20 6f 72 20 0a 2a 2a 20 67 72 65 61 74 65   2 or .** greate
e480: 72 20 61 6e 64 20 74 68 65 20 66 75 6e 63 74 69  r and the functi
e490: 6f 6e 20 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f  on pointer is no
e4a0: 74 20 4e 55 4c 4c 29 20 61 6e 64 20 77 69 6c 6c  t NULL) and will
e4b0: 20 66 61 6c 6c 20 62 61 63 6b 0a 2a 2a 20 74 6f   fall back.** to
e4c0: 20 78 43 75 72 72 65 6e 74 54 69 6d 65 28 29 20   xCurrentTime() 
e4d0: 69 66 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49  if xCurrentTimeI
e4e0: 6e 74 36 34 28 29 20 69 73 20 75 6e 61 76 61 69  nt64() is unavai
e4f0: 6c 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  lable..**.** ^Th
e500: 65 20 78 53 65 74 53 79 73 74 65 6d 43 61 6c 6c  e xSetSystemCall
e510: 28 29 2c 20 78 47 65 74 53 79 73 74 65 6d 43 61  (), xGetSystemCa
e520: 6c 6c 28 29 2c 20 61 6e 64 20 78 4e 65 73 74 53  ll(), and xNestS
e530: 79 73 74 65 6d 43 61 6c 6c 28 29 20 69 6e 74 65  ystemCall() inte
e540: 72 66 61 63 65 73 0a 2a 2a 20 61 72 65 20 6e 6f  rfaces.** are no
e550: 74 20 75 73 65 64 20 62 79 20 74 68 65 20 53 51  t used by the SQ
e560: 4c 69 74 65 20 63 6f 72 65 2e 20 20 54 68 65 73  Lite core.  Thes
e570: 65 20 6f 70 74 69 6f 6e 61 6c 20 69 6e 74 65 72  e optional inter
e580: 66 61 63 65 73 20 61 72 65 20 70 72 6f 76 69 64  faces are provid
e590: 65 64 0a 2a 2a 20 62 79 20 73 6f 6d 65 20 56 46  ed.** by some VF
e5a0: 53 65 73 20 74 6f 20 66 61 63 69 6c 69 74 61 74  Ses to facilitat
e5b0: 65 20 74 65 73 74 69 6e 67 20 6f 66 20 74 68 65  e testing of the
e5c0: 20 56 46 53 20 63 6f 64 65 2e 20 42 79 20 6f 76   VFS code. By ov
e5d0: 65 72 72 69 64 69 6e 67 20 0a 2a 2a 20 73 79 73  erriding .** sys
e5e0: 74 65 6d 20 63 61 6c 6c 73 20 77 69 74 68 20 66  tem calls with f
e5f0: 75 6e 63 74 69 6f 6e 73 20 75 6e 64 65 72 20 69  unctions under i
e600: 74 73 20 63 6f 6e 74 72 6f 6c 2c 20 61 20 74 65  ts control, a te
e610: 73 74 20 70 72 6f 67 72 61 6d 20 63 61 6e 0a 2a  st program can.*
e620: 2a 20 73 69 6d 75 6c 61 74 65 20 66 61 75 6c 74  * simulate fault
e630: 73 20 61 6e 64 20 65 72 72 6f 72 20 63 6f 6e 64  s and error cond
e640: 69 74 69 6f 6e 73 20 74 68 61 74 20 77 6f 75 6c  itions that woul
e650: 64 20 6f 74 68 65 72 77 69 73 65 20 62 65 20 64  d otherwise be d
e660: 69 66 66 69 63 75 6c 74 0a 2a 2a 20 6f 72 20 69  ifficult.** or i
e670: 6d 70 6f 73 73 69 62 6c 65 20 74 6f 20 69 6e 64  mpossible to ind
e680: 75 63 65 2e 20 20 54 68 65 20 73 65 74 20 6f 66  uce.  The set of
e690: 20 73 79 73 74 65 6d 20 63 61 6c 6c 73 20 74 68   system calls th
e6a0: 61 74 20 63 61 6e 20 62 65 20 6f 76 65 72 72 69  at can be overri
e6b0: 64 64 65 6e 0a 2a 2a 20 76 61 72 69 65 73 20 66  dden.** varies f
e6c0: 72 6f 6d 20 6f 6e 65 20 56 46 53 20 74 6f 20 61  rom one VFS to a
e6d0: 6e 6f 74 68 65 72 2c 20 61 6e 64 20 66 72 6f 6d  nother, and from
e6e0: 20 6f 6e 65 20 76 65 72 73 69 6f 6e 20 6f 66 20   one version of 
e6f0: 74 68 65 20 73 61 6d 65 20 56 46 53 20 74 6f 20  the same VFS to 
e700: 74 68 65 0a 2a 2a 20 6e 65 78 74 2e 20 20 41 70  the.** next.  Ap
e710: 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20  plications that 
e720: 75 73 65 20 74 68 65 73 65 20 69 6e 74 65 72 66  use these interf
e730: 61 63 65 73 20 6d 75 73 74 20 62 65 20 70 72 65  aces must be pre
e740: 70 61 72 65 64 20 66 6f 72 20 61 6e 79 0a 2a 2a  pared for any.**
e750: 20 6f 72 20 61 6c 6c 20 6f 66 20 74 68 65 73 65   or all of these
e760: 20 69 6e 74 65 72 66 61 63 65 73 20 74 6f 20 62   interfaces to b
e770: 65 20 4e 55 4c 4c 20 6f 72 20 66 6f 72 20 74 68  e NULL or for th
e780: 65 69 72 20 62 65 68 61 76 69 6f 72 20 74 6f 20  eir behavior to 
e790: 63 68 61 6e 67 65 0a 2a 2a 20 66 72 6f 6d 20 6f  change.** from o
e7a0: 6e 65 20 72 65 6c 65 61 73 65 20 74 6f 20 74 68  ne release to th
e7b0: 65 20 6e 65 78 74 2e 20 20 41 70 70 6c 69 63 61  e next.  Applica
e7c0: 74 69 6f 6e 73 20 6d 75 73 74 20 6e 6f 74 20 61  tions must not a
e7d0: 74 74 65 6d 70 74 20 74 6f 20 61 63 63 65 73 73  ttempt to access
e7e0: 0a 2a 2a 20 61 6e 79 20 6f 66 20 74 68 65 73 65  .** any of these
e7f0: 20 6d 65 74 68 6f 64 73 20 69 66 20 74 68 65 20   methods if the 
e800: 69 56 65 72 73 69 6f 6e 20 6f 66 20 74 68 65 20  iVersion of the 
e810: 56 46 53 20 69 73 20 6c 65 73 73 20 74 68 61 6e  VFS is less than
e820: 20 33 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73   3..*/.typedef s
e830: 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76 66  truct sqlite3_vf
e840: 73 20 73 71 6c 69 74 65 33 5f 76 66 73 3b 0a 74  s sqlite3_vfs;.t
e850: 79 70 65 64 65 66 20 76 6f 69 64 20 28 2a 73 71  ypedef void (*sq
e860: 6c 69 74 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74  lite3_syscall_pt
e870: 72 29 28 76 6f 69 64 29 3b 0a 73 74 72 75 63 74  r)(void);.struct
e880: 20 73 71 6c 69 74 65 33 5f 76 66 73 20 7b 0a 20   sqlite3_vfs {. 
e890: 20 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b 20 20   int iVersion;  
e8a0: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53 74 72            /* Str
e8b0: 75 63 74 75 72 65 20 76 65 72 73 69 6f 6e 20 6e  ucture version n
e8c0: 75 6d 62 65 72 20 28 63 75 72 72 65 6e 74 6c 79  umber (currently
e8d0: 20 33 29 20 2a 2f 0a 20 20 69 6e 74 20 73 7a 4f   3) */.  int szO
e8e0: 73 46 69 6c 65 3b 20 20 20 20 20 20 20 20 20 20  sFile;          
e8f0: 20 20 2f 2a 20 53 69 7a 65 20 6f 66 20 73 75 62    /* Size of sub
e900: 63 6c 61 73 73 65 64 20 73 71 6c 69 74 65 33 5f  classed sqlite3_
e910: 66 69 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 6d 78  file */.  int mx
e920: 50 61 74 68 6e 61 6d 65 3b 20 20 20 20 20 20 20  Pathname;       
e930: 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 66 69     /* Maximum fi
e940: 6c 65 20 70 61 74 68 6e 61 6d 65 20 6c 65 6e 67  le pathname leng
e950: 74 68 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f  th */.  sqlite3_
e960: 76 66 73 20 2a 70 4e 65 78 74 3b 20 20 20 20 20  vfs *pNext;     
e970: 20 2f 2a 20 4e 65 78 74 20 72 65 67 69 73 74 65   /* Next registe
e980: 72 65 64 20 56 46 53 20 2a 2f 0a 20 20 63 6f 6e  red VFS */.  con
e990: 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 3b 20  st char *zName; 
e9a0: 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66        /* Name of
e9b0: 20 74 68 69 73 20 76 69 72 74 75 61 6c 20 66 69   this virtual fi
e9c0: 6c 65 20 73 79 73 74 65 6d 20 2a 2f 0a 20 20 76  le system */.  v
e9d0: 6f 69 64 20 2a 70 41 70 70 44 61 74 61 3b 20 20  oid *pAppData;  
e9e0: 20 20 20 20 20 20 20 20 2f 2a 20 50 6f 69 6e 74          /* Point
e9f0: 65 72 20 74 6f 20 61 70 70 6c 69 63 61 74 69 6f  er to applicatio
ea00: 6e 2d 73 70 65 63 69 66 69 63 20 64 61 74 61 20  n-specific data 
ea10: 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 4f 70 65 6e  */.  int (*xOpen
ea20: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
ea30: 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
ea40: 65 2c 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  e, sqlite3_file*
ea50: 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ,.              
ea60: 20 69 6e 74 20 66 6c 61 67 73 2c 20 69 6e 74 20   int flags, int 
ea70: 2a 70 4f 75 74 46 6c 61 67 73 29 3b 0a 20 20 69  *pOutFlags);.  i
ea80: 6e 74 20 28 2a 78 44 65 6c 65 74 65 29 28 73 71  nt (*xDelete)(sq
ea90: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73  lite3_vfs*, cons
eaa0: 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69  t char *zName, i
eab0: 6e 74 20 73 79 6e 63 44 69 72 29 3b 0a 20 20 69  nt syncDir);.  i
eac0: 6e 74 20 28 2a 78 41 63 63 65 73 73 29 28 73 71  nt (*xAccess)(sq
ead0: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73  lite3_vfs*, cons
eae0: 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69  t char *zName, i
eaf0: 6e 74 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a 70  nt flags, int *p
eb00: 52 65 73 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28  ResOut);.  int (
eb10: 2a 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 29 28  *xFullPathname)(
eb20: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f  sqlite3_vfs*, co
eb30: 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c  nst char *zName,
eb40: 20 69 6e 74 20 6e 4f 75 74 2c 20 63 68 61 72 20   int nOut, char 
eb50: 2a 7a 4f 75 74 29 3b 0a 20 20 76 6f 69 64 20 2a  *zOut);.  void *
eb60: 28 2a 78 44 6c 4f 70 65 6e 29 28 73 71 6c 69 74  (*xDlOpen)(sqlit
eb70: 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63  e3_vfs*, const c
eb80: 68 61 72 20 2a 7a 46 69 6c 65 6e 61 6d 65 29 3b  har *zFilename);
eb90: 0a 20 20 76 6f 69 64 20 28 2a 78 44 6c 45 72 72  .  void (*xDlErr
eba0: 6f 72 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  or)(sqlite3_vfs*
ebb0: 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 63 68 61  , int nByte, cha
ebc0: 72 20 2a 7a 45 72 72 4d 73 67 29 3b 0a 20 20 76  r *zErrMsg);.  v
ebd0: 6f 69 64 20 28 2a 28 2a 78 44 6c 53 79 6d 29 28  oid (*(*xDlSym)(
ebe0: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 76 6f 69  sqlite3_vfs*,voi
ebf0: 64 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  d*, const char *
ec00: 7a 53 79 6d 62 6f 6c 29 29 28 76 6f 69 64 29 3b  zSymbol))(void);
ec10: 0a 20 20 76 6f 69 64 20 28 2a 78 44 6c 43 6c 6f  .  void (*xDlClo
ec20: 73 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  se)(sqlite3_vfs*
ec30: 2c 20 76 6f 69 64 2a 29 3b 0a 20 20 69 6e 74 20  , void*);.  int 
ec40: 28 2a 78 52 61 6e 64 6f 6d 6e 65 73 73 29 28 73  (*xRandomness)(s
ec50: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74  qlite3_vfs*, int
ec60: 20 6e 42 79 74 65 2c 20 63 68 61 72 20 2a 7a 4f   nByte, char *zO
ec70: 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 6c  ut);.  int (*xSl
ec80: 65 65 70 29 28 73 71 6c 69 74 65 33 5f 76 66 73  eep)(sqlite3_vfs
ec90: 2a 2c 20 69 6e 74 20 6d 69 63 72 6f 73 65 63 6f  *, int microseco
eca0: 6e 64 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43  nds);.  int (*xC
ecb0: 75 72 72 65 6e 74 54 69 6d 65 29 28 73 71 6c 69  urrentTime)(sqli
ecc0: 74 65 33 5f 76 66 73 2a 2c 20 64 6f 75 62 6c 65  te3_vfs*, double
ecd0: 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 47 65 74  *);.  int (*xGet
ece0: 4c 61 73 74 45 72 72 6f 72 29 28 73 71 6c 69 74  LastError)(sqlit
ecf0: 65 33 5f 76 66 73 2a 2c 20 69 6e 74 2c 20 63 68  e3_vfs*, int, ch
ed00: 61 72 20 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a  ar *);.  /*.  **
ed10: 20 54 68 65 20 6d 65 74 68 6f 64 73 20 61 62 6f   The methods abo
ed20: 76 65 20 61 72 65 20 69 6e 20 76 65 72 73 69 6f  ve are in versio
ed30: 6e 20 31 20 6f 66 20 74 68 65 20 73 71 6c 69 74  n 1 of the sqlit
ed40: 65 5f 76 66 73 20 6f 62 6a 65 63 74 0a 20 20 2a  e_vfs object.  *
ed50: 2a 20 64 65 66 69 6e 69 74 69 6f 6e 2e 20 20 54  * definition.  T
ed60: 68 6f 73 65 20 74 68 61 74 20 66 6f 6c 6c 6f 77  hose that follow
ed70: 20 61 72 65 20 61 64 64 65 64 20 69 6e 20 76 65   are added in ve
ed80: 72 73 69 6f 6e 20 32 20 6f 72 20 6c 61 74 65 72  rsion 2 or later
ed90: 0a 20 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 43  .  */.  int (*xC
eda0: 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 29  urrentTimeInt64)
edb0: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 73  (sqlite3_vfs*, s
edc0: 71 6c 69 74 65 33 5f 69 6e 74 36 34 2a 29 3b 0a  qlite3_int64*);.
edd0: 20 20 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65    /*.  ** The me
ede0: 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20  thods above are 
edf0: 69 6e 20 76 65 72 73 69 6f 6e 73 20 31 20 61 6e  in versions 1 an
ee00: 64 20 32 20 6f 66 20 74 68 65 20 73 71 6c 69 74  d 2 of the sqlit
ee10: 65 5f 76 66 73 20 6f 62 6a 65 63 74 2e 0a 20 20  e_vfs object..  
ee20: 2a 2a 20 54 68 6f 73 65 20 62 65 6c 6f 77 20 61  ** Those below a
ee30: 72 65 20 66 6f 72 20 76 65 72 73 69 6f 6e 20 33  re for version 3
ee40: 20 61 6e 64 20 67 72 65 61 74 65 72 2e 0a 20 20   and greater..  
ee50: 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 53 65 74 53  */.  int (*xSetS
ee60: 79 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74  ystemCall)(sqlit
ee70: 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63  e3_vfs*, const c
ee80: 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69  har *zName, sqli
ee90: 74 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72 29  te3_syscall_ptr)
eea0: 3b 0a 20 20 73 71 6c 69 74 65 33 5f 73 79 73 63  ;.  sqlite3_sysc
eeb0: 61 6c 6c 5f 70 74 72 20 28 2a 78 47 65 74 53 79  all_ptr (*xGetSy
eec0: 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65  stemCall)(sqlite
eed0: 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68  3_vfs*, const ch
eee0: 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 20 20 63 6f  ar *zName);.  co
eef0: 6e 73 74 20 63 68 61 72 20 2a 28 2a 78 4e 65 78  nst char *(*xNex
ef00: 74 53 79 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c  tSystemCall)(sql
ef10: 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74  ite3_vfs*, const
ef20: 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 20   char *zName);. 
ef30: 20 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74   /*.  ** The met
ef40: 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 69  hods above are i
ef50: 6e 20 76 65 72 73 69 6f 6e 73 20 31 20 74 68 72  n versions 1 thr
ef60: 6f 75 67 68 20 33 20 6f 66 20 74 68 65 20 73 71  ough 3 of the sq
ef70: 6c 69 74 65 5f 76 66 73 20 6f 62 6a 65 63 74 2e  lite_vfs object.
ef80: 0a 20 20 2a 2a 20 4e 65 77 20 66 69 65 6c 64 73  .  ** New fields
ef90: 20 6d 61 79 20 62 65 20 61 70 70 65 6e 64 65 64   may be appended
efa0: 20 69 6e 20 66 75 74 75 72 65 20 76 65 72 73 69   in future versi
efb0: 6f 6e 73 2e 20 20 54 68 65 20 69 56 65 72 73 69  ons.  The iVersi
efc0: 6f 6e 0a 20 20 2a 2a 20 76 61 6c 75 65 20 77 69  on.  ** value wi
efd0: 6c 6c 20 69 6e 63 72 65 6d 65 6e 74 20 77 68 65  ll increment whe
efe0: 6e 65 76 65 72 20 74 68 69 73 20 68 61 70 70 65  never this happe
eff0: 6e 73 2e 20 0a 20 20 2a 2f 0a 7d 3b 0a 0a 2f 2a  ns. .  */.};../*
f000: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6c  .** CAPI3REF: Fl
f010: 61 67 73 20 66 6f 72 20 74 68 65 20 78 41 63 63  ags for the xAcc
f020: 65 73 73 20 56 46 53 20 6d 65 74 68 6f 64 0a 2a  ess VFS method.*
f030: 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 67  *.** These integ
f040: 65 72 20 63 6f 6e 73 74 61 6e 74 73 20 63 61 6e  er constants can
f050: 20 62 65 20 75 73 65 64 20 61 73 20 74 68 65 20   be used as the 
f060: 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20  third parameter 
f070: 74 6f 0a 2a 2a 20 74 68 65 20 78 41 63 63 65 73  to.** the xAcces
f080: 73 20 6d 65 74 68 6f 64 20 6f 66 20 61 6e 20 5b  s method of an [
f090: 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a  sqlite3_vfs] obj
f0a0: 65 63 74 2e 20 20 54 68 65 79 20 64 65 74 65 72  ect.  They deter
f0b0: 6d 69 6e 65 0a 2a 2a 20 77 68 61 74 20 6b 69 6e  mine.** what kin
f0c0: 64 20 6f 66 20 70 65 72 6d 69 73 73 69 6f 6e 73  d of permissions
f0d0: 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74   the xAccess met
f0e0: 68 6f 64 20 69 73 20 6c 6f 6f 6b 69 6e 67 20 66  hod is looking f
f0f0: 6f 72 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49  or..** With SQLI
f100: 54 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53  TE_ACCESS_EXISTS
f110: 2c 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65  , the xAccess me
f120: 74 68 6f 64 0a 2a 2a 20 73 69 6d 70 6c 79 20 63  thod.** simply c
f130: 68 65 63 6b 73 20 77 68 65 74 68 65 72 20 74 68  hecks whether th
f140: 65 20 66 69 6c 65 20 65 78 69 73 74 73 2e 0a 2a  e file exists..*
f150: 2a 20 57 69 74 68 20 53 51 4c 49 54 45 5f 41 43  * With SQLITE_AC
f160: 43 45 53 53 5f 52 45 41 44 57 52 49 54 45 2c 20  CESS_READWRITE, 
f170: 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68  the xAccess meth
f180: 6f 64 0a 2a 2a 20 63 68 65 63 6b 73 20 77 68 65  od.** checks whe
f190: 74 68 65 72 20 74 68 65 20 6e 61 6d 65 64 20 64  ther the named d
f1a0: 69 72 65 63 74 6f 72 79 20 69 73 20 62 6f 74 68  irectory is both
f1b0: 20 72 65 61 64 61 62 6c 65 20 61 6e 64 20 77 72   readable and wr
f1c0: 69 74 61 62 6c 65 0a 2a 2a 20 28 69 6e 20 6f 74  itable.** (in ot
f1d0: 68 65 72 20 77 6f 72 64 73 2c 20 69 66 20 66 69  her words, if fi
f1e0: 6c 65 73 20 63 61 6e 20 62 65 20 61 64 64 65 64  les can be added
f1f0: 2c 20 72 65 6d 6f 76 65 64 2c 20 61 6e 64 20 72  , removed, and r
f200: 65 6e 61 6d 65 64 20 77 69 74 68 69 6e 0a 2a 2a  enamed within.**
f210: 20 74 68 65 20 64 69 72 65 63 74 6f 72 79 29 2e   the directory).
f220: 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 41  .** The SQLITE_A
f230: 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 45 20  CCESS_READWRITE 
f240: 63 6f 6e 73 74 61 6e 74 20 69 73 20 63 75 72 72  constant is curr
f250: 65 6e 74 6c 79 20 75 73 65 64 20 6f 6e 6c 79 20  ently used only 
f260: 62 79 20 74 68 65 0a 2a 2a 20 5b 74 65 6d 70 5f  by the.** [temp_
f270: 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20  store_directory 
f280: 70 72 61 67 6d 61 5d 2c 20 74 68 6f 75 67 68 20  pragma], though 
f290: 74 68 69 73 20 63 6f 75 6c 64 20 63 68 61 6e 67  this could chang
f2a0: 65 20 69 6e 20 61 20 66 75 74 75 72 65 0a 2a 2a  e in a future.**
f2b0: 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69   release of SQLi
f2c0: 74 65 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49  te..** With SQLI
f2d0: 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 2c 20  TE_ACCESS_READ, 
f2e0: 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68  the xAccess meth
f2f0: 6f 64 0a 2a 2a 20 63 68 65 63 6b 73 20 77 68 65  od.** checks whe
f300: 74 68 65 72 20 74 68 65 20 66 69 6c 65 20 69 73  ther the file is
f310: 20 72 65 61 64 61 62 6c 65 2e 20 20 54 68 65 20   readable.  The 
f320: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45  SQLITE_ACCESS_RE
f330: 41 44 20 63 6f 6e 73 74 61 6e 74 20 69 73 0a 2a  AD constant is.*
f340: 2a 20 63 75 72 72 65 6e 74 6c 79 20 75 6e 75 73  * currently unus
f350: 65 64 2c 20 74 68 6f 75 67 68 20 69 74 20 6d 69  ed, though it mi
f360: 67 68 74 20 62 65 20 75 73 65 64 20 69 6e 20 61  ght be used in a
f370: 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 20   future release 
f380: 6f 66 0a 2a 2a 20 53 51 4c 69 74 65 2e 0a 2a 2f  of.** SQLite..*/
f390: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
f3a0: 41 43 43 45 53 53 5f 45 58 49 53 54 53 20 20 20  ACCESS_EXISTS   
f3b0: 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   0.#define SQLIT
f3c0: 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52 49  E_ACCESS_READWRI
f3d0: 54 45 20 31 20 20 20 2f 2a 20 55 73 65 64 20 62  TE 1   /* Used b
f3e0: 79 20 50 52 41 47 4d 41 20 74 65 6d 70 5f 73 74  y PRAGMA temp_st
f3f0: 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20 2a 2f  ore_directory */
f400: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
f410: 41 43 43 45 53 53 5f 52 45 41 44 20 20 20 20 20  ACCESS_READ     
f420: 20 32 20 20 20 2f 2a 20 55 6e 75 73 65 64 20 2a   2   /* Unused *
f430: 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  /../*.** CAPI3RE
f440: 46 3a 20 46 6c 61 67 73 20 66 6f 72 20 74 68 65  F: Flags for the
f450: 20 78 53 68 6d 4c 6f 63 6b 20 56 46 53 20 6d 65   xShmLock VFS me
f460: 74 68 6f 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  thod.**.** These
f470: 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e   integer constan
f480: 74 73 20 64 65 66 69 6e 65 20 74 68 65 20 76 61  ts define the va
f490: 72 69 6f 75 73 20 6c 6f 63 6b 69 6e 67 20 6f 70  rious locking op
f4a0: 65 72 61 74 69 6f 6e 73 0a 2a 2a 20 61 6c 6c 6f  erations.** allo
f4b0: 77 65 64 20 62 79 20 74 68 65 20 78 53 68 6d 4c  wed by the xShmL
f4c0: 6f 63 6b 20 6d 65 74 68 6f 64 20 6f 66 20 5b 73  ock method of [s
f4d0: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
f4e0: 73 5d 2e 20 20 54 68 65 0a 2a 2a 20 66 6f 6c 6c  s].  The.** foll
f4f0: 6f 77 69 6e 67 20 61 72 65 20 74 68 65 20 6f 6e  owing are the on
f500: 6c 79 20 6c 65 67 61 6c 20 63 6f 6d 62 69 6e 61  ly legal combina
f510: 74 69 6f 6e 73 20 6f 66 20 66 6c 61 67 73 20 74  tions of flags t
f520: 6f 20 74 68 65 0a 2a 2a 20 78 53 68 6d 4c 6f 63  o the.** xShmLoc
f530: 6b 20 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20  k method:.**.** 
f540: 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51  <ul>.** <li>  SQ
f550: 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 7c 20  LITE_SHM_LOCK | 
f560: 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52 45  SQLITE_SHM_SHARE
f570: 44 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54  D.** <li>  SQLIT
f580: 45 5f 53 48 4d 5f 4c 4f 43 4b 20 7c 20 53 51 4c  E_SHM_LOCK | SQL
f590: 49 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56  ITE_SHM_EXCLUSIV
f5a0: 45 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54  E.** <li>  SQLIT
f5b0: 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53  E_SHM_UNLOCK | S
f5c0: 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52 45 44  QLITE_SHM_SHARED
f5d0: 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45  .** <li>  SQLITE
f5e0: 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51  _SHM_UNLOCK | SQ
f5f0: 4c 49 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49  LITE_SHM_EXCLUSI
f600: 56 45 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a  VE.** </ul>.**.*
f610: 2a 20 57 68 65 6e 20 75 6e 6c 6f 63 6b 69 6e 67  * When unlocking
f620: 2c 20 74 68 65 20 73 61 6d 65 20 53 48 41 52 45  , the same SHARE
f630: 44 20 6f 72 20 45 58 43 4c 55 53 49 56 45 20 66  D or EXCLUSIVE f
f640: 6c 61 67 20 6d 75 73 74 20 62 65 20 73 75 70 70  lag must be supp
f650: 6c 69 65 64 20 61 73 0a 2a 2a 20 77 61 73 20 67  lied as.** was g
f660: 69 76 65 6e 20 6f 6e 20 74 68 65 20 63 6f 72 72  iven on the corr
f670: 65 73 70 6f 6e 64 69 6e 67 20 6c 6f 63 6b 2e 20  esponding lock. 
f680: 20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 68 6d   .**.** The xShm
f690: 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 63 61 6e 20  Lock method can 
f6a0: 74 72 61 6e 73 69 74 69 6f 6e 20 62 65 74 77 65  transition betwe
f6b0: 65 6e 20 75 6e 6c 6f 63 6b 65 64 20 61 6e 64 20  en unlocked and 
f6c0: 53 48 41 52 45 44 20 6f 72 0a 2a 2a 20 62 65 74  SHARED or.** bet
f6d0: 77 65 65 6e 20 75 6e 6c 6f 63 6b 65 64 20 61 6e  ween unlocked an
f6e0: 64 20 45 58 43 4c 55 53 49 56 45 2e 20 20 49 74  d EXCLUSIVE.  It
f6f0: 20 63 61 6e 6e 6f 74 20 74 72 61 6e 73 69 74 69   cannot transiti
f700: 6f 6e 20 62 65 74 77 65 65 6e 20 53 48 41 52 45  on between SHARE
f710: 44 0a 2a 2a 20 61 6e 64 20 45 58 43 4c 55 53 49  D.** and EXCLUSI
f720: 56 45 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  VE..*/.#define S
f730: 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b  QLITE_SHM_UNLOCK
f740: 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65         1.#define
f750: 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b   SQLITE_SHM_LOCK
f760: 20 20 20 20 20 20 20 20 20 32 0a 23 64 65 66 69           2.#defi
f770: 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48  ne SQLITE_SHM_SH
f780: 41 52 45 44 20 20 20 20 20 20 20 34 0a 23 64 65  ARED       4.#de
f790: 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f  fine SQLITE_SHM_
f7a0: 45 58 43 4c 55 53 49 56 45 20 20 20 20 38 0a 0a  EXCLUSIVE    8..
f7b0: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
f7c0: 4d 61 78 69 6d 75 6d 20 78 53 68 6d 4c 6f 63 6b  Maximum xShmLock
f7d0: 20 69 6e 64 65 78 0a 2a 2a 0a 2a 2a 20 54 68 65   index.**.** The
f7e0: 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64   xShmLock method
f7f0: 20 6f 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f   on [sqlite3_io_
f800: 6d 65 74 68 6f 64 73 5d 20 6d 61 79 20 75 73 65  methods] may use
f810: 20 76 61 6c 75 65 73 0a 2a 2a 20 62 65 74 77 65   values.** betwe
f820: 65 6e 20 30 20 61 6e 64 20 74 68 69 73 20 75 70  en 0 and this up
f830: 70 65 72 20 62 6f 75 6e 64 20 61 73 20 69 74 73  per bound as its
f840: 20 22 6f 66 66 73 65 74 22 20 61 72 67 75 6d 65   "offset" argume
f850: 6e 74 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74  nt..** The SQLit
f860: 65 20 63 6f 72 65 20 77 69 6c 6c 20 6e 65 76 65  e core will neve
f870: 72 20 61 74 74 65 6d 70 74 20 74 6f 20 61 63 71  r attempt to acq
f880: 75 69 72 65 20 6f 72 20 72 65 6c 65 61 73 65 20  uire or release 
f890: 61 0a 2a 2a 20 6c 6f 63 6b 20 6f 75 74 73 69 64  a.** lock outsid
f8a0: 65 20 6f 66 20 74 68 69 73 20 72 61 6e 67 65 0a  e of this range.
f8b0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
f8c0: 45 5f 53 48 4d 5f 4e 4c 4f 43 4b 20 20 20 20 20  E_SHM_NLOCK     
f8d0: 20 20 20 38 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50     8.../*.** CAP
f8e0: 49 33 52 45 46 3a 20 49 6e 69 74 69 61 6c 69 7a  I3REF: Initializ
f8f0: 65 20 54 68 65 20 53 51 4c 69 74 65 20 4c 69 62  e The SQLite Lib
f900: 72 61 72 79 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  rary.**.** ^The 
f910: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
f920: 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 69 6e 69  ze() routine ini
f930: 74 69 61 6c 69 7a 65 73 20 74 68 65 0a 2a 2a 20  tializes the.** 
f940: 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 2e 20  SQLite library. 
f950: 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 68   ^The sqlite3_sh
f960: 75 74 64 6f 77 6e 28 29 20 72 6f 75 74 69 6e 65  utdown() routine
f970: 0a 2a 2a 20 64 65 61 6c 6c 6f 63 61 74 65 73 20  .** deallocates 
f980: 61 6e 79 20 72 65 73 6f 75 72 63 65 73 20 74 68  any resources th
f990: 61 74 20 77 65 72 65 20 61 6c 6c 6f 63 61 74 65  at were allocate
f9a0: 64 20 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 69  d by sqlite3_ini
f9b0: 74 69 61 6c 69 7a 65 28 29 2e 0a 2a 2a 20 54 68  tialize()..** Th
f9c0: 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65  ese routines are
f9d0: 20 64 65 73 69 67 6e 65 64 20 74 6f 20 61 69 64   designed to aid
f9e0: 20 69 6e 20 70 72 6f 63 65 73 73 20 69 6e 69 74   in process init
f9f0: 69 61 6c 69 7a 61 74 69 6f 6e 20 61 6e 64 0a 2a  ialization and.*
fa00: 2a 20 73 68 75 74 64 6f 77 6e 20 6f 6e 20 65 6d  * shutdown on em
fa10: 62 65 64 64 65 64 20 73 79 73 74 65 6d 73 2e 20  bedded systems. 
fa20: 20 57 6f 72 6b 73 74 61 74 69 6f 6e 20 61 70 70   Workstation app
fa30: 6c 69 63 61 74 69 6f 6e 73 20 75 73 69 6e 67 0a  lications using.
fa40: 2a 2a 20 53 51 4c 69 74 65 20 6e 6f 72 6d 61 6c  ** SQLite normal
fa50: 6c 79 20 64 6f 20 6e 6f 74 20 6e 65 65 64 20 74  ly do not need t
fa60: 6f 20 69 6e 76 6f 6b 65 20 65 69 74 68 65 72 20  o invoke either 
fa70: 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  of these routine
fa80: 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20  s..**.** A call 
fa90: 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  to sqlite3_initi
faa0: 61 6c 69 7a 65 28 29 20 69 73 20 61 6e 20 22 65  alize() is an "e
fab0: 66 66 65 63 74 69 76 65 22 20 63 61 6c 6c 20 69  ffective" call i
fac0: 66 20 69 74 20 69 73 0a 2a 2a 20 74 68 65 20 66  f it is.** the f
fad0: 69 72 73 74 20 74 69 6d 65 20 73 71 6c 69 74 65  irst time sqlite
fae0: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69  3_initialize() i
faf0: 73 20 69 6e 76 6f 6b 65 64 20 64 75 72 69 6e 67  s invoked during
fb00: 20 74 68 65 20 6c 69 66 65 74 69 6d 65 20 6f 66   the lifetime of
fb10: 0a 2a 2a 20 74 68 65 20 70 72 6f 63 65 73 73 2c  .** the process,
fb20: 20 6f 72 20 69 66 20 69 74 20 69 73 20 74 68 65   or if it is the
fb30: 20 66 69 72 73 74 20 74 69 6d 65 20 73 71 6c 69   first time sqli
fb40: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
fb50: 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 66   is invoked.** f
fb60: 6f 6c 6c 6f 77 69 6e 67 20 61 20 63 61 6c 6c 20  ollowing a call 
fb70: 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64  to sqlite3_shutd
fb80: 6f 77 6e 28 29 2e 20 20 5e 28 4f 6e 6c 79 20 61  own().  ^(Only a
fb90: 6e 20 65 66 66 65 63 74 69 76 65 20 63 61 6c 6c  n effective call
fba0: 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f 69  .** of sqlite3_i
fbb0: 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 6f 65 73  nitialize() does
fbc0: 20 61 6e 79 20 69 6e 69 74 69 61 6c 69 7a 61 74   any initializat
fbd0: 69 6f 6e 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20  ion.  All other 
fbe0: 63 61 6c 6c 73 0a 2a 2a 20 61 72 65 20 68 61 72  calls.** are har
fbf0: 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e 29 5e 0a  mless no-ops.)^.
fc00: 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20  **.** A call to 
fc10: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
fc20: 28 29 20 69 73 20 61 6e 20 22 65 66 66 65 63 74  () is an "effect
fc30: 69 76 65 22 20 63 61 6c 6c 20 69 66 20 69 74 20  ive" call if it 
fc40: 69 73 20 74 68 65 20 66 69 72 73 74 0a 2a 2a 20  is the first.** 
fc50: 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f  call to sqlite3_
fc60: 73 68 75 74 64 6f 77 6e 28 29 20 73 69 6e 63 65  shutdown() since
fc70: 20 74 68 65 20 6c 61 73 74 20 73 71 6c 69 74 65   the last sqlite
fc80: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 2e 20  3_initialize(). 
fc90: 20 5e 28 4f 6e 6c 79 0a 2a 2a 20 61 6e 20 65 66   ^(Only.** an ef
fca0: 66 65 63 74 69 76 65 20 63 61 6c 6c 20 74 6f 20  fective call to 
fcb0: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
fcc0: 28 29 20 64 6f 65 73 20 61 6e 79 20 64 65 69 6e  () does any dein
fcd0: 69 74 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a  itialization..**
fce0: 20 41 6c 6c 20 6f 74 68 65 72 20 76 61 6c 69 64   All other valid
fcf0: 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65   calls to sqlite
fd00: 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 61 72 65  3_shutdown() are
fd10: 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73   harmless no-ops
fd20: 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  .)^.**.** The sq
fd30: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
fd40: 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  () interface is 
fd50: 74 68 72 65 61 64 73 61 66 65 2c 20 62 75 74 20  threadsafe, but 
fd60: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
fd70: 28 29 0a 2a 2a 20 69 73 20 6e 6f 74 2e 20 20 54  ().** is not.  T
fd80: 68 65 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64  he sqlite3_shutd
fd90: 6f 77 6e 28 29 20 69 6e 74 65 72 66 61 63 65 20  own() interface 
fda0: 6d 75 73 74 20 6f 6e 6c 79 20 62 65 20 63 61 6c  must only be cal
fdb0: 6c 65 64 20 66 72 6f 6d 20 61 0a 2a 2a 20 73 69  led from a.** si
fdc0: 6e 67 6c 65 20 74 68 72 65 61 64 2e 20 20 41 6c  ngle thread.  Al
fdd0: 6c 20 6f 70 65 6e 20 5b 64 61 74 61 62 61 73 65  l open [database
fde0: 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 6d 75   connections] mu
fdf0: 73 74 20 62 65 20 63 6c 6f 73 65 64 20 61 6e 64  st be closed and
fe00: 20 61 6c 6c 0a 2a 2a 20 6f 74 68 65 72 20 53 51   all.** other SQ
fe10: 4c 69 74 65 20 72 65 73 6f 75 72 63 65 73 20 6d  Lite resources m
fe20: 75 73 74 20 62 65 20 64 65 61 6c 6c 6f 63 61 74  ust be deallocat
fe30: 65 64 20 70 72 69 6f 72 20 74 6f 20 69 6e 76 6f  ed prior to invo
fe40: 6b 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  king.** sqlite3_
fe50: 73 68 75 74 64 6f 77 6e 28 29 2e 0a 2a 2a 0a 2a  shutdown()..**.*
fe60: 2a 20 41 6d 6f 6e 67 20 6f 74 68 65 72 20 74 68  * Among other th
fe70: 69 6e 67 73 2c 20 5e 73 71 6c 69 74 65 33 5f 69  ings, ^sqlite3_i
fe80: 6e 69 74 69 61 6c 69 7a 65 28 29 20 77 69 6c 6c  nitialize() will
fe90: 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74   invoke.** sqlit
fea0: 65 33 5f 6f 73 5f 69 6e 69 74 28 29 2e 20 20 53  e3_os_init().  S
feb0: 69 6d 69 6c 61 72 6c 79 2c 20 5e 73 71 6c 69 74  imilarly, ^sqlit
fec0: 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 0a 2a 2a  e3_shutdown().**
fed0: 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 73 71 6c   will invoke sql
fee0: 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 2e 0a 2a  ite3_os_end()..*
fef0: 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
ff00: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 72  3_initialize() r
ff10: 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 5b  outine returns [
ff20: 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75  SQLITE_OK] on su
ff30: 63 63 65 73 73 2e 0a 2a 2a 20 5e 49 66 20 66 6f  ccess..** ^If fo
ff40: 72 20 73 6f 6d 65 20 72 65 61 73 6f 6e 2c 20 73  r some reason, s
ff50: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
ff60: 65 28 29 20 69 73 20 75 6e 61 62 6c 65 20 74 6f  e() is unable to
ff70: 20 69 6e 69 74 69 61 6c 69 7a 65 0a 2a 2a 20 74   initialize.** t
ff80: 68 65 20 6c 69 62 72 61 72 79 20 28 70 65 72 68  he library (perh
ff90: 61 70 73 20 69 74 20 69 73 20 75 6e 61 62 6c 65  aps it is unable
ffa0: 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 61 20 6e   to allocate a n
ffb0: 65 65 64 65 64 20 72 65 73 6f 75 72 63 65 20 73  eeded resource s
ffc0: 75 63 68 0a 2a 2a 20 61 73 20 61 20 6d 75 74 65  uch.** as a mute
ffd0: 78 29 20 69 74 20 72 65 74 75 72 6e 73 20 61 6e  x) it returns an
ffe0: 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f 74   [error code] ot
fff0: 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45  her than [SQLITE
10000 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  _OK]..**.** ^The
10010 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
10020 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 69 73  ize() routine is
10030 20 63 61 6c 6c 65 64 20 69 6e 74 65 72 6e 61 6c   called internal
10040 6c 79 20 62 79 20 6d 61 6e 79 20 6f 74 68 65 72  ly by many other
10050 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74 65 72  .** SQLite inter
10060 66 61 63 65 73 20 73 6f 20 74 68 61 74 20 61 6e  faces so that an
10070 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 75 73 75   application usu
10080 61 6c 6c 79 20 64 6f 65 73 20 6e 6f 74 20 6e 65  ally does not ne
10090 65 64 20 74 6f 0a 2a 2a 20 69 6e 76 6f 6b 65 20  ed to.** invoke 
100a0 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
100b0 7a 65 28 29 20 64 69 72 65 63 74 6c 79 2e 20 20  ze() directly.  
100c0 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 5b 73 71  For example, [sq
100d0 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a  lite3_open()].**
100e0 20 63 61 6c 6c 73 20 73 71 6c 69 74 65 33 5f 69   calls sqlite3_i
100f0 6e 69 74 69 61 6c 69 7a 65 28 29 20 73 6f 20 74  nitialize() so t
10100 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72  he SQLite librar
10110 79 20 77 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61  y will be automa
10120 74 69 63 61 6c 6c 79 0a 2a 2a 20 69 6e 69 74 69  tically.** initi
10130 61 6c 69 7a 65 64 20 77 68 65 6e 20 5b 73 71 6c  alized when [sql
10140 69 74 65 33 5f 6f 70 65 6e 28 29 5d 20 69 73 20  ite3_open()] is 
10150 63 61 6c 6c 65 64 20 69 66 20 69 74 20 68 61 73  called if it has
10160 20 6e 6f 74 20 62 65 20 69 6e 69 74 69 61 6c 69   not be initiali
10170 7a 65 64 0a 2a 2a 20 61 6c 72 65 61 64 79 2e 20  zed.** already. 
10180 20 5e 48 6f 77 65 76 65 72 2c 20 69 66 20 53 51   ^However, if SQ
10190 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  Lite is compiled
101a0 20 77 69 74 68 20 74 68 65 20 5b 53 51 4c 49 54   with the [SQLIT
101b0 45 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e 49 54 5d  E_OMIT_AUTOINIT]
101c0 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  .** compile-time
101d0 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68   option, then th
101e0 65 20 61 75 74 6f 6d 61 74 69 63 20 63 61 6c 6c  e automatic call
101f0 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e 69  s to sqlite3_ini
10200 74 69 61 6c 69 7a 65 28 29 0a 2a 2a 20 61 72 65  tialize().** are
10210 20 6f 6d 69 74 74 65 64 20 61 6e 64 20 74 68 65   omitted and the
10220 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73   application mus
10230 74 20 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f 69  t call sqlite3_i
10240 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 69 72 65  nitialize() dire
10250 63 74 6c 79 0a 2a 2a 20 70 72 69 6f 72 20 74 6f  ctly.** prior to
10260 20 75 73 69 6e 67 20 61 6e 79 20 6f 74 68 65 72   using any other
10270 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63   SQLite interfac
10280 65 2e 20 20 46 6f 72 20 6d 61 78 69 6d 75 6d 20  e.  For maximum 
10290 70 6f 72 74 61 62 69 6c 69 74 79 2c 0a 2a 2a 20  portability,.** 
102a0 69 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65  it is recommende
102b0 64 20 74 68 61 74 20 61 70 70 6c 69 63 61 74 69  d that applicati
102c0 6f 6e 73 20 61 6c 77 61 79 73 20 69 6e 76 6f 6b  ons always invok
102d0 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  e sqlite3_initia
102e0 6c 69 7a 65 28 29 0a 2a 2a 20 64 69 72 65 63 74  lize().** direct
102f0 6c 79 20 70 72 69 6f 72 20 74 6f 20 75 73 69 6e  ly prior to usin
10300 67 20 61 6e 79 20 6f 74 68 65 72 20 53 51 4c 69  g any other SQLi
10310 74 65 20 69 6e 74 65 72 66 61 63 65 2e 20 20 46  te interface.  F
10320 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 0a 2a  uture releases.*
10330 2a 20 6f 66 20 53 51 4c 69 74 65 20 6d 61 79 20  * of SQLite may 
10340 72 65 71 75 69 72 65 20 74 68 69 73 2e 20 20 49  require this.  I
10350 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74  n other words, t
10360 68 65 20 62 65 68 61 76 69 6f 72 20 65 78 68 69  he behavior exhi
10370 62 69 74 65 64 0a 2a 2a 20 77 68 65 6e 20 53 51  bited.** when SQ
10380 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  Lite is compiled
10390 20 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 4f 4d   with [SQLITE_OM
103a0 49 54 5f 41 55 54 4f 49 4e 49 54 5d 20 6d 69 67  IT_AUTOINIT] mig
103b0 68 74 20 62 65 63 6f 6d 65 20 74 68 65 0a 2a 2a  ht become the.**
103c0 20 64 65 66 61 75 6c 74 20 62 65 68 61 76 69 6f   default behavio
103d0 72 20 69 6e 20 73 6f 6d 65 20 66 75 74 75 72 65  r in some future
103e0 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69   release of SQLi
103f0 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  te..**.** The sq
10400 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20  lite3_os_init() 
10410 72 6f 75 74 69 6e 65 20 64 6f 65 73 20 6f 70 65  routine does ope
10420 72 61 74 69 6e 67 2d 73 79 73 74 65 6d 20 73 70  rating-system sp
10430 65 63 69 66 69 63 0a 2a 2a 20 69 6e 69 74 69 61  ecific.** initia
10440 6c 69 7a 61 74 69 6f 6e 20 6f 66 20 74 68 65 20  lization of the 
10450 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 2e 20  SQLite library. 
10460 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f   The sqlite3_os_
10470 65 6e 64 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65  end().** routine
10480 20 75 6e 64 6f 65 73 20 74 68 65 20 65 66 66 65   undoes the effe
10490 63 74 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 73  ct of sqlite3_os
104a0 5f 69 6e 69 74 28 29 2e 20 20 54 79 70 69 63 61  _init().  Typica
104b0 6c 20 74 61 73 6b 73 0a 2a 2a 20 70 65 72 66 6f  l tasks.** perfo
104c0 72 6d 65 64 20 62 79 20 74 68 65 73 65 20 72 6f  rmed by these ro
104d0 75 74 69 6e 65 73 20 69 6e 63 6c 75 64 65 20 61  utines include a
104e0 6c 6c 6f 63 61 74 69 6f 6e 20 6f 72 20 64 65 61  llocation or dea
104f0 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20  llocation.** of 
10500 73 74 61 74 69 63 20 72 65 73 6f 75 72 63 65 73  static resources
10510 2c 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e  , initialization
10520 20 6f 66 20 67 6c 6f 62 61 6c 20 76 61 72 69 61   of global varia
10530 62 6c 65 73 2c 0a 2a 2a 20 73 65 74 74 69 6e 67  bles,.** setting
10540 20 75 70 20 61 20 64 65 66 61 75 6c 74 20 5b 73   up a default [s
10550 71 6c 69 74 65 33 5f 76 66 73 5d 20 6d 6f 64 75  qlite3_vfs] modu
10560 6c 65 2c 20 6f 72 20 73 65 74 74 69 6e 67 20 75  le, or setting u
10570 70 0a 2a 2a 20 61 20 64 65 66 61 75 6c 74 20 63  p.** a default c
10580 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 75 73 69  onfiguration usi
10590 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  ng [sqlite3_conf
105a0 69 67 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ig()]..**.** The
105b0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f   application sho
105c0 75 6c 64 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65  uld never invoke
105d0 20 65 69 74 68 65 72 20 73 71 6c 69 74 65 33 5f   either sqlite3_
105e0 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a 20 6f 72 20  os_init().** or 
105f0 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29  sqlite3_os_end()
10600 20 64 69 72 65 63 74 6c 79 2e 20 20 54 68 65 20   directly.  The 
10610 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75  application shou
10620 6c 64 20 6f 6e 6c 79 20 69 6e 76 6f 6b 65 0a 2a  ld only invoke.*
10630 2a 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  * sqlite3_initia
10640 6c 69 7a 65 28 29 20 61 6e 64 20 73 71 6c 69 74  lize() and sqlit
10650 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20  e3_shutdown().  
10660 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69  The sqlite3_os_i
10670 6e 69 74 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61  nit().** interfa
10680 63 65 20 69 73 20 63 61 6c 6c 65 64 20 61 75 74  ce is called aut
10690 6f 6d 61 74 69 63 61 6c 6c 79 20 62 79 20 73 71  omatically by sq
106a0 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
106b0 28 29 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65  () and.** sqlite
106c0 33 5f 6f 73 5f 65 6e 64 28 29 20 69 73 20 63 61  3_os_end() is ca
106d0 6c 6c 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  lled by sqlite3_
106e0 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 41 70 70  shutdown().  App
106f0 72 6f 70 72 69 61 74 65 0a 2a 2a 20 69 6d 70 6c  ropriate.** impl
10700 65 6d 65 6e 74 61 74 69 6f 6e 73 20 66 6f 72 20  ementations for 
10710 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28  sqlite3_os_init(
10720 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 73  ) and sqlite3_os
10730 5f 65 6e 64 28 29 0a 2a 2a 20 61 72 65 20 62 75  _end().** are bu
10740 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 20  ilt into SQLite 
10750 77 68 65 6e 20 69 74 20 69 73 20 63 6f 6d 70 69  when it is compi
10760 6c 65 64 20 66 6f 72 20 55 6e 69 78 2c 20 57 69  led for Unix, Wi
10770 6e 64 6f 77 73 2c 20 6f 72 20 4f 53 2f 32 2e 0a  ndows, or OS/2..
10780 2a 2a 20 57 68 65 6e 20 5b 63 75 73 74 6f 6d 20  ** When [custom 
10790 62 75 69 6c 64 73 20 7c 20 62 75 69 6c 74 20 66  builds | built f
107a0 6f 72 20 6f 74 68 65 72 20 70 6c 61 74 66 6f 72  or other platfor
107b0 6d 73 5d 0a 2a 2a 20 28 75 73 69 6e 67 20 74 68  ms].** (using th
107c0 65 20 5b 53 51 4c 49 54 45 5f 4f 53 5f 4f 54 48  e [SQLITE_OS_OTH
107d0 45 52 3d 31 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  ER=1] compile-ti
107e0 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e 29 20 74 68  me.** option) th
107f0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75  e application mu
10800 73 74 20 73 75 70 70 6c 79 20 61 20 73 75 69 74  st supply a suit
10810 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  able implementat
10820 69 6f 6e 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74  ion for.** sqlit
10830 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 61 6e 64  e3_os_init() and
10840 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28   sqlite3_os_end(
10850 29 2e 20 20 41 6e 20 61 70 70 6c 69 63 61 74 69  ).  An applicati
10860 6f 6e 2d 73 75 70 70 6c 69 65 64 0a 2a 2a 20 69  on-supplied.** i
10870 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
10880 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74   sqlite3_os_init
10890 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73  () or sqlite3_os
108a0 5f 65 6e 64 28 29 0a 2a 2a 20 6d 75 73 74 20 72  _end().** must r
108b0 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b  eturn [SQLITE_OK
108c0 5d 20 6f 6e 20 73 75 63 63 65 73 73 20 61 6e 64  ] on success and
108d0 20 73 6f 6d 65 20 6f 74 68 65 72 20 5b 65 72 72   some other [err
108e0 6f 72 20 63 6f 64 65 5d 20 75 70 6f 6e 0a 2a 2a  or code] upon.**
108f0 20 66 61 69 6c 75 72 65 2e 0a 2a 2f 0a 69 6e 74   failure..*/.int
10900 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
10910 69 7a 65 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73  ize(void);.int s
10920 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
10930 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74  void);.int sqlit
10940 65 33 5f 6f 73 5f 69 6e 69 74 28 76 6f 69 64 29  e3_os_init(void)
10950 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 73  ;.int sqlite3_os
10960 5f 65 6e 64 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a  _end(void);../*.
10970 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e  ** CAPI3REF: Con
10980 66 69 67 75 72 69 6e 67 20 54 68 65 20 53 51 4c  figuring The SQL
10990 69 74 65 20 4c 69 62 72 61 72 79 0a 2a 2a 0a 2a  ite Library.**.*
109a0 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f  * The sqlite3_co
109b0 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61 63 65  nfig() interface
109c0 20 69 73 20 75 73 65 64 20 74 6f 20 6d 61 6b 65   is used to make
109d0 20 67 6c 6f 62 61 6c 20 63 6f 6e 66 69 67 75 72   global configur
109e0 61 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65 73  ation.** changes
109f0 20 74 6f 20 53 51 4c 69 74 65 20 69 6e 20 6f 72   to SQLite in or
10a00 64 65 72 20 74 6f 20 74 75 6e 65 20 53 51 4c 69  der to tune SQLi
10a10 74 65 20 74 6f 20 74 68 65 20 73 70 65 63 69 66  te to the specif
10a20 69 63 20 6e 65 65 64 73 20 6f 66 0a 2a 2a 20 74  ic needs of.** t
10a30 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20  he application. 
10a40 20 54 68 65 20 64 65 66 61 75 6c 74 20 63 6f 6e   The default con
10a50 66 69 67 75 72 61 74 69 6f 6e 20 69 73 20 72 65  figuration is re
10a60 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 6d 6f  commended for mo
10a70 73 74 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f  st.** applicatio
10a80 6e 73 20 61 6e 64 20 73 6f 20 74 68 69 73 20 72  ns and so this r
10a90 6f 75 74 69 6e 65 20 69 73 20 75 73 75 61 6c 6c  outine is usuall
10aa0 79 20 6e 6f 74 20 6e 65 63 65 73 73 61 72 79 2e  y not necessary.
10ab0 20 20 49 74 20 69 73 0a 2a 2a 20 70 72 6f 76 69    It is.** provi
10ac0 64 65 64 20 74 6f 20 73 75 70 70 6f 72 74 20 72  ded to support r
10ad0 61 72 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  are applications
10ae0 20 77 69 74 68 20 75 6e 75 73 75 61 6c 20 6e 65   with unusual ne
10af0 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 54 68  eds..**.** <b>Th
10b00 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67  e sqlite3_config
10b10 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  () interface is 
10b20 6e 6f 74 20 74 68 72 65 61 64 73 61 66 65 2e 20  not threadsafe. 
10b30 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a  The application.
10b40 2a 2a 20 6d 75 73 74 20 65 6e 73 75 72 65 20 74  ** must ensure t
10b50 68 61 74 20 6e 6f 20 6f 74 68 65 72 20 53 51 4c  hat no other SQL
10b60 69 74 65 20 69 6e 74 65 72 66 61 63 65 73 20 61  ite interfaces a
10b70 72 65 20 69 6e 76 6f 6b 65 64 20 62 79 20 6f 74  re invoked by ot
10b80 68 65 72 0a 2a 2a 20 74 68 72 65 61 64 73 20 77  her.** threads w
10b90 68 69 6c 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e  hile sqlite3_con
10ba0 66 69 67 28 29 20 69 73 20 72 75 6e 6e 69 6e 67  fig() is running
10bb0 2e 3c 2f 62 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  .</b>.**.** The 
10bc0 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
10bd0 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 6d 61   interface.** ma
10be0 79 20 6f 6e 6c 79 20 62 65 20 69 6e 76 6f 6b 65  y only be invoke
10bf0 64 20 70 72 69 6f 72 20 74 6f 20 6c 69 62 72 61  d prior to libra
10c00 72 79 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f  ry initializatio
10c10 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69  n using.** [sqli
10c20 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
10c30 5d 20 6f 72 20 61 66 74 65 72 20 73 68 75 74 64  ] or after shutd
10c40 6f 77 6e 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  own by [sqlite3_
10c50 73 68 75 74 64 6f 77 6e 28 29 5d 2e 0a 2a 2a 20  shutdown()]..** 
10c60 5e 49 66 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66  ^If sqlite3_conf
10c70 69 67 28 29 20 69 73 20 63 61 6c 6c 65 64 20 61  ig() is called a
10c80 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 69 6e  fter [sqlite3_in
10c90 69 74 69 61 6c 69 7a 65 28 29 5d 20 61 6e 64 20  itialize()] and 
10ca0 62 65 66 6f 72 65 0a 2a 2a 20 5b 73 71 6c 69 74  before.** [sqlit
10cb0 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20 74  e3_shutdown()] t
10cc0 68 65 6e 20 69 74 20 77 69 6c 6c 20 72 65 74 75  hen it will retu
10cd0 72 6e 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  rn SQLITE_MISUSE
10ce0 2e 0a 2a 2a 20 4e 6f 74 65 2c 20 68 6f 77 65 76  ..** Note, howev
10cf0 65 72 2c 20 74 68 61 74 20 5e 73 71 6c 69 74 65  er, that ^sqlite
10d00 33 5f 63 6f 6e 66 69 67 28 29 20 63 61 6e 20 62  3_config() can b
10d10 65 20 63 61 6c 6c 65 64 20 61 73 20 70 61 72 74  e called as part
10d20 20 6f 66 20 74 68 65 0a 2a 2a 20 69 6d 70 6c 65   of the.** imple
10d30 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61 6e 20  mentation of an 
10d40 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
10d50 6e 65 64 20 5b 73 71 6c 69 74 65 33 5f 6f 73 5f  ned [sqlite3_os_
10d60 69 6e 69 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54  init()]..**.** T
10d70 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
10d80 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6e  t to sqlite3_con
10d90 66 69 67 28 29 20 69 73 20 61 6e 20 69 6e 74 65  fig() is an inte
10da0 67 65 72 0a 2a 2a 20 5b 63 6f 6e 66 69 67 75 72  ger.** [configur
10db0 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d 20 74 68  ation option] th
10dc0 61 74 20 64 65 74 65 72 6d 69 6e 65 73 0a 2a 2a  at determines.**
10dd0 20 77 68 61 74 20 70 72 6f 70 65 72 74 79 20 6f   what property o
10de0 66 20 53 51 4c 69 74 65 20 69 73 20 74 6f 20 62  f SQLite is to b
10df0 65 20 63 6f 6e 66 69 67 75 72 65 64 2e 20 20 53  e configured.  S
10e00 75 62 73 65 71 75 65 6e 74 20 61 72 67 75 6d 65  ubsequent argume
10e10 6e 74 73 0a 2a 2a 20 76 61 72 79 20 64 65 70 65  nts.** vary depe
10e20 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 5b 63 6f  nding on the [co
10e30 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
10e40 6f 6e 5d 0a 2a 2a 20 69 6e 20 74 68 65 20 66 69  on].** in the fi
10e50 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a  rst argument..**
10e60 0a 2a 2a 20 5e 57 68 65 6e 20 61 20 63 6f 6e 66  .** ^When a conf
10e70 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
10e80 20 69 73 20 73 65 74 2c 20 73 71 6c 69 74 65 33   is set, sqlite3
10e90 5f 63 6f 6e 66 69 67 28 29 20 72 65 74 75 72 6e  _config() return
10ea0 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a  s [SQLITE_OK]..*
10eb0 2a 20 5e 49 66 20 74 68 65 20 6f 70 74 69 6f 6e  * ^If the option
10ec0 20 69 73 20 75 6e 6b 6e 6f 77 6e 20 6f 72 20 53   is unknown or S
10ed0 51 4c 69 74 65 20 69 73 20 75 6e 61 62 6c 65 20  QLite is unable 
10ee0 74 6f 20 73 65 74 20 74 68 65 20 6f 70 74 69 6f  to set the optio
10ef0 6e 0a 2a 2a 20 74 68 65 6e 20 74 68 69 73 20 72  n.** then this r
10f00 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61  outine returns a
10f10 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72   non-zero [error
10f20 20 63 6f 64 65 5d 2e 0a 2a 2f 0a 69 6e 74 20 73   code]..*/.int s
10f30 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 69 6e  qlite3_config(in
10f40 74 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20  t, ...);../*.** 
10f50 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 67  CAPI3REF: Config
10f60 75 72 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  ure database con
10f70 6e 65 63 74 69 6f 6e 73 0a 2a 2a 20 4d 45 54 48  nections.** METH
10f80 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a  OD: sqlite3.**.*
10f90 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 64 62  * The sqlite3_db
10fa0 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66  _config() interf
10fb0 61 63 65 20 69 73 20 75 73 65 64 20 74 6f 20 6d  ace is used to m
10fc0 61 6b 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ake configuratio
10fd0 6e 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f 20  n.** changes to 
10fe0 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  a [database conn
10ff0 65 63 74 69 6f 6e 5d 2e 20 20 54 68 65 20 69 6e  ection].  The in
11000 74 65 72 66 61 63 65 20 69 73 20 73 69 6d 69 6c  terface is simil
11010 61 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  ar to.** [sqlite
11020 33 5f 63 6f 6e 66 69 67 28 29 5d 20 65 78 63 65  3_config()] exce
11030 70 74 20 74 68 61 74 20 74 68 65 20 63 68 61 6e  pt that the chan
11040 67 65 73 20 61 70 70 6c 79 20 74 6f 20 61 20 73  ges apply to a s
11050 69 6e 67 6c 65 0a 2a 2a 20 5b 64 61 74 61 62 61  ingle.** [databa
11060 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28  se connection] (
11070 73 70 65 63 69 66 69 65 64 20 69 6e 20 74 68 65  specified in the
11080 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 29   first argument)
11090 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f  ..**.** The seco
110a0 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73  nd argument to s
110b0 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67  qlite3_db_config
110c0 28 44 2c 56 2c 2e 2e 2e 29 20 20 69 73 20 74 68  (D,V,...)  is th
110d0 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 42 43  e.** [SQLITE_DBC
110e0 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20  ONFIG_LOOKASIDE 
110f0 7c 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  | configuration 
11100 76 65 72 62 5d 20 2d 20 61 6e 20 69 6e 74 65 67  verb] - an integ
11110 65 72 20 63 6f 64 65 20 0a 2a 2a 20 74 68 61 74  er code .** that
11120 20 69 6e 64 69 63 61 74 65 73 20 77 68 61 74 20   indicates what 
11130 61 73 70 65 63 74 20 6f 66 20 74 68 65 20 5b 64  aspect of the [d
11140 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
11150 6f 6e 5d 20 69 73 20 62 65 69 6e 67 20 63 6f 6e  on] is being con
11160 66 69 67 75 72 65 64 2e 0a 2a 2a 20 53 75 62 73  figured..** Subs
11170 65 71 75 65 6e 74 20 61 72 67 75 6d 65 6e 74 73  equent arguments
11180 20 76 61 72 79 20 64 65 70 65 6e 64 69 6e 67 20   vary depending 
11190 6f 6e 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61  on the configura
111a0 74 69 6f 6e 20 76 65 72 62 2e 0a 2a 2a 0a 2a 2a  tion verb..**.**
111b0 20 5e 43 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74   ^Calls to sqlit
111c0 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 20 72  e3_db_config() r
111d0 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4f 4b 20  eturn SQLITE_OK 
111e0 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a  if and only if.*
111f0 2a 20 74 68 65 20 63 61 6c 6c 20 69 73 20 63 6f  * the call is co
11200 6e 73 69 64 65 72 65 64 20 73 75 63 63 65 73 73  nsidered success
11210 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ful..*/.int sqli
11220 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 73 71  te3_db_config(sq
11230 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6f 70 2c 20  lite3*, int op, 
11240 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ...);../*.** CAP
11250 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c  I3REF: Memory Al
11260 6c 6f 63 61 74 69 6f 6e 20 52 6f 75 74 69 6e 65  location Routine
11270 73 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61  s.**.** An insta
11280 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65  nce of this obje
11290 63 74 20 64 65 66 69 6e 65 73 20 74 68 65 20 69  ct defines the i
112a0 6e 74 65 72 66 61 63 65 20 62 65 74 77 65 65 6e  nterface between
112b0 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 6c   SQLite.** and l
112c0 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72 79 20  ow-level memory 
112d0 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69  allocation routi
112e0 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  nes..**.** This 
112f0 6f 62 6a 65 63 74 20 69 73 20 75 73 65 64 20 69  object is used i
11300 6e 20 6f 6e 6c 79 20 6f 6e 65 20 70 6c 61 63 65  n only one place
11310 20 69 6e 20 74 68 65 20 53 51 4c 69 74 65 20 69   in the SQLite i
11320 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20 41 20 70  nterface..** A p
11330 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73  ointer to an ins
11340 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62  tance of this ob
11350 6a 65 63 74 20 69 73 20 74 68 65 20 61 72 67 75  ject is the argu
11360 6d 65 6e 74 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  ment to.** [sqli
11370 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 68  te3_config()] wh
11380 65 6e 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61  en the configura
11390 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 0a 2a  tion option is.*
113a0 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  * [SQLITE_CONFIG
113b0 5f 4d 41 4c 4c 4f 43 5d 20 6f 72 20 5b 53 51 4c  _MALLOC] or [SQL
113c0 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41  ITE_CONFIG_GETMA
113d0 4c 4c 4f 43 5d 2e 20 20 0a 2a 2a 20 42 79 20 63  LLOC].  .** By c
113e0 72 65 61 74 69 6e 67 20 61 6e 20 69 6e 73 74 61  reating an insta
113f0 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65  nce of this obje
11400 63 74 0a 2a 2a 20 61 6e 64 20 70 61 73 73 69 6e  ct.** and passin
11410 67 20 69 74 20 74 6f 20 5b 73 71 6c 69 74 65 33  g it to [sqlite3
11420 5f 63 6f 6e 66 69 67 5d 28 5b 53 51 4c 49 54 45  _config]([SQLITE
11430 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 29  _CONFIG_MALLOC])
11440 0a 2a 2a 20 64 75 72 69 6e 67 20 63 6f 6e 66 69  .** during confi
11450 67 75 72 61 74 69 6f 6e 2c 20 61 6e 20 61 70 70  guration, an app
11460 6c 69 63 61 74 69 6f 6e 20 63 61 6e 20 73 70 65  lication can spe
11470 63 69 66 79 20 61 6e 20 61 6c 74 65 72 6e 61 74  cify an alternat
11480 69 76 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c  ive.** memory al
11490 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73 79 73 74  location subsyst
114a0 65 6d 20 66 6f 72 20 53 51 4c 69 74 65 20 74 6f  em for SQLite to
114b0 20 75 73 65 20 66 6f 72 20 61 6c 6c 20 6f 66 20   use for all of 
114c0 69 74 73 0a 2a 2a 20 64 79 6e 61 6d 69 63 20 6d  its.** dynamic m
114d0 65 6d 6f 72 79 20 6e 65 65 64 73 2e 0a 2a 2a 0a  emory needs..**.
114e0 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 53 51 4c  ** Note that SQL
114f0 69 74 65 20 63 6f 6d 65 73 20 77 69 74 68 20 73  ite comes with s
11500 65 76 65 72 61 6c 20 5b 62 75 69 6c 74 2d 69 6e  everal [built-in
11510 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f   memory allocato
11520 72 73 5d 0a 2a 2a 20 74 68 61 74 20 61 72 65 20  rs].** that are 
11530 70 65 72 66 65 63 74 6c 79 20 61 64 65 71 75 61  perfectly adequa
11540 74 65 20 66 6f 72 20 74 68 65 20 6f 76 65 72 77  te for the overw
11550 68 65 6c 6d 69 6e 67 20 6d 61 6a 6f 72 69 74 79  helming majority
11560 20 6f 66 20 61 70 70 6c 69 63 61 74 69 6f 6e 73   of applications
11570 0a 2a 2a 20 61 6e 64 20 74 68 61 74 20 74 68 69  .** and that thi
11580 73 20 6f 62 6a 65 63 74 20 69 73 20 6f 6e 6c 79  s object is only
11590 20 75 73 65 66 75 6c 20 74 6f 20 61 20 74 69 6e   useful to a tin
115a0 79 20 6d 69 6e 6f 72 69 74 79 20 6f 66 20 61 70  y minority of ap
115b0 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 77 69  plications.** wi
115c0 74 68 20 73 70 65 63 69 61 6c 69 7a 65 64 20 6d  th specialized m
115d0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
115e0 20 72 65 71 75 69 72 65 6d 65 6e 74 73 2e 20 20   requirements.  
115f0 54 68 69 73 20 6f 62 6a 65 63 74 20 69 73 0a 2a  This object is.*
11600 2a 20 61 6c 73 6f 20 75 73 65 64 20 64 75 72 69  * also used duri
11610 6e 67 20 74 65 73 74 69 6e 67 20 6f 66 20 53 51  ng testing of SQ
11620 4c 69 74 65 20 69 6e 20 6f 72 64 65 72 20 74 6f  Lite in order to
11630 20 73 70 65 63 69 66 79 20 61 6e 20 61 6c 74 65   specify an alte
11640 72 6e 61 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f 72  rnative.** memor
11650 79 20 61 6c 6c 6f 63 61 74 6f 72 20 74 68 61 74  y allocator that
11660 20 73 69 6d 75 6c 61 74 65 73 20 6d 65 6d 6f 72   simulates memor
11670 79 20 6f 75 74 2d 6f 66 2d 6d 65 6d 6f 72 79 20  y out-of-memory 
11680 63 6f 6e 64 69 74 69 6f 6e 73 20 69 6e 0a 2a 2a  conditions in.**
11690 20 6f 72 64 65 72 20 74 6f 20 76 65 72 69 66 79   order to verify
116a0 20 74 68 61 74 20 53 51 4c 69 74 65 20 72 65 63   that SQLite rec
116b0 6f 76 65 72 73 20 67 72 61 63 65 66 75 6c 6c 79  overs gracefully
116c0 20 66 72 6f 6d 20 73 75 63 68 0a 2a 2a 20 63 6f   from such.** co
116d0 6e 64 69 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20  nditions..**.** 
116e0 54 68 65 20 78 4d 61 6c 6c 6f 63 2c 20 78 52 65  The xMalloc, xRe
116f0 61 6c 6c 6f 63 2c 20 61 6e 64 20 78 46 72 65 65  alloc, and xFree
11700 20 6d 65 74 68 6f 64 73 20 6d 75 73 74 20 77 6f   methods must wo
11710 72 6b 20 6c 69 6b 65 20 74 68 65 0a 2a 2a 20 6d  rk like the.** m
11720 61 6c 6c 6f 63 28 29 2c 20 72 65 61 6c 6c 6f 63  alloc(), realloc
11730 28 29 20 61 6e 64 20 66 72 65 65 28 29 20 66 75  () and free() fu
11740 6e 63 74 69 6f 6e 73 20 66 72 6f 6d 20 74 68 65  nctions from the
11750 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72   standard C libr
11760 61 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20  ary..** ^SQLite 
11770 67 75 61 72 61 6e 74 65 65 73 20 74 68 61 74 20  guarantees that 
11780 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  the second argum
11790 65 6e 74 20 74 6f 0a 2a 2a 20 78 52 65 61 6c 6c  ent to.** xReall
117a0 6f 63 20 69 73 20 61 6c 77 61 79 73 20 61 20 76  oc is always a v
117b0 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79  alue returned by
117c0 20 61 20 70 72 69 6f 72 20 63 61 6c 6c 20 74 6f   a prior call to
117d0 20 78 52 6f 75 6e 64 75 70 2e 0a 2a 2a 0a 2a 2a   xRoundup..**.**
117e0 20 78 53 69 7a 65 20 73 68 6f 75 6c 64 20 72 65   xSize should re
117f0 74 75 72 6e 20 74 68 65 20 61 6c 6c 6f 63 61 74  turn the allocat
11800 65 64 20 73 69 7a 65 20 6f 66 20 61 20 6d 65 6d  ed size of a mem
11810 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a  ory allocation.*
11820 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 6f 62 74  * previously obt
11830 61 69 6e 65 64 20 66 72 6f 6d 20 78 4d 61 6c 6c  ained from xMall
11840 6f 63 20 6f 72 20 78 52 65 61 6c 6c 6f 63 2e 20  oc or xRealloc. 
11850 20 54 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 73   The allocated s
11860 69 7a 65 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73  ize.** is always
11870 20 61 74 20 6c 65 61 73 74 20 61 73 20 62 69 67   at least as big
11880 20 61 73 20 74 68 65 20 72 65 71 75 65 73 74 65   as the requeste
11890 64 20 73 69 7a 65 20 62 75 74 20 6d 61 79 20 62  d size but may b
118a0 65 20 6c 61 72 67 65 72 2e 0a 2a 2a 0a 2a 2a 20  e larger..**.** 
118b0 54 68 65 20 78 52 6f 75 6e 64 75 70 20 6d 65 74  The xRoundup met
118c0 68 6f 64 20 72 65 74 75 72 6e 73 20 77 68 61 74  hod returns what
118d0 20 77 6f 75 6c 64 20 62 65 20 74 68 65 20 61 6c   would be the al
118e0 6c 6f 63 61 74 65 64 20 73 69 7a 65 20 6f 66 0a  located size of.
118f0 2a 2a 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  ** a memory allo
11900 63 61 74 69 6f 6e 20 67 69 76 65 6e 20 61 20 70  cation given a p
11910 61 72 74 69 63 75 6c 61 72 20 72 65 71 75 65 73  articular reques
11920 74 65 64 20 73 69 7a 65 2e 20 20 4d 6f 73 74 20  ted size.  Most 
11930 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61  memory.** alloca
11940 74 6f 72 73 20 72 6f 75 6e 64 20 75 70 20 6d 65  tors round up me
11950 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73  mory allocations
11960 20 61 74 20 6c 65 61 73 74 20 74 6f 20 74 68 65   at least to the
11970 20 6e 65 78 74 20 6d 75 6c 74 69 70 6c 65 0a 2a   next multiple.*
11980 2a 20 6f 66 20 38 2e 20 20 53 6f 6d 65 20 61 6c  * of 8.  Some al
11990 6c 6f 63 61 74 6f 72 73 20 72 6f 75 6e 64 20 75  locators round u
119a0 70 20 74 6f 20 61 20 6c 61 72 67 65 72 20 6d 75  p to a larger mu
119b0 6c 74 69 70 6c 65 20 6f 72 20 74 6f 20 61 20 70  ltiple or to a p
119c0 6f 77 65 72 20 6f 66 20 32 2e 0a 2a 2a 20 45 76  ower of 2..** Ev
119d0 65 72 79 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ery memory alloc
119e0 61 74 69 6f 6e 20 72 65 71 75 65 73 74 20 63 6f  ation request co
119f0 6d 69 6e 67 20 69 6e 20 74 68 72 6f 75 67 68 20  ming in through 
11a00 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
11a10 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65  )].** or [sqlite
11a20 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 20 66 69 72  3_realloc()] fir
11a30 73 74 20 63 61 6c 6c 73 20 78 52 6f 75 6e 64 75  st calls xRoundu
11a40 70 2e 20 20 49 66 20 78 52 6f 75 6e 64 75 70 20  p.  If xRoundup 
11a50 72 65 74 75 72 6e 73 20 30 2c 20 0a 2a 2a 20 74  returns 0, .** t
11a60 68 61 74 20 63 61 75 73 65 73 20 74 68 65 20 63  hat causes the c
11a70 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 6d 65 6d  orresponding mem
11a80 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74  ory allocation t
11a90 6f 20 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20 54 68  o fail..**.** Th
11aa0 65 20 78 49 6e 69 74 20 6d 65 74 68 6f 64 20 69  e xInit method i
11ab0 6e 69 74 69 61 6c 69 7a 65 73 20 74 68 65 20 6d  nitializes the m
11ac0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 2e  emory allocator.
11ad0 20 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 0a 2a    For example,.*
11ae0 2a 20 69 74 20 6d 69 67 68 74 20 61 6c 6c 6f 63  * it might alloc
11af0 61 74 65 20 61 6e 79 20 72 65 71 75 69 72 65 20  ate any require 
11b00 6d 75 74 65 78 65 73 20 6f 72 20 69 6e 69 74 69  mutexes or initi
11b10 61 6c 69 7a 65 20 69 6e 74 65 72 6e 61 6c 20 64  alize internal d
11b20 61 74 61 0a 2a 2a 20 73 74 72 75 63 74 75 72 65  ata.** structure
11b30 73 2e 20 20 54 68 65 20 78 53 68 75 74 64 6f 77  s.  The xShutdow
11b40 6e 20 6d 65 74 68 6f 64 20 69 73 20 69 6e 76 6f  n method is invo
11b50 6b 65 64 20 28 69 6e 64 69 72 65 63 74 6c 79 29  ked (indirectly)
11b60 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   by.** [sqlite3_
11b70 73 68 75 74 64 6f 77 6e 28 29 5d 20 61 6e 64 20  shutdown()] and 
11b80 73 68 6f 75 6c 64 20 64 65 61 6c 6c 6f 63 61 74  should deallocat
11b90 65 20 61 6e 79 20 72 65 73 6f 75 72 63 65 73 20  e any resources 
11ba0 61 63 71 75 69 72 65 64 0a 2a 2a 20 62 79 20 78  acquired.** by x
11bb0 49 6e 69 74 2e 20 20 54 68 65 20 70 41 70 70 44  Init.  The pAppD
11bc0 61 74 61 20 70 6f 69 6e 74 65 72 20 69 73 20 75  ata pointer is u
11bd0 73 65 64 20 61 73 20 74 68 65 20 6f 6e 6c 79 20  sed as the only 
11be0 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20  parameter to.** 
11bf0 78 49 6e 69 74 20 61 6e 64 20 78 53 68 75 74 64  xInit and xShutd
11c00 6f 77 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74  own..**.** SQLit
11c10 65 20 68 6f 6c 64 73 20 74 68 65 20 5b 53 51 4c  e holds the [SQL
11c20 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43  ITE_MUTEX_STATIC
11c30 5f 4d 41 53 54 45 52 5d 20 6d 75 74 65 78 20 77  _MASTER] mutex w
11c40 68 65 6e 20 69 74 20 69 6e 76 6f 6b 65 73 0a 2a  hen it invokes.*
11c50 2a 20 74 68 65 20 78 49 6e 69 74 20 6d 65 74 68  * the xInit meth
11c60 6f 64 2c 20 73 6f 20 74 68 65 20 78 49 6e 69 74  od, so the xInit
11c70 20 6d 65 74 68 6f 64 20 6e 65 65 64 20 6e 6f 74   method need not
11c80 20 62 65 20 74 68 72 65 61 64 73 61 66 65 2e 20   be threadsafe. 
11c90 20 54 68 65 0a 2a 2a 20 78 53 68 75 74 64 6f 77   The.** xShutdow
11ca0 6e 20 6d 65 74 68 6f 64 20 69 73 20 6f 6e 6c 79  n method is only
11cb0 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 5b 73 71   called from [sq
11cc0 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
11cd0 5d 20 73 6f 20 69 74 20 64 6f 65 73 0a 2a 2a 20  ] so it does.** 
11ce0 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20 74  not need to be t
11cf0 68 72 65 61 64 73 61 66 65 20 65 69 74 68 65 72  hreadsafe either
11d00 2e 20 20 46 6f 72 20 61 6c 6c 20 6f 74 68 65 72  .  For all other
11d10 20 6d 65 74 68 6f 64 73 2c 20 53 51 4c 69 74 65   methods, SQLite
11d20 0a 2a 2a 20 68 6f 6c 64 73 20 74 68 65 20 5b 53  .** holds the [S
11d30 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54  QLITE_MUTEX_STAT
11d40 49 43 5f 4d 45 4d 5d 20 6d 75 74 65 78 20 61 73  IC_MEM] mutex as
11d50 20 6c 6f 6e 67 20 61 73 20 74 68 65 0a 2a 2a 20   long as the.** 
11d60 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
11d70 45 4d 53 54 41 54 55 53 5d 20 63 6f 6e 66 69 67  EMSTATUS] config
11d80 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69  uration option i
11d90 73 20 74 75 72 6e 65 64 20 6f 6e 20 28 77 68 69  s turned on (whi
11da0 63 68 0a 2a 2a 20 69 74 20 69 73 20 62 79 20 64  ch.** it is by d
11db0 65 66 61 75 6c 74 29 20 61 6e 64 20 73 6f 20 74  efault) and so t
11dc0 68 65 20 6d 65 74 68 6f 64 73 20 61 72 65 20 61  he methods are a
11dd0 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 73 65 72  utomatically ser
11de0 69 61 6c 69 7a 65 64 2e 0a 2a 2a 20 48 6f 77 65  ialized..** Howe
11df0 76 65 72 2c 20 69 66 20 5b 53 51 4c 49 54 45 5f  ver, if [SQLITE_
11e00 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53  CONFIG_MEMSTATUS
11e10 5d 20 69 73 20 64 69 73 61 62 6c 65 64 2c 20 74  ] is disabled, t
11e20 68 65 6e 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a  hen the other.**
11e30 20 6d 65 74 68 6f 64 73 20 6d 75 73 74 20 62 65   methods must be
11e40 20 74 68 72 65 61 64 73 61 66 65 20 6f 72 20 65   threadsafe or e
11e50 6c 73 65 20 6d 61 6b 65 20 74 68 65 69 72 20 6f  lse make their o
11e60 77 6e 20 61 72 72 61 6e 67 65 6d 65 6e 74 73 20  wn arrangements 
11e70 66 6f 72 0a 2a 2a 20 73 65 72 69 61 6c 69 7a 61  for.** serializa
11e80 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  tion..**.** SQLi
11e90 74 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 69 6e  te will never in
11ea0 76 6f 6b 65 20 78 49 6e 69 74 28 29 20 6d 6f 72  voke xInit() mor
11eb0 65 20 74 68 61 6e 20 6f 6e 63 65 20 77 69 74 68  e than once with
11ec0 6f 75 74 20 61 6e 20 69 6e 74 65 72 76 65 6e 69  out an interveni
11ed0 6e 67 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 78 53  ng.** call to xS
11ee0 68 75 74 64 6f 77 6e 28 29 2e 0a 2a 2f 0a 74 79  hutdown()..*/.ty
11ef0 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c  pedef struct sql
11f00 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73  ite3_mem_methods
11f10 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74   sqlite3_mem_met
11f20 68 6f 64 73 3b 0a 73 74 72 75 63 74 20 73 71 6c  hods;.struct sql
11f30 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73  ite3_mem_methods
11f40 20 7b 0a 20 20 76 6f 69 64 20 2a 28 2a 78 4d 61   {.  void *(*xMa
11f50 6c 6c 6f 63 29 28 69 6e 74 29 3b 20 20 20 20 20  lloc)(int);     
11f60 20 20 20 20 2f 2a 20 4d 65 6d 6f 72 79 20 61 6c      /* Memory al
11f70 6c 6f 63 61 74 69 6f 6e 20 66 75 6e 63 74 69 6f  location functio
11f80 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 28 2a 78 46  n */.  void (*xF
11f90 72 65 65 29 28 76 6f 69 64 2a 29 3b 20 20 20 20  ree)(void*);    
11fa0 20 20 20 20 20 20 2f 2a 20 46 72 65 65 20 61 20        /* Free a 
11fb0 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e  prior allocation
11fc0 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 28 2a 78 52   */.  void *(*xR
11fd0 65 61 6c 6c 6f 63 29 28 76 6f 69 64 2a 2c 69 6e  ealloc)(void*,in
11fe0 74 29 3b 20 20 2f 2a 20 52 65 73 69 7a 65 20 61  t);  /* Resize a
11ff0 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a  n allocation */.
12000 20 20 69 6e 74 20 28 2a 78 53 69 7a 65 29 28 76    int (*xSize)(v
12010 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 20 20 20  oid*);          
12020 20 2f 2a 20 52 65 74 75 72 6e 20 74 68 65 20 73   /* Return the s
12030 69 7a 65 20 6f 66 20 61 6e 20 61 6c 6c 6f 63 61  ize of an alloca
12040 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20 28 2a  tion */.  int (*
12050 78 52 6f 75 6e 64 75 70 29 28 69 6e 74 29 3b 20  xRoundup)(int); 
12060 20 20 20 20 20 20 20 20 20 2f 2a 20 52 6f 75 6e           /* Roun
12070 64 20 75 70 20 72 65 71 75 65 73 74 20 73 69 7a  d up request siz
12080 65 20 74 6f 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  e to allocation 
12090 73 69 7a 65 20 2a 2f 0a 20 20 69 6e 74 20 28 2a  size */.  int (*
120a0 78 49 6e 69 74 29 28 76 6f 69 64 2a 29 3b 20 20  xInit)(void*);  
120b0 20 20 20 20 20 20 20 20 20 2f 2a 20 49 6e 69 74           /* Init
120c0 69 61 6c 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72  ialize the memor
120d0 79 20 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20  y allocator */. 
120e0 20 76 6f 69 64 20 28 2a 78 53 68 75 74 64 6f 77   void (*xShutdow
120f0 6e 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20  n)(void*);      
12100 2f 2a 20 44 65 69 6e 69 74 69 61 6c 69 7a 65 20  /* Deinitialize 
12110 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  the memory alloc
12120 61 74 6f 72 20 2a 2f 0a 20 20 76 6f 69 64 20 2a  ator */.  void *
12130 70 41 70 70 44 61 74 61 3b 20 20 20 20 20 20 20  pAppData;       
12140 20 20 20 20 20 20 20 20 20 2f 2a 20 41 72 67 75           /* Argu
12150 6d 65 6e 74 20 74 6f 20 78 49 6e 69 74 28 29 20  ment to xInit() 
12160 61 6e 64 20 78 53 68 75 74 64 6f 77 6e 28 29 20  and xShutdown() 
12170 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  */.};../*.** CAP
12180 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 61  I3REF: Configura
12190 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a 20  tion Options.** 
121a0 4b 45 59 57 4f 52 44 53 3a 20 7b 63 6f 6e 66 69  KEYWORDS: {confi
121b0 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 7d  guration option}
121c0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e  .**.** These con
121d0 73 74 61 6e 74 73 20 61 72 65 20 74 68 65 20 61  stants are the a
121e0 76 61 69 6c 61 62 6c 65 20 69 6e 74 65 67 65 72  vailable integer
121f0 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
12200 70 74 69 6f 6e 73 20 74 68 61 74 0a 2a 2a 20 63  ptions that.** c
12210 61 6e 20 62 65 20 70 61 73 73 65 64 20 61 73 20  an be passed as 
12220 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
12230 6e 74 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74  nt to the [sqlit
12240 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74  e3_config()] int
12250 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65  erface..**.** Ne
12260 77 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  w configuration 
12270 6f 70 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 61  options may be a
12280 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72  dded in future r
12290 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74  eleases of SQLit
122a0 65 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20 63  e..** Existing c
122b0 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
122c0 69 6f 6e 73 20 6d 69 67 68 74 20 62 65 20 64 69  ions might be di
122d0 73 63 6f 6e 74 69 6e 75 65 64 2e 20 20 41 70 70  scontinued.  App
122e0 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f  lications.** sho
122f0 75 6c 64 20 63 68 65 63 6b 20 74 68 65 20 72 65  uld check the re
12300 74 75 72 6e 20 63 6f 64 65 20 66 72 6f 6d 20 5b  turn code from [
12310 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
12320 5d 20 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 74  ] to make sure t
12330 68 61 74 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20  hat.** the call 
12340 77 6f 72 6b 65 64 2e 20 20 54 68 65 20 5b 73 71  worked.  The [sq
12350 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20  lite3_config()] 
12360 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20 72  interface will r
12370 65 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a  eturn a.** non-z
12380 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d  ero [error code]
12390 20 69 66 20 61 20 64 69 73 63 6f 6e 74 69 6e 75   if a discontinu
123a0 65 64 20 6f 72 20 75 6e 73 75 70 70 6f 72 74 65  ed or unsupporte
123b0 64 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  d configuration 
123c0 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76  option.** is inv
123d0 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e  oked..**.** <dl>
123e0 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
123f0 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44  FIG_SINGLETHREAD
12400 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
12410 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41  NFIG_SINGLETHREA
12420 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  D</dt>.** <dd>Th
12430 65 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d  ere are no argum
12440 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74  ents to this opt
12450 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74 69  ion.  ^This opti
12460 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b  on sets the.** [
12470 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20  threading mode] 
12480 74 6f 20 53 69 6e 67 6c 65 2d 74 68 72 65 61 64  to Single-thread
12490 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64  .  In other word
124a0 73 2c 20 69 74 20 64 69 73 61 62 6c 65 73 0a 2a  s, it disables.*
124b0 2a 20 61 6c 6c 20 6d 75 74 65 78 69 6e 67 20 61  * all mutexing a
124c0 6e 64 20 70 75 74 73 20 53 51 4c 69 74 65 20 69  nd puts SQLite i
124d0 6e 74 6f 20 61 20 6d 6f 64 65 20 77 68 65 72 65  nto a mode where
124e0 20 69 74 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20   it can only be 
124f0 75 73 65 64 0a 2a 2a 20 62 79 20 61 20 73 69 6e  used.** by a sin
12500 67 6c 65 20 74 68 72 65 61 64 2e 20 20 20 5e 49  gle thread.   ^I
12510 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70  f SQLite is comp
12520 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65  iled with.** the
12530 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53   [SQLITE_THREADS
12540 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52  AFE | SQLITE_THR
12550 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69  EADSAFE=0] compi
12560 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74  le-time option t
12570 68 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74  hen.** it is not
12580 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 63 68 61   possible to cha
12590 6e 67 65 20 74 68 65 20 5b 74 68 72 65 61 64 69  nge the [threadi
125a0 6e 67 20 6d 6f 64 65 5d 20 66 72 6f 6d 20 69 74  ng mode] from it
125b0 73 20 64 65 66 61 75 6c 74 0a 2a 2a 20 76 61 6c  s default.** val
125c0 75 65 20 6f 66 20 53 69 6e 67 6c 65 2d 74 68 72  ue of Single-thr
125d0 65 61 64 20 61 6e 64 20 73 6f 20 5b 73 71 6c 69  ead and so [sqli
125e0 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69  te3_config()] wi
125f0 6c 6c 20 72 65 74 75 72 6e 20 0a 2a 2a 20 5b 53  ll return .** [S
12600 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20  QLITE_ERROR] if 
12610 63 61 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20  called with the 
12620 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49  SQLITE_CONFIG_SI
12630 4e 47 4c 45 54 48 52 45 41 44 0a 2a 2a 20 63 6f  NGLETHREAD.** co
12640 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
12650 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  on.</dd>.**.** [
12660 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
12670 55 4c 54 49 54 48 52 45 41 44 5d 5d 20 3c 64 74  ULTITHREAD]] <dt
12680 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  >SQLITE_CONFIG_M
12690 55 4c 54 49 54 48 52 45 41 44 3c 2f 64 74 3e 0a  ULTITHREAD</dt>.
126a0 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65  ** <dd>There are
126b0 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f   no arguments to
126c0 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e   this option.  ^
126d0 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73  This option sets
126e0 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69   the.** [threadi
126f0 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 4d 75 6c 74  ng mode] to Mult
12700 69 2d 74 68 72 65 61 64 2e 20 20 49 6e 20 6f 74  i-thread.  In ot
12710 68 65 72 20 77 6f 72 64 73 2c 20 69 74 20 64 69  her words, it di
12720 73 61 62 6c 65 73 0a 2a 2a 20 6d 75 74 65 78 69  sables.** mutexi
12730 6e 67 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20  ng on [database 
12740 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64 20  connection] and 
12750 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
12760 65 6e 74 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a  ent] objects..**
12770 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   The application
12780 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20   is responsible 
12790 66 6f 72 20 73 65 72 69 61 6c 69 7a 69 6e 67 20  for serializing 
127a0 61 63 63 65 73 73 20 74 6f 0a 2a 2a 20 5b 64 61  access to.** [da
127b0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
127c0 6e 73 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65  ns] and [prepare
127d0 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 2e 20 20  d statements].  
127e0 42 75 74 20 6f 74 68 65 72 20 6d 75 74 65 78 65  But other mutexe
127f0 73 0a 2a 2a 20 61 72 65 20 65 6e 61 62 6c 65 64  s.** are enabled
12800 20 73 6f 20 74 68 61 74 20 53 51 4c 69 74 65 20   so that SQLite 
12810 77 69 6c 6c 20 62 65 20 73 61 66 65 20 74 6f 20  will be safe to 
12820 75 73 65 20 69 6e 20 61 20 6d 75 6c 74 69 2d 74  use in a multi-t
12830 68 72 65 61 64 65 64 0a 2a 2a 20 65 6e 76 69 72  hreaded.** envir
12840 6f 6e 6d 65 6e 74 20 61 73 20 6c 6f 6e 67 20 61  onment as long a
12850 73 20 6e 6f 20 74 77 6f 20 74 68 72 65 61 64 73  s no two threads
12860 20 61 74 74 65 6d 70 74 20 74 6f 20 75 73 65 20   attempt to use 
12870 74 68 65 20 73 61 6d 65 0a 2a 2a 20 5b 64 61 74  the same.** [dat
12880 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
12890 5d 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 69  ] at the same ti
128a0 6d 65 2e 20 20 5e 49 66 20 53 51 4c 69 74 65 20  me.  ^If SQLite 
128b0 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  is compiled with
128c0 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  .** the [SQLITE_
128d0 54 48 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c  THREADSAFE | SQL
128e0 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30  ITE_THREADSAFE=0
128f0 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
12900 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74  ption then.** it
12910 20 69 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65   is not possible
12920 20 74 6f 20 73 65 74 20 74 68 65 20 4d 75 6c 74   to set the Mult
12930 69 2d 74 68 72 65 61 64 20 5b 74 68 72 65 61 64  i-thread [thread
12940 69 6e 67 20 6d 6f 64 65 5d 20 61 6e 64 0a 2a 2a  ing mode] and.**
12950 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
12960 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20  ()] will return 
12970 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69  [SQLITE_ERROR] i
12980 66 20 63 61 6c 6c 65 64 20 77 69 74 68 20 74 68  f called with th
12990 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 43 4f 4e 46  e.** SQLITE_CONF
129a0 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 20 63  IG_MULTITHREAD c
129b0 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
129c0 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ion.</dd>.**.** 
129d0 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
129e0 53 45 52 49 41 4c 49 5a 45 44 5d 5d 20 3c 64 74  SERIALIZED]] <dt
129f0 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53  >SQLITE_CONFIG_S
12a00 45 52 49 41 4c 49 5a 45 44 3c 2f 64 74 3e 0a 2a  ERIALIZED</dt>.*
12a10 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20  * <dd>There are 
12a20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20  no arguments to 
12a30 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54  this option.  ^T
12a40 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20  his option sets 
12a50 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e  the.** [threadin
12a60 67 20 6d 6f 64 65 5d 20 74 6f 20 53 65 72 69 61  g mode] to Seria
12a70 6c 69 7a 65 64 2e 20 49 6e 20 6f 74 68 65 72 20  lized. In other 
12a80 77 6f 72 64 73 2c 20 74 68 69 73 20 6f 70 74 69  words, this opti
12a90 6f 6e 20 65 6e 61 62 6c 65 73 0a 2a 2a 20 61 6c  on enables.** al
12aa0 6c 20 6d 75 74 65 78 65 73 20 69 6e 63 6c 75 64  l mutexes includ
12ab0 69 6e 67 20 74 68 65 20 72 65 63 75 72 73 69 76  ing the recursiv
12ac0 65 0a 2a 2a 20 6d 75 74 65 78 65 73 20 6f 6e 20  e.** mutexes on 
12ad0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
12ae0 74 69 6f 6e 5d 20 61 6e 64 20 5b 70 72 65 70 61  tion] and [prepa
12af0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f  red statement] o
12b00 62 6a 65 63 74 73 2e 0a 2a 2a 20 49 6e 20 74 68  bjects..** In th
12b10 69 73 20 6d 6f 64 65 20 28 77 68 69 63 68 20 69  is mode (which i
12b20 73 20 74 68 65 20 64 65 66 61 75 6c 74 20 77 68  s the default wh
12b30 65 6e 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  en SQLite is com
12b40 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 5b 53  piled with.** [S
12b50 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
12b60 3d 31 5d 29 20 74 68 65 20 53 51 4c 69 74 65 20  =1]) the SQLite 
12b70 6c 69 62 72 61 72 79 20 77 69 6c 6c 20 69 74 73  library will its
12b80 65 6c 66 20 73 65 72 69 61 6c 69 7a 65 20 61 63  elf serialize ac
12b90 63 65 73 73 0a 2a 2a 20 74 6f 20 5b 64 61 74 61  cess.** to [data
12ba0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  base connections
12bb0 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20  ] and [prepared 
12bc0 73 74 61 74 65 6d 65 6e 74 73 5d 20 73 6f 20 74  statements] so t
12bd0 68 61 74 20 74 68 65 0a 2a 2a 20 61 70 70 6c 69  hat the.** appli
12be0 63 61 74 69 6f 6e 20 69 73 20 66 72 65 65 20 74  cation is free t
12bf0 6f 20 75 73 65 20 74 68 65 20 73 61 6d 65 20 5b  o use the same [
12c00 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
12c10 69 6f 6e 5d 20 6f 72 20 74 68 65 0a 2a 2a 20 73  ion] or the.** s
12c20 61 6d 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  ame [prepared st
12c30 61 74 65 6d 65 6e 74 5d 20 69 6e 20 64 69 66 66  atement] in diff
12c40 65 72 65 6e 74 20 74 68 72 65 61 64 73 20 61 74  erent threads at
12c50 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 2e 0a   the same time..
12c60 2a 2a 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73  ** ^If SQLite is
12c70 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a   compiled with.*
12c80 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48  * the [SQLITE_TH
12c90 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54  READSAFE | SQLIT
12ca0 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20  E_THREADSAFE=0] 
12cb0 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
12cc0 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69  ion then.** it i
12cd0 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 74  s not possible t
12ce0 6f 20 73 65 74 20 74 68 65 20 53 65 72 69 61 6c  o set the Serial
12cf0 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e 67 20  ized [threading 
12d00 6d 6f 64 65 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71  mode] and.** [sq
12d10 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20  lite3_config()] 
12d20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c  will return [SQL
12d30 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 63 61  ITE_ERROR] if ca
12d40 6c 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a  lled with the.**
12d50 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53   SQLITE_CONFIG_S
12d60 45 52 49 41 4c 49 5a 45 44 20 63 6f 6e 66 69 67  ERIALIZED config
12d70 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c  uration option.<
12d80 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
12d90 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f  ITE_CONFIG_MALLO
12da0 43 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  C]] <dt>SQLITE_C
12db0 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 3c 2f 64 74  ONFIG_MALLOC</dt
12dc0 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20  >.** <dd> ^(The 
12dd0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41  SQLITE_CONFIG_MA
12de0 4c 4c 4f 43 20 6f 70 74 69 6f 6e 20 74 61 6b 65  LLOC option take
12df0 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d  s a single argum
12e00 65 6e 74 20 77 68 69 63 68 20 69 73 20 0a 2a 2a  ent which is .**
12e10 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
12e20 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65   instance of the
12e30 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65   [sqlite3_mem_me
12e40 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65  thods] structure
12e50 2e 0a 2a 2a 20 54 68 65 20 61 72 67 75 6d 65 6e  ..** The argumen
12e60 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 61  t specifies.** a
12e70 6c 74 65 72 6e 61 74 69 76 65 20 6c 6f 77 2d 6c  lternative low-l
12e80 65 76 65 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  evel memory allo
12e90 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 20  cation routines 
12ea0 74 6f 20 62 65 20 75 73 65 64 20 69 6e 20 70 6c  to be used in pl
12eb0 61 63 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6d 65  ace of.** the me
12ec0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
12ed0 72 6f 75 74 69 6e 65 73 20 62 75 69 6c 74 20 69  routines built i
12ee0 6e 74 6f 20 53 51 4c 69 74 65 2e 29 5e 20 5e 53  nto SQLite.)^ ^S
12ef0 51 4c 69 74 65 20 6d 61 6b 65 73 0a 2a 2a 20 69  QLite makes.** i
12f00 74 73 20 6f 77 6e 20 70 72 69 76 61 74 65 20 63  ts own private c
12f10 6f 70 79 20 6f 66 20 74 68 65 20 63 6f 6e 74 65  opy of the conte
12f20 6e 74 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  nt of the [sqlit
12f30 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20  e3_mem_methods] 
12f40 73 74 72 75 63 74 75 72 65 0a 2a 2a 20 62 65 66  structure.** bef
12f50 6f 72 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33  ore the [sqlite3
12f60 5f 63 6f 6e 66 69 67 28 29 5d 20 63 61 6c 6c 20  _config()] call 
12f70 72 65 74 75 72 6e 73 2e 3c 2f 64 64 3e 0a 2a 2a  returns.</dd>.**
12f80 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
12f90 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 5d 5d 20  FIG_GETMALLOC]] 
12fa0 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
12fb0 47 5f 47 45 54 4d 41 4c 4c 4f 43 3c 2f 64 74 3e  G_GETMALLOC</dt>
12fc0 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 53  .** <dd> ^(The S
12fd0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
12fe0 4d 41 4c 4c 4f 43 20 6f 70 74 69 6f 6e 20 74 61  MALLOC option ta
12ff0 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67  kes a single arg
13000 75 6d 65 6e 74 20 77 68 69 63 68 0a 2a 2a 20 69  ument which.** i
13010 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
13020 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  n instance of th
13030 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d  e [sqlite3_mem_m
13040 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72  ethods] structur
13050 65 2e 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74  e..** The [sqlit
13060 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 0a  e3_mem_methods].
13070 2a 2a 20 73 74 72 75 63 74 75 72 65 20 69 73 20  ** structure is 
13080 66 69 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20  filled with the 
13090 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65  currently define
130a0 64 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  d memory allocat
130b0 69 6f 6e 20 72 6f 75 74 69 6e 65 73 2e 29 5e 0a  ion routines.)^.
130c0 2a 2a 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 63  ** This option c
130d0 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f 76  an be used to ov
130e0 65 72 6c 6f 61 64 20 74 68 65 20 64 65 66 61 75  erload the defau
130f0 6c 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  lt memory alloca
13100 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65 73  tion.** routines
13110 20 77 69 74 68 20 61 20 77 72 61 70 70 65 72 20   with a wrapper 
13120 74 68 61 74 20 73 69 6d 75 6c 61 74 69 6f 6e 73  that simulations
13130 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
13140 6f 6e 20 66 61 69 6c 75 72 65 20 6f 72 0a 2a 2a  on failure or.**
13150 20 74 72 61 63 6b 73 20 6d 65 6d 6f 72 79 20 75   tracks memory u
13160 73 61 67 65 2c 20 66 6f 72 20 65 78 61 6d 70 6c  sage, for exampl
13170 65 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  e. </dd>.**.** [
13180 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
13190 45 4d 53 54 41 54 55 53 5d 5d 20 3c 64 74 3e 53  EMSTATUS]] <dt>S
131a0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d  QLITE_CONFIG_MEM
131b0 53 54 41 54 55 53 3c 2f 64 74 3e 0a 2a 2a 20 3c  STATUS</dt>.** <
131c0 64 64 3e 20 5e 54 68 65 20 53 51 4c 49 54 45 5f  dd> ^The SQLITE_
131d0 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53  CONFIG_MEMSTATUS
131e0 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 73 69   option takes si
131f0 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 6f 66  ngle argument of
13200 20 74 79 70 65 20 69 6e 74 2c 0a 2a 2a 20 69 6e   type int,.** in
13210 74 65 72 70 72 65 74 65 64 20 61 73 20 61 20 62  terpreted as a b
13220 6f 6f 6c 65 61 6e 2c 20 77 68 69 63 68 20 65 6e  oolean, which en
13230 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62 6c 65  ables or disable
13240 73 20 74 68 65 20 63 6f 6c 6c 65 63 74 69 6f 6e  s the collection
13250 20 6f 66 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c   of.** memory al
13260 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 69 73 74  location statist
13270 69 63 73 2e 20 5e 28 57 68 65 6e 20 6d 65 6d 6f  ics. ^(When memo
13280 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74  ry allocation st
13290 61 74 69 73 74 69 63 73 20 61 72 65 0a 2a 2a 20  atistics are.** 
132a0 64 69 73 61 62 6c 65 64 2c 20 74 68 65 20 66 6f  disabled, the fo
132b0 6c 6c 6f 77 69 6e 67 20 53 51 4c 69 74 65 20 69  llowing SQLite i
132c0 6e 74 65 72 66 61 63 65 73 20 62 65 63 6f 6d 65  nterfaces become
132d0 20 6e 6f 6e 2d 6f 70 65 72 61 74 69 6f 6e 61 6c   non-operational
132e0 3a 0a 2a 2a 20 20 20 3c 75 6c 3e 0a 2a 2a 20 20  :.**   <ul>.**  
132f0 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 6d   <li> [sqlite3_m
13300 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 0a 2a 2a  emory_used()].**
13310 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33     <li> [sqlite3
13320 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65  _memory_highwate
13330 72 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b  r()].**   <li> [
13340 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65 61  sqlite3_soft_hea
13350 70 5f 6c 69 6d 69 74 36 34 28 29 5d 0a 2a 2a 20  p_limit64()].** 
13360 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f    <li> [sqlite3_
13370 73 74 61 74 75 73 36 34 28 29 5d 0a 2a 2a 20 20  status64()].**  
13380 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 20 5e 4d 65 6d   </ul>)^.** ^Mem
13390 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73  ory allocation s
133a0 74 61 74 69 73 74 69 63 73 20 61 72 65 20 65 6e  tatistics are en
133b0 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74  abled by default
133c0 20 75 6e 6c 65 73 73 20 53 51 4c 69 74 65 20 69   unless SQLite i
133d0 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 77 69  s.** compiled wi
133e0 74 68 20 5b 53 51 4c 49 54 45 5f 44 45 46 41 55  th [SQLITE_DEFAU
133f0 4c 54 5f 4d 45 4d 53 54 41 54 55 53 5d 3d 30 20  LT_MEMSTATUS]=0 
13400 69 6e 20 77 68 69 63 68 20 63 61 73 65 20 6d 65  in which case me
13410 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69  mory.** allocati
13420 6f 6e 20 73 74 61 74 69 73 74 69 63 73 20 61 72  on statistics ar
13430 65 20 64 69 73 61 62 6c 65 64 20 62 79 20 64 65  e disabled by de
13440 66 61 75 6c 74 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a  fault..** </dd>.
13450 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
13460 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 5d 5d 20  ONFIG_SCRATCH]] 
13470 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
13480 47 5f 53 43 52 41 54 43 48 3c 2f 64 74 3e 0a 2a  G_SCRATCH</dt>.*
13490 2a 20 3c 64 64 3e 20 5e 54 68 65 20 53 51 4c 49  * <dd> ^The SQLI
134a0 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43  TE_CONFIG_SCRATC
134b0 48 20 6f 70 74 69 6f 6e 20 73 70 65 63 69 66 69  H option specifi
134c0 65 73 20 61 20 73 74 61 74 69 63 20 6d 65 6d 6f  es a static memo
134d0 72 79 20 62 75 66 66 65 72 0a 2a 2a 20 74 68 61  ry buffer.** tha
134e0 74 20 53 51 4c 69 74 65 20 63 61 6e 20 75 73 65  t SQLite can use
134f0 20 66 6f 72 20 73 63 72 61 74 63 68 20 6d 65 6d   for scratch mem
13500 6f 72 79 2e 20 20 5e 28 54 68 65 72 65 20 61 72  ory.  ^(There ar
13510 65 20 74 68 72 65 65 20 61 72 67 75 6d 65 6e 74  e three argument
13520 73 0a 2a 2a 20 74 6f 20 53 51 4c 49 54 45 5f 43  s.** to SQLITE_C
13530 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 3a 20 20  ONFIG_SCRATCH:  
13540 41 20 70 6f 69 6e 74 65 72 20 61 6e 20 38 2d 62  A pointer an 8-b
13550 79 74 65 0a 2a 2a 20 61 6c 69 67 6e 65 64 20 6d  yte.** aligned m
13560 65 6d 6f 72 79 20 62 75 66 66 65 72 20 66 72 6f  emory buffer fro
13570 6d 20 77 68 69 63 68 20 74 68 65 20 73 63 72 61  m which the scra
13580 74 63 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20  tch allocations 
13590 77 69 6c 6c 20 62 65 0a 2a 2a 20 64 72 61 77 6e  will be.** drawn
135a0 2c 20 74 68 65 20 73 69 7a 65 20 6f 66 20 65 61  , the size of ea
135b0 63 68 20 73 63 72 61 74 63 68 20 61 6c 6c 6f 63  ch scratch alloc
135c0 61 74 69 6f 6e 20 28 73 7a 29 2c 0a 2a 2a 20 61  ation (sz),.** a
135d0 6e 64 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6e  nd the maximum n
135e0 75 6d 62 65 72 20 6f 66 20 73 63 72 61 74 63 68  umber of scratch
135f0 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 28 4e 29   allocations (N)
13600 2e 29 5e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74  .)^.** The first
13610 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 74 20 62   argument must b
13620 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  e a pointer to a
13630 6e 20 38 2d 62 79 74 65 20 61 6c 69 67 6e 65 64  n 8-byte aligned
13640 20 62 75 66 66 65 72 0a 2a 2a 20 6f 66 20 61 74   buffer.** of at
13650 20 6c 65 61 73 74 20 73 7a 2a 4e 20 62 79 74 65   least sz*N byte
13660 73 20 6f 66 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20  s of memory..** 
13670 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 6e 6f 74  ^SQLite will not
13680 20 75 73 65 20 6d 6f 72 65 20 74 68 61 6e 20 6f   use more than o
13690 6e 65 20 73 63 72 61 74 63 68 20 62 75 66 66 65  ne scratch buffe
136a0 72 73 20 70 65 72 20 74 68 72 65 61 64 2e 0a 2a  rs per thread..*
136b0 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 6e  * ^SQLite will n
136c0 65 76 65 72 20 72 65 71 75 65 73 74 20 61 20 73  ever request a s
136d0 63 72 61 74 63 68 20 62 75 66 66 65 72 20 74 68  cratch buffer th
136e0 61 74 20 69 73 20 6d 6f 72 65 20 74 68 61 6e 20  at is more than 
136f0 36 0a 2a 2a 20 74 69 6d 65 73 20 74 68 65 20 64  6.** times the d
13700 61 74 61 62 61 73 65 20 70 61 67 65 20 73 69 7a  atabase page siz
13710 65 2e 0a 2a 2a 20 5e 49 66 20 53 51 4c 69 74 65  e..** ^If SQLite
13720 20 6e 65 65 64 73 20 6e 65 65 64 73 20 61 64 64   needs needs add
13730 69 74 69 6f 6e 61 6c 0a 2a 2a 20 73 63 72 61 74  itional.** scrat
13740 63 68 20 6d 65 6d 6f 72 79 20 62 65 79 6f 6e 64  ch memory beyond
13750 20 77 68 61 74 20 69 73 20 70 72 6f 76 69 64 65   what is provide
13760 64 20 62 79 20 74 68 69 73 20 63 6f 6e 66 69 67  d by this config
13770 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2c 20  uration option, 
13780 74 68 65 6e 20 0a 2a 2a 20 5b 73 71 6c 69 74 65  then .** [sqlite
13790 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 77 69 6c 6c  3_malloc()] will
137a0 20 62 65 20 75 73 65 64 20 74 6f 20 6f 62 74 61   be used to obta
137b0 69 6e 20 74 68 65 20 6d 65 6d 6f 72 79 20 6e 65  in the memory ne
137c0 65 64 65 64 2e 3c 70 3e 0a 2a 2a 20 5e 57 68 65  eded.<p>.** ^Whe
137d0 6e 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  n the applicatio
137e0 6e 20 70 72 6f 76 69 64 65 73 20 61 6e 79 20 61  n provides any a
137f0 6d 6f 75 6e 74 20 6f 66 20 73 63 72 61 74 63 68  mount of scratch
13800 20 6d 65 6d 6f 72 79 20 75 73 69 6e 67 0a 2a 2a   memory using.**
13810 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53   SQLITE_CONFIG_S
13820 43 52 41 54 43 48 2c 20 53 51 4c 69 74 65 20 61  CRATCH, SQLite a
13830 76 6f 69 64 73 20 75 6e 6e 65 63 65 73 73 61 72  voids unnecessar
13840 79 20 6c 61 72 67 65 0a 2a 2a 20 5b 73 71 6c 69  y large.** [sqli
13850 74 65 33 5f 6d 61 6c 6c 6f 63 7c 68 65 61 70 20  te3_malloc|heap 
13860 61 6c 6c 6f 63 61 74 69 6f 6e 73 5d 2e 0a 2a 2a  allocations]..**
13870 20 54 68 69 73 20 63 61 6e 20 68 65 6c 70 20 5b   This can help [
13880 52 6f 62 73 6f 6e 20 70 72 6f 6f 66 7c 70 72 65  Robson proof|pre
13890 76 65 6e 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  vent memory allo
138a0 63 61 74 69 6f 6e 20 66 61 69 6c 75 72 65 73 5d  cation failures]
138b0 20 64 75 65 20 74 6f 20 68 65 61 70 0a 2a 2a 20   due to heap.** 
138c0 66 72 61 67 6d 65 6e 74 61 74 69 6f 6e 20 69 6e  fragmentation in
138d0 20 6c 6f 77 2d 6d 65 6d 6f 72 79 20 65 6d 62 65   low-memory embe
138e0 64 64 65 64 20 73 79 73 74 65 6d 73 2e 0a 2a 2a  dded systems..**
138f0 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53   </dd>.**.** [[S
13900 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47  QLITE_CONFIG_PAG
13910 45 43 41 43 48 45 5d 5d 20 3c 64 74 3e 53 51 4c  ECACHE]] <dt>SQL
13920 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43  ITE_CONFIG_PAGEC
13930 41 43 48 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  ACHE</dt>.** <dd
13940 3e 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f  > ^The SQLITE_CO
13950 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 20 6f  NFIG_PAGECACHE o
13960 70 74 69 6f 6e 20 73 70 65 63 69 66 69 65 73 20  ption specifies 
13970 61 20 6d 65 6d 6f 72 79 20 70 6f 6f 6c 0a 2a 2a  a memory pool.**
13980 20 74 68 61 74 20 53 51 4c 69 74 65 20 63 61 6e   that SQLite can
13990 20 75 73 65 20 66 6f 72 20 74 68 65 20 64 61 74   use for the dat
139a0 61 62 61 73 65 20 70 61 67 65 20 63 61 63 68 65  abase page cache
139b0 20 77 69 74 68 20 74 68 65 20 64 65 66 61 75 6c   with the defaul
139c0 74 20 70 61 67 65 0a 2a 2a 20 63 61 63 68 65 20  t page.** cache 
139d0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20  implementation. 
139e0 20 0a 2a 2a 20 54 68 69 73 20 63 6f 6e 66 69 67   .** This config
139f0 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69  uration option i
13a00 73 20 61 20 6e 6f 2d 6f 70 20 69 66 20 61 6e 20  s a no-op if an 
13a10 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
13a20 6e 65 20 70 61 67 65 0a 2a 2a 20 63 61 63 68 65  ne page.** cache
13a30 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
13a40 69 73 20 6c 6f 61 64 65 64 20 75 73 69 6e 67 20  is loaded using 
13a50 74 68 65 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  the [SQLITE_CONF
13a60 49 47 5f 50 43 41 43 48 45 32 5d 2e 0a 2a 2a 20  IG_PCACHE2]..** 
13a70 5e 54 68 65 72 65 20 61 72 65 20 74 68 72 65 65  ^There are three
13a80 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 53 51   arguments to SQ
13a90 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45  LITE_CONFIG_PAGE
13aa0 43 41 43 48 45 3a 20 41 20 70 6f 69 6e 74 65 72  CACHE: A pointer
13ab0 20 74 6f 0a 2a 2a 20 38 2d 62 79 74 65 20 61 6c   to.** 8-byte al
13ac0 69 67 6e 65 64 20 6d 65 6d 6f 72 79 20 28 70 4d  igned memory (pM
13ad0 65 6d 29 2c 20 74 68 65 20 73 69 7a 65 20 6f 66  em), the size of
13ae0 20 65 61 63 68 20 70 61 67 65 20 63 61 63 68 65   each page cache
13af0 20 6c 69 6e 65 20 28 73 7a 29 2c 0a 2a 2a 20 61   line (sz),.** a
13b00 6e 64 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  nd the number of
13b10 20 63 61 63 68 65 20 6c 69 6e 65 73 20 28 4e 29   cache lines (N)
13b20 2e 0a 2a 2a 20 54 68 65 20 73 7a 20 61 72 67 75  ..** The sz argu
13b30 6d 65 6e 74 20 73 68 6f 75 6c 64 20 62 65 20 74  ment should be t
13b40 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 6c  he size of the l
13b50 61 72 67 65 73 74 20 64 61 74 61 62 61 73 65 20  argest database 
13b60 70 61 67 65 0a 2a 2a 20 28 61 20 70 6f 77 65 72  page.** (a power
13b70 20 6f 66 20 74 77 6f 20 62 65 74 77 65 65 6e 20   of two between 
13b80 35 31 32 20 61 6e 64 20 36 35 35 33 36 29 20 70  512 and 65536) p
13b90 6c 75 73 20 73 6f 6d 65 20 65 78 74 72 61 20 62  lus some extra b
13ba0 79 74 65 73 20 66 6f 72 20 65 61 63 68 0a 2a 2a  ytes for each.**
13bb0 20 70 61 67 65 20 68 65 61 64 65 72 2e 20 20 5e   page header.  ^
13bc0 54 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 65 78  The number of ex
13bd0 74 72 61 20 62 79 74 65 73 20 6e 65 65 64 65 64  tra bytes needed
13be0 20 62 79 20 74 68 65 20 70 61 67 65 20 68 65 61   by the page hea
13bf0 64 65 72 0a 2a 2a 20 63 61 6e 20 62 65 20 64 65  der.** can be de
13c00 74 65 72 6d 69 6e 65 64 20 75 73 69 6e 67 20 5b  termined using [
13c10 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43  SQLITE_CONFIG_PC
13c20 41 43 48 45 5f 48 44 52 53 5a 5d 2e 0a 2a 2a 20  ACHE_HDRSZ]..** 
13c30 5e 49 74 20 69 73 20 68 61 72 6d 6c 65 73 73 2c  ^It is harmless,
13c40 20 61 70 61 72 74 20 66 72 6f 6d 20 74 68 65 20   apart from the 
13c50 77 61 73 74 65 64 20 6d 65 6d 6f 72 79 2c 0a 2a  wasted memory,.*
13c60 2a 20 66 6f 72 20 74 68 65 20 73 7a 20 70 61 72  * for the sz par
13c70 61 6d 65 74 65 72 20 74 6f 20 62 65 20 6c 61 72  ameter to be lar
13c80 67 65 72 20 74 68 61 6e 20 6e 65 63 65 73 73 61  ger than necessa
13c90 72 79 2e 20 20 54 68 65 20 70 4d 65 6d 0a 2a 2a  ry.  The pMem.**
13ca0 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 74 20 62   argument must b
13cb0 65 20 65 69 74 68 65 72 20 61 20 4e 55 4c 4c 20  e either a NULL 
13cc0 70 6f 69 6e 74 65 72 20 6f 72 20 61 20 70 6f 69  pointer or a poi
13cd0 6e 74 65 72 20 74 6f 20 61 6e 20 38 2d 62 79 74  nter to an 8-byt
13ce0 65 0a 2a 2a 20 61 6c 69 67 6e 65 64 20 62 6c 6f  e.** aligned blo
13cf0 63 6b 20 6f 66 20 6d 65 6d 6f 72 79 20 6f 66 20  ck of memory of 
13d00 61 74 20 6c 65 61 73 74 20 73 7a 2a 4e 20 62 79  at least sz*N by
13d10 74 65 73 2c 20 6f 74 68 65 72 77 69 73 65 0a 2a  tes, otherwise.*
13d20 2a 20 73 75 62 73 65 71 75 65 6e 74 20 62 65 68  * subsequent beh
13d30 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e  avior is undefin
13d40 65 64 2e 0a 2a 2a 20 5e 57 68 65 6e 20 70 4d 65  ed..** ^When pMe
13d50 6d 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 53  m is not NULL, S
13d60 51 4c 69 74 65 20 77 69 6c 6c 20 73 74 72 69 76  QLite will striv
13d70 65 20 74 6f 20 75 73 65 20 74 68 65 20 6d 65 6d  e to use the mem
13d80 6f 72 79 20 70 72 6f 76 69 64 65 64 0a 2a 2a 20  ory provided.** 
13d90 74 6f 20 73 61 74 69 73 66 79 20 70 61 67 65 20  to satisfy page 
13da0 63 61 63 68 65 20 6e 65 65 64 73 2c 20 66 61 6c  cache needs, fal
13db0 6c 69 6e 67 20 62 61 63 6b 20 74 6f 20 5b 73 71  ling back to [sq
13dc0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20  lite3_malloc()] 
13dd0 69 66 0a 2a 2a 20 61 20 70 61 67 65 20 63 61 63  if.** a page cac
13de0 68 65 20 6c 69 6e 65 20 69 73 20 6c 61 72 67 65  he line is large
13df0 72 20 74 68 61 6e 20 73 7a 20 62 79 74 65 73 20  r than sz bytes 
13e00 6f 72 20 69 66 20 61 6c 6c 20 6f 66 20 74 68 65  or if all of the
13e10 20 70 4d 65 6d 20 62 75 66 66 65 72 0a 2a 2a 20   pMem buffer.** 
13e20 69 73 20 65 78 68 61 75 73 74 65 64 2e 0a 2a 2a  is exhausted..**
13e30 20 5e 49 66 20 70 4d 65 6d 20 69 73 20 4e 55 4c   ^If pMem is NUL
13e40 4c 20 61 6e 64 20 4e 20 69 73 20 6e 6f 6e 2d 7a  L and N is non-z
13e50 65 72 6f 2c 20 74 68 65 6e 20 65 61 63 68 20 64  ero, then each d
13e60 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
13e70 6f 6e 0a 2a 2a 20 64 6f 65 73 20 61 6e 20 69 6e  on.** does an in
13e80 69 74 69 61 6c 20 62 75 6c 6b 20 61 6c 6c 6f 63  itial bulk alloc
13e90 61 74 69 6f 6e 20 66 6f 72 20 70 61 67 65 20 63  ation for page c
13ea0 61 63 68 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 66  ache memory.** f
13eb0 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  rom [sqlite3_mal
13ec0 6c 6f 63 28 29 5d 20 73 75 66 66 69 63 69 65 6e  loc()] sufficien
13ed0 74 20 66 6f 72 20 4e 20 63 61 63 68 65 20 6c 69  t for N cache li
13ee0 6e 65 73 20 69 66 20 4e 20 69 73 20 70 6f 73 69  nes if N is posi
13ef0 74 69 76 65 20 6f 72 0a 2a 2a 20 6f 66 20 2d 31  tive or.** of -1
13f00 30 32 34 2a 4e 20 62 79 74 65 73 20 69 66 20 4e  024*N bytes if N
13f10 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 2e 20   is negative, . 
13f20 5e 49 66 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a  ^If additional.*
13f30 2a 20 70 61 67 65 20 63 61 63 68 65 20 6d 65 6d  * page cache mem
13f40 6f 72 79 20 69 73 20 6e 65 65 64 65 64 20 62 65  ory is needed be
13f50 79 6f 6e 64 20 77 68 61 74 20 69 73 20 70 72 6f  yond what is pro
13f60 76 69 64 65 64 20 62 79 20 74 68 65 20 69 6e 69  vided by the ini
13f70 74 69 61 6c 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69  tial.** allocati
13f80 6f 6e 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20  on, then SQLite 
13f90 67 6f 65 73 20 74 6f 20 5b 73 71 6c 69 74 65 33  goes to [sqlite3
13fa0 5f 6d 61 6c 6c 6f 63 28 29 5d 20 73 65 70 61 72  _malloc()] separ
13fb0 61 74 65 6c 79 20 66 6f 72 20 65 61 63 68 0a 2a  ately for each.*
13fc0 2a 20 61 64 64 69 74 69 6f 6e 61 6c 20 63 61 63  * additional cac
13fd0 68 65 20 6c 69 6e 65 2e 20 3c 2f 64 64 3e 0a 2a  he line. </dd>.*
13fe0 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
13ff0 4e 46 49 47 5f 48 45 41 50 5d 5d 20 3c 64 74 3e  NFIG_HEAP]] <dt>
14000 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45  SQLITE_CONFIG_HE
14010 41 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  AP</dt>.** <dd> 
14020 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  ^The SQLITE_CONF
14030 49 47 5f 48 45 41 50 20 6f 70 74 69 6f 6e 20 73  IG_HEAP option s
14040 70 65 63 69 66 69 65 73 20 61 20 73 74 61 74 69  pecifies a stati
14050 63 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20  c memory buffer 
14060 0a 2a 2a 20 74 68 61 74 20 53 51 4c 69 74 65 20  .** that SQLite 
14070 77 69 6c 6c 20 75 73 65 20 66 6f 72 20 61 6c 6c  will use for all
14080 20 6f 66 20 69 74 73 20 64 79 6e 61 6d 69 63 20   of its dynamic 
14090 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
140a0 6e 20 6e 65 65 64 73 0a 2a 2a 20 62 65 79 6f 6e  n needs.** beyon
140b0 64 20 74 68 6f 73 65 20 70 72 6f 76 69 64 65 64  d those provided
140c0 20 66 6f 72 20 62 79 20 5b 53 51 4c 49 54 45 5f   for by [SQLITE_
140d0 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 5d 20  CONFIG_SCRATCH] 
140e0 61 6e 64 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43  and.** [SQLITE_C
140f0 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 5d  ONFIG_PAGECACHE]
14100 2e 0a 2a 2a 20 5e 54 68 65 20 53 51 4c 49 54 45  ..** ^The SQLITE
14110 5f 43 4f 4e 46 49 47 5f 48 45 41 50 20 6f 70 74  _CONFIG_HEAP opt
14120 69 6f 6e 20 69 73 20 6f 6e 6c 79 20 61 76 61 69  ion is only avai
14130 6c 61 62 6c 65 20 69 66 20 53 51 4c 69 74 65 20  lable if SQLite 
14140 69 73 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 77  is compiled.** w
14150 69 74 68 20 65 69 74 68 65 72 20 5b 53 51 4c 49  ith either [SQLI
14160 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53 59 53  TE_ENABLE_MEMSYS
14170 33 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 45 4e  3] or [SQLITE_EN
14180 41 42 4c 45 5f 4d 45 4d 53 59 53 35 5d 20 61 6e  ABLE_MEMSYS5] an
14190 64 20 72 65 74 75 72 6e 73 0a 2a 2a 20 5b 53 51  d returns.** [SQ
141a0 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 69  LITE_ERROR] if i
141b0 6e 76 6f 6b 65 64 20 6f 74 68 65 72 77 69 73 65  nvoked otherwise
141c0 2e 0a 2a 2a 20 5e 54 68 65 72 65 20 61 72 65 20  ..** ^There are 
141d0 74 68 72 65 65 20 61 72 67 75 6d 65 6e 74 73 20  three arguments 
141e0 74 6f 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  to SQLITE_CONFIG
141f0 5f 48 45 41 50 3a 0a 2a 2a 20 41 6e 20 38 2d 62  _HEAP:.** An 8-b
14200 79 74 65 20 61 6c 69 67 6e 65 64 20 70 6f 69 6e  yte aligned poin
14210 74 65 72 20 74 6f 20 74 68 65 20 6d 65 6d 6f 72  ter to the memor
14220 79 2c 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72  y,.** the number
14230 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 65   of bytes in the
14240 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 2c 20   memory buffer, 
14250 61 6e 64 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20  and the minimum 
14260 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 2e  allocation size.
14270 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 72 73  .** ^If the firs
14280 74 20 70 6f 69 6e 74 65 72 20 28 74 68 65 20 6d  t pointer (the m
14290 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72 29 20 69  emory pointer) i
142a0 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 53 51 4c  s NULL, then SQL
142b0 69 74 65 20 72 65 76 65 72 74 73 0a 2a 2a 20 74  ite reverts.** t
142c0 6f 20 75 73 69 6e 67 20 69 74 73 20 64 65 66 61  o using its defa
142d0 75 6c 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ult memory alloc
142e0 61 74 6f 72 20 28 74 68 65 20 73 79 73 74 65 6d  ator (the system
142f0 20 6d 61 6c 6c 6f 63 28 29 20 69 6d 70 6c 65 6d   malloc() implem
14300 65 6e 74 61 74 69 6f 6e 29 2c 0a 2a 2a 20 75 6e  entation),.** un
14310 64 6f 69 6e 67 20 61 6e 79 20 70 72 69 6f 72 20  doing any prior 
14320 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 53  invocation of [S
14330 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c  QLITE_CONFIG_MAL
14340 4c 4f 43 5d 2e 20 20 5e 49 66 20 74 68 65 0a 2a  LOC].  ^If the.*
14350 2a 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72  * memory pointer
14360 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 74 68 65   is not NULL the
14370 6e 20 74 68 65 20 61 6c 74 65 72 6e 61 74 69 76  n the alternativ
14380 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f  e memory.** allo
14390 63 61 74 6f 72 20 69 73 20 65 6e 67 61 67 65 64  cator is engaged
143a0 20 74 6f 20 68 61 6e 64 6c 65 20 61 6c 6c 20 6f   to handle all o
143b0 66 20 53 51 4c 69 74 65 73 20 6d 65 6d 6f 72 79  f SQLites memory
143c0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64   allocation need
143d0 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20  s..** The first 
143e0 70 6f 69 6e 74 65 72 20 28 74 68 65 20 6d 65 6d  pointer (the mem
143f0 6f 72 79 20 70 6f 69 6e 74 65 72 29 20 6d 75 73  ory pointer) mus
14400 74 20 62 65 20 61 6c 69 67 6e 65 64 20 74 6f 20  t be aligned to 
14410 61 6e 20 38 2d 62 79 74 65 0a 2a 2a 20 62 6f 75  an 8-byte.** bou
14420 6e 64 61 72 79 20 6f 72 20 73 75 62 73 65 71 75  ndary or subsequ
14430 65 6e 74 20 62 65 68 61 76 69 6f 72 20 6f 66 20  ent behavior of 
14440 53 51 4c 69 74 65 20 77 69 6c 6c 20 62 65 20 75  SQLite will be u
14450 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 54 68 65  ndefined..** The
14460 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 74   minimum allocat
14470 69 6f 6e 20 73 69 7a 65 20 69 73 20 63 61 70 70  ion size is capp
14480 65 64 20 61 74 20 32 2a 2a 31 32 2e 20 52 65 61  ed at 2**12. Rea
14490 73 6f 6e 61 62 6c 65 20 76 61 6c 75 65 73 0a 2a  sonable values.*
144a0 2a 20 66 6f 72 20 74 68 65 20 6d 69 6e 69 6d 75  * for the minimu
144b0 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a  m allocation siz
144c0 65 20 61 72 65 20 32 2a 2a 35 20 74 68 72 6f 75  e are 2**5 throu
144d0 67 68 20 32 2a 2a 38 2e 3c 2f 64 64 3e 0a 2a 2a  gh 2**8.</dd>.**
144e0 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
144f0 46 49 47 5f 4d 55 54 45 58 5d 5d 20 3c 64 74 3e  FIG_MUTEX]] <dt>
14500 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55  SQLITE_CONFIG_MU
14510 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  TEX</dt>.** <dd>
14520 20 5e 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f   ^(The SQLITE_CO
14530 4e 46 49 47 5f 4d 55 54 45 58 20 6f 70 74 69 6f  NFIG_MUTEX optio
14540 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65  n takes a single
14550 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20   argument which 
14560 69 73 20 61 0a 2a 2a 20 70 6f 69 6e 74 65 72 20  is a.** pointer 
14570 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f  to an instance o
14580 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d  f the [sqlite3_m
14590 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74  utex_methods] st
145a0 72 75 63 74 75 72 65 2e 0a 2a 2a 20 54 68 65 20  ructure..** The 
145b0 61 72 67 75 6d 65 6e 74 20 73 70 65 63 69 66 69  argument specifi
145c0 65 73 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6c  es alternative l
145d0 6f 77 2d 6c 65 76 65 6c 20 6d 75 74 65 78 20 72  ow-level mutex r
145e0 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20 75 73  outines to be us
145f0 65 64 0a 2a 2a 20 69 6e 20 70 6c 61 63 65 20 74  ed.** in place t
14600 68 65 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65  he mutex routine
14610 73 20 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c  s built into SQL
14620 69 74 65 2e 29 5e 20 20 5e 53 51 4c 69 74 65 20  ite.)^  ^SQLite 
14630 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 0a  makes a copy of.
14640 2a 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f  ** the content o
14650 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d  f the [sqlite3_m
14660 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74  utex_methods] st
14670 72 75 63 74 75 72 65 20 62 65 66 6f 72 65 20 74  ructure before t
14680 68 65 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73  he call to.** [s
14690 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
146a0 20 72 65 74 75 72 6e 73 2e 20 5e 49 66 20 53 51   returns. ^If SQ
146b0 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  Lite is compiled
146c0 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51   with.** the [SQ
146d0 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 20  LITE_THREADSAFE 
146e0 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53  | SQLITE_THREADS
146f0 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74  AFE=0] compile-t
14700 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a  ime option then.
14710 2a 2a 20 74 68 65 20 65 6e 74 69 72 65 20 6d 75  ** the entire mu
14720 74 65 78 69 6e 67 20 73 75 62 73 79 73 74 65 6d  texing subsystem
14730 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d   is omitted from
14740 20 74 68 65 20 62 75 69 6c 64 20 61 6e 64 20 68   the build and h
14750 65 6e 63 65 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a  ence calls to.**
14760 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
14770 28 29 5d 20 77 69 74 68 20 74 68 65 20 53 51 4c  ()] with the SQL
14780 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58  ITE_CONFIG_MUTEX
14790 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
147a0 70 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 72 65  ption will.** re
147b0 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52  turn [SQLITE_ERR
147c0 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  OR].</dd>.**.** 
147d0 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
147e0 47 45 54 4d 55 54 45 58 5d 5d 20 3c 64 74 3e 53  GETMUTEX]] <dt>S
147f0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
14800 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  MUTEX</dt>.** <d
14810 64 3e 20 5e 28 54 68 65 20 53 51 4c 49 54 45 5f  d> ^(The SQLITE_
14820 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 20  CONFIG_GETMUTEX 
14830 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73  option takes a s
14840 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77  ingle argument w
14850 68 69 63 68 0a 2a 2a 20 69 73 20 61 20 70 6f 69  hich.** is a poi
14860 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61  nter to an insta
14870 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  nce of the [sqli
14880 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64  te3_mutex_method
14890 73 5d 20 73 74 72 75 63 74 75 72 65 2e 20 20 54  s] structure.  T
148a0 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d  he.** [sqlite3_m
148b0 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a  utex_methods].**
148c0 20 73 74 72 75 63 74 75 72 65 20 69 73 20 66 69   structure is fi
148d0 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20 63 75  lled with the cu
148e0 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 20  rrently defined 
148f0 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73 2e 29  mutex routines.)
14900 5e 0a 2a 2a 20 54 68 69 73 20 6f 70 74 69 6f 6e  ^.** This option
14910 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
14920 6f 76 65 72 6c 6f 61 64 20 74 68 65 20 64 65 66  overload the def
14930 61 75 6c 74 20 6d 75 74 65 78 20 61 6c 6c 6f 63  ault mutex alloc
14940 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65  ation.** routine
14950 73 20 77 69 74 68 20 61 20 77 72 61 70 70 65 72  s with a wrapper
14960 20 75 73 65 64 20 74 6f 20 74 72 61 63 6b 20 6d   used to track m
14970 75 74 65 78 20 75 73 61 67 65 20 66 6f 72 20 70  utex usage for p
14980 65 72 66 6f 72 6d 61 6e 63 65 0a 2a 2a 20 70 72  erformance.** pr
14990 6f 66 69 6c 69 6e 67 20 6f 72 20 74 65 73 74 69  ofiling or testi
149a0 6e 67 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2e  ng, for example.
149b0 20 20 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73     ^If SQLite is
149c0 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a   compiled with.*
149d0 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48  * the [SQLITE_TH
149e0 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54  READSAFE | SQLIT
149f0 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20  E_THREADSAFE=0] 
14a00 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
14a10 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20  ion then.** the 
14a20 65 6e 74 69 72 65 20 6d 75 74 65 78 69 6e 67 20  entire mutexing 
14a30 73 75 62 73 79 73 74 65 6d 20 69 73 20 6f 6d 69  subsystem is omi
14a40 74 74 65 64 20 66 72 6f 6d 20 74 68 65 20 62 75  tted from the bu
14a50 69 6c 64 20 61 6e 64 20 68 65 6e 63 65 20 63 61  ild and hence ca
14a60 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  lls to.** [sqlit
14a70 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 74  e3_config()] wit
14a80 68 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e  h the SQLITE_CON
14a90 46 49 47 5f 47 45 54 4d 55 54 45 58 20 63 6f 6e  FIG_GETMUTEX con
14aa0 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
14ab0 6e 20 77 69 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e  n will.** return
14ac0 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2e   [SQLITE_ERROR].
14ad0 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
14ae0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b  LITE_CONFIG_LOOK
14af0 41 53 49 44 45 5d 5d 20 3c 64 74 3e 53 51 4c 49  ASIDE]] <dt>SQLI
14b00 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53  TE_CONFIG_LOOKAS
14b10 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  IDE</dt>.** <dd>
14b20 20 5e 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f   ^(The SQLITE_CO
14b30 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 6f  NFIG_LOOKASIDE o
14b40 70 74 69 6f 6e 20 74 61 6b 65 73 20 74 77 6f 20  ption takes two 
14b50 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74 20 64  arguments that d
14b60 65 74 65 72 6d 69 6e 65 0a 2a 2a 20 74 68 65 20  etermine.** the 
14b70 64 65 66 61 75 6c 74 20 73 69 7a 65 20 6f 66 20  default size of 
14b80 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79  lookaside memory
14b90 20 6f 6e 20 65 61 63 68 20 5b 64 61 74 61 62 61   on each [databa
14ba0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a  se connection]..
14bb0 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67  ** The first arg
14bc0 75 6d 65 6e 74 20 69 73 20 74 68 65 0a 2a 2a 20  ument is the.** 
14bd0 73 69 7a 65 20 6f 66 20 65 61 63 68 20 6c 6f 6f  size of each loo
14be0 6b 61 73 69 64 65 20 62 75 66 66 65 72 20 73 6c  kaside buffer sl
14bf0 6f 74 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e  ot and the secon
14c00 64 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20  d is the number 
14c10 6f 66 0a 2a 2a 20 73 6c 6f 74 73 20 61 6c 6c 6f  of.** slots allo
14c20 63 61 74 65 64 20 74 6f 20 65 61 63 68 20 64 61  cated to each da
14c30 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
14c40 6e 2e 29 5e 20 20 5e 28 53 51 4c 49 54 45 5f 43  n.)^  ^(SQLITE_C
14c50 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 0a  ONFIG_LOOKASIDE.
14c60 2a 2a 20 73 65 74 73 20 74 68 65 20 3c 69 3e 64  ** sets the <i>d
14c70 65 66 61 75 6c 74 3c 2f 69 3e 20 6c 6f 6f 6b 61  efault</i> looka
14c80 73 69 64 65 20 73 69 7a 65 2e 20 54 68 65 20 5b  side size. The [
14c90 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
14ca0 4c 4f 4f 4b 41 53 49 44 45 5d 0a 2a 2a 20 6f 70  LOOKASIDE].** op
14cb0 74 69 6f 6e 20 74 6f 20 5b 73 71 6c 69 74 65 33  tion to [sqlite3
14cc0 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 63 61  _db_config()] ca
14cd0 6e 20 62 65 20 75 73 65 64 20 74 6f 20 63 68 61  n be used to cha
14ce0 6e 67 65 20 74 68 65 20 6c 6f 6f 6b 61 73 69 64  nge the lookasid
14cf0 65 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69  e.** configurati
14d00 6f 6e 20 6f 6e 20 69 6e 64 69 76 69 64 75 61 6c  on on individual
14d10 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 2e 29 5e 20   connections.)^ 
14d20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
14d30 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43  LITE_CONFIG_PCAC
14d40 48 45 32 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45  HE2]] <dt>SQLITE
14d50 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 3c  _CONFIG_PCACHE2<
14d60 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54  /dt>.** <dd> ^(T
14d70 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
14d80 5f 50 43 41 43 48 45 32 20 6f 70 74 69 6f 6e 20  _PCACHE2 option 
14d90 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61  takes a single a
14da0 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73  rgument which is
14db0 20 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74   .** a pointer t
14dc0 6f 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 70 63  o an [sqlite3_pc
14dd0 61 63 68 65 5f 6d 65 74 68 6f 64 73 32 5d 20 6f  ache_methods2] o
14de0 62 6a 65 63 74 2e 20 20 54 68 69 73 20 6f 62 6a  bject.  This obj
14df0 65 63 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a  ect specifies.**
14e00 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 20 74   the interface t
14e10 6f 20 61 20 63 75 73 74 6f 6d 20 70 61 67 65 20  o a custom page 
14e20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61  cache implementa
14e30 74 69 6f 6e 2e 29 5e 0a 2a 2a 20 5e 53 51 4c 69  tion.)^.** ^SQLi
14e40 74 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20  te makes a copy 
14e50 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
14e60 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 32 5d  pcache_methods2]
14e70 20 6f 62 6a 65 63 74 2e 3c 2f 64 64 3e 0a 2a 2a   object.</dd>.**
14e80 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
14e90 46 49 47 5f 47 45 54 50 43 41 43 48 45 32 5d 5d  FIG_GETPCACHE2]]
14ea0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
14eb0 49 47 5f 47 45 54 50 43 41 43 48 45 32 3c 2f 64  IG_GETPCACHE2</d
14ec0 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65  t>.** <dd> ^(The
14ed0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47   SQLITE_CONFIG_G
14ee0 45 54 50 43 41 43 48 45 32 20 6f 70 74 69 6f 6e  ETPCACHE2 option
14ef0 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20   takes a single 
14f00 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 0a 2a  argument which.*
14f10 2a 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  * is a pointer t
14f20 6f 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 70 63  o an [sqlite3_pc
14f30 61 63 68 65 5f 6d 65 74 68 6f 64 73 32 5d 20 6f  ache_methods2] o
14f40 62 6a 65 63 74 2e 20 20 53 51 4c 69 74 65 20 63  bject.  SQLite c
14f50 6f 70 69 65 73 20 6f 66 0a 2a 2a 20 74 68 65 20  opies of.** the 
14f60 63 75 72 72 65 6e 74 20 70 61 67 65 20 63 61 63  current page cac
14f70 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
14f80 6e 20 69 6e 74 6f 20 74 68 61 74 20 6f 62 6a 65  n into that obje
14f90 63 74 2e 29 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a  ct.)^ </dd>.**.*
14fa0 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
14fb0 47 5f 4c 4f 47 5d 5d 20 3c 64 74 3e 53 51 4c 49  G_LOG]] <dt>SQLI
14fc0 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 3c 2f 64  TE_CONFIG_LOG</d
14fd0 74 3e 0a 2a 2a 20 3c 64 64 3e 20 54 68 65 20 53  t>.** <dd> The S
14fe0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47  QLITE_CONFIG_LOG
14ff0 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64 20   option is used 
15000 74 6f 20 63 6f 6e 66 69 67 75 72 65 20 74 68 65  to configure the
15010 20 53 51 4c 69 74 65 0a 2a 2a 20 67 6c 6f 62 61   SQLite.** globa
15020 6c 20 5b 65 72 72 6f 72 20 6c 6f 67 5d 2e 0a 2a  l [error log]..*
15030 2a 20 28 5e 54 68 65 20 53 51 4c 49 54 45 5f 43  * (^The SQLITE_C
15040 4f 4e 46 49 47 5f 4c 4f 47 20 6f 70 74 69 6f 6e  ONFIG_LOG option
15050 20 74 61 6b 65 73 20 74 77 6f 20 61 72 67 75 6d   takes two argum
15060 65 6e 74 73 3a 20 61 20 70 6f 69 6e 74 65 72 20  ents: a pointer 
15070 74 6f 20 61 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  to a.** function
15080 20 77 69 74 68 20 61 20 63 61 6c 6c 20 73 69 67   with a call sig
15090 6e 61 74 75 72 65 20 6f 66 20 76 6f 69 64 28 2a  nature of void(*
150a0 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73  )(void*,int,cons
150b0 74 20 63 68 61 72 2a 29 2c 20 0a 2a 2a 20 61 6e  t char*), .** an
150c0 64 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 76  d a pointer to v
150d0 6f 69 64 2e 20 5e 49 66 20 74 68 65 20 66 75 6e  oid. ^If the fun
150e0 63 74 69 6f 6e 20 70 6f 69 6e 74 65 72 20 69 73  ction pointer is
150f0 20 6e 6f 74 20 4e 55 4c 4c 2c 20 69 74 20 69 73   not NULL, it is
15100 0a 2a 2a 20 69 6e 76 6f 6b 65 64 20 62 79 20 5b  .** invoked by [
15110 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20 74  sqlite3_log()] t
15120 6f 20 70 72 6f 63 65 73 73 20 65 61 63 68 20 6c  o process each l
15130 6f 67 67 69 6e 67 20 65 76 65 6e 74 2e 20 20 5e  ogging event.  ^
15140 49 66 20 74 68 65 0a 2a 2a 20 66 75 6e 63 74 69  If the.** functi
15150 6f 6e 20 70 6f 69 6e 74 65 72 20 69 73 20 4e 55  on pointer is NU
15160 4c 4c 2c 20 74 68 65 20 5b 73 71 6c 69 74 65 33  LL, the [sqlite3
15170 5f 6c 6f 67 28 29 5d 20 69 6e 74 65 72 66 61 63  _log()] interfac
15180 65 20 62 65 63 6f 6d 65 73 20 61 20 6e 6f 2d 6f  e becomes a no-o
15190 70 2e 0a 2a 2a 20 5e 54 68 65 20 76 6f 69 64 20  p..** ^The void 
151a0 70 6f 69 6e 74 65 72 20 74 68 61 74 20 69 73 20  pointer that is 
151b0 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  the second argum
151c0 65 6e 74 20 74 6f 20 53 51 4c 49 54 45 5f 43 4f  ent to SQLITE_CO
151d0 4e 46 49 47 5f 4c 4f 47 20 69 73 0a 2a 2a 20 70  NFIG_LOG is.** p
151e0 61 73 73 65 64 20 74 68 72 6f 75 67 68 20 61 73  assed through as
151f0 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d   the first param
15200 65 74 65 72 20 74 6f 20 74 68 65 20 61 70 70 6c  eter to the appl
15210 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
15220 6c 6f 67 67 65 72 0a 2a 2a 20 66 75 6e 63 74 69  logger.** functi
15230 6f 6e 20 77 68 65 6e 65 76 65 72 20 74 68 61 74  on whenever that
15240 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 69 6e 76   function is inv
15250 6f 6b 65 64 2e 20 20 5e 54 68 65 20 73 65 63 6f  oked.  ^The seco
15260 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a  nd parameter to.
15270 2a 2a 20 74 68 65 20 6c 6f 67 67 65 72 20 66 75  ** the logger fu
15280 6e 63 74 69 6f 6e 20 69 73 20 61 20 63 6f 70 79  nction is a copy
15290 20 6f 66 20 74 68 65 20 66 69 72 73 74 20 70 61   of the first pa
152a0 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 63  rameter to the c
152b0 6f 72 72 65 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20  orresponding.** 
152c0 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20  [sqlite3_log()] 
152d0 63 61 6c 6c 20 61 6e 64 20 69 73 20 69 6e 74 65  call and is inte
152e0 6e 64 65 64 20 74 6f 20 62 65 20 61 20 5b 72 65  nded to be a [re
152f0 73 75 6c 74 20 63 6f 64 65 5d 20 6f 72 20 61 6e  sult code] or an
15300 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65  .** [extended re
15310 73 75 6c 74 20 63 6f 64 65 5d 2e 20 20 5e 54 68  sult code].  ^Th
15320 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  e third paramete
15330 72 20 70 61 73 73 65 64 20 74 6f 20 74 68 65 20  r passed to the 
15340 6c 6f 67 67 65 72 20 69 73 0a 2a 2a 20 6c 6f 67  logger is.** log
15350 20 6d 65 73 73 61 67 65 20 61 66 74 65 72 20 66   message after f
15360 6f 72 6d 61 74 74 69 6e 67 20 76 69 61 20 5b 73  ormatting via [s
15370 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28  qlite3_snprintf(
15380 29 5d 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74  )]..** The SQLit
15390 65 20 6c 6f 67 67 69 6e 67 20 69 6e 74 65 72 66  e logging interf
153a0 61 63 65 20 69 73 20 6e 6f 74 20 72 65 65 6e 74  ace is not reent
153b0 72 61 6e 74 3b 20 74 68 65 20 6c 6f 67 67 65 72  rant; the logger
153c0 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 73 75 70   function.** sup
153d0 70 6c 69 65 64 20 62 79 20 74 68 65 20 61 70 70  plied by the app
153e0 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f  lication must no
153f0 74 20 69 6e 76 6f 6b 65 20 61 6e 79 20 53 51 4c  t invoke any SQL
15400 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a  ite interface..*
15410 2a 20 49 6e 20 61 20 6d 75 6c 74 69 2d 74 68 72  * In a multi-thr
15420 65 61 64 65 64 20 61 70 70 6c 69 63 61 74 69 6f  eaded applicatio
15430 6e 2c 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  n, the applicati
15440 6f 6e 2d 64 65 66 69 6e 65 64 20 6c 6f 67 67 65  on-defined logge
15450 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 6d 75  r.** function mu
15460 73 74 20 62 65 20 74 68 72 65 61 64 73 61 66 65  st be threadsafe
15470 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  . </dd>.**.** [[
15480 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52  SQLITE_CONFIG_UR
15490 49 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  I]] <dt>SQLITE_C
154a0 4f 4e 46 49 47 5f 55 52 49 0a 2a 2a 20 3c 64 64  ONFIG_URI.** <dd
154b0 3e 5e 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f  >^(The SQLITE_CO
154c0 4e 46 49 47 5f 55 52 49 20 6f 70 74 69 6f 6e 20  NFIG_URI option 
154d0 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61  takes a single a
154e0 72 67 75 6d 65 6e 74 20 6f 66 20 74 79 70 65 20  rgument of type 
154f0 69 6e 74 2e 0a 2a 2a 20 49 66 20 6e 6f 6e 2d 7a  int..** If non-z
15500 65 72 6f 2c 20 74 68 65 6e 20 55 52 49 20 68 61  ero, then URI ha
15510 6e 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c  ndling is global
15520 6c 79 20 65 6e 61 62 6c 65 64 2e 20 49 66 20 74  ly enabled. If t
15530 68 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  he parameter is 
15540 7a 65 72 6f 2c 0a 2a 2a 20 74 68 65 6e 20 55 52  zero,.** then UR
15550 49 20 68 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c  I handling is gl
15560 6f 62 61 6c 6c 79 20 64 69 73 61 62 6c 65 64 2e  obally disabled.
15570 29 5e 20 5e 49 66 20 55 52 49 20 68 61 6e 64 6c  )^ ^If URI handl
15580 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79 0a  ing is globally.
15590 2a 2a 20 65 6e 61 62 6c 65 64 2c 20 61 6c 6c 20  ** enabled, all 
155a0 66 69 6c 65 6e 61 6d 65 73 20 70 61 73 73 65 64  filenames passed
155b0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65   to [sqlite3_ope
155c0 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f  n()], [sqlite3_o
155d0 70 65 6e 5f 76 32 28 29 5d 2c 0a 2a 2a 20 5b 73  pen_v2()],.** [s
155e0 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d  qlite3_open16()]
155f0 20 6f 72 0a 2a 2a 20 73 70 65 63 69 66 69 65 64   or.** specified
15600 20 61 73 20 70 61 72 74 20 6f 66 20 5b 41 54 54   as part of [ATT
15610 41 43 48 5d 20 63 6f 6d 6d 61 6e 64 73 20 61 72  ACH] commands ar
15620 65 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73  e interpreted as
15630 20 55 52 49 73 2c 20 72 65 67 61 72 64 6c 65 73   URIs, regardles
15640 73 0a 2a 2a 20 6f 66 20 77 68 65 74 68 65 72 20  s.** of whether 
15650 6f 72 20 6e 6f 74 20 74 68 65 20 5b 53 51 4c 49  or not the [SQLI
15660 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 66 6c 61  TE_OPEN_URI] fla
15670 67 20 69 73 20 73 65 74 20 77 68 65 6e 20 74 68  g is set when th
15680 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f  e database.** co
15690 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e  nnection is open
156a0 65 64 2e 20 5e 49 66 20 69 74 20 69 73 20 67 6c  ed. ^If it is gl
156b0 6f 62 61 6c 6c 79 20 64 69 73 61 62 6c 65 64 2c  obally disabled,
156c0 20 66 69 6c 65 6e 61 6d 65 73 20 61 72 65 0a 2a   filenames are.*
156d0 2a 20 6f 6e 6c 79 20 69 6e 74 65 72 70 72 65 74  * only interpret
156e0 65 64 20 61 73 20 55 52 49 73 20 69 66 20 74 68  ed as URIs if th
156f0 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52  e SQLITE_OPEN_UR
15700 49 20 66 6c 61 67 20 69 73 20 73 65 74 20 77 68  I flag is set wh
15710 65 6e 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61  en the.** databa
15720 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  se connection is
15730 20 6f 70 65 6e 65 64 2e 20 5e 28 42 79 20 64 65   opened. ^(By de
15740 66 61 75 6c 74 2c 20 55 52 49 20 68 61 6e 64 6c  fault, URI handl
15750 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79 0a  ing is globally.
15760 2a 2a 20 64 69 73 61 62 6c 65 64 2e 20 54 68 65  ** disabled. The
15770 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65 20 6d   default value m
15780 61 79 20 62 65 20 63 68 61 6e 67 65 64 20 62 79  ay be changed by
15790 20 63 6f 6d 70 69 6c 69 6e 67 20 77 69 74 68 20   compiling with 
157a0 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55  the.** [SQLITE_U
157b0 53 45 5f 55 52 49 5d 20 73 79 6d 62 6f 6c 20 64  SE_URI] symbol d
157c0 65 66 69 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20  efined.)^.**.** 
157d0 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
157e0 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53  COVERING_INDEX_S
157f0 43 41 4e 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45  CAN]] <dt>SQLITE
15800 5f 43 4f 4e 46 49 47 5f 43 4f 56 45 52 49 4e 47  _CONFIG_COVERING
15810 5f 49 4e 44 45 58 5f 53 43 41 4e 0a 2a 2a 20 3c  _INDEX_SCAN.** <
15820 64 64 3e 5e 54 68 65 20 53 51 4c 49 54 45 5f 43  dd>^The SQLITE_C
15830 4f 4e 46 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49  ONFIG_COVERING_I
15840 4e 44 45 58 5f 53 43 41 4e 20 6f 70 74 69 6f 6e  NDEX_SCAN option
15850 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20   takes a single 
15860 69 6e 74 65 67 65 72 0a 2a 2a 20 61 72 67 75 6d  integer.** argum
15870 65 6e 74 20 77 68 69 63 68 20 69 73 20 69 6e 74  ent which is int
15880 65 72 70 72 65 74 65 64 20 61 73 20 61 20 62 6f  erpreted as a bo
15890 6f 6c 65 61 6e 20 69 6e 20 6f 72 64 65 72 20 74  olean in order t
158a0 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64 69 73 61  o enable or disa
158b0 62 6c 65 0a 2a 2a 20 74 68 65 20 75 73 65 20 6f  ble.** the use o
158c0 66 20 63 6f 76 65 72 69 6e 67 20 69 6e 64 69 63  f covering indic
158d0 65 73 20 66 6f 72 20 66 75 6c 6c 20 74 61 62 6c  es for full tabl
158e0 65 20 73 63 61 6e 73 20 69 6e 20 74 68 65 20 71  e scans in the q
158f0 75 65 72 79 20 6f 70 74 69 6d 69 7a 65 72 2e 0a  uery optimizer..
15900 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20  ** ^The default 
15910 73 65 74 74 69 6e 67 20 69 73 20 64 65 74 65 72  setting is deter
15920 6d 69 6e 65 64 0a 2a 2a 20 62 79 20 74 68 65 20  mined.** by the 
15930 5b 53 51 4c 49 54 45 5f 41 4c 4c 4f 57 5f 43 4f  [SQLITE_ALLOW_CO
15940 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41  VERING_INDEX_SCA
15950 4e 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  N] compile-time 
15960 6f 70 74 69 6f 6e 2c 20 6f 72 20 69 73 20 22 6f  option, or is "o
15970 6e 22 0a 2a 2a 20 69 66 20 74 68 61 74 20 63 6f  n".** if that co
15980 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
15990 6e 20 69 73 20 6f 6d 69 74 74 65 64 2e 0a 2a 2a  n is omitted..**
159a0 20 54 68 65 20 61 62 69 6c 69 74 79 20 74 6f 20   The ability to 
159b0 64 69 73 61 62 6c 65 20 74 68 65 20 75 73 65 20  disable the use 
159c0 6f 66 20 63 6f 76 65 72 69 6e 67 20 69 6e 64 69  of covering indi
159d0 63 65 73 20 66 6f 72 20 66 75 6c 6c 20 74 61 62  ces for full tab
159e0 6c 65 20 73 63 61 6e 73 0a 2a 2a 20 69 73 20 62  le scans.** is b
159f0 65 63 61 75 73 65 20 73 6f 6d 65 20 69 6e 63 6f  ecause some inco
15a00 72 72 65 63 74 6c 79 20 63 6f 64 65 64 20 6c 65  rrectly coded le
15a10 67 61 63 79 20 61 70 70 6c 69 63 61 74 69 6f 6e  gacy application
15a20 73 20 6d 69 67 68 74 20 6d 61 6c 66 75 6e 63 74  s might malfunct
15a30 69 6f 6e 0a 2a 2a 20 77 68 65 6e 20 74 68 65 20  ion.** when the 
15a40 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 20 69 73 20  optimization is 
15a50 65 6e 61 62 6c 65 64 2e 20 20 50 72 6f 76 69 64  enabled.  Provid
15a60 69 6e 67 20 74 68 65 20 61 62 69 6c 69 74 79 20  ing the ability 
15a70 74 6f 0a 2a 2a 20 64 69 73 61 62 6c 65 20 74 68  to.** disable th
15a80 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 20 61  e optimization a
15a90 6c 6c 6f 77 73 20 74 68 65 20 6f 6c 64 65 72 2c  llows the older,
15aa0 20 62 75 67 67 79 20 61 70 70 6c 69 63 61 74 69   buggy applicati
15ab0 6f 6e 20 63 6f 64 65 20 74 6f 20 77 6f 72 6b 0a  on code to work.
15ac0 2a 2a 20 77 69 74 68 6f 75 74 20 63 68 61 6e 67  ** without chang
15ad0 65 20 65 76 65 6e 20 77 69 74 68 20 6e 65 77 65  e even with newe
15ae0 72 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51  r versions of SQ
15af0 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  Lite..**.** [[SQ
15b00 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43  LITE_CONFIG_PCAC
15b10 48 45 5d 5d 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  HE]] [[SQLITE_CO
15b20 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 5d 5d  NFIG_GETPCACHE]]
15b30 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  .** <dt>SQLITE_C
15b40 4f 4e 46 49 47 5f 50 43 41 43 48 45 20 61 6e 64  ONFIG_PCACHE and
15b50 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47   SQLITE_CONFIG_G
15b60 45 54 50 43 41 43 48 45 0a 2a 2a 20 3c 64 64 3e  ETPCACHE.** <dd>
15b70 20 54 68 65 73 65 20 6f 70 74 69 6f 6e 73 20 61   These options a
15b80 72 65 20 6f 62 73 6f 6c 65 74 65 20 61 6e 64 20  re obsolete and 
15b90 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 75 73  should not be us
15ba0 65 64 20 62 79 20 6e 65 77 20 63 6f 64 65 2e 0a  ed by new code..
15bb0 2a 2a 20 54 68 65 79 20 61 72 65 20 72 65 74 61  ** They are reta
15bc0 69 6e 65 64 20 66 6f 72 20 62 61 63 6b 77 61 72  ined for backwar
15bd0 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79  ds compatibility
15be0 20 62 75 74 20 61 72 65 20 6e 6f 77 20 6e 6f 2d   but are now no-
15bf0 6f 70 73 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a  ops..** </dd>.**
15c00 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
15c10 46 49 47 5f 53 51 4c 4c 4f 47 5d 5d 0a 2a 2a 20  FIG_SQLLOG]].** 
15c20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
15c30 47 5f 53 51 4c 4c 4f 47 0a 2a 2a 20 3c 64 64 3e  G_SQLLOG.** <dd>
15c40 54 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 6f  This option is o
15c50 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 69 66  nly available if
15c60 20 73 71 6c 69 74 65 20 69 73 20 63 6f 6d 70 69   sqlite is compi
15c70 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20  led with the.** 
15c80 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 53  [SQLITE_ENABLE_S
15c90 51 4c 4c 4f 47 5d 20 70 72 65 2d 70 72 6f 63 65  QLLOG] pre-proce
15ca0 73 73 6f 72 20 6d 61 63 72 6f 20 64 65 66 69 6e  ssor macro defin
15cb0 65 64 2e 20 54 68 65 20 66 69 72 73 74 20 61 72  ed. The first ar
15cc0 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 0a 2a 2a  gument should.**
15cd0 20 62 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   be a pointer to
15ce0 20 61 20 66 75 6e 63 74 69 6f 6e 20 6f 66 20 74   a function of t
15cf0 79 70 65 20 76 6f 69 64 28 2a 29 28 76 6f 69 64  ype void(*)(void
15d00 2a 2c 73 71 6c 69 74 65 33 2a 2c 63 6f 6e 73 74  *,sqlite3*,const
15d10 20 63 68 61 72 2a 2c 20 69 6e 74 29 2e 0a 2a 2a   char*, int)..**
15d20 20 54 68 65 20 73 65 63 6f 6e 64 20 73 68 6f 75   The second shou
15d30 6c 64 20 62 65 20 6f 66 20 74 79 70 65 20 28 76  ld be of type (v
15d40 6f 69 64 2a 29 2e 20 54 68 65 20 63 61 6c 6c 62  oid*). The callb
15d50 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 62  ack is invoked b
15d60 79 20 74 68 65 20 6c 69 62 72 61 72 79 0a 2a 2a  y the library.**
15d70 20 69 6e 20 74 68 72 65 65 20 73 65 70 61 72 61   in three separa
15d80 74 65 20 63 69 72 63 75 6d 73 74 61 6e 63 65 73  te circumstances
15d90 2c 20 69 64 65 6e 74 69 66 69 65 64 20 62 79 20  , identified by 
15da0 74 68 65 20 76 61 6c 75 65 20 70 61 73 73 65 64  the value passed
15db0 20 61 73 20 74 68 65 0a 2a 2a 20 66 6f 75 72 74   as the.** fourt
15dc0 68 20 70 61 72 61 6d 65 74 65 72 2e 20 49 66 20  h parameter. If 
15dd0 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  the fourth param
15de0 65 74 65 72 20 69 73 20 30 2c 20 74 68 65 6e 20  eter is 0, then 
15df0 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
15e00 6e 65 63 74 69 6f 6e 0a 2a 2a 20 70 61 73 73 65  nection.** passe
15e10 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20  d as the second 
15e20 61 72 67 75 6d 65 6e 74 20 68 61 73 20 6a 75 73  argument has jus
15e30 74 20 62 65 65 6e 20 6f 70 65 6e 65 64 2e 20 54  t been opened. T
15e40 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e  he third argumen
15e50 74 0a 2a 2a 20 70 6f 69 6e 74 73 20 74 6f 20 61  t.** points to a
15e60 20 62 75 66 66 65 72 20 63 6f 6e 74 61 69 6e 69   buffer containi
15e70 6e 67 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  ng the name of t
15e80 68 65 20 6d 61 69 6e 20 64 61 74 61 62 61 73 65  he main database
15e90 20 66 69 6c 65 2e 20 49 66 20 74 68 65 0a 2a 2a   file. If the.**
15ea0 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
15eb0 72 20 69 73 20 31 2c 20 74 68 65 6e 20 74 68 65  r is 1, then the
15ec0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74   SQL statement t
15ed0 68 61 74 20 74 68 65 20 74 68 69 72 64 20 70 61  hat the third pa
15ee0 72 61 6d 65 74 65 72 0a 2a 2a 20 70 6f 69 6e 74  rameter.** point
15ef0 73 20 74 6f 20 68 61 73 20 6a 75 73 74 20 62 65  s to has just be
15f00 65 6e 20 65 78 65 63 75 74 65 64 2e 20 4f 72 2c  en executed. Or,
15f10 20 69 66 20 74 68 65 20 66 6f 75 72 74 68 20 70   if the fourth p
15f20 61 72 61 6d 65 74 65 72 20 69 73 20 32 2c 20 74  arameter is 2, t
15f30 68 65 6e 0a 2a 2a 20 74 68 65 20 63 6f 6e 6e 65  hen.** the conne
15f40 63 74 69 6f 6e 20 62 65 69 6e 67 20 70 61 73 73  ction being pass
15f50 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64  ed as the second
15f60 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 62 65   parameter is be
15f70 69 6e 67 20 63 6c 6f 73 65 64 2e 20 54 68 65 0a  ing closed. The.
15f80 2a 2a 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  ** third paramet
15f90 65 72 20 69 73 20 70 61 73 73 65 64 20 4e 55 4c  er is passed NUL
15fa0 4c 20 49 6e 20 74 68 69 73 20 63 61 73 65 2e 20  L In this case. 
15fb0 20 41 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20 75   An example of u
15fc0 73 69 6e 67 20 74 68 69 73 0a 2a 2a 20 63 6f 6e  sing this.** con
15fd0 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
15fe0 6e 20 63 61 6e 20 62 65 20 73 65 65 6e 20 69 6e  n can be seen in
15ff0 20 74 68 65 20 22 74 65 73 74 5f 73 71 6c 6c 6f   the "test_sqllo
16000 67 2e 63 22 20 73 6f 75 72 63 65 20 66 69 6c 65  g.c" source file
16010 20 69 6e 0a 2a 2a 20 74 68 65 20 63 61 6e 6f 6e   in.** the canon
16020 69 63 61 6c 20 53 51 4c 69 74 65 20 73 6f 75 72  ical SQLite sour
16030 63 65 20 74 72 65 65 2e 3c 2f 64 64 3e 0a 2a 2a  ce tree.</dd>.**
16040 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
16050 46 49 47 5f 4d 4d 41 50 5f 53 49 5a 45 5d 5d 0a  FIG_MMAP_SIZE]].
16060 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ** <dt>SQLITE_CO
16070 4e 46 49 47 5f 4d 4d 41 50 5f 53 49 5a 45 0a 2a  NFIG_MMAP_SIZE.*
16080 2a 20 3c 64 64 3e 5e 53 51 4c 49 54 45 5f 43 4f  * <dd>^SQLITE_CO
16090 4e 46 49 47 5f 4d 4d 41 50 5f 53 49 5a 45 20 74  NFIG_MMAP_SIZE t
160a0 61 6b 65 73 20 74 77 6f 20 36 34 2d 62 69 74 20  akes two 64-bit 
160b0 69 6e 74 65 67 65 72 20 28 73 71 6c 69 74 65 33  integer (sqlite3
160c0 5f 69 6e 74 36 34 29 20 76 61 6c 75 65 73 0a 2a  _int64) values.*
160d0 2a 20 74 68 61 74 20 61 72 65 20 74 68 65 20 64  * that are the d
160e0 65 66 61 75 6c 74 20 6d 6d 61 70 20 73 69 7a 65  efault mmap size
160f0 20 6c 69 6d 69 74 20 28 74 68 65 20 64 65 66 61   limit (the defa
16100 75 6c 74 20 73 65 74 74 69 6e 67 20 66 6f 72 0a  ult setting for.
16110 2a 2a 20 5b 50 52 41 47 4d 41 20 6d 6d 61 70 5f  ** [PRAGMA mmap_
16120 73 69 7a 65 5d 29 20 61 6e 64 20 74 68 65 20 6d  size]) and the m
16130 61 78 69 6d 75 6d 20 61 6c 6c 6f 77 65 64 20 6d  aximum allowed m
16140 6d 61 70 20 73 69 7a 65 20 6c 69 6d 69 74 2e 0a  map size limit..
16150 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20  ** ^The default 
16160 73 65 74 74 69 6e 67 20 63 61 6e 20 62 65 20 6f  setting can be o
16170 76 65 72 72 69 64 64 65 6e 20 62 79 20 65 61 63  verridden by eac
16180 68 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  h database conne
16190 63 74 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 65  ction using.** e
161a0 69 74 68 65 72 20 74 68 65 20 5b 50 52 41 47 4d  ither the [PRAGM
161b0 41 20 6d 6d 61 70 5f 73 69 7a 65 5d 20 63 6f 6d  A mmap_size] com
161c0 6d 61 6e 64 2c 20 6f 72 20 62 79 20 75 73 69 6e  mand, or by usin
161d0 67 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45  g the.** [SQLITE
161e0 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45  _FCNTL_MMAP_SIZE
161f0 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 2e 20  ] file control. 
16200 20 5e 28 54 68 65 20 6d 61 78 69 6d 75 6d 20 61   ^(The maximum a
16210 6c 6c 6f 77 65 64 20 6d 6d 61 70 20 73 69 7a 65  llowed mmap size
16220 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 73 69 6c 65  .** will be sile
16230 6e 74 6c 79 20 74 72 75 6e 63 61 74 65 64 20 69  ntly truncated i
16240 66 20 6e 65 63 65 73 73 61 72 79 20 73 6f 20 74  f necessary so t
16250 68 61 74 20 69 74 20 64 6f 65 73 20 6e 6f 74 20  hat it does not 
16260 65 78 63 65 65 64 20 74 68 65 0a 2a 2a 20 63 6f  exceed the.** co
16270 6d 70 69 6c 65 2d 74 69 6d 65 20 6d 61 78 69 6d  mpile-time maxim
16280 75 6d 20 6d 6d 61 70 20 73 69 7a 65 20 73 65 74  um mmap size set
16290 20 62 79 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49   by the.** [SQLI
162a0 54 45 5f 4d 41 58 5f 4d 4d 41 50 5f 53 49 5a 45  TE_MAX_MMAP_SIZE
162b0 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
162c0 70 74 69 6f 6e 2e 29 5e 0a 2a 2a 20 5e 49 66 20  ption.)^.** ^If 
162d0 65 69 74 68 65 72 20 61 72 67 75 6d 65 6e 74 20  either argument 
162e0 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 20 69  to this option i
162f0 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e  s negative, then
16300 20 74 68 61 74 20 61 72 67 75 6d 65 6e 74 20 69   that argument i
16310 73 0a 2a 2a 20 63 68 61 6e 67 65 64 20 74 6f 20  s.** changed to 
16320 69 74 73 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  its compile-time
16330 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20   default..**.** 
16340 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
16350 57 49 4e 33 32 5f 48 45 41 50 53 49 5a 45 5d 5d  WIN32_HEAPSIZE]]
16360 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  .** <dt>SQLITE_C
16370 4f 4e 46 49 47 5f 57 49 4e 33 32 5f 48 45 41 50  ONFIG_WIN32_HEAP
16380 53 49 5a 45 0a 2a 2a 20 3c 64 64 3e 5e 54 68 65  SIZE.** <dd>^The
16390 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 57   SQLITE_CONFIG_W
163a0 49 4e 33 32 5f 48 45 41 50 53 49 5a 45 20 6f 70  IN32_HEAPSIZE op
163b0 74 69 6f 6e 20 69 73 20 6f 6e 6c 79 20 61 76 61  tion is only ava
163c0 69 6c 61 62 6c 65 20 69 66 20 53 51 4c 69 74 65  ilable if SQLite
163d0 20 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20   is.** compiled 
163e0 66 6f 72 20 57 69 6e 64 6f 77 73 20 77 69 74 68  for Windows with
163f0 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 57 49 4e   the [SQLITE_WIN
16400 33 32 5f 4d 41 4c 4c 4f 43 5d 20 70 72 65 2d 70  32_MALLOC] pre-p
16410 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 0a 2a  rocessor macro.*
16420 2a 20 64 65 66 69 6e 65 64 2e 20 5e 53 51 4c 49  * defined. ^SQLI
16430 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f  TE_CONFIG_WIN32_
16440 48 45 41 50 53 49 5a 45 20 74 61 6b 65 73 20 61  HEAPSIZE takes a
16450 20 33 32 2d 62 69 74 20 75 6e 73 69 67 6e 65 64   32-bit unsigned
16460 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 0a 2a   integer value.*
16470 2a 20 74 68 61 74 20 73 70 65 63 69 66 69 65 73  * that specifies
16480 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 73 69 7a   the maximum siz
16490 65 20 6f 66 20 74 68 65 20 63 72 65 61 74 65 64  e of the created
164a0 20 68 65 61 70 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53   heap..**.** [[S
164b0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41  QLITE_CONFIG_PCA
164c0 43 48 45 5f 48 44 52 53 5a 5d 5d 0a 2a 2a 20 3c  CHE_HDRSZ]].** <
164d0 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
164e0 5f 50 43 41 43 48 45 5f 48 44 52 53 5a 0a 2a 2a  _PCACHE_HDRSZ.**
164f0 20 3c 64 64 3e 5e 54 68 65 20 53 51 4c 49 54 45   <dd>^The SQLITE
16500 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 5f 48  _CONFIG_PCACHE_H
16510 44 52 53 5a 20 6f 70 74 69 6f 6e 20 74 61 6b 65  DRSZ option take
16520 73 20 61 20 73 69 6e 67 6c 65 20 70 61 72 61 6d  s a single param
16530 65 74 65 72 20 77 68 69 63 68 0a 2a 2a 20 69 73  eter which.** is
16540 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
16550 20 69 6e 74 65 67 65 72 20 61 6e 64 20 77 72 69   integer and wri
16560 74 65 73 20 69 6e 74 6f 20 74 68 61 74 20 69 6e  tes into that in
16570 74 65 67 65 72 20 74 68 65 20 6e 75 6d 62 65 72  teger the number
16580 20 6f 66 20 65 78 74 72 61 0a 2a 2a 20 62 79 74   of extra.** byt
16590 65 73 20 70 65 72 20 70 61 67 65 20 72 65 71 75  es per page requ
165a0 69 72 65 64 20 66 6f 72 20 65 61 63 68 20 70 61  ired for each pa
165b0 67 65 20 69 6e 20 5b 53 51 4c 49 54 45 5f 43 4f  ge in [SQLITE_CO
165c0 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 5d 2e  NFIG_PAGECACHE].
165d0 0a 2a 2a 20 54 68 65 20 61 6d 6f 75 6e 74 20 6f  .** The amount o
165e0 66 20 65 78 74 72 61 20 73 70 61 63 65 20 72 65  f extra space re
165f0 71 75 69 72 65 64 20 63 61 6e 20 63 68 61 6e 67  quired can chang
16600 65 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74  e depending on t
16610 68 65 20 63 6f 6d 70 69 6c 65 72 2c 0a 2a 2a 20  he compiler,.** 
16620 74 61 72 67 65 74 20 70 6c 61 74 66 6f 72 6d 2c  target platform,
16630 20 61 6e 64 20 53 51 4c 69 74 65 20 76 65 72 73   and SQLite vers
16640 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  ion..**.** [[SQL
16650 49 54 45 5f 43 4f 4e 46 49 47 5f 50 4d 41 53 5a  ITE_CONFIG_PMASZ
16660 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  ]].** <dt>SQLITE
16670 5f 43 4f 4e 46 49 47 5f 50 4d 41 53 5a 0a 2a 2a  _CONFIG_PMASZ.**
16680 20 3c 64 64 3e 5e 54 68 65 20 53 51 4c 49 54 45   <dd>^The SQLITE
16690 5f 43 4f 4e 46 49 47 5f 50 4d 41 53 5a 20 6f 70  _CONFIG_PMASZ op
166a0 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e  tion takes a sin
166b0 67 6c 65 20 70 61 72 61 6d 65 74 65 72 20 77 68  gle parameter wh
166c0 69 63 68 0a 2a 2a 20 69 73 20 61 6e 20 75 6e 73  ich.** is an uns
166d0 69 67 6e 65 64 20 69 6e 74 65 67 65 72 20 61 6e  igned integer an
166e0 64 20 73 65 74 73 20 74 68 65 20 22 4d 69 6e 69  d sets the "Mini
166f0 6d 75 6d 20 50 4d 41 20 53 69 7a 65 22 20 66 6f  mum PMA Size" fo
16700 72 20 74 68 65 20 6d 75 6c 74 69 74 68 72 65 61  r the multithrea
16710 64 65 64 0a 2a 2a 20 73 6f 72 74 65 72 20 74 6f  ded.** sorter to
16720 20 74 68 61 74 20 69 6e 74 65 67 65 72 2e 20 20   that integer.  
16730 54 68 65 20 64 65 66 61 75 6c 74 20 6d 69 6e 69  The default mini
16740 6d 75 6d 20 50 4d 41 20 53 69 7a 65 20 69 73 20  mum PMA Size is 
16750 73 65 74 20 62 79 20 74 68 65 0a 2a 2a 20 5b 53  set by the.** [S
16760 51 4c 49 54 45 5f 53 4f 52 54 45 52 5f 50 4d 41  QLITE_SORTER_PMA
16770 53 5a 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  SZ] compile-time
16780 20 6f 70 74 69 6f 6e 2e 20 20 4e 65 77 20 74 68   option.  New th
16790 72 65 61 64 73 20 61 72 65 20 6c 61 75 6e 63 68  reads are launch
167a0 65 64 0a 2a 2a 20 74 6f 20 68 65 6c 70 20 77 69  ed.** to help wi
167b0 74 68 20 73 6f 72 74 20 6f 70 65 72 61 74 69 6f  th sort operatio
167c0 6e 73 20 77 68 65 6e 20 6d 75 6c 74 69 74 68 72  ns when multithr
167d0 65 61 64 65 64 20 73 6f 72 74 69 6e 67 0a 2a 2a  eaded sorting.**
167e0 20 69 73 20 65 6e 61 62 6c 65 64 20 28 75 73 69   is enabled (usi
167f0 6e 67 20 74 68 65 20 5b 50 52 41 47 4d 41 20 74  ng the [PRAGMA t
16800 68 72 65 61 64 73 5d 20 63 6f 6d 6d 61 6e 64 29  hreads] command)
16810 20 61 6e 64 20 74 68 65 20 61 6d 6f 75 6e 74 20   and the amount 
16820 6f 66 20 63 6f 6e 74 65 6e 74 0a 2a 2a 20 74 6f  of content.** to
16830 20 62 65 20 73 6f 72 74 65 64 20 65 78 63 65 65   be sorted excee
16840 64 73 20 74 68 65 20 70 61 67 65 20 73 69 7a 65  ds the page size
16850 20 74 69 6d 65 73 20 74 68 65 20 6d 69 6e 69 6d   times the minim
16860 75 6d 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 50 52  um of the.** [PR
16870 41 47 4d 41 20 63 61 63 68 65 5f 73 69 7a 65 5d  AGMA cache_size]
16880 20 73 65 74 74 69 6e 67 20 61 6e 64 20 74 68 69   setting and thi
16890 73 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 5b  s value..**.** [
168a0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53  [SQLITE_CONFIG_S
168b0 54 4d 54 4a 52 4e 4c 5f 53 50 49 4c 4c 5d 5d 0a  TMTJRNL_SPILL]].
168c0 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ** <dt>SQLITE_CO
168d0 4e 46 49 47 5f 53 54 4d 54 4a 52 4e 4c 5f 53 50  NFIG_STMTJRNL_SP
168e0 49 4c 4c 0a 2a 2a 20 3c 64 64 3e 5e 54 68 65 20  ILL.** <dd>^The 
168f0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 54  SQLITE_CONFIG_ST
16900 4d 54 4a 52 4e 4c 5f 53 50 49 4c 4c 20 6f 70 74  MTJRNL_SPILL opt
16910 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67  ion takes a sing
16920 6c 65 20 70 61 72 61 6d 65 74 65 72 20 77 68 69  le parameter whi
16930 63 68 0a 2a 2a 20 62 65 63 6f 6d 65 73 20 74 68  ch.** becomes th
16940 65 20 5b 73 74 61 74 65 6d 65 6e 74 20 6a 6f 75  e [statement jou
16950 72 6e 61 6c 5d 20 73 70 69 6c 6c 2d 74 6f 2d 64  rnal] spill-to-d
16960 69 73 6b 20 74 68 72 65 73 68 6f 6c 64 2e 20 20  isk threshold.  
16970 0a 2a 2a 20 5b 53 74 61 74 65 6d 65 6e 74 20 6a  .** [Statement j
16980 6f 75 72 6e 61 6c 73 5d 20 61 72 65 20 68 65 6c  ournals] are hel
16990 64 20 69 6e 20 6d 65 6d 6f 72 79 20 75 6e 74 69  d in memory unti
169a0 6c 20 74 68 65 69 72 20 73 69 7a 65 20 28 69 6e  l their size (in
169b0 20 62 79 74 65 73 29 0a 2a 2a 20 65 78 63 65 65   bytes).** excee
169c0 64 73 20 74 68 69 73 20 74 68 72 65 73 68 6f 6c  ds this threshol
169d0 64 2c 20 61 74 20 77 68 69 63 68 20 70 6f 69 6e  d, at which poin
169e0 74 20 74 68 65 79 20 61 72 65 20 77 72 69 74 74  t they are writt
169f0 65 6e 20 74 6f 20 64 69 73 6b 2e 0a 2a 2a 20 4f  en to disk..** O
16a00 72 20 69 66 20 74 68 65 20 74 68 72 65 73 68 6f  r if the thresho
16a10 6c 64 20 69 73 20 2d 31 2c 20 73 74 61 74 65 6d  ld is -1, statem
16a20 65 6e 74 20 6a 6f 75 72 6e 61 6c 73 20 61 72 65  ent journals are
16a30 20 61 6c 77 61 79 73 20 68 65 6c 64 0a 2a 2a 20   always held.** 
16a40 65 78 63 6c 75 73 69 76 65 6c 79 20 69 6e 20 6d  exclusively in m
16a50 65 6d 6f 72 79 2e 0a 2a 2a 20 53 69 6e 63 65 20  emory..** Since 
16a60 6d 61 6e 79 20 73 74 61 74 65 6d 65 6e 74 20 6a  many statement j
16a70 6f 75 72 6e 61 6c 73 20 6e 65 76 65 72 20 62 65  ournals never be
16a80 63 6f 6d 65 20 6c 61 72 67 65 2c 20 73 65 74 74  come large, sett
16a90 69 6e 67 20 74 68 65 20 73 70 69 6c 6c 0a 2a 2a  ing the spill.**
16aa0 20 74 68 72 65 73 68 6f 6c 64 20 74 6f 20 61 20   threshold to a 
16ab0 76 61 6c 75 65 20 73 75 63 68 20 61 73 20 36 34  value such as 64
16ac0 4b 69 42 20 63 61 6e 20 67 72 65 61 74 6c 79 20  KiB can greatly 
16ad0 72 65 64 75 63 65 20 74 68 65 20 61 6d 6f 75 6e  reduce the amoun
16ae0 74 20 6f 66 0a 2a 2a 20 49 2f 4f 20 72 65 71 75  t of.** I/O requ
16af0 69 72 65 64 20 74 6f 20 73 75 70 70 6f 72 74 20  ired to support 
16b00 73 74 61 74 65 6d 65 6e 74 20 72 6f 6c 6c 62 61  statement rollba
16b10 63 6b 2e 0a 2a 2a 20 54 68 65 20 64 65 66 61 75  ck..** The defau
16b20 6c 74 20 76 61 6c 75 65 20 66 6f 72 20 74 68 69  lt value for thi
16b30 73 20 73 65 74 74 69 6e 67 20 69 73 20 63 6f 6e  s setting is con
16b40 74 72 6f 6c 6c 65 64 20 62 79 20 74 68 65 0a 2a  trolled by the.*
16b50 2a 20 5b 53 51 4c 49 54 45 5f 53 54 4d 54 4a 52  * [SQLITE_STMTJR
16b60 4e 4c 5f 53 50 49 4c 4c 5d 20 63 6f 6d 70 69 6c  NL_SPILL] compil
16b70 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2e 0a 2a  e-time option..*
16b80 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69  * </dl>.*/.#defi
16b90 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
16ba0 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 20 20 31  _SINGLETHREAD  1
16bb0 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66    /* nil */.#def
16bc0 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
16bd0 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 20 20 20  G_MULTITHREAD   
16be0 32 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65  2  /* nil */.#de
16bf0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
16c00 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 20 20 20  IG_SERIALIZED   
16c10 20 33 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64   3  /* nil */.#d
16c20 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
16c30 46 49 47 5f 4d 41 4c 4c 4f 43 20 20 20 20 20 20  FIG_MALLOC      
16c40 20 20 34 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f    4  /* sqlite3_
16c50 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a  mem_methods* */.
16c60 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
16c70 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 20  ONFIG_GETMALLOC 
16c80 20 20 20 20 35 20 20 2f 2a 20 73 71 6c 69 74 65      5  /* sqlite
16c90 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a  3_mem_methods* *
16ca0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
16cb0 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 20  _CONFIG_SCRATCH 
16cc0 20 20 20 20 20 20 36 20 20 2f 2a 20 76 6f 69 64        6  /* void
16cd0 2a 2c 20 69 6e 74 20 73 7a 2c 20 69 6e 74 20 4e  *, int sz, int N
16ce0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
16cf0 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41  TE_CONFIG_PAGECA
16d00 43 48 45 20 20 20 20 20 37 20 20 2f 2a 20 76 6f  CHE     7  /* vo
16d10 69 64 2a 2c 20 69 6e 74 20 73 7a 2c 20 69 6e 74  id*, int sz, int
16d20 20 4e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51   N */.#define SQ
16d30 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50  LITE_CONFIG_HEAP
16d40 20 20 20 20 20 20 20 20 20 20 38 20 20 2f 2a 20            8  /* 
16d50 76 6f 69 64 2a 2c 20 69 6e 74 20 6e 42 79 74 65  void*, int nByte
16d60 2c 20 69 6e 74 20 6d 69 6e 20 2a 2f 0a 23 64 65  , int min */.#de
16d70 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
16d80 49 47 5f 4d 45 4d 53 54 41 54 55 53 20 20 20 20  IG_MEMSTATUS    
16d90 20 39 20 20 2f 2a 20 62 6f 6f 6c 65 61 6e 20 2a   9  /* boolean *
16da0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
16db0 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 20 20 20  _CONFIG_MUTEX   
16dc0 20 20 20 20 20 31 30 20 20 2f 2a 20 73 71 6c 69       10  /* sqli
16dd0 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64  te3_mutex_method
16de0 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  s* */.#define SQ
16df0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d  LITE_CONFIG_GETM
16e00 55 54 45 58 20 20 20 20 20 31 31 20 20 2f 2a 20  UTEX     11  /* 
16e10 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65  sqlite3_mutex_me
16e20 74 68 6f 64 73 2a 20 2a 2f 0a 2f 2a 20 70 72 65  thods* */./* pre
16e30 76 69 6f 75 73 6c 79 20 53 51 4c 49 54 45 5f 43  viously SQLITE_C
16e40 4f 4e 46 49 47 5f 43 48 55 4e 4b 41 4c 4c 4f 43  ONFIG_CHUNKALLOC
16e50 20 31 32 20 77 68 69 63 68 20 69 73 20 6e 6f 77   12 which is now
16e60 20 75 6e 75 73 65 64 2e 20 2a 2f 20 0a 23 64 65   unused. */ .#de
16e70 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
16e80 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 20 20 20  IG_LOOKASIDE    
16e90 31 33 20 20 2f 2a 20 69 6e 74 20 69 6e 74 20 2a  13  /* int int *
16ea0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
16eb0 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 20 20  _CONFIG_PCACHE  
16ec0 20 20 20 20 20 31 34 20 20 2f 2a 20 6e 6f 2d 6f       14  /* no-o
16ed0 70 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  p */.#define SQL
16ee0 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43  ITE_CONFIG_GETPC
16ef0 41 43 48 45 20 20 20 20 31 35 20 20 2f 2a 20 6e  ACHE    15  /* n
16f00 6f 2d 6f 70 20 2a 2f 0a 23 64 65 66 69 6e 65 20  o-op */.#define 
16f10 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f  SQLITE_CONFIG_LO
16f20 47 20 20 20 20 20 20 20 20 20 20 31 36 20 20 2f  G          16  /
16f30 2a 20 78 46 75 6e 63 2c 20 76 6f 69 64 2a 20 2a  * xFunc, void* *
16f40 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
16f50 5f 43 4f 4e 46 49 47 5f 55 52 49 20 20 20 20 20  _CONFIG_URI     
16f60 20 20 20 20 20 31 37 20 20 2f 2a 20 69 6e 74 20       17  /* int 
16f70 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
16f80 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32  E_CONFIG_PCACHE2
16f90 20 20 20 20 20 20 31 38 20 20 2f 2a 20 73 71 6c        18  /* sql
16fa0 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68  ite3_pcache_meth
16fb0 6f 64 73 32 2a 20 2a 2f 0a 23 64 65 66 69 6e 65  ods2* */.#define
16fc0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47   SQLITE_CONFIG_G
16fd0 45 54 50 43 41 43 48 45 32 20 20 20 31 39 20 20  ETPCACHE2   19  
16fe0 2f 2a 20 73 71 6c 69 74 65 33 5f 70 63 61 63 68  /* sqlite3_pcach
16ff0 65 5f 6d 65 74 68 6f 64 73 32 2a 20 2a 2f 0a 23  e_methods2* */.#
17000 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
17010 4e 46 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49 4e  NFIG_COVERING_IN
17020 44 45 58 5f 53 43 41 4e 20 32 30 20 20 2f 2a 20  DEX_SCAN 20  /* 
17030 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  int */.#define S
17040 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 51 4c  QLITE_CONFIG_SQL
17050 4c 4f 47 20 20 20 20 20 20 20 32 31 20 20 2f 2a  LOG       21  /*
17060 20 78 53 71 6c 6c 6f 67 2c 20 76 6f 69 64 2a 20   xSqllog, void* 
17070 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
17080 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f 53 49  E_CONFIG_MMAP_SI
17090 5a 45 20 20 20 20 32 32 20 20 2f 2a 20 73 71 6c  ZE    22  /* sql
170a0 69 74 65 33 5f 69 6e 74 36 34 2c 20 73 71 6c 69  ite3_int64, sqli
170b0 74 65 33 5f 69 6e 74 36 34 20 2a 2f 0a 23 64 65  te3_int64 */.#de
170c0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
170d0 49 47 5f 57 49 4e 33 32 5f 48 45 41 50 53 49 5a  IG_WIN32_HEAPSIZ
170e0 45 20 20 20 20 20 20 32 33 20 20 2f 2a 20 69 6e  E      23  /* in
170f0 74 20 6e 42 79 74 65 20 2a 2f 0a 23 64 65 66 69  t nByte */.#defi
17100 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
17110 5f 50 43 41 43 48 45 5f 48 44 52 53 5a 20 20 20  _PCACHE_HDRSZ   
17120 20 20 20 20 20 32 34 20 20 2f 2a 20 69 6e 74 20       24  /* int 
17130 2a 70 73 7a 20 2a 2f 0a 23 64 65 66 69 6e 65 20  *psz */.#define 
17140 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 4d  SQLITE_CONFIG_PM
17150 41 53 5a 20 20 20 20 20 20 20 20 20 20 20 20 20  ASZ             
17160 20 20 32 35 20 20 2f 2a 20 75 6e 73 69 67 6e 65    25  /* unsigne
17170 64 20 69 6e 74 20 73 7a 50 6d 61 20 2a 2f 0a 23  d int szPma */.#
17180 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
17190 4e 46 49 47 5f 53 54 4d 54 4a 52 4e 4c 5f 53 50  NFIG_STMTJRNL_SP
171a0 49 4c 4c 20 20 20 20 20 20 32 36 20 20 2f 2a 20  ILL      26  /* 
171b0 69 6e 74 20 6e 42 79 74 65 20 2a 2f 0a 0a 2f 2a  int nByte */../*
171c0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 61  .** CAPI3REF: Da
171d0 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f  tabase Connectio
171e0 6e 20 43 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  n Configuration 
171f0 4f 70 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68  Options.**.** Th
17200 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72  ese constants ar
17210 65 20 74 68 65 20 61 76 61 69 6c 61 62 6c 65 20  e the available 
17220 69 6e 74 65 67 65 72 20 63 6f 6e 66 69 67 75 72  integer configur
17230 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 74 68  ation options th
17240 61 74 0a 2a 2a 20 63 61 6e 20 62 65 20 70 61 73  at.** can be pas
17250 73 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e  sed as the secon
17260 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  d argument to th
17270 65 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f  e [sqlite3_db_co
17280 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63  nfig()] interfac
17290 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e  e..**.** New con
172a0 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
172b0 6e 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 20  ns may be added 
172c0 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73  in future releas
172d0 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a  es of SQLite..**
172e0 20 45 78 69 73 74 69 6e 67 20 63 6f 6e 66 69 67   Existing config
172f0 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20  uration options 
17300 6d 69 67 68 74 20 62 65 20 64 69 73 63 6f 6e 74  might be discont
17310 69 6e 75 65 64 2e 20 20 41 70 70 6c 69 63 61 74  inued.  Applicat
17320 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 63  ions.** should c
17330 68 65 63 6b 20 74 68 65 20 72 65 74 75 72 6e 20  heck the return 
17340 63 6f 64 65 20 66 72 6f 6d 20 5b 73 71 6c 69 74  code from [sqlit
17350 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20  e3_db_config()] 
17360 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 74 68 61  to make sure tha
17370 74 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20 77 6f  t.** the call wo
17380 72 6b 65 64 2e 20 20 5e 54 68 65 20 5b 73 71 6c  rked.  ^The [sql
17390 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29  ite3_db_config()
173a0 5d 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c  ] interface will
173b0 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e   return a.** non
173c0 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64  -zero [error cod
173d0 65 5d 20 69 66 20 61 20 64 69 73 63 6f 6e 74 69  e] if a disconti
173e0 6e 75 65 64 20 6f 72 20 75 6e 73 75 70 70 6f 72  nued or unsuppor
173f0 74 65 64 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ted configuratio
17400 6e 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73 20 69  n option.** is i
17410 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64  nvoked..**.** <d
17420 6c 3e 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  l>.** <dt>SQLITE
17430 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53  _DBCONFIG_LOOKAS
17440 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  IDE</dt>.** <dd>
17450 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61   ^This option ta
17460 6b 65 73 20 74 68 72 65 65 20 61 64 64 69 74 69  kes three additi
17470 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 20 74  onal arguments t
17480 68 61 74 20 64 65 74 65 72 6d 69 6e 65 20 74 68  hat determine th
17490 65 20 0a 2a 2a 20 5b 6c 6f 6f 6b 61 73 69 64 65  e .** [lookaside
174a0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f   memory allocato
174b0 72 5d 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  r] configuration
174c0 20 66 6f 72 20 74 68 65 20 5b 64 61 74 61 62 61   for the [databa
174d0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a  se connection]..
174e0 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 72  ** ^The first ar
174f0 67 75 6d 65 6e 74 20 28 74 68 65 20 74 68 69 72  gument (the thir
17500 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b  d parameter to [
17510 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69  sqlite3_db_confi
17520 67 28 29 5d 20 69 73 20 61 0a 2a 2a 20 70 6f 69  g()] is a.** poi
17530 6e 74 65 72 20 74 6f 20 61 20 6d 65 6d 6f 72 79  nter to a memory
17540 20 62 75 66 66 65 72 20 74 6f 20 75 73 65 20 66   buffer to use f
17550 6f 72 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d  or lookaside mem
17560 6f 72 79 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 72  ory..** ^The fir
17570 73 74 20 61 72 67 75 6d 65 6e 74 20 61 66 74 65  st argument afte
17580 72 20 74 68 65 20 53 51 4c 49 54 45 5f 44 42 43  r the SQLITE_DBC
17590 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20  ONFIG_LOOKASIDE 
175a0 76 65 72 62 0a 2a 2a 20 6d 61 79 20 62 65 20 4e  verb.** may be N
175b0 55 4c 4c 20 69 6e 20 77 68 69 63 68 20 63 61 73  ULL in which cas
175c0 65 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c  e SQLite will al
175d0 6c 6f 63 61 74 65 20 74 68 65 0a 2a 2a 20 6c 6f  locate the.** lo
175e0 6f 6b 61 73 69 64 65 20 62 75 66 66 65 72 20 69  okaside buffer i
175f0 74 73 65 6c 66 20 75 73 69 6e 67 20 5b 73 71 6c  tself using [sql
17600 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20  ite3_malloc()]. 
17610 5e 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75  ^The second argu
17620 6d 65 6e 74 20 69 73 20 74 68 65 0a 2a 2a 20 73  ment is the.** s
17630 69 7a 65 20 6f 66 20 65 61 63 68 20 6c 6f 6f 6b  ize of each look
17640 61 73 69 64 65 20 62 75 66 66 65 72 20 73 6c 6f  aside buffer slo
17650 74 2e 20 20 5e 54 68 65 20 74 68 69 72 64 20 61  t.  ^The third a
17660 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 6e  rgument is the n
17670 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 73 6c 6f 74  umber of.** slot
17680 73 2e 20 20 54 68 65 20 73 69 7a 65 20 6f 66 20  s.  The size of 
17690 74 68 65 20 62 75 66 66 65 72 20 69 6e 20 74 68  the buffer in th
176a0 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
176b0 20 6d 75 73 74 20 62 65 20 67 72 65 61 74 65 72   must be greater
176c0 20 74 68 61 6e 0a 2a 2a 20 6f 72 20 65 71 75 61   than.** or equa
176d0 6c 20 74 6f 20 74 68 65 20 70 72 6f 64 75 63 74  l to the product
176e0 20 6f 66 20 74 68 65 20 73 65 63 6f 6e 64 20 61   of the second a
176f0 6e 64 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e  nd third argumen
17700 74 73 2e 20 20 54 68 65 20 62 75 66 66 65 72 0a  ts.  The buffer.
17710 2a 2a 20 6d 75 73 74 20 62 65 20 61 6c 69 67 6e  ** must be align
17720 65 64 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 20  ed to an 8-byte 
17730 62 6f 75 6e 64 61 72 79 2e 20 20 5e 49 66 20 74  boundary.  ^If t
17740 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
17750 6e 74 20 74 6f 0a 2a 2a 20 53 51 4c 49 54 45 5f  nt to.** SQLITE_
17760 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49  DBCONFIG_LOOKASI
17770 44 45 20 69 73 20 6e 6f 74 20 61 20 6d 75 6c 74  DE is not a mult
17780 69 70 6c 65 20 6f 66 20 38 2c 20 69 74 20 69 73  iple of 8, it is
17790 20 69 6e 74 65 72 6e 61 6c 6c 79 0a 2a 2a 20 72   internally.** r
177a0 6f 75 6e 64 65 64 20 64 6f 77 6e 20 74 6f 20 74  ounded down to t
177b0 68 65 20 6e 65 78 74 20 73 6d 61 6c 6c 65 72 20  he next smaller 
177c0 6d 75 6c 74 69 70 6c 65 20 6f 66 20 38 2e 20 20  multiple of 8.  
177d0 5e 28 54 68 65 20 6c 6f 6f 6b 61 73 69 64 65 20  ^(The lookaside 
177e0 6d 65 6d 6f 72 79 0a 2a 2a 20 63 6f 6e 66 69 67  memory.** config
177f0 75 72 61 74 69 6f 6e 20 66 6f 72 20 61 20 64 61  uration for a da
17800 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
17810 6e 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 63 68  n can only be ch
17820 61 6e 67 65 64 20 77 68 65 6e 20 74 68 61 74 0a  anged when that.
17830 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  ** connection is
17840 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79 20 75   not currently u
17850 73 69 6e 67 20 6c 6f 6f 6b 61 73 69 64 65 20 6d  sing lookaside m
17860 65 6d 6f 72 79 2c 20 6f 72 20 69 6e 20 6f 74 68  emory, or in oth
17870 65 72 20 77 6f 72 64 73 0a 2a 2a 20 77 68 65 6e  er words.** when
17880 20 74 68 65 20 22 63 75 72 72 65 6e 74 20 76 61   the "current va
17890 6c 75 65 22 20 72 65 74 75 72 6e 65 64 20 62 79  lue" returned by
178a0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f  .** [sqlite3_db_
178b0 73 74 61 74 75 73 5d 28 44 2c 5b 53 51 4c 49 54  status](D,[SQLIT
178c0 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49  E_CONFIG_LOOKASI
178d0 44 45 5d 2c 2e 2e 2e 29 20 69 73 20 7a 65 72 6f  DE],...) is zero
178e0 2e 0a 2a 2a 20 41 6e 79 20 61 74 74 65 6d 70 74  ..** Any attempt
178f0 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65 20 6c   to change the l
17900 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20  ookaside memory 
17910 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 77 68  configuration wh
17920 65 6e 20 6c 6f 6f 6b 61 73 69 64 65 0a 2a 2a 20  en lookaside.** 
17930 6d 65 6d 6f 72 79 20 69 73 20 69 6e 20 75 73 65  memory is in use
17940 20 6c 65 61 76 65 73 20 74 68 65 20 63 6f 6e 66   leaves the conf
17950 69 67 75 72 61 74 69 6f 6e 20 75 6e 63 68 61 6e  iguration unchan
17960 67 65 64 20 61 6e 64 20 72 65 74 75 72 6e 73 20  ged and returns 
17970 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  .** [SQLITE_BUSY
17980 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ].)^</dd>.**.** 
17990 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e  <dt>SQLITE_DBCON
179a0 46 49 47 5f 45 4e 41 42 4c 45 5f 46 4b 45 59 3c  FIG_ENABLE_FKEY<
179b0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68  /dt>.** <dd> ^Th
179c0 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65  is option is use
179d0 64 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64  d to enable or d
179e0 69 73 61 62 6c 65 20 74 68 65 20 65 6e 66 6f 72  isable the enfor
179f0 63 65 6d 65 6e 74 20 6f 66 0a 2a 2a 20 5b 66 6f  cement of.** [fo
17a00 72 65 69 67 6e 20 6b 65 79 20 63 6f 6e 73 74 72  reign key constr
17a10 61 69 6e 74 73 5d 2e 20 20 54 68 65 72 65 20 73  aints].  There s
17a20 68 6f 75 6c 64 20 62 65 20 74 77 6f 20 61 64 64  hould be two add
17a30 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74  itional argument
17a40 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20  s..** The first 
17a50 61 72 67 75 6d 65 6e 74 20 69 73 20 61 6e 20 69  argument is an i
17a60 6e 74 65 67 65 72 20 77 68 69 63 68 20 69 73 20  nteger which is 
17a70 30 20 74 6f 20 64 69 73 61 62 6c 65 20 46 4b 20  0 to disable FK 
17a80 65 6e 66 6f 72 63 65 6d 65 6e 74 2c 0a 2a 2a 20  enforcement,.** 
17a90 70 6f 73 69 74 69 76 65 20 74 6f 20 65 6e 61 62  positive to enab
17aa0 6c 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e  le FK enforcemen
17ab0 74 20 6f 72 20 6e 65 67 61 74 69 76 65 20 74 6f  t or negative to
17ac0 20 6c 65 61 76 65 20 46 4b 20 65 6e 66 6f 72 63   leave FK enforc
17ad0 65 6d 65 6e 74 0a 2a 2a 20 75 6e 63 68 61 6e 67  ement.** unchang
17ae0 65 64 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20  ed.  The second 
17af0 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 70  parameter is a p
17b00 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74  ointer to an int
17b10 65 67 65 72 20 69 6e 74 6f 20 77 68 69 63 68 0a  eger into which.
17b20 2a 2a 20 69 73 20 77 72 69 74 74 65 6e 20 30 20  ** is written 0 
17b30 6f 72 20 31 20 74 6f 20 69 6e 64 69 63 61 74 65  or 1 to indicate
17b40 20 77 68 65 74 68 65 72 20 46 4b 20 65 6e 66 6f   whether FK enfo
17b50 72 63 65 6d 65 6e 74 20 69 73 20 6f 66 66 20 6f  rcement is off o
17b60 72 20 6f 6e 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e  r on.** followin
17b70 67 20 74 68 69 73 20 63 61 6c 6c 2e 20 20 54 68  g this call.  Th
17b80 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
17b90 65 72 20 6d 61 79 20 62 65 20 61 20 4e 55 4c 4c  er may be a NULL
17ba0 20 70 6f 69 6e 74 65 72 2c 20 69 6e 0a 2a 2a 20   pointer, in.** 
17bb0 77 68 69 63 68 20 63 61 73 65 20 74 68 65 20 46  which case the F
17bc0 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 73 65  K enforcement se
17bd0 74 74 69 6e 67 20 69 73 20 6e 6f 74 20 72 65 70  tting is not rep
17be0 6f 72 74 65 64 20 62 61 63 6b 2e 20 3c 2f 64 64  orted back. </dd
17bf0 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  >.**.** <dt>SQLI
17c00 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42  TE_DBCONFIG_ENAB
17c10 4c 45 5f 54 52 49 47 47 45 52 3c 2f 64 74 3e 0a  LE_TRIGGER</dt>.
17c20 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70  ** <dd> ^This op
17c30 74 69 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20  tion is used to 
17c40 65 6e 61 62 6c 65 20 6f 72 20 64 69 73 61 62 6c  enable or disabl
17c50 65 20 5b 43 52 45 41 54 45 20 54 52 49 47 47 45  e [CREATE TRIGGE
17c60 52 20 7c 20 74 72 69 67 67 65 72 73 5d 2e 0a 2a  R | triggers]..*
17c70 2a 20 54 68 65 72 65 20 73 68 6f 75 6c 64 20 62  * There should b
17c80 65 20 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c  e two additional
17c90 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20 54   arguments..** T
17ca0 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
17cb0 74 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20  t is an integer 
17cc0 77 68 69 63 68 20 69 73 20 30 20 74 6f 20 64 69  which is 0 to di
17cd0 73 61 62 6c 65 20 74 72 69 67 67 65 72 73 2c 0a  sable triggers,.
17ce0 2a 2a 20 70 6f 73 69 74 69 76 65 20 74 6f 20 65  ** positive to e
17cf0 6e 61 62 6c 65 20 74 72 69 67 67 65 72 73 20 6f  nable triggers o
17d00 72 20 6e 65 67 61 74 69 76 65 20 74 6f 20 6c 65  r negative to le
17d10 61 76 65 20 74 68 65 20 73 65 74 74 69 6e 67 20  ave the setting 
17d20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 20 54 68  unchanged..** Th
17d30 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
17d40 65 72 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20  er is a pointer 
17d50 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 69 6e  to an integer in
17d60 74 6f 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 77  to which.** is w
17d70 72 69 74 74 65 6e 20 30 20 6f 72 20 31 20 74 6f  ritten 0 or 1 to
17d80 20 69 6e 64 69 63 61 74 65 20 77 68 65 74 68 65   indicate whethe
17d90 72 20 74 72 69 67 67 65 72 73 20 61 72 65 20 64  r triggers are d
17da0 69 73 61 62 6c 65 64 20 6f 72 20 65 6e 61 62 6c  isabled or enabl
17db0 65 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20  ed.** following 
17dc0 74 68 69 73 20 63 61 6c 6c 2e 20 20 54 68 65 20  this call.  The 
17dd0 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
17de0 20 6d 61 79 20 62 65 20 61 20 4e 55 4c 4c 20 70   may be a NULL p
17df0 6f 69 6e 74 65 72 2c 20 69 6e 0a 2a 2a 20 77 68  ointer, in.** wh
17e00 69 63 68 20 63 61 73 65 20 74 68 65 20 74 72 69  ich case the tri
17e10 67 67 65 72 20 73 65 74 74 69 6e 67 20 69 73 20  gger setting is 
17e20 6e 6f 74 20 72 65 70 6f 72 74 65 64 20 62 61 63  not reported bac
17e30 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c  k. </dd>.**.** <
17e40 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46  dt>SQLITE_DBCONF
17e50 49 47 5f 45 4e 41 42 4c 45 5f 46 54 53 33 5f 54  IG_ENABLE_FTS3_T
17e60 4f 4b 45 4e 49 5a 45 52 3c 2f 64 74 3e 0a 2a 2a  OKENIZER</dt>.**
17e70 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69   <dd> ^This opti
17e80 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20 65 6e  on is used to en
17e90 61 62 6c 65 20 6f 72 20 64 69 73 61 62 6c 65 20  able or disable 
17ea0 74 68 65 20 74 77 6f 2d 61 72 67 75 6d 65 6e 74  the two-argument
17eb0 0a 2a 2a 20 76 65 72 73 69 6f 6e 20 6f 66 20 74  .** version of t
17ec0 68 65 20 5b 66 74 73 33 5f 74 6f 6b 65 6e 69 7a  he [fts3_tokeniz
17ed0 65 72 28 29 5d 20 66 75 6e 63 74 69 6f 6e 20 77  er()] function w
17ee0 68 69 63 68 20 69 73 20 70 61 72 74 20 6f 66 20  hich is part of 
17ef0 74 68 65 0a 2a 2a 20 5b 46 54 53 33 5d 20 66 75  the.** [FTS3] fu
17f00 6c 6c 2d 74 65 78 74 20 73 65 61 72 63 68 20 65  ll-text search e
17f10 6e 67 69 6e 65 20 65 78 74 65 6e 73 69 6f 6e 2e  ngine extension.
17f20 0a 2a 2a 20 54 68 65 72 65 20 73 68 6f 75 6c 64  .** There should
17f30 20 62 65 20 74 77 6f 20 61 64 64 69 74 69 6f 6e   be two addition
17f40 61 6c 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a  al arguments..**
17f50 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   The first argum
17f60 65 6e 74 20 69 73 20 61 6e 20 69 6e 74 65 67 65  ent is an intege
17f70 72 20 77 68 69 63 68 20 69 73 20 30 20 74 6f 20  r which is 0 to 
17f80 64 69 73 61 62 6c 65 20 66 74 73 33 5f 74 6f 6b  disable fts3_tok
17f90 65 6e 69 7a 65 72 28 29 20 6f 72 0a 2a 2a 20 70  enizer() or.** p
17fa0 6f 73 69 74 69 76 65 20 74 6f 20 65 6e 61 62 6c  ositive to enabl
17fb0 65 20 66 74 73 33 5f 74 6f 6b 65 6e 69 7a 65 72  e fts3_tokenizer
17fc0 28 29 20 6f 72 20 6e 65 67 61 74 69 76 65 20 74  () or negative t
17fd0 6f 20 6c 65 61 76 65 20 74 68 65 20 73 65 74 74  o leave the sett
17fe0 69 6e 67 0a 2a 2a 20 75 6e 63 68 61 6e 67 65 64  ing.** unchanged
17ff0 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20  ..** The second 
18000 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 70  parameter is a p
18010 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74  ointer to an int
18020 65 67 65 72 20 69 6e 74 6f 20 77 68 69 63 68 0a  eger into which.
18030 2a 2a 20 69 73 20 77 72 69 74 74 65 6e 20 30 20  ** is written 0 
18040 6f 72 20 31 20 74 6f 20 69 6e 64 69 63 61 74 65  or 1 to indicate
18050 20 77 68 65 74 68 65 72 20 66 74 73 33 5f 74 6f   whether fts3_to
18060 6b 65 6e 69 7a 65 72 20 69 73 20 64 69 73 61 62  kenizer is disab
18070 6c 65 64 20 6f 72 20 65 6e 61 62 6c 65 64 0a 2a  led or enabled.*
18080 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 69 73  * following this
18090 20 63 61 6c 6c 2e 20 20 54 68 65 20 73 65 63 6f   call.  The seco
180a0 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79  nd parameter may
180b0 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   be a NULL point
180c0 65 72 2c 20 69 6e 0a 2a 2a 20 77 68 69 63 68 20  er, in.** which 
180d0 63 61 73 65 20 74 68 65 20 6e 65 77 20 73 65 74  case the new set
180e0 74 69 6e 67 20 69 73 20 6e 6f 74 20 72 65 70 6f  ting is not repo
180f0 72 74 65 64 20 62 61 63 6b 2e 20 3c 2f 64 64 3e  rted back. </dd>
18100 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  .**.** <dt>SQLIT
18110 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c  E_DBCONFIG_ENABL
18120 45 5f 4c 4f 41 44 5f 45 58 54 45 4e 53 49 4f 4e  E_LOAD_EXTENSION
18130 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54  </dt>.** <dd> ^T
18140 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 75 73  his option is us
18150 65 64 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20  ed to enable or 
18160 64 69 73 61 62 6c 65 20 74 68 65 20 5b 73 71 6c  disable the [sql
18170 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65 6e 73  ite3_load_extens
18180 69 6f 6e 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66  ion()].** interf
18190 61 63 65 20 69 6e 64 65 70 65 6e 64 65 6e 74 6c  ace independentl
181a0 79 20 6f 66 20 74 68 65 20 5b 6c 6f 61 64 5f 65  y of the [load_e
181b0 78 74 65 6e 73 69 6f 6e 28 29 5d 20 53 51 4c 20  xtension()] SQL 
181c0 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 54 68 65  function..** The
181d0 20 5b 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65   [sqlite3_enable
181e0 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28  _load_extension(
181f0 29 5d 20 41 50 49 20 65 6e 61 62 6c 65 73 20 6f  )] API enables o
18200 72 20 64 69 73 61 62 6c 65 73 20 62 6f 74 68 20  r disables both 
18210 74 68 65 0a 2a 2a 20 43 2d 41 50 49 20 5b 73 71  the.** C-API [sq
18220 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65 6e  lite3_load_exten
18230 73 69 6f 6e 28 29 5d 20 61 6e 64 20 74 68 65 20  sion()] and the 
18240 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 5b 6c 6f  SQL function [lo
18250 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d 2e  ad_extension()].
18260 0a 2a 2a 20 54 68 65 72 65 20 73 68 6f 75 6c 64  .** There should
18270 20 62 65 20 74 77 6f 20 61 64 64 69 74 69 6f 6e   be two addition
18280 61 6c 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a  al arguments..**
18290 20 57 68 65 6e 20 74 68 65 20 66 69 72 73 74 20   When the first 
182a0 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 69 73  argument to this
182b0 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 31 2c   interface is 1,
182c0 20 74 68 65 6e 20 6f 6e 6c 79 20 74 68 65 20 43   then only the C
182d0 2d 41 50 49 20 69 73 0a 2a 2a 20 65 6e 61 62 6c  -API is.** enabl
182e0 65 64 20 61 6e 64 20 74 68 65 20 53 51 4c 20 66  ed and the SQL f
182f0 75 6e 63 74 69 6f 6e 20 72 65 6d 61 69 6e 73 20  unction remains 
18300 64 69 73 61 62 6c 65 64 2e 20 20 49 66 20 74 68  disabled.  If th
18310 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
18320 20 74 6f 0a 2a 2a 20 74 68 69 73 20 69 6e 74 65   to.** this inte
18330 72 66 61 63 65 20 69 73 20 30 2c 20 74 68 65 6e  rface is 0, then
18340 20 62 6f 74 68 20 74 68 65 20 43 2d 41 50 49 20   both the C-API 
18350 61 6e 64 20 74 68 65 20 53 51 4c 20 66 75 6e 63  and the SQL func
18360 74 69 6f 6e 20 61 72 65 20 64 69 73 61 62 6c 65  tion are disable
18370 64 2e 0a 2a 2a 20 49 66 20 74 68 65 20 66 69 72  d..** If the fir
18380 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20 2d  st argument is -
18390 31 2c 20 74 68 65 6e 20 6e 6f 20 63 68 61 6e 67  1, then no chang
183a0 65 73 20 61 72 65 20 6d 61 64 65 20 74 6f 20 73  es are made to s
183b0 74 61 74 65 20 6f 66 20 65 69 74 68 65 72 20 74  tate of either t
183c0 68 65 0a 2a 2a 20 43 2d 41 50 49 20 6f 72 20 74  he.** C-API or t
183d0 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 2e  he SQL function.
183e0 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 70  .** The second p
183f0 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 70 6f  arameter is a po
18400 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65  inter to an inte
18410 67 65 72 20 69 6e 74 6f 20 77 68 69 63 68 0a 2a  ger into which.*
18420 2a 20 69 73 20 77 72 69 74 74 65 6e 20 30 20 6f  * is written 0 o
18430 72 20 31 20 74 6f 20 69 6e 64 69 63 61 74 65 20  r 1 to indicate 
18440 77 68 65 74 68 65 72 20 5b 73 71 6c 69 74 65 33  whether [sqlite3
18450 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28  _load_extension(
18460 29 5d 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20  )] interface.** 
18470 69 73 20 64 69 73 61 62 6c 65 64 20 6f 72 20 65  is disabled or e
18480 6e 61 62 6c 65 64 20 66 6f 6c 6c 6f 77 69 6e 67  nabled following
18490 20 74 68 69 73 20 63 61 6c 6c 2e 20 20 54 68 65   this call.  The
184a0 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
184b0 72 20 6d 61 79 0a 2a 2a 20 62 65 20 61 20 4e 55  r may.** be a NU
184c0 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69 6e 20 77  LL pointer, in w
184d0 68 69 63 68 20 63 61 73 65 20 74 68 65 20 6e 65  hich case the ne
184e0 77 20 73 65 74 74 69 6e 67 20 69 73 20 6e 6f 74  w setting is not
184f0 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b 2e 0a   reported back..
18500 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c  ** </dd>.**.** <
18510 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46  dt>SQLITE_DBCONF
18520 49 47 5f 4d 41 49 4e 44 42 4e 41 4d 45 3c 2f 64  IG_MAINDBNAME</d
18530 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73  t>.** <dd> ^This
18540 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64 20   option is used 
18550 74 6f 20 63 68 61 6e 67 65 20 74 68 65 20 6e 61  to change the na
18560 6d 65 20 6f 66 20 74 68 65 20 22 6d 61 69 6e 22  me of the "main"
18570 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 73 63 68   database.** sch
18580 65 6d 61 2e 20 20 5e 54 68 65 20 73 6f 6c 65 20  ema.  ^The sole 
18590 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f  argument is a po
185a0 69 6e 74 65 72 20 74 6f 20 61 20 63 6f 6e 73 74  inter to a const
185b0 61 6e 74 20 55 54 46 38 20 73 74 72 69 6e 67 0a  ant UTF8 string.
185c0 2a 2a 20 77 68 69 63 68 20 77 69 6c 6c 20 62 65  ** which will be
185d0 63 6f 6d 65 20 74 68 65 20 6e 65 77 20 73 63 68  come the new sch
185e0 65 6d 61 20 6e 61 6d 65 20 69 6e 20 70 6c 61 63  ema name in plac
185f0 65 20 6f 66 20 22 6d 61 69 6e 22 2e 20 20 5e 53  e of "main".  ^S
18600 51 4c 69 74 65 0a 2a 2a 20 64 6f 65 73 20 6e 6f  QLite.** does no
18610 74 20 6d 61 6b 65 20 61 20 63 6f 70 79 20 6f 66  t make a copy of
18620 20 74 68 65 20 6e 65 77 20 6d 61 69 6e 20 73 63   the new main sc
18630 68 65 6d 61 20 6e 61 6d 65 20 73 74 72 69 6e 67  hema name string
18640 2c 20 73 6f 20 74 68 65 20 61 70 70 6c 69 63 61  , so the applica
18650 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 65 6e 73  tion.** must ens
18660 75 72 65 20 74 68 61 74 20 74 68 65 20 61 72 67  ure that the arg
18670 75 6d 65 6e 74 20 70 61 73 73 65 64 20 69 6e 74  ument passed int
18680 6f 20 74 68 69 73 20 44 42 43 4f 4e 46 49 47 20  o this DBCONFIG 
18690 6f 70 74 69 6f 6e 20 69 73 20 75 6e 63 68 61 6e  option is unchan
186a0 67 65 64 0a 2a 2a 20 75 6e 74 69 6c 20 61 66 74  ged.** until aft
186b0 65 72 20 74 68 65 20 64 61 74 61 62 61 73 65 20  er the database 
186c0 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f 73 65  connection close
186d0 73 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a  s..** </dd>.**.*
186e0 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43  * <dt>SQLITE_DBC
186f0 4f 4e 46 49 47 5f 4e 4f 5f 43 4b 50 54 5f 4f 4e  ONFIG_NO_CKPT_ON
18700 5f 43 4c 4f 53 45 3c 2f 64 74 3e 0a 2a 2a 20 3c  _CLOSE</dt>.** <
18710 64 64 3e 20 55 73 75 61 6c 6c 79 2c 20 77 68 65  dd> Usually, whe
18720 6e 20 61 20 64 61 74 61 62 61 73 65 20 69 6e 20  n a database in 
18730 77 61 6c 20 6d 6f 64 65 20 69 73 20 63 6c 6f 73  wal mode is clos
18740 65 64 20 6f 72 20 64 65 74 61 63 68 65 64 20 66  ed or detached f
18750 72 6f 6d 20 61 20 0a 2a 2a 20 64 61 74 61 62 61  rom a .** databa
18760 73 65 20 68 61 6e 64 6c 65 2c 20 53 51 4c 69 74  se handle, SQLit
18770 65 20 63 68 65 63 6b 73 20 69 66 20 74 68 69 73  e checks if this
18780 20 77 69 6c 6c 20 6d 65 61 6e 20 74 68 61 74 20   will mean that 
18790 74 68 65 72 65 20 61 72 65 20 6e 6f 77 20 6e 6f  there are now no
187a0 20 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 73   .** connections
187b0 20 61 74 20 61 6c 6c 20 74 6f 20 74 68 65 20 64   at all to the d
187c0 61 74 61 62 61 73 65 2e 20 49 66 20 73 6f 2c 20  atabase. If so, 
187d0 69 74 20 70 65 72 66 6f 72 6d 73 20 61 20 63 68  it performs a ch
187e0 65 63 6b 70 6f 69 6e 74 20 0a 2a 2a 20 6f 70 65  eckpoint .** ope
187f0 72 61 74 69 6f 6e 20 62 65 66 6f 72 65 20 63 6c  ration before cl
18800 6f 73 69 6e 67 20 74 68 65 20 63 6f 6e 6e 65 63  osing the connec
18810 74 69 6f 6e 2e 20 54 68 69 73 20 6f 70 74 69 6f  tion. This optio
18820 6e 20 6d 61 79 20 62 65 20 75 73 65 64 20 74 6f  n may be used to
18830 0a 2a 2a 20 6f 76 65 72 72 69 64 65 20 74 68 69  .** override thi
18840 73 20 62 65 68 61 76 69 6f 75 72 2e 20 54 68 65  s behaviour. The
18850 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
18860 20 70 61 73 73 65 64 20 74 6f 20 74 68 69 73 20   passed to this 
18870 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 69 73 20  operation.** is 
18880 61 6e 20 69 6e 74 65 67 65 72 20 2d 20 6e 6f 6e  an integer - non
18890 2d 7a 65 72 6f 20 74 6f 20 64 69 73 61 62 6c 65  -zero to disable
188a0 20 63 68 65 63 6b 70 6f 69 6e 74 73 2d 6f 6e 2d   checkpoints-on-
188b0 63 6c 6f 73 65 2c 20 6f 72 20 7a 65 72 6f 20 28  close, or zero (
188c0 74 68 65 0a 2a 2a 20 64 65 66 61 75 6c 74 29 20  the.** default) 
188d0 74 6f 20 65 6e 61 62 6c 65 20 74 68 65 6d 2e 20  to enable them. 
188e0 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  The second param
188f0 65 74 65 72 20 69 73 20 61 20 70 6f 69 6e 74 65  eter is a pointe
18900 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 0a  r to an integer.
18910 2a 2a 20 69 6e 74 6f 20 77 68 69 63 68 20 69 73  ** into which is
18920 20 77 72 69 74 74 65 6e 20 30 20 6f 72 20 31 20   written 0 or 1 
18930 74 6f 20 69 6e 64 69 63 61 74 65 20 77 68 65 74  to indicate whet
18940 68 65 72 20 63 68 65 63 6b 70 6f 69 6e 74 73 2d  her checkpoints-
18950 6f 6e 2d 63 6c 6f 73 65 0a 2a 2a 20 68 61 76 65  on-close.** have
18960 20 62 65 65 6e 20 64 69 73 61 62 6c 65 64 20 2d   been disabled -
18970 20 30 20 69 66 20 74 68 65 79 20 61 72 65 20 6e   0 if they are n
18980 6f 74 20 64 69 73 61 62 6c 65 64 2c 20 31 20 69  ot disabled, 1 i
18990 66 20 74 68 65 79 20 61 72 65 2e 0a 2a 2a 20 3c  f they are..** <
189a0 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 2f 64 6c 3e  /dd>.**.** </dl>
189b0 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
189c0 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4d 41 49 4e  TE_DBCONFIG_MAIN
189d0 44 42 4e 41 4d 45 20 20 20 20 20 20 20 20 20 20  DBNAME          
189e0 20 20 31 30 30 30 20 2f 2a 20 63 6f 6e 73 74 20    1000 /* const 
189f0 63 68 61 72 2a 20 2a 2f 0a 23 64 65 66 69 6e 65  char* */.#define
18a00 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47   SQLITE_DBCONFIG
18a10 5f 4c 4f 4f 4b 41 53 49 44 45 20 20 20 20 20 20  _LOOKASIDE      
18a20 20 20 20 20 20 20 20 31 30 30 31 20 2f 2a 20 76         1001 /* v
18a30 6f 69 64 2a 20 69 6e 74 20 69 6e 74 20 2a 2f 0a  oid* int int */.
18a40 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
18a50 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 46  BCONFIG_ENABLE_F
18a60 4b 45 59 20 20 20 20 20 20 20 20 20 20 20 31 30  KEY           10
18a70 30 32 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a  02 /* int int* *
18a80 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
18a90 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45  _DBCONFIG_ENABLE
18aa0 5f 54 52 49 47 47 45 52 20 20 20 20 20 20 20 20  _TRIGGER        
18ab0 31 30 30 33 20 2f 2a 20 69 6e 74 20 69 6e 74 2a  1003 /* int int*
18ac0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
18ad0 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42  TE_DBCONFIG_ENAB
18ae0 4c 45 5f 46 54 53 33 5f 54 4f 4b 45 4e 49 5a 45  LE_FTS3_TOKENIZE
18af0 52 20 31 30 30 34 20 2f 2a 20 69 6e 74 20 69 6e  R 1004 /* int in
18b00 74 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  t* */.#define SQ
18b10 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e  LITE_DBCONFIG_EN
18b20 41 42 4c 45 5f 4c 4f 41 44 5f 45 58 54 45 4e 53  ABLE_LOAD_EXTENS
18b30 49 4f 4e 20 31 30 30 35 20 2f 2a 20 69 6e 74 20  ION 1005 /* int 
18b40 69 6e 74 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20  int* */.#define 
18b50 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
18b60 4e 4f 5f 43 4b 50 54 5f 4f 4e 5f 43 4c 4f 53 45  NO_CKPT_ON_CLOSE
18b70 20 20 20 20 20 20 31 30 30 36 20 2f 2a 20 69 6e        1006 /* in
18b80 74 20 69 6e 74 2a 20 2a 2f 0a 0a 0a 2f 2a 0a 2a  t int* */.../*.*
18b90 2a 20 43 41 50 49 33 52 45 46 3a 20 45 6e 61 62  * CAPI3REF: Enab
18ba0 6c 65 20 4f 72 20 44 69 73 61 62 6c 65 20 45 78  le Or Disable Ex
18bb0 74 65 6e 64 65 64 20 52 65 73 75 6c 74 20 43 6f  tended Result Co
18bc0 64 65 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  des.** METHOD: s
18bd0 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68  qlite3.**.** ^Th
18be0 65 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64  e sqlite3_extend
18bf0 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28  ed_result_codes(
18c00 29 20 72 6f 75 74 69 6e 65 20 65 6e 61 62 6c 65  ) routine enable
18c10 73 20 6f 72 20 64 69 73 61 62 6c 65 73 20 74 68  s or disables th
18c20 65 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72  e.** [extended r
18c30 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 66 65 61  esult codes] fea
18c40 74 75 72 65 20 6f 66 20 53 51 4c 69 74 65 2e 20  ture of SQLite. 
18c50 5e 54 68 65 20 65 78 74 65 6e 64 65 64 20 72 65  ^The extended re
18c60 73 75 6c 74 0a 2a 2a 20 63 6f 64 65 73 20 61 72  sult.** codes ar
18c70 65 20 64 69 73 61 62 6c 65 64 20 62 79 20 64 65  e disabled by de
18c80 66 61 75 6c 74 20 66 6f 72 20 68 69 73 74 6f 72  fault for histor
18c90 69 63 61 6c 20 63 6f 6d 70 61 74 69 62 69 6c 69  ical compatibili
18ca0 74 79 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  ty..*/.int sqlit
18cb0 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75  e3_extended_resu
18cc0 6c 74 5f 63 6f 64 65 73 28 73 71 6c 69 74 65 33  lt_codes(sqlite3
18cd0 2a 2c 20 69 6e 74 20 6f 6e 6f 66 66 29 3b 0a 0a  *, int onoff);..
18ce0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
18cf0 4c 61 73 74 20 49 6e 73 65 72 74 20 52 6f 77 69  Last Insert Rowi
18d00 64 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  d.** METHOD: sql
18d10 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 45 61 63 68  ite3.**.** ^Each
18d20 20 65 6e 74 72 79 20 69 6e 20 6d 6f 73 74 20 53   entry in most S
18d30 51 4c 69 74 65 20 74 61 62 6c 65 73 20 28 65 78  QLite tables (ex
18d40 63 65 70 74 20 66 6f 72 20 5b 57 49 54 48 4f 55  cept for [WITHOU
18d50 54 20 52 4f 57 49 44 5d 20 74 61 62 6c 65 73 29  T ROWID] tables)
18d60 0a 2a 2a 20 68 61 73 20 61 20 75 6e 69 71 75 65  .** has a unique
18d70 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 0a 2a   64-bit signed.*
18d80 2a 20 69 6e 74 65 67 65 72 20 6b 65 79 20 63 61  * integer key ca
18d90 6c 6c 65 64 20 74 68 65 20 5b 52 4f 57 49 44 20  lled the [ROWID 
18da0 7c 20 22 72 6f 77 69 64 22 5d 2e 20 5e 54 68 65  | "rowid"]. ^The
18db0 20 72 6f 77 69 64 20 69 73 20 61 6c 77 61 79 73   rowid is always
18dc0 20 61 76 61 69 6c 61 62 6c 65 0a 2a 2a 20 61 73   available.** as
18dd0 20 61 6e 20 75 6e 64 65 63 6c 61 72 65 64 20 63   an undeclared c
18de0 6f 6c 75 6d 6e 20 6e 61 6d 65 64 20 52 4f 57 49  olumn named ROWI
18df0 44 2c 20 4f 49 44 2c 20 6f 72 20 5f 52 4f 57 49  D, OID, or _ROWI
18e00 44 5f 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68  D_ as long as th
18e10 6f 73 65 0a 2a 2a 20 6e 61 6d 65 73 20 61 72 65  ose.** names are
18e20 20 6e 6f 74 20 61 6c 73 6f 20 75 73 65 64 20 62   not also used b
18e30 79 20 65 78 70 6c 69 63 69 74 6c 79 20 64 65 63  y explicitly dec
18e40 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 73 2e 20 5e  lared columns. ^
18e50 49 66 0a 2a 2a 20 74 68 65 20 74 61 62 6c 65 20  If.** the table 
18e60 68 61 73 20 61 20 63 6f 6c 75 6d 6e 20 6f 66 20  has a column of 
18e70 74 79 70 65 20 5b 49 4e 54 45 47 45 52 20 50 52  type [INTEGER PR
18e80 49 4d 41 52 59 20 4b 45 59 5d 20 74 68 65 6e 20  IMARY KEY] then 
18e90 74 68 61 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69  that column.** i
18ea0 73 20 61 6e 6f 74 68 65 72 20 61 6c 69 61 73 20  s another alias 
18eb0 66 6f 72 20 74 68 65 20 72 6f 77 69 64 2e 0a 2a  for the rowid..*
18ec0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
18ed0 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f  3_last_insert_ro
18ee0 77 69 64 28 44 29 20 69 6e 74 65 72 66 61 63 65  wid(D) interface
18ef0 20 72 65 74 75 72 6e 73 20 74 68 65 20 5b 72 6f   returns the [ro
18f00 77 69 64 5d 20 6f 66 20 74 68 65 20 0a 2a 2a 20  wid] of the .** 
18f10 6d 6f 73 74 20 72 65 63 65 6e 74 20 73 75 63 63  most recent succ
18f20 65 73 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d 20  essful [INSERT] 
18f30 69 6e 74 6f 20 61 20 72 6f 77 69 64 20 74 61 62  into a rowid tab
18f40 6c 65 20 6f 72 20 5b 76 69 72 74 75 61 6c 20 74  le or [virtual t
18f50 61 62 6c 65 5d 0a 2a 2a 20 6f 6e 20 64 61 74 61  able].** on data
18f60 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
18f70 44 2e 0a 2a 2a 20 5e 49 6e 73 65 72 74 73 20 69  D..** ^Inserts i
18f80 6e 74 6f 20 5b 57 49 54 48 4f 55 54 20 52 4f 57  nto [WITHOUT ROW
18f90 49 44 5d 20 74 61 62 6c 65 73 20 61 72 65 20 6e  ID] tables are n
18fa0 6f 74 20 72 65 63 6f 72 64 65 64 2e 0a 2a 2a 20  ot recorded..** 
18fb0 5e 49 66 20 6e 6f 20 73 75 63 63 65 73 73 66 75  ^If no successfu
18fc0 6c 20 5b 49 4e 53 45 52 54 5d 73 20 69 6e 74 6f  l [INSERT]s into
18fd0 20 72 6f 77 69 64 20 74 61 62 6c 65 73 0a 2a 2a   rowid tables.**
18fe0 20 68 61 76 65 20 65 76 65 72 20 6f 63 63 75 72   have ever occur
18ff0 72 65 64 20 6f 6e 20 74 68 65 20 64 61 74 61 62  red on the datab
19000 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44  ase connection D
19010 2c 20 0a 2a 2a 20 74 68 65 6e 20 73 71 6c 69 74  , .** then sqlit
19020 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72  e3_last_insert_r
19030 6f 77 69 64 28 44 29 20 72 65 74 75 72 6e 73 20  owid(D) returns 
19040 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66  zero..**.** ^(If
19050 20 61 6e 20 5b 49 4e 53 45 52 54 5d 20 6f 63 63   an [INSERT] occ
19060 75 72 73 20 77 69 74 68 69 6e 20 61 20 74 72 69  urs within a tri
19070 67 67 65 72 20 6f 72 20 77 69 74 68 69 6e 20 61  gger or within a
19080 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 5d   [virtual table]
19090 0a 2a 2a 20 6d 65 74 68 6f 64 2c 20 74 68 65 6e  .** method, then
190a0 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69   this routine wi
190b0 6c 6c 20 72 65 74 75 72 6e 20 74 68 65 20 5b 72  ll return the [r
190c0 6f 77 69 64 5d 20 6f 66 20 74 68 65 20 69 6e 73  owid] of the ins
190d0 65 72 74 65 64 0a 2a 2a 20 72 6f 77 20 61 73 20  erted.** row as 
190e0 6c 6f 6e 67 20 61 73 20 74 68 65 20 74 72 69 67  long as the trig
190f0 67 65 72 20 6f 72 20 76 69 72 74 75 61 6c 20 74  ger or virtual t
19100 61 62 6c 65 20 6d 65 74 68 6f 64 20 69 73 20 72  able method is r
19110 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 42 75 74 20 6f  unning..** But o
19120 6e 63 65 20 74 68 65 20 74 72 69 67 67 65 72 20  nce the trigger 
19130 6f 72 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65  or virtual table
19140 20 6d 65 74 68 6f 64 20 65 6e 64 73 2c 20 74 68   method ends, th
19150 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  e value returned
19160 20 0a 2a 2a 20 62 79 20 74 68 69 73 20 72 6f 75   .** by this rou
19170 74 69 6e 65 20 72 65 76 65 72 74 73 20 74 6f 20  tine reverts to 
19180 77 68 61 74 20 69 74 20 77 61 73 20 62 65 66 6f  what it was befo
19190 72 65 20 74 68 65 20 74 72 69 67 67 65 72 20 6f  re the trigger o
191a0 72 20 76 69 72 74 75 61 6c 0a 2a 2a 20 74 61 62  r virtual.** tab
191b0 6c 65 20 6d 65 74 68 6f 64 20 62 65 67 61 6e 2e  le method began.
191c0 29 5e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 5b 49 4e  )^.**.** ^An [IN
191d0 53 45 52 54 5d 20 74 68 61 74 20 66 61 69 6c 73  SERT] that fails
191e0 20 64 75 65 20 74 6f 20 61 20 63 6f 6e 73 74 72   due to a constr
191f0 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 20 69  aint violation i
19200 73 20 6e 6f 74 20 61 0a 2a 2a 20 73 75 63 63 65  s not a.** succe
19210 73 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d 20 61  ssful [INSERT] a
19220 6e 64 20 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e  nd does not chan
19230 67 65 20 74 68 65 20 76 61 6c 75 65 20 72 65 74  ge the value ret
19240 75 72 6e 65 64 20 62 79 20 74 68 69 73 0a 2a 2a  urned by this.**
19250 20 72 6f 75 74 69 6e 65 2e 20 20 5e 54 68 75 73   routine.  ^Thus
19260 20 49 4e 53 45 52 54 20 4f 52 20 46 41 49 4c 2c   INSERT OR FAIL,
19270 20 49 4e 53 45 52 54 20 4f 52 20 49 47 4e 4f 52   INSERT OR IGNOR
19280 45 2c 20 49 4e 53 45 52 54 20 4f 52 20 52 4f 4c  E, INSERT OR ROL
19290 4c 42 41 43 4b 2c 0a 2a 2a 20 61 6e 64 20 49 4e  LBACK,.** and IN
192a0 53 45 52 54 20 4f 52 20 41 42 4f 52 54 20 6d 61  SERT OR ABORT ma
192b0 6b 65 20 6e 6f 20 63 68 61 6e 67 65 73 20 74 6f  ke no changes to
192c0 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   the return valu
192d0 65 20 6f 66 20 74 68 69 73 0a 2a 2a 20 72 6f 75  e of this.** rou
192e0 74 69 6e 65 20 77 68 65 6e 20 74 68 65 69 72 20  tine when their 
192f0 69 6e 73 65 72 74 69 6f 6e 20 66 61 69 6c 73 2e  insertion fails.
19300 20 20 5e 28 57 68 65 6e 20 49 4e 53 45 52 54 20    ^(When INSERT 
19310 4f 52 20 52 45 50 4c 41 43 45 0a 2a 2a 20 65 6e  OR REPLACE.** en
19320 63 6f 75 6e 74 65 72 73 20 61 20 63 6f 6e 73 74  counters a const
19330 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 2c  raint violation,
19340 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 66 61 69   it does not fai
19350 6c 2e 20 20 54 68 65 0a 2a 2a 20 49 4e 53 45 52  l.  The.** INSER
19360 54 20 63 6f 6e 74 69 6e 75 65 73 20 74 6f 20 63  T continues to c
19370 6f 6d 70 6c 65 74 69 6f 6e 20 61 66 74 65 72 20  ompletion after 
19380 64 65 6c 65 74 69 6e 67 20 72 6f 77 73 20 74 68  deleting rows th
19390 61 74 20 63 61 75 73 65 64 0a 2a 2a 20 74 68 65  at caused.** the
193a0 20 63 6f 6e 73 74 72 61 69 6e 74 20 70 72 6f 62   constraint prob
193b0 6c 65 6d 20 73 6f 20 49 4e 53 45 52 54 20 4f 52  lem so INSERT OR
193c0 20 52 45 50 4c 41 43 45 20 77 69 6c 6c 20 61 6c   REPLACE will al
193d0 77 61 79 73 20 63 68 61 6e 67 65 0a 2a 2a 20 74  ways change.** t
193e0 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20  he return value 
193f0 6f 66 20 74 68 69 73 20 69 6e 74 65 72 66 61 63  of this interfac
19400 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 46 6f 72 20  e.)^.**.** ^For 
19410 74 68 65 20 70 75 72 70 6f 73 65 73 20 6f 66 20  the purposes of 
19420 74 68 69 73 20 72 6f 75 74 69 6e 65 2c 20 61 6e  this routine, an
19430 20 5b 49 4e 53 45 52 54 5d 20 69 73 20 63 6f 6e   [INSERT] is con
19440 73 69 64 65 72 65 64 20 74 6f 0a 2a 2a 20 62 65  sidered to.** be
19450 20 73 75 63 63 65 73 73 66 75 6c 20 65 76 65 6e   successful even
19460 20 69 66 20 69 74 20 69 73 20 73 75 62 73 65 71   if it is subseq
19470 75 65 6e 74 6c 79 20 72 6f 6c 6c 65 64 20 62 61  uently rolled ba
19480 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66  ck..**.** This f
19490 75 6e 63 74 69 6f 6e 20 69 73 20 61 63 63 65 73  unction is acces
194a0 73 69 62 6c 65 20 74 6f 20 53 51 4c 20 73 74 61  sible to SQL sta
194b0 74 65 6d 65 6e 74 73 20 76 69 61 20 74 68 65 0a  tements via the.
194c0 2a 2a 20 5b 6c 61 73 74 5f 69 6e 73 65 72 74 5f  ** [last_insert_
194d0 72 6f 77 69 64 28 29 20 53 51 4c 20 66 75 6e 63  rowid() SQL func
194e0 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  tion]..**.** If 
194f0 61 20 73 65 70 61 72 61 74 65 20 74 68 72 65 61  a separate threa
19500 64 20 70 65 72 66 6f 72 6d 73 20 61 20 6e 65 77  d performs a new
19510 20 5b 49 4e 53 45 52 54 5d 20 6f 6e 20 74 68 65   [INSERT] on the
19520 20 73 61 6d 65 0a 2a 2a 20 64 61 74 61 62 61 73   same.** databas
19530 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 77 68 69  e connection whi
19540 6c 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  le the [sqlite3_
19550 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69  last_insert_rowi
19560 64 28 29 5d 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  d()].** function
19570 20 69 73 20 72 75 6e 6e 69 6e 67 20 61 6e 64 20   is running and 
19580 74 68 75 73 20 63 68 61 6e 67 65 73 20 74 68 65  thus changes the
19590 20 6c 61 73 74 20 69 6e 73 65 72 74 20 5b 72 6f   last insert [ro
195a0 77 69 64 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74 68  wid],.** then th
195b0 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  e value returned
195c0 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73   by [sqlite3_las
195d0 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29  t_insert_rowid()
195e0 5d 20 69 73 0a 2a 2a 20 75 6e 70 72 65 64 69 63  ] is.** unpredic
195f0 74 61 62 6c 65 20 61 6e 64 20 6d 69 67 68 74 20  table and might 
19600 6e 6f 74 20 65 71 75 61 6c 20 65 69 74 68 65 72  not equal either
19610 20 74 68 65 20 6f 6c 64 20 6f 72 20 74 68 65 20   the old or the 
19620 6e 65 77 0a 2a 2a 20 6c 61 73 74 20 69 6e 73 65  new.** last inse
19630 72 74 20 5b 72 6f 77 69 64 5d 2e 0a 2a 2f 0a 73  rt [rowid]..*/.s
19640 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c  qlite3_int64 sql
19650 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74  ite3_last_insert
19660 5f 72 6f 77 69 64 28 73 71 6c 69 74 65 33 2a 29  _rowid(sqlite3*)
19670 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
19680 46 3a 20 43 6f 75 6e 74 20 54 68 65 20 4e 75 6d  F: Count The Num
19690 62 65 72 20 4f 66 20 52 6f 77 73 20 4d 6f 64 69  ber Of Rows Modi
196a0 66 69 65 64 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  fied.** METHOD: 
196b0 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54  sqlite3.**.** ^T
196c0 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74  his function ret
196d0 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20  urns the number 
196e0 6f 66 20 72 6f 77 73 20 6d 6f 64 69 66 69 65 64  of rows modified
196f0 2c 20 69 6e 73 65 72 74 65 64 20 6f 72 0a 2a 2a  , inserted or.**
19700 20 64 65 6c 65 74 65 64 20 62 79 20 74 68 65 20   deleted by the 
19710 6d 6f 73 74 20 72 65 63 65 6e 74 6c 79 20 63 6f  most recently co
19720 6d 70 6c 65 74 65 64 20 49 4e 53 45 52 54 2c 20  mpleted INSERT, 
19730 55 50 44 41 54 45 20 6f 72 20 44 45 4c 45 54 45  UPDATE or DELETE
19740 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 6f 6e  .** statement on
19750 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
19760 6e 6e 65 63 74 69 6f 6e 20 73 70 65 63 69 66 69  nnection specifi
19770 65 64 20 62 79 20 74 68 65 20 6f 6e 6c 79 20 70  ed by the only p
19780 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e 45 78  arameter..** ^Ex
19790 65 63 75 74 69 6e 67 20 61 6e 79 20 6f 74 68 65  ecuting any othe
197a0 72 20 74 79 70 65 20 6f 66 20 53 51 4c 20 73 74  r type of SQL st
197b0 61 74 65 6d 65 6e 74 20 64 6f 65 73 20 6e 6f 74  atement does not
197c0 20 6d 6f 64 69 66 79 20 74 68 65 20 76 61 6c 75   modify the valu
197d0 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 79  e.** returned by
197e0 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 2e 0a   this function..
197f0 2a 2a 0a 2a 2a 20 5e 4f 6e 6c 79 20 63 68 61 6e  **.** ^Only chan
19800 67 65 73 20 6d 61 64 65 20 64 69 72 65 63 74 6c  ges made directl
19810 79 20 62 79 20 74 68 65 20 49 4e 53 45 52 54 2c  y by the INSERT,
19820 20 55 50 44 41 54 45 20 6f 72 20 44 45 4c 45 54   UPDATE or DELET
19830 45 20 73 74 61 74 65 6d 65 6e 74 20 61 72 65 0a  E statement are.
19840 2a 2a 20 63 6f 6e 73 69 64 65 72 65 64 20 2d 20  ** considered - 
19850 61 75 78 69 6c 69 61 72 79 20 63 68 61 6e 67 65  auxiliary change
19860 73 20 63 61 75 73 65 64 20 62 79 20 5b 43 52 45  s caused by [CRE
19870 41 54 45 20 54 52 49 47 47 45 52 20 7c 20 74 72  ATE TRIGGER | tr
19880 69 67 67 65 72 73 5d 2c 20 0a 2a 2a 20 5b 66 6f  iggers], .** [fo
19890 72 65 69 67 6e 20 6b 65 79 20 61 63 74 69 6f 6e  reign key action
198a0 73 5d 20 6f 72 20 5b 52 45 50 4c 41 43 45 5d 20  s] or [REPLACE] 
198b0 63 6f 6e 73 74 72 61 69 6e 74 20 72 65 73 6f 6c  constraint resol
198c0 75 74 69 6f 6e 20 61 72 65 20 6e 6f 74 20 63 6f  ution are not co
198d0 75 6e 74 65 64 2e 0a 2a 2a 20 0a 2a 2a 20 43 68  unted..** .** Ch
198e0 61 6e 67 65 73 20 74 6f 20 61 20 76 69 65 77 20  anges to a view 
198f0 74 68 61 74 20 61 72 65 20 69 6e 74 65 72 63 65  that are interce
19900 70 74 65 64 20 62 79 20 0a 2a 2a 20 5b 49 4e 53  pted by .** [INS
19910 54 45 41 44 20 4f 46 20 74 72 69 67 67 65 72 20  TEAD OF trigger 
19920 7c 20 49 4e 53 54 45 41 44 20 4f 46 20 74 72 69  | INSTEAD OF tri
19930 67 67 65 72 73 5d 20 61 72 65 20 6e 6f 74 20 63  ggers] are not c
19940 6f 75 6e 74 65 64 2e 20 5e 54 68 65 20 76 61 6c  ounted. ^The val
19950 75 65 20 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20  ue .** returned 
19960 62 79 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67  by sqlite3_chang
19970 65 73 28 29 20 69 6d 6d 65 64 69 61 74 65 6c 79  es() immediately
19980 20 61 66 74 65 72 20 61 6e 20 49 4e 53 45 52 54   after an INSERT
19990 2c 20 55 50 44 41 54 45 20 6f 72 20 0a 2a 2a 20  , UPDATE or .** 
199a0 44 45 4c 45 54 45 20 73 74 61 74 65 6d 65 6e 74  DELETE statement
199b0 20 72 75 6e 20 6f 6e 20 61 20 76 69 65 77 20 69   run on a view i
199c0 73 20 61 6c 77 61 79 73 20 7a 65 72 6f 2e 20 4f  s always zero. O
199d0 6e 6c 79 20 63 68 61 6e 67 65 73 20 6d 61 64 65  nly changes made
199e0 20 74 6f 20 72 65 61 6c 20 0a 2a 2a 20 74 61 62   to real .** tab
199f0 6c 65 73 20 61 72 65 20 63 6f 75 6e 74 65 64 2e  les are counted.
19a00 0a 2a 2a 0a 2a 2a 20 54 68 69 6e 67 73 20 61 72  .**.** Things ar
19a10 65 20 6d 6f 72 65 20 63 6f 6d 70 6c 69 63 61 74  e more complicat
19a20 65 64 20 69 66 20 74 68 65 20 73 71 6c 69 74 65  ed if the sqlite
19a30 33 5f 63 68 61 6e 67 65 73 28 29 20 66 75 6e 63  3_changes() func
19a40 74 69 6f 6e 20 69 73 0a 2a 2a 20 65 78 65 63 75  tion is.** execu
19a50 74 65 64 20 77 68 69 6c 65 20 61 20 74 72 69 67  ted while a trig
19a60 67 65 72 20 70 72 6f 67 72 61 6d 20 69 73 20 72  ger program is r
19a70 75 6e 6e 69 6e 67 2e 20 54 68 69 73 20 6d 61 79  unning. This may
19a80 20 68 61 70 70 65 6e 20 69 66 20 74 68 65 0a 2a   happen if the.*
19a90 2a 20 70 72 6f 67 72 61 6d 20 75 73 65 73 20 74  * program uses t
19aa0 68 65 20 5b 63 68 61 6e 67 65 73 28 29 20 53 51  he [changes() SQ
19ab0 4c 20 66 75 6e 63 74 69 6f 6e 5d 2c 20 6f 72 20  L function], or 
19ac0 69 66 20 73 6f 6d 65 20 6f 74 68 65 72 20 63 61  if some other ca
19ad0 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 69  llback.** functi
19ae0 6f 6e 20 69 6e 76 6f 6b 65 73 20 73 71 6c 69 74  on invokes sqlit
19af0 65 33 5f 63 68 61 6e 67 65 73 28 29 20 64 69 72  e3_changes() dir
19b00 65 63 74 6c 79 2e 20 45 73 73 65 6e 74 69 61 6c  ectly. Essential
19b10 6c 79 3a 0a 2a 2a 20 0a 2a 2a 20 3c 75 6c 3e 0a  ly:.** .** <ul>.
19b20 2a 2a 20 20 20 3c 6c 69 3e 20 5e 28 42 65 66 6f  **   <li> ^(Befo
19b30 72 65 20 65 6e 74 65 72 69 6e 67 20 61 20 74 72  re entering a tr
19b40 69 67 67 65 72 20 70 72 6f 67 72 61 6d 20 74 68  igger program th
19b50 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  e value returned
19b60 20 62 79 0a 2a 2a 20 20 20 20 20 20 20 20 73 71   by.**        sq
19b70 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20  lite3_changes() 
19b80 66 75 6e 63 74 69 6f 6e 20 69 73 20 73 61 76 65  function is save
19b90 64 2e 20 41 66 74 65 72 20 74 68 65 20 74 72 69  d. After the tri
19ba0 67 67 65 72 20 70 72 6f 67 72 61 6d 20 0a 2a 2a  gger program .**
19bb0 20 20 20 20 20 20 20 20 68 61 73 20 66 69 6e 69          has fini
19bc0 73 68 65 64 2c 20 74 68 65 20 6f 72 69 67 69 6e  shed, the origin
19bd0 61 6c 20 76 61 6c 75 65 20 69 73 20 72 65 73 74  al value is rest
19be0 6f 72 65 64 2e 29 5e 0a 2a 2a 20 0a 2a 2a 20 20  ored.)^.** .**  
19bf0 20 3c 6c 69 3e 20 5e 28 57 69 74 68 69 6e 20 61   <li> ^(Within a
19c00 20 74 72 69 67 67 65 72 20 70 72 6f 67 72 61 6d   trigger program
19c10 20 65 61 63 68 20 49 4e 53 45 52 54 2c 20 55 50   each INSERT, UP
19c20 44 41 54 45 20 61 6e 64 20 44 45 4c 45 54 45 20  DATE and DELETE 
19c30 0a 2a 2a 20 20 20 20 20 20 20 20 73 74 61 74 65  .**        state
19c40 6d 65 6e 74 20 73 65 74 73 20 74 68 65 20 76 61  ment sets the va
19c50 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20  lue returned by 
19c60 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28  sqlite3_changes(
19c70 29 20 0a 2a 2a 20 20 20 20 20 20 20 20 75 70 6f  ) .**        upo
19c80 6e 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 61 73 20  n completion as 
19c90 6e 6f 72 6d 61 6c 2e 20 4f 66 20 63 6f 75 72 73  normal. Of cours
19ca0 65 2c 20 74 68 69 73 20 76 61 6c 75 65 20 77 69  e, this value wi
19cb0 6c 6c 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 0a  ll not include .
19cc0 2a 2a 20 20 20 20 20 20 20 20 61 6e 79 20 63 68  **        any ch
19cd0 61 6e 67 65 73 20 70 65 72 66 6f 72 6d 65 64 20  anges performed 
19ce0 62 79 20 73 75 62 2d 74 72 69 67 67 65 72 73 2c  by sub-triggers,
19cf0 20 61 73 20 74 68 65 20 73 71 6c 69 74 65 33 5f   as the sqlite3_
19d00 63 68 61 6e 67 65 73 28 29 20 0a 2a 2a 20 20 20  changes() .**   
19d10 20 20 20 20 20 76 61 6c 75 65 20 77 69 6c 6c 20       value will 
19d20 62 65 20 73 61 76 65 64 20 61 6e 64 20 72 65 73  be saved and res
19d30 74 6f 72 65 64 20 61 66 74 65 72 20 65 61 63 68  tored after each
19d40 20 73 75 62 2d 74 72 69 67 67 65 72 20 68 61 73   sub-trigger has
19d50 20 72 75 6e 2e 29 5e 0a 2a 2a 20 3c 2f 75 6c 3e   run.)^.** </ul>
19d60 0a 2a 2a 20 0a 2a 2a 20 5e 54 68 69 73 20 6d 65  .** .** ^This me
19d70 61 6e 73 20 74 68 61 74 20 69 66 20 74 68 65 20  ans that if the 
19d80 63 68 61 6e 67 65 73 28 29 20 53 51 4c 20 66 75  changes() SQL fu
19d90 6e 63 74 69 6f 6e 20 28 6f 72 20 73 69 6d 69 6c  nction (or simil
19da0 61 72 29 20 69 73 20 75 73 65 64 0a 2a 2a 20 62  ar) is used.** b
19db0 79 20 74 68 65 20 66 69 72 73 74 20 49 4e 53 45  y the first INSE
19dc0 52 54 2c 20 55 50 44 41 54 45 20 6f 72 20 44 45  RT, UPDATE or DE
19dd0 4c 45 54 45 20 73 74 61 74 65 6d 65 6e 74 20 77  LETE statement w
19de0 69 74 68 69 6e 20 61 20 74 72 69 67 67 65 72 2c  ithin a trigger,
19df0 20 69 74 20 0a 2a 2a 20 72 65 74 75 72 6e 73 20   it .** returns 
19e00 74 68 65 20 76 61 6c 75 65 20 61 73 20 73 65 74  the value as set
19e10 20 77 68 65 6e 20 74 68 65 20 63 61 6c 6c 69 6e   when the callin
19e20 67 20 73 74 61 74 65 6d 65 6e 74 20 62 65 67 61  g statement bega
19e30 6e 20 65 78 65 63 75 74 69 6e 67 2e 0a 2a 2a 20  n executing..** 
19e40 5e 49 66 20 69 74 20 69 73 20 75 73 65 64 20 62  ^If it is used b
19e50 79 20 74 68 65 20 73 65 63 6f 6e 64 20 6f 72 20  y the second or 
19e60 73 75 62 73 65 71 75 65 6e 74 20 73 75 63 68 20  subsequent such 
19e70 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68 69 6e  statement within
19e80 20 61 20 74 72 69 67 67 65 72 20 0a 2a 2a 20 70   a trigger .** p
19e90 72 6f 67 72 61 6d 2c 20 74 68 65 20 76 61 6c 75  rogram, the valu
19ea0 65 20 72 65 74 75 72 6e 65 64 20 72 65 66 6c 65  e returned refle
19eb0 63 74 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  cts the number o
19ec0 66 20 72 6f 77 73 20 6d 6f 64 69 66 69 65 64 20  f rows modified 
19ed0 62 79 20 74 68 65 20 0a 2a 2a 20 70 72 65 76 69  by the .** previ
19ee0 6f 75 73 20 49 4e 53 45 52 54 2c 20 55 50 44 41  ous INSERT, UPDA
19ef0 54 45 20 6f 72 20 44 45 4c 45 54 45 20 73 74 61  TE or DELETE sta
19f00 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 74 68  tement within th
19f10 65 20 73 61 6d 65 20 74 72 69 67 67 65 72 2e 0a  e same trigger..
19f20 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74  **.** See also t
19f30 68 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61  he [sqlite3_tota
19f40 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 6e 74  l_changes()] int
19f50 65 72 66 61 63 65 2c 20 74 68 65 0a 2a 2a 20 5b  erface, the.** [
19f60 63 6f 75 6e 74 5f 63 68 61 6e 67 65 73 20 70 72  count_changes pr
19f70 61 67 6d 61 5d 2c 20 61 6e 64 20 74 68 65 20 5b  agma], and the [
19f80 63 68 61 6e 67 65 73 28 29 20 53 51 4c 20 66 75  changes() SQL fu
19f90 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49  nction]..**.** I
19fa0 66 20 61 20 73 65 70 61 72 61 74 65 20 74 68 72  f a separate thr
19fb0 65 61 64 20 6d 61 6b 65 73 20 63 68 61 6e 67 65  ead makes change
19fc0 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 64 61  s on the same da
19fd0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
19fe0 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b 73 71 6c 69  n.** while [sqli
19ff0 74 65 33 5f 63 68 61 6e 67 65 73 28 29 5d 20 69  te3_changes()] i
1a000 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20 74  s running then t
1a010 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65  he value returne
1a020 64 0a 2a 2a 20 69 73 20 75 6e 70 72 65 64 69 63  d.** is unpredic
1a030 74 61 62 6c 65 20 61 6e 64 20 6e 6f 74 20 6d 65  table and not me
1a040 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 69 6e 74  aningful..*/.int
1a050 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73   sqlite3_changes
1a060 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a  (sqlite3*);../*.
1a070 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 6f 74  ** CAPI3REF: Tot
1a080 61 6c 20 4e 75 6d 62 65 72 20 4f 66 20 52 6f 77  al Number Of Row
1a090 73 20 4d 6f 64 69 66 69 65 64 0a 2a 2a 20 4d 45  s Modified.** ME
1a0a0 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a  THOD: sqlite3.**
1a0b0 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69  .** ^This functi
1a0c0 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 74  on returns the t
1a0d0 6f 74 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20 72  otal number of r
1a0e0 6f 77 73 20 69 6e 73 65 72 74 65 64 2c 20 6d 6f  ows inserted, mo
1a0f0 64 69 66 69 65 64 20 6f 72 0a 2a 2a 20 64 65 6c  dified or.** del
1a100 65 74 65 64 20 62 79 20 61 6c 6c 20 5b 49 4e 53  eted by all [INS
1a110 45 52 54 5d 2c 20 5b 55 50 44 41 54 45 5d 20 6f  ERT], [UPDATE] o
1a120 72 20 5b 44 45 4c 45 54 45 5d 20 73 74 61 74 65  r [DELETE] state
1a130 6d 65 6e 74 73 20 63 6f 6d 70 6c 65 74 65 64 0a  ments completed.
1a140 2a 2a 20 73 69 6e 63 65 20 74 68 65 20 64 61 74  ** since the dat
1a150 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1a160 20 77 61 73 20 6f 70 65 6e 65 64 2c 20 69 6e 63   was opened, inc
1a170 6c 75 64 69 6e 67 20 74 68 6f 73 65 20 65 78 65  luding those exe
1a180 63 75 74 65 64 20 61 73 0a 2a 2a 20 70 61 72 74  cuted as.** part
1a190 20 6f 66 20 74 72 69 67 67 65 72 20 70 72 6f 67   of trigger prog
1a1a0 72 61 6d 73 2e 20 5e 45 78 65 63 75 74 69 6e 67  rams. ^Executing
1a1b0 20 61 6e 79 20 6f 74 68 65 72 20 74 79 70 65 20   any other type 
1a1c0 6f 66 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  of SQL statement
1a1d0 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 61 66 66  .** does not aff
1a1e0 65 63 74 20 74 68 65 20 76 61 6c 75 65 20 72 65  ect the value re
1a1f0 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65  turned by sqlite
1a200 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28  3_total_changes(
1a210 29 2e 0a 2a 2a 20 0a 2a 2a 20 5e 43 68 61 6e 67  )..** .** ^Chang
1a220 65 73 20 6d 61 64 65 20 61 73 20 70 61 72 74 20  es made as part 
1a230 6f 66 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20  of [foreign key 
1a240 61 63 74 69 6f 6e 73 5d 20 61 72 65 20 69 6e 63  actions] are inc
1a250 6c 75 64 65 64 20 69 6e 20 74 68 65 0a 2a 2a 20  luded in the.** 
1a260 63 6f 75 6e 74 2c 20 62 75 74 20 74 68 6f 73 65  count, but those
1a270 20 6d 61 64 65 20 61 73 20 70 61 72 74 20 6f 66   made as part of
1a280 20 52 45 50 4c 41 43 45 20 63 6f 6e 73 74 72 61   REPLACE constra
1a290 69 6e 74 20 72 65 73 6f 6c 75 74 69 6f 6e 20 61  int resolution a
1a2a0 72 65 0a 2a 2a 20 6e 6f 74 2e 20 5e 43 68 61 6e  re.** not. ^Chan
1a2b0 67 65 73 20 74 6f 20 61 20 76 69 65 77 20 74 68  ges to a view th
1a2c0 61 74 20 61 72 65 20 69 6e 74 65 72 63 65 70 74  at are intercept
1a2d0 65 64 20 62 79 20 49 4e 53 54 45 41 44 20 4f 46  ed by INSTEAD OF
1a2e0 20 74 72 69 67 67 65 72 73 20 0a 2a 2a 20 61 72   triggers .** ar
1a2f0 65 20 6e 6f 74 20 63 6f 75 6e 74 65 64 2e 0a 2a  e not counted..*
1a300 2a 20 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74  * .** See also t
1a310 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e  he [sqlite3_chan
1a320 67 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63 65  ges()] interface
1a330 2c 20 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e 74 5f  , the.** [count_
1a340 63 68 61 6e 67 65 73 20 70 72 61 67 6d 61 5d 2c  changes pragma],
1a350 20 61 6e 64 20 74 68 65 20 5b 74 6f 74 61 6c 5f   and the [total_
1a360 63 68 61 6e 67 65 73 28 29 20 53 51 4c 20 66 75  changes() SQL fu
1a370 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49  nction]..**.** I
1a380 66 20 61 20 73 65 70 61 72 61 74 65 20 74 68 72  f a separate thr
1a390 65 61 64 20 6d 61 6b 65 73 20 63 68 61 6e 67 65  ead makes change
1a3a0 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 64 61  s on the same da
1a3b0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1a3c0 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b 73 71 6c 69  n.** while [sqli
1a3d0 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65  te3_total_change
1a3e0 73 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20  s()] is running 
1a3f0 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65 0a 2a  then the value.*
1a400 2a 20 72 65 74 75 72 6e 65 64 20 69 73 20 75 6e  * returned is un
1a410 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20  predictable and 
1a420 6e 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a  not meaningful..
1a430 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 74  */.int sqlite3_t
1a440 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 73 71 6c  otal_changes(sql
1a450 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ite3*);../*.** C
1a460 41 50 49 33 52 45 46 3a 20 49 6e 74 65 72 72 75  API3REF: Interru
1a470 70 74 20 41 20 4c 6f 6e 67 2d 52 75 6e 6e 69 6e  pt A Long-Runnin
1a480 67 20 51 75 65 72 79 0a 2a 2a 20 4d 45 54 48 4f  g Query.** METHO
1a490 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a  D: sqlite3.**.**
1a4a0 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20   ^This function 
1a4b0 63 61 75 73 65 73 20 61 6e 79 20 70 65 6e 64 69  causes any pendi
1a4c0 6e 67 20 64 61 74 61 62 61 73 65 20 6f 70 65 72  ng database oper
1a4d0 61 74 69 6f 6e 20 74 6f 20 61 62 6f 72 74 20 61  ation to abort a
1a4e0 6e 64 0a 2a 2a 20 72 65 74 75 72 6e 20 61 74 20  nd.** return at 
1a4f0 69 74 73 20 65 61 72 6c 69 65 73 74 20 6f 70 70  its earliest opp
1a500 6f 72 74 75 6e 69 74 79 2e 20 54 68 69 73 20 72  ortunity. This r
1a510 6f 75 74 69 6e 65 20 69 73 20 74 79 70 69 63 61  outine is typica
1a520 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64 20 69 6e  lly.** called in
1a530 20 72 65 73 70 6f 6e 73 65 20 74 6f 20 61 20 75   response to a u
1a540 73 65 72 20 61 63 74 69 6f 6e 20 73 75 63 68 20  ser action such 
1a550 61 73 20 70 72 65 73 73 69 6e 67 20 22 43 61 6e  as pressing "Can
1a560 63 65 6c 22 0a 2a 2a 20 6f 72 20 43 74 72 6c 2d  cel".** or Ctrl-
1a570 43 20 77 68 65 72 65 20 74 68 65 20 75 73 65 72  C where the user
1a580 20 77 61 6e 74 73 20 61 20 6c 6f 6e 67 20 71 75   wants a long qu
1a590 65 72 79 20 6f 70 65 72 61 74 69 6f 6e 20 74 6f  ery operation to
1a5a0 20 68 61 6c 74 0a 2a 2a 20 69 6d 6d 65 64 69 61   halt.** immedia
1a5b0 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74 20  tely..**.** ^It 
1a5c0 69 73 20 73 61 66 65 20 74 6f 20 63 61 6c 6c 20  is safe to call 
1a5d0 74 68 69 73 20 72 6f 75 74 69 6e 65 20 66 72 6f  this routine fro
1a5e0 6d 20 61 20 74 68 72 65 61 64 20 64 69 66 66 65  m a thread diffe
1a5f0 72 65 6e 74 20 66 72 6f 6d 20 74 68 65 0a 2a 2a  rent from the.**
1a600 20 74 68 72 65 61 64 20 74 68 61 74 20 69 73 20   thread that is 
1a610 63 75 72 72 65 6e 74 6c 79 20 72 75 6e 6e 69 6e  currently runnin
1a620 67 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6f  g the database o
1a630 70 65 72 61 74 69 6f 6e 2e 20 20 42 75 74 20 69  peration.  But i
1a640 74 0a 2a 2a 20 69 73 20 6e 6f 74 20 73 61 66 65  t.** is not safe
1a650 20 74 6f 20 63 61 6c 6c 20 74 68 69 73 20 72 6f   to call this ro
1a660 75 74 69 6e 65 20 77 69 74 68 20 61 20 5b 64 61  utine with a [da
1a670 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1a680 6e 5d 20 74 68 61 74 0a 2a 2a 20 69 73 20 63 6c  n] that.** is cl
1a690 6f 73 65 64 20 6f 72 20 6d 69 67 68 74 20 63 6c  osed or might cl
1a6a0 6f 73 65 20 62 65 66 6f 72 65 20 73 71 6c 69 74  ose before sqlit
1a6b0 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 72  e3_interrupt() r
1a6c0 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49  eturns..**.** ^I
1a6d0 66 20 61 6e 20 53 51 4c 20 6f 70 65 72 61 74 69  f an SQL operati
1a6e0 6f 6e 20 69 73 20 76 65 72 79 20 6e 65 61 72 6c  on is very nearl
1a6f0 79 20 66 69 6e 69 73 68 65 64 20 61 74 20 74 68  y finished at th
1a700 65 20 74 69 6d 65 20 77 68 65 6e 0a 2a 2a 20 73  e time when.** s
1a710 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
1a720 28 29 20 69 73 20 63 61 6c 6c 65 64 2c 20 74 68  () is called, th
1a730 65 6e 20 69 74 20 6d 69 67 68 74 20 6e 6f 74 20  en it might not 
1a740 68 61 76 65 20 61 6e 20 6f 70 70 6f 72 74 75 6e  have an opportun
1a750 69 74 79 0a 2a 2a 20 74 6f 20 62 65 20 69 6e 74  ity.** to be int
1a760 65 72 72 75 70 74 65 64 20 61 6e 64 20 6d 69 67  errupted and mig
1a770 68 74 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 63  ht continue to c
1a780 6f 6d 70 6c 65 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  ompletion..**.**
1a790 20 5e 41 6e 20 53 51 4c 20 6f 70 65 72 61 74 69   ^An SQL operati
1a7a0 6f 6e 20 74 68 61 74 20 69 73 20 69 6e 74 65 72  on that is inter
1a7b0 72 75 70 74 65 64 20 77 69 6c 6c 20 72 65 74 75  rupted will retu
1a7c0 72 6e 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52  rn [SQLITE_INTER
1a7d0 52 55 50 54 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68  RUPT]..** ^If th
1a7e0 65 20 69 6e 74 65 72 72 75 70 74 65 64 20 53 51  e interrupted SQ
1a7f0 4c 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 61  L operation is a
1a800 6e 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45  n INSERT, UPDATE
1a810 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20 74  , or DELETE.** t
1a820 68 61 74 20 69 73 20 69 6e 73 69 64 65 20 61 6e  hat is inside an
1a830 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61   explicit transa
1a840 63 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20  ction, then the 
1a850 65 6e 74 69 72 65 20 74 72 61 6e 73 61 63 74 69  entire transacti
1a860 6f 6e 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 72 6f  on.** will be ro
1a870 6c 6c 65 64 20 62 61 63 6b 20 61 75 74 6f 6d 61  lled back automa
1a880 74 69 63 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e  tically..**.** ^
1a890 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65  The sqlite3_inte
1a8a0 72 72 75 70 74 28 44 29 20 63 61 6c 6c 20 69 73  rrupt(D) call is
1a8b0 20 69 6e 20 65 66 66 65 63 74 20 75 6e 74 69 6c   in effect until
1a8c0 20 61 6c 6c 20 63 75 72 72 65 6e 74 6c 79 20 72   all currently r
1a8d0 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51 4c 20 73 74  unning.** SQL st
1a8e0 61 74 65 6d 65 6e 74 73 20 6f 6e 20 5b 64 61 74  atements on [dat
1a8f0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1a900 5d 20 44 20 63 6f 6d 70 6c 65 74 65 2e 20 20 5e  ] D complete.  ^
1a910 41 6e 79 20 6e 65 77 20 53 51 4c 20 73 74 61 74  Any new SQL stat
1a920 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61  ements.** that a
1a930 72 65 20 73 74 61 72 74 65 64 20 61 66 74 65 72  re started after
1a940 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74   the sqlite3_int
1a950 65 72 72 75 70 74 28 29 20 63 61 6c 6c 20 61 6e  errupt() call an
1a960 64 20 62 65 66 6f 72 65 20 74 68 65 20 0a 2a 2a  d before the .**
1a970 20 72 75 6e 6e 69 6e 67 20 73 74 61 74 65 6d 65   running stateme
1a980 6e 74 73 20 72 65 61 63 68 65 73 20 7a 65 72 6f  nts reaches zero
1a990 20 61 72 65 20 69 6e 74 65 72 72 75 70 74 65 64   are interrupted
1a9a0 20 61 73 20 69 66 20 74 68 65 79 20 68 61 64 20   as if they had 
1a9b0 62 65 65 6e 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20  been.** running 
1a9c0 70 72 69 6f 72 20 74 6f 20 74 68 65 20 73 71 6c  prior to the sql
1a9d0 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29  ite3_interrupt()
1a9e0 20 63 61 6c 6c 2e 20 20 5e 4e 65 77 20 53 51 4c   call.  ^New SQL
1a9f0 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74   statements.** t
1aa00 68 61 74 20 61 72 65 20 73 74 61 72 74 65 64 20  hat are started 
1aa10 61 66 74 65 72 20 74 68 65 20 72 75 6e 6e 69 6e  after the runnin
1aa20 67 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 75 6e  g statement coun
1aa30 74 20 72 65 61 63 68 65 73 20 7a 65 72 6f 20 61  t reaches zero a
1aa40 72 65 0a 2a 2a 20 6e 6f 74 20 65 66 66 65 63 74  re.** not effect
1aa50 65 64 20 62 79 20 74 68 65 20 73 71 6c 69 74 65  ed by the sqlite
1aa60 33 5f 69 6e 74 65 72 72 75 70 74 28 29 2e 0a 2a  3_interrupt()..*
1aa70 2a 20 5e 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c  * ^A call to sql
1aa80 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 44  ite3_interrupt(D
1aa90 29 20 74 68 61 74 20 6f 63 63 75 72 73 20 77 68  ) that occurs wh
1aaa0 65 6e 20 74 68 65 72 65 20 61 72 65 20 6e 6f 20  en there are no 
1aab0 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51 4c 20 73  running.** SQL s
1aac0 74 61 74 65 6d 65 6e 74 73 20 69 73 20 61 20 6e  tatements is a n
1aad0 6f 2d 6f 70 20 61 6e 64 20 68 61 73 20 6e 6f 20  o-op and has no 
1aae0 65 66 66 65 63 74 20 6f 6e 20 53 51 4c 20 73 74  effect on SQL st
1aaf0 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74  atements.** that
1ab00 20 61 72 65 20 73 74 61 72 74 65 64 20 61 66 74   are started aft
1ab10 65 72 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69  er the sqlite3_i
1ab20 6e 74 65 72 72 75 70 74 28 29 20 63 61 6c 6c 20  nterrupt() call 
1ab30 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 49  returns..**.** I
1ab40 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  f the database c
1ab50 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f 73 65 73  onnection closes
1ab60 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f   while [sqlite3_
1ab70 69 6e 74 65 72 72 75 70 74 28 29 5d 0a 2a 2a 20  interrupt()].** 
1ab80 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20  is running then 
1ab90 62 61 64 20 74 68 69 6e 67 73 20 77 69 6c 6c 20  bad things will 
1aba0 6c 69 6b 65 6c 79 20 68 61 70 70 65 6e 2e 0a 2a  likely happen..*
1abb0 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 69  /.void sqlite3_i
1abc0 6e 74 65 72 72 75 70 74 28 73 71 6c 69 74 65 33  nterrupt(sqlite3
1abd0 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
1abe0 52 45 46 3a 20 44 65 74 65 72 6d 69 6e 65 20 49  REF: Determine I
1abf0 66 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65  f An SQL Stateme
1ac00 6e 74 20 49 73 20 43 6f 6d 70 6c 65 74 65 0a 2a  nt Is Complete.*
1ac10 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
1ac20 6e 65 73 20 61 72 65 20 75 73 65 66 75 6c 20 64  nes are useful d
1ac30 75 72 69 6e 67 20 63 6f 6d 6d 61 6e 64 2d 6c 69  uring command-li
1ac40 6e 65 20 69 6e 70 75 74 20 74 6f 20 64 65 74 65  ne input to dete
1ac50 72 6d 69 6e 65 20 69 66 20 74 68 65 0a 2a 2a 20  rmine if the.** 
1ac60 63 75 72 72 65 6e 74 6c 79 20 65 6e 74 65 72 65  currently entere
1ac70 64 20 74 65 78 74 20 73 65 65 6d 73 20 74 6f 20  d text seems to 
1ac80 66 6f 72 6d 20 61 20 63 6f 6d 70 6c 65 74 65 20  form a complete 
1ac90 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 6f 72  SQL statement or
1aca0 0a 2a 2a 20 69 66 20 61 64 64 69 74 69 6f 6e 61  .** if additiona
1acb0 6c 20 69 6e 70 75 74 20 69 73 20 6e 65 65 64 65  l input is neede
1acc0 64 20 62 65 66 6f 72 65 20 73 65 6e 64 69 6e 67  d before sending
1acd0 20 74 68 65 20 74 65 78 74 20 69 6e 74 6f 0a 2a   the text into.*
1ace0 2a 20 53 51 4c 69 74 65 20 66 6f 72 20 70 61 72  * SQLite for par
1acf0 73 69 6e 67 2e 20 20 5e 54 68 65 73 65 20 72 6f  sing.  ^These ro
1ad00 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 31 20  utines return 1 
1ad10 69 66 20 74 68 65 20 69 6e 70 75 74 20 73 74 72  if the input str
1ad20 69 6e 67 0a 2a 2a 20 61 70 70 65 61 72 73 20 74  ing.** appears t
1ad30 6f 20 62 65 20 61 20 63 6f 6d 70 6c 65 74 65 20  o be a complete 
1ad40 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 20 20  SQL statement.  
1ad50 5e 41 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  ^A statement is 
1ad60 6a 75 64 67 65 64 20 74 6f 20 62 65 0a 2a 2a 20  judged to be.** 
1ad70 63 6f 6d 70 6c 65 74 65 20 69 66 20 69 74 20 65  complete if it e
1ad80 6e 64 73 20 77 69 74 68 20 61 20 73 65 6d 69 63  nds with a semic
1ad90 6f 6c 6f 6e 20 74 6f 6b 65 6e 20 61 6e 64 20 69  olon token and i
1ada0 73 20 6e 6f 74 20 61 20 70 72 65 66 69 78 20 6f  s not a prefix o
1adb0 66 20 61 0a 2a 2a 20 77 65 6c 6c 2d 66 6f 72 6d  f a.** well-form
1adc0 65 64 20 43 52 45 41 54 45 20 54 52 49 47 47 45  ed CREATE TRIGGE
1add0 52 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 53  R statement.  ^S
1ade0 65 6d 69 63 6f 6c 6f 6e 73 20 74 68 61 74 20 61  emicolons that a
1adf0 72 65 20 65 6d 62 65 64 64 65 64 20 77 69 74 68  re embedded with
1ae00 69 6e 0a 2a 2a 20 73 74 72 69 6e 67 20 6c 69 74  in.** string lit
1ae10 65 72 61 6c 73 20 6f 72 20 71 75 6f 74 65 64 20  erals or quoted 
1ae20 69 64 65 6e 74 69 66 69 65 72 20 6e 61 6d 65 73  identifier names
1ae30 20 6f 72 20 63 6f 6d 6d 65 6e 74 73 20 61 72 65   or comments are
1ae40 20 6e 6f 74 0a 2a 2a 20 69 6e 64 65 70 65 6e 64   not.** independ
1ae50 65 6e 74 20 74 6f 6b 65 6e 73 20 28 74 68 65 79  ent tokens (they
1ae60 20 61 72 65 20 70 61 72 74 20 6f 66 20 74 68 65   are part of the
1ae70 20 74 6f 6b 65 6e 20 69 6e 20 77 68 69 63 68 20   token in which 
1ae80 74 68 65 79 20 61 72 65 0a 2a 2a 20 65 6d 62 65  they are.** embe
1ae90 64 64 65 64 29 20 61 6e 64 20 74 68 75 73 20 64  dded) and thus d
1aea0 6f 20 6e 6f 74 20 63 6f 75 6e 74 20 61 73 20 61  o not count as a
1aeb0 20 73 74 61 74 65 6d 65 6e 74 20 74 65 72 6d 69   statement termi
1aec0 6e 61 74 6f 72 2e 20 20 5e 57 68 69 74 65 73 70  nator.  ^Whitesp
1aed0 61 63 65 0a 2a 2a 20 61 6e 64 20 63 6f 6d 6d 65  ace.** and comme
1aee0 6e 74 73 20 74 68 61 74 20 66 6f 6c 6c 6f 77 20  nts that follow 
1aef0 74 68 65 20 66 69 6e 61 6c 20 73 65 6d 69 63 6f  the final semico
1af00 6c 6f 6e 20 61 72 65 20 69 67 6e 6f 72 65 64 2e  lon are ignored.
1af10 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f  .**.** ^These ro
1af20 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 30 20  utines return 0 
1af30 69 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  if the statement
1af40 20 69 73 20 69 6e 63 6f 6d 70 6c 65 74 65 2e 20   is incomplete. 
1af50 20 5e 49 66 20 61 0a 2a 2a 20 6d 65 6d 6f 72 79   ^If a.** memory
1af60 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c   allocation fail
1af70 73 2c 20 74 68 65 6e 20 53 51 4c 49 54 45 5f 4e  s, then SQLITE_N
1af80 4f 4d 45 4d 20 69 73 20 72 65 74 75 72 6e 65 64  OMEM is returned
1af90 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72  ..**.** ^These r
1afa0 6f 75 74 69 6e 65 73 20 64 6f 20 6e 6f 74 20 70  outines do not p
1afb0 61 72 73 65 20 74 68 65 20 53 51 4c 20 73 74 61  arse the SQL sta
1afc0 74 65 6d 65 6e 74 73 20 74 68 75 73 0a 2a 2a 20  tements thus.** 
1afd0 77 69 6c 6c 20 6e 6f 74 20 64 65 74 65 63 74 20  will not detect 
1afe0 73 79 6e 74 61 63 74 69 63 61 6c 6c 79 20 69 6e  syntactically in
1aff0 63 6f 72 72 65 63 74 20 53 51 4c 2e 0a 2a 2a 0a  correct SQL..**.
1b000 2a 2a 20 5e 28 49 66 20 53 51 4c 69 74 65 20 68  ** ^(If SQLite h
1b010 61 73 20 6e 6f 74 20 62 65 65 6e 20 69 6e 69 74  as not been init
1b020 69 61 6c 69 7a 65 64 20 75 73 69 6e 67 20 5b 73  ialized using [s
1b030 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
1b040 65 28 29 5d 20 70 72 69 6f 72 20 0a 2a 2a 20 74  e()] prior .** t
1b050 6f 20 69 6e 76 6f 6b 69 6e 67 20 73 71 6c 69 74  o invoking sqlit
1b060 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 20  e3_complete16() 
1b070 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 69 6e 69  then sqlite3_ini
1b080 74 69 61 6c 69 7a 65 28 29 20 69 73 20 69 6e 76  tialize() is inv
1b090 6f 6b 65 64 0a 2a 2a 20 61 75 74 6f 6d 61 74 69  oked.** automati
1b0a0 63 61 6c 6c 79 20 62 79 20 73 71 6c 69 74 65 33  cally by sqlite3
1b0b0 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 2e 20 20  _complete16().  
1b0c0 49 66 20 74 68 61 74 20 69 6e 69 74 69 61 6c 69  If that initiali
1b0d0 7a 61 74 69 6f 6e 20 66 61 69 6c 73 2c 0a 2a 2a  zation fails,.**
1b0e0 20 74 68 65 6e 20 74 68 65 20 72 65 74 75 72 6e   then the return
1b0f0 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69   value from sqli
1b100 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29  te3_complete16()
1b110 20 77 69 6c 6c 20 62 65 20 6e 6f 6e 2d 7a 65 72   will be non-zer
1b120 6f 0a 2a 2a 20 72 65 67 61 72 64 6c 65 73 73 20  o.** regardless 
1b130 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f  of whether or no
1b140 74 20 74 68 65 20 69 6e 70 75 74 20 53 51 4c 20  t the input SQL 
1b150 69 73 20 63 6f 6d 70 6c 65 74 65 2e 29 5e 0a 2a  is complete.)^.*
1b160 2a 0a 2a 2a 20 54 68 65 20 69 6e 70 75 74 20 74  *.** The input t
1b170 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c  o [sqlite3_compl
1b180 65 74 65 28 29 5d 20 6d 75 73 74 20 62 65 20 61  ete()] must be a
1b190 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
1b1a0 0a 2a 2a 20 55 54 46 2d 38 20 73 74 72 69 6e 67  .** UTF-8 string
1b1b0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 70 75  ..**.** The inpu
1b1c0 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f  t to [sqlite3_co
1b1d0 6d 70 6c 65 74 65 31 36 28 29 5d 20 6d 75 73 74  mplete16()] must
1b1e0 20 62 65 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69   be a zero-termi
1b1f0 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d 31 36 20  nated.** UTF-16 
1b200 73 74 72 69 6e 67 20 69 6e 20 6e 61 74 69 76 65  string in native
1b210 20 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2f 0a   byte order..*/.
1b220 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70  int sqlite3_comp
1b230 6c 65 74 65 28 63 6f 6e 73 74 20 63 68 61 72 20  lete(const char 
1b240 2a 73 71 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74  *sql);.int sqlit
1b250 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 63 6f  e3_complete16(co
1b260 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 29 3b 0a  nst void *sql);.
1b270 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1b280 20 52 65 67 69 73 74 65 72 20 41 20 43 61 6c 6c   Register A Call
1b290 62 61 63 6b 20 54 6f 20 48 61 6e 64 6c 65 20 53  back To Handle S
1b2a0 51 4c 49 54 45 5f 42 55 53 59 20 45 72 72 6f 72  QLITE_BUSY Error
1b2b0 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  s.** KEYWORDS: {
1b2c0 62 75 73 79 2d 68 61 6e 64 6c 65 72 20 63 61 6c  busy-handler cal
1b2d0 6c 62 61 63 6b 7d 20 7b 62 75 73 79 20 68 61 6e  lback} {busy han
1b2e0 64 6c 65 72 7d 0a 2a 2a 20 4d 45 54 48 4f 44 3a  dler}.** METHOD:
1b2f0 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e   sqlite3.**.** ^
1b300 54 68 65 20 73 71 6c 69 74 65 33 5f 62 75 73 79  The sqlite3_busy
1b310 5f 68 61 6e 64 6c 65 72 28 44 2c 58 2c 50 29 20  _handler(D,X,P) 
1b320 72 6f 75 74 69 6e 65 20 73 65 74 73 20 61 20 63  routine sets a c
1b330 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
1b340 20 58 0a 2a 2a 20 74 68 61 74 20 6d 69 67 68 74   X.** that might
1b350 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 69 74 68   be invoked with
1b360 20 61 72 67 75 6d 65 6e 74 20 50 20 77 68 65 6e   argument P when
1b370 65 76 65 72 0a 2a 2a 20 61 6e 20 61 74 74 65 6d  ever.** an attem
1b380 70 74 20 69 73 20 6d 61 64 65 20 74 6f 20 61 63  pt is made to ac
1b390 63 65 73 73 20 61 20 64 61 74 61 62 61 73 65 20  cess a database 
1b3a0 74 61 62 6c 65 20 61 73 73 6f 63 69 61 74 65 64  table associated
1b3b0 20 77 69 74 68 0a 2a 2a 20 5b 64 61 74 61 62 61   with.** [databa
1b3c0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44  se connection] D
1b3d0 20 77 68 65 6e 20 61 6e 6f 74 68 65 72 20 74 68   when another th
1b3e0 72 65 61 64 0a 2a 2a 20 6f 72 20 70 72 6f 63 65  read.** or proce
1b3f0 73 73 20 68 61 73 20 74 68 65 20 74 61 62 6c 65  ss has the table
1b400 20 6c 6f 63 6b 65 64 2e 0a 2a 2a 20 54 68 65 20   locked..** The 
1b410 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e  sqlite3_busy_han
1b420 64 6c 65 72 28 29 20 69 6e 74 65 72 66 61 63 65  dler() interface
1b430 20 69 73 20 75 73 65 64 20 74 6f 20 69 6d 70 6c   is used to impl
1b440 65 6d 65 6e 74 0a 2a 2a 20 5b 73 71 6c 69 74 65  ement.** [sqlite
1b450 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29  3_busy_timeout()
1b460 5d 20 61 6e 64 20 5b 50 52 41 47 4d 41 20 62 75  ] and [PRAGMA bu
1b470 73 79 5f 74 69 6d 65 6f 75 74 5d 2e 0a 2a 2a 0a  sy_timeout]..**.
1b480 2a 2a 20 5e 49 66 20 74 68 65 20 62 75 73 79 20  ** ^If the busy 
1b490 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c  callback is NULL
1b4a0 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54 45 5f 42  , then [SQLITE_B
1b4b0 55 53 59 5d 0a 2a 2a 20 69 73 20 72 65 74 75 72  USY].** is retur
1b4c0 6e 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 20  ned immediately 
1b4d0 75 70 6f 6e 20 65 6e 63 6f 75 6e 74 65 72 69 6e  upon encounterin
1b4e0 67 20 74 68 65 20 6c 6f 63 6b 2e 20 20 5e 49 66  g the lock.  ^If
1b4f0 20 74 68 65 20 62 75 73 79 20 63 61 6c 6c 62 61   the busy callba
1b500 63 6b 0a 2a 2a 20 69 73 20 6e 6f 74 20 4e 55 4c  ck.** is not NUL
1b510 4c 2c 20 74 68 65 6e 20 74 68 65 20 63 61 6c 6c  L, then the call
1b520 62 61 63 6b 20 6d 69 67 68 74 20 62 65 20 69 6e  back might be in
1b530 76 6f 6b 65 64 20 77 69 74 68 20 74 77 6f 20 61  voked with two a
1b540 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20  rguments..**.** 
1b550 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d  ^The first argum
1b560 65 6e 74 20 74 6f 20 74 68 65 20 62 75 73 79 20  ent to the busy 
1b570 68 61 6e 64 6c 65 72 20 69 73 20 61 20 63 6f 70  handler is a cop
1b580 79 20 6f 66 20 74 68 65 20 76 6f 69 64 2a 20 70  y of the void* p
1b590 6f 69 6e 74 65 72 20 77 68 69 63 68 0a 2a 2a 20  ointer which.** 
1b5a0 69 73 20 74 68 65 20 74 68 69 72 64 20 61 72 67  is the third arg
1b5b0 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33  ument to sqlite3
1b5c0 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 29 2e  _busy_handler().
1b5d0 20 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 61 72    ^The second ar
1b5e0 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 74 68 65  gument to.** the
1b5f0 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 63 61   busy handler ca
1b600 6c 6c 62 61 63 6b 20 69 73 20 74 68 65 20 6e 75  llback is the nu
1b610 6d 62 65 72 20 6f 66 20 74 69 6d 65 73 20 74 68  mber of times th
1b620 61 74 20 74 68 65 20 62 75 73 79 20 68 61 6e 64  at the busy hand
1b630 6c 65 72 20 68 61 73 0a 2a 2a 20 62 65 65 6e 20  ler has.** been 
1b640 69 6e 76 6f 6b 65 64 20 70 72 65 76 69 6f 75 73  invoked previous
1b650 6c 79 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20  ly for the same 
1b660 6c 6f 63 6b 69 6e 67 20 65 76 65 6e 74 2e 20 20  locking event.  
1b670 5e 49 66 20 74 68 65 0a 2a 2a 20 62 75 73 79 20  ^If the.** busy 
1b680 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73  callback returns
1b690 20 30 2c 20 74 68 65 6e 20 6e 6f 20 61 64 64 69   0, then no addi
1b6a0 74 69 6f 6e 61 6c 20 61 74 74 65 6d 70 74 73 20  tional attempts 
1b6b0 61 72 65 20 6d 61 64 65 20 74 6f 0a 2a 2a 20 61  are made to.** a
1b6c0 63 63 65 73 73 20 74 68 65 20 64 61 74 61 62 61  ccess the databa
1b6d0 73 65 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 42  se and [SQLITE_B
1b6e0 55 53 59 5d 20 69 73 20 72 65 74 75 72 6e 65 64  USY] is returned
1b6f0 0a 2a 2a 20 74 6f 20 74 68 65 20 61 70 70 6c 69  .** to the appli
1b700 63 61 74 69 6f 6e 2e 0a 2a 2a 20 5e 49 66 20 74  cation..** ^If t
1b710 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  he callback retu
1b720 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68  rns non-zero, th
1b730 65 6e 20 61 6e 6f 74 68 65 72 20 61 74 74 65 6d  en another attem
1b740 70 74 0a 2a 2a 20 69 73 20 6d 61 64 65 20 74 6f  pt.** is made to
1b750 20 61 63 63 65 73 73 20 74 68 65 20 64 61 74 61   access the data
1b760 62 61 73 65 20 61 6e 64 20 74 68 65 20 63 79 63  base and the cyc
1b770 6c 65 20 72 65 70 65 61 74 73 2e 0a 2a 2a 0a 2a  le repeats..**.*
1b780 2a 20 54 68 65 20 70 72 65 73 65 6e 63 65 20 6f  * The presence o
1b790 66 20 61 20 62 75 73 79 20 68 61 6e 64 6c 65 72  f a busy handler
1b7a0 20 64 6f 65 73 20 6e 6f 74 20 67 75 61 72 61 6e   does not guaran
1b7b0 74 65 65 20 74 68 61 74 20 69 74 20 77 69 6c 6c  tee that it will
1b7c0 20 62 65 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 77   be invoked.** w
1b7d0 68 65 6e 20 74 68 65 72 65 20 69 73 20 6c 6f 63  hen there is loc
1b7e0 6b 20 63 6f 6e 74 65 6e 74 69 6f 6e 2e 20 5e 49  k contention. ^I
1b7f0 66 20 53 51 4c 69 74 65 20 64 65 74 65 72 6d 69  f SQLite determi
1b800 6e 65 73 20 74 68 61 74 20 69 6e 76 6f 6b 69 6e  nes that invokin
1b810 67 20 74 68 65 20 62 75 73 79 0a 2a 2a 20 68 61  g the busy.** ha
1b820 6e 64 6c 65 72 20 63 6f 75 6c 64 20 72 65 73 75  ndler could resu
1b830 6c 74 20 69 6e 20 61 20 64 65 61 64 6c 6f 63 6b  lt in a deadlock
1b840 2c 20 69 74 20 77 69 6c 6c 20 67 6f 20 61 68 65  , it will go ahe
1b850 61 64 20 61 6e 64 20 72 65 74 75 72 6e 20 5b 53  ad and return [S
1b860 51 4c 49 54 45 5f 42 55 53 59 5d 0a 2a 2a 20 74  QLITE_BUSY].** t
1b870 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  o the applicatio
1b880 6e 20 69 6e 73 74 65 61 64 20 6f 66 20 69 6e 76  n instead of inv
1b890 6f 6b 69 6e 67 20 74 68 65 20 0a 2a 2a 20 62 75  oking the .** bu
1b8a0 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 43  sy handler..** C
1b8b0 6f 6e 73 69 64 65 72 20 61 20 73 63 65 6e 61 72  onsider a scenar
1b8c0 69 6f 20 77 68 65 72 65 20 6f 6e 65 20 70 72 6f  io where one pro
1b8d0 63 65 73 73 20 69 73 20 68 6f 6c 64 69 6e 67 20  cess is holding 
1b8e0 61 20 72 65 61 64 20 6c 6f 63 6b 20 74 68 61 74  a read lock that
1b8f0 0a 2a 2a 20 69 74 20 69 73 20 74 72 79 69 6e 67  .** it is trying
1b900 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61   to promote to a
1b910 20 72 65 73 65 72 76 65 64 20 6c 6f 63 6b 20 61   reserved lock a
1b920 6e 64 0a 2a 2a 20 61 20 73 65 63 6f 6e 64 20 70  nd.** a second p
1b930 72 6f 63 65 73 73 20 69 73 20 68 6f 6c 64 69 6e  rocess is holdin
1b940 67 20 61 20 72 65 73 65 72 76 65 64 20 6c 6f 63  g a reserved loc
1b950 6b 20 74 68 61 74 20 69 74 20 69 73 20 74 72 79  k that it is try
1b960 69 6e 67 0a 2a 2a 20 74 6f 20 70 72 6f 6d 6f 74  ing.** to promot
1b970 65 20 74 6f 20 61 6e 20 65 78 63 6c 75 73 69 76  e to an exclusiv
1b980 65 20 6c 6f 63 6b 2e 20 20 54 68 65 20 66 69 72  e lock.  The fir
1b990 73 74 20 70 72 6f 63 65 73 73 20 63 61 6e 6e 6f  st process canno
1b9a0 74 20 70 72 6f 63 65 65 64 0a 2a 2a 20 62 65 63  t proceed.** bec
1b9b0 61 75 73 65 20 69 74 20 69 73 20 62 6c 6f 63 6b  ause it is block
1b9c0 65 64 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64  ed by the second
1b9d0 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20   and the second 
1b9e0 70 72 6f 63 65 73 73 20 63 61 6e 6e 6f 74 0a 2a  process cannot.*
1b9f0 2a 20 70 72 6f 63 65 65 64 20 62 65 63 61 75 73  * proceed becaus
1ba00 65 20 69 74 20 69 73 20 62 6c 6f 63 6b 65 64 20  e it is blocked 
1ba10 62 79 20 74 68 65 20 66 69 72 73 74 2e 20 20 49  by the first.  I
1ba20 66 20 62 6f 74 68 20 70 72 6f 63 65 73 73 65 73  f both processes
1ba30 0a 2a 2a 20 69 6e 76 6f 6b 65 20 74 68 65 20 62  .** invoke the b
1ba40 75 73 79 20 68 61 6e 64 6c 65 72 73 2c 20 6e 65  usy handlers, ne
1ba50 69 74 68 65 72 20 77 69 6c 6c 20 6d 61 6b 65 20  ither will make 
1ba60 61 6e 79 20 70 72 6f 67 72 65 73 73 2e 20 20 54  any progress.  T
1ba70 68 65 72 65 66 6f 72 65 2c 0a 2a 2a 20 53 51 4c  herefore,.** SQL
1ba80 69 74 65 20 72 65 74 75 72 6e 73 20 5b 53 51 4c  ite returns [SQL
1ba90 49 54 45 5f 42 55 53 59 5d 20 66 6f 72 20 74 68  ITE_BUSY] for th
1baa0 65 20 66 69 72 73 74 20 70 72 6f 63 65 73 73 2c  e first process,
1bab0 20 68 6f 70 69 6e 67 20 74 68 61 74 20 74 68 69   hoping that thi
1bac0 73 0a 2a 2a 20 77 69 6c 6c 20 69 6e 64 75 63 65  s.** will induce
1bad0 20 74 68 65 20 66 69 72 73 74 20 70 72 6f 63 65   the first proce
1bae0 73 73 20 74 6f 20 72 65 6c 65 61 73 65 20 69 74  ss to release it
1baf0 73 20 72 65 61 64 20 6c 6f 63 6b 20 61 6e 64 20  s read lock and 
1bb00 61 6c 6c 6f 77 0a 2a 2a 20 74 68 65 20 73 65 63  allow.** the sec
1bb10 6f 6e 64 20 70 72 6f 63 65 73 73 20 74 6f 20 70  ond process to p
1bb20 72 6f 63 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54  roceed..**.** ^T
1bb30 68 65 20 64 65 66 61 75 6c 74 20 62 75 73 79 20  he default busy 
1bb40 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c  callback is NULL
1bb50 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 72 65 20  ..**.** ^(There 
1bb60 63 61 6e 20 6f 6e 6c 79 20 62 65 20 61 20 73 69  can only be a si
1bb70 6e 67 6c 65 20 62 75 73 79 20 68 61 6e 64 6c 65  ngle busy handle
1bb80 72 20 64 65 66 69 6e 65 64 20 66 6f 72 20 65 61  r defined for ea
1bb90 63 68 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20  ch.** [database 
1bba0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 53 65  connection].  Se
1bbb0 74 74 69 6e 67 20 61 20 6e 65 77 20 62 75 73 79  tting a new busy
1bbc0 20 68 61 6e 64 6c 65 72 20 63 6c 65 61 72 73 20   handler clears 
1bbd0 61 6e 79 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c  any.** previousl
1bbe0 79 20 73 65 74 20 68 61 6e 64 6c 65 72 2e 29 5e  y set handler.)^
1bbf0 20 20 5e 4e 6f 74 65 20 74 68 61 74 20 63 61 6c    ^Note that cal
1bc00 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 62 75  ling [sqlite3_bu
1bc10 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d 0a 2a 2a  sy_timeout()].**
1bc20 20 6f 72 20 65 76 61 6c 75 61 74 69 6e 67 20 5b   or evaluating [
1bc30 50 52 41 47 4d 41 20 62 75 73 79 5f 74 69 6d 65  PRAGMA busy_time
1bc40 6f 75 74 3d 4e 5d 20 77 69 6c 6c 20 63 68 61 6e  out=N] will chan
1bc50 67 65 20 74 68 65 0a 2a 2a 20 62 75 73 79 20 68  ge the.** busy h
1bc60 61 6e 64 6c 65 72 20 61 6e 64 20 74 68 75 73 20  andler and thus 
1bc70 63 6c 65 61 72 20 61 6e 79 20 70 72 65 76 69 6f  clear any previo
1bc80 75 73 6c 79 20 73 65 74 20 62 75 73 79 20 68 61  usly set busy ha
1bc90 6e 64 6c 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ndler..**.** The
1bca0 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 73   busy callback s
1bcb0 68 6f 75 6c 64 20 6e 6f 74 20 74 61 6b 65 20 61  hould not take a
1bcc0 6e 79 20 61 63 74 69 6f 6e 73 20 77 68 69 63 68  ny actions which
1bcd0 20 6d 6f 64 69 66 79 20 74 68 65 0a 2a 2a 20 64   modify the.** d
1bce0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1bcf0 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20  on that invoked 
1bd00 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72  the busy handler
1bd10 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64  .  In other word
1bd20 73 2c 0a 2a 2a 20 74 68 65 20 62 75 73 79 20 68  s,.** the busy h
1bd30 61 6e 64 6c 65 72 20 69 73 20 6e 6f 74 20 72 65  andler is not re
1bd40 65 6e 74 72 61 6e 74 2e 20 20 41 6e 79 20 73 75  entrant.  Any su
1bd50 63 68 20 61 63 74 69 6f 6e 73 0a 2a 2a 20 72 65  ch actions.** re
1bd60 73 75 6c 74 20 69 6e 20 75 6e 64 65 66 69 6e 65  sult in undefine
1bd70 64 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 20 0a  d behavior..** .
1bd80 2a 2a 20 41 20 62 75 73 79 20 68 61 6e 64 6c 65  ** A busy handle
1bd90 72 20 6d 75 73 74 20 6e 6f 74 20 63 6c 6f 73 65  r must not close
1bda0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
1bdb0 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f 72 20 5b  nnection.** or [
1bdc0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
1bdd0 6e 74 5d 20 74 68 61 74 20 69 6e 76 6f 6b 65 64  nt] that invoked
1bde0 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65   the busy handle
1bdf0 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  r..*/.int sqlite
1be00 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 73  3_busy_handler(s
1be10 71 6c 69 74 65 33 2a 2c 69 6e 74 28 2a 29 28 76  qlite3*,int(*)(v
1be20 6f 69 64 2a 2c 69 6e 74 29 2c 76 6f 69 64 2a 29  oid*,int),void*)
1be30 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
1be40 46 3a 20 53 65 74 20 41 20 42 75 73 79 20 54 69  F: Set A Busy Ti
1be50 6d 65 6f 75 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a  meout.** METHOD:
1be60 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e   sqlite3.**.** ^
1be70 54 68 69 73 20 72 6f 75 74 69 6e 65 20 73 65 74  This routine set
1be80 73 20 61 20 5b 73 71 6c 69 74 65 33 5f 62 75 73  s a [sqlite3_bus
1be90 79 5f 68 61 6e 64 6c 65 72 20 7c 20 62 75 73 79  y_handler | busy
1bea0 20 68 61 6e 64 6c 65 72 5d 20 74 68 61 74 20 73   handler] that s
1beb0 6c 65 65 70 73 0a 2a 2a 20 66 6f 72 20 61 20 73  leeps.** for a s
1bec0 70 65 63 69 66 69 65 64 20 61 6d 6f 75 6e 74 20  pecified amount 
1bed0 6f 66 20 74 69 6d 65 20 77 68 65 6e 20 61 20 74  of time when a t
1bee0 61 62 6c 65 20 69 73 20 6c 6f 63 6b 65 64 2e 20  able is locked. 
1bef0 20 5e 54 68 65 20 68 61 6e 64 6c 65 72 0a 2a 2a   ^The handler.**
1bf00 20 77 69 6c 6c 20 73 6c 65 65 70 20 6d 75 6c 74   will sleep mult
1bf10 69 70 6c 65 20 74 69 6d 65 73 20 75 6e 74 69 6c  iple times until
1bf20 20 61 74 20 6c 65 61 73 74 20 22 6d 73 22 20 6d   at least "ms" m
1bf30 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73  illiseconds of s
1bf40 6c 65 65 70 69 6e 67 0a 2a 2a 20 68 61 76 65 20  leeping.** have 
1bf50 61 63 63 75 6d 75 6c 61 74 65 64 2e 20 20 5e 41  accumulated.  ^A
1bf60 66 74 65 72 20 61 74 20 6c 65 61 73 74 20 22 6d  fter at least "m
1bf70 73 22 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20  s" milliseconds 
1bf80 6f 66 20 73 6c 65 65 70 69 6e 67 2c 0a 2a 2a 20  of sleeping,.** 
1bf90 74 68 65 20 68 61 6e 64 6c 65 72 20 72 65 74 75  the handler retu
1bfa0 72 6e 73 20 30 20 77 68 69 63 68 20 63 61 75 73  rns 0 which caus
1bfb0 65 73 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  es [sqlite3_step
1bfc0 28 29 5d 20 74 6f 20 72 65 74 75 72 6e 0a 2a 2a  ()] to return.**
1bfd0 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2e 0a   [SQLITE_BUSY]..
1bfe0 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 74  **.** ^Calling t
1bff0 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69 74 68  his routine with
1c000 20 61 6e 20 61 72 67 75 6d 65 6e 74 20 6c 65 73   an argument les
1c010 73 20 74 68 61 6e 20 6f 72 20 65 71 75 61 6c 20  s than or equal 
1c020 74 6f 20 7a 65 72 6f 0a 2a 2a 20 74 75 72 6e 73  to zero.** turns
1c030 20 6f 66 66 20 61 6c 6c 20 62 75 73 79 20 68 61   off all busy ha
1c040 6e 64 6c 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28  ndlers..**.** ^(
1c050 54 68 65 72 65 20 63 61 6e 20 6f 6e 6c 79 20 62  There can only b
1c060 65 20 61 20 73 69 6e 67 6c 65 20 62 75 73 79 20  e a single busy 
1c070 68 61 6e 64 6c 65 72 20 66 6f 72 20 61 20 70 61  handler for a pa
1c080 72 74 69 63 75 6c 61 72 0a 2a 2a 20 5b 64 61 74  rticular.** [dat
1c090 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1c0a0 5d 20 61 74 20 61 6e 79 20 67 69 76 65 6e 20 6d  ] at any given m
1c0b0 6f 6d 65 6e 74 2e 20 20 49 66 20 61 6e 6f 74 68  oment.  If anoth
1c0c0 65 72 20 62 75 73 79 20 68 61 6e 64 6c 65 72 0a  er busy handler.
1c0d0 2a 2a 20 77 61 73 20 64 65 66 69 6e 65 64 20 20  ** was defined  
1c0e0 28 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  (using [sqlite3_
1c0f0 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 29 5d 29  busy_handler()])
1c100 20 70 72 69 6f 72 20 74 6f 20 63 61 6c 6c 69 6e   prior to callin
1c110 67 0a 2a 2a 20 74 68 69 73 20 72 6f 75 74 69 6e  g.** this routin
1c120 65 2c 20 74 68 61 74 20 6f 74 68 65 72 20 62 75  e, that other bu
1c130 73 79 20 68 61 6e 64 6c 65 72 20 69 73 20 63 6c  sy handler is cl
1c140 65 61 72 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53  eared.)^.**.** S
1c150 65 65 20 61 6c 73 6f 3a 20 20 5b 50 52 41 47 4d  ee also:  [PRAGM
1c160 41 20 62 75 73 79 5f 74 69 6d 65 6f 75 74 5d 0a  A busy_timeout].
1c170 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  */.int sqlite3_b
1c180 75 73 79 5f 74 69 6d 65 6f 75 74 28 73 71 6c 69  usy_timeout(sqli
1c190 74 65 33 2a 2c 20 69 6e 74 20 6d 73 29 3b 0a 0a  te3*, int ms);..
1c1a0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1c1b0 43 6f 6e 76 65 6e 69 65 6e 63 65 20 52 6f 75 74  Convenience Rout
1c1c0 69 6e 65 73 20 46 6f 72 20 52 75 6e 6e 69 6e 67  ines For Running
1c1d0 20 51 75 65 72 69 65 73 0a 2a 2a 20 4d 45 54 48   Queries.** METH
1c1e0 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a  OD: sqlite3.**.*
1c1f0 2a 20 54 68 69 73 20 69 73 20 61 20 6c 65 67 61  * This is a lega
1c200 63 79 20 69 6e 74 65 72 66 61 63 65 20 74 68 61  cy interface tha
1c210 74 20 69 73 20 70 72 65 73 65 72 76 65 64 20 66  t is preserved f
1c220 6f 72 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d  or backwards com
1c230 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a 20 55  patibility..** U
1c240 73 65 20 6f 66 20 74 68 69 73 20 69 6e 74 65 72  se of this inter
1c250 66 61 63 65 20 69 73 20 6e 6f 74 20 72 65 63 6f  face is not reco
1c260 6d 6d 65 6e 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 44  mmended..**.** D
1c270 65 66 69 6e 69 74 69 6f 6e 3a 20 41 20 3c 62 3e  efinition: A <b>
1c280 72 65 73 75 6c 74 20 74 61 62 6c 65 3c 2f 62 3e  result table</b>
1c290 20 69 73 20 6d 65 6d 6f 72 79 20 64 61 74 61 20   is memory data 
1c2a0 73 74 72 75 63 74 75 72 65 20 63 72 65 61 74 65  structure create
1c2b0 64 20 62 79 20 74 68 65 0a 2a 2a 20 5b 73 71 6c  d by the.** [sql
1c2c0 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29  ite3_get_table()
1c2d0 5d 20 69 6e 74 65 72 66 61 63 65 2e 20 20 41 20  ] interface.  A 
1c2e0 72 65 73 75 6c 74 20 74 61 62 6c 65 20 72 65 63  result table rec
1c2f0 6f 72 64 73 20 74 68 65 0a 2a 2a 20 63 6f 6d 70  ords the.** comp
1c300 6c 65 74 65 20 71 75 65 72 79 20 72 65 73 75 6c  lete query resul
1c310 74 73 20 66 72 6f 6d 20 6f 6e 65 20 6f 72 20 6d  ts from one or m
1c320 6f 72 65 20 71 75 65 72 69 65 73 2e 0a 2a 2a 0a  ore queries..**.
1c330 2a 2a 20 54 68 65 20 74 61 62 6c 65 20 63 6f 6e  ** The table con
1c340 63 65 70 74 75 61 6c 6c 79 20 68 61 73 20 61 20  ceptually has a 
1c350 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 20 61  number of rows a
1c360 6e 64 20 63 6f 6c 75 6d 6e 73 2e 20 20 42 75 74  nd columns.  But
1c370 0a 2a 2a 20 74 68 65 73 65 20 6e 75 6d 62 65 72  .** these number
1c380 73 20 61 72 65 20 6e 6f 74 20 70 61 72 74 20 6f  s are not part o
1c390 66 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 62  f the result tab
1c3a0 6c 65 20 69 74 73 65 6c 66 2e 20 20 54 68 65 73  le itself.  Thes
1c3b0 65 0a 2a 2a 20 6e 75 6d 62 65 72 73 20 61 72 65  e.** numbers are
1c3c0 20 6f 62 74 61 69 6e 65 64 20 73 65 70 61 72 61   obtained separa
1c3d0 74 65 6c 79 2e 20 20 4c 65 74 20 4e 20 62 65 20  tely.  Let N be 
1c3e0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f  the number of ro
1c3f0 77 73 0a 2a 2a 20 61 6e 64 20 4d 20 62 65 20 74  ws.** and M be t
1c400 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c  he number of col
1c410 75 6d 6e 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65  umns..**.** A re
1c420 73 75 6c 74 20 74 61 62 6c 65 20 69 73 20 61 6e  sult table is an
1c430 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65   array of pointe
1c440 72 73 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69  rs to zero-termi
1c450 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74 72 69  nated UTF-8 stri
1c460 6e 67 73 2e 0a 2a 2a 20 54 68 65 72 65 20 61 72  ngs..** There ar
1c470 65 20 28 4e 2b 31 29 2a 4d 20 65 6c 65 6d 65 6e  e (N+1)*M elemen
1c480 74 73 20 69 6e 20 74 68 65 20 61 72 72 61 79 2e  ts in the array.
1c490 20 20 54 68 65 20 66 69 72 73 74 20 4d 20 70 6f    The first M po
1c4a0 69 6e 74 65 72 73 20 70 6f 69 6e 74 0a 2a 2a 20  inters point.** 
1c4b0 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74  to zero-terminat
1c4c0 65 64 20 73 74 72 69 6e 67 73 20 74 68 61 74 20  ed strings that 
1c4d0 20 63 6f 6e 74 61 69 6e 20 74 68 65 20 6e 61 6d   contain the nam
1c4e0 65 73 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e  es of the column
1c4f0 73 2e 0a 2a 2a 20 54 68 65 20 72 65 6d 61 69 6e  s..** The remain
1c500 69 6e 67 20 65 6e 74 72 69 65 73 20 61 6c 6c 20  ing entries all 
1c510 70 6f 69 6e 74 20 74 6f 20 71 75 65 72 79 20 72  point to query r
1c520 65 73 75 6c 74 73 2e 20 20 4e 55 4c 4c 20 76 61  esults.  NULL va
1c530 6c 75 65 73 20 72 65 73 75 6c 74 0a 2a 2a 20 69  lues result.** i
1c540 6e 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73 2e  n NULL pointers.
1c550 20 20 41 6c 6c 20 6f 74 68 65 72 20 76 61 6c 75    All other valu
1c560 65 73 20 61 72 65 20 69 6e 20 74 68 65 69 72 20  es are in their 
1c570 55 54 46 2d 38 20 7a 65 72 6f 2d 74 65 72 6d 69  UTF-8 zero-termi
1c580 6e 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20  nated.** string 
1c590 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 61  representation a
1c5a0 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73  s returned by [s
1c5b0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
1c5c0 78 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 41 20 72  xt()]..**.** A r
1c5d0 65 73 75 6c 74 20 74 61 62 6c 65 20 6d 69 67 68  esult table migh
1c5e0 74 20 63 6f 6e 73 69 73 74 20 6f 66 20 6f 6e 65  t consist of one
1c5f0 20 6f 72 20 6d 6f 72 65 20 6d 65 6d 6f 72 79 20   or more memory 
1c600 61 6c 6c 6f 63 61 74 69 6f 6e 73 2e 0a 2a 2a 20  allocations..** 
1c610 49 74 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74  It is not safe t
1c620 6f 20 70 61 73 73 20 61 20 72 65 73 75 6c 74 20  o pass a result 
1c630 74 61 62 6c 65 20 64 69 72 65 63 74 6c 79 20 74  table directly t
1c640 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  o [sqlite3_free(
1c650 29 5d 2e 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20  )]..** A result 
1c660 74 61 62 6c 65 20 73 68 6f 75 6c 64 20 62 65 20  table should be 
1c670 64 65 61 6c 6c 6f 63 61 74 65 64 20 75 73 69 6e  deallocated usin
1c680 67 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 5f  g [sqlite3_free_
1c690 74 61 62 6c 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  table()]..**.** 
1c6a0 5e 28 41 73 20 61 6e 20 65 78 61 6d 70 6c 65 20  ^(As an example 
1c6b0 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 74 61  of the result ta
1c6c0 62 6c 65 20 66 6f 72 6d 61 74 2c 20 73 75 70 70  ble format, supp
1c6d0 6f 73 65 20 61 20 71 75 65 72 79 20 72 65 73 75  ose a query resu
1c6e0 6c 74 0a 2a 2a 20 69 73 20 61 73 20 66 6f 6c 6c  lt.** is as foll
1c6f0 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63  ows:.**.** <bloc
1c700 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20  kquote><pre>.** 
1c710 20 20 20 20 20 20 20 4e 61 6d 65 20 20 20 20 20         Name     
1c720 20 20 20 7c 20 41 67 65 0a 2a 2a 20 20 20 20 20     | Age.**     
1c730 20 20 20 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d     -------------
1c740 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 0a 2a 2a 20 20 20  ----------.**   
1c750 20 20 20 20 20 41 6c 69 63 65 20 20 20 20 20 20       Alice      
1c760 20 7c 20 34 33 0a 2a 2a 20 20 20 20 20 20 20 20   | 43.**        
1c770 42 6f 62 20 20 20 20 20 20 20 20 20 7c 20 32 38  Bob         | 28
1c780 0a 2a 2a 20 20 20 20 20 20 20 20 43 69 6e 64 79  .**        Cindy
1c790 20 20 20 20 20 20 20 7c 20 32 31 0a 2a 2a 20 3c         | 21.** <
1c7a0 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
1c7b0 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 72 65 20 61  e>.**.** There a
1c7c0 72 65 20 74 77 6f 20 63 6f 6c 75 6d 6e 20 28 4d  re two column (M
1c7d0 3d 3d 32 29 20 61 6e 64 20 74 68 72 65 65 20 72  ==2) and three r
1c7e0 6f 77 73 20 28 4e 3d 3d 33 29 2e 20 20 54 68 75  ows (N==3).  Thu
1c7f0 73 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20  s the.** result 
1c800 74 61 62 6c 65 20 68 61 73 20 38 20 65 6e 74 72  table has 8 entr
1c810 69 65 73 2e 20 20 53 75 70 70 6f 73 65 20 74 68  ies.  Suppose th
1c820 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69  e result table i
1c830 73 20 73 74 6f 72 65 64 0a 2a 2a 20 69 6e 20 61  s stored.** in a
1c840 6e 20 61 72 72 61 79 20 6e 61 6d 65 73 20 61 7a  n array names az
1c850 52 65 73 75 6c 74 2e 20 20 54 68 65 6e 20 61 7a  Result.  Then az
1c860 52 65 73 75 6c 74 20 68 6f 6c 64 73 20 74 68 69  Result holds thi
1c870 73 20 63 6f 6e 74 65 6e 74 3a 0a 2a 2a 0a 2a 2a  s content:.**.**
1c880 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72   <blockquote><pr
1c890 65 3e 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52  e>.**        azR
1c8a0 65 73 75 6c 74 26 23 39 31 3b 30 5d 20 3d 20 22  esult&#91;0] = "
1c8b0 4e 61 6d 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20  Name";.**       
1c8c0 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 31 5d   azResult&#91;1]
1c8d0 20 3d 20 22 41 67 65 22 3b 0a 2a 2a 20 20 20 20   = "Age";.**    
1c8e0 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31      azResult&#91
1c8f0 3b 32 5d 20 3d 20 22 41 6c 69 63 65 22 3b 0a 2a  ;2] = "Alice";.*
1c900 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c  *        azResul
1c910 74 26 23 39 31 3b 33 5d 20 3d 20 22 34 33 22 3b  t&#91;3] = "43";
1c920 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73  .**        azRes
1c930 75 6c 74 26 23 39 31 3b 34 5d 20 3d 20 22 42 6f  ult&#91;4] = "Bo
1c940 62 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a  b";.**        az
1c950 52 65 73 75 6c 74 26 23 39 31 3b 35 5d 20 3d 20  Result&#91;5] = 
1c960 22 32 38 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20  "28";.**        
1c970 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 36 5d 20  azResult&#91;6] 
1c980 3d 20 22 43 69 6e 64 79 22 3b 0a 2a 2a 20 20 20  = "Cindy";.**   
1c990 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39       azResult&#9
1c9a0 31 3b 37 5d 20 3d 20 22 32 31 22 3b 0a 2a 2a 20  1;7] = "21";.** 
1c9b0 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f  </pre></blockquo
1c9c0 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  te>)^.**.** ^The
1c9d0 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62   sqlite3_get_tab
1c9e0 6c 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 65 76  le() function ev
1c9f0 61 6c 75 61 74 65 73 20 6f 6e 65 20 6f 72 20 6d  aluates one or m
1ca00 6f 72 65 0a 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e  ore.** semicolon
1ca10 2d 73 65 70 61 72 61 74 65 64 20 53 51 4c 20 73  -separated SQL s
1ca20 74 61 74 65 6d 65 6e 74 73 20 69 6e 20 74 68 65  tatements in the
1ca30 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
1ca40 20 55 54 46 2d 38 0a 2a 2a 20 73 74 72 69 6e 67   UTF-8.** string
1ca50 20 6f 66 20 69 74 73 20 32 6e 64 20 70 61 72 61   of its 2nd para
1ca60 6d 65 74 65 72 20 61 6e 64 20 72 65 74 75 72 6e  meter and return
1ca70 73 20 61 20 72 65 73 75 6c 74 20 74 61 62 6c 65  s a result table
1ca80 20 74 6f 20 74 68 65 0a 2a 2a 20 70 6f 69 6e 74   to the.** point
1ca90 65 72 20 67 69 76 65 6e 20 69 6e 20 69 74 73 20  er given in its 
1caa0 33 72 64 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a  3rd parameter..*
1cab0 2a 0a 2a 2a 20 41 66 74 65 72 20 74 68 65 20 61  *.** After the a
1cac0 70 70 6c 69 63 61 74 69 6f 6e 20 68 61 73 20 66  pplication has f
1cad0 69 6e 69 73 68 65 64 20 77 69 74 68 20 74 68 65  inished with the
1cae0 20 72 65 73 75 6c 74 20 66 72 6f 6d 20 73 71 6c   result from sql
1caf0 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29  ite3_get_table()
1cb00 2c 0a 2a 2a 20 69 74 20 6d 75 73 74 20 70 61 73  ,.** it must pas
1cb10 73 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 62  s the result tab
1cb20 6c 65 20 70 6f 69 6e 74 65 72 20 74 6f 20 73 71  le pointer to sq
1cb30 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65  lite3_free_table
1cb40 28 29 20 69 6e 20 6f 72 64 65 72 20 74 6f 0a 2a  () in order to.*
1cb50 2a 20 72 65 6c 65 61 73 65 20 74 68 65 20 6d 65  * release the me
1cb60 6d 6f 72 79 20 74 68 61 74 20 77 61 73 20 6d 61  mory that was ma
1cb70 6c 6c 6f 63 65 64 2e 20 20 42 65 63 61 75 73 65  lloced.  Because
1cb80 20 6f 66 20 74 68 65 20 77 61 79 20 74 68 65 0a   of the way the.
1cb90 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  ** [sqlite3_mall
1cba0 6f 63 28 29 5d 20 68 61 70 70 65 6e 73 20 77 69  oc()] happens wi
1cbb0 74 68 69 6e 20 73 71 6c 69 74 65 33 5f 67 65 74  thin sqlite3_get
1cbc0 5f 74 61 62 6c 65 28 29 2c 20 74 68 65 20 63 61  _table(), the ca
1cbd0 6c 6c 69 6e 67 0a 2a 2a 20 66 75 6e 63 74 69 6f  lling.** functio
1cbe0 6e 20 6d 75 73 74 20 6e 6f 74 20 74 72 79 20 74  n must not try t
1cbf0 6f 20 63 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f  o call [sqlite3_
1cc00 66 72 65 65 28 29 5d 20 64 69 72 65 63 74 6c 79  free()] directly
1cc10 2e 20 20 4f 6e 6c 79 0a 2a 2a 20 5b 73 71 6c 69  .  Only.** [sqli
1cc20 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29  te3_free_table()
1cc30 5d 20 69 73 20 61 62 6c 65 20 74 6f 20 72 65 6c  ] is able to rel
1cc40 65 61 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20  ease the memory 
1cc50 70 72 6f 70 65 72 6c 79 20 61 6e 64 20 73 61 66  properly and saf
1cc60 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ely..**.** The s
1cc70 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65  qlite3_get_table
1cc80 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  () interface is 
1cc90 69 6d 70 6c 65 6d 65 6e 74 65 64 20 61 73 20 61  implemented as a
1cca0 20 77 72 61 70 70 65 72 20 61 72 6f 75 6e 64 0a   wrapper around.
1ccb0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63  ** [sqlite3_exec
1ccc0 28 29 5d 2e 20 20 54 68 65 20 73 71 6c 69 74 65  ()].  The sqlite
1ccd0 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 72 6f  3_get_table() ro
1cce0 75 74 69 6e 65 20 64 6f 65 73 20 6e 6f 74 20 68  utine does not h
1ccf0 61 76 65 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f  ave access.** to
1cd00 20 61 6e 79 20 69 6e 74 65 72 6e 61 6c 20 64 61   any internal da
1cd10 74 61 20 73 74 72 75 63 74 75 72 65 73 20 6f 66  ta structures of
1cd20 20 53 51 4c 69 74 65 2e 20 20 49 74 20 75 73 65   SQLite.  It use
1cd30 73 20 6f 6e 6c 79 20 74 68 65 20 70 75 62 6c 69  s only the publi
1cd40 63 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 64  c.** interface d
1cd50 65 66 69 6e 65 64 20 68 65 72 65 2e 20 20 41 73  efined here.  As
1cd60 20 61 20 63 6f 6e 73 65 71 75 65 6e 63 65 2c 20   a consequence, 
1cd70 65 72 72 6f 72 73 20 74 68 61 74 20 6f 63 63 75  errors that occu
1cd80 72 20 69 6e 20 74 68 65 0a 2a 2a 20 77 72 61 70  r in the.** wrap
1cd90 70 65 72 20 6c 61 79 65 72 20 6f 75 74 73 69 64  per layer outsid
1cda0 65 20 6f 66 20 74 68 65 20 69 6e 74 65 72 6e 61  e of the interna
1cdb0 6c 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28  l [sqlite3_exec(
1cdc0 29 5d 20 63 61 6c 6c 20 61 72 65 20 6e 6f 74 0a  )] call are not.
1cdd0 2a 2a 20 72 65 66 6c 65 63 74 65 64 20 69 6e 20  ** reflected in 
1cde0 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73  subsequent calls
1cdf0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 72 72   to [sqlite3_err
1ce00 63 6f 64 65 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73  code()] or.** [s
1ce10 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d  qlite3_errmsg()]
1ce20 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
1ce30 5f 67 65 74 5f 74 61 62 6c 65 28 0a 20 20 73 71  _get_table(.  sq
1ce40 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20  lite3 *db,      
1ce50 20 20 20 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64      /* An open d
1ce60 61 74 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e  atabase */.  con
1ce70 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20  st char *zSql,  
1ce80 20 20 20 2f 2a 20 53 51 4c 20 74 6f 20 62 65 20     /* SQL to be 
1ce90 65 76 61 6c 75 61 74 65 64 20 2a 2f 0a 20 20 63  evaluated */.  c
1cea0 68 61 72 20 2a 2a 2a 70 61 7a 52 65 73 75 6c 74  har ***pazResult
1ceb0 2c 20 20 20 20 2f 2a 20 52 65 73 75 6c 74 73 20  ,    /* Results 
1cec0 6f 66 20 74 68 65 20 71 75 65 72 79 20 2a 2f 0a  of the query */.
1ced0 20 20 69 6e 74 20 2a 70 6e 52 6f 77 2c 20 20 20    int *pnRow,   
1cee0 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65          /* Numbe
1cef0 72 20 6f 66 20 72 65 73 75 6c 74 20 72 6f 77 73  r of result rows
1cf00 20 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f   written here */
1cf10 0a 20 20 69 6e 74 20 2a 70 6e 43 6f 6c 75 6d 6e  .  int *pnColumn
1cf20 2c 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62  ,        /* Numb
1cf30 65 72 20 6f 66 20 72 65 73 75 6c 74 20 63 6f 6c  er of result col
1cf40 75 6d 6e 73 20 77 72 69 74 74 65 6e 20 68 65 72  umns written her
1cf50 65 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 70 7a  e */.  char **pz
1cf60 45 72 72 6d 73 67 20 20 20 20 20 20 20 2f 2a 20  Errmsg       /* 
1cf70 45 72 72 6f 72 20 6d 73 67 20 77 72 69 74 74 65  Error msg writte
1cf80 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a 76 6f 69  n here */.);.voi
1cf90 64 20 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74  d sqlite3_free_t
1cfa0 61 62 6c 65 28 63 68 61 72 20 2a 2a 72 65 73 75  able(char **resu
1cfb0 6c 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  lt);../*.** CAPI
1cfc0 33 52 45 46 3a 20 46 6f 72 6d 61 74 74 65 64 20  3REF: Formatted 
1cfd0 53 74 72 69 6e 67 20 50 72 69 6e 74 69 6e 67 20  String Printing 
1cfe0 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20  Functions.**.** 
1cff0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  These routines a
1d000 72 65 20 77 6f 72 6b 2d 61 6c 69 6b 65 73 20 6f  re work-alikes o
1d010 66 20 74 68 65 20 22 70 72 69 6e 74 66 28 29 22  f the "printf()"
1d020 20 66 61 6d 69 6c 79 20 6f 66 20 66 75 6e 63 74   family of funct
1d030 69 6f 6e 73 0a 2a 2a 20 66 72 6f 6d 20 74 68 65  ions.** from the
1d040 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72   standard C libr
1d050 61 72 79 2e 0a 2a 2a 20 54 68 65 73 65 20 72 6f  ary..** These ro
1d060 75 74 69 6e 65 73 20 75 6e 64 65 72 73 74 61 6e  utines understan
1d070 64 20 6d 6f 73 74 20 6f 66 20 74 68 65 20 63 6f  d most of the co
1d080 6d 6d 6f 6e 20 4b 26 52 20 66 6f 72 6d 61 74 74  mmon K&R formatt
1d090 69 6e 67 20 6f 70 74 69 6f 6e 73 2c 0a 2a 2a 20  ing options,.** 
1d0a0 70 6c 75 73 20 73 6f 6d 65 20 61 64 64 69 74 69  plus some additi
1d0b0 6f 6e 61 6c 20 6e 6f 6e 2d 73 74 61 6e 64 61 72  onal non-standar
1d0c0 64 20 66 6f 72 6d 61 74 73 2c 20 64 65 74 61 69  d formats, detai
1d0d0 6c 65 64 20 62 65 6c 6f 77 2e 0a 2a 2a 20 4e 6f  led below..** No
1d0e0 74 65 20 74 68 61 74 20 73 6f 6d 65 20 6f 66 20  te that some of 
1d0f0 74 68 65 20 6d 6f 72 65 20 6f 62 73 63 75 72 65  the more obscure
1d100 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 69   formatting opti
1d110 6f 6e 73 20 66 72 6f 6d 20 72 65 63 65 6e 74 0a  ons from recent.
1d120 2a 2a 20 43 2d 6c 69 62 72 61 72 79 20 73 74 61  ** C-library sta
1d130 6e 64 61 72 64 73 20 61 72 65 20 6f 6d 69 74 74  ndards are omitt
1d140 65 64 20 66 72 6f 6d 20 74 68 69 73 20 69 6d 70  ed from this imp
1d150 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 0a 2a 2a 0a  lementation..**.
1d160 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
1d170 6d 70 72 69 6e 74 66 28 29 20 61 6e 64 20 73 71  mprintf() and sq
1d180 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74 66 28 29  lite3_vmprintf()
1d190 20 72 6f 75 74 69 6e 65 73 20 77 72 69 74 65 20   routines write 
1d1a0 74 68 65 69 72 0a 2a 2a 20 72 65 73 75 6c 74 73  their.** results
1d1b0 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74   into memory obt
1d1c0 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69  ained from [sqli
1d1d0 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 0a 2a  te3_malloc()]..*
1d1e0 2a 20 54 68 65 20 73 74 72 69 6e 67 73 20 72 65  * The strings re
1d1f0 74 75 72 6e 65 64 20 62 79 20 74 68 65 73 65 20  turned by these 
1d200 74 77 6f 20 72 6f 75 74 69 6e 65 73 20 73 68 6f  two routines sho
1d210 75 6c 64 20 62 65 0a 2a 2a 20 72 65 6c 65 61 73  uld be.** releas
1d220 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 66  ed by [sqlite3_f
1d230 72 65 65 28 29 5d 2e 20 20 5e 42 6f 74 68 20 72  ree()].  ^Both r
1d240 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 61  outines return a
1d250 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  .** NULL pointer
1d260 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c   if [sqlite3_mal
1d270 6c 6f 63 28 29 5d 20 69 73 20 75 6e 61 62 6c 65  loc()] is unable
1d280 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 65 6e 6f   to allocate eno
1d290 75 67 68 0a 2a 2a 20 6d 65 6d 6f 72 79 20 74 6f  ugh.** memory to
1d2a0 20 68 6f 6c 64 20 74 68 65 20 72 65 73 75 6c 74   hold the result
1d2b0 69 6e 67 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a  ing string..**.*
1d2c0 2a 20 5e 28 54 68 65 20 73 71 6c 69 74 65 33 5f  * ^(The sqlite3_
1d2d0 73 6e 70 72 69 6e 74 66 28 29 20 72 6f 75 74 69  snprintf() routi
1d2e0 6e 65 20 69 73 20 73 69 6d 69 6c 61 72 20 74 6f  ne is similar to
1d2f0 20 22 73 6e 70 72 69 6e 74 66 28 29 22 20 66 72   "snprintf()" fr
1d300 6f 6d 0a 2a 2a 20 74 68 65 20 73 74 61 6e 64 61  om.** the standa
1d310 72 64 20 43 20 6c 69 62 72 61 72 79 2e 20 20 54  rd C library.  T
1d320 68 65 20 72 65 73 75 6c 74 20 69 73 20 77 72 69  he result is wri
1d330 74 74 65 6e 20 69 6e 74 6f 20 74 68 65 0a 2a 2a  tten into the.**
1d340 20 62 75 66 66 65 72 20 73 75 70 70 6c 69 65 64   buffer supplied
1d350 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70   as the second p
1d360 61 72 61 6d 65 74 65 72 20 77 68 6f 73 65 20 73  arameter whose s
1d370 69 7a 65 20 69 73 20 67 69 76 65 6e 20 62 79 0a  ize is given by.
1d380 2a 2a 20 74 68 65 20 66 69 72 73 74 20 70 61 72  ** the first par
1d390 61 6d 65 74 65 72 2e 20 4e 6f 74 65 20 74 68 61  ameter. Note tha
1d3a0 74 20 74 68 65 20 6f 72 64 65 72 20 6f 66 20 74  t the order of t
1d3b0 68 65 0a 2a 2a 20 66 69 72 73 74 20 74 77 6f 20  he.** first two 
1d3c0 70 61 72 61 6d 65 74 65 72 73 20 69 73 20 72 65  parameters is re
1d3d0 76 65 72 73 65 64 20 66 72 6f 6d 20 73 6e 70 72  versed from snpr
1d3e0 69 6e 74 66 28 29 2e 29 5e 20 20 54 68 69 73 20  intf().)^  This 
1d3f0 69 73 20 61 6e 0a 2a 2a 20 68 69 73 74 6f 72 69  is an.** histori
1d400 63 61 6c 20 61 63 63 69 64 65 6e 74 20 74 68 61  cal accident tha
1d410 74 20 63 61 6e 6e 6f 74 20 62 65 20 66 69 78 65  t cannot be fixe
1d420 64 20 77 69 74 68 6f 75 74 20 62 72 65 61 6b 69  d without breaki
1d430 6e 67 0a 2a 2a 20 62 61 63 6b 77 61 72 64 73 20  ng.** backwards 
1d440 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 20 20  compatibility.  
1d450 5e 28 4e 6f 74 65 20 61 6c 73 6f 20 74 68 61 74  ^(Note also that
1d460 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74   sqlite3_snprint
1d470 66 28 29 0a 2a 2a 20 72 65 74 75 72 6e 73 20 61  f().** returns a
1d480 20 70 6f 69 6e 74 65 72 20 74 6f 20 69 74 73 20   pointer to its 
1d490 62 75 66 66 65 72 20 69 6e 73 74 65 61 64 20 6f  buffer instead o
1d4a0 66 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a  f the number of.
1d4b0 2a 2a 20 63 68 61 72 61 63 74 65 72 73 20 61 63  ** characters ac
1d4c0 74 75 61 6c 6c 79 20 77 72 69 74 74 65 6e 20 69  tually written i
1d4d0 6e 74 6f 20 74 68 65 20 62 75 66 66 65 72 2e 29  nto the buffer.)
1d4e0 5e 20 20 57 65 20 61 64 6d 69 74 20 74 68 61 74  ^  We admit that
1d4f0 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  .** the number o
1d500 66 20 63 68 61 72 61 63 74 65 72 73 20 77 72 69  f characters wri
1d510 74 74 65 6e 20 77 6f 75 6c 64 20 62 65 20 61 20  tten would be a 
1d520 6d 6f 72 65 20 75 73 65 66 75 6c 20 72 65 74 75  more useful retu
1d530 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 62 75 74 20  rn.** value but 
1d540 77 65 20 63 61 6e 6e 6f 74 20 63 68 61 6e 67 65  we cannot change
1d550 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74   the implementat
1d560 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f 73  ion of sqlite3_s
1d570 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 6e 6f 77  nprintf().** now
1d580 20 77 69 74 68 6f 75 74 20 62 72 65 61 6b 69 6e   without breakin
1d590 67 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e  g compatibility.
1d5a0 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 6c 6f 6e 67 20  .**.** ^As long 
1d5b0 61 73 20 74 68 65 20 62 75 66 66 65 72 20 73 69  as the buffer si
1d5c0 7a 65 20 69 73 20 67 72 65 61 74 65 72 20 74 68  ze is greater th
1d5d0 61 6e 20 7a 65 72 6f 2c 20 73 71 6c 69 74 65 33  an zero, sqlite3
1d5e0 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 67  _snprintf().** g
1d5f0 75 61 72 61 6e 74 65 65 73 20 74 68 61 74 20 74  uarantees that t
1d600 68 65 20 62 75 66 66 65 72 20 69 73 20 61 6c 77  he buffer is alw
1d610 61 79 73 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  ays zero-termina
1d620 74 65 64 2e 20 20 5e 54 68 65 20 66 69 72 73 74  ted.  ^The first
1d630 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 22 6e  .** parameter "n
1d640 22 20 69 73 20 74 68 65 20 74 6f 74 61 6c 20 73  " is the total s
1d650 69 7a 65 20 6f 66 20 74 68 65 20 62 75 66 66 65  ize of the buffe
1d660 72 2c 20 69 6e 63 6c 75 64 69 6e 67 20 73 70 61  r, including spa
1d670 63 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 7a 65  ce for.** the ze
1d680 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20  ro terminator.  
1d690 53 6f 20 74 68 65 20 6c 6f 6e 67 65 73 74 20 73  So the longest s
1d6a0 74 72 69 6e 67 20 74 68 61 74 20 63 61 6e 20 62  tring that can b
1d6b0 65 20 63 6f 6d 70 6c 65 74 65 6c 79 0a 2a 2a 20  e completely.** 
1d6c0 77 72 69 74 74 65 6e 20 77 69 6c 6c 20 62 65 20  written will be 
1d6d0 6e 2d 31 20 63 68 61 72 61 63 74 65 72 73 2e 0a  n-1 characters..
1d6e0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
1d6f0 65 33 5f 76 73 6e 70 72 69 6e 74 66 28 29 20 72  e3_vsnprintf() r
1d700 6f 75 74 69 6e 65 20 69 73 20 61 20 76 61 72 61  outine is a vara
1d710 72 67 73 20 76 65 72 73 69 6f 6e 20 6f 66 20 73  rgs version of s
1d720 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28  qlite3_snprintf(
1d730 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  )..**.** These r
1d740 6f 75 74 69 6e 65 73 20 61 6c 6c 20 69 6d 70 6c  outines all impl
1d750 65 6d 65 6e 74 20 73 6f 6d 65 20 61 64 64 69 74  ement some addit
1d760 69 6f 6e 61 6c 20 66 6f 72 6d 61 74 74 69 6e 67  ional formatting
1d770 0a 2a 2a 20 6f 70 74 69 6f 6e 73 20 74 68 61 74  .** options that
1d780 20 61 72 65 20 75 73 65 66 75 6c 20 66 6f 72 20   are useful for 
1d790 63 6f 6e 73 74 72 75 63 74 69 6e 67 20 53 51 4c  constructing SQL
1d7a0 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20   statements..** 
1d7b0 41 6c 6c 20 6f 66 20 74 68 65 20 75 73 75 61 6c  All of the usual
1d7c0 20 70 72 69 6e 74 66 28 29 20 66 6f 72 6d 61 74   printf() format
1d7d0 74 69 6e 67 20 6f 70 74 69 6f 6e 73 20 61 70 70  ting options app
1d7e0 6c 79 2e 20 20 49 6e 20 61 64 64 69 74 69 6f 6e  ly.  In addition
1d7f0 2c 20 74 68 65 72 65 0a 2a 2a 20 69 73 20 61 72  , there.** is ar
1d800 65 20 22 25 71 22 2c 20 22 25 51 22 2c 20 22 25  e "%q", "%Q", "%
1d810 77 22 20 61 6e 64 20 22 25 7a 22 20 6f 70 74 69  w" and "%z" opti
1d820 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65  ons..**.** ^(The
1d830 20 25 71 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73   %q option works
1d840 20 6c 69 6b 65 20 25 73 20 69 6e 20 74 68 61 74   like %s in that
1d850 20 69 74 20 73 75 62 73 74 69 74 75 74 65 73 20   it substitutes 
1d860 61 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 65 64  a nul-terminated
1d870 0a 2a 2a 20 73 74 72 69 6e 67 20 66 72 6f 6d 20  .** string from 
1d880 74 68 65 20 61 72 67 75 6d 65 6e 74 20 6c 69 73  the argument lis
1d890 74 2e 20 20 42 75 74 20 25 71 20 61 6c 73 6f 20  t.  But %q also 
1d8a0 64 6f 75 62 6c 65 73 20 65 76 65 72 79 20 27 5c  doubles every '\
1d8b0 27 27 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a  '' character..**
1d8c0 20 25 71 20 69 73 20 64 65 73 69 67 6e 65 64 20   %q is designed 
1d8d0 66 6f 72 20 75 73 65 20 69 6e 73 69 64 65 20 61  for use inside a
1d8e0 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 2e   string literal.
1d8f0 29 5e 20 20 42 79 20 64 6f 75 62 6c 69 6e 67 20  )^  By doubling 
1d900 65 61 63 68 20 27 5c 27 27 0a 2a 2a 20 63 68 61  each '\''.** cha
1d910 72 61 63 74 65 72 20 69 74 20 65 73 63 61 70 65  racter it escape
1d920 73 20 74 68 61 74 20 63 68 61 72 61 63 74 65 72  s that character
1d930 20 61 6e 64 20 61 6c 6c 6f 77 73 20 69 74 20 74   and allows it t
1d940 6f 20 62 65 20 69 6e 73 65 72 74 65 64 20 69 6e  o be inserted in
1d950 74 6f 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67  to.** the string
1d960 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 65 78 61 6d  ..**.** For exam
1d970 70 6c 65 2c 20 61 73 73 75 6d 65 20 74 68 65 20  ple, assume the 
1d980 73 74 72 69 6e 67 20 76 61 72 69 61 62 6c 65 20  string variable 
1d990 7a 54 65 78 74 20 63 6f 6e 74 61 69 6e 73 20 74  zText contains t
1d9a0 65 78 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a  ext as follows:.
1d9b0 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74  **.** <blockquot
1d9c0 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72  e><pre>.**  char
1d9d0 20 2a 7a 54 65 78 74 20 3d 20 22 49 74 27 73 20   *zText = "It's 
1d9e0 61 20 68 61 70 70 79 20 64 61 79 21 22 3b 0a 2a  a happy day!";.*
1d9f0 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71  * </pre></blockq
1da00 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 4f 6e 65 20  uote>.**.** One 
1da10 63 61 6e 20 75 73 65 20 74 68 69 73 20 74 65 78  can use this tex
1da20 74 20 69 6e 20 61 6e 20 53 51 4c 20 73 74 61 74  t in an SQL stat
1da30 65 6d 65 6e 74 20 61 73 20 66 6f 6c 6c 6f 77 73  ement as follows
1da40 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  :.**.** <blockqu
1da50 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68  ote><pre>.**  ch
1da60 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71 6c 69 74  ar *zSQL = sqlit
1da70 65 33 5f 6d 70 72 69 6e 74 66 28 22 49 4e 53 45  e3_mprintf("INSE
1da80 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 20 56 41  RT INTO table VA
1da90 4c 55 45 53 28 27 25 71 27 29 22 2c 20 7a 54 65  LUES('%q')", zTe
1daa0 78 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33  xt);.**  sqlite3
1dab0 5f 65 78 65 63 28 64 62 2c 20 7a 53 51 4c 2c 20  _exec(db, zSQL, 
1dac0 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 71  0, 0, 0);.**  sq
1dad0 6c 69 74 65 33 5f 66 72 65 65 28 7a 53 51 4c 29  lite3_free(zSQL)
1dae0 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f  ;.** </pre></blo
1daf0 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 42  ckquote>.**.** B
1db00 65 63 61 75 73 65 20 74 68 65 20 25 71 20 66 6f  ecause the %q fo
1db10 72 6d 61 74 20 73 74 72 69 6e 67 20 69 73 20 75  rmat string is u
1db20 73 65 64 2c 20 74 68 65 20 27 5c 27 27 20 63 68  sed, the '\'' ch
1db30 61 72 61 63 74 65 72 20 69 6e 20 7a 54 65 78 74  aracter in zText
1db40 0a 2a 2a 20 69 73 20 65 73 63 61 70 65 64 20 61  .** is escaped a
1db50 6e 64 20 74 68 65 20 53 51 4c 20 67 65 6e 65 72  nd the SQL gener
1db60 61 74 65 64 20 69 73 20 61 73 20 66 6f 6c 6c 6f  ated is as follo
1db70 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  ws:.**.** <block
1db80 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20  quote><pre>.**  
1db90 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c  INSERT INTO tabl
1dba0 65 31 20 56 41 4c 55 45 53 28 27 49 74 27 27 73  e1 VALUES('It''s
1dbb0 20 61 20 68 61 70 70 79 20 64 61 79 21 27 29 0a   a happy day!').
1dbc0 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b  ** </pre></block
1dbd0 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69  quote>.**.** Thi
1dbe0 73 20 69 73 20 63 6f 72 72 65 63 74 2e 20 20 48  s is correct.  H
1dbf0 61 64 20 77 65 20 75 73 65 64 20 25 73 20 69 6e  ad we used %s in
1dc00 73 74 65 61 64 20 6f 66 20 25 71 2c 20 74 68 65  stead of %q, the
1dc10 20 67 65 6e 65 72 61 74 65 64 20 53 51 4c 0a 2a   generated SQL.*
1dc20 2a 20 77 6f 75 6c 64 20 68 61 76 65 20 6c 6f 6f  * would have loo
1dc30 6b 65 64 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a  ked like this:.*
1dc40 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65  *.** <blockquote
1dc50 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e 53 45 52  ><pre>.**  INSER
1dc60 54 20 49 4e 54 4f 20 74 61 62 6c 65 31 20 56 41  T INTO table1 VA
1dc70 4c 55 45 53 28 27 49 74 27 73 20 61 20 68 61 70  LUES('It's a hap
1dc80 70 79 20 64 61 79 21 27 29 3b 0a 2a 2a 20 3c 2f  py day!');.** </
1dc90 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  pre></blockquote
1dca0 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 73 65 63  >.**.** This sec
1dcb0 6f 6e 64 20 65 78 61 6d 70 6c 65 20 69 73 20 61  ond example is a
1dcc0 6e 20 53 51 4c 20 73 79 6e 74 61 78 20 65 72 72  n SQL syntax err
1dcd0 6f 72 2e 20 20 41 73 20 61 20 67 65 6e 65 72 61  or.  As a genera
1dce0 6c 20 72 75 6c 65 20 79 6f 75 20 73 68 6f 75 6c  l rule you shoul
1dcf0 64 0a 2a 2a 20 61 6c 77 61 79 73 20 75 73 65 20  d.** always use 
1dd00 25 71 20 69 6e 73 74 65 61 64 20 6f 66 20 25 73  %q instead of %s
1dd10 20 77 68 65 6e 20 69 6e 73 65 72 74 69 6e 67 20   when inserting 
1dd20 74 65 78 74 20 69 6e 74 6f 20 61 20 73 74 72 69  text into a stri
1dd30 6e 67 20 6c 69 74 65 72 61 6c 2e 0a 2a 2a 0a 2a  ng literal..**.*
1dd40 2a 20 5e 28 54 68 65 20 25 51 20 6f 70 74 69 6f  * ^(The %Q optio
1dd50 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20 25 71 20  n works like %q 
1dd60 65 78 63 65 70 74 20 69 74 20 61 6c 73 6f 20 61  except it also a
1dd70 64 64 73 20 73 69 6e 67 6c 65 20 71 75 6f 74 65  dds single quote
1dd80 73 20 61 72 6f 75 6e 64 0a 2a 2a 20 74 68 65 20  s around.** the 
1dd90 6f 75 74 73 69 64 65 20 6f 66 20 74 68 65 20 74  outside of the t
1dda0 6f 74 61 6c 20 73 74 72 69 6e 67 2e 20 20 41 64  otal string.  Ad
1ddb0 64 69 74 69 6f 6e 61 6c 6c 79 2c 20 69 66 20 74  ditionally, if t
1ddc0 68 65 20 70 61 72 61 6d 65 74 65 72 20 69 6e 20  he parameter in 
1ddd0 74 68 65 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20  the.** argument 
1dde0 6c 69 73 74 20 69 73 20 61 20 4e 55 4c 4c 20 70  list is a NULL p
1ddf0 6f 69 6e 74 65 72 2c 20 25 51 20 73 75 62 73 74  ointer, %Q subst
1de00 69 74 75 74 65 73 20 74 68 65 20 74 65 78 74 20  itutes the text 
1de10 22 4e 55 4c 4c 22 20 28 77 69 74 68 6f 75 74 0a  "NULL" (without.
1de20 2a 2a 20 73 69 6e 67 6c 65 20 71 75 6f 74 65 73  ** single quotes
1de30 29 2e 29 5e 20 20 53 6f 2c 20 66 6f 72 20 65 78  ).)^  So, for ex
1de40 61 6d 70 6c 65 2c 20 6f 6e 65 20 63 6f 75 6c 64  ample, one could
1de50 20 73 61 79 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f   say:.**.** <blo
1de60 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a  ckquote><pre>.**
1de70 20 20 63 68 61 72 20 2a 7a 53 51 4c 20 3d 20 73    char *zSQL = s
1de80 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 22  qlite3_mprintf("
1de90 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c  INSERT INTO tabl
1dea0 65 20 56 41 4c 55 45 53 28 25 51 29 22 2c 20 7a  e VALUES(%Q)", z
1deb0 54 65 78 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74  Text);.**  sqlit
1dec0 65 33 5f 65 78 65 63 28 64 62 2c 20 7a 53 51 4c  e3_exec(db, zSQL
1ded0 2c 20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20  , 0, 0, 0);.**  
1dee0 73 71 6c 69 74 65 33 5f 66 72 65 65 28 7a 53 51  sqlite3_free(zSQ
1def0 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62  L);.** </pre></b
1df00 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a  lockquote>.**.**
1df10 20 54 68 65 20 63 6f 64 65 20 61 62 6f 76 65 20   The code above 
1df20 77 69 6c 6c 20 72 65 6e 64 65 72 20 61 20 63 6f  will render a co
1df30 72 72 65 63 74 20 53 51 4c 20 73 74 61 74 65 6d  rrect SQL statem
1df40 65 6e 74 20 69 6e 20 74 68 65 20 7a 53 51 4c 0a  ent in the zSQL.
1df50 2a 2a 20 76 61 72 69 61 62 6c 65 20 65 76 65 6e  ** variable even
1df60 20 69 66 20 74 68 65 20 7a 54 65 78 74 20 76 61   if the zText va
1df70 72 69 61 62 6c 65 20 69 73 20 61 20 4e 55 4c 4c  riable is a NULL
1df80 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20   pointer..**.** 
1df90 5e 28 54 68 65 20 22 25 77 22 20 66 6f 72 6d 61  ^(The "%w" forma
1dfa0 74 74 69 6e 67 20 6f 70 74 69 6f 6e 20 69 73 20  tting option is 
1dfb0 6c 69 6b 65 20 22 25 71 22 20 65 78 63 65 70 74  like "%q" except
1dfc0 20 74 68 61 74 20 69 74 20 65 78 70 65 63 74 73   that it expects
1dfd0 20 74 6f 0a 2a 2a 20 62 65 20 63 6f 6e 74 61 69   to.** be contai
1dfe0 6e 65 64 20 77 69 74 68 69 6e 20 64 6f 75 62 6c  ned within doubl
1dff0 65 2d 71 75 6f 74 65 73 20 69 6e 73 74 65 61 64  e-quotes instead
1e000 20 6f 66 20 73 69 6e 67 6c 65 20 71 75 6f 74 65   of single quote
1e010 73 2c 20 61 6e 64 20 69 74 0a 2a 2a 20 65 73 63  s, and it.** esc
1e020 61 70 65 73 20 74 68 65 20 64 6f 75 62 6c 65 2d  apes the double-
1e030 71 75 6f 74 65 20 63 68 61 72 61 63 74 65 72 20  quote character 
1e040 69 6e 73 74 65 61 64 20 6f 66 20 74 68 65 20 73  instead of the s
1e050 69 6e 67 6c 65 2d 71 75 6f 74 65 0a 2a 2a 20 63  ingle-quote.** c
1e060 68 61 72 61 63 74 65 72 2e 29 5e 20 20 54 68 65  haracter.)^  The
1e070 20 22 25 77 22 20 66 6f 72 6d 61 74 74 69 6e 67   "%w" formatting
1e080 20 6f 70 74 69 6f 6e 20 69 73 20 69 6e 74 65 6e   option is inten
1e090 64 65 64 20 66 6f 72 20 73 61 66 65 6c 79 20 69  ded for safely i
1e0a0 6e 73 65 72 74 69 6e 67 0a 2a 2a 20 74 61 62 6c  nserting.** tabl
1e0b0 65 20 61 6e 64 20 63 6f 6c 75 6d 6e 20 6e 61 6d  e and column nam
1e0c0 65 73 20 69 6e 74 6f 20 61 20 63 6f 6e 73 74 72  es into a constr
1e0d0 75 63 74 65 64 20 53 51 4c 20 73 74 61 74 65 6d  ucted SQL statem
1e0e0 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65  ent..**.** ^(The
1e0f0 20 22 25 7a 22 20 66 6f 72 6d 61 74 74 69 6e 67   "%z" formatting
1e100 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69   option works li
1e110 6b 65 20 22 25 73 22 20 62 75 74 20 77 69 74 68  ke "%s" but with
1e120 20 74 68 65 0a 2a 2a 20 61 64 64 69 74 69 6f 6e   the.** addition
1e130 20 74 68 61 74 20 61 66 74 65 72 20 74 68 65 20   that after the 
1e140 73 74 72 69 6e 67 20 68 61 73 20 62 65 65 6e 20  string has been 
1e150 72 65 61 64 20 61 6e 64 20 63 6f 70 69 65 64 20  read and copied 
1e160 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 72 65 73 75  into.** the resu
1e170 6c 74 2c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  lt, [sqlite3_fre
1e180 65 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 20 6f  e()] is called o
1e190 6e 20 74 68 65 20 69 6e 70 75 74 20 73 74 72 69  n the input stri
1e1a0 6e 67 2e 29 5e 0a 2a 2f 0a 63 68 61 72 20 2a 73  ng.)^.*/.char *s
1e1b0 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 63  qlite3_mprintf(c
1e1c0 6f 6e 73 74 20 63 68 61 72 2a 2c 2e 2e 2e 29 3b  onst char*,...);
1e1d0 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 76  .char *sqlite3_v
1e1e0 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74 20 63 68  mprintf(const ch
1e1f0 61 72 2a 2c 20 76 61 5f 6c 69 73 74 29 3b 0a 63  ar*, va_list);.c
1e200 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 73 6e 70  har *sqlite3_snp
1e210 72 69 6e 74 66 28 69 6e 74 2c 63 68 61 72 2a 2c  rintf(int,char*,
1e220 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 2e 2e 2e  const char*, ...
1e230 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33  );.char *sqlite3
1e240 5f 76 73 6e 70 72 69 6e 74 66 28 69 6e 74 2c 63  _vsnprintf(int,c
1e250 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a  har*,const char*
1e260 2c 20 76 61 5f 6c 69 73 74 29 3b 0a 0a 2f 2a 0a  , va_list);../*.
1e270 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d  ** CAPI3REF: Mem
1e280 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f 6e 20 53  ory Allocation S
1e290 75 62 73 79 73 74 65 6d 0a 2a 2a 0a 2a 2a 20 54  ubsystem.**.** T
1e2a0 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 75  he SQLite core u
1e2b0 73 65 73 20 74 68 65 73 65 20 74 68 72 65 65 20  ses these three 
1e2c0 72 6f 75 74 69 6e 65 73 20 66 6f 72 20 61 6c 6c  routines for all
1e2d0 20 6f 66 20 69 74 73 20 6f 77 6e 0a 2a 2a 20 69   of its own.** i
1e2e0 6e 74 65 72 6e 61 6c 20 6d 65 6d 6f 72 79 20 61  nternal memory a
1e2f0 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e  llocation needs.
1e300 20 22 43 6f 72 65 22 20 69 6e 20 74 68 65 20 70   "Core" in the p
1e310 72 65 76 69 6f 75 73 20 73 65 6e 74 65 6e 63 65  revious sentence
1e320 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63  .** does not inc
1e330 6c 75 64 65 20 6f 70 65 72 61 74 69 6e 67 2d 73  lude operating-s
1e340 79 73 74 65 6d 20 73 70 65 63 69 66 69 63 20 56  ystem specific V
1e350 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  FS implementatio
1e360 6e 2e 20 20 54 68 65 0a 2a 2a 20 57 69 6e 64 6f  n.  The.** Windo
1e370 77 73 20 56 46 53 20 75 73 65 73 20 6e 61 74 69  ws VFS uses nati
1e380 76 65 20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20  ve malloc() and 
1e390 66 72 65 65 28 29 20 66 6f 72 20 73 6f 6d 65 20  free() for some 
1e3a0 6f 70 65 72 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a  operations..**.*
1e3b0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6d  * ^The sqlite3_m
1e3c0 61 6c 6c 6f 63 28 29 20 72 6f 75 74 69 6e 65 20  alloc() routine 
1e3d0 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65  returns a pointe
1e3e0 72 20 74 6f 20 61 20 62 6c 6f 63 6b 0a 2a 2a 20  r to a block.** 
1e3f0 6f 66 20 6d 65 6d 6f 72 79 20 61 74 20 6c 65 61  of memory at lea
1e400 73 74 20 4e 20 62 79 74 65 73 20 69 6e 20 6c 65  st N bytes in le
1e410 6e 67 74 68 2c 20 77 68 65 72 65 20 4e 20 69 73  ngth, where N is
1e420 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e 0a   the parameter..
1e430 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6d  ** ^If sqlite3_m
1e440 61 6c 6c 6f 63 28 29 20 69 73 20 75 6e 61 62 6c  alloc() is unabl
1e450 65 20 74 6f 20 6f 62 74 61 69 6e 20 73 75 66 66  e to obtain suff
1e460 69 63 69 65 6e 74 20 66 72 65 65 0a 2a 2a 20 6d  icient free.** m
1e470 65 6d 6f 72 79 2c 20 69 74 20 72 65 74 75 72 6e  emory, it return
1e480 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
1e490 2e 20 20 5e 49 66 20 74 68 65 20 70 61 72 61 6d  .  ^If the param
1e4a0 65 74 65 72 20 4e 20 74 6f 0a 2a 2a 20 73 71 6c  eter N to.** sql
1e4b0 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 69 73  ite3_malloc() is
1e4c0 20 7a 65 72 6f 20 6f 72 20 6e 65 67 61 74 69 76   zero or negativ
1e4d0 65 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 6d  e then sqlite3_m
1e4e0 61 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e 73 0a  alloc() returns.
1e4f0 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  ** a NULL pointe
1e500 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  r..**.** ^The sq
1e510 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 36 34 28 4e  lite3_malloc64(N
1e520 29 20 72 6f 75 74 69 6e 65 20 77 6f 72 6b 73 20  ) routine works 
1e530 6a 75 73 74 20 6c 69 6b 65 0a 2a 2a 20 73 71 6c  just like.** sql
1e540 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29 20 65  ite3_malloc(N) e
1e550 78 63 65 70 74 20 74 68 61 74 20 4e 20 69 73 20  xcept that N is 
1e560 61 6e 20 75 6e 73 69 67 6e 65 64 20 36 34 2d 62  an unsigned 64-b
1e570 69 74 20 69 6e 74 65 67 65 72 20 69 6e 73 74 65  it integer inste
1e580 61 64 0a 2a 2a 20 6f 66 20 61 20 73 69 67 6e 65  ad.** of a signe
1e590 64 20 33 32 2d 62 69 74 20 69 6e 74 65 67 65 72  d 32-bit integer
1e5a0 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67  ..**.** ^Calling
1e5b0 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20   sqlite3_free() 
1e5c0 77 69 74 68 20 61 20 70 6f 69 6e 74 65 72 20 70  with a pointer p
1e5d0 72 65 76 69 6f 75 73 6c 79 20 72 65 74 75 72 6e  reviously return
1e5e0 65 64 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 33  ed.** by sqlite3
1e5f0 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 20 73 71 6c  _malloc() or sql
1e600 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 72  ite3_realloc() r
1e610 65 6c 65 61 73 65 73 20 74 68 61 74 20 6d 65 6d  eleases that mem
1e620 6f 72 79 20 73 6f 0a 2a 2a 20 74 68 61 74 20 69  ory so.** that i
1e630 74 20 6d 69 67 68 74 20 62 65 20 72 65 75 73 65  t might be reuse
1e640 64 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33  d.  ^The sqlite3
1e650 5f 66 72 65 65 28 29 20 72 6f 75 74 69 6e 65 20  _free() routine 
1e660 69 73 0a 2a 2a 20 61 20 6e 6f 2d 6f 70 20 69 66  is.** a no-op if
1e670 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74 68 20   is called with 
1e680 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20  a NULL pointer. 
1e690 20 50 61 73 73 69 6e 67 20 61 20 4e 55 4c 4c 20   Passing a NULL 
1e6a0 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 73 71  pointer.** to sq
1e6b0 6c 69 74 65 33 5f 66 72 65 65 28 29 20 69 73 20  lite3_free() is 
1e6c0 68 61 72 6d 6c 65 73 73 2e 20 20 41 66 74 65 72  harmless.  After
1e6d0 20 62 65 69 6e 67 20 66 72 65 65 64 2c 20 6d 65   being freed, me
1e6e0 6d 6f 72 79 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e  mory.** should n
1e6f0 65 69 74 68 65 72 20 62 65 20 72 65 61 64 20 6e  either be read n
1e700 6f 72 20 77 72 69 74 74 65 6e 2e 20 20 45 76 65  or written.  Eve
1e710 6e 20 72 65 61 64 69 6e 67 20 70 72 65 76 69 6f  n reading previo
1e720 75 73 6c 79 20 66 72 65 65 64 0a 2a 2a 20 6d 65  usly freed.** me
1e730 6d 6f 72 79 20 6d 69 67 68 74 20 72 65 73 75 6c  mory might resul
1e740 74 20 69 6e 20 61 20 73 65 67 6d 65 6e 74 61 74  t in a segmentat
1e750 69 6f 6e 20 66 61 75 6c 74 20 6f 72 20 6f 74 68  ion fault or oth
1e760 65 72 20 73 65 76 65 72 65 20 65 72 72 6f 72 2e  er severe error.
1e770 0a 2a 2a 20 4d 65 6d 6f 72 79 20 63 6f 72 72 75  .** Memory corru
1e780 70 74 69 6f 6e 2c 20 61 20 73 65 67 6d 65 6e 74  ption, a segment
1e790 61 74 69 6f 6e 20 66 61 75 6c 74 2c 20 6f 72 20  ation fault, or 
1e7a0 6f 74 68 65 72 20 73 65 76 65 72 65 20 65 72 72  other severe err
1e7b0 6f 72 0a 2a 2a 20 6d 69 67 68 74 20 72 65 73 75  or.** might resu
1e7c0 6c 74 20 69 66 20 73 71 6c 69 74 65 33 5f 66 72  lt if sqlite3_fr
1e7d0 65 65 28 29 20 69 73 20 63 61 6c 6c 65 64 20 77  ee() is called w
1e7e0 69 74 68 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70  ith a non-NULL p
1e7f0 6f 69 6e 74 65 72 20 74 68 61 74 0a 2a 2a 20 77  ointer that.** w
1e800 61 73 20 6e 6f 74 20 6f 62 74 61 69 6e 65 64 20  as not obtained 
1e810 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6d 61 6c  from sqlite3_mal
1e820 6c 6f 63 28 29 20 6f 72 20 73 71 6c 69 74 65 33  loc() or sqlite3
1e830 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 0a 2a  _realloc()..**.*
1e840 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72  * ^The sqlite3_r
1e850 65 61 6c 6c 6f 63 28 58 2c 4e 29 20 69 6e 74 65  ealloc(X,N) inte
1e860 72 66 61 63 65 20 61 74 74 65 6d 70 74 73 20 74  rface attempts t
1e870 6f 20 72 65 73 69 7a 65 20 61 0a 2a 2a 20 70 72  o resize a.** pr
1e880 69 6f 72 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ior memory alloc
1e890 61 74 69 6f 6e 20 58 20 74 6f 20 62 65 20 61 74  ation X to be at
1e8a0 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73 2e 0a   least N bytes..
1e8b0 2a 2a 20 5e 49 66 20 74 68 65 20 58 20 70 61 72  ** ^If the X par
1e8c0 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
1e8d0 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 0a 2a  3_realloc(X,N).*
1e8e0 2a 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  * is a NULL poin
1e8f0 74 65 72 20 74 68 65 6e 20 69 74 73 20 62 65 68  ter then its beh
1e900 61 76 69 6f 72 20 69 73 20 69 64 65 6e 74 69 63  avior is identic
1e910 61 6c 20 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a  al to calling.**
1e920 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28   sqlite3_malloc(
1e930 4e 29 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 4e  N)..** ^If the N
1e940 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
1e950 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c  lite3_realloc(X,
1e960 4e 29 20 69 73 20 7a 65 72 6f 20 6f 72 0a 2a 2a  N) is zero or.**
1e970 20 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20 74   negative then t
1e980 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 65  he behavior is e
1e990 78 61 63 74 6c 79 20 74 68 65 20 73 61 6d 65 20  xactly the same 
1e9a0 61 73 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71  as calling.** sq
1e9b0 6c 69 74 65 33 5f 66 72 65 65 28 58 29 2e 0a 2a  lite3_free(X)..*
1e9c0 2a 20 5e 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  * ^sqlite3_reall
1e9d0 6f 63 28 58 2c 4e 29 20 72 65 74 75 72 6e 73 20  oc(X,N) returns 
1e9e0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 6d  a pointer to a m
1e9f0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
1ea00 0a 2a 2a 20 6f 66 20 61 74 20 6c 65 61 73 74 20  .** of at least 
1ea10 4e 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20  N bytes in size 
1ea20 6f 72 20 4e 55 4c 4c 20 69 66 20 69 6e 73 75 66  or NULL if insuf
1ea30 66 69 63 69 65 6e 74 20 6d 65 6d 6f 72 79 20 69  ficient memory i
1ea40 73 20 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20  s available..** 
1ea50 5e 49 66 20 4d 20 69 73 20 74 68 65 20 73 69 7a  ^If M is the siz
1ea60 65 20 6f 66 20 74 68 65 20 70 72 69 6f 72 20 61  e of the prior a
1ea70 6c 6c 6f 63 61 74 69 6f 6e 2c 20 74 68 65 6e 20  llocation, then 
1ea80 6d 69 6e 28 4e 2c 4d 29 20 62 79 74 65 73 0a 2a  min(N,M) bytes.*
1ea90 2a 20 6f 66 20 74 68 65 20 70 72 69 6f 72 20 61  * of the prior a
1eaa0 6c 6c 6f 63 61 74 69 6f 6e 20 61 72 65 20 63 6f  llocation are co
1eab0 70 69 65 64 20 69 6e 74 6f 20 74 68 65 20 62 65  pied into the be
1eac0 67 69 6e 6e 69 6e 67 20 6f 66 20 62 75 66 66 65  ginning of buffe
1ead0 72 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79  r returned.** by
1eae0 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
1eaf0 28 58 2c 4e 29 20 61 6e 64 20 74 68 65 20 70 72  (X,N) and the pr
1eb00 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69  ior allocation i
1eb10 73 20 66 72 65 65 64 2e 0a 2a 2a 20 5e 49 66 20  s freed..** ^If 
1eb20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
1eb30 58 2c 4e 29 20 72 65 74 75 72 6e 73 20 4e 55 4c  X,N) returns NUL
1eb40 4c 20 61 6e 64 20 4e 20 69 73 20 70 6f 73 69 74  L and N is posit
1eb50 69 76 65 2c 20 74 68 65 6e 20 74 68 65 0a 2a 2a  ive, then the.**
1eb60 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f   prior allocatio
1eb70 6e 20 69 73 20 6e 6f 74 20 66 72 65 65 64 2e 0a  n is not freed..
1eb80 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
1eb90 65 33 5f 72 65 61 6c 6c 6f 63 36 34 28 58 2c 4e  e3_realloc64(X,N
1eba0 29 20 69 6e 74 65 72 66 61 63 65 73 20 77 6f 72  ) interfaces wor
1ebb0 6b 73 20 74 68 65 20 73 61 6d 65 20 61 73 0a 2a  ks the same as.*
1ebc0 2a 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  * sqlite3_reallo
1ebd0 63 28 58 2c 4e 29 20 65 78 63 65 70 74 20 74 68  c(X,N) except th
1ebe0 61 74 20 4e 20 69 73 20 61 20 36 34 2d 62 69 74  at N is a 64-bit
1ebf0 20 75 6e 73 69 67 6e 65 64 20 69 6e 74 65 67 65   unsigned intege
1ec00 72 20 69 6e 73 74 65 61 64 0a 2a 2a 20 6f 66 20  r instead.** of 
1ec10 61 20 33 32 2d 62 69 74 20 73 69 67 6e 65 64 20  a 32-bit signed 
1ec20 69 6e 74 65 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e  integer..**.** ^
1ec30 49 66 20 58 20 69 73 20 61 20 6d 65 6d 6f 72 79  If X is a memory
1ec40 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 70 72 65 76   allocation prev
1ec50 69 6f 75 73 6c 79 20 6f 62 74 61 69 6e 65 64 20  iously obtained 
1ec60 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6d 61 6c  from sqlite3_mal
1ec70 6c 6f 63 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65  loc(),.** sqlite
1ec80 33 5f 6d 61 6c 6c 6f 63 36 34 28 29 2c 20 73 71  3_malloc64(), sq
1ec90 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2c  lite3_realloc(),
1eca0 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 61 6c   or sqlite3_real
1ecb0 6c 6f 63 36 34 28 29 2c 20 74 68 65 6e 0a 2a 2a  loc64(), then.**
1ecc0 20 73 71 6c 69 74 65 33 5f 6d 73 69 7a 65 28 58   sqlite3_msize(X
1ecd0 29 20 72 65 74 75 72 6e 73 20 74 68 65 20 73 69  ) returns the si
1ece0 7a 65 20 6f 66 20 74 68 61 74 20 6d 65 6d 6f 72  ze of that memor
1ecf0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 6e 20  y allocation in 
1ed00 62 79 74 65 73 2e 0a 2a 2a 20 5e 54 68 65 20 76  bytes..** ^The v
1ed10 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79  alue returned by
1ed20 20 73 71 6c 69 74 65 33 5f 6d 73 69 7a 65 28 58   sqlite3_msize(X
1ed30 29 20 6d 69 67 68 74 20 62 65 20 6c 61 72 67 65  ) might be large
1ed40 72 20 74 68 61 6e 20 74 68 65 20 6e 75 6d 62 65  r than the numbe
1ed50 72 0a 2a 2a 20 6f 66 20 62 79 74 65 73 20 72 65  r.** of bytes re
1ed60 71 75 65 73 74 65 64 20 77 68 65 6e 20 58 20 77  quested when X w
1ed70 61 73 20 61 6c 6c 6f 63 61 74 65 64 2e 20 20 5e  as allocated.  ^
1ed80 49 66 20 58 20 69 73 20 61 20 4e 55 4c 4c 20 70  If X is a NULL p
1ed90 6f 69 6e 74 65 72 20 74 68 65 6e 0a 2a 2a 20 73  ointer then.** s
1eda0 71 6c 69 74 65 33 5f 6d 73 69 7a 65 28 58 29 20  qlite3_msize(X) 
1edb0 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e 20 20 49  returns zero.  I
1edc0 66 20 58 20 70 6f 69 6e 74 73 20 74 6f 20 73 6f  f X points to so
1edd0 6d 65 74 68 69 6e 67 20 74 68 61 74 20 69 73 20  mething that is 
1ede0 6e 6f 74 0a 2a 2a 20 74 68 65 20 62 65 67 69 6e  not.** the begin
1edf0 6e 69 6e 67 20 6f 66 20 6d 65 6d 6f 72 79 20 61  ning of memory a
1ee00 6c 6c 6f 63 61 74 69 6f 6e 2c 20 6f 72 20 69 66  llocation, or if
1ee10 20 69 74 20 70 6f 69 6e 74 73 20 74 6f 20 61 20   it points to a 
1ee20 66 6f 72 6d 65 72 6c 79 0a 2a 2a 20 76 61 6c 69  formerly.** vali
1ee30 64 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  d memory allocat
1ee40 69 6f 6e 20 74 68 61 74 20 68 61 73 20 6e 6f 77  ion that has now
1ee50 20 62 65 65 6e 20 66 72 65 65 64 2c 20 74 68 65   been freed, the
1ee60 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 0a 2a  n the behavior.*
1ee70 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f 6d 73 69  * of sqlite3_msi
1ee80 7a 65 28 58 29 20 69 73 20 75 6e 64 65 66 69 6e  ze(X) is undefin
1ee90 65 64 20 61 6e 64 20 70 6f 73 73 69 62 6c 79 20  ed and possibly 
1eea0 68 61 72 6d 66 75 6c 2e 0a 2a 2a 0a 2a 2a 20 5e  harmful..**.** ^
1eeb0 54 68 65 20 6d 65 6d 6f 72 79 20 72 65 74 75 72  The memory retur
1eec0 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 6d  ned by sqlite3_m
1eed0 61 6c 6c 6f 63 28 29 2c 20 73 71 6c 69 74 65 33  alloc(), sqlite3
1eee0 5f 72 65 61 6c 6c 6f 63 28 29 2c 0a 2a 2a 20 73  _realloc(),.** s
1eef0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 36 34 28  qlite3_malloc64(
1ef00 29 2c 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72  ), and sqlite3_r
1ef10 65 61 6c 6c 6f 63 36 34 28 29 0a 2a 2a 20 69 73  ealloc64().** is
1ef20 20 61 6c 77 61 79 73 20 61 6c 69 67 6e 65 64 20   always aligned 
1ef30 74 6f 20 61 74 20 6c 65 61 73 74 20 61 6e 20 38  to at least an 8
1ef40 20 62 79 74 65 20 62 6f 75 6e 64 61 72 79 2c 20   byte boundary, 
1ef50 6f 72 20 74 6f 20 61 0a 2a 2a 20 34 20 62 79 74  or to a.** 4 byt
1ef60 65 20 62 6f 75 6e 64 61 72 79 20 69 66 20 74 68  e boundary if th
1ef70 65 20 5b 53 51 4c 49 54 45 5f 34 5f 42 59 54 45  e [SQLITE_4_BYTE
1ef80 5f 41 4c 49 47 4e 45 44 5f 4d 41 4c 4c 4f 43 5d  _ALIGNED_MALLOC]
1ef90 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a   compile-time.**
1efa0 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64 2e   option is used.
1efb0 0a 2a 2a 0a 2a 2a 20 49 6e 20 53 51 4c 69 74 65  .**.** In SQLite
1efc0 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30 20 61   version 3.5.0 a
1efd0 6e 64 20 33 2e 35 2e 31 2c 20 69 74 20 77 61 73  nd 3.5.1, it was
1efe0 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 64 65 66   possible to def
1eff0 69 6e 65 0a 2a 2a 20 74 68 65 20 53 51 4c 49 54  ine.** the SQLIT
1f000 45 5f 4f 4d 49 54 5f 4d 45 4d 4f 52 59 5f 41 4c  E_OMIT_MEMORY_AL
1f010 4c 4f 43 41 54 49 4f 4e 20 77 68 69 63 68 20 77  LOCATION which w
1f020 6f 75 6c 64 20 63 61 75 73 65 20 74 68 65 20 62  ould cause the b
1f030 75 69 6c 74 2d 69 6e 0a 2a 2a 20 69 6d 70 6c 65  uilt-in.** imple
1f040 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65  mentation of the
1f050 73 65 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 62  se routines to b
1f060 65 20 6f 6d 69 74 74 65 64 2e 20 20 54 68 61 74  e omitted.  That
1f070 20 63 61 70 61 62 69 6c 69 74 79 0a 2a 2a 20 69   capability.** i
1f080 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 70 72 6f 76  s no longer prov
1f090 69 64 65 64 2e 20 20 4f 6e 6c 79 20 62 75 69 6c  ided.  Only buil
1f0a0 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  t-in memory allo
1f0b0 63 61 74 6f 72 73 20 63 61 6e 20 62 65 20 75 73  cators can be us
1f0c0 65 64 2e 0a 2a 2a 0a 2a 2a 20 50 72 69 6f 72 20  ed..**.** Prior 
1f0d0 74 6f 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f  to SQLite versio
1f0e0 6e 20 33 2e 37 2e 31 30 2c 20 74 68 65 20 57 69  n 3.7.10, the Wi
1f0f0 6e 64 6f 77 73 20 4f 53 20 69 6e 74 65 72 66 61  ndows OS interfa
1f100 63 65 20 6c 61 79 65 72 20 63 61 6c 6c 65 64 0a  ce layer called.
1f110 2a 2a 20 74 68 65 20 73 79 73 74 65 6d 20 6d 61  ** the system ma
1f120 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 65 65 28  lloc() and free(
1f130 29 20 64 69 72 65 63 74 6c 79 20 77 68 65 6e 20  ) directly when 
1f140 63 6f 6e 76 65 72 74 69 6e 67 0a 2a 2a 20 66 69  converting.** fi
1f150 6c 65 6e 61 6d 65 73 20 62 65 74 77 65 65 6e 20  lenames between 
1f160 74 68 65 20 55 54 46 2d 38 20 65 6e 63 6f 64 69  the UTF-8 encodi
1f170 6e 67 20 75 73 65 64 20 62 79 20 53 51 4c 69 74  ng used by SQLit
1f180 65 0a 2a 2a 20 61 6e 64 20 77 68 61 74 65 76 65  e.** and whateve
1f190 72 20 66 69 6c 65 6e 61 6d 65 20 65 6e 63 6f 64  r filename encod
1f1a0 69 6e 67 20 69 73 20 75 73 65 64 20 62 79 20 74  ing is used by t
1f1b0 68 65 20 70 61 72 74 69 63 75 6c 61 72 20 57 69  he particular Wi
1f1c0 6e 64 6f 77 73 0a 2a 2a 20 69 6e 73 74 61 6c 6c  ndows.** install
1f1d0 61 74 69 6f 6e 2e 20 20 4d 65 6d 6f 72 79 20 61  ation.  Memory a
1f1e0 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 73  llocation errors
1f1f0 20 77 65 72 65 20 64 65 74 65 63 74 65 64 2c 20   were detected, 
1f200 62 75 74 0a 2a 2a 20 74 68 65 79 20 77 65 72 65  but.** they were
1f210 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b 20 61   reported back a
1f220 73 20 5b 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50  s [SQLITE_CANTOP
1f230 45 4e 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54  EN] or.** [SQLIT
1f240 45 5f 49 4f 45 52 52 5d 20 72 61 74 68 65 72 20  E_IOERR] rather 
1f250 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d  than [SQLITE_NOM
1f260 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70  EM]..**.** The p
1f270 6f 69 6e 74 65 72 20 61 72 67 75 6d 65 6e 74 73  ointer arguments
1f280 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72 65   to [sqlite3_fre
1f290 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  e()] and [sqlite
1f2a0 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20  3_realloc()].** 
1f2b0 6d 75 73 74 20 62 65 20 65 69 74 68 65 72 20 4e  must be either N
1f2c0 55 4c 4c 20 6f 72 20 65 6c 73 65 20 70 6f 69 6e  ULL or else poin
1f2d0 74 65 72 73 20 6f 62 74 61 69 6e 65 64 20 66 72  ters obtained fr
1f2e0 6f 6d 20 61 20 70 72 69 6f 72 0a 2a 2a 20 69 6e  om a prior.** in
1f2f0 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c  vocation of [sql
1f300 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6f  ite3_malloc()] o
1f310 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  r [sqlite3_reall
1f320 6f 63 28 29 5d 20 74 68 61 74 20 68 61 76 65 0a  oc()] that have.
1f330 2a 2a 20 6e 6f 74 20 79 65 74 20 62 65 65 6e 20  ** not yet been 
1f340 72 65 6c 65 61 73 65 64 2e 0a 2a 2a 0a 2a 2a 20  released..**.** 
1f350 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  The application 
1f360 6d 75 73 74 20 6e 6f 74 20 72 65 61 64 20 6f 72  must not read or
1f370 20 77 72 69 74 65 20 61 6e 79 20 70 61 72 74 20   write any part 
1f380 6f 66 0a 2a 2a 20 61 20 62 6c 6f 63 6b 20 6f 66  of.** a block of
1f390 20 6d 65 6d 6f 72 79 20 61 66 74 65 72 20 69 74   memory after it
1f3a0 20 68 61 73 20 62 65 65 6e 20 72 65 6c 65 61 73   has been releas
1f3b0 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c  ed using.** [sql
1f3c0 69 74 65 33 5f 66 72 65 65 28 29 5d 20 6f 72 20  ite3_free()] or 
1f3d0 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63  [sqlite3_realloc
1f3e0 28 29 5d 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71  ()]..*/.void *sq
1f3f0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 69 6e 74  lite3_malloc(int
1f400 29 3b 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  );.void *sqlite3
1f410 5f 6d 61 6c 6c 6f 63 36 34 28 73 71 6c 69 74 65  _malloc64(sqlite
1f420 33 5f 75 69 6e 74 36 34 29 3b 0a 76 6f 69 64 20  3_uint64);.void 
1f430 2a 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63  *sqlite3_realloc
1f440 28 76 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a 76 6f  (void*, int);.vo
1f450 69 64 20 2a 73 71 6c 69 74 65 33 5f 72 65 61 6c  id *sqlite3_real
1f460 6c 6f 63 36 34 28 76 6f 69 64 2a 2c 20 73 71 6c  loc64(void*, sql
1f470 69 74 65 33 5f 75 69 6e 74 36 34 29 3b 0a 76 6f  ite3_uint64);.vo
1f480 69 64 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28  id sqlite3_free(
1f490 76 6f 69 64 2a 29 3b 0a 73 71 6c 69 74 65 33 5f  void*);.sqlite3_
1f4a0 75 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6d  uint64 sqlite3_m
1f4b0 73 69 7a 65 28 76 6f 69 64 2a 29 3b 0a 0a 2f 2a  size(void*);../*
1f4c0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65  .** CAPI3REF: Me
1f4d0 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 6f 72 20 53  mory Allocator S
1f4e0 74 61 74 69 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20  tatistics.**.** 
1f4f0 53 51 4c 69 74 65 20 70 72 6f 76 69 64 65 73 20  SQLite provides 
1f500 74 68 65 73 65 20 74 77 6f 20 69 6e 74 65 72 66  these two interf
1f510 61 63 65 73 20 66 6f 72 20 72 65 70 6f 72 74 69  aces for reporti
1f520 6e 67 20 6f 6e 20 74 68 65 20 73 74 61 74 75 73  ng on the status
1f530 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  .** of the [sqli
1f540 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 20 5b  te3_malloc()], [
1f550 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2c  sqlite3_free()],
1f560 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65   and [sqlite3_re
1f570 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 72 6f 75 74  alloc()].** rout
1f580 69 6e 65 73 2c 20 77 68 69 63 68 20 66 6f 72 6d  ines, which form
1f590 20 74 68 65 20 62 75 69 6c 74 2d 69 6e 20 6d 65   the built-in me
1f5a0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
1f5b0 73 75 62 73 79 73 74 65 6d 2e 0a 2a 2a 0a 2a 2a  subsystem..**.**
1f5c0 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d   ^The [sqlite3_m
1f5d0 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 72 6f  emory_used()] ro
1f5e0 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68  utine returns th
1f5f0 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  e number of byte
1f600 73 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79 20 63  s.** of memory c
1f610 75 72 72 65 6e 74 6c 79 20 6f 75 74 73 74 61 6e  urrently outstan
1f620 64 69 6e 67 20 28 6d 61 6c 6c 6f 63 65 64 20 62  ding (malloced b
1f630 75 74 20 6e 6f 74 20 66 72 65 65 64 29 2e 0a 2a  ut not freed)..*
1f640 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  * ^The [sqlite3_
1f650 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72  memory_highwater
1f660 28 29 5d 20 72 6f 75 74 69 6e 65 20 72 65 74 75  ()] routine retu
1f670 72 6e 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 0a  rns the maximum.
1f680 2a 2a 20 76 61 6c 75 65 20 6f 66 20 5b 73 71 6c  ** value of [sql
1f690 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64  ite3_memory_used
1f6a0 28 29 5d 20 73 69 6e 63 65 20 74 68 65 20 68 69  ()] since the hi
1f6b0 67 68 2d 77 61 74 65 72 20 6d 61 72 6b 0a 2a 2a  gh-water mark.**
1f6c0 20 77 61 73 20 6c 61 73 74 20 72 65 73 65 74 2e   was last reset.
1f6d0 20 20 5e 54 68 65 20 76 61 6c 75 65 73 20 72 65    ^The values re
1f6e0 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74  turned by [sqlit
1f6f0 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29  e3_memory_used()
1f700 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  ] and.** [sqlite
1f710 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74  3_memory_highwat
1f720 65 72 28 29 5d 20 69 6e 63 6c 75 64 65 20 61 6e  er()] include an
1f730 79 20 6f 76 65 72 68 65 61 64 0a 2a 2a 20 61 64  y overhead.** ad
1f740 64 65 64 20 62 79 20 53 51 4c 69 74 65 20 69 6e  ded by SQLite in
1f750 20 69 74 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74   its implementat
1f760 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f  ion of [sqlite3_
1f770 6d 61 6c 6c 6f 63 28 29 5d 2c 0a 2a 2a 20 62 75  malloc()],.** bu
1f780 74 20 6e 6f 74 20 6f 76 65 72 68 65 61 64 20 61  t not overhead a
1f790 64 64 65 64 20 62 79 20 74 68 65 20 61 6e 79 20  dded by the any 
1f7a0 75 6e 64 65 72 6c 79 69 6e 67 20 73 79 73 74 65  underlying syste
1f7b0 6d 20 6c 69 62 72 61 72 79 0a 2a 2a 20 72 6f 75  m library.** rou
1f7c0 74 69 6e 65 73 20 74 68 61 74 20 5b 73 71 6c 69  tines that [sqli
1f7d0 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6d 61  te3_malloc()] ma
1f7e0 79 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 54  y call..**.** ^T
1f7f0 68 65 20 6d 65 6d 6f 72 79 20 68 69 67 68 2d 77  he memory high-w
1f800 61 74 65 72 20 6d 61 72 6b 20 69 73 20 72 65 73  ater mark is res
1f810 65 74 20 74 6f 20 74 68 65 20 63 75 72 72 65 6e  et to the curren
1f820 74 20 76 61 6c 75 65 20 6f 66 0a 2a 2a 20 5b 73  t value of.** [s
1f830 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73  qlite3_memory_us
1f840 65 64 28 29 5d 20 69 66 20 61 6e 64 20 6f 6e 6c  ed()] if and onl
1f850 79 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74  y if the paramet
1f860 65 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  er to.** [sqlite
1f870 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74  3_memory_highwat
1f880 65 72 28 29 5d 20 69 73 20 74 72 75 65 2e 20 20  er()] is true.  
1f890 5e 54 68 65 20 76 61 6c 75 65 20 72 65 74 75 72  ^The value retur
1f8a0 6e 65 64 0a 2a 2a 20 62 79 20 5b 73 71 6c 69 74  ned.** by [sqlit
1f8b0 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61  e3_memory_highwa
1f8c0 74 65 72 28 31 29 5d 20 69 73 20 74 68 65 20 68  ter(1)] is the h
1f8d0 69 67 68 2d 77 61 74 65 72 20 6d 61 72 6b 0a 2a  igh-water mark.*
1f8e0 2a 20 70 72 69 6f 72 20 74 6f 20 74 68 65 20 72  * prior to the r
1f8f0 65 73 65 74 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33  eset..*/.sqlite3
1f900 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6d  _int64 sqlite3_m
1f910 65 6d 6f 72 79 5f 75 73 65 64 28 76 6f 69 64 29  emory_used(void)
1f920 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  ;.sqlite3_int64 
1f930 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68  sqlite3_memory_h
1f940 69 67 68 77 61 74 65 72 28 69 6e 74 20 72 65 73  ighwater(int res
1f950 65 74 46 6c 61 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20  etFlag);../*.** 
1f960 43 41 50 49 33 52 45 46 3a 20 50 73 65 75 64 6f  CAPI3REF: Pseudo
1f970 2d 52 61 6e 64 6f 6d 20 4e 75 6d 62 65 72 20 47  -Random Number G
1f980 65 6e 65 72 61 74 6f 72 0a 2a 2a 0a 2a 2a 20 53  enerator.**.** S
1f990 51 4c 69 74 65 20 63 6f 6e 74 61 69 6e 73 20 61  QLite contains a
1f9a0 20 68 69 67 68 2d 71 75 61 6c 69 74 79 20 70 73   high-quality ps
1f9b0 65 75 64 6f 2d 72 61 6e 64 6f 6d 20 6e 75 6d 62  eudo-random numb
1f9c0 65 72 20 67 65 6e 65 72 61 74 6f 72 20 28 50 52  er generator (PR
1f9d0 4e 47 29 20 75 73 65 64 20 74 6f 0a 2a 2a 20 73  NG) used to.** s
1f9e0 65 6c 65 63 74 20 72 61 6e 64 6f 6d 20 5b 52 4f  elect random [RO
1f9f0 57 49 44 20 7c 20 52 4f 57 49 44 73 5d 20 77 68  WID | ROWIDs] wh
1fa00 65 6e 20 69 6e 73 65 72 74 69 6e 67 20 6e 65 77  en inserting new
1fa10 20 72 65 63 6f 72 64 73 20 69 6e 74 6f 20 61 20   records into a 
1fa20 74 61 62 6c 65 20 74 68 61 74 0a 2a 2a 20 61 6c  table that.** al
1fa30 72 65 61 64 79 20 75 73 65 73 20 74 68 65 20 6c  ready uses the l
1fa40 61 72 67 65 73 74 20 70 6f 73 73 69 62 6c 65 20  argest possible 
1fa50 5b 52 4f 57 49 44 5d 2e 20 20 54 68 65 20 50 52  [ROWID].  The PR
1fa60 4e 47 20 69 73 20 61 6c 73 6f 20 75 73 65 64 20  NG is also used 
1fa70 66 6f 72 0a 2a 2a 20 74 68 65 20 62 75 69 6c 64  for.** the build
1fa80 2d 69 6e 20 72 61 6e 64 6f 6d 28 29 20 61 6e 64  -in random() and
1fa90 20 72 61 6e 64 6f 6d 62 6c 6f 62 28 29 20 53 51   randomblob() SQ
1faa0 4c 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 54 68  L functions.  Th
1fab0 69 73 20 69 6e 74 65 72 66 61 63 65 20 61 6c 6c  is interface all
1fac0 6f 77 73 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69  ows.** applicati
1fad0 6f 6e 73 20 74 6f 20 61 63 63 65 73 73 20 74 68  ons to access th
1fae0 65 20 73 61 6d 65 20 50 52 4e 47 20 66 6f 72 20  e same PRNG for 
1faf0 6f 74 68 65 72 20 70 75 72 70 6f 73 65 73 2e 0a  other purposes..
1fb00 2a 2a 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 6f  **.** ^A call to
1fb10 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 73 74   this routine st
1fb20 6f 72 65 73 20 4e 20 62 79 74 65 73 20 6f 66 20  ores N bytes of 
1fb30 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f 20  randomness into 
1fb40 62 75 66 66 65 72 20 50 2e 0a 2a 2a 20 5e 54 68  buffer P..** ^Th
1fb50 65 20 50 20 70 61 72 61 6d 65 74 65 72 20 63 61  e P parameter ca
1fb60 6e 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  n be a NULL poin
1fb70 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  ter..**.** ^If t
1fb80 68 69 73 20 72 6f 75 74 69 6e 65 20 68 61 73 20  his routine has 
1fb90 6e 6f 74 20 62 65 65 6e 20 70 72 65 76 69 6f 75  not been previou
1fba0 73 6c 79 20 63 61 6c 6c 65 64 20 6f 72 20 69 66  sly called or if
1fbb0 20 74 68 65 20 70 72 65 76 69 6f 75 73 0a 2a 2a   the previous.**
1fbc0 20 63 61 6c 6c 20 68 61 64 20 4e 20 6c 65 73 73   call had N less
1fbd0 20 74 68 61 6e 20 6f 6e 65 20 6f 72 20 61 20 4e   than one or a N
1fbe0 55 4c 4c 20 70 6f 69 6e 74 65 72 20 66 6f 72 20  ULL pointer for 
1fbf0 50 2c 20 74 68 65 6e 20 74 68 65 20 50 52 4e 47  P, then the PRNG
1fc00 20 69 73 0a 2a 2a 20 73 65 65 64 65 64 20 75 73   is.** seeded us
1fc10 69 6e 67 20 72 61 6e 64 6f 6d 6e 65 73 73 20 6f  ing randomness o
1fc20 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 74 68 65  btained from the
1fc30 20 78 52 61 6e 64 6f 6d 6e 65 73 73 20 6d 65 74   xRandomness met
1fc40 68 6f 64 20 6f 66 0a 2a 2a 20 74 68 65 20 64 65  hod of.** the de
1fc50 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76  fault [sqlite3_v
1fc60 66 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 5e  fs] object..** ^
1fc70 49 66 20 74 68 65 20 70 72 65 76 69 6f 75 73 20  If the previous 
1fc80 63 61 6c 6c 20 74 6f 20 74 68 69 73 20 72 6f 75  call to this rou
1fc90 74 69 6e 65 20 68 61 64 20 61 6e 20 4e 20 6f 66  tine had an N of
1fca0 20 31 20 6f 72 20 6d 6f 72 65 20 61 6e 64 20 61   1 or more and a
1fcb0 0a 2a 2a 20 6e 6f 6e 2d 4e 55 4c 4c 20 50 20 74  .** non-NULL P t
1fcc0 68 65 6e 20 74 68 65 20 70 73 65 75 64 6f 2d 72  hen the pseudo-r
1fcd0 61 6e 64 6f 6d 6e 65 73 73 20 69 73 20 67 65 6e  andomness is gen
1fce0 65 72 61 74 65 64 0a 2a 2a 20 69 6e 74 65 72 6e  erated.** intern
1fcf0 61 6c 6c 79 20 61 6e 64 20 77 69 74 68 6f 75 74  ally and without
1fd00 20 72 65 63 6f 75 72 73 65 20 74 6f 20 74 68 65   recourse to the
1fd10 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 78   [sqlite3_vfs] x
1fd20 52 61 6e 64 6f 6d 6e 65 73 73 0a 2a 2a 20 6d 65  Randomness.** me
1fd30 74 68 6f 64 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71  thod..*/.void sq
1fd40 6c 69 74 65 33 5f 72 61 6e 64 6f 6d 6e 65 73 73  lite3_randomness
1fd50 28 69 6e 74 20 4e 2c 20 76 6f 69 64 20 2a 50 29  (int N, void *P)
1fd60 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
1fd70 46 3a 20 43 6f 6d 70 69 6c 65 2d 54 69 6d 65 20  F: Compile-Time 
1fd80 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 43 61  Authorization Ca
1fd90 6c 6c 62 61 63 6b 73 0a 2a 2a 20 4d 45 54 48 4f  llbacks.** METHO
1fda0 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a  D: sqlite3.**.**
1fdb0 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72   ^This routine r
1fdc0 65 67 69 73 74 65 72 73 20 61 6e 20 61 75 74 68  egisters an auth
1fdd0 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
1fde0 77 69 74 68 20 61 20 70 61 72 74 69 63 75 6c 61  with a particula
1fdf0 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63  r.** [database c
1fe00 6f 6e 6e 65 63 74 69 6f 6e 5d 2c 20 73 75 70 70  onnection], supp
1fe10 6c 69 65 64 20 69 6e 20 74 68 65 20 66 69 72 73  lied in the firs
1fe20 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e  t argument..** ^
1fe30 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  The authorizer c
1fe40 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b  allback is invok
1fe50 65 64 20 61 73 20 53 51 4c 20 73 74 61 74 65 6d  ed as SQL statem
1fe60 65 6e 74 73 20 61 72 65 20 62 65 69 6e 67 20 63  ents are being c
1fe70 6f 6d 70 69 6c 65 64 0a 2a 2a 20 62 79 20 5b 73  ompiled.** by [s
1fe80 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29  qlite3_prepare()
1fe90 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74  ] or its variant
1fea0 73 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  s [sqlite3_prepa
1feb0 72 65 5f 76 32 28 29 5d 2c 0a 2a 2a 20 5b 73 71  re_v2()],.** [sq
1fec0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28  lite3_prepare16(
1fed0 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
1fee0 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e  prepare16_v2()].
1fef0 20 20 5e 41 74 20 76 61 72 69 6f 75 73 0a 2a 2a    ^At various.**
1ff00 20 70 6f 69 6e 74 73 20 64 75 72 69 6e 67 20 74   points during t
1ff10 68 65 20 63 6f 6d 70 69 6c 61 74 69 6f 6e 20 70  he compilation p
1ff20 72 6f 63 65 73 73 2c 20 61 73 20 6c 6f 67 69 63  rocess, as logic
1ff30 20 69 73 20 62 65 69 6e 67 20 63 72 65 61 74 65   is being create
1ff40 64 0a 2a 2a 20 74 6f 20 70 65 72 66 6f 72 6d 20  d.** to perform 
1ff50 76 61 72 69 6f 75 73 20 61 63 74 69 6f 6e 73 2c  various actions,
1ff60 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   the authorizer 
1ff70 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f  callback is invo
1ff80 6b 65 64 20 74 6f 0a 2a 2a 20 73 65 65 20 69 66  ked to.** see if
1ff90 20 74 68 6f 73 65 20 61 63 74 69 6f 6e 73 20 61   those actions a
1ffa0 72 65 20 61 6c 6c 6f 77 65 64 2e 20 20 5e 54 68  re allowed.  ^Th
1ffb0 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
1ffc0 6c 62 61 63 6b 20 73 68 6f 75 6c 64 0a 2a 2a 20  lback should.** 
1ffd0 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f  return [SQLITE_O
1ffe0 4b 5d 20 74 6f 20 61 6c 6c 6f 77 20 74 68 65 20  K] to allow the 
1fff0 61 63 74 69 6f 6e 2c 20 5b 53 51 4c 49 54 45 5f  action, [SQLITE_
20000 49 47 4e 4f 52 45 5d 20 74 6f 20 64 69 73 61 6c  IGNORE] to disal
20010 6c 6f 77 20 74 68 65 0a 2a 2a 20 73 70 65 63 69  low the.** speci
20020 66 69 63 20 61 63 74 69 6f 6e 20 62 75 74 20 61  fic action but a
20030 6c 6c 6f 77 20 74 68 65 20 53 51 4c 20 73 74 61  llow the SQL sta
20040 74 65 6d 65 6e 74 20 74 6f 20 63 6f 6e 74 69 6e  tement to contin
20050 75 65 20 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70  ue to be.** comp
20060 69 6c 65 64 2c 20 6f 72 20 5b 53 51 4c 49 54 45  iled, or [SQLITE
20070 5f 44 45 4e 59 5d 20 74 6f 20 63 61 75 73 65 20  _DENY] to cause 
20080 74 68 65 20 65 6e 74 69 72 65 20 53 51 4c 20 73  the entire SQL s
20090 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 0a 2a  tatement to be.*
200a0 2a 20 72 65 6a 65 63 74 65 64 20 77 69 74 68 20  * rejected with 
200b0 61 6e 20 65 72 72 6f 72 2e 20 20 5e 49 66 20 74  an error.  ^If t
200c0 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
200d0 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 0a 2a  llback returns.*
200e0 2a 20 61 6e 79 20 76 61 6c 75 65 20 6f 74 68 65  * any value othe
200f0 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 49  r than [SQLITE_I
20100 47 4e 4f 52 45 5d 2c 20 5b 53 51 4c 49 54 45 5f  GNORE], [SQLITE_
20110 4f 4b 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f  OK], or [SQLITE_
20120 44 45 4e 59 5d 0a 2a 2a 20 74 68 65 6e 20 74 68  DENY].** then th
20130 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  e [sqlite3_prepa
20140 72 65 5f 76 32 28 29 5d 20 6f 72 20 65 71 75 69  re_v2()] or equi
20150 76 61 6c 65 6e 74 20 63 61 6c 6c 20 74 68 61 74  valent call that
20160 20 74 72 69 67 67 65 72 65 64 0a 2a 2a 20 74 68   triggered.** th
20170 65 20 61 75 74 68 6f 72 69 7a 65 72 20 77 69 6c  e authorizer wil
20180 6c 20 66 61 69 6c 20 77 69 74 68 20 61 6e 20 65  l fail with an e
20190 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a  rror message..**
201a0 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 63 61 6c  .** When the cal
201b0 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53  lback returns [S
201c0 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74 68 61 74 20  QLITE_OK], that 
201d0 6d 65 61 6e 73 20 74 68 65 20 6f 70 65 72 61 74  means the operat
201e0 69 6f 6e 0a 2a 2a 20 72 65 71 75 65 73 74 65 64  ion.** requested
201f0 20 69 73 20 6f 6b 2e 20 20 5e 57 68 65 6e 20 74   is ok.  ^When t
20200 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  he callback retu
20210 72 6e 73 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59  rns [SQLITE_DENY
20220 5d 2c 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  ], the.** [sqlit
20230 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
20240 20 6f 72 20 65 71 75 69 76 61 6c 65 6e 74 20 63   or equivalent c
20250 61 6c 6c 20 74 68 61 74 20 74 72 69 67 67 65 72  all that trigger
20260 65 64 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f 72  ed the.** author
20270 69 7a 65 72 20 77 69 6c 6c 20 66 61 69 6c 20 77  izer will fail w
20280 69 74 68 20 61 6e 20 65 72 72 6f 72 20 6d 65 73  ith an error mes
20290 73 61 67 65 20 65 78 70 6c 61 69 6e 69 6e 67 20  sage explaining 
202a0 74 68 61 74 0a 2a 2a 20 61 63 63 65 73 73 20 69  that.** access i
202b0 73 20 64 65 6e 69 65 64 2e 20 0a 2a 2a 0a 2a 2a  s denied. .**.**
202c0 20 5e 54 68 65 20 66 69 72 73 74 20 70 61 72 61   ^The first para
202d0 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61 75 74  meter to the aut
202e0 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
202f0 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68   is a copy of th
20300 65 20 74 68 69 72 64 0a 2a 2a 20 70 61 72 61 6d  e third.** param
20310 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69  eter to the sqli
20320 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a  te3_set_authoriz
20330 65 72 28 29 20 69 6e 74 65 72 66 61 63 65 2e 20  er() interface. 
20340 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61  ^The second para
20350 6d 65 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20  meter.** to the 
20360 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 69  callback is an i
20370 6e 74 65 67 65 72 20 5b 53 51 4c 49 54 45 5f 43  nteger [SQLITE_C
20380 4f 50 59 20 7c 20 61 63 74 69 6f 6e 20 63 6f 64  OPY | action cod
20390 65 5d 20 74 68 61 74 20 73 70 65 63 69 66 69 65  e] that specifie
203a0 73 0a 2a 2a 20 74 68 65 20 70 61 72 74 69 63 75  s.** the particu
203b0 6c 61 72 20 61 63 74 69 6f 6e 20 74 6f 20 62 65  lar action to be
203c0 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 5e 54 68   authorized. ^Th
203d0 65 20 74 68 69 72 64 20 74 68 72 6f 75 67 68 20  e third through 
203e0 73 69 78 74 68 20 70 61 72 61 6d 65 74 65 72 73  sixth parameters
203f0 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c 62  .** to the callb
20400 61 63 6b 20 61 72 65 20 7a 65 72 6f 2d 74 65 72  ack are zero-ter
20410 6d 69 6e 61 74 65 64 20 73 74 72 69 6e 67 73 20  minated strings 
20420 74 68 61 74 20 63 6f 6e 74 61 69 6e 20 61 64 64  that contain add
20430 69 74 69 6f 6e 61 6c 0a 2a 2a 20 64 65 74 61 69  itional.** detai
20440 6c 73 20 61 62 6f 75 74 20 74 68 65 20 61 63 74  ls about the act
20450 69 6f 6e 20 74 6f 20 62 65 20 61 75 74 68 6f 72  ion to be author
20460 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  ized..**.** ^If 
20470 74 68 65 20 61 63 74 69 6f 6e 20 63 6f 64 65 20  the action code 
20480 69 73 20 5b 53 51 4c 49 54 45 5f 52 45 41 44 5d  is [SQLITE_READ]
20490 0a 2a 2a 20 61 6e 64 20 74 68 65 20 63 61 6c 6c  .** and the call
204a0 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51  back returns [SQ
204b0 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 68 65  LITE_IGNORE] the
204c0 6e 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72  n the.** [prepar
204d0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 73 74  ed statement] st
204e0 61 74 65 6d 65 6e 74 20 69 73 20 63 6f 6e 73 74  atement is const
204f0 72 75 63 74 65 64 20 74 6f 20 73 75 62 73 74 69  ructed to substi
20500 74 75 74 65 0a 2a 2a 20 61 20 4e 55 4c 4c 20 76  tute.** a NULL v
20510 61 6c 75 65 20 69 6e 20 70 6c 61 63 65 20 6f 66  alue in place of
20520 20 74 68 65 20 74 61 62 6c 65 20 63 6f 6c 75 6d   the table colum
20530 6e 20 74 68 61 74 20 77 6f 75 6c 64 20 68 61 76  n that would hav
20540 65 0a 2a 2a 20 62 65 65 6e 20 72 65 61 64 20 69  e.** been read i
20550 66 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 68 61  f [SQLITE_OK] ha
20560 64 20 62 65 65 6e 20 72 65 74 75 72 6e 65 64 2e  d been returned.
20570 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 49 47    The [SQLITE_IG
20580 4e 4f 52 45 5d 0a 2a 2a 20 72 65 74 75 72 6e 20  NORE].** return 
20590 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 64  can be used to d
205a0 65 6e 79 20 61 6e 20 75 6e 74 72 75 73 74 65 64  eny an untrusted
205b0 20 75 73 65 72 20 61 63 63 65 73 73 20 74 6f 20   user access to 
205c0 69 6e 64 69 76 69 64 75 61 6c 0a 2a 2a 20 63 6f  individual.** co
205d0 6c 75 6d 6e 73 20 6f 66 20 61 20 74 61 62 6c 65  lumns of a table
205e0 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 61 63 74  ..** ^If the act
205f0 69 6f 6e 20 63 6f 64 65 20 69 73 20 5b 53 51 4c  ion code is [SQL
20600 49 54 45 5f 44 45 4c 45 54 45 5d 20 61 6e 64 20  ITE_DELETE] and 
20610 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  the callback ret
20620 75 72 6e 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  urns.** [SQLITE_
20630 49 47 4e 4f 52 45 5d 20 74 68 65 6e 20 74 68 65  IGNORE] then the
20640 20 5b 44 45 4c 45 54 45 5d 20 6f 70 65 72 61 74   [DELETE] operat
20650 69 6f 6e 20 70 72 6f 63 65 65 64 73 20 62 75 74  ion proceeds but
20660 20 74 68 65 0a 2a 2a 20 5b 74 72 75 6e 63 61 74   the.** [truncat
20670 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 5d 20  e optimization] 
20680 69 73 20 64 69 73 61 62 6c 65 64 20 61 6e 64 20  is disabled and 
20690 61 6c 6c 20 72 6f 77 73 20 61 72 65 20 64 65 6c  all rows are del
206a0 65 74 65 64 20 69 6e 64 69 76 69 64 75 61 6c 6c  eted individuall
206b0 79 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 61 75 74 68  y..**.** An auth
206c0 6f 72 69 7a 65 72 20 69 73 20 75 73 65 64 20 77  orizer is used w
206d0 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  hen [sqlite3_pre
206e0 70 61 72 65 20 7c 20 70 72 65 70 61 72 69 6e 67  pare | preparing
206f0 5d 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65  ].** SQL stateme
20700 6e 74 73 20 66 72 6f 6d 20 61 6e 20 75 6e 74 72  nts from an untr
20710 75 73 74 65 64 20 73 6f 75 72 63 65 2c 20 74 6f  usted source, to
20720 20 65 6e 73 75 72 65 20 74 68 61 74 20 74 68 65   ensure that the
20730 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a   SQL statements.
20740 2a 2a 20 64 6f 20 6e 6f 74 20 74 72 79 20 74 6f  ** do not try to
20750 20 61 63 63 65 73 73 20 64 61 74 61 20 74 68 65   access data the
20760 79 20 61 72 65 20 6e 6f 74 20 61 6c 6c 6f 77 65  y are not allowe
20770 64 20 74 6f 20 73 65 65 2c 20 6f 72 20 74 68 61  d to see, or tha
20780 74 20 74 68 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a  t they do not.**
20790 20 74 72 79 20 74 6f 20 65 78 65 63 75 74 65 20   try to execute 
207a0 6d 61 6c 69 63 69 6f 75 73 20 73 74 61 74 65 6d  malicious statem
207b0 65 6e 74 73 20 74 68 61 74 20 64 61 6d 61 67 65  ents that damage
207c0 20 74 68 65 20 64 61 74 61 62 61 73 65 2e 20 20   the database.  
207d0 46 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20  For.** example, 
207e0 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d  an application m
207f0 61 79 20 61 6c 6c 6f 77 20 61 20 75 73 65 72 20  ay allow a user 
20800 74 6f 20 65 6e 74 65 72 20 61 72 62 69 74 72 61  to enter arbitra
20810 72 79 0a 2a 2a 20 53 51 4c 20 71 75 65 72 69 65  ry.** SQL querie
20820 73 20 66 6f 72 20 65 76 61 6c 75 61 74 69 6f 6e  s for evaluation
20830 20 62 79 20 61 20 64 61 74 61 62 61 73 65 2e 20   by a database. 
20840 20 42 75 74 20 74 68 65 20 61 70 70 6c 69 63 61   But the applica
20850 74 69 6f 6e 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74  tion does.** not
20860 20 77 61 6e 74 20 74 68 65 20 75 73 65 72 20 74   want the user t
20870 6f 20 62 65 20 61 62 6c 65 20 74 6f 20 6d 61 6b  o be able to mak
20880 65 20 61 72 62 69 74 72 61 72 79 20 63 68 61 6e  e arbitrary chan
20890 67 65 73 20 74 6f 20 74 68 65 0a 2a 2a 20 64 61  ges to the.** da
208a0 74 61 62 61 73 65 2e 20 20 41 6e 20 61 75 74 68  tabase.  An auth
208b0 6f 72 69 7a 65 72 20 63 6f 75 6c 64 20 74 68 65  orizer could the
208c0 6e 20 62 65 20 70 75 74 20 69 6e 20 70 6c 61 63  n be put in plac
208d0 65 20 77 68 69 6c 65 20 74 68 65 0a 2a 2a 20 75  e while the.** u
208e0 73 65 72 2d 65 6e 74 65 72 65 64 20 53 51 4c 20  ser-entered SQL 
208f0 69 73 20 62 65 69 6e 67 20 5b 73 71 6c 69 74 65  is being [sqlite
20900 33 5f 70 72 65 70 61 72 65 20 7c 20 70 72 65 70  3_prepare | prep
20910 61 72 65 64 5d 20 74 68 61 74 0a 2a 2a 20 64 69  ared] that.** di
20920 73 61 6c 6c 6f 77 73 20 65 76 65 72 79 74 68 69  sallows everythi
20930 6e 67 20 65 78 63 65 70 74 20 5b 53 45 4c 45 43  ng except [SELEC
20940 54 5d 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a  T] statements..*
20950 2a 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e  *.** Application
20960 73 20 74 68 61 74 20 6e 65 65 64 20 74 6f 20 70  s that need to p
20970 72 6f 63 65 73 73 20 53 51 4c 20 66 72 6f 6d 20  rocess SQL from 
20980 75 6e 74 72 75 73 74 65 64 20 73 6f 75 72 63 65  untrusted source
20990 73 0a 2a 2a 20 6d 69 67 68 74 20 61 6c 73 6f 20  s.** might also 
209a0 63 6f 6e 73 69 64 65 72 20 6c 6f 77 65 72 69 6e  consider lowerin
209b0 67 20 72 65 73 6f 75 72 63 65 20 6c 69 6d 69 74  g resource limit
209c0 73 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  s using [sqlite3
209d0 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 61 6e 64  _limit()].** and
209e0 20 6c 69 6d 69 74 69 6e 67 20 64 61 74 61 62 61   limiting databa
209f0 73 65 20 73 69 7a 65 20 75 73 69 6e 67 20 74 68  se size using th
20a00 65 20 5b 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e  e [max_page_coun
20a10 74 5d 20 5b 50 52 41 47 4d 41 5d 0a 2a 2a 20 69  t] [PRAGMA].** i
20a20 6e 20 61 64 64 69 74 69 6f 6e 20 74 6f 20 75 73  n addition to us
20a30 69 6e 67 20 61 6e 20 61 75 74 68 6f 72 69 7a 65  ing an authorize
20a40 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 4f 6e 6c 79 20  r..**.** ^(Only 
20a50 61 20 73 69 6e 67 6c 65 20 61 75 74 68 6f 72 69  a single authori
20a60 7a 65 72 20 63 61 6e 20 62 65 20 69 6e 20 70 6c  zer can be in pl
20a70 61 63 65 20 6f 6e 20 61 20 64 61 74 61 62 61 73  ace on a databas
20a80 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20  e connection.** 
20a90 61 74 20 61 20 74 69 6d 65 2e 20 20 45 61 63 68  at a time.  Each
20aa0 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33   call to sqlite3
20ab0 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20  _set_authorizer 
20ac0 6f 76 65 72 72 69 64 65 73 20 74 68 65 0a 2a 2a  overrides the.**
20ad0 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 2e 29   previous call.)
20ae0 5e 20 20 5e 44 69 73 61 62 6c 65 20 74 68 65 20  ^  ^Disable the 
20af0 61 75 74 68 6f 72 69 7a 65 72 20 62 79 20 69 6e  authorizer by in
20b00 73 74 61 6c 6c 69 6e 67 20 61 20 4e 55 4c 4c 20  stalling a NULL 
20b10 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 54 68 65  callback..** The
20b20 20 61 75 74 68 6f 72 69 7a 65 72 20 69 73 20 64   authorizer is d
20b30 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 61 75  isabled by defau
20b40 6c 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 75  lt..**.** The au
20b50 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
20b60 6b 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e  k must not do an
20b70 79 74 68 69 6e 67 20 74 68 61 74 20 77 69 6c 6c  ything that will
20b80 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64   modify.** the d
20b90 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
20ba0 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20  on that invoked 
20bb0 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  the authorizer c
20bc0 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 4e 6f 74 65  allback..** Note
20bd0 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 70   that [sqlite3_p
20be0 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64  repare_v2()] and
20bf0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
20c00 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79 20 74 68  ] both modify th
20c10 65 69 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20  eir.** database 
20c20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20  connections for 
20c30 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22  the meaning of "
20c40 6d 6f 64 69 66 79 22 20 69 6e 20 74 68 69 73 20  modify" in this 
20c50 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a  paragraph..**.**
20c60 20 5e 57 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f   ^When [sqlite3_
20c70 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 69 73  prepare_v2()] is
20c80 20 75 73 65 64 20 74 6f 20 70 72 65 70 61 72 65   used to prepare
20c90 20 61 20 73 74 61 74 65 6d 65 6e 74 2c 20 74 68   a statement, th
20ca0 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 6d  e.** statement m
20cb0 69 67 68 74 20 62 65 20 72 65 2d 70 72 65 70 61  ight be re-prepa
20cc0 72 65 64 20 64 75 72 69 6e 67 20 5b 73 71 6c 69  red during [sqli
20cd0 74 65 33 5f 73 74 65 70 28 29 5d 20 64 75 65 20  te3_step()] due 
20ce0 74 6f 20 61 20 0a 2a 2a 20 73 63 68 65 6d 61 20  to a .** schema 
20cf0 63 68 61 6e 67 65 2e 20 20 48 65 6e 63 65 2c 20  change.  Hence, 
20d00 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
20d10 73 68 6f 75 6c 64 20 65 6e 73 75 72 65 20 74 68  should ensure th
20d20 61 74 20 74 68 65 0a 2a 2a 20 63 6f 72 72 65 63  at the.** correc
20d30 74 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  t authorizer cal
20d40 6c 62 61 63 6b 20 72 65 6d 61 69 6e 73 20 69 6e  lback remains in
20d50 20 70 6c 61 63 65 20 64 75 72 69 6e 67 20 74 68   place during th
20d60 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  e [sqlite3_step(
20d70 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 4e 6f 74 65 20  )]..**.** ^Note 
20d80 74 68 61 74 20 74 68 65 20 61 75 74 68 6f 72 69  that the authori
20d90 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  zer callback is 
20da0 69 6e 76 6f 6b 65 64 20 6f 6e 6c 79 20 64 75 72  invoked only dur
20db0 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ing.** [sqlite3_
20dc0 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20 69 74  prepare()] or it
20dd0 73 20 76 61 72 69 61 6e 74 73 2e 20 20 41 75 74  s variants.  Aut
20de0 68 6f 72 69 7a 61 74 69 6f 6e 20 69 73 20 6e 6f  horization is no
20df0 74 0a 2a 2a 20 70 65 72 66 6f 72 6d 65 64 20 64  t.** performed d
20e00 75 72 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20  uring statement 
20e10 65 76 61 6c 75 61 74 69 6f 6e 20 69 6e 20 5b 73  evaluation in [s
20e20 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2c 20  qlite3_step()], 
20e30 75 6e 6c 65 73 73 0a 2a 2a 20 61 73 20 73 74 61  unless.** as sta
20e40 74 65 64 20 69 6e 20 74 68 65 20 70 72 65 76 69  ted in the previ
20e50 6f 75 73 20 70 61 72 61 67 72 61 70 68 2c 20 73  ous paragraph, s
20e60 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69 6e  qlite3_step() in
20e70 76 6f 6b 65 73 0a 2a 2a 20 73 71 6c 69 74 65 33  vokes.** sqlite3
20e80 5f 70 72 65 70 61 72 65 5f 76 32 28 29 20 74 6f  _prepare_v2() to
20e90 20 72 65 70 72 65 70 61 72 65 20 61 20 73 74 61   reprepare a sta
20ea0 74 65 6d 65 6e 74 20 61 66 74 65 72 20 61 20 73  tement after a s
20eb0 63 68 65 6d 61 20 63 68 61 6e 67 65 2e 0a 2a 2f  chema change..*/
20ec0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 65 74  .int sqlite3_set
20ed0 5f 61 75 74 68 6f 72 69 7a 65 72 28 0a 20 20 73  _authorizer(.  s
20ee0 71 6c 69 74 65 33 2a 2c 0a 20 20 69 6e 74 20 28  qlite3*,.  int (
20ef0 2a 78 41 75 74 68 29 28 76 6f 69 64 2a 2c 69 6e  *xAuth)(void*,in
20f00 74 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f  t,const char*,co
20f10 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20  nst char*,const 
20f20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72  char*,const char
20f30 2a 29 2c 0a 20 20 76 6f 69 64 20 2a 70 55 73 65  *),.  void *pUse
20f40 72 44 61 74 61 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  rData.);../*.** 
20f50 43 41 50 49 33 52 45 46 3a 20 41 75 74 68 6f 72  CAPI3REF: Author
20f60 69 7a 65 72 20 52 65 74 75 72 6e 20 43 6f 64 65  izer Return Code
20f70 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c  s.**.** The [sql
20f80 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69  ite3_set_authori
20f90 7a 65 72 20 7c 20 61 75 74 68 6f 72 69 7a 65 72  zer | authorizer
20fa0 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
20fb0 6f 6e 5d 20 6d 75 73 74 0a 2a 2a 20 72 65 74 75  on] must.** retu
20fc0 72 6e 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54  rn either [SQLIT
20fd0 45 5f 4f 4b 5d 20 6f 72 20 6f 6e 65 20 6f 66 20  E_OK] or one of 
20fe0 74 68 65 73 65 20 74 77 6f 20 63 6f 6e 73 74 61  these two consta
20ff0 6e 74 73 20 69 6e 20 6f 72 64 65 72 0a 2a 2a 20  nts in order.** 
21000 74 6f 20 73 69 67 6e 61 6c 20 53 51 4c 69 74 65  to signal SQLite
21010 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20   whether or not 
21020 74 68 65 20 61 63 74 69 6f 6e 20 69 73 20 70 65  the action is pe
21030 72 6d 69 74 74 65 64 2e 20 20 53 65 65 20 74 68  rmitted.  See th
21040 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 65  e.** [sqlite3_se
21050 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c 20 61  t_authorizer | a
21060 75 74 68 6f 72 69 7a 65 72 20 64 6f 63 75 6d 65  uthorizer docume
21070 6e 74 61 74 69 6f 6e 5d 20 66 6f 72 20 61 64 64  ntation] for add
21080 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72  itional.** infor
21090 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 4e 6f  mation..**.** No
210a0 74 65 20 74 68 61 74 20 53 51 4c 49 54 45 5f 49  te that SQLITE_I
210b0 47 4e 4f 52 45 20 69 73 20 61 6c 73 6f 20 75 73  GNORE is also us
210c0 65 64 20 61 73 20 61 20 5b 63 6f 6e 66 6c 69 63  ed as a [conflic
210d0 74 20 72 65 73 6f 6c 75 74 69 6f 6e 20 6d 6f 64  t resolution mod
210e0 65 5d 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 66  e].** returned f
210f0 72 6f 6d 20 74 68 65 20 5b 73 71 6c 69 74 65 33  rom the [sqlite3
21100 5f 76 74 61 62 5f 6f 6e 5f 63 6f 6e 66 6c 69 63  _vtab_on_conflic
21110 74 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a  t()] interface..
21120 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
21130 45 5f 44 45 4e 59 20 20 20 31 20 20 20 2f 2a 20  E_DENY   1   /* 
21140 41 62 6f 72 74 20 74 68 65 20 53 51 4c 20 73 74  Abort the SQL st
21150 61 74 65 6d 65 6e 74 20 77 69 74 68 20 61 6e 20  atement with an 
21160 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65  error */.#define
21170 20 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 20 32   SQLITE_IGNORE 2
21180 20 20 20 2f 2a 20 44 6f 6e 27 74 20 61 6c 6c 6f     /* Don't allo
21190 77 20 61 63 63 65 73 73 2c 20 62 75 74 20 64 6f  w access, but do
211a0 6e 27 74 20 67 65 6e 65 72 61 74 65 20 61 6e 20  n't generate an 
211b0 65 72 72 6f 72 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20  error */../*.** 
211c0 43 41 50 49 33 52 45 46 3a 20 41 75 74 68 6f 72  CAPI3REF: Author
211d0 69 7a 65 72 20 41 63 74 69 6f 6e 20 43 6f 64 65  izer Action Code
211e0 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c  s.**.** The [sql
211f0 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69  ite3_set_authori
21200 7a 65 72 28 29 5d 20 69 6e 74 65 72 66 61 63 65  zer()] interface
21210 20 72 65 67 69 73 74 65 72 73 20 61 20 63 61 6c   registers a cal
21220 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 0a 2a  lback function.*
21230 2a 20 74 68 61 74 20 69 73 20 69 6e 76 6f 6b 65  * that is invoke
21240 64 20 74 6f 20 61 75 74 68 6f 72 69 7a 65 20 63  d to authorize c
21250 65 72 74 61 69 6e 20 53 51 4c 20 73 74 61 74 65  ertain SQL state
21260 6d 65 6e 74 20 61 63 74 69 6f 6e 73 2e 20 20 54  ment actions.  T
21270 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72  he.** second par
21280 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 63 61  ameter to the ca
21290 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 69 6e 74  llback is an int
212a0 65 67 65 72 20 63 6f 64 65 20 74 68 61 74 20 73  eger code that s
212b0 70 65 63 69 66 69 65 73 0a 2a 2a 20 77 68 61 74  pecifies.** what
212c0 20 61 63 74 69 6f 6e 20 69 73 20 62 65 69 6e 67   action is being
212d0 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 20 54 68   authorized.  Th
212e0 65 73 65 20 61 72 65 20 74 68 65 20 69 6e 74 65  ese are the inte
212f0 67 65 72 20 61 63 74 69 6f 6e 20 63 6f 64 65 73  ger action codes
21300 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 61 75 74   that.** the aut
21310 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
21320 20 6d 61 79 20 62 65 20 70 61 73 73 65 64 2e 0a   may be passed..
21330 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61 63 74 69  **.** These acti
21340 6f 6e 20 63 6f 64 65 20 76 61 6c 75 65 73 20 73  on code values s
21350 69 67 6e 69 66 79 20 77 68 61 74 20 6b 69 6e 64  ignify what kind
21360 20 6f 66 20 6f 70 65 72 61 74 69 6f 6e 20 69 73   of operation is
21370 20 74 6f 20 62 65 0a 2a 2a 20 61 75 74 68 6f 72   to be.** author
21380 69 7a 65 64 2e 20 20 54 68 65 20 33 72 64 20 61  ized.  The 3rd a
21390 6e 64 20 34 74 68 20 70 61 72 61 6d 65 74 65 72  nd 4th parameter
213a0 73 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69  s to the authori
213b0 7a 61 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 61  zation.** callba
213c0 63 6b 20 66 75 6e 63 74 69 6f 6e 20 77 69 6c 6c  ck function will
213d0 20 62 65 20 70 61 72 61 6d 65 74 65 72 73 20 6f   be parameters o
213e0 72 20 4e 55 4c 4c 20 64 65 70 65 6e 64 69 6e 67  r NULL depending
213f0 20 6f 6e 20 77 68 69 63 68 20 6f 66 20 74 68 65   on which of the
21400 73 65 0a 2a 2a 20 63 6f 64 65 73 20 69 73 20 75  se.** codes is u
21410 73 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e  sed as the secon
21420 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20 5e 28  d parameter.  ^(
21430 54 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65  The 5th paramete
21440 72 20 74 6f 20 74 68 65 0a 2a 2a 20 61 75 74 68  r to the.** auth
21450 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
21460 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  is the name of t
21470 68 65 20 64 61 74 61 62 61 73 65 20 28 22 6d 61  he database ("ma
21480 69 6e 22 2c 20 22 74 65 6d 70 22 2c 0a 2a 2a 20  in", "temp",.** 
21490 65 74 63 2e 29 20 69 66 20 61 70 70 6c 69 63 61  etc.) if applica
214a0 62 6c 65 2e 29 5e 20 20 5e 54 68 65 20 36 74 68  ble.)^  ^The 6th
214b0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
214c0 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
214d0 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 74 68 65 20  lback.** is the 
214e0 6e 61 6d 65 20 6f 66 20 74 68 65 20 69 6e 6e 65  name of the inne
214f0 72 2d 6d 6f 73 74 20 74 72 69 67 67 65 72 20 6f  r-most trigger o
21500 72 20 76 69 65 77 20 74 68 61 74 20 69 73 20 72  r view that is r
21510 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 0a 2a  esponsible for.*
21520 2a 20 74 68 65 20 61 63 63 65 73 73 20 61 74 74  * the access att
21530 65 6d 70 74 20 6f 72 20 4e 55 4c 4c 20 69 66 20  empt or NULL if 
21540 74 68 69 73 20 61 63 63 65 73 73 20 61 74 74 65  this access atte
21550 6d 70 74 20 69 73 20 64 69 72 65 63 74 6c 79 20  mpt is directly 
21560 66 72 6f 6d 0a 2a 2a 20 74 6f 70 2d 6c 65 76 65  from.** top-leve
21570 6c 20 53 51 4c 20 63 6f 64 65 2e 0a 2a 2f 0a 2f  l SQL code..*/./
21580 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
21590 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
215a0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 33 72 64 20  *********** 3rd 
215b0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 34 74 68  ************ 4th
215c0 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 23 64   ***********/.#d
215d0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45  efine SQLITE_CRE
215e0 41 54 45 5f 49 4e 44 45 58 20 20 20 20 20 20 20  ATE_INDEX       
215f0 20 20 20 31 20 20 20 2f 2a 20 49 6e 64 65 78 20     1   /* Index 
21600 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20  Name      Table 
21610 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65  Name      */.#de
21620 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41  fine SQLITE_CREA
21630 54 45 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20  TE_TABLE        
21640 20 20 32 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e    2   /* Table N
21650 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  ame      NULL   
21660 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
21670 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54  ine SQLITE_CREAT
21680 45 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20 20 20  E_TEMP_INDEX    
21690 20 33 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61   3   /* Index Na
216a0 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61  me      Table Na
216b0 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  me      */.#defi
216c0 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45  ne SQLITE_CREATE
216d0 5f 54 45 4d 50 5f 54 41 42 4c 45 20 20 20 20 20  _TEMP_TABLE     
216e0 34 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  4   /* Table Nam
216f0 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20  e      NULL     
21700 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
21710 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f  e SQLITE_CREATE_
21720 54 45 4d 50 5f 54 52 49 47 47 45 52 20 20 20 35  TEMP_TRIGGER   5
21730 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61     /* Trigger Na
21740 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65  me    Table Name
21750 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
21760 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54   SQLITE_CREATE_T
21770 45 4d 50 5f 56 49 45 57 20 20 20 20 20 20 36 20  EMP_VIEW      6 
21780 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20    /* View Name  
21790 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
217a0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
217b0 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 52  SQLITE_CREATE_TR
217c0 49 47 47 45 52 20 20 20 20 20 20 20 20 37 20 20  IGGER        7  
217d0 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65   /* Trigger Name
217e0 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20      Table Name  
217f0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
21800 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 56 49 45  QLITE_CREATE_VIE
21810 57 20 20 20 20 20 20 20 20 20 20 20 38 20 20 20  W           8   
21820 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20  /* View Name    
21830 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
21840 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
21850 4c 49 54 45 5f 44 45 4c 45 54 45 20 20 20 20 20  LITE_DELETE     
21860 20 20 20 20 20 20 20 20 20 20 20 39 20 20 20 2f             9   /
21870 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
21880 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
21890 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
218a0 49 54 45 5f 44 52 4f 50 5f 49 4e 44 45 58 20 20  ITE_DROP_INDEX  
218b0 20 20 20 20 20 20 20 20 20 31 30 20 20 20 2f 2a           10   /*
218c0 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20   Index Name     
218d0 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
218e0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
218f0 54 45 5f 44 52 4f 50 5f 54 41 42 4c 45 20 20 20  TE_DROP_TABLE   
21900 20 20 20 20 20 20 20 20 31 31 20 20 20 2f 2a 20          11   /* 
21910 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
21920 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
21930 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
21940 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 49 4e 44 45  E_DROP_TEMP_INDE
21950 58 20 20 20 20 20 20 31 32 20 20 20 2f 2a 20 49  X      12   /* I
21960 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54  ndex Name      T
21970 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a  able Name      *
21980 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
21990 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 41 42 4c 45  _DROP_TEMP_TABLE
219a0 20 20 20 20 20 20 31 33 20 20 20 2f 2a 20 54 61        13   /* Ta
219b0 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55  ble Name      NU
219c0 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
219d0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
219e0 44 52 4f 50 5f 54 45 4d 50 5f 54 52 49 47 47 45  DROP_TEMP_TRIGGE
219f0 52 20 20 20 20 31 34 20 20 20 2f 2a 20 54 72 69  R    14   /* Tri
21a00 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62  gger Name    Tab
21a10 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a  le Name      */.
21a20 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
21a30 52 4f 50 5f 54 45 4d 50 5f 56 49 45 57 20 20 20  ROP_TEMP_VIEW   
21a40 20 20 20 20 31 35 20 20 20 2f 2a 20 56 69 65 77      15   /* View
21a50 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c   Name       NULL
21a60 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
21a70 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52  define SQLITE_DR
21a80 4f 50 5f 54 52 49 47 47 45 52 20 20 20 20 20 20  OP_TRIGGER      
21a90 20 20 20 31 36 20 20 20 2f 2a 20 54 72 69 67 67     16   /* Trigg
21aa0 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65  er Name    Table
21ab0 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64   Name      */.#d
21ac0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f  efine SQLITE_DRO
21ad0 50 5f 56 49 45 57 20 20 20 20 20 20 20 20 20 20  P_VIEW          
21ae0 20 20 31 37 20 20 20 2f 2a 20 56 69 65 77 20 4e    17   /* View N
21af0 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20  ame       NULL  
21b00 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
21b10 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 53 45  fine SQLITE_INSE
21b20 52 54 20 20 20 20 20 20 20 20 20 20 20 20 20 20  RT              
21b30 20 31 38 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e   18   /* Table N
21b40 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  ame      NULL   
21b50 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
21b60 69 6e 65 20 53 51 4c 49 54 45 5f 50 52 41 47 4d  ine SQLITE_PRAGM
21b70 41 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  A               
21b80 31 39 20 20 20 2f 2a 20 50 72 61 67 6d 61 20 4e  19   /* Pragma N
21b90 61 6d 65 20 20 20 20 20 31 73 74 20 61 72 67 20  ame     1st arg 
21ba0 6f 72 20 4e 55 4c 4c 20 2a 2f 0a 23 64 65 66 69  or NULL */.#defi
21bb0 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44 20 20  ne SQLITE_READ  
21bc0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32                 2
21bd0 30 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  0   /* Table Nam
21be0 65 20 20 20 20 20 20 43 6f 6c 75 6d 6e 20 4e 61  e      Column Na
21bf0 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  me     */.#defin
21c00 65 20 53 51 4c 49 54 45 5f 53 45 4c 45 43 54 20  e SQLITE_SELECT 
21c10 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 31                21
21c20 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20     /* NULL      
21c30 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
21c40 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
21c50 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 41 43 54   SQLITE_TRANSACT
21c60 49 4f 4e 20 20 20 20 20 20 20 20 20 20 32 32 20  ION          22 
21c70 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20 20    /* Operation  
21c80 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
21c90 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
21ca0 53 51 4c 49 54 45 5f 55 50 44 41 54 45 20 20 20  SQLITE_UPDATE   
21cb0 20 20 20 20 20 20 20 20 20 20 20 20 32 33 20 20              23  
21cc0 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
21cd0 20 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20      Column Name 
21ce0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
21cf0 51 4c 49 54 45 5f 41 54 54 41 43 48 20 20 20 20  QLITE_ATTACH    
21d00 20 20 20 20 20 20 20 20 20 20 20 32 34 20 20 20             24   
21d10 2f 2a 20 46 69 6c 65 6e 61 6d 65 20 20 20 20 20  /* Filename     
21d20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
21d30 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
21d40 4c 49 54 45 5f 44 45 54 41 43 48 20 20 20 20 20  LITE_DETACH     
21d50 20 20 20 20 20 20 20 20 20 20 32 35 20 20 20 2f            25   /
21d60 2a 20 44 61 74 61 62 61 73 65 20 4e 61 6d 65 20  * Database Name 
21d70 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
21d80 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
21d90 49 54 45 5f 41 4c 54 45 52 5f 54 41 42 4c 45 20  ITE_ALTER_TABLE 
21da0 20 20 20 20 20 20 20 20 20 32 36 20 20 20 2f 2a           26   /*
21db0 20 44 61 74 61 62 61 73 65 20 4e 61 6d 65 20 20   Database Name  
21dc0 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
21dd0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
21de0 54 45 5f 52 45 49 4e 44 45 58 20 20 20 20 20 20  TE_REINDEX      
21df0 20 20 20 20 20 20 20 20 32 37 20 20 20 2f 2a 20          27   /* 
21e00 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20  Index Name      
21e10 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
21e20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
21e30 45 5f 41 4e 41 4c 59 5a 45 20 20 20 20 20 20 20  E_ANALYZE       
21e40 20 20 20 20 20 20 20 32 38 20 20 20 2f 2a 20 54         28   /* T
21e50 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e  able Name      N
21e60 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
21e70 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
21e80 5f 43 52 45 41 54 45 5f 56 54 41 42 4c 45 20 20  _CREATE_VTABLE  
21e90 20 20 20 20 20 20 32 39 20 20 20 2f 2a 20 54 61        29   /* Ta
21ea0 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4d 6f  ble Name      Mo
21eb0 64 75 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a 2f  dule Name     */
21ec0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
21ed0 44 52 4f 50 5f 56 54 41 42 4c 45 20 20 20 20 20  DROP_VTABLE     
21ee0 20 20 20 20 20 33 30 20 20 20 2f 2a 20 54 61 62       30   /* Tab
21ef0 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4d 6f 64  le Name      Mod
21f00 75 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a  ule Name     */.
21f10 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
21f20 55 4e 43 54 49 4f 4e 20 20 20 20 20 20 20 20 20  UNCTION         
21f30 20 20 20 20 33 31 20 20 20 2f 2a 20 4e 55 4c 4c      31   /* NULL
21f40 20 20 20 20 20 20 20 20 20 20 20 20 46 75 6e 63              Func
21f50 74 69 6f 6e 20 4e 61 6d 65 20 20 20 2a 2f 0a 23  tion Name   */.#
21f60 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 41  define SQLITE_SA
21f70 56 45 50 4f 49 4e 54 20 20 20 20 20 20 20 20 20  VEPOINT         
21f80 20 20 20 33 32 20 20 20 2f 2a 20 4f 70 65 72 61     32   /* Opera
21f90 74 69 6f 6e 20 20 20 20 20 20 20 53 61 76 65 70  tion       Savep
21fa0 6f 69 6e 74 20 4e 61 6d 65 20 20 2a 2f 0a 23 64  oint Name  */.#d
21fb0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 50  efine SQLITE_COP
21fc0 59 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  Y               
21fd0 20 20 20 30 20 20 20 2f 2a 20 4e 6f 20 6c 6f 6e     0   /* No lon
21fe0 67 65 72 20 75 73 65 64 20 2a 2f 0a 23 64 65 66  ger used */.#def
21ff0 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 43 55 52  ine SQLITE_RECUR
22000 53 49 56 45 20 20 20 20 20 20 20 20 20 20 20 20  SIVE            
22010 33 33 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20  33   /* NULL    
22020 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20          NULL    
22030 20 20 20 20 20 20 20 20 2a 2f 0a 0a 2f 2a 0a 2a          */../*.*
22040 2a 20 43 41 50 49 33 52 45 46 3a 20 54 72 61 63  * CAPI3REF: Trac
22050 69 6e 67 20 41 6e 64 20 50 72 6f 66 69 6c 69 6e  ing And Profilin
22060 67 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 4d  g Functions.** M
22070 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a  ETHOD: sqlite3.*
22080 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
22090 6e 65 73 20 61 72 65 20 64 65 70 72 65 63 61 74  nes are deprecat
220a0 65 64 2e 20 55 73 65 20 74 68 65 20 5b 73 71 6c  ed. Use the [sql
220b0 69 74 65 33 5f 74 72 61 63 65 5f 76 32 28 29 5d  ite3_trace_v2()]
220c0 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 69 6e   interface.** in
220d0 73 74 65 61 64 20 6f 66 20 74 68 65 20 72 6f 75  stead of the rou
220e0 74 69 6e 65 73 20 64 65 73 63 72 69 62 65 64 20  tines described 
220f0 68 65 72 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73  here..**.** Thes
22100 65 20 72 6f 75 74 69 6e 65 73 20 72 65 67 69 73  e routines regis
22110 74 65 72 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  ter callback fun
22120 63 74 69 6f 6e 73 20 74 68 61 74 20 63 61 6e 20  ctions that can 
22130 62 65 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20 74  be used for.** t
22140 72 61 63 69 6e 67 20 61 6e 64 20 70 72 6f 66 69  racing and profi
22150 6c 69 6e 67 20 74 68 65 20 65 78 65 63 75 74 69  ling the executi
22160 6f 6e 20 6f 66 20 53 51 4c 20 73 74 61 74 65 6d  on of SQL statem
22170 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ents..**.** ^The
22180 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
22190 6f 6e 20 72 65 67 69 73 74 65 72 65 64 20 62 79  on registered by
221a0 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29   sqlite3_trace()
221b0 20 69 73 20 69 6e 76 6f 6b 65 64 20 61 74 0a 2a   is invoked at.*
221c0 2a 20 76 61 72 69 6f 75 73 20 74 69 6d 65 73 20  * various times 
221d0 77 68 65 6e 20 61 6e 20 53 51 4c 20 73 74 61 74  when an SQL stat
221e0 65 6d 65 6e 74 20 69 73 20 62 65 69 6e 67 20 72  ement is being r
221f0 75 6e 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 73  un by [sqlite3_s
22200 74 65 70 28 29 5d 2e 0a 2a 2a 20 5e 54 68 65 20  tep()]..** ^The 
22210 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 20  sqlite3_trace() 
22220 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f  callback is invo
22230 6b 65 64 20 77 69 74 68 20 61 20 55 54 46 2d 38  ked with a UTF-8
22240 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68   rendering of th
22250 65 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65  e.** SQL stateme
22260 6e 74 20 74 65 78 74 20 61 73 20 74 68 65 20 73  nt text as the s
22270 74 61 74 65 6d 65 6e 74 20 66 69 72 73 74 20 62  tatement first b
22280 65 67 69 6e 73 20 65 78 65 63 75 74 69 6e 67 2e  egins executing.
22290 0a 2a 2a 20 5e 28 41 64 64 69 74 69 6f 6e 61 6c  .** ^(Additional
222a0 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29   sqlite3_trace()
222b0 20 63 61 6c 6c 62 61 63 6b 73 20 6d 69 67 68 74   callbacks might
222c0 20 6f 63 63 75 72 0a 2a 2a 20 61 73 20 65 61 63   occur.** as eac
222d0 68 20 74 72 69 67 67 65 72 65 64 20 73 75 62 70  h triggered subp
222e0 72 6f 67 72 61 6d 20 69 73 20 65 6e 74 65 72 65  rogram is entere
222f0 64 2e 20 20 54 68 65 20 63 61 6c 6c 62 61 63 6b  d.  The callback
22300 73 20 66 6f 72 20 74 72 69 67 67 65 72 73 0a 2a  s for triggers.*
22310 2a 20 63 6f 6e 74 61 69 6e 20 61 20 55 54 46 2d  * contain a UTF-
22320 38 20 53 51 4c 20 63 6f 6d 6d 65 6e 74 20 74 68  8 SQL comment th
22330 61 74 20 69 64 65 6e 74 69 66 69 65 73 20 74 68  at identifies th
22340 65 20 74 72 69 67 67 65 72 2e 29 5e 0a 2a 2a 0a  e trigger.)^.**.
22350 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 54  ** The [SQLITE_T
22360 52 41 43 45 5f 53 49 5a 45 5f 4c 49 4d 49 54 5d  RACE_SIZE_LIMIT]
22370 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
22380 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 73 65 64  tion can be used
22390 20 74 6f 20 6c 69 6d 69 74 0a 2a 2a 20 74 68 65   to limit.** the
223a0 20 6c 65 6e 67 74 68 20 6f 66 20 5b 62 6f 75 6e   length of [boun
223b0 64 20 70 61 72 61 6d 65 74 65 72 5d 20 65 78 70  d parameter] exp
223c0 61 6e 73 69 6f 6e 20 69 6e 20 74 68 65 20 6f 75  ansion in the ou
223d0 74 70 75 74 20 6f 66 20 73 71 6c 69 74 65 33 5f  tput of sqlite3_
223e0 74 72 61 63 65 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e  trace()..**.** ^
223f0 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  The callback fun
22400 63 74 69 6f 6e 20 72 65 67 69 73 74 65 72 65 64  ction registered
22410 20 62 79 20 73 71 6c 69 74 65 33 5f 70 72 6f 66   by sqlite3_prof
22420 69 6c 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64  ile() is invoked
22430 0a 2a 2a 20 61 73 20 65 61 63 68 20 53 51 4c 20  .** as each SQL 
22440 73 74 61 74 65 6d 65 6e 74 20 66 69 6e 69 73 68  statement finish
22450 65 73 2e 20 20 5e 54 68 65 20 70 72 6f 66 69 6c  es.  ^The profil
22460 65 20 63 61 6c 6c 62 61 63 6b 20 63 6f 6e 74 61  e callback conta
22470 69 6e 73 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69  ins.** the origi
22480 6e 61 6c 20 73 74 61 74 65 6d 65 6e 74 20 74 65  nal statement te
22490 78 74 20 61 6e 64 20 61 6e 20 65 73 74 69 6d 61  xt and an estima
224a0 74 65 20 6f 66 20 77 61 6c 6c 2d 63 6c 6f 63 6b  te of wall-clock
224b0 20 74 69 6d 65 0a 2a 2a 20 6f 66 20 68 6f 77 20   time.** of how 
224c0 6c 6f 6e 67 20 74 68 61 74 20 73 74 61 74 65 6d  long that statem
224d0 65 6e 74 20 74 6f 6f 6b 20 74 6f 20 72 75 6e 2e  ent took to run.
224e0 20 20 5e 54 68 65 20 70 72 6f 66 69 6c 65 20 63    ^The profile c
224f0 61 6c 6c 62 61 63 6b 0a 2a 2a 20 74 69 6d 65 20  allback.** time 
22500 69 73 20 69 6e 20 75 6e 69 74 73 20 6f 66 20 6e  is in units of n
22510 61 6e 6f 73 65 63 6f 6e 64 73 2c 20 68 6f 77 65  anoseconds, howe
22520 76 65 72 20 74 68 65 20 63 75 72 72 65 6e 74 20  ver the current 
22530 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a  implementation.*
22540 2a 20 69 73 20 6f 6e 6c 79 20 63 61 70 61 62 6c  * is only capabl
22550 65 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64  e of millisecond
22560 20 72 65 73 6f 6c 75 74 69 6f 6e 20 73 6f 20 74   resolution so t
22570 68 65 20 73 69 78 20 6c 65 61 73 74 20 73 69 67  he six least sig
22580 6e 69 66 69 63 61 6e 74 0a 2a 2a 20 64 69 67 69  nificant.** digi
22590 74 73 20 69 6e 20 74 68 65 20 74 69 6d 65 20 61  ts in the time a
225a0 72 65 20 6d 65 61 6e 69 6e 67 6c 65 73 73 2e 20  re meaningless. 
225b0 20 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73   Future versions
225c0 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20 6d 69   of SQLite.** mi
225d0 67 68 74 20 70 72 6f 76 69 64 65 20 67 72 65 61  ght provide grea
225e0 74 65 72 20 72 65 73 6f 6c 75 74 69 6f 6e 20 6f  ter resolution o
225f0 6e 20 74 68 65 20 70 72 6f 66 69 6c 65 72 20 63  n the profiler c
22600 61 6c 6c 62 61 63 6b 2e 20 20 54 68 65 0a 2a 2a  allback.  The.**
22610 20 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65   sqlite3_profile
22620 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63  () function is c
22630 6f 6e 73 69 64 65 72 65 64 20 65 78 70 65 72 69  onsidered experi
22640 6d 65 6e 74 61 6c 20 61 6e 64 20 69 73 0a 2a 2a  mental and is.**
22650 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e   subject to chan
22660 67 65 20 69 6e 20 66 75 74 75 72 65 20 76 65 72  ge in future ver
22670 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e  sions of SQLite.
22680 0a 2a 2f 0a 53 51 4c 49 54 45 5f 44 45 50 52 45  .*/.SQLITE_DEPRE
22690 43 41 54 45 44 20 76 6f 69 64 20 2a 73 71 6c 69  CATED void *sqli
226a0 74 65 33 5f 74 72 61 63 65 28 73 71 6c 69 74 65  te3_trace(sqlite
226b0 33 2a 2c 0a 20 20 20 76 6f 69 64 28 2a 78 54 72  3*,.   void(*xTr
226c0 61 63 65 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74  ace)(void*,const
226d0 20 63 68 61 72 2a 29 2c 20 76 6f 69 64 2a 29 3b   char*), void*);
226e0 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54  .SQLITE_DEPRECAT
226f0 45 44 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  ED void *sqlite3
22700 5f 70 72 6f 66 69 6c 65 28 73 71 6c 69 74 65 33  _profile(sqlite3
22710 2a 2c 0a 20 20 20 76 6f 69 64 28 2a 78 50 72 6f  *,.   void(*xPro
22720 66 69 6c 65 29 28 76 6f 69 64 2a 2c 63 6f 6e 73  file)(void*,cons
22730 74 20 63 68 61 72 2a 2c 73 71 6c 69 74 65 33 5f  t char*,sqlite3_
22740 75 69 6e 74 36 34 29 2c 20 76 6f 69 64 2a 29 3b  uint64), void*);
22750 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
22760 3a 20 53 51 4c 20 54 72 61 63 65 20 45 76 65 6e  : SQL Trace Even
22770 74 20 43 6f 64 65 73 0a 2a 2a 20 4b 45 59 57 4f  t Codes.** KEYWO
22780 52 44 53 3a 20 53 51 4c 49 54 45 5f 54 52 41 43  RDS: SQLITE_TRAC
22790 45 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f  E.**.** These co
227a0 6e 73 74 61 6e 74 73 20 69 64 65 6e 74 69 66 79  nstants identify
227b0 20 63 6c 61 73 73 65 73 20 6f 66 20 65 76 65 6e   classes of even
227c0 74 73 20 74 68 61 74 20 63 61 6e 20 62 65 20 6d  ts that can be m
227d0 6f 6e 69 74 6f 72 65 64 0a 2a 2a 20 75 73 69 6e  onitored.** usin
227e0 67 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 74  g the [sqlite3_t
227f0 72 61 63 65 5f 76 32 28 29 5d 20 74 72 61 63 69  race_v2()] traci
22800 6e 67 20 6c 6f 67 69 63 2e 20 20 54 68 65 20 74  ng logic.  The t
22810 68 69 72 64 20 61 72 67 75 6d 65 6e 74 0a 2a 2a  hird argument.**
22820 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 74 72 61   to [sqlite3_tra
22830 63 65 5f 76 32 28 29 5d 20 69 73 20 61 6e 20 4f  ce_v2()] is an O
22840 52 2d 65 64 20 63 6f 6d 62 69 6e 61 74 69 6f 6e  R-ed combination
22850 20 6f 66 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20   of one or more 
22860 6f 66 0a 2a 2a 20 74 68 65 20 66 6f 6c 6c 6f 77  of.** the follow
22870 69 6e 67 20 63 6f 6e 73 74 61 6e 74 73 2e 20 20  ing constants.  
22880 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d  ^The first argum
22890 65 6e 74 20 74 6f 20 74 68 65 20 74 72 61 63 65  ent to the trace
228a0 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20   callback.** is 
228b0 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f  one of the follo
228c0 77 69 6e 67 20 63 6f 6e 73 74 61 6e 74 73 2e 0a  wing constants..
228d0 2a 2a 0a 2a 2a 20 4e 65 77 20 74 72 61 63 69 6e  **.** New tracin
228e0 67 20 63 6f 6e 73 74 61 6e 74 73 20 6d 61 79 20  g constants may 
228f0 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75  be added in futu
22900 72 65 20 72 65 6c 65 61 73 65 73 2e 0a 2a 2a 0a  re releases..**.
22910 2a 2a 20 5e 41 20 74 72 61 63 65 20 63 61 6c 6c  ** ^A trace call
22920 62 61 63 6b 20 68 61 73 20 66 6f 75 72 20 61 72  back has four ar
22930 67 75 6d 65 6e 74 73 3a 20 78 43 61 6c 6c 62 61  guments: xCallba
22940 63 6b 28 54 2c 43 2c 50 2c 58 29 2e 0a 2a 2a 20  ck(T,C,P,X)..** 
22950 5e 54 68 65 20 54 20 61 72 67 75 6d 65 6e 74 20  ^The T argument 
22960 69 73 20 6f 6e 65 20 6f 66 20 74 68 65 20 69 6e  is one of the in
22970 74 65 67 65 72 20 74 79 70 65 20 63 6f 64 65 73  teger type codes
22980 20 61 62 6f 76 65 2e 0a 2a 2a 20 5e 54 68 65 20   above..** ^The 
22990 43 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20  C argument is a 
229a0 63 6f 70 79 20 6f 66 20 74 68 65 20 63 6f 6e 74  copy of the cont
229b0 65 78 74 20 70 6f 69 6e 74 65 72 20 70 61 73 73  ext pointer pass
229c0 65 64 20 69 6e 20 61 73 20 74 68 65 0a 2a 2a 20  ed in as the.** 
229d0 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 20  fourth argument 
229e0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 74 72 61 63  to [sqlite3_trac
229f0 65 5f 76 32 28 29 5d 2e 0a 2a 2a 20 54 68 65 20  e_v2()]..** The 
22a00 50 20 61 6e 64 20 58 20 61 72 67 75 6d 65 6e 74  P and X argument
22a10 73 20 61 72 65 20 70 6f 69 6e 74 65 72 73 20 77  s are pointers w
22a20 68 6f 73 65 20 6d 65 61 6e 69 6e 67 73 20 64 65  hose meanings de
22a30 70 65 6e 64 20 6f 6e 20 54 2e 0a 2a 2a 0a 2a 2a  pend on T..**.**
22a40 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c 49 54   <dl>.** [[SQLIT
22a50 45 5f 54 52 41 43 45 5f 53 54 4d 54 5d 5d 20 3c  E_TRACE_STMT]] <
22a60 64 74 3e 53 51 4c 49 54 45 5f 54 52 41 43 45 5f  dt>SQLITE_TRACE_
22a70 53 54 4d 54 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  STMT</dt>.** <dd
22a80 3e 5e 41 6e 20 53 51 4c 49 54 45 5f 54 52 41 43  >^An SQLITE_TRAC
22a90 45 5f 53 54 4d 54 20 63 61 6c 6c 62 61 63 6b 20  E_STMT callback 
22aa0 69 73 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20  is invoked when 
22ab0 61 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  a prepared state
22ac0 6d 65 6e 74 0a 2a 2a 20 66 69 72 73 74 20 62 65  ment.** first be
22ad0 67 69 6e 73 20 72 75 6e 6e 69 6e 67 20 61 6e 64  gins running and
22ae0 20 70 6f 73 73 69 62 6c 79 20 61 74 20 6f 74 68   possibly at oth
22af0 65 72 20 74 69 6d 65 73 20 64 75 72 69 6e 67 20  er times during 
22b00 74 68 65 0a 2a 2a 20 65 78 65 63 75 74 69 6f 6e  the.** execution
22b10 20 6f 66 20 74 68 65 20 70 72 65 70 61 72 65 64   of the prepared
22b20 20 73 74 61 74 65 6d 65 6e 74 2c 20 73 75 63 68   statement, such
22b30 20 61 73 20 61 74 20 74 68 65 20 73 74 61 72 74   as at the start
22b40 20 6f 66 20 65 61 63 68 0a 2a 2a 20 74 72 69 67   of each.** trig
22b50 67 65 72 20 73 75 62 70 72 6f 67 72 61 6d 2e 20  ger subprogram. 
22b60 5e 54 68 65 20 50 20 61 72 67 75 6d 65 6e 74 20  ^The P argument 
22b70 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
22b80 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64  the.** [prepared
22b90 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 5e 54 68   statement]. ^Th
22ba0 65 20 58 20 61 72 67 75 6d 65 6e 74 20 69 73 20  e X argument is 
22bb0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 73  a pointer to a s
22bc0 74 72 69 6e 67 20 77 68 69 63 68 0a 2a 2a 20 69  tring which.** i
22bd0 73 20 74 68 65 20 75 6e 65 78 70 61 6e 64 65 64  s the unexpanded
22be0 20 53 51 4c 20 74 65 78 74 20 6f 66 20 74 68 65   SQL text of the
22bf0 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
22c00 65 6e 74 20 6f 72 20 61 6e 20 53 51 4c 20 63 6f  ent or an SQL co
22c10 6d 6d 65 6e 74 20 0a 2a 2a 20 74 68 61 74 20 69  mment .** that i
22c20 6e 64 69 63 61 74 65 73 20 74 68 65 20 69 6e 76  ndicates the inv
22c30 6f 63 61 74 69 6f 6e 20 6f 66 20 61 20 74 72 69  ocation of a tri
22c40 67 67 65 72 2e 20 20 5e 54 68 65 20 63 61 6c 6c  gger.  ^The call
22c50 62 61 63 6b 20 63 61 6e 20 63 6f 6d 70 75 74 65  back can compute
22c60 0a 2a 2a 20 74 68 65 20 73 61 6d 65 20 74 65 78  .** the same tex
22c70 74 20 74 68 61 74 20 77 6f 75 6c 64 20 68 61 76  t that would hav
22c80 65 20 62 65 65 6e 20 72 65 74 75 72 6e 65 64 20  e been returned 
22c90 62 79 20 74 68 65 20 6c 65 67 61 63 79 20 5b 73  by the legacy [s
22ca0 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 5d 0a  qlite3_trace()].
22cb0 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 62 79 20  ** interface by 
22cc0 75 73 69 6e 67 20 74 68 65 20 58 20 61 72 67 75  using the X argu
22cd0 6d 65 6e 74 20 77 68 65 6e 20 58 20 62 65 67 69  ment when X begi
22ce0 6e 73 20 77 69 74 68 20 22 2d 2d 22 20 61 6e 64  ns with "--" and
22cf0 20 69 6e 76 6f 6b 69 6e 67 0a 2a 2a 20 5b 73 71   invoking.** [sq
22d00 6c 69 74 65 33 5f 65 78 70 61 6e 64 65 64 5f 73  lite3_expanded_s
22d10 71 6c 28 50 29 5d 20 6f 74 68 65 72 77 69 73 65  ql(P)] otherwise
22d20 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  ..**.** [[SQLITE
22d30 5f 54 52 41 43 45 5f 50 52 4f 46 49 4c 45 5d 5d  _TRACE_PROFILE]]
22d40 20 3c 64 74 3e 53 51 4c 49 54 45 5f 54 52 41 43   <dt>SQLITE_TRAC
22d50 45 5f 50 52 4f 46 49 4c 45 3c 2f 64 74 3e 0a 2a  E_PROFILE</dt>.*
22d60 2a 20 3c 64 64 3e 5e 41 6e 20 53 51 4c 49 54 45  * <dd>^An SQLITE
22d70 5f 54 52 41 43 45 5f 50 52 4f 46 49 4c 45 20 63  _TRACE_PROFILE c
22d80 61 6c 6c 62 61 63 6b 20 70 72 6f 76 69 64 65 73  allback provides
22d90 20 61 70 70 72 6f 78 69 6d 61 74 65 6c 79 20 74   approximately t
22da0 68 65 20 73 61 6d 65 0a 2a 2a 20 69 6e 66 6f 72  he same.** infor
22db0 6d 61 74 69 6f 6e 20 61 73 20 69 73 20 70 72 6f  mation as is pro
22dc0 76 69 64 65 64 20 62 79 20 74 68 65 20 5b 73 71  vided by the [sq
22dd0 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 29 5d  lite3_profile()]
22de0 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 5e 54   callback..** ^T
22df0 68 65 20 50 20 61 72 67 75 6d 65 6e 74 20 69 73  he P argument is
22e00 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   a pointer to th
22e10 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
22e20 65 6d 65 6e 74 5d 20 61 6e 64 20 74 68 65 0a 2a  ement] and the.*
22e30 2a 20 58 20 61 72 67 75 6d 65 6e 74 20 70 6f 69  * X argument poi
22e40 6e 74 73 20 74 6f 20 61 20 36 34 2d 62 69 74 20  nts to a 64-bit 
22e50 69 6e 74 65 67 65 72 20 77 68 69 63 68 20 69 73  integer which is
22e60 20 74 68 65 20 65 73 74 69 6d 61 74 65 64 20 6f   the estimated o
22e70 66 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20  f.** the number 
22e80 6f 66 20 6e 61 6e 6f 73 65 63 6f 6e 64 20 74 68  of nanosecond th
22e90 61 74 20 74 68 65 20 70 72 65 70 61 72 65 64 20  at the prepared 
22ea0 73 74 61 74 65 6d 65 6e 74 20 74 6f 6f 6b 20 74  statement took t
22eb0 6f 20 72 75 6e 2e 0a 2a 2a 20 5e 54 68 65 20 53  o run..** ^The S
22ec0 51 4c 49 54 45 5f 54 52 41 43 45 5f 50 52 4f 46  QLITE_TRACE_PROF
22ed0 49 4c 45 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  ILE callback is 
22ee0 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 74 68 65  invoked when the
22ef0 20 73 74 61 74 65 6d 65 6e 74 20 66 69 6e 69 73   statement finis
22f00 68 65 73 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  hes..**.** [[SQL
22f10 49 54 45 5f 54 52 41 43 45 5f 52 4f 57 5d 5d 20  ITE_TRACE_ROW]] 
22f20 3c 64 74 3e 53 51 4c 49 54 45 5f 54 52 41 43 45  <dt>SQLITE_TRACE
22f30 5f 52 4f 57 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  _ROW</dt>.** <dd
22f40 3e 5e 41 6e 20 53 51 4c 49 54 45 5f 54 52 41 43  >^An SQLITE_TRAC
22f50 45 5f 52 4f 57 20 63 61 6c 6c 62 61 63 6b 20 69  E_ROW callback i
22f60 73 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76  s invoked whenev
22f70 65 72 20 61 20 70 72 65 70 61 72 65 64 0a 2a 2a  er a prepared.**
22f80 20 73 74 61 74 65 6d 65 6e 74 20 67 65 6e 65 72   statement gener
22f90 61 74 65 73 20 61 20 73 69 6e 67 6c 65 20 72 6f  ates a single ro
22fa0 77 20 6f 66 20 72 65 73 75 6c 74 2e 20 20 0a 2a  w of result.  .*
22fb0 2a 20 5e 54 68 65 20 50 20 61 72 67 75 6d 65 6e  * ^The P argumen
22fc0 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  t is a pointer t
22fd0 6f 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20  o the [prepared 
22fe0 73 74 61 74 65 6d 65 6e 74 5d 20 61 6e 64 20 74  statement] and t
22ff0 68 65 0a 2a 2a 20 58 20 61 72 67 75 6d 65 6e 74  he.** X argument
23000 20 69 73 20 75 6e 75 73 65 64 2e 0a 2a 2a 0a 2a   is unused..**.*
23010 2a 20 5b 5b 53 51 4c 49 54 45 5f 54 52 41 43 45  * [[SQLITE_TRACE
23020 5f 43 4c 4f 53 45 5d 5d 20 3c 64 74 3e 53 51 4c  _CLOSE]] <dt>SQL
23030 49 54 45 5f 54 52 41 43 45 5f 43 4c 4f 53 45 3c  ITE_TRACE_CLOSE<
23040 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 5e 41 6e 20  /dt>.** <dd>^An 
23050 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 43 4c 4f  SQLITE_TRACE_CLO
23060 53 45 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69  SE callback is i
23070 6e 76 6f 6b 65 64 20 77 68 65 6e 20 61 20 64 61  nvoked when a da
23080 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63  tabase.** connec
23090 74 69 6f 6e 20 63 6c 6f 73 65 73 2e 0a 2a 2a 20  tion closes..** 
230a0 5e 54 68 65 20 50 20 61 72 67 75 6d 65 6e 74 20  ^The P argument 
230b0 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
230c0 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
230d0 6e 6e 65 63 74 69 6f 6e 5d 20 6f 62 6a 65 63 74  nnection] object
230e0 0a 2a 2a 20 61 6e 64 20 74 68 65 20 58 20 61 72  .** and the X ar
230f0 67 75 6d 65 6e 74 20 69 73 20 75 6e 75 73 65 64  gument is unused
23100 2e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64  ..** </dl>.*/.#d
23110 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 52 41  efine SQLITE_TRA
23120 43 45 5f 53 54 4d 54 20 20 20 20 20 20 20 30 78  CE_STMT       0x
23130 30 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  01.#define SQLIT
23140 45 5f 54 52 41 43 45 5f 50 52 4f 46 49 4c 45 20  E_TRACE_PROFILE 
23150 20 20 20 30 78 30 32 0a 23 64 65 66 69 6e 65 20     0x02.#define 
23160 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 52 4f 57  SQLITE_TRACE_ROW
23170 20 20 20 20 20 20 20 20 30 78 30 34 0a 23 64 65          0x04.#de
23180 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 52 41 43  fine SQLITE_TRAC
23190 45 5f 43 4c 4f 53 45 20 20 20 20 20 20 30 78 30  E_CLOSE      0x0
231a0 38 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  8../*.** CAPI3RE
231b0 46 3a 20 53 51 4c 20 54 72 61 63 65 20 48 6f 6f  F: SQL Trace Hoo
231c0 6b 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  k.** METHOD: sql
231d0 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ite3.**.** ^The 
231e0 73 71 6c 69 74 65 33 5f 74 72 61 63 65 5f 76 32  sqlite3_trace_v2
231f0 28 44 2c 4d 2c 58 2c 50 29 20 69 6e 74 65 72 66  (D,M,X,P) interf
23200 61 63 65 20 72 65 67 69 73 74 65 72 73 20 61 20  ace registers a 
23210 74 72 61 63 65 20 63 61 6c 6c 62 61 63 6b 0a 2a  trace callback.*
23220 2a 20 66 75 6e 63 74 69 6f 6e 20 58 20 61 67 61  * function X aga
23230 69 6e 73 74 20 5b 64 61 74 61 62 61 73 65 20 63  inst [database c
23240 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 2c 20 75 73  onnection] D, us
23250 69 6e 67 20 70 72 6f 70 65 72 74 79 20 6d 61 73  ing property mas
23260 6b 20 4d 0a 2a 2a 20 61 6e 64 20 63 6f 6e 74 65  k M.** and conte
23270 78 74 20 70 6f 69 6e 74 65 72 20 50 2e 20 20 5e  xt pointer P.  ^
23280 49 66 20 74 68 65 20 58 20 63 61 6c 6c 62 61 63  If the X callbac
23290 6b 20 69 73 0a 2a 2a 20 4e 55 4c 4c 20 6f 72 20  k is.** NULL or 
232a0 69 66 20 74 68 65 20 4d 20 6d 61 73 6b 20 69 73  if the M mask is
232b0 20 7a 65 72 6f 2c 20 74 68 65 6e 20 74 72 61 63   zero, then trac
232c0 69 6e 67 20 69 73 20 64 69 73 61 62 6c 65 64 2e  ing is disabled.
232d0 20 20 54 68 65 0a 2a 2a 20 4d 20 61 72 67 75 6d    The.** M argum
232e0 65 6e 74 20 73 68 6f 75 6c 64 20 62 65 20 74 68  ent should be th
232f0 65 20 62 69 74 77 69 73 65 20 4f 52 2d 65 64 20  e bitwise OR-ed 
23300 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 6f 66 0a 2a  combination of.*
23310 2a 20 7a 65 72 6f 20 6f 72 20 6d 6f 72 65 20 5b  * zero or more [
23320 53 51 4c 49 54 45 5f 54 52 41 43 45 5d 20 63 6f  SQLITE_TRACE] co
23330 6e 73 74 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e  nstants..**.** ^
23340 45 61 63 68 20 63 61 6c 6c 20 74 6f 20 65 69 74  Each call to eit
23350 68 65 72 20 73 71 6c 69 74 65 33 5f 74 72 61 63  her sqlite3_trac
23360 65 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 74  e() or sqlite3_t
23370 72 61 63 65 5f 76 32 28 29 20 6f 76 65 72 72 69  race_v2() overri
23380 64 65 73 20 0a 2a 2a 20 28 63 61 6e 63 65 6c 73  des .** (cancels
23390 29 20 61 6e 79 20 70 72 69 6f 72 20 63 61 6c 6c  ) any prior call
233a0 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 74 72 61  s to sqlite3_tra
233b0 63 65 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  ce() or sqlite3_
233c0 74 72 61 63 65 5f 76 32 28 29 2e 0a 2a 2a 0a 2a  trace_v2()..**.*
233d0 2a 20 5e 54 68 65 20 58 20 63 61 6c 6c 62 61 63  * ^The X callbac
233e0 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 68 65  k is invoked whe
233f0 6e 65 76 65 72 20 61 6e 79 20 6f 66 20 74 68 65  never any of the
23400 20 65 76 65 6e 74 73 20 69 64 65 6e 74 69 66 69   events identifi
23410 65 64 20 62 79 20 0a 2a 2a 20 6d 61 73 6b 20 4d  ed by .** mask M
23420 20 6f 63 63 75 72 2e 20 20 5e 54 68 65 20 69 6e   occur.  ^The in
23430 74 65 67 65 72 20 72 65 74 75 72 6e 20 76 61 6c  teger return val
23440 75 65 20 66 72 6f 6d 20 74 68 65 20 63 61 6c 6c  ue from the call
23450 62 61 63 6b 20 69 73 20 63 75 72 72 65 6e 74 6c  back is currentl
23460 79 0a 2a 2a 20 69 67 6e 6f 72 65 64 2c 20 74 68  y.** ignored, th
23470 6f 75 67 68 20 74 68 69 73 20 6d 61 79 20 63 68  ough this may ch
23480 61 6e 67 65 20 69 6e 20 66 75 74 75 72 65 20 72  ange in future r
23490 65 6c 65 61 73 65 73 2e 20 20 43 61 6c 6c 62 61  eleases.  Callba
234a0 63 6b 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61  ck.** implementa
234b0 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 72 65 74  tions should ret
234c0 75 72 6e 20 7a 65 72 6f 20 74 6f 20 65 6e 73 75  urn zero to ensu
234d0 72 65 20 66 75 74 75 72 65 20 63 6f 6d 70 61 74  re future compat
234e0 69 62 69 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e  ibility..**.** ^
234f0 41 20 74 72 61 63 65 20 63 61 6c 6c 62 61 63 6b  A trace callback
23500 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 69 74 68   is invoked with
23510 20 66 6f 75 72 20 61 72 67 75 6d 65 6e 74 73 3a   four arguments:
23520 20 63 61 6c 6c 62 61 63 6b 28 54 2c 43 2c 50 2c   callback(T,C,P,
23530 58 29 2e 0a 2a 2a 20 5e 54 68 65 20 54 20 61 72  X)..** ^The T ar
23540 67 75 6d 65 6e 74 20 69 73 20 6f 6e 65 20 6f 66  gument is one of
23550 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 52 41   the [SQLITE_TRA
23560 43 45 5d 0a 2a 2a 20 63 6f 6e 73 74 61 6e 74 73  CE].** constants
23570 20 74 6f 20 69 6e 64 69 63 61 74 65 20 77 68 79   to indicate why
23580 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 77 61   the callback wa
23590 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 20 5e 54  s invoked..** ^T
235a0 68 65 20 43 20 61 72 67 75 6d 65 6e 74 20 69 73  he C argument is
235b0 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 63   a copy of the c
235c0 6f 6e 74 65 78 74 20 70 6f 69 6e 74 65 72 2e 0a  ontext pointer..
235d0 2a 2a 20 54 68 65 20 50 20 61 6e 64 20 58 20 61  ** The P and X a
235e0 72 67 75 6d 65 6e 74 73 20 61 72 65 20 70 6f 69  rguments are poi
235f0 6e 74 65 72 73 20 77 68 6f 73 65 20 6d 65 61 6e  nters whose mean
23600 69 6e 67 73 20 64 65 70 65 6e 64 20 6f 6e 20 54  ings depend on T
23610 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
23620 74 65 33 5f 74 72 61 63 65 5f 76 32 28 29 20 69  te3_trace_v2() i
23630 6e 74 65 72 66 61 63 65 20 69 73 20 69 6e 74 65  nterface is inte
23640 6e 64 65 64 20 74 6f 20 72 65 70 6c 61 63 65 20  nded to replace 
23650 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e  the legacy.** in
23660 74 65 72 66 61 63 65 73 20 5b 73 71 6c 69 74 65  terfaces [sqlite
23670 33 5f 74 72 61 63 65 28 29 5d 20 61 6e 64 20 5b  3_trace()] and [
23680 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28  sqlite3_profile(
23690 29 5d 2c 20 62 6f 74 68 20 6f 66 20 77 68 69 63  )], both of whic
236a0 68 0a 2a 2a 20 61 72 65 20 64 65 70 72 65 63 61  h.** are depreca
236b0 74 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ted..*/.int sqli
236c0 74 65 33 5f 74 72 61 63 65 5f 76 32 28 0a 20 20  te3_trace_v2(.  
236d0 73 71 6c 69 74 65 33 2a 2c 0a 20 20 75 6e 73 69  sqlite3*,.  unsi
236e0 67 6e 65 64 20 75 4d 61 73 6b 2c 0a 20 20 69 6e  gned uMask,.  in
236f0 74 28 2a 78 43 61 6c 6c 62 61 63 6b 29 28 75 6e  t(*xCallback)(un
23700 73 69 67 6e 65 64 2c 76 6f 69 64 2a 2c 76 6f 69  signed,void*,voi
23710 64 2a 2c 76 6f 69 64 2a 29 2c 0a 20 20 76 6f 69  d*,void*),.  voi
23720 64 20 2a 70 43 74 78 0a 29 3b 0a 0a 2f 2a 0a 2a  d *pCtx.);../*.*
23730 2a 20 43 41 50 49 33 52 45 46 3a 20 51 75 65 72  * CAPI3REF: Quer
23740 79 20 50 72 6f 67 72 65 73 73 20 43 61 6c 6c 62  y Progress Callb
23750 61 63 6b 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  acks.** METHOD: 
23760 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54  sqlite3.**.** ^T
23770 68 65 20 73 71 6c 69 74 65 33 5f 70 72 6f 67 72  he sqlite3_progr
23780 65 73 73 5f 68 61 6e 64 6c 65 72 28 44 2c 4e 2c  ess_handler(D,N,
23790 58 2c 50 29 20 69 6e 74 65 72 66 61 63 65 20 63  X,P) interface c
237a0 61 75 73 65 73 20 74 68 65 20 63 61 6c 6c 62 61  auses the callba
237b0 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 58  ck.** function X
237c0 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 70   to be invoked p
237d0 65 72 69 6f 64 69 63 61 6c 6c 79 20 64 75 72 69  eriodically duri
237e0 6e 67 20 6c 6f 6e 67 20 72 75 6e 6e 69 6e 67 20  ng long running 
237f0 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c  calls to.** [sql
23800 69 74 65 33 5f 65 78 65 63 28 29 5d 2c 20 5b 73  ite3_exec()], [s
23810 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 61  qlite3_step()] a
23820 6e 64 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f  nd [sqlite3_get_
23830 74 61 62 6c 65 28 29 5d 20 66 6f 72 0a 2a 2a 20  table()] for.** 
23840 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
23850 69 6f 6e 20 44 2e 20 20 41 6e 20 65 78 61 6d 70  ion D.  An examp
23860 6c 65 20 75 73 65 20 66 6f 72 20 74 68 69 73 0a  le use for this.
23870 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  ** interface is 
23880 74 6f 20 6b 65 65 70 20 61 20 47 55 49 20 75 70  to keep a GUI up
23890 64 61 74 65 64 20 64 75 72 69 6e 67 20 61 20 6c  dated during a l
238a0 61 72 67 65 20 71 75 65 72 79 2e 0a 2a 2a 0a 2a  arge query..**.*
238b0 2a 20 5e 54 68 65 20 70 61 72 61 6d 65 74 65 72  * ^The parameter
238c0 20 50 20 69 73 20 70 61 73 73 65 64 20 74 68 72   P is passed thr
238d0 6f 75 67 68 20 61 73 20 74 68 65 20 6f 6e 6c 79  ough as the only
238e0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
238f0 65 20 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 66  e .** callback f
23900 75 6e 63 74 69 6f 6e 20 58 2e 20 20 5e 54 68 65  unction X.  ^The
23910 20 70 61 72 61 6d 65 74 65 72 20 4e 20 69 73 20   parameter N is 
23920 74 68 65 20 61 70 70 72 6f 78 69 6d 61 74 65 20  the approximate 
23930 6e 75 6d 62 65 72 20 6f 66 20 0a 2a 2a 20 5b 76  number of .** [v
23940 69 72 74 75 61 6c 20 6d 61 63 68 69 6e 65 20 69  irtual machine i
23950 6e 73 74 72 75 63 74 69 6f 6e 73 5d 20 74 68 61  nstructions] tha
23960 74 20 61 72 65 20 65 76 61 6c 75 61 74 65 64 20  t are evaluated 
23970 62 65 74 77 65 65 6e 20 73 75 63 63 65 73 73 69  between successi
23980 76 65 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e  ve.** invocation
23990 73 20 6f 66 20 74 68 65 20 63 61 6c 6c 62 61 63  s of the callbac
239a0 6b 20 58 2e 20 20 5e 49 66 20 4e 20 69 73 20 6c  k X.  ^If N is l
239b0 65 73 73 20 74 68 61 6e 20 6f 6e 65 20 74 68 65  ess than one the
239c0 6e 20 74 68 65 20 70 72 6f 67 72 65 73 73 0a 2a  n the progress.*
239d0 2a 20 68 61 6e 64 6c 65 72 20 69 73 20 64 69 73  * handler is dis
239e0 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e  abled..**.** ^On
239f0 6c 79 20 61 20 73 69 6e 67 6c 65 20 70 72 6f 67  ly a single prog
23a00 72 65 73 73 20 68 61 6e 64 6c 65 72 20 6d 61 79  ress handler may
23a10 20 62 65 20 64 65 66 69 6e 65 64 20 61 74 20 6f   be defined at o
23a20 6e 65 20 74 69 6d 65 20 70 65 72 0a 2a 2a 20 5b  ne time per.** [
23a30 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
23a40 69 6f 6e 5d 3b 20 73 65 74 74 69 6e 67 20 61 20  ion]; setting a 
23a50 6e 65 77 20 70 72 6f 67 72 65 73 73 20 68 61 6e  new progress han
23a60 64 6c 65 72 20 63 61 6e 63 65 6c 73 20 74 68 65  dler cancels the
23a70 0a 2a 2a 20 6f 6c 64 20 6f 6e 65 2e 20 20 5e 53  .** old one.  ^S
23a80 65 74 74 69 6e 67 20 70 61 72 61 6d 65 74 65 72  etting parameter
23a90 20 58 20 74 6f 20 4e 55 4c 4c 20 64 69 73 61 62   X to NULL disab
23aa0 6c 65 73 20 74 68 65 20 70 72 6f 67 72 65 73 73  les the progress
23ab0 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 5e 54 68   handler..** ^Th
23ac0 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c  e progress handl
23ad0 65 72 20 69 73 20 61 6c 73 6f 20 64 69 73 61 62  er is also disab
23ae0 6c 65 64 20 62 79 20 73 65 74 74 69 6e 67 20 4e  led by setting N
23af0 20 74 6f 20 61 20 76 61 6c 75 65 20 6c 65 73 73   to a value less
23b00 0a 2a 2a 20 74 68 61 6e 20 31 2e 0a 2a 2a 0a 2a  .** than 1..**.*
23b10 2a 20 5e 49 66 20 74 68 65 20 70 72 6f 67 72 65  * ^If the progre
23b20 73 73 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  ss callback retu
23b30 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68  rns non-zero, th
23b40 65 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 0a 2a  e operation is.*
23b50 2a 20 69 6e 74 65 72 72 75 70 74 65 64 2e 20 20  * interrupted.  
23b60 54 68 69 73 20 66 65 61 74 75 72 65 20 63 61 6e  This feature can
23b70 20 62 65 20 75 73 65 64 20 74 6f 20 69 6d 70 6c   be used to impl
23b80 65 6d 65 6e 74 20 61 0a 2a 2a 20 22 43 61 6e 63  ement a.** "Canc
23b90 65 6c 22 20 62 75 74 74 6f 6e 20 6f 6e 20 61 20  el" button on a 
23ba0 47 55 49 20 70 72 6f 67 72 65 73 73 20 64 69 61  GUI progress dia
23bb0 6c 6f 67 20 62 6f 78 2e 0a 2a 2a 0a 2a 2a 20 54  log box..**.** T
23bc0 68 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64  he progress hand
23bd0 6c 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d 75 73  ler callback mus
23be0 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e  t not do anythin
23bf0 67 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69  g that will modi
23c00 66 79 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61  fy.** the databa
23c10 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68  se connection th
23c20 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 70  at invoked the p
23c30 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 2e  rogress handler.
23c40 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b 73  .** Note that [s
23c50 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
23c60 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  2()] and [sqlite
23c70 33 5f 73 74 65 70 28 29 5d 20 62 6f 74 68 20 6d  3_step()] both m
23c80 6f 64 69 66 79 20 74 68 65 69 72 0a 2a 2a 20 64  odify their.** d
23c90 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
23ca0 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d 65 61 6e  ons for the mean
23cb0 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79 22 20  ing of "modify" 
23cc0 69 6e 20 74 68 69 73 20 70 61 72 61 67 72 61 70  in this paragrap
23cd0 68 2e 0a 2a 2a 0a 2a 2f 0a 76 6f 69 64 20 73 71  h..**.*/.void sq
23ce0 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73 5f 68  lite3_progress_h
23cf0 61 6e 64 6c 65 72 28 73 71 6c 69 74 65 33 2a 2c  andler(sqlite3*,
23d00 20 69 6e 74 2c 20 69 6e 74 28 2a 29 28 76 6f 69   int, int(*)(voi
23d10 64 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a  d*), void*);../*
23d20 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 70  .** CAPI3REF: Op
23d30 65 6e 69 6e 67 20 41 20 4e 65 77 20 44 61 74 61  ening A New Data
23d40 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 0a  base Connection.
23d50 2a 2a 20 43 4f 4e 53 54 52 55 43 54 4f 52 3a 20  ** CONSTRUCTOR: 
23d60 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54  sqlite3.**.** ^T
23d70 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 70  hese routines op
23d80 65 6e 20 61 6e 20 53 51 4c 69 74 65 20 64 61 74  en an SQLite dat
23d90 61 62 61 73 65 20 66 69 6c 65 20 61 73 20 73 70  abase file as sp
23da0 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20 0a  ecified by the .
23db0 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75  ** filename argu
23dc0 6d 65 6e 74 2e 20 5e 54 68 65 20 66 69 6c 65 6e  ment. ^The filen
23dd0 61 6d 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20  ame argument is 
23de0 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 55  interpreted as U
23df0 54 46 2d 38 20 66 6f 72 0a 2a 2a 20 73 71 6c 69  TF-8 for.** sqli
23e00 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73  te3_open() and s
23e10 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
23e20 20 61 6e 64 20 61 73 20 55 54 46 2d 31 36 20 69   and as UTF-16 i
23e30 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 74  n the native byt
23e40 65 0a 2a 2a 20 6f 72 64 65 72 20 66 6f 72 20 73  e.** order for s
23e50 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e  qlite3_open16().
23e60 20 5e 28 41 20 5b 64 61 74 61 62 61 73 65 20 63   ^(A [database c
23e70 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c  onnection] handl
23e80 65 20 69 73 20 75 73 75 61 6c 6c 79 0a 2a 2a 20  e is usually.** 
23e90 72 65 74 75 72 6e 65 64 20 69 6e 20 2a 70 70 44  returned in *ppD
23ea0 62 2c 20 65 76 65 6e 20 69 66 20 61 6e 20 65 72  b, even if an er
23eb0 72 6f 72 20 6f 63 63 75 72 73 2e 20 20 54 68 65  ror occurs.  The
23ec0 20 6f 6e 6c 79 20 65 78 63 65 70 74 69 6f 6e 20   only exception 
23ed0 69 73 20 74 68 61 74 0a 2a 2a 20 69 66 20 53 51  is that.** if SQ
23ee0 4c 69 74 65 20 69 73 20 75 6e 61 62 6c 65 20 74  Lite is unable t
23ef0 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72  o allocate memor
23f00 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 5b 73  y to hold the [s
23f10 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 2c 0a  qlite3] object,.
23f20 2a 2a 20 61 20 4e 55 4c 4c 20 77 69 6c 6c 20 62  ** a NULL will b
23f30 65 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 2a  e written into *
23f40 70 70 44 62 20 69 6e 73 74 65 61 64 20 6f 66 20  ppDb instead of 
23f50 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
23f60 20 5b 73 71 6c 69 74 65 33 5d 0a 2a 2a 20 6f 62   [sqlite3].** ob
23f70 6a 65 63 74 2e 29 5e 20 5e 28 49 66 20 74 68 65  ject.)^ ^(If the
23f80 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65   database is ope
23f90 6e 65 64 20 28 61 6e 64 2f 6f 72 20 63 72 65 61  ned (and/or crea
23fa0 74 65 64 29 20 73 75 63 63 65 73 73 66 75 6c 6c  ted) successfull
23fb0 79 2c 20 74 68 65 6e 0a 2a 2a 20 5b 53 51 4c 49  y, then.** [SQLI
23fc0 54 45 5f 4f 4b 5d 20 69 73 20 72 65 74 75 72 6e  TE_OK] is return
23fd0 65 64 2e 20 20 4f 74 68 65 72 77 69 73 65 20 61  ed.  Otherwise a
23fe0 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69  n [error code] i
23ff0 73 20 72 65 74 75 72 6e 65 64 2e 29 5e 20 5e 54  s returned.)^ ^T
24000 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65  he.** [sqlite3_e
24010 72 72 6d 73 67 28 29 5d 20 6f 72 20 5b 73 71 6c  rrmsg()] or [sql
24020 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29 5d  ite3_errmsg16()]
24030 20 72 6f 75 74 69 6e 65 73 20 63 61 6e 20 62 65   routines can be
24040 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 0a   used to obtain.
24050 2a 2a 20 61 6e 20 45 6e 67 6c 69 73 68 20 6c 61  ** an English la
24060 6e 67 75 61 67 65 20 64 65 73 63 72 69 70 74 69  nguage descripti
24070 6f 6e 20 6f 66 20 74 68 65 20 65 72 72 6f 72 20  on of the error 
24080 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 66 61 69 6c  following a fail
24090 75 72 65 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66  ure of any.** of
240a0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 6f 70 65   the sqlite3_ope
240b0 6e 28 29 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a  n() routines..**
240c0 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c 74  .** ^The default
240d0 20 65 6e 63 6f 64 69 6e 67 20 77 69 6c 6c 20 62   encoding will b
240e0 65 20 55 54 46 2d 38 20 66 6f 72 20 64 61 74 61  e UTF-8 for data
240f0 62 61 73 65 73 20 63 72 65 61 74 65 64 20 75 73  bases created us
24100 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f  ing.** sqlite3_o
24110 70 65 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33  pen() or sqlite3
24120 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 20 5e 54 68  _open_v2().  ^Th
24130 65 20 64 65 66 61 75 6c 74 20 65 6e 63 6f 64 69  e default encodi
24140 6e 67 20 66 6f 72 20 64 61 74 61 62 61 73 65 73  ng for databases
24150 0a 2a 2a 20 63 72 65 61 74 65 64 20 75 73 69 6e  .** created usin
24160 67 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36  g sqlite3_open16
24170 28 29 20 77 69 6c 6c 20 62 65 20 55 54 46 2d 31  () will be UTF-1
24180 36 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20  6 in the native 
24190 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2a 0a 2a  byte order..**.*
241a0 2a 20 57 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  * Whether or not
241b0 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73   an error occurs
241c0 20 77 68 65 6e 20 69 74 20 69 73 20 6f 70 65 6e   when it is open
241d0 65 64 2c 20 72 65 73 6f 75 72 63 65 73 0a 2a 2a  ed, resources.**
241e0 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
241f0 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
24200 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c  onnection] handl
24210 65 20 73 68 6f 75 6c 64 20 62 65 20 72 65 6c 65  e should be rele
24220 61 73 65 64 20 62 79 0a 2a 2a 20 70 61 73 73 69  ased by.** passi
24230 6e 67 20 69 74 20 74 6f 20 5b 73 71 6c 69 74 65  ng it to [sqlite
24240 33 5f 63 6c 6f 73 65 28 29 5d 20 77 68 65 6e 20  3_close()] when 
24250 69 74 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20  it is no longer 
24260 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20  required..**.** 
24270 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  The sqlite3_open
24280 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63 65 20  _v2() interface 
24290 77 6f 72 6b 73 20 6c 69 6b 65 20 73 71 6c 69 74  works like sqlit
242a0 65 33 5f 6f 70 65 6e 28 29 0a 2a 2a 20 65 78 63  e3_open().** exc
242b0 65 70 74 20 74 68 61 74 20 69 74 20 61 63 63 65  ept that it acce
242c0 70 74 73 20 74 77 6f 20 61 64 64 69 74 69 6f 6e  pts two addition
242d0 61 6c 20 70 61 72 61 6d 65 74 65 72 73 20 66 6f  al parameters fo
242e0 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 63 6f 6e  r additional con
242f0 74 72 6f 6c 0a 2a 2a 20 6f 76 65 72 20 74 68 65  trol.** over the
24300 20 6e 65 77 20 64 61 74 61 62 61 73 65 20 63 6f   new database co
24310 6e 6e 65 63 74 69 6f 6e 2e 20 20 5e 28 54 68 65  nnection.  ^(The
24320 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72   flags parameter
24330 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f   to.** sqlite3_o
24340 70 65 6e 5f 76 32 28 29 20 63 61 6e 20 74 61 6b  pen_v2() can tak
24350 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 74 68 65 20  e one of.** the 
24360 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 72 65 65 20  following three 
24370 76 61 6c 75 65 73 2c 20 6f 70 74 69 6f 6e 61 6c  values, optional
24380 6c 79 20 63 6f 6d 62 69 6e 65 64 20 77 69 74 68  ly combined with
24390 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45   the .** [SQLITE
243a0 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 2c 20  _OPEN_NOMUTEX], 
243b0 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c  [SQLITE_OPEN_FUL
243c0 4c 4d 55 54 45 58 5d 2c 20 5b 53 51 4c 49 54 45  LMUTEX], [SQLITE
243d0 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48  _OPEN_SHAREDCACH
243e0 45 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f  E],.** [SQLITE_O
243f0 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45  PEN_PRIVATECACHE
24400 5d 2c 20 61 6e 64 2f 6f 72 20 5b 53 51 4c 49 54  ], and/or [SQLIT
24410 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 66 6c 61 67  E_OPEN_URI] flag
24420 73 3a 29 5e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a  s:)^.**.** <dl>.
24430 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 45  ** ^(<dt>[SQLITE
24440 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 3c  _OPEN_READONLY]<
24450 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
24460 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e  database is open
24470 65 64 20 69 6e 20 72 65 61 64 2d 6f 6e 6c 79 20  ed in read-only 
24480 6d 6f 64 65 2e 20 20 49 66 20 74 68 65 20 64 61  mode.  If the da
24490 74 61 62 61 73 65 20 64 6f 65 73 20 6e 6f 74 0a  tabase does not.
244a0 2a 2a 20 61 6c 72 65 61 64 79 20 65 78 69 73 74  ** already exist
244b0 2c 20 61 6e 20 65 72 72 6f 72 20 69 73 20 72 65  , an error is re
244c0 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e 0a 2a  turned.</dd>)^.*
244d0 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49  *.** ^(<dt>[SQLI
244e0 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54  TE_OPEN_READWRIT
244f0 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  E]</dt>.** <dd>T
24500 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f  he database is o
24510 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64 69 6e  pened for readin
24520 67 20 61 6e 64 20 77 72 69 74 69 6e 67 20 69 66  g and writing if
24530 20 70 6f 73 73 69 62 6c 65 2c 20 6f 72 20 72 65   possible, or re
24540 61 64 69 6e 67 0a 2a 2a 20 6f 6e 6c 79 20 69 66  ading.** only if
24550 20 74 68 65 20 66 69 6c 65 20 69 73 20 77 72 69   the file is wri
24560 74 65 20 70 72 6f 74 65 63 74 65 64 20 62 79 20  te protected by 
24570 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79  the operating sy
24580 73 74 65 6d 2e 20 20 49 6e 20 65 69 74 68 65 72  stem.  In either
24590 0a 2a 2a 20 63 61 73 65 20 74 68 65 20 64 61 74  .** case the dat
245a0 61 62 61 73 65 20 6d 75 73 74 20 61 6c 72 65 61  abase must alrea
245b0 64 79 20 65 78 69 73 74 2c 20 6f 74 68 65 72 77  dy exist, otherw
245c0 69 73 65 20 61 6e 20 65 72 72 6f 72 20 69 73 20  ise an error is 
245d0 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e  returned.</dd>)^
245e0 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51  .**.** ^(<dt>[SQ
245f0 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52  LITE_OPEN_READWR
24600 49 54 45 5d 20 7c 20 5b 53 51 4c 49 54 45 5f 4f  ITE] | [SQLITE_O
24610 50 45 4e 5f 43 52 45 41 54 45 5d 3c 2f 64 74 3e  PEN_CREATE]</dt>
24620 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 74 61  .** <dd>The data
24630 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66  base is opened f
24640 6f 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20 77  or reading and w
24650 72 69 74 69 6e 67 2c 20 61 6e 64 20 69 73 20 63  riting, and is c
24660 72 65 61 74 65 64 20 69 66 0a 2a 2a 20 69 74 20  reated if.** it 
24670 64 6f 65 73 20 6e 6f 74 20 61 6c 72 65 61 64 79  does not already
24680 20 65 78 69 73 74 2e 20 54 68 69 73 20 69 73 20   exist. This is 
24690 74 68 65 20 62 65 68 61 76 69 6f 72 20 74 68 61  the behavior tha
246a0 74 20 69 73 20 61 6c 77 61 79 73 20 75 73 65 64  t is always used
246b0 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   for.** sqlite3_
246c0 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 74  open() and sqlit
246d0 65 33 5f 6f 70 65 6e 31 36 28 29 2e 3c 2f 64 64  e3_open16().</dd
246e0 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2a 0a  >)^.** </dl>.**.
246f0 2a 2a 20 49 66 20 74 68 65 20 33 72 64 20 70 61  ** If the 3rd pa
24700 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
24710 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20  e3_open_v2() is 
24720 6e 6f 74 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a  not one of the.*
24730 2a 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 73 20 73  * combinations s
24740 68 6f 77 6e 20 61 62 6f 76 65 20 6f 70 74 69 6f  hown above optio
24750 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e 65 64 20 77  nally combined w
24760 69 74 68 20 6f 74 68 65 72 0a 2a 2a 20 5b 53 51  ith other.** [SQ
24770 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e  LITE_OPEN_READON
24780 4c 59 20 7c 20 53 51 4c 49 54 45 5f 4f 50 45 4e  LY | SQLITE_OPEN
24790 5f 2a 20 62 69 74 73 5d 0a 2a 2a 20 74 68 65 6e  _* bits].** then
247a0 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73   the behavior is
247b0 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a   undefined..**.*
247c0 2a 20 5e 49 66 20 74 68 65 20 5b 53 51 4c 49 54  * ^If the [SQLIT
247d0 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 20  E_OPEN_NOMUTEX] 
247e0 66 6c 61 67 20 69 73 20 73 65 74 2c 20 74 68 65  flag is set, the
247f0 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  n the database c
24800 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f 70 65  onnection.** ope
24810 6e 73 20 69 6e 20 74 68 65 20 6d 75 6c 74 69 2d  ns in the multi-
24820 74 68 72 65 61 64 20 5b 74 68 72 65 61 64 69 6e  thread [threadin
24830 67 20 6d 6f 64 65 5d 20 61 73 20 6c 6f 6e 67 20  g mode] as long 
24840 61 73 20 74 68 65 20 73 69 6e 67 6c 65 2d 74 68  as the single-th
24850 72 65 61 64 0a 2a 2a 20 6d 6f 64 65 20 68 61 73  read.** mode has
24860 20 6e 6f 74 20 62 65 65 6e 20 73 65 74 20 61 74   not been set at
24870 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 72   compile-time or
24880 20 73 74 61 72 74 2d 74 69 6d 65 2e 20 20 5e 49   start-time.  ^I
24890 66 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45  f the.** [SQLITE
248a0 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d  _OPEN_FULLMUTEX]
248b0 20 66 6c 61 67 20 69 73 20 73 65 74 20 74 68 65   flag is set the
248c0 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  n the database c
248d0 6f 6e 6e 65 63 74 69 6f 6e 20 6f 70 65 6e 73 0a  onnection opens.
248e0 2a 2a 20 69 6e 20 74 68 65 20 73 65 72 69 61 6c  ** in the serial
248f0 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e 67 20  ized [threading 
24900 6d 6f 64 65 5d 20 75 6e 6c 65 73 73 20 73 69 6e  mode] unless sin
24910 67 6c 65 2d 74 68 72 65 61 64 20 77 61 73 0a 2a  gle-thread was.*
24920 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 73 65 6c  * previously sel
24930 65 63 74 65 64 20 61 74 20 63 6f 6d 70 69 6c 65  ected at compile
24940 2d 74 69 6d 65 20 6f 72 20 73 74 61 72 74 2d 74  -time or start-t
24950 69 6d 65 2e 0a 2a 2a 20 5e 54 68 65 20 5b 53 51  ime..** ^The [SQ
24960 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44  LITE_OPEN_SHARED
24970 43 41 43 48 45 5d 20 66 6c 61 67 20 63 61 75 73  CACHE] flag caus
24980 65 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20  es the database 
24990 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 62 65  connection to be
249a0 0a 2a 2a 20 65 6c 69 67 69 62 6c 65 20 74 6f 20  .** eligible to 
249b0 75 73 65 20 5b 73 68 61 72 65 64 20 63 61 63 68  use [shared cach
249c0 65 20 6d 6f 64 65 5d 2c 20 72 65 67 61 72 64 6c  e mode], regardl
249d0 65 73 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f  ess of whether o
249e0 72 20 6e 6f 74 20 73 68 61 72 65 64 0a 2a 2a 20  r not shared.** 
249f0 63 61 63 68 65 20 69 73 20 65 6e 61 62 6c 65 64  cache is enabled
24a00 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
24a10 65 6e 61 62 6c 65 5f 73 68 61 72 65 64 5f 63 61  enable_shared_ca
24a20 63 68 65 28 29 5d 2e 20 20 5e 54 68 65 0a 2a 2a  che()].  ^The.**
24a30 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52   [SQLITE_OPEN_PR
24a40 49 56 41 54 45 43 41 43 48 45 5d 20 66 6c 61 67  IVATECACHE] flag
24a50 20 63 61 75 73 65 73 20 74 68 65 20 64 61 74 61   causes the data
24a60 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
24a70 74 6f 20 6e 6f 74 0a 2a 2a 20 70 61 72 74 69 63  to not.** partic
24a80 69 70 61 74 65 20 69 6e 20 5b 73 68 61 72 65 64  ipate in [shared
24a90 20 63 61 63 68 65 20 6d 6f 64 65 5d 20 65 76 65   cache mode] eve
24aa0 6e 20 69 66 20 69 74 20 69 73 20 65 6e 61 62 6c  n if it is enabl
24ab0 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66  ed..**.** ^The f
24ac0 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
24ad0 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  to sqlite3_open_
24ae0 76 32 28 29 20 69 73 20 74 68 65 20 6e 61 6d 65  v2() is the name
24af0 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69   of the.** [sqli
24b00 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20  te3_vfs] object 
24b10 74 68 61 74 20 64 65 66 69 6e 65 73 20 74 68 65  that defines the
24b20 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65   operating syste
24b30 6d 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74  m interface that
24b40 0a 2a 2a 20 74 68 65 20 6e 65 77 20 64 61 74 61  .** the new data
24b50 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
24b60 73 68 6f 75 6c 64 20 75 73 65 2e 20 20 5e 49 66  should use.  ^If
24b70 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61   the fourth para
24b80 6d 65 74 65 72 20 69 73 0a 2a 2a 20 61 20 4e 55  meter is.** a NU
24b90 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20  LL pointer then 
24ba0 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c  the default [sql
24bb0 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74  ite3_vfs] object
24bc0 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20   is used..**.** 
24bd0 5e 49 66 20 74 68 65 20 66 69 6c 65 6e 61 6d 65  ^If the filename
24be0 20 69 73 20 22 3a 6d 65 6d 6f 72 79 3a 22 2c 20   is ":memory:", 
24bf0 74 68 65 6e 20 61 20 70 72 69 76 61 74 65 2c 20  then a private, 
24c00 74 65 6d 70 6f 72 61 72 79 20 69 6e 2d 6d 65 6d  temporary in-mem
24c10 6f 72 79 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  ory database.** 
24c20 69 73 20 63 72 65 61 74 65 64 20 66 6f 72 20 74  is created for t
24c30 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20  he connection.  
24c40 5e 54 68 69 73 20 69 6e 2d 6d 65 6d 6f 72 79 20  ^This in-memory 
24c50 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 76 61  database will va
24c60 6e 69 73 68 20 77 68 65 6e 0a 2a 2a 20 74 68 65  nish when.** the
24c70 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
24c80 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e 20  tion is closed. 
24c90 20 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73   Future versions
24ca0 20 6f 66 20 53 51 4c 69 74 65 20 6d 69 67 68 74   of SQLite might
24cb0 0a 2a 2a 20 6d 61 6b 65 20 75 73 65 20 6f 66 20  .** make use of 
24cc0 61 64 64 69 74 69 6f 6e 61 6c 20 73 70 65 63 69  additional speci
24cd0 61 6c 20 66 69 6c 65 6e 61 6d 65 73 20 74 68 61  al filenames tha
24ce0 74 20 62 65 67 69 6e 20 77 69 74 68 20 74 68 65  t begin with the
24cf0 20 22 3a 22 20 63 68 61 72 61 63 74 65 72 2e 0a   ":" character..
24d00 2a 2a 20 49 74 20 69 73 20 72 65 63 6f 6d 6d 65  ** It is recomme
24d10 6e 64 65 64 20 74 68 61 74 20 77 68 65 6e 20 61  nded that when a
24d20 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61   database filena
24d30 6d 65 20 61 63 74 75 61 6c 6c 79 20 64 6f 65 73  me actually does
24d40 20 62 65 67 69 6e 20 77 69 74 68 0a 2a 2a 20 61   begin with.** a
24d50 20 22 3a 22 20 63 68 61 72 61 63 74 65 72 20 79   ":" character y
24d60 6f 75 20 73 68 6f 75 6c 64 20 70 72 65 66 69 78  ou should prefix
24d70 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 77 69   the filename wi
24d80 74 68 20 61 20 70 61 74 68 6e 61 6d 65 20 73 75  th a pathname su
24d90 63 68 20 61 73 0a 2a 2a 20 22 2e 2f 22 20 74 6f  ch as.** "./" to
24da0 20 61 76 6f 69 64 20 61 6d 62 69 67 75 69 74 79   avoid ambiguity
24db0 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
24dc0 66 69 6c 65 6e 61 6d 65 20 69 73 20 61 6e 20 65  filename is an e
24dd0 6d 70 74 79 20 73 74 72 69 6e 67 2c 20 74 68 65  mpty string, the
24de0 6e 20 61 20 70 72 69 76 61 74 65 2c 20 74 65 6d  n a private, tem
24df0 70 6f 72 61 72 79 0a 2a 2a 20 6f 6e 2d 64 69 73  porary.** on-dis
24e00 6b 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20  k database will 
24e10 62 65 20 63 72 65 61 74 65 64 2e 20 20 5e 54 68  be created.  ^Th
24e20 69 73 20 70 72 69 76 61 74 65 20 64 61 74 61 62  is private datab
24e30 61 73 65 20 77 69 6c 6c 20 62 65 0a 2a 2a 20 61  ase will be.** a
24e40 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 64 65 6c  utomatically del
24e50 65 74 65 64 20 61 73 20 73 6f 6f 6e 20 61 73 20  eted as soon as 
24e60 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
24e70 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65  nection is close
24e80 64 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 55 52 49 20 66  d..**.** [[URI f
24e90 69 6c 65 6e 61 6d 65 73 20 69 6e 20 73 71 6c 69  ilenames in sqli
24ea0 74 65 33 5f 6f 70 65 6e 28 29 5d 5d 20 3c 68 33  te3_open()]] <h3
24eb0 3e 55 52 49 20 46 69 6c 65 6e 61 6d 65 73 3c 2f  >URI Filenames</
24ec0 68 33 3e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 5b 55  h3>.**.** ^If [U
24ed0 52 49 20 66 69 6c 65 6e 61 6d 65 5d 20 69 6e 74  RI filename] int
24ee0 65 72 70 72 65 74 61 74 69 6f 6e 20 69 73 20 65  erpretation is e
24ef0 6e 61 62 6c 65 64 2c 20 61 6e 64 20 74 68 65 20  nabled, and the 
24f00 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e  filename argumen
24f10 74 0a 2a 2a 20 62 65 67 69 6e 73 20 77 69 74 68  t.** begins with
24f20 20 22 66 69 6c 65 3a 22 2c 20 74 68 65 6e 20 74   "file:", then t
24f30 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 69  he filename is i
24f40 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 61 20  nterpreted as a 
24f50 55 52 49 2e 20 5e 55 52 49 0a 2a 2a 20 66 69 6c  URI. ^URI.** fil
24f60 65 6e 61 6d 65 20 69 6e 74 65 72 70 72 65 74 61  ename interpreta
24f70 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 20  tion is enabled 
24f80 69 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f  if the [SQLITE_O
24f90 50 45 4e 5f 55 52 49 5d 20 66 6c 61 67 20 69 73  PEN_URI] flag is
24fa0 0a 2a 2a 20 73 65 74 20 69 6e 20 74 68 65 20 66  .** set in the f
24fb0 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 20 74  ourth argument t
24fc0 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  o sqlite3_open_v
24fd0 32 28 29 2c 20 6f 72 20 69 66 20 69 74 20 68 61  2(), or if it ha
24fe0 73 0a 2a 2a 20 62 65 65 6e 20 65 6e 61 62 6c 65  s.** been enable
24ff0 64 20 67 6c 6f 62 61 6c 6c 79 20 75 73 69 6e 67  d globally using
25000 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 43 4f 4e   the [SQLITE_CON
25010 46 49 47 5f 55 52 49 5d 20 6f 70 74 69 6f 6e 20  FIG_URI] option 
25020 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 73 71 6c  with the.** [sql
25030 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 6d  ite3_config()] m
25040 65 74 68 6f 64 20 6f 72 20 62 79 20 74 68 65 20  ethod or by the 
25050 5b 53 51 4c 49 54 45 5f 55 53 45 5f 55 52 49 5d  [SQLITE_USE_URI]
25060 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
25070 74 69 6f 6e 2e 0a 2a 2a 20 41 73 20 6f 66 20 53  tion..** As of S
25080 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e  QLite version 3.
25090 37 2e 37 2c 20 55 52 49 20 66 69 6c 65 6e 61 6d  7.7, URI filenam
250a0 65 20 69 6e 74 65 72 70 72 65 74 61 74 69 6f 6e  e interpretation
250b0 20 69 73 20 74 75 72 6e 65 64 20 6f 66 66 0a 2a   is turned off.*
250c0 2a 20 62 79 20 64 65 66 61 75 6c 74 2c 20 62 75  * by default, bu
250d0 74 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65  t future release
250e0 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 69 67 68  s of SQLite migh
250f0 74 20 65 6e 61 62 6c 65 20 55 52 49 20 66 69 6c  t enable URI fil
25100 65 6e 61 6d 65 0a 2a 2a 20 69 6e 74 65 72 70 72  ename.** interpr
25110 65 74 61 74 69 6f 6e 20 62 79 20 64 65 66 61 75  etation by defau
25120 6c 74 2e 20 20 53 65 65 20 22 5b 55 52 49 20 66  lt.  See "[URI f
25130 69 6c 65 6e 61 6d 65 73 5d 22 20 66 6f 72 20 61  ilenames]" for a
25140 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66  dditional.** inf
25150 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  ormation..**.** 
25160 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 20 61 72  URI filenames ar
25170 65 20 70 61 72 73 65 64 20 61 63 63 6f 72 64 69  e parsed accordi
25180 6e 67 20 74 6f 20 52 46 43 20 33 39 38 36 2e 20  ng to RFC 3986. 
25190 5e 49 66 20 74 68 65 20 55 52 49 20 63 6f 6e 74  ^If the URI cont
251a0 61 69 6e 73 20 61 6e 0a 2a 2a 20 61 75 74 68 6f  ains an.** autho
251b0 72 69 74 79 2c 20 74 68 65 6e 20 69 74 20 6d 75  rity, then it mu
251c0 73 74 20 62 65 20 65 69 74 68 65 72 20 61 6e 20  st be either an 
251d0 65 6d 70 74 79 20 73 74 72 69 6e 67 20 6f 72 20  empty string or 
251e0 74 68 65 20 73 74 72 69 6e 67 20 0a 2a 2a 20 22  the string .** "
251f0 6c 6f 63 61 6c 68 6f 73 74 22 2e 20 5e 49 66 20  localhost". ^If 
25200 74 68 65 20 61 75 74 68 6f 72 69 74 79 20 69 73  the authority is
25210 20 6e 6f 74 20 61 6e 20 65 6d 70 74 79 20 73 74   not an empty st
25220 72 69 6e 67 20 6f 72 20 22 6c 6f 63 61 6c 68 6f  ring or "localho
25230 73 74 22 2c 20 61 6e 20 0a 2a 2a 20 65 72 72 6f  st", an .** erro
25240 72 20 69 73 20 72 65 74 75 72 6e 65 64 20 74 6f  r is returned to
25250 20 74 68 65 20 63 61 6c 6c 65 72 2e 20 5e 54 68   the caller. ^Th
25260 65 20 66 72 61 67 6d 65 6e 74 20 63 6f 6d 70 6f  e fragment compo
25270 6e 65 6e 74 20 6f 66 20 61 20 55 52 49 2c 20 69  nent of a URI, i
25280 66 20 0a 2a 2a 20 70 72 65 73 65 6e 74 2c 20 69  f .** present, i
25290 73 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a  s ignored..**.**
252a0 20 5e 53 51 4c 69 74 65 20 75 73 65 73 20 74 68   ^SQLite uses th
252b0 65 20 70 61 74 68 20 63 6f 6d 70 6f 6e 65 6e 74  e path component
252c0 20 6f 66 20 74 68 65 20 55 52 49 20 61 73 20 74   of the URI as t
252d0 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64  he name of the d
252e0 69 73 6b 20 66 69 6c 65 0a 2a 2a 20 77 68 69 63  isk file.** whic
252f0 68 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 20 64  h contains the d
25300 61 74 61 62 61 73 65 2e 20 5e 49 66 20 74 68 65  atabase. ^If the
25310 20 70 61 74 68 20 62 65 67 69 6e 73 20 77 69 74   path begins wit
25320 68 20 61 20 27 2f 27 20 63 68 61 72 61 63 74 65  h a '/' characte
25330 72 2c 20 0a 2a 2a 20 74 68 65 6e 20 69 74 20 69  r, .** then it i
25340 73 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73  s interpreted as
25350 20 61 6e 20 61 62 73 6f 6c 75 74 65 20 70 61 74   an absolute pat
25360 68 2e 20 5e 49 66 20 74 68 65 20 70 61 74 68 20  h. ^If the path 
25370 64 6f 65 73 20 6e 6f 74 20 62 65 67 69 6e 20 0a  does not begin .
25380 2a 2a 20 77 69 74 68 20 61 20 27 2f 27 20 28 6d  ** with a '/' (m
25390 65 61 6e 69 6e 67 20 74 68 61 74 20 74 68 65 20  eaning that the 
253a0 61 75 74 68 6f 72 69 74 79 20 73 65 63 74 69 6f  authority sectio
253b0 6e 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f  n is omitted fro
253c0 6d 20 74 68 65 20 55 52 49 29 0a 2a 2a 20 74 68  m the URI).** th
253d0 65 6e 20 74 68 65 20 70 61 74 68 20 69 73 20 69  en the path is i
253e0 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 61 20  nterpreted as a 
253f0 72 65 6c 61 74 69 76 65 20 70 61 74 68 2e 20 0a  relative path. .
25400 2a 2a 20 5e 28 4f 6e 20 77 69 6e 64 6f 77 73 2c  ** ^(On windows,
25410 20 74 68 65 20 66 69 72 73 74 20 63 6f 6d 70 6f   the first compo
25420 6e 65 6e 74 20 6f 66 20 61 6e 20 61 62 73 6f 6c  nent of an absol
25430 75 74 65 20 70 61 74 68 20 0a 2a 2a 20 69 73 20  ute path .** is 
25440 61 20 64 72 69 76 65 20 73 70 65 63 69 66 69 63  a drive specific
25450 61 74 69 6f 6e 20 28 65 2e 67 2e 20 22 43 3a 22  ation (e.g. "C:"
25460 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 63 6f 72  ).)^.**.** [[cor
25470 65 20 55 52 49 20 71 75 65 72 79 20 70 61 72 61  e URI query para
25480 6d 65 74 65 72 73 5d 5d 0a 2a 2a 20 54 68 65 20  meters]].** The 
25490 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 20  query component 
254a0 6f 66 20 61 20 55 52 49 20 6d 61 79 20 63 6f 6e  of a URI may con
254b0 74 61 69 6e 20 70 61 72 61 6d 65 74 65 72 73 20  tain parameters 
254c0 74 68 61 74 20 61 72 65 20 69 6e 74 65 72 70 72  that are interpr
254d0 65 74 65 64 0a 2a 2a 20 65 69 74 68 65 72 20 62  eted.** either b
254e0 79 20 53 51 4c 69 74 65 20 69 74 73 65 6c 66 2c  y SQLite itself,
254f0 20 6f 72 20 62 79 20 61 20 5b 56 46 53 20 7c 20   or by a [VFS | 
25500 63 75 73 74 6f 6d 20 56 46 53 20 69 6d 70 6c 65  custom VFS imple
25510 6d 65 6e 74 61 74 69 6f 6e 5d 2e 0a 2a 2a 20 53  mentation]..** S
25520 51 4c 69 74 65 20 61 6e 64 20 69 74 73 20 62 75  QLite and its bu
25530 69 6c 74 2d 69 6e 20 5b 56 46 53 65 73 5d 20 69  ilt-in [VFSes] i
25540 6e 74 65 72 70 72 65 74 20 74 68 65 0a 2a 2a 20  nterpret the.** 
25550 66 6f 6c 6c 6f 77 69 6e 67 20 71 75 65 72 79 20  following query 
25560 70 61 72 61 6d 65 74 65 72 73 3a 0a 2a 2a 0a 2a  parameters:.**.*
25570 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e  * <ul>.**   <li>
25580 20 3c 62 3e 76 66 73 3c 2f 62 3e 3a 20 5e 54 68   <b>vfs</b>: ^Th
25590 65 20 22 76 66 73 22 20 70 61 72 61 6d 65 74 65  e "vfs" paramete
255a0 72 20 6d 61 79 20 62 65 20 75 73 65 64 20 74 6f  r may be used to
255b0 20 73 70 65 63 69 66 79 20 74 68 65 20 6e 61 6d   specify the nam
255c0 65 20 6f 66 0a 2a 2a 20 20 20 20 20 61 20 56 46  e of.**     a VF
255d0 53 20 6f 62 6a 65 63 74 20 74 68 61 74 20 70 72  S object that pr
255e0 6f 76 69 64 65 73 20 74 68 65 20 6f 70 65 72 61  ovides the opera
255f0 74 69 6e 67 20 73 79 73 74 65 6d 20 69 6e 74 65  ting system inte
25600 72 66 61 63 65 20 74 68 61 74 20 73 68 6f 75 6c  rface that shoul
25610 64 0a 2a 2a 20 20 20 20 20 62 65 20 75 73 65 64  d.**     be used
25620 20 74 6f 20 61 63 63 65 73 73 20 74 68 65 20 64   to access the d
25630 61 74 61 62 61 73 65 20 66 69 6c 65 20 6f 6e 20  atabase file on 
25640 64 69 73 6b 2e 20 5e 49 66 20 74 68 69 73 20 6f  disk. ^If this o
25650 70 74 69 6f 6e 20 69 73 20 73 65 74 20 74 6f 0a  ption is set to.
25660 2a 2a 20 20 20 20 20 61 6e 20 65 6d 70 74 79 20  **     an empty 
25670 73 74 72 69 6e 67 20 74 68 65 20 64 65 66 61 75  string the defau
25680 6c 74 20 56 46 53 20 6f 62 6a 65 63 74 20 69 73  lt VFS object is
25690 20 75 73 65 64 2e 20 5e 53 70 65 63 69 66 79 69   used. ^Specifyi
256a0 6e 67 20 61 6e 20 75 6e 6b 6e 6f 77 6e 0a 2a 2a  ng an unknown.**
256b0 20 20 20 20 20 56 46 53 20 69 73 20 61 6e 20 65       VFS is an e
256c0 72 72 6f 72 2e 20 5e 49 66 20 73 71 6c 69 74 65  rror. ^If sqlite
256d0 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 75  3_open_v2() is u
256e0 73 65 64 20 61 6e 64 20 74 68 65 20 76 66 73 20  sed and the vfs 
256f0 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 20 20 20  option is.**    
25700 20 70 72 65 73 65 6e 74 2c 20 74 68 65 6e 20 74   present, then t
25710 68 65 20 56 46 53 20 73 70 65 63 69 66 69 65 64  he VFS specified
25720 20 62 79 20 74 68 65 20 6f 70 74 69 6f 6e 20 74   by the option t
25730 61 6b 65 73 20 70 72 65 63 65 64 65 6e 63 65 20  akes precedence 
25740 6f 76 65 72 0a 2a 2a 20 20 20 20 20 74 68 65 20  over.**     the 
25750 76 61 6c 75 65 20 70 61 73 73 65 64 20 61 73 20  value passed as 
25760 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  the fourth param
25770 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
25780 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a  open_v2()..**.**
25790 20 20 20 3c 6c 69 3e 20 3c 62 3e 6d 6f 64 65 3c     <li> <b>mode<
257a0 2f 62 3e 3a 20 5e 28 54 68 65 20 6d 6f 64 65 20  /b>: ^(The mode 
257b0 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65  parameter may be
257c0 20 73 65 74 20 74 6f 20 65 69 74 68 65 72 20 22   set to either "
257d0 72 6f 22 2c 20 22 72 77 22 2c 0a 2a 2a 20 20 20  ro", "rw",.**   
257e0 20 20 22 72 77 63 22 2c 20 6f 72 20 22 6d 65 6d    "rwc", or "mem
257f0 6f 72 79 22 2e 20 41 74 74 65 6d 70 74 69 6e 67  ory". Attempting
25800 20 74 6f 20 73 65 74 20 69 74 20 74 6f 20 61 6e   to set it to an
25810 79 20 6f 74 68 65 72 20 76 61 6c 75 65 20 69 73  y other value is
25820 0a 2a 2a 20 20 20 20 20 61 6e 20 65 72 72 6f 72  .**     an error
25830 29 5e 2e 20 0a 2a 2a 20 20 20 20 20 5e 49 66 20  )^. .**     ^If 
25840 22 72 6f 22 20 69 73 20 73 70 65 63 69 66 69 65  "ro" is specifie
25850 64 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74 61  d, then the data
25860 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66  base is opened f
25870 6f 72 20 72 65 61 64 2d 6f 6e 6c 79 20 0a 2a 2a  or read-only .**
25880 20 20 20 20 20 61 63 63 65 73 73 2c 20 6a 75 73       access, jus
25890 74 20 61 73 20 69 66 20 74 68 65 20 5b 53 51 4c  t as if the [SQL
258a0 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c  ITE_OPEN_READONL
258b0 59 5d 20 66 6c 61 67 20 68 61 64 20 62 65 65 6e  Y] flag had been
258c0 20 73 65 74 20 69 6e 20 74 68 65 20 0a 2a 2a 20   set in the .** 
258d0 20 20 20 20 74 68 69 72 64 20 61 72 67 75 6d 65      third argume
258e0 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70  nt to sqlite3_op
258f0 65 6e 5f 76 32 28 29 2e 20 5e 49 66 20 74 68 65  en_v2(). ^If the
25900 20 6d 6f 64 65 20 6f 70 74 69 6f 6e 20 69 73 20   mode option is 
25910 73 65 74 20 74 6f 20 0a 2a 2a 20 20 20 20 20 22  set to .**     "
25920 72 77 22 2c 20 74 68 65 6e 20 74 68 65 20 64 61  rw", then the da
25930 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64  tabase is opened
25940 20 66 6f 72 20 72 65 61 64 2d 77 72 69 74 65 20   for read-write 
25950 28 62 75 74 20 6e 6f 74 20 63 72 65 61 74 65 29  (but not create)
25960 20 0a 2a 2a 20 20 20 20 20 61 63 63 65 73 73 2c   .**     access,
25970 20 61 73 20 69 66 20 53 51 4c 49 54 45 5f 4f 50   as if SQLITE_OP
25980 45 4e 5f 52 45 41 44 57 52 49 54 45 20 28 62 75  EN_READWRITE (bu
25990 74 20 6e 6f 74 20 53 51 4c 49 54 45 5f 4f 50 45  t not SQLITE_OPE
259a0 4e 5f 43 52 45 41 54 45 29 20 68 61 64 20 0a 2a  N_CREATE) had .*
259b0 2a 20 20 20 20 20 62 65 65 6e 20 73 65 74 2e 20  *     been set. 
259c0 5e 56 61 6c 75 65 20 22 72 77 63 22 20 69 73 20  ^Value "rwc" is 
259d0 65 71 75 69 76 61 6c 65 6e 74 20 74 6f 20 73 65  equivalent to se
259e0 74 74 69 6e 67 20 62 6f 74 68 20 0a 2a 2a 20 20  tting both .**  
259f0 20 20 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52     SQLITE_OPEN_R
25a00 45 41 44 57 52 49 54 45 20 61 6e 64 20 53 51 4c  EADWRITE and SQL
25a10 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 2e  ITE_OPEN_CREATE.
25a20 20 20 5e 49 66 20 74 68 65 20 6d 6f 64 65 20 6f    ^If the mode o
25a30 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 20 20 20 20  ption is.**     
25a40 73 65 74 20 74 6f 20 22 6d 65 6d 6f 72 79 22 20  set to "memory" 
25a50 74 68 65 6e 20 61 20 70 75 72 65 20 5b 69 6e 2d  then a pure [in-
25a60 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65 5d  memory database]
25a70 20 74 68 61 74 20 6e 65 76 65 72 20 72 65 61 64   that never read
25a80 73 0a 2a 2a 20 20 20 20 20 6f 72 20 77 72 69 74  s.**     or writ
25a90 65 73 20 66 72 6f 6d 20 64 69 73 6b 20 69 73 20  es from disk is 
25aa0 75 73 65 64 2e 20 5e 49 74 20 69 73 20 61 6e 20  used. ^It is an 
25ab0 65 72 72 6f 72 20 74 6f 20 73 70 65 63 69 66 79  error to specify
25ac0 20 61 20 76 61 6c 75 65 20 66 6f 72 0a 2a 2a 20   a value for.** 
25ad0 20 20 20 20 74 68 65 20 6d 6f 64 65 20 70 61 72      the mode par
25ae0 61 6d 65 74 65 72 20 74 68 61 74 20 69 73 20 6c  ameter that is l
25af0 65 73 73 20 72 65 73 74 72 69 63 74 69 76 65 20  ess restrictive 
25b00 74 68 61 6e 20 74 68 61 74 20 73 70 65 63 69 66  than that specif
25b10 69 65 64 20 62 79 0a 2a 2a 20 20 20 20 20 74 68  ied by.**     th
25b20 65 20 66 6c 61 67 73 20 70 61 73 73 65 64 20 69  e flags passed i
25b30 6e 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61  n the third para
25b40 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
25b50 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a  _open_v2()..**.*
25b60 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e 63 61 63 68  *   <li> <b>cach
25b70 65 3c 2f 62 3e 3a 20 5e 54 68 65 20 63 61 63 68  e</b>: ^The cach
25b80 65 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20  e parameter may 
25b90 62 65 20 73 65 74 20 74 6f 20 65 69 74 68 65 72  be set to either
25ba0 20 22 73 68 61 72 65 64 22 20 6f 72 0a 2a 2a 20   "shared" or.** 
25bb0 20 20 20 20 22 70 72 69 76 61 74 65 22 2e 20 5e      "private". ^
25bc0 53 65 74 74 69 6e 67 20 69 74 20 74 6f 20 22 73  Setting it to "s
25bd0 68 61 72 65 64 22 20 69 73 20 65 71 75 69 76 61  hared" is equiva
25be0 6c 65 6e 74 20 74 6f 20 73 65 74 74 69 6e 67 20  lent to setting 
25bf0 74 68 65 0a 2a 2a 20 20 20 20 20 53 51 4c 49 54  the.**     SQLIT
25c00 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43  E_OPEN_SHAREDCAC
25c10 48 45 20 62 69 74 20 69 6e 20 74 68 65 20 66 6c  HE bit in the fl
25c20 61 67 73 20 61 72 67 75 6d 65 6e 74 20 70 61 73  ags argument pas
25c30 73 65 64 20 74 6f 0a 2a 2a 20 20 20 20 20 73 71  sed to.**     sq
25c40 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e  lite3_open_v2().
25c50 20 5e 53 65 74 74 69 6e 67 20 74 68 65 20 63 61   ^Setting the ca
25c60 63 68 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f  che parameter to
25c70 20 22 70 72 69 76 61 74 65 22 20 69 73 20 0a 2a   "private" is .*
25c80 2a 20 20 20 20 20 65 71 75 69 76 61 6c 65 6e 74  *     equivalent
25c90 20 74 6f 20 73 65 74 74 69 6e 67 20 74 68 65 20   to setting the 
25ca0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56  SQLITE_OPEN_PRIV
25cb0 41 54 45 43 41 43 48 45 20 62 69 74 2e 0a 2a 2a  ATECACHE bit..**
25cc0 20 20 20 20 20 5e 49 66 20 73 71 6c 69 74 65 33       ^If sqlite3
25cd0 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 75 73  _open_v2() is us
25ce0 65 64 20 61 6e 64 20 74 68 65 20 22 63 61 63 68  ed and the "cach
25cf0 65 22 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  e" parameter is 
25d00 70 72 65 73 65 6e 74 20 69 6e 0a 2a 2a 20 20 20  present in.**   
25d10 20 20 61 20 55 52 49 20 66 69 6c 65 6e 61 6d 65    a URI filename
25d20 2c 20 69 74 73 20 76 61 6c 75 65 20 6f 76 65 72  , its value over
25d30 72 69 64 65 73 20 61 6e 79 20 62 65 68 61 76 69  rides any behavi
25d40 6f 72 20 72 65 71 75 65 73 74 65 64 20 62 79 20  or requested by 
25d50 73 65 74 74 69 6e 67 0a 2a 2a 20 20 20 20 20 53  setting.**     S
25d60 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41  QLITE_OPEN_PRIVA
25d70 54 45 43 41 43 48 45 20 6f 72 20 53 51 4c 49 54  TECACHE or SQLIT
25d80 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43  E_OPEN_SHAREDCAC
25d90 48 45 20 66 6c 61 67 2e 0a 2a 2a 0a 2a 2a 20 20  HE flag..**.**  
25da0 3c 6c 69 3e 20 3c 62 3e 70 73 6f 77 3c 2f 62 3e  <li> <b>psow</b>
25db0 3a 20 5e 54 68 65 20 70 73 6f 77 20 70 61 72 61  : ^The psow para
25dc0 6d 65 74 65 72 20 69 6e 64 69 63 61 74 65 73 20  meter indicates 
25dd0 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74  whether or not t
25de0 68 65 0a 2a 2a 20 20 20 20 20 5b 70 6f 77 65 72  he.**     [power
25df0 73 61 66 65 20 6f 76 65 72 77 72 69 74 65 5d 20  safe overwrite] 
25e00 70 72 6f 70 65 72 74 79 20 64 6f 65 73 20 6f 72  property does or
25e10 20 64 6f 65 73 20 6e 6f 74 20 61 70 70 6c 79 20   does not apply 
25e20 74 6f 20 74 68 65 0a 2a 2a 20 20 20 20 20 73 74  to the.**     st
25e30 6f 72 61 67 65 20 6d 65 64 69 61 20 6f 6e 20 77  orage media on w
25e40 68 69 63 68 20 74 68 65 20 64 61 74 61 62 61 73  hich the databas
25e50 65 20 66 69 6c 65 20 72 65 73 69 64 65 73 2e 0a  e file resides..
25e60 2a 2a 0a 2a 2a 20 20 3c 6c 69 3e 20 3c 62 3e 6e  **.**  <li> <b>n
25e70 6f 6c 6f 63 6b 3c 2f 62 3e 3a 20 5e 54 68 65 20  olock</b>: ^The 
25e80 6e 6f 6c 6f 63 6b 20 70 61 72 61 6d 65 74 65 72  nolock parameter
25e90 20 69 73 20 61 20 62 6f 6f 6c 65 61 6e 20 71 75   is a boolean qu
25ea0 65 72 79 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a  ery parameter.**
25eb0 20 20 20 20 20 77 68 69 63 68 20 69 66 20 73 65       which if se
25ec0 74 20 64 69 73 61 62 6c 65 73 20 66 69 6c 65 20  t disables file 
25ed0 6c 6f 63 6b 69 6e 67 20 69 6e 20 72 6f 6c 6c 62  locking in rollb
25ee0 61 63 6b 20 6a 6f 75 72 6e 61 6c 20 6d 6f 64 65  ack journal mode
25ef0 73 2e 20 20 54 68 69 73 0a 2a 2a 20 20 20 20 20  s.  This.**     
25f00 69 73 20 75 73 65 66 75 6c 20 66 6f 72 20 61 63  is useful for ac
25f10 63 65 73 73 69 6e 67 20 61 20 64 61 74 61 62 61  cessing a databa
25f20 73 65 20 6f 6e 20 61 20 66 69 6c 65 73 79 73 74  se on a filesyst
25f30 65 6d 20 74 68 61 74 20 64 6f 65 73 20 6e 6f 74  em that does not
25f40 0a 2a 2a 20 20 20 20 20 73 75 70 70 6f 72 74 20  .**     support 
25f50 6c 6f 63 6b 69 6e 67 2e 20 20 43 61 75 74 69 6f  locking.  Cautio
25f60 6e 3a 20 20 44 61 74 61 62 61 73 65 20 63 6f 72  n:  Database cor
25f70 72 75 70 74 69 6f 6e 20 6d 69 67 68 74 20 72 65  ruption might re
25f80 73 75 6c 74 20 69 66 20 74 77 6f 0a 2a 2a 20 20  sult if two.**  
25f90 20 20 20 6f 72 20 6d 6f 72 65 20 70 72 6f 63 65     or more proce
25fa0 73 73 65 73 20 77 72 69 74 65 20 74 6f 20 74 68  sses write to th
25fb0 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20  e same database 
25fc0 61 6e 64 20 61 6e 79 20 6f 6e 65 20 6f 66 20 74  and any one of t
25fd0 68 6f 73 65 0a 2a 2a 20 20 20 20 20 70 72 6f 63  hose.**     proc
25fe0 65 73 73 65 73 20 75 73 65 73 20 6e 6f 6c 6f 63  esses uses noloc
25ff0 6b 3d 31 2e 0a 2a 2a 0a 2a 2a 20 20 3c 6c 69 3e  k=1..**.**  <li>
26000 20 3c 62 3e 69 6d 6d 75 74 61 62 6c 65 3c 2f 62   <b>immutable</b
26010 3e 3a 20 5e 54 68 65 20 69 6d 6d 75 74 61 62 6c  >: ^The immutabl
26020 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61  e parameter is a
26030 20 62 6f 6f 6c 65 61 6e 20 71 75 65 72 79 0a 2a   boolean query.*
26040 2a 20 20 20 20 20 70 61 72 61 6d 65 74 65 72 20  *     parameter 
26050 74 68 61 74 20 69 6e 64 69 63 61 74 65 73 20 74  that indicates t
26060 68 61 74 20 74 68 65 20 64 61 74 61 62 61 73 65  hat the database
26070 20 66 69 6c 65 20 69 73 20 73 74 6f 72 65 64 20   file is stored 
26080 6f 6e 0a 2a 2a 20 20 20 20 20 72 65 61 64 2d 6f  on.**     read-o
26090 6e 6c 79 20 6d 65 64 69 61 2e 20 20 5e 57 68 65  nly media.  ^Whe
260a0 6e 20 69 6d 6d 75 74 61 62 6c 65 20 69 73 20 73  n immutable is s
260b0 65 74 2c 20 53 51 4c 69 74 65 20 61 73 73 75 6d  et, SQLite assum
260c0 65 73 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 20  es that the.**  
260d0 20 20 20 64 61 74 61 62 61 73 65 20 66 69 6c 65     database file
260e0 20 63 61 6e 6e 6f 74 20 62 65 20 63 68 61 6e 67   cannot be chang
260f0 65 64 2c 20 65 76 65 6e 20 62 79 20 61 20 70 72  ed, even by a pr
26100 6f 63 65 73 73 20 77 69 74 68 20 68 69 67 68 65  ocess with highe
26110 72 0a 2a 2a 20 20 20 20 20 70 72 69 76 69 6c 65  r.**     privile
26120 67 65 2c 20 61 6e 64 20 73 6f 20 74 68 65 20 64  ge, and so the d
26130 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65  atabase is opene
26140 64 20 72 65 61 64 2d 6f 6e 6c 79 20 61 6e 64 20  d read-only and 
26150 61 6c 6c 20 6c 6f 63 6b 69 6e 67 0a 2a 2a 20 20  all locking.**  
26160 20 20 20 61 6e 64 20 63 68 61 6e 67 65 20 64 65     and change de
26170 74 65 63 74 69 6f 6e 20 69 73 20 64 69 73 61 62  tection is disab
26180 6c 65 64 2e 20 20 43 61 75 74 69 6f 6e 3a 20 53  led.  Caution: S
26190 65 74 74 69 6e 67 20 74 68 65 20 69 6d 6d 75 74  etting the immut
261a0 61 62 6c 65 0a 2a 2a 20 20 20 20 20 70 72 6f 70  able.**     prop
261b0 65 72 74 79 20 6f 6e 20 61 20 64 61 74 61 62 61  erty on a databa
261c0 73 65 20 66 69 6c 65 20 74 68 61 74 20 64 6f 65  se file that doe
261d0 73 20 69 6e 20 66 61 63 74 20 63 68 61 6e 67 65  s in fact change
261e0 20 63 61 6e 20 72 65 73 75 6c 74 0a 2a 2a 20 20   can result.**  
261f0 20 20 20 69 6e 20 69 6e 63 6f 72 72 65 63 74 20     in incorrect 
26200 71 75 65 72 79 20 72 65 73 75 6c 74 73 20 61 6e  query results an
26210 64 2f 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f 52  d/or [SQLITE_COR
26220 52 55 50 54 5d 20 65 72 72 6f 72 73 2e 0a 2a 2a  RUPT] errors..**
26230 20 20 20 20 20 53 65 65 20 61 6c 73 6f 3a 20 5b       See also: [
26240 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 49 4d 4d  SQLITE_IOCAP_IMM
26250 55 54 41 42 4c 45 5d 2e 0a 2a 2a 20 20 20 20 20  UTABLE]..**     
26260 20 20 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a    .** </ul>.**.*
26270 2a 20 5e 53 70 65 63 69 66 79 69 6e 67 20 61 6e  * ^Specifying an
26280 20 75 6e 6b 6e 6f 77 6e 20 70 61 72 61 6d 65 74   unknown paramet
26290 65 72 20 69 6e 20 74 68 65 20 71 75 65 72 79 20  er in the query 
262a0 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 20 55  component of a U
262b0 52 49 20 69 73 20 6e 6f 74 20 61 6e 0a 2a 2a 20  RI is not an.** 
262c0 65 72 72 6f 72 2e 20 20 46 75 74 75 72 65 20 76  error.  Future v
262d0 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
262e0 65 20 6d 69 67 68 74 20 75 6e 64 65 72 73 74 61  e might understa
262f0 6e 64 20 61 64 64 69 74 69 6f 6e 61 6c 20 71 75  nd additional qu
26300 65 72 79 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  ery.** parameter
26310 73 2e 20 20 53 65 65 20 22 5b 71 75 65 72 79 20  s.  See "[query 
26320 70 61 72 61 6d 65 74 65 72 73 20 77 69 74 68 20  parameters with 
26330 73 70 65 63 69 61 6c 20 6d 65 61 6e 69 6e 67 20  special meaning 
26340 74 6f 20 53 51 4c 69 74 65 5d 22 20 66 6f 72 0a  to SQLite]" for.
26350 2a 2a 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e  ** additional in
26360 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  formation..**.**
26370 20 5b 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65 20   [[URI filename 
26380 65 78 61 6d 70 6c 65 73 5d 5d 20 3c 68 33 3e 55  examples]] <h3>U
26390 52 49 20 66 69 6c 65 6e 61 6d 65 20 65 78 61 6d  RI filename exam
263a0 70 6c 65 73 3c 2f 68 33 3e 0a 2a 2a 0a 2a 2a 20  ples</h3>.**.** 
263b0 3c 74 61 62 6c 65 20 62 6f 72 64 65 72 3d 22 31  <table border="1
263c0 22 20 61 6c 69 67 6e 3d 63 65 6e 74 65 72 20 63  " align=center c
263d0 65 6c 6c 70 61 64 64 69 6e 67 3d 35 3e 0a 2a 2a  ellpadding=5>.**
263e0 20 3c 74 72 3e 3c 74 68 3e 20 55 52 49 20 66 69   <tr><th> URI fi
263f0 6c 65 6e 61 6d 65 73 20 3c 74 68 3e 20 52 65 73  lenames <th> Res
26400 75 6c 74 73 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  ults.** <tr><td>
26410 20 66 69 6c 65 3a 64 61 74 61 2e 64 62 20 3c 74   file:data.db <t
26420 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  d> .**          
26430 4f 70 65 6e 20 74 68 65 20 66 69 6c 65 20 22 64  Open the file "d
26440 61 74 61 2e 64 62 22 20 69 6e 20 74 68 65 20 63  ata.db" in the c
26450 75 72 72 65 6e 74 20 64 69 72 65 63 74 6f 72 79  urrent directory
26460 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69  ..** <tr><td> fi
26470 6c 65 3a 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61  le:/home/fred/da
26480 74 61 2e 64 62 3c 62 72 3e 0a 2a 2a 20 20 20 20  ta.db<br>.**    
26490 20 20 20 20 20 20 66 69 6c 65 3a 2f 2f 2f 68 6f        file:///ho
264a0 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 20  me/fred/data.db 
264b0 3c 62 72 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20  <br> .**        
264c0 20 20 66 69 6c 65 3a 2f 2f 6c 6f 63 61 6c 68 6f    file://localho
264d0 73 74 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74  st/home/fred/dat
264e0 61 2e 64 62 20 3c 62 72 3e 20 3c 74 64 3e 20 0a  a.db <br> <td> .
264f0 2a 2a 20 20 20 20 20 20 20 20 20 20 4f 70 65 6e  **          Open
26500 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
26510 6c 65 20 22 2f 68 6f 6d 65 2f 66 72 65 64 2f 64  le "/home/fred/d
26520 61 74 61 2e 64 62 22 2e 0a 2a 2a 20 3c 74 72 3e  ata.db"..** <tr>
26530 3c 74 64 3e 20 66 69 6c 65 3a 2f 2f 64 61 72 6b  <td> file://dark
26540 73 74 61 72 2f 68 6f 6d 65 2f 66 72 65 64 2f 64  star/home/fred/d
26550 61 74 61 2e 64 62 20 3c 74 64 3e 20 0a 2a 2a 20  ata.db <td> .** 
26560 20 20 20 20 20 20 20 20 20 41 6e 20 65 72 72 6f           An erro
26570 72 2e 20 22 64 61 72 6b 73 74 61 72 22 20 69 73  r. "darkstar" is
26580 20 6e 6f 74 20 61 20 72 65 63 6f 67 6e 69 7a 65   not a recognize
26590 64 20 61 75 74 68 6f 72 69 74 79 2e 0a 2a 2a 20  d authority..** 
265a0 3c 74 72 3e 3c 74 64 20 73 74 79 6c 65 3d 22 77  <tr><td style="w
265b0 68 69 74 65 2d 73 70 61 63 65 3a 6e 6f 77 72 61  hite-space:nowra
265c0 70 22 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20  p"> .**         
265d0 20 66 69 6c 65 3a 2f 2f 2f 43 3a 2f 44 6f 63 75   file:///C:/Docu
265e0 6d 65 6e 74 73 25 32 30 61 6e 64 25 32 30 53 65  ments%20and%20Se
265f0 74 74 69 6e 67 73 2f 66 72 65 64 2f 44 65 73 6b  ttings/fred/Desk
26600 74 6f 70 2f 64 61 74 61 2e 64 62 0a 2a 2a 20 20  top/data.db.**  
26610 20 20 20 3c 74 64 3e 20 57 69 6e 64 6f 77 73 20     <td> Windows 
26620 6f 6e 6c 79 3a 20 4f 70 65 6e 20 74 68 65 20 66  only: Open the f
26630 69 6c 65 20 22 64 61 74 61 2e 64 62 22 20 6f 6e  ile "data.db" on
26640 20 66 72 65 64 27 73 20 64 65 73 6b 74 6f 70 20   fred's desktop 
26650 6f 6e 20 64 72 69 76 65 0a 2a 2a 20 20 20 20 20  on drive.**     
26660 20 20 20 20 20 43 3a 2e 20 4e 6f 74 65 20 74 68       C:. Note th
26670 61 74 20 74 68 65 20 25 32 30 20 65 73 63 61 70  at the %20 escap
26680 69 6e 67 20 69 6e 20 74 68 69 73 20 65 78 61 6d  ing in this exam
26690 70 6c 65 20 69 73 20 6e 6f 74 20 73 74 72 69 63  ple is not stric
266a0 74 6c 79 20 0a 2a 2a 20 20 20 20 20 20 20 20 20  tly .**         
266b0 20 6e 65 63 65 73 73 61 72 79 20 2d 20 73 70 61   necessary - spa
266c0 63 65 20 63 68 61 72 61 63 74 65 72 73 20 63 61  ce characters ca
266d0 6e 20 62 65 20 75 73 65 64 20 6c 69 74 65 72 61  n be used litera
266e0 6c 6c 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  lly.**          
266f0 69 6e 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 73  in URI filenames
26700 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69  ..** <tr><td> fi
26710 6c 65 3a 64 61 74 61 2e 64 62 3f 6d 6f 64 65 3d  le:data.db?mode=
26720 72 6f 26 63 61 63 68 65 3d 70 72 69 76 61 74 65  ro&cache=private
26730 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20   <td> .**       
26740 20 20 20 4f 70 65 6e 20 66 69 6c 65 20 22 64 61     Open file "da
26750 74 61 2e 64 62 22 20 69 6e 20 74 68 65 20 63 75  ta.db" in the cu
26760 72 72 65 6e 74 20 64 69 72 65 63 74 6f 72 79 20  rrent directory 
26770 66 6f 72 20 72 65 61 64 2d 6f 6e 6c 79 20 61 63  for read-only ac
26780 63 65 73 73 2e 0a 2a 2a 20 20 20 20 20 20 20 20  cess..**        
26790 20 20 52 65 67 61 72 64 6c 65 73 73 20 6f 66 20    Regardless of 
267a0 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 73  whether or not s
267b0 68 61 72 65 64 2d 63 61 63 68 65 20 6d 6f 64 65  hared-cache mode
267c0 20 69 73 20 65 6e 61 62 6c 65 64 20 62 79 0a 2a   is enabled by.*
267d0 2a 20 20 20 20 20 20 20 20 20 20 64 65 66 61 75  *          defau
267e0 6c 74 2c 20 75 73 65 20 61 20 70 72 69 76 61 74  lt, use a privat
267f0 65 20 63 61 63 68 65 2e 0a 2a 2a 20 3c 74 72 3e  e cache..** <tr>
26800 3c 74 64 3e 20 66 69 6c 65 3a 2f 68 6f 6d 65 2f  <td> file:/home/
26810 66 72 65 64 2f 64 61 74 61 2e 64 62 3f 76 66 73  fred/data.db?vfs
26820 3d 75 6e 69 78 2d 64 6f 74 66 69 6c 65 20 3c 74  =unix-dotfile <t
26830 64 3e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4f  d>.**          O
26840 70 65 6e 20 66 69 6c 65 20 22 2f 68 6f 6d 65 2f  pen file "/home/
26850 66 72 65 64 2f 64 61 74 61 2e 64 62 22 2e 20 55  fred/data.db". U
26860 73 65 20 74 68 65 20 73 70 65 63 69 61 6c 20 56  se the special V
26870 46 53 20 22 75 6e 69 78 2d 64 6f 74 66 69 6c 65  FS "unix-dotfile
26880 22 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68  ".**          th
26890 61 74 20 75 73 65 73 20 64 6f 74 2d 66 69 6c 65  at uses dot-file
268a0 73 20 69 6e 20 70 6c 61 63 65 20 6f 66 20 70 6f  s in place of po
268b0 73 69 78 20 61 64 76 69 73 6f 72 79 20 6c 6f 63  six advisory loc
268c0 6b 69 6e 67 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64  king..** <tr><td
268d0 3e 20 66 69 6c 65 3a 64 61 74 61 2e 64 62 3f 6d  > file:data.db?m
268e0 6f 64 65 3d 72 65 61 64 6f 6e 6c 79 20 3c 74 64  ode=readonly <td
268f0 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 41  > .**          A
26900 6e 20 65 72 72 6f 72 2e 20 22 72 65 61 64 6f 6e  n error. "readon
26910 6c 79 22 20 69 73 20 6e 6f 74 20 61 20 76 61 6c  ly" is not a val
26920 69 64 20 6f 70 74 69 6f 6e 20 66 6f 72 20 74 68  id option for th
26930 65 20 22 6d 6f 64 65 22 20 70 61 72 61 6d 65 74  e "mode" paramet
26940 65 72 2e 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a  er..** </table>.
26950 2a 2a 0a 2a 2a 20 5e 55 52 49 20 68 65 78 61 64  **.** ^URI hexad
26960 65 63 69 6d 61 6c 20 65 73 63 61 70 65 20 73 65  ecimal escape se
26970 71 75 65 6e 63 65 73 20 28 25 48 48 29 20 61 72  quences (%HH) ar
26980 65 20 73 75 70 70 6f 72 74 65 64 20 77 69 74 68  e supported with
26990 69 6e 20 74 68 65 20 70 61 74 68 20 61 6e 64 0a  in the path and.
269a0 2a 2a 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65  ** query compone
269b0 6e 74 73 20 6f 66 20 61 20 55 52 49 2e 20 41 20  nts of a URI. A 
269c0 68 65 78 61 64 65 63 69 6d 61 6c 20 65 73 63 61  hexadecimal esca
269d0 70 65 20 73 65 71 75 65 6e 63 65 20 63 6f 6e 73  pe sequence cons
269e0 69 73 74 73 20 6f 66 20 61 0a 2a 2a 20 70 65 72  ists of a.** per
269f0 63 65 6e 74 20 73 69 67 6e 20 2d 20 22 25 22 20  cent sign - "%" 
26a00 2d 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 65 78  - followed by ex
26a10 61 63 74 6c 79 20 74 77 6f 20 68 65 78 61 64 65  actly two hexade
26a20 63 69 6d 61 6c 20 64 69 67 69 74 73 20 0a 2a 2a  cimal digits .**
26a30 20 73 70 65 63 69 66 79 69 6e 67 20 61 6e 20 6f   specifying an o
26a40 63 74 65 74 20 76 61 6c 75 65 2e 20 5e 42 65 66  ctet value. ^Bef
26a50 6f 72 65 20 74 68 65 20 70 61 74 68 20 6f 72 20  ore the path or 
26a60 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 73  query components
26a70 20 6f 66 20 61 0a 2a 2a 20 55 52 49 20 66 69 6c   of a.** URI fil
26a80 65 6e 61 6d 65 20 61 72 65 20 69 6e 74 65 72 70  ename are interp
26a90 72 65 74 65 64 2c 20 74 68 65 79 20 61 72 65 20  reted, they are 
26aa0 65 6e 63 6f 64 65 64 20 75 73 69 6e 67 20 55 54  encoded using UT
26ab0 46 2d 38 20 61 6e 64 20 61 6c 6c 20 0a 2a 2a 20  F-8 and all .** 
26ac0 68 65 78 61 64 65 63 69 6d 61 6c 20 65 73 63 61  hexadecimal esca
26ad0 70 65 20 73 65 71 75 65 6e 63 65 73 20 72 65 70  pe sequences rep
26ae0 6c 61 63 65 64 20 62 79 20 61 20 73 69 6e 67 6c  laced by a singl
26af0 65 20 62 79 74 65 20 63 6f 6e 74 61 69 6e 69 6e  e byte containin
26b00 67 20 74 68 65 0a 2a 2a 20 63 6f 72 72 65 73 70  g the.** corresp
26b10 6f 6e 64 69 6e 67 20 6f 63 74 65 74 2e 20 49 66  onding octet. If
26b20 20 74 68 69 73 20 70 72 6f 63 65 73 73 20 67 65   this process ge
26b30 6e 65 72 61 74 65 73 20 61 6e 20 69 6e 76 61 6c  nerates an inval
26b40 69 64 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e  id UTF-8 encodin
26b50 67 2c 0a 2a 2a 20 74 68 65 20 72 65 73 75 6c 74  g,.** the result
26b60 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e  s are undefined.
26b70 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74  .**.** <b>Note t
26b80 6f 20 57 69 6e 64 6f 77 73 20 75 73 65 72 73 3a  o Windows users:
26b90 3c 2f 62 3e 20 20 54 68 65 20 65 6e 63 6f 64 69  </b>  The encodi
26ba0 6e 67 20 75 73 65 64 20 66 6f 72 20 74 68 65 20  ng used for the 
26bb0 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e  filename argumen
26bc0 74 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f  t.** of sqlite3_
26bd0 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 74  open() and sqlit
26be0 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 6d 75 73  e3_open_v2() mus
26bf0 74 20 62 65 20 55 54 46 2d 38 2c 20 6e 6f 74 20  t be UTF-8, not 
26c00 77 68 61 74 65 76 65 72 0a 2a 2a 20 63 6f 64 65  whatever.** code
26c10 70 61 67 65 20 69 73 20 63 75 72 72 65 6e 74 6c  page is currentl
26c20 79 20 64 65 66 69 6e 65 64 2e 20 20 46 69 6c 65  y defined.  File
26c30 6e 61 6d 65 73 20 63 6f 6e 74 61 69 6e 69 6e 67  names containing
26c40 20 69 6e 74 65 72 6e 61 74 69 6f 6e 61 6c 0a 2a   international.*
26c50 2a 20 63 68 61 72 61 63 74 65 72 73 20 6d 75 73  * characters mus
26c60 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64 20 74  t be converted t
26c70 6f 20 55 54 46 2d 38 20 70 72 69 6f 72 20 74 6f  o UTF-8 prior to
26c80 20 70 61 73 73 69 6e 67 20 74 68 65 6d 20 69 6e   passing them in
26c90 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70  to.** sqlite3_op
26ca0 65 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  en() or sqlite3_
26cb0 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a  open_v2()..**.**
26cc0 20 3c 62 3e 4e 6f 74 65 20 74 6f 20 57 69 6e 64   <b>Note to Wind
26cd0 6f 77 73 20 52 75 6e 74 69 6d 65 20 75 73 65 72  ows Runtime user
26ce0 73 3a 3c 2f 62 3e 20 20 54 68 65 20 74 65 6d 70  s:</b>  The temp
26cf0 6f 72 61 72 79 20 64 69 72 65 63 74 6f 72 79 20  orary directory 
26d00 6d 75 73 74 20 62 65 20 73 65 74 0a 2a 2a 20 70  must be set.** p
26d10 72 69 6f 72 20 74 6f 20 63 61 6c 6c 69 6e 67 20  rior to calling 
26d20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f  sqlite3_open() o
26d30 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
26d40 32 28 29 2e 20 20 4f 74 68 65 72 77 69 73 65 2c  2().  Otherwise,
26d50 20 76 61 72 69 6f 75 73 0a 2a 2a 20 66 65 61 74   various.** feat
26d60 75 72 65 73 20 74 68 61 74 20 72 65 71 75 69 72  ures that requir
26d70 65 20 74 68 65 20 75 73 65 20 6f 66 20 74 65 6d  e the use of tem
26d80 70 6f 72 61 72 79 20 66 69 6c 65 73 20 6d 61 79  porary files may
26d90 20 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20 53 65 65   fail..**.** See
26da0 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f   also: [sqlite3_
26db0 74 65 6d 70 5f 64 69 72 65 63 74 6f 72 79 5d 0a  temp_directory].
26dc0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f  */.int sqlite3_o
26dd0 70 65 6e 28 0a 20 20 63 6f 6e 73 74 20 63 68 61  pen(.  const cha
26de0 72 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f  r *filename,   /
26df0 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e  * Database filen
26e00 61 6d 65 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20  ame (UTF-8) */. 
26e10 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 20   sqlite3 **ppDb 
26e20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a           /* OUT:
26e30 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c   SQLite db handl
26e40 65 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69  e */.);.int sqli
26e50 74 65 33 5f 6f 70 65 6e 31 36 28 0a 20 20 63 6f  te3_open16(.  co
26e60 6e 73 74 20 76 6f 69 64 20 2a 66 69 6c 65 6e 61  nst void *filena
26e70 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73  me,   /* Databas
26e80 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d  e filename (UTF-
26e90 31 36 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33  16) */.  sqlite3
26ea0 20 2a 2a 70 70 44 62 20 20 20 20 20 20 20 20 20   **ppDb         
26eb0 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 20   /* OUT: SQLite 
26ec0 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a  db handle */.);.
26ed0 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  int sqlite3_open
26ee0 5f 76 32 28 0a 20 20 63 6f 6e 73 74 20 63 68 61  _v2(.  const cha
26ef0 72 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f  r *filename,   /
26f00 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e  * Database filen
26f10 61 6d 65 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20  ame (UTF-8) */. 
26f20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 2c   sqlite3 **ppDb,
26f30 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a           /* OUT:
26f40 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c   SQLite db handl
26f50 65 20 2a 2f 0a 20 20 69 6e 74 20 66 6c 61 67 73  e */.  int flags
26f60 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f  ,              /
26f70 2a 20 46 6c 61 67 73 20 2a 2f 0a 20 20 63 6f 6e  * Flags */.  con
26f80 73 74 20 63 68 61 72 20 2a 7a 56 66 73 20 20 20  st char *zVfs   
26f90 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20       /* Name of 
26fa0 56 46 53 20 6d 6f 64 75 6c 65 20 74 6f 20 75 73  VFS module to us
26fb0 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  e */.);../*.** C
26fc0 41 50 49 33 52 45 46 3a 20 4f 62 74 61 69 6e 20  API3REF: Obtain 
26fd0 56 61 6c 75 65 73 20 46 6f 72 20 55 52 49 20 50  Values For URI P
26fe0 61 72 61 6d 65 74 65 72 73 0a 2a 2a 0a 2a 2a 20  arameters.**.** 
26ff0 54 68 65 73 65 20 61 72 65 20 75 74 69 6c 69 74  These are utilit
27000 79 20 72 6f 75 74 69 6e 65 73 2c 20 75 73 65 66  y routines, usef
27010 75 6c 20 74 6f 20 56 46 53 20 69 6d 70 6c 65 6d  ul to VFS implem
27020 65 6e 74 61 74 69 6f 6e 73 2c 20 74 68 61 74 20  entations, that 
27030 63 68 65 63 6b 0a 2a 2a 20 74 6f 20 73 65 65 20  check.** to see 
27040 69 66 20 61 20 64 61 74 61 62 61 73 65 20 66 69  if a database fi
27050 6c 65 20 77 61 73 20 61 20 55 52 49 20 74 68 61  le was a URI tha
27060 74 20 63 6f 6e 74 61 69 6e 65 64 20 61 20 73 70  t contained a sp
27070 65 63 69 66 69 63 20 71 75 65 72 79 20 0a 2a 2a  ecific query .**
27080 20 70 61 72 61 6d 65 74 65 72 2c 20 61 6e 64 20   parameter, and 
27090 69 66 20 73 6f 20 6f 62 74 61 69 6e 73 20 74 68  if so obtains th
270a0 65 20 76 61 6c 75 65 20 6f 66 20 74 68 61 74 20  e value of that 
270b0 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 2e  query parameter.
270c0 0a 2a 2a 0a 2a 2a 20 49 66 20 46 20 69 73 20 74  .**.** If F is t
270d0 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
270e0 6e 61 6d 65 20 70 6f 69 6e 74 65 72 20 70 61 73  name pointer pas
270f0 73 65 64 20 69 6e 74 6f 20 74 68 65 20 78 4f 70  sed into the xOp
27100 65 6e 28 29 20 6d 65 74 68 6f 64 20 6f 66 20 0a  en() method of .
27110 2a 2a 20 61 20 56 46 53 20 69 6d 70 6c 65 6d 65  ** a VFS impleme
27120 6e 74 61 74 69 6f 6e 20 77 68 65 6e 20 74 68 65  ntation when the
27130 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72   flags parameter
27140 20 74 6f 20 78 4f 70 65 6e 28 29 20 68 61 73 20   to xOpen() has 
27150 6f 6e 65 20 6f 72 20 0a 2a 2a 20 6d 6f 72 65 20  one or .** more 
27160 6f 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f  of the [SQLITE_O
27170 50 45 4e 5f 55 52 49 5d 20 6f 72 20 5b 53 51 4c  PEN_URI] or [SQL
27180 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42  ITE_OPEN_MAIN_DB
27190 5d 20 62 69 74 73 20 73 65 74 20 61 6e 64 0a 2a  ] bits set and.*
271a0 2a 20 50 20 69 73 20 74 68 65 20 6e 61 6d 65 20  * P is the name 
271b0 6f 66 20 74 68 65 20 71 75 65 72 79 20 70 61 72  of the query par
271c0 61 6d 65 74 65 72 2c 20 74 68 65 6e 0a 2a 2a 20  ameter, then.** 
271d0 73 71 6c 69 74 65 33 5f 75 72 69 5f 70 61 72 61  sqlite3_uri_para
271e0 6d 65 74 65 72 28 46 2c 50 29 20 72 65 74 75 72  meter(F,P) retur
271f0 6e 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20  ns the value of 
27200 74 68 65 20 50 0a 2a 2a 20 70 61 72 61 6d 65 74  the P.** paramet
27210 65 72 20 69 66 20 69 74 20 65 78 69 73 74 73 20  er if it exists 
27220 6f 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  or a NULL pointe
27230 72 20 69 66 20 50 20 64 6f 65 73 20 6e 6f 74 20  r if P does not 
27240 61 70 70 65 61 72 20 61 73 20 61 20 0a 2a 2a 20  appear as a .** 
27250 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 20  query parameter 
27260 6f 6e 20 46 2e 20 20 49 66 20 50 20 69 73 20 61  on F.  If P is a
27270 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72   query parameter
27280 20 6f 66 20 46 0a 2a 2a 20 68 61 73 20 6e 6f 20   of F.** has no 
27290 65 78 70 6c 69 63 69 74 20 76 61 6c 75 65 2c 20  explicit value, 
272a0 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 75 72 69  then sqlite3_uri
272b0 5f 70 61 72 61 6d 65 74 65 72 28 46 2c 50 29 20  _parameter(F,P) 
272c0 72 65 74 75 72 6e 73 0a 2a 2a 20 61 20 70 6f 69  returns.** a poi
272d0 6e 74 65 72 20 74 6f 20 61 6e 20 65 6d 70 74 79  nter to an empty
272e0 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54   string..**.** T
272f0 68 65 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62  he sqlite3_uri_b
27300 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 6f  oolean(F,P,B) ro
27310 75 74 69 6e 65 20 61 73 73 75 6d 65 73 20 74 68  utine assumes th
27320 61 74 20 50 20 69 73 20 61 20 62 6f 6f 6c 65 61  at P is a boolea
27330 6e 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 61  n.** parameter a
27340 6e 64 20 72 65 74 75 72 6e 73 20 74 72 75 65 20  nd returns true 
27350 28 31 29 20 6f 72 20 66 61 6c 73 65 20 28 30 29  (1) or false (0)
27360 20 61 63 63 6f 72 64 69 6e 67 20 74 6f 20 74 68   according to th
27370 65 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 50 2e  e value.** of P.
27380 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 75 72    The sqlite3_ur
27390 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29  i_boolean(F,P,B)
273a0 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
273b0 20 74 72 75 65 20 28 31 29 20 69 66 20 74 68 65   true (1) if the
273c0 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 71 75 65  .** value of que
273d0 72 79 20 70 61 72 61 6d 65 74 65 72 20 50 20 69  ry parameter P i
273e0 73 20 6f 6e 65 20 6f 66 20 22 79 65 73 22 2c 20  s one of "yes", 
273f0 22 74 72 75 65 22 2c 20 6f 72 20 22 6f 6e 22 20  "true", or "on" 
27400 69 6e 20 61 6e 79 0a 2a 2a 20 63 61 73 65 20 6f  in any.** case o
27410 72 20 69 66 20 74 68 65 20 76 61 6c 75 65 20 62  r if the value b
27420 65 67 69 6e 73 20 77 69 74 68 20 61 20 6e 6f 6e  egins with a non
27430 2d 7a 65 72 6f 20 6e 75 6d 62 65 72 2e 20 20 54  -zero number.  T
27440 68 65 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75  he .** sqlite3_u
27450 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42  ri_boolean(F,P,B
27460 29 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  ) routines retur
27470 6e 73 20 66 61 6c 73 65 20 28 30 29 20 69 66 20  ns false (0) if 
27480 74 68 65 20 76 61 6c 75 65 20 6f 66 0a 2a 2a 20  the value of.** 
27490 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 20  query parameter 
274a0 50 20 69 73 20 6f 6e 65 20 6f 66 20 22 6e 6f 22  P is one of "no"
274b0 2c 20 22 66 61 6c 73 65 22 2c 20 6f 72 20 22 6f  , "false", or "o
274c0 66 66 22 20 69 6e 20 61 6e 79 20 63 61 73 65 20  ff" in any case 
274d0 6f 72 0a 2a 2a 20 69 66 20 74 68 65 20 76 61 6c  or.** if the val
274e0 75 65 20 62 65 67 69 6e 73 20 77 69 74 68 20 61  ue begins with a
274f0 20 6e 75 6d 65 72 69 63 20 7a 65 72 6f 2e 20 20   numeric zero.  
27500 49 66 20 50 20 69 73 20 6e 6f 74 20 61 20 71 75  If P is not a qu
27510 65 72 79 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  ery.** parameter
27520 20 6f 6e 20 46 20 6f 72 20 69 66 20 74 68 65 20   on F or if the 
27530 76 61 6c 75 65 20 6f 66 20 50 20 69 73 20 64 6f  value of P is do
27540 65 73 20 6e 6f 74 20 6d 61 74 63 68 20 61 6e 79  es not match any
27550 20 6f 66 20 74 68 65 0a 2a 2a 20 61 62 6f 76 65   of the.** above
27560 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 75  , then sqlite3_u
27570 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42  ri_boolean(F,P,B
27580 29 20 72 65 74 75 72 6e 73 20 28 42 21 3d 30 29  ) returns (B!=0)
27590 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
275a0 74 65 33 5f 75 72 69 5f 69 6e 74 36 34 28 46 2c  te3_uri_int64(F,
275b0 50 2c 44 29 20 72 6f 75 74 69 6e 65 20 63 6f 6e  P,D) routine con
275c0 76 65 72 74 73 20 74 68 65 20 76 61 6c 75 65 20  verts the value 
275d0 6f 66 20 50 20 69 6e 74 6f 20 61 0a 2a 2a 20 36  of P into a.** 6
275e0 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74  4-bit signed int
275f0 65 67 65 72 20 61 6e 64 20 72 65 74 75 72 6e 73  eger and returns
27600 20 74 68 61 74 20 69 6e 74 65 67 65 72 2c 20 6f   that integer, o
27610 72 20 44 20 69 66 20 50 20 64 6f 65 73 20 6e 6f  r D if P does no
27620 74 0a 2a 2a 20 65 78 69 73 74 2e 20 20 49 66 20  t.** exist.  If 
27630 74 68 65 20 76 61 6c 75 65 20 6f 66 20 50 20 69  the value of P i
27640 73 20 73 6f 6d 65 74 68 69 6e 67 20 6f 74 68 65  s something othe
27650 72 20 74 68 61 6e 20 61 6e 20 69 6e 74 65 67 65  r than an intege
27660 72 2c 20 74 68 65 6e 0a 2a 2a 20 7a 65 72 6f 20  r, then.** zero 
27670 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20  is returned..** 
27680 0a 2a 2a 20 49 66 20 46 20 69 73 20 61 20 4e 55  .** If F is a NU
27690 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e  LL pointer, then
276a0 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 70 61 72   sqlite3_uri_par
276b0 61 6d 65 74 65 72 28 46 2c 50 29 20 72 65 74 75  ameter(F,P) retu
276c0 72 6e 73 20 4e 55 4c 4c 20 61 6e 64 0a 2a 2a 20  rns NULL and.** 
276d0 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c  sqlite3_uri_bool
276e0 65 61 6e 28 46 2c 50 2c 42 29 20 72 65 74 75 72  ean(F,P,B) retur
276f0 6e 73 20 42 2e 20 20 49 66 20 46 20 69 73 20 6e  ns B.  If F is n
27700 6f 74 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  ot a NULL pointe
27710 72 20 61 6e 64 0a 2a 2a 20 69 73 20 6e 6f 74 20  r and.** is not 
27720 61 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  a database file 
27730 70 61 74 68 6e 61 6d 65 20 70 6f 69 6e 74 65 72  pathname pointer
27740 20 74 68 61 74 20 53 51 4c 69 74 65 20 70 61 73   that SQLite pas
27750 73 65 64 20 69 6e 74 6f 20 74 68 65 20 78 4f 70  sed into the xOp
27760 65 6e 0a 2a 2a 20 56 46 53 20 6d 65 74 68 6f 64  en.** VFS method
27770 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76  , then the behav
27780 69 6f 72 20 6f 66 20 74 68 69 73 20 72 6f 75 74  ior of this rout
27790 69 6e 65 20 69 73 20 75 6e 64 65 66 69 6e 65 64  ine is undefined
277a0 20 61 6e 64 20 70 72 6f 62 61 62 6c 79 0a 2a 2a   and probably.**
277b0 20 75 6e 64 65 73 69 72 61 62 6c 65 2e 0a 2a 2f   undesirable..*/
277c0 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  .const char *sql
277d0 69 74 65 33 5f 75 72 69 5f 70 61 72 61 6d 65 74  ite3_uri_paramet
277e0 65 72 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  er(const char *z
277f0 46 69 6c 65 6e 61 6d 65 2c 20 63 6f 6e 73 74 20  Filename, const 
27800 63 68 61 72 20 2a 7a 50 61 72 61 6d 29 3b 0a 69  char *zParam);.i
27810 6e 74 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62  nt sqlite3_uri_b
27820 6f 6f 6c 65 61 6e 28 63 6f 6e 73 74 20 63 68 61  oolean(const cha
27830 72 20 2a 7a 46 69 6c 65 2c 20 63 6f 6e 73 74 20  r *zFile, const 
27840 63 68 61 72 20 2a 7a 50 61 72 61 6d 2c 20 69 6e  char *zParam, in
27850 74 20 62 44 65 66 61 75 6c 74 29 3b 0a 73 71 6c  t bDefault);.sql
27860 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74  ite3_int64 sqlit
27870 65 33 5f 75 72 69 5f 69 6e 74 36 34 28 63 6f 6e  e3_uri_int64(con
27880 73 74 20 63 68 61 72 2a 2c 20 63 6f 6e 73 74 20  st char*, const 
27890 63 68 61 72 2a 2c 20 73 71 6c 69 74 65 33 5f 69  char*, sqlite3_i
278a0 6e 74 36 34 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43  nt64);.../*.** C
278b0 41 50 49 33 52 45 46 3a 20 45 72 72 6f 72 20 43  API3REF: Error C
278c0 6f 64 65 73 20 41 6e 64 20 4d 65 73 73 61 67 65  odes And Message
278d0 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  s.** METHOD: sql
278e0 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  ite3.**.** ^If t
278f0 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 73  he most recent s
27900 71 6c 69 74 65 33 5f 2a 20 41 50 49 20 63 61 6c  qlite3_* API cal
27910 6c 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74  l associated wit
27920 68 20 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20  h .** [database 
27930 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 66 61  connection] D fa
27940 69 6c 65 64 2c 20 74 68 65 6e 20 74 68 65 20 73  iled, then the s
27950 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 44  qlite3_errcode(D
27960 29 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 72  ) interface.** r
27970 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 65 72  eturns the numer
27980 69 63 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d  ic [result code]
27990 20 6f 72 20 5b 65 78 74 65 6e 64 65 64 20 72 65   or [extended re
279a0 73 75 6c 74 20 63 6f 64 65 5d 20 66 6f 72 20 74  sult code] for t
279b0 68 61 74 0a 2a 2a 20 41 50 49 20 63 61 6c 6c 2e  hat.** API call.
279c0 0a 2a 2a 20 49 66 20 74 68 65 20 6d 6f 73 74 20  .** If the most 
279d0 72 65 63 65 6e 74 20 41 50 49 20 63 61 6c 6c 20  recent API call 
279e0 77 61 73 20 73 75 63 63 65 73 73 66 75 6c 2c 0a  was successful,.
279f0 2a 2a 20 74 68 65 6e 20 74 68 65 20 72 65 74 75  ** then the retu
27a00 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71  rn value from sq
27a10 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 20  lite3_errcode() 
27a20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  is undefined..**
27a30 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78   ^The sqlite3_ex
27a40 74 65 6e 64 65 64 5f 65 72 72 63 6f 64 65 28 29  tended_errcode()
27a50 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73  .** interface is
27a60 20 74 68 65 20 73 61 6d 65 20 65 78 63 65 70 74   the same except
27a70 20 74 68 61 74 20 69 74 20 61 6c 77 61 79 73 20   that it always 
27a80 72 65 74 75 72 6e 73 20 74 68 65 20 0a 2a 2a 20  returns the .** 
27a90 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74  [extended result
27aa0 20 63 6f 64 65 5d 20 65 76 65 6e 20 77 68 65 6e   code] even when
27ab0 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74   extended result
27ac0 20 63 6f 64 65 73 20 61 72 65 0a 2a 2a 20 64 69   codes are.** di
27ad0 73 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54  sabled..**.** ^T
27ae0 68 65 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  he sqlite3_errms
27af0 67 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  g() and sqlite3_
27b00 65 72 72 6d 73 67 31 36 28 29 20 72 65 74 75 72  errmsg16() retur
27b10 6e 20 45 6e 67 6c 69 73 68 2d 6c 61 6e 67 75 61  n English-langua
27b20 67 65 0a 2a 2a 20 74 65 78 74 20 74 68 61 74 20  ge.** text that 
27b30 64 65 73 63 72 69 62 65 73 20 74 68 65 20 65 72  describes the er
27b40 72 6f 72 2c 20 61 73 20 65 69 74 68 65 72 20 55  ror, as either U
27b50 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 20 72  TF-8 or UTF-16 r
27b60 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20  espectively..** 
27b70 5e 28 4d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64  ^(Memory to hold
27b80 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61   the error messa
27b90 67 65 20 73 74 72 69 6e 67 20 69 73 20 6d 61 6e  ge string is man
27ba0 61 67 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 2e  aged internally.
27bb0 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74  .** The applicat
27bc0 69 6f 6e 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65  ion does not nee
27bd0 64 20 74 6f 20 77 6f 72 72 79 20 61 62 6f 75 74  d to worry about
27be0 20 66 72 65 65 69 6e 67 20 74 68 65 20 72 65 73   freeing the res
27bf0 75 6c 74 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c  ult..** However,
27c00 20 74 68 65 20 65 72 72 6f 72 20 73 74 72 69 6e   the error strin
27c10 67 20 6d 69 67 68 74 20 62 65 20 6f 76 65 72 77  g might be overw
27c20 72 69 74 74 65 6e 20 6f 72 20 64 65 61 6c 6c 6f  ritten or deallo
27c30 63 61 74 65 64 20 62 79 0a 2a 2a 20 73 75 62 73  cated by.** subs
27c40 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20  equent calls to 
27c50 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74  other SQLite int
27c60 65 72 66 61 63 65 20 66 75 6e 63 74 69 6f 6e 73  erface functions
27c70 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  .)^.**.** ^The s
27c80 71 6c 69 74 65 33 5f 65 72 72 73 74 72 28 29 20  qlite3_errstr() 
27c90 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
27ca0 73 20 74 68 65 20 45 6e 67 6c 69 73 68 2d 6c 61  s the English-la
27cb0 6e 67 75 61 67 65 20 74 65 78 74 0a 2a 2a 20 74  nguage text.** t
27cc0 68 61 74 20 64 65 73 63 72 69 62 65 73 20 74 68  hat describes th
27cd0 65 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d 2c  e [result code],
27ce0 20 61 73 20 55 54 46 2d 38 2e 0a 2a 2a 20 5e 28   as UTF-8..** ^(
27cf0 4d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74  Memory to hold t
27d00 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  he error message
27d10 20 73 74 72 69 6e 67 20 69 73 20 6d 61 6e 61 67   string is manag
27d20 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 0a 2a 2a  ed internally.**
27d30 20 61 6e 64 20 6d 75 73 74 20 6e 6f 74 20 62 65   and must not be
27d40 20 66 72 65 65 64 20 62 79 20 74 68 65 20 61 70   freed by the ap
27d50 70 6c 69 63 61 74 69 6f 6e 29 5e 2e 0a 2a 2a 0a  plication)^..**.
27d60 2a 2a 20 57 68 65 6e 20 74 68 65 20 73 65 72 69  ** When the seri
27d70 61 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e  alized [threadin
27d80 67 20 6d 6f 64 65 5d 20 69 73 20 69 6e 20 75 73  g mode] is in us
27d90 65 2c 20 69 74 20 6d 69 67 68 74 20 62 65 20 74  e, it might be t
27da0 68 65 0a 2a 2a 20 63 61 73 65 20 74 68 61 74 20  he.** case that 
27db0 61 20 73 65 63 6f 6e 64 20 65 72 72 6f 72 20 6f  a second error o
27dc0 63 63 75 72 73 20 6f 6e 20 61 20 73 65 70 61 72  ccurs on a separ
27dd0 61 74 65 20 74 68 72 65 61 64 20 69 6e 20 62 65  ate thread in be
27de0 74 77 65 65 6e 0a 2a 2a 20 74 68 65 20 74 69 6d  tween.** the tim
27df0 65 20 6f 66 20 74 68 65 20 66 69 72 73 74 20 65  e of the first e
27e00 72 72 6f 72 20 61 6e 64 20 74 68 65 20 63 61 6c  rror and the cal
27e10 6c 20 74 6f 20 74 68 65 73 65 20 69 6e 74 65 72  l to these inter
27e20 66 61 63 65 73 2e 0a 2a 2a 20 57 68 65 6e 20 74  faces..** When t
27e30 68 61 74 20 68 61 70 70 65 6e 73 2c 20 74 68 65  hat happens, the
27e40 20 73 65 63 6f 6e 64 20 65 72 72 6f 72 20 77 69   second error wi
27e50 6c 6c 20 62 65 20 72 65 70 6f 72 74 65 64 20 73  ll be reported s
27e60 69 6e 63 65 20 74 68 65 73 65 0a 2a 2a 20 69 6e  ince these.** in
27e70 74 65 72 66 61 63 65 73 20 61 6c 77 61 79 73 20  terfaces always 
27e80 72 65 70 6f 72 74 20 74 68 65 20 6d 6f 73 74 20  report the most 
27e90 72 65 63 65 6e 74 20 72 65 73 75 6c 74 2e 20 20  recent result.  
27ea0 54 6f 20 61 76 6f 69 64 0a 2a 2a 20 74 68 69 73  To avoid.** this
27eb0 2c 20 65 61 63 68 20 74 68 72 65 61 64 20 63 61  , each thread ca
27ec0 6e 20 6f 62 74 61 69 6e 20 65 78 63 6c 75 73 69  n obtain exclusi
27ed0 76 65 20 75 73 65 20 6f 66 20 74 68 65 20 5b 64  ve use of the [d
27ee0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
27ef0 6f 6e 5d 20 44 0a 2a 2a 20 62 79 20 69 6e 76 6f  on] D.** by invo
27f00 6b 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75  king [sqlite3_mu
27f10 74 65 78 5f 65 6e 74 65 72 5d 28 5b 73 71 6c 69  tex_enter]([sqli
27f20 74 65 33 5f 64 62 5f 6d 75 74 65 78 5d 28 44 29  te3_db_mutex](D)
27f30 29 20 62 65 66 6f 72 65 20 62 65 67 69 6e 6e 69  ) before beginni
27f40 6e 67 0a 2a 2a 20 74 6f 20 75 73 65 20 44 20 61  ng.** to use D a
27f50 6e 64 20 69 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c  nd invoking [sql
27f60 69 74 65 33 5f 6d 75 74 65 78 5f 6c 65 61 76 65  ite3_mutex_leave
27f70 5d 28 5b 73 71 6c 69 74 65 33 5f 64 62 5f 6d 75  ]([sqlite3_db_mu
27f80 74 65 78 5d 28 44 29 29 20 61 66 74 65 72 0a 2a  tex](D)) after.*
27f90 2a 20 61 6c 6c 20 63 61 6c 6c 73 20 74 6f 20 74  * all calls to t
27fa0 68 65 20 69 6e 74 65 72 66 61 63 65 73 20 6c 69  he interfaces li
27fb0 73 74 65 64 20 68 65 72 65 20 61 72 65 20 63 6f  sted here are co
27fc0 6d 70 6c 65 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 49  mpleted..**.** I
27fd0 66 20 61 6e 20 69 6e 74 65 72 66 61 63 65 20 66  f an interface f
27fe0 61 69 6c 73 20 77 69 74 68 20 53 51 4c 49 54 45  ails with SQLITE
27ff0 5f 4d 49 53 55 53 45 2c 20 74 68 61 74 20 6d 65  _MISUSE, that me
28000 61 6e 73 20 74 68 65 20 69 6e 74 65 72 66 61 63  ans the interfac
28010 65 0a 2a 2a 20 77 61 73 20 69 6e 76 6f 6b 65 64  e.** was invoked
28020 20 69 6e 63 6f 72 72 65 63 74 6c 79 20 62 79 20   incorrectly by 
28030 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e  the application.
28040 20 20 49 6e 20 74 68 61 74 20 63 61 73 65 2c 20    In that case, 
28050 74 68 65 0a 2a 2a 20 65 72 72 6f 72 20 63 6f 64  the.** error cod
28060 65 20 61 6e 64 20 6d 65 73 73 61 67 65 20 6d 61  e and message ma
28070 79 20 6f 72 20 6d 61 79 20 6e 6f 74 20 62 65 20  y or may not be 
28080 73 65 74 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  set..*/.int sqli
28090 74 65 33 5f 65 72 72 63 6f 64 65 28 73 71 6c 69  te3_errcode(sqli
280a0 74 65 33 20 2a 64 62 29 3b 0a 69 6e 74 20 73 71  te3 *db);.int sq
280b0 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 65  lite3_extended_e
280c0 72 72 63 6f 64 65 28 73 71 6c 69 74 65 33 20 2a  rrcode(sqlite3 *
280d0 64 62 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20  db);.const char 
280e0 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28  *sqlite3_errmsg(
280f0 73 71 6c 69 74 65 33 2a 29 3b 0a 63 6f 6e 73 74  sqlite3*);.const
28100 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 65   void *sqlite3_e
28110 72 72 6d 73 67 31 36 28 73 71 6c 69 74 65 33 2a  rrmsg16(sqlite3*
28120 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  );.const char *s
28130 71 6c 69 74 65 33 5f 65 72 72 73 74 72 28 69 6e  qlite3_errstr(in
28140 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
28150 52 45 46 3a 20 50 72 65 70 61 72 65 64 20 53 74  REF: Prepared St
28160 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a  atement Object.*
28170 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70 72 65  * KEYWORDS: {pre
28180 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 7d  pared statement}
28190 20 7b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   {prepared state
281a0 6d 65 6e 74 73 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20  ments}.**.** An 
281b0 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73  instance of this
281c0 20 6f 62 6a 65 63 74 20 72 65 70 72 65 73 65 6e   object represen
281d0 74 73 20 61 20 73 69 6e 67 6c 65 20 53 51 4c 20  ts a single SQL 
281e0 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74 0a 2a  statement that.*
281f0 2a 20 68 61 73 20 62 65 65 6e 20 63 6f 6d 70 69  * has been compi
28200 6c 65 64 20 69 6e 74 6f 20 62 69 6e 61 72 79 20  led into binary 
28210 66 6f 72 6d 20 61 6e 64 20 69 73 20 72 65 61 64  form and is read
28220 79 20 74 6f 20 62 65 20 65 76 61 6c 75 61 74 65  y to be evaluate
28230 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 6e 6b 20 6f  d..**.** Think o
28240 66 20 65 61 63 68 20 53 51 4c 20 73 74 61 74 65  f each SQL state
28250 6d 65 6e 74 20 61 73 20 61 20 73 65 70 61 72 61  ment as a separa
28260 74 65 20 63 6f 6d 70 75 74 65 72 20 70 72 6f 67  te computer prog
28270 72 61 6d 2e 20 20 54 68 65 0a 2a 2a 20 6f 72 69  ram.  The.** ori
28280 67 69 6e 61 6c 20 53 51 4c 20 74 65 78 74 20 69  ginal SQL text i
28290 73 20 73 6f 75 72 63 65 20 63 6f 64 65 2e 20 20  s source code.  
282a0 41 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  A prepared state
282b0 6d 65 6e 74 20 6f 62 6a 65 63 74 20 0a 2a 2a 20  ment object .** 
282c0 69 73 20 74 68 65 20 63 6f 6d 70 69 6c 65 64 20  is the compiled 
282d0 6f 62 6a 65 63 74 20 63 6f 64 65 2e 20 20 41 6c  object code.  Al
282e0 6c 20 53 51 4c 20 6d 75 73 74 20 62 65 20 63 6f  l SQL must be co
282f0 6e 76 65 72 74 65 64 20 69 6e 74 6f 20 61 0a 2a  nverted into a.*
28300 2a 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  * prepared state
28310 6d 65 6e 74 20 62 65 66 6f 72 65 20 69 74 20 63  ment before it c
28320 61 6e 20 62 65 20 72 75 6e 2e 0a 2a 2a 0a 2a 2a  an be run..**.**
28330 20 54 68 65 20 6c 69 66 65 2d 63 79 63 6c 65 20   The life-cycle 
28340 6f 66 20 61 20 70 72 65 70 61 72 65 64 20 73 74  of a prepared st
28350 61 74 65 6d 65 6e 74 20 6f 62 6a 65 63 74 20 75  atement object u
28360 73 75 61 6c 6c 79 20 67 6f 65 73 20 6c 69 6b 65  sually goes like
28370 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c   this:.**.** <ol
28380 3e 0a 2a 2a 20 3c 6c 69 3e 20 43 72 65 61 74 65  >.** <li> Create
28390 20 74 68 65 20 70 72 65 70 61 72 65 64 20 73 74   the prepared st
283a0 61 74 65 6d 65 6e 74 20 6f 62 6a 65 63 74 20 75  atement object u
283b0 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72  sing [sqlite3_pr
283c0 65 70 61 72 65 5f 76 32 28 29 5d 2e 0a 2a 2a 20  epare_v2()]..** 
283d0 3c 6c 69 3e 20 42 69 6e 64 20 76 61 6c 75 65 73  <li> Bind values
283e0 20 74 6f 20 5b 70 61 72 61 6d 65 74 65 72 73 5d   to [parameters]
283f0 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69 74   using the sqlit
28400 65 33 5f 62 69 6e 64 5f 2a 28 29 0a 2a 2a 20 20  e3_bind_*().**  
28410 20 20 20 20 69 6e 74 65 72 66 61 63 65 73 2e 0a      interfaces..
28420 2a 2a 20 3c 6c 69 3e 20 52 75 6e 20 74 68 65 20  ** <li> Run the 
28430 53 51 4c 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b  SQL by calling [
28440 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
28450 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65  one or more time
28460 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 65 73 65 74  s..** <li> Reset
28470 20 74 68 65 20 70 72 65 70 61 72 65 64 20 73 74   the prepared st
28480 61 74 65 6d 65 6e 74 20 75 73 69 6e 67 20 5b 73  atement using [s
28490 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
284a0 74 68 65 6e 20 67 6f 20 62 61 63 6b 0a 2a 2a 20  then go back.** 
284b0 20 20 20 20 20 74 6f 20 73 74 65 70 20 32 2e 20       to step 2. 
284c0 20 44 6f 20 74 68 69 73 20 7a 65 72 6f 20 6f 72   Do this zero or
284d0 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a 2a 2a 20   more times..** 
284e0 3c 6c 69 3e 20 44 65 73 74 72 6f 79 20 74 68 65  <li> Destroy the
284f0 20 6f 62 6a 65 63 74 20 75 73 69 6e 67 20 5b 73   object using [s
28500 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
28510 29 5d 2e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2f 0a  )]..** </ol>.*/.
28520 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73  typedef struct s
28530 71 6c 69 74 65 33 5f 73 74 6d 74 20 73 71 6c 69  qlite3_stmt sqli
28540 74 65 33 5f 73 74 6d 74 3b 0a 0a 2f 2a 0a 2a 2a  te3_stmt;../*.**
28550 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 74   CAPI3REF: Run-t
28560 69 6d 65 20 4c 69 6d 69 74 73 0a 2a 2a 20 4d 45  ime Limits.** ME
28570 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a  THOD: sqlite3.**
28580 0a 2a 2a 20 5e 28 54 68 69 73 20 69 6e 74 65 72  .** ^(This inter
28590 66 61 63 65 20 61 6c 6c 6f 77 73 20 74 68 65 20  face allows the 
285a0 73 69 7a 65 20 6f 66 20 76 61 72 69 6f 75 73 20  size of various 
285b0 63 6f 6e 73 74 72 75 63 74 73 20 74 6f 20 62 65  constructs to be
285c0 20 6c 69 6d 69 74 65 64 0a 2a 2a 20 6f 6e 20 61   limited.** on a
285d0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 79 20 63   connection by c
285e0 6f 6e 6e 65 63 74 69 6f 6e 20 62 61 73 69 73 2e  onnection basis.
285f0 20 20 54 68 65 20 66 69 72 73 74 20 70 61 72 61    The first para
28600 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20  meter is the.** 
28610 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
28620 74 69 6f 6e 5d 20 77 68 6f 73 65 20 6c 69 6d 69  tion] whose limi
28630 74 20 69 73 20 74 6f 20 62 65 20 73 65 74 20 6f  t is to be set o
28640 72 20 71 75 65 72 69 65 64 2e 20 20 54 68 65 0a  r queried.  The.
28650 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  ** second parame
28660 74 65 72 20 69 73 20 6f 6e 65 20 6f 66 20 74 68  ter is one of th
28670 65 20 5b 6c 69 6d 69 74 20 63 61 74 65 67 6f 72  e [limit categor
28680 69 65 73 5d 20 74 68 61 74 20 64 65 66 69 6e 65  ies] that define
28690 20 61 0a 2a 2a 20 63 6c 61 73 73 20 6f 66 20 63   a.** class of c
286a0 6f 6e 73 74 72 75 63 74 73 20 74 6f 20 62 65 20  onstructs to be 
286b0 73 69 7a 65 20 6c 69 6d 69 74 65 64 2e 20 20 54  size limited.  T
286c0 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  he third paramet
286d0 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 6e 65 77  er is the.** new
286e0 20 6c 69 6d 69 74 20 66 6f 72 20 74 68 61 74 20   limit for that 
286f0 63 6f 6e 73 74 72 75 63 74 2e 29 5e 0a 2a 2a 0a  construct.)^.**.
28700 2a 2a 20 5e 49 66 20 74 68 65 20 6e 65 77 20 6c  ** ^If the new l
28710 69 6d 69 74 20 69 73 20 61 20 6e 65 67 61 74 69  imit is a negati
28720 76 65 20 6e 75 6d 62 65 72 2c 20 74 68 65 20 6c  ve number, the l
28730 69 6d 69 74 20 69 73 20 75 6e 63 68 61 6e 67 65  imit is unchange
28740 64 2e 0a 2a 2a 20 5e 28 46 6f 72 20 65 61 63 68  d..** ^(For each
28750 20 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 79 20   limit category 
28760 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 3c 69 3e  SQLITE_LIMIT_<i>
28770 4e 41 4d 45 3c 2f 69 3e 20 74 68 65 72 65 20 69  NAME</i> there i
28780 73 20 61 20 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20  s a .** [limits 
28790 7c 20 68 61 72 64 20 75 70 70 65 72 20 62 6f 75  | hard upper bou
287a0 6e 64 5d 0a 2a 2a 20 73 65 74 20 61 74 20 63 6f  nd].** set at co
287b0 6d 70 69 6c 65 2d 74 69 6d 65 20 62 79 20 61 20  mpile-time by a 
287c0 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d  C preprocessor m
287d0 61 63 72 6f 20 63 61 6c 6c 65 64 0a 2a 2a 20 5b  acro called.** [
287e0 6c 69 6d 69 74 73 20 7c 20 53 51 4c 49 54 45 5f  limits | SQLITE_
287f0 4d 41 58 5f 3c 69 3e 4e 41 4d 45 3c 2f 69 3e 5d  MAX_<i>NAME</i>]
28800 2e 0a 2a 2a 20 28 54 68 65 20 22 5f 4c 49 4d 49  ..** (The "_LIMI
28810 54 5f 22 20 69 6e 20 74 68 65 20 6e 61 6d 65 20  T_" in the name 
28820 69 73 20 63 68 61 6e 67 65 64 20 74 6f 20 22 5f  is changed to "_
28830 4d 41 58 5f 22 2e 29 29 5e 0a 2a 2a 20 5e 41 74  MAX_".))^.** ^At
28840 74 65 6d 70 74 73 20 74 6f 20 69 6e 63 72 65 61  tempts to increa
28850 73 65 20 61 20 6c 69 6d 69 74 20 61 62 6f 76 65  se a limit above
28860 20 69 74 73 20 68 61 72 64 20 75 70 70 65 72 20   its hard upper 
28870 62 6f 75 6e 64 20 61 72 65 0a 2a 2a 20 73 69 6c  bound are.** sil
28880 65 6e 74 6c 79 20 74 72 75 6e 63 61 74 65 64 20  ently truncated 
28890 74 6f 20 74 68 65 20 68 61 72 64 20 75 70 70 65  to the hard uppe
288a0 72 20 62 6f 75 6e 64 2e 0a 2a 2a 0a 2a 2a 20 5e  r bound..**.** ^
288b0 52 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68  Regardless of wh
288c0 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65  ether or not the
288d0 20 6c 69 6d 69 74 20 77 61 73 20 63 68 61 6e 67   limit was chang
288e0 65 64 2c 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c  ed, the .** [sql
288f0 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 20 69 6e  ite3_limit()] in
28900 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
28910 74 68 65 20 70 72 69 6f 72 20 76 61 6c 75 65 20  the prior value 
28920 6f 66 20 74 68 65 20 6c 69 6d 69 74 2e 0a 2a 2a  of the limit..**
28930 20 5e 48 65 6e 63 65 2c 20 74 6f 20 66 69 6e 64   ^Hence, to find
28940 20 74 68 65 20 63 75 72 72 65 6e 74 20 76 61 6c   the current val
28950 75 65 20 6f 66 20 61 20 6c 69 6d 69 74 20 77 69  ue of a limit wi
28960 74 68 6f 75 74 20 63 68 61 6e 67 69 6e 67 20 69  thout changing i
28970 74 2c 0a 2a 2a 20 73 69 6d 70 6c 79 20 69 6e 76  t,.** simply inv
28980 6f 6b 65 20 74 68 69 73 20 69 6e 74 65 72 66 61  oke this interfa
28990 63 65 20 77 69 74 68 20 74 68 65 20 74 68 69 72  ce with the thir
289a0 64 20 70 61 72 61 6d 65 74 65 72 20 73 65 74 20  d parameter set 
289b0 74 6f 20 2d 31 2e 0a 2a 2a 0a 2a 2a 20 52 75 6e  to -1..**.** Run
289c0 2d 74 69 6d 65 20 6c 69 6d 69 74 73 20 61 72 65  -time limits are
289d0 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 73   intended for us
289e0 65 20 69 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  e in application
289f0 73 20 74 68 61 74 20 6d 61 6e 61 67 65 0a 2a 2a  s that manage.**
28a00 20 62 6f 74 68 20 74 68 65 69 72 20 6f 77 6e 20   both their own 
28a10 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 62 61 73  internal databas
28a20 65 20 61 6e 64 20 61 6c 73 6f 20 64 61 74 61 62  e and also datab
28a30 61 73 65 73 20 74 68 61 74 20 61 72 65 20 63 6f  ases that are co
28a40 6e 74 72 6f 6c 6c 65 64 0a 2a 2a 20 62 79 20 75  ntrolled.** by u
28a50 6e 74 72 75 73 74 65 64 20 65 78 74 65 72 6e 61  ntrusted externa
28a60 6c 20 73 6f 75 72 63 65 73 2e 20 20 41 6e 20 65  l sources.  An e
28a70 78 61 6d 70 6c 65 20 61 70 70 6c 69 63 61 74 69  xample applicati
28a80 6f 6e 20 6d 69 67 68 74 20 62 65 20 61 0a 2a 2a  on might be a.**
28a90 20 77 65 62 20 62 72 6f 77 73 65 72 20 74 68 61   web browser tha
28aa0 74 20 68 61 73 20 69 74 73 20 6f 77 6e 20 64 61  t has its own da
28ab0 74 61 62 61 73 65 73 20 66 6f 72 20 73 74 6f 72  tabases for stor
28ac0 69 6e 67 20 68 69 73 74 6f 72 79 20 61 6e 64 0a  ing history and.
28ad0 2a 2a 20 73 65 70 61 72 61 74 65 20 64 61 74 61  ** separate data
28ae0 62 61 73 65 73 20 63 6f 6e 74 72 6f 6c 6c 65 64  bases controlled
28af0 20 62 79 20 4a 61 76 61 53 63 72 69 70 74 20 61   by JavaScript a
28b00 70 70 6c 69 63 61 74 69 6f 6e 73 20 64 6f 77 6e  pplications down
28b10 6c 6f 61 64 65 64 0a 2a 2a 20 6f 66 66 20 74 68  loaded.** off th
28b20 65 20 49 6e 74 65 72 6e 65 74 2e 20 20 54 68 65  e Internet.  The
28b30 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 62 61   internal databa
28b40 73 65 73 20 63 61 6e 20 62 65 20 67 69 76 65 6e  ses can be given
28b50 20 74 68 65 0a 2a 2a 20 6c 61 72 67 65 2c 20 64   the.** large, d
28b60 65 66 61 75 6c 74 20 6c 69 6d 69 74 73 2e 20 20  efault limits.  
28b70 44 61 74 61 62 61 73 65 73 20 6d 61 6e 61 67 65  Databases manage
28b80 64 20 62 79 20 65 78 74 65 72 6e 61 6c 20 73 6f  d by external so
28b90 75 72 63 65 73 20 63 61 6e 0a 2a 2a 20 62 65 20  urces can.** be 
28ba0 67 69 76 65 6e 20 6d 75 63 68 20 73 6d 61 6c 6c  given much small
28bb0 65 72 20 6c 69 6d 69 74 73 20 64 65 73 69 67 6e  er limits design
28bc0 65 64 20 74 6f 20 70 72 65 76 65 6e 74 20 61 20  ed to prevent a 
28bd0 64 65 6e 69 61 6c 20 6f 66 20 73 65 72 76 69 63  denial of servic
28be0 65 0a 2a 2a 20 61 74 74 61 63 6b 2e 20 20 44 65  e.** attack.  De
28bf0 76 65 6c 6f 70 65 72 73 20 6d 69 67 68 74 20 61  velopers might a
28c00 6c 73 6f 20 77 61 6e 74 20 74 6f 20 75 73 65 20  lso want to use 
28c10 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74  the [sqlite3_set
28c20 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 5d 0a 2a  _authorizer()].*
28c30 2a 20 69 6e 74 65 72 66 61 63 65 20 74 6f 20 66  * interface to f
28c40 75 72 74 68 65 72 20 63 6f 6e 74 72 6f 6c 20 75  urther control u
28c50 6e 74 72 75 73 74 65 64 20 53 51 4c 2e 20 20 54  ntrusted SQL.  T
28c60 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 64  he size of the d
28c70 61 74 61 62 61 73 65 0a 2a 2a 20 63 72 65 61 74  atabase.** creat
28c80 65 64 20 62 79 20 61 6e 20 75 6e 74 72 75 73 74  ed by an untrust
28c90 65 64 20 73 63 72 69 70 74 20 63 61 6e 20 62 65  ed script can be
28ca0 20 63 6f 6e 74 61 69 6e 65 64 20 75 73 69 6e 67   contained using
28cb0 20 74 68 65 0a 2a 2a 20 5b 6d 61 78 5f 70 61 67   the.** [max_pag
28cc0 65 5f 63 6f 75 6e 74 5d 20 5b 50 52 41 47 4d 41  e_count] [PRAGMA
28cd0 5d 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 72 75 6e  ]..**.** New run
28ce0 2d 74 69 6d 65 20 6c 69 6d 69 74 20 63 61 74 65  -time limit cate
28cf0 67 6f 72 69 65 73 20 6d 61 79 20 62 65 20 61 64  gories may be ad
28d00 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65  ded in future re
28d10 6c 65 61 73 65 73 2e 0a 2a 2f 0a 69 6e 74 20 73  leases..*/.int s
28d20 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 73 71 6c  qlite3_limit(sql
28d30 69 74 65 33 2a 2c 20 69 6e 74 20 69 64 2c 20 69  ite3*, int id, i
28d40 6e 74 20 6e 65 77 56 61 6c 29 3b 0a 0a 2f 2a 0a  nt newVal);../*.
28d50 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e  ** CAPI3REF: Run
28d60 2d 54 69 6d 65 20 4c 69 6d 69 74 20 43 61 74 65  -Time Limit Cate
28d70 67 6f 72 69 65 73 0a 2a 2a 20 4b 45 59 57 4f 52  gories.** KEYWOR
28d80 44 53 3a 20 7b 6c 69 6d 69 74 20 63 61 74 65 67  DS: {limit categ
28d90 6f 72 79 7d 20 7b 2a 6c 69 6d 69 74 20 63 61 74  ory} {*limit cat
28da0 65 67 6f 72 69 65 73 7d 0a 2a 2a 0a 2a 2a 20 54  egories}.**.** T
28db0 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 64  hese constants d
28dc0 65 66 69 6e 65 20 76 61 72 69 6f 75 73 20 70 65  efine various pe
28dd0 72 66 6f 72 6d 61 6e 63 65 20 6c 69 6d 69 74 73  rformance limits
28de0 0a 2a 2a 20 74 68 61 74 20 63 61 6e 20 62 65 20  .** that can be 
28df0 6c 6f 77 65 72 65 64 20 61 74 20 72 75 6e 2d 74  lowered at run-t
28e00 69 6d 65 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ime using [sqlit
28e10 65 33 5f 6c 69 6d 69 74 28 29 5d 2e 0a 2a 2a 20  e3_limit()]..** 
28e20 54 68 65 20 73 79 6e 6f 70 73 69 73 20 6f 66 20  The synopsis of 
28e30 74 68 65 20 6d 65 61 6e 69 6e 67 73 20 6f 66 20  the meanings of 
28e40 74 68 65 20 76 61 72 69 6f 75 73 20 6c 69 6d 69  the various limi
28e50 74 73 20 69 73 20 73 68 6f 77 6e 20 62 65 6c 6f  ts is shown belo
28e60 77 2e 0a 2a 2a 20 41 64 64 69 74 69 6f 6e 61 6c  w..** Additional
28e70 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20   information is 
28e80 61 76 61 69 6c 61 62 6c 65 20 61 74 20 5b 6c 69  available at [li
28e90 6d 69 74 73 20 7c 20 4c 69 6d 69 74 73 20 69 6e  mits | Limits in
28ea0 20 53 51 4c 69 74 65 5d 2e 0a 2a 2a 0a 2a 2a 20   SQLite]..**.** 
28eb0 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  <dl>.** [[SQLITE
28ec0 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 5d 5d 20  _LIMIT_LENGTH]] 
28ed0 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d  ^(<dt>SQLITE_LIM
28ee0 49 54 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a  IT_LENGTH</dt>.*
28ef0 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
28f00 6d 20 73 69 7a 65 20 6f 66 20 61 6e 79 20 73 74  m size of any st
28f10 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20 6f 72 20  ring or BLOB or 
28f20 74 61 62 6c 65 20 72 6f 77 2c 20 69 6e 20 62 79  table row, in by
28f30 74 65 73 2e 3c 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a  tes.<dd>)^.**.**
28f40 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f   [[SQLITE_LIMIT_
28f50 53 51 4c 5f 4c 45 4e 47 54 48 5d 5d 20 5e 28 3c  SQL_LENGTH]] ^(<
28f60 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
28f70 53 51 4c 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a  SQL_LENGTH</dt>.
28f80 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
28f90 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 61 6e 20  um length of an 
28fa0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 69  SQL statement, i
28fb0 6e 20 62 79 74 65 73 2e 3c 2f 64 64 3e 29 5e 0a  n bytes.</dd>)^.
28fc0 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c  **.** [[SQLITE_L
28fd0 49 4d 49 54 5f 43 4f 4c 55 4d 4e 5d 5d 20 5e 28  IMIT_COLUMN]] ^(
28fe0 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54  <dt>SQLITE_LIMIT
28ff0 5f 43 4f 4c 55 4d 4e 3c 2f 64 74 3e 0a 2a 2a 20  _COLUMN</dt>.** 
29000 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
29010 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e  number of column
29020 73 20 69 6e 20 61 20 74 61 62 6c 65 20 64 65 66  s in a table def
29030 69 6e 69 74 69 6f 6e 20 6f 72 20 69 6e 20 74 68  inition or in th
29040 65 0a 2a 2a 20 72 65 73 75 6c 74 20 73 65 74 20  e.** result set 
29050 6f 66 20 61 20 5b 53 45 4c 45 43 54 5d 20 6f 72  of a [SELECT] or
29060 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d   the maximum num
29070 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69  ber of columns i
29080 6e 20 61 6e 20 69 6e 64 65 78 0a 2a 2a 20 6f 72  n an index.** or
29090 20 69 6e 20 61 6e 20 4f 52 44 45 52 20 42 59 20   in an ORDER BY 
290a0 6f 72 20 47 52 4f 55 50 20 42 59 20 63 6c 61 75  or GROUP BY clau
290b0 73 65 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a  se.</dd>)^.**.**
290c0 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f   [[SQLITE_LIMIT_
290d0 45 58 50 52 5f 44 45 50 54 48 5d 5d 20 5e 28 3c  EXPR_DEPTH]] ^(<
290e0 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
290f0 45 58 50 52 5f 44 45 50 54 48 3c 2f 64 74 3e 0a  EXPR_DEPTH</dt>.
29100 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
29110 75 6d 20 64 65 70 74 68 20 6f 66 20 74 68 65 20  um depth of the 
29120 70 61 72 73 65 20 74 72 65 65 20 6f 6e 20 61 6e  parse tree on an
29130 79 20 65 78 70 72 65 73 73 69 6f 6e 2e 3c 2f 64  y expression.</d
29140 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  d>)^.**.** [[SQL
29150 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55  ITE_LIMIT_COMPOU
29160 4e 44 5f 53 45 4c 45 43 54 5d 5d 20 5e 28 3c 64  ND_SELECT]] ^(<d
29170 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43  t>SQLITE_LIMIT_C
29180 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 3c 2f  OMPOUND_SELECT</
29190 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
291a0 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66  aximum number of
291b0 20 74 65 72 6d 73 20 69 6e 20 61 20 63 6f 6d 70   terms in a comp
291c0 6f 75 6e 64 20 53 45 4c 45 43 54 20 73 74 61 74  ound SELECT stat
291d0 65 6d 65 6e 74 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a  ement.</dd>)^.**
291e0 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d  .** [[SQLITE_LIM
291f0 49 54 5f 56 44 42 45 5f 4f 50 5d 5d 20 5e 28 3c  IT_VDBE_OP]] ^(<
29200 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
29210 56 44 42 45 5f 4f 50 3c 2f 64 74 3e 0a 2a 2a 20  VDBE_OP</dt>.** 
29220 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
29230 6e 75 6d 62 65 72 20 6f 66 20 69 6e 73 74 72 75  number of instru
29240 63 74 69 6f 6e 73 20 69 6e 20 61 20 76 69 72 74  ctions in a virt
29250 75 61 6c 20 6d 61 63 68 69 6e 65 20 70 72 6f 67  ual machine prog
29260 72 61 6d 0a 2a 2a 20 75 73 65 64 20 74 6f 20 69  ram.** used to i
29270 6d 70 6c 65 6d 65 6e 74 20 61 6e 20 53 51 4c 20  mplement an SQL 
29280 73 74 61 74 65 6d 65 6e 74 2e 20 20 54 68 69 73  statement.  This
29290 20 6c 69 6d 69 74 20 69 73 20 6e 6f 74 20 63 75   limit is not cu
292a0 72 72 65 6e 74 6c 79 0a 2a 2a 20 65 6e 66 6f 72  rrently.** enfor
292b0 63 65 64 2c 20 74 68 6f 75 67 68 20 74 68 61 74  ced, though that
292c0 20 6d 69 67 68 74 20 62 65 20 61 64 64 65 64 20   might be added 
292d0 69 6e 20 73 6f 6d 65 20 66 75 74 75 72 65 20 72  in some future r
292e0 65 6c 65 61 73 65 20 6f 66 0a 2a 2a 20 53 51 4c  elease of.** SQL
292f0 69 74 65 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a  ite.</dd>)^.**.*
29300 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54  * [[SQLITE_LIMIT
29310 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 5d 5d 20  _FUNCTION_ARG]] 
29320 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d  ^(<dt>SQLITE_LIM
29330 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 3c  IT_FUNCTION_ARG<
29340 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
29350 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f  maximum number o
29360 66 20 61 72 67 75 6d 65 6e 74 73 20 6f 6e 20 61  f arguments on a
29370 20 66 75 6e 63 74 69 6f 6e 2e 3c 2f 64 64 3e 29   function.</dd>)
29380 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  ^.**.** [[SQLITE
29390 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48 45 44 5d  _LIMIT_ATTACHED]
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 41 54 54 41 43 48 45 44 3c 2f 64  IMIT_ATTACHED</d
293c0 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61  t>.** <dd>The ma
293d0 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20  ximum number of 
293e0 5b 41 54 54 41 43 48 20 7c 20 61 74 74 61 63 68  [ATTACH | attach
293f0 65 64 20 64 61 74 61 62 61 73 65 73 5d 2e 29 5e  ed databases].)^
29400 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
29410 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f  LITE_LIMIT_LIKE_
29420 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48 5d 5d  PATTERN_LENGTH]]
29430 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45  .** ^(<dt>SQLITE
29440 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54  _LIMIT_LIKE_PATT
29450 45 52 4e 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a  ERN_LENGTH</dt>.
29460 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
29470 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65  um length of the
29480 20 70 61 74 74 65 72 6e 20 61 72 67 75 6d 65 6e   pattern argumen
29490 74 20 74 6f 20 74 68 65 20 5b 4c 49 4b 45 5d 20  t to the [LIKE] 
294a0 6f 72 0a 2a 2a 20 5b 47 4c 4f 42 5d 20 6f 70 65  or.** [GLOB] ope
294b0 72 61 74 6f 72 73 2e 3c 2f 64 64 3e 29 5e 0a 2a  rators.</dd>)^.*
294c0 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49  *.** [[SQLITE_LI
294d0 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d  MIT_VARIABLE_NUM
294e0 42 45 52 5d 5d 0a 2a 2a 20 5e 28 3c 64 74 3e 53  BER]].** ^(<dt>S
294f0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49  QLITE_LIMIT_VARI
29500 41 42 4c 45 5f 4e 55 4d 42 45 52 3c 2f 64 74 3e  ABLE_NUMBER</dt>
29510 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
29520 6d 75 6d 20 69 6e 64 65 78 20 6e 75 6d 62 65 72  mum index number
29530 20 6f 66 20 61 6e 79 20 5b 70 61 72 61 6d 65 74   of any [paramet
29540 65 72 5d 20 69 6e 20 61 6e 20 53 51 4c 20 73 74  er] in an SQL st
29550 61 74 65 6d 65 6e 74 2e 29 5e 0a 2a 2a 0a 2a 2a  atement.)^.**.**
29560 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f   [[SQLITE_LIMIT_
29570 54 52 49 47 47 45 52 5f 44 45 50 54 48 5d 5d 20  TRIGGER_DEPTH]] 
29580 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d  ^(<dt>SQLITE_LIM
29590 49 54 5f 54 52 49 47 47 45 52 5f 44 45 50 54 48  IT_TRIGGER_DEPTH
295a0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
295b0 20 6d 61 78 69 6d 75 6d 20 64 65 70 74 68 20 6f   maximum depth o
295c0 66 20 72 65 63 75 72 73 69 6f 6e 20 66 6f 72 20  f recursion for 
295d0 74 72 69 67 67 65 72 73 2e 3c 2f 64 64 3e 29 5e  triggers.</dd>)^
295e0 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
295f0 4c 49 4d 49 54 5f 57 4f 52 4b 45 52 5f 54 48 52  LIMIT_WORKER_THR
29600 45 41 44 53 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c  EADS]] ^(<dt>SQL
29610 49 54 45 5f 4c 49 4d 49 54 5f 57 4f 52 4b 45 52  ITE_LIMIT_WORKER
29620 5f 54 48 52 45 41 44 53 3c 2f 64 74 3e 0a 2a 2a  _THREADS</dt>.**
29630 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
29640 20 6e 75 6d 62 65 72 20 6f 66 20 61 75 78 69 6c   number of auxil
29650 69 61 72 79 20 77 6f 72 6b 65 72 20 74 68 72 65  iary worker thre
29660 61 64 73 20 74 68 61 74 20 61 20 73 69 6e 67 6c  ads that a singl
29670 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73  e.** [prepared s
29680 74 61 74 65 6d 65 6e 74 5d 20 6d 61 79 20 73 74  tatement] may st
29690 61 72 74 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 20 3c  art.</dd>)^.** <
296a0 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  /dl>.*/.#define 
296b0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e  SQLITE_LIMIT_LEN
296c0 47 54 48 20 20 20 20 20 20 20 20 20 20 20 20 20  GTH             
296d0 20 20 20 20 20 20 20 30 0a 23 64 65 66 69 6e 65         0.#define
296e0 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51   SQLITE_LIMIT_SQ
296f0 4c 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20 20  L_LENGTH        
29700 20 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e          1.#defin
29710 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43  e SQLITE_LIMIT_C
29720 4f 4c 55 4d 4e 20 20 20 20 20 20 20 20 20 20 20  OLUMN           
29730 20 20 20 20 20 20 20 20 20 32 0a 23 64 65 66 69           2.#defi
29740 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
29750 45 58 50 52 5f 44 45 50 54 48 20 20 20 20 20 20  EXPR_DEPTH      
29760 20 20 20 20 20 20 20 20 20 20 33 0a 23 64 65 66            3.#def
29770 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
29780 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54  _COMPOUND_SELECT
29790 20 20 20 20 20 20 20 20 20 20 20 34 0a 23 64 65             4.#de
297a0 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
297b0 54 5f 56 44 42 45 5f 4f 50 20 20 20 20 20 20 20  T_VDBE_OP       
297c0 20 20 20 20 20 20 20 20 20 20 20 20 35 0a 23 64              5.#d
297d0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
297e0 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 20  IT_FUNCTION_ARG 
297f0 20 20 20 20 20 20 20 20 20 20 20 20 20 36 0a 23               6.#
29800 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
29810 4d 49 54 5f 41 54 54 41 43 48 45 44 20 20 20 20  MIT_ATTACHED    
29820 20 20 20 20 20 20 20 20 20 20 20 20 20 20 37 0a                7.
29830 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
29840 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52  IMIT_LIKE_PATTER
29850 4e 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20 38  N_LENGTH       8
29860 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
29870 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e  LIMIT_VARIABLE_N
29880 55 4d 42 45 52 20 20 20 20 20 20 20 20 20 20 20  UMBER           
29890 39 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  9.#define SQLITE
298a0 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45 52 5f 44  _LIMIT_TRIGGER_D
298b0 45 50 54 48 20 20 20 20 20 20 20 20 20 20 20 20  EPTH            
298c0 31 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  10.#define SQLIT
298d0 45 5f 4c 49 4d 49 54 5f 57 4f 52 4b 45 52 5f 54  E_LIMIT_WORKER_T
298e0 48 52 45 41 44 53 20 20 20 20 20 20 20 20 20 20  HREADS          
298f0 20 31 31 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33   11../*.** CAPI3
29900 52 45 46 3a 20 43 6f 6d 70 69 6c 69 6e 67 20 41  REF: Compiling A
29910 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 0a  n SQL Statement.
29920 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 53 51  ** KEYWORDS: {SQ
29930 4c 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d 70  L statement comp
29940 69 6c 65 72 7d 0a 2a 2a 20 4d 45 54 48 4f 44 3a  iler}.** METHOD:
29950 20 73 71 6c 69 74 65 33 0a 2a 2a 20 43 4f 4e 53   sqlite3.** CONS
29960 54 52 55 43 54 4f 52 3a 20 73 71 6c 69 74 65 33  TRUCTOR: sqlite3
29970 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 54 6f 20 65  _stmt.**.** To e
29980 78 65 63 75 74 65 20 61 6e 20 53 51 4c 20 71 75  xecute an SQL qu
29990 65 72 79 2c 20 69 74 20 6d 75 73 74 20 66 69 72  ery, it must fir
299a0 73 74 20 62 65 20 63 6f 6d 70 69 6c 65 64 20 69  st be compiled i
299b0 6e 74 6f 20 61 20 62 79 74 65 2d 63 6f 64 65 0a  nto a byte-code.
299c0 2a 2a 20 70 72 6f 67 72 61 6d 20 75 73 69 6e 67  ** program using
299d0 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 72 6f   one of these ro
299e0 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  utines..**.** Th
299f0 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
29a00 2c 20 22 64 62 22 2c 20 69 73 20 61 20 5b 64 61  , "db", is a [da
29a10 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
29a20 6e 5d 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  n] obtained from
29a30 20 61 0a 2a 2a 20 70 72 69 6f 72 20 73 75 63 63   a.** prior succ
29a40 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b  essful call to [
29a50 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c  sqlite3_open()],
29a60 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76   [sqlite3_open_v
29a70 32 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69  2()] or.** [sqli
29a80 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2e 20 20  te3_open16()].  
29a90 54 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  The database con
29aa0 6e 65 63 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74  nection must not
29ab0 20 68 61 76 65 20 62 65 65 6e 20 63 6c 6f 73 65   have been close
29ac0 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63  d..**.** The sec
29ad0 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2c 20 22 7a  ond argument, "z
29ae0 53 71 6c 22 2c 20 69 73 20 74 68 65 20 73 74 61  Sql", is the sta
29af0 74 65 6d 65 6e 74 20 74 6f 20 62 65 20 63 6f 6d  tement to be com
29b00 70 69 6c 65 64 2c 20 65 6e 63 6f 64 65 64 0a 2a  piled, encoded.*
29b10 2a 20 61 73 20 65 69 74 68 65 72 20 55 54 46 2d  * as either UTF-
29b20 38 20 6f 72 20 55 54 46 2d 31 36 2e 20 20 54 68  8 or UTF-16.  Th
29b30 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  e sqlite3_prepar
29b40 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  e() and sqlite3_
29b50 70 72 65 70 61 72 65 5f 76 32 28 29 0a 2a 2a 20  prepare_v2().** 
29b60 69 6e 74 65 72 66 61 63 65 73 20 75 73 65 20 55  interfaces use U
29b70 54 46 2d 38 2c 20 61 6e 64 20 73 71 6c 69 74 65  TF-8, and sqlite
29b80 33 5f 70 72 65 70 61 72 65 31 36 28 29 20 61 6e  3_prepare16() an
29b90 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  d sqlite3_prepar
29ba0 65 31 36 5f 76 32 28 29 0a 2a 2a 20 75 73 65 20  e16_v2().** use 
29bb0 55 54 46 2d 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e 49  UTF-16..**.** ^I
29bc0 66 20 74 68 65 20 6e 42 79 74 65 20 61 72 67 75  f the nByte argu
29bd0 6d 65 6e 74 20 69 73 20 6e 65 67 61 74 69 76 65  ment is negative
29be0 2c 20 74 68 65 6e 20 7a 53 71 6c 20 69 73 20 72  , then zSql is r
29bf0 65 61 64 20 75 70 20 74 6f 20 74 68 65 0a 2a 2a  ead up to the.**
29c00 20 66 69 72 73 74 20 7a 65 72 6f 20 74 65 72 6d   first zero term
29c10 69 6e 61 74 6f 72 2e 20 5e 49 66 20 6e 42 79 74  inator. ^If nByt
29c20 65 20 69 73 20 70 6f 73 69 74 69 76 65 2c 20 74  e is positive, t
29c30 68 65 6e 20 69 74 20 69 73 20 74 68 65 0a 2a 2a  hen it is the.**
29c40 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
29c50 20 72 65 61 64 20 66 72 6f 6d 20 7a 53 71 6c 2e   read from zSql.
29c60 20 20 5e 49 66 20 6e 42 79 74 65 20 69 73 20 7a    ^If nByte is z
29c70 65 72 6f 2c 20 74 68 65 6e 20 6e 6f 20 70 72 65  ero, then no pre
29c80 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65  pared.** stateme
29c90 6e 74 20 69 73 20 67 65 6e 65 72 61 74 65 64 2e  nt is generated.
29ca0 0a 2a 2a 20 49 66 20 74 68 65 20 63 61 6c 6c 65  .** If the calle
29cb0 72 20 6b 6e 6f 77 73 20 74 68 61 74 20 74 68 65  r knows that the
29cc0 20 73 75 70 70 6c 69 65 64 20 73 74 72 69 6e 67   supplied string
29cd0 20 69 73 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74   is nul-terminat
29ce0 65 64 2c 20 74 68 65 6e 0a 2a 2a 20 74 68 65 72  ed, then.** ther
29cf0 65 20 69 73 20 61 20 73 6d 61 6c 6c 20 70 65 72  e is a small per
29d00 66 6f 72 6d 61 6e 63 65 20 61 64 76 61 6e 74 61  formance advanta
29d10 67 65 20 74 6f 20 70 61 73 73 69 6e 67 20 61 6e  ge to passing an
29d20 20 6e 42 79 74 65 20 70 61 72 61 6d 65 74 65 72   nByte parameter
29d30 20 74 68 61 74 0a 2a 2a 20 69 73 20 74 68 65 20   that.** is the 
29d40 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
29d50 69 6e 20 74 68 65 20 69 6e 70 75 74 20 73 74 72  in the input str
29d60 69 6e 67 20 3c 69 3e 69 6e 63 6c 75 64 69 6e 67  ing <i>including
29d70 3c 2f 69 3e 0a 2a 2a 20 74 68 65 20 6e 75 6c 2d  </i>.** the nul-
29d80 74 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 0a 2a  terminator..**.*
29d90 2a 20 5e 49 66 20 70 7a 54 61 69 6c 20 69 73 20  * ^If pzTail is 
29da0 6e 6f 74 20 4e 55 4c 4c 20 74 68 65 6e 20 2a 70  not NULL then *p
29db0 7a 54 61 69 6c 20 69 73 20 6d 61 64 65 20 74 6f  zTail is made to
29dc0 20 70 6f 69 6e 74 20 74 6f 20 74 68 65 20 66 69   point to the fi
29dd0 72 73 74 20 62 79 74 65 0a 2a 2a 20 70 61 73 74  rst byte.** past
29de0 20 74 68 65 20 65 6e 64 20 6f 66 20 74 68 65 20   the end of the 
29df0 66 69 72 73 74 20 53 51 4c 20 73 74 61 74 65 6d  first SQL statem
29e00 65 6e 74 20 69 6e 20 7a 53 71 6c 2e 20 20 54 68  ent in zSql.  Th
29e10 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 6e 6c  ese routines onl
29e20 79 0a 2a 2a 20 63 6f 6d 70 69 6c 65 20 74 68 65  y.** compile the
29e30 20 66 69 72 73 74 20 73 74 61 74 65 6d 65 6e 74   first statement
29e40 20 69 6e 20 7a 53 71 6c 2c 20 73 6f 20 2a 70 7a   in zSql, so *pz
29e50 54 61 69 6c 20 69 73 20 6c 65 66 74 20 70 6f 69  Tail is left poi
29e60 6e 74 69 6e 67 20 74 6f 0a 2a 2a 20 77 68 61 74  nting to.** what
29e70 20 72 65 6d 61 69 6e 73 20 75 6e 63 6f 6d 70 69   remains uncompi
29e80 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 2a 70 70 53  led..**.** ^*ppS
29e90 74 6d 74 20 69 73 20 6c 65 66 74 20 70 6f 69 6e  tmt is left poin
29ea0 74 69 6e 67 20 74 6f 20 61 20 63 6f 6d 70 69 6c  ting to a compil
29eb0 65 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  ed [prepared sta
29ec0 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 63 61 6e  tement] that can
29ed0 20 62 65 0a 2a 2a 20 65 78 65 63 75 74 65 64 20   be.** executed 
29ee0 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73  using [sqlite3_s
29ef0 74 65 70 28 29 5d 2e 20 20 5e 49 66 20 74 68 65  tep()].  ^If the
29f00 72 65 20 69 73 20 61 6e 20 65 72 72 6f 72 2c 20  re is an error, 
29f10 2a 70 70 53 74 6d 74 20 69 73 20 73 65 74 0a 2a  *ppStmt is set.*
29f20 2a 20 74 6f 20 4e 55 4c 4c 2e 20 20 5e 49 66 20  * to NULL.  ^If 
29f30 74 68 65 20 69 6e 70 75 74 20 74 65 78 74 20 63  the input text c
29f40 6f 6e 74 61 69 6e 73 20 6e 6f 20 53 51 4c 20 28  ontains no SQL (
29f50 69 66 20 74 68 65 20 69 6e 70 75 74 20 69 73 20  if the input is 
29f60 61 6e 20 65 6d 70 74 79 0a 2a 2a 20 73 74 72 69  an empty.** stri
29f70 6e 67 20 6f 72 20 61 20 63 6f 6d 6d 65 6e 74 29  ng or a comment)
29f80 20 74 68 65 6e 20 2a 70 70 53 74 6d 74 20 69 73   then *ppStmt is
29f90 20 73 65 74 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a   set to NULL..**
29fa0 20 54 68 65 20 63 61 6c 6c 69 6e 67 20 70 72 6f   The calling pro
29fb0 63 65 64 75 72 65 20 69 73 20 72 65 73 70 6f 6e  cedure is respon
29fc0 73 69 62 6c 65 20 66 6f 72 20 64 65 6c 65 74 69  sible for deleti
29fd0 6e 67 20 74 68 65 20 63 6f 6d 70 69 6c 65 64 0a  ng the compiled.
29fe0 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ** SQL statement
29ff0 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
2a000 66 69 6e 61 6c 69 7a 65 28 29 5d 20 61 66 74 65  finalize()] afte
2a010 72 20 69 74 20 68 61 73 20 66 69 6e 69 73 68 65  r it has finishe
2a020 64 20 77 69 74 68 20 69 74 2e 0a 2a 2a 20 70 70  d with it..** pp
2a030 53 74 6d 74 20 6d 61 79 20 6e 6f 74 20 62 65 20  Stmt may not be 
2a040 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 20  NULL..**.** ^On 
2a050 73 75 63 63 65 73 73 2c 20 74 68 65 20 73 71 6c  success, the sql
2a060 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 20 66  ite3_prepare() f
2a070 61 6d 69 6c 79 20 6f 66 20 72 6f 75 74 69 6e 65  amily of routine
2a080 73 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  s return [SQLITE
2a090 5f 4f 4b 5d 3b 0a 2a 2a 20 6f 74 68 65 72 77 69  _OK];.** otherwi
2a0a0 73 65 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64  se an [error cod
2a0b0 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a  e] is returned..
2a0c0 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
2a0d0 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 20 61  3_prepare_v2() a
2a0e0 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  nd sqlite3_prepa
2a0f0 72 65 31 36 5f 76 32 28 29 20 69 6e 74 65 72 66  re16_v2() interf
2a100 61 63 65 73 20 61 72 65 0a 2a 2a 20 72 65 63 6f  aces are.** reco
2a110 6d 6d 65 6e 64 65 64 20 66 6f 72 20 61 6c 6c 20  mmended for all 
2a120 6e 65 77 20 70 72 6f 67 72 61 6d 73 2e 20 54 68  new programs. Th
2a130 65 20 74 77 6f 20 6f 6c 64 65 72 20 69 6e 74 65  e two older inte
2a140 72 66 61 63 65 73 20 61 72 65 20 72 65 74 61 69  rfaces are retai
2a150 6e 65 64 0a 2a 2a 20 66 6f 72 20 62 61 63 6b 77  ned.** for backw
2a160 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69  ards compatibili
2a170 74 79 2c 20 62 75 74 20 74 68 65 69 72 20 75 73  ty, but their us
2a180 65 20 69 73 20 64 69 73 63 6f 75 72 61 67 65 64  e is discouraged
2a190 2e 0a 2a 2a 20 5e 49 6e 20 74 68 65 20 22 76 32  ..** ^In the "v2
2a1a0 22 20 69 6e 74 65 72 66 61 63 65 73 2c 20 74 68  " interfaces, th
2a1b0 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  e prepared state
2a1c0 6d 65 6e 74 0a 2a 2a 20 74 68 61 74 20 69 73 20  ment.** that is 
2a1d0 72 65 74 75 72 6e 65 64 20 28 74 68 65 20 5b 73  returned (the [s
2a1e0 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62 6a  qlite3_stmt] obj
2a1f0 65 63 74 29 20 63 6f 6e 74 61 69 6e 73 20 61 20  ect) contains a 
2a200 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 6f  copy of the.** o
2a210 72 69 67 69 6e 61 6c 20 53 51 4c 20 74 65 78 74  riginal SQL text
2a220 2e 20 54 68 69 73 20 63 61 75 73 65 73 20 74 68  . This causes th
2a230 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  e [sqlite3_step(
2a240 29 5d 20 69 6e 74 65 72 66 61 63 65 20 74 6f 0a  )] interface to.
2a250 2a 2a 20 62 65 68 61 76 65 20 64 69 66 66 65 72  ** behave differ
2a260 65 6e 74 6c 79 20 69 6e 20 74 68 72 65 65 20 77  ently in three w
2a270 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a  ays:.**.** <ol>.
2a280 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 49 66 20 74  ** <li>.** ^If t
2a290 68 65 20 64 61 74 61 62 61 73 65 20 73 63 68 65  he database sche
2a2a0 6d 61 20 63 68 61 6e 67 65 73 2c 20 69 6e 73 74  ma changes, inst
2a2b0 65 61 64 20 6f 66 20 72 65 74 75 72 6e 69 6e 67  ead of returning
2a2c0 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d   [SQLITE_SCHEMA]
2a2d0 20 61 73 20 69 74 0a 2a 2a 20 61 6c 77 61 79 73   as it.** always
2a2e0 20 75 73 65 64 20 74 6f 20 64 6f 2c 20 5b 73 71   used to do, [sq
2a2f0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77 69  lite3_step()] wi
2a300 6c 6c 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  ll automatically
2a310 20 72 65 63 6f 6d 70 69 6c 65 20 74 68 65 20 53   recompile the S
2a320 51 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20  QL.** statement 
2a330 61 6e 64 20 74 72 79 20 74 6f 20 72 75 6e 20 69  and try to run i
2a340 74 20 61 67 61 69 6e 2e 20 41 73 20 6d 61 6e 79  t again. As many
2a350 20 61 73 20 5b 53 51 4c 49 54 45 5f 4d 41 58 5f   as [SQLITE_MAX_
2a360 53 43 48 45 4d 41 5f 52 45 54 52 59 5d 0a 2a 2a  SCHEMA_RETRY].**
2a370 20 72 65 74 72 69 65 73 20 77 69 6c 6c 20 6f 63   retries will oc
2a380 63 75 72 20 62 65 66 6f 72 65 20 73 71 6c 69 74  cur before sqlit
2a390 65 33 5f 73 74 65 70 28 29 20 67 69 76 65 73 20  e3_step() gives 
2a3a0 75 70 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61  up and returns a
2a3b0 6e 20 65 72 72 6f 72 2e 0a 2a 2a 20 3c 2f 6c 69  n error..** </li
2a3c0 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20  >.**.** <li>.** 
2a3d0 5e 57 68 65 6e 20 61 6e 20 65 72 72 6f 72 20 6f  ^When an error o
2a3e0 63 63 75 72 73 2c 20 5b 73 71 6c 69 74 65 33 5f  ccurs, [sqlite3_
2a3f0 73 74 65 70 28 29 5d 20 77 69 6c 6c 20 72 65 74  step()] will ret
2a400 75 72 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20 64  urn one of the d
2a410 65 74 61 69 6c 65 64 0a 2a 2a 20 5b 65 72 72 6f  etailed.** [erro
2a420 72 20 63 6f 64 65 73 5d 20 6f 72 20 5b 65 78 74  r codes] or [ext
2a430 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65  ended error code
2a440 73 5d 2e 20 20 5e 54 68 65 20 6c 65 67 61 63 79  s].  ^The legacy
2a450 20 62 65 68 61 76 69 6f 72 20 77 61 73 20 74 68   behavior was th
2a460 61 74 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73  at.** [sqlite3_s
2a470 74 65 70 28 29 5d 20 77 6f 75 6c 64 20 6f 6e 6c  tep()] would onl
2a480 79 20 72 65 74 75 72 6e 20 61 20 67 65 6e 65 72  y return a gener
2a490 69 63 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  ic [SQLITE_ERROR
2a4a0 5d 20 72 65 73 75 6c 74 20 63 6f 64 65 0a 2a 2a  ] result code.**
2a4b0 20 61 6e 64 20 74 68 65 20 61 70 70 6c 69 63 61   and the applica
2a4c0 74 69 6f 6e 20 77 6f 75 6c 64 20 68 61 76 65 20  tion would have 
2a4d0 74 6f 20 6d 61 6b 65 20 61 20 73 65 63 6f 6e 64  to make a second
2a4e0 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
2a4f0 33 5f 72 65 73 65 74 28 29 5d 0a 2a 2a 20 69 6e  3_reset()].** in
2a500 20 6f 72 64 65 72 20 74 6f 20 66 69 6e 64 20 74   order to find t
2a510 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 63 61  he underlying ca
2a520 75 73 65 20 6f 66 20 74 68 65 20 70 72 6f 62 6c  use of the probl
2a530 65 6d 2e 20 57 69 74 68 20 74 68 65 20 22 76 32  em. With the "v2
2a540 22 20 70 72 65 70 61 72 65 0a 2a 2a 20 69 6e 74  " prepare.** int
2a550 65 72 66 61 63 65 73 2c 20 74 68 65 20 75 6e 64  erfaces, the und
2a560 65 72 6c 79 69 6e 67 20 72 65 61 73 6f 6e 20 66  erlying reason f
2a570 6f 72 20 74 68 65 20 65 72 72 6f 72 20 69 73 20  or the error is 
2a580 72 65 74 75 72 6e 65 64 20 69 6d 6d 65 64 69 61  returned immedia
2a590 74 65 6c 79 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a  tely..** </li>.*
2a5a0 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 49 66  *.** <li>.** ^If
2a5b0 20 74 68 65 20 73 70 65 63 69 66 69 63 20 76 61   the specific va
2a5c0 6c 75 65 20 62 6f 75 6e 64 20 74 6f 20 5b 70 61  lue bound to [pa
2a5d0 72 61 6d 65 74 65 72 20 7c 20 68 6f 73 74 20 70  rameter | host p
2a5e0 61 72 61 6d 65 74 65 72 5d 20 69 6e 20 74 68 65  arameter] in the
2a5f0 20 0a 2a 2a 20 57 48 45 52 45 20 63 6c 61 75 73   .** WHERE claus
2a600 65 20 6d 69 67 68 74 20 69 6e 66 6c 75 65 6e 63  e might influenc
2a610 65 20 74 68 65 20 63 68 6f 69 63 65 20 6f 66 20  e the choice of 
2a620 71 75 65 72 79 20 70 6c 61 6e 20 66 6f 72 20 61  query plan for a
2a630 20 73 74 61 74 65 6d 65 6e 74 2c 0a 2a 2a 20 74   statement,.** t
2a640 68 65 6e 20 74 68 65 20 73 74 61 74 65 6d 65 6e  hen the statemen
2a650 74 20 77 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61  t will be automa
2a660 74 69 63 61 6c 6c 79 20 72 65 63 6f 6d 70 69 6c  tically recompil
2a670 65 64 2c 20 61 73 20 69 66 20 74 68 65 72 65 20  ed, as if there 
2a680 68 61 64 20 62 65 65 6e 20 0a 2a 2a 20 61 20 73  had been .** a s
2a690 63 68 65 6d 61 20 63 68 61 6e 67 65 2c 20 6f 6e  chema change, on
2a6a0 20 74 68 65 20 66 69 72 73 74 20 20 5b 73 71 6c   the first  [sql
2a6b0 69 74 65 33 5f 73 74 65 70 28 29 5d 20 63 61 6c  ite3_step()] cal
2a6c0 6c 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79 20  l following any 
2a6d0 63 68 61 6e 67 65 0a 2a 2a 20 74 6f 20 74 68 65  change.** to the
2a6e0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74   [sqlite3_bind_t
2a6f0 65 78 74 20 7c 20 62 69 6e 64 69 6e 67 73 5d 20  ext | bindings] 
2a700 6f 66 20 74 68 61 74 20 5b 70 61 72 61 6d 65 74  of that [paramet
2a710 65 72 5d 2e 20 0a 2a 2a 20 5e 54 68 65 20 73 70  er]. .** ^The sp
2a720 65 63 69 66 69 63 20 76 61 6c 75 65 20 6f 66 20  ecific value of 
2a730 57 48 45 52 45 2d 63 6c 61 75 73 65 20 5b 70 61  WHERE-clause [pa
2a740 72 61 6d 65 74 65 72 5d 20 6d 69 67 68 74 20 69  rameter] might i
2a750 6e 66 6c 75 65 6e 63 65 20 74 68 65 20 0a 2a 2a  nfluence the .**
2a760 20 63 68 6f 69 63 65 20 6f 66 20 71 75 65 72 79   choice of query
2a770 20 70 6c 61 6e 20 69 66 20 74 68 65 20 70 61 72   plan if the par
2a780 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 6c 65  ameter is the le
2a790 66 74 2d 68 61 6e 64 20 73 69 64 65 20 6f 66 20  ft-hand side of 
2a7a0 61 20 5b 4c 49 4b 45 5d 0a 2a 2a 20 6f 72 20 5b  a [LIKE].** or [
2a7b0 47 4c 4f 42 5d 20 6f 70 65 72 61 74 6f 72 20 6f  GLOB] operator o
2a7c0 72 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74  r if the paramet
2a7d0 65 72 20 69 73 20 63 6f 6d 70 61 72 65 64 20 74  er is compared t
2a7e0 6f 20 61 6e 20 69 6e 64 65 78 65 64 20 63 6f 6c  o an indexed col
2a7f0 75 6d 6e 0a 2a 2a 20 61 6e 64 20 74 68 65 20 5b  umn.** and the [
2a800 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 53 54  SQLITE_ENABLE_ST
2a810 41 54 33 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  AT3] compile-tim
2a820 65 20 6f 70 74 69 6f 6e 20 69 73 20 65 6e 61 62  e option is enab
2a830 6c 65 64 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a  led..** </li>.**
2a840 20 3c 2f 6f 6c 3e 0a 2a 2f 0a 69 6e 74 20 73 71   </ol>.*/.int sq
2a850 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 0a 20  lite3_prepare(. 
2a860 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20   sqlite3 *db,   
2a870 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61           /* Data
2a880 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20  base handle */. 
2a890 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71   const char *zSq
2a8a0 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20  l,       /* SQL 
2a8b0 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 38  statement, UTF-8
2a8c0 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e   encoded */.  in
2a8d0 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20  t nByte,        
2a8e0 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d        /* Maximum
2a8f0 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20   length of zSql 
2a900 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73  in bytes. */.  s
2a910 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70  qlite3_stmt **pp
2a920 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53  Stmt,  /* OUT: S
2a930 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20  tatement handle 
2a940 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  */.  const char 
2a950 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20  **pzTail     /* 
2a960 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20  OUT: Pointer to 
2a970 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f  unused portion o
2a980 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74  f zSql */.);.int
2a990 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
2a9a0 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  _v2(.  sqlite3 *
2a9b0 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f  db,            /
2a9c0 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c  * Database handl
2a9d0 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  e */.  const cha
2a9e0 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f  r *zSql,       /
2a9f0 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c  * SQL statement,
2aa00 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a   UTF-8 encoded *
2aa10 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20  /.  int nByte,  
2aa20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d              /* M
2aa30 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66  aximum length of
2aa40 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20   zSql in bytes. 
2aa50 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d  */.  sqlite3_stm
2aa60 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20  t **ppStmt,  /* 
2aa70 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68  OUT: Statement h
2aa80 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  andle */.  const
2aa90 20 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20   char **pzTail  
2aaa0 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74     /* OUT: Point
2aab0 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72  er to unused por
2aac0 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a  tion of zSql */.
2aad0 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70  );.int sqlite3_p
2aae0 72 65 70 61 72 65 31 36 28 0a 20 20 73 71 6c 69  repare16(.  sqli
2aaf0 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20  te3 *db,        
2ab00 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20      /* Database 
2ab10 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73  handle */.  cons
2ab20 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 20  t void *zSql,   
2ab30 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65      /* SQL state
2ab40 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20 65 6e 63  ment, UTF-16 enc
2ab50 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42  oded */.  int nB
2ab60 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 20  yte,            
2ab70 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e    /* Maximum len
2ab80 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62  gth of zSql in b
2ab90 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74  ytes. */.  sqlit
2aba0 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74  e3_stmt **ppStmt
2abb0 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65  ,  /* OUT: State
2abc0 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20  ment handle */. 
2abd0 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a   const void **pz
2abe0 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a  Tail     /* OUT:
2abf0 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73   Pointer to unus
2ac00 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53  ed portion of zS
2ac10 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c  ql */.);.int sql
2ac20 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
2ac30 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  2(.  sqlite3 *db
2ac40 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20  ,            /* 
2ac50 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20  Database handle 
2ac60 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20  */.  const void 
2ac70 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20  *zSql,       /* 
2ac80 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55  SQL statement, U
2ac90 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f  TF-16 encoded */
2aca0 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20  .  int nByte,   
2acb0 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61             /* Ma
2acc0 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20  ximum length of 
2acd0 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a  zSql in bytes. *
2ace0 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  /.  sqlite3_stmt
2acf0 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f   **ppStmt,  /* O
2ad00 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61  UT: Statement ha
2ad10 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  ndle */.  const 
2ad20 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20  void **pzTail   
2ad30 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65    /* OUT: Pointe
2ad40 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74  r to unused port
2ad50 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29  ion of zSql */.)
2ad60 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2ad70 46 3a 20 52 65 74 72 69 65 76 69 6e 67 20 53 74  F: Retrieving St
2ad80 61 74 65 6d 65 6e 74 20 53 51 4c 0a 2a 2a 20 4d  atement SQL.** M
2ad90 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73  ETHOD: sqlite3_s
2ada0 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  tmt.**.** ^The s
2adb0 71 6c 69 74 65 33 5f 73 71 6c 28 50 29 20 69 6e  qlite3_sql(P) in
2adc0 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
2add0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 63  a pointer to a c
2ade0 6f 70 79 20 6f 66 20 74 68 65 20 55 54 46 2d 38  opy of the UTF-8
2adf0 0a 2a 2a 20 53 51 4c 20 74 65 78 74 20 75 73 65  .** SQL text use
2ae00 64 20 74 6f 20 63 72 65 61 74 65 20 5b 70 72 65  d to create [pre
2ae10 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2ae20 20 50 20 69 66 20 50 20 77 61 73 0a 2a 2a 20 63   P if P was.** c
2ae30 72 65 61 74 65 64 20 62 79 20 65 69 74 68 65 72  reated by either
2ae40 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
2ae50 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69  e_v2()] or [sqli
2ae60 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32  te3_prepare16_v2
2ae70 28 29 5d 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ()]..** ^The sql
2ae80 69 74 65 33 5f 65 78 70 61 6e 64 65 64 5f 73 71  ite3_expanded_sq
2ae90 6c 28 50 29 20 69 6e 74 65 72 66 61 63 65 20 72  l(P) interface r
2aea0 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
2aeb0 20 74 6f 20 61 20 55 54 46 2d 38 0a 2a 2a 20 73   to a UTF-8.** s
2aec0 74 72 69 6e 67 20 63 6f 6e 74 61 69 6e 69 6e 67  tring containing
2aed0 20 74 68 65 20 53 51 4c 20 74 65 78 74 20 6f 66   the SQL text of
2aee0 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
2aef0 65 6e 74 20 50 20 77 69 74 68 0a 2a 2a 20 5b 62  ent P with.** [b
2af00 6f 75 6e 64 20 70 61 72 61 6d 65 74 65 72 73 5d  ound parameters]
2af10 20 65 78 70 61 6e 64 65 64 2e 0a 2a 2a 0a 2a 2a   expanded..**.**
2af20 20 5e 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20   ^(For example, 
2af30 69 66 20 61 20 70 72 65 70 61 72 65 64 20 73 74  if a prepared st
2af40 61 74 65 6d 65 6e 74 20 69 73 20 63 72 65 61 74  atement is creat
2af50 65 64 20 75 73 69 6e 67 20 74 68 65 20 53 51 4c  ed using the SQL
2af60 0a 2a 2a 20 74 65 78 74 20 22 53 45 4c 45 43 54  .** text "SELECT
2af70 20 24 61 62 63 2c 3a 78 79 7a 22 20 61 6e 64 20   $abc,:xyz" and 
2af80 69 66 20 70 61 72 61 6d 65 74 65 72 20 24 61 62  if parameter $ab
2af90 63 20 69 73 20 62 6f 75 6e 64 20 74 6f 20 69 6e  c is bound to in
2afa0 74 65 67 65 72 20 32 33 34 35 0a 2a 2a 20 61 6e  teger 2345.** an
2afb0 64 20 70 61 72 61 6d 65 74 65 72 20 3a 78 79 7a  d parameter :xyz
2afc0 20 69 73 20 75 6e 62 6f 75 6e 64 2c 20 74 68 65   is unbound, the
2afd0 6e 20 73 71 6c 69 74 65 33 5f 73 71 6c 28 29 20  n sqlite3_sql() 
2afe0 77 69 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 74  will return.** t
2aff0 68 65 20 6f 72 69 67 69 6e 61 6c 20 73 74 72 69  he original stri
2b000 6e 67 2c 20 22 53 45 4c 45 43 54 20 24 61 62 63  ng, "SELECT $abc
2b010 2c 3a 78 79 7a 22 20 62 75 74 20 73 71 6c 69 74  ,:xyz" but sqlit
2b020 65 33 5f 65 78 70 61 6e 64 65 64 5f 73 71 6c 28  e3_expanded_sql(
2b030 29 0a 2a 2a 20 77 69 6c 6c 20 72 65 74 75 72 6e  ).** will return
2b040 20 22 53 45 4c 45 43 54 20 32 33 34 35 2c 4e 55   "SELECT 2345,NU
2b050 4c 4c 22 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68  LL".)^.**.** ^Th
2b060 65 20 73 71 6c 69 74 65 33 5f 65 78 70 61 6e 64  e sqlite3_expand
2b070 65 64 5f 73 71 6c 28 29 20 69 6e 74 65 72 66 61  ed_sql() interfa
2b080 63 65 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 20  ce returns NULL 
2b090 69 66 20 69 6e 73 75 66 66 69 63 69 65 6e 74 20  if insufficient 
2b0a0 6d 65 6d 6f 72 79 0a 2a 2a 20 69 73 20 61 76 61  memory.** is ava
2b0b0 69 6c 61 62 6c 65 20 74 6f 20 68 6f 6c 64 20 74  ilable to hold t
2b0c0 68 65 20 72 65 73 75 6c 74 2c 20 6f 72 20 69 66  he result, or if
2b0d0 20 74 68 65 20 72 65 73 75 6c 74 20 77 6f 75 6c   the result woul
2b0e0 64 20 65 78 63 65 65 64 20 74 68 65 0a 2a 2a 20  d exceed the.** 
2b0f0 74 68 65 20 6d 61 78 69 6d 75 6d 20 73 74 72 69  the maximum stri
2b100 6e 67 20 6c 65 6e 67 74 68 20 64 65 74 65 72 6d  ng length determ
2b110 69 6e 65 64 20 62 79 20 74 68 65 20 5b 53 51 4c  ined by the [SQL
2b120 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48  ITE_LIMIT_LENGTH
2b130 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 53  ]..**.** ^The [S
2b140 51 4c 49 54 45 5f 54 52 41 43 45 5f 53 49 5a 45  QLITE_TRACE_SIZE
2b150 5f 4c 49 4d 49 54 5d 20 63 6f 6d 70 69 6c 65 2d  _LIMIT] compile-
2b160 74 69 6d 65 20 6f 70 74 69 6f 6e 20 6c 69 6d 69  time option limi
2b170 74 73 20 74 68 65 20 73 69 7a 65 20 6f 66 0a 2a  ts the size of.*
2b180 2a 20 62 6f 75 6e 64 20 70 61 72 61 6d 65 74 65  * bound paramete
2b190 72 20 65 78 70 61 6e 73 69 6f 6e 73 2e 20 20 5e  r expansions.  ^
2b1a0 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54  The [SQLITE_OMIT
2b1b0 5f 54 52 41 43 45 5d 20 63 6f 6d 70 69 6c 65 2d  _TRACE] compile-
2b1c0 74 69 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e 20 63  time.** option c
2b1d0 61 75 73 65 73 20 73 71 6c 69 74 65 33 5f 65 78  auses sqlite3_ex
2b1e0 70 61 6e 64 65 64 5f 73 71 6c 28 29 20 74 6f 20  panded_sql() to 
2b1f0 61 6c 77 61 79 73 20 72 65 74 75 72 6e 20 4e 55  always return NU
2b200 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  LL..**.** ^The s
2b210 74 72 69 6e 67 20 72 65 74 75 72 6e 65 64 20 62  tring returned b
2b220 79 20 73 71 6c 69 74 65 33 5f 73 71 6c 28 50 29  y sqlite3_sql(P)
2b230 20 69 73 20 6d 61 6e 61 67 65 64 20 62 79 20 53   is managed by S
2b240 51 4c 69 74 65 20 61 6e 64 20 69 73 0a 2a 2a 20  QLite and is.** 
2b250 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 66 72  automatically fr
2b260 65 65 64 20 77 68 65 6e 20 74 68 65 20 70 72 65  eed when the pre
2b270 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20  pared statement 
2b280 69 73 20 66 69 6e 61 6c 69 7a 65 64 2e 0a 2a 2a  is finalized..**
2b290 20 5e 54 68 65 20 73 74 72 69 6e 67 20 72 65 74   ^The string ret
2b2a0 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33  urned by sqlite3
2b2b0 5f 65 78 70 61 6e 64 65 64 5f 73 71 6c 28 50 29  _expanded_sql(P)
2b2c0 2c 20 6f 6e 20 74 68 65 20 6f 74 68 65 72 20 68  , on the other h
2b2d0 61 6e 64 2c 0a 2a 2a 20 69 73 20 6f 62 74 61 69  and,.** is obtai
2b2e0 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  ned from [sqlite
2b2f0 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 61 6e 64 20  3_malloc()] and 
2b300 6d 75 73 74 20 62 65 20 66 72 65 65 20 62 79 20  must be free by 
2b310 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a  the application.
2b320 2a 2a 20 62 79 20 70 61 73 73 69 6e 67 20 69 74  ** by passing it
2b330 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72 65   to [sqlite3_fre
2b340 65 28 29 5d 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63  e()]..*/.const c
2b350 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 73 71 6c  har *sqlite3_sql
2b360 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70  (sqlite3_stmt *p
2b370 53 74 6d 74 29 3b 0a 63 68 61 72 20 2a 73 71 6c  Stmt);.char *sql
2b380 69 74 65 33 5f 65 78 70 61 6e 64 65 64 5f 73 71  ite3_expanded_sq
2b390 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a  l(sqlite3_stmt *
2b3a0 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  pStmt);../*.** C
2b3b0 41 50 49 33 52 45 46 3a 20 44 65 74 65 72 6d 69  API3REF: Determi
2b3c0 6e 65 20 49 66 20 41 6e 20 53 51 4c 20 53 74 61  ne If An SQL Sta
2b3d0 74 65 6d 65 6e 74 20 57 72 69 74 65 73 20 54 68  tement Writes Th
2b3e0 65 20 44 61 74 61 62 61 73 65 0a 2a 2a 20 4d 45  e Database.** ME
2b3f0 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74  THOD: sqlite3_st
2b400 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  mt.**.** ^The sq
2b410 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f  lite3_stmt_reado
2b420 6e 6c 79 28 58 29 20 69 6e 74 65 72 66 61 63 65  nly(X) interface
2b430 20 72 65 74 75 72 6e 73 20 74 72 75 65 20 28 6e   returns true (n
2b440 6f 6e 2d 7a 65 72 6f 29 20 69 66 0a 2a 2a 20 61  on-zero) if.** a
2b450 6e 64 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 5b  nd only if the [
2b460 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2b470 6e 74 5d 20 58 20 6d 61 6b 65 73 20 6e 6f 20 64  nt] X makes no d
2b480 69 72 65 63 74 20 63 68 61 6e 67 65 73 20 74 6f  irect changes to
2b490 0a 2a 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74 20  .** the content 
2b4a0 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  of the database 
2b4b0 66 69 6c 65 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65  file..**.** Note
2b4c0 20 74 68 61 74 20 5b 61 70 70 6c 69 63 61 74 69   that [applicati
2b4d0 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66  on-defined SQL f
2b4e0 75 6e 63 74 69 6f 6e 73 5d 20 6f 72 0a 2a 2a 20  unctions] or.** 
2b4f0 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 73 5d  [virtual tables]
2b500 20 6d 69 67 68 74 20 63 68 61 6e 67 65 20 74 68   might change th
2b510 65 20 64 61 74 61 62 61 73 65 20 69 6e 64 69 72  e database indir
2b520 65 63 74 6c 79 20 61 73 20 61 20 73 69 64 65 20  ectly as a side 
2b530 65 66 66 65 63 74 2e 20 20 0a 2a 2a 20 5e 28 46  effect.  .** ^(F
2b540 6f 72 20 65 78 61 6d 70 6c 65 2c 20 69 66 20 61  or example, if a
2b550 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 65  n application de
2b560 66 69 6e 65 73 20 61 20 66 75 6e 63 74 69 6f 6e  fines a function
2b570 20 22 65 76 61 6c 28 29 22 20 74 68 61 74 20 0a   "eval()" that .
2b580 2a 2a 20 63 61 6c 6c 73 20 5b 73 71 6c 69 74 65  ** calls [sqlite
2b590 33 5f 65 78 65 63 28 29 5d 2c 20 74 68 65 6e 20  3_exec()], then 
2b5a0 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 53 51  the following SQ
2b5b0 4c 20 73 74 61 74 65 6d 65 6e 74 20 77 6f 75 6c  L statement woul
2b5c0 64 0a 2a 2a 20 63 68 61 6e 67 65 20 74 68 65 20  d.** change the 
2b5d0 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 74 68  database file th
2b5e0 72 6f 75 67 68 20 73 69 64 65 2d 65 66 66 65 63  rough side-effec
2b5f0 74 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  ts:.**.** <block
2b600 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20  quote><pre>.**  
2b610 20 20 53 45 4c 45 43 54 20 65 76 61 6c 28 27 44    SELECT eval('D
2b620 45 4c 45 54 45 20 46 52 4f 4d 20 74 31 27 29 20  ELETE FROM t1') 
2b630 46 52 4f 4d 20 74 32 3b 0a 2a 2a 20 3c 2f 70 72  FROM t2;.** </pr
2b640 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a  e></blockquote>.
2b650 2a 2a 0a 2a 2a 20 42 75 74 20 62 65 63 61 75 73  **.** But becaus
2b660 65 20 74 68 65 20 5b 53 45 4c 45 43 54 5d 20 73  e the [SELECT] s
2b670 74 61 74 65 6d 65 6e 74 20 64 6f 65 73 20 6e 6f  tatement does no
2b680 74 20 63 68 61 6e 67 65 20 74 68 65 20 64 61 74  t change the dat
2b690 61 62 61 73 65 20 66 69 6c 65 0a 2a 2a 20 64 69  abase file.** di
2b6a0 72 65 63 74 6c 79 2c 20 73 71 6c 69 74 65 33 5f  rectly, sqlite3_
2b6b0 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20  stmt_readonly() 
2b6c0 77 6f 75 6c 64 20 73 74 69 6c 6c 20 72 65 74 75  would still retu
2b6d0 72 6e 20 74 72 75 65 2e 29 5e 0a 2a 2a 0a 2a 2a  rn true.)^.**.**
2b6e0 20 5e 54 72 61 6e 73 61 63 74 69 6f 6e 20 63 6f   ^Transaction co
2b6f0 6e 74 72 6f 6c 20 73 74 61 74 65 6d 65 6e 74 73  ntrol statements
2b700 20 73 75 63 68 20 61 73 20 5b 42 45 47 49 4e 5d   such as [BEGIN]
2b710 2c 20 5b 43 4f 4d 4d 49 54 5d 2c 20 5b 52 4f 4c  , [COMMIT], [ROL
2b720 4c 42 41 43 4b 5d 2c 0a 2a 2a 20 5b 53 41 56 45  LBACK],.** [SAVE
2b730 50 4f 49 4e 54 5d 2c 20 61 6e 64 20 5b 52 45 4c  POINT], and [REL
2b740 45 41 53 45 5d 20 63 61 75 73 65 20 73 71 6c 69  EASE] cause sqli
2b750 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c  te3_stmt_readonl
2b760 79 28 29 20 74 6f 20 72 65 74 75 72 6e 20 74 72  y() to return tr
2b770 75 65 2c 0a 2a 2a 20 73 69 6e 63 65 20 74 68 65  ue,.** since the
2b780 20 73 74 61 74 65 6d 65 6e 74 73 20 74 68 65 6d   statements them
2b790 73 65 6c 76 65 73 20 64 6f 20 6e 6f 74 20 61 63  selves do not ac
2b7a0 74 75 61 6c 6c 79 20 6d 6f 64 69 66 79 20 74 68  tually modify th
2b7b0 65 20 64 61 74 61 62 61 73 65 20 62 75 74 0a 2a  e database but.*
2b7c0 2a 20 72 61 74 68 65 72 20 74 68 65 79 20 63 6f  * rather they co
2b7d0 6e 74 72 6f 6c 20 74 68 65 20 74 69 6d 69 6e 67  ntrol the timing
2b7e0 20 6f 66 20 77 68 65 6e 20 6f 74 68 65 72 20 73   of when other s
2b7f0 74 61 74 65 6d 65 6e 74 73 20 6d 6f 64 69 66 79  tatements modify
2b800 20 74 68 65 20 0a 2a 2a 20 64 61 74 61 62 61 73   the .** databas
2b810 65 2e 20 20 5e 54 68 65 20 5b 41 54 54 41 43 48  e.  ^The [ATTACH
2b820 5d 20 61 6e 64 20 5b 44 45 54 41 43 48 5d 20 73  ] and [DETACH] s
2b830 74 61 74 65 6d 65 6e 74 73 20 61 6c 73 6f 20 63  tatements also c
2b840 61 75 73 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  ause.** sqlite3_
2b850 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20  stmt_readonly() 
2b860 74 6f 20 72 65 74 75 72 6e 20 74 72 75 65 20 73  to return true s
2b870 69 6e 63 65 2c 20 77 68 69 6c 65 20 74 68 6f 73  ince, while thos
2b880 65 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20  e statements.** 
2b890 63 68 61 6e 67 65 20 74 68 65 20 63 6f 6e 66 69  change the confi
2b8a0 67 75 72 61 74 69 6f 6e 20 6f 66 20 61 20 64 61  guration of a da
2b8b0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
2b8c0 6e 2c 20 74 68 65 79 20 64 6f 20 6e 6f 74 20 6d  n, they do not m
2b8d0 61 6b 65 20 0a 2a 2a 20 63 68 61 6e 67 65 73 20  ake .** changes 
2b8e0 74 6f 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f  to the content o
2b8f0 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  f the database f
2b900 69 6c 65 73 20 6f 6e 20 64 69 73 6b 2e 0a 2a 2f  iles on disk..*/
2b910 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 74 6d  .int sqlite3_stm
2b920 74 5f 72 65 61 64 6f 6e 6c 79 28 73 71 6c 69 74  t_readonly(sqlit
2b930 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b  e3_stmt *pStmt);
2b940 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2b950 3a 20 44 65 74 65 72 6d 69 6e 65 20 49 66 20 41  : Determine If A
2b960 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d   Prepared Statem
2b970 65 6e 74 20 48 61 73 20 42 65 65 6e 20 52 65 73  ent Has Been Res
2b980 65 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  et.** METHOD: sq
2b990 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a  lite3_stmt.**.**
2b9a0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 74   ^The sqlite3_st
2b9b0 6d 74 5f 62 75 73 79 28 53 29 20 69 6e 74 65 72  mt_busy(S) inter
2b9c0 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 72 75  face returns tru
2b9d0 65 20 28 6e 6f 6e 2d 7a 65 72 6f 29 20 69 66 20  e (non-zero) if 
2b9e0 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64  the.** [prepared
2b9f0 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 68 61   statement] S ha
2ba00 73 20 62 65 65 6e 20 73 74 65 70 70 65 64 20 61  s been stepped a
2ba10 74 20 6c 65 61 73 74 20 6f 6e 63 65 20 75 73 69  t least once usi
2ba20 6e 67 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ng .** [sqlite3_
2ba30 73 74 65 70 28 53 29 5d 20 62 75 74 20 68 61 73  step(S)] but has
2ba40 20 6e 65 69 74 68 65 72 20 72 75 6e 20 74 6f 20   neither run to 
2ba50 63 6f 6d 70 6c 65 74 69 6f 6e 20 28 72 65 74 75  completion (retu
2ba60 72 6e 65 64 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  rned.** [SQLITE_
2ba70 44 4f 4e 45 5d 20 66 72 6f 6d 20 5b 73 71 6c 69  DONE] from [sqli
2ba80 74 65 33 5f 73 74 65 70 28 53 29 5d 29 20 6e 6f  te3_step(S)]) no
2ba90 72 0a 2a 2a 20 62 65 65 6e 20 72 65 73 65 74 20  r.** been reset 
2baa0 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72  using [sqlite3_r
2bab0 65 73 65 74 28 53 29 5d 2e 20 20 5e 54 68 65 20  eset(S)].  ^The 
2bac0 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 62 75 73  sqlite3_stmt_bus
2bad0 79 28 53 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63  y(S).** interfac
2bae0 65 20 72 65 74 75 72 6e 73 20 66 61 6c 73 65 20  e returns false 
2baf0 69 66 20 53 20 69 73 20 61 20 4e 55 4c 4c 20 70  if S is a NULL p
2bb00 6f 69 6e 74 65 72 2e 20 20 49 66 20 53 20 69 73  ointer.  If S is
2bb10 20 6e 6f 74 20 61 20 0a 2a 2a 20 4e 55 4c 4c 20   not a .** NULL 
2bb20 70 6f 69 6e 74 65 72 20 61 6e 64 20 69 73 20 6e  pointer and is n
2bb30 6f 74 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ot a pointer to 
2bb40 61 20 76 61 6c 69 64 20 5b 70 72 65 70 61 72 65  a valid [prepare
2bb50 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20  d statement].** 
2bb60 6f 62 6a 65 63 74 2c 20 74 68 65 6e 20 74 68 65  object, then the
2bb70 20 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64   behavior is und
2bb80 65 66 69 6e 65 64 20 61 6e 64 20 70 72 6f 62 61  efined and proba
2bb90 62 6c 79 20 75 6e 64 65 73 69 72 61 62 6c 65 2e  bly undesirable.
2bba0 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65  .**.** This inte
2bbb0 72 66 61 63 65 20 63 61 6e 20 62 65 20 75 73 65  rface can be use
2bbc0 64 20 69 6e 20 63 6f 6d 62 69 6e 61 74 69 6f 6e  d in combination
2bbd0 20 5b 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73   [sqlite3_next_s
2bbe0 74 6d 74 28 29 5d 0a 2a 2a 20 74 6f 20 6c 6f 63  tmt()].** to loc
2bbf0 61 74 65 20 61 6c 6c 20 70 72 65 70 61 72 65 64  ate all prepared
2bc00 20 73 74 61 74 65 6d 65 6e 74 73 20 61 73 73 6f   statements asso
2bc10 63 69 61 74 65 64 20 77 69 74 68 20 61 20 64 61  ciated with a da
2bc20 74 61 62 61 73 65 20 0a 2a 2a 20 63 6f 6e 6e 65  tabase .** conne
2bc30 63 74 69 6f 6e 20 74 68 61 74 20 61 72 65 20 69  ction that are i
2bc40 6e 20 6e 65 65 64 20 6f 66 20 62 65 69 6e 67 20  n need of being 
2bc50 72 65 73 65 74 2e 20 20 54 68 69 73 20 63 61 6e  reset.  This can
2bc60 20 62 65 20 75 73 65 64 2c 0a 2a 2a 20 66 6f 72   be used,.** for
2bc70 20 65 78 61 6d 70 6c 65 2c 20 69 6e 20 64 69 61   example, in dia
2bc80 67 6e 6f 73 74 69 63 20 72 6f 75 74 69 6e 65 73  gnostic routines
2bc90 20 74 6f 20 73 65 61 72 63 68 20 66 6f 72 20 70   to search for p
2bca0 72 65 70 61 72 65 64 20 0a 2a 2a 20 73 74 61 74  repared .** stat
2bcb0 65 6d 65 6e 74 73 20 74 68 61 74 20 61 72 65 20  ements that are 
2bcc0 68 6f 6c 64 69 6e 67 20 61 20 74 72 61 6e 73 61  holding a transa
2bcd0 63 74 69 6f 6e 20 6f 70 65 6e 2e 0a 2a 2f 0a 69  ction open..*/.i
2bce0 6e 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f  nt sqlite3_stmt_
2bcf0 62 75 73 79 28 73 71 6c 69 74 65 33 5f 73 74 6d  busy(sqlite3_stm
2bd00 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  t*);../*.** CAPI
2bd10 33 52 45 46 3a 20 44 79 6e 61 6d 69 63 61 6c 6c  3REF: Dynamicall
2bd20 79 20 54 79 70 65 64 20 56 61 6c 75 65 20 4f 62  y Typed Value Ob
2bd30 6a 65 63 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  ject.** KEYWORDS
2bd40 3a 20 7b 70 72 6f 74 65 63 74 65 64 20 73 71 6c  : {protected sql
2bd50 69 74 65 33 5f 76 61 6c 75 65 7d 20 7b 75 6e 70  ite3_value} {unp
2bd60 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
2bd70 5f 76 61 6c 75 65 7d 0a 2a 2a 0a 2a 2a 20 53 51  _value}.**.** SQ
2bd80 4c 69 74 65 20 75 73 65 73 20 74 68 65 20 73 71  Lite uses the sq
2bd90 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
2bda0 63 74 20 74 6f 20 72 65 70 72 65 73 65 6e 74 20  ct to represent 
2bdb0 61 6c 6c 20 76 61 6c 75 65 73 0a 2a 2a 20 74 68  all values.** th
2bdc0 61 74 20 63 61 6e 20 62 65 20 73 74 6f 72 65 64  at can be stored
2bdd0 20 69 6e 20 61 20 64 61 74 61 62 61 73 65 20 74   in a database t
2bde0 61 62 6c 65 2e 20 53 51 4c 69 74 65 20 75 73 65  able. SQLite use
2bdf0 73 20 64 79 6e 61 6d 69 63 20 74 79 70 69 6e 67  s dynamic typing
2be00 0a 2a 2a 20 66 6f 72 20 74 68 65 20 76 61 6c 75  .** for the valu
2be10 65 73 20 69 74 20 73 74 6f 72 65 73 2e 20 20 5e  es it stores.  ^
2be20 56 61 6c 75 65 73 20 73 74 6f 72 65 64 20 69 6e  Values stored in
2be30 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
2be40 62 6a 65 63 74 73 0a 2a 2a 20 63 61 6e 20 62 65  bjects.** can be
2be50 20 69 6e 74 65 67 65 72 73 2c 20 66 6c 6f 61 74   integers, float
2be60 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 73  ing point values
2be70 2c 20 73 74 72 69 6e 67 73 2c 20 42 4c 4f 42 73  , strings, BLOBs
2be80 2c 20 6f 72 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a  , or NULL..**.**
2be90 20 41 6e 20 73 71 6c 69 74 65 33 5f 76 61 6c 75   An sqlite3_valu
2bea0 65 20 6f 62 6a 65 63 74 20 6d 61 79 20 62 65 20  e object may be 
2beb0 65 69 74 68 65 72 20 22 70 72 6f 74 65 63 74 65  either "protecte
2bec0 64 22 20 6f 72 20 22 75 6e 70 72 6f 74 65 63 74  d" or "unprotect
2bed0 65 64 22 2e 0a 2a 2a 20 53 6f 6d 65 20 69 6e 74  ed"..** Some int
2bee0 65 72 66 61 63 65 73 20 72 65 71 75 69 72 65 20  erfaces require 
2bef0 61 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  a protected sqli
2bf00 74 65 33 5f 76 61 6c 75 65 2e 20 20 4f 74 68 65  te3_value.  Othe
2bf10 72 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20  r interfaces.** 
2bf20 77 69 6c 6c 20 61 63 63 65 70 74 20 65 69 74 68  will accept eith
2bf30 65 72 20 61 20 70 72 6f 74 65 63 74 65 64 20 6f  er a protected o
2bf40 72 20 61 6e 20 75 6e 70 72 6f 74 65 63 74 65 64  r an unprotected
2bf50 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 0a   sqlite3_value..
2bf60 2a 2a 20 45 76 65 72 79 20 69 6e 74 65 72 66 61  ** Every interfa
2bf70 63 65 20 74 68 61 74 20 61 63 63 65 70 74 73 20  ce that accepts 
2bf80 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 61 72  sqlite3_value ar
2bf90 67 75 6d 65 6e 74 73 20 73 70 65 63 69 66 69 65  guments specifie
2bfa0 73 0a 2a 2a 20 77 68 65 74 68 65 72 20 6f 72 20  s.** whether or 
2bfb0 6e 6f 74 20 69 74 20 72 65 71 75 69 72 65 73 20  not it requires 
2bfc0 61 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  a protected sqli
2bfd0 74 65 33 5f 76 61 6c 75 65 2e 20 20 54 68 65 0a  te3_value.  The.
2bfe0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  ** [sqlite3_valu
2bff0 65 5f 64 75 70 28 29 5d 20 69 6e 74 65 72 66 61  e_dup()] interfa
2c000 63 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 74  ce can be used t
2c010 6f 20 63 6f 6e 73 74 72 75 63 74 20 61 20 6e 65  o construct a ne
2c020 77 20 0a 2a 2a 20 70 72 6f 74 65 63 74 65 64 20  w .** protected 
2c030 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 66 72  sqlite3_value fr
2c040 6f 6d 20 61 6e 20 75 6e 70 72 6f 74 65 63 74 65  om an unprotecte
2c050 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e  d sqlite3_value.
2c060 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 65 72 6d 73  .**.** The terms
2c070 20 22 70 72 6f 74 65 63 74 65 64 22 20 61 6e 64   "protected" and
2c080 20 22 75 6e 70 72 6f 74 65 63 74 65 64 22 20 72   "unprotected" r
2c090 65 66 65 72 20 74 6f 20 77 68 65 74 68 65 72 20  efer to whether 
2c0a0 6f 72 20 6e 6f 74 0a 2a 2a 20 61 20 6d 75 74 65  or not.** a mute
2c0b0 78 20 69 73 20 68 65 6c 64 2e 20 20 41 6e 20 69  x is held.  An i
2c0c0 6e 74 65 72 6e 61 6c 20 6d 75 74 65 78 20 69 73  nternal mutex is
2c0d0 20 68 65 6c 64 20 66 6f 72 20 61 20 70 72 6f 74   held for a prot
2c0e0 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33  ected.** sqlite3
2c0f0 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 62 75  _value object bu
2c100 74 20 6e 6f 20 6d 75 74 65 78 20 69 73 20 68 65  t no mutex is he
2c110 6c 64 20 66 6f 72 20 61 6e 20 75 6e 70 72 6f 74  ld for an unprot
2c120 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33  ected.** sqlite3
2c130 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 2e 20 20  _value object.  
2c140 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  If SQLite is com
2c150 70 69 6c 65 64 20 74 6f 20 62 65 20 73 69 6e 67  piled to be sing
2c160 6c 65 2d 74 68 72 65 61 64 65 64 0a 2a 2a 20 28  le-threaded.** (
2c170 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 54 48 52  with [SQLITE_THR
2c180 45 41 44 53 41 46 45 3d 30 5d 20 61 6e 64 20 77  EADSAFE=0] and w
2c190 69 74 68 20 5b 73 71 6c 69 74 65 33 5f 74 68 72  ith [sqlite3_thr
2c1a0 65 61 64 73 61 66 65 28 29 5d 20 72 65 74 75 72  eadsafe()] retur
2c1b0 6e 69 6e 67 20 30 29 0a 2a 2a 20 6f 72 20 69 66  ning 0).** or if
2c1c0 20 53 51 4c 69 74 65 20 69 73 20 72 75 6e 20 69   SQLite is run i
2c1d0 6e 20 6f 6e 65 20 6f 66 20 72 65 64 75 63 65 64  n one of reduced
2c1e0 20 6d 75 74 65 78 20 6d 6f 64 65 73 20 0a 2a 2a   mutex modes .**
2c1f0 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
2c200 53 49 4e 47 4c 45 54 48 52 45 41 44 5d 20 6f 72  SINGLETHREAD] or
2c210 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
2c220 4d 55 4c 54 49 54 48 52 45 41 44 5d 0a 2a 2a 20  MULTITHREAD].** 
2c230 74 68 65 6e 20 74 68 65 72 65 20 69 73 20 6e 6f  then there is no
2c240 20 64 69 73 74 69 6e 63 74 69 6f 6e 20 62 65 74   distinction bet
2c250 77 65 65 6e 20 70 72 6f 74 65 63 74 65 64 20 61  ween protected a
2c260 6e 64 20 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a  nd unprotected.*
2c270 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  * sqlite3_value 
2c280 6f 62 6a 65 63 74 73 20 61 6e 64 20 74 68 65 79  objects and they
2c290 20 63 61 6e 20 62 65 20 75 73 65 64 20 69 6e 74   can be used int
2c2a0 65 72 63 68 61 6e 67 65 61 62 6c 79 2e 20 20 48  erchangeably.  H
2c2b0 6f 77 65 76 65 72 2c 0a 2a 2a 20 66 6f 72 20 6d  owever,.** for m
2c2c0 61 78 69 6d 75 6d 20 63 6f 64 65 20 70 6f 72 74  aximum code port
2c2d0 61 62 69 6c 69 74 79 20 69 74 20 69 73 20 72 65  ability it is re
2c2e0 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 61  commended that a
2c2f0 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73  pplications.** s
2c300 74 69 6c 6c 20 6d 61 6b 65 20 74 68 65 20 64 69  till make the di
2c310 73 74 69 6e 63 74 69 6f 6e 20 62 65 74 77 65 65  stinction betwee
2c320 6e 20 70 72 6f 74 65 63 74 65 64 20 61 6e 64 20  n protected and 
2c330 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73  unprotected.** s
2c340 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
2c350 65 63 74 73 20 65 76 65 6e 20 77 68 65 6e 20 6e  ects even when n
2c360 6f 74 20 73 74 72 69 63 74 6c 79 20 72 65 71 75  ot strictly requ
2c370 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ired..**.** ^The
2c380 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
2c390 62 6a 65 63 74 73 20 74 68 61 74 20 61 72 65 20  bjects that are 
2c3a0 70 61 73 73 65 64 20 61 73 20 70 61 72 61 6d 65  passed as parame
2c3b0 74 65 72 73 20 69 6e 74 6f 20 74 68 65 0a 2a 2a  ters into the.**
2c3c0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
2c3d0 6f 66 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d  of [application-
2c3e0 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63  defined SQL func
2c3f0 74 69 6f 6e 73 5d 20 61 72 65 20 70 72 6f 74 65  tions] are prote
2c400 63 74 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 73 71  cted..** ^The sq
2c410 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
2c420 63 74 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a  ct returned by.*
2c430 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  * [sqlite3_colum
2c440 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 75 6e  n_value()] is un
2c450 70 72 6f 74 65 63 74 65 64 2e 0a 2a 2a 20 55 6e  protected..** Un
2c460 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
2c470 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20  3_value objects 
2c480 6d 61 79 20 6f 6e 6c 79 20 62 65 20 75 73 65 64  may only be used
2c490 20 77 69 74 68 0a 2a 2a 20 5b 73 71 6c 69 74 65   with.** [sqlite
2c4a0 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29  3_result_value()
2c4b0 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62  ] and [sqlite3_b
2c4c0 69 6e 64 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a  ind_value()]..**
2c4d0 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61   The [sqlite3_va
2c4e0 6c 75 65 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74  lue_blob | sqlit
2c4f0 65 33 5f 76 61 6c 75 65 5f 74 79 70 65 28 29 5d  e3_value_type()]
2c500 20 66 61 6d 69 6c 79 20 6f 66 0a 2a 2a 20 69 6e   family of.** in
2c510 74 65 72 66 61 63 65 73 20 72 65 71 75 69 72 65  terfaces require
2c520 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74   protected sqlit
2c530 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73  e3_value objects
2c540 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72  ..*/.typedef str
2c550 75 63 74 20 4d 65 6d 20 73 71 6c 69 74 65 33 5f  uct Mem sqlite3_
2c560 76 61 6c 75 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  value;../*.** CA
2c570 50 49 33 52 45 46 3a 20 53 51 4c 20 46 75 6e 63  PI3REF: SQL Func
2c580 74 69 6f 6e 20 43 6f 6e 74 65 78 74 20 4f 62 6a  tion Context Obj
2c590 65 63 74 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f  ect.**.** The co
2c5a0 6e 74 65 78 74 20 69 6e 20 77 68 69 63 68 20 61  ntext in which a
2c5b0 6e 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 65  n SQL function e
2c5c0 78 65 63 75 74 65 73 20 69 73 20 73 74 6f 72 65  xecutes is store
2c5d0 64 20 69 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69 74  d in an.** sqlit
2c5e0 65 33 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65 63  e3_context objec
2c5f0 74 2e 20 20 5e 41 20 70 6f 69 6e 74 65 72 20 74  t.  ^A pointer t
2c600 6f 20 61 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6e  o an sqlite3_con
2c610 74 65 78 74 20 6f 62 6a 65 63 74 0a 2a 2a 20 69  text object.** i
2c620 73 20 61 6c 77 61 79 73 20 66 69 72 73 74 20 70  s always first p
2c630 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 61 70 70  arameter to [app
2c640 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
2c650 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 2e   SQL functions].
2c660 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74  .** The applicat
2c670 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20  ion-defined SQL 
2c680 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65  function impleme
2c690 6e 74 61 74 69 6f 6e 20 77 69 6c 6c 20 70 61 73  ntation will pas
2c6a0 73 20 74 68 69 73 0a 2a 2a 20 70 6f 69 6e 74 65  s this.** pointe
2c6b0 72 20 74 68 72 6f 75 67 68 20 69 6e 74 6f 20 63  r through into c
2c6c0 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33  alls to [sqlite3
2c6d0 5f 72 65 73 75 6c 74 5f 69 6e 74 20 7c 20 73 71  _result_int | sq
2c6e0 6c 69 74 65 33 5f 72 65 73 75 6c 74 28 29 5d 2c  lite3_result()],
2c6f0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 61 67 67  .** [sqlite3_agg
2c700 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29  regate_context()
2c710 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 75 73 65 72  ], [sqlite3_user
2c720 5f 64 61 74 61 28 29 5d 2c 0a 2a 2a 20 5b 73 71  _data()],.** [sq
2c730 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62  lite3_context_db
2c740 5f 68 61 6e 64 6c 65 28 29 5d 2c 20 5b 73 71 6c  _handle()], [sql
2c750 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61  ite3_get_auxdata
2c760 28 29 5d 2c 0a 2a 2a 20 61 6e 64 2f 6f 72 20 5b  ()],.** and/or [
2c770 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64  sqlite3_set_auxd
2c780 61 74 61 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64  ata()]..*/.typed
2c790 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  ef struct sqlite
2c7a0 33 5f 63 6f 6e 74 65 78 74 20 73 71 6c 69 74 65  3_context sqlite
2c7b0 33 5f 63 6f 6e 74 65 78 74 3b 0a 0a 2f 2a 0a 2a  3_context;../*.*
2c7c0 2a 20 43 41 50 49 33 52 45 46 3a 20 42 69 6e 64  * CAPI3REF: Bind
2c7d0 69 6e 67 20 56 61 6c 75 65 73 20 54 6f 20 50 72  ing Values To Pr
2c7e0 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74  epared Statement
2c7f0 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  s.** KEYWORDS: {
2c800 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 7d 20  host parameter} 
2c810 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73  {host parameters
2c820 7d 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65  } {host paramete
2c830 72 20 6e 61 6d 65 7d 0a 2a 2a 20 4b 45 59 57 4f  r name}.** KEYWO
2c840 52 44 53 3a 20 7b 53 51 4c 20 70 61 72 61 6d 65  RDS: {SQL parame
2c850 74 65 72 7d 20 7b 53 51 4c 20 70 61 72 61 6d 65  ter} {SQL parame
2c860 74 65 72 73 7d 20 7b 70 61 72 61 6d 65 74 65 72  ters} {parameter
2c870 20 62 69 6e 64 69 6e 67 7d 0a 2a 2a 20 4d 45 54   binding}.** MET
2c880 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d  HOD: sqlite3_stm
2c890 74 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 74 68 65  t.**.** ^(In the
2c8a0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74   SQL statement t
2c8b0 65 78 74 20 69 6e 70 75 74 20 74 6f 20 5b 73 71  ext input to [sq
2c8c0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
2c8d0 28 29 5d 20 61 6e 64 20 69 74 73 20 76 61 72 69  ()] and its vari
2c8e0 61 6e 74 73 2c 0a 2a 2a 20 6c 69 74 65 72 61 6c  ants,.** literal
2c8f0 73 20 6d 61 79 20 62 65 20 72 65 70 6c 61 63 65  s may be replace
2c900 64 20 62 79 20 61 20 5b 70 61 72 61 6d 65 74 65  d by a [paramete
2c910 72 5d 20 74 68 61 74 20 6d 61 74 63 68 65 73 20  r] that matches 
2c920 6f 6e 65 20 6f 66 20 66 6f 6c 6c 6f 77 69 6e 67  one of following
2c930 0a 2a 2a 20 74 65 6d 70 6c 61 74 65 73 3a 0a 2a  .** templates:.*
2c940 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ul>.** <li
2c950 3e 20 20 3f 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 4e  >  ?.** <li>  ?N
2c960 4e 4e 0a 2a 2a 20 3c 6c 69 3e 20 20 3a 56 56 56  NN.** <li>  :VVV
2c970 0a 2a 2a 20 3c 6c 69 3e 20 20 40 56 56 56 0a 2a  .** <li>  @VVV.*
2c980 2a 20 3c 6c 69 3e 20 20 24 56 56 56 0a 2a 2a 20  * <li>  $VVV.** 
2c990 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74  </ul>.**.** In t
2c9a0 68 65 20 74 65 6d 70 6c 61 74 65 73 20 61 62 6f  he templates abo
2c9b0 76 65 2c 20 4e 4e 4e 20 72 65 70 72 65 73 65 6e  ve, NNN represen
2c9c0 74 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6c 69  ts an integer li
2c9d0 74 65 72 61 6c 2c 0a 2a 2a 20 61 6e 64 20 56 56  teral,.** and VV
2c9e0 56 20 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20  V represents an 
2c9f0 61 6c 70 68 61 6e 75 6d 65 72 69 63 20 69 64 65  alphanumeric ide
2ca00 6e 74 69 66 69 65 72 2e 29 5e 20 20 5e 54 68 65  ntifier.)^  ^The
2ca10 20 76 61 6c 75 65 73 20 6f 66 20 74 68 65 73 65   values of these
2ca20 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 20 28  .** parameters (
2ca30 61 6c 73 6f 20 63 61 6c 6c 65 64 20 22 68 6f 73  also called "hos
2ca40 74 20 70 61 72 61 6d 65 74 65 72 20 6e 61 6d 65  t parameter name
2ca50 73 22 20 6f 72 20 22 53 51 4c 20 70 61 72 61 6d  s" or "SQL param
2ca60 65 74 65 72 73 22 29 0a 2a 2a 20 63 61 6e 20 62  eters").** can b
2ca70 65 20 73 65 74 20 75 73 69 6e 67 20 74 68 65 20  e set using the 
2ca80 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29  sqlite3_bind_*()
2ca90 20 72 6f 75 74 69 6e 65 73 20 64 65 66 69 6e 65   routines define
2caa0 64 20 68 65 72 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54  d here..**.** ^T
2cab0 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
2cac0 74 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33  t to the sqlite3
2cad0 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e  _bind_*() routin
2cae0 65 73 20 69 73 20 61 6c 77 61 79 73 0a 2a 2a 20  es is always.** 
2caf0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
2cb00 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20   [sqlite3_stmt] 
2cb10 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20  object returned 
2cb20 66 72 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  from.** [sqlite3
2cb30 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f  _prepare_v2()] o
2cb40 72 20 69 74 73 20 76 61 72 69 61 6e 74 73 2e 0a  r its variants..
2cb50 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e  **.** ^The secon
2cb60 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68  d argument is th
2cb70 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20 53  e index of the S
2cb80 51 4c 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  QL parameter to 
2cb90 62 65 20 73 65 74 2e 0a 2a 2a 20 5e 54 68 65 20  be set..** ^The 
2cba0 6c 65 66 74 6d 6f 73 74 20 53 51 4c 20 70 61 72  leftmost SQL par
2cbb0 61 6d 65 74 65 72 20 68 61 73 20 61 6e 20 69 6e  ameter has an in
2cbc0 64 65 78 20 6f 66 20 31 2e 20 20 5e 57 68 65 6e  dex of 1.  ^When
2cbd0 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 64 0a   the same named.
2cbe0 2a 2a 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72  ** SQL parameter
2cbf0 20 69 73 20 75 73 65 64 20 6d 6f 72 65 20 74 68   is used more th
2cc00 61 6e 20 6f 6e 63 65 2c 20 73 65 63 6f 6e 64 20  an once, second 
2cc10 61 6e 64 20 73 75 62 73 65 71 75 65 6e 74 0a 2a  and subsequent.*
2cc20 2a 20 6f 63 63 75 72 72 65 6e 63 65 73 20 68 61  * occurrences ha
2cc30 76 65 20 74 68 65 20 73 61 6d 65 20 69 6e 64 65  ve the same inde
2cc40 78 20 61 73 20 74 68 65 20 66 69 72 73 74 20 6f  x as the first o
2cc50 63 63 75 72 72 65 6e 63 65 2e 0a 2a 2a 20 5e 54  ccurrence..** ^T
2cc60 68 65 20 69 6e 64 65 78 20 66 6f 72 20 6e 61 6d  he index for nam
2cc70 65 64 20 70 61 72 61 6d 65 74 65 72 73 20 63 61  ed parameters ca
2cc80 6e 20 62 65 20 6c 6f 6f 6b 65 64 20 75 70 20 75  n be looked up u
2cc90 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c  sing the.** [sql
2cca0 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
2ccb0 74 65 72 5f 69 6e 64 65 78 28 29 5d 20 41 50 49  ter_index()] API
2ccc0 20 69 66 20 64 65 73 69 72 65 64 2e 20 20 5e 54   if desired.  ^T
2ccd0 68 65 20 69 6e 64 65 78 0a 2a 2a 20 66 6f 72 20  he index.** for 
2cce0 22 3f 4e 4e 4e 22 20 70 61 72 61 6d 65 74 65 72  "?NNN" parameter
2ccf0 73 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f  s is the value o
2cd00 66 20 4e 4e 4e 2e 0a 2a 2a 20 5e 54 68 65 20 4e  f NNN..** ^The N
2cd10 4e 4e 20 76 61 6c 75 65 20 6d 75 73 74 20 62 65  NN value must be
2cd20 20 62 65 74 77 65 65 6e 20 31 20 61 6e 64 20 74   between 1 and t
2cd30 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69  he [sqlite3_limi
2cd40 74 28 29 5d 0a 2a 2a 20 70 61 72 61 6d 65 74 65  t()].** paramete
2cd50 72 20 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  r [SQLITE_LIMIT_
2cd60 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 5d  VARIABLE_NUMBER]
2cd70 20 28 64 65 66 61 75 6c 74 20 76 61 6c 75 65 3a   (default value:
2cd80 20 39 39 39 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68   999)..**.** ^Th
2cd90 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74  e third argument
2cda0 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 74 6f   is the value to
2cdb0 20 62 69 6e 64 20 74 6f 20 74 68 65 20 70 61 72   bind to the par
2cdc0 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 74  ameter..** ^If t
2cdd0 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  he third paramet
2cde0 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69  er to sqlite3_bi
2cdf0 6e 64 5f 74 65 78 74 28 29 20 6f 72 20 73 71 6c  nd_text() or sql
2ce00 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36  ite3_bind_text16
2ce10 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33  ().** or sqlite3
2ce20 5f 62 69 6e 64 5f 62 6c 6f 62 28 29 20 69 73 20  _bind_blob() is 
2ce30 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74  a NULL pointer t
2ce40 68 65 6e 20 74 68 65 20 66 6f 75 72 74 68 20 70  hen the fourth p
2ce50 61 72 61 6d 65 74 65 72 0a 2a 2a 20 69 73 20 69  arameter.** is i
2ce60 67 6e 6f 72 65 64 20 61 6e 64 20 74 68 65 20 65  gnored and the e
2ce70 6e 64 20 72 65 73 75 6c 74 20 69 73 20 74 68 65  nd result is the
2ce80 20 73 61 6d 65 20 61 73 20 73 71 6c 69 74 65 33   same as sqlite3
2ce90 5f 62 69 6e 64 5f 6e 75 6c 6c 28 29 2e 0a 2a 2a  _bind_null()..**
2cea0 0a 2a 2a 20 5e 28 49 6e 20 74 68 6f 73 65 20 72  .** ^(In those r
2ceb0 6f 75 74 69 6e 65 73 20 74 68 61 74 20 68 61 76  outines that hav
2cec0 65 20 61 20 66 6f 75 72 74 68 20 61 72 67 75 6d  e a fourth argum
2ced0 65 6e 74 2c 20 69 74 73 20 76 61 6c 75 65 20 69  ent, its value i
2cee0 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20  s the.** number 
2cef0 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 65 20  of bytes in the 
2cf00 70 61 72 61 6d 65 74 65 72 2e 20 20 54 6f 20 62  parameter.  To b
2cf10 65 20 63 6c 65 61 72 3a 20 74 68 65 20 76 61 6c  e clear: the val
2cf20 75 65 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d  ue is the.** num
2cf30 62 65 72 20 6f 66 20 3c 75 3e 62 79 74 65 73 3c  ber of <u>bytes<
2cf40 2f 75 3e 20 69 6e 20 74 68 65 20 76 61 6c 75 65  /u> in the value
2cf50 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62 65 72  , not the number
2cf60 20 6f 66 20 63 68 61 72 61 63 74 65 72 73 2e 29   of characters.)
2cf70 5e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 6f 75  ^.** ^If the fou
2cf80 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  rth parameter to
2cf90 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65   sqlite3_bind_te
2cfa0 78 74 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  xt() or sqlite3_
2cfb0 62 69 6e 64 5f 74 65 78 74 31 36 28 29 0a 2a 2a  bind_text16().**
2cfc0 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68   is negative, th
2cfd0 65 6e 20 74 68 65 20 6c 65 6e 67 74 68 20 6f 66  en the length of
2cfe0 20 74 68 65 20 73 74 72 69 6e 67 20 69 73 0a 2a   the string is.*
2cff0 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  * the number of 
2d000 62 79 74 65 73 20 75 70 20 74 6f 20 74 68 65 20  bytes up to the 
2d010 66 69 72 73 74 20 7a 65 72 6f 20 74 65 72 6d 69  first zero termi
2d020 6e 61 74 6f 72 2e 0a 2a 2a 20 49 66 20 74 68 65  nator..** If the
2d030 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
2d040 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e  r to sqlite3_bin
2d050 64 5f 62 6c 6f 62 28 29 20 69 73 20 6e 65 67 61  d_blob() is nega
2d060 74 69 76 65 2c 20 74 68 65 6e 0a 2a 2a 20 74 68  tive, then.** th
2d070 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e  e behavior is un
2d080 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 49 66 20 61  defined..** If a
2d090 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 20 66 6f   non-negative fo
2d0a0 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 69  urth parameter i
2d0b0 73 20 70 72 6f 76 69 64 65 64 20 74 6f 20 73 71  s provided to sq
2d0c0 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28  lite3_bind_text(
2d0d0 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f  ).** or sqlite3_
2d0e0 62 69 6e 64 5f 74 65 78 74 31 36 28 29 20 6f 72  bind_text16() or
2d0f0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65   sqlite3_bind_te
2d100 78 74 36 34 28 29 20 74 68 65 6e 0a 2a 2a 20 74  xt64() then.** t
2d110 68 61 74 20 70 61 72 61 6d 65 74 65 72 20 6d 75  hat parameter mu
2d120 73 74 20 62 65 20 74 68 65 20 62 79 74 65 20 6f  st be the byte o
2d130 66 66 73 65 74 0a 2a 2a 20 77 68 65 72 65 20 74  ffset.** where t
2d140 68 65 20 4e 55 4c 20 74 65 72 6d 69 6e 61 74 6f  he NUL terminato
2d150 72 20 77 6f 75 6c 64 20 6f 63 63 75 72 20 61 73  r would occur as
2d160 73 75 6d 69 6e 67 20 74 68 65 20 73 74 72 69 6e  suming the strin
2d170 67 20 77 65 72 65 20 4e 55 4c 0a 2a 2a 20 74 65  g were NUL.** te
2d180 72 6d 69 6e 61 74 65 64 2e 20 20 49 66 20 61 6e  rminated.  If an
2d190 79 20 4e 55 4c 20 63 68 61 72 61 63 74 65 72 73  y NUL characters
2d1a0 20 6f 63 63 75 72 20 61 74 20 62 79 74 65 20 6f   occur at byte o
2d1b0 66 66 73 65 74 73 20 6c 65 73 73 20 74 68 61 6e  ffsets less than
2d1c0 20 0a 2a 2a 20 74 68 65 20 76 61 6c 75 65 20 6f   .** the value o
2d1d0 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72  f the fourth par
2d1e0 61 6d 65 74 65 72 20 74 68 65 6e 20 74 68 65 20  ameter then the 
2d1f0 72 65 73 75 6c 74 69 6e 67 20 73 74 72 69 6e 67  resulting string
2d200 20 76 61 6c 75 65 20 77 69 6c 6c 0a 2a 2a 20 63   value will.** c
2d210 6f 6e 74 61 69 6e 20 65 6d 62 65 64 64 65 64 20  ontain embedded 
2d220 4e 55 4c 73 2e 20 20 54 68 65 20 72 65 73 75 6c  NULs.  The resul
2d230 74 20 6f 66 20 65 78 70 72 65 73 73 69 6f 6e 73  t of expressions
2d240 20 69 6e 76 6f 6c 76 69 6e 67 20 73 74 72 69 6e   involving strin
2d250 67 73 0a 2a 2a 20 77 69 74 68 20 65 6d 62 65 64  gs.** with embed
2d260 64 65 64 20 4e 55 4c 73 20 69 73 20 75 6e 64 65  ded NULs is unde
2d270 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  fined..**.** ^Th
2d280 65 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74  e fifth argument
2d290 20 74 6f 20 74 68 65 20 42 4c 4f 42 20 61 6e 64   to the BLOB and
2d2a0 20 73 74 72 69 6e 67 20 62 69 6e 64 69 6e 67 20   string binding 
2d2b0 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 69 73  interfaces.** is
2d2c0 20 61 20 64 65 73 74 72 75 63 74 6f 72 20 75 73   a destructor us
2d2d0 65 64 20 74 6f 20 64 69 73 70 6f 73 65 20 6f 66  ed to dispose of
2d2e0 20 74 68 65 20 42 4c 4f 42 20 6f 72 0a 2a 2a 20   the BLOB or.** 
2d2f0 73 74 72 69 6e 67 20 61 66 74 65 72 20 53 51 4c  string after SQL
2d300 69 74 65 20 68 61 73 20 66 69 6e 69 73 68 65 64  ite has finished
2d310 20 77 69 74 68 20 69 74 2e 20 20 5e 54 68 65 20   with it.  ^The 
2d320 64 65 73 74 72 75 63 74 6f 72 20 69 73 20 63 61  destructor is ca
2d330 6c 6c 65 64 0a 2a 2a 20 74 6f 20 64 69 73 70 6f  lled.** to dispo
2d340 73 65 20 6f 66 20 74 68 65 20 42 4c 4f 42 20 6f  se of the BLOB o
2d350 72 20 73 74 72 69 6e 67 20 65 76 65 6e 20 69 66  r string even if
2d360 20 74 68 65 20 63 61 6c 6c 20 74 6f 20 62 69 6e   the call to bin
2d370 64 20 41 50 49 20 66 61 69 6c 73 2e 0a 2a 2a 20  d API fails..** 
2d380 5e 49 66 20 74 68 65 20 66 69 66 74 68 20 61 72  ^If the fifth ar
2d390 67 75 6d 65 6e 74 20 69 73 0a 2a 2a 20 74 68 65  gument is.** the
2d3a0 20 73 70 65 63 69 61 6c 20 76 61 6c 75 65 20 5b   special value [
2d3b0 53 51 4c 49 54 45 5f 53 54 41 54 49 43 5d 2c 20  SQLITE_STATIC], 
2d3c0 74 68 65 6e 20 53 51 4c 69 74 65 20 61 73 73 75  then SQLite assu
2d3d0 6d 65 73 20 74 68 61 74 20 74 68 65 0a 2a 2a 20  mes that the.** 
2d3e0 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 69  information is i
2d3f0 6e 20 73 74 61 74 69 63 2c 20 75 6e 6d 61 6e 61  n static, unmana
2d400 67 65 64 20 73 70 61 63 65 20 61 6e 64 20 64 6f  ged space and do
2d410 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62  es not need to b
2d420 65 20 66 72 65 65 64 2e 0a 2a 2a 20 5e 49 66 20  e freed..** ^If 
2d430 74 68 65 20 66 69 66 74 68 20 61 72 67 75 6d 65  the fifth argume
2d440 6e 74 20 68 61 73 20 74 68 65 20 76 61 6c 75 65  nt has the value
2d450 20 5b 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45   [SQLITE_TRANSIE
2d460 4e 54 5d 2c 20 74 68 65 6e 0a 2a 2a 20 53 51 4c  NT], then.** SQL
2d470 69 74 65 20 6d 61 6b 65 73 20 69 74 73 20 6f 77  ite makes its ow
2d480 6e 20 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f  n private copy o
2d490 66 20 74 68 65 20 64 61 74 61 20 69 6d 6d 65 64  f the data immed
2d4a0 69 61 74 65 6c 79 2c 20 62 65 66 6f 72 65 0a 2a  iately, before.*
2d4b0 2a 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69  * the sqlite3_bi
2d4c0 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 20 72  nd_*() routine r
2d4d0 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54  eturns..**.** ^T
2d4e0 68 65 20 73 69 78 74 68 20 61 72 67 75 6d 65 6e  he sixth argumen
2d4f0 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e  t to sqlite3_bin
2d500 64 5f 74 65 78 74 36 34 28 29 20 6d 75 73 74 20  d_text64() must 
2d510 62 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 5b 53 51  be one of.** [SQ
2d520 4c 49 54 45 5f 55 54 46 38 5d 2c 20 5b 53 51 4c  LITE_UTF8], [SQL
2d530 49 54 45 5f 55 54 46 31 36 5d 2c 20 5b 53 51 4c  ITE_UTF16], [SQL
2d540 49 54 45 5f 55 54 46 31 36 42 45 5d 2c 20 6f 72  ITE_UTF16BE], or
2d550 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45   [SQLITE_UTF16LE
2d560 5d 0a 2a 2a 20 74 6f 20 73 70 65 63 69 66 79 20  ].** to specify 
2d570 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 6f 66 20  the encoding of 
2d580 74 68 65 20 74 65 78 74 20 69 6e 20 74 68 65 20  the text in the 
2d590 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 2e  third parameter.
2d5a0 20 20 49 66 0a 2a 2a 20 74 68 65 20 73 69 78 74    If.** the sixt
2d5b0 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71  h argument to sq
2d5c0 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 36  lite3_bind_text6
2d5d0 34 28 29 20 69 73 20 6e 6f 74 20 6f 6e 65 20 6f  4() is not one o
2d5e0 66 20 74 68 65 0a 2a 2a 20 61 6c 6c 6f 77 65 64  f the.** allowed
2d5f0 20 76 61 6c 75 65 73 20 73 68 6f 77 6e 20 61 62   values shown ab
2d600 6f 76 65 2c 20 6f 72 20 69 66 20 74 68 65 20 74  ove, or if the t
2d610 65 78 74 20 65 6e 63 6f 64 69 6e 67 20 69 73 20  ext encoding is 
2d620 64 69 66 66 65 72 65 6e 74 0a 2a 2a 20 66 72 6f  different.** fro
2d630 6d 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 73  m the encoding s
2d640 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20  pecified by the 
2d650 73 69 78 74 68 20 70 61 72 61 6d 65 74 65 72 2c  sixth parameter,
2d660 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69   then the behavi
2d670 6f 72 0a 2a 2a 20 69 73 20 75 6e 64 65 66 69 6e  or.** is undefin
2d680 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ed..**.** ^The s
2d690 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f  qlite3_bind_zero
2d6a0 62 6c 6f 62 28 29 20 72 6f 75 74 69 6e 65 20 62  blob() routine b
2d6b0 69 6e 64 73 20 61 20 42 4c 4f 42 20 6f 66 20 6c  inds a BLOB of l
2d6c0 65 6e 67 74 68 20 4e 20 74 68 61 74 0a 2a 2a 20  ength N that.** 
2d6d0 69 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20 7a  is filled with z
2d6e0 65 72 6f 65 73 2e 20 20 5e 41 20 7a 65 72 6f 62  eroes.  ^A zerob
2d6f0 6c 6f 62 20 75 73 65 73 20 61 20 66 69 78 65 64  lob uses a fixed
2d700 20 61 6d 6f 75 6e 74 20 6f 66 20 6d 65 6d 6f 72   amount of memor
2d710 79 0a 2a 2a 20 28 6a 75 73 74 20 61 6e 20 69 6e  y.** (just an in
2d720 74 65 67 65 72 20 74 6f 20 68 6f 6c 64 20 69 74  teger to hold it
2d730 73 20 73 69 7a 65 29 20 77 68 69 6c 65 20 69 74  s size) while it
2d740 20 69 73 20 62 65 69 6e 67 20 70 72 6f 63 65 73   is being proces
2d750 73 65 64 2e 0a 2a 2a 20 5a 65 72 6f 62 6c 6f 62  sed..** Zeroblob
2d760 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20 74  s are intended t
2d770 6f 20 73 65 72 76 65 20 61 73 20 70 6c 61 63 65  o serve as place
2d780 68 6f 6c 64 65 72 73 20 66 6f 72 20 42 4c 4f 42  holders for BLOB
2d790 73 20 77 68 6f 73 65 0a 2a 2a 20 63 6f 6e 74 65  s whose.** conte
2d7a0 6e 74 20 69 73 20 6c 61 74 65 72 20 77 72 69 74  nt is later writ
2d7b0 74 65 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71  ten using.** [sq
2d7c0 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 20  lite3_blob_open 
2d7d0 7c 20 69 6e 63 72 65 6d 65 6e 74 61 6c 20 42 4c  | incremental BL
2d7e0 4f 42 20 49 2f 4f 5d 20 72 6f 75 74 69 6e 65 73  OB I/O] routines
2d7f0 2e 0a 2a 2a 20 5e 41 20 6e 65 67 61 74 69 76 65  ..** ^A negative
2d800 20 76 61 6c 75 65 20 66 6f 72 20 74 68 65 20 7a   value for the z
2d810 65 72 6f 62 6c 6f 62 20 72 65 73 75 6c 74 73 20  eroblob results 
2d820 69 6e 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68  in a zero-length
2d830 20 42 4c 4f 42 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66   BLOB..**.** ^If
2d840 20 61 6e 79 20 6f 66 20 74 68 65 20 73 71 6c 69   any of the sqli
2d850 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75  te3_bind_*() rou
2d860 74 69 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64  tines are called
2d870 20 77 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69   with a NULL poi
2d880 6e 74 65 72 0a 2a 2a 20 66 6f 72 20 74 68 65 20  nter.** for the 
2d890 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2d8a0 65 6e 74 5d 20 6f 72 20 77 69 74 68 20 61 20 70  ent] or with a p
2d8b0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2d8c0 74 20 66 6f 72 20 77 68 69 63 68 0a 2a 2a 20 5b  t for which.** [
2d8d0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
2d8e0 68 61 73 20 62 65 65 6e 20 63 61 6c 6c 65 64 20  has been called 
2d8f0 6d 6f 72 65 20 72 65 63 65 6e 74 6c 79 20 74 68  more recently th
2d900 61 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  an [sqlite3_rese
2d910 74 28 29 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74 68  t()],.** then th
2d920 65 20 63 61 6c 6c 20 77 69 6c 6c 20 72 65 74 75  e call will retu
2d930 72 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53  rn [SQLITE_MISUS
2d940 45 5d 2e 20 20 49 66 20 61 6e 79 20 73 71 6c 69  E].  If any sqli
2d950 74 65 33 5f 62 69 6e 64 5f 28 29 0a 2a 2a 20 72  te3_bind_().** r
2d960 6f 75 74 69 6e 65 20 69 73 20 70 61 73 73 65 64  outine is passed
2d970 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
2d980 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 68 61 73  tement] that has
2d990 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64 2c   been finalized,
2d9a0 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 69   the.** result i
2d9b0 73 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 20  s undefined and 
2d9c0 70 72 6f 62 61 62 6c 79 20 68 61 72 6d 66 75 6c  probably harmful
2d9d0 2e 0a 2a 2a 0a 2a 2a 20 5e 42 69 6e 64 69 6e 67  ..**.** ^Binding
2d9e0 73 20 61 72 65 20 6e 6f 74 20 63 6c 65 61 72 65  s are not cleare
2d9f0 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65  d by the [sqlite
2da00 33 5f 72 65 73 65 74 28 29 5d 20 72 6f 75 74 69  3_reset()] routi
2da10 6e 65 2e 0a 2a 2a 20 5e 55 6e 62 6f 75 6e 64 20  ne..** ^Unbound 
2da20 70 61 72 61 6d 65 74 65 72 73 20 61 72 65 20 69  parameters are i
2da30 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 4e 55  nterpreted as NU
2da40 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  LL..**.** ^The s
2da50 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 20 72 6f  qlite3_bind_* ro
2da60 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 5b 53  utines return [S
2da70 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63  QLITE_OK] on suc
2da80 63 65 73 73 20 6f 72 20 61 6e 0a 2a 2a 20 5b 65  cess or an.** [e
2da90 72 72 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 6e  rror code] if an
2daa0 79 74 68 69 6e 67 20 67 6f 65 73 20 77 72 6f 6e  ything goes wron
2dab0 67 2e 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 54  g..** ^[SQLITE_T
2dac0 4f 4f 42 49 47 5d 20 6d 69 67 68 74 20 62 65 20  OOBIG] might be 
2dad0 72 65 74 75 72 6e 65 64 20 69 66 20 74 68 65 20  returned if the 
2dae0 73 69 7a 65 20 6f 66 20 61 20 73 74 72 69 6e 67  size of a string
2daf0 20 6f 72 20 42 4c 4f 42 0a 2a 2a 20 65 78 63 65   or BLOB.** exce
2db00 65 64 73 20 6c 69 6d 69 74 73 20 69 6d 70 6f 73  eds limits impos
2db10 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c  ed by [sqlite3_l
2db20 69 6d 69 74 5d 28 5b 53 51 4c 49 54 45 5f 4c 49  imit]([SQLITE_LI
2db30 4d 49 54 5f 4c 45 4e 47 54 48 5d 29 20 6f 72 0a  MIT_LENGTH]) or.
2db40 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 41 58 5f 4c  ** [SQLITE_MAX_L
2db50 45 4e 47 54 48 5d 2e 0a 2a 2a 20 5e 5b 53 51 4c  ENGTH]..** ^[SQL
2db60 49 54 45 5f 52 41 4e 47 45 5d 20 69 73 20 72 65  ITE_RANGE] is re
2db70 74 75 72 6e 65 64 20 69 66 20 74 68 65 20 70 61  turned if the pa
2db80 72 61 6d 65 74 65 72 0a 2a 2a 20 69 6e 64 65 78  rameter.** index
2db90 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65   is out of range
2dba0 2e 20 20 5e 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45  .  ^[SQLITE_NOME
2dbb0 4d 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 69  M] is returned i
2dbc0 66 20 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 73  f malloc() fails
2dbd0 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
2dbe0 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  : [sqlite3_bind_
2dbf0 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28  parameter_count(
2dc00 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  )],.** [sqlite3_
2dc10 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e  bind_parameter_n
2dc20 61 6d 65 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c  ame()], and [sql
2dc30 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
2dc40 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f  ter_index()]..*/
2dc50 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e  .int sqlite3_bin
2dc60 64 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73  d_blob(sqlite3_s
2dc70 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74  tmt*, int, const
2dc80 20 76 6f 69 64 2a 2c 20 69 6e 74 20 6e 2c 20 76   void*, int n, v
2dc90 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a  oid(*)(void*));.
2dca0 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
2dcb0 5f 62 6c 6f 62 36 34 28 73 71 6c 69 74 65 33 5f  _blob64(sqlite3_
2dcc0 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73  stmt*, int, cons
2dcd0 74 20 76 6f 69 64 2a 2c 20 73 71 6c 69 74 65 33  t void*, sqlite3
2dce0 5f 75 69 6e 74 36 34 2c 0a 20 20 20 20 20 20 20  _uint64,.       
2dcf0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2dd00 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29   void(*)(void*))
2dd10 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  ;.int sqlite3_bi
2dd20 6e 64 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65  nd_double(sqlite
2dd30 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 64 6f  3_stmt*, int, do
2dd40 75 62 6c 65 29 3b 0a 69 6e 74 20 73 71 6c 69 74  uble);.int sqlit
2dd50 65 33 5f 62 69 6e 64 5f 69 6e 74 28 73 71 6c 69  e3_bind_int(sqli
2dd60 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20  te3_stmt*, int, 
2dd70 69 6e 74 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  int);.int sqlite
2dd80 33 5f 62 69 6e 64 5f 69 6e 74 36 34 28 73 71 6c  3_bind_int64(sql
2dd90 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c  ite3_stmt*, int,
2dda0 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b   sqlite3_int64);
2ddb0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e  .int sqlite3_bin
2ddc0 64 5f 6e 75 6c 6c 28 73 71 6c 69 74 65 33 5f 73  d_null(sqlite3_s
2ddd0 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a 69 6e 74 20  tmt*, int);.int 
2dde0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
2ddf0 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  t(sqlite3_stmt*,
2de00 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c  int,const char*,
2de10 69 6e 74 2c 76 6f 69 64 28 2a 29 28 76 6f 69 64  int,void(*)(void
2de20 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  *));.int sqlite3
2de30 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 73 71 6c  _bind_text16(sql
2de40 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c  ite3_stmt*, int,
2de50 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e   const void*, in
2de60 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a  t, void(*)(void*
2de70 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  ));.int sqlite3_
2de80 62 69 6e 64 5f 74 65 78 74 36 34 28 73 71 6c 69  bind_text64(sqli
2de90 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20  te3_stmt*, int, 
2dea0 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 73 71 6c  const char*, sql
2deb0 69 74 65 33 5f 75 69 6e 74 36 34 2c 0a 20 20 20  ite3_uint64,.   
2dec0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2ded0 20 20 20 20 20 20 76 6f 69 64 28 2a 29 28 76 6f        void(*)(vo
2dee0 69 64 2a 29 2c 20 75 6e 73 69 67 6e 65 64 20 63  id*), unsigned c
2def0 68 61 72 20 65 6e 63 6f 64 69 6e 67 29 3b 0a 69  har encoding);.i
2df00 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
2df10 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f 73 74  value(sqlite3_st
2df20 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20  mt*, int, const 
2df30 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
2df40 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e  .int sqlite3_bin
2df50 64 5f 7a 65 72 6f 62 6c 6f 62 28 73 71 6c 69 74  d_zeroblob(sqlit
2df60 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 69  e3_stmt*, int, i
2df70 6e 74 20 6e 29 3b 0a 69 6e 74 20 73 71 6c 69 74  nt n);.int sqlit
2df80 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62  e3_bind_zeroblob
2df90 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  64(sqlite3_stmt*
2dfa0 2c 20 69 6e 74 2c 20 73 71 6c 69 74 65 33 5f 75  , int, sqlite3_u
2dfb0 69 6e 74 36 34 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  int64);../*.** C
2dfc0 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20  API3REF: Number 
2dfd0 4f 66 20 53 51 4c 20 50 61 72 61 6d 65 74 65 72  Of SQL Parameter
2dfe0 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  s.** METHOD: sql
2dff0 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20  ite3_stmt.**.** 
2e000 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20 63 61  ^This routine ca
2e010 6e 20 62 65 20 75 73 65 64 20 74 6f 20 66 69 6e  n be used to fin
2e020 64 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  d the number of 
2e030 5b 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 5d  [SQL parameters]
2e040 0a 2a 2a 20 69 6e 20 61 20 5b 70 72 65 70 61 72  .** in a [prepar
2e050 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20  ed statement].  
2e060 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 20 61  SQL parameters a
2e070 72 65 20 74 6f 6b 65 6e 73 20 6f 66 20 74 68 65  re tokens of the
2e080 0a 2a 2a 20 66 6f 72 6d 20 22 3f 22 2c 20 22 3f  .** form "?", "?
2e090 4e 4e 4e 22 2c 20 22 3a 41 41 41 22 2c 20 22 24  NNN", ":AAA", "$
2e0a0 41 41 41 22 2c 20 6f 72 20 22 40 41 41 41 22 20  AAA", or "@AAA" 
2e0b0 74 68 61 74 20 73 65 72 76 65 20 61 73 0a 2a 2a  that serve as.**
2e0c0 20 70 6c 61 63 65 68 6f 6c 64 65 72 73 20 66 6f   placeholders fo
2e0d0 72 20 76 61 6c 75 65 73 20 74 68 61 74 20 61 72  r values that ar
2e0e0 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  e [sqlite3_bind_
2e0f0 62 6c 6f 62 20 7c 20 62 6f 75 6e 64 5d 0a 2a 2a  blob | bound].**
2e100 20 74 6f 20 74 68 65 20 70 61 72 61 6d 65 74 65   to the paramete
2e110 72 73 20 61 74 20 61 20 6c 61 74 65 72 20 74 69  rs at a later ti
2e120 6d 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73  me..**.** ^(This
2e130 20 72 6f 75 74 69 6e 65 20 61 63 74 75 61 6c 6c   routine actuall
2e140 79 20 72 65 74 75 72 6e 73 20 74 68 65 20 69 6e  y returns the in
2e150 64 65 78 20 6f 66 20 74 68 65 20 6c 61 72 67 65  dex of the large
2e160 73 74 20 28 72 69 67 68 74 6d 6f 73 74 29 0a 2a  st (rightmost).*
2e170 2a 20 70 61 72 61 6d 65 74 65 72 2e 20 46 6f 72  * parameter. For
2e180 20 61 6c 6c 20 66 6f 72 6d 73 20 65 78 63 65 70   all forms excep
2e190 74 20 3f 4e 4e 4e 2c 20 74 68 69 73 20 77 69 6c  t ?NNN, this wil
2e1a0 6c 20 63 6f 72 72 65 73 70 6f 6e 64 20 74 6f 20  l correspond to 
2e1b0 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66  the.** number of
2e1c0 20 75 6e 69 71 75 65 20 70 61 72 61 6d 65 74 65   unique paramete
2e1d0 72 73 2e 20 20 49 66 20 70 61 72 61 6d 65 74 65  rs.  If paramete
2e1e0 72 73 20 6f 66 20 74 68 65 20 3f 4e 4e 4e 20 66  rs of the ?NNN f
2e1f0 6f 72 6d 20 61 72 65 20 75 73 65 64 2c 0a 2a 2a  orm are used,.**
2e200 20 74 68 65 72 65 20 6d 61 79 20 62 65 20 67 61   there may be ga
2e210 70 73 20 69 6e 20 74 68 65 20 6c 69 73 74 2e 29  ps in the list.)
2e220 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ^.**.** See also
2e230 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  : [sqlite3_bind_
2e240 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e  blob|sqlite3_bin
2e250 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65  d()],.** [sqlite
2e260 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
2e270 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e 64 0a 2a 2a  _name()], and.**
2e280 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
2e290 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29  arameter_index()
2e2a0 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  ]..*/.int sqlite
2e2b0 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
2e2c0 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73  _count(sqlite3_s
2e2d0 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  tmt*);../*.** CA
2e2e0 50 49 33 52 45 46 3a 20 4e 61 6d 65 20 4f 66 20  PI3REF: Name Of 
2e2f0 41 20 48 6f 73 74 20 50 61 72 61 6d 65 74 65 72  A Host Parameter
2e300 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
2e310 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e  te3_stmt.**.** ^
2e320 54 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  The sqlite3_bind
2e330 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28  _parameter_name(
2e340 50 2c 4e 29 20 69 6e 74 65 72 66 61 63 65 20 72  P,N) interface r
2e350 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 61  eturns.** the na
2e360 6d 65 20 6f 66 20 74 68 65 20 4e 2d 74 68 20 5b  me of the N-th [
2e370 53 51 4c 20 70 61 72 61 6d 65 74 65 72 5d 20 69  SQL parameter] i
2e380 6e 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20  n the [prepared 
2e390 73 74 61 74 65 6d 65 6e 74 5d 20 50 2e 0a 2a 2a  statement] P..**
2e3a0 20 5e 28 53 51 4c 20 70 61 72 61 6d 65 74 65 72   ^(SQL parameter
2e3b0 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 3f  s of the form "?
2e3c0 4e 4e 4e 22 20 6f 72 20 22 3a 41 41 41 22 20 6f  NNN" or ":AAA" o
2e3d0 72 20 22 40 41 41 41 22 20 6f 72 20 22 24 41 41  r "@AAA" or "$AA
2e3e0 41 22 0a 2a 2a 20 68 61 76 65 20 61 20 6e 61 6d  A".** have a nam
2e3f0 65 20 77 68 69 63 68 20 69 73 20 74 68 65 20 73  e which is the s
2e400 74 72 69 6e 67 20 22 3f 4e 4e 4e 22 20 6f 72 20  tring "?NNN" or 
2e410 22 3a 41 41 41 22 20 6f 72 20 22 40 41 41 41 22  ":AAA" or "@AAA"
2e420 20 6f 72 20 22 24 41 41 41 22 0a 2a 2a 20 72 65   or "$AAA".** re
2e430 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 49  spectively..** I
2e440 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74  n other words, t
2e450 68 65 20 69 6e 69 74 69 61 6c 20 22 3a 22 20 6f  he initial ":" o
2e460 72 20 22 24 22 20 6f 72 20 22 40 22 20 6f 72 20  r "$" or "@" or 
2e470 22 3f 22 0a 2a 2a 20 69 73 20 69 6e 63 6c 75 64  "?".** is includ
2e480 65 64 20 61 73 20 70 61 72 74 20 6f 66 20 74 68  ed as part of th
2e490 65 20 6e 61 6d 65 2e 29 5e 0a 2a 2a 20 5e 50 61  e name.)^.** ^Pa
2e4a0 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20  rameters of the 
2e4b0 66 6f 72 6d 20 22 3f 22 20 77 69 74 68 6f 75 74  form "?" without
2e4c0 20 61 20 66 6f 6c 6c 6f 77 69 6e 67 20 69 6e 74   a following int
2e4d0 65 67 65 72 20 68 61 76 65 20 6e 6f 20 6e 61 6d  eger have no nam
2e4e0 65 0a 2a 2a 20 61 6e 64 20 61 72 65 20 72 65 66  e.** and are ref
2e4f0 65 72 72 65 64 20 74 6f 20 61 73 20 22 6e 61 6d  erred to as "nam
2e500 65 6c 65 73 73 22 20 6f 72 20 22 61 6e 6f 6e 79  eless" or "anony
2e510 6d 6f 75 73 20 70 61 72 61 6d 65 74 65 72 73 22  mous parameters"
2e520 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72  ..**.** ^The fir
2e530 73 74 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65  st host paramete
2e540 72 20 68 61 73 20 61 6e 20 69 6e 64 65 78 20 6f  r has an index o
2e550 66 20 31 2c 20 6e 6f 74 20 30 2e 0a 2a 2a 0a 2a  f 1, not 0..**.*
2e560 2a 20 5e 49 66 20 74 68 65 20 76 61 6c 75 65 20  * ^If the value 
2e570 4e 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67  N is out of rang
2e580 65 20 6f 72 20 69 66 20 74 68 65 20 4e 2d 74 68  e or if the N-th
2e590 20 70 61 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a   parameter is.**
2e5a0 20 6e 61 6d 65 6c 65 73 73 2c 20 74 68 65 6e 20   nameless, then 
2e5b0 4e 55 4c 4c 20 69 73 20 72 65 74 75 72 6e 65 64  NULL is returned
2e5c0 2e 20 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64  .  ^The returned
2e5d0 20 73 74 72 69 6e 67 20 69 73 0a 2a 2a 20 61 6c   string is.** al
2e5e0 77 61 79 73 20 69 6e 20 55 54 46 2d 38 20 65 6e  ways in UTF-8 en
2e5f0 63 6f 64 69 6e 67 20 65 76 65 6e 20 69 66 20 74  coding even if t
2e600 68 65 20 6e 61 6d 65 64 20 70 61 72 61 6d 65 74  he named paramet
2e610 65 72 20 77 61 73 0a 2a 2a 20 6f 72 69 67 69 6e  er was.** origin
2e620 61 6c 6c 79 20 73 70 65 63 69 66 69 65 64 20 61  ally specified a
2e630 73 20 55 54 46 2d 31 36 20 69 6e 20 5b 73 71 6c  s UTF-16 in [sql
2e640 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29  ite3_prepare16()
2e650 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ] or.** [sqlite3
2e660 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d  _prepare16_v2()]
2e670 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
2e680 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  : [sqlite3_bind_
2e690 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e  blob|sqlite3_bin
2e6a0 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65  d()],.** [sqlite
2e6b0 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
2e6c0 5f 63 6f 75 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a  _count()], and.*
2e6d0 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  * [sqlite3_bind_
2e6e0 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28  parameter_index(
2e6f0 29 5d 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61  )]..*/.const cha
2e700 72 20 2a 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  r *sqlite3_bind_
2e710 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 73  parameter_name(s
2e720 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
2e730 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
2e740 52 45 46 3a 20 49 6e 64 65 78 20 4f 66 20 41 20  REF: Index Of A 
2e750 50 61 72 61 6d 65 74 65 72 20 57 69 74 68 20 41  Parameter With A
2e760 20 47 69 76 65 6e 20 4e 61 6d 65 0a 2a 2a 20 4d   Given Name.** M
2e770 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73  ETHOD: sqlite3_s
2e780 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 52 65 74 75 72  tmt.**.** ^Retur
2e790 6e 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 61  n the index of a
2e7a0 6e 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20  n SQL parameter 
2e7b0 67 69 76 65 6e 20 69 74 73 20 6e 61 6d 65 2e 20  given its name. 
2e7c0 20 5e 54 68 65 0a 2a 2a 20 69 6e 64 65 78 20 76   ^The.** index v
2e7d0 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 69 73  alue returned is
2e7e0 20 73 75 69 74 61 62 6c 65 20 66 6f 72 20 75 73   suitable for us
2e7f0 65 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 0a  e as the second.
2e800 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  ** parameter to 
2e810 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c  [sqlite3_bind_bl
2e820 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28  ob|sqlite3_bind(
2e830 29 5d 2e 20 20 5e 41 20 7a 65 72 6f 0a 2a 2a 20  )].  ^A zero.** 
2e840 69 73 20 72 65 74 75 72 6e 65 64 20 69 66 20 6e  is returned if n
2e850 6f 20 6d 61 74 63 68 69 6e 67 20 70 61 72 61 6d  o matching param
2e860 65 74 65 72 20 69 73 20 66 6f 75 6e 64 2e 20 20  eter is found.  
2e870 5e 54 68 65 20 70 61 72 61 6d 65 74 65 72 0a 2a  ^The parameter.*
2e880 2a 20 6e 61 6d 65 20 6d 75 73 74 20 62 65 20 67  * name must be g
2e890 69 76 65 6e 20 69 6e 20 55 54 46 2d 38 20 65 76  iven in UTF-8 ev
2e8a0 65 6e 20 69 66 20 74 68 65 20 6f 72 69 67 69 6e  en if the origin
2e8b0 61 6c 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20  al statement.** 
2e8c0 77 61 73 20 70 72 65 70 61 72 65 64 20 66 72 6f  was prepared fro
2e8d0 6d 20 55 54 46 2d 31 36 20 74 65 78 74 20 75 73  m UTF-16 text us
2e8e0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  ing [sqlite3_pre
2e8f0 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a  pare16_v2()]..**
2e900 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73  .** See also: [s
2e910 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
2e920 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d  |sqlite3_bind()]
2e930 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69  ,.** [sqlite3_bi
2e940 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75  nd_parameter_cou
2e950 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73  nt()], and.** [s
2e960 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
2e970 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d 2e 0a 2a  meter_name()]..*
2e980 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  /.int sqlite3_bi
2e990 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64  nd_parameter_ind
2e9a0 65 78 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  ex(sqlite3_stmt*
2e9b0 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e  , const char *zN
2e9c0 61 6d 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ame);../*.** CAP
2e9d0 49 33 52 45 46 3a 20 52 65 73 65 74 20 41 6c 6c  I3REF: Reset All
2e9e0 20 42 69 6e 64 69 6e 67 73 20 4f 6e 20 41 20 50   Bindings On A P
2e9f0 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e  repared Statemen
2ea00 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  t.** METHOD: sql
2ea10 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20  ite3_stmt.**.** 
2ea20 5e 43 6f 6e 74 72 61 72 79 20 74 6f 20 74 68 65  ^Contrary to the
2ea30 20 69 6e 74 75 69 74 69 6f 6e 20 6f 66 20 6d 61   intuition of ma
2ea40 6e 79 2c 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  ny, [sqlite3_res
2ea50 65 74 28 29 5d 20 64 6f 65 73 20 6e 6f 74 20 72  et()] does not r
2ea60 65 73 65 74 0a 2a 2a 20 74 68 65 20 5b 73 71 6c  eset.** the [sql
2ea70 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c  ite3_bind_blob |
2ea80 20 62 69 6e 64 69 6e 67 73 5d 20 6f 6e 20 61 20   bindings] on a 
2ea90 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2eaa0 65 6e 74 5d 2e 0a 2a 2a 20 5e 55 73 65 20 74 68  ent]..** ^Use th
2eab0 69 73 20 72 6f 75 74 69 6e 65 20 74 6f 20 72 65  is routine to re
2eac0 73 65 74 20 61 6c 6c 20 68 6f 73 74 20 70 61 72  set all host par
2ead0 61 6d 65 74 65 72 73 20 74 6f 20 4e 55 4c 4c 2e  ameters to NULL.
2eae0 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
2eaf0 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73 28 73  clear_bindings(s
2eb00 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a  qlite3_stmt*);..
2eb10 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
2eb20 4e 75 6d 62 65 72 20 4f 66 20 43 6f 6c 75 6d 6e  Number Of Column
2eb30 73 20 49 6e 20 41 20 52 65 73 75 6c 74 20 53 65  s In A Result Se
2eb40 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  t.** METHOD: sql
2eb50 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20  ite3_stmt.**.** 
2eb60 5e 52 65 74 75 72 6e 20 74 68 65 20 6e 75 6d 62  ^Return the numb
2eb70 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e  er of columns in
2eb80 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20   the result set 
2eb90 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 0a  returned by the.
2eba0 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  ** [prepared sta
2ebb0 74 65 6d 65 6e 74 5d 2e 20 5e 54 68 69 73 20 72  tement]. ^This r
2ebc0 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 30  outine returns 0
2ebd0 20 69 66 20 70 53 74 6d 74 20 69 73 20 61 6e 20   if pStmt is an 
2ebe0 53 51 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74  SQL.** statement
2ebf0 20 74 68 61 74 20 64 6f 65 73 20 6e 6f 74 20 72   that does not r
2ec00 65 74 75 72 6e 20 64 61 74 61 20 28 66 6f 72 20  eturn data (for 
2ec10 65 78 61 6d 70 6c 65 20 61 6e 20 5b 55 50 44 41  example an [UPDA
2ec20 54 45 5d 29 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  TE])..**.** See 
2ec30 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 64  also: [sqlite3_d
2ec40 61 74 61 5f 63 6f 75 6e 74 28 29 5d 0a 2a 2f 0a  ata_count()].*/.
2ec50 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  int sqlite3_colu
2ec60 6d 6e 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33  mn_count(sqlite3
2ec70 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a  _stmt *pStmt);..
2ec80 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
2ec90 43 6f 6c 75 6d 6e 20 4e 61 6d 65 73 20 49 6e 20  Column Names In 
2eca0 41 20 52 65 73 75 6c 74 20 53 65 74 0a 2a 2a 20  A Result Set.** 
2ecb0 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f  METHOD: sqlite3_
2ecc0 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73  stmt.**.** ^Thes
2ecd0 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  e routines retur
2ece0 6e 20 74 68 65 20 6e 61 6d 65 20 61 73 73 69 67  n the name assig
2ecf0 6e 65 64 20 74 6f 20 61 20 70 61 72 74 69 63 75  ned to a particu
2ed00 6c 61 72 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 6e  lar column.** in
2ed10 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20   the result set 
2ed20 6f 66 20 61 20 5b 53 45 4c 45 43 54 5d 20 73 74  of a [SELECT] st
2ed30 61 74 65 6d 65 6e 74 2e 20 20 5e 54 68 65 20 73  atement.  ^The s
2ed40 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61  qlite3_column_na
2ed50 6d 65 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63  me().** interfac
2ed60 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  e returns a poin
2ed70 74 65 72 20 74 6f 20 61 20 7a 65 72 6f 2d 74 65  ter to a zero-te
2ed80 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73  rminated UTF-8 s
2ed90 74 72 69 6e 67 0a 2a 2a 20 61 6e 64 20 73 71 6c  tring.** and sql
2eda0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65  ite3_column_name
2edb0 31 36 28 29 20 72 65 74 75 72 6e 73 20 61 20 70  16() returns a p
2edc0 6f 69 6e 74 65 72 20 74 6f 20 61 20 7a 65 72 6f  ointer to a zero
2edd0 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55  -terminated.** U
2ede0 54 46 2d 31 36 20 73 74 72 69 6e 67 2e 20 20 5e  TF-16 string.  ^
2edf0 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  The first parame
2ee00 74 65 72 20 69 73 20 74 68 65 20 5b 70 72 65 70  ter is the [prep
2ee10 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a  ared statement].
2ee20 2a 2a 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e  ** that implemen
2ee30 74 73 20 74 68 65 20 5b 53 45 4c 45 43 54 5d 20  ts the [SELECT] 
2ee40 73 74 61 74 65 6d 65 6e 74 2e 20 5e 54 68 65 20  statement. ^The 
2ee50 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
2ee60 20 69 73 20 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d   is the.** colum
2ee70 6e 20 6e 75 6d 62 65 72 2e 20 20 5e 54 68 65 20  n number.  ^The 
2ee80 6c 65 66 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20  leftmost column 
2ee90 69 73 20 6e 75 6d 62 65 72 20 30 2e 0a 2a 2a 0a  is number 0..**.
2eea0 2a 2a 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64  ** ^The returned
2eeb0 20 73 74 72 69 6e 67 20 70 6f 69 6e 74 65 72 20   string pointer 
2eec0 69 73 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 65  is valid until e
2eed0 69 74 68 65 72 20 74 68 65 20 5b 70 72 65 70 61  ither the [prepa
2eee0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a  red statement].*
2eef0 2a 20 69 73 20 64 65 73 74 72 6f 79 65 64 20 62  * is destroyed b
2ef00 79 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  y [sqlite3_final
2ef10 69 7a 65 28 29 5d 20 6f 72 20 75 6e 74 69 6c 20  ize()] or until 
2ef20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73  the statement is
2ef30 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a   automatically.*
2ef40 2a 20 72 65 70 72 65 70 61 72 65 64 20 62 79 20  * reprepared by 
2ef50 74 68 65 20 66 69 72 73 74 20 63 61 6c 6c 20 74  the first call t
2ef60 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  o [sqlite3_step(
2ef70 29 5d 20 66 6f 72 20 61 20 70 61 72 74 69 63 75  )] for a particu
2ef80 6c 61 72 20 72 75 6e 0a 2a 2a 20 6f 72 20 75 6e  lar run.** or un
2ef90 74 69 6c 20 74 68 65 20 6e 65 78 74 20 63 61 6c  til the next cal
2efa0 6c 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  l to.** sqlite3_
2efb0 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 20 6f 72  column_name() or
2efc0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2efd0 6e 61 6d 65 31 36 28 29 20 6f 6e 20 74 68 65 20  name16() on the 
2efe0 73 61 6d 65 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a  same column..**.
2eff0 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6d  ** ^If sqlite3_m
2f000 61 6c 6c 6f 63 28 29 20 66 61 69 6c 73 20 64 75  alloc() fails du
2f010 72 69 6e 67 20 74 68 65 20 70 72 6f 63 65 73 73  ring the process
2f020 69 6e 67 20 6f 66 20 65 69 74 68 65 72 20 72 6f  ing of either ro
2f030 75 74 69 6e 65 0a 2a 2a 20 28 66 6f 72 20 65 78  utine.** (for ex
2f040 61 6d 70 6c 65 20 64 75 72 69 6e 67 20 61 20 63  ample during a c
2f050 6f 6e 76 65 72 73 69 6f 6e 20 66 72 6f 6d 20 55  onversion from U
2f060 54 46 2d 38 20 74 6f 20 55 54 46 2d 31 36 29 20  TF-8 to UTF-16) 
2f070 74 68 65 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70  then a.** NULL p
2f080 6f 69 6e 74 65 72 20 69 73 20 72 65 74 75 72 6e  ointer is return
2f090 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e  ed..**.** ^The n
2f0a0 61 6d 65 20 6f 66 20 61 20 72 65 73 75 6c 74 20  ame of a result 
2f0b0 63 6f 6c 75 6d 6e 20 69 73 20 74 68 65 20 76 61  column is the va
2f0c0 6c 75 65 20 6f 66 20 74 68 65 20 22 41 53 22 20  lue of the "AS" 
2f0d0 63 6c 61 75 73 65 20 66 6f 72 0a 2a 2a 20 74 68  clause for.** th
2f0e0 61 74 20 63 6f 6c 75 6d 6e 2c 20 69 66 20 74 68  at column, if th
2f0f0 65 72 65 20 69 73 20 61 6e 20 41 53 20 63 6c 61  ere is an AS cla
2f100 75 73 65 2e 20 20 49 66 20 74 68 65 72 65 20 69  use.  If there i
2f110 73 20 6e 6f 20 41 53 20 63 6c 61 75 73 65 0a 2a  s no AS clause.*
2f120 2a 20 74 68 65 6e 20 74 68 65 20 6e 61 6d 65 20  * then the name 
2f130 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20 69 73  of the column is
2f140 20 75 6e 73 70 65 63 69 66 69 65 64 20 61 6e 64   unspecified and
2f150 20 6d 61 79 20 63 68 61 6e 67 65 20 66 72 6f 6d   may change from
2f160 0a 2a 2a 20 6f 6e 65 20 72 65 6c 65 61 73 65 20  .** one release 
2f170 6f 66 20 53 51 4c 69 74 65 20 74 6f 20 74 68 65  of SQLite to the
2f180 20 6e 65 78 74 2e 0a 2a 2f 0a 63 6f 6e 73 74 20   next..*/.const 
2f190 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f  char *sqlite3_co
2f1a0 6c 75 6d 6e 5f 6e 61 6d 65 28 73 71 6c 69 74 65  lumn_name(sqlite
2f1b0 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b  3_stmt*, int N);
2f1c0 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  .const void *sql
2f1d0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65  ite3_column_name
2f1e0 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  16(sqlite3_stmt*
2f1f0 2c 20 69 6e 74 20 4e 29 3b 0a 0a 2f 2a 0a 2a 2a  , int N);../*.**
2f200 20 43 41 50 49 33 52 45 46 3a 20 53 6f 75 72 63   CAPI3REF: Sourc
2f210 65 20 4f 66 20 44 61 74 61 20 49 6e 20 41 20 51  e Of Data In A Q
2f220 75 65 72 79 20 52 65 73 75 6c 74 0a 2a 2a 20 4d  uery Result.** M
2f230 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73  ETHOD: sqlite3_s
2f240 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65  tmt.**.** ^These
2f250 20 72 6f 75 74 69 6e 65 73 20 70 72 6f 76 69 64   routines provid
2f260 65 20 61 20 6d 65 61 6e 73 20 74 6f 20 64 65 74  e a means to det
2f270 65 72 6d 69 6e 65 20 74 68 65 20 64 61 74 61 62  ermine the datab
2f280 61 73 65 2c 20 74 61 62 6c 65 2c 20 61 6e 64 0a  ase, table, and.
2f290 2a 2a 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20  ** table column 
2f2a0 74 68 61 74 20 69 73 20 74 68 65 20 6f 72 69 67  that is the orig
2f2b0 69 6e 20 6f 66 20 61 20 70 61 72 74 69 63 75 6c  in of a particul
2f2c0 61 72 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e  ar result column
2f2d0 20 69 6e 0a 2a 2a 20 5b 53 45 4c 45 43 54 5d 20   in.** [SELECT] 
2f2e0 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 5e 54  statement..** ^T
2f2f0 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64  he name of the d
2f300 61 74 61 62 61 73 65 20 6f 72 20 74 61 62 6c 65  atabase or table
2f310 20 6f 72 20 63 6f 6c 75 6d 6e 20 63 61 6e 20 62   or column can b
2f320 65 20 72 65 74 75 72 6e 65 64 20 61 73 0a 2a 2a  e returned as.**
2f330 20 65 69 74 68 65 72 20 61 20 55 54 46 2d 38 20   either a UTF-8 
2f340 6f 72 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67  or UTF-16 string
2f350 2e 20 20 5e 54 68 65 20 5f 64 61 74 61 62 61 73  .  ^The _databas
2f360 65 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  e_ routines retu
2f370 72 6e 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61  rn.** the databa
2f380 73 65 20 6e 61 6d 65 2c 20 74 68 65 20 5f 74 61  se name, the _ta
2f390 62 6c 65 5f 20 72 6f 75 74 69 6e 65 73 20 72 65  ble_ routines re
2f3a0 74 75 72 6e 20 74 68 65 20 74 61 62 6c 65 20 6e  turn the table n
2f3b0 61 6d 65 2c 20 61 6e 64 0a 2a 2a 20 74 68 65 20  ame, and.** the 
2f3c0 6f 72 69 67 69 6e 5f 20 72 6f 75 74 69 6e 65 73  origin_ routines
2f3d0 20 72 65 74 75 72 6e 20 74 68 65 20 63 6f 6c 75   return the colu
2f3e0 6d 6e 20 6e 61 6d 65 2e 0a 2a 2a 20 5e 54 68 65  mn name..** ^The
2f3f0 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67   returned string
2f400 20 69 73 20 76 61 6c 69 64 20 75 6e 74 69 6c 20   is valid until 
2f410 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
2f420 61 74 65 6d 65 6e 74 5d 20 69 73 20 64 65 73 74  atement] is dest
2f430 72 6f 79 65 64 0a 2a 2a 20 75 73 69 6e 67 20 5b  royed.** using [
2f440 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
2f450 28 29 5d 20 6f 72 20 75 6e 74 69 6c 20 74 68 65  ()] or until the
2f460 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 75   statement is au
2f470 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 72  tomatically.** r
2f480 65 70 72 65 70 61 72 65 64 20 62 79 20 74 68 65  eprepared by the
2f490 20 66 69 72 73 74 20 63 61 6c 6c 20 74 6f 20 5b   first call to [
2f4a0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
2f4b0 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61 72  for a particular
2f4c0 20 72 75 6e 0a 2a 2a 20 6f 72 20 75 6e 74 69 6c   run.** or until
2f4d0 20 74 68 65 20 73 61 6d 65 20 69 6e 66 6f 72 6d   the same inform
2f4e0 61 74 69 6f 6e 20 69 73 20 72 65 71 75 65 73 74  ation is request
2f4f0 65 64 0a 2a 2a 20 61 67 61 69 6e 20 69 6e 20 61  ed.** again in a
2f500 20 64 69 66 66 65 72 65 6e 74 20 65 6e 63 6f 64   different encod
2f510 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ing..**.** ^The 
2f520 6e 61 6d 65 73 20 72 65 74 75 72 6e 65 64 20 61  names returned a
2f530 72 65 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20  re the original 
2f540 75 6e 2d 61 6c 69 61 73 65 64 20 6e 61 6d 65 73  un-aliased names
2f550 20 6f 66 20 74 68 65 0a 2a 2a 20 64 61 74 61 62   of the.** datab
2f560 61 73 65 2c 20 74 61 62 6c 65 2c 20 61 6e 64 20  ase, table, and 
2f570 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54  column..**.** ^T
2f580 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
2f590 74 20 74 6f 20 74 68 65 73 65 20 69 6e 74 65 72  t to these inter
2f5a0 66 61 63 65 73 20 69 73 20 61 20 5b 70 72 65 70  faces is a [prep
2f5b0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e  ared statement].
2f5c0 0a 2a 2a 20 5e 54 68 65 73 65 20 66 75 6e 63 74  .** ^These funct
2f5d0 69 6f 6e 73 20 72 65 74 75 72 6e 20 69 6e 66 6f  ions return info
2f5e0 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 74 68  rmation about th
2f5f0 65 20 4e 74 68 20 72 65 73 75 6c 74 20 63 6f 6c  e Nth result col
2f600 75 6d 6e 20 72 65 74 75 72 6e 65 64 20 62 79 0a  umn returned by.
2f610 2a 2a 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  ** the statement
2f620 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65  , where N is the
2f630 20 73 65 63 6f 6e 64 20 66 75 6e 63 74 69 6f 6e   second function
2f640 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54   argument..** ^T
2f650 68 65 20 6c 65 66 74 2d 6d 6f 73 74 20 63 6f 6c  he left-most col
2f660 75 6d 6e 20 69 73 20 63 6f 6c 75 6d 6e 20 30 20  umn is column 0 
2f670 66 6f 72 20 74 68 65 73 65 20 72 6f 75 74 69 6e  for these routin
2f680 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  es..**.** ^If th
2f690 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 72 65 74  e Nth column ret
2f6a0 75 72 6e 65 64 20 62 79 20 74 68 65 20 73 74 61  urned by the sta
2f6b0 74 65 6d 65 6e 74 20 69 73 20 61 6e 20 65 78 70  tement is an exp
2f6c0 72 65 73 73 69 6f 6e 20 6f 72 0a 2a 2a 20 73 75  ression or.** su
2f6d0 62 71 75 65 72 79 20 61 6e 64 20 69 73 20 6e 6f  bquery and is no
2f6e0 74 20 61 20 63 6f 6c 75 6d 6e 20 76 61 6c 75 65  t a column value
2f6f0 2c 20 74 68 65 6e 20 61 6c 6c 20 6f 66 20 74 68  , then all of th
2f700 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 72 65  ese functions re
2f710 74 75 72 6e 0a 2a 2a 20 4e 55 4c 4c 2e 20 20 5e  turn.** NULL.  ^
2f720 54 68 65 73 65 20 72 6f 75 74 69 6e 65 20 6d 69  These routine mi
2f730 67 68 74 20 61 6c 73 6f 20 72 65 74 75 72 6e 20  ght also return 
2f740 4e 55 4c 4c 20 69 66 20 61 20 6d 65 6d 6f 72 79  NULL if a memory
2f750 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f   allocation erro
2f760 72 0a 2a 2a 20 6f 63 63 75 72 73 2e 20 20 5e 4f  r.** occurs.  ^O
2f770 74 68 65 72 77 69 73 65 2c 20 74 68 65 79 20 72  therwise, they r
2f780 65 74 75 72 6e 20 74 68 65 20 6e 61 6d 65 20 6f  eturn the name o
2f790 66 20 74 68 65 20 61 74 74 61 63 68 65 64 20 64  f the attached d
2f7a0 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65 2c 0a  atabase, table,.
2f7b0 2a 2a 20 6f 72 20 63 6f 6c 75 6d 6e 20 74 68 61  ** or column tha
2f7c0 74 20 71 75 65 72 79 20 72 65 73 75 6c 74 20 63  t query result c
2f7d0 6f 6c 75 6d 6e 20 77 61 73 20 65 78 74 72 61 63  olumn was extrac
2f7e0 74 65 64 20 66 72 6f 6d 2e 0a 2a 2a 0a 2a 2a 20  ted from..**.** 
2f7f0 5e 41 73 20 77 69 74 68 20 61 6c 6c 20 6f 74 68  ^As with all oth
2f800 65 72 20 53 51 4c 69 74 65 20 41 50 49 73 2c 20  er SQLite APIs, 
2f810 74 68 6f 73 65 20 77 68 6f 73 65 20 6e 61 6d 65  those whose name
2f820 73 20 65 6e 64 20 77 69 74 68 20 22 31 36 22 20  s end with "16" 
2f830 72 65 74 75 72 6e 0a 2a 2a 20 55 54 46 2d 31 36  return.** UTF-16
2f840 20 65 6e 63 6f 64 65 64 20 73 74 72 69 6e 67 73   encoded strings
2f850 20 61 6e 64 20 74 68 65 20 6f 74 68 65 72 20 66   and the other f
2f860 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20  unctions return 
2f870 55 54 46 2d 38 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  UTF-8..**.** ^Th
2f880 65 73 65 20 41 50 49 73 20 61 72 65 20 6f 6e 6c  ese APIs are onl
2f890 79 20 61 76 61 69 6c 61 62 6c 65 20 69 66 20 74  y available if t
2f8a0 68 65 20 6c 69 62 72 61 72 79 20 77 61 73 20 63  he library was c
2f8b0 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68 65  ompiled with the
2f8c0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42  .** [SQLITE_ENAB
2f8d0 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d 45 54 41 44 41  LE_COLUMN_METADA
2f8e0 54 41 5d 20 43 2d 70 72 65 70 72 6f 63 65 73 73  TA] C-preprocess
2f8f0 6f 72 20 73 79 6d 62 6f 6c 2e 0a 2a 2a 0a 2a 2a  or symbol..**.**
2f900 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20   If two or more 
2f910 74 68 72 65 61 64 73 20 63 61 6c 6c 20 6f 6e 65  threads call one
2f920 20 6f 72 20 6d 6f 72 65 20 6f 66 20 74 68 65 73   or more of thes
2f930 65 20 72 6f 75 74 69 6e 65 73 20 61 67 61 69 6e  e routines again
2f940 73 74 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 70  st the same.** p
2f950 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2f960 74 20 61 6e 64 20 63 6f 6c 75 6d 6e 20 61 74 20  t and column at 
2f970 74 68 65 20 73 61 6d 65 20 74 69 6d 65 20 74 68  the same time th
2f980 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20 61  en the results a
2f990 72 65 0a 2a 2a 20 75 6e 64 65 66 69 6e 65 64 2e  re.** undefined.
2f9a0 0a 2a 2a 0a 2a 2a 20 49 66 20 74 77 6f 20 6f 72  .**.** If two or
2f9b0 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20 63 61   more threads ca
2f9c0 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a  ll one or more.*
2f9d0 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  * [sqlite3_colum
2f9e0 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 20  n_database_name 
2f9f0 7c 20 63 6f 6c 75 6d 6e 20 6d 65 74 61 64 61 74  | column metadat
2fa00 61 20 69 6e 74 65 72 66 61 63 65 73 5d 0a 2a 2a  a interfaces].**
2fa10 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20 5b 70   for the same [p
2fa20 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2fa30 74 5d 20 61 6e 64 20 72 65 73 75 6c 74 20 63 6f  t] and result co
2fa40 6c 75 6d 6e 0a 2a 2a 20 61 74 20 74 68 65 20 73  lumn.** at the s
2fa50 61 6d 65 20 74 69 6d 65 20 74 68 65 6e 20 74 68  ame time then th
2fa60 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e  e results are un
2fa70 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 63 6f 6e 73  defined..*/.cons
2fa80 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
2fa90 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f  column_database_
2faa0 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  name(sqlite3_stm
2fab0 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76  t*,int);.const v
2fac0 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  oid *sqlite3_col
2fad0 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d  umn_database_nam
2fae0 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  e16(sqlite3_stmt
2faf0 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 63 68  *,int);.const ch
2fb00 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ar *sqlite3_colu
2fb10 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 28 73 71  mn_table_name(sq
2fb20 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29  lite3_stmt*,int)
2fb30 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  ;.const void *sq
2fb40 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62  lite3_column_tab
2fb50 6c 65 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65  le_name16(sqlite
2fb60 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f  3_stmt*,int);.co
2fb70 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65  nst char *sqlite
2fb80 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f  3_column_origin_
2fb90 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  name(sqlite3_stm
2fba0 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76  t*,int);.const v
2fbb0 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  oid *sqlite3_col
2fbc0 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 31  umn_origin_name1
2fbd0 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  6(sqlite3_stmt*,
2fbe0 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  int);../*.** CAP
2fbf0 49 33 52 45 46 3a 20 44 65 63 6c 61 72 65 64 20  I3REF: Declared 
2fc00 44 61 74 61 74 79 70 65 20 4f 66 20 41 20 51 75  Datatype Of A Qu
2fc10 65 72 79 20 52 65 73 75 6c 74 0a 2a 2a 20 4d 45  ery Result.** ME
2fc20 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74  THOD: sqlite3_st
2fc30 6d 74 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 66  mt.**.** ^(The f
2fc40 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69  irst parameter i
2fc50 73 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74  s a [prepared st
2fc60 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 49 66 20  atement]..** If 
2fc70 74 68 69 73 20 73 74 61 74 65 6d 65 6e 74 20 69  this statement i
2fc80 73 20 61 20 5b 53 45 4c 45 43 54 5d 20 73 74 61  s a [SELECT] sta
2fc90 74 65 6d 65 6e 74 20 61 6e 64 20 74 68 65 20 4e  tement and the N
2fca0 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65  th column of the
2fcb0 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 72 65 73  .** returned res
2fcc0 75 6c 74 20 73 65 74 20 6f 66 20 74 68 61 74 20  ult set of that 
2fcd0 5b 53 45 4c 45 43 54 5d 20 69 73 20 61 20 74 61  [SELECT] is a ta
2fce0 62 6c 65 20 63 6f 6c 75 6d 6e 20 28 6e 6f 74 20  ble column (not 
2fcf0 61 6e 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e  an.** expression
2fd00 20 6f 72 20 73 75 62 71 75 65 72 79 29 20 74 68   or subquery) th
2fd10 65 6e 20 74 68 65 20 64 65 63 6c 61 72 65 64 20  en the declared 
2fd20 74 79 70 65 20 6f 66 20 74 68 65 20 74 61 62 6c  type of the tabl
2fd30 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69 73 20 72  e.** column is r
2fd40 65 74 75 72 6e 65 64 2e 29 5e 20 20 5e 49 66 20  eturned.)^  ^If 
2fd50 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f  the Nth column o
2fd60 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74  f the result set
2fd70 20 69 73 20 61 6e 0a 2a 2a 20 65 78 70 72 65 73   is an.** expres
2fd80 73 69 6f 6e 20 6f 72 20 73 75 62 71 75 65 72 79  sion or subquery
2fd90 2c 20 74 68 65 6e 20 61 20 4e 55 4c 4c 20 70 6f  , then a NULL po
2fda0 69 6e 74 65 72 20 69 73 20 72 65 74 75 72 6e 65  inter is returne
2fdb0 64 2e 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75 72  d..** ^The retur
2fdc0 6e 65 64 20 73 74 72 69 6e 67 20 69 73 20 61 6c  ned string is al
2fdd0 77 61 79 73 20 55 54 46 2d 38 20 65 6e 63 6f 64  ways UTF-8 encod
2fde0 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 46 6f 72 20  ed..**.** ^(For 
2fdf0 65 78 61 6d 70 6c 65 2c 20 67 69 76 65 6e 20 74  example, given t
2fe00 68 65 20 64 61 74 61 62 61 73 65 20 73 63 68 65  he database sche
2fe10 6d 61 3a 0a 2a 2a 0a 2a 2a 20 43 52 45 41 54 45  ma:.**.** CREATE
2fe20 20 54 41 42 4c 45 20 74 31 28 63 31 20 56 41 52   TABLE t1(c1 VAR
2fe30 49 41 4e 54 29 3b 0a 2a 2a 0a 2a 2a 20 61 6e 64  IANT);.**.** and
2fe40 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 73   the following s
2fe50 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 20 63  tatement to be c
2fe60 6f 6d 70 69 6c 65 64 3a 0a 2a 2a 0a 2a 2a 20 53  ompiled:.**.** S
2fe70 45 4c 45 43 54 20 63 31 20 2b 20 31 2c 20 63 31  ELECT c1 + 1, c1
2fe80 20 46 52 4f 4d 20 74 31 3b 0a 2a 2a 0a 2a 2a 20   FROM t1;.**.** 
2fe90 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 6f 75  this routine wou
2fea0 6c 64 20 72 65 74 75 72 6e 20 74 68 65 20 73 74  ld return the st
2feb0 72 69 6e 67 20 22 56 41 52 49 41 4e 54 22 20 66  ring "VARIANT" f
2fec0 6f 72 20 74 68 65 20 73 65 63 6f 6e 64 20 72 65  or the second re
2fed0 73 75 6c 74 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 28  sult.** column (
2fee0 69 3d 3d 31 29 2c 20 61 6e 64 20 61 20 4e 55 4c  i==1), and a NUL
2fef0 4c 20 70 6f 69 6e 74 65 72 20 66 6f 72 20 74 68  L pointer for th
2ff00 65 20 66 69 72 73 74 20 72 65 73 75 6c 74 20 63  e first result c
2ff10 6f 6c 75 6d 6e 20 28 69 3d 3d 30 29 2e 29 5e 0a  olumn (i==0).)^.
2ff20 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 75 73  **.** ^SQLite us
2ff30 65 73 20 64 79 6e 61 6d 69 63 20 72 75 6e 2d 74  es dynamic run-t
2ff40 69 6d 65 20 74 79 70 69 6e 67 2e 20 20 5e 53 6f  ime typing.  ^So
2ff50 20 6a 75 73 74 20 62 65 63 61 75 73 65 20 61 20   just because a 
2ff60 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20 64 65 63  column.** is dec
2ff70 6c 61 72 65 64 20 74 6f 20 63 6f 6e 74 61 69 6e  lared to contain
2ff80 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 74 79   a particular ty
2ff90 70 65 20 64 6f 65 73 20 6e 6f 74 20 6d 65 61 6e  pe does not mean
2ffa0 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 64 61 74   that the.** dat
2ffb0 61 20 73 74 6f 72 65 64 20 69 6e 20 74 68 61 74  a stored in that
2ffc0 20 63 6f 6c 75 6d 6e 20 69 73 20 6f 66 20 74 68   column is of th
2ffd0 65 20 64 65 63 6c 61 72 65 64 20 74 79 70 65 2e  e declared type.
2ffe0 20 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20 73    SQLite is.** s
2fff0 74 72 6f 6e 67 6c 79 20 74 79 70 65 64 2c 20 62  trongly typed, b
30000 75 74 20 74 68 65 20 74 79 70 69 6e 67 20 69 73  ut the typing is
30010 20 64 79 6e 61 6d 69 63 20 6e 6f 74 20 73 74 61   dynamic not sta
30020 74 69 63 2e 20 20 5e 54 79 70 65 0a 2a 2a 20 69  tic.  ^Type.** i
30030 73 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74  s associated wit
30040 68 20 69 6e 64 69 76 69 64 75 61 6c 20 76 61 6c  h individual val
30050 75 65 73 2c 20 6e 6f 74 20 77 69 74 68 20 74 68  ues, not with th
30060 65 20 63 6f 6e 74 61 69 6e 65 72 73 0a 2a 2a 20  e containers.** 
30070 75 73 65 64 20 74 6f 20 68 6f 6c 64 20 74 68 6f  used to hold tho
30080 73 65 20 76 61 6c 75 65 73 2e 0a 2a 2f 0a 63 6f  se values..*/.co
30090 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65  nst char *sqlite
300a0 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70  3_column_decltyp
300b0 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
300c0 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64  int);.const void
300d0 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
300e0 5f 64 65 63 6c 74 79 70 65 31 36 28 73 71 6c 69  _decltype16(sqli
300f0 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a  te3_stmt*,int);.
30100 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
30110 20 45 76 61 6c 75 61 74 65 20 41 6e 20 53 51 4c   Evaluate An SQL
30120 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 4d 45   Statement.** ME
30130 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74  THOD: sqlite3_st
30140 6d 74 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 61  mt.**.** After a
30150 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
30160 6d 65 6e 74 5d 20 68 61 73 20 62 65 65 6e 20 70  ment] has been p
30170 72 65 70 61 72 65 64 20 75 73 69 6e 67 20 65 69  repared using ei
30180 74 68 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ther.** [sqlite3
30190 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f  _prepare_v2()] o
301a0 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  r [sqlite3_prepa
301b0 72 65 31 36 5f 76 32 28 29 5d 20 6f 72 20 6f 6e  re16_v2()] or on
301c0 65 20 6f 66 20 74 68 65 20 6c 65 67 61 63 79 0a  e of the legacy.
301d0 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 5b 73  ** interfaces [s
301e0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29  qlite3_prepare()
301f0 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72  ] or [sqlite3_pr
30200 65 70 61 72 65 31 36 28 29 5d 2c 20 74 68 69 73  epare16()], this
30210 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 6d 75 73   function.** mus
30220 74 20 62 65 20 63 61 6c 6c 65 64 20 6f 6e 65 20  t be called one 
30230 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 20 74 6f  or more times to
30240 20 65 76 61 6c 75 61 74 65 20 74 68 65 20 73 74   evaluate the st
30250 61 74 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54  atement..**.** T
30260 68 65 20 64 65 74 61 69 6c 73 20 6f 66 20 74 68  he details of th
30270 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20 74 68  e behavior of th
30280 65 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29  e sqlite3_step()
30290 20 69 6e 74 65 72 66 61 63 65 20 64 65 70 65 6e   interface depen
302a0 64 0a 2a 2a 20 6f 6e 20 77 68 65 74 68 65 72 20  d.** on whether 
302b0 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 77 61  the statement wa
302c0 73 20 70 72 65 70 61 72 65 64 20 75 73 69 6e 67  s prepared using
302d0 20 74 68 65 20 6e 65 77 65 72 20 22 76 32 22 20   the newer "v2" 
302e0 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 5b 73 71  interface.** [sq
302f0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
30300 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
30310 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d  _prepare16_v2()]
30320 20 6f 72 20 74 68 65 20 6f 6c 64 65 72 20 6c 65   or the older le
30330 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63  gacy.** interfac
30340 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  e [sqlite3_prepa
30350 72 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  re()] and [sqlit
30360 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2e  e3_prepare16()].
30370 20 20 54 68 65 20 75 73 65 20 6f 66 20 74 68 65    The use of the
30380 0a 2a 2a 20 6e 65 77 20 22 76 32 22 20 69 6e 74  .** new "v2" int
30390 65 72 66 61 63 65 20 69 73 20 72 65 63 6f 6d 6d  erface is recomm
303a0 65 6e 64 65 64 20 66 6f 72 20 6e 65 77 20 61 70  ended for new ap
303b0 70 6c 69 63 61 74 69 6f 6e 73 20 62 75 74 20 74  plications but t
303c0 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74  he legacy.** int
303d0 65 72 66 61 63 65 20 77 69 6c 6c 20 63 6f 6e 74  erface will cont
303e0 69 6e 75 65 20 74 6f 20 62 65 20 73 75 70 70 6f  inue to be suppo
303f0 72 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 20  rted..**.** ^In 
30400 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72  the legacy inter
30410 66 61 63 65 2c 20 74 68 65 20 72 65 74 75 72 6e  face, the return
30420 20 76 61 6c 75 65 20 77 69 6c 6c 20 62 65 20 65   value will be e
30430 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 42 55  ither [SQLITE_BU
30440 53 59 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  SY],.** [SQLITE_
30450 44 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 52  DONE], [SQLITE_R
30460 4f 57 5d 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52  OW], [SQLITE_ERR
30470 4f 52 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f  OR], or [SQLITE_
30480 4d 49 53 55 53 45 5d 2e 0a 2a 2a 20 5e 57 69 74  MISUSE]..** ^Wit
30490 68 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72  h the "v2" inter
304a0 66 61 63 65 2c 20 61 6e 79 20 6f 66 20 74 68 65  face, any of the
304b0 20 6f 74 68 65 72 20 5b 72 65 73 75 6c 74 20 63   other [result c
304c0 6f 64 65 73 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74  odes] or.** [ext
304d0 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
304e0 65 73 5d 20 6d 69 67 68 74 20 62 65 20 72 65 74  es] might be ret
304f0 75 72 6e 65 64 20 61 73 20 77 65 6c 6c 2e 0a 2a  urned as well..*
30500 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 42 55  *.** ^[SQLITE_BU
30510 53 59 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74  SY] means that t
30520 68 65 20 64 61 74 61 62 61 73 65 20 65 6e 67 69  he database engi
30530 6e 65 20 77 61 73 20 75 6e 61 62 6c 65 20 74 6f  ne was unable to
30540 20 61 63 71 75 69 72 65 20 74 68 65 0a 2a 2a 20   acquire the.** 
30550 64 61 74 61 62 61 73 65 20 6c 6f 63 6b 73 20 69  database locks i
30560 74 20 6e 65 65 64 73 20 74 6f 20 64 6f 20 69 74  t needs to do it
30570 73 20 6a 6f 62 2e 20 20 5e 49 66 20 74 68 65 20  s job.  ^If the 
30580 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 20 5b  statement is a [
30590 43 4f 4d 4d 49 54 5d 0a 2a 2a 20 6f 72 20 6f 63  COMMIT].** or oc
305a0 63 75 72 73 20 6f 75 74 73 69 64 65 20 6f 66 20  curs outside of 
305b0 61 6e 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e  an explicit tran
305c0 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20 79 6f  saction, then yo
305d0 75 20 63 61 6e 20 72 65 74 72 79 20 74 68 65 0a  u can retry the.
305e0 2a 2a 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 49  ** statement.  I
305f0 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  f the statement 
30600 69 73 20 6e 6f 74 20 61 20 5b 43 4f 4d 4d 49 54  is not a [COMMIT
30610 5d 20 61 6e 64 20 6f 63 63 75 72 73 20 77 69 74  ] and occurs wit
30620 68 69 6e 20 61 6e 0a 2a 2a 20 65 78 70 6c 69 63  hin an.** explic
30630 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 74  it transaction t
30640 68 65 6e 20 79 6f 75 20 73 68 6f 75 6c 64 20 72  hen you should r
30650 6f 6c 6c 62 61 63 6b 20 74 68 65 20 74 72 61 6e  ollback the tran
30660 73 61 63 74 69 6f 6e 20 62 65 66 6f 72 65 0a 2a  saction before.*
30670 2a 20 63 6f 6e 74 69 6e 75 69 6e 67 2e 0a 2a 2a  * continuing..**
30680 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 44 4f 4e  .** ^[SQLITE_DON
30690 45 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68  E] means that th
306a0 65 20 73 74 61 74 65 6d 65 6e 74 20 68 61 73 20  e statement has 
306b0 66 69 6e 69 73 68 65 64 20 65 78 65 63 75 74 69  finished executi
306c0 6e 67 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c  ng.** successful
306d0 6c 79 2e 20 20 73 71 6c 69 74 65 33 5f 73 74 65  ly.  sqlite3_ste
306e0 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62  p() should not b
306f0 65 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f  e called again o
30700 6e 20 74 68 69 73 20 76 69 72 74 75 61 6c 0a 2a  n this virtual.*
30710 2a 20 6d 61 63 68 69 6e 65 20 77 69 74 68 6f 75  * machine withou
30720 74 20 66 69 72 73 74 20 63 61 6c 6c 69 6e 67 20  t first calling 
30730 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
30740 5d 20 74 6f 20 72 65 73 65 74 20 74 68 65 20 76  ] to reset the v
30750 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e  irtual.** machin
30760 65 20 62 61 63 6b 20 74 6f 20 69 74 73 20 69 6e  e back to its in
30770 69 74 69 61 6c 20 73 74 61 74 65 2e 0a 2a 2a 0a  itial state..**.
30780 2a 2a 20 5e 49 66 20 74 68 65 20 53 51 4c 20 73  ** ^If the SQL s
30790 74 61 74 65 6d 65 6e 74 20 62 65 69 6e 67 20 65  tatement being e
307a0 78 65 63 75 74 65 64 20 72 65 74 75 72 6e 73 20  xecuted returns 
307b0 61 6e 79 20 64 61 74 61 2c 20 74 68 65 6e 20 5b  any data, then [
307c0 53 51 4c 49 54 45 5f 52 4f 57 5d 0a 2a 2a 20 69  SQLITE_ROW].** i
307d0 73 20 72 65 74 75 72 6e 65 64 20 65 61 63 68 20  s returned each 
307e0 74 69 6d 65 20 61 20 6e 65 77 20 72 6f 77 20 6f  time a new row o
307f0 66 20 64 61 74 61 20 69 73 20 72 65 61 64 79 20  f data is ready 
30800 66 6f 72 20 70 72 6f 63 65 73 73 69 6e 67 20 62  for processing b
30810 79 20 74 68 65 0a 2a 2a 20 63 61 6c 6c 65 72 2e  y the.** caller.
30820 20 54 68 65 20 76 61 6c 75 65 73 20 6d 61 79 20   The values may 
30830 62 65 20 61 63 63 65 73 73 65 64 20 75 73 69 6e  be accessed usin
30840 67 20 74 68 65 20 5b 63 6f 6c 75 6d 6e 20 61 63  g the [column ac
30850 63 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 5d 2e  cess functions].
30860 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70  .** sqlite3_step
30870 28 29 20 69 73 20 63 61 6c 6c 65 64 20 61 67 61  () is called aga
30880 69 6e 20 74 6f 20 72 65 74 72 69 65 76 65 20 74  in to retrieve t
30890 68 65 20 6e 65 78 74 20 72 6f 77 20 6f 66 20 64  he next row of d
308a0 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c  ata..**.** ^[SQL
308b0 49 54 45 5f 45 52 52 4f 52 5d 20 6d 65 61 6e 73  ITE_ERROR] means
308c0 20 74 68 61 74 20 61 20 72 75 6e 2d 74 69 6d 65   that a run-time
308d0 20 65 72 72 6f 72 20 28 73 75 63 68 20 61 73 20   error (such as 
308e0 61 20 63 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a 20  a constraint.** 
308f0 76 69 6f 6c 61 74 69 6f 6e 29 20 68 61 73 20 6f  violation) has o
30900 63 63 75 72 72 65 64 2e 20 20 73 71 6c 69 74 65  ccurred.  sqlite
30910 33 5f 73 74 65 70 28 29 20 73 68 6f 75 6c 64 20  3_step() should 
30920 6e 6f 74 20 62 65 20 63 61 6c 6c 65 64 20 61 67  not be called ag
30930 61 69 6e 20 6f 6e 0a 2a 2a 20 74 68 65 20 56 4d  ain on.** the VM
30940 2e 20 4d 6f 72 65 20 69 6e 66 6f 72 6d 61 74 69  . More informati
30950 6f 6e 20 6d 61 79 20 62 65 20 66 6f 75 6e 64 20  on may be found 
30960 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69  by calling [sqli
30970 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a  te3_errmsg()]..*
30980 2a 20 5e 57 69 74 68 20 74 68 65 20 6c 65 67 61  * ^With the lega
30990 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20 61 20  cy interface, a 
309a0 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20 65 72  more specific er
309b0 72 6f 72 20 63 6f 64 65 20 28 66 6f 72 20 65 78  ror code (for ex
309c0 61 6d 70 6c 65 2c 0a 2a 2a 20 5b 53 51 4c 49 54  ample,.** [SQLIT
309d0 45 5f 49 4e 54 45 52 52 55 50 54 5d 2c 20 5b 53  E_INTERRUPT], [S
309e0 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 2c 20 5b  QLITE_SCHEMA], [
309f0 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 5d 2c  SQLITE_CORRUPT],
30a00 20 61 6e 64 20 73 6f 20 66 6f 72 74 68 29 0a 2a   and so forth).*
30a10 2a 20 63 61 6e 20 62 65 20 6f 62 74 61 69 6e 65  * can be obtaine
30a20 64 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71  d by calling [sq
30a30 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f  lite3_reset()] o
30a40 6e 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72  n the.** [prepar
30a50 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20  ed statement].  
30a60 5e 49 6e 20 74 68 65 20 22 76 32 22 20 69 6e 74  ^In the "v2" int
30a70 65 72 66 61 63 65 2c 0a 2a 2a 20 74 68 65 20 6d  erface,.** the m
30a80 6f 72 65 20 73 70 65 63 69 66 69 63 20 65 72 72  ore specific err
30a90 6f 72 20 63 6f 64 65 20 69 73 20 72 65 74 75 72  or code is retur
30aa0 6e 65 64 20 64 69 72 65 63 74 6c 79 20 62 79 20  ned directly by 
30ab0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 0a  sqlite3_step()..
30ac0 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 49  **.** [SQLITE_MI
30ad0 53 55 53 45 5d 20 6d 65 61 6e 73 20 74 68 61 74  SUSE] means that
30ae0 20 74 68 65 20 74 68 69 73 20 72 6f 75 74 69 6e   the this routin
30af0 65 20 77 61 73 20 63 61 6c 6c 65 64 20 69 6e 61  e was called ina
30b00 70 70 72 6f 70 72 69 61 74 65 6c 79 2e 0a 2a 2a  ppropriately..**
30b10 20 50 65 72 68 61 70 73 20 69 74 20 77 61 73 20   Perhaps it was 
30b20 63 61 6c 6c 65 64 20 6f 6e 20 61 20 5b 70 72 65  called on a [pre
30b30 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
30b40 20 74 68 61 74 20 68 61 73 0a 2a 2a 20 61 6c 72   that has.** alr
30b50 65 61 64 79 20 62 65 65 6e 20 5b 73 71 6c 69 74  eady been [sqlit
30b60 65 33 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 66 69  e3_finalize | fi
30b70 6e 61 6c 69 7a 65 64 5d 20 6f 72 20 6f 6e 20 6f  nalized] or on o
30b80 6e 65 20 74 68 61 74 20 68 61 64 0a 2a 2a 20 70  ne that had.** p
30b90 72 65 76 69 6f 75 73 6c 79 20 72 65 74 75 72 6e  reviously return
30ba0 65 64 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  ed [SQLITE_ERROR
30bb0 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 4f 4e  ] or [SQLITE_DON
30bc0 45 5d 2e 20 20 4f 72 20 69 74 20 63 6f 75 6c 64  E].  Or it could
30bd0 0a 2a 2a 20 62 65 20 74 68 65 20 63 61 73 65 20  .** be the case 
30be0 74 68 61 74 20 74 68 65 20 73 61 6d 65 20 64 61  that the same da
30bf0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
30c00 6e 20 69 73 20 62 65 69 6e 67 20 75 73 65 64 20  n is being used 
30c10 62 79 20 74 77 6f 20 6f 72 0a 2a 2a 20 6d 6f 72  by two or.** mor
30c20 65 20 74 68 72 65 61 64 73 20 61 74 20 74 68 65  e threads at the
30c30 20 73 61 6d 65 20 6d 6f 6d 65 6e 74 20 69 6e 20   same moment in 
30c40 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20  time..**.** For 
30c50 61 6c 6c 20 76 65 72 73 69 6f 6e 73 20 6f 66 20  all versions of 
30c60 53 51 4c 69 74 65 20 75 70 20 74 6f 20 61 6e 64  SQLite up to and
30c70 20 69 6e 63 6c 75 64 69 6e 67 20 33 2e 36 2e 32   including 3.6.2
30c80 33 2e 31 2c 20 61 20 63 61 6c 6c 20 74 6f 0a 2a  3.1, a call to.*
30c90 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  * [sqlite3_reset
30ca0 28 29 5d 20 77 61 73 20 72 65 71 75 69 72 65 64  ()] was required
30cb0 20 61 66 74 65 72 20 73 71 6c 69 74 65 33 5f 73   after sqlite3_s
30cc0 74 65 70 28 29 20 72 65 74 75 72 6e 65 64 20 61  tep() returned a
30cd0 6e 79 74 68 69 6e 67 0a 2a 2a 20 6f 74 68 65 72  nything.** other
30ce0 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 52 4f   than [SQLITE_RO
30cf0 57 5d 20 62 65 66 6f 72 65 20 61 6e 79 20 73 75  W] before any su
30d00 62 73 65 71 75 65 6e 74 20 69 6e 76 6f 63 61 74  bsequent invocat
30d10 69 6f 6e 20 6f 66 0a 2a 2a 20 73 71 6c 69 74 65  ion of.** sqlite
30d20 33 5f 73 74 65 70 28 29 2e 20 20 46 61 69 6c 75  3_step().  Failu
30d30 72 65 20 74 6f 20 72 65 73 65 74 20 74 68 65 20  re to reset the 
30d40 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
30d50 6e 74 20 75 73 69 6e 67 20 0a 2a 2a 20 5b 73 71  nt using .** [sq
30d60 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 77  lite3_reset()] w
30d70 6f 75 6c 64 20 72 65 73 75 6c 74 20 69 6e 20 61  ould result in a
30d80 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  n [SQLITE_MISUSE
30d90 5d 20 72 65 74 75 72 6e 20 66 72 6f 6d 0a 2a 2a  ] return from.**
30da0 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e   sqlite3_step().
30db0 20 20 42 75 74 20 61 66 74 65 72 20 5b 76 65 72    But after [ver
30dc0 73 69 6f 6e 20 33 2e 36 2e 32 33 2e 31 5d 20 28  sion 3.6.23.1] (
30dd0 5b 64 61 74 65 6f 66 3a 33 2e 36 2e 32 33 2e 31  [dateof:3.6.23.1
30de0 5d 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74  ],.** sqlite3_st
30df0 65 70 28 29 20 62 65 67 61 6e 0a 2a 2a 20 63 61  ep() began.** ca
30e00 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72  lling [sqlite3_r
30e10 65 73 65 74 28 29 5d 20 61 75 74 6f 6d 61 74 69  eset()] automati
30e20 63 61 6c 6c 79 20 69 6e 20 74 68 69 73 20 63 69  cally in this ci
30e30 72 63 75 6d 73 74 61 6e 63 65 20 72 61 74 68 65  rcumstance rathe
30e40 72 0a 2a 2a 20 74 68 61 6e 20 72 65 74 75 72 6e  r.** than return
30e50 69 6e 67 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55  ing [SQLITE_MISU
30e60 53 45 5d 2e 20 20 54 68 69 73 20 69 73 20 6e 6f  SE].  This is no
30e70 74 20 63 6f 6e 73 69 64 65 72 65 64 20 61 20 63  t considered a c
30e80 6f 6d 70 61 74 69 62 69 6c 69 74 79 0a 2a 2a 20  ompatibility.** 
30e90 62 72 65 61 6b 20 62 65 63 61 75 73 65 20 61 6e  break because an
30ea0 79 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 68  y application th
30eb0 61 74 20 65 76 65 72 20 72 65 63 65 69 76 65 73  at ever receives
30ec0 20 61 6e 20 53 51 4c 49 54 45 5f 4d 49 53 55 53   an SQLITE_MISUS
30ed0 45 20 65 72 72 6f 72 0a 2a 2a 20 69 73 20 62 72  E error.** is br
30ee0 6f 6b 65 6e 20 62 79 20 64 65 66 69 6e 69 74 69  oken by definiti
30ef0 6f 6e 2e 20 20 54 68 65 20 5b 53 51 4c 49 54 45  on.  The [SQLITE
30f00 5f 4f 4d 49 54 5f 41 55 54 4f 52 45 53 45 54 5d  _OMIT_AUTORESET]
30f10 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
30f20 74 69 6f 6e 0a 2a 2a 20 63 61 6e 20 62 65 20 75  tion.** can be u
30f30 73 65 64 20 74 6f 20 72 65 73 74 6f 72 65 20 74  sed to restore t
30f40 68 65 20 6c 65 67 61 63 79 20 62 65 68 61 76 69  he legacy behavi
30f50 6f 72 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 47 6f 6f  or..**.** <b>Goo
30f60 66 79 20 49 6e 74 65 72 66 61 63 65 20 41 6c 65  fy Interface Ale
30f70 72 74 3a 3c 2f 62 3e 20 49 6e 20 74 68 65 20 6c  rt:</b> In the l
30f80 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c  egacy interface,
30f90 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 74 65   the sqlite3_ste
30fa0 70 28 29 0a 2a 2a 20 41 50 49 20 61 6c 77 61 79  p().** API alway
30fb0 73 20 72 65 74 75 72 6e 73 20 61 20 67 65 6e 65  s returns a gene
30fc0 72 69 63 20 65 72 72 6f 72 20 63 6f 64 65 2c 20  ric error code, 
30fd0 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c 20  [SQLITE_ERROR], 
30fe0 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79 0a 2a 2a  following any.**
30ff0 20 65 72 72 6f 72 20 6f 74 68 65 72 20 74 68 61   error other tha
31000 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20  n [SQLITE_BUSY] 
31010 61 6e 64 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55  and [SQLITE_MISU
31020 53 45 5d 2e 20 20 59 6f 75 20 6d 75 73 74 20 63  SE].  You must c
31030 61 6c 6c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  all.** [sqlite3_
31040 72 65 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c  reset()] or [sql
31050 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
31060 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 66 69 6e   in order to fin
31070 64 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20  d one of the.** 
31080 73 70 65 63 69 66 69 63 20 5b 65 72 72 6f 72 20  specific [error 
31090 63 6f 64 65 73 5d 20 74 68 61 74 20 62 65 74 74  codes] that bett
310a0 65 72 20 64 65 73 63 72 69 62 65 73 20 74 68 65  er describes the
310b0 20 65 72 72 6f 72 2e 0a 2a 2a 20 57 65 20 61 64   error..** We ad
310c0 6d 69 74 20 74 68 61 74 20 74 68 69 73 20 69 73  mit that this is
310d0 20 61 20 67 6f 6f 66 79 20 64 65 73 69 67 6e 2e   a goofy design.
310e0 20 20 54 68 65 20 70 72 6f 62 6c 65 6d 20 68 61    The problem ha
310f0 73 20 62 65 65 6e 20 66 69 78 65 64 0a 2a 2a 20  s been fixed.** 
31100 77 69 74 68 20 74 68 65 20 22 76 32 22 20 69 6e  with the "v2" in
31110 74 65 72 66 61 63 65 2e 20 20 49 66 20 79 6f 75  terface.  If you
31120 20 70 72 65 70 61 72 65 20 61 6c 6c 20 6f 66 20   prepare all of 
31130 79 6f 75 72 20 53 51 4c 20 73 74 61 74 65 6d 65  your SQL stateme
31140 6e 74 73 0a 2a 2a 20 75 73 69 6e 67 20 65 69 74  nts.** using eit
31150 68 65 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  her [sqlite3_pre
31160 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73  pare_v2()] or [s
31170 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
31180 5f 76 32 28 29 5d 20 69 6e 73 74 65 61 64 0a 2a  _v2()] instead.*
31190 2a 20 6f 66 20 74 68 65 20 6c 65 67 61 63 79 20  * of the legacy 
311a0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
311b0 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
311c0 5f 70 72 65 70 61 72 65 31 36 28 29 5d 20 69 6e  _prepare16()] in
311d0 74 65 72 66 61 63 65 73 2c 0a 2a 2a 20 74 68 65  terfaces,.** the
311e0 6e 20 74 68 65 20 6d 6f 72 65 20 73 70 65 63 69  n the more speci
311f0 66 69 63 20 5b 65 72 72 6f 72 20 63 6f 64 65 73  fic [error codes
31200 5d 20 61 72 65 20 72 65 74 75 72 6e 65 64 20 64  ] are returned d
31210 69 72 65 63 74 6c 79 0a 2a 2a 20 62 79 20 73 71  irectly.** by sq
31220 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 20 20 54  lite3_step().  T
31230 68 65 20 75 73 65 20 6f 66 20 74 68 65 20 22 76  he use of the "v
31240 32 22 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  2" interface is 
31250 72 65 63 6f 6d 6d 65 6e 64 65 64 2e 0a 2a 2f 0a  recommended..*/.
31260 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 74 65 70  int sqlite3_step
31270 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b  (sqlite3_stmt*);
31280 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
31290 3a 20 4e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75  : Number of colu
312a0 6d 6e 73 20 69 6e 20 61 20 72 65 73 75 6c 74 20  mns in a result 
312b0 73 65 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  set.** METHOD: s
312c0 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a  qlite3_stmt.**.*
312d0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64  * ^The sqlite3_d
312e0 61 74 61 5f 63 6f 75 6e 74 28 50 29 20 69 6e 74  ata_count(P) int
312f0 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74  erface returns t
31300 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c  he number of col
31310 75 6d 6e 73 20 69 6e 20 74 68 65 0a 2a 2a 20 63  umns in the.** c
31320 75 72 72 65 6e 74 20 72 6f 77 20 6f 66 20 74 68  urrent row of th
31330 65 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20  e result set of 
31340 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
31350 65 6e 74 5d 20 50 2e 0a 2a 2a 20 5e 49 66 20 70  ent] P..** ^If p
31360 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
31370 74 20 50 20 64 6f 65 73 20 6e 6f 74 20 68 61 76  t P does not hav
31380 65 20 72 65 73 75 6c 74 73 20 72 65 61 64 79 20  e results ready 
31390 74 6f 20 72 65 74 75 72 6e 0a 2a 2a 20 28 76 69  to return.** (vi
313a0 61 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 20 5b  a calls to the [
313b0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69  sqlite3_column_i
313c0 6e 74 20 7c 20 73 71 6c 69 74 65 33 5f 63 6f 6c  nt | sqlite3_col
313d0 75 6d 6e 5f 2a 28 29 5d 20 6f 66 0a 2a 2a 20 69  umn_*()] of.** i
313e0 6e 74 65 72 66 61 63 65 73 29 20 74 68 65 6e 20  nterfaces) then 
313f0 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75  sqlite3_data_cou
31400 6e 74 28 50 29 20 72 65 74 75 72 6e 73 20 30 2e  nt(P) returns 0.
31410 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
31420 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 20 72  _data_count(P) r
31430 6f 75 74 69 6e 65 20 61 6c 73 6f 20 72 65 74 75  outine also retu
31440 72 6e 73 20 30 20 69 66 20 50 20 69 73 20 61 20  rns 0 if P is a 
31450 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a  NULL pointer..**
31460 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61   ^The sqlite3_da
31470 74 61 5f 63 6f 75 6e 74 28 50 29 20 72 6f 75 74  ta_count(P) rout
31480 69 6e 65 20 72 65 74 75 72 6e 73 20 30 20 69 66  ine returns 0 if
31490 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 63 61   the previous ca
314a0 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  ll to.** [sqlite
314b0 33 5f 73 74 65 70 5d 28 50 29 20 72 65 74 75 72  3_step](P) retur
314c0 6e 65 64 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45  ned [SQLITE_DONE
314d0 5d 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33  ].  ^The sqlite3
314e0 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 0a 2a  _data_count(P).*
314f0 2a 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 6e 6f  * will return no
31500 6e 2d 7a 65 72 6f 20 69 66 20 70 72 65 76 69 6f  n-zero if previo
31510 75 73 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  us call to [sqli
31520 74 65 33 5f 73 74 65 70 5d 28 50 29 20 72 65 74  te3_step](P) ret
31530 75 72 6e 65 64 0a 2a 2a 20 5b 53 51 4c 49 54 45  urned.** [SQLITE
31540 5f 52 4f 57 5d 2c 20 65 78 63 65 70 74 20 69 6e  _ROW], except in
31550 20 74 68 65 20 63 61 73 65 20 6f 66 20 74 68 65   the case of the
31560 20 5b 50 52 41 47 4d 41 20 69 6e 63 72 65 6d 65   [PRAGMA increme
31570 6e 74 61 6c 5f 76 61 63 75 75 6d 5d 0a 2a 2a 20  ntal_vacuum].** 
31580 77 68 65 72 65 20 69 74 20 61 6c 77 61 79 73 20  where it always 
31590 72 65 74 75 72 6e 73 20 7a 65 72 6f 20 73 69 6e  returns zero sin
315a0 63 65 20 65 61 63 68 20 73 74 65 70 20 6f 66 20  ce each step of 
315b0 74 68 61 74 20 6d 75 6c 74 69 2d 73 74 65 70 0a  that multi-step.
315c0 2a 2a 20 70 72 61 67 6d 61 20 72 65 74 75 72 6e  ** pragma return
315d0 73 20 30 20 63 6f 6c 75 6d 6e 73 20 6f 66 20 64  s 0 columns of d
315e0 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  ata..**.** See a
315f0 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  lso: [sqlite3_co
31600 6c 75 6d 6e 5f 63 6f 75 6e 74 28 29 5d 0a 2a 2f  lumn_count()].*/
31610 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 64 61 74  .int sqlite3_dat
31620 61 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f  a_count(sqlite3_
31630 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f  stmt *pStmt);../
31640 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46  *.** CAPI3REF: F
31650 75 6e 64 61 6d 65 6e 74 61 6c 20 44 61 74 61 74  undamental Datat
31660 79 70 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  ypes.** KEYWORDS
31670 3a 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 2a 2a  : SQLITE_TEXT.**
31680 0a 2a 2a 20 5e 28 45 76 65 72 79 20 76 61 6c 75  .** ^(Every valu
31690 65 20 69 6e 20 53 51 4c 69 74 65 20 68 61 73 20  e in SQLite has 
316a0 6f 6e 65 20 6f 66 20 66 69 76 65 20 66 75 6e 64  one of five fund
316b0 61 6d 65 6e 74 61 6c 20 64 61 74 61 74 79 70 65  amental datatype
316c0 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  s:.**.** <ul>.**
316d0 20 3c 6c 69 3e 20 36 34 2d 62 69 74 20 73 69 67   <li> 64-bit sig
316e0 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c  ned integer.** <
316f0 6c 69 3e 20 36 34 2d 62 69 74 20 49 45 45 45 20  li> 64-bit IEEE 
31700 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 6e  floating point n
31710 75 6d 62 65 72 0a 2a 2a 20 3c 6c 69 3e 20 73 74  umber.** <li> st
31720 72 69 6e 67 0a 2a 2a 20 3c 6c 69 3e 20 42 4c 4f  ring.** <li> BLO
31730 42 0a 2a 2a 20 3c 6c 69 3e 20 4e 55 4c 4c 0a 2a  B.** <li> NULL.*
31740 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20  * </ul>)^.**.** 
31750 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20  These constants 
31760 61 72 65 20 63 6f 64 65 73 20 66 6f 72 20 65 61  are codes for ea
31770 63 68 20 6f 66 20 74 68 6f 73 65 20 74 79 70 65  ch of those type
31780 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68  s..**.** Note th
31790 61 74 20 74 68 65 20 53 51 4c 49 54 45 5f 54 45  at the SQLITE_TE
317a0 58 54 20 63 6f 6e 73 74 61 6e 74 20 77 61 73 20  XT constant was 
317b0 61 6c 73 6f 20 75 73 65 64 20 69 6e 20 53 51 4c  also used in SQL
317c0 69 74 65 20 76 65 72 73 69 6f 6e 20 32 0a 2a 2a  ite version 2.**
317d0 20 66 6f 72 20 61 20 63 6f 6d 70 6c 65 74 65 6c   for a completel
317e0 79 20 64 69 66 66 65 72 65 6e 74 20 6d 65 61 6e  y different mean
317f0 69 6e 67 2e 20 20 53 6f 66 74 77 61 72 65 20 74  ing.  Software t
31800 68 61 74 20 6c 69 6e 6b 73 20 61 67 61 69 6e 73  hat links agains
31810 74 20 62 6f 74 68 0a 2a 2a 20 53 51 4c 69 74 65  t both.** SQLite
31820 20 76 65 72 73 69 6f 6e 20 32 20 61 6e 64 20 53   version 2 and S
31830 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 20  QLite version 3 
31840 73 68 6f 75 6c 64 20 75 73 65 20 53 51 4c 49 54  should use SQLIT
31850 45 33 5f 54 45 58 54 2c 20 6e 6f 74 0a 2a 2a 20  E3_TEXT, not.** 
31860 53 51 4c 49 54 45 5f 54 45 58 54 2e 0a 2a 2f 0a  SQLITE_TEXT..*/.
31870 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
31880 4e 54 45 47 45 52 20 20 31 0a 23 64 65 66 69 6e  NTEGER  1.#defin
31890 65 20 53 51 4c 49 54 45 5f 46 4c 4f 41 54 20 20  e SQLITE_FLOAT  
318a0 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    2.#define SQLI
318b0 54 45 5f 42 4c 4f 42 20 20 20 20 20 34 0a 23 64  TE_BLOB     4.#d
318c0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 55 4c  efine SQLITE_NUL
318d0 4c 20 20 20 20 20 35 0a 23 69 66 64 65 66 20 53  L     5.#ifdef S
318e0 51 4c 49 54 45 5f 54 45 58 54 0a 23 20 75 6e 64  QLITE_TEXT.# und
318f0 65 66 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 23  ef SQLITE_TEXT.#
31900 65 6c 73 65 0a 23 20 64 65 66 69 6e 65 20 53 51  else.# define SQ
31910 4c 49 54 45 5f 54 45 58 54 20 20 20 20 20 33 0a  LITE_TEXT     3.
31920 23 65 6e 64 69 66 0a 23 64 65 66 69 6e 65 20 53  #endif.#define S
31930 51 4c 49 54 45 33 5f 54 45 58 54 20 20 20 20 20  QLITE3_TEXT     
31940 33 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  3../*.** CAPI3RE
31950 46 3a 20 52 65 73 75 6c 74 20 56 61 6c 75 65 73  F: Result Values
31960 20 46 72 6f 6d 20 41 20 51 75 65 72 79 0a 2a 2a   From A Query.**
31970 20 4b 45 59 57 4f 52 44 53 3a 20 7b 63 6f 6c 75   KEYWORDS: {colu
31980 6d 6e 20 61 63 63 65 73 73 20 66 75 6e 63 74 69  mn access functi
31990 6f 6e 73 7d 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  ons}.** METHOD: 
319a0 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a  sqlite3_stmt.**.
319b0 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e  ** ^These routin
319c0 65 73 20 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d  es return inform
319d0 61 74 69 6f 6e 20 61 62 6f 75 74 20 61 20 73 69  ation about a si
319e0 6e 67 6c 65 20 63 6f 6c 75 6d 6e 20 6f 66 20 74  ngle column of t
319f0 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 72 65  he current.** re
31a00 73 75 6c 74 20 72 6f 77 20 6f 66 20 61 20 71 75  sult row of a qu
31a10 65 72 79 2e 20 20 5e 49 6e 20 65 76 65 72 79 20  ery.  ^In every 
31a20 63 61 73 65 20 74 68 65 20 66 69 72 73 74 20 61  case the first a
31a30 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69  rgument is a poi
31a40 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 5b  nter.** to the [
31a50 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
31a60 6e 74 5d 20 74 68 61 74 20 69 73 20 62 65 69 6e  nt] that is bein
31a70 67 20 65 76 61 6c 75 61 74 65 64 20 28 74 68 65  g evaluated (the
31a80 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 5d   [sqlite3_stmt*]
31a90 0a 2a 2a 20 74 68 61 74 20 77 61 73 20 72 65 74  .** that was ret
31aa0 75 72 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69  urned from [sqli
31ab0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
31ac0 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 69 74 73 20  ] or one of its 
31ad0 76 61 72 69 61 6e 74 73 29 0a 2a 2a 20 61 6e 64  variants).** and
31ae0 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   the second argu
31af0 6d 65 6e 74 20 69 73 20 74 68 65 20 69 6e 64 65  ment is the inde
31b00 78 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20  x of the column 
31b10 66 6f 72 20 77 68 69 63 68 20 69 6e 66 6f 72 6d  for which inform
31b20 61 74 69 6f 6e 0a 2a 2a 20 73 68 6f 75 6c 64 20  ation.** should 
31b30 62 65 20 72 65 74 75 72 6e 65 64 2e 20 5e 54 68  be returned. ^Th
31b40 65 20 6c 65 66 74 6d 6f 73 74 20 63 6f 6c 75 6d  e leftmost colum
31b50 6e 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20  n of the result 
31b60 73 65 74 20 68 61 73 20 74 68 65 20 69 6e 64 65  set has the inde
31b70 78 20 30 2e 0a 2a 2a 20 5e 54 68 65 20 6e 75 6d  x 0..** ^The num
31b80 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69  ber of columns i
31b90 6e 20 74 68 65 20 72 65 73 75 6c 74 20 63 61 6e  n the result can
31ba0 20 62 65 20 64 65 74 65 72 6d 69 6e 65 64 20 75   be determined u
31bb0 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  sing.** [sqlite3
31bc0 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 29 5d  _column_count()]
31bd0 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 53  ..**.** If the S
31be0 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 64 6f 65  QL statement doe
31bf0 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79 20  s not currently 
31c00 70 6f 69 6e 74 20 74 6f 20 61 20 76 61 6c 69 64  point to a valid
31c10 20 72 6f 77 2c 20 6f 72 20 69 66 20 74 68 65 0a   row, or if the.
31c20 2a 2a 20 63 6f 6c 75 6d 6e 20 69 6e 64 65 78 20  ** column index 
31c30 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 2c  is out of range,
31c40 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 75   the result is u
31c50 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 54 68 65  ndefined..** The
31c60 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 61 79 20  se routines may 
31c70 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64 20 77  only be called w
31c80 68 65 6e 20 74 68 65 20 6d 6f 73 74 20 72 65 63  hen the most rec
31c90 65 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b  ent call to.** [
31ca0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
31cb0 68 61 73 20 72 65 74 75 72 6e 65 64 20 5b 53 51  has returned [SQ
31cc0 4c 49 54 45 5f 52 4f 57 5d 20 61 6e 64 20 6e 65  LITE_ROW] and ne
31cd0 69 74 68 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  ither.** [sqlite
31ce0 33 5f 72 65 73 65 74 28 29 5d 20 6e 6f 72 20 5b  3_reset()] nor [
31cf0 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
31d00 28 29 5d 20 68 61 76 65 20 62 65 65 6e 20 63 61  ()] have been ca
31d10 6c 6c 65 64 20 73 75 62 73 65 71 75 65 6e 74 6c  lled subsequentl
31d20 79 2e 0a 2a 2a 20 49 66 20 61 6e 79 20 6f 66 20  y..** If any of 
31d30 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  these routines a
31d40 72 65 20 63 61 6c 6c 65 64 20 61 66 74 65 72 20  re called after 
31d50 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
31d60 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ] or.** [sqlite3
31d70 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20  _finalize()] or 
31d80 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 73  after [sqlite3_s
31d90 74 65 70 28 29 5d 20 68 61 73 20 72 65 74 75 72  tep()] has retur
31da0 6e 65 64 0a 2a 2a 20 73 6f 6d 65 74 68 69 6e 67  ned.** something
31db0 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c   other than [SQL
31dc0 49 54 45 5f 52 4f 57 5d 2c 20 74 68 65 20 72 65  ITE_ROW], the re
31dd0 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69  sults are undefi
31de0 6e 65 64 2e 0a 2a 2a 20 49 66 20 5b 73 71 6c 69  ned..** If [sqli
31df0 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 72 20 5b  te3_step()] or [
31e00 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
31e10 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e   or [sqlite3_fin
31e20 61 6c 69 7a 65 28 29 5d 0a 2a 2a 20 61 72 65 20  alize()].** are 
31e30 63 61 6c 6c 65 64 20 66 72 6f 6d 20 61 20 64 69  called from a di
31e40 66 66 65 72 65 6e 74 20 74 68 72 65 61 64 20 77  fferent thread w
31e50 68 69 6c 65 20 61 6e 79 20 6f 66 20 74 68 65 73  hile any of thes
31e60 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 61 72  e routines.** ar
31e70 65 20 70 65 6e 64 69 6e 67 2c 20 74 68 65 6e 20  e pending, then 
31e80 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 20  the results are 
31e90 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a  undefined..**.**
31ea0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f   ^The sqlite3_co
31eb0 6c 75 6d 6e 5f 74 79 70 65 28 29 20 72 6f 75 74  lumn_type() rout
31ec0 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 0a  ine returns the.
31ed0 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47  ** [SQLITE_INTEG
31ee0 45 52 20 7c 20 64 61 74 61 74 79 70 65 20 63 6f  ER | datatype co
31ef0 64 65 5d 20 66 6f 72 20 74 68 65 20 69 6e 69 74  de] for the init
31f00 69 61 6c 20 64 61 74 61 20 74 79 70 65 0a 2a 2a  ial data type.**
31f10 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 63   of the result c
31f20 6f 6c 75 6d 6e 2e 20 20 5e 54 68 65 20 72 65 74  olumn.  ^The ret
31f30 75 72 6e 65 64 20 76 61 6c 75 65 20 69 73 20 6f  urned value is o
31f40 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 49 4e  ne of [SQLITE_IN
31f50 54 45 47 45 52 5d 2c 0a 2a 2a 20 5b 53 51 4c 49  TEGER],.** [SQLI
31f60 54 45 5f 46 4c 4f 41 54 5d 2c 20 5b 53 51 4c 49  TE_FLOAT], [SQLI
31f70 54 45 5f 54 45 58 54 5d 2c 20 5b 53 51 4c 49 54  TE_TEXT], [SQLIT
31f80 45 5f 42 4c 4f 42 5d 2c 20 6f 72 20 5b 53 51 4c  E_BLOB], or [SQL
31f90 49 54 45 5f 4e 55 4c 4c 5d 2e 20 20 54 68 65 20  ITE_NULL].  The 
31fa0 76 61 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65  value.** returne
31fb0 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c  d by sqlite3_col
31fc0 75 6d 6e 5f 74 79 70 65 28 29 20 69 73 20 6f 6e  umn_type() is on
31fd0 6c 79 20 6d 65 61 6e 69 6e 67 66 75 6c 20 69 66  ly meaningful if
31fe0 20 6e 6f 20 74 79 70 65 0a 2a 2a 20 63 6f 6e 76   no type.** conv
31ff0 65 72 73 69 6f 6e 73 20 68 61 76 65 20 6f 63 63  ersions have occ
32000 75 72 72 65 64 20 61 73 20 64 65 73 63 72 69 62  urred as describ
32010 65 64 20 62 65 6c 6f 77 2e 20 20 41 66 74 65 72  ed below.  After
32020 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69   a type conversi
32030 6f 6e 2c 0a 2a 2a 20 74 68 65 20 76 61 6c 75 65  on,.** the value
32040 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c   returned by sql
32050 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65  ite3_column_type
32060 28 29 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e  () is undefined.
32070 20 20 46 75 74 75 72 65 0a 2a 2a 20 76 65 72 73    Future.** vers
32080 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d  ions of SQLite m
32090 61 79 20 63 68 61 6e 67 65 20 74 68 65 20 62 65  ay change the be
320a0 68 61 76 69 6f 72 20 6f 66 20 73 71 6c 69 74 65  havior of sqlite
320b0 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 0a  3_column_type().
320c0 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 74  ** following a t
320d0 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a  ype conversion..
320e0 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65  **.** ^If the re
320f0 73 75 6c 74 20 69 73 20 61 20 42 4c 4f 42 20 6f  sult is a BLOB o
32100 72 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20 74  r UTF-8 string t
32110 68 65 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f  hen the sqlite3_
32120 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 0a 2a  column_bytes().*
32130 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  * routine return
32140 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
32150 62 79 74 65 73 20 69 6e 20 74 68 61 74 20 42 4c  bytes in that BL
32160 4f 42 20 6f 72 20 73 74 72 69 6e 67 2e 0a 2a 2a  OB or string..**
32170 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20   ^If the result 
32180 69 73 20 61 20 55 54 46 2d 31 36 20 73 74 72 69  is a UTF-16 stri
32190 6e 67 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33  ng, then sqlite3
321a0 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20  _column_bytes() 
321b0 63 6f 6e 76 65 72 74 73 0a 2a 2a 20 74 68 65 20  converts.** the 
321c0 73 74 72 69 6e 67 20 74 6f 20 55 54 46 2d 38 20  string to UTF-8 
321d0 61 6e 64 20 74 68 65 6e 20 72 65 74 75 72 6e 73  and then returns
321e0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62   the number of b
321f0 79 74 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  ytes..** ^If the
32200 20 72 65 73 75 6c 74 20 69 73 20 61 20 6e 75 6d   result is a num
32210 65 72 69 63 20 76 61 6c 75 65 20 74 68 65 6e 20  eric value then 
32220 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
32230 79 74 65 73 28 29 20 75 73 65 73 0a 2a 2a 20 5b  ytes() uses.** [
32240 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66  sqlite3_snprintf
32250 28 29 5d 20 74 6f 20 63 6f 6e 76 65 72 74 20 74  ()] to convert t
32260 68 61 74 20 76 61 6c 75 65 20 74 6f 20 61 20 55  hat value to a U
32270 54 46 2d 38 20 73 74 72 69 6e 67 20 61 6e 64 20  TF-8 string and 
32280 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e  returns.** the n
32290 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69  umber of bytes i
322a0 6e 20 74 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a  n that string..*
322b0 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74  * ^If the result
322c0 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 73   is NULL, then s
322d0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
322e0 74 65 73 28 29 20 72 65 74 75 72 6e 73 20 7a 65  tes() returns ze
322f0 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  ro..**.** ^If th
32300 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 42 4c  e result is a BL
32310 4f 42 20 6f 72 20 55 54 46 2d 31 36 20 73 74 72  OB or UTF-16 str
32320 69 6e 67 20 74 68 65 6e 20 74 68 65 20 73 71 6c  ing then the sql
32330 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
32340 73 31 36 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65  s16().** routine
32350 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d   returns the num
32360 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20  ber of bytes in 
32370 74 68 61 74 20 42 4c 4f 42 20 6f 72 20 73 74 72  that BLOB or str
32380 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ing..** ^If the 
32390 72 65 73 75 6c 74 20 69 73 20 61 20 55 54 46 2d  result is a UTF-
323a0 38 20 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 73  8 string, then s
323b0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
323c0 74 65 73 31 36 28 29 20 63 6f 6e 76 65 72 74 73  tes16() converts
323d0 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 20 74  .** the string t
323e0 6f 20 55 54 46 2d 31 36 20 61 6e 64 20 74 68 65  o UTF-16 and the
323f0 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75  n returns the nu
32400 6d 62 65 72 20 6f 66 20 62 79 74 65 73 2e 0a 2a  mber of bytes..*
32410 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74  * ^If the result
32420 20 69 73 20 61 20 6e 75 6d 65 72 69 63 20 76 61   is a numeric va
32430 6c 75 65 20 74 68 65 6e 20 73 71 6c 69 74 65 33  lue then sqlite3
32440 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
32450 29 20 75 73 65 73 0a 2a 2a 20 5b 73 71 6c 69 74  ) uses.** [sqlit
32460 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 74  e3_snprintf()] t
32470 6f 20 63 6f 6e 76 65 72 74 20 74 68 61 74 20 76  o convert that v
32480 61 6c 75 65 20 74 6f 20 61 20 55 54 46 2d 31 36  alue to a UTF-16
32490 20 73 74 72 69 6e 67 20 61 6e 64 20 72 65 74 75   string and retu
324a0 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65  rns.** the numbe
324b0 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68  r of bytes in th
324c0 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49  at string..** ^I
324d0 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20  f the result is 
324e0 4e 55 4c 4c 2c 20 74 68 65 6e 20 73 71 6c 69 74  NULL, then sqlit
324f0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
32500 36 28 29 20 72 65 74 75 72 6e 73 20 7a 65 72 6f  6() returns zero
32510 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 76 61 6c  ..**.** ^The val
32520 75 65 73 20 72 65 74 75 72 6e 65 64 20 62 79 20  ues returned by 
32530 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
32540 62 79 74 65 73 28 29 5d 20 61 6e 64 20 0a 2a 2a  bytes()] and .**
32550 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
32560 5f 62 79 74 65 73 31 36 28 29 5d 20 64 6f 20 6e  _bytes16()] do n
32570 6f 74 20 69 6e 63 6c 75 64 65 20 74 68 65 20 7a  ot include the z
32580 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 73 20  ero terminators 
32590 61 74 20 74 68 65 20 65 6e 64 0a 2a 2a 20 6f 66  at the end.** of
325a0 20 74 68 65 20 73 74 72 69 6e 67 2e 20 20 5e 46   the string.  ^F
325b0 6f 72 20 63 6c 61 72 69 74 79 3a 20 74 68 65 20  or clarity: the 
325c0 76 61 6c 75 65 73 20 72 65 74 75 72 6e 65 64 20  values returned 
325d0 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  by.** [sqlite3_c
325e0 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 5d 20 61  olumn_bytes()] a
325f0 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  nd [sqlite3_colu
32600 6d 6e 5f 62 79 74 65 73 31 36 28 29 5d 20 61 72  mn_bytes16()] ar
32610 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a  e the number of.
32620 2a 2a 20 62 79 74 65 73 20 69 6e 20 74 68 65 20  ** bytes in the 
32630 73 74 72 69 6e 67 2c 20 6e 6f 74 20 74 68 65 20  string, not the 
32640 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63  number of charac
32650 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 53 74 72  ters..**.** ^Str
32660 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20 62 79  ings returned by
32670 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
32680 74 65 78 74 28 29 20 61 6e 64 20 73 71 6c 69 74  text() and sqlit
32690 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36  e3_column_text16
326a0 28 29 2c 0a 2a 2a 20 65 76 65 6e 20 65 6d 70 74  (),.** even empt
326b0 79 20 73 74 72 69 6e 67 73 2c 20 61 72 65 20 61  y strings, are a
326c0 6c 77 61 79 73 20 7a 65 72 6f 2d 74 65 72 6d 69  lways zero-termi
326d0 6e 61 74 65 64 2e 20 20 5e 54 68 65 20 72 65 74  nated.  ^The ret
326e0 75 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 66 72 6f  urn.** value fro
326f0 6d 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  m sqlite3_column
32700 5f 62 6c 6f 62 28 29 20 66 6f 72 20 61 20 7a 65  _blob() for a ze
32710 72 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f 42 20 69  ro-length BLOB i
32720 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
32730 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 57 61 72 6e 69  ..**.** <b>Warni
32740 6e 67 3a 3c 2f 62 3e 20 5e 54 68 65 20 6f 62 6a  ng:</b> ^The obj
32750 65 63 74 20 72 65 74 75 72 6e 65 64 20 62 79 20  ect returned by 
32760 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
32770 76 61 6c 75 65 28 29 5d 20 69 73 20 61 6e 0a 2a  value()] is an.*
32780 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73  * [unprotected s
32790 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
327a0 6a 65 63 74 2e 20 20 49 6e 20 61 20 6d 75 6c 74  ject.  In a mult
327b0 69 74 68 72 65 61 64 65 64 20 65 6e 76 69 72 6f  ithreaded enviro
327c0 6e 6d 65 6e 74 2c 0a 2a 2a 20 61 6e 20 75 6e 70  nment,.** an unp
327d0 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
327e0 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 6d 61  _value object ma
327f0 79 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 20 73  y only be used s
32800 61 66 65 6c 79 20 77 69 74 68 0a 2a 2a 20 5b 73  afely with.** [s
32810 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75  qlite3_bind_valu
32820 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  e()] and [sqlite
32830 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29  3_result_value()
32840 5d 2e 0a 2a 2a 20 49 66 20 74 68 65 20 5b 75 6e  ]..** If the [un
32850 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
32860 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20  3_value] object 
32870 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b  returned by.** [
32880 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76  sqlite3_column_v
32890 61 6c 75 65 28 29 5d 20 69 73 20 75 73 65 64 20  alue()] is used 
328a0 69 6e 20 61 6e 79 20 6f 74 68 65 72 20 77 61 79  in any other way
328b0 2c 20 69 6e 63 6c 75 64 69 6e 67 20 63 61 6c 6c  , including call
328c0 73 0a 2a 2a 20 74 6f 20 72 6f 75 74 69 6e 65 73  s.** to routines
328d0 20 6c 69 6b 65 20 5b 73 71 6c 69 74 65 33 5f 76   like [sqlite3_v
328e0 61 6c 75 65 5f 69 6e 74 28 29 5d 2c 20 5b 73 71  alue_int()], [sq
328f0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
32900 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69  ()],.** or [sqli
32910 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 28  te3_value_bytes(
32920 29 5d 2c 20 74 68 65 20 62 65 68 61 76 69 6f 72  )], the behavior
32930 20 69 73 20 6e 6f 74 20 74 68 72 65 61 64 73 61   is not threadsa
32940 66 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  fe..**.** These 
32950 72 6f 75 74 69 6e 65 73 20 61 74 74 65 6d 70 74  routines attempt
32960 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 65 20   to convert the 
32970 76 61 6c 75 65 20 77 68 65 72 65 20 61 70 70 72  value where appr
32980 6f 70 72 69 61 74 65 2e 20 20 5e 46 6f 72 0a 2a  opriate.  ^For.*
32990 2a 20 65 78 61 6d 70 6c 65 2c 20 69 66 20 74 68  * example, if th
329a0 65 20 69 6e 74 65 72 6e 61 6c 20 72 65 70 72 65  e internal repre
329b0 73 65 6e 74 61 74 69 6f 6e 20 69 73 20 46 4c 4f  sentation is FLO
329c0 41 54 20 61 6e 64 20 61 20 74 65 78 74 20 72 65  AT and a text re
329d0 73 75 6c 74 0a 2a 2a 20 69 73 20 72 65 71 75 65  sult.** is reque
329e0 73 74 65 64 2c 20 5b 73 71 6c 69 74 65 33 5f 73  sted, [sqlite3_s
329f0 6e 70 72 69 6e 74 66 28 29 5d 20 69 73 20 75 73  nprintf()] is us
32a00 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 74 6f  ed internally to
32a10 20 70 65 72 66 6f 72 6d 20 74 68 65 0a 2a 2a 20   perform the.** 
32a20 63 6f 6e 76 65 72 73 69 6f 6e 20 61 75 74 6f 6d  conversion autom
32a30 61 74 69 63 61 6c 6c 79 2e 20 20 5e 28 54 68 65  atically.  ^(The
32a40 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 61 62 6c 65   following table
32a50 20 64 65 74 61 69 6c 73 20 74 68 65 20 63 6f 6e   details the con
32a60 76 65 72 73 69 6f 6e 73 0a 2a 2a 20 74 68 61 74  versions.** that
32a70 20 61 72 65 20 61 70 70 6c 69 65 64 3a 0a 2a 2a   are applied:.**
32a80 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
32a90 0a 2a 2a 20 3c 74 61 62 6c 65 20 62 6f 72 64 65  .** <table borde
32aa0 72 3d 22 31 22 3e 0a 2a 2a 20 3c 74 72 3e 3c 74  r="1">.** <tr><t
32ab0 68 3e 20 49 6e 74 65 72 6e 61 6c 3c 62 72 3e 54  h> Internal<br>T
32ac0 79 70 65 20 3c 74 68 3e 20 52 65 71 75 65 73 74  ype <th> Request
32ad0 65 64 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e 20  ed<br>Type <th> 
32ae0 20 43 6f 6e 76 65 72 73 69 6f 6e 0a 2a 2a 0a 2a   Conversion.**.*
32af0 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c  * <tr><td>  NULL
32b00 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52      <td> INTEGER
32b10 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69     <td> Result i
32b20 73 20 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  s 0.** <tr><td> 
32b30 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 46   NULL    <td>  F
32b40 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 52 65 73  LOAT    <td> Res
32b50 75 6c 74 20 69 73 20 30 2e 30 0a 2a 2a 20 3c 74  ult is 0.0.** <t
32b60 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20  r><td>  NULL    
32b70 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c  <td>   TEXT    <
32b80 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 61 20  td> Result is a 
32b90 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20  NULL pointer.** 
32ba0 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20  <tr><td>  NULL  
32bb0 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20    <td>   BLOB   
32bc0 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20   <td> Result is 
32bd0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a  a NULL pointer.*
32be0 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47  * <tr><td> INTEG
32bf0 45 52 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20  ER  <td>  FLOAT 
32c00 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20     <td> Convert 
32c10 66 72 6f 6d 20 69 6e 74 65 67 65 72 20 74 6f 20  from integer to 
32c20 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64  float.** <tr><td
32c30 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20  > INTEGER  <td> 
32c40 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41    TEXT    <td> A
32c50 53 43 49 49 20 72 65 6e 64 65 72 69 6e 67 20 6f  SCII rendering o
32c60 66 20 74 68 65 20 69 6e 74 65 67 65 72 0a 2a 2a  f the integer.**
32c70 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45   <tr><td> INTEGE
32c80 52 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20  R  <td>   BLOB  
32c90 20 20 3c 74 64 3e 20 53 61 6d 65 20 61 73 20 49    <td> Same as I
32ca0 4e 54 45 47 45 52 2d 3e 54 45 58 54 0a 2a 2a 20  NTEGER->TEXT.** 
32cb0 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20  <tr><td>  FLOAT 
32cc0 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20    <td> INTEGER  
32cd0 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20   <td> [CAST] to 
32ce0 49 4e 54 45 47 45 52 0a 2a 2a 20 3c 74 72 3e 3c  INTEGER.** <tr><
32cf0 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64  td>  FLOAT   <td
32d00 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e  >   TEXT    <td>
32d10 20 41 53 43 49 49 20 72 65 6e 64 65 72 69 6e 67   ASCII rendering
32d20 20 6f 66 20 74 68 65 20 66 6c 6f 61 74 0a 2a 2a   of the float.**
32d30 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54   <tr><td>  FLOAT
32d40 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20     <td>   BLOB  
32d50 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f    <td> [CAST] to
32d60 20 42 4c 4f 42 0a 2a 2a 20 3c 74 72 3e 3c 74 64   BLOB.** <tr><td
32d70 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20  >  TEXT    <td> 
32d80 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 5b  INTEGER   <td> [
32d90 43 41 53 54 5d 20 74 6f 20 49 4e 54 45 47 45 52  CAST] to INTEGER
32da0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45  .** <tr><td>  TE
32db0 58 54 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41  XT    <td>  FLOA
32dc0 54 20 20 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d  T    <td> [CAST]
32dd0 20 74 6f 20 52 45 41 4c 0a 2a 2a 20 3c 74 72 3e   to REAL.** <tr>
32de0 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74  <td>  TEXT    <t
32df0 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64  d>   BLOB    <td
32e00 3e 20 4e 6f 20 63 68 61 6e 67 65 0a 2a 2a 20 3c  > No change.** <
32e10 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20  tr><td>  BLOB   
32e20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20   <td> INTEGER   
32e30 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20 49  <td> [CAST] to I
32e40 4e 54 45 47 45 52 0a 2a 2a 20 3c 74 72 3e 3c 74  NTEGER.** <tr><t
32e50 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e  d>  BLOB    <td>
32e60 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20    FLOAT    <td> 
32e70 5b 43 41 53 54 5d 20 74 6f 20 52 45 41 4c 0a 2a  [CAST] to REAL.*
32e80 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42  * <tr><td>  BLOB
32e90 20 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20      <td>   TEXT 
32ea0 20 20 20 3c 74 64 3e 20 41 64 64 20 61 20 7a 65     <td> Add a ze
32eb0 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20 69 66  ro terminator if
32ec0 20 6e 65 65 64 65 64 0a 2a 2a 20 3c 2f 74 61 62   needed.** </tab
32ed0 6c 65 3e 0a 2a 2a 20 3c 2f 62 6c 6f 63 6b 71 75  le>.** </blockqu
32ee0 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 4e 6f 74  ote>)^.**.** Not
32ef0 65 20 74 68 61 74 20 77 68 65 6e 20 74 79 70 65  e that when type
32f00 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 6f 63 63   conversions occ
32f10 75 72 2c 20 70 6f 69 6e 74 65 72 73 20 72 65 74  ur, pointers ret
32f20 75 72 6e 65 64 20 62 79 20 70 72 69 6f 72 0a 2a  urned by prior.*
32f30 2a 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74  * calls to sqlit
32f40 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29  e3_column_blob()
32f50 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  , sqlite3_column
32f60 5f 74 65 78 74 28 29 2c 20 61 6e 64 2f 6f 72 0a  _text(), and/or.
32f70 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  ** sqlite3_colum
32f80 6e 5f 74 65 78 74 31 36 28 29 20 6d 61 79 20 62  n_text16() may b
32f90 65 20 69 6e 76 61 6c 69 64 61 74 65 64 2e 0a 2a  e invalidated..*
32fa0 2a 20 54 79 70 65 20 63 6f 6e 76 65 72 73 69 6f  * Type conversio
32fb0 6e 73 20 61 6e 64 20 70 6f 69 6e 74 65 72 20 69  ns and pointer i
32fc0 6e 76 61 6c 69 64 61 74 69 6f 6e 73 20 6d 69 67  nvalidations mig
32fd0 68 74 20 6f 63 63 75 72 0a 2a 2a 20 69 6e 20 74  ht occur.** in t
32fe0 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 63 61 73  he following cas
32ff0 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a  es:.**.** <ul>.*
33000 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74 69  * <li> The initi
33010 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 61 20  al content is a 
33020 42 4c 4f 42 20 61 6e 64 20 73 71 6c 69 74 65 33  BLOB and sqlite3
33030 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 6f  _column_text() o
33040 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 74 65  r.**      sqlite
33050 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28  3_column_text16(
33060 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 41 20  ) is called.  A 
33070 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 6f 72 20  zero-terminator 
33080 6d 69 67 68 74 0a 2a 2a 20 20 20 20 20 20 6e 65  might.**      ne
33090 65 64 20 74 6f 20 62 65 20 61 64 64 65 64 20 74  ed to be added t
330a0 6f 20 74 68 65 20 73 74 72 69 6e 67 2e 3c 2f 6c  o the string.</l
330b0 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69  i>.** <li> The i
330c0 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69  nitial content i
330d0 73 20 55 54 46 2d 38 20 74 65 78 74 20 61 6e 64  s UTF-8 text and
330e0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
330f0 62 79 74 65 73 31 36 28 29 20 6f 72 0a 2a 2a 20  bytes16() or.** 
33100 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c       sqlite3_col
33110 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 69 73 20  umn_text16() is 
33120 63 61 6c 6c 65 64 2e 20 20 54 68 65 20 63 6f 6e  called.  The con
33130 74 65 6e 74 20 6d 75 73 74 20 62 65 20 63 6f 6e  tent must be con
33140 76 65 72 74 65 64 0a 2a 2a 20 20 20 20 20 20 74  verted.**      t
33150 6f 20 55 54 46 2d 31 36 2e 3c 2f 6c 69 3e 0a 2a  o UTF-16.</li>.*
33160 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74 69  * <li> The initi
33170 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 55 54  al content is UT
33180 46 2d 31 36 20 74 65 78 74 20 61 6e 64 20 73 71  F-16 text and sq
33190 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
331a0 65 73 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20  es() or.**      
331b0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
331c0 65 78 74 28 29 20 69 73 20 63 61 6c 6c 65 64 2e  ext() is called.
331d0 20 20 54 68 65 20 63 6f 6e 74 65 6e 74 20 6d 75    The content mu
331e0 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64 0a  st be converted.
331f0 2a 2a 20 20 20 20 20 20 74 6f 20 55 54 46 2d 38  **      to UTF-8
33200 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a  .</li>.** </ul>.
33210 2a 2a 0a 2a 2a 20 5e 43 6f 6e 76 65 72 73 69 6f  **.** ^Conversio
33220 6e 73 20 62 65 74 77 65 65 6e 20 55 54 46 2d 31  ns between UTF-1
33230 36 62 65 20 61 6e 64 20 55 54 46 2d 31 36 6c 65  6be and UTF-16le
33240 20 61 72 65 20 61 6c 77 61 79 73 20 64 6f 6e 65   are always done
33250 20 69 6e 20 70 6c 61 63 65 20 61 6e 64 20 64 6f   in place and do
33260 0a 2a 2a 20 6e 6f 74 20 69 6e 76 61 6c 69 64 61  .** not invalida
33270 74 65 20 61 20 70 72 69 6f 72 20 70 6f 69 6e 74  te a prior point
33280 65 72 2c 20 74 68 6f 75 67 68 20 6f 66 20 63 6f  er, though of co
33290 75 72 73 65 20 74 68 65 20 63 6f 6e 74 65 6e 74  urse the content
332a0 20 6f 66 20 74 68 65 20 62 75 66 66 65 72 0a 2a   of the buffer.*
332b0 2a 20 74 68 61 74 20 74 68 65 20 70 72 69 6f 72  * that the prior
332c0 20 70 6f 69 6e 74 65 72 20 72 65 66 65 72 65 6e   pointer referen
332d0 63 65 73 20 77 69 6c 6c 20 68 61 76 65 20 62 65  ces will have be
332e0 65 6e 20 6d 6f 64 69 66 69 65 64 2e 20 20 4f 74  en modified.  Ot
332f0 68 65 72 20 6b 69 6e 64 73 0a 2a 2a 20 6f 66 20  her kinds.** of 
33300 63 6f 6e 76 65 72 73 69 6f 6e 20 61 72 65 20 64  conversion are d
33310 6f 6e 65 20 69 6e 20 70 6c 61 63 65 20 77 68 65  one in place whe
33320 6e 20 69 74 20 69 73 20 70 6f 73 73 69 62 6c 65  n it is possible
33330 2c 20 62 75 74 20 73 6f 6d 65 74 69 6d 65 73 20  , but sometimes 
33340 74 68 65 79 0a 2a 2a 20 61 72 65 20 6e 6f 74 20  they.** are not 
33350 70 6f 73 73 69 62 6c 65 20 61 6e 64 20 69 6e 20  possible and in 
33360 74 68 6f 73 65 20 63 61 73 65 73 20 70 72 69 6f  those cases prio
33370 72 20 70 6f 69 6e 74 65 72 73 20 61 72 65 20 69  r pointers are i
33380 6e 76 61 6c 69 64 61 74 65 64 2e 0a 2a 2a 0a 2a  nvalidated..**.*
33390 2a 20 54 68 65 20 73 61 66 65 73 74 20 70 6f 6c  * The safest pol
333a0 69 63 79 20 69 73 20 74 6f 20 69 6e 76 6f 6b 65  icy is to invoke
333b0 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 0a   these routines.
333c0 2a 2a 20 69 6e 20 6f 6e 65 20 6f 66 20 74 68 65  ** in one of the
333d0 20 66 6f 6c 6c 6f 77 69 6e 67 20 77 61 79 73 3a   following ways:
333e0 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20  .**.** <ul>.**  
333f0 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75  <li>sqlite3_colu
33400 6d 6e 5f 74 65 78 74 28 29 20 66 6f 6c 6c 6f 77  mn_text() follow
33410 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f  ed by sqlite3_co
33420 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3c 2f 6c 69  lumn_bytes()</li
33430 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65  >.**  <li>sqlite
33440 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20  3_column_blob() 
33450 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69  followed by sqli
33460 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
33470 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e  ()</li>.**  <li>
33480 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
33490 65 78 74 31 36 28 29 20 66 6f 6c 6c 6f 77 65 64  ext16() followed
334a0 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   by sqlite3_colu
334b0 6d 6e 5f 62 79 74 65 73 31 36 28 29 3c 2f 6c 69  mn_bytes16()</li
334c0 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a  >.** </ul>.**.**
334d0 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c   In other words,
334e0 20 79 6f 75 20 73 68 6f 75 6c 64 20 63 61 6c 6c   you should call
334f0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
33500 74 65 78 74 28 29 2c 0a 2a 2a 20 73 71 6c 69 74  text(),.** sqlit
33510 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29  e3_column_blob()
33520 2c 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c  , or sqlite3_col
33530 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 66 69 72  umn_text16() fir
33540 73 74 20 74 6f 20 66 6f 72 63 65 20 74 68 65 20  st to force the 
33550 72 65 73 75 6c 74 0a 2a 2a 20 69 6e 74 6f 20 74  result.** into t
33560 68 65 20 64 65 73 69 72 65 64 20 66 6f 72 6d 61  he desired forma
33570 74 2c 20 74 68 65 6e 20 69 6e 76 6f 6b 65 20 73  t, then invoke s
33580 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
33590 74 65 73 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69  tes() or.** sqli
335a0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
335b0 31 36 28 29 20 74 6f 20 66 69 6e 64 20 74 68 65  16() to find the
335c0 20 73 69 7a 65 20 6f 66 20 74 68 65 20 72 65 73   size of the res
335d0 75 6c 74 2e 20 20 44 6f 20 6e 6f 74 20 6d 69 78  ult.  Do not mix
335e0 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 73 71 6c   calls.** to sql
335f0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
33600 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f  () or sqlite3_co
33610 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 77 69 74 68  lumn_blob() with
33620 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 73 71 6c   calls to.** sql
33630 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
33640 73 31 36 28 29 2c 20 61 6e 64 20 64 6f 20 6e 6f  s16(), and do no
33650 74 20 6d 69 78 20 63 61 6c 6c 73 20 74 6f 20 73  t mix calls to s
33660 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
33670 78 74 31 36 28 29 0a 2a 2a 20 77 69 74 68 20 63  xt16().** with c
33680 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f  alls to sqlite3_
33690 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 2e 0a  column_bytes()..
336a0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 70 6f 69 6e 74  **.** ^The point
336b0 65 72 73 20 72 65 74 75 72 6e 65 64 20 61 72 65  ers returned are
336c0 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 61 20 74   valid until a t
336d0 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20 6f  ype conversion o
336e0 63 63 75 72 73 20 61 73 0a 2a 2a 20 64 65 73 63  ccurs as.** desc
336f0 72 69 62 65 64 20 61 62 6f 76 65 2c 20 6f 72 20  ribed above, or 
33700 75 6e 74 69 6c 20 5b 73 71 6c 69 74 65 33 5f 73  until [sqlite3_s
33710 74 65 70 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  tep()] or [sqlit
33720 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a  e3_reset()] or.*
33730 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  * [sqlite3_final
33740 69 7a 65 28 29 5d 20 69 73 20 63 61 6c 6c 65 64  ize()] is called
33750 2e 20 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20 73  .  ^The memory s
33760 70 61 63 65 20 75 73 65 64 20 74 6f 20 68 6f 6c  pace used to hol
33770 64 20 73 74 72 69 6e 67 73 0a 2a 2a 20 61 6e 64  d strings.** and
33780 20 42 4c 4f 42 73 20 69 73 20 66 72 65 65 64 20   BLOBs is freed 
33790 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20  automatically.  
337a0 44 6f 20 3c 65 6d 3e 6e 6f 74 3c 2f 65 6d 3e 20  Do <em>not</em> 
337b0 70 61 73 73 20 74 68 65 20 70 6f 69 6e 74 65 72  pass the pointer
337c0 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 66 72  s returned.** fr
337d0 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  om [sqlite3_colu
337e0 6d 6e 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c  mn_blob()], [sql
337f0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
33800 28 29 5d 2c 20 65 74 63 2e 20 69 6e 74 6f 0a 2a  ()], etc. into.*
33810 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  * [sqlite3_free(
33820 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 61  )]..**.** ^(If a
33830 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
33840 6f 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20  on error occurs 
33850 64 75 72 69 6e 67 20 74 68 65 20 65 76 61 6c 75  during the evalu
33860 61 74 69 6f 6e 20 6f 66 20 61 6e 79 0a 2a 2a 20  ation of any.** 
33870 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  of these routine
33880 73 2c 20 61 20 64 65 66 61 75 6c 74 20 76 61 6c  s, a default val
33890 75 65 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20  ue is returned. 
338a0 20 54 68 65 20 64 65 66 61 75 6c 74 20 76 61 6c   The default val
338b0 75 65 0a 2a 2a 20 69 73 20 65 69 74 68 65 72 20  ue.** is either 
338c0 74 68 65 20 69 6e 74 65 67 65 72 20 30 2c 20 74  the integer 0, t
338d0 68 65 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e  he floating poin
338e0 74 20 6e 75 6d 62 65 72 20 30 2e 30 2c 20 6f 72  t number 0.0, or
338f0 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74   a NULL.** point
33900 65 72 2e 20 20 53 75 62 73 65 71 75 65 6e 74 20  er.  Subsequent 
33910 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65  calls to [sqlite
33920 33 5f 65 72 72 63 6f 64 65 28 29 5d 20 77 69 6c  3_errcode()] wil
33930 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c  l return.** [SQL
33940 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 29 5e 0a 2a 2f  ITE_NOMEM].)^.*/
33950 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  .const void *sql
33960 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62  ite3_column_blob
33970 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
33980 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73  int iCol);.int s
33990 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
339a0 74 65 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  tes(sqlite3_stmt
339b0 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e  *, int iCol);.in
339c0 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  t sqlite3_column
339d0 5f 62 79 74 65 73 31 36 28 73 71 6c 69 74 65 33  _bytes16(sqlite3
339e0 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
339f0 29 3b 0a 64 6f 75 62 6c 65 20 73 71 6c 69 74 65  );.double sqlite
33a00 33 5f 63 6f 6c 75 6d 6e 5f 64 6f 75 62 6c 65 28  3_column_double(
33a10 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
33a20 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71  nt iCol);.int sq
33a30 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74  lite3_column_int
33a40 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
33a50 69 6e 74 20 69 43 6f 6c 29 3b 0a 73 71 6c 69 74  int iCol);.sqlit
33a60 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33  e3_int64 sqlite3
33a70 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 36 34 28 73 71  _column_int64(sq
33a80 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
33a90 20 69 43 6f 6c 29 3b 0a 63 6f 6e 73 74 20 75 6e   iCol);.const un
33aa0 73 69 67 6e 65 64 20 63 68 61 72 20 2a 73 71 6c  signed char *sql
33ab0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
33ac0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
33ad0 69 6e 74 20 69 43 6f 6c 29 3b 0a 63 6f 6e 73 74  int iCol);.const
33ae0 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63   void *sqlite3_c
33af0 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 73 71 6c  olumn_text16(sql
33b00 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
33b10 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74  iCol);.int sqlit
33b20 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 73  e3_column_type(s
33b30 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
33b40 74 20 69 43 6f 6c 29 3b 0a 73 71 6c 69 74 65 33  t iCol);.sqlite3
33b50 5f 76 61 6c 75 65 20 2a 73 71 6c 69 74 65 33 5f  _value *sqlite3_
33b60 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 73 71 6c  column_value(sql
33b70 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
33b80 69 43 6f 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  iCol);../*.** CA
33b90 50 49 33 52 45 46 3a 20 44 65 73 74 72 6f 79 20  PI3REF: Destroy 
33ba0 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65  A Prepared State
33bb0 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 20 44  ment Object.** D
33bc0 45 53 54 52 55 43 54 4f 52 3a 20 73 71 6c 69 74  ESTRUCTOR: sqlit
33bd0 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54  e3_stmt.**.** ^T
33be0 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  he sqlite3_final
33bf0 69 7a 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 69  ize() function i
33c00 73 20 63 61 6c 6c 65 64 20 74 6f 20 64 65 6c 65  s called to dele
33c10 74 65 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  te a [prepared s
33c20 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 49  tatement]..** ^I
33c30 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  f the most recen
33c40 74 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20  t evaluation of 
33c50 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 65 6e  the statement en
33c60 63 6f 75 6e 74 65 72 65 64 20 6e 6f 20 65 72 72  countered no err
33c70 6f 72 73 0a 2a 2a 20 6f 72 20 69 66 20 74 68 65  ors.** or if the
33c80 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6e 65   statement is ne
33c90 76 65 72 20 62 65 65 6e 20 65 76 61 6c 75 61 74  ver been evaluat
33ca0 65 64 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33  ed, then sqlite3
33cb0 5f 66 69 6e 61 6c 69 7a 65 28 29 20 72 65 74 75  _finalize() retu
33cc0 72 6e 73 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f 4b  rns.** SQLITE_OK
33cd0 2e 20 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20  .  ^If the most 
33ce0 72 65 63 65 6e 74 20 65 76 61 6c 75 61 74 69 6f  recent evaluatio
33cf0 6e 20 6f 66 20 73 74 61 74 65 6d 65 6e 74 20 53  n of statement S
33d00 20 66 61 69 6c 65 64 2c 20 74 68 65 6e 0a 2a 2a   failed, then.**
33d10 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a   sqlite3_finaliz
33d20 65 28 53 29 20 72 65 74 75 72 6e 73 20 74 68 65  e(S) returns the
33d30 20 61 70 70 72 6f 70 72 69 61 74 65 20 5b 65 72   appropriate [er
33d40 72 6f 72 20 63 6f 64 65 5d 20 6f 72 0a 2a 2a 20  ror code] or.** 
33d50 5b 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20  [extended error 
33d60 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  code]..**.** ^Th
33d70 65 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69  e sqlite3_finali
33d80 7a 65 28 53 29 20 72 6f 75 74 69 6e 65 20 63 61  ze(S) routine ca
33d90 6e 20 62 65 20 63 61 6c 6c 65 64 20 61 74 20 61  n be called at a
33da0 6e 79 20 70 6f 69 6e 74 20 64 75 72 69 6e 67 0a  ny point during.
33db0 2a 2a 20 74 68 65 20 6c 69 66 65 20 63 79 63 6c  ** the life cycl
33dc0 65 20 6f 66 20 5b 70 72 65 70 61 72 65 64 20 73  e of [prepared s
33dd0 74 61 74 65 6d 65 6e 74 5d 20 53 3a 0a 2a 2a 20  tatement] S:.** 
33de0 62 65 66 6f 72 65 20 73 74 61 74 65 6d 65 6e 74  before statement
33df0 20 53 20 69 73 20 65 76 65 72 20 65 76 61 6c 75   S is ever evalu
33e00 61 74 65 64 2c 20 61 66 74 65 72 0a 2a 2a 20 6f  ated, after.** o
33e10 6e 65 20 6f 72 20 6d 6f 72 65 20 63 61 6c 6c 73  ne or more calls
33e20 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73   to [sqlite3_res
33e30 65 74 28 29 5d 2c 20 6f 72 20 61 66 74 65 72 20  et()], or after 
33e40 61 6e 79 20 63 61 6c 6c 0a 2a 2a 20 74 6f 20 5b  any call.** to [
33e50 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
33e60 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68  regardless of wh
33e70 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65  ether or not the
33e80 20 73 74 61 74 65 6d 65 6e 74 20 68 61 73 0a 2a   statement has.*
33e90 2a 20 63 6f 6d 70 6c 65 74 65 64 20 65 78 65 63  * completed exec
33ea0 75 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e  ution..**.** ^In
33eb0 76 6f 6b 69 6e 67 20 73 71 6c 69 74 65 33 5f 66  voking sqlite3_f
33ec0 69 6e 61 6c 69 7a 65 28 29 20 6f 6e 20 61 20 4e  inalize() on a N
33ed0 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 61  ULL pointer is a
33ee0 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e   harmless no-op.
33ef0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69  .**.** The appli
33f00 63 61 74 69 6f 6e 20 6d 75 73 74 20 66 69 6e 61  cation must fina
33f10 6c 69 7a 65 20 65 76 65 72 79 20 5b 70 72 65 70  lize every [prep
33f20 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
33f30 69 6e 20 6f 72 64 65 72 20 74 6f 20 61 76 6f 69  in order to avoi
33f40 64 0a 2a 2a 20 72 65 73 6f 75 72 63 65 20 6c 65  d.** resource le
33f50 61 6b 73 2e 20 20 49 74 20 69 73 20 61 20 67 72  aks.  It is a gr
33f60 69 65 76 6f 75 73 20 65 72 72 6f 72 20 66 6f 72  ievous error for
33f70 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
33f80 20 74 6f 20 74 72 79 20 74 6f 20 75 73 65 0a 2a   to try to use.*
33f90 2a 20 61 20 70 72 65 70 61 72 65 64 20 73 74 61  * a prepared sta
33fa0 74 65 6d 65 6e 74 20 61 66 74 65 72 20 69 74 20  tement after it 
33fb0 68 61 73 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a  has been finaliz
33fc0 65 64 2e 20 20 41 6e 79 20 75 73 65 20 6f 66 20  ed.  Any use of 
33fd0 61 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74  a prepared.** st
33fe0 61 74 65 6d 65 6e 74 20 61 66 74 65 72 20 69 74  atement after it
33ff0 20 68 61 73 20 62 65 65 6e 20 66 69 6e 61 6c 69   has been finali
34000 7a 65 64 20 63 61 6e 20 72 65 73 75 6c 74 20 69  zed can result i
34010 6e 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 0a  n undefined and.
34020 2a 2a 20 75 6e 64 65 73 69 72 61 62 6c 65 20 62  ** undesirable b
34030 65 68 61 76 69 6f 72 20 73 75 63 68 20 61 73 20  ehavior such as 
34040 73 65 67 66 61 75 6c 74 73 20 61 6e 64 20 68 65  segfaults and he
34050 61 70 20 63 6f 72 72 75 70 74 69 6f 6e 2e 0a 2a  ap corruption..*
34060 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 66 69  /.int sqlite3_fi
34070 6e 61 6c 69 7a 65 28 73 71 6c 69 74 65 33 5f 73  nalize(sqlite3_s
34080 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a  tmt *pStmt);../*
34090 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65  .** CAPI3REF: Re
340a0 73 65 74 20 41 20 50 72 65 70 61 72 65 64 20 53  set A Prepared S
340b0 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a  tatement Object.
340c0 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
340d0 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 54 68  e3_stmt.**.** Th
340e0 65 20 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28  e sqlite3_reset(
340f0 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 61  ) function is ca
34100 6c 6c 65 64 20 74 6f 20 72 65 73 65 74 20 61 20  lled to reset a 
34110 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
34120 65 6e 74 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 62  ent].** object b
34130 61 63 6b 20 74 6f 20 69 74 73 20 69 6e 69 74 69  ack to its initi
34140 61 6c 20 73 74 61 74 65 2c 20 72 65 61 64 79 20  al state, ready 
34150 74 6f 20 62 65 20 72 65 2d 65 78 65 63 75 74 65  to be re-execute
34160 64 2e 0a 2a 2a 20 5e 41 6e 79 20 53 51 4c 20 73  d..** ^Any SQL s
34170 74 61 74 65 6d 65 6e 74 20 76 61 72 69 61 62 6c  tatement variabl
34180 65 73 20 74 68 61 74 20 68 61 64 20 76 61 6c 75  es that had valu
34190 65 73 20 62 6f 75 6e 64 20 74 6f 20 74 68 65 6d  es bound to them
341a0 20 75 73 69 6e 67 0a 2a 2a 20 74 68 65 20 5b 73   using.** the [s
341b0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
341c0 20 7c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f   | sqlite3_bind_
341d0 2a 28 29 20 41 50 49 5d 20 72 65 74 61 69 6e 20  *() API] retain 
341e0 74 68 65 69 72 20 76 61 6c 75 65 73 2e 0a 2a 2a  their values..**
341f0 20 55 73 65 20 5b 73 71 6c 69 74 65 33 5f 63 6c   Use [sqlite3_cl
34200 65 61 72 5f 62 69 6e 64 69 6e 67 73 28 29 5d 20  ear_bindings()] 
34210 74 6f 20 72 65 73 65 74 20 74 68 65 20 62 69 6e  to reset the bin
34220 64 69 6e 67 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  dings..**.** ^Th
34230 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  e [sqlite3_reset
34240 28 53 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72  (S)] interface r
34250 65 73 65 74 73 20 74 68 65 20 5b 70 72 65 70 61  esets the [prepa
34260 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53  red statement] S
34270 0a 2a 2a 20 62 61 63 6b 20 74 6f 20 74 68 65 20  .** back to the 
34280 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 69 74 73  beginning of its
34290 20 70 72 6f 67 72 61 6d 2e 0a 2a 2a 0a 2a 2a 20   program..**.** 
342a0 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63  ^If the most rec
342b0 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  ent call to [sql
342c0 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 66 6f  ite3_step(S)] fo
342d0 72 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72  r the.** [prepar
342e0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20  ed statement] S 
342f0 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45  returned [SQLITE
34300 5f 52 4f 57 5d 20 6f 72 20 5b 53 51 4c 49 54 45  _ROW] or [SQLITE
34310 5f 44 4f 4e 45 5d 2c 0a 2a 2a 20 6f 72 20 69 66  _DONE],.** or if
34320 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53   [sqlite3_step(S
34330 29 5d 20 68 61 73 20 6e 65 76 65 72 20 62 65 66  )] has never bef
34340 6f 72 65 20 62 65 65 6e 20 63 61 6c 6c 65 64 20  ore been called 
34350 6f 6e 20 53 2c 0a 2a 2a 20 74 68 65 6e 20 5b 73  on S,.** then [s
34360 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d  qlite3_reset(S)]
34370 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
34380 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  _OK]..**.** ^If 
34390 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20  the most recent 
343a0 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
343b0 5f 73 74 65 70 28 53 29 5d 20 66 6f 72 20 74 68  _step(S)] for th
343c0 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73  e.** [prepared s
343d0 74 61 74 65 6d 65 6e 74 5d 20 53 20 69 6e 64 69  tatement] S indi
343e0 63 61 74 65 64 20 61 6e 20 65 72 72 6f 72 2c 20  cated an error, 
343f0 74 68 65 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  then.** [sqlite3
34400 5f 72 65 73 65 74 28 53 29 5d 20 72 65 74 75 72  _reset(S)] retur
34410 6e 73 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74  ns an appropriat
34420 65 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a  e [error code]..
34430 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69  **.** ^The [sqli
34440 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20 69 6e  te3_reset(S)] in
34450 74 65 72 66 61 63 65 20 64 6f 65 73 20 6e 6f 74  terface does not
34460 20 63 68 61 6e 67 65 20 74 68 65 20 76 61 6c 75   change the valu
34470 65 73 0a 2a 2a 20 6f 66 20 61 6e 79 20 5b 73 71  es.** of any [sq
34480 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c  lite3_bind_blob|
34490 62 69 6e 64 69 6e 67 73 5d 20 6f 6e 20 74 68 65  bindings] on the
344a0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
344b0 6d 65 6e 74 5d 20 53 2e 0a 2a 2f 0a 69 6e 74 20  ment] S..*/.int 
344c0 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 73 71  sqlite3_reset(sq
344d0 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d  lite3_stmt *pStm
344e0 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
344f0 52 45 46 3a 20 43 72 65 61 74 65 20 4f 72 20 52  REF: Create Or R
34500 65 64 65 66 69 6e 65 20 53 51 4c 20 46 75 6e 63  edefine SQL Func
34510 74 69 6f 6e 73 0a 2a 2a 20 4b 45 59 57 4f 52 44  tions.** KEYWORD
34520 53 3a 20 7b 66 75 6e 63 74 69 6f 6e 20 63 72 65  S: {function cre
34530 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 7d 0a  ation routines}.
34540 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61 70  ** KEYWORDS: {ap
34550 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
34560 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 7d 0a  d SQL function}.
34570 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61 70  ** KEYWORDS: {ap
34580 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
34590 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 7d  d SQL functions}
345a0 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
345b0 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65  te3.**.** ^These
345c0 20 66 75 6e 63 74 69 6f 6e 73 20 28 63 6f 6c 6c   functions (coll
345d0 65 63 74 69 76 65 6c 79 20 6b 6e 6f 77 6e 20 61  ectively known a
345e0 73 20 22 66 75 6e 63 74 69 6f 6e 20 63 72 65 61  s "function crea
345f0 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 22 29 0a  tion routines").
34600 2a 2a 20 61 72 65 20 75 73 65 64 20 74 6f 20 61  ** are used to a
34610 64 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  dd SQL functions
34620 20 6f 72 20 61 67 67 72 65 67 61 74 65 73 20 6f   or aggregates o
34630 72 20 74 6f 20 72 65 64 65 66 69 6e 65 20 74 68  r to redefine th
34640 65 20 62 65 68 61 76 69 6f 72 0a 2a 2a 20 6f 66  e behavior.** of
34650 20 65 78 69 73 74 69 6e 67 20 53 51 4c 20 66 75   existing SQL fu
34660 6e 63 74 69 6f 6e 73 20 6f 72 20 61 67 67 72 65  nctions or aggre
34670 67 61 74 65 73 2e 20 20 54 68 65 20 6f 6e 6c 79  gates.  The only
34680 20 64 69 66 66 65 72 65 6e 63 65 73 20 62 65 74   differences bet
34690 77 65 65 6e 0a 2a 2a 20 74 68 65 73 65 20 72 6f  ween.** these ro
346a0 75 74 69 6e 65 73 20 61 72 65 20 74 68 65 20 74  utines are the t
346b0 65 78 74 20 65 6e 63 6f 64 69 6e 67 20 65 78 70  ext encoding exp
346c0 65 63 74 65 64 20 66 6f 72 0a 2a 2a 20 74 68 65  ected for.** the
346d0 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
346e0 72 20 28 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  r (the name of t
346f0 68 65 20 66 75 6e 63 74 69 6f 6e 20 62 65 69 6e  he function bein
34700 67 20 63 72 65 61 74 65 64 29 0a 2a 2a 20 61 6e  g created).** an
34710 64 20 74 68 65 20 70 72 65 73 65 6e 63 65 20 6f  d the presence o
34720 72 20 61 62 73 65 6e 63 65 20 6f 66 20 61 20 64  r absence of a d
34730 65 73 74 72 75 63 74 6f 72 20 63 61 6c 6c 62 61  estructor callba
34740 63 6b 20 66 6f 72 0a 2a 2a 20 74 68 65 20 61 70  ck for.** the ap
34750 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20 70  plication data p
34760 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ointer..**.** ^T
34770 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
34780 65 72 20 69 73 20 74 68 65 20 5b 64 61 74 61 62  er is the [datab
34790 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
347a0 74 6f 20 77 68 69 63 68 20 74 68 65 20 53 51 4c  to which the SQL
347b0 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  .** function is 
347c0 74 6f 20 62 65 20 61 64 64 65 64 2e 20 20 5e 49  to be added.  ^I
347d0 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  f an application
347e0 20 75 73 65 73 20 6d 6f 72 65 20 74 68 61 6e 20   uses more than 
347f0 6f 6e 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  one database.** 
34800 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 65 6e 20  connection then 
34810 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
34820 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ned SQL function
34830 73 20 6d 75 73 74 20 62 65 20 61 64 64 65 64 0a  s must be added.
34840 2a 2a 20 74 6f 20 65 61 63 68 20 64 61 74 61 62  ** to each datab
34850 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73  ase connection s
34860 65 70 61 72 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a  eparately..**.**
34870 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72   ^The second par
34880 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 6e 61  ameter is the na
34890 6d 65 20 6f 66 20 74 68 65 20 53 51 4c 20 66 75  me of the SQL fu
348a0 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 63 72 65  nction to be cre
348b0 61 74 65 64 20 6f 72 0a 2a 2a 20 72 65 64 65 66  ated or.** redef
348c0 69 6e 65 64 2e 20 20 5e 54 68 65 20 6c 65 6e 67  ined.  ^The leng
348d0 74 68 20 6f 66 20 74 68 65 20 6e 61 6d 65 20 69  th of the name i
348e0 73 20 6c 69 6d 69 74 65 64 20 74 6f 20 32 35 35  s limited to 255
348f0 20 62 79 74 65 73 20 69 6e 20 61 20 55 54 46 2d   bytes in a UTF-
34900 38 0a 2a 2a 20 72 65 70 72 65 73 65 6e 74 61 74  8.** representat
34910 69 6f 6e 2c 20 65 78 63 6c 75 73 69 76 65 20 6f  ion, exclusive o
34920 66 20 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d 69  f the zero-termi
34930 6e 61 74 6f 72 2e 20 20 5e 4e 6f 74 65 20 74 68  nator.  ^Note th
34940 61 74 20 74 68 65 20 6e 61 6d 65 0a 2a 2a 20 6c  at the name.** l
34950 65 6e 67 74 68 20 6c 69 6d 69 74 20 69 73 20 69  ength limit is i
34960 6e 20 55 54 46 2d 38 20 62 79 74 65 73 2c 20 6e  n UTF-8 bytes, n
34970 6f 74 20 63 68 61 72 61 63 74 65 72 73 20 6e 6f  ot characters no
34980 72 20 55 54 46 2d 31 36 20 62 79 74 65 73 2e 20  r UTF-16 bytes. 
34990 20 0a 2a 2a 20 5e 41 6e 79 20 61 74 74 65 6d 70   .** ^Any attemp
349a0 74 20 74 6f 20 63 72 65 61 74 65 20 61 20 66 75  t to create a fu
349b0 6e 63 74 69 6f 6e 20 77 69 74 68 20 61 20 6c 6f  nction with a lo
349c0 6e 67 65 72 20 6e 61 6d 65 0a 2a 2a 20 77 69 6c  nger name.** wil
349d0 6c 20 72 65 73 75 6c 74 20 69 6e 20 5b 53 51 4c  l result in [SQL
349e0 49 54 45 5f 4d 49 53 55 53 45 5d 20 62 65 69 6e  ITE_MISUSE] bein
349f0 67 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a  g returned..**.*
34a00 2a 20 5e 54 68 65 20 74 68 69 72 64 20 70 61 72  * ^The third par
34a10 61 6d 65 74 65 72 20 28 6e 41 72 67 29 0a 2a 2a  ameter (nArg).**
34a20 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   is the number o
34a30 66 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74  f arguments that
34a40 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f   the SQL functio
34a50 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74  n or.** aggregat
34a60 65 20 74 61 6b 65 73 2e 20 5e 49 66 20 74 68 69  e takes. ^If thi
34a70 73 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 2d  s parameter is -
34a80 31 2c 20 74 68 65 6e 20 74 68 65 20 53 51 4c 20  1, then the SQL 
34a90 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61  function or.** a
34aa0 67 67 72 65 67 61 74 65 20 6d 61 79 20 74 61 6b  ggregate may tak
34ab0 65 20 61 6e 79 20 6e 75 6d 62 65 72 20 6f 66 20  e any number of 
34ac0 61 72 67 75 6d 65 6e 74 73 20 62 65 74 77 65 65  arguments betwee
34ad0 6e 20 30 20 61 6e 64 20 74 68 65 20 6c 69 6d 69  n 0 and the limi
34ae0 74 0a 2a 2a 20 73 65 74 20 62 79 20 5b 73 71 6c  t.** set by [sql
34af0 69 74 65 33 5f 6c 69 6d 69 74 5d 28 5b 53 51 4c  ite3_limit]([SQL
34b00 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49  ITE_LIMIT_FUNCTI
34b10 4f 4e 5f 41 52 47 5d 29 2e 20 20 49 66 20 74 68  ON_ARG]).  If th
34b20 65 20 74 68 69 72 64 0a 2a 2a 20 70 61 72 61 6d  e third.** param
34b30 65 74 65 72 20 69 73 20 6c 65 73 73 20 74 68 61  eter is less tha
34b40 6e 20 2d 31 20 6f 72 20 67 72 65 61 74 65 72 20  n -1 or greater 
34b50 74 68 61 6e 20 31 32 37 20 74 68 65 6e 20 74 68  than 127 then th
34b60 65 20 62 65 68 61 76 69 6f 72 20 69 73 0a 2a 2a  e behavior is.**
34b70 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a   undefined..**.*
34b80 2a 20 5e 54 68 65 20 66 6f 75 72 74 68 20 70 61  * ^The fourth pa
34b90 72 61 6d 65 74 65 72 2c 20 65 54 65 78 74 52 65  rameter, eTextRe
34ba0 70 2c 20 73 70 65 63 69 66 69 65 73 20 77 68 61  p, specifies wha
34bb0 74 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46  t.** [SQLITE_UTF
34bc0 38 20 7c 20 74 65 78 74 20 65 6e 63 6f 64 69 6e  8 | text encodin
34bd0 67 5d 20 74 68 69 73 20 53 51 4c 20 66 75 6e 63  g] this SQL func
34be0 74 69 6f 6e 20 70 72 65 66 65 72 73 20 66 6f 72  tion prefers for
34bf0 0a 2a 2a 20 69 74 73 20 70 61 72 61 6d 65 74 65  .** its paramete
34c00 72 73 2e 20 20 54 68 65 20 61 70 70 6c 69 63 61  rs.  The applica
34c10 74 69 6f 6e 20 73 68 6f 75 6c 64 20 73 65 74 20  tion should set 
34c20 74 68 69 73 20 70 61 72 61 6d 65 74 65 72 20 74  this parameter t
34c30 6f 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46  o.** [SQLITE_UTF
34c40 31 36 4c 45 5d 20 69 66 20 74 68 65 20 66 75 6e  16LE] if the fun
34c50 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61  ction implementa
34c60 74 69 6f 6e 20 69 6e 76 6f 6b 65 73 20 0a 2a 2a  tion invokes .**
34c70 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
34c80 74 65 78 74 31 36 6c 65 28 29 5d 20 6f 6e 20 61  text16le()] on a
34c90 6e 20 69 6e 70 75 74 2c 20 6f 72 20 5b 53 51 4c  n input, or [SQL
34ca0 49 54 45 5f 55 54 46 31 36 42 45 5d 20 69 66 20  ITE_UTF16BE] if 
34cb0 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74  the.** implement
34cc0 61 74 69 6f 6e 20 69 6e 76 6f 6b 65 73 20 5b 73  ation invokes [s
34cd0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
34ce0 74 31 36 62 65 28 29 5d 20 6f 6e 20 61 6e 20 69  t16be()] on an i
34cf0 6e 70 75 74 2c 20 6f 72 0a 2a 2a 20 5b 53 51 4c  nput, or.** [SQL
34d00 49 54 45 5f 55 54 46 31 36 5d 20 69 66 20 5b 73  ITE_UTF16] if [s
34d10 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
34d20 74 31 36 28 29 5d 20 69 73 20 75 73 65 64 2c 20  t16()] is used, 
34d30 6f 72 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d  or [SQLITE_UTF8]
34d40 0a 2a 2a 20 6f 74 68 65 72 77 69 73 65 2e 20 20  .** otherwise.  
34d50 5e 54 68 65 20 73 61 6d 65 20 53 51 4c 20 66 75  ^The same SQL fu
34d60 6e 63 74 69 6f 6e 20 6d 61 79 20 62 65 20 72 65  nction may be re
34d70 67 69 73 74 65 72 65 64 20 6d 75 6c 74 69 70 6c  gistered multipl
34d80 65 20 74 69 6d 65 73 20 75 73 69 6e 67 0a 2a 2a  e times using.**
34d90 20 64 69 66 66 65 72 65 6e 74 20 70 72 65 66 65   different prefe
34da0 72 72 65 64 20 74 65 78 74 20 65 6e 63 6f 64 69  rred text encodi
34db0 6e 67 73 2c 20 77 69 74 68 20 64 69 66 66 65 72  ngs, with differ
34dc0 65 6e 74 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ent implementati
34dd0 6f 6e 73 20 66 6f 72 0a 2a 2a 20 65 61 63 68 20  ons for.** each 
34de0 65 6e 63 6f 64 69 6e 67 2e 0a 2a 2a 20 5e 57 68  encoding..** ^Wh
34df0 65 6e 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c  en multiple impl
34e00 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74  ementations of t
34e10 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e  he same function
34e20 20 61 72 65 20 61 76 61 69 6c 61 62 6c 65 2c 20   are available, 
34e30 53 51 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c 20 70  SQLite.** will p
34e40 69 63 6b 20 74 68 65 20 6f 6e 65 20 74 68 61 74  ick the one that
34e50 20 69 6e 76 6f 6c 76 65 73 20 74 68 65 20 6c 65   involves the le
34e60 61 73 74 20 61 6d 6f 75 6e 74 20 6f 66 20 64 61  ast amount of da
34e70 74 61 20 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a  ta conversion..*
34e80 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 72 74 68  *.** ^The fourth
34e90 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 6f   parameter may o
34ea0 70 74 69 6f 6e 61 6c 6c 79 20 62 65 20 4f 52 65  ptionally be ORe
34eb0 64 20 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 44  d with [SQLITE_D
34ec0 45 54 45 52 4d 49 4e 49 53 54 49 43 5d 0a 2a 2a  ETERMINISTIC].**
34ed0 20 74 6f 20 73 69 67 6e 61 6c 20 74 68 61 74 20   to signal that 
34ee0 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 77 69 6c  the function wil
34ef0 6c 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 20  l always return 
34f00 74 68 65 20 73 61 6d 65 20 72 65 73 75 6c 74 20  the same result 
34f10 67 69 76 65 6e 0a 2a 2a 20 74 68 65 20 73 61 6d  given.** the sam
34f20 65 20 69 6e 70 75 74 73 20 77 69 74 68 69 6e 20  e inputs within 
34f30 61 20 73 69 6e 67 6c 65 20 53 51 4c 20 73 74 61  a single SQL sta
34f40 74 65 6d 65 6e 74 2e 20 20 4d 6f 73 74 20 53 51  tement.  Most SQ
34f50 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 0a  L functions are.
34f60 2a 2a 20 64 65 74 65 72 6d 69 6e 69 73 74 69 63  ** deterministic
34f70 2e 20 20 54 68 65 20 62 75 69 6c 74 2d 69 6e 20  .  The built-in 
34f80 5b 72 61 6e 64 6f 6d 28 29 5d 20 53 51 4c 20 66  [random()] SQL f
34f90 75 6e 63 74 69 6f 6e 20 69 73 20 61 6e 20 65 78  unction is an ex
34fa0 61 6d 70 6c 65 20 6f 66 20 61 0a 2a 2a 20 66 75  ample of a.** fu
34fb0 6e 63 74 69 6f 6e 20 74 68 61 74 20 69 73 20 6e  nction that is n
34fc0 6f 74 20 64 65 74 65 72 6d 69 6e 69 73 74 69 63  ot deterministic
34fd0 2e 20 20 54 68 65 20 53 51 4c 69 74 65 20 71 75  .  The SQLite qu
34fe0 65 72 79 20 70 6c 61 6e 6e 65 72 20 69 73 20 61  ery planner is a
34ff0 62 6c 65 20 74 6f 0a 2a 2a 20 70 65 72 66 6f 72  ble to.** perfor
35000 6d 20 61 64 64 69 74 69 6f 6e 61 6c 20 6f 70 74  m additional opt
35010 69 6d 69 7a 61 74 69 6f 6e 73 20 6f 6e 20 64 65  imizations on de
35020 74 65 72 6d 69 6e 69 73 74 69 63 20 66 75 6e 63  terministic func
35030 74 69 6f 6e 73 2c 20 73 6f 20 75 73 65 0a 2a 2a  tions, so use.**
35040 20 6f 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f   of the [SQLITE_
35050 44 45 54 45 52 4d 49 4e 49 53 54 49 43 5d 20 66  DETERMINISTIC] f
35060 6c 61 67 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64  lag is recommend
35070 65 64 20 77 68 65 72 65 20 70 6f 73 73 69 62 6c  ed where possibl
35080 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 66  e..**.** ^(The f
35090 69 66 74 68 20 70 61 72 61 6d 65 74 65 72 20 69  ifth parameter i
350a0 73 20 61 6e 20 61 72 62 69 74 72 61 72 79 20 70  s an arbitrary p
350b0 6f 69 6e 74 65 72 2e 20 20 54 68 65 20 69 6d 70  ointer.  The imp
350c0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74  lementation of t
350d0 68 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 63  he.** function c
350e0 61 6e 20 67 61 69 6e 20 61 63 63 65 73 73 20 74  an gain access t
350f0 6f 20 74 68 69 73 20 70 6f 69 6e 74 65 72 20 75  o this pointer u
35100 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 75 73  sing [sqlite3_us
35110 65 72 5f 64 61 74 61 28 29 5d 2e 29 5e 0a 2a 2a  er_data()].)^.**
35120 0a 2a 2a 20 5e 54 68 65 20 73 69 78 74 68 2c 20  .** ^The sixth, 
35130 73 65 76 65 6e 74 68 20 61 6e 64 20 65 69 67 68  seventh and eigh
35140 74 68 20 70 61 72 61 6d 65 74 65 72 73 2c 20 78  th parameters, x
35150 46 75 6e 63 2c 20 78 53 74 65 70 20 61 6e 64 20  Func, xStep and 
35160 78 46 69 6e 61 6c 2c 20 61 72 65 0a 2a 2a 20 70  xFinal, are.** p
35170 6f 69 6e 74 65 72 73 20 74 6f 20 43 2d 6c 61 6e  ointers to C-lan
35180 67 75 61 67 65 20 66 75 6e 63 74 69 6f 6e 73 20  guage functions 
35190 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 20 74  that implement t
351a0 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  he SQL function 
351b0 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 2e  or.** aggregate.
351c0 20 5e 41 20 73 63 61 6c 61 72 20 53 51 4c 20 66   ^A scalar SQL f
351d0 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65 73  unction requires
351e0 20 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69   an implementati
351f0 6f 6e 20 6f 66 20 74 68 65 20 78 46 75 6e 63 0a  on of the xFunc.
35200 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 6f 6e 6c 79  ** callback only
35210 3b 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73 20  ; NULL pointers 
35220 6d 75 73 74 20 62 65 20 70 61 73 73 65 64 20 61  must be passed a
35230 73 20 74 68 65 20 78 53 74 65 70 20 61 6e 64 20  s the xStep and 
35240 78 46 69 6e 61 6c 0a 2a 2a 20 70 61 72 61 6d 65  xFinal.** parame
35250 74 65 72 73 2e 20 5e 41 6e 20 61 67 67 72 65 67  ters. ^An aggreg
35260 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ate SQL function
35270 20 72 65 71 75 69 72 65 73 20 61 6e 20 69 6d 70   requires an imp
35280 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 78  lementation of x
35290 53 74 65 70 0a 2a 2a 20 61 6e 64 20 78 46 69 6e  Step.** and xFin
352a0 61 6c 20 61 6e 64 20 4e 55 4c 4c 20 70 6f 69 6e  al and NULL poin
352b0 74 65 72 20 6d 75 73 74 20 62 65 20 70 61 73 73  ter must be pass
352c0 65 64 20 66 6f 72 20 78 46 75 6e 63 2e 20 5e 54  ed for xFunc. ^T
352d0 6f 20 64 65 6c 65 74 65 20 61 6e 20 65 78 69 73  o delete an exis
352e0 74 69 6e 67 0a 2a 2a 20 53 51 4c 20 66 75 6e 63  ting.** SQL func
352f0 74 69 6f 6e 20 6f 72 20 61 67 67 72 65 67 61 74  tion or aggregat
35300 65 2c 20 70 61 73 73 20 4e 55 4c 4c 20 70 6f 69  e, pass NULL poi
35310 6e 74 65 72 73 20 66 6f 72 20 61 6c 6c 20 74 68  nters for all th
35320 72 65 65 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20  ree function.** 
35330 63 61 6c 6c 62 61 63 6b 73 2e 0a 2a 2a 0a 2a 2a  callbacks..**.**
35340 20 5e 28 49 66 20 74 68 65 20 6e 69 6e 74 68 20   ^(If the ninth 
35350 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
35360 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
35370 74 69 6f 6e 5f 76 32 28 29 20 69 73 20 6e 6f 74  tion_v2() is not
35380 20 4e 55 4c 4c 2c 0a 2a 2a 20 74 68 65 6e 20 69   NULL,.** then i
35390 74 20 69 73 20 64 65 73 74 72 75 63 74 6f 72 20  t is destructor 
353a0 66 6f 72 20 74 68 65 20 61 70 70 6c 69 63 61 74  for the applicat
353b0 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74 65 72  ion data pointer
353c0 2e 20 0a 2a 2a 20 54 68 65 20 64 65 73 74 72 75  . .** The destru
353d0 63 74 6f 72 20 69 73 20 69 6e 76 6f 6b 65 64 20  ctor is invoked 
353e0 77 68 65 6e 20 74 68 65 20 66 75 6e 63 74 69 6f  when the functio
353f0 6e 20 69 73 20 64 65 6c 65 74 65 64 2c 20 65 69  n is deleted, ei
35400 74 68 65 72 20 62 79 20 62 65 69 6e 67 0a 2a 2a  ther by being.**
35410 20 6f 76 65 72 6c 6f 61 64 65 64 20 6f 72 20 77   overloaded or w
35420 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65  hen the database
35430 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f 73   connection clos
35440 65 73 2e 29 5e 0a 2a 2a 20 5e 54 68 65 20 64 65  es.)^.** ^The de
35450 73 74 72 75 63 74 6f 72 20 69 73 20 61 6c 73 6f  structor is also
35460 20 69 6e 76 6f 6b 65 64 20 69 66 20 74 68 65 20   invoked if the 
35470 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c 69 74  call to.** sqlit
35480 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
35490 6f 6e 5f 76 32 28 29 20 66 61 69 6c 73 2e 0a 2a  on_v2() fails..*
354a0 2a 20 5e 57 68 65 6e 20 74 68 65 20 64 65 73 74  * ^When the dest
354b0 72 75 63 74 6f 72 20 63 61 6c 6c 62 61 63 6b 20  ructor callback 
354c0 6f 66 20 74 68 65 20 74 65 6e 74 68 20 70 61 72  of the tenth par
354d0 61 6d 65 74 65 72 20 69 73 20 69 6e 76 6f 6b 65  ameter is invoke
354e0 64 2c 20 69 74 0a 2a 2a 20 69 73 20 70 61 73 73  d, it.** is pass
354f0 65 64 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75  ed a single argu
35500 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20  ment which is a 
35510 63 6f 70 79 20 6f 66 20 74 68 65 20 61 70 70 6c  copy of the appl
35520 69 63 61 74 69 6f 6e 20 64 61 74 61 20 0a 2a 2a  ication data .**
35530 20 70 6f 69 6e 74 65 72 20 77 68 69 63 68 20 77   pointer which w
35540 61 73 20 74 68 65 20 66 69 66 74 68 20 70 61 72  as the fifth par
35550 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
35560 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
35570 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 49  n_v2()..**.** ^I
35580 74 20 69 73 20 70 65 72 6d 69 74 74 65 64 20 74  t is permitted t
35590 6f 20 72 65 67 69 73 74 65 72 20 6d 75 6c 74 69  o register multi
355a0 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ple implementati
355b0 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65 0a  ons of the same.
355c0 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20 77 69 74  ** functions wit
355d0 68 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 20  h the same name 
355e0 62 75 74 20 77 69 74 68 20 65 69 74 68 65 72 20  but with either 
355f0 64 69 66 66 65 72 69 6e 67 20 6e 75 6d 62 65 72  differing number
35600 73 20 6f 66 0a 2a 2a 20 61 72 67 75 6d 65 6e 74  s of.** argument
35610 73 20 6f 72 20 64 69 66 66 65 72 69 6e 67 20 70  s or differing p
35620 72 65 66 65 72 72 65 64 20 74 65 78 74 20 65 6e  referred text en
35630 63 6f 64 69 6e 67 73 2e 20 20 5e 53 51 4c 69 74  codings.  ^SQLit
35640 65 20 77 69 6c 6c 20 75 73 65 0a 2a 2a 20 74 68  e will use.** th
35650 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
35660 20 74 68 61 74 20 6d 6f 73 74 20 63 6c 6f 73 65   that most close
35670 6c 79 20 6d 61 74 63 68 65 73 20 74 68 65 20 77  ly matches the w
35680 61 79 20 69 6e 20 77 68 69 63 68 20 74 68 65 0a  ay in which the.
35690 2a 2a 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  ** SQL function 
356a0 69 73 20 75 73 65 64 2e 20 20 5e 41 20 66 75 6e  is used.  ^A fun
356b0 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61  ction implementa
356c0 74 69 6f 6e 20 77 69 74 68 20 61 20 6e 6f 6e 2d  tion with a non-
356d0 6e 65 67 61 74 69 76 65 0a 2a 2a 20 6e 41 72 67  negative.** nArg
356e0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20   parameter is a 
356f0 62 65 74 74 65 72 20 6d 61 74 63 68 20 74 68 61  better match tha
35700 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70  n a function imp
35710 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 74 68  lementation with
35720 0a 2a 2a 20 61 20 6e 65 67 61 74 69 76 65 20 6e  .** a negative n
35730 41 72 67 2e 20 20 5e 41 20 66 75 6e 63 74 69 6f  Arg.  ^A functio
35740 6e 20 77 68 65 72 65 20 74 68 65 20 70 72 65 66  n where the pref
35750 65 72 72 65 64 20 74 65 78 74 20 65 6e 63 6f 64  erred text encod
35760 69 6e 67 0a 2a 2a 20 6d 61 74 63 68 65 73 20 74  ing.** matches t
35770 68 65 20 64 61 74 61 62 61 73 65 20 65 6e 63 6f  he database enco
35780 64 69 6e 67 20 69 73 20 61 20 62 65 74 74 65 72  ding is a better
35790 0a 2a 2a 20 6d 61 74 63 68 20 74 68 61 6e 20 61  .** match than a
357a0 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20   function where 
357b0 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 69 73 20  the encoding is 
357c0 64 69 66 66 65 72 65 6e 74 2e 20 20 0a 2a 2a 20  different.  .** 
357d0 5e 41 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72  ^A function wher
357e0 65 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 64  e the encoding d
357f0 69 66 66 65 72 65 6e 63 65 20 69 73 20 62 65 74  ifference is bet
35800 77 65 65 6e 20 55 54 46 31 36 6c 65 20 61 6e 64  ween UTF16le and
35810 20 55 54 46 31 36 62 65 0a 2a 2a 20 69 73 20 61   UTF16be.** is a
35820 20 63 6c 6f 73 65 72 20 6d 61 74 63 68 20 74 68   closer match th
35830 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 68  an a function wh
35840 65 72 65 20 74 68 65 20 65 6e 63 6f 64 69 6e 67  ere the encoding
35850 20 64 69 66 66 65 72 65 6e 63 65 20 69 73 0a 2a   difference is.*
35860 2a 20 62 65 74 77 65 65 6e 20 55 54 46 38 20 61  * between UTF8 a
35870 6e 64 20 55 54 46 31 36 2e 0a 2a 2a 0a 2a 2a 20  nd UTF16..**.** 
35880 5e 42 75 69 6c 74 2d 69 6e 20 66 75 6e 63 74 69  ^Built-in functi
35890 6f 6e 73 20 6d 61 79 20 62 65 20 6f 76 65 72 6c  ons may be overl
358a0 6f 61 64 65 64 20 62 79 20 6e 65 77 20 61 70 70  oaded by new app
358b0 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
358c0 20 66 75 6e 63 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a   functions..**.*
358d0 2a 20 5e 41 6e 20 61 70 70 6c 69 63 61 74 69 6f  * ^An applicatio
358e0 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
358f0 6f 6e 20 69 73 20 70 65 72 6d 69 74 74 65 64 20  on is permitted 
35900 74 6f 20 63 61 6c 6c 20 6f 74 68 65 72 0a 2a 2a  to call other.**
35910 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63   SQLite interfac
35920 65 73 2e 20 20 48 6f 77 65 76 65 72 2c 20 73 75  es.  However, su
35930 63 68 20 63 61 6c 6c 73 20 6d 75 73 74 20 6e 6f  ch calls must no
35940 74 0a 2a 2a 20 63 6c 6f 73 65 20 74 68 65 20 64  t.** close the d
35950 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
35960 6f 6e 20 6e 6f 72 20 66 69 6e 61 6c 69 7a 65 20  on nor finalize 
35970 6f 72 20 72 65 73 65 74 20 74 68 65 20 70 72 65  or reset the pre
35980 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65  pared.** stateme
35990 6e 74 20 69 6e 20 77 68 69 63 68 20 74 68 65 20  nt in which the 
359a0 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e  function is runn
359b0 69 6e 67 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ing..*/.int sqli
359c0 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
359d0 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  ion(.  sqlite3 *
359e0 64 62 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61 72  db,.  const char
359f0 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c   *zFunctionName,
35a00 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69  .  int nArg,.  i
35a10 6e 74 20 65 54 65 78 74 52 65 70 2c 0a 20 20 76  nt eTextRep,.  v
35a20 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69  oid *pApp,.  voi
35a30 64 20 28 2a 78 46 75 6e 63 29 28 73 71 6c 69 74  d (*xFunc)(sqlit
35a40 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c  e3_context*,int,
35a50 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29  sqlite3_value**)
35a60 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53 74 65 70  ,.  void (*xStep
35a70 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  )(sqlite3_contex
35a80 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76  t*,int,sqlite3_v
35a90 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20  alue**),.  void 
35aa0 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69 74 65  (*xFinal)(sqlite
35ab0 33 5f 63 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a 69  3_context*).);.i
35ac0 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  nt sqlite3_creat
35ad0 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 0a 20 20  e_function16(.  
35ae0 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20 63  sqlite3 *db,.  c
35af0 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 46 75 6e 63  onst void *zFunc
35b00 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20  tionName,.  int 
35b10 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65 54 65 78  nArg,.  int eTex
35b20 74 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41  tRep,.  void *pA
35b30 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 75  pp,.  void (*xFu
35b40 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  nc)(sqlite3_cont
35b50 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33  ext*,int,sqlite3
35b60 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69  _value**),.  voi
35b70 64 20 28 2a 78 53 74 65 70 29 28 73 71 6c 69 74  d (*xStep)(sqlit
35b80 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c  e3_context*,int,
35b90 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29  sqlite3_value**)
35ba0 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 69 6e 61  ,.  void (*xFina
35bb0 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  l)(sqlite3_conte
35bc0 78 74 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69  xt*).);.int sqli
35bd0 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
35be0 69 6f 6e 5f 76 32 28 0a 20 20 73 71 6c 69 74 65  ion_v2(.  sqlite
35bf0 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20 63  3 *db,.  const c
35c00 68 61 72 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61  har *zFunctionNa
35c10 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a  me,.  int nArg,.
35c20 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 0a    int eTextRep,.
35c30 20 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20    void *pApp,.  
35c40 76 6f 69 64 20 28 2a 78 46 75 6e 63 29 28 73 71  void (*xFunc)(sq
35c50 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69  lite3_context*,i
35c60 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt,sqlite3_value
35c70 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53  **),.  void (*xS
35c80 74 65 70 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e  tep)(sqlite3_con
35c90 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65  text*,int,sqlite
35ca0 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f  3_value**),.  vo
35cb0 69 64 20 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c  id (*xFinal)(sql
35cc0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 2c 0a  ite3_context*),.
35cd0 20 20 76 6f 69 64 28 2a 78 44 65 73 74 72 6f 79    void(*xDestroy
35ce0 29 28 76 6f 69 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a  )(void*).);../*.
35cf0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 65 78  ** CAPI3REF: Tex
35d00 74 20 45 6e 63 6f 64 69 6e 67 73 0a 2a 2a 0a 2a  t Encodings.**.*
35d10 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74  * These constant
35d20 20 64 65 66 69 6e 65 20 69 6e 74 65 67 65 72 20   define integer 
35d30 63 6f 64 65 73 20 74 68 61 74 20 72 65 70 72 65  codes that repre
35d40 73 65 6e 74 20 74 68 65 20 76 61 72 69 6f 75 73  sent the various
35d50 0a 2a 2a 20 74 65 78 74 20 65 6e 63 6f 64 69 6e  .** text encodin
35d60 67 73 20 73 75 70 70 6f 72 74 65 64 20 62 79 20  gs supported by 
35d70 53 51 4c 69 74 65 2e 0a 2a 2f 0a 23 64 65 66 69  SQLite..*/.#defi
35d80 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 38 20 20  ne SQLITE_UTF8  
35d90 20 20 20 20 20 20 20 20 20 31 20 20 20 20 2f 2a           1    /*
35da0 20 49 4d 50 3a 20 52 2d 33 37 35 31 34 2d 33 35   IMP: R-37514-35
35db0 35 36 36 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  566 */.#define S
35dc0 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 20 20 20  QLITE_UTF16LE   
35dd0 20 20 20 20 20 32 20 20 20 20 2f 2a 20 49 4d 50       2    /* IMP
35de0 3a 20 52 2d 30 33 33 37 31 2d 33 37 36 33 37 20  : R-03371-37637 
35df0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
35e00 45 5f 55 54 46 31 36 42 45 20 20 20 20 20 20 20  E_UTF16BE       
35e10 20 33 20 20 20 20 2f 2a 20 49 4d 50 3a 20 52 2d   3    /* IMP: R-
35e20 35 31 39 37 31 2d 33 34 31 35 34 20 2a 2f 0a 23  51971-34154 */.#
35e30 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54  define SQLITE_UT
35e40 46 31 36 20 20 20 20 20 20 20 20 20 20 34 20 20  F16          4  
35e50 20 20 2f 2a 20 55 73 65 20 6e 61 74 69 76 65 20    /* Use native 
35e60 62 79 74 65 20 6f 72 64 65 72 20 2a 2f 0a 23 64  byte order */.#d
35e70 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4e 59  efine SQLITE_ANY
35e80 20 20 20 20 20 20 20 20 20 20 20 20 35 20 20 20              5   
35e90 20 2f 2a 20 44 65 70 72 65 63 61 74 65 64 20 2a   /* Deprecated *
35ea0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
35eb0 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45 44 20 20  _UTF16_ALIGNED  
35ec0 38 20 20 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f  8    /* sqlite3_
35ed0 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
35ee0 20 6f 6e 6c 79 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20   only */../*.** 
35ef0 43 41 50 49 33 52 45 46 3a 20 46 75 6e 63 74 69  CAPI3REF: Functi
35f00 6f 6e 20 46 6c 61 67 73 0a 2a 2a 0a 2a 2a 20 54  on Flags.**.** T
35f10 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 6d  hese constants m
35f20 61 79 20 62 65 20 4f 52 65 64 20 74 6f 67 65 74  ay be ORed toget
35f30 68 65 72 20 77 69 74 68 20 74 68 65 20 0a 2a 2a  her with the .**
35f40 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 20 7c 20   [SQLITE_UTF8 | 
35f50 70 72 65 66 65 72 72 65 64 20 74 65 78 74 20 65  preferred text e
35f60 6e 63 6f 64 69 6e 67 5d 20 61 73 20 74 68 65 20  ncoding] as the 
35f70 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 0a  fourth argument.
35f80 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  ** to [sqlite3_c
35f90 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29  reate_function()
35fa0 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  ], [sqlite3_crea
35fb0 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d  te_function16()]
35fc0 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  , or.** [sqlite3
35fd0 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
35fe0 5f 76 32 28 29 5d 2e 0a 2a 2f 0a 23 64 65 66 69  _v2()]..*/.#defi
35ff0 6e 65 20 53 51 4c 49 54 45 5f 44 45 54 45 52 4d  ne SQLITE_DETERM
36000 49 4e 49 53 54 49 43 20 20 20 20 30 78 38 30 30  INISTIC    0x800
36010 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
36020 3a 20 44 65 70 72 65 63 61 74 65 64 20 46 75 6e  : Deprecated Fun
36030 63 74 69 6f 6e 73 0a 2a 2a 20 44 45 50 52 45 43  ctions.** DEPREC
36040 41 54 45 44 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ATED.**.** These
36050 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 20 5b   functions are [
36060 64 65 70 72 65 63 61 74 65 64 5d 2e 20 20 49 6e  deprecated].  In
36070 20 6f 72 64 65 72 20 74 6f 20 6d 61 69 6e 74 61   order to mainta
36080 69 6e 0a 2a 2a 20 62 61 63 6b 77 61 72 64 73 20  in.** backwards 
36090 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 77 69  compatibility wi
360a0 74 68 20 6f 6c 64 65 72 20 63 6f 64 65 2c 20 74  th older code, t
360b0 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 63  hese functions c
360c0 6f 6e 74 69 6e 75 65 20 0a 2a 2a 20 74 6f 20 62  ontinue .** to b
360d0 65 20 73 75 70 70 6f 72 74 65 64 2e 20 20 48 6f  e supported.  Ho
360e0 77 65 76 65 72 2c 20 6e 65 77 20 61 70 70 6c 69  wever, new appli
360f0 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 61  cations should a
36100 76 6f 69 64 0a 2a 2a 20 74 68 65 20 75 73 65 20  void.** the use 
36110 6f 66 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f  of these functio
36120 6e 73 2e 20 20 54 6f 20 65 6e 63 6f 75 72 61 67  ns.  To encourag
36130 65 20 70 72 6f 67 72 61 6d 6d 65 72 73 20 74 6f  e programmers to
36140 20 61 76 6f 69 64 0a 2a 2a 20 74 68 65 73 65 20   avoid.** these 
36150 66 75 6e 63 74 69 6f 6e 73 2c 20 77 65 20 77 69  functions, we wi
36160 6c 6c 20 6e 6f 74 20 65 78 70 6c 61 69 6e 20 77  ll not explain w
36170 68 61 74 20 74 68 65 79 20 64 6f 2e 0a 2a 2f 0a  hat they do..*/.
36180 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 4f  #ifndef SQLITE_O
36190 4d 49 54 5f 44 45 50 52 45 43 41 54 45 44 0a 53  MIT_DEPRECATED.S
361a0 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44  QLITE_DEPRECATED
361b0 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 61 67 67   int sqlite3_agg
361c0 72 65 67 61 74 65 5f 63 6f 75 6e 74 28 73 71 6c  regate_count(sql
361d0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a  ite3_context*);.
361e0 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45  SQLITE_DEPRECATE
361f0 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78  D int sqlite3_ex
36200 70 69 72 65 64 28 73 71 6c 69 74 65 33 5f 73 74  pired(sqlite3_st
36210 6d 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50  mt*);.SQLITE_DEP
36220 52 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69  RECATED int sqli
36230 74 65 33 5f 74 72 61 6e 73 66 65 72 5f 62 69 6e  te3_transfer_bin
36240 64 69 6e 67 73 28 73 71 6c 69 74 65 33 5f 73 74  dings(sqlite3_st
36250 6d 74 2a 2c 20 73 71 6c 69 74 65 33 5f 73 74 6d  mt*, sqlite3_stm
36260 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52  t*);.SQLITE_DEPR
36270 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74  ECATED int sqlit
36280 65 33 5f 67 6c 6f 62 61 6c 5f 72 65 63 6f 76 65  e3_global_recove
36290 72 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f  r(void);.SQLITE_
362a0 44 45 50 52 45 43 41 54 45 44 20 76 6f 69 64 20  DEPRECATED void 
362b0 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 5f 63  sqlite3_thread_c
362c0 6c 65 61 6e 75 70 28 76 6f 69 64 29 3b 0a 53 51  leanup(void);.SQ
362d0 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20  LITE_DEPRECATED 
362e0 69 6e 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  int sqlite3_memo
362f0 72 79 5f 61 6c 61 72 6d 28 76 6f 69 64 28 2a 29  ry_alarm(void(*)
36300 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 5f 69  (void*,sqlite3_i
36310 6e 74 36 34 2c 69 6e 74 29 2c 0a 20 20 20 20 20  nt64,int),.     
36320 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
36330 20 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 5f 69   void*,sqlite3_i
36340 6e 74 36 34 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f  nt64);.#endif../
36350 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f  *.** CAPI3REF: O
36360 62 74 61 69 6e 69 6e 67 20 53 51 4c 20 56 61 6c  btaining SQL Val
36370 75 65 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  ues.** METHOD: s
36380 71 6c 69 74 65 33 5f 76 61 6c 75 65 0a 2a 2a 0a  qlite3_value.**.
36390 2a 2a 20 54 68 65 20 43 2d 6c 61 6e 67 75 61 67  ** The C-languag
363a0 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
363b0 20 6f 66 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e   of SQL function
363c0 73 20 61 6e 64 20 61 67 67 72 65 67 61 74 65 73  s and aggregates
363d0 20 75 73 65 73 0a 2a 2a 20 74 68 69 73 20 73 65   uses.** this se
363e0 74 20 6f 66 20 69 6e 74 65 72 66 61 63 65 20 72  t of interface r
363f0 6f 75 74 69 6e 65 73 20 74 6f 20 61 63 63 65 73  outines to acces
36400 73 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20  s the parameter 
36410 76 61 6c 75 65 73 20 6f 6e 0a 2a 2a 20 74 68 65  values on.** the
36420 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67   function or agg
36430 72 65 67 61 74 65 2e 20 20 0a 2a 2a 0a 2a 2a 20  regate.  .**.** 
36440 54 68 65 20 78 46 75 6e 63 20 28 66 6f 72 20 73  The xFunc (for s
36450 63 61 6c 61 72 20 66 75 6e 63 74 69 6f 6e 73 29  calar functions)
36460 20 6f 72 20 78 53 74 65 70 20 28 66 6f 72 20 61   or xStep (for a
36470 67 67 72 65 67 61 74 65 73 29 20 70 61 72 61 6d  ggregates) param
36480 65 74 65 72 73 0a 2a 2a 20 74 6f 20 5b 73 71 6c  eters.** to [sql
36490 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
364a0 74 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c  tion()] and [sql
364b0 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
364c0 74 69 6f 6e 31 36 28 29 5d 0a 2a 2a 20 64 65 66  tion16()].** def
364d0 69 6e 65 20 63 61 6c 6c 62 61 63 6b 73 20 74 68  ine callbacks th
364e0 61 74 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65  at implement the
364f0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61   SQL functions a
36500 6e 64 20 61 67 67 72 65 67 61 74 65 73 2e 0a 2a  nd aggregates..*
36510 2a 20 54 68 65 20 33 72 64 20 70 61 72 61 6d 65  * The 3rd parame
36520 74 65 72 20 74 6f 20 74 68 65 73 65 20 63 61 6c  ter to these cal
36530 6c 62 61 63 6b 73 20 69 73 20 61 6e 20 61 72 72  lbacks is an arr
36540 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74  ay of pointers t
36550 6f 0a 2a 2a 20 5b 70 72 6f 74 65 63 74 65 64 20  o.** [protected 
36560 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
36570 62 6a 65 63 74 73 2e 20 20 54 68 65 72 65 20 69  bjects.  There i
36580 73 20 6f 6e 65 20 5b 73 71 6c 69 74 65 33 5f 76  s one [sqlite3_v
36590 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 66 6f 72  alue] object for
365a0 0a 2a 2a 20 65 61 63 68 20 70 61 72 61 6d 65 74  .** each paramet
365b0 65 72 20 74 6f 20 74 68 65 20 53 51 4c 20 66 75  er to the SQL fu
365c0 6e 63 74 69 6f 6e 2e 20 20 54 68 65 73 65 20 72  nction.  These r
365d0 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73 65 64  outines are used
365e0 20 74 6f 0a 2a 2a 20 65 78 74 72 61 63 74 20 76   to.** extract v
365f0 61 6c 75 65 73 20 66 72 6f 6d 20 74 68 65 20 5b  alues from the [
36600 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
36610 62 6a 65 63 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  bjects..**.** Th
36620 65 73 65 20 72 6f 75 74 69 6e 65 73 20 77 6f 72  ese routines wor
36630 6b 20 6f 6e 6c 79 20 77 69 74 68 20 5b 70 72 6f  k only with [pro
36640 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
36650 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a  alue] objects..*
36660 2a 20 41 6e 79 20 61 74 74 65 6d 70 74 20 74 6f  * Any attempt to
36670 20 75 73 65 20 74 68 65 73 65 20 72 6f 75 74 69   use these routi
36680 6e 65 73 20 6f 6e 20 61 6e 20 5b 75 6e 70 72 6f  nes on an [unpro
36690 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
366a0 61 6c 75 65 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20  alue].** object 
366b0 72 65 73 75 6c 74 73 20 69 6e 20 75 6e 64 65 66  results in undef
366c0 69 6e 65 64 20 62 65 68 61 76 69 6f 72 2e 0a 2a  ined behavior..*
366d0 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74  *.** ^These rout
366e0 69 6e 65 73 20 77 6f 72 6b 20 6a 75 73 74 20 6c  ines work just l
366f0 69 6b 65 20 74 68 65 20 63 6f 72 72 65 73 70 6f  ike the correspo
36700 6e 64 69 6e 67 20 5b 63 6f 6c 75 6d 6e 20 61 63  nding [column ac
36710 63 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 5d 0a  cess functions].
36720 2a 2a 20 65 78 63 65 70 74 20 74 68 61 74 20 74  ** except that t
36730 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 74 61  hese routines ta
36740 6b 65 20 61 20 73 69 6e 67 6c 65 20 5b 70 72 6f  ke a single [pro
36750 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
36760 61 6c 75 65 5d 20 6f 62 6a 65 63 74 0a 2a 2a 20  alue] object.** 
36770 70 6f 69 6e 74 65 72 20 69 6e 73 74 65 61 64 20  pointer instead 
36780 6f 66 20 61 20 5b 73 71 6c 69 74 65 33 5f 73 74  of a [sqlite3_st
36790 6d 74 2a 5d 20 70 6f 69 6e 74 65 72 20 61 6e 64  mt*] pointer and
367a0 20 61 6e 20 69 6e 74 65 67 65 72 20 63 6f 6c 75   an integer colu
367b0 6d 6e 20 6e 75 6d 62 65 72 2e 0a 2a 2a 0a 2a 2a  mn number..**.**
367c0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61   ^The sqlite3_va
367d0 6c 75 65 5f 74 65 78 74 31 36 28 29 20 69 6e 74  lue_text16() int
367e0 65 72 66 61 63 65 20 65 78 74 72 61 63 74 73 20  erface extracts 
367f0 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 0a  a UTF-16 string.
36800 2a 2a 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65  ** in the native
36810 20 62 79 74 65 2d 6f 72 64 65 72 20 6f 66 20 74   byte-order of t
36820 68 65 20 68 6f 73 74 20 6d 61 63 68 69 6e 65 2e  he host machine.
36830 20 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65    ^The.** sqlite
36840 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 62 65  3_value_text16be
36850 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 76  () and sqlite3_v
36860 61 6c 75 65 5f 74 65 78 74 31 36 6c 65 28 29 20  alue_text16le() 
36870 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 65 78  interfaces.** ex
36880 74 72 61 63 74 20 55 54 46 2d 31 36 20 73 74 72  tract UTF-16 str
36890 69 6e 67 73 20 61 73 20 62 69 67 2d 65 6e 64 69  ings as big-endi
368a0 61 6e 20 61 6e 64 20 6c 69 74 74 6c 65 2d 65 6e  an and little-en
368b0 64 69 61 6e 20 72 65 73 70 65 63 74 69 76 65 6c  dian respectivel
368c0 79 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 73  y..**.** ^(The s
368d0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 6e 75 6d  qlite3_value_num
368e0 65 72 69 63 5f 74 79 70 65 28 29 20 69 6e 74 65  eric_type() inte
368f0 72 66 61 63 65 20 61 74 74 65 6d 70 74 73 20 74  rface attempts t
36900 6f 20 61 70 70 6c 79 0a 2a 2a 20 6e 75 6d 65 72  o apply.** numer
36910 69 63 20 61 66 66 69 6e 69 74 79 20 74 6f 20 74  ic affinity to t
36920 68 65 20 76 61 6c 75 65 2e 20 20 54 68 69 73 20  he value.  This 
36930 6d 65 61 6e 73 20 74 68 61 74 20 61 6e 20 61 74  means that an at
36940 74 65 6d 70 74 20 69 73 0a 2a 2a 20 6d 61 64 65  tempt is.** made
36950 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 65 20   to convert the 
36960 76 61 6c 75 65 20 74 6f 20 61 6e 20 69 6e 74 65  value to an inte
36970 67 65 72 20 6f 72 20 66 6c 6f 61 74 69 6e 67 20  ger or floating 
36980 70 6f 69 6e 74 2e 20 20 49 66 0a 2a 2a 20 73 75  point.  If.** su
36990 63 68 20 61 20 63 6f 6e 76 65 72 73 69 6f 6e 20  ch a conversion 
369a0 69 73 20 70 6f 73 73 69 62 6c 65 20 77 69 74 68  is possible with
369b0 6f 75 74 20 6c 6f 73 73 20 6f 66 20 69 6e 66 6f  out loss of info
369c0 72 6d 61 74 69 6f 6e 20 28 69 6e 20 6f 74 68 65  rmation (in othe
369d0 72 0a 2a 2a 20 77 6f 72 64 73 2c 20 69 66 20 74  r.** words, if t
369e0 68 65 20 76 61 6c 75 65 20 69 73 20 61 20 73 74  he value is a st
369f0 72 69 6e 67 20 74 68 61 74 20 6c 6f 6f 6b 73 20  ring that looks 
36a00 6c 69 6b 65 20 61 20 6e 75 6d 62 65 72 29 0a 2a  like a number).*
36a10 2a 20 74 68 65 6e 20 74 68 65 20 63 6f 6e 76 65  * then the conve
36a20 72 73 69 6f 6e 20 69 73 20 70 65 72 66 6f 72 6d  rsion is perform
36a30 65 64 2e 20 20 4f 74 68 65 72 77 69 73 65 20 6e  ed.  Otherwise n
36a40 6f 20 63 6f 6e 76 65 72 73 69 6f 6e 20 6f 63 63  o conversion occ
36a50 75 72 73 2e 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  urs..** The [SQL
36a60 49 54 45 5f 49 4e 54 45 47 45 52 20 7c 20 64 61  ITE_INTEGER | da
36a70 74 61 74 79 70 65 5d 20 61 66 74 65 72 20 63 6f  tatype] after co
36a80 6e 76 65 72 73 69 6f 6e 20 69 73 20 72 65 74 75  nversion is retu
36a90 72 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 50 6c  rned.)^.**.** Pl
36aa0 65 61 73 65 20 70 61 79 20 70 61 72 74 69 63 75  ease pay particu
36ab0 6c 61 72 20 61 74 74 65 6e 74 69 6f 6e 20 74 6f  lar attention to
36ac0 20 74 68 65 20 66 61 63 74 20 74 68 61 74 20 74   the fact that t
36ad0 68 65 20 70 6f 69 6e 74 65 72 20 72 65 74 75 72  he pointer retur
36ae0 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c  ned.** from [sql
36af0 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28  ite3_value_blob(
36b00 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  )], [sqlite3_val
36b10 75 65 5f 74 65 78 74 28 29 5d 2c 20 6f 72 0a 2a  ue_text()], or.*
36b20 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  * [sqlite3_value
36b30 5f 74 65 78 74 31 36 28 29 5d 20 63 61 6e 20 62  _text16()] can b
36b40 65 20 69 6e 76 61 6c 69 64 61 74 65 64 20 62 79  e invalidated by
36b50 20 61 20 73 75 62 73 65 71 75 65 6e 74 20 63 61   a subsequent ca
36b60 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  ll to.** [sqlite
36b70 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 29 5d  3_value_bytes()]
36b80 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  , [sqlite3_value
36b90 5f 62 79 74 65 73 31 36 28 29 5d 2c 20 5b 73 71  _bytes16()], [sq
36ba0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
36bb0 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69  ()],.** or [sqli
36bc0 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36  te3_value_text16
36bd0 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ()]..**.** These
36be0 20 72 6f 75 74 69 6e 65 73 20 6d 75 73 74 20 62   routines must b
36bf0 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68  e called from th
36c00 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 61 73  e same thread as
36c10 0a 2a 2a 20 74 68 65 20 53 51 4c 20 66 75 6e 63  .** the SQL func
36c20 74 69 6f 6e 20 74 68 61 74 20 73 75 70 70 6c 69  tion that suppli
36c30 65 64 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  ed the [sqlite3_
36c40 76 61 6c 75 65 2a 5d 20 70 61 72 61 6d 65 74 65  value*] paramete
36c50 72 73 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 76 6f 69  rs..*/.const voi
36c60 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  d *sqlite3_value
36c70 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 76 61  _blob(sqlite3_va
36c80 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74  lue*);.int sqlit
36c90 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 73  e3_value_bytes(s
36ca0 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
36cb0 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  int sqlite3_valu
36cc0 65 5f 62 79 74 65 73 31 36 28 73 71 6c 69 74 65  e_bytes16(sqlite
36cd0 33 5f 76 61 6c 75 65 2a 29 3b 0a 64 6f 75 62 6c  3_value*);.doubl
36ce0 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  e sqlite3_value_
36cf0 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 76  double(sqlite3_v
36d00 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69  alue*);.int sqli
36d10 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28 73 71  te3_value_int(sq
36d20 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 73  lite3_value*);.s
36d30 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c  qlite3_int64 sql
36d40 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 36 34  ite3_value_int64
36d50 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
36d60 3b 0a 63 6f 6e 73 74 20 75 6e 73 69 67 6e 65 64  ;.const unsigned
36d70 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 76   char *sqlite3_v
36d80 61 6c 75 65 5f 74 65 78 74 28 73 71 6c 69 74 65  alue_text(sqlite
36d90 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74  3_value*);.const
36da0 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76   void *sqlite3_v
36db0 61 6c 75 65 5f 74 65 78 74 31 36 28 73 71 6c 69  alue_text16(sqli
36dc0 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e  te3_value*);.con
36dd0 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
36de0 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 6c 65 28  _value_text16le(
36df0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
36e00 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  .const void *sql
36e10 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31  ite3_value_text1
36e20 36 62 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  6be(sqlite3_valu
36e30 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  e*);.int sqlite3
36e40 5f 76 61 6c 75 65 5f 74 79 70 65 28 73 71 6c 69  _value_type(sqli
36e50 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74  te3_value*);.int
36e60 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 6e   sqlite3_value_n
36e70 75 6d 65 72 69 63 5f 74 79 70 65 28 73 71 6c 69  umeric_type(sqli
36e80 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 0a 2f 2a  te3_value*);../*
36e90 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 69  .** CAPI3REF: Fi
36ea0 6e 64 69 6e 67 20 54 68 65 20 53 75 62 74 79 70  nding The Subtyp
36eb0 65 20 4f 66 20 53 51 4c 20 56 61 6c 75 65 73 0a  e Of SQL Values.
36ec0 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
36ed0 65 33 5f 76 61 6c 75 65 0a 2a 2a 0a 2a 2a 20 54  e3_value.**.** T
36ee0 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  he sqlite3_value
36ef0 5f 73 75 62 74 79 70 65 28 56 29 20 66 75 6e 63  _subtype(V) func
36f00 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65  tion returns the
36f10 20 73 75 62 74 79 70 65 20 66 6f 72 0a 2a 2a 20   subtype for.** 
36f20 61 6e 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d  an [application-
36f30 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63  defined SQL func
36f40 74 69 6f 6e 5d 20 61 72 67 75 6d 65 6e 74 20 56  tion] argument V
36f50 2e 20 20 54 68 65 20 73 75 62 74 79 70 65 0a 2a  .  The subtype.*
36f60 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 63 61  * information ca
36f70 6e 20 62 65 20 75 73 65 64 20 74 6f 20 70 61 73  n be used to pas
36f80 73 20 61 20 6c 69 6d 69 74 65 64 20 61 6d 6f 75  s a limited amou
36f90 6e 74 20 6f 66 20 63 6f 6e 74 65 78 74 20 66 72  nt of context fr
36fa0 6f 6d 0a 2a 2a 20 6f 6e 65 20 53 51 4c 20 66 75  om.** one SQL fu
36fb0 6e 63 74 69 6f 6e 20 74 6f 20 61 6e 6f 74 68 65  nction to anothe
36fc0 72 2e 20 20 55 73 65 20 74 68 65 20 5b 73 71 6c  r.  Use the [sql
36fd0 69 74 65 33 5f 72 65 73 75 6c 74 5f 73 75 62 74  ite3_result_subt
36fe0 79 70 65 28 29 5d 0a 2a 2a 20 72 6f 75 74 69 6e  ype()].** routin
36ff0 65 20 74 6f 20 73 65 74 20 74 68 65 20 73 75 62  e to set the sub
37000 74 79 70 65 20 66 6f 72 20 74 68 65 20 72 65 74  type for the ret
37010 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 61 6e 20  urn value of an 
37020 53 51 4c 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a  SQL function..**
37030 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 61 6b 65 73  .** SQLite makes
37040 20 6e 6f 20 75 73 65 20 6f 66 20 73 75 62 74 79   no use of subty
37050 70 65 20 69 74 73 65 6c 66 2e 20 20 49 74 20 6d  pe itself.  It m
37060 65 72 65 6c 79 20 70 61 73 73 65 73 20 74 68 65  erely passes the
37070 20 73 75 62 74 79 70 65 0a 2a 2a 20 66 72 6f 6d   subtype.** from
37080 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66 20 6f   the result of o
37090 6e 65 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d  ne [application-
370a0 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63  defined SQL func
370b0 74 69 6f 6e 5d 20 69 6e 74 6f 20 74 68 65 0a 2a  tion] into the.*
370c0 2a 20 69 6e 70 75 74 20 6f 66 20 61 6e 6f 74 68  * input of anoth
370d0 65 72 2e 0a 2a 2f 0a 75 6e 73 69 67 6e 65 64 20  er..*/.unsigned 
370e0 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  int sqlite3_valu
370f0 65 5f 73 75 62 74 79 70 65 28 73 71 6c 69 74 65  e_subtype(sqlite
37100 33 5f 76 61 6c 75 65 2a 29 3b 0a 0a 2f 2a 0a 2a  3_value*);../*.*
37110 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 70 79  * CAPI3REF: Copy
37120 20 41 6e 64 20 46 72 65 65 20 53 51 4c 20 56 61   And Free SQL Va
37130 6c 75 65 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  lues.** METHOD: 
37140 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 0a 2a 2a  sqlite3_value.**
37150 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
37160 5f 76 61 6c 75 65 5f 64 75 70 28 56 29 20 69 6e  _value_dup(V) in
37170 74 65 72 66 61 63 65 20 6d 61 6b 65 73 20 61 20  terface makes a 
37180 63 6f 70 79 20 6f 66 20 74 68 65 20 5b 73 71 6c  copy of the [sql
37190 69 74 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20 6f  ite3_value].** o
371a0 62 6a 65 63 74 20 44 20 61 6e 64 20 72 65 74 75  bject D and retu
371b0 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
371c0 20 74 68 61 74 20 63 6f 70 79 2e 20 20 5e 54 68   that copy.  ^Th
371d0 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  e [sqlite3_value
371e0 5d 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 69 73  ] returned.** is
371f0 20 61 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71   a [protected sq
37200 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
37210 65 63 74 20 65 76 65 6e 20 69 66 20 74 68 65 20  ect even if the 
37220 69 6e 70 75 74 20 69 73 20 6e 6f 74 2e 0a 2a 2a  input is not..**
37230 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61   ^The sqlite3_va
37240 6c 75 65 5f 64 75 70 28 56 29 20 69 6e 74 65 72  lue_dup(V) inter
37250 66 61 63 65 20 72 65 74 75 72 6e 73 20 4e 55 4c  face returns NUL
37260 4c 20 69 66 20 56 20 69 73 20 4e 55 4c 4c 20 6f  L if V is NULL o
37270 72 20 69 66 20 61 0a 2a 2a 20 6d 65 6d 6f 72 79  r if a.** memory
37280 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c   allocation fail
37290 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  s..**.** ^The sq
372a0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 66 72 65 65  lite3_value_free
372b0 28 56 29 20 69 6e 74 65 72 66 61 63 65 20 66 72  (V) interface fr
372c0 65 65 73 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f  ees an [sqlite3_
372d0 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 0a 2a 2a  value] object.**
372e0 20 70 72 65 76 69 6f 75 73 6c 79 20 6f 62 74 61   previously obta
372f0 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74  ined from [sqlit
37300 65 33 5f 76 61 6c 75 65 5f 64 75 70 28 29 5d 2e  e3_value_dup()].
37310 20 20 5e 49 66 20 56 20 69 73 20 61 20 4e 55 4c    ^If V is a NUL
37320 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 68 65  L pointer.** the
37330 6e 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  n sqlite3_value_
37340 66 72 65 65 28 56 29 20 69 73 20 61 20 68 61 72  free(V) is a har
37350 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2f 0a  mless no-op..*/.
37360 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 2a 73  sqlite3_value *s
37370 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 64 75 70  qlite3_value_dup
37380 28 63 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f 76  (const sqlite3_v
37390 61 6c 75 65 2a 29 3b 0a 76 6f 69 64 20 73 71 6c  alue*);.void sql
373a0 69 74 65 33 5f 76 61 6c 75 65 5f 66 72 65 65 28  ite3_value_free(
373b0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
373c0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
373d0 3a 20 4f 62 74 61 69 6e 20 41 67 67 72 65 67 61  : Obtain Aggrega
373e0 74 65 20 46 75 6e 63 74 69 6f 6e 20 43 6f 6e 74  te Function Cont
373f0 65 78 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  ext.** METHOD: s
37400 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 0a 2a  qlite3_context.*
37410 2a 0a 2a 2a 20 49 6d 70 6c 65 6d 65 6e 74 61 74  *.** Implementat
37420 69 6f 6e 73 20 6f 66 20 61 67 67 72 65 67 61 74  ions of aggregat
37430 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20  e SQL functions 
37440 75 73 65 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74  use this.** rout
37450 69 6e 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20  ine to allocate 
37460 6d 65 6d 6f 72 79 20 66 6f 72 20 73 74 6f 72 69  memory for stori
37470 6e 67 20 74 68 65 69 72 20 73 74 61 74 65 2e 0a  ng their state..
37480 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74  **.** ^The first
37490 20 74 69 6d 65 20 74 68 65 20 73 71 6c 69 74 65   time the sqlite
374a0 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74  3_aggregate_cont
374b0 65 78 74 28 43 2c 4e 29 20 72 6f 75 74 69 6e 65  ext(C,N) routine
374c0 20 69 73 20 63 61 6c 6c 65 64 20 0a 2a 2a 20 66   is called .** f
374d0 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61 72 20  or a particular 
374e0 61 67 67 72 65 67 61 74 65 20 66 75 6e 63 74 69  aggregate functi
374f0 6f 6e 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6c  on, SQLite.** al
37500 6c 6f 63 61 74 65 73 20 4e 20 6f 66 20 6d 65 6d  locates N of mem
37510 6f 72 79 2c 20 7a 65 72 6f 65 73 20 6f 75 74 20  ory, zeroes out 
37520 74 68 61 74 20 6d 65 6d 6f 72 79 2c 20 61 6e 64  that memory, and
37530 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
37540 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 6e 65 77  er.** to the new
37550 20 6d 65 6d 6f 72 79 2e 20 5e 4f 6e 20 73 65 63   memory. ^On sec
37560 6f 6e 64 20 61 6e 64 20 73 75 62 73 65 71 75 65  ond and subseque
37570 6e 74 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 73  nt calls to.** s
37580 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65  qlite3_aggregate
37590 5f 63 6f 6e 74 65 78 74 28 29 20 66 6f 72 20 74  _context() for t
375a0 68 65 20 73 61 6d 65 20 61 67 67 72 65 67 61 74  he same aggregat
375b0 65 20 66 75 6e 63 74 69 6f 6e 20 69 6e 73 74 61  e function insta
375c0 6e 63 65 2c 0a 2a 2a 20 74 68 65 20 73 61 6d 65  nce,.** the same
375d0 20 62 75 66 66 65 72 20 69 73 20 72 65 74 75 72   buffer is retur
375e0 6e 65 64 2e 20 20 53 71 6c 69 74 65 33 5f 61 67  ned.  Sqlite3_ag
375f0 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28  gregate_context(
37600 29 20 69 73 20 6e 6f 72 6d 61 6c 6c 79 0a 2a 2a  ) is normally.**
37610 20 63 61 6c 6c 65 64 20 6f 6e 63 65 20 66 6f 72   called once for
37620 20 65 61 63 68 20 69 6e 76 6f 63 61 74 69 6f 6e   each invocation
37630 20 6f 66 20 74 68 65 20 78 53 74 65 70 20 63 61   of the xStep ca
37640 6c 6c 62 61 63 6b 20 61 6e 64 20 74 68 65 6e 20  llback and then 
37650 6f 6e 65 0a 2a 2a 20 6c 61 73 74 20 74 69 6d 65  one.** last time
37660 20 77 68 65 6e 20 74 68 65 20 78 46 69 6e 61 6c   when the xFinal
37670 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76   callback is inv
37680 6f 6b 65 64 2e 20 20 5e 28 57 68 65 6e 20 6e 6f  oked.  ^(When no
37690 20 72 6f 77 73 20 6d 61 74 63 68 0a 2a 2a 20 61   rows match.** a
376a0 6e 20 61 67 67 72 65 67 61 74 65 20 71 75 65 72  n aggregate quer
376b0 79 2c 20 74 68 65 20 78 53 74 65 70 28 29 20 63  y, the xStep() c
376c0 61 6c 6c 62 61 63 6b 20 6f 66 20 74 68 65 20 61  allback of the a
376d0 67 67 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f  ggregate functio
376e0 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74  n.** implementat
376f0 69 6f 6e 20 69 73 20 6e 65 76 65 72 20 63 61 6c  ion is never cal
37700 6c 65 64 20 61 6e 64 20 78 46 69 6e 61 6c 28 29  led and xFinal()
37710 20 69 73 20 63 61 6c 6c 65 64 20 65 78 61 63 74   is called exact
37720 6c 79 20 6f 6e 63 65 2e 0a 2a 2a 20 49 6e 20 74  ly once..** In t
37730 68 6f 73 65 20 63 61 73 65 73 2c 20 73 71 6c 69  hose cases, sqli
37740 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f  te3_aggregate_co
37750 6e 74 65 78 74 28 29 20 6d 69 67 68 74 20 62 65  ntext() might be
37760 20 63 61 6c 6c 65 64 20 66 6f 72 20 74 68 65 0a   called for the.
37770 2a 2a 20 66 69 72 73 74 20 74 69 6d 65 20 66 72  ** first time fr
37780 6f 6d 20 77 69 74 68 69 6e 20 78 46 69 6e 61 6c  om within xFinal
37790 28 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ().)^.**.** ^The
377a0 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61   sqlite3_aggrega
377b0 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20  te_context(C,N) 
377c0 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
377d0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 0a  a NULL pointer .
377e0 2a 2a 20 77 68 65 6e 20 66 69 72 73 74 20 63 61  ** when first ca
377f0 6c 6c 65 64 20 69 66 20 4e 20 69 73 20 6c 65 73  lled if N is les
37800 73 20 74 68 61 6e 20 6f 72 20 65 71 75 61 6c 20  s than or equal 
37810 74 6f 20 7a 65 72 6f 20 6f 72 20 69 66 20 61 20  to zero or if a 
37820 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61  memory.** alloca
37830 74 65 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2e  te error occurs.
37840 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 61 6d 6f  .**.** ^(The amo
37850 75 6e 74 20 6f 66 20 73 70 61 63 65 20 61 6c 6c  unt of space all
37860 6f 63 61 74 65 64 20 62 79 20 73 71 6c 69 74 65  ocated by sqlite
37870 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74  3_aggregate_cont
37880 65 78 74 28 43 2c 4e 29 20 69 73 0a 2a 2a 20 64  ext(C,N) is.** d
37890 65 74 65 72 6d 69 6e 65 64 20 62 79 20 74 68 65  etermined by the
378a0 20 4e 20 70 61 72 61 6d 65 74 65 72 20 6f 6e 20   N parameter on 
378b0 66 69 72 73 74 20 73 75 63 63 65 73 73 66 75 6c  first successful
378c0 20 63 61 6c 6c 2e 20 20 43 68 61 6e 67 69 6e 67   call.  Changing
378d0 20 74 68 65 0a 2a 2a 20 76 61 6c 75 65 20 6f 66   the.** value of
378e0 20 4e 20 69 6e 20 73 75 62 73 65 71 75 65 6e 74   N in subsequent
378f0 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33   call to sqlite3
37900 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65  _aggregate_conte
37910 78 74 28 29 20 77 69 74 68 69 6e 0a 2a 2a 20 74  xt() within.** t
37920 68 65 20 73 61 6d 65 20 61 67 67 72 65 67 61 74  he same aggregat
37930 65 20 66 75 6e 63 74 69 6f 6e 20 69 6e 73 74 61  e function insta
37940 6e 63 65 20 77 69 6c 6c 20 6e 6f 74 20 72 65 73  nce will not res
37950 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79 0a 2a  ize the memory.*
37960 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e 2e 29 5e 20  * allocation.)^ 
37970 20 57 69 74 68 69 6e 20 74 68 65 20 78 46 69 6e   Within the xFin
37980 61 6c 20 63 61 6c 6c 62 61 63 6b 2c 20 69 74 20  al callback, it 
37990 69 73 20 63 75 73 74 6f 6d 61 72 79 20 74 6f 20  is customary to 
379a0 73 65 74 0a 2a 2a 20 4e 3d 30 20 69 6e 20 63 61  set.** N=0 in ca
379b0 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 61  lls to sqlite3_a
379c0 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74  ggregate_context
379d0 28 43 2c 4e 29 20 73 6f 20 74 68 61 74 20 6e 6f  (C,N) so that no
379e0 20 0a 2a 2a 20 70 6f 69 6e 74 6c 65 73 73 20 6d   .** pointless m
379f0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
37a00 73 20 6f 63 63 75 72 2e 0a 2a 2a 0a 2a 2a 20 5e  s occur..**.** ^
37a10 53 51 4c 69 74 65 20 61 75 74 6f 6d 61 74 69 63  SQLite automatic
37a20 61 6c 6c 79 20 66 72 65 65 73 20 74 68 65 20 6d  ally frees the m
37a30 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 65 64 20  emory allocated 
37a40 62 79 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 61  by .** sqlite3_a
37a50 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74  ggregate_context
37a60 28 29 20 77 68 65 6e 20 74 68 65 20 61 67 67 72  () when the aggr
37a70 65 67 61 74 65 20 71 75 65 72 79 20 63 6f 6e 63  egate query conc
37a80 6c 75 64 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ludes..**.** The
37a90 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
37aa0 20 6d 75 73 74 20 62 65 20 61 20 63 6f 70 79 20   must be a copy 
37ab0 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  of the.** [sqlit
37ac0 65 33 5f 63 6f 6e 74 65 78 74 20 7c 20 53 51 4c  e3_context | SQL
37ad0 20 66 75 6e 63 74 69 6f 6e 20 63 6f 6e 74 65 78   function contex
37ae0 74 5d 20 74 68 61 74 20 69 73 20 74 68 65 20 66  t] that is the f
37af0 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 0a 2a  irst parameter.*
37b00 2a 20 74 6f 20 74 68 65 20 78 53 74 65 70 20 6f  * to the xStep o
37b10 72 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63  r xFinal callbac
37b20 6b 20 72 6f 75 74 69 6e 65 20 74 68 61 74 20 69  k routine that i
37b30 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65 20 61 67  mplements the ag
37b40 67 72 65 67 61 74 65 0a 2a 2a 20 66 75 6e 63 74  gregate.** funct
37b50 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  ion..**.** This 
37b60 72 6f 75 74 69 6e 65 20 6d 75 73 74 20 62 65 20  routine must be 
37b70 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20  called from the 
37b80 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e 20 77  same thread in w
37b90 68 69 63 68 0a 2a 2a 20 74 68 65 20 61 67 67 72  hich.** the aggr
37ba0 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69  egate SQL functi
37bb0 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a  on is running..*
37bc0 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  /.void *sqlite3_
37bd0 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78  aggregate_contex
37be0 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  t(sqlite3_contex
37bf0 74 2a 2c 20 69 6e 74 20 6e 42 79 74 65 73 29 3b  t*, int nBytes);
37c00 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
37c10 3a 20 55 73 65 72 20 44 61 74 61 20 46 6f 72 20  : User Data For 
37c20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 4d 45 54  Functions.** MET
37c30 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 63 6f 6e  HOD: sqlite3_con
37c40 74 65 78 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  text.**.** ^The 
37c50 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74  sqlite3_user_dat
37c60 61 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  a() interface re
37c70 74 75 72 6e 73 20 61 20 63 6f 70 79 20 6f 66 0a  turns a copy of.
37c80 2a 2a 20 74 68 65 20 70 6f 69 6e 74 65 72 20 74  ** the pointer t
37c90 68 61 74 20 77 61 73 20 74 68 65 20 70 55 73 65  hat was the pUse
37ca0 72 44 61 74 61 20 70 61 72 61 6d 65 74 65 72 20  rData parameter 
37cb0 28 74 68 65 20 35 74 68 20 70 61 72 61 6d 65 74  (the 5th paramet
37cc0 65 72 29 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73  er).** of the [s
37cd0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
37ce0 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61 6e 64  nction()].** and
37cf0 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
37d00 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 20 72  _function16()] r
37d10 6f 75 74 69 6e 65 73 20 74 68 61 74 20 6f 72 69  outines that ori
37d20 67 69 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67 69 73  ginally.** regis
37d30 74 65 72 65 64 20 74 68 65 20 61 70 70 6c 69 63  tered the applic
37d40 61 74 69 6f 6e 20 64 65 66 69 6e 65 64 20 66 75  ation defined fu
37d50 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68  nction..**.** Th
37d60 69 73 20 72 6f 75 74 69 6e 65 20 6d 75 73 74 20  is routine must 
37d70 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74  be called from t
37d80 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 69  he same thread i
37d90 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 20 61  n which.** the a
37da0 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
37db0 65 64 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72  ed function is r
37dc0 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76 6f 69 64 20  unning..*/.void 
37dd0 2a 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61  *sqlite3_user_da
37de0 74 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  ta(sqlite3_conte
37df0 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  xt*);../*.** CAP
37e00 49 33 52 45 46 3a 20 44 61 74 61 62 61 73 65 20  I3REF: Database 
37e10 43 6f 6e 6e 65 63 74 69 6f 6e 20 46 6f 72 20 46  Connection For F
37e20 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 4d 45 54 48  unctions.** METH
37e30 4f 44 3a 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74  OD: sqlite3_cont
37e40 65 78 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ext.**.** ^The s
37e50 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64  qlite3_context_d
37e60 62 5f 68 61 6e 64 6c 65 28 29 20 69 6e 74 65 72  b_handle() inter
37e70 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 63  face returns a c
37e80 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 70 6f  opy of.** the po
37e90 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 64 61  inter to the [da
37ea0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
37eb0 6e 5d 20 28 74 68 65 20 31 73 74 20 70 61 72 61  n] (the 1st para
37ec0 6d 65 74 65 72 29 0a 2a 2a 20 6f 66 20 74 68 65  meter).** of the
37ed0 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
37ee0 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20  _function()].** 
37ef0 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  and [sqlite3_cre
37f00 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29  ate_function16()
37f10 5d 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20  ] routines that 
37f20 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20 72 65  originally.** re
37f30 67 69 73 74 65 72 65 64 20 74 68 65 20 61 70 70  gistered the app
37f40 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 64  lication defined
37f50 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2f 0a 73 71   function..*/.sq
37f60 6c 69 74 65 33 20 2a 73 71 6c 69 74 65 33 5f 63  lite3 *sqlite3_c
37f70 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65  ontext_db_handle
37f80 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
37f90 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
37fa0 52 45 46 3a 20 46 75 6e 63 74 69 6f 6e 20 41 75  REF: Function Au
37fb0 78 69 6c 69 61 72 79 20 44 61 74 61 0a 2a 2a 20  xiliary Data.** 
37fc0 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f  METHOD: sqlite3_
37fd0 63 6f 6e 74 65 78 74 0a 2a 2a 0a 2a 2a 20 54 68  context.**.** Th
37fe0 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 6d 61  ese functions ma
37ff0 79 20 62 65 20 75 73 65 64 20 62 79 20 28 6e 6f  y be used by (no
38000 6e 2d 61 67 67 72 65 67 61 74 65 29 20 53 51 4c  n-aggregate) SQL
38010 20 66 75 6e 63 74 69 6f 6e 73 20 74 6f 0a 2a 2a   functions to.**
38020 20 61 73 73 6f 63 69 61 74 65 20 6d 65 74 61 64   associate metad
38030 61 74 61 20 77 69 74 68 20 61 72 67 75 6d 65 6e  ata with argumen
38040 74 20 76 61 6c 75 65 73 2e 20 49 66 20 74 68 65  t values. If the
38050 20 73 61 6d 65 20 76 61 6c 75 65 20 69 73 20 70   same value is p
38060 61 73 73 65 64 20 74 6f 0a 2a 2a 20 6d 75 6c 74  assed to.** mult
38070 69 70 6c 65 20 69 6e 76 6f 63 61 74 69 6f 6e 73  iple invocations
38080 20 6f 66 20 74 68 65 20 73 61 6d 65 20 53 51 4c   of the same SQL
38090 20 66 75 6e 63 74 69 6f 6e 20 64 75 72 69 6e 67   function during
380a0 20 71 75 65 72 79 20 65 78 65 63 75 74 69 6f 6e   query execution
380b0 2c 20 75 6e 64 65 72 0a 2a 2a 20 73 6f 6d 65 20  , under.** some 
380c0 63 69 72 63 75 6d 73 74 61 6e 63 65 73 20 74 68  circumstances th
380d0 65 20 61 73 73 6f 63 69 61 74 65 64 20 6d 65 74  e associated met
380e0 61 64 61 74 61 20 6d 61 79 20 62 65 20 70 72 65  adata may be pre
380f0 73 65 72 76 65 64 2e 20 20 41 6e 20 65 78 61 6d  served.  An exam
38100 70 6c 65 0a 2a 2a 20 6f 66 20 77 68 65 72 65 20  ple.** of where 
38110 74 68 69 73 20 6d 69 67 68 74 20 62 65 20 75 73  this might be us
38120 65 66 75 6c 20 69 73 20 69 6e 20 61 20 72 65 67  eful is in a reg
38130 75 6c 61 72 2d 65 78 70 72 65 73 73 69 6f 6e 20  ular-expression 
38140 6d 61 74 63 68 69 6e 67 0a 2a 2a 20 66 75 6e 63  matching.** func
38150 74 69 6f 6e 2e 20 54 68 65 20 63 6f 6d 70 69 6c  tion. The compil
38160 65 64 20 76 65 72 73 69 6f 6e 20 6f 66 20 74 68  ed version of th
38170 65 20 72 65 67 75 6c 61 72 20 65 78 70 72 65 73  e regular expres
38180 73 69 6f 6e 20 63 61 6e 20 62 65 20 73 74 6f 72  sion can be stor
38190 65 64 20 61 73 0a 2a 2a 20 6d 65 74 61 64 61 74  ed as.** metadat
381a0 61 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74  a associated wit
381b0 68 20 74 68 65 20 70 61 74 74 65 72 6e 20 73 74  h the pattern st
381c0 72 69 6e 67 2e 20 20 0a 2a 2a 20 54 68 65 6e 20  ring.  .** Then 
381d0 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 70  as long as the p
381e0 61 74 74 65 72 6e 20 73 74 72 69 6e 67 20 72 65  attern string re
381f0 6d 61 69 6e 73 20 74 68 65 20 73 61 6d 65 2c 0a  mains the same,.
38200 2a 2a 20 74 68 65 20 63 6f 6d 70 69 6c 65 64 20  ** the compiled 
38210 72 65 67 75 6c 61 72 20 65 78 70 72 65 73 73 69  regular expressi
38220 6f 6e 20 63 61 6e 20 62 65 20 72 65 75 73 65 64  on can be reused
38230 20 6f 6e 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20   on multiple.** 
38240 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74  invocations of t
38250 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e  he same function
38260 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
38270 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61  ite3_get_auxdata
38280 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  () interface ret
38290 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
382a0 6f 20 74 68 65 20 6d 65 74 61 64 61 74 61 0a 2a  o the metadata.*
382b0 2a 20 61 73 73 6f 63 69 61 74 65 64 20 62 79 20  * associated by 
382c0 74 68 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f  the sqlite3_set_
382d0 61 75 78 64 61 74 61 28 29 20 66 75 6e 63 74 69  auxdata() functi
382e0 6f 6e 20 77 69 74 68 20 74 68 65 20 4e 74 68 20  on with the Nth 
382f0 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 76 61 6c 75  argument.** valu
38300 65 20 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61  e to the applica
38310 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
38320 63 74 69 6f 6e 2e 20 5e 49 66 20 74 68 65 72 65  ction. ^If there
38330 20 69 73 20 6e 6f 20 6d 65 74 61 64 61 74 61 0a   is no metadata.
38340 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  ** associated wi
38350 74 68 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20  th the function 
38360 61 72 67 75 6d 65 6e 74 2c 20 74 68 69 73 20 73  argument, this s
38370 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61  qlite3_get_auxda
38380 74 61 28 29 20 69 6e 74 65 72 66 61 63 65 0a 2a  ta() interface.*
38390 2a 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c  * returns a NULL
383a0 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20   pointer..**.** 
383b0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 65 74  ^The sqlite3_set
383c0 5f 61 75 78 64 61 74 61 28 43 2c 4e 2c 50 2c 58  _auxdata(C,N,P,X
383d0 29 20 69 6e 74 65 72 66 61 63 65 20 73 61 76 65  ) interface save
383e0 73 20 50 20 61 73 20 6d 65 74 61 64 61 74 61 20  s P as metadata 
383f0 66 6f 72 20 74 68 65 20 4e 2d 74 68 0a 2a 2a 20  for the N-th.** 
38400 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 68 65 20  argument of the 
38410 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
38420 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 20 20 5e  ned function.  ^
38430 53 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20 63 61  Subsequent.** ca
38440 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 67  lls to sqlite3_g
38450 65 74 5f 61 75 78 64 61 74 61 28 43 2c 4e 29 20  et_auxdata(C,N) 
38460 72 65 74 75 72 6e 20 50 20 66 72 6f 6d 20 74 68  return P from th
38470 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 0a 2a 2a  e most recent.**
38480 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78   sqlite3_set_aux
38490 64 61 74 61 28 43 2c 4e 2c 50 2c 58 29 20 63 61  data(C,N,P,X) ca
384a0 6c 6c 20 69 66 20 74 68 65 20 6d 65 74 61 64 61  ll if the metada
384b0 74 61 20 69 73 20 73 74 69 6c 6c 20 76 61 6c 69  ta is still vali
384c0 64 20 6f 72 0a 2a 2a 20 4e 55 4c 4c 20 69 66 20  d or.** NULL if 
384d0 74 68 65 20 6d 65 74 61 64 61 74 61 20 68 61 73  the metadata has
384e0 20 62 65 65 6e 20 64 69 73 63 61 72 64 65 64 2e   been discarded.
384f0 0a 2a 2a 20 5e 41 66 74 65 72 20 65 61 63 68 20  .** ^After each 
38500 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f  call to sqlite3_
38510 73 65 74 5f 61 75 78 64 61 74 61 28 43 2c 4e 2c  set_auxdata(C,N,
38520 50 2c 58 29 20 77 68 65 72 65 20 58 20 69 73 20  P,X) where X is 
38530 6e 6f 74 20 4e 55 4c 4c 2c 0a 2a 2a 20 53 51 4c  not NULL,.** SQL
38540 69 74 65 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 20  ite will invoke 
38550 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 66  the destructor f
38560 75 6e 63 74 69 6f 6e 20 58 20 77 69 74 68 20 70  unction X with p
38570 61 72 61 6d 65 74 65 72 20 50 20 65 78 61 63 74  arameter P exact
38580 6c 79 0a 2a 2a 20 6f 6e 63 65 2c 20 77 68 65 6e  ly.** once, when
38590 20 74 68 65 20 6d 65 74 61 64 61 74 61 20 69 73   the metadata is
385a0 20 64 69 73 63 61 72 64 65 64 2e 0a 2a 2a 20 53   discarded..** S
385b0 51 4c 69 74 65 20 69 73 20 66 72 65 65 20 74 6f  QLite is free to
385c0 20 64 69 73 63 61 72 64 20 74 68 65 20 6d 65 74   discard the met
385d0 61 64 61 74 61 20 61 74 20 61 6e 79 20 74 69 6d  adata at any tim
385e0 65 2c 20 69 6e 63 6c 75 64 69 6e 67 3a 20 3c 75  e, including: <u
385f0 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5e 28 77 68 65  l>.** <li> ^(whe
38600 6e 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64  n the correspond
38610 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 70 61 72  ing function par
38620 61 6d 65 74 65 72 20 63 68 61 6e 67 65 73 29 5e  ameter changes)^
38630 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 5e 28 77  , or.** <li> ^(w
38640 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  hen [sqlite3_res
38650 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  et()] or [sqlite
38660 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69 73  3_finalize()] is
38670 20 63 61 6c 6c 65 64 20 66 6f 72 20 74 68 65 0a   called for the.
38680 2a 2a 20 20 20 20 20 20 53 51 4c 20 73 74 61 74  **      SQL stat
38690 65 6d 65 6e 74 29 5e 2c 20 6f 72 0a 2a 2a 20 3c  ement)^, or.** <
386a0 6c 69 3e 20 5e 28 77 68 65 6e 20 73 71 6c 69 74  li> ^(when sqlit
386b0 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29  e3_set_auxdata()
386c0 20 69 73 20 69 6e 76 6f 6b 65 64 20 61 67 61 69   is invoked agai
386d0 6e 20 6f 6e 20 74 68 65 20 73 61 6d 65 0a 2a 2a  n on the same.**
386e0 20 20 20 20 20 20 20 70 61 72 61 6d 65 74 65 72         parameter
386f0 29 5e 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 5e  )^, or.** <li> ^
38700 28 64 75 72 69 6e 67 20 74 68 65 20 6f 72 69 67  (during the orig
38710 69 6e 61 6c 20 73 71 6c 69 74 65 33 5f 73 65 74  inal sqlite3_set
38720 5f 61 75 78 64 61 74 61 28 29 20 63 61 6c 6c 20  _auxdata() call 
38730 77 68 65 6e 20 61 20 6d 65 6d 6f 72 79 20 0a 2a  when a memory .*
38740 2a 20 20 20 20 20 20 61 6c 6c 6f 63 61 74 69 6f  *      allocatio
38750 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2e 29  n error occurs.)
38760 5e 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 4e 6f  ^ </ul>.**.** No
38770 74 65 20 74 68 65 20 6c 61 73 74 20 62 75 6c 6c  te the last bull
38780 65 74 20 69 6e 20 70 61 72 74 69 63 75 6c 61 72  et in particular
38790 2e 20 20 54 68 65 20 64 65 73 74 72 75 63 74 6f  .  The destructo
387a0 72 20 58 20 69 6e 20 0a 2a 2a 20 73 71 6c 69 74  r X in .** sqlit
387b0 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 43  e3_set_auxdata(C
387c0 2c 4e 2c 50 2c 58 29 20 6d 69 67 68 74 20 62 65  ,N,P,X) might be
387d0 20 63 61 6c 6c 65 64 20 69 6d 6d 65 64 69 61 74   called immediat
387e0 65 6c 79 2c