System.Data.SQLite
Hex Artifact Content
Not logged in

Artifact 7318fd28b111ba9f6d59176939595220ff204ce3:


0000: 2f 2a 0a 2a 2a 20 32 30 30 31 20 53 65 70 74 65  /*.** 2001 Septe
0010: 6d 62 65 72 20 31 35 0a 2a 2a 0a 2a 2a 20 54 68  mber 15.**.** Th
0020: 65 20 61 75 74 68 6f 72 20 64 69 73 63 6c 61 69  e author disclai
0030: 6d 73 20 63 6f 70 79 72 69 67 68 74 20 74 6f 20  ms copyright to 
0040: 74 68 69 73 20 73 6f 75 72 63 65 20 63 6f 64 65  this source code
0050: 2e 20 20 49 6e 20 70 6c 61 63 65 20 6f 66 0a 2a  .  In place of.*
0060: 2a 20 61 20 6c 65 67 61 6c 20 6e 6f 74 69 63 65  * a legal notice
0070: 2c 20 68 65 72 65 20 69 73 20 61 20 62 6c 65 73  , here is a bles
0080: 73 69 6e 67 3a 0a 2a 2a 0a 2a 2a 20 20 20 20 4d  sing:.**.**    M
0090: 61 79 20 79 6f 75 20 64 6f 20 67 6f 6f 64 20 61  ay you do good a
00a0: 6e 64 20 6e 6f 74 20 65 76 69 6c 2e 0a 2a 2a 20  nd not evil..** 
00b0: 20 20 20 4d 61 79 20 79 6f 75 20 66 69 6e 64 20     May you find 
00c0: 66 6f 72 67 69 76 65 6e 65 73 73 20 66 6f 72 20  forgiveness for 
00d0: 79 6f 75 72 73 65 6c 66 20 61 6e 64 20 66 6f 72  yourself and for
00e0: 67 69 76 65 20 6f 74 68 65 72 73 2e 0a 2a 2a 20  give others..** 
00f0: 20 20 20 4d 61 79 20 79 6f 75 20 73 68 61 72 65     May you share
0100: 20 66 72 65 65 6c 79 2c 20 6e 65 76 65 72 20 74   freely, never t
0110: 61 6b 69 6e 67 20 6d 6f 72 65 20 74 68 61 6e 20  aking more than 
0120: 79 6f 75 20 67 69 76 65 2e 0a 2a 2a 0a 2a 2a 2a  you give..**.***
0130: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0140: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0150: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0160: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0170: 2a 2a 2a 2a 2a 2a 0a 2a 2a 20 54 68 69 73 20 68  ******.** This h
0180: 65 61 64 65 72 20 66 69 6c 65 20 64 65 66 69 6e  eader file defin
0190: 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  es the interface
01a0: 20 74 68 61 74 20 74 68 65 20 53 51 4c 69 74 65   that the SQLite
01b0: 20 6c 69 62 72 61 72 79 0a 2a 2a 20 70 72 65 73   library.** pres
01c0: 65 6e 74 73 20 74 6f 20 63 6c 69 65 6e 74 20 70  ents to client p
01d0: 72 6f 67 72 61 6d 73 2e 20 20 49 66 20 61 20 43  rograms.  If a C
01e0: 2d 66 75 6e 63 74 69 6f 6e 2c 20 73 74 72 75 63  -function, struc
01f0: 74 75 72 65 2c 20 64 61 74 61 74 79 70 65 2c 0a  ture, datatype,.
0200: 2a 2a 20 6f 72 20 63 6f 6e 73 74 61 6e 74 20 64  ** or constant d
0210: 65 66 69 6e 69 74 69 6f 6e 20 64 6f 65 73 20 6e  efinition does n
0220: 6f 74 20 61 70 70 65 61 72 20 69 6e 20 74 68 69  ot appear in thi
0230: 73 20 66 69 6c 65 2c 20 74 68 65 6e 20 69 74 20  s file, then it 
0240: 69 73 0a 2a 2a 20 6e 6f 74 20 61 20 70 75 62 6c  is.** not a publ
0250: 69 73 68 65 64 20 41 50 49 20 6f 66 20 53 51 4c  ished API of SQL
0260: 69 74 65 2c 20 69 73 20 73 75 62 6a 65 63 74 20  ite, is subject 
0270: 74 6f 20 63 68 61 6e 67 65 20 77 69 74 68 6f 75  to change withou
0280: 74 0a 2a 2a 20 6e 6f 74 69 63 65 2c 20 61 6e 64  t.** notice, and
0290: 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 72   should not be r
02a0: 65 66 65 72 65 6e 63 65 64 20 62 79 20 70 72 6f  eferenced by pro
02b0: 67 72 61 6d 73 20 74 68 61 74 20 75 73 65 20 53  grams that use S
02c0: 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 53 6f 6d  QLite..**.** Som
02d0: 65 20 6f 66 20 74 68 65 20 64 65 66 69 6e 69 74  e of the definit
02e0: 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20 69 6e  ions that are in
02f0: 20 74 68 69 73 20 66 69 6c 65 20 61 72 65 20 6d   this file are m
0300: 61 72 6b 65 64 20 61 73 0a 2a 2a 20 22 65 78 70  arked as.** "exp
0310: 65 72 69 6d 65 6e 74 61 6c 22 2e 20 20 45 78 70  erimental".  Exp
0320: 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74 65 72 66  erimental interf
0330: 61 63 65 73 20 61 72 65 20 6e 6f 72 6d 61 6c 6c  aces are normall
0340: 79 20 6e 65 77 0a 2a 2a 20 66 65 61 74 75 72 65  y new.** feature
0350: 73 20 72 65 63 65 6e 74 6c 79 20 61 64 64 65 64  s recently added
0360: 20 74 6f 20 53 51 4c 69 74 65 2e 20 20 57 65 20   to SQLite.  We 
0370: 64 6f 20 6e 6f 74 20 61 6e 74 69 63 69 70 61 74  do not anticipat
0380: 65 20 63 68 61 6e 67 65 73 0a 2a 2a 20 74 6f 20  e changes.** to 
0390: 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74  experimental int
03a0: 65 72 66 61 63 65 73 20 62 75 74 20 72 65 73 65  erfaces but rese
03b0: 72 76 65 20 74 68 65 20 72 69 67 68 74 20 74 6f  rve the right to
03c0: 20 6d 61 6b 65 20 6d 69 6e 6f 72 20 63 68 61 6e   make minor chan
03d0: 67 65 73 0a 2a 2a 20 69 66 20 65 78 70 65 72 69  ges.** if experi
03e0: 65 6e 63 65 20 66 72 6f 6d 20 75 73 65 20 22 69  ence from use "i
03f0: 6e 20 74 68 65 20 77 69 6c 64 22 20 73 75 67 67  n the wild" sugg
0400: 65 73 74 20 73 75 63 68 20 63 68 61 6e 67 65 73  est such changes
0410: 20 61 72 65 20 70 72 75 64 65 6e 74 2e 0a 2a 2a   are prudent..**
0420: 0a 2a 2a 20 54 68 65 20 6f 66 66 69 63 69 61 6c  .** The official
0430: 20 43 2d 6c 61 6e 67 75 61 67 65 20 41 50 49 20   C-language API 
0440: 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f  documentation fo
0450: 72 20 53 51 4c 69 74 65 20 69 73 20 64 65 72 69  r SQLite is deri
0460: 76 65 64 0a 2a 2a 20 66 72 6f 6d 20 63 6f 6d 6d  ved.** from comm
0470: 65 6e 74 73 20 69 6e 20 74 68 69 73 20 66 69 6c  ents in this fil
0480: 65 2e 20 20 54 68 69 73 20 66 69 6c 65 20 69 73  e.  This file is
0490: 20 74 68 65 20 61 75 74 68 6f 72 69 74 61 74 69   the authoritati
04a0: 76 65 20 73 6f 75 72 63 65 0a 2a 2a 20 6f 6e 20  ve source.** on 
04b0: 68 6f 77 20 53 51 4c 69 74 65 20 69 6e 74 65 72  how SQLite inter
04c0: 66 61 63 65 73 20 61 72 65 20 73 75 70 70 6f 73  faces are suppos
04d0: 65 64 20 74 6f 20 6f 70 65 72 61 74 65 2e 0a 2a  ed to operate..*
04e0: 2a 0a 2a 2a 20 54 68 65 20 6e 61 6d 65 20 6f 66  *.** The name of
04f0: 20 74 68 69 73 20 66 69 6c 65 20 75 6e 64 65 72   this file under
0500: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6d   configuration m
0510: 61 6e 61 67 65 6d 65 6e 74 20 69 73 20 22 73 71  anagement is "sq
0520: 6c 69 74 65 2e 68 2e 69 6e 22 2e 0a 2a 2a 20 54  lite.h.in"..** T
0530: 68 65 20 6d 61 6b 65 66 69 6c 65 20 6d 61 6b 65  he makefile make
0540: 73 20 73 6f 6d 65 20 6d 69 6e 6f 72 20 63 68 61  s some minor cha
0550: 6e 67 65 73 20 74 6f 20 74 68 69 73 20 66 69 6c  nges to this fil
0560: 65 20 28 73 75 63 68 20 61 73 20 69 6e 73 65 72  e (such as inser
0570: 74 69 6e 67 0a 2a 2a 20 74 68 65 20 76 65 72 73  ting.** the vers
0580: 69 6f 6e 20 6e 75 6d 62 65 72 29 20 61 6e 64 20  ion number) and 
0590: 63 68 61 6e 67 65 73 20 69 74 73 20 6e 61 6d 65  changes its name
05a0: 20 74 6f 20 22 73 71 6c 69 74 65 33 2e 68 22 20   to "sqlite3.h" 
05b0: 61 73 0a 2a 2a 20 70 61 72 74 20 6f 66 20 74 68  as.** part of th
05c0: 65 20 62 75 69 6c 64 20 70 72 6f 63 65 73 73 2e  e build process.
05d0: 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c 49  .*/.#ifndef SQLI
05e0: 54 45 33 5f 48 0a 23 64 65 66 69 6e 65 20 53 51  TE3_H.#define SQ
05f0: 4c 49 54 45 33 5f 48 0a 23 69 6e 63 6c 75 64 65  LITE3_H.#include
0600: 20 3c 73 74 64 61 72 67 2e 68 3e 20 20 20 20 20   <stdarg.h>     
0610: 2f 2a 20 4e 65 65 64 65 64 20 66 6f 72 20 74 68  /* Needed for th
0620: 65 20 64 65 66 69 6e 69 74 69 6f 6e 20 6f 66 20  e definition of 
0630: 76 61 5f 6c 69 73 74 20 2a 2f 0a 0a 2f 2a 0a 2a  va_list */../*.*
0640: 2a 20 4d 61 6b 65 20 73 75 72 65 20 77 65 20 63  * Make sure we c
0650: 61 6e 20 63 61 6c 6c 20 74 68 69 73 20 73 74 75  an call this stu
0660: 66 66 20 66 72 6f 6d 20 43 2b 2b 2e 0a 2a 2f 0a  ff from C++..*/.
0670: 23 69 66 64 65 66 20 5f 5f 63 70 6c 75 73 70 6c  #ifdef __cpluspl
0680: 75 73 0a 65 78 74 65 72 6e 20 22 43 22 20 7b 0a  us.extern "C" {.
0690: 23 65 6e 64 69 66 0a 0a 0a 2f 2a 0a 2a 2a 20 50  #endif.../*.** P
06a0: 72 6f 76 69 64 65 20 74 68 65 20 61 62 69 6c 69  rovide the abili
06b0: 74 79 20 74 6f 20 6f 76 65 72 72 69 64 65 20 6c  ty to override l
06c0: 69 6e 6b 61 67 65 20 66 65 61 74 75 72 65 73 20  inkage features 
06d0: 6f 66 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  of the interface
06e0: 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c  ..*/.#ifndef SQL
06f0: 49 54 45 5f 45 58 54 45 52 4e 0a 23 20 64 65 66  ITE_EXTERN.# def
0700: 69 6e 65 20 53 51 4c 49 54 45 5f 45 58 54 45 52  ine SQLITE_EXTER
0710: 4e 20 65 78 74 65 72 6e 0a 23 65 6e 64 69 66 0a  N extern.#endif.
0720: 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 41  #ifndef SQLITE_A
0730: 50 49 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49  PI.# define SQLI
0740: 54 45 5f 41 50 49 0a 23 65 6e 64 69 66 0a 23 69  TE_API.#endif.#i
0750: 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 43 44 45  fndef SQLITE_CDE
0760: 43 4c 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49  CL.# define SQLI
0770: 54 45 5f 43 44 45 43 4c 0a 23 65 6e 64 69 66 0a  TE_CDECL.#endif.
0780: 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 41  #ifndef SQLITE_A
0790: 50 49 43 41 4c 4c 0a 23 20 64 65 66 69 6e 65 20  PICALL.# define 
07a0: 53 51 4c 49 54 45 5f 41 50 49 43 41 4c 4c 0a 23  SQLITE_APICALL.#
07b0: 65 6e 64 69 66 0a 23 69 66 6e 64 65 66 20 53 51  endif.#ifndef SQ
07c0: 4c 49 54 45 5f 53 54 44 43 41 4c 4c 0a 23 20 64  LITE_STDCALL.# d
07d0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 54 44  efine SQLITE_STD
07e0: 43 41 4c 4c 20 53 51 4c 49 54 45 5f 41 50 49 43  CALL SQLITE_APIC
07f0: 41 4c 4c 0a 23 65 6e 64 69 66 0a 23 69 66 6e 64  ALL.#endif.#ifnd
0800: 65 66 20 53 51 4c 49 54 45 5f 43 41 4c 4c 42 41  ef SQLITE_CALLBA
0810: 43 4b 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49  CK.# define SQLI
0820: 54 45 5f 43 41 4c 4c 42 41 43 4b 0a 23 65 6e 64  TE_CALLBACK.#end
0830: 69 66 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54  if.#ifndef SQLIT
0840: 45 5f 53 59 53 41 50 49 0a 23 20 64 65 66 69 6e  E_SYSAPI.# defin
0850: 65 20 53 51 4c 49 54 45 5f 53 59 53 41 50 49 0a  e SQLITE_SYSAPI.
0860: 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 54 68  #endif../*.** Th
0870: 65 73 65 20 6e 6f 2d 6f 70 20 6d 61 63 72 6f 73  ese no-op macros
0880: 20 61 72 65 20 75 73 65 64 20 69 6e 20 66 72 6f   are used in fro
0890: 6e 74 20 6f 66 20 69 6e 74 65 72 66 61 63 65 73  nt of interfaces
08a0: 20 74 6f 20 6d 61 72 6b 20 74 68 6f 73 65 0a 2a   to mark those.*
08b0: 2a 20 69 6e 74 65 72 66 61 63 65 73 20 61 73 20  * interfaces as 
08c0: 65 69 74 68 65 72 20 64 65 70 72 65 63 61 74 65  either deprecate
08d0: 64 20 6f 72 20 65 78 70 65 72 69 6d 65 6e 74 61  d or experimenta
08e0: 6c 2e 20 20 4e 65 77 20 61 70 70 6c 69 63 61 74  l.  New applicat
08f0: 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e  ions.** should n
0900: 6f 74 20 75 73 65 20 64 65 70 72 65 63 61 74 65  ot use deprecate
0910: 64 20 69 6e 74 65 72 66 61 63 65 73 20 2d 20 74  d interfaces - t
0920: 68 65 79 20 61 72 65 20 73 75 70 70 6f 72 74 65  hey are supporte
0930: 64 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73 0a  d for backwards.
0940: 2a 2a 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79  ** compatibility
0950: 20 6f 6e 6c 79 2e 20 20 41 70 70 6c 69 63 61 74   only.  Applicat
0960: 69 6f 6e 20 77 72 69 74 65 72 73 20 73 68 6f 75  ion writers shou
0970: 6c 64 20 62 65 20 61 77 61 72 65 20 74 68 61 74  ld be aware that
0980: 0a 2a 2a 20 65 78 70 65 72 69 6d 65 6e 74 61 6c  .** experimental
0990: 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20   interfaces are 
09a0: 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67  subject to chang
09b0: 65 20 69 6e 20 70 6f 69 6e 74 20 72 65 6c 65 61  e in point relea
09c0: 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ses..**.** These
09d0: 20 6d 61 63 72 6f 73 20 75 73 65 64 20 74 6f 20   macros used to 
09e0: 72 65 73 6f 6c 76 65 20 74 6f 20 76 61 72 69 6f  resolve to vario
09f0: 75 73 20 6b 69 6e 64 73 20 6f 66 20 63 6f 6d 70  us kinds of comp
0a00: 69 6c 65 72 20 6d 61 67 69 63 20 74 68 61 74 0a  iler magic that.
0a10: 2a 2a 20 77 6f 75 6c 64 20 67 65 6e 65 72 61 74  ** would generat
0a20: 65 20 77 61 72 6e 69 6e 67 20 6d 65 73 73 61 67  e warning messag
0a30: 65 73 20 77 68 65 6e 20 74 68 65 79 20 77 65 72  es when they wer
0a40: 65 20 75 73 65 64 2e 20 20 42 75 74 20 74 68 61  e used.  But tha
0a50: 74 0a 2a 2a 20 63 6f 6d 70 69 6c 65 72 20 6d 61  t.** compiler ma
0a60: 67 69 63 20 65 6e 64 65 64 20 75 70 20 67 65 6e  gic ended up gen
0a70: 65 72 61 74 69 6e 67 20 73 75 63 68 20 61 20 66  erating such a f
0a80: 6c 75 72 72 79 20 6f 66 20 62 75 67 20 72 65 70  lurry of bug rep
0a90: 6f 72 74 73 0a 2a 2a 20 74 68 61 74 20 77 65 20  orts.** that we 
0aa0: 68 61 76 65 20 74 61 6b 65 6e 20 69 74 20 61 6c  have taken it al
0ab0: 6c 20 6f 75 74 20 61 6e 64 20 67 6f 6e 65 20 62  l out and gone b
0ac0: 61 63 6b 20 74 6f 20 75 73 69 6e 67 20 73 69 6d  ack to using sim
0ad0: 70 6c 65 0a 2a 2a 20 6e 6f 6f 70 20 6d 61 63 72  ple.** noop macr
0ae0: 6f 73 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  os..*/.#define S
0af0: 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44  QLITE_DEPRECATED
0b00: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
0b10: 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a 0a 2f 2a  EXPERIMENTAL../*
0b20: 0a 2a 2a 20 45 6e 73 75 72 65 20 74 68 65 73 65  .** Ensure these
0b30: 20 73 79 6d 62 6f 6c 73 20 77 65 72 65 20 6e 6f   symbols were no
0b40: 74 20 64 65 66 69 6e 65 64 20 62 79 20 73 6f 6d  t defined by som
0b50: 65 20 70 72 65 76 69 6f 75 73 20 68 65 61 64 65  e previous heade
0b60: 72 20 66 69 6c 65 2e 0a 2a 2f 0a 23 69 66 64 65  r file..*/.#ifde
0b70: 66 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e  f SQLITE_VERSION
0b80: 0a 23 20 75 6e 64 65 66 20 53 51 4c 49 54 45 5f  .# undef SQLITE_
0b90: 56 45 52 53 49 4f 4e 0a 23 65 6e 64 69 66 0a 23  VERSION.#endif.#
0ba0: 69 66 64 65 66 20 53 51 4c 49 54 45 5f 56 45 52  ifdef SQLITE_VER
0bb0: 53 49 4f 4e 5f 4e 55 4d 42 45 52 0a 23 20 75 6e  SION_NUMBER.# un
0bc0: 64 65 66 20 53 51 4c 49 54 45 5f 56 45 52 53 49  def SQLITE_VERSI
0bd0: 4f 4e 5f 4e 55 4d 42 45 52 0a 23 65 6e 64 69 66  ON_NUMBER.#endif
0be0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
0bf0: 3a 20 43 6f 6d 70 69 6c 65 2d 54 69 6d 65 20 4c  : Compile-Time L
0c00: 69 62 72 61 72 79 20 56 65 72 73 69 6f 6e 20 4e  ibrary Version N
0c10: 75 6d 62 65 72 73 0a 2a 2a 0a 2a 2a 20 5e 28 54  umbers.**.** ^(T
0c20: 68 65 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49  he [SQLITE_VERSI
0c30: 4f 4e 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73  ON] C preprocess
0c40: 6f 72 20 6d 61 63 72 6f 20 69 6e 20 74 68 65 20  or macro in the 
0c50: 73 71 6c 69 74 65 33 2e 68 20 68 65 61 64 65 72  sqlite3.h header
0c60: 0a 2a 2a 20 65 76 61 6c 75 61 74 65 73 20 74 6f  .** evaluates to
0c70: 20 61 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61   a string litera
0c80: 6c 20 74 68 61 74 20 69 73 20 74 68 65 20 53 51  l that is the SQ
0c90: 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 69 6e 20  Lite version in 
0ca0: 74 68 65 0a 2a 2a 20 66 6f 72 6d 61 74 20 22 58  the.** format "X
0cb0: 2e 59 2e 5a 22 20 77 68 65 72 65 20 58 20 69 73  .Y.Z" where X is
0cc0: 20 74 68 65 20 6d 61 6a 6f 72 20 76 65 72 73 69   the major versi
0cd0: 6f 6e 20 6e 75 6d 62 65 72 20 28 61 6c 77 61 79  on number (alway
0ce0: 73 20 33 20 66 6f 72 0a 2a 2a 20 53 51 4c 69 74  s 3 for.** SQLit
0cf0: 65 33 29 20 61 6e 64 20 59 20 69 73 20 74 68 65  e3) and Y is the
0d00: 20 6d 69 6e 6f 72 20 76 65 72 73 69 6f 6e 20 6e   minor version n
0d10: 75 6d 62 65 72 20 61 6e 64 20 5a 20 69 73 20 74  umber and Z is t
0d20: 68 65 20 72 65 6c 65 61 73 65 20 6e 75 6d 62 65  he release numbe
0d30: 72 2e 29 5e 0a 2a 2a 20 5e 28 54 68 65 20 5b 53  r.)^.** ^(The [S
0d40: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55  QLITE_VERSION_NU
0d50: 4d 42 45 52 5d 20 43 20 70 72 65 70 72 6f 63 65  MBER] C preproce
0d60: 73 73 6f 72 20 6d 61 63 72 6f 20 72 65 73 6f 6c  ssor macro resol
0d70: 76 65 73 20 74 6f 20 61 6e 20 69 6e 74 65 67 65  ves to an intege
0d80: 72 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 76 61  r.** with the va
0d90: 6c 75 65 20 28 58 2a 31 30 30 30 30 30 30 20 2b  lue (X*1000000 +
0da0: 20 59 2a 31 30 30 30 20 2b 20 5a 29 20 77 68 65   Y*1000 + Z) whe
0db0: 72 65 20 58 2c 20 59 2c 20 61 6e 64 20 5a 20 61  re X, Y, and Z a
0dc0: 72 65 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 6e  re the same.** n
0dd0: 75 6d 62 65 72 73 20 75 73 65 64 20 69 6e 20 5b  umbers used in [
0de0: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d 2e  SQLITE_VERSION].
0df0: 29 5e 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45  )^.** The SQLITE
0e00: 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20  _VERSION_NUMBER 
0e10: 66 6f 72 20 61 6e 79 20 67 69 76 65 6e 20 72 65  for any given re
0e20: 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65 20  lease of SQLite 
0e30: 77 69 6c 6c 20 61 6c 73 6f 0a 2a 2a 20 62 65 20  will also.** be 
0e40: 6c 61 72 67 65 72 20 74 68 61 6e 20 74 68 65 20  larger than the 
0e50: 72 65 6c 65 61 73 65 20 66 72 6f 6d 20 77 68 69  release from whi
0e60: 63 68 20 69 74 20 69 73 20 64 65 72 69 76 65 64  ch it is derived
0e70: 2e 20 20 45 69 74 68 65 72 20 59 20 77 69 6c 6c  .  Either Y will
0e80: 0a 2a 2a 20 62 65 20 68 65 6c 64 20 63 6f 6e 73  .** be held cons
0e90: 74 61 6e 74 20 61 6e 64 20 5a 20 77 69 6c 6c 20  tant and Z will 
0ea0: 62 65 20 69 6e 63 72 65 6d 65 6e 74 65 64 20 6f  be incremented o
0eb0: 72 20 65 6c 73 65 20 59 20 77 69 6c 6c 20 62 65  r else Y will be
0ec0: 20 69 6e 63 72 65 6d 65 6e 74 65 64 0a 2a 2a 20   incremented.** 
0ed0: 61 6e 64 20 5a 20 77 69 6c 6c 20 62 65 20 72 65  and Z will be re
0ee0: 73 65 74 20 74 6f 20 7a 65 72 6f 2e 0a 2a 2a 0a  set to zero..**.
0ef0: 2a 2a 20 53 69 6e 63 65 20 5b 76 65 72 73 69 6f  ** Since [versio
0f00: 6e 20 33 2e 36 2e 31 38 5d 20 28 5b 64 61 74 65  n 3.6.18] ([date
0f10: 6f 66 3a 33 2e 36 2e 31 38 5d 29 2c 20 0a 2a 2a  of:3.6.18]), .**
0f20: 20 53 51 4c 69 74 65 20 73 6f 75 72 63 65 20 63   SQLite source c
0f30: 6f 64 65 20 68 61 73 20 62 65 65 6e 20 73 74 6f  ode has been sto
0f40: 72 65 64 20 69 6e 20 74 68 65 0a 2a 2a 20 3c 61  red in the.** <a
0f50: 20 68 72 65 66 3d 22 68 74 74 70 3a 2f 2f 77 77   href="http://ww
0f60: 77 2e 66 6f 73 73 69 6c 2d 73 63 6d 2e 6f 72 67  w.fossil-scm.org
0f70: 2f 22 3e 46 6f 73 73 69 6c 20 63 6f 6e 66 69 67  /">Fossil config
0f80: 75 72 61 74 69 6f 6e 20 6d 61 6e 61 67 65 6d 65  uration manageme
0f90: 6e 74 0a 2a 2a 20 73 79 73 74 65 6d 3c 2f 61 3e  nt.** system</a>
0fa0: 2e 20 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 53  .  ^The SQLITE_S
0fb0: 4f 55 52 43 45 5f 49 44 20 6d 61 63 72 6f 20 65  OURCE_ID macro e
0fc0: 76 61 6c 75 61 74 65 73 20 74 6f 0a 2a 2a 20 61  valuates to.** a
0fd0: 20 73 74 72 69 6e 67 20 77 68 69 63 68 20 69 64   string which id
0fe0: 65 6e 74 69 66 69 65 73 20 61 20 70 61 72 74 69  entifies a parti
0ff0: 63 75 6c 61 72 20 63 68 65 63 6b 2d 69 6e 20 6f  cular check-in o
1000: 66 20 53 51 4c 69 74 65 0a 2a 2a 20 77 69 74 68  f SQLite.** with
1010: 69 6e 20 69 74 73 20 63 6f 6e 66 69 67 75 72 61  in its configura
1020: 74 69 6f 6e 20 6d 61 6e 61 67 65 6d 65 6e 74 20  tion management 
1030: 73 79 73 74 65 6d 2e 20 20 5e 54 68 65 20 53 51  system.  ^The SQ
1040: 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 0a 2a  LITE_SOURCE_ID.*
1050: 2a 20 73 74 72 69 6e 67 20 63 6f 6e 74 61 69 6e  * string contain
1060: 73 20 74 68 65 20 64 61 74 65 20 61 6e 64 20 74  s the date and t
1070: 69 6d 65 20 6f 66 20 74 68 65 20 63 68 65 63 6b  ime of the check
1080: 2d 69 6e 20 28 55 54 43 29 20 61 6e 64 20 61 6e  -in (UTC) and an
1090: 20 53 48 41 31 0a 2a 2a 20 68 61 73 68 20 6f 66   SHA1.** hash of
10a0: 20 74 68 65 20 65 6e 74 69 72 65 20 73 6f 75 72   the entire sour
10b0: 63 65 20 74 72 65 65 2e 0a 2a 2a 0a 2a 2a 20 53  ce tree..**.** S
10c0: 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65  ee also: [sqlite
10d0: 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29 5d 2c  3_libversion()],
10e0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6c 69 62  .** [sqlite3_lib
10f0: 76 65 72 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 29  version_number()
1100: 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73 6f 75 72  ], [sqlite3_sour
1110: 63 65 69 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c  ceid()],.** [sql
1120: 69 74 65 5f 76 65 72 73 69 6f 6e 28 29 5d 20 61  ite_version()] a
1130: 6e 64 20 5b 73 71 6c 69 74 65 5f 73 6f 75 72 63  nd [sqlite_sourc
1140: 65 5f 69 64 28 29 5d 2e 0a 2a 2f 0a 23 64 65 66  e_id()]..*/.#def
1150: 69 6e 65 20 53 51 4c 49 54 45 5f 56 45 52 53 49  ine SQLITE_VERSI
1160: 4f 4e 20 20 20 20 20 20 20 20 22 33 2e 31 35 2e  ON        "3.15.
1170: 31 22 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  1".#define SQLIT
1180: 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52  E_VERSION_NUMBER
1190: 20 33 30 31 35 30 30 31 0a 23 64 65 66 69 6e 65   3015001.#define
11a0: 20 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49   SQLITE_SOURCE_I
11b0: 44 20 20 20 20 20 20 22 32 30 31 36 2d 31 31 2d  D      "2016-11-
11c0: 30 34 20 31 32 3a 30 38 3a 34 39 20 31 31 33 36  04 12:08:49 1136
11d0: 38 36 33 63 37 36 35 37 36 31 31 30 65 37 31 30  863c76576110e710
11e0: 64 64 35 64 36 39 61 62 36 62 66 33 34 37 63 36  dd5d69ab6bf347c6
11f0: 35 65 33 36 22 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  5e36"../*.** CAP
1200: 49 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d 65 20  I3REF: Run-Time 
1210: 4c 69 62 72 61 72 79 20 56 65 72 73 69 6f 6e 20  Library Version 
1220: 4e 75 6d 62 65 72 73 0a 2a 2a 20 4b 45 59 57 4f  Numbers.** KEYWO
1230: 52 44 53 3a 20 73 71 6c 69 74 65 33 5f 76 65 72  RDS: sqlite3_ver
1240: 73 69 6f 6e 2c 20 73 71 6c 69 74 65 33 5f 73 6f  sion, sqlite3_so
1250: 75 72 63 65 69 64 0a 2a 2a 0a 2a 2a 20 54 68 65  urceid.**.** The
1260: 73 65 20 69 6e 74 65 72 66 61 63 65 73 20 70 72  se interfaces pr
1270: 6f 76 69 64 65 20 74 68 65 20 73 61 6d 65 20 69  ovide the same i
1280: 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 73 20 74 68  nformation as th
1290: 65 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f  e [SQLITE_VERSIO
12a0: 4e 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 56  N],.** [SQLITE_V
12b0: 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d 2c 20  ERSION_NUMBER], 
12c0: 61 6e 64 20 5b 53 51 4c 49 54 45 5f 53 4f 55 52  and [SQLITE_SOUR
12d0: 43 45 5f 49 44 5d 20 43 20 70 72 65 70 72 6f 63  CE_ID] C preproc
12e0: 65 73 73 6f 72 20 6d 61 63 72 6f 73 0a 2a 2a 20  essor macros.** 
12f0: 62 75 74 20 61 72 65 20 61 73 73 6f 63 69 61 74  but are associat
1300: 65 64 20 77 69 74 68 20 74 68 65 20 6c 69 62 72  ed with the libr
1310: 61 72 79 20 69 6e 73 74 65 61 64 20 6f 66 20 74  ary instead of t
1320: 68 65 20 68 65 61 64 65 72 20 66 69 6c 65 2e 20  he header file. 
1330: 20 5e 28 43 61 75 74 69 6f 75 73 0a 2a 2a 20 70   ^(Cautious.** p
1340: 72 6f 67 72 61 6d 6d 65 72 73 20 6d 69 67 68 74  rogrammers might
1350: 20 69 6e 63 6c 75 64 65 20 61 73 73 65 72 74 28   include assert(
1360: 29 20 73 74 61 74 65 6d 65 6e 74 73 20 69 6e 20  ) statements in 
1370: 74 68 65 69 72 20 61 70 70 6c 69 63 61 74 69 6f  their applicatio
1380: 6e 20 74 6f 0a 2a 2a 20 76 65 72 69 66 79 20 74  n to.** verify t
1390: 68 61 74 20 76 61 6c 75 65 73 20 72 65 74 75 72  hat values retur
13a0: 6e 65 64 20 62 79 20 74 68 65 73 65 20 69 6e 74  ned by these int
13b0: 65 72 66 61 63 65 73 20 6d 61 74 63 68 20 74 68  erfaces match th
13c0: 65 20 6d 61 63 72 6f 73 20 69 6e 0a 2a 2a 20 74  e macros in.** t
13d0: 68 65 20 68 65 61 64 65 72 2c 20 61 6e 64 20 74  he header, and t
13e0: 68 75 73 20 65 6e 73 75 72 65 20 74 68 61 74 20  hus ensure that 
13f0: 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
1400: 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 77  is.** compiled w
1410: 69 74 68 20 6d 61 74 63 68 69 6e 67 20 6c 69 62  ith matching lib
1420: 72 61 72 79 20 61 6e 64 20 68 65 61 64 65 72 20  rary and header 
1430: 66 69 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 3c 62 6c  files..**.** <bl
1440: 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a  ockquote><pre>.*
1450: 2a 20 61 73 73 65 72 74 28 20 73 71 6c 69 74 65  * assert( sqlite
1460: 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d  3_libversion_num
1470: 62 65 72 28 29 3d 3d 53 51 4c 49 54 45 5f 56 45  ber()==SQLITE_VE
1480: 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 29 3b 0a  RSION_NUMBER );.
1490: 2a 2a 20 61 73 73 65 72 74 28 20 73 74 72 63 6d  ** assert( strcm
14a0: 70 28 73 71 6c 69 74 65 33 5f 73 6f 75 72 63 65  p(sqlite3_source
14b0: 69 64 28 29 2c 53 51 4c 49 54 45 5f 53 4f 55 52  id(),SQLITE_SOUR
14c0: 43 45 5f 49 44 29 3d 3d 30 20 29 3b 0a 2a 2a 20  CE_ID)==0 );.** 
14d0: 61 73 73 65 72 74 28 20 73 74 72 63 6d 70 28 73  assert( strcmp(s
14e0: 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f  qlite3_libversio
14f0: 6e 28 29 2c 53 51 4c 49 54 45 5f 56 45 52 53 49  n(),SQLITE_VERSI
1500: 4f 4e 29 3d 3d 30 20 29 3b 0a 2a 2a 20 3c 2f 70  ON)==0 );.** </p
1510: 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e  re></blockquote>
1520: 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  )^.**.** ^The sq
1530: 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b 5d 20  lite3_version[] 
1540: 73 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e 74 20  string constant 
1550: 63 6f 6e 74 61 69 6e 73 20 74 68 65 20 74 65 78  contains the tex
1560: 74 20 6f 66 20 5b 53 51 4c 49 54 45 5f 56 45 52  t of [SQLITE_VER
1570: 53 49 4f 4e 5d 0a 2a 2a 20 6d 61 63 72 6f 2e 20  SION].** macro. 
1580: 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6c 69   ^The sqlite3_li
1590: 62 76 65 72 73 69 6f 6e 28 29 20 66 75 6e 63 74  bversion() funct
15a0: 69 6f 6e 20 72 65 74 75 72 6e 73 20 61 20 70 6f  ion returns a po
15b0: 69 6e 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20  inter to the.** 
15c0: 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76  to the sqlite3_v
15d0: 65 72 73 69 6f 6e 5b 5d 20 73 74 72 69 6e 67 20  ersion[] string 
15e0: 63 6f 6e 73 74 61 6e 74 2e 20 20 54 68 65 20 73  constant.  The s
15f0: 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f  qlite3_libversio
1600: 6e 28 29 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  n().** function 
1610: 69 73 20 70 72 6f 76 69 64 65 64 20 66 6f 72 20  is provided for 
1620: 75 73 65 20 69 6e 20 44 4c 4c 73 20 73 69 6e 63  use in DLLs sinc
1630: 65 20 44 4c 4c 20 75 73 65 72 73 20 75 73 75 61  e DLL users usua
1640: 6c 6c 79 20 64 6f 20 6e 6f 74 20 68 61 76 65 0a  lly do not have.
1650: 2a 2a 20 64 69 72 65 63 74 20 61 63 63 65 73 73  ** direct access
1660: 20 74 6f 20 73 74 72 69 6e 67 20 63 6f 6e 73 74   to string const
1670: 61 6e 74 73 20 77 69 74 68 69 6e 20 74 68 65 20  ants within the 
1680: 44 4c 4c 2e 20 20 5e 54 68 65 0a 2a 2a 20 73 71  DLL.  ^The.** sq
1690: 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e  lite3_libversion
16a0: 5f 6e 75 6d 62 65 72 28 29 20 66 75 6e 63 74 69  _number() functi
16b0: 6f 6e 20 72 65 74 75 72 6e 73 20 61 6e 20 69 6e  on returns an in
16c0: 74 65 67 65 72 20 65 71 75 61 6c 20 74 6f 0a 2a  teger equal to.*
16d0: 2a 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f  * [SQLITE_VERSIO
16e0: 4e 5f 4e 55 4d 42 45 52 5d 2e 20 20 5e 54 68 65  N_NUMBER].  ^The
16f0: 20 73 71 6c 69 74 65 33 5f 73 6f 75 72 63 65 69   sqlite3_sourcei
1700: 64 28 29 20 66 75 6e 63 74 69 6f 6e 20 72 65 74  d() function ret
1710: 75 72 6e 73 20 0a 2a 2a 20 61 20 70 6f 69 6e 74  urns .** a point
1720: 65 72 20 74 6f 20 61 20 73 74 72 69 6e 67 20 63  er to a string c
1730: 6f 6e 73 74 61 6e 74 20 77 68 6f 73 65 20 76 61  onstant whose va
1740: 6c 75 65 20 69 73 20 74 68 65 20 73 61 6d 65 20  lue is the same 
1750: 61 73 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c 49  as the .** [SQLI
1760: 54 45 5f 53 4f 55 52 43 45 5f 49 44 5d 20 43 20  TE_SOURCE_ID] C 
1770: 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63  preprocessor mac
1780: 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  ro..**.** See al
1790: 73 6f 3a 20 5b 73 71 6c 69 74 65 5f 76 65 72 73  so: [sqlite_vers
17a0: 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  ion()] and [sqli
17b0: 74 65 5f 73 6f 75 72 63 65 5f 69 64 28 29 5d 2e  te_source_id()].
17c0: 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 53  .*/.SQLITE_API S
17d0: 51 4c 49 54 45 5f 45 58 54 45 52 4e 20 63 6f 6e  QLITE_EXTERN con
17e0: 73 74 20 63 68 61 72 20 73 71 6c 69 74 65 33 5f  st char sqlite3_
17f0: 76 65 72 73 69 6f 6e 5b 5d 3b 0a 53 51 4c 49 54  version[];.SQLIT
1800: 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72  E_API const char
1810: 20 2a 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72   *sqlite3_libver
1820: 73 69 6f 6e 28 76 6f 69 64 29 3b 0a 53 51 4c 49  sion(void);.SQLI
1830: 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61  TE_API const cha
1840: 72 20 2a 73 71 6c 69 74 65 33 5f 73 6f 75 72 63  r *sqlite3_sourc
1850: 65 69 64 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54  eid(void);.SQLIT
1860: 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
1870: 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d  3_libversion_num
1880: 62 65 72 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a  ber(void);../*.*
1890: 2a 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d  * CAPI3REF: Run-
18a0: 54 69 6d 65 20 4c 69 62 72 61 72 79 20 43 6f 6d  Time Library Com
18b0: 70 69 6c 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73  pilation Options
18c0: 20 44 69 61 67 6e 6f 73 74 69 63 73 0a 2a 2a 0a   Diagnostics.**.
18d0: 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
18e0: 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73  compileoption_us
18f0: 65 64 28 29 20 66 75 6e 63 74 69 6f 6e 20 72 65  ed() function re
1900: 74 75 72 6e 73 20 30 20 6f 72 20 31 20 0a 2a 2a  turns 0 or 1 .**
1910: 20 69 6e 64 69 63 61 74 69 6e 67 20 77 68 65 74   indicating whet
1920: 68 65 72 20 74 68 65 20 73 70 65 63 69 66 69 65  her the specifie
1930: 64 20 6f 70 74 69 6f 6e 20 77 61 73 20 64 65 66  d option was def
1940: 69 6e 65 64 20 61 74 20 0a 2a 2a 20 63 6f 6d 70  ined at .** comp
1950: 69 6c 65 20 74 69 6d 65 2e 20 20 5e 54 68 65 20  ile time.  ^The 
1960: 53 51 4c 49 54 45 5f 20 70 72 65 66 69 78 20 6d  SQLITE_ prefix m
1970: 61 79 20 62 65 20 6f 6d 69 74 74 65 64 20 66 72  ay be omitted fr
1980: 6f 6d 20 74 68 65 20 0a 2a 2a 20 6f 70 74 69 6f  om the .** optio
1990: 6e 20 6e 61 6d 65 20 70 61 73 73 65 64 20 74 6f  n name passed to
19a0: 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65   sqlite3_compile
19b0: 6f 70 74 69 6f 6e 5f 75 73 65 64 28 29 2e 20 20  option_used().  
19c0: 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
19d0: 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f  te3_compileoptio
19e0: 6e 5f 67 65 74 28 29 20 66 75 6e 63 74 69 6f 6e  n_get() function
19f0: 20 61 6c 6c 6f 77 73 20 69 74 65 72 61 74 69 6e   allows iteratin
1a00: 67 0a 2a 2a 20 6f 76 65 72 20 74 68 65 20 6c 69  g.** over the li
1a10: 73 74 20 6f 66 20 6f 70 74 69 6f 6e 73 20 74 68  st of options th
1a20: 61 74 20 77 65 72 65 20 64 65 66 69 6e 65 64 20  at were defined 
1a30: 61 74 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 20  at compile time 
1a40: 62 79 0a 2a 2a 20 72 65 74 75 72 6e 69 6e 67 20  by.** returning 
1a50: 74 68 65 20 4e 2d 74 68 20 63 6f 6d 70 69 6c 65  the N-th compile
1a60: 20 74 69 6d 65 20 6f 70 74 69 6f 6e 20 73 74 72   time option str
1a70: 69 6e 67 2e 20 20 5e 49 66 20 4e 20 69 73 20 6f  ing.  ^If N is o
1a80: 75 74 20 6f 66 20 72 61 6e 67 65 2c 0a 2a 2a 20  ut of range,.** 
1a90: 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f  sqlite3_compileo
1aa0: 70 74 69 6f 6e 5f 67 65 74 28 29 20 72 65 74 75  ption_get() retu
1ab0: 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  rns a NULL point
1ac0: 65 72 2e 20 20 5e 54 68 65 20 53 51 4c 49 54 45  er.  ^The SQLITE
1ad0: 5f 20 0a 2a 2a 20 70 72 65 66 69 78 20 69 73 20  _ .** prefix is 
1ae0: 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 61 6e 79  omitted from any
1af0: 20 73 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65   strings returne
1b00: 64 20 62 79 20 0a 2a 2a 20 73 71 6c 69 74 65 33  d by .** sqlite3
1b10: 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67  _compileoption_g
1b20: 65 74 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 53 75 70  et()..**.** ^Sup
1b30: 70 6f 72 74 20 66 6f 72 20 74 68 65 20 64 69 61  port for the dia
1b40: 67 6e 6f 73 74 69 63 20 66 75 6e 63 74 69 6f 6e  gnostic function
1b50: 73 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c  s sqlite3_compil
1b60: 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28 29 0a 2a  eoption_used().*
1b70: 2a 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f  * and sqlite3_co
1b80: 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28  mpileoption_get(
1b90: 29 20 6d 61 79 20 62 65 20 6f 6d 69 74 74 65 64  ) may be omitted
1ba0: 20 62 79 20 73 70 65 63 69 66 79 69 6e 67 20 74   by specifying t
1bb0: 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f  he .** [SQLITE_O
1bc0: 4d 49 54 5f 43 4f 4d 50 49 4c 45 4f 50 54 49 4f  MIT_COMPILEOPTIO
1bd0: 4e 5f 44 49 41 47 53 5d 20 6f 70 74 69 6f 6e 20  N_DIAGS] option 
1be0: 61 74 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 2e  at compile time.
1bf0: 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a  .**.** See also:
1c00: 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 5b   SQL functions [
1c10: 73 71 6c 69 74 65 5f 63 6f 6d 70 69 6c 65 6f 70  sqlite_compileop
1c20: 74 69 6f 6e 5f 75 73 65 64 28 29 5d 20 61 6e 64  tion_used()] and
1c30: 0a 2a 2a 20 5b 73 71 6c 69 74 65 5f 63 6f 6d 70  .** [sqlite_comp
1c40: 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29 5d  ileoption_get()]
1c50: 20 61 6e 64 20 74 68 65 20 5b 63 6f 6d 70 69 6c   and the [compil
1c60: 65 5f 6f 70 74 69 6f 6e 73 20 70 72 61 67 6d 61  e_options pragma
1c70: 5d 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51  ]..*/.#ifndef SQ
1c80: 4c 49 54 45 5f 4f 4d 49 54 5f 43 4f 4d 50 49 4c  LITE_OMIT_COMPIL
1c90: 45 4f 50 54 49 4f 4e 5f 44 49 41 47 53 0a 53 51  EOPTION_DIAGS.SQ
1ca0: 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
1cb0: 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69  ite3_compileopti
1cc0: 6f 6e 5f 75 73 65 64 28 63 6f 6e 73 74 20 63 68  on_used(const ch
1cd0: 61 72 20 2a 7a 4f 70 74 4e 61 6d 65 29 3b 0a 53  ar *zOptName);.S
1ce0: 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20  QLITE_API const 
1cf0: 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f  char *sqlite3_co
1d00: 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28  mpileoption_get(
1d10: 69 6e 74 20 4e 29 3b 0a 23 65 6e 64 69 66 0a 0a  int N);.#endif..
1d20: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1d30: 54 65 73 74 20 54 6f 20 53 65 65 20 49 66 20 54  Test To See If T
1d40: 68 65 20 4c 69 62 72 61 72 79 20 49 73 20 54 68  he Library Is Th
1d50: 72 65 61 64 73 61 66 65 0a 2a 2a 0a 2a 2a 20 5e  readsafe.**.** ^
1d60: 54 68 65 20 73 71 6c 69 74 65 33 5f 74 68 72 65  The sqlite3_thre
1d70: 61 64 73 61 66 65 28 29 20 66 75 6e 63 74 69 6f  adsafe() functio
1d80: 6e 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 20 69  n returns zero i
1d90: 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a  f and only if.**
1da0: 20 53 51 4c 69 74 65 20 77 61 73 20 63 6f 6d 70   SQLite was comp
1db0: 69 6c 65 64 20 77 69 74 68 20 6d 75 74 65 78 69  iled with mutexi
1dc0: 6e 67 20 63 6f 64 65 20 6f 6d 69 74 74 65 64 20  ng code omitted 
1dd0: 64 75 65 20 74 6f 20 74 68 65 0a 2a 2a 20 5b 53  due to the.** [S
1de0: 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
1df0: 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
1e00: 70 74 69 6f 6e 20 62 65 69 6e 67 20 73 65 74 20  ption being set 
1e10: 74 6f 20 30 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  to 0..**.** SQLi
1e20: 74 65 20 63 61 6e 20 62 65 20 63 6f 6d 70 69 6c  te can be compil
1e30: 65 64 20 77 69 74 68 20 6f 72 20 77 69 74 68 6f  ed with or witho
1e40: 75 74 20 6d 75 74 65 78 65 73 2e 20 20 57 68 65  ut mutexes.  Whe
1e50: 6e 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45  n.** the [SQLITE
1e60: 5f 54 48 52 45 41 44 53 41 46 45 5d 20 43 20 70  _THREADSAFE] C p
1e70: 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72  reprocessor macr
1e80: 6f 20 69 73 20 31 20 6f 72 20 32 2c 20 6d 75 74  o is 1 or 2, mut
1e90: 65 78 65 73 0a 2a 2a 20 61 72 65 20 65 6e 61 62  exes.** are enab
1ea0: 6c 65 64 20 61 6e 64 20 53 51 4c 69 74 65 20 69  led and SQLite i
1eb0: 73 20 74 68 72 65 61 64 73 61 66 65 2e 20 20 57  s threadsafe.  W
1ec0: 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49  hen the.** [SQLI
1ed0: 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20 6d  TE_THREADSAFE] m
1ee0: 61 63 72 6f 20 69 73 20 30 2c 20 0a 2a 2a 20 74  acro is 0, .** t
1ef0: 68 65 20 6d 75 74 65 78 65 73 20 61 72 65 20 6f  he mutexes are o
1f00: 6d 69 74 74 65 64 2e 20 20 57 69 74 68 6f 75 74  mitted.  Without
1f10: 20 74 68 65 20 6d 75 74 65 78 65 73 2c 20 69 74   the mutexes, it
1f20: 20 69 73 20 6e 6f 74 20 73 61 66 65 0a 2a 2a 20   is not safe.** 
1f30: 74 6f 20 75 73 65 20 53 51 4c 69 74 65 20 63 6f  to use SQLite co
1f40: 6e 63 75 72 72 65 6e 74 6c 79 20 66 72 6f 6d 20  ncurrently from 
1f50: 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 74 68  more than one th
1f60: 72 65 61 64 2e 0a 2a 2a 0a 2a 2a 20 45 6e 61 62  read..**.** Enab
1f70: 6c 69 6e 67 20 6d 75 74 65 78 65 73 20 69 6e 63  ling mutexes inc
1f80: 75 72 73 20 61 20 6d 65 61 73 75 72 61 62 6c 65  urs a measurable
1f90: 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 70 65 6e   performance pen
1fa0: 61 6c 74 79 2e 0a 2a 2a 20 53 6f 20 69 66 20 73  alty..** So if s
1fb0: 70 65 65 64 20 69 73 20 6f 66 20 75 74 6d 6f 73  peed is of utmos
1fc0: 74 20 69 6d 70 6f 72 74 61 6e 63 65 2c 20 69 74  t importance, it
1fd0: 20 6d 61 6b 65 73 20 73 65 6e 73 65 20 74 6f 20   makes sense to 
1fe0: 64 69 73 61 62 6c 65 0a 2a 2a 20 74 68 65 20 6d  disable.** the m
1ff0: 75 74 65 78 65 73 2e 20 20 42 75 74 20 66 6f 72  utexes.  But for
2000: 20 6d 61 78 69 6d 75 6d 20 73 61 66 65 74 79 2c   maximum safety,
2010: 20 6d 75 74 65 78 65 73 20 73 68 6f 75 6c 64 20   mutexes should 
2020: 62 65 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 20 5e  be enabled..** ^
2030: 54 68 65 20 64 65 66 61 75 6c 74 20 62 65 68 61  The default beha
2040: 76 69 6f 72 20 69 73 20 66 6f 72 20 6d 75 74 65  vior is for mute
2050: 78 65 73 20 74 6f 20 62 65 20 65 6e 61 62 6c 65  xes to be enable
2060: 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e  d..**.** This in
2070: 74 65 72 66 61 63 65 20 63 61 6e 20 62 65 20 75  terface can be u
2080: 73 65 64 20 62 79 20 61 6e 20 61 70 70 6c 69 63  sed by an applic
2090: 61 74 69 6f 6e 20 74 6f 20 6d 61 6b 65 20 73 75  ation to make su
20a0: 72 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 76  re that the.** v
20b0: 65 72 73 69 6f 6e 20 6f 66 20 53 51 4c 69 74 65  ersion of SQLite
20c0: 20 74 68 61 74 20 69 74 20 69 73 20 6c 69 6e 6b   that it is link
20d0: 69 6e 67 20 61 67 61 69 6e 73 74 20 77 61 73 20  ing against was 
20e0: 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a  compiled with.**
20f0: 20 74 68 65 20 64 65 73 69 72 65 64 20 73 65 74   the desired set
2100: 74 69 6e 67 20 6f 66 20 74 68 65 20 5b 53 51 4c  ting of the [SQL
2110: 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20  ITE_THREADSAFE] 
2120: 6d 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 69  macro..**.** Thi
2130: 73 20 69 6e 74 65 72 66 61 63 65 20 6f 6e 6c 79  s interface only
2140: 20 72 65 70 6f 72 74 73 20 6f 6e 20 74 68 65 20   reports on the 
2150: 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6d 75 74  compile-time mut
2160: 65 78 20 73 65 74 74 69 6e 67 0a 2a 2a 20 6f 66  ex setting.** of
2170: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52   the [SQLITE_THR
2180: 45 41 44 53 41 46 45 5d 20 66 6c 61 67 2e 20 20  EADSAFE] flag.  
2190: 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  If SQLite is com
21a0: 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 53 51  piled with.** SQ
21b0: 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d  LITE_THREADSAFE=
21c0: 31 20 6f 72 20 3d 32 20 74 68 65 6e 20 6d 75 74  1 or =2 then mut
21d0: 65 78 65 73 20 61 72 65 20 65 6e 61 62 6c 65 64  exes are enabled
21e0: 20 62 79 20 64 65 66 61 75 6c 74 20 62 75 74 0a   by default but.
21f0: 2a 2a 20 63 61 6e 20 62 65 20 66 75 6c 6c 79 20  ** can be fully 
2200: 6f 72 20 70 61 72 74 69 61 6c 6c 79 20 64 69 73  or partially dis
2210: 61 62 6c 65 64 20 75 73 69 6e 67 20 61 20 63 61  abled using a ca
2220: 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  ll to [sqlite3_c
2230: 6f 6e 66 69 67 28 29 5d 0a 2a 2a 20 77 69 74 68  onfig()].** with
2240: 20 74 68 65 20 76 65 72 62 73 20 5b 53 51 4c 49   the verbs [SQLI
2250: 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45  TE_CONFIG_SINGLE
2260: 54 48 52 45 41 44 5d 2c 20 5b 53 51 4c 49 54 45  THREAD], [SQLITE
2270: 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52  _CONFIG_MULTITHR
2280: 45 41 44 5d 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c  EAD],.** or [SQL
2290: 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41  ITE_CONFIG_SERIA
22a0: 4c 49 5a 45 44 5d 2e 20 20 5e 28 54 68 65 20 72  LIZED].  ^(The r
22b0: 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74  eturn value of t
22c0: 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 74 68  he.** sqlite3_th
22d0: 72 65 61 64 73 61 66 65 28 29 20 66 75 6e 63 74  readsafe() funct
22e0: 69 6f 6e 20 73 68 6f 77 73 20 6f 6e 6c 79 20 74  ion shows only t
22f0: 68 65 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  he compile-time 
2300: 73 65 74 74 69 6e 67 20 6f 66 0a 2a 2a 20 74 68  setting of.** th
2310: 72 65 61 64 20 73 61 66 65 74 79 2c 20 6e 6f 74  read safety, not
2320: 20 61 6e 79 20 72 75 6e 2d 74 69 6d 65 20 63 68   any run-time ch
2330: 61 6e 67 65 73 20 74 6f 20 74 68 61 74 20 73 65  anges to that se
2340: 74 74 69 6e 67 20 6d 61 64 65 20 62 79 0a 2a 2a  tting made by.**
2350: 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28   sqlite3_config(
2360: 29 2e 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64  ). In other word
2370: 73 2c 20 74 68 65 20 72 65 74 75 72 6e 20 76 61  s, the return va
2380: 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33  lue from sqlite3
2390: 5f 74 68 72 65 61 64 73 61 66 65 28 29 0a 2a 2a  _threadsafe().**
23a0: 20 69 73 20 75 6e 63 68 61 6e 67 65 64 20 62 79   is unchanged by
23b0: 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65   calls to sqlite
23c0: 33 5f 63 6f 6e 66 69 67 28 29 2e 29 5e 0a 2a 2a  3_config().)^.**
23d0: 0a 2a 2a 20 53 65 65 20 74 68 65 20 5b 74 68 72  .** See the [thr
23e0: 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 64 6f 63  eading mode] doc
23f0: 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 20 61  umentation for a
2400: 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d  dditional inform
2410: 61 74 69 6f 6e 2e 0a 2a 2f 0a 53 51 4c 49 54 45  ation..*/.SQLITE
2420: 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
2430: 5f 74 68 72 65 61 64 73 61 66 65 28 76 6f 69 64  _threadsafe(void
2440: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2450: 45 46 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e  EF: Database Con
2460: 6e 65 63 74 69 6f 6e 20 48 61 6e 64 6c 65 0a 2a  nection Handle.*
2470: 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 64 61 74  * KEYWORDS: {dat
2480: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
2490: 7d 20 7b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  } {database conn
24a0: 65 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 45  ections}.**.** E
24b0: 61 63 68 20 6f 70 65 6e 20 53 51 4c 69 74 65 20  ach open SQLite 
24c0: 64 61 74 61 62 61 73 65 20 69 73 20 72 65 70 72  database is repr
24d0: 65 73 65 6e 74 65 64 20 62 79 20 61 20 70 6f 69  esented by a poi
24e0: 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61  nter to an insta
24f0: 6e 63 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6f 70  nce of.** the op
2500: 61 71 75 65 20 73 74 72 75 63 74 75 72 65 20 6e  aque structure n
2510: 61 6d 65 64 20 22 73 71 6c 69 74 65 33 22 2e 20  amed "sqlite3". 
2520: 20 49 74 20 69 73 20 75 73 65 66 75 6c 20 74 6f   It is useful to
2530: 20 74 68 69 6e 6b 20 6f 66 20 61 6e 20 73 71 6c   think of an sql
2540: 69 74 65 33 0a 2a 2a 20 70 6f 69 6e 74 65 72 20  ite3.** pointer 
2550: 61 73 20 61 6e 20 6f 62 6a 65 63 74 2e 20 20 54  as an object.  T
2560: 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  he [sqlite3_open
2570: 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70  ()], [sqlite3_op
2580: 65 6e 31 36 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20  en16()], and.** 
2590: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32  [sqlite3_open_v2
25a0: 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 20 61  ()] interfaces a
25b0: 72 65 20 69 74 73 20 63 6f 6e 73 74 72 75 63 74  re its construct
25c0: 6f 72 73 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65  ors, and [sqlite
25d0: 33 5f 63 6c 6f 73 65 28 29 5d 0a 2a 2a 20 61 6e  3_close()].** an
25e0: 64 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  d [sqlite3_close
25f0: 5f 76 32 28 29 5d 20 61 72 65 20 69 74 73 20 64  _v2()] are its d
2600: 65 73 74 72 75 63 74 6f 72 73 2e 20 20 54 68 65  estructors.  The
2610: 72 65 20 61 72 65 20 6d 61 6e 79 20 6f 74 68 65  re are many othe
2620: 72 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20  r.** interfaces 
2630: 28 73 75 63 68 20 61 73 0a 2a 2a 20 5b 73 71 6c  (such as.** [sql
2640: 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
2650: 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  )], [sqlite3_cre
2660: 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 2c  ate_function()],
2670: 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   and.** [sqlite3
2680: 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d  _busy_timeout()]
2690: 20 74 6f 20 6e 61 6d 65 20 62 75 74 20 74 68 72   to name but thr
26a0: 65 65 29 20 74 68 61 74 20 61 72 65 20 6d 65 74  ee) that are met
26b0: 68 6f 64 73 20 6f 6e 20 61 6e 0a 2a 2a 20 73 71  hods on an.** sq
26c0: 6c 69 74 65 33 20 6f 62 6a 65 63 74 2e 0a 2a 2f  lite3 object..*/
26d0: 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
26e0: 73 71 6c 69 74 65 33 20 73 71 6c 69 74 65 33 3b  sqlite3 sqlite3;
26f0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2700: 3a 20 36 34 2d 42 69 74 20 49 6e 74 65 67 65 72  : 64-Bit Integer
2710: 20 54 79 70 65 73 0a 2a 2a 20 4b 45 59 57 4f 52   Types.** KEYWOR
2720: 44 53 3a 20 73 71 6c 69 74 65 5f 69 6e 74 36 34  DS: sqlite_int64
2730: 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 0a 2a   sqlite_uint64.*
2740: 2a 0a 2a 2a 20 42 65 63 61 75 73 65 20 74 68 65  *.** Because the
2750: 72 65 20 69 73 20 6e 6f 20 63 72 6f 73 73 2d 70  re is no cross-p
2760: 6c 61 74 66 6f 72 6d 20 77 61 79 20 74 6f 20 73  latform way to s
2770: 70 65 63 69 66 79 20 36 34 2d 62 69 74 20 69 6e  pecify 64-bit in
2780: 74 65 67 65 72 20 74 79 70 65 73 0a 2a 2a 20 53  teger types.** S
2790: 51 4c 69 74 65 20 69 6e 63 6c 75 64 65 73 20 74  QLite includes t
27a0: 79 70 65 64 65 66 73 20 66 6f 72 20 36 34 2d 62  ypedefs for 64-b
27b0: 69 74 20 73 69 67 6e 65 64 20 61 6e 64 20 75 6e  it signed and un
27c0: 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 73 2e  signed integers.
27d0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
27e0: 65 33 5f 69 6e 74 36 34 20 61 6e 64 20 73 71 6c  e3_int64 and sql
27f0: 69 74 65 33 5f 75 69 6e 74 36 34 20 61 72 65 20  ite3_uint64 are 
2800: 74 68 65 20 70 72 65 66 65 72 72 65 64 20 74 79  the preferred ty
2810: 70 65 20 64 65 66 69 6e 69 74 69 6f 6e 73 2e 0a  pe definitions..
2820: 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 5f 69 6e  ** The sqlite_in
2830: 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 5f 75  t64 and sqlite_u
2840: 69 6e 74 36 34 20 74 79 70 65 73 20 61 72 65 20  int64 types are 
2850: 73 75 70 70 6f 72 74 65 64 20 66 6f 72 20 62 61  supported for ba
2860: 63 6b 77 61 72 64 73 0a 2a 2a 20 63 6f 6d 70 61  ckwards.** compa
2870: 74 69 62 69 6c 69 74 79 20 6f 6e 6c 79 2e 0a 2a  tibility only..*
2880: 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
2890: 33 5f 69 6e 74 36 34 20 61 6e 64 20 73 71 6c 69  3_int64 and sqli
28a0: 74 65 5f 69 6e 74 36 34 20 74 79 70 65 73 20 63  te_int64 types c
28b0: 61 6e 20 73 74 6f 72 65 20 69 6e 74 65 67 65 72  an store integer
28c0: 20 76 61 6c 75 65 73 0a 2a 2a 20 62 65 74 77 65   values.** betwe
28d0: 65 6e 20 2d 39 32 32 33 33 37 32 30 33 36 38 35  en -922337203685
28e0: 34 37 37 35 38 30 38 20 61 6e 64 20 2b 39 32 32  4775808 and +922
28f0: 33 33 37 32 30 33 36 38 35 34 37 37 35 38 30 37  3372036854775807
2900: 20 69 6e 63 6c 75 73 69 76 65 2e 20 20 5e 54 68   inclusive.  ^Th
2910: 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75 69 6e  e.** sqlite3_uin
2920: 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 5f 75  t64 and sqlite_u
2930: 69 6e 74 36 34 20 74 79 70 65 73 20 63 61 6e 20  int64 types can 
2940: 73 74 6f 72 65 20 69 6e 74 65 67 65 72 20 76 61  store integer va
2950: 6c 75 65 73 20 0a 2a 2a 20 62 65 74 77 65 65 6e  lues .** between
2960: 20 30 20 61 6e 64 20 2b 31 38 34 34 36 37 34 34   0 and +18446744
2970: 30 37 33 37 30 39 35 35 31 36 31 35 20 69 6e 63  073709551615 inc
2980: 6c 75 73 69 76 65 2e 0a 2a 2f 0a 23 69 66 64 65  lusive..*/.#ifde
2990: 66 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54  f SQLITE_INT64_T
29a0: 59 50 45 0a 20 20 74 79 70 65 64 65 66 20 53 51  YPE.  typedef SQ
29b0: 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 45 20  LITE_INT64_TYPE 
29c0: 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a 20 20  sqlite_int64;.  
29d0: 74 79 70 65 64 65 66 20 75 6e 73 69 67 6e 65 64  typedef unsigned
29e0: 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59   SQLITE_INT64_TY
29f0: 50 45 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34  PE sqlite_uint64
2a00: 3b 0a 23 65 6c 69 66 20 64 65 66 69 6e 65 64 28  ;.#elif defined(
2a10: 5f 4d 53 43 5f 56 45 52 29 20 7c 7c 20 64 65 66  _MSC_VER) || def
2a20: 69 6e 65 64 28 5f 5f 42 4f 52 4c 41 4e 44 43 5f  ined(__BORLANDC_
2a30: 5f 29 0a 20 20 74 79 70 65 64 65 66 20 5f 5f 69  _).  typedef __i
2a40: 6e 74 36 34 20 73 71 6c 69 74 65 5f 69 6e 74 36  nt64 sqlite_int6
2a50: 34 3b 0a 20 20 74 79 70 65 64 65 66 20 75 6e 73  4;.  typedef uns
2a60: 69 67 6e 65 64 20 5f 5f 69 6e 74 36 34 20 73 71  igned __int64 sq
2a70: 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6c  lite_uint64;.#el
2a80: 73 65 0a 20 20 74 79 70 65 64 65 66 20 6c 6f 6e  se.  typedef lon
2a90: 67 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69 74  g long int sqlit
2aa0: 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70 65 64  e_int64;.  typed
2ab0: 65 66 20 75 6e 73 69 67 6e 65 64 20 6c 6f 6e 67  ef unsigned long
2ac0: 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69 74 65   long int sqlite
2ad0: 5f 75 69 6e 74 36 34 3b 0a 23 65 6e 64 69 66 0a  _uint64;.#endif.
2ae0: 74 79 70 65 64 65 66 20 73 71 6c 69 74 65 5f 69  typedef sqlite_i
2af0: 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 69 6e 74  nt64 sqlite3_int
2b00: 36 34 3b 0a 74 79 70 65 64 65 66 20 73 71 6c 69  64;.typedef sqli
2b10: 74 65 5f 75 69 6e 74 36 34 20 73 71 6c 69 74 65  te_uint64 sqlite
2b20: 33 5f 75 69 6e 74 36 34 3b 0a 0a 2f 2a 0a 2a 2a  3_uint64;../*.**
2b30: 20 49 66 20 63 6f 6d 70 69 6c 69 6e 67 20 66 6f   If compiling fo
2b40: 72 20 61 20 70 72 6f 63 65 73 73 6f 72 20 74 68  r a processor th
2b50: 61 74 20 6c 61 63 6b 73 20 66 6c 6f 61 74 69 6e  at lacks floatin
2b60: 67 20 70 6f 69 6e 74 20 73 75 70 70 6f 72 74 2c  g point support,
2b70: 0a 2a 2a 20 73 75 62 73 74 69 74 75 74 65 20 69  .** substitute i
2b80: 6e 74 65 67 65 72 20 66 6f 72 20 66 6c 6f 61 74  nteger for float
2b90: 69 6e 67 2d 70 6f 69 6e 74 2e 0a 2a 2f 0a 23 69  ing-point..*/.#i
2ba0: 66 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54  fdef SQLITE_OMIT
2bb0: 5f 46 4c 4f 41 54 49 4e 47 5f 50 4f 49 4e 54 0a  _FLOATING_POINT.
2bc0: 23 20 64 65 66 69 6e 65 20 64 6f 75 62 6c 65 20  # define double 
2bd0: 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 0a 23 65  sqlite3_int64.#e
2be0: 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ndif../*.** CAPI
2bf0: 33 52 45 46 3a 20 43 6c 6f 73 69 6e 67 20 41 20  3REF: Closing A 
2c00: 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74  Database Connect
2c10: 69 6f 6e 0a 2a 2a 20 44 45 53 54 52 55 43 54 4f  ion.** DESTRUCTO
2c20: 52 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a  R: sqlite3.**.**
2c30: 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6c   ^The sqlite3_cl
2c40: 6f 73 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65  ose() and sqlite
2c50: 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 72 6f 75  3_close_v2() rou
2c60: 74 69 6e 65 73 20 61 72 65 20 64 65 73 74 72 75  tines are destru
2c70: 63 74 6f 72 73 0a 2a 2a 20 66 6f 72 20 74 68 65  ctors.** for the
2c80: 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63   [sqlite3] objec
2c90: 74 2e 0a 2a 2a 20 5e 43 61 6c 6c 73 20 74 6f 20  t..** ^Calls to 
2ca0: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 20  sqlite3_close() 
2cb0: 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73  and sqlite3_clos
2cc0: 65 5f 76 32 28 29 20 72 65 74 75 72 6e 20 5b 53  e_v2() return [S
2cd0: 51 4c 49 54 45 5f 4f 4b 5d 20 69 66 0a 2a 2a 20  QLITE_OK] if.** 
2ce0: 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62  the [sqlite3] ob
2cf0: 6a 65 63 74 20 69 73 20 73 75 63 63 65 73 73 66  ject is successf
2d00: 75 6c 6c 79 20 64 65 73 74 72 6f 79 65 64 20 61  ully destroyed a
2d10: 6e 64 20 61 6c 6c 20 61 73 73 6f 63 69 61 74 65  nd all associate
2d20: 64 0a 2a 2a 20 72 65 73 6f 75 72 63 65 73 20 61  d.** resources a
2d30: 72 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 2e 0a  re deallocated..
2d40: 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 64 61  **.** ^If the da
2d50: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
2d60: 6e 20 69 73 20 61 73 73 6f 63 69 61 74 65 64 20  n is associated 
2d70: 77 69 74 68 20 75 6e 66 69 6e 61 6c 69 7a 65 64  with unfinalized
2d80: 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74 61   prepared.** sta
2d90: 74 65 6d 65 6e 74 73 20 6f 72 20 75 6e 66 69 6e  tements or unfin
2da0: 69 73 68 65 64 20 73 71 6c 69 74 65 33 5f 62 61  ished sqlite3_ba
2db0: 63 6b 75 70 20 6f 62 6a 65 63 74 73 20 74 68 65  ckup objects the
2dc0: 6e 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28  n sqlite3_close(
2dd0: 29 0a 2a 2a 20 77 69 6c 6c 20 6c 65 61 76 65 20  ).** will leave 
2de0: 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
2df0: 6e 65 63 74 69 6f 6e 20 6f 70 65 6e 20 61 6e 64  nection open and
2e00: 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
2e10: 42 55 53 59 5d 2e 0a 2a 2a 20 5e 49 66 20 73 71  BUSY]..** ^If sq
2e20: 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29  lite3_close_v2()
2e30: 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74 68 20   is called with 
2e40: 75 6e 66 69 6e 61 6c 69 7a 65 64 20 70 72 65 70  unfinalized prep
2e50: 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 0a  ared statements.
2e60: 2a 2a 20 61 6e 64 2f 6f 72 20 75 6e 66 69 6e 69  ** and/or unfini
2e70: 73 68 65 64 20 73 71 6c 69 74 65 33 5f 62 61 63  shed sqlite3_bac
2e80: 6b 75 70 73 2c 20 74 68 65 6e 20 74 68 65 20 64  kups, then the d
2e90: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
2ea0: 6f 6e 20 62 65 63 6f 6d 65 73 0a 2a 2a 20 61 6e  on becomes.** an
2eb0: 20 75 6e 75 73 61 62 6c 65 20 22 7a 6f 6d 62 69   unusable "zombi
2ec0: 65 22 20 77 68 69 63 68 20 77 69 6c 6c 20 61 75  e" which will au
2ed0: 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62 65 20 64  tomatically be d
2ee0: 65 61 6c 6c 6f 63 61 74 65 64 20 77 68 65 6e 20  eallocated when 
2ef0: 74 68 65 0a 2a 2a 20 6c 61 73 74 20 70 72 65 70  the.** last prep
2f00: 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 69  ared statement i
2f10: 73 20 66 69 6e 61 6c 69 7a 65 64 20 6f 72 20 74  s finalized or t
2f20: 68 65 20 6c 61 73 74 20 73 71 6c 69 74 65 33 5f  he last sqlite3_
2f30: 62 61 63 6b 75 70 20 69 73 0a 2a 2a 20 66 69 6e  backup is.** fin
2f40: 69 73 68 65 64 2e 20 20 54 68 65 20 73 71 6c 69  ished.  The sqli
2f50: 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 69  te3_close_v2() i
2f60: 6e 74 65 72 66 61 63 65 20 69 73 20 69 6e 74 65  nterface is inte
2f70: 6e 64 65 64 20 66 6f 72 20 75 73 65 20 77 69 74  nded for use wit
2f80: 68 0a 2a 2a 20 68 6f 73 74 20 6c 61 6e 67 75 61  h.** host langua
2f90: 67 65 73 20 74 68 61 74 20 61 72 65 20 67 61 72  ges that are gar
2fa0: 62 61 67 65 20 63 6f 6c 6c 65 63 74 65 64 2c 20  bage collected, 
2fb0: 61 6e 64 20 77 68 65 72 65 20 74 68 65 20 6f 72  and where the or
2fc0: 64 65 72 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20  der in which.** 
2fd0: 64 65 73 74 72 75 63 74 6f 72 73 20 61 72 65 20  destructors are 
2fe0: 63 61 6c 6c 65 64 20 69 73 20 61 72 62 69 74 72  called is arbitr
2ff0: 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69  ary..**.** Appli
3000: 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 5b  cations should [
3010: 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
3020: 20 7c 20 66 69 6e 61 6c 69 7a 65 5d 20 61 6c 6c   | finalize] all
3030: 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
3040: 6d 65 6e 74 73 5d 2c 0a 2a 2a 20 5b 73 71 6c 69  ments],.** [sqli
3050: 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 20 7c  te3_blob_close |
3060: 20 63 6c 6f 73 65 5d 20 61 6c 6c 20 5b 42 4c 4f   close] all [BLO
3070: 42 20 68 61 6e 64 6c 65 73 5d 2c 20 61 6e 64 20  B handles], and 
3080: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 61 63  .** [sqlite3_bac
3090: 6b 75 70 5f 66 69 6e 69 73 68 20 7c 20 66 69 6e  kup_finish | fin
30a0: 69 73 68 5d 20 61 6c 6c 20 5b 73 71 6c 69 74 65  ish] all [sqlite
30b0: 33 5f 62 61 63 6b 75 70 5d 20 6f 62 6a 65 63 74  3_backup] object
30c0: 73 20 61 73 73 6f 63 69 61 74 65 64 0a 2a 2a 20  s associated.** 
30d0: 77 69 74 68 20 74 68 65 20 5b 73 71 6c 69 74 65  with the [sqlite
30e0: 33 5d 20 6f 62 6a 65 63 74 20 70 72 69 6f 72 20  3] object prior 
30f0: 74 6f 20 61 74 74 65 6d 70 74 69 6e 67 20 74 6f  to attempting to
3100: 20 63 6c 6f 73 65 20 74 68 65 20 6f 62 6a 65 63   close the objec
3110: 74 2e 20 20 5e 49 66 0a 2a 2a 20 73 71 6c 69 74  t.  ^If.** sqlit
3120: 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 69 73  e3_close_v2() is
3130: 20 63 61 6c 6c 65 64 20 6f 6e 20 61 20 5b 64 61   called on a [da
3140: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
3150: 6e 5d 20 74 68 61 74 20 73 74 69 6c 6c 20 68 61  n] that still ha
3160: 73 0a 2a 2a 20 6f 75 74 73 74 61 6e 64 69 6e 67  s.** outstanding
3170: 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
3180: 6d 65 6e 74 73 5d 2c 20 5b 42 4c 4f 42 20 68 61  ments], [BLOB ha
3190: 6e 64 6c 65 73 5d 2c 20 61 6e 64 2f 6f 72 0a 2a  ndles], and/or.*
31a0: 2a 20 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b 75  * [sqlite3_backu
31b0: 70 5d 20 6f 62 6a 65 63 74 73 20 74 68 65 6e 20  p] objects then 
31c0: 69 74 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49  it returns [SQLI
31d0: 54 45 5f 4f 4b 5d 20 61 6e 64 20 74 68 65 20 64  TE_OK] and the d
31e0: 65 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f  eallocation.** o
31f0: 66 20 72 65 73 6f 75 72 63 65 73 20 69 73 20 64  f resources is d
3200: 65 66 65 72 72 65 64 20 75 6e 74 69 6c 20 61 6c  eferred until al
3210: 6c 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  l [prepared stat
3220: 65 6d 65 6e 74 73 5d 2c 20 5b 42 4c 4f 42 20 68  ements], [BLOB h
3230: 61 6e 64 6c 65 73 5d 2c 0a 2a 2a 20 61 6e 64 20  andles],.** and 
3240: 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5d  [sqlite3_backup]
3250: 20 6f 62 6a 65 63 74 73 20 61 72 65 20 61 6c 73   objects are als
3260: 6f 20 64 65 73 74 72 6f 79 65 64 2e 0a 2a 2a 0a  o destroyed..**.
3270: 2a 2a 20 5e 49 66 20 61 6e 20 5b 73 71 6c 69 74  ** ^If an [sqlit
3280: 65 33 5d 20 6f 62 6a 65 63 74 20 69 73 20 64 65  e3] object is de
3290: 73 74 72 6f 79 65 64 20 77 68 69 6c 65 20 61 20  stroyed while a 
32a0: 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 6f  transaction is o
32b0: 70 65 6e 2c 0a 2a 2a 20 74 68 65 20 74 72 61 6e  pen,.** the tran
32c0: 73 61 63 74 69 6f 6e 20 69 73 20 61 75 74 6f 6d  saction is autom
32d0: 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64 20  atically rolled 
32e0: 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  back..**.** The 
32f0: 43 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b  C parameter to [
3300: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 43 29  sqlite3_close(C)
3310: 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63  ] and [sqlite3_c
3320: 6c 6f 73 65 5f 76 32 28 43 29 5d 0a 2a 2a 20 6d  lose_v2(C)].** m
3330: 75 73 74 20 62 65 20 65 69 74 68 65 72 20 61 20  ust be either a 
3340: 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 20  NULL.** pointer 
3350: 6f 72 20 61 6e 20 5b 73 71 6c 69 74 65 33 5d 20  or an [sqlite3] 
3360: 6f 62 6a 65 63 74 20 70 6f 69 6e 74 65 72 20 6f  object pointer o
3370: 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20  btained.** from 
3380: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d  [sqlite3_open()]
3390: 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  , [sqlite3_open1
33a0: 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c  6()], or.** [sql
33b0: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c  ite3_open_v2()],
33c0: 20 61 6e 64 20 6e 6f 74 20 70 72 65 76 69 6f 75   and not previou
33d0: 73 6c 79 20 63 6c 6f 73 65 64 2e 0a 2a 2a 20 5e  sly closed..** ^
33e0: 43 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f  Calling sqlite3_
33f0: 63 6c 6f 73 65 28 29 20 6f 72 20 73 71 6c 69 74  close() or sqlit
3400: 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 77 69  e3_close_v2() wi
3410: 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  th a NULL pointe
3420: 72 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 69 73  r.** argument is
3430: 20 61 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f   a harmless no-o
3440: 70 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  p..*/.SQLITE_API
3450: 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c 6f   int sqlite3_clo
3460: 73 65 28 73 71 6c 69 74 65 33 2a 29 3b 0a 53 51  se(sqlite3*);.SQ
3470: 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
3480: 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 73 71  ite3_close_v2(sq
3490: 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  lite3*);../*.** 
34a0: 54 68 65 20 74 79 70 65 20 66 6f 72 20 61 20 63  The type for a c
34b0: 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
34c0: 2e 0a 2a 2a 20 54 68 69 73 20 69 73 20 6c 65 67  ..** This is leg
34d0: 61 63 79 20 61 6e 64 20 64 65 70 72 65 63 61 74  acy and deprecat
34e0: 65 64 2e 20 20 49 74 20 69 73 20 69 6e 63 6c 75  ed.  It is inclu
34f0: 64 65 64 20 66 6f 72 20 68 69 73 74 6f 72 69 63  ded for historic
3500: 61 6c 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 69 6c  al.** compatibil
3510: 69 74 79 20 61 6e 64 20 69 73 20 6e 6f 74 20 64  ity and is not d
3520: 6f 63 75 6d 65 6e 74 65 64 2e 0a 2a 2f 0a 74 79  ocumented..*/.ty
3530: 70 65 64 65 66 20 69 6e 74 20 28 2a 73 71 6c 69  pedef int (*sqli
3540: 74 65 33 5f 63 61 6c 6c 62 61 63 6b 29 28 76 6f  te3_callback)(vo
3550: 69 64 2a 2c 69 6e 74 2c 63 68 61 72 2a 2a 2c 20  id*,int,char**, 
3560: 63 68 61 72 2a 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  char**);../*.** 
3570: 43 41 50 49 33 52 45 46 3a 20 4f 6e 65 2d 53 74  CAPI3REF: One-St
3580: 65 70 20 51 75 65 72 79 20 45 78 65 63 75 74 69  ep Query Executi
3590: 6f 6e 20 49 6e 74 65 72 66 61 63 65 0a 2a 2a 20  on Interface.** 
35a0: 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a  METHOD: sqlite3.
35b0: 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
35c0: 33 5f 65 78 65 63 28 29 20 69 6e 74 65 72 66 61  3_exec() interfa
35d0: 63 65 20 69 73 20 61 20 63 6f 6e 76 65 6e 69 65  ce is a convenie
35e0: 6e 63 65 20 77 72 61 70 70 65 72 20 61 72 6f 75  nce wrapper arou
35f0: 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70  nd.** [sqlite3_p
3600: 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 20 5b 73  repare_v2()], [s
3610: 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2c 20  qlite3_step()], 
3620: 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e  and [sqlite3_fin
3630: 61 6c 69 7a 65 28 29 5d 2c 0a 2a 2a 20 74 68 61  alize()],.** tha
3640: 74 20 61 6c 6c 6f 77 73 20 61 6e 20 61 70 70 6c  t allows an appl
3650: 69 63 61 74 69 6f 6e 20 74 6f 20 72 75 6e 20 6d  ication to run m
3660: 75 6c 74 69 70 6c 65 20 73 74 61 74 65 6d 65 6e  ultiple statemen
3670: 74 73 20 6f 66 20 53 51 4c 0a 2a 2a 20 77 69 74  ts of SQL.** wit
3680: 68 6f 75 74 20 68 61 76 69 6e 67 20 74 6f 20 75  hout having to u
3690: 73 65 20 61 20 6c 6f 74 20 6f 66 20 43 20 63 6f  se a lot of C co
36a0: 64 65 2e 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  de. .**.** ^The 
36b0: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69  sqlite3_exec() i
36c0: 6e 74 65 72 66 61 63 65 20 72 75 6e 73 20 7a 65  nterface runs ze
36d0: 72 6f 20 6f 72 20 6d 6f 72 65 20 55 54 46 2d 38  ro or more UTF-8
36e0: 20 65 6e 63 6f 64 65 64 2c 0a 2a 2a 20 73 65 6d   encoded,.** sem
36f0: 69 63 6f 6c 6f 6e 2d 73 65 70 61 72 61 74 65 20  icolon-separate 
3700: 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 70  SQL statements p
3710: 61 73 73 65 64 20 69 6e 74 6f 20 69 74 73 20 32  assed into its 2
3720: 6e 64 20 61 72 67 75 6d 65 6e 74 2c 0a 2a 2a 20  nd argument,.** 
3730: 69 6e 20 74 68 65 20 63 6f 6e 74 65 78 74 20 6f  in the context o
3740: 66 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  f the [database 
3750: 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 70 61 73 73  connection] pass
3760: 65 64 20 69 6e 20 61 73 20 69 74 73 20 31 73 74  ed in as its 1st
3770: 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 2e 20 20 5e  .** argument.  ^
3780: 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  If the callback 
3790: 66 75 6e 63 74 69 6f 6e 20 6f 66 20 74 68 65 20  function of the 
37a0: 33 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a  3rd argument to.
37b0: 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  ** sqlite3_exec(
37c0: 29 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74  ) is not NULL, t
37d0: 68 65 6e 20 69 74 20 69 73 20 69 6e 76 6f 6b 65  hen it is invoke
37e0: 64 20 66 6f 72 20 65 61 63 68 20 72 65 73 75 6c  d for each resul
37f0: 74 20 72 6f 77 0a 2a 2a 20 63 6f 6d 69 6e 67 20  t row.** coming 
3800: 6f 75 74 20 6f 66 20 74 68 65 20 65 76 61 6c 75  out of the evalu
3810: 61 74 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65  ated SQL stateme
3820: 6e 74 73 2e 20 20 5e 54 68 65 20 34 74 68 20 61  nts.  ^The 4th a
3830: 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 73 71  rgument to.** sq
3840: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20  lite3_exec() is 
3850: 72 65 6c 61 79 65 64 20 74 68 72 6f 75 67 68 20  relayed through 
3860: 74 6f 20 74 68 65 20 31 73 74 20 61 72 67 75 6d  to the 1st argum
3870: 65 6e 74 20 6f 66 20 65 61 63 68 0a 2a 2a 20 63  ent of each.** c
3880: 61 6c 6c 62 61 63 6b 20 69 6e 76 6f 63 61 74 69  allback invocati
3890: 6f 6e 2e 20 20 5e 49 66 20 74 68 65 20 63 61 6c  on.  ^If the cal
38a0: 6c 62 61 63 6b 20 70 6f 69 6e 74 65 72 20 74 6f  lback pointer to
38b0: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a   sqlite3_exec().
38c0: 2a 2a 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e  ** is NULL, then
38d0: 20 6e 6f 20 63 61 6c 6c 62 61 63 6b 20 69 73 20   no callback is 
38e0: 65 76 65 72 20 69 6e 76 6f 6b 65 64 20 61 6e 64  ever invoked and
38f0: 20 72 65 73 75 6c 74 20 72 6f 77 73 20 61 72 65   result rows are
3900: 0a 2a 2a 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a  .** ignored..**.
3910: 2a 2a 20 5e 49 66 20 61 6e 20 65 72 72 6f 72 20  ** ^If an error 
3920: 6f 63 63 75 72 73 20 77 68 69 6c 65 20 65 76 61  occurs while eva
3930: 6c 75 61 74 69 6e 67 20 74 68 65 20 53 51 4c 20  luating the SQL 
3940: 73 74 61 74 65 6d 65 6e 74 73 20 70 61 73 73 65  statements passe
3950: 64 20 69 6e 74 6f 0a 2a 2a 20 73 71 6c 69 74 65  d into.** sqlite
3960: 33 5f 65 78 65 63 28 29 2c 20 74 68 65 6e 20 65  3_exec(), then e
3970: 78 65 63 75 74 69 6f 6e 20 6f 66 20 74 68 65 20  xecution of the 
3980: 63 75 72 72 65 6e 74 20 73 74 61 74 65 6d 65 6e  current statemen
3990: 74 20 73 74 6f 70 73 20 61 6e 64 0a 2a 2a 20 73  t stops and.** s
39a0: 75 62 73 65 71 75 65 6e 74 20 73 74 61 74 65 6d  ubsequent statem
39b0: 65 6e 74 73 20 61 72 65 20 73 6b 69 70 70 65 64  ents are skipped
39c0: 2e 20 20 5e 49 66 20 74 68 65 20 35 74 68 20 70  .  ^If the 5th p
39d0: 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
39e0: 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20 69 73  te3_exec().** is
39f0: 20 6e 6f 74 20 4e 55 4c 4c 20 74 68 65 6e 20 61   not NULL then a
3a00: 6e 79 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  ny error message
3a10: 20 69 73 20 77 72 69 74 74 65 6e 20 69 6e 74 6f   is written into
3a20: 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64   memory obtained
3a30: 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  .** from [sqlite
3a40: 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 61 6e 64 20  3_malloc()] and 
3a50: 70 61 73 73 65 64 20 62 61 63 6b 20 74 68 72 6f  passed back thro
3a60: 75 67 68 20 74 68 65 20 35 74 68 20 70 61 72 61  ugh the 5th para
3a70: 6d 65 74 65 72 2e 0a 2a 2a 20 54 6f 20 61 76 6f  meter..** To avo
3a80: 69 64 20 6d 65 6d 6f 72 79 20 6c 65 61 6b 73 2c  id memory leaks,
3a90: 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
3aa0: 20 73 68 6f 75 6c 64 20 69 6e 76 6f 6b 65 20 5b   should invoke [
3ab0: 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 0a  sqlite3_free()].
3ac0: 2a 2a 20 6f 6e 20 65 72 72 6f 72 20 6d 65 73 73  ** on error mess
3ad0: 61 67 65 20 73 74 72 69 6e 67 73 20 72 65 74 75  age strings retu
3ae0: 72 6e 65 64 20 74 68 72 6f 75 67 68 20 74 68 65  rned through the
3af0: 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 6f   5th parameter o
3b00: 66 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65  f.** sqlite3_exe
3b10: 63 28 29 20 61 66 74 65 72 20 74 68 65 20 65 72  c() after the er
3b20: 72 6f 72 20 6d 65 73 73 61 67 65 20 73 74 72 69  ror message stri
3b30: 6e 67 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20  ng is no longer 
3b40: 6e 65 65 64 65 64 2e 0a 2a 2a 20 5e 49 66 20 74  needed..** ^If t
3b50: 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72  he 5th parameter
3b60: 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63   to sqlite3_exec
3b70: 28 29 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 61  () is not NULL a
3b80: 6e 64 20 6e 6f 20 65 72 72 6f 72 73 0a 2a 2a 20  nd no errors.** 
3b90: 6f 63 63 75 72 2c 20 74 68 65 6e 20 73 71 6c 69  occur, then sqli
3ba0: 74 65 33 5f 65 78 65 63 28 29 20 73 65 74 73 20  te3_exec() sets 
3bb0: 74 68 65 20 70 6f 69 6e 74 65 72 20 69 6e 20 69  the pointer in i
3bc0: 74 73 20 35 74 68 20 70 61 72 61 6d 65 74 65 72  ts 5th parameter
3bd0: 20 74 6f 0a 2a 2a 20 4e 55 4c 4c 20 62 65 66 6f   to.** NULL befo
3be0: 72 65 20 72 65 74 75 72 6e 69 6e 67 2e 0a 2a 2a  re returning..**
3bf0: 0a 2a 2a 20 5e 49 66 20 61 6e 20 73 71 6c 69 74  .** ^If an sqlit
3c00: 65 33 5f 65 78 65 63 28 29 20 63 61 6c 6c 62 61  e3_exec() callba
3c10: 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a  ck returns non-z
3c20: 65 72 6f 2c 20 74 68 65 20 73 71 6c 69 74 65 33  ero, the sqlite3
3c30: 5f 65 78 65 63 28 29 0a 2a 2a 20 72 6f 75 74 69  _exec().** routi
3c40: 6e 65 20 72 65 74 75 72 6e 73 20 53 51 4c 49 54  ne returns SQLIT
3c50: 45 5f 41 42 4f 52 54 20 77 69 74 68 6f 75 74 20  E_ABORT without 
3c60: 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20 63 61 6c  invoking the cal
3c70: 6c 62 61 63 6b 20 61 67 61 69 6e 20 61 6e 64 0a  lback again and.
3c80: 2a 2a 20 77 69 74 68 6f 75 74 20 72 75 6e 6e 69  ** without runni
3c90: 6e 67 20 61 6e 79 20 73 75 62 73 65 71 75 65 6e  ng any subsequen
3ca0: 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  t SQL statements
3cb0: 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 32 6e 64  ..**.** ^The 2nd
3cc0: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
3cd0: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20   sqlite3_exec() 
3ce0: 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
3cf0: 6e 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62  n is the.** numb
3d00: 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e  er of columns in
3d10: 20 74 68 65 20 72 65 73 75 6c 74 2e 20 20 5e 54   the result.  ^T
3d20: 68 65 20 33 72 64 20 61 72 67 75 6d 65 6e 74 20  he 3rd argument 
3d30: 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 65  to the sqlite3_e
3d40: 78 65 63 28 29 0a 2a 2a 20 63 61 6c 6c 62 61 63  xec().** callbac
3d50: 6b 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66  k is an array of
3d60: 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 73 74 72   pointers to str
3d70: 69 6e 67 73 20 6f 62 74 61 69 6e 65 64 20 61 73  ings obtained as
3d80: 20 69 66 20 66 72 6f 6d 0a 2a 2a 20 5b 73 71 6c   if from.** [sql
3d90: 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
3da0: 28 29 5d 2c 20 6f 6e 65 20 66 6f 72 20 65 61 63  ()], one for eac
3db0: 68 20 63 6f 6c 75 6d 6e 2e 20 20 5e 49 66 20 61  h column.  ^If a
3dc0: 6e 20 65 6c 65 6d 65 6e 74 20 6f 66 20 61 0a 2a  n element of a.*
3dd0: 2a 20 72 65 73 75 6c 74 20 72 6f 77 20 69 73 20  * result row is 
3de0: 4e 55 4c 4c 20 74 68 65 6e 20 74 68 65 20 63 6f  NULL then the co
3df0: 72 72 65 73 70 6f 6e 64 69 6e 67 20 73 74 72 69  rresponding stri
3e00: 6e 67 20 70 6f 69 6e 74 65 72 20 66 6f 72 20 74  ng pointer for t
3e10: 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78  he.** sqlite3_ex
3e20: 65 63 28 29 20 63 61 6c 6c 62 61 63 6b 20 69 73  ec() callback is
3e30: 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e   a NULL pointer.
3e40: 20 20 5e 54 68 65 20 34 74 68 20 61 72 67 75 6d    ^The 4th argum
3e50: 65 6e 74 20 74 6f 20 74 68 65 0a 2a 2a 20 73 71  ent to the.** sq
3e60: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 63 61 6c  lite3_exec() cal
3e70: 6c 62 61 63 6b 20 69 73 20 61 6e 20 61 72 72 61  lback is an arra
3e80: 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f  y of pointers to
3e90: 20 73 74 72 69 6e 67 73 20 77 68 65 72 65 20 65   strings where e
3ea0: 61 63 68 0a 2a 2a 20 65 6e 74 72 79 20 72 65 70  ach.** entry rep
3eb0: 72 65 73 65 6e 74 73 20 74 68 65 20 6e 61 6d 65  resents the name
3ec0: 20 6f 66 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e   of correspondin
3ed0: 67 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20  g result column 
3ee0: 61 73 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66  as obtained.** f
3ef0: 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  rom [sqlite3_col
3f00: 75 6d 6e 5f 6e 61 6d 65 28 29 5d 2e 0a 2a 2a 0a  umn_name()]..**.
3f10: 2a 2a 20 5e 49 66 20 74 68 65 20 32 6e 64 20 70  ** ^If the 2nd p
3f20: 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
3f30: 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 61 20  te3_exec() is a 
3f40: 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 61 20  NULL pointer, a 
3f50: 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 61 6e  pointer.** to an
3f60: 20 65 6d 70 74 79 20 73 74 72 69 6e 67 2c 20 6f   empty string, o
3f70: 72 20 61 20 70 6f 69 6e 74 65 72 20 74 68 61 74  r a pointer that
3f80: 20 63 6f 6e 74 61 69 6e 73 20 6f 6e 6c 79 20 77   contains only w
3f90: 68 69 74 65 73 70 61 63 65 20 61 6e 64 2f 6f 72  hitespace and/or
3fa0: 20 0a 2a 2a 20 53 51 4c 20 63 6f 6d 6d 65 6e 74   .** SQL comment
3fb0: 73 2c 20 74 68 65 6e 20 6e 6f 20 53 51 4c 20 73  s, then no SQL s
3fc0: 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20 65 76  tatements are ev
3fd0: 61 6c 75 61 74 65 64 20 61 6e 64 20 74 68 65 20  aluated and the 
3fe0: 64 61 74 61 62 61 73 65 0a 2a 2a 20 69 73 20 6e  database.** is n
3ff0: 6f 74 20 63 68 61 6e 67 65 64 2e 0a 2a 2a 0a 2a  ot changed..**.*
4000: 2a 20 52 65 73 74 72 69 63 74 69 6f 6e 73 3a 0a  * Restrictions:.
4010: 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c  **.** <ul>.** <l
4020: 69 3e 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  i> The applicati
4030: 6f 6e 20 6d 75 73 74 20 65 6e 73 75 72 65 20 74  on must ensure t
4040: 68 61 74 20 74 68 65 20 31 73 74 20 70 61 72 61  hat the 1st para
4050: 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
4060: 5f 65 78 65 63 28 29 0a 2a 2a 20 20 20 20 20 20  _exec().**      
4070: 69 73 20 61 20 76 61 6c 69 64 20 61 6e 64 20 6f  is a valid and o
4080: 70 65 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f  pen [database co
4090: 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 20 3c 6c  nnection]..** <l
40a0: 69 3e 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  i> The applicati
40b0: 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 63 6c 6f 73  on must not clos
40c0: 65 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  e the [database 
40d0: 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73 70 65 63  connection] spec
40e0: 69 66 69 65 64 20 62 79 0a 2a 2a 20 20 20 20 20  ified by.**     
40f0: 20 74 68 65 20 31 73 74 20 70 61 72 61 6d 65 74   the 1st paramet
4100: 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78  er to sqlite3_ex
4110: 65 63 28 29 20 77 68 69 6c 65 20 73 71 6c 69 74  ec() while sqlit
4120: 65 33 5f 65 78 65 63 28 29 20 69 73 20 72 75 6e  e3_exec() is run
4130: 6e 69 6e 67 2e 0a 2a 2a 20 3c 6c 69 3e 20 54 68  ning..** <li> Th
4140: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75  e application mu
4150: 73 74 20 6e 6f 74 20 6d 6f 64 69 66 79 20 74 68  st not modify th
4160: 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  e SQL statement 
4170: 74 65 78 74 20 70 61 73 73 65 64 20 69 6e 74 6f  text passed into
4180: 0a 2a 2a 20 20 20 20 20 20 74 68 65 20 32 6e 64  .**      the 2nd
4190: 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 73 71   parameter of sq
41a0: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 77 68 69  lite3_exec() whi
41b0: 6c 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  le sqlite3_exec(
41c0: 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a  ) is running..**
41d0: 20 3c 2f 75 6c 3e 0a 2a 2f 0a 53 51 4c 49 54 45   </ul>.*/.SQLITE
41e0: 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
41f0: 5f 65 78 65 63 28 0a 20 20 73 71 6c 69 74 65 33  _exec(.  sqlite3
4200: 2a 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20  *,              
4210: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4220: 20 20 20 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64      /* An open d
4230: 61 74 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e  atabase */.  con
4240: 73 74 20 63 68 61 72 20 2a 73 71 6c 2c 20 20 20  st char *sql,   
4250: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4260: 20 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 74          /* SQL t
4270: 6f 20 62 65 20 65 76 61 6c 75 61 74 65 64 20 2a  o be evaluated *
4280: 2f 0a 20 20 69 6e 74 20 28 2a 63 61 6c 6c 62 61  /.  int (*callba
4290: 63 6b 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68  ck)(void*,int,ch
42a0: 61 72 2a 2a 2c 63 68 61 72 2a 2a 29 2c 20 20 2f  ar**,char**),  /
42b0: 2a 20 43 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  * Callback funct
42c0: 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 2c  ion */.  void *,
42d0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
42e0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
42f0: 20 20 20 20 2f 2a 20 31 73 74 20 61 72 67 75 6d      /* 1st argum
4300: 65 6e 74 20 74 6f 20 63 61 6c 6c 62 61 63 6b 20  ent to callback 
4310: 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 65 72 72 6d  */.  char **errm
4320: 73 67 20 20 20 20 20 20 20 20 20 20 20 20 20 20  sg              
4330: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4340: 2f 2a 20 45 72 72 6f 72 20 6d 73 67 20 77 72 69  /* Error msg wri
4350: 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a  tten here */.);.
4360: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
4370: 20 52 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a   Result Codes.**
4380: 20 4b 45 59 57 4f 52 44 53 3a 20 7b 72 65 73 75   KEYWORDS: {resu
4390: 6c 74 20 63 6f 64 65 20 64 65 66 69 6e 69 74 69  lt code definiti
43a0: 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 4d 61 6e 79 20  ons}.**.** Many 
43b0: 53 51 4c 69 74 65 20 66 75 6e 63 74 69 6f 6e 73  SQLite functions
43c0: 20 72 65 74 75 72 6e 20 61 6e 20 69 6e 74 65 67   return an integ
43d0: 65 72 20 72 65 73 75 6c 74 20 63 6f 64 65 20 66  er result code f
43e0: 72 6f 6d 20 74 68 65 20 73 65 74 20 73 68 6f 77  rom the set show
43f0: 6e 0a 2a 2a 20 68 65 72 65 20 69 6e 20 6f 72 64  n.** here in ord
4400: 65 72 20 74 6f 20 69 6e 64 69 63 61 74 65 20 73  er to indicate s
4410: 75 63 63 65 73 73 20 6f 72 20 66 61 69 6c 75 72  uccess or failur
4420: 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 65 72 72  e..**.** New err
4430: 6f 72 20 63 6f 64 65 73 20 6d 61 79 20 62 65 20  or codes may be 
4440: 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20  added in future 
4450: 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69  versions of SQLi
4460: 74 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  te..**.** See al
4470: 73 6f 3a 20 5b 65 78 74 65 6e 64 65 64 20 72 65  so: [extended re
4480: 73 75 6c 74 20 63 6f 64 65 20 64 65 66 69 6e 69  sult code defini
4490: 74 69 6f 6e 73 5d 0a 2a 2f 0a 23 64 65 66 69 6e  tions].*/.#defin
44a0: 65 20 53 51 4c 49 54 45 5f 4f 4b 20 20 20 20 20  e SQLITE_OK     
44b0: 20 20 20 20 20 20 30 20 20 20 2f 2a 20 53 75 63        0   /* Suc
44c0: 63 65 73 73 66 75 6c 20 72 65 73 75 6c 74 20 2a  cessful result *
44d0: 2f 0a 2f 2a 20 62 65 67 69 6e 6e 69 6e 67 2d 6f  /./* beginning-o
44e0: 66 2d 65 72 72 6f 72 2d 63 6f 64 65 73 20 2a 2f  f-error-codes */
44f0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4500: 45 52 52 4f 52 20 20 20 20 20 20 20 20 31 20 20  ERROR        1  
4510: 20 2f 2a 20 53 51 4c 20 65 72 72 6f 72 20 6f 72   /* SQL error or
4520: 20 6d 69 73 73 69 6e 67 20 64 61 74 61 62 61 73   missing databas
4530: 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  e */.#define SQL
4540: 49 54 45 5f 49 4e 54 45 52 4e 41 4c 20 20 20 20  ITE_INTERNAL    
4550: 20 32 20 20 20 2f 2a 20 49 6e 74 65 72 6e 61 6c   2   /* Internal
4560: 20 6c 6f 67 69 63 20 65 72 72 6f 72 20 69 6e 20   logic error in 
4570: 53 51 4c 69 74 65 20 2a 2f 0a 23 64 65 66 69 6e  SQLite */.#defin
4580: 65 20 53 51 4c 49 54 45 5f 50 45 52 4d 20 20 20  e SQLITE_PERM   
4590: 20 20 20 20 20 20 33 20 20 20 2f 2a 20 41 63 63        3   /* Acc
45a0: 65 73 73 20 70 65 72 6d 69 73 73 69 6f 6e 20 64  ess permission d
45b0: 65 6e 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65  enied */.#define
45c0: 20 53 51 4c 49 54 45 5f 41 42 4f 52 54 20 20 20   SQLITE_ABORT   
45d0: 20 20 20 20 20 34 20 20 20 2f 2a 20 43 61 6c 6c       4   /* Call
45e0: 62 61 63 6b 20 72 6f 75 74 69 6e 65 20 72 65 71  back routine req
45f0: 75 65 73 74 65 64 20 61 6e 20 61 62 6f 72 74 20  uested an abort 
4600: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
4610: 45 5f 42 55 53 59 20 20 20 20 20 20 20 20 20 35  E_BUSY         5
4620: 20 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62 61     /* The databa
4630: 73 65 20 66 69 6c 65 20 69 73 20 6c 6f 63 6b 65  se file is locke
4640: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  d */.#define SQL
4650: 49 54 45 5f 4c 4f 43 4b 45 44 20 20 20 20 20 20  ITE_LOCKED      
4660: 20 36 20 20 20 2f 2a 20 41 20 74 61 62 6c 65 20   6   /* A table 
4670: 69 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  in the database 
4680: 69 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64 65  is locked */.#de
4690: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 4d 45  fine SQLITE_NOME
46a0: 4d 20 20 20 20 20 20 20 20 37 20 20 20 2f 2a 20  M        7   /* 
46b0: 41 20 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 65  A malloc() faile
46c0: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  d */.#define SQL
46d0: 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 20 20 20  ITE_READONLY    
46e0: 20 38 20 20 20 2f 2a 20 41 74 74 65 6d 70 74 20   8   /* Attempt 
46f0: 74 6f 20 77 72 69 74 65 20 61 20 72 65 61 64 6f  to write a reado
4700: 6e 6c 79 20 64 61 74 61 62 61 73 65 20 2a 2f 0a  nly database */.
4710: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
4720: 4e 54 45 52 52 55 50 54 20 20 20 20 39 20 20 20  NTERRUPT    9   
4730: 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20 74 65 72  /* Operation ter
4740: 6d 69 6e 61 74 65 64 20 62 79 20 73 71 6c 69 74  minated by sqlit
4750: 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 2a 2f  e3_interrupt()*/
4760: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4770: 49 4f 45 52 52 20 20 20 20 20 20 20 31 30 20 20  IOERR       10  
4780: 20 2f 2a 20 53 6f 6d 65 20 6b 69 6e 64 20 6f 66   /* Some kind of
4790: 20 64 69 73 6b 20 49 2f 4f 20 65 72 72 6f 72 20   disk I/O error 
47a0: 6f 63 63 75 72 72 65 64 20 2a 2f 0a 23 64 65 66  occurred */.#def
47b0: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 52 52 55  ine SQLITE_CORRU
47c0: 50 54 20 20 20 20 20 31 31 20 20 20 2f 2a 20 54  PT     11   /* T
47d0: 68 65 20 64 61 74 61 62 61 73 65 20 64 69 73 6b  he database disk
47e0: 20 69 6d 61 67 65 20 69 73 20 6d 61 6c 66 6f 72   image is malfor
47f0: 6d 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  med */.#define S
4800: 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 20 20  QLITE_NOTFOUND  
4810: 20 20 31 32 20 20 20 2f 2a 20 55 6e 6b 6e 6f 77    12   /* Unknow
4820: 6e 20 6f 70 63 6f 64 65 20 69 6e 20 73 71 6c 69  n opcode in sqli
4830: 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c  te3_file_control
4840: 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  () */.#define SQ
4850: 4c 49 54 45 5f 46 55 4c 4c 20 20 20 20 20 20 20  LITE_FULL       
4860: 20 31 33 20 20 20 2f 2a 20 49 6e 73 65 72 74 69   13   /* Inserti
4870: 6f 6e 20 66 61 69 6c 65 64 20 62 65 63 61 75 73  on failed becaus
4880: 65 20 64 61 74 61 62 61 73 65 20 69 73 20 66 75  e database is fu
4890: 6c 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ll */.#define SQ
48a0: 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 20 20  LITE_CANTOPEN   
48b0: 20 31 34 20 20 20 2f 2a 20 55 6e 61 62 6c 65 20   14   /* Unable 
48c0: 74 6f 20 6f 70 65 6e 20 74 68 65 20 64 61 74 61  to open the data
48d0: 62 61 73 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65  base file */.#de
48e0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 52 4f 54  fine SQLITE_PROT
48f0: 4f 43 4f 4c 20 20 20 20 31 35 20 20 20 2f 2a 20  OCOL    15   /* 
4900: 44 61 74 61 62 61 73 65 20 6c 6f 63 6b 20 70 72  Database lock pr
4910: 6f 74 6f 63 6f 6c 20 65 72 72 6f 72 20 2a 2f 0a  otocol error */.
4920: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45  #define SQLITE_E
4930: 4d 50 54 59 20 20 20 20 20 20 20 31 36 20 20 20  MPTY       16   
4940: 2f 2a 20 44 61 74 61 62 61 73 65 20 69 73 20 65  /* Database is e
4950: 6d 70 74 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20  mpty */.#define 
4960: 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 20 20 20  SQLITE_SCHEMA   
4970: 20 20 20 31 37 20 20 20 2f 2a 20 54 68 65 20 64     17   /* The d
4980: 61 74 61 62 61 73 65 20 73 63 68 65 6d 61 20 63  atabase schema c
4990: 68 61 6e 67 65 64 20 2a 2f 0a 23 64 65 66 69 6e  hanged */.#defin
49a0: 65 20 53 51 4c 49 54 45 5f 54 4f 4f 42 49 47 20  e SQLITE_TOOBIG 
49b0: 20 20 20 20 20 31 38 20 20 20 2f 2a 20 53 74 72       18   /* Str
49c0: 69 6e 67 20 6f 72 20 42 4c 4f 42 20 65 78 63 65  ing or BLOB exce
49d0: 65 64 73 20 73 69 7a 65 20 6c 69 6d 69 74 20 2a  eds size limit *
49e0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
49f0: 5f 43 4f 4e 53 54 52 41 49 4e 54 20 20 31 39 20  _CONSTRAINT  19 
4a00: 20 20 2f 2a 20 41 62 6f 72 74 20 64 75 65 20 74    /* Abort due t
4a10: 6f 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f  o constraint vio
4a20: 6c 61 74 69 6f 6e 20 2a 2f 0a 23 64 65 66 69 6e  lation */.#defin
4a30: 65 20 53 51 4c 49 54 45 5f 4d 49 53 4d 41 54 43  e SQLITE_MISMATC
4a40: 48 20 20 20 20 32 30 20 20 20 2f 2a 20 44 61 74  H    20   /* Dat
4a50: 61 20 74 79 70 65 20 6d 69 73 6d 61 74 63 68 20  a type mismatch 
4a60: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
4a70: 45 5f 4d 49 53 55 53 45 20 20 20 20 20 20 32 31  E_MISUSE      21
4a80: 20 20 20 2f 2a 20 4c 69 62 72 61 72 79 20 75 73     /* Library us
4a90: 65 64 20 69 6e 63 6f 72 72 65 63 74 6c 79 20 2a  ed incorrectly *
4aa0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4ab0: 5f 4e 4f 4c 46 53 20 20 20 20 20 20 20 32 32 20  _NOLFS       22 
4ac0: 20 20 2f 2a 20 55 73 65 73 20 4f 53 20 66 65 61    /* Uses OS fea
4ad0: 74 75 72 65 73 20 6e 6f 74 20 73 75 70 70 6f 72  tures not suppor
4ae0: 74 65 64 20 6f 6e 20 68 6f 73 74 20 2a 2f 0a 23  ted on host */.#
4af0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 55  define SQLITE_AU
4b00: 54 48 20 20 20 20 20 20 20 20 32 33 20 20 20 2f  TH        23   /
4b10: 2a 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20  * Authorization 
4b20: 64 65 6e 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e  denied */.#defin
4b30: 65 20 53 51 4c 49 54 45 5f 46 4f 52 4d 41 54 20  e SQLITE_FORMAT 
4b40: 20 20 20 20 20 32 34 20 20 20 2f 2a 20 41 75 78       24   /* Aux
4b50: 69 6c 69 61 72 79 20 64 61 74 61 62 61 73 65 20  iliary database 
4b60: 66 6f 72 6d 61 74 20 65 72 72 6f 72 20 2a 2f 0a  format error */.
4b70: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52  #define SQLITE_R
4b80: 41 4e 47 45 20 20 20 20 20 20 20 32 35 20 20 20  ANGE       25   
4b90: 2f 2a 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  /* 2nd parameter
4ba0: 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64   to sqlite3_bind
4bb0: 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 20 2a 2f   out of range */
4bc0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4bd0: 4e 4f 54 41 44 42 20 20 20 20 20 20 32 36 20 20  NOTADB      26  
4be0: 20 2f 2a 20 46 69 6c 65 20 6f 70 65 6e 65 64 20   /* File opened 
4bf0: 74 68 61 74 20 69 73 20 6e 6f 74 20 61 20 64 61  that is not a da
4c00: 74 61 62 61 73 65 20 66 69 6c 65 20 2a 2f 0a 23  tabase file */.#
4c10: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f  define SQLITE_NO
4c20: 54 49 43 45 20 20 20 20 20 20 32 37 20 20 20 2f  TICE      27   /
4c30: 2a 20 4e 6f 74 69 66 69 63 61 74 69 6f 6e 73 20  * Notifications 
4c40: 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6c 6f 67  from sqlite3_log
4c50: 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  () */.#define SQ
4c60: 4c 49 54 45 5f 57 41 52 4e 49 4e 47 20 20 20 20  LITE_WARNING    
4c70: 20 32 38 20 20 20 2f 2a 20 57 61 72 6e 69 6e 67   28   /* Warning
4c80: 73 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6c  s from sqlite3_l
4c90: 6f 67 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20  og() */.#define 
4ca0: 53 51 4c 49 54 45 5f 52 4f 57 20 20 20 20 20 20  SQLITE_ROW      
4cb0: 20 20 20 31 30 30 20 20 2f 2a 20 73 71 6c 69 74     100  /* sqlit
4cc0: 65 33 5f 73 74 65 70 28 29 20 68 61 73 20 61 6e  e3_step() has an
4cd0: 6f 74 68 65 72 20 72 6f 77 20 72 65 61 64 79 20  other row ready 
4ce0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
4cf0: 45 5f 44 4f 4e 45 20 20 20 20 20 20 20 20 31 30  E_DONE        10
4d00: 31 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 73 74  1  /* sqlite3_st
4d10: 65 70 28 29 20 68 61 73 20 66 69 6e 69 73 68 65  ep() has finishe
4d20: 64 20 65 78 65 63 75 74 69 6e 67 20 2a 2f 0a 2f  d executing */./
4d30: 2a 20 65 6e 64 2d 6f 66 2d 65 72 72 6f 72 2d 63  * end-of-error-c
4d40: 6f 64 65 73 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43  odes */../*.** C
4d50: 41 50 49 33 52 45 46 3a 20 45 78 74 65 6e 64 65  API3REF: Extende
4d60: 64 20 52 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a  d Result Codes.*
4d70: 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 65 78 74  * KEYWORDS: {ext
4d80: 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
4d90: 65 20 64 65 66 69 6e 69 74 69 6f 6e 73 7d 0a 2a  e definitions}.*
4da0: 2a 0a 2a 2a 20 49 6e 20 69 74 73 20 64 65 66 61  *.** In its defa
4db0: 75 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ult configuratio
4dc0: 6e 2c 20 53 51 4c 69 74 65 20 41 50 49 20 72 6f  n, SQLite API ro
4dd0: 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 6f 6e  utines return on
4de0: 65 20 6f 66 20 33 30 20 69 6e 74 65 67 65 72 0a  e of 30 integer.
4df0: 2a 2a 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 73  ** [result codes
4e00: 5d 2e 20 20 48 6f 77 65 76 65 72 2c 20 65 78 70  ].  However, exp
4e10: 65 72 69 65 6e 63 65 20 68 61 73 20 73 68 6f 77  erience has show
4e20: 6e 20 74 68 61 74 20 6d 61 6e 79 20 6f 66 0a 2a  n that many of.*
4e30: 2a 20 74 68 65 73 65 20 72 65 73 75 6c 74 20 63  * these result c
4e40: 6f 64 65 73 20 61 72 65 20 74 6f 6f 20 63 6f 61  odes are too coa
4e50: 72 73 65 2d 67 72 61 69 6e 65 64 2e 20 20 54 68  rse-grained.  Th
4e60: 65 79 20 64 6f 20 6e 6f 74 20 70 72 6f 76 69 64  ey do not provid
4e70: 65 20 61 73 0a 2a 2a 20 6d 75 63 68 20 69 6e 66  e as.** much inf
4e80: 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 70  ormation about p
4e90: 72 6f 62 6c 65 6d 73 20 61 73 20 70 72 6f 67 72  roblems as progr
4ea0: 61 6d 6d 65 72 73 20 6d 69 67 68 74 20 6c 69 6b  ammers might lik
4eb0: 65 2e 20 20 49 6e 20 61 6e 20 65 66 66 6f 72 74  e.  In an effort
4ec0: 20 74 6f 0a 2a 2a 20 61 64 64 72 65 73 73 20 74   to.** address t
4ed0: 68 69 73 2c 20 6e 65 77 65 72 20 76 65 72 73 69  his, newer versi
4ee0: 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 28 76  ons of SQLite (v
4ef0: 65 72 73 69 6f 6e 20 33 2e 33 2e 38 20 5b 64 61  ersion 3.3.8 [da
4f00: 74 65 6f 66 3a 33 2e 33 2e 38 5d 0a 2a 2a 20 61  teof:3.3.8].** a
4f10: 6e 64 20 6c 61 74 65 72 29 20 69 6e 63 6c 75 64  nd later) includ
4f20: 65 0a 2a 2a 20 73 75 70 70 6f 72 74 20 66 6f 72  e.** support for
4f30: 20 61 64 64 69 74 69 6f 6e 61 6c 20 72 65 73 75   additional resu
4f40: 6c 74 20 63 6f 64 65 73 20 74 68 61 74 20 70 72  lt codes that pr
4f50: 6f 76 69 64 65 20 6d 6f 72 65 20 64 65 74 61 69  ovide more detai
4f60: 6c 65 64 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a  led information.
4f70: 2a 2a 20 61 62 6f 75 74 20 65 72 72 6f 72 73 2e  ** about errors.
4f80: 20 54 68 65 73 65 20 5b 65 78 74 65 6e 64 65 64   These [extended
4f90: 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 61   result codes] a
4fa0: 72 65 20 65 6e 61 62 6c 65 64 20 6f 72 20 64 69  re enabled or di
4fb0: 73 61 62 6c 65 64 0a 2a 2a 20 6f 6e 20 61 20 70  sabled.** on a p
4fc0: 65 72 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  er database conn
4fd0: 65 63 74 69 6f 6e 20 62 61 73 69 73 20 75 73 69  ection basis usi
4fe0: 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  ng the.** [sqlit
4ff0: 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75  e3_extended_resu
5000: 6c 74 5f 63 6f 64 65 73 28 29 5d 20 41 50 49 2e  lt_codes()] API.
5010: 20 20 4f 72 2c 20 74 68 65 20 65 78 74 65 6e 64    Or, the extend
5020: 65 64 20 63 6f 64 65 20 66 6f 72 0a 2a 2a 20 74  ed code for.** t
5030: 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 65  he most recent e
5040: 72 72 6f 72 20 63 61 6e 20 62 65 20 6f 62 74 61  rror can be obta
5050: 69 6e 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73  ined using.** [s
5060: 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f  qlite3_extended_
5070: 65 72 72 63 6f 64 65 28 29 5d 2e 0a 2a 2f 0a 23  errcode()]..*/.#
5080: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5090: 45 52 52 5f 52 45 41 44 20 20 20 20 20 20 20 20  ERR_READ        
50a0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
50b0: 45 52 52 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64  ERR | (1<<8)).#d
50c0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
50d0: 52 52 5f 53 48 4f 52 54 5f 52 45 41 44 20 20 20  RR_SHORT_READ   
50e0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
50f0: 52 52 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65  RR | (2<<8)).#de
5100: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
5110: 52 5f 57 52 49 54 45 20 20 20 20 20 20 20 20 20  R_WRITE         
5120: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
5130: 52 20 7c 20 28 33 3c 3c 38 29 29 0a 23 64 65 66  R | (3<<8)).#def
5140: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5150: 5f 46 53 59 4e 43 20 20 20 20 20 20 20 20 20 20  _FSYNC          
5160: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5170: 20 7c 20 28 34 3c 3c 38 29 29 0a 23 64 65 66 69   | (4<<8)).#defi
5180: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5190: 44 49 52 5f 46 53 59 4e 43 20 20 20 20 20 20 20  DIR_FSYNC       
51a0: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
51b0: 7c 20 28 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (5<<8)).#defin
51c0: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 54  e SQLITE_IOERR_T
51d0: 52 55 4e 43 41 54 45 20 20 20 20 20 20 20 20 20  RUNCATE         
51e0: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c   (SQLITE_IOERR |
51f0: 20 28 36 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (6<<8)).#define
5200: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 46 53   SQLITE_IOERR_FS
5210: 54 41 54 20 20 20 20 20 20 20 20 20 20 20 20 20  TAT             
5220: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
5230: 28 37 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (7<<8)).#define 
5240: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 55 4e 4c  SQLITE_IOERR_UNL
5250: 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20 20 28  OCK            (
5260: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
5270: 38 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  8<<8)).#define S
5280: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52 44 4c 4f  QLITE_IOERR_RDLO
5290: 43 4b 20 20 20 20 20 20 20 20 20 20 20 20 28 53  CK            (S
52a0: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 39  QLITE_IOERR | (9
52b0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
52c0: 4c 49 54 45 5f 49 4f 45 52 52 5f 44 45 4c 45 54  LITE_IOERR_DELET
52d0: 45 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51  E            (SQ
52e0: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 30  LITE_IOERR | (10
52f0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5300: 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b  LITE_IOERR_BLOCK
5310: 45 44 20 20 20 20 20 20 20 20 20 20 20 28 53 51  ED           (SQ
5320: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 31  LITE_IOERR | (11
5330: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5340: 4c 49 54 45 5f 49 4f 45 52 52 5f 4e 4f 4d 45 4d  LITE_IOERR_NOMEM
5350: 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51               (SQ
5360: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 32  LITE_IOERR | (12
5370: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5380: 4c 49 54 45 5f 49 4f 45 52 52 5f 41 43 43 45 53  LITE_IOERR_ACCES
5390: 53 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51  S            (SQ
53a0: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 33  LITE_IOERR | (13
53b0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
53c0: 4c 49 54 45 5f 49 4f 45 52 52 5f 43 48 45 43 4b  LITE_IOERR_CHECK
53d0: 52 45 53 45 52 56 45 44 4c 4f 43 4b 20 28 53 51  RESERVEDLOCK (SQ
53e0: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 34  LITE_IOERR | (14
53f0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5400: 4c 49 54 45 5f 49 4f 45 52 52 5f 4c 4f 43 4b 20  LITE_IOERR_LOCK 
5410: 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51               (SQ
5420: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 35  LITE_IOERR | (15
5430: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5440: 4c 49 54 45 5f 49 4f 45 52 52 5f 43 4c 4f 53 45  LITE_IOERR_CLOSE
5450: 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51               (SQ
5460: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 36  LITE_IOERR | (16
5470: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5480: 4c 49 54 45 5f 49 4f 45 52 52 5f 44 49 52 5f 43  LITE_IOERR_DIR_C
5490: 4c 4f 53 45 20 20 20 20 20 20 20 20 20 28 53 51  LOSE         (SQ
54a0: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 37  LITE_IOERR | (17
54b0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
54c0: 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4d 4f 50  LITE_IOERR_SHMOP
54d0: 45 4e 20 20 20 20 20 20 20 20 20 20 20 28 53 51  EN           (SQ
54e0: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 38  LITE_IOERR | (18
54f0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5500: 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4d 53 49  LITE_IOERR_SHMSI
5510: 5a 45 20 20 20 20 20 20 20 20 20 20 20 28 53 51  ZE           (SQ
5520: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 39  LITE_IOERR | (19
5530: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5540: 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4d 4c 4f  LITE_IOERR_SHMLO
5550: 43 4b 20 20 20 20 20 20 20 20 20 20 20 28 53 51  CK           (SQ
5560: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 30  LITE_IOERR | (20
5570: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5580: 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4d 4d 41  LITE_IOERR_SHMMA
5590: 50 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51  P            (SQ
55a0: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 31  LITE_IOERR | (21
55b0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
55c0: 4c 49 54 45 5f 49 4f 45 52 52 5f 53 45 45 4b 20  LITE_IOERR_SEEK 
55d0: 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51               (SQ
55e0: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 32  LITE_IOERR | (22
55f0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5600: 4c 49 54 45 5f 49 4f 45 52 52 5f 44 45 4c 45 54  LITE_IOERR_DELET
5610: 45 5f 4e 4f 45 4e 54 20 20 20 20 20 20 28 53 51  E_NOENT      (SQ
5620: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 33  LITE_IOERR | (23
5630: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5640: 4c 49 54 45 5f 49 4f 45 52 52 5f 4d 4d 41 50 20  LITE_IOERR_MMAP 
5650: 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51               (SQ
5660: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 34  LITE_IOERR | (24
5670: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5680: 4c 49 54 45 5f 49 4f 45 52 52 5f 47 45 54 54 45  LITE_IOERR_GETTE
5690: 4d 50 50 41 54 48 20 20 20 20 20 20 20 28 53 51  MPPATH       (SQ
56a0: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 35  LITE_IOERR | (25
56b0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
56c0: 4c 49 54 45 5f 49 4f 45 52 52 5f 43 4f 4e 56 50  LITE_IOERR_CONVP
56d0: 41 54 48 20 20 20 20 20 20 20 20 20 20 28 53 51  ATH          (SQ
56e0: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 36  LITE_IOERR | (26
56f0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5700: 4c 49 54 45 5f 49 4f 45 52 52 5f 56 4e 4f 44 45  LITE_IOERR_VNODE
5710: 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51               (SQ
5720: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 37  LITE_IOERR | (27
5730: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5740: 4c 49 54 45 5f 49 4f 45 52 52 5f 41 55 54 48 20  LITE_IOERR_AUTH 
5750: 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51               (SQ
5760: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 38  LITE_IOERR | (28
5770: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5780: 4c 49 54 45 5f 4c 4f 43 4b 45 44 5f 53 48 41 52  LITE_LOCKED_SHAR
5790: 45 44 43 41 43 48 45 20 20 20 20 20 20 28 53 51  EDCACHE      (SQ
57a0: 4c 49 54 45 5f 4c 4f 43 4b 45 44 20 7c 20 20 28  LITE_LOCKED |  (
57b0: 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  1<<8)).#define S
57c0: 51 4c 49 54 45 5f 42 55 53 59 5f 52 45 43 4f 56  QLITE_BUSY_RECOV
57d0: 45 52 59 20 20 20 20 20 20 20 20 20 20 20 28 53  ERY           (S
57e0: 51 4c 49 54 45 5f 42 55 53 59 20 20 20 7c 20 20  QLITE_BUSY   |  
57f0: 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (1<<8)).#define 
5800: 53 51 4c 49 54 45 5f 42 55 53 59 5f 53 4e 41 50  SQLITE_BUSY_SNAP
5810: 53 48 4f 54 20 20 20 20 20 20 20 20 20 20 20 28  SHOT           (
5820: 53 51 4c 49 54 45 5f 42 55 53 59 20 20 20 7c 20  SQLITE_BUSY   | 
5830: 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (2<<8)).#define
5840: 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e   SQLITE_CANTOPEN
5850: 5f 4e 4f 54 45 4d 50 44 49 52 20 20 20 20 20 20  _NOTEMPDIR      
5860: 28 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e  (SQLITE_CANTOPEN
5870: 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69   | (1<<8)).#defi
5880: 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50  ne SQLITE_CANTOP
5890: 45 4e 5f 49 53 44 49 52 20 20 20 20 20 20 20 20  EN_ISDIR        
58a0: 20 20 28 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50    (SQLITE_CANTOP
58b0: 45 4e 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65  EN | (2<<8)).#de
58c0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e 54  fine SQLITE_CANT
58d0: 4f 50 45 4e 5f 46 55 4c 4c 50 41 54 48 20 20 20  OPEN_FULLPATH   
58e0: 20 20 20 20 28 53 51 4c 49 54 45 5f 43 41 4e 54      (SQLITE_CANT
58f0: 4f 50 45 4e 20 7c 20 28 33 3c 3c 38 29 29 0a 23  OPEN | (3<<8)).#
5900: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41  define SQLITE_CA
5910: 4e 54 4f 50 45 4e 5f 43 4f 4e 56 50 41 54 48 20  NTOPEN_CONVPATH 
5920: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 41        (SQLITE_CA
5930: 4e 54 4f 50 45 4e 20 7c 20 28 34 3c 3c 38 29 29  NTOPEN | (4<<8))
5940: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5950: 43 4f 52 52 55 50 54 5f 56 54 41 42 20 20 20 20  CORRUPT_VTAB    
5960: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
5970: 43 4f 52 52 55 50 54 20 7c 20 28 31 3c 3c 38 29  CORRUPT | (1<<8)
5980: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5990: 5f 52 45 41 44 4f 4e 4c 59 5f 52 45 43 4f 56 45  _READONLY_RECOVE
59a0: 52 59 20 20 20 20 20 20 20 28 53 51 4c 49 54 45  RY       (SQLITE
59b0: 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28 31 3c 3c  _READONLY | (1<<
59c0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
59d0: 54 45 5f 52 45 41 44 4f 4e 4c 59 5f 43 41 4e 54  TE_READONLY_CANT
59e0: 4c 4f 43 4b 20 20 20 20 20 20 20 28 53 51 4c 49  LOCK       (SQLI
59f0: 54 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28 32  TE_READONLY | (2
5a00: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5a10: 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5f 52 4f  LITE_READONLY_RO
5a20: 4c 4c 42 41 43 4b 20 20 20 20 20 20 20 28 53 51  LLBACK       (SQ
5a30: 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20  LITE_READONLY | 
5a40: 28 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (3<<8)).#define 
5a50: 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5f  SQLITE_READONLY_
5a60: 44 42 4d 4f 56 45 44 20 20 20 20 20 20 20 20 28  DBMOVED        (
5a70: 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20  SQLITE_READONLY 
5a80: 7c 20 28 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (4<<8)).#defin
5a90: 65 20 53 51 4c 49 54 45 5f 41 42 4f 52 54 5f 52  e SQLITE_ABORT_R
5aa0: 4f 4c 4c 42 41 43 4b 20 20 20 20 20 20 20 20 20  OLLBACK         
5ab0: 20 28 53 51 4c 49 54 45 5f 41 42 4f 52 54 20 7c   (SQLITE_ABORT |
5ac0: 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (2<<8)).#define
5ad0: 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49   SQLITE_CONSTRAI
5ae0: 4e 54 5f 43 48 45 43 4b 20 20 20 20 20 20 20 20  NT_CHECK        
5af0: 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49  (SQLITE_CONSTRAI
5b00: 4e 54 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65  NT | (1<<8)).#de
5b10: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53  fine SQLITE_CONS
5b20: 54 52 41 49 4e 54 5f 43 4f 4d 4d 49 54 48 4f 4f  TRAINT_COMMITHOO
5b30: 4b 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53  K   (SQLITE_CONS
5b40: 54 52 41 49 4e 54 20 7c 20 28 32 3c 3c 38 29 29  TRAINT | (2<<8))
5b50: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5b60: 43 4f 4e 53 54 52 41 49 4e 54 5f 46 4f 52 45 49  CONSTRAINT_FOREI
5b70: 47 4e 4b 45 59 20 20 20 28 53 51 4c 49 54 45 5f  GNKEY   (SQLITE_
5b80: 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 33 3c  CONSTRAINT | (3<
5b90: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5ba0: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 46  ITE_CONSTRAINT_F
5bb0: 55 4e 43 54 49 4f 4e 20 20 20 20 20 28 53 51 4c  UNCTION     (SQL
5bc0: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c  ITE_CONSTRAINT |
5bd0: 20 28 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (4<<8)).#define
5be0: 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49   SQLITE_CONSTRAI
5bf0: 4e 54 5f 4e 4f 54 4e 55 4c 4c 20 20 20 20 20 20  NT_NOTNULL      
5c00: 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49  (SQLITE_CONSTRAI
5c10: 4e 54 20 7c 20 28 35 3c 3c 38 29 29 0a 23 64 65  NT | (5<<8)).#de
5c20: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53  fine SQLITE_CONS
5c30: 54 52 41 49 4e 54 5f 50 52 49 4d 41 52 59 4b 45  TRAINT_PRIMARYKE
5c40: 59 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53  Y   (SQLITE_CONS
5c50: 54 52 41 49 4e 54 20 7c 20 28 36 3c 3c 38 29 29  TRAINT | (6<<8))
5c60: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5c70: 43 4f 4e 53 54 52 41 49 4e 54 5f 54 52 49 47 47  CONSTRAINT_TRIGG
5c80: 45 52 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f  ER      (SQLITE_
5c90: 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 37 3c  CONSTRAINT | (7<
5ca0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5cb0: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 55  ITE_CONSTRAINT_U
5cc0: 4e 49 51 55 45 20 20 20 20 20 20 20 28 53 51 4c  NIQUE       (SQL
5cd0: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c  ITE_CONSTRAINT |
5ce0: 20 28 38 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (8<<8)).#define
5cf0: 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49   SQLITE_CONSTRAI
5d00: 4e 54 5f 56 54 41 42 20 20 20 20 20 20 20 20 20  NT_VTAB         
5d10: 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49  (SQLITE_CONSTRAI
5d20: 4e 54 20 7c 20 28 39 3c 3c 38 29 29 0a 23 64 65  NT | (9<<8)).#de
5d30: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53  fine SQLITE_CONS
5d40: 54 52 41 49 4e 54 5f 52 4f 57 49 44 20 20 20 20  TRAINT_ROWID    
5d50: 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53      (SQLITE_CONS
5d60: 54 52 41 49 4e 54 20 7c 28 31 30 3c 3c 38 29 29  TRAINT |(10<<8))
5d70: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5d80: 4e 4f 54 49 43 45 5f 52 45 43 4f 56 45 52 5f 57  NOTICE_RECOVER_W
5d90: 41 4c 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f  AL      (SQLITE_
5da0: 4e 4f 54 49 43 45 20 7c 20 28 31 3c 3c 38 29 29  NOTICE | (1<<8))
5db0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5dc0: 4e 4f 54 49 43 45 5f 52 45 43 4f 56 45 52 5f 52  NOTICE_RECOVER_R
5dd0: 4f 4c 4c 42 41 43 4b 20 28 53 51 4c 49 54 45 5f  OLLBACK (SQLITE_
5de0: 4e 4f 54 49 43 45 20 7c 20 28 32 3c 3c 38 29 29  NOTICE | (2<<8))
5df0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5e00: 57 41 52 4e 49 4e 47 5f 41 55 54 4f 49 4e 44 45  WARNING_AUTOINDE
5e10: 58 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f  X       (SQLITE_
5e20: 57 41 52 4e 49 4e 47 20 7c 20 28 31 3c 3c 38 29  WARNING | (1<<8)
5e30: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5e40: 5f 41 55 54 48 5f 55 53 45 52 20 20 20 20 20 20  _AUTH_USER      
5e50: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
5e60: 5f 41 55 54 48 20 7c 20 28 31 3c 3c 38 29 29 0a  _AUTH | (1<<8)).
5e70: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
5e80: 4b 5f 4c 4f 41 44 5f 50 45 52 4d 41 4e 45 4e 54  K_LOAD_PERMANENT
5e90: 4c 59 20 20 20 20 20 28 53 51 4c 49 54 45 5f 4f  LY     (SQLITE_O
5ea0: 4b 20 7c 20 28 31 3c 3c 38 29 29 0a 0a 2f 2a 0a  K | (1<<8))../*.
5eb0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6c 61  ** CAPI3REF: Fla
5ec0: 67 73 20 46 6f 72 20 46 69 6c 65 20 4f 70 65 6e  gs For File Open
5ed0: 20 4f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 0a 2a   Operations.**.*
5ee0: 2a 20 54 68 65 73 65 20 62 69 74 20 76 61 6c 75  * These bit valu
5ef0: 65 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20  es are intended 
5f00: 66 6f 72 20 75 73 65 20 69 6e 20 74 68 65 0a 2a  for use in the.*
5f10: 2a 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20  * 3rd parameter 
5f20: 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
5f30: 6f 70 65 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72  open_v2()] inter
5f40: 66 61 63 65 20 61 6e 64 0a 2a 2a 20 69 6e 20 74  face and.** in t
5f50: 68 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 72  he 4th parameter
5f60: 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
5f70: 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 6d 65 74 68  _vfs.xOpen] meth
5f80: 6f 64 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  od..*/.#define S
5f90: 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f  QLITE_OPEN_READO
5fa0: 4e 4c 59 20 20 20 20 20 20 20 20 20 30 78 30 30  NLY         0x00
5fb0: 30 30 30 30 30 31 20 20 2f 2a 20 4f 6b 20 66 6f  000001  /* Ok fo
5fc0: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
5fd0: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  2() */.#define S
5fe0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57  QLITE_OPEN_READW
5ff0: 52 49 54 45 20 20 20 20 20 20 20 20 30 78 30 30  RITE        0x00
6000: 30 30 30 30 30 32 20 20 2f 2a 20 4f 6b 20 66 6f  000002  /* Ok fo
6010: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
6020: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  2() */.#define S
6030: 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54  QLITE_OPEN_CREAT
6040: 45 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30  E           0x00
6050: 30 30 30 30 30 34 20 20 2f 2a 20 4f 6b 20 66 6f  000004  /* Ok fo
6060: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
6070: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  2() */.#define S
6080: 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54  QLITE_OPEN_DELET
6090: 45 4f 4e 43 4c 4f 53 45 20 20 20 20 30 78 30 30  EONCLOSE    0x00
60a0: 30 30 30 30 30 38 20 20 2f 2a 20 56 46 53 20 6f  000008  /* VFS o
60b0: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
60c0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55  QLITE_OPEN_EXCLU
60d0: 53 49 56 45 20 20 20 20 20 20 20 20 30 78 30 30  SIVE        0x00
60e0: 30 30 30 30 31 30 20 20 2f 2a 20 56 46 53 20 6f  000010  /* VFS o
60f0: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
6100: 51 4c 49 54 45 5f 4f 50 45 4e 5f 41 55 54 4f 50  QLITE_OPEN_AUTOP
6110: 52 4f 58 59 20 20 20 20 20 20 20 20 30 78 30 30  ROXY        0x00
6120: 30 30 30 30 32 30 20 20 2f 2a 20 56 46 53 20 6f  000020  /* VFS o
6130: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
6140: 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 20 20  QLITE_OPEN_URI  
6150: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30              0x00
6160: 30 30 30 30 34 30 20 20 2f 2a 20 4f 6b 20 66 6f  000040  /* Ok fo
6170: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
6180: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  2() */.#define S
6190: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 45 4d 4f 52  QLITE_OPEN_MEMOR
61a0: 59 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30  Y           0x00
61b0: 30 30 30 30 38 30 20 20 2f 2a 20 4f 6b 20 66 6f  000080  /* Ok fo
61c0: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
61d0: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  2() */.#define S
61e0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f  QLITE_OPEN_MAIN_
61f0: 44 42 20 20 20 20 20 20 20 20 20 20 30 78 30 30  DB          0x00
6200: 30 30 30 31 30 30 20 20 2f 2a 20 56 46 53 20 6f  000100  /* VFS o
6210: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
6220: 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f  QLITE_OPEN_TEMP_
6230: 44 42 20 20 20 20 20 20 20 20 20 20 30 78 30 30  DB          0x00
6240: 30 30 30 32 30 30 20 20 2f 2a 20 56 46 53 20 6f  000200  /* VFS o
6250: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
6260: 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 52 41 4e 53  QLITE_OPEN_TRANS
6270: 49 45 4e 54 5f 44 42 20 20 20 20 20 30 78 30 30  IENT_DB     0x00
6280: 30 30 30 34 30 30 20 20 2f 2a 20 56 46 53 20 6f  000400  /* VFS o
6290: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
62a0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f  QLITE_OPEN_MAIN_
62b0: 4a 4f 55 52 4e 41 4c 20 20 20 20 20 30 78 30 30  JOURNAL     0x00
62c0: 30 30 30 38 30 30 20 20 2f 2a 20 56 46 53 20 6f  000800  /* VFS o
62d0: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
62e0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f  QLITE_OPEN_TEMP_
62f0: 4a 4f 55 52 4e 41 4c 20 20 20 20 20 30 78 30 30  JOURNAL     0x00
6300: 30 30 31 30 30 30 20 20 2f 2a 20 56 46 53 20 6f  001000  /* VFS o
6310: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
6320: 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f  QLITE_OPEN_SUBJO
6330: 55 52 4e 41 4c 20 20 20 20 20 20 20 30 78 30 30  URNAL       0x00
6340: 30 30 32 30 30 30 20 20 2f 2a 20 56 46 53 20 6f  002000  /* VFS o
6350: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
6360: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 53 54 45  QLITE_OPEN_MASTE
6370: 52 5f 4a 4f 55 52 4e 41 4c 20 20 20 30 78 30 30  R_JOURNAL   0x00
6380: 30 30 34 30 30 30 20 20 2f 2a 20 56 46 53 20 6f  004000  /* VFS o
6390: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
63a0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54  QLITE_OPEN_NOMUT
63b0: 45 58 20 20 20 20 20 20 20 20 20 20 30 78 30 30  EX          0x00
63c0: 30 30 38 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f  008000  /* Ok fo
63d0: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
63e0: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  2() */.#define S
63f0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d  QLITE_OPEN_FULLM
6400: 55 54 45 58 20 20 20 20 20 20 20 20 30 78 30 30  UTEX        0x00
6410: 30 31 30 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f  010000  /* Ok fo
6420: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
6430: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  2() */.#define S
6440: 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45  QLITE_OPEN_SHARE
6450: 44 43 41 43 48 45 20 20 20 20 20 20 30 78 30 30  DCACHE      0x00
6460: 30 32 30 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f  020000  /* Ok fo
6470: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
6480: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  2() */.#define S
6490: 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41  QLITE_OPEN_PRIVA
64a0: 54 45 43 41 43 48 45 20 20 20 20 20 30 78 30 30  TECACHE     0x00
64b0: 30 34 30 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f  040000  /* Ok fo
64c0: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
64d0: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  2() */.#define S
64e0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 57 41 4c 20 20  QLITE_OPEN_WAL  
64f0: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30              0x00
6500: 30 38 30 30 30 30 20 20 2f 2a 20 56 46 53 20 6f  080000  /* VFS o
6510: 6e 6c 79 20 2a 2f 0a 0a 2f 2a 20 52 65 73 65 72  nly */../* Reser
6520: 76 65 64 3a 20 20 20 20 20 20 20 20 20 20 20 20  ved:            
6530: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30               0x0
6540: 30 46 30 30 30 30 30 20 2a 2f 0a 0a 2f 2a 0a 2a  0F00000 */../*.*
6550: 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 76 69  * CAPI3REF: Devi
6560: 63 65 20 43 68 61 72 61 63 74 65 72 69 73 74 69  ce Characteristi
6570: 63 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 44 65  cs.**.** The xDe
6580: 76 69 63 65 43 68 61 72 61 63 74 65 72 69 73 74  viceCharacterist
6590: 69 63 73 20 6d 65 74 68 6f 64 20 6f 66 20 74 68  ics method of th
65a0: 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  e [sqlite3_io_me
65b0: 74 68 6f 64 73 5d 0a 2a 2a 20 6f 62 6a 65 63 74  thods].** object
65c0: 20 72 65 74 75 72 6e 73 20 61 6e 20 69 6e 74 65   returns an inte
65d0: 67 65 72 20 77 68 69 63 68 20 69 73 20 61 20 76  ger which is a v
65e0: 65 63 74 6f 72 20 6f 66 20 74 68 65 73 65 0a 2a  ector of these.*
65f0: 2a 20 62 69 74 20 76 61 6c 75 65 73 20 65 78 70  * bit values exp
6600: 72 65 73 73 69 6e 67 20 49 2f 4f 20 63 68 61 72  ressing I/O char
6610: 61 63 74 65 72 69 73 74 69 63 73 20 6f 66 20 74  acteristics of t
6620: 68 65 20 6d 61 73 73 20 73 74 6f 72 61 67 65 0a  he mass storage.
6630: 2a 2a 20 64 65 76 69 63 65 20 74 68 61 74 20 68  ** device that h
6640: 6f 6c 64 73 20 74 68 65 20 66 69 6c 65 20 74 68  olds the file th
6650: 61 74 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  at the [sqlite3_
6660: 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 72  io_methods].** r
6670: 65 66 65 72 73 20 74 6f 2e 0a 2a 2a 0a 2a 2a 20  efers to..**.** 
6680: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
6690: 5f 41 54 4f 4d 49 43 20 70 72 6f 70 65 72 74 79  _ATOMIC property
66a0: 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6c 6c 20   means that all 
66b0: 77 72 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79  writes of.** any
66c0: 20 73 69 7a 65 20 61 72 65 20 61 74 6f 6d 69 63   size are atomic
66d0: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f  .  The SQLITE_IO
66e0: 43 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61  CAP_ATOMICnnn va
66f0: 6c 75 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61  lues.** mean tha
6700: 74 20 77 72 69 74 65 73 20 6f 66 20 62 6c 6f 63  t writes of bloc
6710: 6b 73 20 74 68 61 74 20 61 72 65 20 6e 6e 6e 20  ks that are nnn 
6720: 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20 61 6e  bytes in size an
6730: 64 0a 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65 64  d.** are aligned
6740: 20 74 6f 20 61 6e 20 61 64 64 72 65 73 73 20 77   to an address w
6750: 68 69 63 68 20 69 73 20 61 6e 20 69 6e 74 65 67  hich is an integ
6760: 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a  er multiple of.*
6770: 2a 20 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63  * nnn are atomic
6780: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f  .  The SQLITE_IO
6790: 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20  CAP_SAFE_APPEND 
67a0: 76 61 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74  value means.** t
67b0: 68 61 74 20 77 68 65 6e 20 64 61 74 61 20 69 73  hat when data is
67c0: 20 61 70 70 65 6e 64 65 64 20 74 6f 20 61 20 66   appended to a f
67d0: 69 6c 65 2c 20 74 68 65 20 64 61 74 61 20 69 73  ile, the data is
67e0: 20 61 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72   appended.** fir
67f0: 73 74 20 74 68 65 6e 20 74 68 65 20 73 69 7a 65  st then the size
6800: 20 6f 66 20 74 68 65 20 66 69 6c 65 20 69 73 20   of the file is 
6810: 65 78 74 65 6e 64 65 64 2c 20 6e 65 76 65 72 20  extended, never 
6820: 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79  the other.** way
6830: 20 61 72 6f 75 6e 64 2e 20 20 54 68 65 20 53 51   around.  The SQ
6840: 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45  LITE_IOCAP_SEQUE
6850: 4e 54 49 41 4c 20 70 72 6f 70 65 72 74 79 20 6d  NTIAL property m
6860: 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66  eans that.** inf
6870: 6f 72 6d 61 74 69 6f 6e 20 69 73 20 77 72 69 74  ormation is writ
6880: 74 65 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20 74  ten to disk in t
6890: 68 65 20 73 61 6d 65 20 6f 72 64 65 72 20 61 73  he same order as
68a0: 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72   calls.** to xWr
68b0: 69 74 65 28 29 2e 20 20 54 68 65 20 53 51 4c 49  ite().  The SQLI
68c0: 54 45 5f 49 4f 43 41 50 5f 50 4f 57 45 52 53 41  TE_IOCAP_POWERSA
68d0: 46 45 5f 4f 56 45 52 57 52 49 54 45 20 70 72 6f  FE_OVERWRITE pro
68e0: 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74  perty means that
68f0: 0a 2a 2a 20 61 66 74 65 72 20 72 65 62 6f 6f 74  .** after reboot
6900: 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 63 72 61   following a cra
6910: 73 68 20 6f 72 20 70 6f 77 65 72 20 6c 6f 73 73  sh or power loss
6920: 2c 20 74 68 65 20 6f 6e 6c 79 20 62 79 74 65 73  , the only bytes
6930: 20 69 6e 20 61 0a 2a 2a 20 66 69 6c 65 20 74 68   in a.** file th
6940: 61 74 20 77 65 72 65 20 77 72 69 74 74 65 6e 20  at were written 
6950: 61 74 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  at the applicati
6960: 6f 6e 20 6c 65 76 65 6c 20 6d 69 67 68 74 20 68  on level might h
6970: 61 76 65 20 63 68 61 6e 67 65 64 0a 2a 2a 20 61  ave changed.** a
6980: 6e 64 20 74 68 61 74 20 61 64 6a 61 63 65 6e 74  nd that adjacent
6990: 20 62 79 74 65 73 2c 20 65 76 65 6e 20 62 79 74   bytes, even byt
69a0: 65 73 20 77 69 74 68 69 6e 20 74 68 65 20 73 61  es within the sa
69b0: 6d 65 20 73 65 63 74 6f 72 20 61 72 65 0a 2a 2a  me sector are.**
69c0: 20 67 75 61 72 61 6e 74 65 65 64 20 74 6f 20 62   guaranteed to b
69d0: 65 20 75 6e 63 68 61 6e 67 65 64 2e 20 20 54 68  e unchanged.  Th
69e0: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 55  e SQLITE_IOCAP_U
69f0: 4e 44 45 4c 45 54 41 42 4c 45 5f 57 48 45 4e 5f  NDELETABLE_WHEN_
6a00: 4f 50 45 4e 0a 2a 2a 20 66 6c 61 67 20 69 6e 64  OPEN.** flag ind
6a10: 69 63 61 74 65 20 74 68 61 74 20 61 20 66 69 6c  icate that a fil
6a20: 65 20 63 61 6e 6e 6f 74 20 62 65 20 64 65 6c 65  e cannot be dele
6a30: 74 65 64 20 77 68 65 6e 20 6f 70 65 6e 2e 20 20  ted when open.  
6a40: 54 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 49 4f  The.** SQLITE_IO
6a50: 43 41 50 5f 49 4d 4d 55 54 41 42 4c 45 20 66 6c  CAP_IMMUTABLE fl
6a60: 61 67 20 69 6e 64 69 63 61 74 65 73 20 74 68 61  ag indicates tha
6a70: 74 20 74 68 65 20 66 69 6c 65 20 69 73 20 6f 6e  t the file is on
6a80: 0a 2a 2a 20 72 65 61 64 2d 6f 6e 6c 79 20 6d 65  .** read-only me
6a90: 64 69 61 20 61 6e 64 20 63 61 6e 6e 6f 74 20 62  dia and cannot b
6aa0: 65 20 63 68 61 6e 67 65 64 20 65 76 65 6e 20 62  e changed even b
6ab0: 79 20 70 72 6f 63 65 73 73 65 73 20 77 69 74 68  y processes with
6ac0: 0a 2a 2a 20 65 6c 65 76 61 74 65 64 20 70 72 69  .** elevated pri
6ad0: 76 69 6c 65 67 65 73 2e 0a 2a 2f 0a 23 64 65 66  vileges..*/.#def
6ae0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
6af0: 5f 41 54 4f 4d 49 43 20 20 20 20 20 20 20 20 20  _ATOMIC         
6b00: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
6b10: 30 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  01.#define SQLIT
6b20: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 35 31  E_IOCAP_ATOMIC51
6b30: 32 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30  2              0
6b40: 78 30 30 30 30 30 30 30 32 0a 23 64 65 66 69 6e  x00000002.#defin
6b50: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
6b60: 54 4f 4d 49 43 31 4b 20 20 20 20 20 20 20 20 20  TOMIC1K         
6b70: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 34        0x00000004
6b80: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6b90: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 32 4b 20 20  IOCAP_ATOMIC2K  
6ba0: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30               0x0
6bb0: 30 30 30 30 30 30 38 0a 23 64 65 66 69 6e 65 20  0000008.#define 
6bc0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
6bd0: 4d 49 43 34 4b 20 20 20 20 20 20 20 20 20 20 20  MIC4K           
6be0: 20 20 20 20 30 78 30 30 30 30 30 30 31 30 0a 23      0x00000010.#
6bf0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
6c00: 43 41 50 5f 41 54 4f 4d 49 43 38 4b 20 20 20 20  CAP_ATOMIC8K    
6c10: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
6c20: 30 30 30 32 30 0a 23 64 65 66 69 6e 65 20 53 51  00020.#define SQ
6c30: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
6c40: 43 31 36 4b 20 20 20 20 20 20 20 20 20 20 20 20  C16K            
6c50: 20 20 30 78 30 30 30 30 30 30 34 30 0a 23 64 65    0x00000040.#de
6c60: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
6c70: 50 5f 41 54 4f 4d 49 43 33 32 4b 20 20 20 20 20  P_ATOMIC32K     
6c80: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
6c90: 30 38 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  080.#define SQLI
6ca0: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 36  TE_IOCAP_ATOMIC6
6cb0: 34 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20  4K              
6cc0: 30 78 30 30 30 30 30 31 30 30 0a 23 64 65 66 69  0x00000100.#defi
6cd0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
6ce0: 53 41 46 45 5f 41 50 50 45 4e 44 20 20 20 20 20  SAFE_APPEND     
6cf0: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 32 30         0x0000020
6d00: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
6d10: 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41  _IOCAP_SEQUENTIA
6d20: 4c 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78  L             0x
6d30: 30 30 30 30 30 34 30 30 0a 23 64 65 66 69 6e 65  00000400.#define
6d40: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 55 4e   SQLITE_IOCAP_UN
6d50: 44 45 4c 45 54 41 42 4c 45 5f 57 48 45 4e 5f 4f  DELETABLE_WHEN_O
6d60: 50 45 4e 20 20 30 78 30 30 30 30 30 38 30 30 0a  PEN  0x00000800.
6d70: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
6d80: 4f 43 41 50 5f 50 4f 57 45 52 53 41 46 45 5f 4f  OCAP_POWERSAFE_O
6d90: 56 45 52 57 52 49 54 45 20 20 20 20 30 78 30 30  VERWRITE    0x00
6da0: 30 30 31 30 30 30 0a 23 64 65 66 69 6e 65 20 53  001000.#define S
6db0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 49 4d 4d 55  QLITE_IOCAP_IMMU
6dc0: 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 20  TABLE           
6dd0: 20 20 20 30 78 30 30 30 30 32 30 30 30 0a 0a 2f     0x00002000../
6de0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46  *.** CAPI3REF: F
6df0: 69 6c 65 20 4c 6f 63 6b 69 6e 67 20 4c 65 76 65  ile Locking Leve
6e00: 6c 73 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20  ls.**.** SQLite 
6e10: 75 73 65 73 20 6f 6e 65 20 6f 66 20 74 68 65 73  uses one of thes
6e20: 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73  e integer values
6e30: 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a   as the second.*
6e40: 2a 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 63 61  * argument to ca
6e50: 6c 6c 73 20 69 74 20 6d 61 6b 65 73 20 74 6f 20  lls it makes to 
6e60: 74 68 65 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20  the xLock() and 
6e70: 78 55 6e 6c 6f 63 6b 28 29 20 6d 65 74 68 6f 64  xUnlock() method
6e80: 73 0a 2a 2a 20 6f 66 20 61 6e 20 5b 73 71 6c 69  s.** of an [sqli
6e90: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20  te3_io_methods] 
6ea0: 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 23 64 65 66 69  object..*/.#defi
6eb0: 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e  ne SQLITE_LOCK_N
6ec0: 4f 4e 45 20 20 20 20 20 20 20 20 20 20 30 0a 23  ONE          0.#
6ed0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f  define SQLITE_LO
6ee0: 43 4b 5f 53 48 41 52 45 44 20 20 20 20 20 20 20  CK_SHARED       
6ef0: 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   1.#define SQLIT
6f00: 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44 20  E_LOCK_RESERVED 
6f10: 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53       2.#define S
6f20: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49  QLITE_LOCK_PENDI
6f30: 4e 47 20 20 20 20 20 20 20 33 0a 23 64 65 66 69  NG       3.#defi
6f40: 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45  ne SQLITE_LOCK_E
6f50: 58 43 4c 55 53 49 56 45 20 20 20 20 20 34 0a 0a  XCLUSIVE     4..
6f60: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
6f70: 53 79 6e 63 68 72 6f 6e 69 7a 61 74 69 6f 6e 20  Synchronization 
6f80: 54 79 70 65 20 46 6c 61 67 73 0a 2a 2a 0a 2a 2a  Type Flags.**.**
6f90: 20 57 68 65 6e 20 53 51 4c 69 74 65 20 69 6e 76   When SQLite inv
6fa0: 6f 6b 65 73 20 74 68 65 20 78 53 79 6e 63 28 29  okes the xSync()
6fb0: 20 6d 65 74 68 6f 64 20 6f 66 20 61 6e 0a 2a 2a   method of an.**
6fc0: 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74   [sqlite3_io_met
6fd0: 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 69 74 20  hods] object it 
6fe0: 75 73 65 73 20 61 20 63 6f 6d 62 69 6e 61 74 69  uses a combinati
6ff0: 6f 6e 20 6f 66 0a 2a 2a 20 74 68 65 73 65 20 69  on of.** these i
7000: 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20 61 73  nteger values as
7010: 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   the second argu
7020: 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e  ment..**.** When
7030: 20 74 68 65 20 53 51 4c 49 54 45 5f 53 59 4e 43   the SQLITE_SYNC
7040: 5f 44 41 54 41 4f 4e 4c 59 20 66 6c 61 67 20 69  _DATAONLY flag i
7050: 73 20 75 73 65 64 2c 20 69 74 20 6d 65 61 6e 73  s used, it means
7060: 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 73 79 6e   that the.** syn
7070: 63 20 6f 70 65 72 61 74 69 6f 6e 20 6f 6e 6c 79  c operation only
7080: 20 6e 65 65 64 73 20 74 6f 20 66 6c 75 73 68 20   needs to flush 
7090: 64 61 74 61 20 74 6f 20 6d 61 73 73 20 73 74 6f  data to mass sto
70a0: 72 61 67 65 2e 20 20 49 6e 6f 64 65 0a 2a 2a 20  rage.  Inode.** 
70b0: 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 6e 65 65 64  information need
70c0: 20 6e 6f 74 20 62 65 20 66 6c 75 73 68 65 64 2e   not be flushed.
70d0: 20 49 66 20 74 68 65 20 6c 6f 77 65 72 20 66 6f   If the lower fo
70e0: 75 72 20 62 69 74 73 20 6f 66 20 74 68 65 20 66  ur bits of the f
70f0: 6c 61 67 0a 2a 2a 20 65 71 75 61 6c 20 53 51 4c  lag.** equal SQL
7100: 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 2c  ITE_SYNC_NORMAL,
7110: 20 74 68 61 74 20 6d 65 61 6e 73 20 74 6f 20 75   that means to u
7120: 73 65 20 6e 6f 72 6d 61 6c 20 66 73 79 6e 63 28  se normal fsync(
7130: 29 20 73 65 6d 61 6e 74 69 63 73 2e 0a 2a 2a 20  ) semantics..** 
7140: 49 66 20 74 68 65 20 6c 6f 77 65 72 20 66 6f 75  If the lower fou
7150: 72 20 62 69 74 73 20 65 71 75 61 6c 20 53 51 4c  r bits equal SQL
7160: 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 2c 20 74  ITE_SYNC_FULL, t
7170: 68 61 74 20 6d 65 61 6e 73 0a 2a 2a 20 74 6f 20  hat means.** to 
7180: 75 73 65 20 4d 61 63 20 4f 53 20 58 20 73 74 79  use Mac OS X sty
7190: 6c 65 20 66 75 6c 6c 73 79 6e 63 20 69 6e 73 74  le fullsync inst
71a0: 65 61 64 20 6f 66 20 66 73 79 6e 63 28 29 2e 0a  ead of fsync()..
71b0: 2a 2a 0a 2a 2a 20 44 6f 20 6e 6f 74 20 63 6f 6e  **.** Do not con
71c0: 66 75 73 65 20 74 68 65 20 53 51 4c 49 54 45 5f  fuse the SQLITE_
71d0: 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20  SYNC_NORMAL and 
71e0: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c  SQLITE_SYNC_FULL
71f0: 20 66 6c 61 67 73 0a 2a 2a 20 77 69 74 68 20 74   flags.** with t
7200: 68 65 20 5b 50 52 41 47 4d 41 20 73 79 6e 63 68  he [PRAGMA synch
7210: 72 6f 6e 6f 75 73 5d 3d 4e 4f 52 4d 41 4c 20 61  ronous]=NORMAL a
7220: 6e 64 20 5b 50 52 41 47 4d 41 20 73 79 6e 63 68  nd [PRAGMA synch
7230: 72 6f 6e 6f 75 73 5d 3d 46 55 4c 4c 0a 2a 2a 20  ronous]=FULL.** 
7240: 73 65 74 74 69 6e 67 73 2e 20 20 54 68 65 20 5b  settings.  The [
7250: 73 79 6e 63 68 72 6f 6e 6f 75 73 20 70 72 61 67  synchronous prag
7260: 6d 61 5d 20 64 65 74 65 72 6d 69 6e 65 73 20 77  ma] determines w
7270: 68 65 6e 20 63 61 6c 6c 73 20 74 6f 20 74 68 65  hen calls to the
7280: 0a 2a 2a 20 78 53 79 6e 63 20 56 46 53 20 6d 65  .** xSync VFS me
7290: 74 68 6f 64 20 6f 63 63 75 72 20 61 6e 64 20 61  thod occur and a
72a0: 70 70 6c 69 65 73 20 75 6e 69 66 6f 72 6d 6c 79  pplies uniformly
72b0: 20 61 63 72 6f 73 73 20 61 6c 6c 20 70 6c 61 74   across all plat
72c0: 66 6f 72 6d 73 2e 0a 2a 2a 20 54 68 65 20 53 51  forms..** The SQ
72d0: 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c  LITE_SYNC_NORMAL
72e0: 20 61 6e 64 20 53 51 4c 49 54 45 5f 53 59 4e 43   and SQLITE_SYNC
72f0: 5f 46 55 4c 4c 20 66 6c 61 67 73 20 64 65 74 65  _FULL flags dete
7300: 72 6d 69 6e 65 20 68 6f 77 0a 2a 2a 20 65 6e 65  rmine how.** ene
7310: 72 67 65 74 69 63 20 6f 72 20 72 69 67 6f 72 6f  rgetic or rigoro
7320: 75 73 20 6f 72 20 66 6f 72 63 65 66 75 6c 20 74  us or forceful t
7330: 68 65 20 73 79 6e 63 20 6f 70 65 72 61 74 69 6f  he sync operatio
7340: 6e 73 20 61 72 65 20 61 6e 64 0a 2a 2a 20 6f 6e  ns are and.** on
7350: 6c 79 20 6d 61 6b 65 20 61 20 64 69 66 66 65 72  ly make a differ
7360: 65 6e 63 65 20 6f 6e 20 4d 61 63 20 4f 53 58 20  ence on Mac OSX 
7370: 66 6f 72 20 74 68 65 20 64 65 66 61 75 6c 74 20  for the default 
7380: 53 51 4c 69 74 65 20 63 6f 64 65 2e 0a 2a 2a 20  SQLite code..** 
7390: 28 54 68 69 72 64 2d 70 61 72 74 79 20 56 46 53  (Third-party VFS
73a0: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
73b0: 20 6d 69 67 68 74 20 61 6c 73 6f 20 6d 61 6b 65   might also make
73c0: 20 74 68 65 20 64 69 73 74 69 6e 63 74 69 6f 6e   the distinction
73d0: 0a 2a 2a 20 62 65 74 77 65 65 6e 20 53 51 4c 49  .** between SQLI
73e0: 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61  TE_SYNC_NORMAL a
73f0: 6e 64 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46  nd SQLITE_SYNC_F
7400: 55 4c 4c 2c 20 62 75 74 20 61 6d 6f 6e 67 20 74  ULL, but among t
7410: 68 65 0a 2a 2a 20 6f 70 65 72 61 74 69 6e 67 20  he.** operating 
7420: 73 79 73 74 65 6d 73 20 6e 61 74 69 76 65 6c 79  systems natively
7430: 20 73 75 70 70 6f 72 74 65 64 20 62 79 20 53 51   supported by SQ
7440: 4c 69 74 65 2c 20 6f 6e 6c 79 20 4d 61 63 20 4f  Lite, only Mac O
7450: 53 58 0a 2a 2a 20 63 61 72 65 73 20 61 62 6f 75  SX.** cares abou
7460: 74 20 74 68 65 20 64 69 66 66 65 72 65 6e 63 65  t the difference
7470: 2e 29 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  .).*/.#define SQ
7480: 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c  LITE_SYNC_NORMAL
7490: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 32 0a          0x00002.
74a0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
74b0: 59 4e 43 5f 46 55 4c 4c 20 20 20 20 20 20 20 20  YNC_FULL        
74c0: 20 20 30 78 30 30 30 30 33 0a 23 64 65 66 69 6e    0x00003.#defin
74d0: 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41  e SQLITE_SYNC_DA
74e0: 54 41 4f 4e 4c 59 20 20 20 20 20 20 30 78 30 30  TAONLY      0x00
74f0: 30 31 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  010../*.** CAPI3
7500: 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66 61 63  REF: OS Interfac
7510: 65 20 4f 70 65 6e 20 46 69 6c 65 20 48 61 6e 64  e Open File Hand
7520: 6c 65 0a 2a 2a 0a 2a 2a 20 41 6e 20 5b 73 71 6c  le.**.** An [sql
7530: 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63  ite3_file] objec
7540: 74 20 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20  t represents an 
7550: 6f 70 65 6e 20 66 69 6c 65 20 69 6e 20 74 68 65  open file in the
7560: 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66   .** [sqlite3_vf
7570: 73 20 7c 20 4f 53 20 69 6e 74 65 72 66 61 63 65  s | OS interface
7580: 20 6c 61 79 65 72 5d 2e 20 20 49 6e 64 69 76 69   layer].  Indivi
7590: 64 75 61 6c 20 4f 53 20 69 6e 74 65 72 66 61 63  dual OS interfac
75a0: 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74  e.** implementat
75b0: 69 6f 6e 73 20 77 69 6c 6c 0a 2a 2a 20 77 61 6e  ions will.** wan
75c0: 74 20 74 6f 20 73 75 62 63 6c 61 73 73 20 74 68  t to subclass th
75d0: 69 73 20 6f 62 6a 65 63 74 20 62 79 20 61 70 70  is object by app
75e0: 65 6e 64 69 6e 67 20 61 64 64 69 74 69 6f 6e 61  ending additiona
75f0: 6c 20 66 69 65 6c 64 73 0a 2a 2a 20 66 6f 72 20  l fields.** for 
7600: 74 68 65 69 72 20 6f 77 6e 20 75 73 65 2e 20 20  their own use.  
7610: 54 68 65 20 70 4d 65 74 68 6f 64 73 20 65 6e 74  The pMethods ent
7620: 72 79 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20  ry is a pointer 
7630: 74 6f 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65  to an.** [sqlite
7640: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62  3_io_methods] ob
7650: 6a 65 63 74 20 74 68 61 74 20 64 65 66 69 6e 65  ject that define
7660: 73 20 6d 65 74 68 6f 64 73 20 66 6f 72 20 70 65  s methods for pe
7670: 72 66 6f 72 6d 69 6e 67 0a 2a 2a 20 49 2f 4f 20  rforming.** I/O 
7680: 6f 70 65 72 61 74 69 6f 6e 73 20 6f 6e 20 74 68  operations on th
7690: 65 20 6f 70 65 6e 20 66 69 6c 65 2e 0a 2a 2f 0a  e open file..*/.
76a0: 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73  typedef struct s
76b0: 71 6c 69 74 65 33 5f 66 69 6c 65 20 73 71 6c 69  qlite3_file sqli
76c0: 74 65 33 5f 66 69 6c 65 3b 0a 73 74 72 75 63 74  te3_file;.struct
76d0: 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 20 7b 0a   sqlite3_file {.
76e0: 20 20 63 6f 6e 73 74 20 73 74 72 75 63 74 20 73    const struct s
76f0: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
7700: 73 20 2a 70 4d 65 74 68 6f 64 73 3b 20 20 2f 2a  s *pMethods;  /*
7710: 20 4d 65 74 68 6f 64 73 20 66 6f 72 20 61 6e 20   Methods for an 
7720: 6f 70 65 6e 20 66 69 6c 65 20 2a 2f 0a 7d 3b 0a  open file */.};.
7730: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
7740: 20 4f 53 20 49 6e 74 65 72 66 61 63 65 20 46 69   OS Interface Fi
7750: 6c 65 20 56 69 72 74 75 61 6c 20 4d 65 74 68 6f  le Virtual Metho
7760: 64 73 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20  ds Object.**.** 
7770: 45 76 65 72 79 20 66 69 6c 65 20 6f 70 65 6e 65  Every file opene
7780: 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65  d by the [sqlite
7790: 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 6d 65 74  3_vfs.xOpen] met
77a0: 68 6f 64 20 70 6f 70 75 6c 61 74 65 73 20 61 6e  hod populates an
77b0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  .** [sqlite3_fil
77c0: 65 5d 20 6f 62 6a 65 63 74 20 28 6f 72 2c 20 6d  e] object (or, m
77d0: 6f 72 65 20 63 6f 6d 6d 6f 6e 6c 79 2c 20 61 20  ore commonly, a 
77e0: 73 75 62 63 6c 61 73 73 20 6f 66 20 74 68 65 0a  subclass of the.
77f0: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  ** [sqlite3_file
7800: 5d 20 6f 62 6a 65 63 74 29 20 77 69 74 68 20 61  ] object) with a
7810: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69   pointer to an i
7820: 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20  nstance of this 
7830: 6f 62 6a 65 63 74 2e 0a 2a 2a 20 54 68 69 73 20  object..** This 
7840: 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74  object defines t
7850: 68 65 20 6d 65 74 68 6f 64 73 20 75 73 65 64 20  he methods used 
7860: 74 6f 20 70 65 72 66 6f 72 6d 20 76 61 72 69 6f  to perform vario
7870: 75 73 20 6f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a  us operations.**
7880: 20 61 67 61 69 6e 73 74 20 74 68 65 20 6f 70 65   against the ope
7890: 6e 20 66 69 6c 65 20 72 65 70 72 65 73 65 6e 74  n file represent
78a0: 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74  ed by the [sqlit
78b0: 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 2e  e3_file] object.
78c0: 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 5b 73  .**.** If the [s
78d0: 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e  qlite3_vfs.xOpen
78e0: 5d 20 6d 65 74 68 6f 64 20 73 65 74 73 20 74 68  ] method sets th
78f0: 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70  e sqlite3_file.p
7900: 4d 65 74 68 6f 64 73 20 65 6c 65 6d 65 6e 74 20  Methods element 
7910: 0a 2a 2a 20 74 6f 20 61 20 6e 6f 6e 2d 4e 55 4c  .** to a non-NUL
7920: 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20  L pointer, then 
7930: 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  the sqlite3_io_m
7940: 65 74 68 6f 64 73 2e 78 43 6c 6f 73 65 20 6d 65  ethods.xClose me
7950: 74 68 6f 64 0a 2a 2a 20 6d 61 79 20 62 65 20 69  thod.** may be i
7960: 6e 76 6f 6b 65 64 20 65 76 65 6e 20 69 66 20 74  nvoked even if t
7970: 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e  he [sqlite3_vfs.
7980: 78 4f 70 65 6e 5d 20 72 65 70 6f 72 74 65 64 20  xOpen] reported 
7990: 74 68 61 74 20 69 74 20 66 61 69 6c 65 64 2e 20  that it failed. 
79a0: 20 54 68 65 0a 2a 2a 20 6f 6e 6c 79 20 77 61 79   The.** only way
79b0: 20 74 6f 20 70 72 65 76 65 6e 74 20 61 20 63 61   to prevent a ca
79c0: 6c 6c 20 74 6f 20 78 43 6c 6f 73 65 20 66 6f 6c  ll to xClose fol
79d0: 6c 6f 77 69 6e 67 20 61 20 66 61 69 6c 65 64 20  lowing a failed 
79e0: 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70  [sqlite3_vfs.xOp
79f0: 65 6e 5d 0a 2a 2a 20 69 73 20 66 6f 72 20 74 68  en].** is for th
7a00: 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78  e [sqlite3_vfs.x
7a10: 4f 70 65 6e 5d 20 74 6f 20 73 65 74 20 74 68 65  Open] to set the
7a20: 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d   sqlite3_file.pM
7a30: 65 74 68 6f 64 73 20 65 6c 65 6d 65 6e 74 0a 2a  ethods element.*
7a40: 2a 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a  * to NULL..**.**
7a50: 20 54 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d   The flags argum
7a60: 65 6e 74 20 74 6f 20 78 53 79 6e 63 20 6d 61 79  ent to xSync may
7a70: 20 62 65 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49   be one of [SQLI
7a80: 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 5d 20  TE_SYNC_NORMAL] 
7a90: 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 53 59  or.** [SQLITE_SY
7aa0: 4e 43 5f 46 55 4c 4c 5d 2e 20 20 54 68 65 20 66  NC_FULL].  The f
7ab0: 69 72 73 74 20 63 68 6f 69 63 65 20 69 73 20 74  irst choice is t
7ac0: 68 65 20 6e 6f 72 6d 61 6c 20 66 73 79 6e 63 28  he normal fsync(
7ad0: 29 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64  )..** The second
7ae0: 20 63 68 6f 69 63 65 20 69 73 20 61 20 4d 61 63   choice is a Mac
7af0: 20 4f 53 20 58 20 73 74 79 6c 65 20 66 75 6c 6c   OS X style full
7b00: 73 79 6e 63 2e 20 20 54 68 65 20 5b 53 51 4c 49  sync.  The [SQLI
7b10: 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59  TE_SYNC_DATAONLY
7b20: 5d 0a 2a 2a 20 66 6c 61 67 20 6d 61 79 20 62 65  ].** flag may be
7b30: 20 4f 52 65 64 20 69 6e 20 74 6f 20 69 6e 64 69   ORed in to indi
7b40: 63 61 74 65 20 74 68 61 74 20 6f 6e 6c 79 20 74  cate that only t
7b50: 68 65 20 64 61 74 61 20 6f 66 20 74 68 65 20 66  he data of the f
7b60: 69 6c 65 0a 2a 2a 20 61 6e 64 20 6e 6f 74 20 69  ile.** and not i
7b70: 74 73 20 69 6e 6f 64 65 20 6e 65 65 64 73 20 74  ts inode needs t
7b80: 6f 20 62 65 20 73 79 6e 63 65 64 2e 0a 2a 2a 0a  o be synced..**.
7b90: 2a 2a 20 54 68 65 20 69 6e 74 65 67 65 72 20 76  ** The integer v
7ba0: 61 6c 75 65 73 20 74 6f 20 78 4c 6f 63 6b 28 29  alues to xLock()
7bb0: 20 61 6e 64 20 78 55 6e 6c 6f 63 6b 28 29 20 61   and xUnlock() a
7bc0: 72 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 3c 75 6c  re one of.** <ul
7bd0: 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  >.** <li> [SQLIT
7be0: 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 0a 2a 2a  E_LOCK_NONE],.**
7bf0: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f   <li> [SQLITE_LO
7c00: 43 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 3c  CK_SHARED],.** <
7c10: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b  li> [SQLITE_LOCK
7c20: 5f 52 45 53 45 52 56 45 44 5d 2c 0a 2a 2a 20 3c  _RESERVED],.** <
7c30: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b  li> [SQLITE_LOCK
7c40: 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f 72 0a 2a 2a  _PENDING], or.**
7c50: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f   <li> [SQLITE_LO
7c60: 43 4b 5f 45 58 43 4c 55 53 49 56 45 5d 2e 0a 2a  CK_EXCLUSIVE]..*
7c70: 2a 20 3c 2f 75 6c 3e 0a 2a 2a 20 78 4c 6f 63 6b  * </ul>.** xLock
7c80: 28 29 20 69 6e 63 72 65 61 73 65 73 20 74 68 65  () increases the
7c90: 20 6c 6f 63 6b 2e 20 78 55 6e 6c 6f 63 6b 28 29   lock. xUnlock()
7ca0: 20 64 65 63 72 65 61 73 65 73 20 74 68 65 20 6c   decreases the l
7cb0: 6f 63 6b 2e 0a 2a 2a 20 54 68 65 20 78 43 68 65  ock..** The xChe
7cc0: 63 6b 52 65 73 65 72 76 65 64 4c 6f 63 6b 28 29  ckReservedLock()
7cd0: 20 6d 65 74 68 6f 64 20 63 68 65 63 6b 73 20 77   method checks w
7ce0: 68 65 74 68 65 72 20 61 6e 79 20 64 61 74 61 62  hether any datab
7cf0: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 0a  ase connection,.
7d00: 2a 2a 20 65 69 74 68 65 72 20 69 6e 20 74 68 69  ** either in thi
7d10: 73 20 70 72 6f 63 65 73 73 20 6f 72 20 69 6e 20  s process or in 
7d20: 73 6f 6d 65 20 6f 74 68 65 72 20 70 72 6f 63 65  some other proce
7d30: 73 73 2c 20 69 73 20 68 6f 6c 64 69 6e 67 20 61  ss, is holding a
7d40: 20 52 45 53 45 52 56 45 44 2c 0a 2a 2a 20 50 45   RESERVED,.** PE
7d50: 4e 44 49 4e 47 2c 20 6f 72 20 45 58 43 4c 55 53  NDING, or EXCLUS
7d60: 49 56 45 20 6c 6f 63 6b 20 6f 6e 20 74 68 65 20  IVE lock on the 
7d70: 66 69 6c 65 2e 20 20 49 74 20 72 65 74 75 72 6e  file.  It return
7d80: 73 20 74 72 75 65 0a 2a 2a 20 69 66 20 73 75 63  s true.** if suc
7d90: 68 20 61 20 6c 6f 63 6b 20 65 78 69 73 74 73 20  h a lock exists 
7da0: 61 6e 64 20 66 61 6c 73 65 20 6f 74 68 65 72 77  and false otherw
7db0: 69 73 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78  ise..**.** The x
7dc0: 46 69 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d 65  FileControl() me
7dd0: 74 68 6f 64 20 69 73 20 61 20 67 65 6e 65 72 69  thod is a generi
7de0: 63 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74  c interface that
7df0: 20 61 6c 6c 6f 77 73 20 63 75 73 74 6f 6d 0a 2a   allows custom.*
7e00: 2a 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61  * VFS implementa
7e10: 74 69 6f 6e 73 20 74 6f 20 64 69 72 65 63 74 6c  tions to directl
7e20: 79 20 63 6f 6e 74 72 6f 6c 20 61 6e 20 6f 70 65  y control an ope
7e30: 6e 20 66 69 6c 65 20 75 73 69 6e 67 20 74 68 65  n file using the
7e40: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  .** [sqlite3_fil
7e50: 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 69 6e 74  e_control()] int
7e60: 65 72 66 61 63 65 2e 20 20 54 68 65 20 73 65 63  erface.  The sec
7e70: 6f 6e 64 20 22 6f 70 22 20 61 72 67 75 6d 65 6e  ond "op" argumen
7e80: 74 20 69 73 20 61 6e 0a 2a 2a 20 69 6e 74 65 67  t is an.** integ
7e90: 65 72 20 6f 70 63 6f 64 65 2e 20 20 54 68 65 20  er opcode.  The 
7ea0: 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69  third argument i
7eb0: 73 20 61 20 67 65 6e 65 72 69 63 20 70 6f 69 6e  s a generic poin
7ec0: 74 65 72 20 69 6e 74 65 6e 64 65 64 20 74 6f 0a  ter intended to.
7ed0: 2a 2a 20 70 6f 69 6e 74 20 74 6f 20 61 20 73 74  ** point to a st
7ee0: 72 75 63 74 75 72 65 20 74 68 61 74 20 6d 61 79  ructure that may
7ef0: 20 63 6f 6e 74 61 69 6e 20 61 72 67 75 6d 65 6e   contain argumen
7f00: 74 73 20 6f 72 20 73 70 61 63 65 20 69 6e 20 77  ts or space in w
7f10: 68 69 63 68 20 74 6f 0a 2a 2a 20 77 72 69 74 65  hich to.** write
7f20: 20 72 65 74 75 72 6e 20 76 61 6c 75 65 73 2e 20   return values. 
7f30: 20 50 6f 74 65 6e 74 69 61 6c 20 75 73 65 73 20   Potential uses 
7f40: 66 6f 72 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c  for xFileControl
7f50: 28 29 20 6d 69 67 68 74 20 62 65 0a 2a 2a 20 66  () might be.** f
7f60: 75 6e 63 74 69 6f 6e 73 20 74 6f 20 65 6e 61 62  unctions to enab
7f70: 6c 65 20 62 6c 6f 63 6b 69 6e 67 20 6c 6f 63 6b  le blocking lock
7f80: 73 20 77 69 74 68 20 74 69 6d 65 6f 75 74 73 2c  s with timeouts,
7f90: 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65 0a 2a   to change the.*
7fa0: 2a 20 6c 6f 63 6b 69 6e 67 20 73 74 72 61 74 65  * locking strate
7fb0: 67 79 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20  gy (for example 
7fc0: 74 6f 20 75 73 65 20 64 6f 74 2d 66 69 6c 65 20  to use dot-file 
7fd0: 6c 6f 63 6b 73 29 2c 20 74 6f 20 69 6e 71 75 69  locks), to inqui
7fe0: 72 65 0a 2a 2a 20 61 62 6f 75 74 20 74 68 65 20  re.** about the 
7ff0: 73 74 61 74 75 73 20 6f 66 20 61 20 6c 6f 63 6b  status of a lock
8000: 2c 20 6f 72 20 74 6f 20 62 72 65 61 6b 20 73 74  , or to break st
8010: 61 6c 65 20 6c 6f 63 6b 73 2e 20 20 54 68 65 20  ale locks.  The 
8020: 53 51 4c 69 74 65 0a 2a 2a 20 63 6f 72 65 20 72  SQLite.** core r
8030: 65 73 65 72 76 65 73 20 61 6c 6c 20 6f 70 63 6f  eserves all opco
8040: 64 65 73 20 6c 65 73 73 20 74 68 61 6e 20 31 30  des less than 10
8050: 30 20 66 6f 72 20 69 74 73 20 6f 77 6e 20 75 73  0 for its own us
8060: 65 2e 0a 2a 2a 20 41 20 5b 66 69 6c 65 20 63 6f  e..** A [file co
8070: 6e 74 72 6f 6c 20 6f 70 63 6f 64 65 73 20 7c 20  ntrol opcodes | 
8080: 6c 69 73 74 20 6f 66 20 6f 70 63 6f 64 65 73 5d  list of opcodes]
8090: 20 6c 65 73 73 20 74 68 61 6e 20 31 30 30 20 69   less than 100 i
80a0: 73 20 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20  s available..** 
80b0: 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61  Applications tha
80c0: 74 20 64 65 66 69 6e 65 20 61 20 63 75 73 74 6f  t define a custo
80d0: 6d 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d  m xFileControl m
80e0: 65 74 68 6f 64 20 73 68 6f 75 6c 64 20 75 73 65  ethod should use
80f0: 20 6f 70 63 6f 64 65 73 0a 2a 2a 20 67 72 65 61   opcodes.** grea
8100: 74 65 72 20 74 68 61 6e 20 31 30 30 20 74 6f 20  ter than 100 to 
8110: 61 76 6f 69 64 20 63 6f 6e 66 6c 69 63 74 73 2e  avoid conflicts.
8120: 20 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61    VFS implementa
8130: 74 69 6f 6e 73 20 73 68 6f 75 6c 64 0a 2a 2a 20  tions should.** 
8140: 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4e  return [SQLITE_N
8150: 4f 54 46 4f 55 4e 44 5d 20 66 6f 72 20 66 69 6c  OTFOUND] for fil
8160: 65 20 63 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64 65  e control opcode
8170: 73 20 74 68 61 74 20 74 68 65 79 20 64 6f 20 6e  s that they do n
8180: 6f 74 0a 2a 2a 20 72 65 63 6f 67 6e 69 7a 65 2e  ot.** recognize.
8190: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 65 63 74  .**.** The xSect
81a0: 6f 72 53 69 7a 65 28 29 20 6d 65 74 68 6f 64 20  orSize() method 
81b0: 72 65 74 75 72 6e 73 20 74 68 65 20 73 65 63 74  returns the sect
81c0: 6f 72 20 73 69 7a 65 20 6f 66 20 74 68 65 0a 2a  or size of the.*
81d0: 2a 20 64 65 76 69 63 65 20 74 68 61 74 20 75 6e  * device that un
81e0: 64 65 72 6c 69 65 73 20 74 68 65 20 66 69 6c 65  derlies the file
81f0: 2e 20 20 54 68 65 20 73 65 63 74 6f 72 20 73 69  .  The sector si
8200: 7a 65 20 69 73 20 74 68 65 0a 2a 2a 20 6d 69 6e  ze is the.** min
8210: 69 6d 75 6d 20 77 72 69 74 65 20 74 68 61 74 20  imum write that 
8220: 63 61 6e 20 62 65 20 70 65 72 66 6f 72 6d 65 64  can be performed
8230: 20 77 69 74 68 6f 75 74 20 64 69 73 74 75 72 62   without disturb
8240: 69 6e 67 0a 2a 2a 20 6f 74 68 65 72 20 62 79 74  ing.** other byt
8250: 65 73 20 69 6e 20 74 68 65 20 66 69 6c 65 2e 20  es in the file. 
8260: 20 54 68 65 20 78 44 65 76 69 63 65 43 68 61 72   The xDeviceChar
8270: 61 63 74 65 72 69 73 74 69 63 73 28 29 0a 2a 2a  acteristics().**
8280: 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20   method returns 
8290: 61 20 62 69 74 20 76 65 63 74 6f 72 20 64 65 73  a bit vector des
82a0: 63 72 69 62 69 6e 67 20 62 65 68 61 76 69 6f 72  cribing behavior
82b0: 73 20 6f 66 20 74 68 65 0a 2a 2a 20 75 6e 64 65  s of the.** unde
82c0: 72 6c 79 69 6e 67 20 64 65 76 69 63 65 3a 0a 2a  rlying device:.*
82d0: 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ul>.** <li
82e0: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
82f0: 41 54 4f 4d 49 43 5d 0a 2a 2a 20 3c 6c 69 3e 20  ATOMIC].** <li> 
8300: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54  [SQLITE_IOCAP_AT
8310: 4f 4d 49 43 35 31 32 5d 0a 2a 2a 20 3c 6c 69 3e  OMIC512].** <li>
8320: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
8330: 54 4f 4d 49 43 31 4b 5d 0a 2a 2a 20 3c 6c 69 3e  TOMIC1K].** <li>
8340: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
8350: 54 4f 4d 49 43 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e  TOMIC2K].** <li>
8360: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
8370: 54 4f 4d 49 43 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e  TOMIC4K].** <li>
8380: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
8390: 54 4f 4d 49 43 38 4b 5d 0a 2a 2a 20 3c 6c 69 3e  TOMIC8K].** <li>
83a0: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
83b0: 54 4f 4d 49 43 31 36 4b 5d 0a 2a 2a 20 3c 6c 69  TOMIC16K].** <li
83c0: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
83d0: 41 54 4f 4d 49 43 33 32 4b 5d 0a 2a 2a 20 3c 6c  ATOMIC32K].** <l
83e0: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  i> [SQLITE_IOCAP
83f0: 5f 41 54 4f 4d 49 43 36 34 4b 5d 0a 2a 2a 20 3c  _ATOMIC64K].** <
8400: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41  li> [SQLITE_IOCA
8410: 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 5d 0a 2a  P_SAFE_APPEND].*
8420: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49  * <li> [SQLITE_I
8430: 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 5d  OCAP_SEQUENTIAL]
8440: 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20  .** </ul>.**.** 
8450: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
8460: 5f 41 54 4f 4d 49 43 20 70 72 6f 70 65 72 74 79  _ATOMIC property
8470: 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6c 6c 20   means that all 
8480: 77 72 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79  writes of.** any
8490: 20 73 69 7a 65 20 61 72 65 20 61 74 6f 6d 69 63   size are atomic
84a0: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f  .  The SQLITE_IO
84b0: 43 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61  CAP_ATOMICnnn va
84c0: 6c 75 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61  lues.** mean tha
84d0: 74 20 77 72 69 74 65 73 20 6f 66 20 62 6c 6f 63  t writes of bloc
84e0: 6b 73 20 74 68 61 74 20 61 72 65 20 6e 6e 6e 20  ks that are nnn 
84f0: 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20 61 6e  bytes in size an
8500: 64 0a 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65 64  d.** are aligned
8510: 20 74 6f 20 61 6e 20 61 64 64 72 65 73 73 20 77   to an address w
8520: 68 69 63 68 20 69 73 20 61 6e 20 69 6e 74 65 67  hich is an integ
8530: 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a  er multiple of.*
8540: 2a 20 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63  * nnn are atomic
8550: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f  .  The SQLITE_IO
8560: 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20  CAP_SAFE_APPEND 
8570: 76 61 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74  value means.** t
8580: 68 61 74 20 77 68 65 6e 20 64 61 74 61 20 69 73  hat when data is
8590: 20 61 70 70 65 6e 64 65 64 20 74 6f 20 61 20 66   appended to a f
85a0: 69 6c 65 2c 20 74 68 65 20 64 61 74 61 20 69 73  ile, the data is
85b0: 20 61 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72   appended.** fir
85c0: 73 74 20 74 68 65 6e 20 74 68 65 20 73 69 7a 65  st then the size
85d0: 20 6f 66 20 74 68 65 20 66 69 6c 65 20 69 73 20   of the file is 
85e0: 65 78 74 65 6e 64 65 64 2c 20 6e 65 76 65 72 20  extended, never 
85f0: 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79  the other.** way
8600: 20 61 72 6f 75 6e 64 2e 20 20 54 68 65 20 53 51   around.  The SQ
8610: 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45  LITE_IOCAP_SEQUE
8620: 4e 54 49 41 4c 20 70 72 6f 70 65 72 74 79 20 6d  NTIAL property m
8630: 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66  eans that.** inf
8640: 6f 72 6d 61 74 69 6f 6e 20 69 73 20 77 72 69 74  ormation is writ
8650: 74 65 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20 74  ten to disk in t
8660: 68 65 20 73 61 6d 65 20 6f 72 64 65 72 20 61 73  he same order as
8670: 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72   calls.** to xWr
8680: 69 74 65 28 29 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  ite()..**.** If 
8690: 78 52 65 61 64 28 29 20 72 65 74 75 72 6e 73 20  xRead() returns 
86a0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4f  SQLITE_IOERR_SHO
86b0: 52 54 5f 52 45 41 44 20 69 74 20 6d 75 73 74 20  RT_READ it must 
86c0: 61 6c 73 6f 20 66 69 6c 6c 0a 2a 2a 20 69 6e 20  also fill.** in 
86d0: 74 68 65 20 75 6e 72 65 61 64 20 70 6f 72 74 69  the unread porti
86e0: 6f 6e 73 20 6f 66 20 74 68 65 20 62 75 66 66 65  ons of the buffe
86f0: 72 20 77 69 74 68 20 7a 65 72 6f 73 2e 20 20 41  r with zeros.  A
8700: 20 56 46 53 20 74 68 61 74 0a 2a 2a 20 66 61 69   VFS that.** fai
8710: 6c 73 20 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c 20  ls to zero-fill 
8720: 73 68 6f 72 74 20 72 65 61 64 73 20 6d 69 67 68  short reads migh
8730: 74 20 73 65 65 6d 20 74 6f 20 77 6f 72 6b 2e 20  t seem to work. 
8740: 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 66 61 69   However,.** fai
8750: 6c 75 72 65 20 74 6f 20 7a 65 72 6f 2d 66 69 6c  lure to zero-fil
8760: 6c 20 73 68 6f 72 74 20 72 65 61 64 73 20 77 69  l short reads wi
8770: 6c 6c 20 65 76 65 6e 74 75 61 6c 6c 79 20 6c 65  ll eventually le
8780: 61 64 20 74 6f 0a 2a 2a 20 64 61 74 61 62 61 73  ad to.** databas
8790: 65 20 63 6f 72 72 75 70 74 69 6f 6e 2e 0a 2a 2f  e corruption..*/
87a0: 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
87b0: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
87c0: 64 73 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  ds sqlite3_io_me
87d0: 74 68 6f 64 73 3b 0a 73 74 72 75 63 74 20 73 71  thods;.struct sq
87e0: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
87f0: 20 7b 0a 20 20 69 6e 74 20 69 56 65 72 73 69 6f   {.  int iVersio
8800: 6e 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6c 6f 73  n;.  int (*xClos
8810: 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  e)(sqlite3_file*
8820: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52 65 61 64  );.  int (*xRead
8830: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
8840: 20 76 6f 69 64 2a 2c 20 69 6e 74 20 69 41 6d 74   void*, int iAmt
8850: 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  , sqlite3_int64 
8860: 69 4f 66 73 74 29 3b 0a 20 20 69 6e 74 20 28 2a  iOfst);.  int (*
8870: 78 57 72 69 74 65 29 28 73 71 6c 69 74 65 33 5f  xWrite)(sqlite3_
8880: 66 69 6c 65 2a 2c 20 63 6f 6e 73 74 20 76 6f 69  file*, const voi
8890: 64 2a 2c 20 69 6e 74 20 69 41 6d 74 2c 20 73 71  d*, int iAmt, sq
88a0: 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66 73  lite3_int64 iOfs
88b0: 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 54 72 75  t);.  int (*xTru
88c0: 6e 63 61 74 65 29 28 73 71 6c 69 74 65 33 5f 66  ncate)(sqlite3_f
88d0: 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e  ile*, sqlite3_in
88e0: 74 36 34 20 73 69 7a 65 29 3b 0a 20 20 69 6e 74  t64 size);.  int
88f0: 20 28 2a 78 53 79 6e 63 29 28 73 71 6c 69 74 65   (*xSync)(sqlite
8900: 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 66 6c 61  3_file*, int fla
8910: 67 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69  gs);.  int (*xFi
8920: 6c 65 53 69 7a 65 29 28 73 71 6c 69 74 65 33 5f  leSize)(sqlite3_
8930: 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69  file*, sqlite3_i
8940: 6e 74 36 34 20 2a 70 53 69 7a 65 29 3b 0a 20 20  nt64 *pSize);.  
8950: 69 6e 74 20 28 2a 78 4c 6f 63 6b 29 28 73 71 6c  int (*xLock)(sql
8960: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 29  ite3_file*, int)
8970: 3b 0a 20 20 69 6e 74 20 28 2a 78 55 6e 6c 6f 63  ;.  int (*xUnloc
8980: 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  k)(sqlite3_file*
8990: 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28 2a  , int);.  int (*
89a0: 78 43 68 65 63 6b 52 65 73 65 72 76 65 64 4c 6f  xCheckReservedLo
89b0: 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ck)(sqlite3_file
89c0: 2a 2c 20 69 6e 74 20 2a 70 52 65 73 4f 75 74 29  *, int *pResOut)
89d0: 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69 6c 65 43  ;.  int (*xFileC
89e0: 6f 6e 74 72 6f 6c 29 28 73 71 6c 69 74 65 33 5f  ontrol)(sqlite3_
89f0: 66 69 6c 65 2a 2c 20 69 6e 74 20 6f 70 2c 20 76  file*, int op, v
8a00: 6f 69 64 20 2a 70 41 72 67 29 3b 0a 20 20 69 6e  oid *pArg);.  in
8a10: 74 20 28 2a 78 53 65 63 74 6f 72 53 69 7a 65 29  t (*xSectorSize)
8a20: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b  (sqlite3_file*);
8a30: 0a 20 20 69 6e 74 20 28 2a 78 44 65 76 69 63 65  .  int (*xDevice
8a40: 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73 29  Characteristics)
8a50: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b  (sqlite3_file*);
8a60: 0a 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61 62  .  /* Methods ab
8a70: 6f 76 65 20 61 72 65 20 76 61 6c 69 64 20 66 6f  ove are valid fo
8a80: 72 20 76 65 72 73 69 6f 6e 20 31 20 2a 2f 0a 20  r version 1 */. 
8a90: 20 69 6e 74 20 28 2a 78 53 68 6d 4d 61 70 29 28   int (*xShmMap)(
8aa0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69  sqlite3_file*, i
8ab0: 6e 74 20 69 50 67 2c 20 69 6e 74 20 70 67 73 7a  nt iPg, int pgsz
8ac0: 2c 20 69 6e 74 2c 20 76 6f 69 64 20 76 6f 6c 61  , int, void vola
8ad0: 74 69 6c 65 2a 2a 29 3b 0a 20 20 69 6e 74 20 28  tile**);.  int (
8ae0: 2a 78 53 68 6d 4c 6f 63 6b 29 28 73 71 6c 69 74  *xShmLock)(sqlit
8af0: 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 6f 66  e3_file*, int of
8b00: 66 73 65 74 2c 20 69 6e 74 20 6e 2c 20 69 6e 74  fset, int n, int
8b10: 20 66 6c 61 67 73 29 3b 0a 20 20 76 6f 69 64 20   flags);.  void 
8b20: 28 2a 78 53 68 6d 42 61 72 72 69 65 72 29 28 73  (*xShmBarrier)(s
8b30: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20  qlite3_file*);. 
8b40: 20 69 6e 74 20 28 2a 78 53 68 6d 55 6e 6d 61 70   int (*xShmUnmap
8b50: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
8b60: 20 69 6e 74 20 64 65 6c 65 74 65 46 6c 61 67 29   int deleteFlag)
8b70: 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61  ;.  /* Methods a
8b80: 62 6f 76 65 20 61 72 65 20 76 61 6c 69 64 20 66  bove are valid f
8b90: 6f 72 20 76 65 72 73 69 6f 6e 20 32 20 2a 2f 0a  or version 2 */.
8ba0: 20 20 69 6e 74 20 28 2a 78 46 65 74 63 68 29 28    int (*xFetch)(
8bb0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73  sqlite3_file*, s
8bc0: 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66  qlite3_int64 iOf
8bd0: 73 74 2c 20 69 6e 74 20 69 41 6d 74 2c 20 76 6f  st, int iAmt, vo
8be0: 69 64 20 2a 2a 70 70 29 3b 0a 20 20 69 6e 74 20  id **pp);.  int 
8bf0: 28 2a 78 55 6e 66 65 74 63 68 29 28 73 71 6c 69  (*xUnfetch)(sqli
8c00: 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74  te3_file*, sqlit
8c10: 65 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 2c 20  e3_int64 iOfst, 
8c20: 76 6f 69 64 20 2a 70 29 3b 0a 20 20 2f 2a 20 4d  void *p);.  /* M
8c30: 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65  ethods above are
8c40: 20 76 61 6c 69 64 20 66 6f 72 20 76 65 72 73 69   valid for versi
8c50: 6f 6e 20 33 20 2a 2f 0a 20 20 2f 2a 20 41 64 64  on 3 */.  /* Add
8c60: 69 74 69 6f 6e 61 6c 20 6d 65 74 68 6f 64 73 20  itional methods 
8c70: 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20  may be added in 
8c80: 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20  future releases 
8c90: 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  */.};../*.** CAP
8ca0: 49 33 52 45 46 3a 20 53 74 61 6e 64 61 72 64 20  I3REF: Standard 
8cb0: 46 69 6c 65 20 43 6f 6e 74 72 6f 6c 20 4f 70 63  File Control Opc
8cc0: 6f 64 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  odes.** KEYWORDS
8cd0: 3a 20 7b 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20  : {file control 
8ce0: 6f 70 63 6f 64 65 73 7d 20 7b 66 69 6c 65 20 63  opcodes} {file c
8cf0: 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64 65 7d 0a 2a  ontrol opcode}.*
8d00: 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 67  *.** These integ
8d10: 65 72 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65  er constants are
8d20: 20 6f 70 63 6f 64 65 73 20 66 6f 72 20 74 68 65   opcodes for the
8d30: 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65   xFileControl me
8d40: 74 68 6f 64 0a 2a 2a 20 6f 66 20 74 68 65 20 5b  thod.** of the [
8d50: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
8d60: 64 73 5d 20 6f 62 6a 65 63 74 20 61 6e 64 20 66  ds] object and f
8d70: 6f 72 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  or the [sqlite3_
8d80: 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 0a  file_control()].
8d90: 2a 2a 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a  ** interface..**
8da0: 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
8db0: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c  [[SQLITE_FCNTL_L
8dc0: 4f 43 4b 53 54 41 54 45 5d 5d 0a 2a 2a 20 54 68  OCKSTATE]].** Th
8dd0: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
8de0: 4c 4f 43 4b 53 54 41 54 45 5d 20 6f 70 63 6f 64  LOCKSTATE] opcod
8df0: 65 20 69 73 20 75 73 65 64 20 66 6f 72 20 64 65  e is used for de
8e00: 62 75 67 67 69 6e 67 2e 20 20 54 68 69 73 0a 2a  bugging.  This.*
8e10: 2a 20 6f 70 63 6f 64 65 20 63 61 75 73 65 73 20  * opcode causes 
8e20: 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c  the xFileControl
8e30: 20 6d 65 74 68 6f 64 20 74 6f 20 77 72 69 74 65   method to write
8e40: 20 74 68 65 20 63 75 72 72 65 6e 74 20 73 74 61   the current sta
8e50: 74 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6c 6f 63  te of.** the loc
8e60: 6b 20 28 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54  k (one of [SQLIT
8e70: 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 20 5b 53  E_LOCK_NONE], [S
8e80: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45  QLITE_LOCK_SHARE
8e90: 44 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4c  D],.** [SQLITE_L
8ea0: 4f 43 4b 5f 52 45 53 45 52 56 45 44 5d 2c 20 5b  OCK_RESERVED], [
8eb0: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44  SQLITE_LOCK_PEND
8ec0: 49 4e 47 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45  ING], or [SQLITE
8ed0: 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 5d  _LOCK_EXCLUSIVE]
8ee0: 29 0a 2a 2a 20 69 6e 74 6f 20 61 6e 20 69 6e 74  ).** into an int
8ef0: 65 67 65 72 20 74 68 61 74 20 74 68 65 20 70 41  eger that the pA
8f00: 72 67 20 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e  rg argument poin
8f10: 74 73 20 74 6f 2e 20 54 68 69 73 20 63 61 70 61  ts to. This capa
8f20: 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20 75 73 65  bility.** is use
8f30: 64 20 64 75 72 69 6e 67 20 74 65 73 74 69 6e 67  d during testing
8f40: 20 61 6e 64 20 69 73 20 6f 6e 6c 79 20 61 76 61   and is only ava
8f50: 69 6c 61 62 6c 65 20 77 68 65 6e 20 74 68 65 20  ilable when the 
8f60: 53 51 4c 49 54 45 5f 54 45 53 54 0a 2a 2a 20 63  SQLITE_TEST.** c
8f70: 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
8f80: 6f 6e 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a  on is used..**.*
8f90: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
8fa0: 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e 54 5d 5d  CNTL_SIZE_HINT]]
8fb0: 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  .** The [SQLITE_
8fc0: 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e 54 5d  FCNTL_SIZE_HINT]
8fd0: 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20   opcode is used 
8fe0: 62 79 20 53 51 4c 69 74 65 20 74 6f 20 67 69 76  by SQLite to giv
8ff0: 65 20 74 68 65 20 56 46 53 0a 2a 2a 20 6c 61 79  e the VFS.** lay
9000: 65 72 20 61 20 68 69 6e 74 20 6f 66 20 68 6f 77  er a hint of how
9010: 20 6c 61 72 67 65 20 74 68 65 20 64 61 74 61 62   large the datab
9020: 61 73 65 20 66 69 6c 65 20 77 69 6c 6c 20 67 72  ase file will gr
9030: 6f 77 20 74 6f 20 62 65 20 64 75 72 69 6e 67 20  ow to be during 
9040: 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 20 74  the.** current t
9050: 72 61 6e 73 61 63 74 69 6f 6e 2e 20 20 54 68 69  ransaction.  Thi
9060: 73 20 68 69 6e 74 20 69 73 20 6e 6f 74 20 67 75  s hint is not gu
9070: 61 72 61 6e 74 65 65 64 20 74 6f 20 62 65 20 61  aranteed to be a
9080: 63 63 75 72 61 74 65 20 62 75 74 20 69 74 0a 2a  ccurate but it.*
9090: 2a 20 69 73 20 6f 66 74 65 6e 20 63 6c 6f 73 65  * is often close
90a0: 2e 20 20 54 68 65 20 75 6e 64 65 72 6c 79 69 6e  .  The underlyin
90b0: 67 20 56 46 53 20 6d 69 67 68 74 20 63 68 6f 6f  g VFS might choo
90c0: 73 65 20 74 6f 20 70 72 65 61 6c 6c 6f 63 61 74  se to preallocat
90d0: 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 66 69  e database.** fi
90e0: 6c 65 20 73 70 61 63 65 20 62 61 73 65 64 20 6f  le space based o
90f0: 6e 20 74 68 69 73 20 68 69 6e 74 20 69 6e 20 6f  n this hint in o
9100: 72 64 65 72 20 74 6f 20 68 65 6c 70 20 77 72 69  rder to help wri
9110: 74 65 73 20 74 6f 20 74 68 65 20 64 61 74 61 62  tes to the datab
9120: 61 73 65 0a 2a 2a 20 66 69 6c 65 20 72 75 6e 20  ase.** file run 
9130: 66 61 73 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  faster..**.** <l
9140: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
9150: 5f 43 48 55 4e 4b 5f 53 49 5a 45 5d 5d 0a 2a 2a  _CHUNK_SIZE]].**
9160: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e   The [SQLITE_FCN
9170: 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45 5d 20 6f  TL_CHUNK_SIZE] o
9180: 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f  pcode is used to
9190: 20 72 65 71 75 65 73 74 20 74 68 61 74 20 74 68   request that th
91a0: 65 20 56 46 53 0a 2a 2a 20 65 78 74 65 6e 64 73  e VFS.** extends
91b0: 20 61 6e 64 20 74 72 75 6e 63 61 74 65 73 20 74   and truncates t
91c0: 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
91d0: 20 69 6e 20 63 68 75 6e 6b 73 20 6f 66 20 61 20   in chunks of a 
91e0: 73 69 7a 65 20 73 70 65 63 69 66 69 65 64 0a 2a  size specified.*
91f0: 2a 20 62 79 20 74 68 65 20 75 73 65 72 2e 20 54  * by the user. T
9200: 68 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65  he fourth argume
9210: 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66  nt to [sqlite3_f
9220: 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 73  ile_control()] s
9230: 68 6f 75 6c 64 20 0a 2a 2a 20 70 6f 69 6e 74 20  hould .** point 
9240: 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 28 74  to an integer (t
9250: 79 70 65 20 69 6e 74 29 20 63 6f 6e 74 61 69 6e  ype int) contain
9260: 69 6e 67 20 74 68 65 20 6e 65 77 20 63 68 75 6e  ing the new chun
9270: 6b 2d 73 69 7a 65 20 74 6f 20 75 73 65 0a 2a 2a  k-size to use.**
9280: 20 66 6f 72 20 74 68 65 20 6e 6f 6d 69 6e 61 74   for the nominat
9290: 65 64 20 64 61 74 61 62 61 73 65 2e 20 41 6c 6c  ed database. All
92a0: 6f 63 61 74 69 6e 67 20 64 61 74 61 62 61 73 65  ocating database
92b0: 20 66 69 6c 65 20 73 70 61 63 65 20 69 6e 20 6c   file space in l
92c0: 61 72 67 65 0a 2a 2a 20 63 68 75 6e 6b 73 20 28  arge.** chunks (
92d0: 73 61 79 20 31 4d 42 20 61 74 20 61 20 74 69 6d  say 1MB at a tim
92e0: 65 29 2c 20 6d 61 79 20 72 65 64 75 63 65 20 66  e), may reduce f
92f0: 69 6c 65 2d 73 79 73 74 65 6d 20 66 72 61 67 6d  ile-system fragm
9300: 65 6e 74 61 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20  entation and.** 
9310: 69 6d 70 72 6f 76 65 20 70 65 72 66 6f 72 6d 61  improve performa
9320: 6e 63 65 20 6f 6e 20 73 6f 6d 65 20 73 79 73 74  nce on some syst
9330: 65 6d 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  ems..**.** <li>[
9340: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49  [SQLITE_FCNTL_FI
9350: 4c 45 5f 50 4f 49 4e 54 45 52 5d 5d 0a 2a 2a 20  LE_POINTER]].** 
9360: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
9370: 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52 5d 20  L_FILE_POINTER] 
9380: 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 74  opcode is used t
9390: 6f 20 6f 62 74 61 69 6e 20 61 20 70 6f 69 6e 74  o obtain a point
93a0: 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73 71  er.** to the [sq
93b0: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65  lite3_file] obje
93c0: 63 74 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  ct associated wi
93d0: 74 68 20 61 20 70 61 72 74 69 63 75 6c 61 72 20  th a particular 
93e0: 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e  database.** conn
93f0: 65 63 74 69 6f 6e 2e 20 20 53 65 65 20 61 6c 73  ection.  See als
9400: 6f 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  o [SQLITE_FCNTL_
9410: 4a 4f 55 52 4e 41 4c 5f 50 4f 49 4e 54 45 52 5d  JOURNAL_POINTER]
9420: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51  ..**.** <li>[[SQ
9430: 4c 49 54 45 5f 46 43 4e 54 4c 5f 4a 4f 55 52 4e  LITE_FCNTL_JOURN
9440: 41 4c 5f 50 4f 49 4e 54 45 52 5d 5d 0a 2a 2a 20  AL_POINTER]].** 
9450: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
9460: 4c 5f 4a 4f 55 52 4e 41 4c 5f 50 4f 49 4e 54 45  L_JOURNAL_POINTE
9470: 52 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65  R] opcode is use
9480: 64 20 74 6f 20 6f 62 74 61 69 6e 20 61 20 70 6f  d to obtain a po
9490: 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20  inter.** to the 
94a0: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f  [sqlite3_file] o
94b0: 62 6a 65 63 74 20 61 73 73 6f 63 69 61 74 65 64  bject associated
94c0: 20 77 69 74 68 20 74 68 65 20 6a 6f 75 72 6e 61   with the journa
94d0: 6c 20 66 69 6c 65 20 28 65 69 74 68 65 72 0a 2a  l file (either.*
94e0: 2a 20 74 68 65 20 5b 72 6f 6c 6c 62 61 63 6b 20  * the [rollback 
94f0: 6a 6f 75 72 6e 61 6c 5d 20 6f 72 20 74 68 65 20  journal] or the 
9500: 5b 77 72 69 74 65 2d 61 68 65 61 64 20 6c 6f 67  [write-ahead log
9510: 5d 29 20 66 6f 72 20 61 20 70 61 72 74 69 63 75  ]) for a particu
9520: 6c 61 72 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  lar database.** 
9530: 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 53 65 65  connection.  See
9540: 20 61 6c 73 6f 20 5b 53 51 4c 49 54 45 5f 46 43   also [SQLITE_FC
9550: 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52  NTL_FILE_POINTER
9560: 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53  ]..**.** <li>[[S
9570: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43  QLITE_FCNTL_SYNC
9580: 5f 4f 4d 49 54 54 45 44 5d 5d 0a 2a 2a 20 4e 6f  _OMITTED]].** No
9590: 20 6c 6f 6e 67 65 72 20 69 6e 20 75 73 65 2e 0a   longer in use..
95a0: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
95b0: 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5d 5d 0a  TE_FCNTL_SYNC]].
95c0: 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  ** The [SQLITE_F
95d0: 43 4e 54 4c 5f 53 59 4e 43 5d 20 6f 70 63 6f 64  CNTL_SYNC] opcod
95e0: 65 20 69 73 20 67 65 6e 65 72 61 74 65 64 20 69  e is generated i
95f0: 6e 74 65 72 6e 61 6c 6c 79 20 62 79 20 53 51 4c  nternally by SQL
9600: 69 74 65 20 61 6e 64 0a 2a 2a 20 73 65 6e 74 20  ite and.** sent 
9610: 74 6f 20 74 68 65 20 56 46 53 20 69 6d 6d 65 64  to the VFS immed
9620: 69 61 74 65 6c 79 20 62 65 66 6f 72 65 20 74 68  iately before th
9630: 65 20 78 53 79 6e 63 20 6d 65 74 68 6f 64 20 69  e xSync method i
9640: 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 20 61 0a 2a  s invoked on a.*
9650: 2a 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  * database file 
9660: 64 65 73 63 72 69 70 74 6f 72 2e 20 4f 72 2c 20  descriptor. Or, 
9670: 69 66 20 74 68 65 20 78 53 79 6e 63 20 6d 65 74  if the xSync met
9680: 68 6f 64 20 69 73 20 6e 6f 74 20 69 6e 76 6f 6b  hod is not invok
9690: 65 64 20 0a 2a 2a 20 62 65 63 61 75 73 65 20 74  ed .** because t
96a0: 68 65 20 75 73 65 72 20 68 61 73 20 63 6f 6e 66  he user has conf
96b0: 69 67 75 72 65 64 20 53 51 4c 69 74 65 20 77 69  igured SQLite wi
96c0: 74 68 20 0a 2a 2a 20 5b 50 52 41 47 4d 41 20 73  th .** [PRAGMA s
96d0: 79 6e 63 68 72 6f 6e 6f 75 73 20 7c 20 50 52 41  ynchronous | PRA
96e0: 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 3d  GMA synchronous=
96f0: 4f 46 46 5d 20 69 74 20 69 73 20 69 6e 76 6f 6b  OFF] it is invok
9700: 65 64 20 69 6e 20 70 6c 61 63 65 20 0a 2a 2a 20  ed in place .** 
9710: 6f 66 20 74 68 65 20 78 53 79 6e 63 20 6d 65 74  of the xSync met
9720: 68 6f 64 2e 20 49 6e 20 6d 6f 73 74 20 63 61 73  hod. In most cas
9730: 65 73 2c 20 74 68 65 20 70 6f 69 6e 74 65 72 20  es, the pointer 
9740: 61 72 67 75 6d 65 6e 74 20 70 61 73 73 65 64 20  argument passed 
9750: 77 69 74 68 0a 2a 2a 20 74 68 69 73 20 66 69 6c  with.** this fil
9760: 65 2d 63 6f 6e 74 72 6f 6c 20 69 73 20 4e 55 4c  e-control is NUL
9770: 4c 2e 20 48 6f 77 65 76 65 72 2c 20 69 66 20 74  L. However, if t
9780: 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
9790: 20 69 73 20 62 65 69 6e 67 20 73 79 6e 63 65 64   is being synced
97a0: 0a 2a 2a 20 61 73 20 70 61 72 74 20 6f 66 20 61  .** as part of a
97b0: 20 6d 75 6c 74 69 2d 64 61 74 61 62 61 73 65 20   multi-database 
97c0: 63 6f 6d 6d 69 74 2c 20 74 68 65 20 61 72 67 75  commit, the argu
97d0: 6d 65 6e 74 20 70 6f 69 6e 74 73 20 74 6f 20 61  ment points to a
97e0: 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 65 64 0a   nul-terminated.
97f0: 2a 2a 20 73 74 72 69 6e 67 20 63 6f 6e 74 61 69  ** string contai
9800: 6e 69 6e 67 20 74 68 65 20 74 72 61 6e 73 61 63  ning the transac
9810: 74 69 6f 6e 73 20 6d 61 73 74 65 72 2d 6a 6f 75  tions master-jou
9820: 72 6e 61 6c 20 66 69 6c 65 20 6e 61 6d 65 2e 20  rnal file name. 
9830: 56 46 53 65 73 20 74 68 61 74 20 0a 2a 2a 20 64  VFSes that .** d
9840: 6f 20 6e 6f 74 20 6e 65 65 64 20 74 68 69 73 20  o not need this 
9850: 73 69 67 6e 61 6c 20 73 68 6f 75 6c 64 20 73 69  signal should si
9860: 6c 65 6e 74 6c 79 20 69 67 6e 6f 72 65 20 74 68  lently ignore th
9870: 69 73 20 6f 70 63 6f 64 65 2e 20 41 70 70 6c 69  is opcode. Appli
9880: 63 61 74 69 6f 6e 73 20 0a 2a 2a 20 73 68 6f 75  cations .** shou
9890: 6c 64 20 6e 6f 74 20 63 61 6c 6c 20 5b 73 71 6c  ld not call [sql
98a0: 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f  ite3_file_contro
98b0: 6c 28 29 5d 20 77 69 74 68 20 74 68 69 73 20 6f  l()] with this o
98c0: 70 63 6f 64 65 20 61 73 20 64 6f 69 6e 67 20 73  pcode as doing s
98d0: 6f 20 6d 61 79 20 0a 2a 2a 20 64 69 73 72 75 70  o may .** disrup
98e0: 74 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 20  t the operation 
98f0: 6f 66 20 74 68 65 20 73 70 65 63 69 61 6c 69 7a  of the specializ
9900: 65 64 20 56 46 53 65 73 20 74 68 61 74 20 64 6f  ed VFSes that do
9910: 20 72 65 71 75 69 72 65 20 69 74 2e 20 20 0a 2a   require it.  .*
9920: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
9930: 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 50  E_FCNTL_COMMIT_P
9940: 48 41 53 45 54 57 4f 5d 5d 0a 2a 2a 20 54 68 65  HASETWO]].** The
9950: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43   [SQLITE_FCNTL_C
9960: 4f 4d 4d 49 54 5f 50 48 41 53 45 54 57 4f 5d 20  OMMIT_PHASETWO] 
9970: 6f 70 63 6f 64 65 20 69 73 20 67 65 6e 65 72 61  opcode is genera
9980: 74 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 62  ted internally b
9990: 79 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20  y SQLite.** and 
99a0: 73 65 6e 74 20 74 6f 20 74 68 65 20 56 46 53 20  sent to the VFS 
99b0: 61 66 74 65 72 20 61 20 74 72 61 6e 73 61 63 74  after a transact
99c0: 69 6f 6e 20 68 61 73 20 62 65 65 6e 20 63 6f 6d  ion has been com
99d0: 6d 69 74 74 65 64 20 69 6d 6d 65 64 69 61 74 65  mitted immediate
99e0: 6c 79 0a 2a 2a 20 62 75 74 20 62 65 66 6f 72 65  ly.** but before
99f0: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73   the database is
9a00: 20 75 6e 6c 6f 63 6b 65 64 2e 20 56 46 53 65 73   unlocked. VFSes
9a10: 20 74 68 61 74 20 64 6f 20 6e 6f 74 20 6e 65 65   that do not nee
9a20: 64 20 74 68 69 73 20 73 69 67 6e 61 6c 0a 2a 2a  d this signal.**
9a30: 20 73 68 6f 75 6c 64 20 73 69 6c 65 6e 74 6c 79   should silently
9a40: 20 69 67 6e 6f 72 65 20 74 68 69 73 20 6f 70 63   ignore this opc
9a50: 6f 64 65 2e 20 41 70 70 6c 69 63 61 74 69 6f 6e  ode. Application
9a60: 73 20 73 68 6f 75 6c 64 20 6e 6f 74 20 63 61 6c  s should not cal
9a70: 6c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69  l.** [sqlite3_fi
9a80: 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 77 69  le_control()] wi
9a90: 74 68 20 74 68 69 73 20 6f 70 63 6f 64 65 20 61  th this opcode a
9aa0: 73 20 64 6f 69 6e 67 20 73 6f 20 6d 61 79 20 64  s doing so may d
9ab0: 69 73 72 75 70 74 20 74 68 65 20 0a 2a 2a 20 6f  isrupt the .** o
9ac0: 70 65 72 61 74 69 6f 6e 20 6f 66 20 74 68 65 20  peration of the 
9ad0: 73 70 65 63 69 61 6c 69 7a 65 64 20 56 46 53 65  specialized VFSe
9ae0: 73 20 74 68 61 74 20 64 6f 20 72 65 71 75 69 72  s that do requir
9af0: 65 20 69 74 2e 20 20 0a 2a 2a 0a 2a 2a 20 3c 6c  e it.  .**.** <l
9b00: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
9b10: 5f 57 49 4e 33 32 5f 41 56 5f 52 45 54 52 59 5d  _WIN32_AV_RETRY]
9b20: 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54  ].** ^The [SQLIT
9b30: 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 41 56  E_FCNTL_WIN32_AV
9b40: 5f 52 45 54 52 59 5d 20 6f 70 63 6f 64 65 20 69  _RETRY] opcode i
9b50: 73 20 75 73 65 64 20 74 6f 20 63 6f 6e 66 69 67  s used to config
9b60: 75 72 65 20 61 75 74 6f 6d 61 74 69 63 0a 2a 2a  ure automatic.**
9b70: 20 72 65 74 72 79 20 63 6f 75 6e 74 73 20 61 6e   retry counts an
9b80: 64 20 69 6e 74 65 72 76 61 6c 73 20 66 6f 72 20  d intervals for 
9b90: 63 65 72 74 61 69 6e 20 64 69 73 6b 20 49 2f 4f  certain disk I/O
9ba0: 20 6f 70 65 72 61 74 69 6f 6e 73 20 66 6f 72 20   operations for 
9bb0: 74 68 65 0a 2a 2a 20 77 69 6e 64 6f 77 73 20 5b  the.** windows [
9bc0: 56 46 53 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f  VFS] in order to
9bd0: 20 70 72 6f 76 69 64 65 20 72 6f 62 75 73 74 6e   provide robustn
9be0: 65 73 73 20 69 6e 20 74 68 65 20 70 72 65 73 65  ess in the prese
9bf0: 6e 63 65 20 6f 66 0a 2a 2a 20 61 6e 74 69 2d 76  nce of.** anti-v
9c00: 69 72 75 73 20 70 72 6f 67 72 61 6d 73 2e 20 20  irus programs.  
9c10: 42 79 20 64 65 66 61 75 6c 74 2c 20 74 68 65 20  By default, the 
9c20: 77 69 6e 64 6f 77 73 20 56 46 53 20 77 69 6c 6c  windows VFS will
9c30: 20 72 65 74 72 79 20 66 69 6c 65 20 72 65 61 64   retry file read
9c40: 2c 0a 2a 2a 20 66 69 6c 65 20 77 72 69 74 65 2c  ,.** file write,
9c50: 20 61 6e 64 20 66 69 6c 65 20 64 65 6c 65 74 65   and file delete
9c60: 20 6f 70 65 72 61 74 69 6f 6e 73 20 75 70 20 74   operations up t
9c70: 6f 20 31 30 20 74 69 6d 65 73 2c 20 77 69 74 68  o 10 times, with
9c80: 20 61 20 64 65 6c 61 79 0a 2a 2a 20 6f 66 20 32   a delay.** of 2
9c90: 35 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 62  5 milliseconds b
9ca0: 65 66 6f 72 65 20 74 68 65 20 66 69 72 73 74 20  efore the first 
9cb0: 72 65 74 72 79 20 61 6e 64 20 77 69 74 68 20 74  retry and with t
9cc0: 68 65 20 64 65 6c 61 79 20 69 6e 63 72 65 61 73  he delay increas
9cd0: 69 6e 67 0a 2a 2a 20 62 79 20 61 6e 20 61 64 64  ing.** by an add
9ce0: 69 74 69 6f 6e 61 6c 20 32 35 20 6d 69 6c 6c 69  itional 25 milli
9cf0: 73 65 63 6f 6e 64 73 20 77 69 74 68 20 65 61 63  seconds with eac
9d00: 68 20 73 75 62 73 65 71 75 65 6e 74 20 72 65 74  h subsequent ret
9d10: 72 79 2e 20 20 54 68 69 73 0a 2a 2a 20 6f 70 63  ry.  This.** opc
9d20: 6f 64 65 20 61 6c 6c 6f 77 73 20 74 68 65 73 65  ode allows these
9d30: 20 74 77 6f 20 76 61 6c 75 65 73 20 28 31 30 20   two values (10 
9d40: 72 65 74 72 69 65 73 20 61 6e 64 20 32 35 20 6d  retries and 25 m
9d50: 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 64  illiseconds of d
9d60: 65 6c 61 79 29 0a 2a 2a 20 74 6f 20 62 65 20 61  elay).** to be a
9d70: 64 6a 75 73 74 65 64 2e 20 20 54 68 65 20 76 61  djusted.  The va
9d80: 6c 75 65 73 20 61 72 65 20 63 68 61 6e 67 65 64  lues are changed
9d90: 20 66 6f 72 20 61 6c 6c 20 64 61 74 61 62 61 73   for all databas
9da0: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a  e connections.**
9db0: 20 77 69 74 68 69 6e 20 74 68 65 20 73 61 6d 65   within the same
9dc0: 20 70 72 6f 63 65 73 73 2e 20 20 54 68 65 20 61   process.  The a
9dd0: 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69  rgument is a poi
9de0: 6e 74 65 72 20 74 6f 20 61 6e 20 61 72 72 61 79  nter to an array
9df0: 20 6f 66 20 74 77 6f 0a 2a 2a 20 69 6e 74 65 67   of two.** integ
9e00: 65 72 73 20 77 68 65 72 65 20 74 68 65 20 66 69  ers where the fi
9e10: 72 73 74 20 69 6e 74 65 67 65 72 20 69 20 74 68  rst integer i th
9e20: 65 20 6e 65 77 20 72 65 74 72 79 20 63 6f 75 6e  e new retry coun
9e30: 74 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64  t and the second
9e40: 0a 2a 2a 20 69 6e 74 65 67 65 72 20 69 73 20 74  .** integer is t
9e50: 68 65 20 64 65 6c 61 79 2e 20 20 49 66 20 65 69  he delay.  If ei
9e60: 74 68 65 72 20 69 6e 74 65 67 65 72 20 69 73 20  ther integer is 
9e70: 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 74  negative, then t
9e80: 68 65 20 73 65 74 74 69 6e 67 0a 2a 2a 20 69 73  he setting.** is
9e90: 20 6e 6f 74 20 63 68 61 6e 67 65 64 20 62 75 74   not changed but
9ea0: 20 69 6e 73 74 65 61 64 20 74 68 65 20 70 72 69   instead the pri
9eb0: 6f 72 20 76 61 6c 75 65 20 6f 66 20 74 68 61 74  or value of that
9ec0: 20 73 65 74 74 69 6e 67 20 69 73 20 77 72 69 74   setting is writ
9ed0: 74 65 6e 0a 2a 2a 20 69 6e 74 6f 20 74 68 65 20  ten.** into the 
9ee0: 61 72 72 61 79 20 65 6e 74 72 79 2c 20 61 6c 6c  array entry, all
9ef0: 6f 77 69 6e 67 20 74 68 65 20 63 75 72 72 65 6e  owing the curren
9f00: 74 20 72 65 74 72 79 20 73 65 74 74 69 6e 67 73  t retry settings
9f10: 20 74 6f 20 62 65 0a 2a 2a 20 69 6e 74 65 72 72   to be.** interr
9f20: 6f 67 61 74 65 64 2e 20 20 54 68 65 20 7a 44 62  ogated.  The zDb
9f30: 4e 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20 69  Name parameter i
9f40: 73 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a  s ignored..**.**
9f50: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
9f60: 4e 54 4c 5f 50 45 52 53 49 53 54 5f 57 41 4c 5d  NTL_PERSIST_WAL]
9f70: 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54  ].** ^The [SQLIT
9f80: 45 5f 46 43 4e 54 4c 5f 50 45 52 53 49 53 54 5f  E_FCNTL_PERSIST_
9f90: 57 41 4c 5d 20 6f 70 63 6f 64 65 20 69 73 20 75  WAL] opcode is u
9fa0: 73 65 64 20 74 6f 20 73 65 74 20 6f 72 20 71 75  sed to set or qu
9fb0: 65 72 79 20 74 68 65 0a 2a 2a 20 70 65 72 73 69  ery the.** persi
9fc0: 73 74 65 6e 74 20 5b 57 41 4c 20 7c 20 57 72 69  stent [WAL | Wri
9fd0: 74 65 20 41 68 65 61 64 20 4c 6f 67 5d 20 73 65  te Ahead Log] se
9fe0: 74 74 69 6e 67 2e 20 20 42 79 20 64 65 66 61 75  tting.  By defau
9ff0: 6c 74 2c 20 74 68 65 20 61 75 78 69 6c 69 61 72  lt, the auxiliar
a000: 79 0a 2a 2a 20 77 72 69 74 65 20 61 68 65 61 64  y.** write ahead
a010: 20 6c 6f 67 20 61 6e 64 20 73 68 61 72 65 64 20   log and shared 
a020: 6d 65 6d 6f 72 79 20 66 69 6c 65 73 20 75 73 65  memory files use
a030: 64 20 66 6f 72 20 74 72 61 6e 73 61 63 74 69 6f  d for transactio
a040: 6e 20 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 61 72 65  n control.** are
a050: 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 64   automatically d
a060: 65 6c 65 74 65 64 20 77 68 65 6e 20 74 68 65 20  eleted when the 
a070: 6c 61 74 65 73 74 20 63 6f 6e 6e 65 63 74 69 6f  latest connectio
a080: 6e 20 74 6f 20 74 68 65 20 64 61 74 61 62 61 73  n to the databas
a090: 65 0a 2a 2a 20 63 6c 6f 73 65 73 2e 20 20 53 65  e.** closes.  Se
a0a0: 74 74 69 6e 67 20 70 65 72 73 69 73 74 65 6e 74  tting persistent
a0b0: 20 57 41 4c 20 6d 6f 64 65 20 63 61 75 73 65 73   WAL mode causes
a0c0: 20 74 68 6f 73 65 20 66 69 6c 65 73 20 74 6f 20   those files to 
a0d0: 70 65 72 73 69 73 74 20 61 66 74 65 72 0a 2a 2a  persist after.**
a0e0: 20 63 6c 6f 73 65 2e 20 20 50 65 72 73 69 73 74   close.  Persist
a0f0: 69 6e 67 20 74 68 65 20 66 69 6c 65 73 20 69 73  ing the files is
a100: 20 75 73 65 66 75 6c 20 77 68 65 6e 20 6f 74 68   useful when oth
a110: 65 72 20 70 72 6f 63 65 73 73 65 73 20 74 68 61  er processes tha
a120: 74 20 64 6f 20 6e 6f 74 0a 2a 2a 20 68 61 76 65  t do not.** have
a130: 20 77 72 69 74 65 20 70 65 72 6d 69 73 73 69 6f   write permissio
a140: 6e 20 6f 6e 20 74 68 65 20 64 69 72 65 63 74 6f  n on the directo
a150: 72 79 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68  ry containing th
a160: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
a170: 77 61 6e 74 0a 2a 2a 20 74 6f 20 72 65 61 64 20  want.** to read 
a180: 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
a190: 65 2c 20 61 73 20 74 68 65 20 57 41 4c 20 61 6e  e, as the WAL an
a1a0: 64 20 73 68 61 72 65 64 20 6d 65 6d 6f 72 79 20  d shared memory 
a1b0: 66 69 6c 65 73 20 6d 75 73 74 20 65 78 69 73 74  files must exist
a1c0: 0a 2a 2a 20 69 6e 20 6f 72 64 65 72 20 66 6f 72  .** in order for
a1d0: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 74 6f   the database to
a1e0: 20 62 65 20 72 65 61 64 61 62 6c 65 2e 20 20 54   be readable.  T
a1f0: 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
a200: 74 65 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  ter to.** [sqlit
a210: 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28  e3_file_control(
a220: 29 5d 20 66 6f 72 20 74 68 69 73 20 6f 70 63 6f  )] for this opco
a230: 64 65 20 73 68 6f 75 6c 64 20 62 65 20 61 20 70  de should be a p
a240: 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74  ointer to an int
a250: 65 67 65 72 2e 0a 2a 2a 20 54 68 61 74 20 69 6e  eger..** That in
a260: 74 65 67 65 72 20 69 73 20 30 20 74 6f 20 64 69  teger is 0 to di
a270: 73 61 62 6c 65 20 70 65 72 73 69 73 74 65 6e 74  sable persistent
a280: 20 57 41 4c 20 6d 6f 64 65 20 6f 72 20 31 20 74   WAL mode or 1 t
a290: 6f 20 65 6e 61 62 6c 65 20 70 65 72 73 69 73 74  o enable persist
a2a0: 65 6e 74 0a 2a 2a 20 57 41 4c 20 6d 6f 64 65 2e  ent.** WAL mode.
a2b0: 20 20 49 66 20 74 68 65 20 69 6e 74 65 67 65 72    If the integer
a2c0: 20 69 73 20 2d 31 2c 20 74 68 65 6e 20 69 74 20   is -1, then it 
a2d0: 69 73 20 6f 76 65 72 77 72 69 74 74 65 6e 20 77  is overwritten w
a2e0: 69 74 68 20 74 68 65 20 63 75 72 72 65 6e 74 0a  ith the current.
a2f0: 2a 2a 20 57 41 4c 20 70 65 72 73 69 73 74 65 6e  ** WAL persisten
a300: 63 65 20 73 65 74 74 69 6e 67 2e 0a 2a 2a 0a 2a  ce setting..**.*
a310: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
a320: 43 4e 54 4c 5f 50 4f 57 45 52 53 41 46 45 5f 4f  CNTL_POWERSAFE_O
a330: 56 45 52 57 52 49 54 45 5d 5d 0a 2a 2a 20 5e 54  VERWRITE]].** ^T
a340: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
a350: 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57  _POWERSAFE_OVERW
a360: 52 49 54 45 5d 20 6f 70 63 6f 64 65 20 69 73 20  RITE] opcode is 
a370: 75 73 65 64 20 74 6f 20 73 65 74 20 6f 72 20 71  used to set or q
a380: 75 65 72 79 20 74 68 65 0a 2a 2a 20 70 65 72 73  uery the.** pers
a390: 69 73 74 65 6e 74 20 22 70 6f 77 65 72 73 61 66  istent "powersaf
a3a0: 65 2d 6f 76 65 72 77 72 69 74 65 22 20 6f 72 20  e-overwrite" or 
a3b0: 22 50 53 4f 57 22 20 73 65 74 74 69 6e 67 2e 20  "PSOW" setting. 
a3c0: 20 54 68 65 20 50 53 4f 57 20 73 65 74 74 69 6e   The PSOW settin
a3d0: 67 0a 2a 2a 20 64 65 74 65 72 6d 69 6e 65 73 20  g.** determines 
a3e0: 74 68 65 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41  the [SQLITE_IOCA
a3f0: 50 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52  P_POWERSAFE_OVER
a400: 57 52 49 54 45 5d 20 62 69 74 20 6f 66 20 74 68  WRITE] bit of th
a410: 65 0a 2a 2a 20 78 44 65 76 69 63 65 43 68 61 72  e.** xDeviceChar
a420: 61 63 74 65 72 69 73 74 69 63 73 20 6d 65 74 68  acteristics meth
a430: 6f 64 73 2e 20 54 68 65 20 66 6f 75 72 74 68 20  ods. The fourth 
a440: 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20  parameter to.** 
a450: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f  [sqlite3_file_co
a460: 6e 74 72 6f 6c 28 29 5d 20 66 6f 72 20 74 68 69  ntrol()] for thi
a470: 73 20 6f 70 63 6f 64 65 20 73 68 6f 75 6c 64 20  s opcode should 
a480: 62 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  be a pointer to 
a490: 61 6e 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 20 54  an integer..** T
a4a0: 68 61 74 20 69 6e 74 65 67 65 72 20 69 73 20 30  hat integer is 0
a4b0: 20 74 6f 20 64 69 73 61 62 6c 65 20 7a 65 72 6f   to disable zero
a4c0: 2d 64 61 6d 61 67 65 20 6d 6f 64 65 20 6f 72 20  -damage mode or 
a4d0: 31 20 74 6f 20 65 6e 61 62 6c 65 20 7a 65 72 6f  1 to enable zero
a4e0: 2d 64 61 6d 61 67 65 0a 2a 2a 20 6d 6f 64 65 2e  -damage.** mode.
a4f0: 20 20 49 66 20 74 68 65 20 69 6e 74 65 67 65 72    If the integer
a500: 20 69 73 20 2d 31 2c 20 74 68 65 6e 20 69 74 20   is -1, then it 
a510: 69 73 20 6f 76 65 72 77 72 69 74 74 65 6e 20 77  is overwritten w
a520: 69 74 68 20 74 68 65 20 63 75 72 72 65 6e 74 0a  ith the current.
a530: 2a 2a 20 7a 65 72 6f 2d 64 61 6d 61 67 65 20 6d  ** zero-damage m
a540: 6f 64 65 20 73 65 74 74 69 6e 67 2e 0a 2a 2a 0a  ode setting..**.
a550: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
a560: 46 43 4e 54 4c 5f 4f 56 45 52 57 52 49 54 45 5d  FCNTL_OVERWRITE]
a570: 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54  ].** ^The [SQLIT
a580: 45 5f 46 43 4e 54 4c 5f 4f 56 45 52 57 52 49 54  E_FCNTL_OVERWRIT
a590: 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 69 6e 76  E] opcode is inv
a5a0: 6f 6b 65 64 20 62 79 20 53 51 4c 69 74 65 20 61  oked by SQLite a
a5b0: 66 74 65 72 20 6f 70 65 6e 69 6e 67 0a 2a 2a 20  fter opening.** 
a5c0: 61 20 77 72 69 74 65 20 74 72 61 6e 73 61 63 74  a write transact
a5d0: 69 6f 6e 20 74 6f 20 69 6e 64 69 63 61 74 65 20  ion to indicate 
a5e0: 74 68 61 74 2c 20 75 6e 6c 65 73 73 20 69 74 20  that, unless it 
a5f0: 69 73 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 66  is rolled back f
a600: 6f 72 20 73 6f 6d 65 0a 2a 2a 20 72 65 61 73 6f  or some.** reaso
a610: 6e 2c 20 74 68 65 20 65 6e 74 69 72 65 20 64 61  n, the entire da
a620: 74 61 62 61 73 65 20 66 69 6c 65 20 77 69 6c 6c  tabase file will
a630: 20 62 65 20 6f 76 65 72 77 72 69 74 74 65 6e 20   be overwritten 
a640: 62 79 20 74 68 65 20 63 75 72 72 65 6e 74 20 0a  by the current .
a650: 2a 2a 20 74 72 61 6e 73 61 63 74 69 6f 6e 2e 20  ** transaction. 
a660: 54 68 69 73 20 69 73 20 75 73 65 64 20 62 79 20  This is used by 
a670: 56 41 43 55 55 4d 20 6f 70 65 72 61 74 69 6f 6e  VACUUM operation
a680: 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53  s..**.** <li>[[S
a690: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 4e  QLITE_FCNTL_VFSN
a6a0: 41 4d 45 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53  AME]].** ^The [S
a6b0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 4e  QLITE_FCNTL_VFSN
a6c0: 41 4d 45 5d 20 6f 70 63 6f 64 65 20 63 61 6e 20  AME] opcode can 
a6d0: 62 65 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69  be used to obtai
a6e0: 6e 20 74 68 65 20 6e 61 6d 65 73 20 6f 66 0a 2a  n the names of.*
a6f0: 2a 20 61 6c 6c 20 5b 56 46 53 65 73 5d 20 69 6e  * all [VFSes] in
a700: 20 74 68 65 20 56 46 53 20 73 74 61 63 6b 2e 20   the VFS stack. 
a710: 20 54 68 65 20 6e 61 6d 65 73 20 61 72 65 20 6f   The names are o
a720: 66 20 61 6c 6c 20 56 46 53 20 73 68 69 6d 73 20  f all VFS shims 
a730: 61 6e 64 20 74 68 65 0a 2a 2a 20 66 69 6e 61 6c  and the.** final
a740: 20 62 6f 74 74 6f 6d 2d 6c 65 76 65 6c 20 56 46   bottom-level VF
a750: 53 20 61 72 65 20 77 72 69 74 74 65 6e 20 69 6e  S are written in
a760: 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e  to memory obtain
a770: 65 64 20 66 72 6f 6d 20 0a 2a 2a 20 5b 73 71 6c  ed from .** [sql
a780: 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 61  ite3_malloc()] a
a790: 6e 64 20 74 68 65 20 72 65 73 75 6c 74 20 69 73  nd the result is
a7a0: 20 73 74 6f 72 65 64 20 69 6e 20 74 68 65 20 63   stored in the c
a7b0: 68 61 72 2a 20 76 61 72 69 61 62 6c 65 0a 2a 2a  har* variable.**
a7c0: 20 74 68 61 74 20 74 68 65 20 66 6f 75 72 74 68   that the fourth
a7d0: 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 5b 73   parameter of [s
a7e0: 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74  qlite3_file_cont
a7f0: 72 6f 6c 28 29 5d 20 70 6f 69 6e 74 73 20 74 6f  rol()] points to
a800: 2e 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 65 72 20  ..** The caller 
a810: 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66  is responsible f
a820: 6f 72 20 66 72 65 65 69 6e 67 20 74 68 65 20 6d  or freeing the m
a830: 65 6d 6f 72 79 20 77 68 65 6e 20 64 6f 6e 65 2e  emory when done.
a840: 20 20 41 73 20 77 69 74 68 0a 2a 2a 20 61 6c 6c    As with.** all
a850: 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 61 63   file-control ac
a860: 74 69 6f 6e 73 2c 20 74 68 65 72 65 20 69 73 20  tions, there is 
a870: 6e 6f 20 67 75 61 72 61 6e 74 65 65 20 74 68 61  no guarantee tha
a880: 74 20 74 68 69 73 20 77 69 6c 6c 20 61 63 74 75  t this will actu
a890: 61 6c 6c 79 0a 2a 2a 20 64 6f 20 61 6e 79 74 68  ally.** do anyth
a8a0: 69 6e 67 2e 20 20 43 61 6c 6c 65 72 73 20 73 68  ing.  Callers sh
a8b0: 6f 75 6c 64 20 69 6e 69 74 69 61 6c 69 7a 65 20  ould initialize 
a8c0: 74 68 65 20 63 68 61 72 2a 20 76 61 72 69 61 62  the char* variab
a8d0: 6c 65 20 74 6f 20 61 20 4e 55 4c 4c 0a 2a 2a 20  le to a NULL.** 
a8e0: 70 6f 69 6e 74 65 72 20 69 6e 20 63 61 73 65 20  pointer in case 
a8f0: 74 68 69 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f  this file-contro
a900: 6c 20 69 73 20 6e 6f 74 20 69 6d 70 6c 65 6d 65  l is not impleme
a910: 6e 74 65 64 2e 20 20 54 68 69 73 20 66 69 6c 65  nted.  This file
a920: 2d 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 69 73 20 69  -control.** is i
a930: 6e 74 65 6e 64 65 64 20 66 6f 72 20 64 69 61 67  ntended for diag
a940: 6e 6f 73 74 69 63 20 75 73 65 20 6f 6e 6c 79 2e  nostic use only.
a950: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
a960: 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 5f 50 4f  ITE_FCNTL_VFS_PO
a970: 49 4e 54 45 52 5d 5d 0a 2a 2a 20 5e 54 68 65 20  INTER]].** ^The 
a980: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46  [SQLITE_FCNTL_VF
a990: 53 5f 50 4f 49 4e 54 45 52 5d 20 6f 70 63 6f 64  S_POINTER] opcod
a9a0: 65 20 66 69 6e 64 73 20 61 20 70 6f 69 6e 74 65  e finds a pointe
a9b0: 72 20 74 6f 20 74 68 65 20 74 6f 70 2d 6c 65 76  r to the top-lev
a9c0: 65 6c 0a 2a 2a 20 5b 56 46 53 65 73 5d 20 63 75  el.** [VFSes] cu
a9d0: 72 72 65 6e 74 6c 79 20 69 6e 20 75 73 65 2e 20  rrently in use. 
a9e0: 20 5e 28 54 68 65 20 61 72 67 75 6d 65 6e 74 20   ^(The argument 
a9f0: 58 20 69 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  X in.** sqlite3_
aa00: 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 64 62 2c  file_control(db,
aa10: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53  SQLITE_FCNTL_VFS
aa20: 5f 50 4f 49 4e 54 45 52 2c 58 29 20 6d 75 73 74  _POINTER,X) must
aa30: 20 62 65 0a 2a 2a 20 6f 66 20 74 79 70 65 20 22   be.** of type "
aa40: 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 2a 2a  [sqlite3_vfs] **
aa50: 22 2e 20 20 54 68 69 73 20 6f 70 63 6f 64 65 73  ".  This opcodes
aa60: 20 77 69 6c 6c 20 73 65 74 20 2a 58 0a 2a 2a 20   will set *X.** 
aa70: 74 6f 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  to a pointer to 
aa80: 74 68 65 20 74 6f 70 2d 6c 65 76 65 6c 20 56 46  the top-level VF
aa90: 53 2e 29 5e 0a 2a 2a 20 5e 57 68 65 6e 20 74 68  S.)^.** ^When th
aaa0: 65 72 65 20 61 72 65 20 6d 75 6c 74 69 70 6c 65  ere are multiple
aab0: 20 56 46 53 20 73 68 69 6d 73 20 69 6e 20 74 68   VFS shims in th
aac0: 65 20 73 74 61 63 6b 2c 20 74 68 69 73 20 6f 70  e stack, this op
aad0: 63 6f 64 65 20 66 69 6e 64 73 20 74 68 65 0a 2a  code finds the.*
aae0: 2a 20 75 70 70 65 72 2d 6d 6f 73 74 20 73 68 69  * upper-most shi
aaf0: 6d 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  m only..**.** <l
ab00: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
ab10: 5f 50 52 41 47 4d 41 5d 5d 0a 2a 2a 20 5e 57 68  _PRAGMA]].** ^Wh
ab20: 65 6e 65 76 65 72 20 61 20 5b 50 52 41 47 4d 41  enever a [PRAGMA
ab30: 5d 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 70  ] statement is p
ab40: 61 72 73 65 64 2c 20 61 6e 20 5b 53 51 4c 49 54  arsed, an [SQLIT
ab50: 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20  E_FCNTL_PRAGMA] 
ab60: 0a 2a 2a 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c  .** file control
ab70: 20 69 73 20 73 65 6e 74 20 74 6f 20 74 68 65 20   is sent to the 
ab80: 6f 70 65 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69  open [sqlite3_fi
ab90: 6c 65 5d 20 6f 62 6a 65 63 74 20 63 6f 72 72 65  le] object corre
aba0: 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20 74 6f 20 74  sponding.** to t
abb0: 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
abc0: 20 74 6f 20 77 68 69 63 68 20 74 68 65 20 70 72   to which the pr
abd0: 61 67 6d 61 20 73 74 61 74 65 6d 65 6e 74 20 72  agma statement r
abe0: 65 66 65 72 73 2e 20 5e 54 68 65 20 61 72 67 75  efers. ^The argu
abf0: 6d 65 6e 74 0a 2a 2a 20 74 6f 20 74 68 65 20 5b  ment.** to the [
ac00: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41  SQLITE_FCNTL_PRA
ac10: 47 4d 41 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f  GMA] file contro
ac20: 6c 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66  l is an array of
ac30: 0a 2a 2a 20 70 6f 69 6e 74 65 72 73 20 74 6f 20  .** pointers to 
ac40: 73 74 72 69 6e 67 73 20 28 63 68 61 72 2a 2a 29  strings (char**)
ac50: 20 69 6e 20 77 68 69 63 68 20 74 68 65 20 73 65   in which the se
ac60: 63 6f 6e 64 20 65 6c 65 6d 65 6e 74 20 6f 66 20  cond element of 
ac70: 74 68 65 20 61 72 72 61 79 0a 2a 2a 20 69 73 20  the array.** is 
ac80: 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
ac90: 70 72 61 67 6d 61 20 61 6e 64 20 74 68 65 20 74  pragma and the t
aca0: 68 69 72 64 20 65 6c 65 6d 65 6e 74 20 69 73 20  hird element is 
acb0: 74 68 65 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  the argument to 
acc0: 74 68 65 0a 2a 2a 20 70 72 61 67 6d 61 20 6f 72  the.** pragma or
acd0: 20 4e 55 4c 4c 20 69 66 20 74 68 65 20 70 72 61   NULL if the pra
ace0: 67 6d 61 20 68 61 73 20 6e 6f 20 61 72 67 75 6d  gma has no argum
acf0: 65 6e 74 2e 20 20 5e 54 68 65 20 68 61 6e 64 6c  ent.  ^The handl
ad00: 65 72 20 66 6f 72 20 61 6e 0a 2a 2a 20 5b 53 51  er for an.** [SQ
ad10: 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d  LITE_FCNTL_PRAGM
ad20: 41 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20  A] file control 
ad30: 63 61 6e 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 6d  can optionally m
ad40: 61 6b 65 20 74 68 65 20 66 69 72 73 74 20 65 6c  ake the first el
ad50: 65 6d 65 6e 74 0a 2a 2a 20 6f 66 20 74 68 65 20  ement.** of the 
ad60: 63 68 61 72 2a 2a 20 61 72 67 75 6d 65 6e 74 20  char** argument 
ad70: 70 6f 69 6e 74 20 74 6f 20 61 20 73 74 72 69 6e  point to a strin
ad80: 67 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  g obtained from 
ad90: 5b 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66  [sqlite3_mprintf
ada0: 28 29 5d 0a 2a 2a 20 6f 72 20 74 68 65 20 65 71  ()].** or the eq
adb0: 75 69 76 61 6c 65 6e 74 20 61 6e 64 20 74 68 61  uivalent and tha
adc0: 74 20 73 74 72 69 6e 67 20 77 69 6c 6c 20 62 65  t string will be
add0: 63 6f 6d 65 20 74 68 65 20 72 65 73 75 6c 74 20  come the result 
ade0: 6f 66 20 74 68 65 20 70 72 61 67 6d 61 20 6f 72  of the pragma or
adf0: 0a 2a 2a 20 74 68 65 20 65 72 72 6f 72 20 6d 65  .** the error me
ae00: 73 73 61 67 65 20 69 66 20 74 68 65 20 70 72 61  ssage if the pra
ae10: 67 6d 61 20 66 61 69 6c 73 2e 20 5e 49 66 20 74  gma fails. ^If t
ae20: 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43  he.** [SQLITE_FC
ae30: 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65  NTL_PRAGMA] file
ae40: 20 63 6f 6e 74 72 6f 6c 20 72 65 74 75 72 6e 73   control returns
ae50: 20 5b 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e   [SQLITE_NOTFOUN
ae60: 44 5d 2c 20 74 68 65 6e 20 6e 6f 72 6d 61 6c 20  D], then normal 
ae70: 0a 2a 2a 20 5b 50 52 41 47 4d 41 5d 20 70 72 6f  .** [PRAGMA] pro
ae80: 63 65 73 73 69 6e 67 20 63 6f 6e 74 69 6e 75 65  cessing continue
ae90: 73 2e 20 20 5e 49 66 20 74 68 65 20 5b 53 51 4c  s.  ^If the [SQL
aea0: 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41  ITE_FCNTL_PRAGMA
aeb0: 5d 0a 2a 2a 20 66 69 6c 65 20 63 6f 6e 74 72 6f  ].** file contro
aec0: 6c 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54  l returns [SQLIT
aed0: 45 5f 4f 4b 5d 2c 20 74 68 65 6e 20 74 68 65 20  E_OK], then the 
aee0: 70 61 72 73 65 72 20 61 73 73 75 6d 65 73 20 74  parser assumes t
aef0: 68 61 74 20 74 68 65 0a 2a 2a 20 56 46 53 20 68  hat the.** VFS h
af00: 61 73 20 68 61 6e 64 6c 65 64 20 74 68 65 20 50  as handled the P
af10: 52 41 47 4d 41 20 69 74 73 65 6c 66 20 61 6e 64  RAGMA itself and
af20: 20 74 68 65 20 70 61 72 73 65 72 20 67 65 6e 65   the parser gene
af30: 72 61 74 65 73 20 61 20 6e 6f 2d 6f 70 0a 2a 2a  rates a no-op.**
af40: 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
af50: 65 6e 74 20 69 66 20 72 65 73 75 6c 74 20 73 74  ent if result st
af60: 72 69 6e 67 20 69 73 20 4e 55 4c 4c 2c 20 6f 72  ring is NULL, or
af70: 20 74 68 61 74 20 72 65 74 75 72 6e 73 20 61 20   that returns a 
af80: 63 6f 70 79 0a 2a 2a 20 6f 66 20 74 68 65 20 72  copy.** of the r
af90: 65 73 75 6c 74 20 73 74 72 69 6e 67 20 69 66 20  esult string if 
afa0: 74 68 65 20 73 74 72 69 6e 67 20 69 73 20 6e 6f  the string is no
afb0: 6e 2d 4e 55 4c 4c 2e 0a 2a 2a 20 5e 49 66 20 74  n-NULL..** ^If t
afc0: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
afd0: 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65 20 63 6f  _PRAGMA] file co
afe0: 6e 74 72 6f 6c 20 72 65 74 75 72 6e 73 0a 2a 2a  ntrol returns.**
aff0: 20 61 6e 79 20 72 65 73 75 6c 74 20 63 6f 64 65   any result code
b000: 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c   other than [SQL
b010: 49 54 45 5f 4f 4b 5d 20 6f 72 20 5b 53 51 4c 49  ITE_OK] or [SQLI
b020: 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d 2c 20 74 68  TE_NOTFOUND], th
b030: 61 74 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74  at means.** that
b040: 20 74 68 65 20 56 46 53 20 65 6e 63 6f 75 6e 74   the VFS encount
b050: 65 72 65 64 20 61 6e 20 65 72 72 6f 72 20 77 68  ered an error wh
b060: 69 6c 65 20 68 61 6e 64 6c 69 6e 67 20 74 68 65  ile handling the
b070: 20 5b 50 52 41 47 4d 41 5d 20 61 6e 64 20 74 68   [PRAGMA] and th
b080: 65 0a 2a 2a 20 63 6f 6d 70 69 6c 61 74 69 6f 6e  e.** compilation
b090: 20 6f 66 20 74 68 65 20 50 52 41 47 4d 41 20 66   of the PRAGMA f
b0a0: 61 69 6c 73 20 77 69 74 68 20 61 6e 20 65 72 72  ails with an err
b0b0: 6f 72 2e 20 20 5e 54 68 65 20 5b 53 51 4c 49 54  or.  ^The [SQLIT
b0c0: 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 0a  E_FCNTL_PRAGMA].
b0d0: 2a 2a 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20  ** file control 
b0e0: 6f 63 63 75 72 73 20 61 74 20 74 68 65 20 62 65  occurs at the be
b0f0: 67 69 6e 6e 69 6e 67 20 6f 66 20 70 72 61 67 6d  ginning of pragm
b100: 61 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 61 6c  a statement anal
b110: 79 73 69 73 20 61 6e 64 20 73 6f 0a 2a 2a 20 69  ysis and so.** i
b120: 74 20 69 73 20 61 62 6c 65 20 74 6f 20 6f 76 65  t is able to ove
b130: 72 72 69 64 65 20 62 75 69 6c 74 2d 69 6e 20 5b  rride built-in [
b140: 50 52 41 47 4d 41 5d 20 73 74 61 74 65 6d 65 6e  PRAGMA] statemen
b150: 74 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  ts..**.** <li>[[
b160: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 55 53  SQLITE_FCNTL_BUS
b170: 59 48 41 4e 44 4c 45 52 5d 5d 0a 2a 2a 20 5e 54  YHANDLER]].** ^T
b180: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
b190: 5f 42 55 53 59 48 41 4e 44 4c 45 52 5d 0a 2a 2a  _BUSYHANDLER].**
b1a0: 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 6d 61   file-control ma
b1b0: 79 20 62 65 20 69 6e 76 6f 6b 65 64 20 62 79 20  y be invoked by 
b1c0: 53 51 4c 69 74 65 20 6f 6e 20 74 68 65 20 64 61  SQLite on the da
b1d0: 74 61 62 61 73 65 20 66 69 6c 65 20 68 61 6e 64  tabase file hand
b1e0: 6c 65 0a 2a 2a 20 73 68 6f 72 74 6c 79 20 61 66  le.** shortly af
b1f0: 74 65 72 20 69 74 20 69 73 20 6f 70 65 6e 65 64  ter it is opened
b200: 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 70 72 6f   in order to pro
b210: 76 69 64 65 20 61 20 63 75 73 74 6f 6d 20 56 46  vide a custom VF
b220: 53 20 77 69 74 68 20 61 63 63 65 73 73 0a 2a 2a  S with access.**
b230: 20 74 6f 20 74 68 65 20 63 6f 6e 6e 65 63 74 69   to the connecti
b240: 6f 6e 73 20 62 75 73 79 2d 68 61 6e 64 6c 65 72  ons busy-handler
b250: 20 63 61 6c 6c 62 61 63 6b 2e 20 54 68 65 20 61   callback. The a
b260: 72 67 75 6d 65 6e 74 20 69 73 20 6f 66 20 74 79  rgument is of ty
b270: 70 65 20 28 76 6f 69 64 20 2a 2a 29 0a 2a 2a 20  pe (void **).** 
b280: 2d 20 61 6e 20 61 72 72 61 79 20 6f 66 20 74 77  - an array of tw
b290: 6f 20 28 76 6f 69 64 20 2a 29 20 76 61 6c 75 65  o (void *) value
b2a0: 73 2e 20 54 68 65 20 66 69 72 73 74 20 28 76 6f  s. The first (vo
b2b0: 69 64 20 2a 29 20 61 63 74 75 61 6c 6c 79 20 70  id *) actually p
b2c0: 6f 69 6e 74 73 0a 2a 2a 20 74 6f 20 61 20 66 75  oints.** to a fu
b2d0: 6e 63 74 69 6f 6e 20 6f 66 20 74 79 70 65 20 28  nction of type (
b2e0: 69 6e 74 20 28 2a 29 28 76 6f 69 64 20 2a 29 29  int (*)(void *))
b2f0: 2e 20 49 6e 20 6f 72 64 65 72 20 74 6f 20 69 6e  . In order to in
b300: 76 6f 6b 65 20 74 68 65 20 63 6f 6e 6e 65 63 74  voke the connect
b310: 69 6f 6e 73 0a 2a 2a 20 62 75 73 79 2d 68 61 6e  ions.** busy-han
b320: 64 6c 65 72 2c 20 74 68 69 73 20 66 75 6e 63 74  dler, this funct
b330: 69 6f 6e 20 73 68 6f 75 6c 64 20 62 65 20 69 6e  ion should be in
b340: 76 6f 6b 65 64 20 77 69 74 68 20 74 68 65 20 73  voked with the s
b350: 65 63 6f 6e 64 20 28 76 6f 69 64 20 2a 29 20 69  econd (void *) i
b360: 6e 0a 2a 2a 20 74 68 65 20 61 72 72 61 79 20 61  n.** the array a
b370: 73 20 74 68 65 20 6f 6e 6c 79 20 61 72 67 75 6d  s the only argum
b380: 65 6e 74 2e 20 49 66 20 69 74 20 72 65 74 75 72  ent. If it retur
b390: 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65  ns non-zero, the
b3a0: 6e 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 0a  n the operation.
b3b0: 2a 2a 20 73 68 6f 75 6c 64 20 62 65 20 72 65 74  ** should be ret
b3c0: 72 69 65 64 2e 20 49 66 20 69 74 20 72 65 74 75  ried. If it retu
b3d0: 72 6e 73 20 7a 65 72 6f 2c 20 74 68 65 20 63 75  rns zero, the cu
b3e0: 73 74 6f 6d 20 56 46 53 20 73 68 6f 75 6c 64 20  stom VFS should 
b3f0: 61 62 61 6e 64 6f 6e 20 74 68 65 0a 2a 2a 20 63  abandon the.** c
b400: 75 72 72 65 6e 74 20 6f 70 65 72 61 74 69 6f 6e  urrent operation
b410: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51  ..**.** <li>[[SQ
b420: 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 45 4d 50 46  LITE_FCNTL_TEMPF
b430: 49 4c 45 4e 41 4d 45 5d 5d 0a 2a 2a 20 5e 41 70  ILENAME]].** ^Ap
b440: 70 6c 69 63 61 74 69 6f 6e 20 63 61 6e 20 69 6e  plication can in
b450: 76 6f 6b 65 20 74 68 65 20 5b 53 51 4c 49 54 45  voke the [SQLITE
b460: 5f 46 43 4e 54 4c 5f 54 45 4d 50 46 49 4c 45 4e  _FCNTL_TEMPFILEN
b470: 41 4d 45 5d 20 66 69 6c 65 2d 63 6f 6e 74 72 6f  AME] file-contro
b480: 6c 0a 2a 2a 20 74 6f 20 68 61 76 65 20 53 51 4c  l.** to have SQL
b490: 69 74 65 20 67 65 6e 65 72 61 74 65 20 61 0a 2a  ite generate a.*
b4a0: 2a 20 74 65 6d 70 6f 72 61 72 79 20 66 69 6c 65  * temporary file
b4b0: 6e 61 6d 65 20 75 73 69 6e 67 20 74 68 65 20 73  name using the s
b4c0: 61 6d 65 20 61 6c 67 6f 72 69 74 68 6d 20 74 68  ame algorithm th
b4d0: 61 74 20 69 73 20 66 6f 6c 6c 6f 77 65 64 20 74  at is followed t
b4e0: 6f 20 67 65 6e 65 72 61 74 65 0a 2a 2a 20 74 65  o generate.** te
b4f0: 6d 70 6f 72 61 72 79 20 66 69 6c 65 6e 61 6d 65  mporary filename
b500: 73 20 66 6f 72 20 54 45 4d 50 20 74 61 62 6c 65  s for TEMP table
b510: 73 20 61 6e 64 20 6f 74 68 65 72 20 69 6e 74 65  s and other inte
b520: 72 6e 61 6c 20 75 73 65 73 2e 20 20 54 68 65 0a  rnal uses.  The.
b530: 2a 2a 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75  ** argument shou
b540: 6c 64 20 62 65 20 61 20 63 68 61 72 2a 2a 20 77  ld be a char** w
b550: 68 69 63 68 20 77 69 6c 6c 20 62 65 20 66 69 6c  hich will be fil
b560: 6c 65 64 20 77 69 74 68 20 74 68 65 20 66 69 6c  led with the fil
b570: 65 6e 61 6d 65 0a 2a 2a 20 77 72 69 74 74 65 6e  ename.** written
b580: 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74   into memory obt
b590: 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69  ained from [sqli
b5a0: 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20 20  te3_malloc()].  
b5b0: 54 68 65 20 63 61 6c 6c 65 72 20 73 68 6f 75 6c  The caller shoul
b5c0: 64 0a 2a 2a 20 69 6e 76 6f 6b 65 20 5b 73 71 6c  d.** invoke [sql
b5d0: 69 74 65 33 5f 66 72 65 65 28 29 5d 20 6f 6e 20  ite3_free()] on 
b5e0: 74 68 65 20 72 65 73 75 6c 74 20 74 6f 20 61 76  the result to av
b5f0: 6f 69 64 20 61 20 6d 65 6d 6f 72 79 20 6c 65 61  oid a memory lea
b600: 6b 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53  k..**.** <li>[[S
b610: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41 50  QLITE_FCNTL_MMAP
b620: 5f 53 49 5a 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b  _SIZE]].** The [
b630: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41  SQLITE_FCNTL_MMA
b640: 50 5f 53 49 5a 45 5d 20 66 69 6c 65 20 63 6f 6e  P_SIZE] file con
b650: 74 72 6f 6c 20 69 73 20 75 73 65 64 20 74 6f 20  trol is used to 
b660: 71 75 65 72 79 20 6f 72 20 73 65 74 20 74 68 65  query or set the
b670: 0a 2a 2a 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62  .** maximum numb
b680: 65 72 20 6f 66 20 62 79 74 65 73 20 74 68 61 74  er of bytes that
b690: 20 77 69 6c 6c 20 62 65 20 75 73 65 64 20 66 6f   will be used fo
b6a0: 72 20 6d 65 6d 6f 72 79 2d 6d 61 70 70 65 64 20  r memory-mapped 
b6b0: 49 2f 4f 2e 0a 2a 2a 20 54 68 65 20 61 72 67 75  I/O..** The argu
b6c0: 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65  ment is a pointe
b6d0: 72 20 74 6f 20 61 20 76 61 6c 75 65 20 6f 66 20  r to a value of 
b6e0: 74 79 70 65 20 73 71 6c 69 74 65 33 5f 69 6e 74  type sqlite3_int
b6f0: 36 34 20 74 68 61 74 0a 2a 2a 20 69 73 20 61 6e  64 that.** is an
b700: 20 61 64 76 69 73 6f 72 79 20 6d 61 78 69 6d 75   advisory maximu
b710: 6d 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  m number of byte
b720: 73 20 69 6e 20 74 68 65 20 66 69 6c 65 20 74 6f  s in the file to
b730: 20 6d 65 6d 6f 72 79 20 6d 61 70 2e 20 20 54 68   memory map.  Th
b740: 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 69 73 20  e.** pointer is 
b750: 6f 76 65 72 77 72 69 74 74 65 6e 20 77 69 74 68  overwritten with
b760: 20 74 68 65 20 6f 6c 64 20 76 61 6c 75 65 2e 20   the old value. 
b770: 20 54 68 65 20 6c 69 6d 69 74 20 69 73 20 6e 6f   The limit is no
b780: 74 20 63 68 61 6e 67 65 64 20 69 66 0a 2a 2a 20  t changed if.** 
b790: 74 68 65 20 76 61 6c 75 65 20 6f 72 69 67 69 6e  the value origin
b7a0: 61 6c 6c 79 20 70 6f 69 6e 74 65 64 20 74 6f 20  ally pointed to 
b7b0: 69 73 20 6e 65 67 61 74 69 76 65 2c 20 61 6e 64  is negative, and
b7c0: 20 73 6f 20 74 68 65 20 63 75 72 72 65 6e 74 20   so the current 
b7d0: 6c 69 6d 69 74 20 0a 2a 2a 20 63 61 6e 20 62 65  limit .** can be
b7e0: 20 71 75 65 72 69 65 64 20 62 79 20 70 61 73 73   queried by pass
b7f0: 69 6e 67 20 69 6e 20 61 20 70 6f 69 6e 74 65 72  ing in a pointer
b800: 20 74 6f 20 61 20 6e 65 67 61 74 69 76 65 20 6e   to a negative n
b810: 75 6d 62 65 72 2e 20 20 54 68 69 73 0a 2a 2a 20  umber.  This.** 
b820: 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 69 73 20  file-control is 
b830: 75 73 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20  used internally 
b840: 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 5b 50 52  to implement [PR
b850: 41 47 4d 41 20 6d 6d 61 70 5f 73 69 7a 65 5d 2e  AGMA mmap_size].
b860: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
b870: 49 54 45 5f 46 43 4e 54 4c 5f 54 52 41 43 45 5d  ITE_FCNTL_TRACE]
b880: 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45  ].** The [SQLITE
b890: 5f 46 43 4e 54 4c 5f 54 52 41 43 45 5d 20 66 69  _FCNTL_TRACE] fi
b8a0: 6c 65 20 63 6f 6e 74 72 6f 6c 20 70 72 6f 76 69  le control provi
b8b0: 64 65 73 20 61 64 76 69 73 6f 72 79 20 69 6e 66  des advisory inf
b8c0: 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 74 6f 20 74  ormation.** to t
b8d0: 68 65 20 56 46 53 20 61 62 6f 75 74 20 77 68 61  he VFS about wha
b8e0: 74 20 74 68 65 20 68 69 67 68 65 72 20 6c 61 79  t the higher lay
b8f0: 65 72 73 20 6f 66 20 74 68 65 20 53 51 4c 69 74  ers of the SQLit
b900: 65 20 73 74 61 63 6b 20 61 72 65 20 64 6f 69 6e  e stack are doin
b910: 67 2e 0a 2a 2a 20 54 68 69 73 20 66 69 6c 65 20  g..** This file 
b920: 63 6f 6e 74 72 6f 6c 20 69 73 20 75 73 65 64 20  control is used 
b930: 62 79 20 73 6f 6d 65 20 56 46 53 20 61 63 74 69  by some VFS acti
b940: 76 69 74 79 20 74 72 61 63 69 6e 67 20 5b 73 68  vity tracing [sh
b950: 69 6d 73 5d 2e 0a 2a 2a 20 54 68 65 20 61 72 67  ims]..** The arg
b960: 75 6d 65 6e 74 20 69 73 20 61 20 7a 65 72 6f 2d  ument is a zero-
b970: 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72 69 6e  terminated strin
b980: 67 2e 20 20 48 69 67 68 65 72 20 6c 61 79 65 72  g.  Higher layer
b990: 73 20 69 6e 20 74 68 65 0a 2a 2a 20 53 51 4c 69  s in the.** SQLi
b9a0: 74 65 20 73 74 61 63 6b 20 6d 61 79 20 67 65 6e  te stack may gen
b9b0: 65 72 61 74 65 20 69 6e 73 74 61 6e 63 65 73 20  erate instances 
b9c0: 6f 66 20 74 68 69 73 20 66 69 6c 65 20 63 6f 6e  of this file con
b9d0: 74 72 6f 6c 20 69 66 0a 2a 2a 20 74 68 65 20 5b  trol if.** the [
b9e0: 53 51 4c 49 54 45 5f 55 53 45 5f 46 43 4e 54 4c  SQLITE_USE_FCNTL
b9f0: 5f 54 52 41 43 45 5d 20 63 6f 6d 70 69 6c 65 2d  _TRACE] compile-
ba00: 74 69 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20 65  time option is e
ba10: 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  nabled..**.** <l
ba20: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
ba30: 5f 48 41 53 5f 4d 4f 56 45 44 5d 5d 0a 2a 2a 20  _HAS_MOVED]].** 
ba40: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
ba50: 4c 5f 48 41 53 5f 4d 4f 56 45 44 5d 20 66 69 6c  L_HAS_MOVED] fil
ba60: 65 20 63 6f 6e 74 72 6f 6c 20 69 6e 74 65 72 70  e control interp
ba70: 72 65 74 73 20 69 74 73 20 61 72 67 75 6d 65 6e  rets its argumen
ba80: 74 20 61 73 20 61 0a 2a 2a 20 70 6f 69 6e 74 65  t as a.** pointe
ba90: 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20  r to an integer 
baa0: 61 6e 64 20 69 74 20 77 72 69 74 65 73 20 61 20  and it writes a 
bab0: 62 6f 6f 6c 65 61 6e 20 69 6e 74 6f 20 74 68 61  boolean into tha
bac0: 74 20 69 6e 74 65 67 65 72 20 64 65 70 65 6e 64  t integer depend
bad0: 69 6e 67 0a 2a 2a 20 6f 6e 20 77 68 65 74 68 65  ing.** on whethe
bae0: 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 66 69 6c  r or not the fil
baf0: 65 20 68 61 73 20 62 65 65 6e 20 72 65 6e 61 6d  e has been renam
bb00: 65 64 2c 20 6d 6f 76 65 64 2c 20 6f 72 20 64 65  ed, moved, or de
bb10: 6c 65 74 65 64 20 73 69 6e 63 65 20 69 74 0a 2a  leted since it.*
bb20: 2a 20 77 61 73 20 66 69 72 73 74 20 6f 70 65 6e  * was first open
bb30: 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  ed..**.** <li>[[
bb40: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e  SQLITE_FCNTL_WIN
bb50: 33 32 5f 47 45 54 5f 48 41 4e 44 4c 45 5d 5d 0a  32_GET_HANDLE]].
bb60: 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  ** The [SQLITE_F
bb70: 43 4e 54 4c 5f 57 49 4e 33 32 5f 47 45 54 5f 48  CNTL_WIN32_GET_H
bb80: 41 4e 44 4c 45 5d 20 6f 70 63 6f 64 65 20 63 61  ANDLE] opcode ca
bb90: 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f 62 74  n be used to obt
bba0: 61 69 6e 20 74 68 65 0a 2a 2a 20 75 6e 64 65 72  ain the.** under
bbb0: 6c 79 69 6e 67 20 6e 61 74 69 76 65 20 66 69 6c  lying native fil
bbc0: 65 20 68 61 6e 64 6c 65 20 61 73 73 6f 63 69 61  e handle associa
bbd0: 74 65 64 20 77 69 74 68 20 61 20 66 69 6c 65 20  ted with a file 
bbe0: 68 61 6e 64 6c 65 2e 20 20 54 68 69 73 20 66 69  handle.  This fi
bbf0: 6c 65 0a 2a 2a 20 63 6f 6e 74 72 6f 6c 20 69 6e  le.** control in
bc00: 74 65 72 70 72 65 74 73 20 69 74 73 20 61 72 67  terprets its arg
bc10: 75 6d 65 6e 74 20 61 73 20 61 20 70 6f 69 6e 74  ument as a point
bc20: 65 72 20 74 6f 20 61 20 6e 61 74 69 76 65 20 66  er to a native f
bc30: 69 6c 65 20 68 61 6e 64 6c 65 20 61 6e 64 0a 2a  ile handle and.*
bc40: 2a 20 77 72 69 74 65 73 20 74 68 65 20 72 65 73  * writes the res
bc50: 75 6c 74 69 6e 67 20 76 61 6c 75 65 20 74 68 65  ulting value the
bc60: 72 65 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  re..**.** <li>[[
bc70: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e  SQLITE_FCNTL_WIN
bc80: 33 32 5f 53 45 54 5f 48 41 4e 44 4c 45 5d 5d 0a  32_SET_HANDLE]].
bc90: 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  ** The [SQLITE_F
bca0: 43 4e 54 4c 5f 57 49 4e 33 32 5f 53 45 54 5f 48  CNTL_WIN32_SET_H
bcb0: 41 4e 44 4c 45 5d 20 6f 70 63 6f 64 65 20 69 73  ANDLE] opcode is
bcc0: 20 75 73 65 64 20 66 6f 72 20 64 65 62 75 67 67   used for debugg
bcd0: 69 6e 67 2e 20 20 54 68 69 73 0a 2a 2a 20 6f 70  ing.  This.** op
bce0: 63 6f 64 65 20 63 61 75 73 65 73 20 74 68 65 20  code causes the 
bcf0: 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74  xFileControl met
bd00: 68 6f 64 20 74 6f 20 73 77 61 70 20 74 68 65 20  hod to swap the 
bd10: 66 69 6c 65 20 68 61 6e 64 6c 65 20 77 69 74 68  file handle with
bd20: 20 74 68 65 20 6f 6e 65 0a 2a 2a 20 70 6f 69 6e   the one.** poin
bd30: 74 65 64 20 74 6f 20 62 79 20 74 68 65 20 70 41  ted to by the pA
bd40: 72 67 20 61 72 67 75 6d 65 6e 74 2e 20 20 54 68  rg argument.  Th
bd50: 69 73 20 63 61 70 61 62 69 6c 69 74 79 20 69 73  is capability is
bd60: 20 75 73 65 64 20 64 75 72 69 6e 67 20 74 65 73   used during tes
bd70: 74 69 6e 67 0a 2a 2a 20 61 6e 64 20 6f 6e 6c 79  ting.** and only
bd80: 20 6e 65 65 64 73 20 74 6f 20 62 65 20 73 75 70   needs to be sup
bd90: 70 6f 72 74 65 64 20 77 68 65 6e 20 53 51 4c 49  ported when SQLI
bda0: 54 45 5f 54 45 53 54 20 69 73 20 64 65 66 69 6e  TE_TEST is defin
bdb0: 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  ed..**.** <li>[[
bdc0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 41 4c  SQLITE_FCNTL_WAL
bdd0: 5f 42 4c 4f 43 4b 5d 5d 0a 2a 2a 20 54 68 65 20  _BLOCK]].** The 
bde0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 41  [SQLITE_FCNTL_WA
bdf0: 4c 5f 42 4c 4f 43 4b 5d 20 69 73 20 61 20 73 69  L_BLOCK] is a si
be00: 67 6e 61 6c 20 74 6f 20 74 68 65 20 56 46 53 20  gnal to the VFS 
be10: 6c 61 79 65 72 20 74 68 61 74 20 69 74 20 6d 69  layer that it mi
be20: 67 68 74 0a 2a 2a 20 62 65 20 61 64 76 61 6e 74  ght.** be advant
be30: 61 67 65 6f 75 73 20 74 6f 20 62 6c 6f 63 6b 20  ageous to block 
be40: 6f 6e 20 74 68 65 20 6e 65 78 74 20 57 41 4c 20  on the next WAL 
be50: 6c 6f 63 6b 20 69 66 20 74 68 65 20 6c 6f 63 6b  lock if the lock
be60: 20 69 73 20 6e 6f 74 20 69 6d 6d 65 64 69 61 74   is not immediat
be70: 65 6c 79 0a 2a 2a 20 61 76 61 69 6c 61 62 6c 65  ely.** available
be80: 2e 20 20 54 68 65 20 57 41 4c 20 73 75 62 73 79  .  The WAL subsy
be90: 73 74 65 6d 20 69 73 73 75 65 73 20 74 68 69 73  stem issues this
bea0: 20 73 69 67 6e 61 6c 20 64 75 72 69 6e 67 20 72   signal during r
beb0: 61 72 65 0a 2a 2a 20 63 69 72 63 75 6d 73 74 61  are.** circumsta
bec0: 6e 63 65 73 20 69 6e 20 6f 72 64 65 72 20 74 6f  nces in order to
bed0: 20 66 69 78 20 61 20 70 72 6f 62 6c 65 6d 20 77   fix a problem w
bee0: 69 74 68 20 70 72 69 6f 72 69 74 79 20 69 6e 76  ith priority inv
bef0: 65 72 73 69 6f 6e 2e 0a 2a 2a 20 41 70 70 6c 69  ersion..** Appli
bf00: 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 3c  cations should <
bf10: 65 6d 3e 6e 6f 74 3c 2f 65 6d 3e 20 75 73 65 20  em>not</em> use 
bf20: 74 68 69 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f  this file-contro
bf30: 6c 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53  l..**.** <li>[[S
bf40: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 5a 49 50 56  QLITE_FCNTL_ZIPV
bf50: 46 53 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  FS]].** The [SQL
bf60: 49 54 45 5f 46 43 4e 54 4c 5f 5a 49 50 56 46 53  ITE_FCNTL_ZIPVFS
bf70: 5d 20 6f 70 63 6f 64 65 20 69 73 20 69 6d 70 6c  ] opcode is impl
bf80: 65 6d 65 6e 74 65 64 20 62 79 20 7a 69 70 76 66  emented by zipvf
bf90: 73 20 6f 6e 6c 79 2e 20 41 6c 6c 20 6f 74 68 65  s only. All othe
bfa0: 72 0a 2a 2a 20 56 46 53 20 73 68 6f 75 6c 64 20  r.** VFS should 
bfb0: 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4e 4f  return SQLITE_NO
bfc0: 54 46 4f 55 4e 44 20 66 6f 72 20 74 68 69 73 20  TFOUND for this 
bfd0: 6f 70 63 6f 64 65 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  opcode..**.** <l
bfe0: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
bff0: 5f 52 42 55 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53  _RBU]].** The [S
c000: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 52 42 55 5d  QLITE_FCNTL_RBU]
c010: 20 6f 70 63 6f 64 65 20 69 73 20 69 6d 70 6c 65   opcode is imple
c020: 6d 65 6e 74 65 64 20 62 79 20 74 68 65 20 73 70  mented by the sp
c030: 65 63 69 61 6c 20 56 46 53 20 75 73 65 64 20 62  ecial VFS used b
c040: 79 0a 2a 2a 20 74 68 65 20 52 42 55 20 65 78 74  y.** the RBU ext
c050: 65 6e 73 69 6f 6e 20 6f 6e 6c 79 2e 20 20 41 6c  ension only.  Al
c060: 6c 20 6f 74 68 65 72 20 56 46 53 20 73 68 6f 75  l other VFS shou
c070: 6c 64 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45  ld return SQLITE
c080: 5f 4e 4f 54 46 4f 55 4e 44 20 66 6f 72 0a 2a 2a  _NOTFOUND for.**
c090: 20 74 68 69 73 20 6f 70 63 6f 64 65 2e 20 20 0a   this opcode.  .
c0a0: 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2f 0a 23 64 65 66  ** </ul>.*/.#def
c0b0: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
c0c0: 5f 4c 4f 43 4b 53 54 41 54 45 20 20 20 20 20 20  _LOCKSTATE      
c0d0: 20 20 20 20 20 20 20 20 20 31 0a 23 64 65 66 69           1.#defi
c0e0: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
c0f0: 47 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c  GET_LOCKPROXYFIL
c100: 45 20 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e  E       2.#defin
c110: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53  e SQLITE_FCNTL_S
c120: 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45  ET_LOCKPROXYFILE
c130: 20 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65         3.#define
c140: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 41   SQLITE_FCNTL_LA
c150: 53 54 5f 45 52 52 4e 4f 20 20 20 20 20 20 20 20  ST_ERRNO        
c160: 20 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20        4.#define 
c170: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a  SQLITE_FCNTL_SIZ
c180: 45 5f 48 49 4e 54 20 20 20 20 20 20 20 20 20 20  E_HINT          
c190: 20 20 20 20 20 35 0a 23 64 65 66 69 6e 65 20 53       5.#define S
c1a0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e  QLITE_FCNTL_CHUN
c1b0: 4b 5f 53 49 5a 45 20 20 20 20 20 20 20 20 20 20  K_SIZE          
c1c0: 20 20 20 20 36 0a 23 64 65 66 69 6e 65 20 53 51      6.#define SQ
c1d0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f  LITE_FCNTL_FILE_
c1e0: 50 4f 49 4e 54 45 52 20 20 20 20 20 20 20 20 20  POINTER         
c1f0: 20 20 20 37 0a 23 64 65 66 69 6e 65 20 53 51 4c     7.#define SQL
c200: 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5f 4f  ITE_FCNTL_SYNC_O
c210: 4d 49 54 54 45 44 20 20 20 20 20 20 20 20 20 20  MITTED          
c220: 20 20 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    8.#define SQLI
c230: 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 41  TE_FCNTL_WIN32_A
c240: 56 5f 52 45 54 52 59 20 20 20 20 20 20 20 20 20  V_RETRY         
c250: 20 39 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   9.#define SQLIT
c260: 45 5f 46 43 4e 54 4c 5f 50 45 52 53 49 53 54 5f  E_FCNTL_PERSIST_
c270: 57 41 4c 20 20 20 20 20 20 20 20 20 20 20 20 31  WAL            1
c280: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
c290: 5f 46 43 4e 54 4c 5f 4f 56 45 52 57 52 49 54 45  _FCNTL_OVERWRITE
c2a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31 31                11
c2b0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
c2c0: 46 43 4e 54 4c 5f 56 46 53 4e 41 4d 45 20 20 20  FCNTL_VFSNAME   
c2d0: 20 20 20 20 20 20 20 20 20 20 20 20 20 31 32 0a               12.
c2e0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
c2f0: 43 4e 54 4c 5f 50 4f 57 45 52 53 41 46 45 5f 4f  CNTL_POWERSAFE_O
c300: 56 45 52 57 52 49 54 45 20 20 20 20 31 33 0a 23  VERWRITE    13.#
c310: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
c320: 4e 54 4c 5f 50 52 41 47 4d 41 20 20 20 20 20 20  NTL_PRAGMA      
c330: 20 20 20 20 20 20 20 20 20 20 20 31 34 0a 23 64             14.#d
c340: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
c350: 54 4c 5f 42 55 53 59 48 41 4e 44 4c 45 52 20 20  TL_BUSYHANDLER  
c360: 20 20 20 20 20 20 20 20 20 20 31 35 0a 23 64 65            15.#de
c370: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
c380: 4c 5f 54 45 4d 50 46 49 4c 45 4e 41 4d 45 20 20  L_TEMPFILENAME  
c390: 20 20 20 20 20 20 20 20 20 31 36 0a 23 64 65 66           16.#def
c3a0: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
c3b0: 5f 4d 4d 41 50 5f 53 49 5a 45 20 20 20 20 20 20  _MMAP_SIZE      
c3c0: 20 20 20 20 20 20 20 20 31 38 0a 23 64 65 66 69          18.#defi
c3d0: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
c3e0: 54 52 41 43 45 20 20 20 20 20 20 20 20 20 20 20  TRACE           
c3f0: 20 20 20 20 20 20 20 31 39 0a 23 64 65 66 69 6e         19.#defin
c400: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 48  e SQLITE_FCNTL_H
c410: 41 53 5f 4d 4f 56 45 44 20 20 20 20 20 20 20 20  AS_MOVED        
c420: 20 20 20 20 20 20 32 30 0a 23 64 65 66 69 6e 65        20.#define
c430: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59   SQLITE_FCNTL_SY
c440: 4e 43 20 20 20 20 20 20 20 20 20 20 20 20 20 20  NC              
c450: 20 20 20 20 20 32 31 0a 23 64 65 66 69 6e 65 20       21.#define 
c460: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d  SQLITE_FCNTL_COM
c470: 4d 49 54 5f 50 48 41 53 45 54 57 4f 20 20 20 20  MIT_PHASETWO    
c480: 20 20 20 20 32 32 0a 23 64 65 66 69 6e 65 20 53      22.#define S
c490: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33  QLITE_FCNTL_WIN3
c4a0: 32 5f 53 45 54 5f 48 41 4e 44 4c 45 20 20 20 20  2_SET_HANDLE    
c4b0: 20 20 20 32 33 0a 23 64 65 66 69 6e 65 20 53 51     23.#define SQ
c4c0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 41 4c 5f 42  LITE_FCNTL_WAL_B
c4d0: 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20 20  LOCK            
c4e0: 20 20 32 34 0a 23 64 65 66 69 6e 65 20 53 51 4c    24.#define SQL
c4f0: 49 54 45 5f 46 43 4e 54 4c 5f 5a 49 50 56 46 53  ITE_FCNTL_ZIPVFS
c500: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
c510: 20 32 35 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   25.#define SQLI
c520: 54 45 5f 46 43 4e 54 4c 5f 52 42 55 20 20 20 20  TE_FCNTL_RBU    
c530: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
c540: 32 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  26.#define SQLIT
c550: 45 5f 46 43 4e 54 4c 5f 56 46 53 5f 50 4f 49 4e  E_FCNTL_VFS_POIN
c560: 54 45 52 20 20 20 20 20 20 20 20 20 20 20 20 32  TER            2
c570: 37 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  7.#define SQLITE
c580: 5f 46 43 4e 54 4c 5f 4a 4f 55 52 4e 41 4c 5f 50  _FCNTL_JOURNAL_P
c590: 4f 49 4e 54 45 52 20 20 20 20 20 20 20 20 32 38  OINTER        28
c5a0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
c5b0: 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 47 45 54 5f  FCNTL_WIN32_GET_
c5c0: 48 41 4e 44 4c 45 20 20 20 20 20 20 20 32 39 0a  HANDLE       29.
c5d0: 0a 2f 2a 20 64 65 70 72 65 63 61 74 65 64 20 6e  ./* deprecated n
c5e0: 61 6d 65 73 20 2a 2f 0a 23 64 65 66 69 6e 65 20  ames */.#define 
c5f0: 53 51 4c 49 54 45 5f 47 45 54 5f 4c 4f 43 4b 50  SQLITE_GET_LOCKP
c600: 52 4f 58 59 46 49 4c 45 20 20 20 20 20 20 53 51  ROXYFILE      SQ
c610: 4c 49 54 45 5f 46 43 4e 54 4c 5f 47 45 54 5f 4c  LITE_FCNTL_GET_L
c620: 4f 43 4b 50 52 4f 58 59 46 49 4c 45 0a 23 64 65  OCKPROXYFILE.#de
c630: 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 45 54 5f  fine SQLITE_SET_
c640: 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20 20 20  LOCKPROXYFILE   
c650: 20 20 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f     SQLITE_FCNTL_
c660: 53 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c  SET_LOCKPROXYFIL
c670: 45 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  E.#define SQLITE
c680: 5f 4c 41 53 54 5f 45 52 52 4e 4f 20 20 20 20 20  _LAST_ERRNO     
c690: 20 20 20 20 20 20 20 20 53 51 4c 49 54 45 5f 46          SQLITE_F
c6a0: 43 4e 54 4c 5f 4c 41 53 54 5f 45 52 52 4e 4f 0a  CNTL_LAST_ERRNO.
c6b0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
c6c0: 3a 20 4d 75 74 65 78 20 48 61 6e 64 6c 65 0a 2a  : Mutex Handle.*
c6d0: 2a 0a 2a 2a 20 54 68 65 20 6d 75 74 65 78 20 6d  *.** The mutex m
c6e0: 6f 64 75 6c 65 20 77 69 74 68 69 6e 20 53 51 4c  odule within SQL
c6f0: 69 74 65 20 64 65 66 69 6e 65 73 20 5b 73 71 6c  ite defines [sql
c700: 69 74 65 33 5f 6d 75 74 65 78 5d 20 74 6f 20 62  ite3_mutex] to b
c710: 65 20 61 6e 0a 2a 2a 20 61 62 73 74 72 61 63 74  e an.** abstract
c720: 20 74 79 70 65 20 66 6f 72 20 61 20 6d 75 74 65   type for a mute
c730: 78 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 20 53  x object.  The S
c740: 51 4c 69 74 65 20 63 6f 72 65 20 6e 65 76 65 72  QLite core never
c750: 20 6c 6f 6f 6b 73 0a 2a 2a 20 61 74 20 74 68 65   looks.** at the
c760: 20 69 6e 74 65 72 6e 61 6c 20 72 65 70 72 65 73   internal repres
c770: 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61 6e 20 5b  entation of an [
c780: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 2e 20  sqlite3_mutex]. 
c790: 20 49 74 20 6f 6e 6c 79 0a 2a 2a 20 64 65 61 6c   It only.** deal
c7a0: 73 20 77 69 74 68 20 70 6f 69 6e 74 65 72 73 20  s with pointers 
c7b0: 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
c7c0: 6d 75 74 65 78 5d 20 6f 62 6a 65 63 74 2e 0a 2a  mutex] object..*
c7d0: 2a 0a 2a 2a 20 4d 75 74 65 78 65 73 20 61 72 65  *.** Mutexes are
c7e0: 20 63 72 65 61 74 65 64 20 75 73 69 6e 67 20 5b   created using [
c7f0: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c  sqlite3_mutex_al
c800: 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64  loc()]..*/.typed
c810: 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  ef struct sqlite
c820: 33 5f 6d 75 74 65 78 20 73 71 6c 69 74 65 33 5f  3_mutex sqlite3_
c830: 6d 75 74 65 78 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  mutex;../*.** CA
c840: 50 49 33 52 45 46 3a 20 4c 6f 61 64 61 62 6c 65  PI3REF: Loadable
c850: 20 45 78 74 65 6e 73 69 6f 6e 20 54 68 75 6e 6b   Extension Thunk
c860: 0a 2a 2a 0a 2a 2a 20 41 20 70 6f 69 6e 74 65 72  .**.** A pointer
c870: 20 74 6f 20 74 68 65 20 6f 70 61 71 75 65 20 73   to the opaque s
c880: 71 6c 69 74 65 33 5f 61 70 69 5f 72 6f 75 74 69  qlite3_api_routi
c890: 6e 65 73 20 73 74 72 75 63 74 75 72 65 20 69 73  nes structure is
c8a0: 20 70 61 73 73 65 64 20 61 73 0a 2a 2a 20 74 68   passed as.** th
c8b0: 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  e third paramete
c8c0: 72 20 74 6f 20 65 6e 74 72 79 20 70 6f 69 6e 74  r to entry point
c8d0: 73 20 6f 66 20 5b 6c 6f 61 64 61 62 6c 65 20 65  s of [loadable e
c8e0: 78 74 65 6e 73 69 6f 6e 73 5d 2e 20 20 54 68 69  xtensions].  Thi
c8f0: 73 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 6d  s.** structure m
c900: 75 73 74 20 62 65 20 74 79 70 65 64 65 66 65 64  ust be typedefed
c910: 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 77 6f 72   in order to wor
c920: 6b 20 61 72 6f 75 6e 64 20 63 6f 6d 70 69 6c 65  k around compile
c930: 72 20 77 61 72 6e 69 6e 67 73 0a 2a 2a 20 6f 6e  r warnings.** on
c940: 20 73 6f 6d 65 20 70 6c 61 74 66 6f 72 6d 73 2e   some platforms.
c950: 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75  .*/.typedef stru
c960: 63 74 20 73 71 6c 69 74 65 33 5f 61 70 69 5f 72  ct sqlite3_api_r
c970: 6f 75 74 69 6e 65 73 20 73 71 6c 69 74 65 33 5f  outines sqlite3_
c980: 61 70 69 5f 72 6f 75 74 69 6e 65 73 3b 0a 0a 2f  api_routines;../
c990: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f  *.** CAPI3REF: O
c9a0: 53 20 49 6e 74 65 72 66 61 63 65 20 4f 62 6a 65  S Interface Obje
c9b0: 63 74 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74  ct.**.** An inst
c9c0: 61 6e 63 65 20 6f 66 20 74 68 65 20 73 71 6c 69  ance of the sqli
c9d0: 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 20 64  te3_vfs object d
c9e0: 65 66 69 6e 65 73 20 74 68 65 20 69 6e 74 65 72  efines the inter
c9f0: 66 61 63 65 20 62 65 74 77 65 65 6e 0a 2a 2a 20  face between.** 
ca00: 74 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20  the SQLite core 
ca10: 61 6e 64 20 74 68 65 20 75 6e 64 65 72 6c 79 69  and the underlyi
ca20: 6e 67 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73  ng operating sys
ca30: 74 65 6d 2e 20 20 54 68 65 20 22 76 66 73 22 0a  tem.  The "vfs".
ca40: 2a 2a 20 69 6e 20 74 68 65 20 6e 61 6d 65 20 6f  ** in the name o
ca50: 66 20 74 68 65 20 6f 62 6a 65 63 74 20 73 74 61  f the object sta
ca60: 6e 64 73 20 66 6f 72 20 22 76 69 72 74 75 61 6c  nds for "virtual
ca70: 20 66 69 6c 65 20 73 79 73 74 65 6d 22 2e 20 20   file system".  
ca80: 53 65 65 0a 2a 2a 20 74 68 65 20 5b 56 46 53 20  See.** the [VFS 
ca90: 7c 20 56 46 53 20 64 6f 63 75 6d 65 6e 74 61 74  | VFS documentat
caa0: 69 6f 6e 5d 20 66 6f 72 20 66 75 72 74 68 65 72  ion] for further
cab0: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a   information..**
cac0: 0a 2a 2a 20 54 68 65 20 76 61 6c 75 65 20 6f 66  .** The value of
cad0: 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20 66 69   the iVersion fi
cae0: 65 6c 64 20 69 73 20 69 6e 69 74 69 61 6c 6c 79  eld is initially
caf0: 20 31 20 62 75 74 20 6d 61 79 20 62 65 20 6c 61   1 but may be la
cb00: 72 67 65 72 20 69 6e 0a 2a 2a 20 66 75 74 75 72  rger in.** futur
cb10: 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51  e versions of SQ
cb20: 4c 69 74 65 2e 20 20 41 64 64 69 74 69 6f 6e 61  Lite.  Additiona
cb30: 6c 20 66 69 65 6c 64 73 20 6d 61 79 20 62 65 20  l fields may be 
cb40: 61 70 70 65 6e 64 65 64 20 74 6f 20 74 68 69 73  appended to this
cb50: 0a 2a 2a 20 6f 62 6a 65 63 74 20 77 68 65 6e 20  .** object when 
cb60: 74 68 65 20 69 56 65 72 73 69 6f 6e 20 76 61 6c  the iVersion val
cb70: 75 65 20 69 73 20 69 6e 63 72 65 61 73 65 64 2e  ue is increased.
cb80: 20 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20    Note that the 
cb90: 73 74 72 75 63 74 75 72 65 0a 2a 2a 20 6f 66 20  structure.** of 
cba0: 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 20  the sqlite3_vfs 
cbb0: 6f 62 6a 65 63 74 20 63 68 61 6e 67 65 73 20 69  object changes i
cbc0: 6e 20 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f  n the transactio
cbd0: 6e 20 62 65 74 77 65 65 6e 0a 2a 2a 20 53 51 4c  n between.** SQL
cbe0: 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e  ite version 3.5.
cbf0: 39 20 61 6e 64 20 33 2e 36 2e 30 20 61 6e 64 20  9 and 3.6.0 and 
cc00: 79 65 74 20 74 68 65 20 69 56 65 72 73 69 6f 6e  yet the iVersion
cc10: 20 66 69 65 6c 64 20 77 61 73 20 6e 6f 74 0a 2a   field was not.*
cc20: 2a 20 6d 6f 64 69 66 69 65 64 2e 0a 2a 2a 0a 2a  * modified..**.*
cc30: 2a 20 54 68 65 20 73 7a 4f 73 46 69 6c 65 20 66  * The szOsFile f
cc40: 69 65 6c 64 20 69 73 20 74 68 65 20 73 69 7a 65  ield is the size
cc50: 20 6f 66 20 74 68 65 20 73 75 62 63 6c 61 73 73   of the subclass
cc60: 65 64 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  ed [sqlite3_file
cc70: 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 75  ].** structure u
cc80: 73 65 64 20 62 79 20 74 68 69 73 20 56 46 53 2e  sed by this VFS.
cc90: 20 20 6d 78 50 61 74 68 6e 61 6d 65 20 69 73 20    mxPathname is 
cca0: 74 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67  the maximum leng
ccb0: 74 68 20 6f 66 0a 2a 2a 20 61 20 70 61 74 68 6e  th of.** a pathn
ccc0: 61 6d 65 20 69 6e 20 74 68 69 73 20 56 46 53 2e  ame in this VFS.
ccd0: 0a 2a 2a 0a 2a 2a 20 52 65 67 69 73 74 65 72 65  .**.** Registere
cce0: 64 20 73 71 6c 69 74 65 33 5f 76 66 73 20 6f 62  d sqlite3_vfs ob
ccf0: 6a 65 63 74 73 20 61 72 65 20 6b 65 70 74 20 6f  jects are kept o
cd00: 6e 20 61 20 6c 69 6e 6b 65 64 20 6c 69 73 74 20  n a linked list 
cd10: 66 6f 72 6d 65 64 20 62 79 0a 2a 2a 20 74 68 65  formed by.** the
cd20: 20 70 4e 65 78 74 20 70 6f 69 6e 74 65 72 2e 20   pNext pointer. 
cd30: 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66   The [sqlite3_vf
cd40: 73 5f 72 65 67 69 73 74 65 72 28 29 5d 0a 2a 2a  s_register()].**
cd50: 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 76 66   and [sqlite3_vf
cd60: 73 5f 75 6e 72 65 67 69 73 74 65 72 28 29 5d 20  s_unregister()] 
cd70: 69 6e 74 65 72 66 61 63 65 73 20 6d 61 6e 61 67  interfaces manag
cd80: 65 20 74 68 69 73 20 6c 69 73 74 0a 2a 2a 20 69  e this list.** i
cd90: 6e 20 61 20 74 68 72 65 61 64 2d 73 61 66 65 20  n a thread-safe 
cda0: 77 61 79 2e 20 20 54 68 65 20 5b 73 71 6c 69 74  way.  The [sqlit
cdb0: 65 33 5f 76 66 73 5f 66 69 6e 64 28 29 5d 20 69  e3_vfs_find()] i
cdc0: 6e 74 65 72 66 61 63 65 0a 2a 2a 20 73 65 61 72  nterface.** sear
cdd0: 63 68 65 73 20 74 68 65 20 6c 69 73 74 2e 20 20  ches the list.  
cde0: 4e 65 69 74 68 65 72 20 74 68 65 20 61 70 70 6c  Neither the appl
cdf0: 69 63 61 74 69 6f 6e 20 63 6f 64 65 20 6e 6f 72  ication code nor
ce00: 20 74 68 65 20 56 46 53 0a 2a 2a 20 69 6d 70 6c   the VFS.** impl
ce10: 65 6d 65 6e 74 61 74 69 6f 6e 20 73 68 6f 75 6c  ementation shoul
ce20: 64 20 75 73 65 20 74 68 65 20 70 4e 65 78 74 20  d use the pNext 
ce30: 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54  pointer..**.** T
ce40: 68 65 20 70 4e 65 78 74 20 66 69 65 6c 64 20 69  he pNext field i
ce50: 73 20 74 68 65 20 6f 6e 6c 79 20 66 69 65 6c 64  s the only field
ce60: 20 69 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f   in the sqlite3_
ce70: 76 66 73 0a 2a 2a 20 73 74 72 75 63 74 75 72 65  vfs.** structure
ce80: 20 74 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c   that SQLite wil
ce90: 6c 20 65 76 65 72 20 6d 6f 64 69 66 79 2e 20 20  l ever modify.  
cea0: 53 51 4c 69 74 65 20 77 69 6c 6c 20 6f 6e 6c 79  SQLite will only
ceb0: 20 61 63 63 65 73 73 0a 2a 2a 20 6f 72 20 6d 6f   access.** or mo
cec0: 64 69 66 79 20 74 68 69 73 20 66 69 65 6c 64 20  dify this field 
ced0: 77 68 69 6c 65 20 68 6f 6c 64 69 6e 67 20 61 20  while holding a 
cee0: 70 61 72 74 69 63 75 6c 61 72 20 73 74 61 74 69  particular stati
cef0: 63 20 6d 75 74 65 78 2e 0a 2a 2a 20 54 68 65 20  c mutex..** The 
cf00: 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75  application shou
cf10: 6c 64 20 6e 65 76 65 72 20 6d 6f 64 69 66 79 20  ld never modify 
cf20: 61 6e 79 74 68 69 6e 67 20 77 69 74 68 69 6e 20  anything within 
cf30: 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 0a  the sqlite3_vfs.
cf40: 2a 2a 20 6f 62 6a 65 63 74 20 6f 6e 63 65 20 74  ** object once t
cf50: 68 65 20 6f 62 6a 65 63 74 20 68 61 73 20 62 65  he object has be
cf60: 65 6e 20 72 65 67 69 73 74 65 72 65 64 2e 0a 2a  en registered..*
cf70: 2a 0a 2a 2a 20 54 68 65 20 7a 4e 61 6d 65 20 66  *.** The zName f
cf80: 69 65 6c 64 20 68 6f 6c 64 73 20 74 68 65 20 6e  ield holds the n
cf90: 61 6d 65 20 6f 66 20 74 68 65 20 56 46 53 20 6d  ame of the VFS m
cfa0: 6f 64 75 6c 65 2e 20 20 54 68 65 20 6e 61 6d 65  odule.  The name
cfb0: 20 6d 75 73 74 0a 2a 2a 20 62 65 20 75 6e 69 71   must.** be uniq
cfc0: 75 65 20 61 63 72 6f 73 73 20 61 6c 6c 20 56 46  ue across all VF
cfd0: 53 20 6d 6f 64 75 6c 65 73 2e 0a 2a 2a 0a 2a 2a  S modules..**.**
cfe0: 20 5b 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78   [[sqlite3_vfs.x
cff0: 4f 70 65 6e 5d 5d 0a 2a 2a 20 5e 53 51 4c 69 74  Open]].** ^SQLit
d000: 65 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 61  e guarantees tha
d010: 74 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20  t the zFilename 
d020: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 78 4f 70  parameter to xOp
d030: 65 6e 0a 2a 2a 20 69 73 20 65 69 74 68 65 72 20  en.** is either 
d040: 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 6f  a NULL pointer o
d050: 72 20 73 74 72 69 6e 67 20 6f 62 74 61 69 6e 65  r string obtaine
d060: 64 0a 2a 2a 20 66 72 6f 6d 20 78 46 75 6c 6c 50  d.** from xFullP
d070: 61 74 68 6e 61 6d 65 28 29 20 77 69 74 68 20 61  athname() with a
d080: 6e 20 6f 70 74 69 6f 6e 61 6c 20 73 75 66 66 69  n optional suffi
d090: 78 20 61 64 64 65 64 2e 0a 2a 2a 20 5e 49 66 20  x added..** ^If 
d0a0: 61 20 73 75 66 66 69 78 20 69 73 20 61 64 64 65  a suffix is adde
d0b0: 64 20 74 6f 20 74 68 65 20 7a 46 69 6c 65 6e 61  d to the zFilena
d0c0: 6d 65 20 70 61 72 61 6d 65 74 65 72 2c 20 69 74  me parameter, it
d0d0: 20 77 69 6c 6c 0a 2a 2a 20 63 6f 6e 73 69 73 74   will.** consist
d0e0: 20 6f 66 20 61 20 73 69 6e 67 6c 65 20 22 2d 22   of a single "-"
d0f0: 20 63 68 61 72 61 63 74 65 72 20 66 6f 6c 6c 6f   character follo
d100: 77 65 64 20 62 79 20 6e 6f 20 6d 6f 72 65 20 74  wed by no more t
d110: 68 61 6e 0a 2a 2a 20 31 31 20 61 6c 70 68 61 6e  han.** 11 alphan
d120: 75 6d 65 72 69 63 20 61 6e 64 2f 6f 72 20 22 2d  umeric and/or "-
d130: 22 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a  " characters..**
d140: 20 5e 53 51 4c 69 74 65 20 66 75 72 74 68 65 72   ^SQLite further
d150: 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 61 74   guarantees that
d160: 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 20 77  .** the string w
d170: 69 6c 6c 20 62 65 20 76 61 6c 69 64 20 61 6e 64  ill be valid and
d180: 20 75 6e 63 68 61 6e 67 65 64 20 75 6e 74 69 6c   unchanged until
d190: 20 78 43 6c 6f 73 65 28 29 20 69 73 0a 2a 2a 20   xClose() is.** 
d1a0: 63 61 6c 6c 65 64 2e 20 42 65 63 61 75 73 65 20  called. Because 
d1b0: 6f 66 20 74 68 65 20 70 72 65 76 69 6f 75 73 20  of the previous 
d1c0: 73 65 6e 74 65 6e 63 65 2c 0a 2a 2a 20 74 68 65  sentence,.** the
d1d0: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20   [sqlite3_file] 
d1e0: 63 61 6e 20 73 61 66 65 6c 79 20 73 74 6f 72 65  can safely store
d1f0: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   a pointer to th
d200: 65 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 69 66  e.** filename if
d210: 20 69 74 20 6e 65 65 64 73 20 74 6f 20 72 65 6d   it needs to rem
d220: 65 6d 62 65 72 20 74 68 65 20 66 69 6c 65 6e 61  ember the filena
d230: 6d 65 20 66 6f 72 20 73 6f 6d 65 20 72 65 61 73  me for some reas
d240: 6f 6e 2e 0a 2a 2a 20 49 66 20 74 68 65 20 7a 46  on..** If the zF
d250: 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65  ilename paramete
d260: 72 20 74 6f 20 78 4f 70 65 6e 20 69 73 20 61 20  r to xOpen is a 
d270: 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65  NULL pointer the
d280: 6e 20 78 4f 70 65 6e 0a 2a 2a 20 6d 75 73 74 20  n xOpen.** must 
d290: 69 6e 76 65 6e 74 20 69 74 73 20 6f 77 6e 20 74  invent its own t
d2a0: 65 6d 70 6f 72 61 72 79 20 6e 61 6d 65 20 66 6f  emporary name fo
d2b0: 72 20 74 68 65 20 66 69 6c 65 2e 20 20 5e 57 68  r the file.  ^Wh
d2c0: 65 6e 65 76 65 72 20 74 68 65 20 0a 2a 2a 20 78  enever the .** x
d2d0: 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74  Filename paramet
d2e0: 65 72 20 69 73 20 4e 55 4c 4c 20 69 74 20 77 69  er is NULL it wi
d2f0: 6c 6c 20 61 6c 73 6f 20 62 65 20 74 68 65 20 63  ll also be the c
d300: 61 73 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20  ase that the.** 
d310: 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72 20  flags parameter 
d320: 77 69 6c 6c 20 69 6e 63 6c 75 64 65 20 5b 53 51  will include [SQ
d330: 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45  LITE_OPEN_DELETE
d340: 4f 4e 43 4c 4f 53 45 5d 2e 0a 2a 2a 0a 2a 2a 20  ONCLOSE]..**.** 
d350: 54 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65  The flags argume
d360: 6e 74 20 74 6f 20 78 4f 70 65 6e 28 29 20 69 6e  nt to xOpen() in
d370: 63 6c 75 64 65 73 20 61 6c 6c 20 62 69 74 73 20  cludes all bits 
d380: 73 65 74 20 69 6e 0a 2a 2a 20 74 68 65 20 66 6c  set in.** the fl
d390: 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ags argument to 
d3a0: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32  [sqlite3_open_v2
d3b0: 28 29 5d 2e 20 20 4f 72 20 69 66 20 5b 73 71 6c  ()].  Or if [sql
d3c0: 69 74 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20  ite3_open()].** 
d3d0: 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  or [sqlite3_open
d3e0: 31 36 28 29 5d 20 69 73 20 75 73 65 64 2c 20 74  16()] is used, t
d3f0: 68 65 6e 20 66 6c 61 67 73 20 69 6e 63 6c 75 64  hen flags includ
d400: 65 73 20 61 74 20 6c 65 61 73 74 0a 2a 2a 20 5b  es at least.** [
d410: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44  SQLITE_OPEN_READ
d420: 57 52 49 54 45 5d 20 7c 20 5b 53 51 4c 49 54 45  WRITE] | [SQLITE
d430: 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 2e 20 0a  _OPEN_CREATE]. .
d440: 2a 2a 20 49 66 20 78 4f 70 65 6e 28 29 20 6f 70  ** If xOpen() op
d450: 65 6e 73 20 61 20 66 69 6c 65 20 72 65 61 64 2d  ens a file read-
d460: 6f 6e 6c 79 20 74 68 65 6e 20 69 74 20 73 65 74  only then it set
d470: 73 20 2a 70 4f 75 74 46 6c 61 67 73 20 74 6f 0a  s *pOutFlags to.
d480: 2a 2a 20 69 6e 63 6c 75 64 65 20 5b 53 51 4c 49  ** include [SQLI
d490: 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59  TE_OPEN_READONLY
d4a0: 5d 2e 20 20 4f 74 68 65 72 20 62 69 74 73 20 69  ].  Other bits i
d4b0: 6e 20 2a 70 4f 75 74 46 6c 61 67 73 20 6d 61 79  n *pOutFlags may
d4c0: 20 62 65 20 73 65 74 2e 0a 2a 2a 0a 2a 2a 20 5e   be set..**.** ^
d4d0: 28 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 73  (SQLite will als
d4e0: 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20 74 68 65  o add one of the
d4f0: 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61 67 73   following flags
d500: 20 74 6f 20 74 68 65 20 78 4f 70 65 6e 28 29 0a   to the xOpen().
d510: 2a 2a 20 63 61 6c 6c 2c 20 64 65 70 65 6e 64 69  ** call, dependi
d520: 6e 67 20 6f 6e 20 74 68 65 20 6f 62 6a 65 63 74  ng on the object
d530: 20 62 65 69 6e 67 20 6f 70 65 6e 65 64 3a 0a 2a   being opened:.*
d540: 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ul>.** <li
d550: 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  >  [SQLITE_OPEN_
d560: 4d 41 49 4e 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e  MAIN_DB].** <li>
d570: 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d    [SQLITE_OPEN_M
d580: 41 49 4e 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20  AIN_JOURNAL].** 
d590: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50  <li>  [SQLITE_OP
d5a0: 45 4e 5f 54 45 4d 50 5f 44 42 5d 0a 2a 2a 20 3c  EN_TEMP_DB].** <
d5b0: 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45  li>  [SQLITE_OPE
d5c0: 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41 4c 5d 0a  N_TEMP_JOURNAL].
d5d0: 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45  ** <li>  [SQLITE
d5e0: 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e 54 5f  _OPEN_TRANSIENT_
d5f0: 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51  DB].** <li>  [SQ
d600: 4c 49 54 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55  LITE_OPEN_SUBJOU
d610: 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b  RNAL].** <li>  [
d620: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 53 54  SQLITE_OPEN_MAST
d630: 45 52 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c  ER_JOURNAL].** <
d640: 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45  li>  [SQLITE_OPE
d650: 4e 5f 57 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e 29  N_WAL].** </ul>)
d660: 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 6c 65  ^.**.** The file
d670: 20 49 2f 4f 20 69 6d 70 6c 65 6d 65 6e 74 61 74   I/O implementat
d680: 69 6f 6e 20 63 61 6e 20 75 73 65 20 74 68 65 20  ion can use the 
d690: 6f 62 6a 65 63 74 20 74 79 70 65 20 66 6c 61 67  object type flag
d6a0: 73 20 74 6f 0a 2a 2a 20 63 68 61 6e 67 65 20 74  s to.** change t
d6b0: 68 65 20 77 61 79 20 69 74 20 64 65 61 6c 73 20  he way it deals 
d6c0: 77 69 74 68 20 66 69 6c 65 73 2e 20 20 46 6f 72  with files.  For
d6d0: 20 65 78 61 6d 70 6c 65 2c 20 61 6e 20 61 70 70   example, an app
d6e0: 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 74 68 61 74  lication.** that
d6f0: 20 64 6f 65 73 20 6e 6f 74 20 63 61 72 65 20 61   does not care a
d700: 62 6f 75 74 20 63 72 61 73 68 20 72 65 63 6f 76  bout crash recov
d710: 65 72 79 20 6f 72 20 72 6f 6c 6c 62 61 63 6b 20  ery or rollback 
d720: 6d 69 67 68 74 20 6d 61 6b 65 0a 2a 2a 20 74 68  might make.** th
d730: 65 20 6f 70 65 6e 20 6f 66 20 61 20 6a 6f 75 72  e open of a jour
d740: 6e 61 6c 20 66 69 6c 65 20 61 20 6e 6f 2d 6f 70  nal file a no-op
d750: 2e 20 20 57 72 69 74 65 73 20 74 6f 20 74 68 69  .  Writes to thi
d760: 73 20 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c 64 0a  s journal would.
d770: 2a 2a 20 61 6c 73 6f 20 62 65 20 6e 6f 2d 6f 70  ** also be no-op
d780: 73 2c 20 61 6e 64 20 61 6e 79 20 61 74 74 65 6d  s, and any attem
d790: 70 74 20 74 6f 20 72 65 61 64 20 74 68 65 20 6a  pt to read the j
d7a0: 6f 75 72 6e 61 6c 20 77 6f 75 6c 64 20 72 65 74  ournal would ret
d7b0: 75 72 6e 0a 2a 2a 20 53 51 4c 49 54 45 5f 49 4f  urn.** SQLITE_IO
d7c0: 45 52 52 2e 20 20 4f 72 20 74 68 65 20 69 6d 70  ERR.  Or the imp
d7d0: 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 69 67 68  lementation migh
d7e0: 74 20 72 65 63 6f 67 6e 69 7a 65 20 74 68 61 74  t recognize that
d7f0: 20 61 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 66   a database.** f
d800: 69 6c 65 20 77 69 6c 6c 20 62 65 20 64 6f 69 6e  ile will be doin
d810: 67 20 70 61 67 65 2d 61 6c 69 67 6e 65 64 20 73  g page-aligned s
d820: 65 63 74 6f 72 20 72 65 61 64 73 20 61 6e 64 20  ector reads and 
d830: 77 72 69 74 65 73 20 69 6e 20 61 20 72 61 6e 64  writes in a rand
d840: 6f 6d 0a 2a 2a 20 6f 72 64 65 72 20 61 6e 64 20  om.** order and 
d850: 73 65 74 20 75 70 20 69 74 73 20 49 2f 4f 20 73  set up its I/O s
d860: 75 62 73 79 73 74 65 6d 20 61 63 63 6f 72 64 69  ubsystem accordi
d870: 6e 67 6c 79 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  ngly..**.** SQLi
d880: 74 65 20 6d 69 67 68 74 20 61 6c 73 6f 20 61 64  te might also ad
d890: 64 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c  d one of the fol
d8a0: 6c 6f 77 69 6e 67 20 66 6c 61 67 73 20 74 6f 20  lowing flags to 
d8b0: 74 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64  the xOpen method
d8c0: 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  :.**.** <ul>.** 
d8d0: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4f 50 45  <li> [SQLITE_OPE
d8e0: 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d  N_DELETEONCLOSE]
d8f0: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
d900: 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 5d  _OPEN_EXCLUSIVE]
d910: 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20  .** </ul>.**.** 
d920: 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  The [SQLITE_OPEN
d930: 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 20  _DELETEONCLOSE] 
d940: 66 6c 61 67 20 6d 65 61 6e 73 20 74 68 65 20 66  flag means the f
d950: 69 6c 65 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a  ile should be.**
d960: 20 64 65 6c 65 74 65 64 20 77 68 65 6e 20 69 74   deleted when it
d970: 20 69 73 20 63 6c 6f 73 65 64 2e 20 20 5e 54 68   is closed.  ^Th
d980: 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44  e [SQLITE_OPEN_D
d990: 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a  ELETEONCLOSE].**
d9a0: 20 77 69 6c 6c 20 62 65 20 73 65 74 20 66 6f 72   will be set for
d9b0: 20 54 45 4d 50 20 64 61 74 61 62 61 73 65 73 20   TEMP databases 
d9c0: 61 6e 64 20 74 68 65 69 72 20 6a 6f 75 72 6e 61  and their journa
d9d0: 6c 73 2c 20 74 72 61 6e 73 69 65 6e 74 0a 2a 2a  ls, transient.**
d9e0: 20 64 61 74 61 62 61 73 65 73 2c 20 61 6e 64 20   databases, and 
d9f0: 73 75 62 6a 6f 75 72 6e 61 6c 73 2e 0a 2a 2a 0a  subjournals..**.
da00: 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f  ** ^The [SQLITE_
da10: 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 5d 20  OPEN_EXCLUSIVE] 
da20: 66 6c 61 67 20 69 73 20 61 6c 77 61 79 73 20 75  flag is always u
da30: 73 65 64 20 69 6e 20 63 6f 6e 6a 75 6e 63 74 69  sed in conjuncti
da40: 6f 6e 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b  on.** with the [
da50: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41  SQLITE_OPEN_CREA
da60: 54 45 5d 20 66 6c 61 67 2c 20 77 68 69 63 68 20  TE] flag, which 
da70: 61 72 65 20 62 6f 74 68 20 64 69 72 65 63 74 6c  are both directl
da80: 79 0a 2a 2a 20 61 6e 61 6c 6f 67 6f 75 73 20 74  y.** analogous t
da90: 6f 20 74 68 65 20 4f 5f 45 58 43 4c 20 61 6e 64  o the O_EXCL and
daa0: 20 4f 5f 43 52 45 41 54 20 66 6c 61 67 73 20 6f   O_CREAT flags o
dab0: 66 20 74 68 65 20 50 4f 53 49 58 20 6f 70 65 6e  f the POSIX open
dac0: 28 29 0a 2a 2a 20 41 50 49 2e 20 20 54 68 65 20  ().** API.  The 
dad0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c  SQLITE_OPEN_EXCL
dae0: 55 53 49 56 45 20 66 6c 61 67 2c 20 77 68 65 6e  USIVE flag, when
daf0: 20 70 61 69 72 65 64 20 77 69 74 68 20 74 68 65   paired with the
db00: 20 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f 50 45 4e   .** SQLITE_OPEN
db10: 5f 43 52 45 41 54 45 2c 20 69 73 20 75 73 65 64  _CREATE, is used
db20: 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68 61   to indicate tha
db30: 74 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 61 6c  t file should al
db40: 77 61 79 73 0a 2a 2a 20 62 65 20 63 72 65 61 74  ways.** be creat
db50: 65 64 2c 20 61 6e 64 20 74 68 61 74 20 69 74 20  ed, and that it 
db60: 69 73 20 61 6e 20 65 72 72 6f 72 20 69 66 20 69  is an error if i
db70: 74 20 61 6c 72 65 61 64 79 20 65 78 69 73 74 73  t already exists
db80: 2e 0a 2a 2a 20 49 74 20 69 73 20 3c 69 3e 6e 6f  ..** It is <i>no
db90: 74 3c 2f 69 3e 20 75 73 65 64 20 74 6f 20 69 6e  t</i> used to in
dba0: 64 69 63 61 74 65 20 74 68 65 20 66 69 6c 65 20  dicate the file 
dbb0: 73 68 6f 75 6c 64 20 62 65 20 6f 70 65 6e 65 64  should be opened
dbc0: 20 0a 2a 2a 20 66 6f 72 20 65 78 63 6c 75 73 69   .** for exclusi
dbd0: 76 65 20 61 63 63 65 73 73 2e 0a 2a 2a 0a 2a 2a  ve access..**.**
dbe0: 20 5e 41 74 20 6c 65 61 73 74 20 73 7a 4f 73 46   ^At least szOsF
dbf0: 69 6c 65 20 62 79 74 65 73 20 6f 66 20 6d 65 6d  ile bytes of mem
dc00: 6f 72 79 20 61 72 65 20 61 6c 6c 6f 63 61 74 65  ory are allocate
dc10: 64 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20 74  d by SQLite.** t
dc20: 6f 20 68 6f 6c 64 20 74 68 65 20 20 5b 73 71 6c  o hold the  [sql
dc30: 69 74 65 33 5f 66 69 6c 65 5d 20 73 74 72 75 63  ite3_file] struc
dc40: 74 75 72 65 20 70 61 73 73 65 64 20 61 73 20 74  ture passed as t
dc50: 68 65 20 74 68 69 72 64 0a 2a 2a 20 61 72 67 75  he third.** argu
dc60: 6d 65 6e 74 20 74 6f 20 78 4f 70 65 6e 2e 20 20  ment to xOpen.  
dc70: 54 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64  The xOpen method
dc80: 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 74   does not have t
dc90: 6f 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 20 74 68  o.** allocate th
dca0: 65 20 73 74 72 75 63 74 75 72 65 3b 20 69 74 20  e structure; it 
dcb0: 73 68 6f 75 6c 64 20 6a 75 73 74 20 66 69 6c 6c  should just fill
dcc0: 20 69 74 20 69 6e 2e 20 20 4e 6f 74 65 20 74 68   it in.  Note th
dcd0: 61 74 0a 2a 2a 20 74 68 65 20 78 4f 70 65 6e 20  at.** the xOpen 
dce0: 6d 65 74 68 6f 64 20 6d 75 73 74 20 73 65 74 20  method must set 
dcf0: 74 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65  the sqlite3_file
dd00: 2e 70 4d 65 74 68 6f 64 73 20 74 6f 20 65 69 74  .pMethods to eit
dd10: 68 65 72 0a 2a 2a 20 61 20 76 61 6c 69 64 20 5b  her.** a valid [
dd20: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
dd30: 64 73 5d 20 6f 62 6a 65 63 74 20 6f 72 20 74 6f  ds] object or to
dd40: 20 4e 55 4c 4c 2e 20 20 78 4f 70 65 6e 20 6d 75   NULL.  xOpen mu
dd50: 73 74 20 64 6f 0a 2a 2a 20 74 68 69 73 20 65 76  st do.** this ev
dd60: 65 6e 20 69 66 20 74 68 65 20 6f 70 65 6e 20 66  en if the open f
dd70: 61 69 6c 73 2e 20 20 53 51 4c 69 74 65 20 65 78  ails.  SQLite ex
dd80: 70 65 63 74 73 20 74 68 61 74 20 74 68 65 20 73  pects that the s
dd90: 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74  qlite3_file.pMet
dda0: 68 6f 64 73 0a 2a 2a 20 65 6c 65 6d 65 6e 74 20  hods.** element 
ddb0: 77 69 6c 6c 20 62 65 20 76 61 6c 69 64 20 61 66  will be valid af
ddc0: 74 65 72 20 78 4f 70 65 6e 20 72 65 74 75 72 6e  ter xOpen return
ddd0: 73 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20  s regardless of 
dde0: 74 68 65 20 73 75 63 63 65 73 73 0a 2a 2a 20 6f  the success.** o
ddf0: 72 20 66 61 69 6c 75 72 65 20 6f 66 20 74 68 65  r failure of the
de00: 20 78 4f 70 65 6e 20 63 61 6c 6c 2e 0a 2a 2a 0a   xOpen call..**.
de10: 2a 2a 20 5b 5b 73 71 6c 69 74 65 33 5f 76 66 73  ** [[sqlite3_vfs
de20: 2e 78 41 63 63 65 73 73 5d 5d 0a 2a 2a 20 5e 54  .xAccess]].** ^T
de30: 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e  he flags argumen
de40: 74 20 74 6f 20 78 41 63 63 65 73 73 28 29 20 6d  t to xAccess() m
de50: 61 79 20 62 65 20 5b 53 51 4c 49 54 45 5f 41 43  ay be [SQLITE_AC
de60: 43 45 53 53 5f 45 58 49 53 54 53 5d 0a 2a 2a 20  CESS_EXISTS].** 
de70: 74 6f 20 74 65 73 74 20 66 6f 72 20 74 68 65 20  to test for the 
de80: 65 78 69 73 74 65 6e 63 65 20 6f 66 20 61 20 66  existence of a f
de90: 69 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f  ile, or [SQLITE_
dea0: 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 45  ACCESS_READWRITE
deb0: 5d 20 74 6f 0a 2a 2a 20 74 65 73 74 20 77 68 65  ] to.** test whe
dec0: 74 68 65 72 20 61 20 66 69 6c 65 20 69 73 20 72  ther a file is r
ded0: 65 61 64 61 62 6c 65 20 61 6e 64 20 77 72 69 74  eadable and writ
dee0: 61 62 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 54 45  able, or [SQLITE
def0: 5f 41 43 43 45 53 53 5f 52 45 41 44 5d 0a 2a 2a  _ACCESS_READ].**
df00: 20 74 6f 20 74 65 73 74 20 77 68 65 74 68 65 72   to test whether
df10: 20 61 20 66 69 6c 65 20 69 73 20 61 74 20 6c 65   a file is at le
df20: 61 73 74 20 72 65 61 64 61 62 6c 65 2e 20 20 20  ast readable.   
df30: 54 68 65 20 66 69 6c 65 20 63 61 6e 20 62 65 20  The file can be 
df40: 61 0a 2a 2a 20 64 69 72 65 63 74 6f 72 79 2e 0a  a.** directory..
df50: 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69  **.** ^SQLite wi
df60: 6c 6c 20 61 6c 77 61 79 73 20 61 6c 6c 6f 63 61  ll always alloca
df70: 74 65 20 61 74 20 6c 65 61 73 74 20 6d 78 50 61  te at least mxPa
df80: 74 68 6e 61 6d 65 2b 31 20 62 79 74 65 73 20 66  thname+1 bytes f
df90: 6f 72 20 74 68 65 0a 2a 2a 20 6f 75 74 70 75 74  or the.** output
dfa0: 20 62 75 66 66 65 72 20 78 46 75 6c 6c 50 61 74   buffer xFullPat
dfb0: 68 6e 61 6d 65 2e 20 20 54 68 65 20 65 78 61 63  hname.  The exac
dfc0: 74 20 73 69 7a 65 20 6f 66 20 74 68 65 20 6f 75  t size of the ou
dfd0: 74 70 75 74 20 62 75 66 66 65 72 0a 2a 2a 20 69  tput buffer.** i
dfe0: 73 20 61 6c 73 6f 20 70 61 73 73 65 64 20 61 73  s also passed as
dff0: 20 61 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20   a parameter to 
e000: 62 6f 74 68 20 20 6d 65 74 68 6f 64 73 2e 20 49  both  methods. I
e010: 66 20 74 68 65 20 6f 75 74 70 75 74 20 62 75 66  f the output buf
e020: 66 65 72 0a 2a 2a 20 69 73 20 6e 6f 74 20 6c 61  fer.** is not la
e030: 72 67 65 20 65 6e 6f 75 67 68 2c 20 5b 53 51 4c  rge enough, [SQL
e040: 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 73 68  ITE_CANTOPEN] sh
e050: 6f 75 6c 64 20 62 65 20 72 65 74 75 72 6e 65 64  ould be returned
e060: 2e 20 53 69 6e 63 65 20 74 68 69 73 20 69 73 0a  . Since this is.
e070: 2a 2a 20 68 61 6e 64 6c 65 64 20 61 73 20 61 20  ** handled as a 
e080: 66 61 74 61 6c 20 65 72 72 6f 72 20 62 79 20 53  fatal error by S
e090: 51 4c 69 74 65 2c 20 76 66 73 20 69 6d 70 6c 65  QLite, vfs imple
e0a0: 6d 65 6e 74 61 74 69 6f 6e 73 20 73 68 6f 75 6c  mentations shoul
e0b0: 64 20 65 6e 64 65 61 76 6f 72 0a 2a 2a 20 74 6f  d endeavor.** to
e0c0: 20 70 72 65 76 65 6e 74 20 74 68 69 73 20 62 79   prevent this by
e0d0: 20 73 65 74 74 69 6e 67 20 6d 78 50 61 74 68 6e   setting mxPathn
e0e0: 61 6d 65 20 74 6f 20 61 20 73 75 66 66 69 63 69  ame to a suffici
e0f0: 65 6e 74 6c 79 20 6c 61 72 67 65 20 76 61 6c 75  ently large valu
e100: 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 52 61  e..**.** The xRa
e110: 6e 64 6f 6d 6e 65 73 73 28 29 2c 20 78 53 6c 65  ndomness(), xSle
e120: 65 70 28 29 2c 20 78 43 75 72 72 65 6e 74 54 69  ep(), xCurrentTi
e130: 6d 65 28 29 2c 20 61 6e 64 20 78 43 75 72 72 65  me(), and xCurre
e140: 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 0a 2a 2a  ntTimeInt64().**
e150: 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20   interfaces are 
e160: 6e 6f 74 20 73 74 72 69 63 74 6c 79 20 61 20 70  not strictly a p
e170: 61 72 74 20 6f 66 20 74 68 65 20 66 69 6c 65 73  art of the files
e180: 79 73 74 65 6d 2c 20 62 75 74 20 74 68 65 79 20  ystem, but they 
e190: 61 72 65 0a 2a 2a 20 69 6e 63 6c 75 64 65 64 20  are.** included 
e1a0: 69 6e 20 74 68 65 20 56 46 53 20 73 74 72 75 63  in the VFS struc
e1b0: 74 75 72 65 20 66 6f 72 20 63 6f 6d 70 6c 65 74  ture for complet
e1c0: 65 6e 65 73 73 2e 0a 2a 2a 20 54 68 65 20 78 52  eness..** The xR
e1d0: 61 6e 64 6f 6d 6e 65 73 73 28 29 20 66 75 6e 63  andomness() func
e1e0: 74 69 6f 6e 20 61 74 74 65 6d 70 74 73 20 74 6f  tion attempts to
e1f0: 20 72 65 74 75 72 6e 20 6e 42 79 74 65 73 20 62   return nBytes b
e200: 79 74 65 73 0a 2a 2a 20 6f 66 20 67 6f 6f 64 2d  ytes.** of good-
e210: 71 75 61 6c 69 74 79 20 72 61 6e 64 6f 6d 6e 65  quality randomne
e220: 73 73 20 69 6e 74 6f 20 7a 4f 75 74 2e 20 20 54  ss into zOut.  T
e230: 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20  he return value 
e240: 69 73 0a 2a 2a 20 74 68 65 20 61 63 74 75 61 6c  is.** the actual
e250: 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
e260: 20 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20 6f   of randomness o
e270: 62 74 61 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 20  btained..** The 
e280: 78 53 6c 65 65 70 28 29 20 6d 65 74 68 6f 64 20  xSleep() method 
e290: 63 61 75 73 65 73 20 74 68 65 20 63 61 6c 6c 69  causes the calli
e2a0: 6e 67 20 74 68 72 65 61 64 20 74 6f 20 73 6c 65  ng thread to sle
e2b0: 65 70 20 66 6f 72 20 61 74 0a 2a 2a 20 6c 65 61  ep for at.** lea
e2c0: 73 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  st the number of
e2d0: 20 6d 69 63 72 6f 73 65 63 6f 6e 64 73 20 67 69   microseconds gi
e2e0: 76 65 6e 2e 20 20 5e 54 68 65 20 78 43 75 72 72  ven.  ^The xCurr
e2f0: 65 6e 74 54 69 6d 65 28 29 0a 2a 2a 20 6d 65 74  entTime().** met
e300: 68 6f 64 20 72 65 74 75 72 6e 73 20 61 20 4a 75  hod returns a Ju
e310: 6c 69 61 6e 20 44 61 79 20 4e 75 6d 62 65 72 20  lian Day Number 
e320: 66 6f 72 20 74 68 65 20 63 75 72 72 65 6e 74 20  for the current 
e330: 64 61 74 65 20 61 6e 64 20 74 69 6d 65 20 61 73  date and time as
e340: 0a 2a 2a 20 61 20 66 6c 6f 61 74 69 6e 67 20 70  .** a floating p
e350: 6f 69 6e 74 20 76 61 6c 75 65 2e 0a 2a 2a 20 5e  oint value..** ^
e360: 54 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d 65  The xCurrentTime
e370: 49 6e 74 36 34 28 29 20 6d 65 74 68 6f 64 20 72  Int64() method r
e380: 65 74 75 72 6e 73 2c 20 61 73 20 61 6e 20 69 6e  eturns, as an in
e390: 74 65 67 65 72 2c 20 74 68 65 20 4a 75 6c 69 61  teger, the Julia
e3a0: 6e 0a 2a 2a 20 44 61 79 20 4e 75 6d 62 65 72 20  n.** Day Number 
e3b0: 6d 75 6c 74 69 70 6c 69 65 64 20 62 79 20 38 36  multiplied by 86
e3c0: 34 30 30 30 30 30 20 28 74 68 65 20 6e 75 6d 62  400000 (the numb
e3d0: 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e  er of millisecon
e3e0: 64 73 20 69 6e 20 0a 2a 2a 20 61 20 32 34 2d 68  ds in .** a 24-h
e3f0: 6f 75 72 20 64 61 79 29 2e 20 20 0a 2a 2a 20 5e  our day).  .** ^
e400: 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20  SQLite will use 
e410: 74 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d 65  the xCurrentTime
e420: 49 6e 74 36 34 28 29 20 6d 65 74 68 6f 64 20 74  Int64() method t
e430: 6f 20 67 65 74 20 74 68 65 20 63 75 72 72 65 6e  o get the curren
e440: 74 0a 2a 2a 20 64 61 74 65 20 61 6e 64 20 74 69  t.** date and ti
e450: 6d 65 20 69 66 20 74 68 61 74 20 6d 65 74 68 6f  me if that metho
e460: 64 20 69 73 20 61 76 61 69 6c 61 62 6c 65 20 28  d is available (
e470: 69 66 20 69 56 65 72 73 69 6f 6e 20 69 73 20 32  if iVersion is 2
e480: 20 6f 72 20 0a 2a 2a 20 67 72 65 61 74 65 72 20   or .** greater 
e490: 61 6e 64 20 74 68 65 20 66 75 6e 63 74 69 6f 6e  and the function
e4a0: 20 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74 20   pointer is not 
e4b0: 4e 55 4c 4c 29 20 61 6e 64 20 77 69 6c 6c 20 66  NULL) and will f
e4c0: 61 6c 6c 20 62 61 63 6b 0a 2a 2a 20 74 6f 20 78  all back.** to x
e4d0: 43 75 72 72 65 6e 74 54 69 6d 65 28 29 20 69 66  CurrentTime() if
e4e0: 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e 74   xCurrentTimeInt
e4f0: 36 34 28 29 20 69 73 20 75 6e 61 76 61 69 6c 61  64() is unavaila
e500: 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ble..**.** ^The 
e510: 78 53 65 74 53 79 73 74 65 6d 43 61 6c 6c 28 29  xSetSystemCall()
e520: 2c 20 78 47 65 74 53 79 73 74 65 6d 43 61 6c 6c  , xGetSystemCall
e530: 28 29 2c 20 61 6e 64 20 78 4e 65 73 74 53 79 73  (), and xNestSys
e540: 74 65 6d 43 61 6c 6c 28 29 20 69 6e 74 65 72 66  temCall() interf
e550: 61 63 65 73 0a 2a 2a 20 61 72 65 20 6e 6f 74 20  aces.** are not 
e560: 75 73 65 64 20 62 79 20 74 68 65 20 53 51 4c 69  used by the SQLi
e570: 74 65 20 63 6f 72 65 2e 20 20 54 68 65 73 65 20  te core.  These 
e580: 6f 70 74 69 6f 6e 61 6c 20 69 6e 74 65 72 66 61  optional interfa
e590: 63 65 73 20 61 72 65 20 70 72 6f 76 69 64 65 64  ces are provided
e5a0: 0a 2a 2a 20 62 79 20 73 6f 6d 65 20 56 46 53 65  .** by some VFSe
e5b0: 73 20 74 6f 20 66 61 63 69 6c 69 74 61 74 65 20  s to facilitate 
e5c0: 74 65 73 74 69 6e 67 20 6f 66 20 74 68 65 20 56  testing of the V
e5d0: 46 53 20 63 6f 64 65 2e 20 42 79 20 6f 76 65 72  FS code. By over
e5e0: 72 69 64 69 6e 67 20 0a 2a 2a 20 73 79 73 74 65  riding .** syste
e5f0: 6d 20 63 61 6c 6c 73 20 77 69 74 68 20 66 75 6e  m calls with fun
e600: 63 74 69 6f 6e 73 20 75 6e 64 65 72 20 69 74 73  ctions under its
e610: 20 63 6f 6e 74 72 6f 6c 2c 20 61 20 74 65 73 74   control, a test
e620: 20 70 72 6f 67 72 61 6d 20 63 61 6e 0a 2a 2a 20   program can.** 
e630: 73 69 6d 75 6c 61 74 65 20 66 61 75 6c 74 73 20  simulate faults 
e640: 61 6e 64 20 65 72 72 6f 72 20 63 6f 6e 64 69 74  and error condit
e650: 69 6f 6e 73 20 74 68 61 74 20 77 6f 75 6c 64 20  ions that would 
e660: 6f 74 68 65 72 77 69 73 65 20 62 65 20 64 69 66  otherwise be dif
e670: 66 69 63 75 6c 74 0a 2a 2a 20 6f 72 20 69 6d 70  ficult.** or imp
e680: 6f 73 73 69 62 6c 65 20 74 6f 20 69 6e 64 75 63  ossible to induc
e690: 65 2e 20 20 54 68 65 20 73 65 74 20 6f 66 20 73  e.  The set of s
e6a0: 79 73 74 65 6d 20 63 61 6c 6c 73 20 74 68 61 74  ystem calls that
e6b0: 20 63 61 6e 20 62 65 20 6f 76 65 72 72 69 64 64   can be overridd
e6c0: 65 6e 0a 2a 2a 20 76 61 72 69 65 73 20 66 72 6f  en.** varies fro
e6d0: 6d 20 6f 6e 65 20 56 46 53 20 74 6f 20 61 6e 6f  m one VFS to ano
e6e0: 74 68 65 72 2c 20 61 6e 64 20 66 72 6f 6d 20 6f  ther, and from o
e6f0: 6e 65 20 76 65 72 73 69 6f 6e 20 6f 66 20 74 68  ne version of th
e700: 65 20 73 61 6d 65 20 56 46 53 20 74 6f 20 74 68  e same VFS to th
e710: 65 0a 2a 2a 20 6e 65 78 74 2e 20 20 41 70 70 6c  e.** next.  Appl
e720: 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 75 73  ications that us
e730: 65 20 74 68 65 73 65 20 69 6e 74 65 72 66 61 63  e these interfac
e740: 65 73 20 6d 75 73 74 20 62 65 20 70 72 65 70 61  es must be prepa
e750: 72 65 64 20 66 6f 72 20 61 6e 79 0a 2a 2a 20 6f  red for any.** o
e760: 72 20 61 6c 6c 20 6f 66 20 74 68 65 73 65 20 69  r all of these i
e770: 6e 74 65 72 66 61 63 65 73 20 74 6f 20 62 65 20  nterfaces to be 
e780: 4e 55 4c 4c 20 6f 72 20 66 6f 72 20 74 68 65 69  NULL or for thei
e790: 72 20 62 65 68 61 76 69 6f 72 20 74 6f 20 63 68  r behavior to ch
e7a0: 61 6e 67 65 0a 2a 2a 20 66 72 6f 6d 20 6f 6e 65  ange.** from one
e7b0: 20 72 65 6c 65 61 73 65 20 74 6f 20 74 68 65 20   release to the 
e7c0: 6e 65 78 74 2e 20 20 41 70 70 6c 69 63 61 74 69  next.  Applicati
e7d0: 6f 6e 73 20 6d 75 73 74 20 6e 6f 74 20 61 74 74  ons must not att
e7e0: 65 6d 70 74 20 74 6f 20 61 63 63 65 73 73 0a 2a  empt to access.*
e7f0: 2a 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20 6d  * any of these m
e800: 65 74 68 6f 64 73 20 69 66 20 74 68 65 20 69 56  ethods if the iV
e810: 65 72 73 69 6f 6e 20 6f 66 20 74 68 65 20 56 46  ersion of the VF
e820: 53 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 33  S is less than 3
e830: 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72  ..*/.typedef str
e840: 75 63 74 20 73 71 6c 69 74 65 33 5f 76 66 73 20  uct sqlite3_vfs 
e850: 73 71 6c 69 74 65 33 5f 76 66 73 3b 0a 74 79 70  sqlite3_vfs;.typ
e860: 65 64 65 66 20 76 6f 69 64 20 28 2a 73 71 6c 69  edef void (*sqli
e870: 74 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72 29  te3_syscall_ptr)
e880: 28 76 6f 69 64 29 3b 0a 73 74 72 75 63 74 20 73  (void);.struct s
e890: 71 6c 69 74 65 33 5f 76 66 73 20 7b 0a 20 20 69  qlite3_vfs {.  i
e8a0: 6e 74 20 69 56 65 72 73 69 6f 6e 3b 20 20 20 20  nt iVersion;    
e8b0: 20 20 20 20 20 20 20 20 2f 2a 20 53 74 72 75 63          /* Struc
e8c0: 74 75 72 65 20 76 65 72 73 69 6f 6e 20 6e 75 6d  ture version num
e8d0: 62 65 72 20 28 63 75 72 72 65 6e 74 6c 79 20 33  ber (currently 3
e8e0: 29 20 2a 2f 0a 20 20 69 6e 74 20 73 7a 4f 73 46  ) */.  int szOsF
e8f0: 69 6c 65 3b 20 20 20 20 20 20 20 20 20 20 20 20  ile;            
e900: 2f 2a 20 53 69 7a 65 20 6f 66 20 73 75 62 63 6c  /* Size of subcl
e910: 61 73 73 65 64 20 73 71 6c 69 74 65 33 5f 66 69  assed sqlite3_fi
e920: 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 6d 78 50 61  le */.  int mxPa
e930: 74 68 6e 61 6d 65 3b 20 20 20 20 20 20 20 20 20  thname;         
e940: 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 66 69 6c 65   /* Maximum file
e950: 20 70 61 74 68 6e 61 6d 65 20 6c 65 6e 67 74 68   pathname length
e960: 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 76 66   */.  sqlite3_vf
e970: 73 20 2a 70 4e 65 78 74 3b 20 20 20 20 20 20 2f  s *pNext;      /
e980: 2a 20 4e 65 78 74 20 72 65 67 69 73 74 65 72 65  * Next registere
e990: 64 20 56 46 53 20 2a 2f 0a 20 20 63 6f 6e 73 74  d VFS */.  const
e9a0: 20 63 68 61 72 20 2a 7a 4e 61 6d 65 3b 20 20 20   char *zName;   
e9b0: 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74      /* Name of t
e9c0: 68 69 73 20 76 69 72 74 75 61 6c 20 66 69 6c 65  his virtual file
e9d0: 20 73 79 73 74 65 6d 20 2a 2f 0a 20 20 76 6f 69   system */.  voi
e9e0: 64 20 2a 70 41 70 70 44 61 74 61 3b 20 20 20 20  d *pAppData;    
e9f0: 20 20 20 20 20 20 2f 2a 20 50 6f 69 6e 74 65 72        /* Pointer
ea00: 20 74 6f 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d   to application-
ea10: 73 70 65 63 69 66 69 63 20 64 61 74 61 20 2a 2f  specific data */
ea20: 0a 20 20 69 6e 74 20 28 2a 78 4f 70 65 6e 29 28  .  int (*xOpen)(
ea30: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f  sqlite3_vfs*, co
ea40: 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c  nst char *zName,
ea50: 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 0a   sqlite3_file*,.
ea60: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 69                 i
ea70: 6e 74 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a 70  nt flags, int *p
ea80: 4f 75 74 46 6c 61 67 73 29 3b 0a 20 20 69 6e 74  OutFlags);.  int
ea90: 20 28 2a 78 44 65 6c 65 74 65 29 28 73 71 6c 69   (*xDelete)(sqli
eaa0: 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20  te3_vfs*, const 
eab0: 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74  char *zName, int
eac0: 20 73 79 6e 63 44 69 72 29 3b 0a 20 20 69 6e 74   syncDir);.  int
ead0: 20 28 2a 78 41 63 63 65 73 73 29 28 73 71 6c 69   (*xAccess)(sqli
eae0: 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20  te3_vfs*, const 
eaf0: 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74  char *zName, int
eb00: 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a 70 52 65   flags, int *pRe
eb10: 73 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78  sOut);.  int (*x
eb20: 46 75 6c 6c 50 61 74 68 6e 61 6d 65 29 28 73 71  FullPathname)(sq
eb30: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73  lite3_vfs*, cons
eb40: 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69  t char *zName, i
eb50: 6e 74 20 6e 4f 75 74 2c 20 63 68 61 72 20 2a 7a  nt nOut, char *z
eb60: 4f 75 74 29 3b 0a 20 20 76 6f 69 64 20 2a 28 2a  Out);.  void *(*
eb70: 78 44 6c 4f 70 65 6e 29 28 73 71 6c 69 74 65 33  xDlOpen)(sqlite3
eb80: 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61  _vfs*, const cha
eb90: 72 20 2a 7a 46 69 6c 65 6e 61 6d 65 29 3b 0a 20  r *zFilename);. 
eba0: 20 76 6f 69 64 20 28 2a 78 44 6c 45 72 72 6f 72   void (*xDlError
ebb0: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
ebc0: 69 6e 74 20 6e 42 79 74 65 2c 20 63 68 61 72 20  int nByte, char 
ebd0: 2a 7a 45 72 72 4d 73 67 29 3b 0a 20 20 76 6f 69  *zErrMsg);.  voi
ebe0: 64 20 28 2a 28 2a 78 44 6c 53 79 6d 29 28 73 71  d (*(*xDlSym)(sq
ebf0: 6c 69 74 65 33 5f 76 66 73 2a 2c 76 6f 69 64 2a  lite3_vfs*,void*
ec00: 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53  , const char *zS
ec10: 79 6d 62 6f 6c 29 29 28 76 6f 69 64 29 3b 0a 20  ymbol))(void);. 
ec20: 20 76 6f 69 64 20 28 2a 78 44 6c 43 6c 6f 73 65   void (*xDlClose
ec30: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
ec40: 76 6f 69 64 2a 29 3b 0a 20 20 69 6e 74 20 28 2a  void*);.  int (*
ec50: 78 52 61 6e 64 6f 6d 6e 65 73 73 29 28 73 71 6c  xRandomness)(sql
ec60: 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6e  ite3_vfs*, int n
ec70: 42 79 74 65 2c 20 63 68 61 72 20 2a 7a 4f 75 74  Byte, char *zOut
ec80: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 6c 65 65  );.  int (*xSlee
ec90: 70 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  p)(sqlite3_vfs*,
eca0: 20 69 6e 74 20 6d 69 63 72 6f 73 65 63 6f 6e 64   int microsecond
ecb0: 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 75 72  s);.  int (*xCur
ecc0: 72 65 6e 74 54 69 6d 65 29 28 73 71 6c 69 74 65  rentTime)(sqlite
ecd0: 33 5f 76 66 73 2a 2c 20 64 6f 75 62 6c 65 2a 29  3_vfs*, double*)
ece0: 3b 0a 20 20 69 6e 74 20 28 2a 78 47 65 74 4c 61  ;.  int (*xGetLa
ecf0: 73 74 45 72 72 6f 72 29 28 73 71 6c 69 74 65 33  stError)(sqlite3
ed00: 5f 76 66 73 2a 2c 20 69 6e 74 2c 20 63 68 61 72  _vfs*, int, char
ed10: 20 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54   *);.  /*.  ** T
ed20: 68 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65  he methods above
ed30: 20 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e 20   are in version 
ed40: 31 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 5f  1 of the sqlite_
ed50: 76 66 73 20 6f 62 6a 65 63 74 0a 20 20 2a 2a 20  vfs object.  ** 
ed60: 64 65 66 69 6e 69 74 69 6f 6e 2e 20 20 54 68 6f  definition.  Tho
ed70: 73 65 20 74 68 61 74 20 66 6f 6c 6c 6f 77 20 61  se that follow a
ed80: 72 65 20 61 64 64 65 64 20 69 6e 20 76 65 72 73  re added in vers
ed90: 69 6f 6e 20 32 20 6f 72 20 6c 61 74 65 72 0a 20  ion 2 or later. 
eda0: 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 43 75 72   */.  int (*xCur
edb0: 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 29 28 73  rentTimeInt64)(s
edc0: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 73 71 6c  qlite3_vfs*, sql
edd0: 69 74 65 33 5f 69 6e 74 36 34 2a 29 3b 0a 20 20  ite3_int64*);.  
ede0: 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 68  /*.  ** The meth
edf0: 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 69 6e  ods above are in
ee00: 20 76 65 72 73 69 6f 6e 73 20 31 20 61 6e 64 20   versions 1 and 
ee10: 32 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 5f  2 of the sqlite_
ee20: 76 66 73 20 6f 62 6a 65 63 74 2e 0a 20 20 2a 2a  vfs object..  **
ee30: 20 54 68 6f 73 65 20 62 65 6c 6f 77 20 61 72 65   Those below are
ee40: 20 66 6f 72 20 76 65 72 73 69 6f 6e 20 33 20 61   for version 3 a
ee50: 6e 64 20 67 72 65 61 74 65 72 2e 0a 20 20 2a 2f  nd greater..  */
ee60: 0a 20 20 69 6e 74 20 28 2a 78 53 65 74 53 79 73  .  int (*xSetSys
ee70: 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65 33  temCall)(sqlite3
ee80: 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61  _vfs*, const cha
ee90: 72 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69 74 65  r *zName, sqlite
eea0: 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72 29 3b 0a  3_syscall_ptr);.
eeb0: 20 20 73 71 6c 69 74 65 33 5f 73 79 73 63 61 6c    sqlite3_syscal
eec0: 6c 5f 70 74 72 20 28 2a 78 47 65 74 53 79 73 74  l_ptr (*xGetSyst
eed0: 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65 33 5f  emCall)(sqlite3_
eee0: 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  vfs*, const char
eef0: 20 2a 7a 4e 61 6d 65 29 3b 0a 20 20 63 6f 6e 73   *zName);.  cons
ef00: 74 20 63 68 61 72 20 2a 28 2a 78 4e 65 78 74 53  t char *(*xNextS
ef10: 79 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74  ystemCall)(sqlit
ef20: 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63  e3_vfs*, const c
ef30: 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 20 20 2f  har *zName);.  /
ef40: 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 68 6f  *.  ** The metho
ef50: 64 73 20 61 62 6f 76 65 20 61 72 65 20 69 6e 20  ds above are in 
ef60: 76 65 72 73 69 6f 6e 73 20 31 20 74 68 72 6f 75  versions 1 throu
ef70: 67 68 20 33 20 6f 66 20 74 68 65 20 73 71 6c 69  gh 3 of the sqli
ef80: 74 65 5f 76 66 73 20 6f 62 6a 65 63 74 2e 0a 20  te_vfs object.. 
ef90: 20 2a 2a 20 4e 65 77 20 66 69 65 6c 64 73 20 6d   ** New fields m
efa0: 61 79 20 62 65 20 61 70 70 65 6e 64 65 64 20 69  ay be appended i
efb0: 6e 20 66 75 74 75 72 65 20 76 65 72 73 69 6f 6e  n future version
efc0: 73 2e 20 20 54 68 65 20 69 56 65 72 73 69 6f 6e  s.  The iVersion
efd0: 0a 20 20 2a 2a 20 76 61 6c 75 65 20 77 69 6c 6c  .  ** value will
efe0: 20 69 6e 63 72 65 6d 65 6e 74 20 77 68 65 6e 65   increment whene
eff0: 76 65 72 20 74 68 69 73 20 68 61 70 70 65 6e 73  ver this happens
f000: 2e 20 0a 20 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a  . .  */.};../*.*
f010: 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6c 61 67  * CAPI3REF: Flag
f020: 73 20 66 6f 72 20 74 68 65 20 78 41 63 63 65 73  s for the xAcces
f030: 73 20 56 46 53 20 6d 65 74 68 6f 64 0a 2a 2a 0a  s VFS method.**.
f040: 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 67 65 72  ** These integer
f050: 20 63 6f 6e 73 74 61 6e 74 73 20 63 61 6e 20 62   constants can b
f060: 65 20 75 73 65 64 20 61 73 20 74 68 65 20 74 68  e used as the th
f070: 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ird parameter to
f080: 0a 2a 2a 20 74 68 65 20 78 41 63 63 65 73 73 20  .** the xAccess 
f090: 6d 65 74 68 6f 64 20 6f 66 20 61 6e 20 5b 73 71  method of an [sq
f0a0: 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63  lite3_vfs] objec
f0b0: 74 2e 20 20 54 68 65 79 20 64 65 74 65 72 6d 69  t.  They determi
f0c0: 6e 65 0a 2a 2a 20 77 68 61 74 20 6b 69 6e 64 20  ne.** what kind 
f0d0: 6f 66 20 70 65 72 6d 69 73 73 69 6f 6e 73 20 74  of permissions t
f0e0: 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f  he xAccess metho
f0f0: 64 20 69 73 20 6c 6f 6f 6b 69 6e 67 20 66 6f 72  d is looking for
f100: 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45  ..** With SQLITE
f110: 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53 2c 20  _ACCESS_EXISTS, 
f120: 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68  the xAccess meth
f130: 6f 64 0a 2a 2a 20 73 69 6d 70 6c 79 20 63 68 65  od.** simply che
f140: 63 6b 73 20 77 68 65 74 68 65 72 20 74 68 65 20  cks whether the 
f150: 66 69 6c 65 20 65 78 69 73 74 73 2e 0a 2a 2a 20  file exists..** 
f160: 57 69 74 68 20 53 51 4c 49 54 45 5f 41 43 43 45  With SQLITE_ACCE
f170: 53 53 5f 52 45 41 44 57 52 49 54 45 2c 20 74 68  SS_READWRITE, th
f180: 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64  e xAccess method
f190: 0a 2a 2a 20 63 68 65 63 6b 73 20 77 68 65 74 68  .** checks wheth
f1a0: 65 72 20 74 68 65 20 6e 61 6d 65 64 20 64 69 72  er the named dir
f1b0: 65 63 74 6f 72 79 20 69 73 20 62 6f 74 68 20 72  ectory is both r
f1c0: 65 61 64 61 62 6c 65 20 61 6e 64 20 77 72 69 74  eadable and writ
f1d0: 61 62 6c 65 0a 2a 2a 20 28 69 6e 20 6f 74 68 65  able.** (in othe
f1e0: 72 20 77 6f 72 64 73 2c 20 69 66 20 66 69 6c 65  r words, if file
f1f0: 73 20 63 61 6e 20 62 65 20 61 64 64 65 64 2c 20  s can be added, 
f200: 72 65 6d 6f 76 65 64 2c 20 61 6e 64 20 72 65 6e  removed, and ren
f210: 61 6d 65 64 20 77 69 74 68 69 6e 0a 2a 2a 20 74  amed within.** t
f220: 68 65 20 64 69 72 65 63 74 6f 72 79 29 2e 0a 2a  he directory)..*
f230: 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 41 43 43  * The SQLITE_ACC
f240: 45 53 53 5f 52 45 41 44 57 52 49 54 45 20 63 6f  ESS_READWRITE co
f250: 6e 73 74 61 6e 74 20 69 73 20 63 75 72 72 65 6e  nstant is curren
f260: 74 6c 79 20 75 73 65 64 20 6f 6e 6c 79 20 62 79  tly used only by
f270: 20 74 68 65 0a 2a 2a 20 5b 74 65 6d 70 5f 73 74   the.** [temp_st
f280: 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20 70 72  ore_directory pr
f290: 61 67 6d 61 5d 2c 20 74 68 6f 75 67 68 20 74 68  agma], though th
f2a0: 69 73 20 63 6f 75 6c 64 20 63 68 61 6e 67 65 20  is could change 
f2b0: 69 6e 20 61 20 66 75 74 75 72 65 0a 2a 2a 20 72  in a future.** r
f2c0: 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65  elease of SQLite
f2d0: 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45  ..** With SQLITE
f2e0: 5f 41 43 43 45 53 53 5f 52 45 41 44 2c 20 74 68  _ACCESS_READ, th
f2f0: 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64  e xAccess method
f300: 0a 2a 2a 20 63 68 65 63 6b 73 20 77 68 65 74 68  .** checks wheth
f310: 65 72 20 74 68 65 20 66 69 6c 65 20 69 73 20 72  er the file is r
f320: 65 61 64 61 62 6c 65 2e 20 20 54 68 65 20 53 51  eadable.  The SQ
f330: 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44  LITE_ACCESS_READ
f340: 20 63 6f 6e 73 74 61 6e 74 20 69 73 0a 2a 2a 20   constant is.** 
f350: 63 75 72 72 65 6e 74 6c 79 20 75 6e 75 73 65 64  currently unused
f360: 2c 20 74 68 6f 75 67 68 20 69 74 20 6d 69 67 68  , though it migh
f370: 74 20 62 65 20 75 73 65 64 20 69 6e 20 61 20 66  t be used in a f
f380: 75 74 75 72 65 20 72 65 6c 65 61 73 65 20 6f 66  uture release of
f390: 0a 2a 2a 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 23  .** SQLite..*/.#
f3a0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43  define SQLITE_AC
f3b0: 43 45 53 53 5f 45 58 49 53 54 53 20 20 20 20 30  CESS_EXISTS    0
f3c0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
f3d0: 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 45  ACCESS_READWRITE
f3e0: 20 31 20 20 20 2f 2a 20 55 73 65 64 20 62 79 20   1   /* Used by 
f3f0: 50 52 41 47 4d 41 20 74 65 6d 70 5f 73 74 6f 72  PRAGMA temp_stor
f400: 65 5f 64 69 72 65 63 74 6f 72 79 20 2a 2f 0a 23  e_directory */.#
f410: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43  define SQLITE_AC
f420: 43 45 53 53 5f 52 45 41 44 20 20 20 20 20 20 32  CESS_READ      2
f430: 20 20 20 2f 2a 20 55 6e 75 73 65 64 20 2a 2f 0a     /* Unused */.
f440: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
f450: 20 46 6c 61 67 73 20 66 6f 72 20 74 68 65 20 78   Flags for the x
f460: 53 68 6d 4c 6f 63 6b 20 56 46 53 20 6d 65 74 68  ShmLock VFS meth
f470: 6f 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69  od.**.** These i
f480: 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73  nteger constants
f490: 20 64 65 66 69 6e 65 20 74 68 65 20 76 61 72 69   define the vari
f4a0: 6f 75 73 20 6c 6f 63 6b 69 6e 67 20 6f 70 65 72  ous locking oper
f4b0: 61 74 69 6f 6e 73 0a 2a 2a 20 61 6c 6c 6f 77 65  ations.** allowe
f4c0: 64 20 62 79 20 74 68 65 20 78 53 68 6d 4c 6f 63  d by the xShmLoc
f4d0: 6b 20 6d 65 74 68 6f 64 20 6f 66 20 5b 73 71 6c  k method of [sql
f4e0: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d  ite3_io_methods]
f4f0: 2e 20 20 54 68 65 0a 2a 2a 20 66 6f 6c 6c 6f 77  .  The.** follow
f500: 69 6e 67 20 61 72 65 20 74 68 65 20 6f 6e 6c 79  ing are the only
f510: 20 6c 65 67 61 6c 20 63 6f 6d 62 69 6e 61 74 69   legal combinati
f520: 6f 6e 73 20 6f 66 20 66 6c 61 67 73 20 74 6f 20  ons of flags to 
f530: 74 68 65 0a 2a 2a 20 78 53 68 6d 4c 6f 63 6b 20  the.** xShmLock 
f540: 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75  method:.**.** <u
f550: 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49  l>.** <li>  SQLI
f560: 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 7c 20 53 51  TE_SHM_LOCK | SQ
f570: 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52 45 44 0a  LITE_SHM_SHARED.
f580: 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f  ** <li>  SQLITE_
f590: 53 48 4d 5f 4c 4f 43 4b 20 7c 20 53 51 4c 49 54  SHM_LOCK | SQLIT
f5a0: 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 45 0a  E_SHM_EXCLUSIVE.
f5b0: 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f  ** <li>  SQLITE_
f5c0: 53 48 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51 4c  SHM_UNLOCK | SQL
f5d0: 49 54 45 5f 53 48 4d 5f 53 48 41 52 45 44 0a 2a  ITE_SHM_SHARED.*
f5e0: 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53  * <li>  SQLITE_S
f5f0: 48 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51 4c 49  HM_UNLOCK | SQLI
f600: 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 45  TE_SHM_EXCLUSIVE
f610: 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20  .** </ul>.**.** 
f620: 57 68 65 6e 20 75 6e 6c 6f 63 6b 69 6e 67 2c 20  When unlocking, 
f630: 74 68 65 20 73 61 6d 65 20 53 48 41 52 45 44 20  the same SHARED 
f640: 6f 72 20 45 58 43 4c 55 53 49 56 45 20 66 6c 61  or EXCLUSIVE fla
f650: 67 20 6d 75 73 74 20 62 65 20 73 75 70 70 6c 69  g must be suppli
f660: 65 64 20 61 73 0a 2a 2a 20 77 61 73 20 67 69 76  ed as.** was giv
f670: 65 6e 20 6f 6e 20 74 68 65 20 63 6f 72 72 65 73  en on the corres
f680: 70 6f 6e 64 69 6e 67 20 6c 6f 63 6b 2e 20 20 0a  ponding lock.  .
f690: 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 68 6d 4c 6f  **.** The xShmLo
f6a0: 63 6b 20 6d 65 74 68 6f 64 20 63 61 6e 20 74 72  ck method can tr
f6b0: 61 6e 73 69 74 69 6f 6e 20 62 65 74 77 65 65 6e  ansition between
f6c0: 20 75 6e 6c 6f 63 6b 65 64 20 61 6e 64 20 53 48   unlocked and SH
f6d0: 41 52 45 44 20 6f 72 0a 2a 2a 20 62 65 74 77 65  ARED or.** betwe
f6e0: 65 6e 20 75 6e 6c 6f 63 6b 65 64 20 61 6e 64 20  en unlocked and 
f6f0: 45 58 43 4c 55 53 49 56 45 2e 20 20 49 74 20 63  EXCLUSIVE.  It c
f700: 61 6e 6e 6f 74 20 74 72 61 6e 73 69 74 69 6f 6e  annot transition
f710: 20 62 65 74 77 65 65 6e 20 53 48 41 52 45 44 0a   between SHARED.
f720: 2a 2a 20 61 6e 64 20 45 58 43 4c 55 53 49 56 45  ** and EXCLUSIVE
f730: 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
f740: 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 20  ITE_SHM_UNLOCK  
f750: 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53       1.#define S
f760: 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 20  QLITE_SHM_LOCK  
f770: 20 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65         2.#define
f780: 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52   SQLITE_SHM_SHAR
f790: 45 44 20 20 20 20 20 20 20 34 0a 23 64 65 66 69  ED       4.#defi
f7a0: 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45 58  ne SQLITE_SHM_EX
f7b0: 43 4c 55 53 49 56 45 20 20 20 20 38 0a 0a 2f 2a  CLUSIVE    8../*
f7c0: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 61  .** CAPI3REF: Ma
f7d0: 78 69 6d 75 6d 20 78 53 68 6d 4c 6f 63 6b 20 69  ximum xShmLock i
f7e0: 6e 64 65 78 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78  ndex.**.** The x
f7f0: 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 6f  ShmLock method o
f800: 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  n [sqlite3_io_me
f810: 74 68 6f 64 73 5d 20 6d 61 79 20 75 73 65 20 76  thods] may use v
f820: 61 6c 75 65 73 0a 2a 2a 20 62 65 74 77 65 65 6e  alues.** between
f830: 20 30 20 61 6e 64 20 74 68 69 73 20 75 70 70 65   0 and this uppe
f840: 72 20 62 6f 75 6e 64 20 61 73 20 69 74 73 20 22  r bound as its "
f850: 6f 66 66 73 65 74 22 20 61 72 67 75 6d 65 6e 74  offset" argument
f860: 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20  ..** The SQLite 
f870: 63 6f 72 65 20 77 69 6c 6c 20 6e 65 76 65 72 20  core will never 
f880: 61 74 74 65 6d 70 74 20 74 6f 20 61 63 71 75 69  attempt to acqui
f890: 72 65 20 6f 72 20 72 65 6c 65 61 73 65 20 61 0a  re or release a.
f8a0: 2a 2a 20 6c 6f 63 6b 20 6f 75 74 73 69 64 65 20  ** lock outside 
f8b0: 6f 66 20 74 68 69 73 20 72 61 6e 67 65 0a 2a 2f  of this range.*/
f8c0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
f8d0: 53 48 4d 5f 4e 4c 4f 43 4b 20 20 20 20 20 20 20  SHM_NLOCK       
f8e0: 20 38 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33   8.../*.** CAPI3
f8f0: 52 45 46 3a 20 49 6e 69 74 69 61 6c 69 7a 65 20  REF: Initialize 
f900: 54 68 65 20 53 51 4c 69 74 65 20 4c 69 62 72 61  The SQLite Libra
f910: 72 79 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  ry.**.** ^The sq
f920: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
f930: 28 29 20 72 6f 75 74 69 6e 65 20 69 6e 69 74 69  () routine initi
f940: 61 6c 69 7a 65 73 20 74 68 65 0a 2a 2a 20 53 51  alizes the.** SQ
f950: 4c 69 74 65 20 6c 69 62 72 61 72 79 2e 20 20 5e  Lite library.  ^
f960: 54 68 65 20 73 71 6c 69 74 65 33 5f 73 68 75 74  The sqlite3_shut
f970: 64 6f 77 6e 28 29 20 72 6f 75 74 69 6e 65 0a 2a  down() routine.*
f980: 2a 20 64 65 61 6c 6c 6f 63 61 74 65 73 20 61 6e  * deallocates an
f990: 79 20 72 65 73 6f 75 72 63 65 73 20 74 68 61 74  y resources that
f9a0: 20 77 65 72 65 20 61 6c 6c 6f 63 61 74 65 64 20   were allocated 
f9b0: 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  by sqlite3_initi
f9c0: 61 6c 69 7a 65 28 29 2e 0a 2a 2a 20 54 68 65 73  alize()..** Thes
f9d0: 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 64  e routines are d
f9e0: 65 73 69 67 6e 65 64 20 74 6f 20 61 69 64 20 69  esigned to aid i
f9f0: 6e 20 70 72 6f 63 65 73 73 20 69 6e 69 74 69 61  n process initia
fa00: 6c 69 7a 61 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20  lization and.** 
fa10: 73 68 75 74 64 6f 77 6e 20 6f 6e 20 65 6d 62 65  shutdown on embe
fa20: 64 64 65 64 20 73 79 73 74 65 6d 73 2e 20 20 57  dded systems.  W
fa30: 6f 72 6b 73 74 61 74 69 6f 6e 20 61 70 70 6c 69  orkstation appli
fa40: 63 61 74 69 6f 6e 73 20 75 73 69 6e 67 0a 2a 2a  cations using.**
fa50: 20 53 51 4c 69 74 65 20 6e 6f 72 6d 61 6c 6c 79   SQLite normally
fa60: 20 64 6f 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20   do not need to 
fa70: 69 6e 76 6f 6b 65 20 65 69 74 68 65 72 20 6f 66  invoke either of
fa80: 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e   these routines.
fa90: 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f  .**.** A call to
faa0: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
fab0: 69 7a 65 28 29 20 69 73 20 61 6e 20 22 65 66 66  ize() is an "eff
fac0: 65 63 74 69 76 65 22 20 63 61 6c 6c 20 69 66 20  ective" call if 
fad0: 69 74 20 69 73 0a 2a 2a 20 74 68 65 20 66 69 72  it is.** the fir
fae0: 73 74 20 74 69 6d 65 20 73 71 6c 69 74 65 33 5f  st time sqlite3_
faf0: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20  initialize() is 
fb00: 69 6e 76 6f 6b 65 64 20 64 75 72 69 6e 67 20 74  invoked during t
fb10: 68 65 20 6c 69 66 65 74 69 6d 65 20 6f 66 0a 2a  he lifetime of.*
fb20: 2a 20 74 68 65 20 70 72 6f 63 65 73 73 2c 20 6f  * the process, o
fb30: 72 20 69 66 20 69 74 20 69 73 20 74 68 65 20 66  r if it is the f
fb40: 69 72 73 74 20 74 69 6d 65 20 73 71 6c 69 74 65  irst time sqlite
fb50: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69  3_initialize() i
fb60: 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 66 6f 6c  s invoked.** fol
fb70: 6c 6f 77 69 6e 67 20 61 20 63 61 6c 6c 20 74 6f  lowing a call to
fb80: 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77   sqlite3_shutdow
fb90: 6e 28 29 2e 20 20 5e 28 4f 6e 6c 79 20 61 6e 20  n().  ^(Only an 
fba0: 65 66 66 65 63 74 69 76 65 20 63 61 6c 6c 0a 2a  effective call.*
fbb0: 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f 69 6e 69  * of sqlite3_ini
fbc0: 74 69 61 6c 69 7a 65 28 29 20 64 6f 65 73 20 61  tialize() does a
fbd0: 6e 79 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f  ny initializatio
fbe0: 6e 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20 63 61  n.  All other ca
fbf0: 6c 6c 73 0a 2a 2a 20 61 72 65 20 68 61 72 6d 6c  lls.** are harml
fc00: 65 73 73 20 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a 2a  ess no-ops.)^.**
fc10: 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20 73 71  .** A call to sq
fc20: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
fc30: 20 69 73 20 61 6e 20 22 65 66 66 65 63 74 69 76   is an "effectiv
fc40: 65 22 20 63 61 6c 6c 20 69 66 20 69 74 20 69 73  e" call if it is
fc50: 20 74 68 65 20 66 69 72 73 74 0a 2a 2a 20 63 61   the first.** ca
fc60: 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68  ll to sqlite3_sh
fc70: 75 74 64 6f 77 6e 28 29 20 73 69 6e 63 65 20 74  utdown() since t
fc80: 68 65 20 6c 61 73 74 20 73 71 6c 69 74 65 33 5f  he last sqlite3_
fc90: 69 6e 69 74 69 61 6c 69 7a 65 28 29 2e 20 20 5e  initialize().  ^
fca0: 28 4f 6e 6c 79 0a 2a 2a 20 61 6e 20 65 66 66 65  (Only.** an effe
fcb0: 63 74 69 76 65 20 63 61 6c 6c 20 74 6f 20 73 71  ctive call to sq
fcc0: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
fcd0: 20 64 6f 65 73 20 61 6e 79 20 64 65 69 6e 69 74   does any deinit
fce0: 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 20 41  ialization..** A
fcf0: 6c 6c 20 6f 74 68 65 72 20 76 61 6c 69 64 20 63  ll other valid c
fd00: 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f  alls to sqlite3_
fd10: 73 68 75 74 64 6f 77 6e 28 29 20 61 72 65 20 68  shutdown() are h
fd20: 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e 29  armless no-ops.)
fd30: 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ^.**.** The sqli
fd40: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
fd50: 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 74 68   interface is th
fd60: 72 65 61 64 73 61 66 65 2c 20 62 75 74 20 73 71  readsafe, but sq
fd70: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
fd80: 0a 2a 2a 20 69 73 20 6e 6f 74 2e 20 20 54 68 65  .** is not.  The
fd90: 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77   sqlite3_shutdow
fda0: 6e 28 29 20 69 6e 74 65 72 66 61 63 65 20 6d 75  n() interface mu
fdb0: 73 74 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65  st only be calle
fdc0: 64 20 66 72 6f 6d 20 61 0a 2a 2a 20 73 69 6e 67  d from a.** sing
fdd0: 6c 65 20 74 68 72 65 61 64 2e 20 20 41 6c 6c 20  le thread.  All 
fde0: 6f 70 65 6e 20 5b 64 61 74 61 62 61 73 65 20 63  open [database c
fdf0: 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 6d 75 73 74  onnections] must
fe00: 20 62 65 20 63 6c 6f 73 65 64 20 61 6e 64 20 61   be closed and a
fe10: 6c 6c 0a 2a 2a 20 6f 74 68 65 72 20 53 51 4c 69  ll.** other SQLi
fe20: 74 65 20 72 65 73 6f 75 72 63 65 73 20 6d 75 73  te resources mus
fe30: 74 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64  t be deallocated
fe40: 20 70 72 69 6f 72 20 74 6f 20 69 6e 76 6f 6b 69   prior to invoki
fe50: 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 68  ng.** sqlite3_sh
fe60: 75 74 64 6f 77 6e 28 29 2e 0a 2a 2a 0a 2a 2a 20  utdown()..**.** 
fe70: 41 6d 6f 6e 67 20 6f 74 68 65 72 20 74 68 69 6e  Among other thin
fe80: 67 73 2c 20 5e 73 71 6c 69 74 65 33 5f 69 6e 69  gs, ^sqlite3_ini
fe90: 74 69 61 6c 69 7a 65 28 29 20 77 69 6c 6c 20 69  tialize() will i
fea0: 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33  nvoke.** sqlite3
feb0: 5f 6f 73 5f 69 6e 69 74 28 29 2e 20 20 53 69 6d  _os_init().  Sim
fec0: 69 6c 61 72 6c 79 2c 20 5e 73 71 6c 69 74 65 33  ilarly, ^sqlite3
fed0: 5f 73 68 75 74 64 6f 77 6e 28 29 0a 2a 2a 20 77  _shutdown().** w
fee0: 69 6c 6c 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74  ill invoke sqlit
fef0: 65 33 5f 6f 73 5f 65 6e 64 28 29 2e 0a 2a 2a 0a  e3_os_end()..**.
ff00: 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
ff10: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75  initialize() rou
ff20: 74 69 6e 65 20 72 65 74 75 72 6e 73 20 5b 53 51  tine returns [SQ
ff30: 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63  LITE_OK] on succ
ff40: 65 73 73 2e 0a 2a 2a 20 5e 49 66 20 66 6f 72 20  ess..** ^If for 
ff50: 73 6f 6d 65 20 72 65 61 73 6f 6e 2c 20 73 71 6c  some reason, sql
ff60: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
ff70: 29 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 69  ) is unable to i
ff80: 6e 69 74 69 61 6c 69 7a 65 0a 2a 2a 20 74 68 65  nitialize.** the
ff90: 20 6c 69 62 72 61 72 79 20 28 70 65 72 68 61 70   library (perhap
ffa0: 73 20 69 74 20 69 73 20 75 6e 61 62 6c 65 20 74  s it is unable t
ffb0: 6f 20 61 6c 6c 6f 63 61 74 65 20 61 20 6e 65 65  o allocate a nee
ffc0: 64 65 64 20 72 65 73 6f 75 72 63 65 20 73 75 63  ded resource suc
ffd0: 68 0a 2a 2a 20 61 73 20 61 20 6d 75 74 65 78 29  h.** as a mutex)
ffe0: 20 69 74 20 72 65 74 75 72 6e 73 20 61 6e 20 5b   it returns an [
fff0: 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f 74 68 65  error code] othe
10000 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4f  r than [SQLITE_O
10010 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  K]..**.** ^The s
10020 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
10030 65 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20 63  e() routine is c
10040 61 6c 6c 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79  alled internally
10050 20 62 79 20 6d 61 6e 79 20 6f 74 68 65 72 0a 2a   by many other.*
10060 2a 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61  * SQLite interfa
10070 63 65 73 20 73 6f 20 74 68 61 74 20 61 6e 20 61  ces so that an a
10080 70 70 6c 69 63 61 74 69 6f 6e 20 75 73 75 61 6c  pplication usual
10090 6c 79 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64  ly does not need
100a0 20 74 6f 0a 2a 2a 20 69 6e 76 6f 6b 65 20 73 71   to.** invoke sq
100b0 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
100c0 28 29 20 64 69 72 65 63 74 6c 79 2e 20 20 46 6f  () directly.  Fo
100d0 72 20 65 78 61 6d 70 6c 65 2c 20 5b 73 71 6c 69  r example, [sqli
100e0 74 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20 63  te3_open()].** c
100f0 61 6c 6c 73 20 73 71 6c 69 74 65 33 5f 69 6e 69  alls sqlite3_ini
10100 74 69 61 6c 69 7a 65 28 29 20 73 6f 20 74 68 65  tialize() so the
10110 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 20   SQLite library 
10120 77 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61 74 69  will be automati
10130 63 61 6c 6c 79 0a 2a 2a 20 69 6e 69 74 69 61 6c  cally.** initial
10140 69 7a 65 64 20 77 68 65 6e 20 5b 73 71 6c 69 74  ized when [sqlit
10150 65 33 5f 6f 70 65 6e 28 29 5d 20 69 73 20 63 61  e3_open()] is ca
10160 6c 6c 65 64 20 69 66 20 69 74 20 68 61 73 20 6e  lled if it has n
10170 6f 74 20 62 65 20 69 6e 69 74 69 61 6c 69 7a 65  ot be initialize
10180 64 0a 2a 2a 20 61 6c 72 65 61 64 79 2e 20 20 5e  d.** already.  ^
10190 48 6f 77 65 76 65 72 2c 20 69 66 20 53 51 4c 69  However, if SQLi
101a0 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77  te is compiled w
101b0 69 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  ith the [SQLITE_
101c0 4f 4d 49 54 5f 41 55 54 4f 49 4e 49 54 5d 0a 2a  OMIT_AUTOINIT].*
101d0 2a 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  * compile-time o
101e0 70 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20  ption, then the 
101f0 61 75 74 6f 6d 61 74 69 63 20 63 61 6c 6c 73 20  automatic calls 
10200 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  to sqlite3_initi
10210 61 6c 69 7a 65 28 29 0a 2a 2a 20 61 72 65 20 6f  alize().** are o
10220 6d 69 74 74 65 64 20 61 6e 64 20 74 68 65 20 61  mitted and the a
10230 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20  pplication must 
10240 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f 69 6e 69  call sqlite3_ini
10250 74 69 61 6c 69 7a 65 28 29 20 64 69 72 65 63 74  tialize() direct
10260 6c 79 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 75  ly.** prior to u
10270 73 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 53  sing any other S
10280 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e  QLite interface.
10290 20 20 46 6f 72 20 6d 61 78 69 6d 75 6d 20 70 6f    For maximum po
102a0 72 74 61 62 69 6c 69 74 79 2c 0a 2a 2a 20 69 74  rtability,.** it
102b0 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20   is recommended 
102c0 74 68 61 74 20 61 70 70 6c 69 63 61 74 69 6f 6e  that application
102d0 73 20 61 6c 77 61 79 73 20 69 6e 76 6f 6b 65 20  s always invoke 
102e0 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
102f0 7a 65 28 29 0a 2a 2a 20 64 69 72 65 63 74 6c 79  ze().** directly
10300 20 70 72 69 6f 72 20 74 6f 20 75 73 69 6e 67 20   prior to using 
10310 61 6e 79 20 6f 74 68 65 72 20 53 51 4c 69 74 65  any other SQLite
10320 20 69 6e 74 65 72 66 61 63 65 2e 20 20 46 75 74   interface.  Fut
10330 75 72 65 20 72 65 6c 65 61 73 65 73 0a 2a 2a 20  ure releases.** 
10340 6f 66 20 53 51 4c 69 74 65 20 6d 61 79 20 72 65  of SQLite may re
10350 71 75 69 72 65 20 74 68 69 73 2e 20 20 49 6e 20  quire this.  In 
10360 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65  other words, the
10370 20 62 65 68 61 76 69 6f 72 20 65 78 68 69 62 69   behavior exhibi
10380 74 65 64 0a 2a 2a 20 77 68 65 6e 20 53 51 4c 69  ted.** when SQLi
10390 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77  te is compiled w
103a0 69 74 68 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54  ith [SQLITE_OMIT
103b0 5f 41 55 54 4f 49 4e 49 54 5d 20 6d 69 67 68 74  _AUTOINIT] might
103c0 20 62 65 63 6f 6d 65 20 74 68 65 0a 2a 2a 20 64   become the.** d
103d0 65 66 61 75 6c 74 20 62 65 68 61 76 69 6f 72 20  efault behavior 
103e0 69 6e 20 73 6f 6d 65 20 66 75 74 75 72 65 20 72  in some future r
103f0 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65  elease of SQLite
10400 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
10410 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 72 6f  te3_os_init() ro
10420 75 74 69 6e 65 20 64 6f 65 73 20 6f 70 65 72 61  utine does opera
10430 74 69 6e 67 2d 73 79 73 74 65 6d 20 73 70 65 63  ting-system spec
10440 69 66 69 63 0a 2a 2a 20 69 6e 69 74 69 61 6c 69  ific.** initiali
10450 7a 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 53 51  zation of the SQ
10460 4c 69 74 65 20 6c 69 62 72 61 72 79 2e 20 20 54  Lite library.  T
10470 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e  he sqlite3_os_en
10480 64 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 75  d().** routine u
10490 6e 64 6f 65 73 20 74 68 65 20 65 66 66 65 63 74  ndoes the effect
104a0 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69   of sqlite3_os_i
104b0 6e 69 74 28 29 2e 20 20 54 79 70 69 63 61 6c 20  nit().  Typical 
104c0 74 61 73 6b 73 0a 2a 2a 20 70 65 72 66 6f 72 6d  tasks.** perform
104d0 65 64 20 62 79 20 74 68 65 73 65 20 72 6f 75 74  ed by these rout
104e0 69 6e 65 73 20 69 6e 63 6c 75 64 65 20 61 6c 6c  ines include all
104f0 6f 63 61 74 69 6f 6e 20 6f 72 20 64 65 61 6c 6c  ocation or deall
10500 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 73 74  ocation.** of st
10510 61 74 69 63 20 72 65 73 6f 75 72 63 65 73 2c 20  atic resources, 
10520 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 6f  initialization o
10530 66 20 67 6c 6f 62 61 6c 20 76 61 72 69 61 62 6c  f global variabl
10540 65 73 2c 0a 2a 2a 20 73 65 74 74 69 6e 67 20 75  es,.** setting u
10550 70 20 61 20 64 65 66 61 75 6c 74 20 5b 73 71 6c  p a default [sql
10560 69 74 65 33 5f 76 66 73 5d 20 6d 6f 64 75 6c 65  ite3_vfs] module
10570 2c 20 6f 72 20 73 65 74 74 69 6e 67 20 75 70 0a  , or setting up.
10580 2a 2a 20 61 20 64 65 66 61 75 6c 74 20 63 6f 6e  ** a default con
10590 66 69 67 75 72 61 74 69 6f 6e 20 75 73 69 6e 67  figuration using
105a0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
105b0 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61  ()]..**.** The a
105c0 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c  pplication shoul
105d0 64 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65 20 65  d never invoke e
105e0 69 74 68 65 72 20 73 71 6c 69 74 65 33 5f 6f 73  ither sqlite3_os
105f0 5f 69 6e 69 74 28 29 0a 2a 2a 20 6f 72 20 73 71  _init().** or sq
10600 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 20 64  lite3_os_end() d
10610 69 72 65 63 74 6c 79 2e 20 20 54 68 65 20 61 70  irectly.  The ap
10620 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64  plication should
10630 20 6f 6e 6c 79 20 69 6e 76 6f 6b 65 0a 2a 2a 20   only invoke.** 
10640 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
10650 7a 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  ze() and sqlite3
10660 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 54 68  _shutdown().  Th
10670 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69  e sqlite3_os_ini
10680 74 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  t().** interface
10690 20 69 73 20 63 61 6c 6c 65 64 20 61 75 74 6f 6d   is called autom
106a0 61 74 69 63 61 6c 6c 79 20 62 79 20 73 71 6c 69  atically by sqli
106b0 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
106c0 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   and.** sqlite3_
106d0 6f 73 5f 65 6e 64 28 29 20 69 73 20 63 61 6c 6c  os_end() is call
106e0 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 73 68  ed by sqlite3_sh
106f0 75 74 64 6f 77 6e 28 29 2e 20 20 41 70 70 72 6f  utdown().  Appro
10700 70 72 69 61 74 65 0a 2a 2a 20 69 6d 70 6c 65 6d  priate.** implem
10710 65 6e 74 61 74 69 6f 6e 73 20 66 6f 72 20 73 71  entations for sq
10720 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20  lite3_os_init() 
10730 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65  and sqlite3_os_e
10740 6e 64 28 29 0a 2a 2a 20 61 72 65 20 62 75 69 6c  nd().** are buil
10750 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 20 77 68  t into SQLite wh
10760 65 6e 20 69 74 20 69 73 20 63 6f 6d 70 69 6c 65  en it is compile
10770 64 20 66 6f 72 20 55 6e 69 78 2c 20 57 69 6e 64  d for Unix, Wind
10780 6f 77 73 2c 20 6f 72 20 4f 53 2f 32 2e 0a 2a 2a  ows, or OS/2..**
10790 20 57 68 65 6e 20 5b 63 75 73 74 6f 6d 20 62 75   When [custom bu
107a0 69 6c 64 73 20 7c 20 62 75 69 6c 74 20 66 6f 72  ilds | built for
107b0 20 6f 74 68 65 72 20 70 6c 61 74 66 6f 72 6d 73   other platforms
107c0 5d 0a 2a 2a 20 28 75 73 69 6e 67 20 74 68 65 20  ].** (using the 
107d0 5b 53 51 4c 49 54 45 5f 4f 53 5f 4f 54 48 45 52  [SQLITE_OS_OTHER
107e0 3d 31 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  =1] compile-time
107f0 0a 2a 2a 20 6f 70 74 69 6f 6e 29 20 74 68 65 20  .** option) the 
10800 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74  application must
10810 20 73 75 70 70 6c 79 20 61 20 73 75 69 74 61 62   supply a suitab
10820 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  le implementatio
10830 6e 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33  n for.** sqlite3
10840 5f 6f 73 5f 69 6e 69 74 28 29 20 61 6e 64 20 73  _os_init() and s
10850 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 2e  qlite3_os_end().
10860 20 20 41 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e    An application
10870 2d 73 75 70 70 6c 69 65 64 0a 2a 2a 20 69 6d 70  -supplied.** imp
10880 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 73  lementation of s
10890 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29  qlite3_os_init()
108a0 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65   or sqlite3_os_e
108b0 6e 64 28 29 0a 2a 2a 20 6d 75 73 74 20 72 65 74  nd().** must ret
108c0 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20  urn [SQLITE_OK] 
108d0 6f 6e 20 73 75 63 63 65 73 73 20 61 6e 64 20 73  on success and s
108e0 6f 6d 65 20 6f 74 68 65 72 20 5b 65 72 72 6f 72  ome other [error
108f0 20 63 6f 64 65 5d 20 75 70 6f 6e 0a 2a 2a 20 66   code] upon.** f
10900 61 69 6c 75 72 65 2e 0a 2a 2f 0a 53 51 4c 49 54  ailure..*/.SQLIT
10910 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
10920 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 76 6f 69  3_initialize(voi
10930 64 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  d);.SQLITE_API i
10940 6e 74 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64  nt sqlite3_shutd
10950 6f 77 6e 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54  own(void);.SQLIT
10960 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
10970 33 5f 6f 73 5f 69 6e 69 74 28 76 6f 69 64 29 3b  3_os_init(void);
10980 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
10990 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 76  sqlite3_os_end(v
109a0 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  oid);../*.** CAP
109b0 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 69  I3REF: Configuri
109c0 6e 67 20 54 68 65 20 53 51 4c 69 74 65 20 4c 69  ng The SQLite Li
109d0 62 72 61 72 79 0a 2a 2a 0a 2a 2a 20 54 68 65 20  brary.**.** The 
109e0 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
109f0 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 75 73   interface is us
10a00 65 64 20 74 6f 20 6d 61 6b 65 20 67 6c 6f 62 61  ed to make globa
10a10 6c 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 0a  l configuration.
10a20 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f 20 53 51  ** changes to SQ
10a30 4c 69 74 65 20 69 6e 20 6f 72 64 65 72 20 74 6f  Lite in order to
10a40 20 74 75 6e 65 20 53 51 4c 69 74 65 20 74 6f 20   tune SQLite to 
10a50 74 68 65 20 73 70 65 63 69 66 69 63 20 6e 65 65  the specific nee
10a60 64 73 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70  ds of.** the app
10a70 6c 69 63 61 74 69 6f 6e 2e 20 20 54 68 65 20 64  lication.  The d
10a80 65 66 61 75 6c 74 20 63 6f 6e 66 69 67 75 72 61  efault configura
10a90 74 69 6f 6e 20 69 73 20 72 65 63 6f 6d 6d 65 6e  tion is recommen
10aa0 64 65 64 20 66 6f 72 20 6d 6f 73 74 0a 2a 2a 20  ded for most.** 
10ab0 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 61 6e 64  applications and
10ac0 20 73 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65   so this routine
10ad0 20 69 73 20 75 73 75 61 6c 6c 79 20 6e 6f 74 20   is usually not 
10ae0 6e 65 63 65 73 73 61 72 79 2e 20 20 49 74 20 69  necessary.  It i
10af0 73 0a 2a 2a 20 70 72 6f 76 69 64 65 64 20 74 6f  s.** provided to
10b00 20 73 75 70 70 6f 72 74 20 72 61 72 65 20 61 70   support rare ap
10b10 70 6c 69 63 61 74 69 6f 6e 73 20 77 69 74 68 20  plications with 
10b20 75 6e 75 73 75 61 6c 20 6e 65 65 64 73 2e 0a 2a  unusual needs..*
10b30 2a 0a 2a 2a 20 3c 62 3e 54 68 65 20 73 71 6c 69  *.** <b>The sqli
10b40 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74  te3_config() int
10b50 65 72 66 61 63 65 20 69 73 20 6e 6f 74 20 74 68  erface is not th
10b60 72 65 61 64 73 61 66 65 2e 20 54 68 65 20 61 70  readsafe. The ap
10b70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 6d 75 73  plication.** mus
10b80 74 20 65 6e 73 75 72 65 20 74 68 61 74 20 6e 6f  t ensure that no
10b90 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e   other SQLite in
10ba0 74 65 72 66 61 63 65 73 20 61 72 65 20 69 6e 76  terfaces are inv
10bb0 6f 6b 65 64 20 62 79 20 6f 74 68 65 72 0a 2a 2a  oked by other.**
10bc0 20 74 68 72 65 61 64 73 20 77 68 69 6c 65 20 73   threads while s
10bd0 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20  qlite3_config() 
10be0 69 73 20 72 75 6e 6e 69 6e 67 2e 3c 2f 62 3e 0a  is running.</b>.
10bf0 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
10c00 33 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72  3_config() inter
10c10 66 61 63 65 0a 2a 2a 20 6d 61 79 20 6f 6e 6c 79  face.** may only
10c20 20 62 65 20 69 6e 76 6f 6b 65 64 20 70 72 69 6f   be invoked prio
10c30 72 20 74 6f 20 6c 69 62 72 61 72 79 20 69 6e 69  r to library ini
10c40 74 69 61 6c 69 7a 61 74 69 6f 6e 20 75 73 69 6e  tialization usin
10c50 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6e  g.** [sqlite3_in
10c60 69 74 69 61 6c 69 7a 65 28 29 5d 20 6f 72 20 61  itialize()] or a
10c70 66 74 65 72 20 73 68 75 74 64 6f 77 6e 20 62 79  fter shutdown by
10c80 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f   [sqlite3_shutdo
10c90 77 6e 28 29 5d 2e 0a 2a 2a 20 5e 49 66 20 73 71  wn()]..** ^If sq
10ca0 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69  lite3_config() i
10cb0 73 20 63 61 6c 6c 65 64 20 61 66 74 65 72 20 5b  s called after [
10cc0 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
10cd0 7a 65 28 29 5d 20 61 6e 64 20 62 65 66 6f 72 65  ze()] and before
10ce0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 68 75  .** [sqlite3_shu
10cf0 74 64 6f 77 6e 28 29 5d 20 74 68 65 6e 20 69 74  tdown()] then it
10d00 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 53 51 4c   will return SQL
10d10 49 54 45 5f 4d 49 53 55 53 45 2e 0a 2a 2a 20 4e  ITE_MISUSE..** N
10d20 6f 74 65 2c 20 68 6f 77 65 76 65 72 2c 20 74 68  ote, however, th
10d30 61 74 20 5e 73 71 6c 69 74 65 33 5f 63 6f 6e 66  at ^sqlite3_conf
10d40 69 67 28 29 20 63 61 6e 20 62 65 20 63 61 6c 6c  ig() can be call
10d50 65 64 20 61 73 20 70 61 72 74 20 6f 66 20 74 68  ed as part of th
10d60 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74  e.** implementat
10d70 69 6f 6e 20 6f 66 20 61 6e 20 61 70 70 6c 69 63  ion of an applic
10d80 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 5b 73  ation-defined [s
10d90 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29  qlite3_os_init()
10da0 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72  ]..**.** The fir
10db0 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73  st argument to s
10dc0 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20  qlite3_config() 
10dd0 69 73 20 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a  is an integer.**
10de0 20 5b 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20   [configuration 
10df0 6f 70 74 69 6f 6e 5d 20 74 68 61 74 20 64 65 74  option] that det
10e00 65 72 6d 69 6e 65 73 0a 2a 2a 20 77 68 61 74 20  ermines.** what 
10e10 70 72 6f 70 65 72 74 79 20 6f 66 20 53 51 4c 69  property of SQLi
10e20 74 65 20 69 73 20 74 6f 20 62 65 20 63 6f 6e 66  te is to be conf
10e30 69 67 75 72 65 64 2e 20 20 53 75 62 73 65 71 75  igured.  Subsequ
10e40 65 6e 74 20 61 72 67 75 6d 65 6e 74 73 0a 2a 2a  ent arguments.**
10e50 20 76 61 72 79 20 64 65 70 65 6e 64 69 6e 67 20   vary depending 
10e60 6f 6e 20 74 68 65 20 5b 63 6f 6e 66 69 67 75 72  on the [configur
10e70 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d 0a 2a 2a  ation option].**
10e80 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72   in the first ar
10e90 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 57  gument..**.** ^W
10ea0 68 65 6e 20 61 20 63 6f 6e 66 69 67 75 72 61 74  hen a configurat
10eb0 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 20 73 65  ion option is se
10ec0 74 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  t, sqlite3_confi
10ed0 67 28 29 20 72 65 74 75 72 6e 73 20 5b 53 51 4c  g() returns [SQL
10ee0 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 20 5e 49 66 20  ITE_OK]..** ^If 
10ef0 74 68 65 20 6f 70 74 69 6f 6e 20 69 73 20 75 6e  the option is un
10f00 6b 6e 6f 77 6e 20 6f 72 20 53 51 4c 69 74 65 20  known or SQLite 
10f10 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 73 65 74  is unable to set
10f20 20 74 68 65 20 6f 70 74 69 6f 6e 0a 2a 2a 20 74   the option.** t
10f30 68 65 6e 20 74 68 69 73 20 72 6f 75 74 69 6e 65  hen this routine
10f40 20 72 65 74 75 72 6e 73 20 61 20 6e 6f 6e 2d 7a   returns a non-z
10f50 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d  ero [error code]
10f60 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
10f70 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66  int sqlite3_conf
10f80 69 67 28 69 6e 74 2c 20 2e 2e 2e 29 3b 0a 0a 2f  ig(int, ...);../
10f90 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
10fa0 6f 6e 66 69 67 75 72 65 20 64 61 74 61 62 61 73  onfigure databas
10fb0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a  e connections.**
10fc0 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
10fd0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
10fe0 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 20 69  e3_db_config() i
10ff0 6e 74 65 72 66 61 63 65 20 69 73 20 75 73 65 64  nterface is used
11000 20 74 6f 20 6d 61 6b 65 20 63 6f 6e 66 69 67 75   to make configu
11010 72 61 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65  ration.** change
11020 73 20 74 6f 20 61 20 5b 64 61 74 61 62 61 73 65  s to a [database
11030 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 54   connection].  T
11040 68 65 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  he interface is 
11050 73 69 6d 69 6c 61 72 20 74 6f 0a 2a 2a 20 5b 73  similar to.** [s
11060 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
11070 20 65 78 63 65 70 74 20 74 68 61 74 20 74 68 65   except that the
11080 20 63 68 61 6e 67 65 73 20 61 70 70 6c 79 20 74   changes apply t
11090 6f 20 61 20 73 69 6e 67 6c 65 0a 2a 2a 20 5b 64  o a single.** [d
110a0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
110b0 6f 6e 5d 20 28 73 70 65 63 69 66 69 65 64 20 69  on] (specified i
110c0 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  n the first argu
110d0 6d 65 6e 74 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ment)..**.** The
110e0 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
110f0 20 74 6f 20 73 71 6c 69 74 65 33 5f 64 62 5f 63   to sqlite3_db_c
11100 6f 6e 66 69 67 28 44 2c 56 2c 2e 2e 2e 29 20 20  onfig(D,V,...)  
11110 69 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54  is the.** [SQLIT
11120 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41  E_DBCONFIG_LOOKA
11130 53 49 44 45 20 7c 20 63 6f 6e 66 69 67 75 72 61  SIDE | configura
11140 74 69 6f 6e 20 76 65 72 62 5d 20 2d 20 61 6e 20  tion verb] - an 
11150 69 6e 74 65 67 65 72 20 63 6f 64 65 20 0a 2a 2a  integer code .**
11160 20 74 68 61 74 20 69 6e 64 69 63 61 74 65 73 20   that indicates 
11170 77 68 61 74 20 61 73 70 65 63 74 20 6f 66 20 74  what aspect of t
11180 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
11190 6e 65 63 74 69 6f 6e 5d 20 69 73 20 62 65 69 6e  nection] is bein
111a0 67 20 63 6f 6e 66 69 67 75 72 65 64 2e 0a 2a 2a  g configured..**
111b0 20 53 75 62 73 65 71 75 65 6e 74 20 61 72 67 75   Subsequent argu
111c0 6d 65 6e 74 73 20 76 61 72 79 20 64 65 70 65 6e  ments vary depen
111d0 64 69 6e 67 20 6f 6e 20 74 68 65 20 63 6f 6e 66  ding on the conf
111e0 69 67 75 72 61 74 69 6f 6e 20 76 65 72 62 2e 0a  iguration verb..
111f0 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 73 20 74 6f 20  **.** ^Calls to 
11200 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69  sqlite3_db_confi
11210 67 28 29 20 72 65 74 75 72 6e 20 53 51 4c 49 54  g() return SQLIT
11220 45 5f 4f 4b 20 69 66 20 61 6e 64 20 6f 6e 6c 79  E_OK if and only
11230 20 69 66 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20   if.** the call 
11240 69 73 20 63 6f 6e 73 69 64 65 72 65 64 20 73 75  is considered su
11250 63 63 65 73 73 66 75 6c 2e 0a 2a 2f 0a 53 51 4c  ccessful..*/.SQL
11260 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
11270 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 73 71  te3_db_config(sq
11280 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6f 70 2c 20  lite3*, int op, 
11290 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ...);../*.** CAP
112a0 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c  I3REF: Memory Al
112b0 6c 6f 63 61 74 69 6f 6e 20 52 6f 75 74 69 6e 65  location Routine
112c0 73 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61  s.**.** An insta
112d0 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65  nce of this obje
112e0 63 74 20 64 65 66 69 6e 65 73 20 74 68 65 20 69  ct defines the i
112f0 6e 74 65 72 66 61 63 65 20 62 65 74 77 65 65 6e  nterface between
11300 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 6c   SQLite.** and l
11310 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72 79 20  ow-level memory 
11320 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69  allocation routi
11330 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  nes..**.** This 
11340 6f 62 6a 65 63 74 20 69 73 20 75 73 65 64 20 69  object is used i
11350 6e 20 6f 6e 6c 79 20 6f 6e 65 20 70 6c 61 63 65  n only one place
11360 20 69 6e 20 74 68 65 20 53 51 4c 69 74 65 20 69   in the SQLite i
11370 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20 41 20 70  nterface..** A p
11380 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73  ointer to an ins
11390 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62  tance of this ob
113a0 6a 65 63 74 20 69 73 20 74 68 65 20 61 72 67 75  ject is the argu
113b0 6d 65 6e 74 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  ment to.** [sqli
113c0 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 68  te3_config()] wh
113d0 65 6e 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61  en the configura
113e0 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 0a 2a  tion option is.*
113f0 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  * [SQLITE_CONFIG
11400 5f 4d 41 4c 4c 4f 43 5d 20 6f 72 20 5b 53 51 4c  _MALLOC] or [SQL
11410 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41  ITE_CONFIG_GETMA
11420 4c 4c 4f 43 5d 2e 20 20 0a 2a 2a 20 42 79 20 63  LLOC].  .** By c
11430 72 65 61 74 69 6e 67 20 61 6e 20 69 6e 73 74 61  reating an insta
11440 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65  nce of this obje
11450 63 74 0a 2a 2a 20 61 6e 64 20 70 61 73 73 69 6e  ct.** and passin
11460 67 20 69 74 20 74 6f 20 5b 73 71 6c 69 74 65 33  g it to [sqlite3
11470 5f 63 6f 6e 66 69 67 5d 28 5b 53 51 4c 49 54 45  _config]([SQLITE
11480 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 29  _CONFIG_MALLOC])
11490 0a 2a 2a 20 64 75 72 69 6e 67 20 63 6f 6e 66 69  .** during confi
114a0 67 75 72 61 74 69 6f 6e 2c 20 61 6e 20 61 70 70  guration, an app
114b0 6c 69 63 61 74 69 6f 6e 20 63 61 6e 20 73 70 65  lication can spe
114c0 63 69 66 79 20 61 6e 20 61 6c 74 65 72 6e 61 74  cify an alternat
114d0 69 76 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c  ive.** memory al
114e0 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73 79 73 74  location subsyst
114f0 65 6d 20 66 6f 72 20 53 51 4c 69 74 65 20 74 6f  em for SQLite to
11500 20 75 73 65 20 66 6f 72 20 61 6c 6c 20 6f 66 20   use for all of 
11510 69 74 73 0a 2a 2a 20 64 79 6e 61 6d 69 63 20 6d  its.** dynamic m
11520 65 6d 6f 72 79 20 6e 65 65 64 73 2e 0a 2a 2a 0a  emory needs..**.
11530 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 53 51 4c  ** Note that SQL
11540 69 74 65 20 63 6f 6d 65 73 20 77 69 74 68 20 73  ite comes with s
11550 65 76 65 72 61 6c 20 5b 62 75 69 6c 74 2d 69 6e  everal [built-in
11560 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f   memory allocato
11570 72 73 5d 0a 2a 2a 20 74 68 61 74 20 61 72 65 20  rs].** that are 
11580 70 65 72 66 65 63 74 6c 79 20 61 64 65 71 75 61  perfectly adequa
11590 74 65 20 66 6f 72 20 74 68 65 20 6f 76 65 72 77  te for the overw
115a0 68 65 6c 6d 69 6e 67 20 6d 61 6a 6f 72 69 74 79  helming majority
115b0 20 6f 66 20 61 70 70 6c 69 63 61 74 69 6f 6e 73   of applications
115c0 0a 2a 2a 20 61 6e 64 20 74 68 61 74 20 74 68 69  .** and that thi
115d0 73 20 6f 62 6a 65 63 74 20 69 73 20 6f 6e 6c 79  s object is only
115e0 20 75 73 65 66 75 6c 20 74 6f 20 61 20 74 69 6e   useful to a tin
115f0 79 20 6d 69 6e 6f 72 69 74 79 20 6f 66 20 61 70  y minority of ap
11600 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 77 69  plications.** wi
11610 74 68 20 73 70 65 63 69 61 6c 69 7a 65 64 20 6d  th specialized m
11620 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
11630 20 72 65 71 75 69 72 65 6d 65 6e 74 73 2e 20 20   requirements.  
11640 54 68 69 73 20 6f 62 6a 65 63 74 20 69 73 0a 2a  This object is.*
11650 2a 20 61 6c 73 6f 20 75 73 65 64 20 64 75 72 69  * also used duri
11660 6e 67 20 74 65 73 74 69 6e 67 20 6f 66 20 53 51  ng testing of SQ
11670 4c 69 74 65 20 69 6e 20 6f 72 64 65 72 20 74 6f  Lite in order to
11680 20 73 70 65 63 69 66 79 20 61 6e 20 61 6c 74 65   specify an alte
11690 72 6e 61 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f 72  rnative.** memor
116a0 79 20 61 6c 6c 6f 63 61 74 6f 72 20 74 68 61 74  y allocator that
116b0 20 73 69 6d 75 6c 61 74 65 73 20 6d 65 6d 6f 72   simulates memor
116c0 79 20 6f 75 74 2d 6f 66 2d 6d 65 6d 6f 72 79 20  y out-of-memory 
116d0 63 6f 6e 64 69 74 69 6f 6e 73 20 69 6e 0a 2a 2a  conditions in.**
116e0 20 6f 72 64 65 72 20 74 6f 20 76 65 72 69 66 79   order to verify
116f0 20 74 68 61 74 20 53 51 4c 69 74 65 20 72 65 63   that SQLite rec
11700 6f 76 65 72 73 20 67 72 61 63 65 66 75 6c 6c 79  overs gracefully
11710 20 66 72 6f 6d 20 73 75 63 68 0a 2a 2a 20 63 6f   from such.** co
11720 6e 64 69 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20  nditions..**.** 
11730 54 68 65 20 78 4d 61 6c 6c 6f 63 2c 20 78 52 65  The xMalloc, xRe
11740 61 6c 6c 6f 63 2c 20 61 6e 64 20 78 46 72 65 65  alloc, and xFree
11750 20 6d 65 74 68 6f 64 73 20 6d 75 73 74 20 77 6f   methods must wo
11760 72 6b 20 6c 69 6b 65 20 74 68 65 0a 2a 2a 20 6d  rk like the.** m
11770 61 6c 6c 6f 63 28 29 2c 20 72 65 61 6c 6c 6f 63  alloc(), realloc
11780 28 29 20 61 6e 64 20 66 72 65 65 28 29 20 66 75  () and free() fu
11790 6e 63 74 69 6f 6e 73 20 66 72 6f 6d 20 74 68 65  nctions from the
117a0 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72   standard C libr
117b0 61 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20  ary..** ^SQLite 
117c0 67 75 61 72 61 6e 74 65 65 73 20 74 68 61 74 20  guarantees that 
117d0 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  the second argum
117e0 65 6e 74 20 74 6f 0a 2a 2a 20 78 52 65 61 6c 6c  ent to.** xReall
117f0 6f 63 20 69 73 20 61 6c 77 61 79 73 20 61 20 76  oc is always a v
11800 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79  alue returned by
11810 20 61 20 70 72 69 6f 72 20 63 61 6c 6c 20 74 6f   a prior call to
11820 20 78 52 6f 75 6e 64 75 70 2e 0a 2a 2a 0a 2a 2a   xRoundup..**.**
11830 20 78 53 69 7a 65 20 73 68 6f 75 6c 64 20 72 65   xSize should re
11840 74 75 72 6e 20 74 68 65 20 61 6c 6c 6f 63 61 74  turn the allocat
11850 65 64 20 73 69 7a 65 20 6f 66 20 61 20 6d 65 6d  ed size of a mem
11860 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a  ory allocation.*
11870 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 6f 62 74  * previously obt
11880 61 69 6e 65 64 20 66 72 6f 6d 20 78 4d 61 6c 6c  ained from xMall
11890 6f 63 20 6f 72 20 78 52 65 61 6c 6c 6f 63 2e 20  oc or xRealloc. 
118a0 20 54 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 73   The allocated s
118b0 69 7a 65 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73  ize.** is always
118c0 20 61 74 20 6c 65 61 73 74 20 61 73 20 62 69 67   at least as big
118d0 20 61 73 20 74 68 65 20 72 65 71 75 65 73 74 65   as the requeste
118e0 64 20 73 69 7a 65 20 62 75 74 20 6d 61 79 20 62  d size but may b
118f0 65 20 6c 61 72 67 65 72 2e 0a 2a 2a 0a 2a 2a 20  e larger..**.** 
11900 54 68 65 20 78 52 6f 75 6e 64 75 70 20 6d 65 74  The xRoundup met
11910 68 6f 64 20 72 65 74 75 72 6e 73 20 77 68 61 74  hod returns what
11920 20 77 6f 75 6c 64 20 62 65 20 74 68 65 20 61 6c   would be the al
11930 6c 6f 63 61 74 65 64 20 73 69 7a 65 20 6f 66 0a  located size of.
11940 2a 2a 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  ** a memory allo
11950 63 61 74 69 6f 6e 20 67 69 76 65 6e 20 61 20 70  cation given a p
11960 61 72 74 69 63 75 6c 61 72 20 72 65 71 75 65 73  articular reques
11970 74 65 64 20 73 69 7a 65 2e 20 20 4d 6f 73 74 20  ted size.  Most 
11980 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61  memory.** alloca
11990 74 6f 72 73 20 72 6f 75 6e 64 20 75 70 20 6d 65  tors round up me
119a0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73  mory allocations
119b0 20 61 74 20 6c 65 61 73 74 20 74 6f 20 74 68 65   at least to the
119c0 20 6e 65 78 74 20 6d 75 6c 74 69 70 6c 65 0a 2a   next multiple.*
119d0 2a 20 6f 66 20 38 2e 20 20 53 6f 6d 65 20 61 6c  * of 8.  Some al
119e0 6c 6f 63 61 74 6f 72 73 20 72 6f 75 6e 64 20 75  locators round u
119f0 70 20 74 6f 20 61 20 6c 61 72 67 65 72 20 6d 75  p to a larger mu
11a00 6c 74 69 70 6c 65 20 6f 72 20 74 6f 20 61 20 70  ltiple or to a p
11a10 6f 77 65 72 20 6f 66 20 32 2e 0a 2a 2a 20 45 76  ower of 2..** Ev
11a20 65 72 79 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ery memory alloc
11a30 61 74 69 6f 6e 20 72 65 71 75 65 73 74 20 63 6f  ation request co
11a40 6d 69 6e 67 20 69 6e 20 74 68 72 6f 75 67 68 20  ming in through 
11a50 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
11a60 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65  )].** or [sqlite
11a70 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 20 66 69 72  3_realloc()] fir
11a80 73 74 20 63 61 6c 6c 73 20 78 52 6f 75 6e 64 75  st calls xRoundu
11a90 70 2e 20 20 49 66 20 78 52 6f 75 6e 64 75 70 20  p.  If xRoundup 
11aa0 72 65 74 75 72 6e 73 20 30 2c 20 0a 2a 2a 20 74  returns 0, .** t
11ab0 68 61 74 20 63 61 75 73 65 73 20 74 68 65 20 63  hat causes the c
11ac0 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 6d 65 6d  orresponding mem
11ad0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74  ory allocation t
11ae0 6f 20 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20 54 68  o fail..**.** Th
11af0 65 20 78 49 6e 69 74 20 6d 65 74 68 6f 64 20 69  e xInit method i
11b00 6e 69 74 69 61 6c 69 7a 65 73 20 74 68 65 20 6d  nitializes the m
11b10 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 2e  emory allocator.
11b20 20 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 0a 2a    For example,.*
11b30 2a 20 69 74 20 6d 69 67 68 74 20 61 6c 6c 6f 63  * it might alloc
11b40 61 74 65 20 61 6e 79 20 72 65 71 75 69 72 65 20  ate any require 
11b50 6d 75 74 65 78 65 73 20 6f 72 20 69 6e 69 74 69  mutexes or initi
11b60 61 6c 69 7a 65 20 69 6e 74 65 72 6e 61 6c 20 64  alize internal d
11b70 61 74 61 0a 2a 2a 20 73 74 72 75 63 74 75 72 65  ata.** structure
11b80 73 2e 20 20 54 68 65 20 78 53 68 75 74 64 6f 77  s.  The xShutdow
11b90 6e 20 6d 65 74 68 6f 64 20 69 73 20 69 6e 76 6f  n method is invo
11ba0 6b 65 64 20 28 69 6e 64 69 72 65 63 74 6c 79 29  ked (indirectly)
11bb0 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   by.** [sqlite3_
11bc0 73 68 75 74 64 6f 77 6e 28 29 5d 20 61 6e 64 20  shutdown()] and 
11bd0 73 68 6f 75 6c 64 20 64 65 61 6c 6c 6f 63 61 74  should deallocat
11be0 65 20 61 6e 79 20 72 65 73 6f 75 72 63 65 73 20  e any resources 
11bf0 61 63 71 75 69 72 65 64 0a 2a 2a 20 62 79 20 78  acquired.** by x
11c00 49 6e 69 74 2e 20 20 54 68 65 20 70 41 70 70 44  Init.  The pAppD
11c10 61 74 61 20 70 6f 69 6e 74 65 72 20 69 73 20 75  ata pointer is u
11c20 73 65 64 20 61 73 20 74 68 65 20 6f 6e 6c 79 20  sed as the only 
11c30 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20  parameter to.** 
11c40 78 49 6e 69 74 20 61 6e 64 20 78 53 68 75 74 64  xInit and xShutd
11c50 6f 77 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74  own..**.** SQLit
11c60 65 20 68 6f 6c 64 73 20 74 68 65 20 5b 53 51 4c  e holds the [SQL
11c70 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43  ITE_MUTEX_STATIC
11c80 5f 4d 41 53 54 45 52 5d 20 6d 75 74 65 78 20 77  _MASTER] mutex w
11c90 68 65 6e 20 69 74 20 69 6e 76 6f 6b 65 73 0a 2a  hen it invokes.*
11ca0 2a 20 74 68 65 20 78 49 6e 69 74 20 6d 65 74 68  * the xInit meth
11cb0 6f 64 2c 20 73 6f 20 74 68 65 20 78 49 6e 69 74  od, so the xInit
11cc0 20 6d 65 74 68 6f 64 20 6e 65 65 64 20 6e 6f 74   method need not
11cd0 20 62 65 20 74 68 72 65 61 64 73 61 66 65 2e 20   be threadsafe. 
11ce0 20 54 68 65 0a 2a 2a 20 78 53 68 75 74 64 6f 77   The.** xShutdow
11cf0 6e 20 6d 65 74 68 6f 64 20 69 73 20 6f 6e 6c 79  n method is only
11d00 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 5b 73 71   called from [sq
11d10 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
11d20 5d 20 73 6f 20 69 74 20 64 6f 65 73 0a 2a 2a 20  ] so it does.** 
11d30 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20 74  not need to be t
11d40 68 72 65 61 64 73 61 66 65 20 65 69 74 68 65 72  hreadsafe either
11d50 2e 20 20 46 6f 72 20 61 6c 6c 20 6f 74 68 65 72  .  For all other
11d60 20 6d 65 74 68 6f 64 73 2c 20 53 51 4c 69 74 65   methods, SQLite
11d70 0a 2a 2a 20 68 6f 6c 64 73 20 74 68 65 20 5b 53  .** holds the [S
11d80 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54  QLITE_MUTEX_STAT
11d90 49 43 5f 4d 45 4d 5d 20 6d 75 74 65 78 20 61 73  IC_MEM] mutex as
11da0 20 6c 6f 6e 67 20 61 73 20 74 68 65 0a 2a 2a 20   long as the.** 
11db0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
11dc0 45 4d 53 54 41 54 55 53 5d 20 63 6f 6e 66 69 67  EMSTATUS] config
11dd0 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69  uration option i
11de0 73 20 74 75 72 6e 65 64 20 6f 6e 20 28 77 68 69  s turned on (whi
11df0 63 68 0a 2a 2a 20 69 74 20 69 73 20 62 79 20 64  ch.** it is by d
11e00 65 66 61 75 6c 74 29 20 61 6e 64 20 73 6f 20 74  efault) and so t
11e10 68 65 20 6d 65 74 68 6f 64 73 20 61 72 65 20 61  he methods are a
11e20 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 73 65 72  utomatically ser
11e30 69 61 6c 69 7a 65 64 2e 0a 2a 2a 20 48 6f 77 65  ialized..** Howe
11e40 76 65 72 2c 20 69 66 20 5b 53 51 4c 49 54 45 5f  ver, if [SQLITE_
11e50 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53  CONFIG_MEMSTATUS
11e60 5d 20 69 73 20 64 69 73 61 62 6c 65 64 2c 20 74  ] is disabled, t
11e70 68 65 6e 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a  hen the other.**
11e80 20 6d 65 74 68 6f 64 73 20 6d 75 73 74 20 62 65   methods must be
11e90 20 74 68 72 65 61 64 73 61 66 65 20 6f 72 20 65   threadsafe or e
11ea0 6c 73 65 20 6d 61 6b 65 20 74 68 65 69 72 20 6f  lse make their o
11eb0 77 6e 20 61 72 72 61 6e 67 65 6d 65 6e 74 73 20  wn arrangements 
11ec0 66 6f 72 0a 2a 2a 20 73 65 72 69 61 6c 69 7a 61  for.** serializa
11ed0 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  tion..**.** SQLi
11ee0 74 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 69 6e  te will never in
11ef0 76 6f 6b 65 20 78 49 6e 69 74 28 29 20 6d 6f 72  voke xInit() mor
11f00 65 20 74 68 61 6e 20 6f 6e 63 65 20 77 69 74 68  e than once with
11f10 6f 75 74 20 61 6e 20 69 6e 74 65 72 76 65 6e 69  out an interveni
11f20 6e 67 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 78 53  ng.** call to xS
11f30 68 75 74 64 6f 77 6e 28 29 2e 0a 2a 2f 0a 74 79  hutdown()..*/.ty
11f40 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c  pedef struct sql
11f50 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73  ite3_mem_methods
11f60 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74   sqlite3_mem_met
11f70 68 6f 64 73 3b 0a 73 74 72 75 63 74 20 73 71 6c  hods;.struct sql
11f80 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73  ite3_mem_methods
11f90 20 7b 0a 20 20 76 6f 69 64 20 2a 28 2a 78 4d 61   {.  void *(*xMa
11fa0 6c 6c 6f 63 29 28 69 6e 74 29 3b 20 20 20 20 20  lloc)(int);     
11fb0 20 20 20 20 2f 2a 20 4d 65 6d 6f 72 79 20 61 6c      /* Memory al
11fc0 6c 6f 63 61 74 69 6f 6e 20 66 75 6e 63 74 69 6f  location functio
11fd0 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 28 2a 78 46  n */.  void (*xF
11fe0 72 65 65 29 28 76 6f 69 64 2a 29 3b 20 20 20 20  ree)(void*);    
11ff0 20 20 20 20 20 20 2f 2a 20 46 72 65 65 20 61 20        /* Free a 
12000 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e  prior allocation
12010 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 28 2a 78 52   */.  void *(*xR
12020 65 61 6c 6c 6f 63 29 28 76 6f 69 64 2a 2c 69 6e  ealloc)(void*,in
12030 74 29 3b 20 20 2f 2a 20 52 65 73 69 7a 65 20 61  t);  /* Resize a
12040 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a  n allocation */.
12050 20 20 69 6e 74 20 28 2a 78 53 69 7a 65 29 28 76    int (*xSize)(v
12060 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 20 20 20  oid*);          
12070 20 2f 2a 20 52 65 74 75 72 6e 20 74 68 65 20 73   /* Return the s
12080 69 7a 65 20 6f 66 20 61 6e 20 61 6c 6c 6f 63 61  ize of an alloca
12090 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20 28 2a  tion */.  int (*
120a0 78 52 6f 75 6e 64 75 70 29 28 69 6e 74 29 3b 20  xRoundup)(int); 
120b0 20 20 20 20 20 20 20 20 20 2f 2a 20 52 6f 75 6e           /* Roun
120c0 64 20 75 70 20 72 65 71 75 65 73 74 20 73 69 7a  d up request siz
120d0 65 20 74 6f 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  e to allocation 
120e0 73 69 7a 65 20 2a 2f 0a 20 20 69 6e 74 20 28 2a  size */.  int (*
120f0 78 49 6e 69 74 29 28 76 6f 69 64 2a 29 3b 20 20  xInit)(void*);  
12100 20 20 20 20 20 20 20 20 20 2f 2a 20 49 6e 69 74           /* Init
12110 69 61 6c 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72  ialize the memor
12120 79 20 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20  y allocator */. 
12130 20 76 6f 69 64 20 28 2a 78 53 68 75 74 64 6f 77   void (*xShutdow
12140 6e 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20  n)(void*);      
12150 2f 2a 20 44 65 69 6e 69 74 69 61 6c 69 7a 65 20  /* Deinitialize 
12160 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  the memory alloc
12170 61 74 6f 72 20 2a 2f 0a 20 20 76 6f 69 64 20 2a  ator */.  void *
12180 70 41 70 70 44 61 74 61 3b 20 20 20 20 20 20 20  pAppData;       
12190 20 20 20 20 20 20 20 20 20 2f 2a 20 41 72 67 75           /* Argu
121a0 6d 65 6e 74 20 74 6f 20 78 49 6e 69 74 28 29 20  ment to xInit() 
121b0 61 6e 64 20 78 53 68 75 74 64 6f 77 6e 28 29 20  and xShutdown() 
121c0 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  */.};../*.** CAP
121d0 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 61  I3REF: Configura
121e0 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a 20  tion Options.** 
121f0 4b 45 59 57 4f 52 44 53 3a 20 7b 63 6f 6e 66 69  KEYWORDS: {confi
12200 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 7d  guration option}
12210 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e  .**.** These con
12220 73 74 61 6e 74 73 20 61 72 65 20 74 68 65 20 61  stants are the a
12230 76 61 69 6c 61 62 6c 65 20 69 6e 74 65 67 65 72  vailable integer
12240 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
12250 70 74 69 6f 6e 73 20 74 68 61 74 0a 2a 2a 20 63  ptions that.** c
12260 61 6e 20 62 65 20 70 61 73 73 65 64 20 61 73 20  an be passed as 
12270 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
12280 6e 74 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74  nt to the [sqlit
12290 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74  e3_config()] int
122a0 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65  erface..**.** Ne
122b0 77 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  w configuration 
122c0 6f 70 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 61  options may be a
122d0 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72  dded in future r
122e0 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74  eleases of SQLit
122f0 65 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20 63  e..** Existing c
12300 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
12310 69 6f 6e 73 20 6d 69 67 68 74 20 62 65 20 64 69  ions might be di
12320 73 63 6f 6e 74 69 6e 75 65 64 2e 20 20 41 70 70  scontinued.  App
12330 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f  lications.** sho
12340 75 6c 64 20 63 68 65 63 6b 20 74 68 65 20 72 65  uld check the re
12350 74 75 72 6e 20 63 6f 64 65 20 66 72 6f 6d 20 5b  turn code from [
12360 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
12370 5d 20 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 74  ] to make sure t
12380 68 61 74 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20  hat.** the call 
12390 77 6f 72 6b 65 64 2e 20 20 54 68 65 20 5b 73 71  worked.  The [sq
123a0 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20  lite3_config()] 
123b0 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20 72  interface will r
123c0 65 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a  eturn a.** non-z
123d0 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d  ero [error code]
123e0 20 69 66 20 61 20 64 69 73 63 6f 6e 74 69 6e 75   if a discontinu
123f0 65 64 20 6f 72 20 75 6e 73 75 70 70 6f 72 74 65  ed or unsupporte
12400 64 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  d configuration 
12410 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76  option.** is inv
12420 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e  oked..**.** <dl>
12430 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
12440 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44  FIG_SINGLETHREAD
12450 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
12460 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41  NFIG_SINGLETHREA
12470 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  D</dt>.** <dd>Th
12480 65 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d  ere are no argum
12490 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74  ents to this opt
124a0 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74 69  ion.  ^This opti
124b0 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b  on sets the.** [
124c0 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20  threading mode] 
124d0 74 6f 20 53 69 6e 67 6c 65 2d 74 68 72 65 61 64  to Single-thread
124e0 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64  .  In other word
124f0 73 2c 20 69 74 20 64 69 73 61 62 6c 65 73 0a 2a  s, it disables.*
12500 2a 20 61 6c 6c 20 6d 75 74 65 78 69 6e 67 20 61  * all mutexing a
12510 6e 64 20 70 75 74 73 20 53 51 4c 69 74 65 20 69  nd puts SQLite i
12520 6e 74 6f 20 61 20 6d 6f 64 65 20 77 68 65 72 65  nto a mode where
12530 20 69 74 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20   it can only be 
12540 75 73 65 64 0a 2a 2a 20 62 79 20 61 20 73 69 6e  used.** by a sin
12550 67 6c 65 20 74 68 72 65 61 64 2e 20 20 20 5e 49  gle thread.   ^I
12560 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70  f SQLite is comp
12570 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65  iled with.** the
12580 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53   [SQLITE_THREADS
12590 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52  AFE | SQLITE_THR
125a0 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69  EADSAFE=0] compi
125b0 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74  le-time option t
125c0 68 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74  hen.** it is not
125d0 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 63 68 61   possible to cha
125e0 6e 67 65 20 74 68 65 20 5b 74 68 72 65 61 64 69  nge the [threadi
125f0 6e 67 20 6d 6f 64 65 5d 20 66 72 6f 6d 20 69 74  ng mode] from it
12600 73 20 64 65 66 61 75 6c 74 0a 2a 2a 20 76 61 6c  s default.** val
12610 75 65 20 6f 66 20 53 69 6e 67 6c 65 2d 74 68 72  ue of Single-thr
12620 65 61 64 20 61 6e 64 20 73 6f 20 5b 73 71 6c 69  ead and so [sqli
12630 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69  te3_config()] wi
12640 6c 6c 20 72 65 74 75 72 6e 20 0a 2a 2a 20 5b 53  ll return .** [S
12650 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20  QLITE_ERROR] if 
12660 63 61 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20  called with the 
12670 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49  SQLITE_CONFIG_SI
12680 4e 47 4c 45 54 48 52 45 41 44 0a 2a 2a 20 63 6f  NGLETHREAD.** co
12690 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
126a0 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  on.</dd>.**.** [
126b0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
126c0 55 4c 54 49 54 48 52 45 41 44 5d 5d 20 3c 64 74  ULTITHREAD]] <dt
126d0 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  >SQLITE_CONFIG_M
126e0 55 4c 54 49 54 48 52 45 41 44 3c 2f 64 74 3e 0a  ULTITHREAD</dt>.
126f0 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65  ** <dd>There are
12700 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f   no arguments to
12710 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e   this option.  ^
12720 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73  This option sets
12730 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69   the.** [threadi
12740 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 4d 75 6c 74  ng mode] to Mult
12750 69 2d 74 68 72 65 61 64 2e 20 20 49 6e 20 6f 74  i-thread.  In ot
12760 68 65 72 20 77 6f 72 64 73 2c 20 69 74 20 64 69  her words, it di
12770 73 61 62 6c 65 73 0a 2a 2a 20 6d 75 74 65 78 69  sables.** mutexi
12780 6e 67 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20  ng on [database 
12790 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64 20  connection] and 
127a0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
127b0 65 6e 74 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a  ent] objects..**
127c0 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   The application
127d0 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20   is responsible 
127e0 66 6f 72 20 73 65 72 69 61 6c 69 7a 69 6e 67 20  for serializing 
127f0 61 63 63 65 73 73 20 74 6f 0a 2a 2a 20 5b 64 61  access to.** [da
12800 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
12810 6e 73 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65  ns] and [prepare
12820 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 2e 20 20  d statements].  
12830 42 75 74 20 6f 74 68 65 72 20 6d 75 74 65 78 65  But other mutexe
12840 73 0a 2a 2a 20 61 72 65 20 65 6e 61 62 6c 65 64  s.** are enabled
12850 20 73 6f 20 74 68 61 74 20 53 51 4c 69 74 65 20   so that SQLite 
12860 77 69 6c 6c 20 62 65 20 73 61 66 65 20 74 6f 20  will be safe to 
12870 75 73 65 20 69 6e 20 61 20 6d 75 6c 74 69 2d 74  use in a multi-t
12880 68 72 65 61 64 65 64 0a 2a 2a 20 65 6e 76 69 72  hreaded.** envir
12890 6f 6e 6d 65 6e 74 20 61 73 20 6c 6f 6e 67 20 61  onment as long a
128a0 73 20 6e 6f 20 74 77 6f 20 74 68 72 65 61 64 73  s no two threads
128b0 20 61 74 74 65 6d 70 74 20 74 6f 20 75 73 65 20   attempt to use 
128c0 74 68 65 20 73 61 6d 65 0a 2a 2a 20 5b 64 61 74  the same.** [dat
128d0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
128e0 5d 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 69  ] at the same ti
128f0 6d 65 2e 20 20 5e 49 66 20 53 51 4c 69 74 65 20  me.  ^If SQLite 
12900 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  is compiled with
12910 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  .** the [SQLITE_
12920 54 48 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c  THREADSAFE | SQL
12930 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30  ITE_THREADSAFE=0
12940 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
12950 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74  ption then.** it
12960 20 69 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65   is not possible
12970 20 74 6f 20 73 65 74 20 74 68 65 20 4d 75 6c 74   to set the Mult
12980 69 2d 74 68 72 65 61 64 20 5b 74 68 72 65 61 64  i-thread [thread
12990 69 6e 67 20 6d 6f 64 65 5d 20 61 6e 64 0a 2a 2a  ing mode] and.**
129a0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
129b0 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20  ()] will return 
129c0 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69  [SQLITE_ERROR] i
129d0 66 20 63 61 6c 6c 65 64 20 77 69 74 68 20 74 68  f called with th
129e0 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 43 4f 4e 46  e.** SQLITE_CONF
129f0 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 20 63  IG_MULTITHREAD c
12a00 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
12a10 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ion.</dd>.**.** 
12a20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
12a30 53 45 52 49 41 4c 49 5a 45 44 5d 5d 20 3c 64 74  SERIALIZED]] <dt
12a40 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53  >SQLITE_CONFIG_S
12a50 45 52 49 41 4c 49 5a 45 44 3c 2f 64 74 3e 0a 2a  ERIALIZED</dt>.*
12a60 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20  * <dd>There are 
12a70 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20  no arguments to 
12a80 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54  this option.  ^T
12a90 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20  his option sets 
12aa0 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e  the.** [threadin
12ab0 67 20 6d 6f 64 65 5d 20 74 6f 20 53 65 72 69 61  g mode] to Seria
12ac0 6c 69 7a 65 64 2e 20 49 6e 20 6f 74 68 65 72 20  lized. In other 
12ad0 77 6f 72 64 73 2c 20 74 68 69 73 20 6f 70 74 69  words, this opti
12ae0 6f 6e 20 65 6e 61 62 6c 65 73 0a 2a 2a 20 61 6c  on enables.** al
12af0 6c 20 6d 75 74 65 78 65 73 20 69 6e 63 6c 75 64  l mutexes includ
12b00 69 6e 67 20 74 68 65 20 72 65 63 75 72 73 69 76  ing the recursiv
12b10 65 0a 2a 2a 20 6d 75 74 65 78 65 73 20 6f 6e 20  e.** mutexes on 
12b20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
12b30 74 69 6f 6e 5d 20 61 6e 64 20 5b 70 72 65 70 61  tion] and [prepa
12b40 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f  red statement] o
12b50 62 6a 65 63 74 73 2e 0a 2a 2a 20 49 6e 20 74 68  bjects..** In th
12b60 69 73 20 6d 6f 64 65 20 28 77 68 69 63 68 20 69  is mode (which i
12b70 73 20 74 68 65 20 64 65 66 61 75 6c 74 20 77 68  s the default wh
12b80 65 6e 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  en SQLite is com
12b90 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 5b 53  piled with.** [S
12ba0 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
12bb0 3d 31 5d 29 20 74 68 65 20 53 51 4c 69 74 65 20  =1]) the SQLite 
12bc0 6c 69 62 72 61 72 79 20 77 69 6c 6c 20 69 74 73  library will its
12bd0 65 6c 66 20 73 65 72 69 61 6c 69 7a 65 20 61 63  elf serialize ac
12be0 63 65 73 73 0a 2a 2a 20 74 6f 20 5b 64 61 74 61  cess.** to [data
12bf0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  base connections
12c00 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20  ] and [prepared 
12c10 73 74 61 74 65 6d 65 6e 74 73 5d 20 73 6f 20 74  statements] so t
12c20 68 61 74 20 74 68 65 0a 2a 2a 20 61 70 70 6c 69  hat the.** appli
12c30 63 61 74 69 6f 6e 20 69 73 20 66 72 65 65 20 74  cation is free t
12c40 6f 20 75 73 65 20 74 68 65 20 73 61 6d 65 20 5b  o use the same [
12c50 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
12c60 69 6f 6e 5d 20 6f 72 20 74 68 65 0a 2a 2a 20 73  ion] or the.** s
12c70 61 6d 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  ame [prepared st
12c80 61 74 65 6d 65 6e 74 5d 20 69 6e 20 64 69 66 66  atement] in diff
12c90 65 72 65 6e 74 20 74 68 72 65 61 64 73 20 61 74  erent threads at
12ca0 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 2e 0a   the same time..
12cb0 2a 2a 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73  ** ^If SQLite is
12cc0 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a   compiled with.*
12cd0 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48  * the [SQLITE_TH
12ce0 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54  READSAFE | SQLIT
12cf0 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20  E_THREADSAFE=0] 
12d00 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
12d10 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69  ion then.** it i
12d20 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 74  s not possible t
12d30 6f 20 73 65 74 20 74 68 65 20 53 65 72 69 61 6c  o set the Serial
12d40 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e 67 20  ized [threading 
12d50 6d 6f 64 65 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71  mode] and.** [sq
12d60 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20  lite3_config()] 
12d70 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c  will return [SQL
12d80 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 63 61  ITE_ERROR] if ca
12d90 6c 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a  lled with the.**
12da0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53   SQLITE_CONFIG_S
12db0 45 52 49 41 4c 49 5a 45 44 20 63 6f 6e 66 69 67  ERIALIZED config
12dc0 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c  uration option.<
12dd0 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
12de0 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f  ITE_CONFIG_MALLO
12df0 43 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  C]] <dt>SQLITE_C
12e00 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 3c 2f 64 74  ONFIG_MALLOC</dt
12e10 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20  >.** <dd> ^(The 
12e20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41  SQLITE_CONFIG_MA
12e30 4c 4c 4f 43 20 6f 70 74 69 6f 6e 20 74 61 6b 65  LLOC option take
12e40 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d  s a single argum
12e50 65 6e 74 20 77 68 69 63 68 20 69 73 20 0a 2a 2a  ent which is .**
12e60 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
12e70 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65   instance of the
12e80 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65   [sqlite3_mem_me
12e90 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65  thods] structure
12ea0 2e 0a 2a 2a 20 54 68 65 20 61 72 67 75 6d 65 6e  ..** The argumen
12eb0 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 61  t specifies.** a
12ec0 6c 74 65 72 6e 61 74 69 76 65 20 6c 6f 77 2d 6c  lternative low-l
12ed0 65 76 65 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  evel memory allo
12ee0 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 20  cation routines 
12ef0 74 6f 20 62 65 20 75 73 65 64 20 69 6e 20 70 6c  to be used in pl
12f00 61 63 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6d 65  ace of.** the me
12f10 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
12f20 72 6f 75 74 69 6e 65 73 20 62 75 69 6c 74 20 69  routines built i
12f30 6e 74 6f 20 53 51 4c 69 74 65 2e 29 5e 20 5e 53  nto SQLite.)^ ^S
12f40 51 4c 69 74 65 20 6d 61 6b 65 73 0a 2a 2a 20 69  QLite makes.** i
12f50 74 73 20 6f 77 6e 20 70 72 69 76 61 74 65 20 63  ts own private c
12f60 6f 70 79 20 6f 66 20 74 68 65 20 63 6f 6e 74 65  opy of the conte
12f70 6e 74 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  nt of the [sqlit
12f80 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20  e3_mem_methods] 
12f90 73 74 72 75 63 74 75 72 65 0a 2a 2a 20 62 65 66  structure.** bef
12fa0 6f 72 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33  ore the [sqlite3
12fb0 5f 63 6f 6e 66 69 67 28 29 5d 20 63 61 6c 6c 20  _config()] call 
12fc0 72 65 74 75 72 6e 73 2e 3c 2f 64 64 3e 0a 2a 2a  returns.</dd>.**
12fd0 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
12fe0 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 5d 5d 20  FIG_GETMALLOC]] 
12ff0 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
13000 47 5f 47 45 54 4d 41 4c 4c 4f 43 3c 2f 64 74 3e  G_GETMALLOC</dt>
13010 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 53  .** <dd> ^(The S
13020 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
13030 4d 41 4c 4c 4f 43 20 6f 70 74 69 6f 6e 20 74 61  MALLOC option ta
13040 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67  kes a single arg
13050 75 6d 65 6e 74 20 77 68 69 63 68 0a 2a 2a 20 69  ument which.** i
13060 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
13070 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  n instance of th
13080 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d  e [sqlite3_mem_m
13090 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72  ethods] structur
130a0 65 2e 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74  e..** The [sqlit
130b0 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 0a  e3_mem_methods].
130c0 2a 2a 20 73 74 72 75 63 74 75 72 65 20 69 73 20  ** structure is 
130d0 66 69 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20  filled with the 
130e0 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65  currently define
130f0 64 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  d memory allocat
13100 69 6f 6e 20 72 6f 75 74 69 6e 65 73 2e 29 5e 0a  ion routines.)^.
13110 2a 2a 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 63  ** This option c
13120 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f 76  an be used to ov
13130 65 72 6c 6f 61 64 20 74 68 65 20 64 65 66 61 75  erload the defau
13140 6c 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  lt memory alloca
13150 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65 73  tion.** routines
13160 20 77 69 74 68 20 61 20 77 72 61 70 70 65 72 20   with a wrapper 
13170 74 68 61 74 20 73 69 6d 75 6c 61 74 69 6f 6e 73  that simulations
13180 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
13190 6f 6e 20 66 61 69 6c 75 72 65 20 6f 72 0a 2a 2a  on failure or.**
131a0 20 74 72 61 63 6b 73 20 6d 65 6d 6f 72 79 20 75   tracks memory u
131b0 73 61 67 65 2c 20 66 6f 72 20 65 78 61 6d 70 6c  sage, for exampl
131c0 65 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  e. </dd>.**.** [
131d0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
131e0 45 4d 53 54 41 54 55 53 5d 5d 20 3c 64 74 3e 53  EMSTATUS]] <dt>S
131f0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d  QLITE_CONFIG_MEM
13200 53 54 41 54 55 53 3c 2f 64 74 3e 0a 2a 2a 20 3c  STATUS</dt>.** <
13210 64 64 3e 20 5e 54 68 65 20 53 51 4c 49 54 45 5f  dd> ^The SQLITE_
13220 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53  CONFIG_MEMSTATUS
13230 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 73 69   option takes si
13240 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 6f 66  ngle argument of
13250 20 74 79 70 65 20 69 6e 74 2c 0a 2a 2a 20 69 6e   type int,.** in
13260 74 65 72 70 72 65 74 65 64 20 61 73 20 61 20 62  terpreted as a b
13270 6f 6f 6c 65 61 6e 2c 20 77 68 69 63 68 20 65 6e  oolean, which en
13280 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62 6c 65  ables or disable
13290 73 20 74 68 65 20 63 6f 6c 6c 65 63 74 69 6f 6e  s the collection
132a0 20 6f 66 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c   of.** memory al
132b0 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 69 73 74  location statist
132c0 69 63 73 2e 20 5e 28 57 68 65 6e 20 6d 65 6d 6f  ics. ^(When memo
132d0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74  ry allocation st
132e0 61 74 69 73 74 69 63 73 20 61 72 65 0a 2a 2a 20  atistics are.** 
132f0 64 69 73 61 62 6c 65 64 2c 20 74 68 65 20 66 6f  disabled, the fo
13300 6c 6c 6f 77 69 6e 67 20 53 51 4c 69 74 65 20 69  llowing SQLite i
13310 6e 74 65 72 66 61 63 65 73 20 62 65 63 6f 6d 65  nterfaces become
13320 20 6e 6f 6e 2d 6f 70 65 72 61 74 69 6f 6e 61 6c   non-operational
13330 3a 0a 2a 2a 20 20 20 3c 75 6c 3e 0a 2a 2a 20 20  :.**   <ul>.**  
13340 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 6d   <li> [sqlite3_m
13350 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 0a 2a 2a  emory_used()].**
13360 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33     <li> [sqlite3
13370 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65  _memory_highwate
13380 72 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b  r()].**   <li> [
13390 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65 61  sqlite3_soft_hea
133a0 70 5f 6c 69 6d 69 74 36 34 28 29 5d 0a 2a 2a 20  p_limit64()].** 
133b0 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f    <li> [sqlite3_
133c0 73 74 61 74 75 73 36 34 28 29 5d 0a 2a 2a 20 20  status64()].**  
133d0 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 20 5e 4d 65 6d   </ul>)^.** ^Mem
133e0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73  ory allocation s
133f0 74 61 74 69 73 74 69 63 73 20 61 72 65 20 65 6e  tatistics are en
13400 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74  abled by default
13410 20 75 6e 6c 65 73 73 20 53 51 4c 69 74 65 20 69   unless SQLite i
13420 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 77 69  s.** compiled wi
13430 74 68 20 5b 53 51 4c 49 54 45 5f 44 45 46 41 55  th [SQLITE_DEFAU
13440 4c 54 5f 4d 45 4d 53 54 41 54 55 53 5d 3d 30 20  LT_MEMSTATUS]=0 
13450 69 6e 20 77 68 69 63 68 20 63 61 73 65 20 6d 65  in which case me
13460 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69  mory.** allocati
13470 6f 6e 20 73 74 61 74 69 73 74 69 63 73 20 61 72  on statistics ar
13480 65 20 64 69 73 61 62 6c 65 64 20 62 79 20 64 65  e disabled by de
13490 66 61 75 6c 74 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a  fault..** </dd>.
134a0 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
134b0 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 5d 5d 20  ONFIG_SCRATCH]] 
134c0 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
134d0 47 5f 53 43 52 41 54 43 48 3c 2f 64 74 3e 0a 2a  G_SCRATCH</dt>.*
134e0 2a 20 3c 64 64 3e 20 5e 54 68 65 20 53 51 4c 49  * <dd> ^The SQLI
134f0 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43  TE_CONFIG_SCRATC
13500 48 20 6f 70 74 69 6f 6e 20 73 70 65 63 69 66 69  H option specifi
13510 65 73 20 61 20 73 74 61 74 69 63 20 6d 65 6d 6f  es a static memo
13520 72 79 20 62 75 66 66 65 72 0a 2a 2a 20 74 68 61  ry buffer.** tha
13530 74 20 53 51 4c 69 74 65 20 63 61 6e 20 75 73 65  t SQLite can use
13540 20 66 6f 72 20 73 63 72 61 74 63 68 20 6d 65 6d   for scratch mem
13550 6f 72 79 2e 20 20 5e 28 54 68 65 72 65 20 61 72  ory.  ^(There ar
13560 65 20 74 68 72 65 65 20 61 72 67 75 6d 65 6e 74  e three argument
13570 73 0a 2a 2a 20 74 6f 20 53 51 4c 49 54 45 5f 43  s.** to SQLITE_C
13580 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 3a 20 20  ONFIG_SCRATCH:  
13590 41 20 70 6f 69 6e 74 65 72 20 61 6e 20 38 2d 62  A pointer an 8-b
135a0 79 74 65 0a 2a 2a 20 61 6c 69 67 6e 65 64 20 6d  yte.** aligned m
135b0 65 6d 6f 72 79 20 62 75 66 66 65 72 20 66 72 6f  emory buffer fro
135c0 6d 20 77 68 69 63 68 20 74 68 65 20 73 63 72 61  m which the scra
135d0 74 63 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20  tch allocations 
135e0 77 69 6c 6c 20 62 65 0a 2a 2a 20 64 72 61 77 6e  will be.** drawn
135f0 2c 20 74 68 65 20 73 69 7a 65 20 6f 66 20 65 61  , the size of ea
13600 63 68 20 73 63 72 61 74 63 68 20 61 6c 6c 6f 63  ch scratch alloc
13610 61 74 69 6f 6e 20 28 73 7a 29 2c 0a 2a 2a 20 61  ation (sz),.** a
13620 6e 64 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6e  nd the maximum n
13630 75 6d 62 65 72 20 6f 66 20 73 63 72 61 74 63 68  umber of scratch
13640 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 28 4e 29   allocations (N)
13650 2e 29 5e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74  .)^.** The first
13660 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 74 20 62   argument must b
13670 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  e a pointer to a
13680 6e 20 38 2d 62 79 74 65 20 61 6c 69 67 6e 65 64  n 8-byte aligned
13690 20 62 75 66 66 65 72 0a 2a 2a 20 6f 66 20 61 74   buffer.** of at
136a0 20 6c 65 61 73 74 20 73 7a 2a 4e 20 62 79 74 65   least sz*N byte
136b0 73 20 6f 66 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20  s of memory..** 
136c0 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 6e 6f 74  ^SQLite will not
136d0 20 75 73 65 20 6d 6f 72 65 20 74 68 61 6e 20 6f   use more than o
136e0 6e 65 20 73 63 72 61 74 63 68 20 62 75 66 66 65  ne scratch buffe
136f0 72 73 20 70 65 72 20 74 68 72 65 61 64 2e 0a 2a  rs per thread..*
13700 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 6e  * ^SQLite will n
13710 65 76 65 72 20 72 65 71 75 65 73 74 20 61 20 73  ever request a s
13720 63 72 61 74 63 68 20 62 75 66 66 65 72 20 74 68  cratch buffer th
13730 61 74 20 69 73 20 6d 6f 72 65 20 74 68 61 6e 20  at is more than 
13740 36 0a 2a 2a 20 74 69 6d 65 73 20 74 68 65 20 64  6.** times the d
13750 61 74 61 62 61 73 65 20 70 61 67 65 20 73 69 7a  atabase page siz
13760 65 2e 0a 2a 2a 20 5e 49 66 20 53 51 4c 69 74 65  e..** ^If SQLite
13770 20 6e 65 65 64 73 20 6e 65 65 64 73 20 61 64 64   needs needs add
13780 69 74 69 6f 6e 61 6c 0a 2a 2a 20 73 63 72 61 74  itional.** scrat
13790 63 68 20 6d 65 6d 6f 72 79 20 62 65 79 6f 6e 64  ch memory beyond
137a0 20 77 68 61 74 20 69 73 20 70 72 6f 76 69 64 65   what is provide
137b0 64 20 62 79 20 74 68 69 73 20 63 6f 6e 66 69 67  d by this config
137c0 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2c 20  uration option, 
137d0 74 68 65 6e 20 0a 2a 2a 20 5b 73 71 6c 69 74 65  then .** [sqlite
137e0 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 77 69 6c 6c  3_malloc()] will
137f0 20 62 65 20 75 73 65 64 20 74 6f 20 6f 62 74 61   be used to obta
13800 69 6e 20 74 68 65 20 6d 65 6d 6f 72 79 20 6e 65  in the memory ne
13810 65 64 65 64 2e 3c 70 3e 0a 2a 2a 20 5e 57 68 65  eded.<p>.** ^Whe
13820 6e 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  n the applicatio
13830 6e 20 70 72 6f 76 69 64 65 73 20 61 6e 79 20 61  n provides any a
13840 6d 6f 75 6e 74 20 6f 66 20 73 63 72 61 74 63 68  mount of scratch
13850 20 6d 65 6d 6f 72 79 20 75 73 69 6e 67 0a 2a 2a   memory using.**
13860 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53   SQLITE_CONFIG_S
13870 43 52 41 54 43 48 2c 20 53 51 4c 69 74 65 20 61  CRATCH, SQLite a
13880 76 6f 69 64 73 20 75 6e 6e 65 63 65 73 73 61 72  voids unnecessar
13890 79 20 6c 61 72 67 65 0a 2a 2a 20 5b 73 71 6c 69  y large.** [sqli
138a0 74 65 33 5f 6d 61 6c 6c 6f 63 7c 68 65 61 70 20  te3_malloc|heap 
138b0 61 6c 6c 6f 63 61 74 69 6f 6e 73 5d 2e 0a 2a 2a  allocations]..**
138c0 20 54 68 69 73 20 63 61 6e 20 68 65 6c 70 20 5b   This can help [
138d0 52 6f 62 73 6f 6e 20 70 72 6f 6f 66 7c 70 72 65  Robson proof|pre
138e0 76 65 6e 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  vent memory allo
138f0 63 61 74 69 6f 6e 20 66 61 69 6c 75 72 65 73 5d  cation failures]
13900 20 64 75 65 20 74 6f 20 68 65 61 70 0a 2a 2a 20   due to heap.** 
13910 66 72 61 67 6d 65 6e 74 61 74 69 6f 6e 20 69 6e  fragmentation in
13920 20 6c 6f 77 2d 6d 65 6d 6f 72 79 20 65 6d 62 65   low-memory embe
13930 64 64 65 64 20 73 79 73 74 65 6d 73 2e 0a 2a 2a  dded systems..**
13940 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53   </dd>.**.** [[S
13950 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47  QLITE_CONFIG_PAG
13960 45 43 41 43 48 45 5d 5d 20 3c 64 74 3e 53 51 4c  ECACHE]] <dt>SQL
13970 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43  ITE_CONFIG_PAGEC
13980 41 43 48 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  ACHE</dt>.** <dd
13990 3e 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f  > ^The SQLITE_CO
139a0 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 20 6f  NFIG_PAGECACHE o
139b0 70 74 69 6f 6e 20 73 70 65 63 69 66 69 65 73 20  ption specifies 
139c0 61 20 6d 65 6d 6f 72 79 20 70 6f 6f 6c 0a 2a 2a  a memory pool.**
139d0 20 74 68 61 74 20 53 51 4c 69 74 65 20 63 61 6e   that SQLite can
139e0 20 75 73 65 20 66 6f 72 20 74 68 65 20 64 61 74   use for the dat
139f0 61 62 61 73 65 20 70 61 67 65 20 63 61 63 68 65  abase page cache
13a00 20 77 69 74 68 20 74 68 65 20 64 65 66 61 75 6c   with the defaul
13a10 74 20 70 61 67 65 0a 2a 2a 20 63 61 63 68 65 20  t page.** cache 
13a20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20  implementation. 
13a30 20 0a 2a 2a 20 54 68 69 73 20 63 6f 6e 66 69 67   .** This config
13a40 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69  uration option i
13a50 73 20 61 20 6e 6f 2d 6f 70 20 69 66 20 61 6e 20  s a no-op if an 
13a60 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
13a70 6e 65 20 70 61 67 65 0a 2a 2a 20 63 61 63 68 65  ne page.** cache
13a80 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
13a90 69 73 20 6c 6f 61 64 65 64 20 75 73 69 6e 67 20  is loaded using 
13aa0 74 68 65 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  the [SQLITE_CONF
13ab0 49 47 5f 50 43 41 43 48 45 32 5d 2e 0a 2a 2a 20  IG_PCACHE2]..** 
13ac0 5e 54 68 65 72 65 20 61 72 65 20 74 68 72 65 65  ^There are three
13ad0 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 53 51   arguments to SQ
13ae0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45  LITE_CONFIG_PAGE
13af0 43 41 43 48 45 3a 20 41 20 70 6f 69 6e 74 65 72  CACHE: A pointer
13b00 20 74 6f 0a 2a 2a 20 38 2d 62 79 74 65 20 61 6c   to.** 8-byte al
13b10 69 67 6e 65 64 20 6d 65 6d 6f 72 79 20 28 70 4d  igned memory (pM
13b20 65 6d 29 2c 20 74 68 65 20 73 69 7a 65 20 6f 66  em), the size of
13b30 20 65 61 63 68 20 70 61 67 65 20 63 61 63 68 65   each page cache
13b40 20 6c 69 6e 65 20 28 73 7a 29 2c 0a 2a 2a 20 61   line (sz),.** a
13b50 6e 64 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  nd the number of
13b60 20 63 61 63 68 65 20 6c 69 6e 65 73 20 28 4e 29   cache lines (N)
13b70 2e 0a 2a 2a 20 54 68 65 20 73 7a 20 61 72 67 75  ..** The sz argu
13b80 6d 65 6e 74 20 73 68 6f 75 6c 64 20 62 65 20 74  ment should be t
13b90 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 6c  he size of the l
13ba0 61 72 67 65 73 74 20 64 61 74 61 62 61 73 65 20  argest database 
13bb0 70 61 67 65 0a 2a 2a 20 28 61 20 70 6f 77 65 72  page.** (a power
13bc0 20 6f 66 20 74 77 6f 20 62 65 74 77 65 65 6e 20   of two between 
13bd0 35 31 32 20 61 6e 64 20 36 35 35 33 36 29 20 70  512 and 65536) p
13be0 6c 75 73 20 73 6f 6d 65 20 65 78 74 72 61 20 62  lus some extra b
13bf0 79 74 65 73 20 66 6f 72 20 65 61 63 68 0a 2a 2a  ytes for each.**
13c00 20 70 61 67 65 20 68 65 61 64 65 72 2e 20 20 5e   page header.  ^
13c10 54 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 65 78  The number of ex
13c20 74 72 61 20 62 79 74 65 73 20 6e 65 65 64 65 64  tra bytes needed
13c30 20 62 79 20 74 68 65 20 70 61 67 65 20 68 65 61   by the page hea
13c40 64 65 72 0a 2a 2a 20 63 61 6e 20 62 65 20 64 65  der.** can be de
13c50 74 65 72 6d 69 6e 65 64 20 75 73 69 6e 67 20 5b  termined using [
13c60 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43  SQLITE_CONFIG_PC
13c70 41 43 48 45 5f 48 44 52 53 5a 5d 2e 0a 2a 2a 20  ACHE_HDRSZ]..** 
13c80 5e 49 74 20 69 73 20 68 61 72 6d 6c 65 73 73 2c  ^It is harmless,
13c90 20 61 70 61 72 74 20 66 72 6f 6d 20 74 68 65 20   apart from the 
13ca0 77 61 73 74 65 64 20 6d 65 6d 6f 72 79 2c 0a 2a  wasted memory,.*
13cb0 2a 20 66 6f 72 20 74 68 65 20 73 7a 20 70 61 72  * for the sz par
13cc0 61 6d 65 74 65 72 20 74 6f 20 62 65 20 6c 61 72  ameter to be lar
13cd0 67 65 72 20 74 68 61 6e 20 6e 65 63 65 73 73 61  ger than necessa
13ce0 72 79 2e 20 20 54 68 65 20 70 4d 65 6d 0a 2a 2a  ry.  The pMem.**
13cf0 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 74 20 62   argument must b
13d00 65 20 65 69 74 68 65 72 20 61 20 4e 55 4c 4c 20  e either a NULL 
13d10 70 6f 69 6e 74 65 72 20 6f 72 20 61 20 70 6f 69  pointer or a poi
13d20 6e 74 65 72 20 74 6f 20 61 6e 20 38 2d 62 79 74  nter to an 8-byt
13d30 65 0a 2a 2a 20 61 6c 69 67 6e 65 64 20 62 6c 6f  e.** aligned blo
13d40 63 6b 20 6f 66 20 6d 65 6d 6f 72 79 20 6f 66 20  ck of memory of 
13d50 61 74 20 6c 65 61 73 74 20 73 7a 2a 4e 20 62 79  at least sz*N by
13d60 74 65 73 2c 20 6f 74 68 65 72 77 69 73 65 0a 2a  tes, otherwise.*
13d70 2a 20 73 75 62 73 65 71 75 65 6e 74 20 62 65 68  * subsequent beh
13d80 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e  avior is undefin
13d90 65 64 2e 0a 2a 2a 20 5e 57 68 65 6e 20 70 4d 65  ed..** ^When pMe
13da0 6d 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 53  m is not NULL, S
13db0 51 4c 69 74 65 20 77 69 6c 6c 20 73 74 72 69 76  QLite will striv
13dc0 65 20 74 6f 20 75 73 65 20 74 68 65 20 6d 65 6d  e to use the mem
13dd0 6f 72 79 20 70 72 6f 76 69 64 65 64 0a 2a 2a 20  ory provided.** 
13de0 74 6f 20 73 61 74 69 73 66 79 20 70 61 67 65 20  to satisfy page 
13df0 63 61 63 68 65 20 6e 65 65 64 73 2c 20 66 61 6c  cache needs, fal
13e00 6c 69 6e 67 20 62 61 63 6b 20 74 6f 20 5b 73 71  ling back to [sq
13e10 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20  lite3_malloc()] 
13e20 69 66 0a 2a 2a 20 61 20 70 61 67 65 20 63 61 63  if.** a page cac
13e30 68 65 20 6c 69 6e 65 20 69 73 20 6c 61 72 67 65  he line is large
13e40 72 20 74 68 61 6e 20 73 7a 20 62 79 74 65 73 20  r than sz bytes 
13e50 6f 72 20 69 66 20 61 6c 6c 20 6f 66 20 74 68 65  or if all of the
13e60 20 70 4d 65 6d 20 62 75 66 66 65 72 0a 2a 2a 20   pMem buffer.** 
13e70 69 73 20 65 78 68 61 75 73 74 65 64 2e 0a 2a 2a  is exhausted..**
13e80 20 5e 49 66 20 70 4d 65 6d 20 69 73 20 4e 55 4c   ^If pMem is NUL
13e90 4c 20 61 6e 64 20 4e 20 69 73 20 6e 6f 6e 2d 7a  L and N is non-z
13ea0 65 72 6f 2c 20 74 68 65 6e 20 65 61 63 68 20 64  ero, then each d
13eb0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
13ec0 6f 6e 0a 2a 2a 20 64 6f 65 73 20 61 6e 20 69 6e  on.** does an in
13ed0 69 74 69 61 6c 20 62 75 6c 6b 20 61 6c 6c 6f 63  itial bulk alloc
13ee0 61 74 69 6f 6e 20 66 6f 72 20 70 61 67 65 20 63  ation for page c
13ef0 61 63 68 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 66  ache memory.** f
13f00 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  rom [sqlite3_mal
13f10 6c 6f 63 28 29 5d 20 73 75 66 66 69 63 69 65 6e  loc()] sufficien
13f20 74 20 66 6f 72 20 4e 20 63 61 63 68 65 20 6c 69  t for N cache li
13f30 6e 65 73 20 69 66 20 4e 20 69 73 20 70 6f 73 69  nes if N is posi
13f40 74 69 76 65 20 6f 72 0a 2a 2a 20 6f 66 20 2d 31  tive or.** of -1
13f50 30 32 34 2a 4e 20 62 79 74 65 73 20 69 66 20 4e  024*N bytes if N
13f60 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 2e 20   is negative, . 
13f70 5e 49 66 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a  ^If additional.*
13f80 2a 20 70 61 67 65 20 63 61 63 68 65 20 6d 65 6d  * page cache mem
13f90 6f 72 79 20 69 73 20 6e 65 65 64 65 64 20 62 65  ory is needed be
13fa0 79 6f 6e 64 20 77 68 61 74 20 69 73 20 70 72 6f  yond what is pro
13fb0 76 69 64 65 64 20 62 79 20 74 68 65 20 69 6e 69  vided by the ini
13fc0 74 69 61 6c 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69  tial.** allocati
13fd0 6f 6e 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20  on, then SQLite 
13fe0 67 6f 65 73 20 74 6f 20 5b 73 71 6c 69 74 65 33  goes to [sqlite3
13ff0 5f 6d 61 6c 6c 6f 63 28 29 5d 20 73 65 70 61 72  _malloc()] separ
14000 61 74 65 6c 79 20 66 6f 72 20 65 61 63 68 0a 2a  ately for each.*
14010 2a 20 61 64 64 69 74 69 6f 6e 61 6c 20 63 61 63  * additional cac
14020 68 65 20 6c 69 6e 65 2e 20 3c 2f 64 64 3e 0a 2a  he line. </dd>.*
14030 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
14040 4e 46 49 47 5f 48 45 41 50 5d 5d 20 3c 64 74 3e  NFIG_HEAP]] <dt>
14050 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45  SQLITE_CONFIG_HE
14060 41 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  AP</dt>.** <dd> 
14070 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  ^The SQLITE_CONF
14080 49 47 5f 48 45 41 50 20 6f 70 74 69 6f 6e 20 73  IG_HEAP option s
14090 70 65 63 69 66 69 65 73 20 61 20 73 74 61 74 69  pecifies a stati
140a0 63 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20  c memory buffer 
140b0 0a 2a 2a 20 74 68 61 74 20 53 51 4c 69 74 65 20  .** that SQLite 
140c0 77 69 6c 6c 20 75 73 65 20 66 6f 72 20 61 6c 6c  will use for all
140d0 20 6f 66 20 69 74 73 20 64 79 6e 61 6d 69 63 20   of its dynamic 
140e0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
140f0 6e 20 6e 65 65 64 73 0a 2a 2a 20 62 65 79 6f 6e  n needs.** beyon
14100 64 20 74 68 6f 73 65 20 70 72 6f 76 69 64 65 64  d those provided
14110 20 66 6f 72 20 62 79 20 5b 53 51 4c 49 54 45 5f   for by [SQLITE_
14120 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 5d 20  CONFIG_SCRATCH] 
14130 61 6e 64 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43  and.** [SQLITE_C
14140 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 5d  ONFIG_PAGECACHE]
14150 2e 0a 2a 2a 20 5e 54 68 65 20 53 51 4c 49 54 45  ..** ^The SQLITE
14160 5f 43 4f 4e 46 49 47 5f 48 45 41 50 20 6f 70 74  _CONFIG_HEAP opt
14170 69 6f 6e 20 69 73 20 6f 6e 6c 79 20 61 76 61 69  ion is only avai
14180 6c 61 62 6c 65 20 69 66 20 53 51 4c 69 74 65 20  lable if SQLite 
14190 69 73 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 77  is compiled.** w
141a0 69 74 68 20 65 69 74 68 65 72 20 5b 53 51 4c 49  ith either [SQLI
141b0 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53 59 53  TE_ENABLE_MEMSYS
141c0 33 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 45 4e  3] or [SQLITE_EN
141d0 41 42 4c 45 5f 4d 45 4d 53 59 53 35 5d 20 61 6e  ABLE_MEMSYS5] an
141e0 64 20 72 65 74 75 72 6e 73 0a 2a 2a 20 5b 53 51  d returns.** [SQ
141f0 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 69  LITE_ERROR] if i
14200 6e 76 6f 6b 65 64 20 6f 74 68 65 72 77 69 73 65  nvoked otherwise
14210 2e 0a 2a 2a 20 5e 54 68 65 72 65 20 61 72 65 20  ..** ^There are 
14220 74 68 72 65 65 20 61 72 67 75 6d 65 6e 74 73 20  three arguments 
14230 74 6f 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  to SQLITE_CONFIG
14240 5f 48 45 41 50 3a 0a 2a 2a 20 41 6e 20 38 2d 62  _HEAP:.** An 8-b
14250 79 74 65 20 61 6c 69 67 6e 65 64 20 70 6f 69 6e  yte aligned poin
14260 74 65 72 20 74 6f 20 74 68 65 20 6d 65 6d 6f 72  ter to the memor
14270 79 2c 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72  y,.** the number
14280 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 65   of bytes in the
14290 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 2c 20   memory buffer, 
142a0 61 6e 64 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20  and the minimum 
142b0 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 2e  allocation size.
142c0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 72 73  .** ^If the firs
142d0 74 20 70 6f 69 6e 74 65 72 20 28 74 68 65 20 6d  t pointer (the m
142e0 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72 29 20 69  emory pointer) i
142f0 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 53 51 4c  s NULL, then SQL
14300 69 74 65 20 72 65 76 65 72 74 73 0a 2a 2a 20 74  ite reverts.** t
14310 6f 20 75 73 69 6e 67 20 69 74 73 20 64 65 66 61  o using its defa
14320 75 6c 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ult memory alloc
14330 61 74 6f 72 20 28 74 68 65 20 73 79 73 74 65 6d  ator (the system
14340 20 6d 61 6c 6c 6f 63 28 29 20 69 6d 70 6c 65 6d   malloc() implem
14350 65 6e 74 61 74 69 6f 6e 29 2c 0a 2a 2a 20 75 6e  entation),.** un
14360 64 6f 69 6e 67 20 61 6e 79 20 70 72 69 6f 72 20  doing any prior 
14370 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 53  invocation of [S
14380 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c  QLITE_CONFIG_MAL
14390 4c 4f 43 5d 2e 20 20 5e 49 66 20 74 68 65 0a 2a  LOC].  ^If the.*
143a0 2a 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72  * memory pointer
143b0 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 74 68 65   is not NULL the
143c0 6e 20 74 68 65 20 61 6c 74 65 72 6e 61 74 69 76  n the alternativ
143d0 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f  e memory.** allo
143e0 63 61 74 6f 72 20 69 73 20 65 6e 67 61 67 65 64  cator is engaged
143f0 20 74 6f 20 68 61 6e 64 6c 65 20 61 6c 6c 20 6f   to handle all o
14400 66 20 53 51 4c 69 74 65 73 20 6d 65 6d 6f 72 79  f SQLites memory
14410 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64   allocation need
14420 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20  s..** The first 
14430 70 6f 69 6e 74 65 72 20 28 74 68 65 20 6d 65 6d  pointer (the mem
14440 6f 72 79 20 70 6f 69 6e 74 65 72 29 20 6d 75 73  ory pointer) mus
14450 74 20 62 65 20 61 6c 69 67 6e 65 64 20 74 6f 20  t be aligned to 
14460 61 6e 20 38 2d 62 79 74 65 0a 2a 2a 20 62 6f 75  an 8-byte.** bou
14470 6e 64 61 72 79 20 6f 72 20 73 75 62 73 65 71 75  ndary or subsequ
14480 65 6e 74 20 62 65 68 61 76 69 6f 72 20 6f 66 20  ent behavior of 
14490 53 51 4c 69 74 65 20 77 69 6c 6c 20 62 65 20 75  SQLite will be u
144a0 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 54 68 65  ndefined..** The
144b0 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 74   minimum allocat
144c0 69 6f 6e 20 73 69 7a 65 20 69 73 20 63 61 70 70  ion size is capp
144d0 65 64 20 61 74 20 32 2a 2a 31 32 2e 20 52 65 61  ed at 2**12. Rea
144e0 73 6f 6e 61 62 6c 65 20 76 61 6c 75 65 73 0a 2a  sonable values.*
144f0 2a 20 66 6f 72 20 74 68 65 20 6d 69 6e 69 6d 75  * for the minimu
14500 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a  m allocation siz
14510 65 20 61 72 65 20 32 2a 2a 35 20 74 68 72 6f 75  e are 2**5 throu
14520 67 68 20 32 2a 2a 38 2e 3c 2f 64 64 3e 0a 2a 2a  gh 2**8.</dd>.**
14530 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
14540 46 49 47 5f 4d 55 54 45 58 5d 5d 20 3c 64 74 3e  FIG_MUTEX]] <dt>
14550 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55  SQLITE_CONFIG_MU
14560 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  TEX</dt>.** <dd>
14570 20 5e 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f   ^(The SQLITE_CO
14580 4e 46 49 47 5f 4d 55 54 45 58 20 6f 70 74 69 6f  NFIG_MUTEX optio
14590 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65  n takes a single
145a0 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20   argument which 
145b0 69 73 20 61 0a 2a 2a 20 70 6f 69 6e 74 65 72 20  is a.** pointer 
145c0 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f  to an instance o
145d0 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d  f the [sqlite3_m
145e0 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74  utex_methods] st
145f0 72 75 63 74 75 72 65 2e 0a 2a 2a 20 54 68 65 20  ructure..** The 
14600 61 72 67 75 6d 65 6e 74 20 73 70 65 63 69 66 69  argument specifi
14610 65 73 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6c  es alternative l
14620 6f 77 2d 6c 65 76 65 6c 20 6d 75 74 65 78 20 72  ow-level mutex r
14630 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20 75 73  outines to be us
14640 65 64 0a 2a 2a 20 69 6e 20 70 6c 61 63 65 20 74  ed.** in place t
14650 68 65 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65  he mutex routine
14660 73 20 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c  s built into SQL
14670 69 74 65 2e 29 5e 20 20 5e 53 51 4c 69 74 65 20  ite.)^  ^SQLite 
14680 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 0a  makes a copy of.
14690 2a 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f  ** the content o
146a0 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d  f the [sqlite3_m
146b0 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74  utex_methods] st
146c0 72 75 63 74 75 72 65 20 62 65 66 6f 72 65 20 74  ructure before t
146d0 68 65 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73  he call to.** [s
146e0 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
146f0 20 72 65 74 75 72 6e 73 2e 20 5e 49 66 20 53 51   returns. ^If SQ
14700 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  Lite is compiled
14710 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51   with.** the [SQ
14720 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 20  LITE_THREADSAFE 
14730 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53  | SQLITE_THREADS
14740 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74  AFE=0] compile-t
14750 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a  ime option then.
14760 2a 2a 20 74 68 65 20 65 6e 74 69 72 65 20 6d 75  ** the entire mu
14770 74 65 78 69 6e 67 20 73 75 62 73 79 73 74 65 6d  texing subsystem
14780 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d   is omitted from
14790 20 74 68 65 20 62 75 69 6c 64 20 61 6e 64 20 68   the build and h
147a0 65 6e 63 65 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a  ence calls to.**
147b0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
147c0 28 29 5d 20 77 69 74 68 20 74 68 65 20 53 51 4c  ()] with the SQL
147d0 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58  ITE_CONFIG_MUTEX
147e0 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
147f0 70 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 72 65  ption will.** re
14800 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52  turn [SQLITE_ERR
14810 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  OR].</dd>.**.** 
14820 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
14830 47 45 54 4d 55 54 45 58 5d 5d 20 3c 64 74 3e 53  GETMUTEX]] <dt>S
14840 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
14850 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  MUTEX</dt>.** <d
14860 64 3e 20 5e 28 54 68 65 20 53 51 4c 49 54 45 5f  d> ^(The SQLITE_
14870 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 20  CONFIG_GETMUTEX 
14880 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73  option takes a s
14890 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77  ingle argument w
148a0 68 69 63 68 0a 2a 2a 20 69 73 20 61 20 70 6f 69  hich.** is a poi
148b0 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61  nter to an insta
148c0 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  nce of the [sqli
148d0 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64  te3_mutex_method
148e0 73 5d 20 73 74 72 75 63 74 75 72 65 2e 20 20 54  s] structure.  T
148f0 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d  he.** [sqlite3_m
14900 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a  utex_methods].**
14910 20 73 74 72 75 63 74 75 72 65 20 69 73 20 66 69   structure is fi
14920 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20 63 75  lled with the cu
14930 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 20  rrently defined 
14940 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73 2e 29  mutex routines.)
14950 5e 0a 2a 2a 20 54 68 69 73 20 6f 70 74 69 6f 6e  ^.** This option
14960 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
14970 6f 76 65 72 6c 6f 61 64 20 74 68 65 20 64 65 66  overload the def
14980 61 75 6c 74 20 6d 75 74 65 78 20 61 6c 6c 6f 63  ault mutex alloc
14990 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65  ation.** routine
149a0 73 20 77 69 74 68 20 61 20 77 72 61 70 70 65 72  s with a wrapper
149b0 20 75 73 65 64 20 74 6f 20 74 72 61 63 6b 20 6d   used to track m
149c0 75 74 65 78 20 75 73 61 67 65 20 66 6f 72 20 70  utex usage for p
149d0 65 72 66 6f 72 6d 61 6e 63 65 0a 2a 2a 20 70 72  erformance.** pr
149e0 6f 66 69 6c 69 6e 67 20 6f 72 20 74 65 73 74 69  ofiling or testi
149f0 6e 67 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2e  ng, for example.
14a00 20 20 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73     ^If SQLite is
14a10 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a   compiled with.*
14a20 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48  * the [SQLITE_TH
14a30 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54  READSAFE | SQLIT
14a40 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20  E_THREADSAFE=0] 
14a50 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
14a60 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20  ion then.** the 
14a70 65 6e 74 69 72 65 20 6d 75 74 65 78 69 6e 67 20  entire mutexing 
14a80 73 75 62 73 79 73 74 65 6d 20 69 73 20 6f 6d 69  subsystem is omi
14a90 74 74 65 64 20 66 72 6f 6d 20 74 68 65 20 62 75  tted from the bu
14aa0 69 6c 64 20 61 6e 64 20 68 65 6e 63 65 20 63 61  ild and hence ca
14ab0 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  lls to.** [sqlit
14ac0 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 74  e3_config()] wit
14ad0 68 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e  h the SQLITE_CON
14ae0 46 49 47 5f 47 45 54 4d 55 54 45 58 20 63 6f 6e  FIG_GETMUTEX con
14af0 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
14b00 6e 20 77 69 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e  n will.** return
14b10 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2e   [SQLITE_ERROR].
14b20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
14b30 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b  LITE_CONFIG_LOOK
14b40 41 53 49 44 45 5d 5d 20 3c 64 74 3e 53 51 4c 49  ASIDE]] <dt>SQLI
14b50 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53  TE_CONFIG_LOOKAS
14b60 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  IDE</dt>.** <dd>
14b70 20 5e 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f   ^(The SQLITE_CO
14b80 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 6f  NFIG_LOOKASIDE o
14b90 70 74 69 6f 6e 20 74 61 6b 65 73 20 74 77 6f 20  ption takes two 
14ba0 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74 20 64  arguments that d
14bb0 65 74 65 72 6d 69 6e 65 0a 2a 2a 20 74 68 65 20  etermine.** the 
14bc0 64 65 66 61 75 6c 74 20 73 69 7a 65 20 6f 66 20  default size of 
14bd0 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79  lookaside memory
14be0 20 6f 6e 20 65 61 63 68 20 5b 64 61 74 61 62 61   on each [databa
14bf0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a  se connection]..
14c00 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67  ** The first arg
14c10 75 6d 65 6e 74 20 69 73 20 74 68 65 0a 2a 2a 20  ument is the.** 
14c20 73 69 7a 65 20 6f 66 20 65 61 63 68 20 6c 6f 6f  size of each loo
14c30 6b 61 73 69 64 65 20 62 75 66 66 65 72 20 73 6c  kaside buffer sl
14c40 6f 74 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e  ot and the secon
14c50 64 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20  d is the number 
14c60 6f 66 0a 2a 2a 20 73 6c 6f 74 73 20 61 6c 6c 6f  of.** slots allo
14c70 63 61 74 65 64 20 74 6f 20 65 61 63 68 20 64 61  cated to each da
14c80 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
14c90 6e 2e 29 5e 20 20 5e 28 53 51 4c 49 54 45 5f 43  n.)^  ^(SQLITE_C
14ca0 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 0a  ONFIG_LOOKASIDE.
14cb0 2a 2a 20 73 65 74 73 20 74 68 65 20 3c 69 3e 64  ** sets the <i>d
14cc0 65 66 61 75 6c 74 3c 2f 69 3e 20 6c 6f 6f 6b 61  efault</i> looka
14cd0 73 69 64 65 20 73 69 7a 65 2e 20 54 68 65 20 5b  side size. The [
14ce0 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
14cf0 4c 4f 4f 4b 41 53 49 44 45 5d 0a 2a 2a 20 6f 70  LOOKASIDE].** op
14d00 74 69 6f 6e 20 74 6f 20 5b 73 71 6c 69 74 65 33  tion to [sqlite3
14d10 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 63 61  _db_config()] ca
14d20 6e 20 62 65 20 75 73 65 64 20 74 6f 20 63 68 61  n be used to cha
14d30 6e 67 65 20 74 68 65 20 6c 6f 6f 6b 61 73 69 64  nge the lookasid
14d40 65 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69  e.** configurati
14d50 6f 6e 20 6f 6e 20 69 6e 64 69 76 69 64 75 61 6c  on on individual
14d60 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 2e 29 5e 20   connections.)^ 
14d70 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
14d80 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43  LITE_CONFIG_PCAC
14d90 48 45 32 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45  HE2]] <dt>SQLITE
14da0 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 3c  _CONFIG_PCACHE2<
14db0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54  /dt>.** <dd> ^(T
14dc0 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
14dd0 5f 50 43 41 43 48 45 32 20 6f 70 74 69 6f 6e 20  _PCACHE2 option 
14de0 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61  takes a single a
14df0 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73  rgument which is
14e00 20 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74   .** a pointer t
14e10 6f 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 70 63  o an [sqlite3_pc
14e20 61 63 68 65 5f 6d 65 74 68 6f 64 73 32 5d 20 6f  ache_methods2] o
14e30 62 6a 65 63 74 2e 20 20 54 68 69 73 20 6f 62 6a  bject.  This obj
14e40 65 63 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a  ect specifies.**
14e50 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 20 74   the interface t
14e60 6f 20 61 20 63 75 73 74 6f 6d 20 70 61 67 65 20  o a custom page 
14e70 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61  cache implementa
14e80 74 69 6f 6e 2e 29 5e 0a 2a 2a 20 5e 53 51 4c 69  tion.)^.** ^SQLi
14e90 74 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20  te makes a copy 
14ea0 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
14eb0 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 32 5d  pcache_methods2]
14ec0 20 6f 62 6a 65 63 74 2e 3c 2f 64 64 3e 0a 2a 2a   object.</dd>.**
14ed0 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
14ee0 46 49 47 5f 47 45 54 50 43 41 43 48 45 32 5d 5d  FIG_GETPCACHE2]]
14ef0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
14f00 49 47 5f 47 45 54 50 43 41 43 48 45 32 3c 2f 64  IG_GETPCACHE2</d
14f10 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65  t>.** <dd> ^(The
14f20 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47   SQLITE_CONFIG_G
14f30 45 54 50 43 41 43 48 45 32 20 6f 70 74 69 6f 6e  ETPCACHE2 option
14f40 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20   takes a single 
14f50 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 0a 2a  argument which.*
14f60 2a 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  * is a pointer t
14f70 6f 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 70 63  o an [sqlite3_pc
14f80 61 63 68 65 5f 6d 65 74 68 6f 64 73 32 5d 20 6f  ache_methods2] o
14f90 62 6a 65 63 74 2e 20 20 53 51 4c 69 74 65 20 63  bject.  SQLite c
14fa0 6f 70 69 65 73 20 6f 66 0a 2a 2a 20 74 68 65 20  opies of.** the 
14fb0 63 75 72 72 65 6e 74 20 70 61 67 65 20 63 61 63  current page cac
14fc0 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
14fd0 6e 20 69 6e 74 6f 20 74 68 61 74 20 6f 62 6a 65  n into that obje
14fe0 63 74 2e 29 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a  ct.)^ </dd>.**.*
14ff0 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
15000 47 5f 4c 4f 47 5d 5d 20 3c 64 74 3e 53 51 4c 49  G_LOG]] <dt>SQLI
15010 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 3c 2f 64  TE_CONFIG_LOG</d
15020 74 3e 0a 2a 2a 20 3c 64 64 3e 20 54 68 65 20 53  t>.** <dd> The S
15030 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47  QLITE_CONFIG_LOG
15040 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64 20   option is used 
15050 74 6f 20 63 6f 6e 66 69 67 75 72 65 20 74 68 65  to configure the
15060 20 53 51 4c 69 74 65 0a 2a 2a 20 67 6c 6f 62 61   SQLite.** globa
15070 6c 20 5b 65 72 72 6f 72 20 6c 6f 67 5d 2e 0a 2a  l [error log]..*
15080 2a 20 28 5e 54 68 65 20 53 51 4c 49 54 45 5f 43  * (^The SQLITE_C
15090 4f 4e 46 49 47 5f 4c 4f 47 20 6f 70 74 69 6f 6e  ONFIG_LOG option
150a0 20 74 61 6b 65 73 20 74 77 6f 20 61 72 67 75 6d   takes two argum
150b0 65 6e 74 73 3a 20 61 20 70 6f 69 6e 74 65 72 20  ents: a pointer 
150c0 74 6f 20 61 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  to a.** function
150d0 20 77 69 74 68 20 61 20 63 61 6c 6c 20 73 69 67   with a call sig
150e0 6e 61 74 75 72 65 20 6f 66 20 76 6f 69 64 28 2a  nature of void(*
150f0 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73  )(void*,int,cons
15100 74 20 63 68 61 72 2a 29 2c 20 0a 2a 2a 20 61 6e  t char*), .** an
15110 64 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 76  d a pointer to v
15120 6f 69 64 2e 20 5e 49 66 20 74 68 65 20 66 75 6e  oid. ^If the fun
15130 63 74 69 6f 6e 20 70 6f 69 6e 74 65 72 20 69 73  ction pointer is
15140 20 6e 6f 74 20 4e 55 4c 4c 2c 20 69 74 20 69 73   not NULL, it is
15150 0a 2a 2a 20 69 6e 76 6f 6b 65 64 20 62 79 20 5b  .** invoked by [
15160 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20 74  sqlite3_log()] t
15170 6f 20 70 72 6f 63 65 73 73 20 65 61 63 68 20 6c  o process each l
15180 6f 67 67 69 6e 67 20 65 76 65 6e 74 2e 20 20 5e  ogging event.  ^
15190 49 66 20 74 68 65 0a 2a 2a 20 66 75 6e 63 74 69  If the.** functi
151a0 6f 6e 20 70 6f 69 6e 74 65 72 20 69 73 20 4e 55  on pointer is NU
151b0 4c 4c 2c 20 74 68 65 20 5b 73 71 6c 69 74 65 33  LL, the [sqlite3
151c0 5f 6c 6f 67 28 29 5d 20 69 6e 74 65 72 66 61 63  _log()] interfac
151d0 65 20 62 65 63 6f 6d 65 73 20 61 20 6e 6f 2d 6f  e becomes a no-o
151e0 70 2e 0a 2a 2a 20 5e 54 68 65 20 76 6f 69 64 20  p..** ^The void 
151f0 70 6f 69 6e 74 65 72 20 74 68 61 74 20 69 73 20  pointer that is 
15200 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  the second argum
15210 65 6e 74 20 74 6f 20 53 51 4c 49 54 45 5f 43 4f  ent to SQLITE_CO
15220 4e 46 49 47 5f 4c 4f 47 20 69 73 0a 2a 2a 20 70  NFIG_LOG is.** p
15230 61 73 73 65 64 20 74 68 72 6f 75 67 68 20 61 73  assed through as
15240 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d   the first param
15250 65 74 65 72 20 74 6f 20 74 68 65 20 61 70 70 6c  eter to the appl
15260 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
15270 6c 6f 67 67 65 72 0a 2a 2a 20 66 75 6e 63 74 69  logger.** functi
15280 6f 6e 20 77 68 65 6e 65 76 65 72 20 74 68 61 74  on whenever that
15290 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 69 6e 76   function is inv
152a0 6f 6b 65 64 2e 20 20 5e 54 68 65 20 73 65 63 6f  oked.  ^The seco
152b0 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a  nd parameter to.
152c0 2a 2a 20 74 68 65 20 6c 6f 67 67 65 72 20 66 75  ** the logger fu
152d0 6e 63 74 69 6f 6e 20 69 73 20 61 20 63 6f 70 79  nction is a copy
152e0 20 6f 66 20 74 68 65 20 66 69 72 73 74 20 70 61   of the first pa
152f0 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 63  rameter to the c
15300 6f 72 72 65 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20  orresponding.** 
15310 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20  [sqlite3_log()] 
15320 63 61 6c 6c 20 61 6e 64 20 69 73 20 69 6e 74 65  call and is inte
15330 6e 64 65 64 20 74 6f 20 62 65 20 61 20 5b 72 65  nded to be a [re
15340 73 75 6c 74 20 63 6f 64 65 5d 20 6f 72 20 61 6e  sult code] or an
15350 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65  .** [extended re
15360 73 75 6c 74 20 63 6f 64 65 5d 2e 20 20 5e 54 68  sult code].  ^Th
15370 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  e third paramete
15380 72 20 70 61 73 73 65 64 20 74 6f 20 74 68 65 20  r passed to the 
15390 6c 6f 67 67 65 72 20 69 73 0a 2a 2a 20 6c 6f 67  logger is.** log
153a0 20 6d 65 73 73 61 67 65 20 61 66 74 65 72 20 66   message after f
153b0 6f 72 6d 61 74 74 69 6e 67 20 76 69 61 20 5b 73  ormatting via [s
153c0 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28  qlite3_snprintf(
153d0 29 5d 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74  )]..** The SQLit
153e0 65 20 6c 6f 67 67 69 6e 67 20 69 6e 74 65 72 66  e logging interf
153f0 61 63 65 20 69 73 20 6e 6f 74 20 72 65 65 6e 74  ace is not reent
15400 72 61 6e 74 3b 20 74 68 65 20 6c 6f 67 67 65 72  rant; the logger
15410 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 73 75 70   function.** sup
15420 70 6c 69 65 64 20 62 79 20 74 68 65 20 61 70 70  plied by the app
15430 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f  lication must no
15440 74 20 69 6e 76 6f 6b 65 20 61 6e 79 20 53 51 4c  t invoke any SQL
15450 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a  ite interface..*
15460 2a 20 49 6e 20 61 20 6d 75 6c 74 69 2d 74 68 72  * In a multi-thr
15470 65 61 64 65 64 20 61 70 70 6c 69 63 61 74 69 6f  eaded applicatio
15480 6e 2c 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  n, the applicati
15490 6f 6e 2d 64 65 66 69 6e 65 64 20 6c 6f 67 67 65  on-defined logge
154a0 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 6d 75  r.** function mu
154b0 73 74 20 62 65 20 74 68 72 65 61 64 73 61 66 65  st be threadsafe
154c0 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  . </dd>.**.** [[
154d0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52  SQLITE_CONFIG_UR
154e0 49 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  I]] <dt>SQLITE_C
154f0 4f 4e 46 49 47 5f 55 52 49 0a 2a 2a 20 3c 64 64  ONFIG_URI.** <dd
15500 3e 5e 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f  >^(The SQLITE_CO
15510 4e 46 49 47 5f 55 52 49 20 6f 70 74 69 6f 6e 20  NFIG_URI option 
15520 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61  takes a single a
15530 72 67 75 6d 65 6e 74 20 6f 66 20 74 79 70 65 20  rgument of type 
15540 69 6e 74 2e 0a 2a 2a 20 49 66 20 6e 6f 6e 2d 7a  int..** If non-z
15550 65 72 6f 2c 20 74 68 65 6e 20 55 52 49 20 68 61  ero, then URI ha
15560 6e 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c  ndling is global
15570 6c 79 20 65 6e 61 62 6c 65 64 2e 20 49 66 20 74  ly enabled. If t
15580 68 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  he parameter is 
15590 7a 65 72 6f 2c 0a 2a 2a 20 74 68 65 6e 20 55 52  zero,.** then UR
155a0 49 20 68 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c  I handling is gl
155b0 6f 62 61 6c 6c 79 20 64 69 73 61 62 6c 65 64 2e  obally disabled.
155c0 29 5e 20 5e 49 66 20 55 52 49 20 68 61 6e 64 6c  )^ ^If URI handl
155d0 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79 0a  ing is globally.
155e0 2a 2a 20 65 6e 61 62 6c 65 64 2c 20 61 6c 6c 20  ** enabled, all 
155f0 66 69 6c 65 6e 61 6d 65 73 20 70 61 73 73 65 64  filenames passed
15600 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65   to [sqlite3_ope
15610 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f  n()], [sqlite3_o
15620 70 65 6e 5f 76 32 28 29 5d 2c 0a 2a 2a 20 5b 73  pen_v2()],.** [s
15630 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d  qlite3_open16()]
15640 20 6f 72 0a 2a 2a 20 73 70 65 63 69 66 69 65 64   or.** specified
15650 20 61 73 20 70 61 72 74 20 6f 66 20 5b 41 54 54   as part of [ATT
15660 41 43 48 5d 20 63 6f 6d 6d 61 6e 64 73 20 61 72  ACH] commands ar
15670 65 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73  e interpreted as
15680 20 55 52 49 73 2c 20 72 65 67 61 72 64 6c 65 73   URIs, regardles
15690 73 0a 2a 2a 20 6f 66 20 77 68 65 74 68 65 72 20  s.** of whether 
156a0 6f 72 20 6e 6f 74 20 74 68 65 20 5b 53 51 4c 49  or not the [SQLI
156b0 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 66 6c 61  TE_OPEN_URI] fla
156c0 67 20 69 73 20 73 65 74 20 77 68 65 6e 20 74 68  g is set when th
156d0 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f  e database.** co
156e0 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e  nnection is open
156f0 65 64 2e 20 5e 49 66 20 69 74 20 69 73 20 67 6c  ed. ^If it is gl
15700 6f 62 61 6c 6c 79 20 64 69 73 61 62 6c 65 64 2c  obally disabled,
15710 20 66 69 6c 65 6e 61 6d 65 73 20 61 72 65 0a 2a   filenames are.*
15720 2a 20 6f 6e 6c 79 20 69 6e 74 65 72 70 72 65 74  * only interpret
15730 65 64 20 61 73 20 55 52 49 73 20 69 66 20 74 68  ed as URIs if th
15740 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52  e SQLITE_OPEN_UR
15750 49 20 66 6c 61 67 20 69 73 20 73 65 74 20 77 68  I flag is set wh
15760 65 6e 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61  en the.** databa
15770 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  se connection is
15780 20 6f 70 65 6e 65 64 2e 20 5e 28 42 79 20 64 65   opened. ^(By de
15790 66 61 75 6c 74 2c 20 55 52 49 20 68 61 6e 64 6c  fault, URI handl
157a0 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79 0a  ing is globally.
157b0 2a 2a 20 64 69 73 61 62 6c 65 64 2e 20 54 68 65  ** disabled. The
157c0 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65 20 6d   default value m
157d0 61 79 20 62 65 20 63 68 61 6e 67 65 64 20 62 79  ay be changed by
157e0 20 63 6f 6d 70 69 6c 69 6e 67 20 77 69 74 68 20   compiling with 
157f0 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55  the.** [SQLITE_U
15800 53 45 5f 55 52 49 5d 20 73 79 6d 62 6f 6c 20 64  SE_URI] symbol d
15810 65 66 69 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20  efined.)^.**.** 
15820 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
15830 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53  COVERING_INDEX_S
15840 43 41 4e 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45  CAN]] <dt>SQLITE
15850 5f 43 4f 4e 46 49 47 5f 43 4f 56 45 52 49 4e 47  _CONFIG_COVERING
15860 5f 49 4e 44 45 58 5f 53 43 41 4e 0a 2a 2a 20 3c  _INDEX_SCAN.** <
15870 64 64 3e 5e 54 68 65 20 53 51 4c 49 54 45 5f 43  dd>^The SQLITE_C
15880 4f 4e 46 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49  ONFIG_COVERING_I
15890 4e 44 45 58 5f 53 43 41 4e 20 6f 70 74 69 6f 6e  NDEX_SCAN option
158a0 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20   takes a single 
158b0 69 6e 74 65 67 65 72 0a 2a 2a 20 61 72 67 75 6d  integer.** argum
158c0 65 6e 74 20 77 68 69 63 68 20 69 73 20 69 6e 74  ent which is int
158d0 65 72 70 72 65 74 65 64 20 61 73 20 61 20 62 6f  erpreted as a bo
158e0 6f 6c 65 61 6e 20 69 6e 20 6f 72 64 65 72 20 74  olean in order t
158f0 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64 69 73 61  o enable or disa
15900 62 6c 65 0a 2a 2a 20 74 68 65 20 75 73 65 20 6f  ble.** the use o
15910 66 20 63 6f 76 65 72 69 6e 67 20 69 6e 64 69 63  f covering indic
15920 65 73 20 66 6f 72 20 66 75 6c 6c 20 74 61 62 6c  es for full tabl
15930 65 20 73 63 61 6e 73 20 69 6e 20 74 68 65 20 71  e scans in the q
15940 75 65 72 79 20 6f 70 74 69 6d 69 7a 65 72 2e 0a  uery optimizer..
15950 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20  ** ^The default 
15960 73 65 74 74 69 6e 67 20 69 73 20 64 65 74 65 72  setting is deter
15970 6d 69 6e 65 64 0a 2a 2a 20 62 79 20 74 68 65 20  mined.** by the 
15980 5b 53 51 4c 49 54 45 5f 41 4c 4c 4f 57 5f 43 4f  [SQLITE_ALLOW_CO
15990 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41  VERING_INDEX_SCA
159a0 4e 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  N] compile-time 
159b0 6f 70 74 69 6f 6e 2c 20 6f 72 20 69 73 20 22 6f  option, or is "o
159c0 6e 22 0a 2a 2a 20 69 66 20 74 68 61 74 20 63 6f  n".** if that co
159d0 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
159e0 6e 20 69 73 20 6f 6d 69 74 74 65 64 2e 0a 2a 2a  n is omitted..**
159f0 20 54 68 65 20 61 62 69 6c 69 74 79 20 74 6f 20   The ability to 
15a00 64 69 73 61 62 6c 65 20 74 68 65 20 75 73 65 20  disable the use 
15a10 6f 66 20 63 6f 76 65 72 69 6e 67 20 69 6e 64 69  of covering indi
15a20 63 65 73 20 66 6f 72 20 66 75 6c 6c 20 74 61 62  ces for full tab
15a30 6c 65 20 73 63 61 6e 73 0a 2a 2a 20 69 73 20 62  le scans.** is b
15a40 65 63 61 75 73 65 20 73 6f 6d 65 20 69 6e 63 6f  ecause some inco
15a50 72 72 65 63 74 6c 79 20 63 6f 64 65 64 20 6c 65  rrectly coded le
15a60 67 61 63 79 20 61 70 70 6c 69 63 61 74 69 6f 6e  gacy application
15a70 73 20 6d 69 67 68 74 20 6d 61 6c 66 75 6e 63 74  s might malfunct
15a80 69 6f 6e 0a 2a 2a 20 77 68 65 6e 20 74 68 65 20  ion.** when the 
15a90 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 20 69 73 20  optimization is 
15aa0 65 6e 61 62 6c 65 64 2e 20 20 50 72 6f 76 69 64  enabled.  Provid
15ab0 69 6e 67 20 74 68 65 20 61 62 69 6c 69 74 79 20  ing the ability 
15ac0 74 6f 0a 2a 2a 20 64 69 73 61 62 6c 65 20 74 68  to.** disable th
15ad0 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 20 61  e optimization a
15ae0 6c 6c 6f 77 73 20 74 68 65 20 6f 6c 64 65 72 2c  llows the older,
15af0 20 62 75 67 67 79 20 61 70 70 6c 69 63 61 74 69   buggy applicati
15b00 6f 6e 20 63 6f 64 65 20 74 6f 20 77 6f 72 6b 0a  on code to work.
15b10 2a 2a 20 77 69 74 68 6f 75 74 20 63 68 61 6e 67  ** without chang
15b20 65 20 65 76 65 6e 20 77 69 74 68 20 6e 65 77 65  e even with newe
15b30 72 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51  r versions of SQ
15b40 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  Lite..**.** [[SQ
15b50 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43  LITE_CONFIG_PCAC
15b60 48 45 5d 5d 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  HE]] [[SQLITE_CO
15b70 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 5d 5d  NFIG_GETPCACHE]]
15b80 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  .** <dt>SQLITE_C
15b90 4f 4e 46 49 47 5f 50 43 41 43 48 45 20 61 6e 64  ONFIG_PCACHE and
15ba0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47   SQLITE_CONFIG_G
15bb0 45 54 50 43 41 43 48 45 0a 2a 2a 20 3c 64 64 3e  ETPCACHE.** <dd>
15bc0 20 54 68 65 73 65 20 6f 70 74 69 6f 6e 73 20 61   These options a
15bd0 72 65 20 6f 62 73 6f 6c 65 74 65 20 61 6e 64 20  re obsolete and 
15be0 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 75 73  should not be us
15bf0 65 64 20 62 79 20 6e 65 77 20 63 6f 64 65 2e 0a  ed by new code..
15c00 2a 2a 20 54 68 65 79 20 61 72 65 20 72 65 74 61  ** They are reta
15c10 69 6e 65 64 20 66 6f 72 20 62 61 63 6b 77 61 72  ined for backwar
15c20 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79  ds compatibility
15c30 20 62 75 74 20 61 72 65 20 6e 6f 77 20 6e 6f 2d   but are now no-
15c40 6f 70 73 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a  ops..** </dd>.**
15c50 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
15c60 46 49 47 5f 53 51 4c 4c 4f 47 5d 5d 0a 2a 2a 20  FIG_SQLLOG]].** 
15c70 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
15c80 47 5f 53 51 4c 4c 4f 47 0a 2a 2a 20 3c 64 64 3e  G_SQLLOG.** <dd>
15c90 54 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 6f  This option is o
15ca0 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 69 66  nly available if
15cb0 20 73 71 6c 69 74 65 20 69 73 20 63 6f 6d 70 69   sqlite is compi
15cc0 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20  led with the.** 
15cd0 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 53  [SQLITE_ENABLE_S
15ce0 51 4c 4c 4f 47 5d 20 70 72 65 2d 70 72 6f 63 65  QLLOG] pre-proce
15cf0 73 73 6f 72 20 6d 61 63 72 6f 20 64 65 66 69 6e  ssor macro defin
15d00 65 64 2e 20 54 68 65 20 66 69 72 73 74 20 61 72  ed. The first ar
15d10 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 0a 2a 2a  gument should.**
15d20 20 62 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   be a pointer to
15d30 20 61 20 66 75 6e 63 74 69 6f 6e 20 6f 66 20 74   a function of t
15d40 79 70 65 20 76 6f 69 64 28 2a 29 28 76 6f 69 64  ype void(*)(void
15d50 2a 2c 73 71 6c 69 74 65 33 2a 2c 63 6f 6e 73 74  *,sqlite3*,const
15d60 20 63 68 61 72 2a 2c 20 69 6e 74 29 2e 0a 2a 2a   char*, int)..**
15d70 20 54 68 65 20 73 65 63 6f 6e 64 20 73 68 6f 75   The second shou
15d80 6c 64 20 62 65 20 6f 66 20 74 79 70 65 20 28 76  ld be of type (v
15d90 6f 69 64 2a 29 2e 20 54 68 65 20 63 61 6c 6c 62  oid*). The callb
15da0 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 62  ack is invoked b
15db0 79 20 74 68 65 20 6c 69 62 72 61 72 79 0a 2a 2a  y the library.**
15dc0 20 69 6e 20 74 68 72 65 65 20 73 65 70 61 72 61   in three separa
15dd0 74 65 20 63 69 72 63 75 6d 73 74 61 6e 63 65 73  te circumstances
15de0 2c 20 69 64 65 6e 74 69 66 69 65 64 20 62 79 20  , identified by 
15df0 74 68 65 20 76 61 6c 75 65 20 70 61 73 73 65 64  the value passed
15e00 20 61 73 20 74 68 65 0a 2a 2a 20 66 6f 75 72 74   as the.** fourt
15e10 68 20 70 61 72 61 6d 65 74 65 72 2e 20 49 66 20  h parameter. If 
15e20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  the fourth param
15e30 65 74 65 72 20 69 73 20 30 2c 20 74 68 65 6e 20  eter is 0, then 
15e40 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
15e50 6e 65 63 74 69 6f 6e 0a 2a 2a 20 70 61 73 73 65  nection.** passe
15e60 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20  d as the second 
15e70 61 72 67 75 6d 65 6e 74 20 68 61 73 20 6a 75 73  argument has jus
15e80 74 20 62 65 65 6e 20 6f 70 65 6e 65 64 2e 20 54  t been opened. T
15e90 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e  he third argumen
15ea0 74 0a 2a 2a 20 70 6f 69 6e 74 73 20 74 6f 20 61  t.** points to a
15eb0 20 62 75 66 66 65 72 20 63 6f 6e 74 61 69 6e 69   buffer containi
15ec0 6e 67 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  ng the name of t
15ed0 68 65 20 6d 61 69 6e 20 64 61 74 61 62 61 73 65  he main database
15ee0 20 66 69 6c 65 2e 20 49 66 20 74 68 65 0a 2a 2a   file. If the.**
15ef0 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
15f00 72 20 69 73 20 31 2c 20 74 68 65 6e 20 74 68 65  r is 1, then the
15f10 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74   SQL statement t
15f20 68 61 74 20 74 68 65 20 74 68 69 72 64 20 70 61  hat the third pa
15f30 72 61 6d 65 74 65 72 0a 2a 2a 20 70 6f 69 6e 74  rameter.** point
15f40 73 20 74 6f 20 68 61 73 20 6a 75 73 74 20 62 65  s to has just be
15f50 65 6e 20 65 78 65 63 75 74 65 64 2e 20 4f 72 2c  en executed. Or,
15f60 20 69 66 20 74 68 65 20 66 6f 75 72 74 68 20 70   if the fourth p
15f70 61 72 61 6d 65 74 65 72 20 69 73 20 32 2c 20 74  arameter is 2, t
15f80 68 65 6e 0a 2a 2a 20 74 68 65 20 63 6f 6e 6e 65  hen.** the conne
15f90 63 74 69 6f 6e 20 62 65 69 6e 67 20 70 61 73 73  ction being pass
15fa0 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64  ed as the second
15fb0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 62 65   parameter is be
15fc0 69 6e 67 20 63 6c 6f 73 65 64 2e 20 54 68 65 0a  ing closed. The.
15fd0 2a 2a 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  ** third paramet
15fe0 65 72 20 69 73 20 70 61 73 73 65 64 20 4e 55 4c  er is passed NUL
15ff0 4c 20 49 6e 20 74 68 69 73 20 63 61 73 65 2e 20  L In this case. 
16000 20 41 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20 75   An example of u
16010 73 69 6e 67 20 74 68 69 73 0a 2a 2a 20 63 6f 6e  sing this.** con
16020 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
16030 6e 20 63 61 6e 20 62 65 20 73 65 65 6e 20 69 6e  n can be seen in
16040 20 74 68 65 20 22 74 65 73 74 5f 73 71 6c 6c 6f   the "test_sqllo
16050 67 2e 63 22 20 73 6f 75 72 63 65 20 66 69 6c 65  g.c" source file
16060 20 69 6e 0a 2a 2a 20 74 68 65 20 63 61 6e 6f 6e   in.** the canon
16070 69 63 61 6c 20 53 51 4c 69 74 65 20 73 6f 75 72  ical SQLite sour
16080 63 65 20 74 72 65 65 2e 3c 2f 64 64 3e 0a 2a 2a  ce tree.</dd>.**
16090 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
160a0 46 49 47 5f 4d 4d 41 50 5f 53 49 5a 45 5d 5d 0a  FIG_MMAP_SIZE]].
160b0 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ** <dt>SQLITE_CO
160c0 4e 46 49 47 5f 4d 4d 41 50 5f 53 49 5a 45 0a 2a  NFIG_MMAP_SIZE.*
160d0 2a 20 3c 64 64 3e 5e 53 51 4c 49 54 45 5f 43 4f  * <dd>^SQLITE_CO
160e0 4e 46 49 47 5f 4d 4d 41 50 5f 53 49 5a 45 20 74  NFIG_MMAP_SIZE t
160f0 61 6b 65 73 20 74 77 6f 20 36 34 2d 62 69 74 20  akes two 64-bit 
16100 69 6e 74 65 67 65 72 20 28 73 71 6c 69 74 65 33  integer (sqlite3
16110 5f 69 6e 74 36 34 29 20 76 61 6c 75 65 73 0a 2a  _int64) values.*
16120 2a 20 74 68 61 74 20 61 72 65 20 74 68 65 20 64  * that are the d
16130 65 66 61 75 6c 74 20 6d 6d 61 70 20 73 69 7a 65  efault mmap size
16140 20 6c 69 6d 69 74 20 28 74 68 65 20 64 65 66 61   limit (the defa
16150 75 6c 74 20 73 65 74 74 69 6e 67 20 66 6f 72 0a  ult setting for.
16160 2a 2a 20 5b 50 52 41 47 4d 41 20 6d 6d 61 70 5f  ** [PRAGMA mmap_
16170 73 69 7a 65 5d 29 20 61 6e 64 20 74 68 65 20 6d  size]) and the m
16180 61 78 69 6d 75 6d 20 61 6c 6c 6f 77 65 64 20 6d  aximum allowed m
16190 6d 61 70 20 73 69 7a 65 20 6c 69 6d 69 74 2e 0a  map size limit..
161a0 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20  ** ^The default 
161b0 73 65 74 74 69 6e 67 20 63 61 6e 20 62 65 20 6f  setting can be o
161c0 76 65 72 72 69 64 64 65 6e 20 62 79 20 65 61 63  verridden by eac
161d0 68 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  h database conne
161e0 63 74 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 65  ction using.** e
161f0 69 74 68 65 72 20 74 68 65 20 5b 50 52 41 47 4d  ither the [PRAGM
16200 41 20 6d 6d 61 70 5f 73 69 7a 65 5d 20 63 6f 6d  A mmap_size] com
16210 6d 61 6e 64 2c 20 6f 72 20 62 79 20 75 73 69 6e  mand, or by usin
16220 67 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45  g the.** [SQLITE
16230 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45  _FCNTL_MMAP_SIZE
16240 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 2e 20  ] file control. 
16250 20 5e 28 54 68 65 20 6d 61 78 69 6d 75 6d 20 61   ^(The maximum a
16260 6c 6c 6f 77 65 64 20 6d 6d 61 70 20 73 69 7a 65  llowed mmap size
16270 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 73 69 6c 65  .** will be sile
16280 6e 74 6c 79 20 74 72 75 6e 63 61 74 65 64 20 69  ntly truncated i
16290 66 20 6e 65 63 65 73 73 61 72 79 20 73 6f 20 74  f necessary so t
162a0 68 61 74 20 69 74 20 64 6f 65 73 20 6e 6f 74 20  hat it does not 
162b0 65 78 63 65 65 64 20 74 68 65 0a 2a 2a 20 63 6f  exceed the.** co
162c0 6d 70 69 6c 65 2d 74 69 6d 65 20 6d 61 78 69 6d  mpile-time maxim
162d0 75 6d 20 6d 6d 61 70 20 73 69 7a 65 20 73 65 74  um mmap size set
162e0 20 62 79 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49   by the.** [SQLI
162f0 54 45 5f 4d 41 58 5f 4d 4d 41 50 5f 53 49 5a 45  TE_MAX_MMAP_SIZE
16300 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
16310 70 74 69 6f 6e 2e 29 5e 0a 2a 2a 20 5e 49 66 20  ption.)^.** ^If 
16320 65 69 74 68 65 72 20 61 72 67 75 6d 65 6e 74 20  either argument 
16330 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 20 69  to this option i
16340 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e  s negative, then
16350 20 74 68 61 74 20 61 72 67 75 6d 65 6e 74 20 69   that argument i
16360 73 0a 2a 2a 20 63 68 61 6e 67 65 64 20 74 6f 20  s.** changed to 
16370 69 74 73 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  its compile-time
16380 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20   default..**.** 
16390 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
163a0 57 49 4e 33 32 5f 48 45 41 50 53 49 5a 45 5d 5d  WIN32_HEAPSIZE]]
163b0 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  .** <dt>SQLITE_C
163c0 4f 4e 46 49 47 5f 57 49 4e 33 32 5f 48 45 41 50  ONFIG_WIN32_HEAP
163d0 53 49 5a 45 0a 2a 2a 20 3c 64 64 3e 5e 54 68 65  SIZE.** <dd>^The
163e0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 57   SQLITE_CONFIG_W
163f0 49 4e 33 32 5f 48 45 41 50 53 49 5a 45 20 6f 70  IN32_HEAPSIZE op
16400 74 69 6f 6e 20 69 73 20 6f 6e 6c 79 20 61 76 61  tion is only ava
16410 69 6c 61 62 6c 65 20 69 66 20 53 51 4c 69 74 65  ilable if SQLite
16420 20 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20   is.** compiled 
16430 66 6f 72 20 57 69 6e 64 6f 77 73 20 77 69 74 68  for Windows with
16440 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 57 49 4e   the [SQLITE_WIN
16450 33 32 5f 4d 41 4c 4c 4f 43 5d 20 70 72 65 2d 70  32_MALLOC] pre-p
16460 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 0a 2a  rocessor macro.*
16470 2a 20 64 65 66 69 6e 65 64 2e 20 5e 53 51 4c 49  * defined. ^SQLI
16480 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f  TE_CONFIG_WIN32_
16490 48 45 41 50 53 49 5a 45 20 74 61 6b 65 73 20 61  HEAPSIZE takes a
164a0 20 33 32 2d 62 69 74 20 75 6e 73 69 67 6e 65 64   32-bit unsigned
164b0 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 0a 2a   integer value.*
164c0 2a 20 74 68 61 74 20 73 70 65 63 69 66 69 65 73  * that specifies
164d0 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 73 69 7a   the maximum siz
164e0 65 20 6f 66 20 74 68 65 20 63 72 65 61 74 65 64  e of the created
164f0 20 68 65 61 70 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53   heap..**.** [[S
16500 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41  QLITE_CONFIG_PCA
16510 43 48 45 5f 48 44 52 53 5a 5d 5d 0a 2a 2a 20 3c  CHE_HDRSZ]].** <
16520 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
16530 5f 50 43 41 43 48 45 5f 48 44 52 53 5a 0a 2a 2a  _PCACHE_HDRSZ.**
16540 20 3c 64 64 3e 5e 54 68 65 20 53 51 4c 49 54 45   <dd>^The SQLITE
16550 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 5f 48  _CONFIG_PCACHE_H
16560 44 52 53 5a 20 6f 70 74 69 6f 6e 20 74 61 6b 65  DRSZ option take
16570 73 20 61 20 73 69 6e 67 6c 65 20 70 61 72 61 6d  s a single param
16580 65 74 65 72 20 77 68 69 63 68 0a 2a 2a 20 69 73  eter which.** is
16590 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
165a0 20 69 6e 74 65 67 65 72 20 61 6e 64 20 77 72 69   integer and wri
165b0 74 65 73 20 69 6e 74 6f 20 74 68 61 74 20 69 6e  tes into that in
165c0 74 65 67 65 72 20 74 68 65 20 6e 75 6d 62 65 72  teger the number
165d0 20 6f 66 20 65 78 74 72 61 0a 2a 2a 20 62 79 74   of extra.** byt
165e0 65 73 20 70 65 72 20 70 61 67 65 20 72 65 71 75  es per page requ
165f0 69 72 65 64 20 66 6f 72 20 65 61 63 68 20 70 61  ired for each pa
16600 67 65 20 69 6e 20 5b 53 51 4c 49 54 45 5f 43 4f  ge in [SQLITE_CO
16610 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 5d 2e  NFIG_PAGECACHE].
16620 0a 2a 2a 20 54 68 65 20 61 6d 6f 75 6e 74 20 6f  .** The amount o
16630 66 20 65 78 74 72 61 20 73 70 61 63 65 20 72 65  f extra space re
16640 71 75 69 72 65 64 20 63 61 6e 20 63 68 61 6e 67  quired can chang
16650 65 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74  e depending on t
16660 68 65 20 63 6f 6d 70 69 6c 65 72 2c 0a 2a 2a 20  he compiler,.** 
16670 74 61 72 67 65 74 20 70 6c 61 74 66 6f 72 6d 2c  target platform,
16680 20 61 6e 64 20 53 51 4c 69 74 65 20 76 65 72 73   and SQLite vers
16690 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  ion..**.** [[SQL
166a0 49 54 45 5f 43 4f 4e 46 49 47 5f 50 4d 41 53 5a  ITE_CONFIG_PMASZ
166b0 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  ]].** <dt>SQLITE
166c0 5f 43 4f 4e 46 49 47 5f 50 4d 41 53 5a 0a 2a 2a  _CONFIG_PMASZ.**
166d0 20 3c 64 64 3e 5e 54 68 65 20 53 51 4c 49 54 45   <dd>^The SQLITE
166e0 5f 43 4f 4e 46 49 47 5f 50 4d 41 53 5a 20 6f 70  _CONFIG_PMASZ op
166f0 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e  tion takes a sin
16700 67 6c 65 20 70 61 72 61 6d 65 74 65 72 20 77 68  gle parameter wh
16710 69 63 68 0a 2a 2a 20 69 73 20 61 6e 20 75 6e 73  ich.** is an uns
16720 69 67 6e 65 64 20 69 6e 74 65 67 65 72 20 61 6e  igned integer an
16730 64 20 73 65 74 73 20 74 68 65 20 22 4d 69 6e 69  d sets the "Mini
16740 6d 75 6d 20 50 4d 41 20 53 69 7a 65 22 20 66 6f  mum PMA Size" fo
16750 72 20 74 68 65 20 6d 75 6c 74 69 74 68 72 65 61  r the multithrea
16760 64 65 64 0a 2a 2a 20 73 6f 72 74 65 72 20 74 6f  ded.** sorter to
16770 20 74 68 61 74 20 69 6e 74 65 67 65 72 2e 20 20   that integer.  
16780 54 68 65 20 64 65 66 61 75 6c 74 20 6d 69 6e 69  The default mini
16790 6d 75 6d 20 50 4d 41 20 53 69 7a 65 20 69 73 20  mum PMA Size is 
167a0 73 65 74 20 62 79 20 74 68 65 0a 2a 2a 20 5b 53  set by the.** [S
167b0 51 4c 49 54 45 5f 53 4f 52 54 45 52 5f 50 4d 41  QLITE_SORTER_PMA
167c0 53 5a 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  SZ] compile-time
167d0 20 6f 70 74 69 6f 6e 2e 20 20 4e 65 77 20 74 68   option.  New th
167e0 72 65 61 64 73 20 61 72 65 20 6c 61 75 6e 63 68  reads are launch
167f0 65 64 0a 2a 2a 20 74 6f 20 68 65 6c 70 20 77 69  ed.** to help wi
16800 74 68 20 73 6f 72 74 20 6f 70 65 72 61 74 69 6f  th sort operatio
16810 6e 73 20 77 68 65 6e 20 6d 75 6c 74 69 74 68 72  ns when multithr
16820 65 61 64 65 64 20 73 6f 72 74 69 6e 67 0a 2a 2a  eaded sorting.**
16830 20 69 73 20 65 6e 61 62 6c 65 64 20 28 75 73 69   is enabled (usi
16840 6e 67 20 74 68 65 20 5b 50 52 41 47 4d 41 20 74  ng the [PRAGMA t
16850 68 72 65 61 64 73 5d 20 63 6f 6d 6d 61 6e 64 29  hreads] command)
16860 20 61 6e 64 20 74 68 65 20 61 6d 6f 75 6e 74 20   and the amount 
16870 6f 66 20 63 6f 6e 74 65 6e 74 0a 2a 2a 20 74 6f  of content.** to
16880 20 62 65 20 73 6f 72 74 65 64 20 65 78 63 65 65   be sorted excee
16890 64 73 20 74 68 65 20 70 61 67 65 20 73 69 7a 65  ds the page size
168a0 20 74 69 6d 65 73 20 74 68 65 20 6d 69 6e 69 6d   times the minim
168b0 75 6d 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 50 52  um of the.** [PR
168c0 41 47 4d 41 20 63 61 63 68 65 5f 73 69 7a 65 5d  AGMA cache_size]
168d0 20 73 65 74 74 69 6e 67 20 61 6e 64 20 74 68 69   setting and thi
168e0 73 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 5b  s value..**.** [
168f0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53  [SQLITE_CONFIG_S
16900 54 4d 54 4a 52 4e 4c 5f 53 50 49 4c 4c 5d 5d 0a  TMTJRNL_SPILL]].
16910 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ** <dt>SQLITE_CO
16920 4e 46 49 47 5f 53 54 4d 54 4a 52 4e 4c 5f 53 50  NFIG_STMTJRNL_SP
16930 49 4c 4c 0a 2a 2a 20 3c 64 64 3e 5e 54 68 65 20  ILL.** <dd>^The 
16940 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 54  SQLITE_CONFIG_ST
16950 4d 54 4a 52 4e 4c 5f 53 50 49 4c 4c 20 6f 70 74  MTJRNL_SPILL opt
16960 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67  ion takes a sing
16970 6c 65 20 70 61 72 61 6d 65 74 65 72 20 77 68 69  le parameter whi
16980 63 68 0a 2a 2a 20 62 65 63 6f 6d 65 73 20 74 68  ch.** becomes th
16990 65 20 5b 73 74 61 74 65 6d 65 6e 74 20 6a 6f 75  e [statement jou
169a0 72 6e 61 6c 5d 20 73 70 69 6c 6c 2d 74 6f 2d 64  rnal] spill-to-d
169b0 69 73 6b 20 74 68 72 65 73 68 6f 6c 64 2e 20 20  isk threshold.  
169c0 0a 2a 2a 20 5b 53 74 61 74 65 6d 65 6e 74 20 6a  .** [Statement j
169d0 6f 75 72 6e 61 6c 73 5d 20 61 72 65 20 68 65 6c  ournals] are hel
169e0 64 20 69 6e 20 6d 65 6d 6f 72 79 20 75 6e 74 69  d in memory unti
169f0 6c 20 74 68 65 69 72 20 73 69 7a 65 20 28 69 6e  l their size (in
16a00 20 62 79 74 65 73 29 0a 2a 2a 20 65 78 63 65 65   bytes).** excee
16a10 64 73 20 74 68 69 73 20 74 68 72 65 73 68 6f 6c  ds this threshol
16a20 64 2c 20 61 74 20 77 68 69 63 68 20 70 6f 69 6e  d, at which poin
16a30 74 20 74 68 65 79 20 61 72 65 20 77 72 69 74 74  t they are writt
16a40 65 6e 20 74 6f 20 64 69 73 6b 2e 0a 2a 2a 20 4f  en to disk..** O
16a50 72 20 69 66 20 74 68 65 20 74 68 72 65 73 68 6f  r if the thresho
16a60 6c 64 20 69 73 20 2d 31 2c 20 73 74 61 74 65 6d  ld is -1, statem
16a70 65 6e 74 20 6a 6f 75 72 6e 61 6c 73 20 61 72 65  ent journals are
16a80 20 61 6c 77 61 79 73 20 68 65 6c 64 0a 2a 2a 20   always held.** 
16a90 65 78 63 6c 75 73 69 76 65 6c 79 20 69 6e 20 6d  exclusively in m
16aa0 65 6d 6f 72 79 2e 0a 2a 2a 20 53 69 6e 63 65 20  emory..** Since 
16ab0 6d 61 6e 79 20 73 74 61 74 65 6d 65 6e 74 20 6a  many statement j
16ac0 6f 75 72 6e 61 6c 73 20 6e 65 76 65 72 20 62 65  ournals never be
16ad0 63 6f 6d 65 20 6c 61 72 67 65 2c 20 73 65 74 74  come large, sett
16ae0 69 6e 67 20 74 68 65 20 73 70 69 6c 6c 0a 2a 2a  ing the spill.**
16af0 20 74 68 72 65 73 68 6f 6c 64 20 74 6f 20 61 20   threshold to a 
16b00 76 61 6c 75 65 20 73 75 63 68 20 61 73 20 36 34  value such as 64
16b10 4b 69 42 20 63 61 6e 20 67 72 65 61 74 6c 79 20  KiB can greatly 
16b20 72 65 64 75 63 65 20 74 68 65 20 61 6d 6f 75 6e  reduce the amoun
16b30 74 20 6f 66 0a 2a 2a 20 49 2f 4f 20 72 65 71 75  t of.** I/O requ
16b40 69 72 65 64 20 74 6f 20 73 75 70 70 6f 72 74 20  ired to support 
16b50 73 74 61 74 65 6d 65 6e 74 20 72 6f 6c 6c 62 61  statement rollba
16b60 63 6b 2e 0a 2a 2a 20 54 68 65 20 64 65 66 61 75  ck..** The defau
16b70 6c 74 20 76 61 6c 75 65 20 66 6f 72 20 74 68 69  lt value for thi
16b80 73 20 73 65 74 74 69 6e 67 20 69 73 20 63 6f 6e  s setting is con
16b90 74 72 6f 6c 6c 65 64 20 62 79 20 74 68 65 0a 2a  trolled by the.*
16ba0 2a 20 5b 53 51 4c 49 54 45 5f 53 54 4d 54 4a 52  * [SQLITE_STMTJR
16bb0 4e 4c 5f 53 50 49 4c 4c 5d 20 63 6f 6d 70 69 6c  NL_SPILL] compil
16bc0 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2e 0a 2a  e-time option..*
16bd0 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69  * </dl>.*/.#defi
16be0 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
16bf0 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 20 20 31  _SINGLETHREAD  1
16c00 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66    /* nil */.#def
16c10 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
16c20 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 20 20 20  G_MULTITHREAD   
16c30 32 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65  2  /* nil */.#de
16c40 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
16c50 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 20 20 20  IG_SERIALIZED   
16c60 20 33 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64   3  /* nil */.#d
16c70 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
16c80 46 49 47 5f 4d 41 4c 4c 4f 43 20 20 20 20 20 20  FIG_MALLOC      
16c90 20 20 34 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f    4  /* sqlite3_
16ca0 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a  mem_methods* */.
16cb0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
16cc0 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 20  ONFIG_GETMALLOC 
16cd0 20 20 20 20 35 20 20 2f 2a 20 73 71 6c 69 74 65      5  /* sqlite
16ce0 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a  3_mem_methods* *
16cf0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
16d00 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 20  _CONFIG_SCRATCH 
16d10 20 20 20 20 20 20 36 20 20 2f 2a 20 76 6f 69 64        6  /* void
16d20 2a 2c 20 69 6e 74 20 73 7a 2c 20 69 6e 74 20 4e  *, int sz, int N
16d30 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
16d40 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41  TE_CONFIG_PAGECA
16d50 43 48 45 20 20 20 20 20 37 20 20 2f 2a 20 76 6f  CHE     7  /* vo
16d60 69 64 2a 2c 20 69 6e 74 20 73 7a 2c 20 69 6e 74  id*, int sz, int
16d70 20 4e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51   N */.#define SQ
16d80 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50  LITE_CONFIG_HEAP
16d90 20 20 20 20 20 20 20 20 20 20 38 20 20 2f 2a 20            8  /* 
16da0 76 6f 69 64 2a 2c 20 69 6e 74 20 6e 42 79 74 65  void*, int nByte
16db0 2c 20 69 6e 74 20 6d 69 6e 20 2a 2f 0a 23 64 65  , int min */.#de
16dc0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
16dd0 49 47 5f 4d 45 4d 53 54 41 54 55 53 20 20 20 20  IG_MEMSTATUS    
16de0 20 39 20 20 2f 2a 20 62 6f 6f 6c 65 61 6e 20 2a   9  /* boolean *
16df0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
16e00 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 20 20 20  _CONFIG_MUTEX   
16e10 20 20 20 20 20 31 30 20 20 2f 2a 20 73 71 6c 69       10  /* sqli
16e20 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64  te3_mutex_method
16e30 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  s* */.#define SQ
16e40 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d  LITE_CONFIG_GETM
16e50 55 54 45 58 20 20 20 20 20 31 31 20 20 2f 2a 20  UTEX     11  /* 
16e60 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65  sqlite3_mutex_me
16e70 74 68 6f 64 73 2a 20 2a 2f 0a 2f 2a 20 70 72 65  thods* */./* pre
16e80 76 69 6f 75 73 6c 79 20 53 51 4c 49 54 45 5f 43  viously SQLITE_C
16e90 4f 4e 46 49 47 5f 43 48 55 4e 4b 41 4c 4c 4f 43  ONFIG_CHUNKALLOC
16ea0 20 31 32 20 77 68 69 63 68 20 69 73 20 6e 6f 77   12 which is now
16eb0 20 75 6e 75 73 65 64 2e 20 2a 2f 20 0a 23 64 65   unused. */ .#de
16ec0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
16ed0 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 20 20 20  IG_LOOKASIDE    
16ee0 31 33 20 20 2f 2a 20 69 6e 74 20 69 6e 74 20 2a  13  /* int int *
16ef0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
16f00 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 20 20  _CONFIG_PCACHE  
16f10 20 20 20 20 20 31 34 20 20 2f 2a 20 6e 6f 2d 6f       14  /* no-o
16f20 70 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  p */.#define SQL
16f30 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43  ITE_CONFIG_GETPC
16f40 41 43 48 45 20 20 20 20 31 35 20 20 2f 2a 20 6e  ACHE    15  /* n
16f50 6f 2d 6f 70 20 2a 2f 0a 23 64 65 66 69 6e 65 20  o-op */.#define 
16f60 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f  SQLITE_CONFIG_LO
16f70 47 20 20 20 20 20 20 20 20 20 20 31 36 20 20 2f  G          16  /
16f80 2a 20 78 46 75 6e 63 2c 20 76 6f 69 64 2a 20 2a  * xFunc, void* *
16f90 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
16fa0 5f 43 4f 4e 46 49 47 5f 55 52 49 20 20 20 20 20  _CONFIG_URI     
16fb0 20 20 20 20 20 31 37 20 20 2f 2a 20 69 6e 74 20       17  /* int 
16fc0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
16fd0 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32  E_CONFIG_PCACHE2
16fe0 20 20 20 20 20 20 31 38 20 20 2f 2a 20 73 71 6c        18  /* sql
16ff0 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68  ite3_pcache_meth
17000 6f 64 73 32 2a 20 2a 2f 0a 23 64 65 66 69 6e 65  ods2* */.#define
17010 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47   SQLITE_CONFIG_G
17020 45 54 50 43 41 43 48 45 32 20 20 20 31 39 20 20  ETPCACHE2   19  
17030 2f 2a 20 73 71 6c 69 74 65 33 5f 70 63 61 63 68  /* sqlite3_pcach
17040 65 5f 6d 65 74 68 6f 64 73 32 2a 20 2a 2f 0a 23  e_methods2* */.#
17050 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
17060 4e 46 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49 4e  NFIG_COVERING_IN
17070 44 45 58 5f 53 43 41 4e 20 32 30 20 20 2f 2a 20  DEX_SCAN 20  /* 
17080 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  int */.#define S
17090 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 51 4c  QLITE_CONFIG_SQL
170a0 4c 4f 47 20 20 20 20 20 20 20 32 31 20 20 2f 2a  LOG       21  /*
170b0 20 78 53 71 6c 6c 6f 67 2c 20 76 6f 69 64 2a 20   xSqllog, void* 
170c0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
170d0 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f 53 49  E_CONFIG_MMAP_SI
170e0 5a 45 20 20 20 20 32 32 20 20 2f 2a 20 73 71 6c  ZE    22  /* sql
170f0 69 74 65 33 5f 69 6e 74 36 34 2c 20 73 71 6c 69  ite3_int64, sqli
17100 74 65 33 5f 69 6e 74 36 34 20 2a 2f 0a 23 64 65  te3_int64 */.#de
17110 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
17120 49 47 5f 57 49 4e 33 32 5f 48 45 41 50 53 49 5a  IG_WIN32_HEAPSIZ
17130 45 20 20 20 20 20 20 32 33 20 20 2f 2a 20 69 6e  E      23  /* in
17140 74 20 6e 42 79 74 65 20 2a 2f 0a 23 64 65 66 69  t nByte */.#defi
17150 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
17160 5f 50 43 41 43 48 45 5f 48 44 52 53 5a 20 20 20  _PCACHE_HDRSZ   
17170 20 20 20 20 20 32 34 20 20 2f 2a 20 69 6e 74 20       24  /* int 
17180 2a 70 73 7a 20 2a 2f 0a 23 64 65 66 69 6e 65 20  *psz */.#define 
17190 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 4d  SQLITE_CONFIG_PM
171a0 41 53 5a 20 20 20 20 20 20 20 20 20 20 20 20 20  ASZ             
171b0 20 20 32 35 20 20 2f 2a 20 75 6e 73 69 67 6e 65    25  /* unsigne
171c0 64 20 69 6e 74 20 73 7a 50 6d 61 20 2a 2f 0a 23  d int szPma */.#
171d0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
171e0 4e 46 49 47 5f 53 54 4d 54 4a 52 4e 4c 5f 53 50  NFIG_STMTJRNL_SP
171f0 49 4c 4c 20 20 20 20 20 20 32 36 20 20 2f 2a 20  ILL      26  /* 
17200 69 6e 74 20 6e 42 79 74 65 20 2a 2f 0a 0a 2f 2a  int nByte */../*
17210 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 61  .** CAPI3REF: Da
17220 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f  tabase Connectio
17230 6e 20 43 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  n Configuration 
17240 4f 70 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68  Options.**.** Th
17250 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72  ese constants ar
17260 65 20 74 68 65 20 61 76 61 69 6c 61 62 6c 65 20  e the available 
17270 69 6e 74 65 67 65 72 20 63 6f 6e 66 69 67 75 72  integer configur
17280 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 74 68  ation options th
17290 61 74 0a 2a 2a 20 63 61 6e 20 62 65 20 70 61 73  at.** can be pas
172a0 73 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e  sed as the secon
172b0 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  d argument to th
172c0 65 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f  e [sqlite3_db_co
172d0 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63  nfig()] interfac
172e0 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e  e..**.** New con
172f0 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
17300 6e 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 20  ns may be added 
17310 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73  in future releas
17320 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a  es of SQLite..**
17330 20 45 78 69 73 74 69 6e 67 20 63 6f 6e 66 69 67   Existing config
17340 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20  uration options 
17350 6d 69 67 68 74 20 62 65 20 64 69 73 63 6f 6e 74  might be discont
17360 69 6e 75 65 64 2e 20 20 41 70 70 6c 69 63 61 74  inued.  Applicat
17370 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 63  ions.** should c
17380 68 65 63 6b 20 74 68 65 20 72 65 74 75 72 6e 20  heck the return 
17390 63 6f 64 65 20 66 72 6f 6d 20 5b 73 71 6c 69 74  code from [sqlit
173a0 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20  e3_db_config()] 
173b0 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 74 68 61  to make sure tha
173c0 74 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20 77 6f  t.** the call wo
173d0 72 6b 65 64 2e 20 20 5e 54 68 65 20 5b 73 71 6c  rked.  ^The [sql
173e0 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29  ite3_db_config()
173f0 5d 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c  ] interface will
17400 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e   return a.** non
17410 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64  -zero [error cod
17420 65 5d 20 69 66 20 61 20 64 69 73 63 6f 6e 74 69  e] if a disconti
17430 6e 75 65 64 20 6f 72 20 75 6e 73 75 70 70 6f 72  nued or unsuppor
17440 74 65 64 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ted configuratio
17450 6e 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73 20 69  n option.** is i
17460 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64  nvoked..**.** <d
17470 6c 3e 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  l>.** <dt>SQLITE
17480 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53  _DBCONFIG_LOOKAS
17490 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  IDE</dt>.** <dd>
174a0 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61   ^This option ta
174b0 6b 65 73 20 74 68 72 65 65 20 61 64 64 69 74 69  kes three additi
174c0 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 20 74  onal arguments t
174d0 68 61 74 20 64 65 74 65 72 6d 69 6e 65 20 74 68  hat determine th
174e0 65 20 0a 2a 2a 20 5b 6c 6f 6f 6b 61 73 69 64 65  e .** [lookaside
174f0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f   memory allocato
17500 72 5d 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  r] configuration
17510 20 66 6f 72 20 74 68 65 20 5b 64 61 74 61 62 61   for the [databa
17520 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a  se connection]..
17530 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 72  ** ^The first ar
17540 67 75 6d 65 6e 74 20 28 74 68 65 20 74 68 69 72  gument (the thir
17550 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b  d parameter to [
17560 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69  sqlite3_db_confi
17570 67 28 29 5d 20 69 73 20 61 0a 2a 2a 20 70 6f 69  g()] is a.** poi
17580 6e 74 65 72 20 74 6f 20 61 20 6d 65 6d 6f 72 79  nter to a memory
17590 20 62 75 66 66 65 72 20 74 6f 20 75 73 65 20 66   buffer to use f
175a0 6f 72 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d  or lookaside mem
175b0 6f 72 79 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 72  ory..** ^The fir
175c0 73 74 20 61 72 67 75 6d 65 6e 74 20 61 66 74 65  st argument afte
175d0 72 20 74 68 65 20 53 51 4c 49 54 45 5f 44 42 43  r the SQLITE_DBC
175e0 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20  ONFIG_LOOKASIDE 
175f0 76 65 72 62 0a 2a 2a 20 6d 61 79 20 62 65 20 4e  verb.** may be N
17600 55 4c 4c 20 69 6e 20 77 68 69 63 68 20 63 61 73  ULL in which cas
17610 65 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c  e SQLite will al
17620 6c 6f 63 61 74 65 20 74 68 65 0a 2a 2a 20 6c 6f  locate the.** lo
17630 6f 6b 61 73 69 64 65 20 62 75 66 66 65 72 20 69  okaside buffer i
17640 74 73 65 6c 66 20 75 73 69 6e 67 20 5b 73 71 6c  tself using [sql
17650 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20  ite3_malloc()]. 
17660 5e 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75  ^The second argu
17670 6d 65 6e 74 20 69 73 20 74 68 65 0a 2a 2a 20 73  ment is the.** s
17680 69 7a 65 20 6f 66 20 65 61 63 68 20 6c 6f 6f 6b  ize of each look
17690 61 73 69 64 65 20 62 75 66 66 65 72 20 73 6c 6f  aside buffer slo
176a0 74 2e 20 20 5e 54 68 65 20 74 68 69 72 64 20 61  t.  ^The third a
176b0 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 6e  rgument is the n
176c0 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 73 6c 6f 74  umber of.** slot
176d0 73 2e 20 20 54 68 65 20 73 69 7a 65 20 6f 66 20  s.  The size of 
176e0 74 68 65 20 62 75 66 66 65 72 20 69 6e 20 74 68  the buffer in th
176f0 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
17700 20 6d 75 73 74 20 62 65 20 67 72 65 61 74 65 72   must be greater
17710 20 74 68 61 6e 0a 2a 2a 20 6f 72 20 65 71 75 61   than.** or equa
17720 6c 20 74 6f 20 74 68 65 20 70 72 6f 64 75 63 74  l to the product
17730 20 6f 66 20 74 68 65 20 73 65 63 6f 6e 64 20 61   of the second a
17740 6e 64 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e  nd third argumen
17750 74 73 2e 20 20 54 68 65 20 62 75 66 66 65 72 0a  ts.  The buffer.
17760 2a 2a 20 6d 75 73 74 20 62 65 20 61 6c 69 67 6e  ** must be align
17770 65 64 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 20  ed to an 8-byte 
17780 62 6f 75 6e 64 61 72 79 2e 20 20 5e 49 66 20 74  boundary.  ^If t
17790 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
177a0 6e 74 20 74 6f 0a 2a 2a 20 53 51 4c 49 54 45 5f  nt to.** SQLITE_
177b0 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49  DBCONFIG_LOOKASI
177c0 44 45 20 69 73 20 6e 6f 74 20 61 20 6d 75 6c 74  DE is not a mult
177d0 69 70 6c 65 20 6f 66 20 38 2c 20 69 74 20 69 73  iple of 8, it is
177e0 20 69 6e 74 65 72 6e 61 6c 6c 79 0a 2a 2a 20 72   internally.** r
177f0 6f 75 6e 64 65 64 20 64 6f 77 6e 20 74 6f 20 74  ounded down to t
17800 68 65 20 6e 65 78 74 20 73 6d 61 6c 6c 65 72 20  he next smaller 
17810 6d 75 6c 74 69 70 6c 65 20 6f 66 20 38 2e 20 20  multiple of 8.  
17820 5e 28 54 68 65 20 6c 6f 6f 6b 61 73 69 64 65 20  ^(The lookaside 
17830 6d 65 6d 6f 72 79 0a 2a 2a 20 63 6f 6e 66 69 67  memory.** config
17840 75 72 61 74 69 6f 6e 20 66 6f 72 20 61 20 64 61  uration for a da
17850 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
17860 6e 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 63 68  n can only be ch
17870 61 6e 67 65 64 20 77 68 65 6e 20 74 68 61 74 0a  anged when that.
17880 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  ** connection is
17890 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79 20 75   not currently u
178a0 73 69 6e 67 20 6c 6f 6f 6b 61 73 69 64 65 20 6d  sing lookaside m
178b0 65 6d 6f 72 79 2c 20 6f 72 20 69 6e 20 6f 74 68  emory, or in oth
178c0 65 72 20 77 6f 72 64 73 0a 2a 2a 20 77 68 65 6e  er words.** when
178d0 20 74 68 65 20 22 63 75 72 72 65 6e 74 20 76 61   the "current va
178e0 6c 75 65 22 20 72 65 74 75 72 6e 65 64 20 62 79  lue" returned by
178f0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f  .** [sqlite3_db_
17900 73 74 61 74 75 73 5d 28 44 2c 5b 53 51 4c 49 54  status](D,[SQLIT
17910 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49  E_CONFIG_LOOKASI
17920 44 45 5d 2c 2e 2e 2e 29 20 69 73 20 7a 65 72 6f  DE],...) is zero
17930 2e 0a 2a 2a 20 41 6e 79 20 61 74 74 65 6d 70 74  ..** Any attempt
17940 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65 20 6c   to change the l
17950 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20  ookaside memory 
17960 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 77 68  configuration wh
17970 65 6e 20 6c 6f 6f 6b 61 73 69 64 65 0a 2a 2a 20  en lookaside.** 
17980 6d 65 6d 6f 72 79 20 69 73 20 69 6e 20 75 73 65  memory is in use
17990 20 6c 65 61 76 65 73 20 74 68 65 20 63 6f 6e 66   leaves the conf
179a0 69 67 75 72 61 74 69 6f 6e 20 75 6e 63 68 61 6e  iguration unchan
179b0 67 65 64 20 61 6e 64 20 72 65 74 75 72 6e 73 20  ged and returns 
179c0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  .** [SQLITE_BUSY
179d0 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ].)^</dd>.**.** 
179e0 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e  <dt>SQLITE_DBCON
179f0 46 49 47 5f 45 4e 41 42 4c 45 5f 46 4b 45 59 3c  FIG_ENABLE_FKEY<
17a00 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68  /dt>.** <dd> ^Th
17a10 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65  is option is use
17a20 64 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64  d to enable or d
17a30 69 73 61 62 6c 65 20 74 68 65 20 65 6e 66 6f 72  isable the enfor
17a40 63 65 6d 65 6e 74 20 6f 66 0a 2a 2a 20 5b 66 6f  cement of.** [fo
17a50 72 65 69 67 6e 20 6b 65 79 20 63 6f 6e 73 74 72  reign key constr
17a60 61 69 6e 74 73 5d 2e 20 20 54 68 65 72 65 20 73  aints].  There s
17a70 68 6f 75 6c 64 20 62 65 20 74 77 6f 20 61 64 64  hould be two add
17a80 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74  itional argument
17a90 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20  s..** The first 
17aa0 61 72 67 75 6d 65 6e 74 20 69 73 20 61 6e 20 69  argument is an i
17ab0 6e 74 65 67 65 72 20 77 68 69 63 68 20 69 73 20  nteger which is 
17ac0 30 20 74 6f 20 64 69 73 61 62 6c 65 20 46 4b 20  0 to disable FK 
17ad0 65 6e 66 6f 72 63 65 6d 65 6e 74 2c 0a 2a 2a 20  enforcement,.** 
17ae0 70 6f 73 69 74 69 76 65 20 74 6f 20 65 6e 61 62  positive to enab
17af0 6c 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e  le FK enforcemen
17b00 74 20 6f 72 20 6e 65 67 61 74 69 76 65 20 74 6f  t or negative to
17b10 20 6c 65 61 76 65 20 46 4b 20 65 6e 66 6f 72 63   leave FK enforc
17b20 65 6d 65 6e 74 0a 2a 2a 20 75 6e 63 68 61 6e 67  ement.** unchang
17b30 65 64 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20  ed.  The second 
17b40 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 70  parameter is a p
17b50 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74  ointer to an int
17b60 65 67 65 72 20 69 6e 74 6f 20 77 68 69 63 68 0a  eger into which.
17b70 2a 2a 20 69 73 20 77 72 69 74 74 65 6e 20 30 20  ** is written 0 
17b80 6f 72 20 31 20 74 6f 20 69 6e 64 69 63 61 74 65  or 1 to indicate
17b90 20 77 68 65 74 68 65 72 20 46 4b 20 65 6e 66 6f   whether FK enfo
17ba0 72 63 65 6d 65 6e 74 20 69 73 20 6f 66 66 20 6f  rcement is off o
17bb0 72 20 6f 6e 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e  r on.** followin
17bc0 67 20 74 68 69 73 20 63 61 6c 6c 2e 20 20 54 68  g this call.  Th
17bd0 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
17be0 65 72 20 6d 61 79 20 62 65 20 61 20 4e 55 4c 4c  er may be a NULL
17bf0 20 70 6f 69 6e 74 65 72 2c 20 69 6e 0a 2a 2a 20   pointer, in.** 
17c00 77 68 69 63 68 20 63 61 73 65 20 74 68 65 20 46  which case the F
17c10 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 73 65  K enforcement se
17c20 74 74 69 6e 67 20 69 73 20 6e 6f 74 20 72 65 70  tting is not rep
17c30 6f 72 74 65 64 20 62 61 63 6b 2e 20 3c 2f 64 64  orted back. </dd
17c40 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  >.**.** <dt>SQLI
17c50 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42  TE_DBCONFIG_ENAB
17c60 4c 45 5f 54 52 49 47 47 45 52 3c 2f 64 74 3e 0a  LE_TRIGGER</dt>.
17c70 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70  ** <dd> ^This op
17c80 74 69 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20  tion is used to 
17c90 65 6e 61 62 6c 65 20 6f 72 20 64 69 73 61 62 6c  enable or disabl
17ca0 65 20 5b 43 52 45 41 54 45 20 54 52 49 47 47 45  e [CREATE TRIGGE
17cb0 52 20 7c 20 74 72 69 67 67 65 72 73 5d 2e 0a 2a  R | triggers]..*
17cc0 2a 20 54 68 65 72 65 20 73 68 6f 75 6c 64 20 62  * There should b
17cd0 65 20 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c  e two additional
17ce0 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20 54   arguments..** T
17cf0 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
17d00 74 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20  t is an integer 
17d10 77 68 69 63 68 20 69 73 20 30 20 74 6f 20 64 69  which is 0 to di
17d20 73 61 62 6c 65 20 74 72 69 67 67 65 72 73 2c 0a  sable triggers,.
17d30 2a 2a 20 70 6f 73 69 74 69 76 65 20 74 6f 20 65  ** positive to e
17d40 6e 61 62 6c 65 20 74 72 69 67 67 65 72 73 20 6f  nable triggers o
17d50 72 20 6e 65 67 61 74 69 76 65 20 74 6f 20 6c 65  r negative to le
17d60 61 76 65 20 74 68 65 20 73 65 74 74 69 6e 67 20  ave the setting 
17d70 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 20 54 68  unchanged..** Th
17d80 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
17d90 65 72 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20  er is a pointer 
17da0 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 69 6e  to an integer in
17db0 74 6f 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 77  to which.** is w
17dc0 72 69 74 74 65 6e 20 30 20 6f 72 20 31 20 74 6f  ritten 0 or 1 to
17dd0 20 69 6e 64 69 63 61 74 65 20 77 68 65 74 68 65   indicate whethe
17de0 72 20 74 72 69 67 67 65 72 73 20 61 72 65 20 64  r triggers are d
17df0 69 73 61 62 6c 65 64 20 6f 72 20 65 6e 61 62 6c  isabled or enabl
17e00 65 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20  ed.** following 
17e10 74 68 69 73 20 63 61 6c 6c 2e 20 20 54 68 65 20  this call.  The 
17e20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
17e30 20 6d 61 79 20 62 65 20 61 20 4e 55 4c 4c 20 70   may be a NULL p
17e40 6f 69 6e 74 65 72 2c 20 69 6e 0a 2a 2a 20 77 68  ointer, in.** wh
17e50 69 63 68 20 63 61 73 65 20 74 68 65 20 74 72 69  ich case the tri
17e60 67 67 65 72 20 73 65 74 74 69 6e 67 20 69 73 20  gger setting is 
17e70 6e 6f 74 20 72 65 70 6f 72 74 65 64 20 62 61 63  not reported bac
17e80 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c  k. </dd>.**.** <
17e90 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46  dt>SQLITE_DBCONF
17ea0 49 47 5f 45 4e 41 42 4c 45 5f 46 54 53 33 5f 54  IG_ENABLE_FTS3_T
17eb0 4f 4b 45 4e 49 5a 45 52 3c 2f 64 74 3e 0a 2a 2a  OKENIZER</dt>.**
17ec0 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69   <dd> ^This opti
17ed0 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20 65 6e  on is used to en
17ee0 61 62 6c 65 20 6f 72 20 64 69 73 61 62 6c 65 20  able or disable 
17ef0 74 68 65 20 74 77 6f 2d 61 72 67 75 6d 65 6e 74  the two-argument
17f00 0a 2a 2a 20 76 65 72 73 69 6f 6e 20 6f 66 20 74  .** version of t
17f10 68 65 20 5b 66 74 73 33 5f 74 6f 6b 65 6e 69 7a  he [fts3_tokeniz
17f20 65 72 28 29 5d 20 66 75 6e 63 74 69 6f 6e 20 77  er()] function w
17f30 68 69 63 68 20 69 73 20 70 61 72 74 20 6f 66 20  hich is part of 
17f40 74 68 65 0a 2a 2a 20 5b 46 54 53 33 5d 20 66 75  the.** [FTS3] fu
17f50 6c 6c 2d 74 65 78 74 20 73 65 61 72 63 68 20 65  ll-text search e
17f60 6e 67 69 6e 65 20 65 78 74 65 6e 73 69 6f 6e 2e  ngine extension.
17f70 0a 2a 2a 20 54 68 65 72 65 20 73 68 6f 75 6c 64  .** There should
17f80 20 62 65 20 74 77 6f 20 61 64 64 69 74 69 6f 6e   be two addition
17f90 61 6c 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a  al arguments..**
17fa0 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   The first argum
17fb0 65 6e 74 20 69 73 20 61 6e 20 69 6e 74 65 67 65  ent is an intege
17fc0 72 20 77 68 69 63 68 20 69 73 20 30 20 74 6f 20  r which is 0 to 
17fd0 64 69 73 61 62 6c 65 20 66 74 73 33 5f 74 6f 6b  disable fts3_tok
17fe0 65 6e 69 7a 65 72 28 29 20 6f 72 0a 2a 2a 20 70  enizer() or.** p
17ff0 6f 73 69 74 69 76 65 20 74 6f 20 65 6e 61 62 6c  ositive to enabl
18000 65 20 66 74 73 33 5f 74 6f 6b 65 6e 69 7a 65 72  e fts3_tokenizer
18010 28 29 20 6f 72 20 6e 65 67 61 74 69 76 65 20 74  () or negative t
18020 6f 20 6c 65 61 76 65 20 74 68 65 20 73 65 74 74  o leave the sett
18030 69 6e 67 0a 2a 2a 20 75 6e 63 68 61 6e 67 65 64  ing.** unchanged
18040 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20  ..** The second 
18050 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 70  parameter is a p
18060 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74  ointer to an int
18070 65 67 65 72 20 69 6e 74 6f 20 77 68 69 63 68 0a  eger into which.
18080 2a 2a 20 69 73 20 77 72 69 74 74 65 6e 20 30 20  ** is written 0 
18090 6f 72 20 31 20 74 6f 20 69 6e 64 69 63 61 74 65  or 1 to indicate
180a0 20 77 68 65 74 68 65 72 20 66 74 73 33 5f 74 6f   whether fts3_to
180b0 6b 65 6e 69 7a 65 72 20 69 73 20 64 69 73 61 62  kenizer is disab
180c0 6c 65 64 20 6f 72 20 65 6e 61 62 6c 65 64 0a 2a  led or enabled.*
180d0 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 69 73  * following this
180e0 20 63 61 6c 6c 2e 20 20 54 68 65 20 73 65 63 6f   call.  The seco
180f0 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79  nd parameter may
18100 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   be a NULL point
18110 65 72 2c 20 69 6e 0a 2a 2a 20 77 68 69 63 68 20  er, in.** which 
18120 63 61 73 65 20 74 68 65 20 6e 65 77 20 73 65 74  case the new set
18130 74 69 6e 67 20 69 73 20 6e 6f 74 20 72 65 70 6f  ting is not repo
18140 72 74 65 64 20 62 61 63 6b 2e 20 3c 2f 64 64 3e  rted back. </dd>
18150 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  .**.** <dt>SQLIT
18160 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c  E_DBCONFIG_ENABL
18170 45 5f 4c 4f 41 44 5f 45 58 54 45 4e 53 49 4f 4e  E_LOAD_EXTENSION
18180 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54  </dt>.** <dd> ^T
18190 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 75 73  his option is us
181a0 65 64 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20  ed to enable or 
181b0 64 69 73 61 62 6c 65 20 74 68 65 20 5b 73 71 6c  disable the [sql
181c0 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65 6e 73  ite3_load_extens
181d0 69 6f 6e 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66  ion()].** interf
181e0 61 63 65 20 69 6e 64 65 70 65 6e 64 65 6e 74 6c  ace independentl
181f0 79 20 6f 66 20 74 68 65 20 5b 6c 6f 61 64 5f 65  y of the [load_e
18200 78 74 65 6e 73 69 6f 6e 28 29 5d 20 53 51 4c 20  xtension()] SQL 
18210 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 54 68 65  function..** The
18220 20 5b 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65   [sqlite3_enable
18230 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28  _load_extension(
18240 29 5d 20 41 50 49 20 65 6e 61 62 6c 65 73 20 6f  )] API enables o
18250 72 20 64 69 73 61 62 6c 65 73 20 62 6f 74 68 20  r disables both 
18260 74 68 65 0a 2a 2a 20 43 2d 41 50 49 20 5b 73 71  the.** C-API [sq
18270 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65 6e  lite3_load_exten
18280 73 69 6f 6e 28 29 5d 20 61 6e 64 20 74 68 65 20  sion()] and the 
18290 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 5b 6c 6f  SQL function [lo
182a0 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d 2e  ad_extension()].
182b0 0a 2a 2a 20 54 68 65 72 65 20 73 68 6f 75 6c 64  .** There should
182c0 20 62 65 20 74 77 6f 20 61 64 64 69 74 69 6f 6e   be two addition
182d0 61 6c 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a  al arguments..**
182e0 20 57 68 65 6e 20 74 68 65 20 66 69 72 73 74 20   When the first 
182f0 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 69 73  argument to this
18300 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 31 2c   interface is 1,
18310 20 74 68 65 6e 20 6f 6e 6c 79 20 74 68 65 20 43   then only the C
18320 2d 41 50 49 20 69 73 0a 2a 2a 20 65 6e 61 62 6c  -API is.** enabl
18330 65 64 20 61 6e 64 20 74 68 65 20 53 51 4c 20 66  ed and the SQL f
18340 75 6e 63 74 69 6f 6e 20 72 65 6d 61 69 6e 73 20  unction remains 
18350 64 69 73 61 62 6c 65 64 2e 20 20 49 66 20 74 68  disabled.  If th
18360 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
18370 20 74 6f 0a 2a 2a 20 74 68 69 73 20 69 6e 74 65   to.** this inte
18380 72 66 61 63 65 20 69 73 20 30 2c 20 74 68 65 6e  rface is 0, then
18390 20 62 6f 74 68 20 74 68 65 20 43 2d 41 50 49 20   both the C-API 
183a0 61 6e 64 20 74 68 65 20 53 51 4c 20 66 75 6e 63  and the SQL func
183b0 74 69 6f 6e 20 61 72 65 20 64 69 73 61 62 6c 65  tion are disable
183c0 64 2e 0a 2a 2a 20 49 66 20 74 68 65 20 66 69 72  d..** If the fir
183d0 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20 2d  st argument is -
183e0 31 2c 20 74 68 65 6e 20 6e 6f 20 63 68 61 6e 67  1, then no chang
183f0 65 73 20 61 72 65 20 6d 61 64 65 20 74 6f 20 73  es are made to s
18400 74 61 74 65 20 6f 66 20 65 69 74 68 65 72 20 74  tate of either t
18410 68 65 0a 2a 2a 20 43 2d 41 50 49 20 6f 72 20 74  he.** C-API or t
18420 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 2e  he SQL function.
18430 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 70  .** The second p
18440 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 70 6f  arameter is a po
18450 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65  inter to an inte
18460 67 65 72 20 69 6e 74 6f 20 77 68 69 63 68 0a 2a  ger into which.*
18470 2a 20 69 73 20 77 72 69 74 74 65 6e 20 30 20 6f  * is written 0 o
18480 72 20 31 20 74 6f 20 69 6e 64 69 63 61 74 65 20  r 1 to indicate 
18490 77 68 65 74 68 65 72 20 5b 73 71 6c 69 74 65 33  whether [sqlite3
184a0 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28  _load_extension(
184b0 29 5d 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20  )] interface.** 
184c0 69 73 20 64 69 73 61 62 6c 65 64 20 6f 72 20 65  is disabled or e
184d0 6e 61 62 6c 65 64 20 66 6f 6c 6c 6f 77 69 6e 67  nabled following
184e0 20 74 68 69 73 20 63 61 6c 6c 2e 20 20 54 68 65   this call.  The
184f0 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
18500 72 20 6d 61 79 0a 2a 2a 20 62 65 20 61 20 4e 55  r may.** be a NU
18510 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69 6e 20 77  LL pointer, in w
18520 68 69 63 68 20 63 61 73 65 20 74 68 65 20 6e 65  hich case the ne
18530 77 20 73 65 74 74 69 6e 67 20 69 73 20 6e 6f 74  w setting is not
18540 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b 2e 0a   reported back..
18550 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c  ** </dd>.**.** <
18560 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46  dt>SQLITE_DBCONF
18570 49 47 5f 4d 41 49 4e 44 42 4e 41 4d 45 3c 2f 64  IG_MAINDBNAME</d
18580 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73  t>.** <dd> ^This
18590 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64 20   option is used 
185a0 74 6f 20 63 68 61 6e 67 65 20 74 68 65 20 6e 61  to change the na
185b0 6d 65 20 6f 66 20 74 68 65 20 22 6d 61 69 6e 22  me of the "main"
185c0 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 73 63 68   database.** sch
185d0 65 6d 61 2e 20 20 5e 54 68 65 20 73 6f 6c 65 20  ema.  ^The sole 
185e0 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f  argument is a po
185f0 69 6e 74 65 72 20 74 6f 20 61 20 63 6f 6e 73 74  inter to a const
18600 61 6e 74 20 55 54 46 38 20 73 74 72 69 6e 67 0a  ant UTF8 string.
18610 2a 2a 20 77 68 69 63 68 20 77 69 6c 6c 20 62 65  ** which will be
18620 63 6f 6d 65 20 74 68 65 20 6e 65 77 20 73 63 68  come the new sch
18630 65 6d 61 20 6e 61 6d 65 20 69 6e 20 70 6c 61 63  ema name in plac
18640 65 20 6f 66 20 22 6d 61 69 6e 22 2e 20 20 5e 53  e of "main".  ^S
18650 51 4c 69 74 65 0a 2a 2a 20 64 6f 65 73 20 6e 6f  QLite.** does no
18660 74 20 6d 61 6b 65 20 61 20 63 6f 70 79 20 6f 66  t make a copy of
18670 20 74 68 65 20 6e 65 77 20 6d 61 69 6e 20 73 63   the new main sc
18680 68 65 6d 61 20 6e 61 6d 65 20 73 74 72 69 6e 67  hema name string
18690 2c 20 73 6f 20 74 68 65 20 61 70 70 6c 69 63 61  , so the applica
186a0 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 65 6e 73  tion.** must ens
186b0 75 72 65 20 74 68 61 74 20 74 68 65 20 61 72 67  ure that the arg
186c0 75 6d 65 6e 74 20 70 61 73 73 65 64 20 69 6e 74  ument passed int
186d0 6f 20 74 68 69 73 20 44 42 43 4f 4e 46 49 47 20  o this DBCONFIG 
186e0 6f 70 74 69 6f 6e 20 69 73 20 75 6e 63 68 61 6e  option is unchan
186f0 67 65 64 0a 2a 2a 20 75 6e 74 69 6c 20 61 66 74  ged.** until aft
18700 65 72 20 74 68 65 20 64 61 74 61 62 61 73 65 20  er the database 
18710 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f 73 65  connection close
18720 73 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a  s..** </dd>.**.*
18730 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69  * </dl>.*/.#defi
18740 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46  ne SQLITE_DBCONF
18750 49 47 5f 4d 41 49 4e 44 42 4e 41 4d 45 20 20 20  IG_MAINDBNAME   
18760 20 20 20 20 20 20 20 20 20 31 30 30 30 20 2f 2a           1000 /*
18770 20 63 6f 6e 73 74 20 63 68 61 72 2a 20 2a 2f 0a   const char* */.
18780 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
18790 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44  BCONFIG_LOOKASID
187a0 45 20 20 20 20 20 20 20 20 20 20 20 20 20 31 30  E             10
187b0 30 31 20 2f 2a 20 76 6f 69 64 2a 20 69 6e 74 20  01 /* void* int 
187c0 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  int */.#define S
187d0 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45  QLITE_DBCONFIG_E
187e0 4e 41 42 4c 45 5f 46 4b 45 59 20 20 20 20 20 20  NABLE_FKEY      
187f0 20 20 20 20 20 31 30 30 32 20 2f 2a 20 69 6e 74       1002 /* int
18800 20 69 6e 74 2a 20 2a 2f 0a 23 64 65 66 69 6e 65   int* */.#define
18810 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47   SQLITE_DBCONFIG
18820 5f 45 4e 41 42 4c 45 5f 54 52 49 47 47 45 52 20  _ENABLE_TRIGGER 
18830 20 20 20 20 20 20 20 31 30 30 33 20 2f 2a 20 69         1003 /* i
18840 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23 64 65 66 69  nt int* */.#defi
18850 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46  ne SQLITE_DBCONF
18860 49 47 5f 45 4e 41 42 4c 45 5f 46 54 53 33 5f 54  IG_ENABLE_FTS3_T
18870 4f 4b 45 4e 49 5a 45 52 20 31 30 30 34 20 2f 2a  OKENIZER 1004 /*
18880 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23 64 65   int int* */.#de
18890 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f  fine SQLITE_DBCO
188a0 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 4c 4f 41 44  NFIG_ENABLE_LOAD
188b0 5f 45 58 54 45 4e 53 49 4f 4e 20 31 30 30 35 20  _EXTENSION 1005 
188c0 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 0a  /* int int* */..
188d0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
188e0 20 45 6e 61 62 6c 65 20 4f 72 20 44 69 73 61 62   Enable Or Disab
188f0 6c 65 20 45 78 74 65 6e 64 65 64 20 52 65 73 75  le Extended Resu
18900 6c 74 20 43 6f 64 65 73 0a 2a 2a 20 4d 45 54 48  lt Codes.** METH
18910 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a  OD: sqlite3.**.*
18920 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65  * ^The sqlite3_e
18930 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63  xtended_result_c
18940 6f 64 65 73 28 29 20 72 6f 75 74 69 6e 65 20 65  odes() routine e
18950 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62 6c  nables or disabl
18960 65 73 20 74 68 65 0a 2a 2a 20 5b 65 78 74 65 6e  es the.** [exten
18970 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73  ded result codes
18980 5d 20 66 65 61 74 75 72 65 20 6f 66 20 53 51 4c  ] feature of SQL
18990 69 74 65 2e 20 5e 54 68 65 20 65 78 74 65 6e 64  ite. ^The extend
189a0 65 64 20 72 65 73 75 6c 74 0a 2a 2a 20 63 6f 64  ed result.** cod
189b0 65 73 20 61 72 65 20 64 69 73 61 62 6c 65 64 20  es are disabled 
189c0 62 79 20 64 65 66 61 75 6c 74 20 66 6f 72 20 68  by default for h
189d0 69 73 74 6f 72 69 63 61 6c 20 63 6f 6d 70 61 74  istorical compat
189e0 69 62 69 6c 69 74 79 2e 0a 2a 2f 0a 53 51 4c 49  ibility..*/.SQLI
189f0 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
18a00 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75  e3_extended_resu
18a10 6c 74 5f 63 6f 64 65 73 28 73 71 6c 69 74 65 33  lt_codes(sqlite3
18a20 2a 2c 20 69 6e 74 20 6f 6e 6f 66 66 29 3b 0a 0a  *, int onoff);..
18a30 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
18a40 4c 61 73 74 20 49 6e 73 65 72 74 20 52 6f 77 69  Last Insert Rowi
18a50 64 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  d.** METHOD: sql
18a60 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 45 61 63 68  ite3.**.** ^Each
18a70 20 65 6e 74 72 79 20 69 6e 20 6d 6f 73 74 20 53   entry in most S
18a80 51 4c 69 74 65 20 74 61 62 6c 65 73 20 28 65 78  QLite tables (ex
18a90 63 65 70 74 20 66 6f 72 20 5b 57 49 54 48 4f 55  cept for [WITHOU
18aa0 54 20 52 4f 57 49 44 5d 20 74 61 62 6c 65 73 29  T ROWID] tables)
18ab0 0a 2a 2a 20 68 61 73 20 61 20 75 6e 69 71 75 65  .** has a unique
18ac0 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 0a 2a   64-bit signed.*
18ad0 2a 20 69 6e 74 65 67 65 72 20 6b 65 79 20 63 61  * integer key ca
18ae0 6c 6c 65 64 20 74 68 65 20 5b 52 4f 57 49 44 20  lled the [ROWID 
18af0 7c 20 22 72 6f 77 69 64 22 5d 2e 20 5e 54 68 65  | "rowid"]. ^The
18b00 20 72 6f 77 69 64 20 69 73 20 61 6c 77 61 79 73   rowid is always
18b10 20 61 76 61 69 6c 61 62 6c 65 0a 2a 2a 20 61 73   available.** as
18b20 20 61 6e 20 75 6e 64 65 63 6c 61 72 65 64 20 63   an undeclared c
18b30 6f 6c 75 6d 6e 20 6e 61 6d 65 64 20 52 4f 57 49  olumn named ROWI
18b40 44 2c 20 4f 49 44 2c 20 6f 72 20 5f 52 4f 57 49  D, OID, or _ROWI
18b50 44 5f 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68  D_ as long as th
18b60 6f 73 65 0a 2a 2a 20 6e 61 6d 65 73 20 61 72 65  ose.** names are
18b70 20 6e 6f 74 20 61 6c 73 6f 20 75 73 65 64 20 62   not also used b
18b80 79 20 65 78 70 6c 69 63 69 74 6c 79 20 64 65 63  y explicitly dec
18b90 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 73 2e 20 5e  lared columns. ^
18ba0 49 66 0a 2a 2a 20 74 68 65 20 74 61 62 6c 65 20  If.** the table 
18bb0 68 61 73 20 61 20 63 6f 6c 75 6d 6e 20 6f 66 20  has a column of 
18bc0 74 79 70 65 20 5b 49 4e 54 45 47 45 52 20 50 52  type [INTEGER PR
18bd0 49 4d 41 52 59 20 4b 45 59 5d 20 74 68 65 6e 20  IMARY KEY] then 
18be0 74 68 61 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69  that column.** i
18bf0 73 20 61 6e 6f 74 68 65 72 20 61 6c 69 61 73 20  s another alias 
18c00 66 6f 72 20 74 68 65 20 72 6f 77 69 64 2e 0a 2a  for the rowid..*
18c10 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
18c20 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f  3_last_insert_ro
18c30 77 69 64 28 44 29 20 69 6e 74 65 72 66 61 63 65  wid(D) interface
18c40 20 72 65 74 75 72 6e 73 20 74 68 65 20 5b 72 6f   returns the [ro
18c50 77 69 64 5d 20 6f 66 20 74 68 65 20 0a 2a 2a 20  wid] of the .** 
18c60 6d 6f 73 74 20 72 65 63 65 6e 74 20 73 75 63 63  most recent succ
18c70 65 73 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d 20  essful [INSERT] 
18c80 69 6e 74 6f 20 61 20 72 6f 77 69 64 20 74 61 62  into a rowid tab
18c90 6c 65 20 6f 72 20 5b 76 69 72 74 75 61 6c 20 74  le or [virtual t
18ca0 61 62 6c 65 5d 0a 2a 2a 20 6f 6e 20 64 61 74 61  able].** on data
18cb0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
18cc0 44 2e 0a 2a 2a 20 5e 49 6e 73 65 72 74 73 20 69  D..** ^Inserts i
18cd0 6e 74 6f 20 5b 57 49 54 48 4f 55 54 20 52 4f 57  nto [WITHOUT ROW
18ce0 49 44 5d 20 74 61 62 6c 65 73 20 61 72 65 20 6e  ID] tables are n
18cf0 6f 74 20 72 65 63 6f 72 64 65 64 2e 0a 2a 2a 20  ot recorded..** 
18d00 5e 49 66 20 6e 6f 20 73 75 63 63 65 73 73 66 75  ^If no successfu
18d10 6c 20 5b 49 4e 53 45 52 54 5d 73 20 69 6e 74 6f  l [INSERT]s into
18d20 20 72 6f 77 69 64 20 74 61 62 6c 65 73 0a 2a 2a   rowid tables.**
18d30 20 68 61 76 65 20 65 76 65 72 20 6f 63 63 75 72   have ever occur
18d40 72 65 64 20 6f 6e 20 74 68 65 20 64 61 74 61 62  red on the datab
18d50 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44  ase connection D
18d60 2c 20 0a 2a 2a 20 74 68 65 6e 20 73 71 6c 69 74  , .** then sqlit
18d70 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72  e3_last_insert_r
18d80 6f 77 69 64 28 44 29 20 72 65 74 75 72 6e 73 20  owid(D) returns 
18d90 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66  zero..**.** ^(If
18da0 20 61 6e 20 5b 49 4e 53 45 52 54 5d 20 6f 63 63   an [INSERT] occ
18db0 75 72 73 20 77 69 74 68 69 6e 20 61 20 74 72 69  urs within a tri
18dc0 67 67 65 72 20 6f 72 20 77 69 74 68 69 6e 20 61  gger or within a
18dd0 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 5d   [virtual table]
18de0 0a 2a 2a 20 6d 65 74 68 6f 64 2c 20 74 68 65 6e  .** method, then
18df0 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69   this routine wi
18e00 6c 6c 20 72 65 74 75 72 6e 20 74 68 65 20 5b 72  ll return the [r
18e10 6f 77 69 64 5d 20 6f 66 20 74 68 65 20 69 6e 73  owid] of the ins
18e20 65 72 74 65 64 0a 2a 2a 20 72 6f 77 20 61 73 20  erted.** row as 
18e30 6c 6f 6e 67 20 61 73 20 74 68 65 20 74 72 69 67  long as the trig
18e40 67 65 72 20 6f 72 20 76 69 72 74 75 61 6c 20 74  ger or virtual t
18e50 61 62 6c 65 20 6d 65 74 68 6f 64 20 69 73 20 72  able method is r
18e60 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 42 75 74 20 6f  unning..** But o
18e70 6e 63 65 20 74 68 65 20 74 72 69 67 67 65 72 20  nce the trigger 
18e80 6f 72 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65  or virtual table
18e90 20 6d 65 74 68 6f 64 20 65 6e 64 73 2c 20 74 68   method ends, th
18ea0 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  e value returned
18eb0 20 0a 2a 2a 20 62 79 20 74 68 69 73 20 72 6f 75   .** by this rou
18ec0 74 69 6e 65 20 72 65 76 65 72 74 73 20 74 6f 20  tine reverts to 
18ed0 77 68 61 74 20 69 74 20 77 61 73 20 62 65 66 6f  what it was befo
18ee0 72 65 20 74 68 65 20 74 72 69 67 67 65 72 20 6f  re the trigger o
18ef0 72 20 76 69 72 74 75 61 6c 0a 2a 2a 20 74 61 62  r virtual.** tab
18f00 6c 65 20 6d 65 74 68 6f 64 20 62 65 67 61 6e 2e  le method began.
18f10 29 5e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 5b 49 4e  )^.**.** ^An [IN
18f20 53 45 52 54 5d 20 74 68 61 74 20 66 61 69 6c 73  SERT] that fails
18f30 20 64 75 65 20 74 6f 20 61 20 63 6f 6e 73 74 72   due to a constr
18f40 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 20 69  aint violation i
18f50 73 20 6e 6f 74 20 61 0a 2a 2a 20 73 75 63 63 65  s not a.** succe
18f60 73 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d 20 61  ssful [INSERT] a
18f70 6e 64 20 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e  nd does not chan
18f80 67 65 20 74 68 65 20 76 61 6c 75 65 20 72 65 74  ge the value ret
18f90 75 72 6e 65 64 20 62 79 20 74 68 69 73 0a 2a 2a  urned by this.**
18fa0 20 72 6f 75 74 69 6e 65 2e 20 20 5e 54 68 75 73   routine.  ^Thus
18fb0 20 49 4e 53 45 52 54 20 4f 52 20 46 41 49 4c 2c   INSERT OR FAIL,
18fc0 20 49 4e 53 45 52 54 20 4f 52 20 49 47 4e 4f 52   INSERT OR IGNOR
18fd0 45 2c 20 49 4e 53 45 52 54 20 4f 52 20 52 4f 4c  E, INSERT OR ROL
18fe0 4c 42 41 43 4b 2c 0a 2a 2a 20 61 6e 64 20 49 4e  LBACK,.** and IN
18ff0 53 45 52 54 20 4f 52 20 41 42 4f 52 54 20 6d 61  SERT OR ABORT ma
19000 6b 65 20 6e 6f 20 63 68 61 6e 67 65 73 20 74 6f  ke no changes to
19010 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   the return valu
19020 65 20 6f 66 20 74 68 69 73 0a 2a 2a 20 72 6f 75  e of this.** rou
19030 74 69 6e 65 20 77 68 65 6e 20 74 68 65 69 72 20  tine when their 
19040 69 6e 73 65 72 74 69 6f 6e 20 66 61 69 6c 73 2e  insertion fails.
19050 20 20 5e 28 57 68 65 6e 20 49 4e 53 45 52 54 20    ^(When INSERT 
19060 4f 52 20 52 45 50 4c 41 43 45 0a 2a 2a 20 65 6e  OR REPLACE.** en
19070 63 6f 75 6e 74 65 72 73 20 61 20 63 6f 6e 73 74  counters a const
19080 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 2c  raint violation,
19090 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 66 61 69   it does not fai
190a0 6c 2e 20 20 54 68 65 0a 2a 2a 20 49 4e 53 45 52  l.  The.** INSER
190b0 54 20 63 6f 6e 74 69 6e 75 65 73 20 74 6f 20 63  T continues to c
190c0 6f 6d 70 6c 65 74 69 6f 6e 20 61 66 74 65 72 20  ompletion after 
190d0 64 65 6c 65 74 69 6e 67 20 72 6f 77 73 20 74 68  deleting rows th
190e0 61 74 20 63 61 75 73 65 64 0a 2a 2a 20 74 68 65  at caused.** the
190f0 20 63 6f 6e 73 74 72 61 69 6e 74 20 70 72 6f 62   constraint prob
19100 6c 65 6d 20 73 6f 20 49 4e 53 45 52 54 20 4f 52  lem so INSERT OR
19110 20 52 45 50 4c 41 43 45 20 77 69 6c 6c 20 61 6c   REPLACE will al
19120 77 61 79 73 20 63 68 61 6e 67 65 0a 2a 2a 20 74  ways change.** t
19130 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20  he return value 
19140 6f 66 20 74 68 69 73 20 69 6e 74 65 72 66 61 63  of this interfac
19150 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 46 6f 72 20  e.)^.**.** ^For 
19160 74 68 65 20 70 75 72 70 6f 73 65 73 20 6f 66 20  the purposes of 
19170 74 68 69 73 20 72 6f 75 74 69 6e 65 2c 20 61 6e  this routine, an
19180 20 5b 49 4e 53 45 52 54 5d 20 69 73 20 63 6f 6e   [INSERT] is con
19190 73 69 64 65 72 65 64 20 74 6f 0a 2a 2a 20 62 65  sidered to.** be
191a0 20 73 75 63 63 65 73 73 66 75 6c 20 65 76 65 6e   successful even
191b0 20 69 66 20 69 74 20 69 73 20 73 75 62 73 65 71   if it is subseq
191c0 75 65 6e 74 6c 79 20 72 6f 6c 6c 65 64 20 62 61  uently rolled ba
191d0 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66  ck..**.** This f
191e0 75 6e 63 74 69 6f 6e 20 69 73 20 61 63 63 65 73  unction is acces
191f0 73 69 62 6c 65 20 74 6f 20 53 51 4c 20 73 74 61  sible to SQL sta
19200 74 65 6d 65 6e 74 73 20 76 69 61 20 74 68 65 0a  tements via the.
19210 2a 2a 20 5b 6c 61 73 74 5f 69 6e 73 65 72 74 5f  ** [last_insert_
19220 72 6f 77 69 64 28 29 20 53 51 4c 20 66 75 6e 63  rowid() SQL func
19230 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  tion]..**.** If 
19240 61 20 73 65 70 61 72 61 74 65 20 74 68 72 65 61  a separate threa
19250 64 20 70 65 72 66 6f 72 6d 73 20 61 20 6e 65 77  d performs a new
19260 20 5b 49 4e 53 45 52 54 5d 20 6f 6e 20 74 68 65   [INSERT] on the
19270 20 73 61 6d 65 0a 2a 2a 20 64 61 74 61 62 61 73   same.** databas
19280 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 77 68 69  e connection whi
19290 6c 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  le the [sqlite3_
192a0 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69  last_insert_rowi
192b0 64 28 29 5d 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  d()].** function
192c0 20 69 73 20 72 75 6e 6e 69 6e 67 20 61 6e 64 20   is running and 
192d0 74 68 75 73 20 63 68 61 6e 67 65 73 20 74 68 65  thus changes the
192e0 20 6c 61 73 74 20 69 6e 73 65 72 74 20 5b 72 6f   last insert [ro
192f0 77 69 64 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74 68  wid],.** then th
19300 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  e value returned
19310 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73   by [sqlite3_las
19320 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29  t_insert_rowid()
19330 5d 20 69 73 0a 2a 2a 20 75 6e 70 72 65 64 69 63  ] is.** unpredic
19340 74 61 62 6c 65 20 61 6e 64 20 6d 69 67 68 74 20  table and might 
19350 6e 6f 74 20 65 71 75 61 6c 20 65 69 74 68 65 72  not equal either
19360 20 74 68 65 20 6f 6c 64 20 6f 72 20 74 68 65 20   the old or the 
19370 6e 65 77 0a 2a 2a 20 6c 61 73 74 20 69 6e 73 65  new.** last inse
19380 72 74 20 5b 72 6f 77 69 64 5d 2e 0a 2a 2f 0a 53  rt [rowid]..*/.S
19390 51 4c 49 54 45 5f 41 50 49 20 73 71 6c 69 74 65  QLITE_API sqlite
193a0 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f  3_int64 sqlite3_
193b0 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69  last_insert_rowi
193c0 64 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a  d(sqlite3*);../*
193d0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
193e0 75 6e 74 20 54 68 65 20 4e 75 6d 62 65 72 20 4f  unt The Number O
193f0 66 20 52 6f 77 73 20 4d 6f 64 69 66 69 65 64 0a  f Rows Modified.
19400 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
19410 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66  e3.**.** ^This f
19420 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20  unction returns 
19430 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f  the number of ro
19440 77 73 20 6d 6f 64 69 66 69 65 64 2c 20 69 6e 73  ws modified, ins
19450 65 72 74 65 64 20 6f 72 0a 2a 2a 20 64 65 6c 65  erted or.** dele
19460 74 65 64 20 62 79 20 74 68 65 20 6d 6f 73 74 20  ted by the most 
19470 72 65 63 65 6e 74 6c 79 20 63 6f 6d 70 6c 65 74  recently complet
19480 65 64 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54  ed INSERT, UPDAT
19490 45 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20 73  E or DELETE.** s
194a0 74 61 74 65 6d 65 6e 74 20 6f 6e 20 74 68 65 20  tatement on the 
194b0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
194c0 69 6f 6e 20 73 70 65 63 69 66 69 65 64 20 62 79  ion specified by
194d0 20 74 68 65 20 6f 6e 6c 79 20 70 61 72 61 6d 65   the only parame
194e0 74 65 72 2e 0a 2a 2a 20 5e 45 78 65 63 75 74 69  ter..** ^Executi
194f0 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 74 79 70  ng any other typ
19500 65 20 6f 66 20 53 51 4c 20 73 74 61 74 65 6d 65  e of SQL stateme
19510 6e 74 20 64 6f 65 73 20 6e 6f 74 20 6d 6f 64 69  nt does not modi
19520 66 79 20 74 68 65 20 76 61 6c 75 65 0a 2a 2a 20  fy the value.** 
19530 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 69 73  returned by this
19540 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a   function..**.**
19550 20 5e 4f 6e 6c 79 20 63 68 61 6e 67 65 73 20 6d   ^Only changes m
19560 61 64 65 20 64 69 72 65 63 74 6c 79 20 62 79 20  ade directly by 
19570 74 68 65 20 49 4e 53 45 52 54 2c 20 55 50 44 41  the INSERT, UPDA
19580 54 45 20 6f 72 20 44 45 4c 45 54 45 20 73 74 61  TE or DELETE sta
19590 74 65 6d 65 6e 74 20 61 72 65 0a 2a 2a 20 63 6f  tement are.** co
195a0 6e 73 69 64 65 72 65 64 20 2d 20 61 75 78 69 6c  nsidered - auxil
195b0 69 61 72 79 20 63 68 61 6e 67 65 73 20 63 61 75  iary changes cau
195c0 73 65 64 20 62 79 20 5b 43 52 45 41 54 45 20 54  sed by [CREATE T
195d0 52 49 47 47 45 52 20 7c 20 74 72 69 67 67 65 72  RIGGER | trigger
195e0 73 5d 2c 20 0a 2a 2a 20 5b 66 6f 72 65 69 67 6e  s], .** [foreign
195f0 20 6b 65 79 20 61 63 74 69 6f 6e 73 5d 20 6f 72   key actions] or
19600 20 5b 52 45 50 4c 41 43 45 5d 20 63 6f 6e 73 74   [REPLACE] const
19610 72 61 69 6e 74 20 72 65 73 6f 6c 75 74 69 6f 6e  raint resolution
19620 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65 64   are not counted
19630 2e 0a 2a 2a 20 0a 2a 2a 20 43 68 61 6e 67 65 73  ..** .** Changes
19640 20 74 6f 20 61 20 76 69 65 77 20 74 68 61 74 20   to a view that 
19650 61 72 65 20 69 6e 74 65 72 63 65 70 74 65 64 20  are intercepted 
19660 62 79 20 0a 2a 2a 20 5b 49 4e 53 54 45 41 44 20  by .** [INSTEAD 
19670 4f 46 20 74 72 69 67 67 65 72 20 7c 20 49 4e 53  OF trigger | INS
19680 54 45 41 44 20 4f 46 20 74 72 69 67 67 65 72 73  TEAD OF triggers
19690 5d 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65  ] are not counte
196a0 64 2e 20 5e 54 68 65 20 76 61 6c 75 65 20 0a 2a  d. ^The value .*
196b0 2a 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71  * returned by sq
196c0 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20  lite3_changes() 
196d0 69 6d 6d 65 64 69 61 74 65 6c 79 20 61 66 74 65  immediately afte
196e0 72 20 61 6e 20 49 4e 53 45 52 54 2c 20 55 50 44  r an INSERT, UPD
196f0 41 54 45 20 6f 72 20 0a 2a 2a 20 44 45 4c 45 54  ATE or .** DELET
19700 45 20 73 74 61 74 65 6d 65 6e 74 20 72 75 6e 20  E statement run 
19710 6f 6e 20 61 20 76 69 65 77 20 69 73 20 61 6c 77  on a view is alw
19720 61 79 73 20 7a 65 72 6f 2e 20 4f 6e 6c 79 20 63  ays zero. Only c
19730 68 61 6e 67 65 73 20 6d 61 64 65 20 74 6f 20 72  hanges made to r
19740 65 61 6c 20 0a 2a 2a 20 74 61 62 6c 65 73 20 61  eal .** tables a
19750 72 65 20 63 6f 75 6e 74 65 64 2e 0a 2a 2a 0a 2a  re counted..**.*
19760 2a 20 54 68 69 6e 67 73 20 61 72 65 20 6d 6f 72  * Things are mor
19770 65 20 63 6f 6d 70 6c 69 63 61 74 65 64 20 69 66  e complicated if
19780 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 68 61   the sqlite3_cha
19790 6e 67 65 73 28 29 20 66 75 6e 63 74 69 6f 6e 20  nges() function 
197a0 69 73 0a 2a 2a 20 65 78 65 63 75 74 65 64 20 77  is.** executed w
197b0 68 69 6c 65 20 61 20 74 72 69 67 67 65 72 20 70  hile a trigger p
197c0 72 6f 67 72 61 6d 20 69 73 20 72 75 6e 6e 69 6e  rogram is runnin
197d0 67 2e 20 54 68 69 73 20 6d 61 79 20 68 61 70 70  g. This may happ
197e0 65 6e 20 69 66 20 74 68 65 0a 2a 2a 20 70 72 6f  en if the.** pro
197f0 67 72 61 6d 20 75 73 65 73 20 74 68 65 20 5b 63  gram uses the [c
19800 68 61 6e 67 65 73 28 29 20 53 51 4c 20 66 75 6e  hanges() SQL fun
19810 63 74 69 6f 6e 5d 2c 20 6f 72 20 69 66 20 73 6f  ction], or if so
19820 6d 65 20 6f 74 68 65 72 20 63 61 6c 6c 62 61 63  me other callbac
19830 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69 6e  k.** function in
19840 76 6f 6b 65 73 20 73 71 6c 69 74 65 33 5f 63 68  vokes sqlite3_ch
19850 61 6e 67 65 73 28 29 20 64 69 72 65 63 74 6c 79  anges() directly
19860 2e 20 45 73 73 65 6e 74 69 61 6c 6c 79 3a 0a 2a  . Essentially:.*
19870 2a 20 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 20  * .** <ul>.**   
19880 3c 6c 69 3e 20 5e 28 42 65 66 6f 72 65 20 65 6e  <li> ^(Before en
19890 74 65 72 69 6e 67 20 61 20 74 72 69 67 67 65 72  tering a trigger
198a0 20 70 72 6f 67 72 61 6d 20 74 68 65 20 76 61 6c   program the val
198b0 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a  ue returned by.*
198c0 2a 20 20 20 20 20 20 20 20 73 71 6c 69 74 65 33  *        sqlite3
198d0 5f 63 68 61 6e 67 65 73 28 29 20 66 75 6e 63 74  _changes() funct
198e0 69 6f 6e 20 69 73 20 73 61 76 65 64 2e 20 41 66  ion is saved. Af
198f0 74 65 72 20 74 68 65 20 74 72 69 67 67 65 72 20  ter the trigger 
19900 70 72 6f 67 72 61 6d 20 0a 2a 2a 20 20 20 20 20  program .**     
19910 20 20 20 68 61 73 20 66 69 6e 69 73 68 65 64 2c     has finished,
19920 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 76 61   the original va
19930 6c 75 65 20 69 73 20 72 65 73 74 6f 72 65 64 2e  lue is restored.
19940 29 5e 0a 2a 2a 20 0a 2a 2a 20 20 20 3c 6c 69 3e  )^.** .**   <li>
19950 20 5e 28 57 69 74 68 69 6e 20 61 20 74 72 69 67   ^(Within a trig
19960 67 65 72 20 70 72 6f 67 72 61 6d 20 65 61 63 68  ger program each
19970 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 20   INSERT, UPDATE 
19980 61 6e 64 20 44 45 4c 45 54 45 20 0a 2a 2a 20 20  and DELETE .**  
19990 20 20 20 20 20 20 73 74 61 74 65 6d 65 6e 74 20        statement 
199a0 73 65 74 73 20 74 68 65 20 76 61 6c 75 65 20 72  sets the value r
199b0 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74  eturned by sqlit
199c0 65 33 5f 63 68 61 6e 67 65 73 28 29 20 0a 2a 2a  e3_changes() .**
199d0 20 20 20 20 20 20 20 20 75 70 6f 6e 20 63 6f 6d          upon com
199e0 70 6c 65 74 69 6f 6e 20 61 73 20 6e 6f 72 6d 61  pletion as norma
199f0 6c 2e 20 4f 66 20 63 6f 75 72 73 65 2c 20 74 68  l. Of course, th
19a00 69 73 20 76 61 6c 75 65 20 77 69 6c 6c 20 6e 6f  is value will no
19a10 74 20 69 6e 63 6c 75 64 65 20 0a 2a 2a 20 20 20  t include .**   
19a20 20 20 20 20 20 61 6e 79 20 63 68 61 6e 67 65 73       any changes
19a30 20 70 65 72 66 6f 72 6d 65 64 20 62 79 20 73 75   performed by su
19a40 62 2d 74 72 69 67 67 65 72 73 2c 20 61 73 20 74  b-triggers, as t
19a50 68 65 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67  he sqlite3_chang
19a60 65 73 28 29 20 0a 2a 2a 20 20 20 20 20 20 20 20  es() .**        
19a70 76 61 6c 75 65 20 77 69 6c 6c 20 62 65 20 73 61  value will be sa
19a80 76 65 64 20 61 6e 64 20 72 65 73 74 6f 72 65 64  ved and restored
19a90 20 61 66 74 65 72 20 65 61 63 68 20 73 75 62 2d   after each sub-
19aa0 74 72 69 67 67 65 72 20 68 61 73 20 72 75 6e 2e  trigger has run.
19ab0 29 5e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 20 0a  )^.** </ul>.** .
19ac0 2a 2a 20 5e 54 68 69 73 20 6d 65 61 6e 73 20 74  ** ^This means t
19ad0 68 61 74 20 69 66 20 74 68 65 20 63 68 61 6e 67  hat if the chang
19ae0 65 73 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f  es() SQL functio
19af0 6e 20 28 6f 72 20 73 69 6d 69 6c 61 72 29 20 69  n (or similar) i
19b00 73 20 75 73 65 64 0a 2a 2a 20 62 79 20 74 68 65  s used.** by the
19b10 20 66 69 72 73 74 20 49 4e 53 45 52 54 2c 20 55   first INSERT, U
19b20 50 44 41 54 45 20 6f 72 20 44 45 4c 45 54 45 20  PDATE or DELETE 
19b30 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68 69 6e  statement within
19b40 20 61 20 74 72 69 67 67 65 72 2c 20 69 74 20 0a   a trigger, it .
19b50 2a 2a 20 72 65 74 75 72 6e 73 20 74 68 65 20 76  ** returns the v
19b60 61 6c 75 65 20 61 73 20 73 65 74 20 77 68 65 6e  alue as set when
19b70 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 73 74 61   the calling sta
19b80 74 65 6d 65 6e 74 20 62 65 67 61 6e 20 65 78 65  tement began exe
19b90 63 75 74 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 69  cuting..** ^If i
19ba0 74 20 69 73 20 75 73 65 64 20 62 79 20 74 68 65  t is used by the
19bb0 20 73 65 63 6f 6e 64 20 6f 72 20 73 75 62 73 65   second or subse
19bc0 71 75 65 6e 74 20 73 75 63 68 20 73 74 61 74 65  quent such state
19bd0 6d 65 6e 74 20 77 69 74 68 69 6e 20 61 20 74 72  ment within a tr
19be0 69 67 67 65 72 20 0a 2a 2a 20 70 72 6f 67 72 61  igger .** progra
19bf0 6d 2c 20 74 68 65 20 76 61 6c 75 65 20 72 65 74  m, the value ret
19c00 75 72 6e 65 64 20 72 65 66 6c 65 63 74 73 20 74  urned reflects t
19c10 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77  he number of row
19c20 73 20 6d 6f 64 69 66 69 65 64 20 62 79 20 74 68  s modified by th
19c30 65 20 0a 2a 2a 20 70 72 65 76 69 6f 75 73 20 49  e .** previous I
19c40 4e 53 45 52 54 2c 20 55 50 44 41 54 45 20 6f 72  NSERT, UPDATE or
19c50 20 44 45 4c 45 54 45 20 73 74 61 74 65 6d 65 6e   DELETE statemen
19c60 74 20 77 69 74 68 69 6e 20 74 68 65 20 73 61 6d  t within the sam
19c70 65 20 74 72 69 67 67 65 72 2e 0a 2a 2a 0a 2a 2a  e trigger..**.**
19c80 20 53 65 65 20 61 6c 73 6f 20 74 68 65 20 5b 73   See also the [s
19c90 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61  qlite3_total_cha
19ca0 6e 67 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63  nges()] interfac
19cb0 65 2c 20 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e 74  e, the.** [count
19cc0 5f 63 68 61 6e 67 65 73 20 70 72 61 67 6d 61 5d  _changes pragma]
19cd0 2c 20 61 6e 64 20 74 68 65 20 5b 63 68 61 6e 67  , and the [chang
19ce0 65 73 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f  es() SQL functio
19cf0 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73  n]..**.** If a s
19d00 65 70 61 72 61 74 65 20 74 68 72 65 61 64 20 6d  eparate thread m
19d10 61 6b 65 73 20 63 68 61 6e 67 65 73 20 6f 6e 20  akes changes on 
19d20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73  the same databas
19d30 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20  e connection.** 
19d40 77 68 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f 63  while [sqlite3_c
19d50 68 61 6e 67 65 73 28 29 5d 20 69 73 20 72 75 6e  hanges()] is run
19d60 6e 69 6e 67 20 74 68 65 6e 20 74 68 65 20 76 61  ning then the va
19d70 6c 75 65 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20  lue returned.** 
19d80 69 73 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65  is unpredictable
19d90 20 61 6e 64 20 6e 6f 74 20 6d 65 61 6e 69 6e 67   and not meaning
19da0 66 75 6c 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  ful..*/.SQLITE_A
19db0 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  PI int sqlite3_c
19dc0 68 61 6e 67 65 73 28 73 71 6c 69 74 65 33 2a 29  hanges(sqlite3*)
19dd0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
19de0 46 3a 20 54 6f 74 61 6c 20 4e 75 6d 62 65 72 20  F: Total Number 
19df0 4f 66 20 52 6f 77 73 20 4d 6f 64 69 66 69 65 64  Of Rows Modified
19e00 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
19e10 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20  te3.**.** ^This 
19e20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73  function returns
19e30 20 74 68 65 20 74 6f 74 61 6c 20 6e 75 6d 62 65   the total numbe
19e40 72 20 6f 66 20 72 6f 77 73 20 69 6e 73 65 72 74  r of rows insert
19e50 65 64 2c 20 6d 6f 64 69 66 69 65 64 20 6f 72 0a  ed, modified or.
19e60 2a 2a 20 64 65 6c 65 74 65 64 20 62 79 20 61 6c  ** deleted by al
19e70 6c 20 5b 49 4e 53 45 52 54 5d 2c 20 5b 55 50 44  l [INSERT], [UPD
19e80 41 54 45 5d 20 6f 72 20 5b 44 45 4c 45 54 45 5d  ATE] or [DELETE]
19e90 20 73 74 61 74 65 6d 65 6e 74 73 20 63 6f 6d 70   statements comp
19ea0 6c 65 74 65 64 0a 2a 2a 20 73 69 6e 63 65 20 74  leted.** since t
19eb0 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
19ec0 65 63 74 69 6f 6e 20 77 61 73 20 6f 70 65 6e 65  ection was opene
19ed0 64 2c 20 69 6e 63 6c 75 64 69 6e 67 20 74 68 6f  d, including tho
19ee0 73 65 20 65 78 65 63 75 74 65 64 20 61 73 0a 2a  se executed as.*
19ef0 2a 20 70 61 72 74 20 6f 66 20 74 72 69 67 67 65  * part of trigge
19f00 72 20 70 72 6f 67 72 61 6d 73 2e 20 5e 45 78 65  r programs. ^Exe
19f10 63 75 74 69 6e 67 20 61 6e 79 20 6f 74 68 65 72  cuting any other
19f20 20 74 79 70 65 20 6f 66 20 53 51 4c 20 73 74 61   type of SQL sta
19f30 74 65 6d 65 6e 74 0a 2a 2a 20 64 6f 65 73 20 6e  tement.** does n
19f40 6f 74 20 61 66 66 65 63 74 20 74 68 65 20 76 61  ot affect the va
19f50 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20  lue returned by 
19f60 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68  sqlite3_total_ch
19f70 61 6e 67 65 73 28 29 2e 0a 2a 2a 20 0a 2a 2a 20  anges()..** .** 
19f80 5e 43 68 61 6e 67 65 73 20 6d 61 64 65 20 61 73  ^Changes made as
19f90 20 70 61 72 74 20 6f 66 20 5b 66 6f 72 65 69 67   part of [foreig
19fa0 6e 20 6b 65 79 20 61 63 74 69 6f 6e 73 5d 20 61  n key actions] a
19fb0 72 65 20 69 6e 63 6c 75 64 65 64 20 69 6e 20 74  re included in t
19fc0 68 65 0a 2a 2a 20 63 6f 75 6e 74 2c 20 62 75 74  he.** count, but
19fd0 20 74 68 6f 73 65 20 6d 61 64 65 20 61 73 20 70   those made as p
19fe0 61 72 74 20 6f 66 20 52 45 50 4c 41 43 45 20 63  art of REPLACE c
19ff0 6f 6e 73 74 72 61 69 6e 74 20 72 65 73 6f 6c 75  onstraint resolu
1a000 74 69 6f 6e 20 61 72 65 0a 2a 2a 20 6e 6f 74 2e  tion are.** not.
1a010 20 5e 43 68 61 6e 67 65 73 20 74 6f 20 61 20 76   ^Changes to a v
1a020 69 65 77 20 74 68 61 74 20 61 72 65 20 69 6e 74  iew that are int
1a030 65 72 63 65 70 74 65 64 20 62 79 20 49 4e 53 54  ercepted by INST
1a040 45 41 44 20 4f 46 20 74 72 69 67 67 65 72 73 20  EAD OF triggers 
1a050 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e  .** are not coun
1a060 74 65 64 2e 0a 2a 2a 20 0a 2a 2a 20 53 65 65 20  ted..** .** See 
1a070 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  also the [sqlite
1a080 33 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 6e 74  3_changes()] int
1a090 65 72 66 61 63 65 2c 20 74 68 65 0a 2a 2a 20 5b  erface, the.** [
1a0a0 63 6f 75 6e 74 5f 63 68 61 6e 67 65 73 20 70 72  count_changes pr
1a0b0 61 67 6d 61 5d 2c 20 61 6e 64 20 74 68 65 20 5b  agma], and the [
1a0c0 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 20  total_changes() 
1a0d0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a  SQL function]..*
1a0e0 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70 61 72 61  *.** If a separa
1a0f0 74 65 20 74 68 72 65 61 64 20 6d 61 6b 65 73 20  te thread makes 
1a100 63 68 61 6e 67 65 73 20 6f 6e 20 74 68 65 20 73  changes on the s
1a110 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  ame database con
1a120 6e 65 63 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65  nection.** while
1a130 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f   [sqlite3_total_
1a140 63 68 61 6e 67 65 73 28 29 5d 20 69 73 20 72 75  changes()] is ru
1a150 6e 6e 69 6e 67 20 74 68 65 6e 20 74 68 65 20 76  nning then the v
1a160 61 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64  alue.** returned
1a170 20 69 73 20 75 6e 70 72 65 64 69 63 74 61 62 6c   is unpredictabl
1a180 65 20 61 6e 64 20 6e 6f 74 20 6d 65 61 6e 69 6e  e and not meanin
1a190 67 66 75 6c 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  gful..*/.SQLITE_
1a1a0 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
1a1b0 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 73 71  total_changes(sq
1a1c0 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  lite3*);../*.** 
1a1d0 43 41 50 49 33 52 45 46 3a 20 49 6e 74 65 72 72  CAPI3REF: Interr
1a1e0 75 70 74 20 41 20 4c 6f 6e 67 2d 52 75 6e 6e 69  upt A Long-Runni
1a1f0 6e 67 20 51 75 65 72 79 0a 2a 2a 20 4d 45 54 48  ng Query.** METH
1a200 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a  OD: sqlite3.**.*
1a210 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e  * ^This function
1a220 20 63 61 75 73 65 73 20 61 6e 79 20 70 65 6e 64   causes any pend
1a230 69 6e 67 20 64 61 74 61 62 61 73 65 20 6f 70 65  ing database ope
1a240 72 61 74 69 6f 6e 20 74 6f 20 61 62 6f 72 74 20  ration to abort 
1a250 61 6e 64 0a 2a 2a 20 72 65 74 75 72 6e 20 61 74  and.** return at
1a260 20 69 74 73 20 65 61 72 6c 69 65 73 74 20 6f 70   its earliest op
1a270 70 6f 72 74 75 6e 69 74 79 2e 20 54 68 69 73 20  portunity. This 
1a280 72 6f 75 74 69 6e 65 20 69 73 20 74 79 70 69 63  routine is typic
1a290 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64 20 69  ally.** called i
1a2a0 6e 20 72 65 73 70 6f 6e 73 65 20 74 6f 20 61 20  n response to a 
1a2b0 75 73 65 72 20 61 63 74 69 6f 6e 20 73 75 63 68  user action such
1a2c0 20 61 73 20 70 72 65 73 73 69 6e 67 20 22 43 61   as pressing "Ca
1a2d0 6e 63 65 6c 22 0a 2a 2a 20 6f 72 20 43 74 72 6c  ncel".** or Ctrl
1a2e0 2d 43 20 77 68 65 72 65 20 74 68 65 20 75 73 65  -C where the use
1a2f0 72 20 77 61 6e 74 73 20 61 20 6c 6f 6e 67 20 71  r wants a long q
1a300 75 65 72 79 20 6f 70 65 72 61 74 69 6f 6e 20 74  uery operation t
1a310 6f 20 68 61 6c 74 0a 2a 2a 20 69 6d 6d 65 64 69  o halt.** immedi
1a320 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74  ately..**.** ^It
1a330 20 69 73 20 73 61 66 65 20 74 6f 20 63 61 6c 6c   is safe to call
1a340 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 66 72   this routine fr
1a350 6f 6d 20 61 20 74 68 72 65 61 64 20 64 69 66 66  om a thread diff
1a360 65 72 65 6e 74 20 66 72 6f 6d 20 74 68 65 0a 2a  erent from the.*
1a370 2a 20 74 68 72 65 61 64 20 74 68 61 74 20 69 73  * thread that is
1a380 20 63 75 72 72 65 6e 74 6c 79 20 72 75 6e 6e 69   currently runni
1a390 6e 67 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ng the database 
1a3a0 6f 70 65 72 61 74 69 6f 6e 2e 20 20 42 75 74 20  operation.  But 
1a3b0 69 74 0a 2a 2a 20 69 73 20 6e 6f 74 20 73 61 66  it.** is not saf
1a3c0 65 20 74 6f 20 63 61 6c 6c 20 74 68 69 73 20 72  e to call this r
1a3d0 6f 75 74 69 6e 65 20 77 69 74 68 20 61 20 5b 64  outine with a [d
1a3e0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1a3f0 6f 6e 5d 20 74 68 61 74 0a 2a 2a 20 69 73 20 63  on] that.** is c
1a400 6c 6f 73 65 64 20 6f 72 20 6d 69 67 68 74 20 63  losed or might c
1a410 6c 6f 73 65 20 62 65 66 6f 72 65 20 73 71 6c 69  lose before sqli
1a420 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20  te3_interrupt() 
1a430 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e  returns..**.** ^
1a440 49 66 20 61 6e 20 53 51 4c 20 6f 70 65 72 61 74  If an SQL operat
1a450 69 6f 6e 20 69 73 20 76 65 72 79 20 6e 65 61 72  ion is very near
1a460 6c 79 20 66 69 6e 69 73 68 65 64 20 61 74 20 74  ly finished at t
1a470 68 65 20 74 69 6d 65 20 77 68 65 6e 0a 2a 2a 20  he time when.** 
1a480 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
1a490 74 28 29 20 69 73 20 63 61 6c 6c 65 64 2c 20 74  t() is called, t
1a4a0 68 65 6e 20 69 74 20 6d 69 67 68 74 20 6e 6f 74  hen it might not
1a4b0 20 68 61 76 65 20 61 6e 20 6f 70 70 6f 72 74 75   have an opportu
1a4c0 6e 69 74 79 0a 2a 2a 20 74 6f 20 62 65 20 69 6e  nity.** to be in
1a4d0 74 65 72 72 75 70 74 65 64 20 61 6e 64 20 6d 69  terrupted and mi
1a4e0 67 68 74 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20  ght continue to 
1a4f0 63 6f 6d 70 6c 65 74 69 6f 6e 2e 0a 2a 2a 0a 2a  completion..**.*
1a500 2a 20 5e 41 6e 20 53 51 4c 20 6f 70 65 72 61 74  * ^An SQL operat
1a510 69 6f 6e 20 74 68 61 74 20 69 73 20 69 6e 74 65  ion that is inte
1a520 72 72 75 70 74 65 64 20 77 69 6c 6c 20 72 65 74  rrupted will ret
1a530 75 72 6e 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45  urn [SQLITE_INTE
1a540 52 52 55 50 54 5d 2e 0a 2a 2a 20 5e 49 66 20 74  RRUPT]..** ^If t
1a550 68 65 20 69 6e 74 65 72 72 75 70 74 65 64 20 53  he interrupted S
1a560 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20  QL operation is 
1a570 61 6e 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54  an INSERT, UPDAT
1a580 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20  E, or DELETE.** 
1a590 74 68 61 74 20 69 73 20 69 6e 73 69 64 65 20 61  that is inside a
1a5a0 6e 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73  n explicit trans
1a5b0 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65  action, then the
1a5c0 20 65 6e 74 69 72 65 20 74 72 61 6e 73 61 63 74   entire transact
1a5d0 69 6f 6e 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 72  ion.** will be r
1a5e0 6f 6c 6c 65 64 20 62 61 63 6b 20 61 75 74 6f 6d  olled back autom
1a5f0 61 74 69 63 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20  atically..**.** 
1a600 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74  ^The sqlite3_int
1a610 65 72 72 75 70 74 28 44 29 20 63 61 6c 6c 20 69  errupt(D) call i
1a620 73 20 69 6e 20 65 66 66 65 63 74 20 75 6e 74 69  s in effect unti
1a630 6c 20 61 6c 6c 20 63 75 72 72 65 6e 74 6c 79 20  l all currently 
1a640 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51 4c 20 73  running.** SQL s
1a650 74 61 74 65 6d 65 6e 74 73 20 6f 6e 20 5b 64 61  tatements on [da
1a660 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1a670 6e 5d 20 44 20 63 6f 6d 70 6c 65 74 65 2e 20 20  n] D complete.  
1a680 5e 41 6e 79 20 6e 65 77 20 53 51 4c 20 73 74 61  ^Any new SQL sta
1a690 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20  tements.** that 
1a6a0 61 72 65 20 73 74 61 72 74 65 64 20 61 66 74 65  are started afte
1a6b0 72 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e  r the sqlite3_in
1a6c0 74 65 72 72 75 70 74 28 29 20 63 61 6c 6c 20 61  terrupt() call a
1a6d0 6e 64 20 62 65 66 6f 72 65 20 74 68 65 20 0a 2a  nd before the .*
1a6e0 2a 20 72 75 6e 6e 69 6e 67 20 73 74 61 74 65 6d  * running statem
1a6f0 65 6e 74 73 20 72 65 61 63 68 65 73 20 7a 65 72  ents reaches zer
1a700 6f 20 61 72 65 20 69 6e 74 65 72 72 75 70 74 65  o are interrupte
1a710 64 20 61 73 20 69 66 20 74 68 65 79 20 68 61 64  d as if they had
1a720 20 62 65 65 6e 0a 2a 2a 20 72 75 6e 6e 69 6e 67   been.** running
1a730 20 70 72 69 6f 72 20 74 6f 20 74 68 65 20 73 71   prior to the sq
1a740 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28  lite3_interrupt(
1a750 29 20 63 61 6c 6c 2e 20 20 5e 4e 65 77 20 53 51  ) call.  ^New SQ
1a760 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20  L statements.** 
1a770 74 68 61 74 20 61 72 65 20 73 74 61 72 74 65 64  that are started
1a780 20 61 66 74 65 72 20 74 68 65 20 72 75 6e 6e 69   after the runni
1a790 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 75  ng statement cou
1a7a0 6e 74 20 72 65 61 63 68 65 73 20 7a 65 72 6f 20  nt reaches zero 
1a7b0 61 72 65 0a 2a 2a 20 6e 6f 74 20 65 66 66 65 63  are.** not effec
1a7c0 74 65 64 20 62 79 20 74 68 65 20 73 71 6c 69 74  ted by the sqlit
1a7d0 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 2e 0a  e3_interrupt()..
1a7e0 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 6f 20 73 71  ** ^A call to sq
1a7f0 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28  lite3_interrupt(
1a800 44 29 20 74 68 61 74 20 6f 63 63 75 72 73 20 77  D) that occurs w
1a810 68 65 6e 20 74 68 65 72 65 20 61 72 65 20 6e 6f  hen there are no
1a820 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51 4c 20   running.** SQL 
1a830 73 74 61 74 65 6d 65 6e 74 73 20 69 73 20 61 20  statements is a 
1a840 6e 6f 2d 6f 70 20 61 6e 64 20 68 61 73 20 6e 6f  no-op and has no
1a850 20 65 66 66 65 63 74 20 6f 6e 20 53 51 4c 20 73   effect on SQL s
1a860 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61  tatements.** tha
1a870 74 20 61 72 65 20 73 74 61 72 74 65 64 20 61 66  t are started af
1a880 74 65 72 20 74 68 65 20 73 71 6c 69 74 65 33 5f  ter the sqlite3_
1a890 69 6e 74 65 72 72 75 70 74 28 29 20 63 61 6c 6c  interrupt() call
1a8a0 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20   returns..**.** 
1a8b0 49 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  If the database 
1a8c0 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f 73 65  connection close
1a8d0 73 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 65 33  s while [sqlite3
1a8e0 5f 69 6e 74 65 72 72 75 70 74 28 29 5d 0a 2a 2a  _interrupt()].**
1a8f0 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e   is running then
1a900 20 62 61 64 20 74 68 69 6e 67 73 20 77 69 6c 6c   bad things will
1a910 20 6c 69 6b 65 6c 79 20 68 61 70 70 65 6e 2e 0a   likely happen..
1a920 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f  */.SQLITE_API vo
1a930 69 64 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  id sqlite3_inter
1a940 72 75 70 74 28 73 71 6c 69 74 65 33 2a 29 3b 0a  rupt(sqlite3*);.
1a950 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1a960 20 44 65 74 65 72 6d 69 6e 65 20 49 66 20 41 6e   Determine If An
1a970 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 49   SQL Statement I
1a980 73 20 43 6f 6d 70 6c 65 74 65 0a 2a 2a 0a 2a 2a  s Complete.**.**
1a990 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
1a9a0 61 72 65 20 75 73 65 66 75 6c 20 64 75 72 69 6e  are useful durin
1a9b0 67 20 63 6f 6d 6d 61 6e 64 2d 6c 69 6e 65 20 69  g command-line i
1a9c0 6e 70 75 74 20 74 6f 20 64 65 74 65 72 6d 69 6e  nput to determin
1a9d0 65 20 69 66 20 74 68 65 0a 2a 2a 20 63 75 72 72  e if the.** curr
1a9e0 65 6e 74 6c 79 20 65 6e 74 65 72 65 64 20 74 65  ently entered te
1a9f0 78 74 20 73 65 65 6d 73 20 74 6f 20 66 6f 72 6d  xt seems to form
1aa00 20 61 20 63 6f 6d 70 6c 65 74 65 20 53 51 4c 20   a complete SQL 
1aa10 73 74 61 74 65 6d 65 6e 74 20 6f 72 0a 2a 2a 20  statement or.** 
1aa20 69 66 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e  if additional in
1aa30 70 75 74 20 69 73 20 6e 65 65 64 65 64 20 62 65  put is needed be
1aa40 66 6f 72 65 20 73 65 6e 64 69 6e 67 20 74 68 65  fore sending the
1aa50 20 74 65 78 74 20 69 6e 74 6f 0a 2a 2a 20 53 51   text into.** SQ
1aa60 4c 69 74 65 20 66 6f 72 20 70 61 72 73 69 6e 67  Lite for parsing
1aa70 2e 20 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e  .  ^These routin
1aa80 65 73 20 72 65 74 75 72 6e 20 31 20 69 66 20 74  es return 1 if t
1aa90 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67 0a  he input string.
1aaa0 2a 2a 20 61 70 70 65 61 72 73 20 74 6f 20 62 65  ** appears to be
1aab0 20 61 20 63 6f 6d 70 6c 65 74 65 20 53 51 4c 20   a complete SQL 
1aac0 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 41 20 73  statement.  ^A s
1aad0 74 61 74 65 6d 65 6e 74 20 69 73 20 6a 75 64 67  tatement is judg
1aae0 65 64 20 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70  ed to be.** comp
1aaf0 6c 65 74 65 20 69 66 20 69 74 20 65 6e 64 73 20  lete if it ends 
1ab00 77 69 74 68 20 61 20 73 65 6d 69 63 6f 6c 6f 6e  with a semicolon
1ab10 20 74 6f 6b 65 6e 20 61 6e 64 20 69 73 20 6e 6f   token and is no
1ab20 74 20 61 20 70 72 65 66 69 78 20 6f 66 20 61 0a  t a prefix of a.
1ab30 2a 2a 20 77 65 6c 6c 2d 66 6f 72 6d 65 64 20 43  ** well-formed C
1ab40 52 45 41 54 45 20 54 52 49 47 47 45 52 20 73 74  REATE TRIGGER st
1ab50 61 74 65 6d 65 6e 74 2e 20 20 5e 53 65 6d 69 63  atement.  ^Semic
1ab60 6f 6c 6f 6e 73 20 74 68 61 74 20 61 72 65 20 65  olons that are e
1ab70 6d 62 65 64 64 65 64 20 77 69 74 68 69 6e 0a 2a  mbedded within.*
1ab80 2a 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c  * string literal
1ab90 73 20 6f 72 20 71 75 6f 74 65 64 20 69 64 65 6e  s or quoted iden
1aba0 74 69 66 69 65 72 20 6e 61 6d 65 73 20 6f 72 20  tifier names or 
1abb0 63 6f 6d 6d 65 6e 74 73 20 61 72 65 20 6e 6f 74  comments are not
1abc0 0a 2a 2a 20 69 6e 64 65 70 65 6e 64 65 6e 74 20  .** independent 
1abd0 74 6f 6b 65 6e 73 20 28 74 68 65 79 20 61 72 65  tokens (they are
1abe0 20 70 61 72 74 20 6f 66 20 74 68 65 20 74 6f 6b   part of the tok
1abf0 65 6e 20 69 6e 20 77 68 69 63 68 20 74 68 65 79  en in which they
1ac00 20 61 72 65 0a 2a 2a 20 65 6d 62 65 64 64 65 64   are.** embedded
1ac10 29 20 61 6e 64 20 74 68 75 73 20 64 6f 20 6e 6f  ) and thus do no
1ac20 74 20 63 6f 75 6e 74 20 61 73 20 61 20 73 74 61  t count as a sta
1ac30 74 65 6d 65 6e 74 20 74 65 72 6d 69 6e 61 74 6f  tement terminato
1ac40 72 2e 20 20 5e 57 68 69 74 65 73 70 61 63 65 0a  r.  ^Whitespace.
1ac50 2a 2a 20 61 6e 64 20 63 6f 6d 6d 65 6e 74 73 20  ** and comments 
1ac60 74 68 61 74 20 66 6f 6c 6c 6f 77 20 74 68 65 20  that follow the 
1ac70 66 69 6e 61 6c 20 73 65 6d 69 63 6f 6c 6f 6e 20  final semicolon 
1ac80 61 72 65 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a  are ignored..**.
1ac90 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e  ** ^These routin
1aca0 65 73 20 72 65 74 75 72 6e 20 30 20 69 66 20 74  es return 0 if t
1acb0 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  he statement is 
1acc0 69 6e 63 6f 6d 70 6c 65 74 65 2e 20 20 5e 49 66  incomplete.  ^If
1acd0 20 61 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c   a.** memory all
1ace0 6f 63 61 74 69 6f 6e 20 66 61 69 6c 73 2c 20 74  ocation fails, t
1acf0 68 65 6e 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d  hen SQLITE_NOMEM
1ad00 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a   is returned..**
1ad10 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69  .** ^These routi
1ad20 6e 65 73 20 64 6f 20 6e 6f 74 20 70 61 72 73 65  nes do not parse
1ad30 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
1ad40 6e 74 73 20 74 68 75 73 0a 2a 2a 20 77 69 6c 6c  nts thus.** will
1ad50 20 6e 6f 74 20 64 65 74 65 63 74 20 73 79 6e 74   not detect synt
1ad60 61 63 74 69 63 61 6c 6c 79 20 69 6e 63 6f 72 72  actically incorr
1ad70 65 63 74 20 53 51 4c 2e 0a 2a 2a 0a 2a 2a 20 5e  ect SQL..**.** ^
1ad80 28 49 66 20 53 51 4c 69 74 65 20 68 61 73 20 6e  (If SQLite has n
1ad90 6f 74 20 62 65 65 6e 20 69 6e 69 74 69 61 6c 69  ot been initiali
1ada0 7a 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  zed using [sqlit
1adb0 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d  e3_initialize()]
1adc0 20 70 72 69 6f 72 20 0a 2a 2a 20 74 6f 20 69 6e   prior .** to in
1add0 76 6f 6b 69 6e 67 20 73 71 6c 69 74 65 33 5f 63  voking sqlite3_c
1ade0 6f 6d 70 6c 65 74 65 31 36 28 29 20 74 68 65 6e  omplete16() then
1adf0 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
1ae00 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64  ize() is invoked
1ae10 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  .** automaticall
1ae20 79 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6d  y by sqlite3_com
1ae30 70 6c 65 74 65 31 36 28 29 2e 20 20 49 66 20 74  plete16().  If t
1ae40 68 61 74 20 69 6e 69 74 69 61 6c 69 7a 61 74 69  hat initializati
1ae50 6f 6e 20 66 61 69 6c 73 2c 0a 2a 2a 20 74 68 65  on fails,.** the
1ae60 6e 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  n the return val
1ae70 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f  ue from sqlite3_
1ae80 63 6f 6d 70 6c 65 74 65 31 36 28 29 20 77 69 6c  complete16() wil
1ae90 6c 20 62 65 20 6e 6f 6e 2d 7a 65 72 6f 0a 2a 2a  l be non-zero.**
1aea0 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77   regardless of w
1aeb0 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68  hether or not th
1aec0 65 20 69 6e 70 75 74 20 53 51 4c 20 69 73 20 63  e input SQL is c
1aed0 6f 6d 70 6c 65 74 65 2e 29 5e 0a 2a 2a 0a 2a 2a  omplete.)^.**.**
1aee0 20 54 68 65 20 69 6e 70 75 74 20 74 6f 20 5b 73   The input to [s
1aef0 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 28  qlite3_complete(
1af00 29 5d 20 6d 75 73 74 20 62 65 20 61 20 7a 65 72  )] must be a zer
1af10 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20  o-terminated.** 
1af20 55 54 46 2d 38 20 73 74 72 69 6e 67 2e 0a 2a 2a  UTF-8 string..**
1af30 0a 2a 2a 20 54 68 65 20 69 6e 70 75 74 20 74 6f  .** The input to
1af40 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65   [sqlite3_comple
1af50 74 65 31 36 28 29 5d 20 6d 75 73 74 20 62 65 20  te16()] must be 
1af60 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  a zero-terminate
1af70 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73 74 72 69  d.** UTF-16 stri
1af80 6e 67 20 69 6e 20 6e 61 74 69 76 65 20 62 79 74  ng in native byt
1af90 65 20 6f 72 64 65 72 2e 0a 2a 2f 0a 53 51 4c 49  e order..*/.SQLI
1afa0 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
1afb0 65 33 5f 63 6f 6d 70 6c 65 74 65 28 63 6f 6e 73  e3_complete(cons
1afc0 74 20 63 68 61 72 20 2a 73 71 6c 29 3b 0a 53 51  t char *sql);.SQ
1afd0 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
1afe0 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28  ite3_complete16(
1aff0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 29  const void *sql)
1b000 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
1b010 46 3a 20 52 65 67 69 73 74 65 72 20 41 20 43 61  F: Register A Ca
1b020 6c 6c 62 61 63 6b 20 54 6f 20 48 61 6e 64 6c 65  llback To Handle
1b030 20 53 51 4c 49 54 45 5f 42 55 53 59 20 45 72 72   SQLITE_BUSY Err
1b040 6f 72 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  ors.** KEYWORDS:
1b050 20 7b 62 75 73 79 2d 68 61 6e 64 6c 65 72 20 63   {busy-handler c
1b060 61 6c 6c 62 61 63 6b 7d 20 7b 62 75 73 79 20 68  allback} {busy h
1b070 61 6e 64 6c 65 72 7d 0a 2a 2a 20 4d 45 54 48 4f  andler}.** METHO
1b080 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a  D: sqlite3.**.**
1b090 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 62 75   ^The sqlite3_bu
1b0a0 73 79 5f 68 61 6e 64 6c 65 72 28 44 2c 58 2c 50  sy_handler(D,X,P
1b0b0 29 20 72 6f 75 74 69 6e 65 20 73 65 74 73 20 61  ) routine sets a
1b0c0 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
1b0d0 6f 6e 20 58 0a 2a 2a 20 74 68 61 74 20 6d 69 67  on X.** that mig
1b0e0 68 74 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 69  ht be invoked wi
1b0f0 74 68 20 61 72 67 75 6d 65 6e 74 20 50 20 77 68  th argument P wh
1b100 65 6e 65 76 65 72 0a 2a 2a 20 61 6e 20 61 74 74  enever.** an att
1b110 65 6d 70 74 20 69 73 20 6d 61 64 65 20 74 6f 20  empt is made to 
1b120 61 63 63 65 73 73 20 61 20 64 61 74 61 62 61 73  access a databas
1b130 65 20 74 61 62 6c 65 20 61 73 73 6f 63 69 61 74  e table associat
1b140 65 64 20 77 69 74 68 0a 2a 2a 20 5b 64 61 74 61  ed with.** [data
1b150 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
1b160 20 44 20 77 68 65 6e 20 61 6e 6f 74 68 65 72 20   D when another 
1b170 74 68 72 65 61 64 0a 2a 2a 20 6f 72 20 70 72 6f  thread.** or pro
1b180 63 65 73 73 20 68 61 73 20 74 68 65 20 74 61 62  cess has the tab
1b190 6c 65 20 6c 6f 63 6b 65 64 2e 0a 2a 2a 20 54 68  le locked..** Th
1b1a0 65 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68  e sqlite3_busy_h
1b1b0 61 6e 64 6c 65 72 28 29 20 69 6e 74 65 72 66 61  andler() interfa
1b1c0 63 65 20 69 73 20 75 73 65 64 20 74 6f 20 69 6d  ce is used to im
1b1d0 70 6c 65 6d 65 6e 74 0a 2a 2a 20 5b 73 71 6c 69  plement.** [sqli
1b1e0 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74  te3_busy_timeout
1b1f0 28 29 5d 20 61 6e 64 20 5b 50 52 41 47 4d 41 20  ()] and [PRAGMA 
1b200 62 75 73 79 5f 74 69 6d 65 6f 75 74 5d 2e 0a 2a  busy_timeout]..*
1b210 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 62 75 73  *.** ^If the bus
1b220 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e 55  y callback is NU
1b230 4c 4c 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54 45  LL, then [SQLITE
1b240 5f 42 55 53 59 5d 0a 2a 2a 20 69 73 20 72 65 74  _BUSY].** is ret
1b250 75 72 6e 65 64 20 69 6d 6d 65 64 69 61 74 65 6c  urned immediatel
1b260 79 20 75 70 6f 6e 20 65 6e 63 6f 75 6e 74 65 72  y upon encounter
1b270 69 6e 67 20 74 68 65 20 6c 6f 63 6b 2e 20 20 5e  ing the lock.  ^
1b280 49 66 20 74 68 65 20 62 75 73 79 20 63 61 6c 6c  If the busy call
1b290 62 61 63 6b 0a 2a 2a 20 69 73 20 6e 6f 74 20 4e  back.** is not N
1b2a0 55 4c 4c 2c 20 74 68 65 6e 20 74 68 65 20 63 61  ULL, then the ca
1b2b0 6c 6c 62 61 63 6b 20 6d 69 67 68 74 20 62 65 20  llback might be 
1b2c0 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 74 77 6f  invoked with two
1b2d0 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a   arguments..**.*
1b2e0 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 72 67  * ^The first arg
1b2f0 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 62 75 73  ument to the bus
1b300 79 20 68 61 6e 64 6c 65 72 20 69 73 20 61 20 63  y handler is a c
1b310 6f 70 79 20 6f 66 20 74 68 65 20 76 6f 69 64 2a  opy of the void*
1b320 20 70 6f 69 6e 74 65 72 20 77 68 69 63 68 0a 2a   pointer which.*
1b330 2a 20 69 73 20 74 68 65 20 74 68 69 72 64 20 61  * is the third a
1b340 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74  rgument to sqlit
1b350 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28  e3_busy_handler(
1b360 29 2e 20 20 5e 54 68 65 20 73 65 63 6f 6e 64 20  ).  ^The second 
1b370 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 74  argument to.** t
1b380 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20  he busy handler 
1b390 63 61 6c 6c 62 61 63 6b 20 69 73 20 74 68 65 20  callback is the 
1b3a0 6e 75 6d 62 65 72 20 6f 66 20 74 69 6d 65 73 20  number of times 
1b3b0 74 68 61 74 20 74 68 65 20 62 75 73 79 20 68 61  that the busy ha
1b3c0 6e 64 6c 65 72 20 68 61 73 0a 2a 2a 20 62 65 65  ndler has.** bee
1b3d0 6e 20 69 6e 76 6f 6b 65 64 20 70 72 65 76 69 6f  n invoked previo
1b3e0 75 73 6c 79 20 66 6f 72 20 74 68 65 20 73 61 6d  usly for the sam
1b3f0 65 20 6c 6f 63 6b 69 6e 67 20 65 76 65 6e 74 2e  e locking event.
1b400 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 62 75 73    ^If the.** bus
1b410 79 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  y callback retur
1b420 6e 73 20 30 2c 20 74 68 65 6e 20 6e 6f 20 61 64  ns 0, then no ad
1b430 64 69 74 69 6f 6e 61 6c 20 61 74 74 65 6d 70 74  ditional attempt
1b440 73 20 61 72 65 20 6d 61 64 65 20 74 6f 0a 2a 2a  s are made to.**
1b450 20 61 63 63 65 73 73 20 74 68 65 20 64 61 74 61   access the data
1b460 62 61 73 65 20 61 6e 64 20 5b 53 51 4c 49 54 45  base and [SQLITE
1b470 5f 42 55 53 59 5d 20 69 73 20 72 65 74 75 72 6e  _BUSY] is return
1b480 65 64 0a 2a 2a 20 74 6f 20 74 68 65 20 61 70 70  ed.** to the app
1b490 6c 69 63 61 74 69 6f 6e 2e 0a 2a 2a 20 5e 49 66  lication..** ^If
1b4a0 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65   the callback re
1b4b0 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20  turns non-zero, 
1b4c0 74 68 65 6e 20 61 6e 6f 74 68 65 72 20 61 74 74  then another att
1b4d0 65 6d 70 74 0a 2a 2a 20 69 73 20 6d 61 64 65 20  empt.** is made 
1b4e0 74 6f 20 61 63 63 65 73 73 20 74 68 65 20 64 61  to access the da
1b4f0 74 61 62 61 73 65 20 61 6e 64 20 74 68 65 20 63  tabase and the c
1b500 79 63 6c 65 20 72 65 70 65 61 74 73 2e 0a 2a 2a  ycle repeats..**
1b510 0a 2a 2a 20 54 68 65 20 70 72 65 73 65 6e 63 65  .** The presence
1b520 20 6f 66 20 61 20 62 75 73 79 20 68 61 6e 64 6c   of a busy handl
1b530 65 72 20 64 6f 65 73 20 6e 6f 74 20 67 75 61 72  er does not guar
1b540 61 6e 74 65 65 20 74 68 61 74 20 69 74 20 77 69  antee that it wi
1b550 6c 6c 20 62 65 20 69 6e 76 6f 6b 65 64 0a 2a 2a  ll be invoked.**
1b560 20 77 68 65 6e 20 74 68 65 72 65 20 69 73 20 6c   when there is l
1b570 6f 63 6b 20 63 6f 6e 74 65 6e 74 69 6f 6e 2e 20  ock contention. 
1b580 5e 49 66 20 53 51 4c 69 74 65 20 64 65 74 65 72  ^If SQLite deter
1b590 6d 69 6e 65 73 20 74 68 61 74 20 69 6e 76 6f 6b  mines that invok
1b5a0 69 6e 67 20 74 68 65 20 62 75 73 79 0a 2a 2a 20  ing the busy.** 
1b5b0 68 61 6e 64 6c 65 72 20 63 6f 75 6c 64 20 72 65  handler could re
1b5c0 73 75 6c 74 20 69 6e 20 61 20 64 65 61 64 6c 6f  sult in a deadlo
1b5d0 63 6b 2c 20 69 74 20 77 69 6c 6c 20 67 6f 20 61  ck, it will go a
1b5e0 68 65 61 64 20 61 6e 64 20 72 65 74 75 72 6e 20  head and return 
1b5f0 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 0a 2a 2a  [SQLITE_BUSY].**
1b600 20 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74   to the applicat
1b610 69 6f 6e 20 69 6e 73 74 65 61 64 20 6f 66 20 69  ion instead of i
1b620 6e 76 6f 6b 69 6e 67 20 74 68 65 20 0a 2a 2a 20  nvoking the .** 
1b630 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a  busy handler..**
1b640 20 43 6f 6e 73 69 64 65 72 20 61 20 73 63 65 6e   Consider a scen
1b650 61 72 69 6f 20 77 68 65 72 65 20 6f 6e 65 20 70  ario where one p
1b660 72 6f 63 65 73 73 20 69 73 20 68 6f 6c 64 69 6e  rocess is holdin
1b670 67 20 61 20 72 65 61 64 20 6c 6f 63 6b 20 74 68  g a read lock th
1b680 61 74 0a 2a 2a 20 69 74 20 69 73 20 74 72 79 69  at.** it is tryi
1b690 6e 67 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 6f  ng to promote to
1b6a0 20 61 20 72 65 73 65 72 76 65 64 20 6c 6f 63 6b   a reserved lock
1b6b0 20 61 6e 64 0a 2a 2a 20 61 20 73 65 63 6f 6e 64   and.** a second
1b6c0 20 70 72 6f 63 65 73 73 20 69 73 20 68 6f 6c 64   process is hold
1b6d0 69 6e 67 20 61 20 72 65 73 65 72 76 65 64 20 6c  ing a reserved l
1b6e0 6f 63 6b 20 74 68 61 74 20 69 74 20 69 73 20 74  ock that it is t
1b6f0 72 79 69 6e 67 0a 2a 2a 20 74 6f 20 70 72 6f 6d  rying.** to prom
1b700 6f 74 65 20 74 6f 20 61 6e 20 65 78 63 6c 75 73  ote to an exclus
1b710 69 76 65 20 6c 6f 63 6b 2e 20 20 54 68 65 20 66  ive lock.  The f
1b720 69 72 73 74 20 70 72 6f 63 65 73 73 20 63 61 6e  irst process can
1b730 6e 6f 74 20 70 72 6f 63 65 65 64 0a 2a 2a 20 62  not proceed.** b
1b740 65 63 61 75 73 65 20 69 74 20 69 73 20 62 6c 6f  ecause it is blo
1b750 63 6b 65 64 20 62 79 20 74 68 65 20 73 65 63 6f  cked by the seco
1b760 6e 64 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e  nd and the secon
1b770 64 20 70 72 6f 63 65 73 73 20 63 61 6e 6e 6f 74  d process cannot
1b780 0a 2a 2a 20 70 72 6f 63 65 65 64 20 62 65 63 61  .** proceed beca
1b790 75 73 65 20 69 74 20 69 73 20 62 6c 6f 63 6b 65  use it is blocke
1b7a0 64 20 62 79 20 74 68 65 20 66 69 72 73 74 2e 20  d by the first. 
1b7b0 20 49 66 20 62 6f 74 68 20 70 72 6f 63 65 73 73   If both process
1b7c0 65 73 0a 2a 2a 20 69 6e 76 6f 6b 65 20 74 68 65  es.** invoke the
1b7d0 20 62 75 73 79 20 68 61 6e 64 6c 65 72 73 2c 20   busy handlers, 
1b7e0 6e 65 69 74 68 65 72 20 77 69 6c 6c 20 6d 61 6b  neither will mak
1b7f0 65 20 61 6e 79 20 70 72 6f 67 72 65 73 73 2e 20  e any progress. 
1b800 20 54 68 65 72 65 66 6f 72 65 2c 0a 2a 2a 20 53   Therefore,.** S
1b810 51 4c 69 74 65 20 72 65 74 75 72 6e 73 20 5b 53  QLite returns [S
1b820 51 4c 49 54 45 5f 42 55 53 59 5d 20 66 6f 72 20  QLITE_BUSY] for 
1b830 74 68 65 20 66 69 72 73 74 20 70 72 6f 63 65 73  the first proces
1b840 73 2c 20 68 6f 70 69 6e 67 20 74 68 61 74 20 74  s, hoping that t
1b850 68 69 73 0a 2a 2a 20 77 69 6c 6c 20 69 6e 64 75  his.** will indu
1b860 63 65 20 74 68 65 20 66 69 72 73 74 20 70 72 6f  ce the first pro
1b870 63 65 73 73 20 74 6f 20 72 65 6c 65 61 73 65 20  cess to release 
1b880 69 74 73 20 72 65 61 64 20 6c 6f 63 6b 20 61 6e  its read lock an
1b890 64 20 61 6c 6c 6f 77 0a 2a 2a 20 74 68 65 20 73  d allow.** the s
1b8a0 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 74 6f  econd process to
1b8b0 20 70 72 6f 63 65 65 64 2e 0a 2a 2a 0a 2a 2a 20   proceed..**.** 
1b8c0 5e 54 68 65 20 64 65 66 61 75 6c 74 20 62 75 73  ^The default bus
1b8d0 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e 55  y callback is NU
1b8e0 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 72  LL..**.** ^(Ther
1b8f0 65 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 61 20  e can only be a 
1b900 73 69 6e 67 6c 65 20 62 75 73 79 20 68 61 6e 64  single busy hand
1b910 6c 65 72 20 64 65 66 69 6e 65 64 20 66 6f 72 20  ler defined for 
1b920 65 61 63 68 0a 2a 2a 20 5b 64 61 74 61 62 61 73  each.** [databas
1b930 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20  e connection].  
1b940 53 65 74 74 69 6e 67 20 61 20 6e 65 77 20 62 75  Setting a new bu
1b950 73 79 20 68 61 6e 64 6c 65 72 20 63 6c 65 61 72  sy handler clear
1b960 73 20 61 6e 79 0a 2a 2a 20 70 72 65 76 69 6f 75  s any.** previou
1b970 73 6c 79 20 73 65 74 20 68 61 6e 64 6c 65 72 2e  sly set handler.
1b980 29 5e 20 20 5e 4e 6f 74 65 20 74 68 61 74 20 63  )^  ^Note that c
1b990 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  alling [sqlite3_
1b9a0 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d 0a  busy_timeout()].
1b9b0 2a 2a 20 6f 72 20 65 76 61 6c 75 61 74 69 6e 67  ** or evaluating
1b9c0 20 5b 50 52 41 47 4d 41 20 62 75 73 79 5f 74 69   [PRAGMA busy_ti
1b9d0 6d 65 6f 75 74 3d 4e 5d 20 77 69 6c 6c 20 63 68  meout=N] will ch
1b9e0 61 6e 67 65 20 74 68 65 0a 2a 2a 20 62 75 73 79  ange the.** busy
1b9f0 20 68 61 6e 64 6c 65 72 20 61 6e 64 20 74 68 75   handler and thu
1ba00 73 20 63 6c 65 61 72 20 61 6e 79 20 70 72 65 76  s clear any prev
1ba10 69 6f 75 73 6c 79 20 73 65 74 20 62 75 73 79 20  iously set busy 
1ba20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 0a 2a 2a 20 54  handler..**.** T
1ba30 68 65 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b  he busy callback
1ba40 20 73 68 6f 75 6c 64 20 6e 6f 74 20 74 61 6b 65   should not take
1ba50 20 61 6e 79 20 61 63 74 69 6f 6e 73 20 77 68 69   any actions whi
1ba60 63 68 20 6d 6f 64 69 66 79 20 74 68 65 0a 2a 2a  ch modify the.**
1ba70 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
1ba80 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65  tion that invoke
1ba90 64 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c  d the busy handl
1baa0 65 72 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f  er.  In other wo
1bab0 72 64 73 2c 0a 2a 2a 20 74 68 65 20 62 75 73 79  rds,.** the busy
1bac0 20 68 61 6e 64 6c 65 72 20 69 73 20 6e 6f 74 20   handler is not 
1bad0 72 65 65 6e 74 72 61 6e 74 2e 20 20 41 6e 79 20  reentrant.  Any 
1bae0 73 75 63 68 20 61 63 74 69 6f 6e 73 0a 2a 2a 20  such actions.** 
1baf0 72 65 73 75 6c 74 20 69 6e 20 75 6e 64 65 66 69  result in undefi
1bb00 6e 65 64 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a  ned behavior..**
1bb10 20 0a 2a 2a 20 41 20 62 75 73 79 20 68 61 6e 64   .** A busy hand
1bb20 6c 65 72 20 6d 75 73 74 20 6e 6f 74 20 63 6c 6f  ler must not clo
1bb30 73 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20  se the database 
1bb40 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f 72  connection.** or
1bb50 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
1bb60 6d 65 6e 74 5d 20 74 68 61 74 20 69 6e 76 6f 6b  ment] that invok
1bb70 65 64 20 74 68 65 20 62 75 73 79 20 68 61 6e 64  ed the busy hand
1bb80 6c 65 72 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  ler..*/.SQLITE_A
1bb90 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  PI int sqlite3_b
1bba0 75 73 79 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69  usy_handler(sqli
1bbb0 74 65 33 2a 2c 69 6e 74 28 2a 29 28 76 6f 69 64  te3*,int(*)(void
1bbc0 2a 2c 69 6e 74 29 2c 76 6f 69 64 2a 29 3b 0a 0a  *,int),void*);..
1bbd0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1bbe0 53 65 74 20 41 20 42 75 73 79 20 54 69 6d 65 6f  Set A Busy Timeo
1bbf0 75 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  ut.** METHOD: sq
1bc00 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 69  lite3.**.** ^Thi
1bc10 73 20 72 6f 75 74 69 6e 65 20 73 65 74 73 20 61  s routine sets a
1bc20 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68   [sqlite3_busy_h
1bc30 61 6e 64 6c 65 72 20 7c 20 62 75 73 79 20 68 61  andler | busy ha
1bc40 6e 64 6c 65 72 5d 20 74 68 61 74 20 73 6c 65 65  ndler] that slee
1bc50 70 73 0a 2a 2a 20 66 6f 72 20 61 20 73 70 65 63  ps.** for a spec
1bc60 69 66 69 65 64 20 61 6d 6f 75 6e 74 20 6f 66 20  ified amount of 
1bc70 74 69 6d 65 20 77 68 65 6e 20 61 20 74 61 62 6c  time when a tabl
1bc80 65 20 69 73 20 6c 6f 63 6b 65 64 2e 20 20 5e 54  e is locked.  ^T
1bc90 68 65 20 68 61 6e 64 6c 65 72 0a 2a 2a 20 77 69  he handler.** wi
1bca0 6c 6c 20 73 6c 65 65 70 20 6d 75 6c 74 69 70 6c  ll sleep multipl
1bcb0 65 20 74 69 6d 65 73 20 75 6e 74 69 6c 20 61 74  e times until at
1bcc0 20 6c 65 61 73 74 20 22 6d 73 22 20 6d 69 6c 6c   least "ms" mill
1bcd0 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65  iseconds of slee
1bce0 70 69 6e 67 0a 2a 2a 20 68 61 76 65 20 61 63 63  ping.** have acc
1bcf0 75 6d 75 6c 61 74 65 64 2e 20 20 5e 41 66 74 65  umulated.  ^Afte
1bd00 72 20 61 74 20 6c 65 61 73 74 20 22 6d 73 22 20  r at least "ms" 
1bd10 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20  milliseconds of 
1bd20 73 6c 65 65 70 69 6e 67 2c 0a 2a 2a 20 74 68 65  sleeping,.** the
1bd30 20 68 61 6e 64 6c 65 72 20 72 65 74 75 72 6e 73   handler returns
1bd40 20 30 20 77 68 69 63 68 20 63 61 75 73 65 73 20   0 which causes 
1bd50 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
1bd60 20 74 6f 20 72 65 74 75 72 6e 0a 2a 2a 20 5b 53   to return.** [S
1bd70 51 4c 49 54 45 5f 42 55 53 59 5d 2e 0a 2a 2a 0a  QLITE_BUSY]..**.
1bd80 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 74 68 69 73  ** ^Calling this
1bd90 20 72 6f 75 74 69 6e 65 20 77 69 74 68 20 61 6e   routine with an
1bda0 20 61 72 67 75 6d 65 6e 74 20 6c 65 73 73 20 74   argument less t
1bdb0 68 61 6e 20 6f 72 20 65 71 75 61 6c 20 74 6f 20  han or equal to 
1bdc0 7a 65 72 6f 0a 2a 2a 20 74 75 72 6e 73 20 6f 66  zero.** turns of
1bdd0 66 20 61 6c 6c 20 62 75 73 79 20 68 61 6e 64 6c  f all busy handl
1bde0 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65  ers..**.** ^(The
1bdf0 72 65 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 61  re can only be a
1be00 20 73 69 6e 67 6c 65 20 62 75 73 79 20 68 61 6e   single busy han
1be10 64 6c 65 72 20 66 6f 72 20 61 20 70 61 72 74 69  dler for a parti
1be20 63 75 6c 61 72 0a 2a 2a 20 5b 64 61 74 61 62 61  cular.** [databa
1be30 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61  se connection] a
1be40 74 20 61 6e 79 20 67 69 76 65 6e 20 6d 6f 6d 65  t any given mome
1be50 6e 74 2e 20 20 49 66 20 61 6e 6f 74 68 65 72 20  nt.  If another 
1be60 62 75 73 79 20 68 61 6e 64 6c 65 72 0a 2a 2a 20  busy handler.** 
1be70 77 61 73 20 64 65 66 69 6e 65 64 20 20 28 75 73  was defined  (us
1be80 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 62 75 73  ing [sqlite3_bus
1be90 79 5f 68 61 6e 64 6c 65 72 28 29 5d 29 20 70 72  y_handler()]) pr
1bea0 69 6f 72 20 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a  ior to calling.*
1beb0 2a 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2c 20  * this routine, 
1bec0 74 68 61 74 20 6f 74 68 65 72 20 62 75 73 79 20  that other busy 
1bed0 68 61 6e 64 6c 65 72 20 69 73 20 63 6c 65 61 72  handler is clear
1bee0 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  ed.)^.**.** See 
1bef0 61 6c 73 6f 3a 20 20 5b 50 52 41 47 4d 41 20 62  also:  [PRAGMA b
1bf00 75 73 79 5f 74 69 6d 65 6f 75 74 5d 0a 2a 2f 0a  usy_timeout].*/.
1bf10 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
1bf20 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65  qlite3_busy_time
1bf30 6f 75 74 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e  out(sqlite3*, in
1bf40 74 20 6d 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  t ms);../*.** CA
1bf50 50 49 33 52 45 46 3a 20 43 6f 6e 76 65 6e 69 65  PI3REF: Convenie
1bf60 6e 63 65 20 52 6f 75 74 69 6e 65 73 20 46 6f 72  nce Routines For
1bf70 20 52 75 6e 6e 69 6e 67 20 51 75 65 72 69 65 73   Running Queries
1bf80 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
1bf90 74 65 33 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69  te3.**.** This i
1bfa0 73 20 61 20 6c 65 67 61 63 79 20 69 6e 74 65 72  s a legacy inter
1bfb0 66 61 63 65 20 74 68 61 74 20 69 73 20 70 72 65  face that is pre
1bfc0 73 65 72 76 65 64 20 66 6f 72 20 62 61 63 6b 77  served for backw
1bfd0 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69  ards compatibili
1bfe0 74 79 2e 0a 2a 2a 20 55 73 65 20 6f 66 20 74 68  ty..** Use of th
1bff0 69 73 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  is interface is 
1c000 6e 6f 74 20 72 65 63 6f 6d 6d 65 6e 64 65 64 2e  not recommended.
1c010 0a 2a 2a 0a 2a 2a 20 44 65 66 69 6e 69 74 69 6f  .**.** Definitio
1c020 6e 3a 20 41 20 3c 62 3e 72 65 73 75 6c 74 20 74  n: A <b>result t
1c030 61 62 6c 65 3c 2f 62 3e 20 69 73 20 6d 65 6d 6f  able</b> is memo
1c040 72 79 20 64 61 74 61 20 73 74 72 75 63 74 75 72  ry data structur
1c050 65 20 63 72 65 61 74 65 64 20 62 79 20 74 68 65  e created by the
1c060 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 67 65 74  .** [sqlite3_get
1c070 5f 74 61 62 6c 65 28 29 5d 20 69 6e 74 65 72 66  _table()] interf
1c080 61 63 65 2e 20 20 41 20 72 65 73 75 6c 74 20 74  ace.  A result t
1c090 61 62 6c 65 20 72 65 63 6f 72 64 73 20 74 68 65  able records the
1c0a0 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 20 71 75 65  .** complete que
1c0b0 72 79 20 72 65 73 75 6c 74 73 20 66 72 6f 6d 20  ry results from 
1c0c0 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 71 75 65 72  one or more quer
1c0d0 69 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74  ies..**.** The t
1c0e0 61 62 6c 65 20 63 6f 6e 63 65 70 74 75 61 6c 6c  able conceptuall
1c0f0 79 20 68 61 73 20 61 20 6e 75 6d 62 65 72 20 6f  y has a number o
1c100 66 20 72 6f 77 73 20 61 6e 64 20 63 6f 6c 75 6d  f rows and colum
1c110 6e 73 2e 20 20 42 75 74 0a 2a 2a 20 74 68 65 73  ns.  But.** thes
1c120 65 20 6e 75 6d 62 65 72 73 20 61 72 65 20 6e 6f  e numbers are no
1c130 74 20 70 61 72 74 20 6f 66 20 74 68 65 20 72 65  t part of the re
1c140 73 75 6c 74 20 74 61 62 6c 65 20 69 74 73 65 6c  sult table itsel
1c150 66 2e 20 20 54 68 65 73 65 0a 2a 2a 20 6e 75 6d  f.  These.** num
1c160 62 65 72 73 20 61 72 65 20 6f 62 74 61 69 6e 65  bers are obtaine
1c170 64 20 73 65 70 61 72 61 74 65 6c 79 2e 20 20 4c  d separately.  L
1c180 65 74 20 4e 20 62 65 20 74 68 65 20 6e 75 6d 62  et N be the numb
1c190 65 72 20 6f 66 20 72 6f 77 73 0a 2a 2a 20 61 6e  er of rows.** an
1c1a0 64 20 4d 20 62 65 20 74 68 65 20 6e 75 6d 62 65  d M be the numbe
1c1b0 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a  r of columns..**
1c1c0 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 61 62  .** A result tab
1c1d0 6c 65 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f  le is an array o
1c1e0 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 7a 65  f pointers to ze
1c1f0 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54  ro-terminated UT
1c200 46 2d 38 20 73 74 72 69 6e 67 73 2e 0a 2a 2a 20  F-8 strings..** 
1c210 54 68 65 72 65 20 61 72 65 20 28 4e 2b 31 29 2a  There are (N+1)*
1c220 4d 20 65 6c 65 6d 65 6e 74 73 20 69 6e 20 74 68  M elements in th
1c230 65 20 61 72 72 61 79 2e 20 20 54 68 65 20 66 69  e array.  The fi
1c240 72 73 74 20 4d 20 70 6f 69 6e 74 65 72 73 20 70  rst M pointers p
1c250 6f 69 6e 74 0a 2a 2a 20 74 6f 20 7a 65 72 6f 2d  oint.** to zero-
1c260 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72 69 6e  terminated strin
1c270 67 73 20 74 68 61 74 20 20 63 6f 6e 74 61 69 6e  gs that  contain
1c280 20 74 68 65 20 6e 61 6d 65 73 20 6f 66 20 74 68   the names of th
1c290 65 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 20 54 68  e columns..** Th
1c2a0 65 20 72 65 6d 61 69 6e 69 6e 67 20 65 6e 74 72  e remaining entr
1c2b0 69 65 73 20 61 6c 6c 20 70 6f 69 6e 74 20 74 6f  ies all point to
1c2c0 20 71 75 65 72 79 20 72 65 73 75 6c 74 73 2e 20   query results. 
1c2d0 20 4e 55 4c 4c 20 76 61 6c 75 65 73 20 72 65 73   NULL values res
1c2e0 75 6c 74 0a 2a 2a 20 69 6e 20 4e 55 4c 4c 20 70  ult.** in NULL p
1c2f0 6f 69 6e 74 65 72 73 2e 20 20 41 6c 6c 20 6f 74  ointers.  All ot
1c300 68 65 72 20 76 61 6c 75 65 73 20 61 72 65 20 69  her values are i
1c310 6e 20 74 68 65 69 72 20 55 54 46 2d 38 20 7a 65  n their UTF-8 ze
1c320 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a  ro-terminated.**
1c330 20 73 74 72 69 6e 67 20 72 65 70 72 65 73 65 6e   string represen
1c340 74 61 74 69 6f 6e 20 61 73 20 72 65 74 75 72 6e  tation as return
1c350 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63  ed by [sqlite3_c
1c360 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2e 0a 2a  olumn_text()]..*
1c370 2a 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 61  *.** A result ta
1c380 62 6c 65 20 6d 69 67 68 74 20 63 6f 6e 73 69 73  ble might consis
1c390 74 20 6f 66 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  t of one or more
1c3a0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
1c3b0 6f 6e 73 2e 0a 2a 2a 20 49 74 20 69 73 20 6e 6f  ons..** It is no
1c3c0 74 20 73 61 66 65 20 74 6f 20 70 61 73 73 20 61  t safe to pass a
1c3d0 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 64 69   result table di
1c3e0 72 65 63 74 6c 79 20 74 6f 20 5b 73 71 6c 69 74  rectly to [sqlit
1c3f0 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 20 41  e3_free()]..** A
1c400 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 73 68   result table sh
1c410 6f 75 6c 64 20 62 65 20 64 65 61 6c 6c 6f 63 61  ould be dealloca
1c420 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ted using [sqlit
1c430 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 5d  e3_free_table()]
1c440 2e 0a 2a 2a 0a 2a 2a 20 5e 28 41 73 20 61 6e 20  ..**.** ^(As an 
1c450 65 78 61 6d 70 6c 65 20 6f 66 20 74 68 65 20 72  example of the r
1c460 65 73 75 6c 74 20 74 61 62 6c 65 20 66 6f 72 6d  esult table form
1c470 61 74 2c 20 73 75 70 70 6f 73 65 20 61 20 71 75  at, suppose a qu
1c480 65 72 79 20 72 65 73 75 6c 74 0a 2a 2a 20 69 73  ery result.** is
1c490 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a   as follows:.**.
1c4a0 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c  ** <blockquote><
1c4b0 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20 20 20 4e  pre>.**        N
1c4c0 61 6d 65 20 20 20 20 20 20 20 20 7c 20 41 67 65  ame        | Age
1c4d0 0a 2a 2a 20 20 20 20 20 20 20 20 2d 2d 2d 2d 2d  .**        -----
1c4e0 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
1c4f0 2d 2d 0a 2a 2a 20 20 20 20 20 20 20 20 41 6c 69  --.**        Ali
1c500 63 65 20 20 20 20 20 20 20 7c 20 34 33 0a 2a 2a  ce       | 43.**
1c510 20 20 20 20 20 20 20 20 42 6f 62 20 20 20 20 20          Bob     
1c520 20 20 20 20 7c 20 32 38 0a 2a 2a 20 20 20 20 20      | 28.**     
1c530 20 20 20 43 69 6e 64 79 20 20 20 20 20 20 20 7c     Cindy       |
1c540 20 32 31 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62   21.** </pre></b
1c550 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a  lockquote>.**.**
1c560 20 54 68 65 72 65 20 61 72 65 20 74 77 6f 20 63   There are two c
1c570 6f 6c 75 6d 6e 20 28 4d 3d 3d 32 29 20 61 6e 64  olumn (M==2) and
1c580 20 74 68 72 65 65 20 72 6f 77 73 20 28 4e 3d 3d   three rows (N==
1c590 33 29 2e 20 20 54 68 75 73 20 74 68 65 0a 2a 2a  3).  Thus the.**
1c5a0 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 68 61   result table ha
1c5b0 73 20 38 20 65 6e 74 72 69 65 73 2e 20 20 53 75  s 8 entries.  Su
1c5c0 70 70 6f 73 65 20 74 68 65 20 72 65 73 75 6c 74  ppose the result
1c5d0 20 74 61 62 6c 65 20 69 73 20 73 74 6f 72 65 64   table is stored
1c5e0 0a 2a 2a 20 69 6e 20 61 6e 20 61 72 72 61 79 20  .** in an array 
1c5f0 6e 61 6d 65 73 20 61 7a 52 65 73 75 6c 74 2e 20  names azResult. 
1c600 20 54 68 65 6e 20 61 7a 52 65 73 75 6c 74 20 68   Then azResult h
1c610 6f 6c 64 73 20 74 68 69 73 20 63 6f 6e 74 65 6e  olds this conten
1c620 74 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71  t:.**.** <blockq
1c630 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20  uote><pre>.**   
1c640 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39       azResult&#9
1c650 31 3b 30 5d 20 3d 20 22 4e 61 6d 65 22 3b 0a 2a  1;0] = "Name";.*
1c660 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c  *        azResul
1c670 74 26 23 39 31 3b 31 5d 20 3d 20 22 41 67 65 22  t&#91;1] = "Age"
1c680 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65  ;.**        azRe
1c690 73 75 6c 74 26 23 39 31 3b 32 5d 20 3d 20 22 41  sult&#91;2] = "A
1c6a0 6c 69 63 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20  lice";.**       
1c6b0 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 33 5d   azResult&#91;3]
1c6c0 20 3d 20 22 34 33 22 3b 0a 2a 2a 20 20 20 20 20   = "43";.**     
1c6d0 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b     azResult&#91;
1c6e0 34 5d 20 3d 20 22 42 6f 62 22 3b 0a 2a 2a 20 20  4] = "Bob";.**  
1c6f0 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23        azResult&#
1c700 39 31 3b 35 5d 20 3d 20 22 32 38 22 3b 0a 2a 2a  91;5] = "28";.**
1c710 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74          azResult
1c720 26 23 39 31 3b 36 5d 20 3d 20 22 43 69 6e 64 79  &#91;6] = "Cindy
1c730 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52  ";.**        azR
1c740 65 73 75 6c 74 26 23 39 31 3b 37 5d 20 3d 20 22  esult&#91;7] = "
1c750 32 31 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f  21";.** </pre></
1c760 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a  blockquote>)^.**
1c770 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
1c780 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 66 75 6e  _get_table() fun
1c790 63 74 69 6f 6e 20 65 76 61 6c 75 61 74 65 73 20  ction evaluates 
1c7a0 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 73  one or more.** s
1c7b0 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61 72 61 74  emicolon-separat
1c7c0 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ed SQL statement
1c7d0 73 20 69 6e 20 74 68 65 20 7a 65 72 6f 2d 74 65  s in the zero-te
1c7e0 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 0a 2a  rminated UTF-8.*
1c7f0 2a 20 73 74 72 69 6e 67 20 6f 66 20 69 74 73 20  * string of its 
1c800 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61 6e  2nd parameter an
1c810 64 20 72 65 74 75 72 6e 73 20 61 20 72 65 73 75  d returns a resu
1c820 6c 74 20 74 61 62 6c 65 20 74 6f 20 74 68 65 0a  lt table to the.
1c830 2a 2a 20 70 6f 69 6e 74 65 72 20 67 69 76 65 6e  ** pointer given
1c840 20 69 6e 20 69 74 73 20 33 72 64 20 70 61 72 61   in its 3rd para
1c850 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 41 66 74  meter..**.** Aft
1c860 65 72 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  er the applicati
1c870 6f 6e 20 68 61 73 20 66 69 6e 69 73 68 65 64 20  on has finished 
1c880 77 69 74 68 20 74 68 65 20 72 65 73 75 6c 74 20  with the result 
1c890 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 67 65 74  from sqlite3_get
1c8a0 5f 74 61 62 6c 65 28 29 2c 0a 2a 2a 20 69 74 20  _table(),.** it 
1c8b0 6d 75 73 74 20 70 61 73 73 20 74 68 65 20 72 65  must pass the re
1c8c0 73 75 6c 74 20 74 61 62 6c 65 20 70 6f 69 6e 74  sult table point
1c8d0 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 66 72  er to sqlite3_fr
1c8e0 65 65 5f 74 61 62 6c 65 28 29 20 69 6e 20 6f 72  ee_table() in or
1c8f0 64 65 72 20 74 6f 0a 2a 2a 20 72 65 6c 65 61 73  der to.** releas
1c900 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 74 68 61  e the memory tha
1c910 74 20 77 61 73 20 6d 61 6c 6c 6f 63 65 64 2e 20  t was malloced. 
1c920 20 42 65 63 61 75 73 65 20 6f 66 20 74 68 65 20   Because of the 
1c930 77 61 79 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69  way the.** [sqli
1c940 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 68 61  te3_malloc()] ha
1c950 70 70 65 6e 73 20 77 69 74 68 69 6e 20 73 71 6c  ppens within sql
1c960 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29  ite3_get_table()
1c970 2c 20 74 68 65 20 63 61 6c 6c 69 6e 67 0a 2a 2a  , the calling.**
1c980 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 6e   function must n
1c990 6f 74 20 74 72 79 20 74 6f 20 63 61 6c 6c 20 5b  ot try to call [
1c9a0 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20  sqlite3_free()] 
1c9b0 64 69 72 65 63 74 6c 79 2e 20 20 4f 6e 6c 79 0a  directly.  Only.
1c9c0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  ** [sqlite3_free
1c9d0 5f 74 61 62 6c 65 28 29 5d 20 69 73 20 61 62 6c  _table()] is abl
1c9e0 65 20 74 6f 20 72 65 6c 65 61 73 65 20 74 68 65  e to release the
1c9f0 20 6d 65 6d 6f 72 79 20 70 72 6f 70 65 72 6c 79   memory properly
1ca00 20 61 6e 64 20 73 61 66 65 6c 79 2e 0a 2a 2a 0a   and safely..**.
1ca10 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 67  ** The sqlite3_g
1ca20 65 74 5f 74 61 62 6c 65 28 29 20 69 6e 74 65 72  et_table() inter
1ca30 66 61 63 65 20 69 73 20 69 6d 70 6c 65 6d 65 6e  face is implemen
1ca40 74 65 64 20 61 73 20 61 20 77 72 61 70 70 65 72  ted as a wrapper
1ca50 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b 73 71 6c 69   around.** [sqli
1ca60 74 65 33 5f 65 78 65 63 28 29 5d 2e 20 20 54 68  te3_exec()].  Th
1ca70 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61  e sqlite3_get_ta
1ca80 62 6c 65 28 29 20 72 6f 75 74 69 6e 65 20 64 6f  ble() routine do
1ca90 65 73 20 6e 6f 74 20 68 61 76 65 20 61 63 63 65  es not have acce
1caa0 73 73 0a 2a 2a 20 74 6f 20 61 6e 79 20 69 6e 74  ss.** to any int
1cab0 65 72 6e 61 6c 20 64 61 74 61 20 73 74 72 75 63  ernal data struc
1cac0 74 75 72 65 73 20 6f 66 20 53 51 4c 69 74 65 2e  tures of SQLite.
1cad0 20 20 49 74 20 75 73 65 73 20 6f 6e 6c 79 20 74    It uses only t
1cae0 68 65 20 70 75 62 6c 69 63 0a 2a 2a 20 69 6e 74  he public.** int
1caf0 65 72 66 61 63 65 20 64 65 66 69 6e 65 64 20 68  erface defined h
1cb00 65 72 65 2e 20 20 41 73 20 61 20 63 6f 6e 73 65  ere.  As a conse
1cb10 71 75 65 6e 63 65 2c 20 65 72 72 6f 72 73 20 74  quence, errors t
1cb20 68 61 74 20 6f 63 63 75 72 20 69 6e 20 74 68 65  hat occur in the
1cb30 0a 2a 2a 20 77 72 61 70 70 65 72 20 6c 61 79 65  .** wrapper laye
1cb40 72 20 6f 75 74 73 69 64 65 20 6f 66 20 74 68 65  r outside of the
1cb50 20 69 6e 74 65 72 6e 61 6c 20 5b 73 71 6c 69 74   internal [sqlit
1cb60 65 33 5f 65 78 65 63 28 29 5d 20 63 61 6c 6c 20  e3_exec()] call 
1cb70 61 72 65 20 6e 6f 74 0a 2a 2a 20 72 65 66 6c 65  are not.** refle
1cb80 63 74 65 64 20 69 6e 20 73 75 62 73 65 71 75 65  cted in subseque
1cb90 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c  nt calls to [sql
1cba0 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d 20  ite3_errcode()] 
1cbb0 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65  or.** [sqlite3_e
1cbc0 72 72 6d 73 67 28 29 5d 2e 0a 2a 2f 0a 53 51 4c  rrmsg()]..*/.SQL
1cbd0 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
1cbe0 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 0a 20  te3_get_table(. 
1cbf0 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20   sqlite3 *db,   
1cc00 20 20 20 20 20 20 20 2f 2a 20 41 6e 20 6f 70 65         /* An ope
1cc10 6e 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 20 20  n database */.  
1cc20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c  const char *zSql
1cc30 2c 20 20 20 20 20 2f 2a 20 53 51 4c 20 74 6f 20  ,     /* SQL to 
1cc40 62 65 20 65 76 61 6c 75 61 74 65 64 20 2a 2f 0a  be evaluated */.
1cc50 20 20 63 68 61 72 20 2a 2a 2a 70 61 7a 52 65 73    char ***pazRes
1cc60 75 6c 74 2c 20 20 20 20 2f 2a 20 52 65 73 75 6c  ult,    /* Resul
1cc70 74 73 20 6f 66 20 74 68 65 20 71 75 65 72 79 20  ts of the query 
1cc80 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e 52 6f 77 2c  */.  int *pnRow,
1cc90 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 75             /* Nu
1cca0 6d 62 65 72 20 6f 66 20 72 65 73 75 6c 74 20 72  mber of result r
1ccb0 6f 77 73 20 77 72 69 74 74 65 6e 20 68 65 72 65  ows written here
1ccc0 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e 43 6f 6c   */.  int *pnCol
1ccd0 75 6d 6e 2c 20 20 20 20 20 20 20 20 2f 2a 20 4e  umn,        /* N
1cce0 75 6d 62 65 72 20 6f 66 20 72 65 73 75 6c 74 20  umber of result 
1ccf0 63 6f 6c 75 6d 6e 73 20 77 72 69 74 74 65 6e 20  columns written 
1cd00 68 65 72 65 20 2a 2f 0a 20 20 63 68 61 72 20 2a  here */.  char *
1cd10 2a 70 7a 45 72 72 6d 73 67 20 20 20 20 20 20 20  *pzErrmsg       
1cd20 2f 2a 20 45 72 72 6f 72 20 6d 73 67 20 77 72 69  /* Error msg wri
1cd30 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a  tten here */.);.
1cd40 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20  SQLITE_API void 
1cd50 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62  sqlite3_free_tab
1cd60 6c 65 28 63 68 61 72 20 2a 2a 72 65 73 75 6c 74  le(char **result
1cd70 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
1cd80 45 46 3a 20 46 6f 72 6d 61 74 74 65 64 20 53 74  EF: Formatted St
1cd90 72 69 6e 67 20 50 72 69 6e 74 69 6e 67 20 46 75  ring Printing Fu
1cda0 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68  nctions.**.** Th
1cdb0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65  ese routines are
1cdc0 20 77 6f 72 6b 2d 61 6c 69 6b 65 73 20 6f 66 20   work-alikes of 
1cdd0 74 68 65 20 22 70 72 69 6e 74 66 28 29 22 20 66  the "printf()" f
1cde0 61 6d 69 6c 79 20 6f 66 20 66 75 6e 63 74 69 6f  amily of functio
1cdf0 6e 73 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20 73  ns.** from the s
1ce00 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72  tandard C librar
1ce10 79 2e 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  y..** These rout
1ce20 69 6e 65 73 20 75 6e 64 65 72 73 74 61 6e 64 20  ines understand 
1ce30 6d 6f 73 74 20 6f 66 20 74 68 65 20 63 6f 6d 6d  most of the comm
1ce40 6f 6e 20 4b 26 52 20 66 6f 72 6d 61 74 74 69 6e  on K&R formattin
1ce50 67 20 6f 70 74 69 6f 6e 73 2c 0a 2a 2a 20 70 6c  g options,.** pl
1ce60 75 73 20 73 6f 6d 65 20 61 64 64 69 74 69 6f 6e  us some addition
1ce70 61 6c 20 6e 6f 6e 2d 73 74 61 6e 64 61 72 64 20  al non-standard 
1ce80 66 6f 72 6d 61 74 73 2c 20 64 65 74 61 69 6c 65  formats, detaile
1ce90 64 20 62 65 6c 6f 77 2e 0a 2a 2a 20 4e 6f 74 65  d below..** Note
1cea0 20 74 68 61 74 20 73 6f 6d 65 20 6f 66 20 74 68   that some of th
1ceb0 65 20 6d 6f 72 65 20 6f 62 73 63 75 72 65 20 66  e more obscure f
1cec0 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e  ormatting option
1ced0 73 20 66 72 6f 6d 20 72 65 63 65 6e 74 0a 2a 2a  s from recent.**
1cee0 20 43 2d 6c 69 62 72 61 72 79 20 73 74 61 6e 64   C-library stand
1cef0 61 72 64 73 20 61 72 65 20 6f 6d 69 74 74 65 64  ards are omitted
1cf00 20 66 72 6f 6d 20 74 68 69 73 20 69 6d 70 6c 65   from this imple
1cf10 6d 65 6e 74 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  mentation..**.**
1cf20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 70   ^The sqlite3_mp
1cf30 72 69 6e 74 66 28 29 20 61 6e 64 20 73 71 6c 69  rintf() and sqli
1cf40 74 65 33 5f 76 6d 70 72 69 6e 74 66 28 29 20 72  te3_vmprintf() r
1cf50 6f 75 74 69 6e 65 73 20 77 72 69 74 65 20 74 68  outines write th
1cf60 65 69 72 0a 2a 2a 20 72 65 73 75 6c 74 73 20 69  eir.** results i
1cf70 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69  nto memory obtai
1cf80 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  ned from [sqlite
1cf90 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2a 20  3_malloc()]..** 
1cfa0 54 68 65 20 73 74 72 69 6e 67 73 20 72 65 74 75  The strings retu
1cfb0 72 6e 65 64 20 62 79 20 74 68 65 73 65 20 74 77  rned by these tw
1cfc0 6f 20 72 6f 75 74 69 6e 65 73 20 73 68 6f 75 6c  o routines shoul
1cfd0 64 20 62 65 0a 2a 2a 20 72 65 6c 65 61 73 65 64  d be.** released
1cfe0 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 66 72 65   by [sqlite3_fre
1cff0 65 28 29 5d 2e 20 20 5e 42 6f 74 68 20 72 6f 75  e()].  ^Both rou
1d000 74 69 6e 65 73 20 72 65 74 75 72 6e 20 61 0a 2a  tines return a.*
1d010 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69  * NULL pointer i
1d020 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  f [sqlite3_mallo
1d030 63 28 29 5d 20 69 73 20 75 6e 61 62 6c 65 20 74  c()] is unable t
1d040 6f 20 61 6c 6c 6f 63 61 74 65 20 65 6e 6f 75 67  o allocate enoug
1d050 68 0a 2a 2a 20 6d 65 6d 6f 72 79 20 74 6f 20 68  h.** memory to h
1d060 6f 6c 64 20 74 68 65 20 72 65 73 75 6c 74 69 6e  old the resultin
1d070 67 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20  g string..**.** 
1d080 5e 28 54 68 65 20 73 71 6c 69 74 65 33 5f 73 6e  ^(The sqlite3_sn
1d090 70 72 69 6e 74 66 28 29 20 72 6f 75 74 69 6e 65  printf() routine
1d0a0 20 69 73 20 73 69 6d 69 6c 61 72 20 74 6f 20 22   is similar to "
1d0b0 73 6e 70 72 69 6e 74 66 28 29 22 20 66 72 6f 6d  snprintf()" from
1d0c0 0a 2a 2a 20 74 68 65 20 73 74 61 6e 64 61 72 64  .** the standard
1d0d0 20 43 20 6c 69 62 72 61 72 79 2e 20 20 54 68 65   C library.  The
1d0e0 20 72 65 73 75 6c 74 20 69 73 20 77 72 69 74 74   result is writt
1d0f0 65 6e 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 62  en into the.** b
1d100 75 66 66 65 72 20 73 75 70 70 6c 69 65 64 20 61  uffer supplied a
1d110 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72  s the second par
1d120 61 6d 65 74 65 72 20 77 68 6f 73 65 20 73 69 7a  ameter whose siz
1d130 65 20 69 73 20 67 69 76 65 6e 20 62 79 0a 2a 2a  e is given by.**
1d140 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d   the first param
1d150 65 74 65 72 2e 20 4e 6f 74 65 20 74 68 61 74 20  eter. Note that 
1d160 74 68 65 20 6f 72 64 65 72 20 6f 66 20 74 68 65  the order of the
1d170 0a 2a 2a 20 66 69 72 73 74 20 74 77 6f 20 70 61  .** first two pa
1d180 72 61 6d 65 74 65 72 73 20 69 73 20 72 65 76 65  rameters is reve
1d190 72 73 65 64 20 66 72 6f 6d 20 73 6e 70 72 69 6e  rsed from snprin
1d1a0 74 66 28 29 2e 29 5e 20 20 54 68 69 73 20 69 73  tf().)^  This is
1d1b0 20 61 6e 0a 2a 2a 20 68 69 73 74 6f 72 69 63 61   an.** historica
1d1c0 6c 20 61 63 63 69 64 65 6e 74 20 74 68 61 74 20  l accident that 
1d1d0 63 61 6e 6e 6f 74 20 62 65 20 66 69 78 65 64 20  cannot be fixed 
1d1e0 77 69 74 68 6f 75 74 20 62 72 65 61 6b 69 6e 67  without breaking
1d1f0 0a 2a 2a 20 62 61 63 6b 77 61 72 64 73 20 63 6f  .** backwards co
1d200 6d 70 61 74 69 62 69 6c 69 74 79 2e 20 20 5e 28  mpatibility.  ^(
1d210 4e 6f 74 65 20 61 6c 73 6f 20 74 68 61 74 20 73  Note also that s
1d220 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28  qlite3_snprintf(
1d230 29 0a 2a 2a 20 72 65 74 75 72 6e 73 20 61 20 70  ).** returns a p
1d240 6f 69 6e 74 65 72 20 74 6f 20 69 74 73 20 62 75  ointer to its bu
1d250 66 66 65 72 20 69 6e 73 74 65 61 64 20 6f 66 20  ffer instead of 
1d260 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a  the number of.**
1d270 20 63 68 61 72 61 63 74 65 72 73 20 61 63 74 75   characters actu
1d280 61 6c 6c 79 20 77 72 69 74 74 65 6e 20 69 6e 74  ally written int
1d290 6f 20 74 68 65 20 62 75 66 66 65 72 2e 29 5e 20  o the buffer.)^ 
1d2a0 20 57 65 20 61 64 6d 69 74 20 74 68 61 74 0a 2a   We admit that.*
1d2b0 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  * the number of 
1d2c0 63 68 61 72 61 63 74 65 72 73 20 77 72 69 74 74  characters writt
1d2d0 65 6e 20 77 6f 75 6c 64 20 62 65 20 61 20 6d 6f  en would be a mo
1d2e0 72 65 20 75 73 65 66 75 6c 20 72 65 74 75 72 6e  re useful return
1d2f0 0a 2a 2a 20 76 61 6c 75 65 20 62 75 74 20 77 65  .** value but we
1d300 20 63 61 6e 6e 6f 74 20 63 68 61 6e 67 65 20 74   cannot change t
1d310 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
1d320 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f 73 6e 70  n of sqlite3_snp
1d330 72 69 6e 74 66 28 29 0a 2a 2a 20 6e 6f 77 20 77  rintf().** now w
1d340 69 74 68 6f 75 74 20 62 72 65 61 6b 69 6e 67 20  ithout breaking 
1d350 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a  compatibility..*
1d360 2a 0a 2a 2a 20 5e 41 73 20 6c 6f 6e 67 20 61 73  *.** ^As long as
1d370 20 74 68 65 20 62 75 66 66 65 72 20 73 69 7a 65   the buffer size
1d380 20 69 73 20 67 72 65 61 74 65 72 20 74 68 61 6e   is greater than
1d390 20 7a 65 72 6f 2c 20 73 71 6c 69 74 65 33 5f 73   zero, sqlite3_s
1d3a0 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 67 75 61  nprintf().** gua
1d3b0 72 61 6e 74 65 65 73 20 74 68 61 74 20 74 68 65  rantees that the
1d3c0 20 62 75 66 66 65 72 20 69 73 20 61 6c 77 61 79   buffer is alway
1d3d0 73 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  s zero-terminate
1d3e0 64 2e 20 20 5e 54 68 65 20 66 69 72 73 74 0a 2a  d.  ^The first.*
1d3f0 2a 20 70 61 72 61 6d 65 74 65 72 20 22 6e 22 20  * parameter "n" 
1d400 69 73 20 74 68 65 20 74 6f 74 61 6c 20 73 69 7a  is the total siz
1d410 65 20 6f 66 20 74 68 65 20 62 75 66 66 65 72 2c  e of the buffer,
1d420 20 69 6e 63 6c 75 64 69 6e 67 20 73 70 61 63 65   including space
1d430 20 66 6f 72 0a 2a 2a 20 74 68 65 20 7a 65 72 6f   for.** the zero
1d440 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20 53 6f   terminator.  So
1d450 20 74 68 65 20 6c 6f 6e 67 65 73 74 20 73 74 72   the longest str
1d460 69 6e 67 20 74 68 61 74 20 63 61 6e 20 62 65 20  ing that can be 
1d470 63 6f 6d 70 6c 65 74 65 6c 79 0a 2a 2a 20 77 72  completely.** wr
1d480 69 74 74 65 6e 20 77 69 6c 6c 20 62 65 20 6e 2d  itten will be n-
1d490 31 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a  1 characters..**
1d4a0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
1d4b0 5f 76 73 6e 70 72 69 6e 74 66 28 29 20 72 6f 75  _vsnprintf() rou
1d4c0 74 69 6e 65 20 69 73 20 61 20 76 61 72 61 72 67  tine is a vararg
1d4d0 73 20 76 65 72 73 69 6f 6e 20 6f 66 20 73 71 6c  s version of sql
1d4e0 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 2e  ite3_snprintf().
1d4f0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
1d500 74 69 6e 65 73 20 61 6c 6c 20 69 6d 70 6c 65 6d  tines all implem
1d510 65 6e 74 20 73 6f 6d 65 20 61 64 64 69 74 69 6f  ent some additio
1d520 6e 61 6c 20 66 6f 72 6d 61 74 74 69 6e 67 0a 2a  nal formatting.*
1d530 2a 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 20 61  * options that a
1d540 72 65 20 75 73 65 66 75 6c 20 66 6f 72 20 63 6f  re useful for co
1d550 6e 73 74 72 75 63 74 69 6e 67 20 53 51 4c 20 73  nstructing SQL s
1d560 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20 41 6c  tatements..** Al
1d570 6c 20 6f 66 20 74 68 65 20 75 73 75 61 6c 20 70  l of the usual p
1d580 72 69 6e 74 66 28 29 20 66 6f 72 6d 61 74 74 69  rintf() formatti
1d590 6e 67 20 6f 70 74 69 6f 6e 73 20 61 70 70 6c 79  ng options apply
1d5a0 2e 20 20 49 6e 20 61 64 64 69 74 69 6f 6e 2c 20  .  In addition, 
1d5b0 74 68 65 72 65 0a 2a 2a 20 69 73 20 61 72 65 20  there.** is are 
1d5c0 22 25 71 22 2c 20 22 25 51 22 2c 20 22 25 77 22  "%q", "%Q", "%w"
1d5d0 20 61 6e 64 20 22 25 7a 22 20 6f 70 74 69 6f 6e   and "%z" option
1d5e0 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 25  s..**.** ^(The %
1d5f0 71 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c  q option works l
1d600 69 6b 65 20 25 73 20 69 6e 20 74 68 61 74 20 69  ike %s in that i
1d610 74 20 73 75 62 73 74 69 74 75 74 65 73 20 61 20  t substitutes a 
1d620 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a  nul-terminated.*
1d630 2a 20 73 74 72 69 6e 67 20 66 72 6f 6d 20 74 68  * string from th
1d640 65 20 61 72 67 75 6d 65 6e 74 20 6c 69 73 74 2e  e argument list.
1d650 20 20 42 75 74 20 25 71 20 61 6c 73 6f 20 64 6f    But %q also do
1d660 75 62 6c 65 73 20 65 76 65 72 79 20 27 5c 27 27  ubles every '\''
1d670 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 25   character..** %
1d680 71 20 69 73 20 64 65 73 69 67 6e 65 64 20 66 6f  q is designed fo
1d690 72 20 75 73 65 20 69 6e 73 69 64 65 20 61 20 73  r use inside a s
1d6a0 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 2e 29 5e  tring literal.)^
1d6b0 20 20 42 79 20 64 6f 75 62 6c 69 6e 67 20 65 61    By doubling ea
1d6c0 63 68 20 27 5c 27 27 0a 2a 2a 20 63 68 61 72 61  ch '\''.** chara
1d6d0 63 74 65 72 20 69 74 20 65 73 63 61 70 65 73 20  cter it escapes 
1d6e0 74 68 61 74 20 63 68 61 72 61 63 74 65 72 20 61  that character a
1d6f0 6e 64 20 61 6c 6c 6f 77 73 20 69 74 20 74 6f 20  nd allows it to 
1d700 62 65 20 69 6e 73 65 72 74 65 64 20 69 6e 74 6f  be inserted into
1d710 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 2e 0a  .** the string..
1d720 2a 2a 0a 2a 2a 20 46 6f 72 20 65 78 61 6d 70 6c  **.** For exampl
1d730 65 2c 20 61 73 73 75 6d 65 20 74 68 65 20 73 74  e, assume the st
1d740 72 69 6e 67 20 76 61 72 69 61 62 6c 65 20 7a 54  ring variable zT
1d750 65 78 74 20 63 6f 6e 74 61 69 6e 73 20 74 65 78  ext contains tex
1d760 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a  t as follows:.**
1d770 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
1d780 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a  <pre>.**  char *
1d790 7a 54 65 78 74 20 3d 20 22 49 74 27 73 20 61 20  zText = "It's a 
1d7a0 68 61 70 70 79 20 64 61 79 21 22 3b 0a 2a 2a 20  happy day!";.** 
1d7b0 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f  </pre></blockquo
1d7c0 74 65 3e 0a 2a 2a 0a 2a 2a 20 4f 6e 65 20 63 61  te>.**.** One ca
1d7d0 6e 20 75 73 65 20 74 68 69 73 20 74 65 78 74 20  n use this text 
1d7e0 69 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d  in an SQL statem
1d7f0 65 6e 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a  ent as follows:.
1d800 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74  **.** <blockquot
1d810 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72  e><pre>.**  char
1d820 20 2a 7a 53 51 4c 20 3d 20 73 71 6c 69 74 65 33   *zSQL = sqlite3
1d830 5f 6d 70 72 69 6e 74 66 28 22 49 4e 53 45 52 54  _mprintf("INSERT
1d840 20 49 4e 54 4f 20 74 61 62 6c 65 20 56 41 4c 55   INTO table VALU
1d850 45 53 28 27 25 71 27 29 22 2c 20 7a 54 65 78 74  ES('%q')", zText
1d860 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 65  );.**  sqlite3_e
1d870 78 65 63 28 64 62 2c 20 7a 53 51 4c 2c 20 30 2c  xec(db, zSQL, 0,
1d880 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 71 6c 69   0, 0);.**  sqli
1d890 74 65 33 5f 66 72 65 65 28 7a 53 51 4c 29 3b 0a  te3_free(zSQL);.
1d8a0 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b  ** </pre></block
1d8b0 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 42 65 63  quote>.**.** Bec
1d8c0 61 75 73 65 20 74 68 65 20 25 71 20 66 6f 72 6d  ause the %q form
1d8d0 61 74 20 73 74 72 69 6e 67 20 69 73 20 75 73 65  at string is use
1d8e0 64 2c 20 74 68 65 20 27 5c 27 27 20 63 68 61 72  d, the '\'' char
1d8f0 61 63 74 65 72 20 69 6e 20 7a 54 65 78 74 0a 2a  acter in zText.*
1d900 2a 20 69 73 20 65 73 63 61 70 65 64 20 61 6e 64  * is escaped and
1d910 20 74 68 65 20 53 51 4c 20 67 65 6e 65 72 61 74   the SQL generat
1d920 65 64 20 69 73 20 61 73 20 66 6f 6c 6c 6f 77 73  ed is as follows
1d930 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  :.**.** <blockqu
1d940 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e  ote><pre>.**  IN
1d950 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 31  SERT INTO table1
1d960 20 56 41 4c 55 45 53 28 27 49 74 27 27 73 20 61   VALUES('It''s a
1d970 20 68 61 70 70 79 20 64 61 79 21 27 29 0a 2a 2a   happy day!').**
1d980 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75   </pre></blockqu
1d990 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  ote>.**.** This 
1d9a0 69 73 20 63 6f 72 72 65 63 74 2e 20 20 48 61 64  is correct.  Had
1d9b0 20 77 65 20 75 73 65 64 20 25 73 20 69 6e 73 74   we used %s inst
1d9c0 65 61 64 20 6f 66 20 25 71 2c 20 74 68 65 20 67  ead of %q, the g
1d9d0 65 6e 65 72 61 74 65 64 20 53 51 4c 0a 2a 2a 20  enerated SQL.** 
1d9e0 77 6f 75 6c 64 20 68 61 76 65 20 6c 6f 6f 6b 65  would have looke
1d9f0 64 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a  d like this:.**.
1da00 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c  ** <blockquote><
1da10 70 72 65 3e 0a 2a 2a 20 20 49 4e 53 45 52 54 20  pre>.**  INSERT 
1da20 49 4e 54 4f 20 74 61 62 6c 65 31 20 56 41 4c 55  INTO table1 VALU
1da30 45 53 28 27 49 74 27 73 20 61 20 68 61 70 70 79  ES('It's a happy
1da40 20 64 61 79 21 27 29 3b 0a 2a 2a 20 3c 2f 70 72   day!');.** </pr
1da50 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a  e></blockquote>.
1da60 2a 2a 0a 2a 2a 20 54 68 69 73 20 73 65 63 6f 6e  **.** This secon
1da70 64 20 65 78 61 6d 70 6c 65 20 69 73 20 61 6e 20  d example is an 
1da80 53 51 4c 20 73 79 6e 74 61 78 20 65 72 72 6f 72  SQL syntax error
1da90 2e 20 20 41 73 20 61 20 67 65 6e 65 72 61 6c 20  .  As a general 
1daa0 72 75 6c 65 20 79 6f 75 20 73 68 6f 75 6c 64 0a  rule you should.
1dab0 2a 2a 20 61 6c 77 61 79 73 20 75 73 65 20 25 71  ** always use %q
1dac0 20 69 6e 73 74 65 61 64 20 6f 66 20 25 73 20 77   instead of %s w
1dad0 68 65 6e 20 69 6e 73 65 72 74 69 6e 67 20 74 65  hen inserting te
1dae0 78 74 20 69 6e 74 6f 20 61 20 73 74 72 69 6e 67  xt into a string
1daf0 20 6c 69 74 65 72 61 6c 2e 0a 2a 2a 0a 2a 2a 20   literal..**.** 
1db00 5e 28 54 68 65 20 25 51 20 6f 70 74 69 6f 6e 20  ^(The %Q option 
1db10 77 6f 72 6b 73 20 6c 69 6b 65 20 25 71 20 65 78  works like %q ex
1db20 63 65 70 74 20 69 74 20 61 6c 73 6f 20 61 64 64  cept it also add
1db30 73 20 73 69 6e 67 6c 65 20 71 75 6f 74 65 73 20  s single quotes 
1db40 61 72 6f 75 6e 64 0a 2a 2a 20 74 68 65 20 6f 75  around.** the ou
1db50 74 73 69 64 65 20 6f 66 20 74 68 65 20 74 6f 74  tside of the tot
1db60 61 6c 20 73 74 72 69 6e 67 2e 20 20 41 64 64 69  al string.  Addi
1db70 74 69 6f 6e 61 6c 6c 79 2c 20 69 66 20 74 68 65  tionally, if the
1db80 20 70 61 72 61 6d 65 74 65 72 20 69 6e 20 74 68   parameter in th
1db90 65 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6c 69  e.** argument li
1dba0 73 74 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69  st is a NULL poi
1dbb0 6e 74 65 72 2c 20 25 51 20 73 75 62 73 74 69 74  nter, %Q substit
1dbc0 75 74 65 73 20 74 68 65 20 74 65 78 74 20 22 4e  utes the text "N
1dbd0 55 4c 4c 22 20 28 77 69 74 68 6f 75 74 0a 2a 2a  ULL" (without.**
1dbe0 20 73 69 6e 67 6c 65 20 71 75 6f 74 65 73 29 2e   single quotes).
1dbf0 29 5e 20 20 53 6f 2c 20 66 6f 72 20 65 78 61 6d  )^  So, for exam
1dc00 70 6c 65 2c 20 6f 6e 65 20 63 6f 75 6c 64 20 73  ple, one could s
1dc10 61 79 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  ay:.**.** <block
1dc20 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20  quote><pre>.**  
1dc30 63 68 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71 6c  char *zSQL = sql
1dc40 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 22 49 4e  ite3_mprintf("IN
1dc50 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 20  SERT INTO table 
1dc60 56 41 4c 55 45 53 28 25 51 29 22 2c 20 7a 54 65  VALUES(%Q)", zTe
1dc70 78 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33  xt);.**  sqlite3
1dc80 5f 65 78 65 63 28 64 62 2c 20 7a 53 51 4c 2c 20  _exec(db, zSQL, 
1dc90 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 71  0, 0, 0);.**  sq
1dca0 6c 69 74 65 33 5f 66 72 65 65 28 7a 53 51 4c 29  lite3_free(zSQL)
1dcb0 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f  ;.** </pre></blo
1dcc0 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54  ckquote>.**.** T
1dcd0 68 65 20 63 6f 64 65 20 61 62 6f 76 65 20 77 69  he code above wi
1dce0 6c 6c 20 72 65 6e 64 65 72 20 61 20 63 6f 72 72  ll render a corr
1dcf0 65 63 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ect SQL statemen
1dd00 74 20 69 6e 20 74 68 65 20 7a 53 51 4c 0a 2a 2a  t in the zSQL.**
1dd10 20 76 61 72 69 61 62 6c 65 20 65 76 65 6e 20 69   variable even i
1dd20 66 20 74 68 65 20 7a 54 65 78 74 20 76 61 72 69  f the zText vari
1dd30 61 62 6c 65 20 69 73 20 61 20 4e 55 4c 4c 20 70  able is a NULL p
1dd40 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28  ointer..**.** ^(
1dd50 54 68 65 20 22 25 77 22 20 66 6f 72 6d 61 74 74  The "%w" formatt
1dd60 69 6e 67 20 6f 70 74 69 6f 6e 20 69 73 20 6c 69  ing option is li
1dd70 6b 65 20 22 25 71 22 20 65 78 63 65 70 74 20 74  ke "%q" except t
1dd80 68 61 74 20 69 74 20 65 78 70 65 63 74 73 20 74  hat it expects t
1dd90 6f 0a 2a 2a 20 62 65 20 63 6f 6e 74 61 69 6e 65  o.** be containe
1dda0 64 20 77 69 74 68 69 6e 20 64 6f 75 62 6c 65 2d  d within double-
1ddb0 71 75 6f 74 65 73 20 69 6e 73 74 65 61 64 20 6f  quotes instead o
1ddc0 66 20 73 69 6e 67 6c 65 20 71 75 6f 74 65 73 2c  f single quotes,
1ddd0 20 61 6e 64 20 69 74 0a 2a 2a 20 65 73 63 61 70   and it.** escap
1dde0 65 73 20 74 68 65 20 64 6f 75 62 6c 65 2d 71 75  es the double-qu
1ddf0 6f 74 65 20 63 68 61 72 61 63 74 65 72 20 69 6e  ote character in
1de00 73 74 65 61 64 20 6f 66 20 74 68 65 20 73 69 6e  stead of the sin
1de10 67 6c 65 2d 71 75 6f 74 65 0a 2a 2a 20 63 68 61  gle-quote.** cha
1de20 72 61 63 74 65 72 2e 29 5e 20 20 54 68 65 20 22  racter.)^  The "
1de30 25 77 22 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f  %w" formatting o
1de40 70 74 69 6f 6e 20 69 73 20 69 6e 74 65 6e 64 65  ption is intende
1de50 64 20 66 6f 72 20 73 61 66 65 6c 79 20 69 6e 73  d for safely ins
1de60 65 72 74 69 6e 67 0a 2a 2a 20 74 61 62 6c 65 20  erting.** table 
1de70 61 6e 64 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 73  and column names
1de80 20 69 6e 74 6f 20 61 20 63 6f 6e 73 74 72 75 63   into a construc
1de90 74 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ted SQL statemen
1dea0 74 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 22  t..**.** ^(The "
1deb0 25 7a 22 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f  %z" formatting o
1dec0 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65  ption works like
1ded0 20 22 25 73 22 20 62 75 74 20 77 69 74 68 20 74   "%s" but with t
1dee0 68 65 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 20 74  he.** addition t
1def0 68 61 74 20 61 66 74 65 72 20 74 68 65 20 73 74  hat after the st
1df00 72 69 6e 67 20 68 61 73 20 62 65 65 6e 20 72 65  ring has been re
1df10 61 64 20 61 6e 64 20 63 6f 70 69 65 64 20 69 6e  ad and copied in
1df20 74 6f 0a 2a 2a 20 74 68 65 20 72 65 73 75 6c 74  to.** the result
1df30 2c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  , [sqlite3_free(
1df40 29 5d 20 69 73 20 63 61 6c 6c 65 64 20 6f 6e 20  )] is called on 
1df50 74 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67  the input string
1df60 2e 29 5e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  .)^.*/.SQLITE_AP
1df70 49 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  I char *sqlite3_
1df80 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74 20 63 68  mprintf(const ch
1df90 61 72 2a 2c 2e 2e 2e 29 3b 0a 53 51 4c 49 54 45  ar*,...);.SQLITE
1dfa0 5f 41 50 49 20 63 68 61 72 20 2a 73 71 6c 69 74  _API char *sqlit
1dfb0 65 33 5f 76 6d 70 72 69 6e 74 66 28 63 6f 6e 73  e3_vmprintf(cons
1dfc0 74 20 63 68 61 72 2a 2c 20 76 61 5f 6c 69 73 74  t char*, va_list
1dfd0 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 68  );.SQLITE_API ch
1dfe0 61 72 20 2a 73 71 6c 69 74 65 33 5f 73 6e 70 72  ar *sqlite3_snpr
1dff0 69 6e 74 66 28 69 6e 74 2c 63 68 61 72 2a 2c 63  intf(int,char*,c
1e000 6f 6e 73 74 20 63 68 61 72 2a 2c 20 2e 2e 2e 29  onst char*, ...)
1e010 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 68 61  ;.SQLITE_API cha
1e020 72 20 2a 73 71 6c 69 74 65 33 5f 76 73 6e 70 72  r *sqlite3_vsnpr
1e030 69 6e 74 66 28 69 6e 74 2c 63 68 61 72 2a 2c 63  intf(int,char*,c
1e040 6f 6e 73 74 20 63 68 61 72 2a 2c 20 76 61 5f 6c  onst char*, va_l
1e050 69 73 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ist);../*.** CAP
1e060 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c  I3REF: Memory Al
1e070 6c 6f 63 61 74 69 6f 6e 20 53 75 62 73 79 73 74  location Subsyst
1e080 65 6d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c  em.**.** The SQL
1e090 69 74 65 20 63 6f 72 65 20 75 73 65 73 20 74 68  ite core uses th
1e0a0 65 73 65 20 74 68 72 65 65 20 72 6f 75 74 69 6e  ese three routin
1e0b0 65 73 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74  es for all of it
1e0c0 73 20 6f 77 6e 0a 2a 2a 20 69 6e 74 65 72 6e 61  s own.** interna
1e0d0 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  l memory allocat
1e0e0 69 6f 6e 20 6e 65 65 64 73 2e 20 22 43 6f 72 65  ion needs. "Core
1e0f0 22 20 69 6e 20 74 68 65 20 70 72 65 76 69 6f 75  " in the previou
1e100 73 20 73 65 6e 74 65 6e 63 65 0a 2a 2a 20 64 6f  s sentence.** do
1e110 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 6f  es not include o
1e120 70 65 72 61 74 69 6e 67 2d 73 79 73 74 65 6d 20  perating-system 
1e130 73 70 65 63 69 66 69 63 20 56 46 53 20 69 6d 70  specific VFS imp
1e140 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 20 54 68  lementation.  Th
1e150 65 0a 2a 2a 20 57 69 6e 64 6f 77 73 20 56 46 53  e.** Windows VFS
1e160 20 75 73 65 73 20 6e 61 74 69 76 65 20 6d 61 6c   uses native mal
1e170 6c 6f 63 28 29 20 61 6e 64 20 66 72 65 65 28 29  loc() and free()
1e180 20 66 6f 72 20 73 6f 6d 65 20 6f 70 65 72 61 74   for some operat
1e190 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ions..**.** ^The
1e1a0 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28   sqlite3_malloc(
1e1b0 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  ) routine return
1e1c0 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
1e1d0 20 62 6c 6f 63 6b 0a 2a 2a 20 6f 66 20 6d 65 6d   block.** of mem
1e1e0 6f 72 79 20 61 74 20 6c 65 61 73 74 20 4e 20 62  ory at least N b
1e1f0 79 74 65 73 20 69 6e 20 6c 65 6e 67 74 68 2c 20  ytes in length, 
1e200 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 20 70  where N is the p
1e210 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e 49 66  arameter..** ^If
1e220 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28   sqlite3_malloc(
1e230 29 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 6f  ) is unable to o
1e240 62 74 61 69 6e 20 73 75 66 66 69 63 69 65 6e 74  btain sufficient
1e250 20 66 72 65 65 0a 2a 2a 20 6d 65 6d 6f 72 79 2c   free.** memory,
1e260 20 69 74 20 72 65 74 75 72 6e 73 20 61 20 4e 55   it returns a NU
1e270 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 5e 49 66  LL pointer.  ^If
1e280 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 4e   the parameter N
1e290 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d   to.** sqlite3_m
1e2a0 61 6c 6c 6f 63 28 29 20 69 73 20 7a 65 72 6f 20  alloc() is zero 
1e2b0 6f 72 20 6e 65 67 61 74 69 76 65 20 74 68 65 6e  or negative then
1e2c0 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28   sqlite3_malloc(
1e2d0 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 20 4e  ) returns.** a N
1e2e0 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a  ULL pointer..**.
1e2f0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
1e300 6d 61 6c 6c 6f 63 36 34 28 4e 29 20 72 6f 75 74  malloc64(N) rout
1e310 69 6e 65 20 77 6f 72 6b 73 20 6a 75 73 74 20 6c  ine works just l
1e320 69 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d  ike.** sqlite3_m
1e330 61 6c 6c 6f 63 28 4e 29 20 65 78 63 65 70 74 20  alloc(N) except 
1e340 74 68 61 74 20 4e 20 69 73 20 61 6e 20 75 6e 73  that N is an uns
1e350 69 67 6e 65 64 20 36 34 2d 62 69 74 20 69 6e 74  igned 64-bit int
1e360 65 67 65 72 20 69 6e 73 74 65 61 64 0a 2a 2a 20  eger instead.** 
1e370 6f 66 20 61 20 73 69 67 6e 65 64 20 33 32 2d 62  of a signed 32-b
1e380 69 74 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 0a 2a  it integer..**.*
1e390 2a 20 5e 43 61 6c 6c 69 6e 67 20 73 71 6c 69 74  * ^Calling sqlit
1e3a0 65 33 5f 66 72 65 65 28 29 20 77 69 74 68 20 61  e3_free() with a
1e3b0 20 70 6f 69 6e 74 65 72 20 70 72 65 76 69 6f 75   pointer previou
1e3c0 73 6c 79 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20  sly returned.** 
1e3d0 62 79 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  by sqlite3_mallo
1e3e0 63 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 72  c() or sqlite3_r
1e3f0 65 61 6c 6c 6f 63 28 29 20 72 65 6c 65 61 73 65  ealloc() release
1e400 73 20 74 68 61 74 20 6d 65 6d 6f 72 79 20 73 6f  s that memory so
1e410 0a 2a 2a 20 74 68 61 74 20 69 74 20 6d 69 67 68  .** that it migh
1e420 74 20 62 65 20 72 65 75 73 65 64 2e 20 20 5e 54  t be reused.  ^T
1e430 68 65 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28  he sqlite3_free(
1e440 29 20 72 6f 75 74 69 6e 65 20 69 73 0a 2a 2a 20  ) routine is.** 
1e450 61 20 6e 6f 2d 6f 70 20 69 66 20 69 73 20 63 61  a no-op if is ca
1e460 6c 6c 65 64 20 77 69 74 68 20 61 20 4e 55 4c 4c  lled with a NULL
1e470 20 70 6f 69 6e 74 65 72 2e 20 20 50 61 73 73 69   pointer.  Passi
1e480 6e 67 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  ng a NULL pointe
1e490 72 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f  r.** to sqlite3_
1e4a0 66 72 65 65 28 29 20 69 73 20 68 61 72 6d 6c 65  free() is harmle
1e4b0 73 73 2e 20 20 41 66 74 65 72 20 62 65 69 6e 67  ss.  After being
1e4c0 20 66 72 65 65 64 2c 20 6d 65 6d 6f 72 79 0a 2a   freed, memory.*
1e4d0 2a 20 73 68 6f 75 6c 64 20 6e 65 69 74 68 65 72  * should neither
1e4e0 20 62 65 20 72 65 61 64 20 6e 6f 72 20 77 72 69   be read nor wri
1e4f0 74 74 65 6e 2e 20 20 45 76 65 6e 20 72 65 61 64  tten.  Even read
1e500 69 6e 67 20 70 72 65 76 69 6f 75 73 6c 79 20 66  ing previously f
1e510 72 65 65 64 0a 2a 2a 20 6d 65 6d 6f 72 79 20 6d  reed.** memory m
1e520 69 67 68 74 20 72 65 73 75 6c 74 20 69 6e 20 61  ight result in a
1e530 20 73 65 67 6d 65 6e 74 61 74 69 6f 6e 20 66 61   segmentation fa
1e540 75 6c 74 20 6f 72 20 6f 74 68 65 72 20 73 65 76  ult or other sev
1e550 65 72 65 20 65 72 72 6f 72 2e 0a 2a 2a 20 4d 65  ere error..** Me
1e560 6d 6f 72 79 20 63 6f 72 72 75 70 74 69 6f 6e 2c  mory corruption,
1e570 20 61 20 73 65 67 6d 65 6e 74 61 74 69 6f 6e 20   a segmentation 
1e580 66 61 75 6c 74 2c 20 6f 72 20 6f 74 68 65 72 20  fault, or other 
1e590 73 65 76 65 72 65 20 65 72 72 6f 72 0a 2a 2a 20  severe error.** 
1e5a0 6d 69 67 68 74 20 72 65 73 75 6c 74 20 69 66 20  might result if 
1e5b0 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 69  sqlite3_free() i
1e5c0 73 20 63 61 6c 6c 65 64 20 77 69 74 68 20 61 20  s called with a 
1e5d0 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  non-NULL pointer
1e5e0 20 74 68 61 74 0a 2a 2a 20 77 61 73 20 6e 6f 74   that.** was not
1e5f0 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 73   obtained from s
1e600 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20  qlite3_malloc() 
1e610 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  or sqlite3_reall
1e620 6f 63 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  oc()..**.** ^The
1e630 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
1e640 28 58 2c 4e 29 20 69 6e 74 65 72 66 61 63 65 20  (X,N) interface 
1e650 61 74 74 65 6d 70 74 73 20 74 6f 20 72 65 73 69  attempts to resi
1e660 7a 65 20 61 0a 2a 2a 20 70 72 69 6f 72 20 6d 65  ze a.** prior me
1e670 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
1e680 58 20 74 6f 20 62 65 20 61 74 20 6c 65 61 73 74  X to be at least
1e690 20 4e 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 49 66   N bytes..** ^If
1e6a0 20 74 68 65 20 58 20 70 61 72 61 6d 65 74 65 72   the X parameter
1e6b0 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c   to sqlite3_real
1e6c0 6c 6f 63 28 58 2c 4e 29 0a 2a 2a 20 69 73 20 61  loc(X,N).** is a
1e6d0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68   NULL pointer th
1e6e0 65 6e 20 69 74 73 20 62 65 68 61 76 69 6f 72 20  en its behavior 
1e6f0 69 73 20 69 64 65 6e 74 69 63 61 6c 20 74 6f 20  is identical to 
1e700 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69 74  calling.** sqlit
1e710 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29 2e 0a 2a 2a  e3_malloc(N)..**
1e720 20 5e 49 66 20 74 68 65 20 4e 20 70 61 72 61 6d   ^If the N param
1e730 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
1e740 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 20 69 73 20  realloc(X,N) is 
1e750 7a 65 72 6f 20 6f 72 0a 2a 2a 20 6e 65 67 61 74  zero or.** negat
1e760 69 76 65 20 74 68 65 6e 20 74 68 65 20 62 65 68  ive then the beh
1e770 61 76 69 6f 72 20 69 73 20 65 78 61 63 74 6c 79  avior is exactly
1e780 20 74 68 65 20 73 61 6d 65 20 61 73 20 63 61 6c   the same as cal
1e790 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  ling.** sqlite3_
1e7a0 66 72 65 65 28 58 29 2e 0a 2a 2a 20 5e 73 71 6c  free(X)..** ^sql
1e7b0 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e  ite3_realloc(X,N
1e7c0 29 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  ) returns a poin
1e7d0 74 65 72 20 74 6f 20 61 20 6d 65 6d 6f 72 79 20  ter to a memory 
1e7e0 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66  allocation.** of
1e7f0 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65   at least N byte
1e800 73 20 69 6e 20 73 69 7a 65 20 6f 72 20 4e 55 4c  s in size or NUL
1e810 4c 20 69 66 20 69 6e 73 75 66 66 69 63 69 65 6e  L if insufficien
1e820 74 20 6d 65 6d 6f 72 79 20 69 73 20 61 76 61 69  t memory is avai
1e830 6c 61 62 6c 65 2e 0a 2a 2a 20 5e 49 66 20 4d 20  lable..** ^If M 
1e840 69 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74  is the size of t
1e850 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74  he prior allocat
1e860 69 6f 6e 2c 20 74 68 65 6e 20 6d 69 6e 28 4e 2c  ion, then min(N,
1e870 4d 29 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 74  M) bytes.** of t
1e880 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74  he prior allocat
1e890 69 6f 6e 20 61 72 65 20 63 6f 70 69 65 64 20 69  ion are copied i
1e8a0 6e 74 6f 20 74 68 65 20 62 65 67 69 6e 6e 69 6e  nto the beginnin
1e8b0 67 20 6f 66 20 62 75 66 66 65 72 20 72 65 74 75  g of buffer retu
1e8c0 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c 69 74  rned.** by sqlit
1e8d0 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 20  e3_realloc(X,N) 
1e8e0 61 6e 64 20 74 68 65 20 70 72 69 6f 72 20 61 6c  and the prior al
1e8f0 6c 6f 63 61 74 69 6f 6e 20 69 73 20 66 72 65 65  location is free
1e900 64 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65  d..** ^If sqlite
1e910 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 20 72  3_realloc(X,N) r
1e920 65 74 75 72 6e 73 20 4e 55 4c 4c 20 61 6e 64 20  eturns NULL and 
1e930 4e 20 69 73 20 70 6f 73 69 74 69 76 65 2c 20 74  N is positive, t
1e940 68 65 6e 20 74 68 65 0a 2a 2a 20 70 72 69 6f 72  hen the.** prior
1e950 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 73 20 6e   allocation is n
1e960 6f 74 20 66 72 65 65 64 2e 0a 2a 2a 0a 2a 2a 20  ot freed..**.** 
1e970 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 61  ^The sqlite3_rea
1e980 6c 6c 6f 63 36 34 28 58 2c 4e 29 20 69 6e 74 65  lloc64(X,N) inte
1e990 72 66 61 63 65 73 20 77 6f 72 6b 73 20 74 68 65  rfaces works the
1e9a0 20 73 61 6d 65 20 61 73 0a 2a 2a 20 73 71 6c 69   same as.** sqli
1e9b0 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29  te3_realloc(X,N)
1e9c0 20 65 78 63 65 70 74 20 74 68 61 74 20 4e 20 69   except that N i
1e9d0 73 20 61 20 36 34 2d 62 69 74 20 75 6e 73 69 67  s a 64-bit unsig
1e9e0 6e 65 64 20 69 6e 74 65 67 65 72 20 69 6e 73 74  ned integer inst
1e9f0 65 61 64 0a 2a 2a 20 6f 66 20 61 20 33 32 2d 62  ead.** of a 32-b
1ea00 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65  it signed intege
1ea10 72 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 58 20 69  r..**.** ^If X i
1ea20 73 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  s a memory alloc
1ea30 61 74 69 6f 6e 20 70 72 65 76 69 6f 75 73 6c 79  ation previously
1ea40 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 73   obtained from s
1ea50 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 2c  qlite3_malloc(),
1ea60 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  .** sqlite3_mall
1ea70 6f 63 36 34 28 29 2c 20 73 71 6c 69 74 65 33 5f  oc64(), sqlite3_
1ea80 72 65 61 6c 6c 6f 63 28 29 2c 20 6f 72 20 73 71  realloc(), or sq
1ea90 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 36 34 28  lite3_realloc64(
1eaa0 29 2c 20 74 68 65 6e 0a 2a 2a 20 73 71 6c 69 74  ), then.** sqlit
1eab0 65 33 5f 6d 73 69 7a 65 28 58 29 20 72 65 74 75  e3_msize(X) retu
1eac0 72 6e 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20  rns the size of 
1ead0 74 68 61 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  that memory allo
1eae0 63 61 74 69 6f 6e 20 69 6e 20 62 79 74 65 73 2e  cation in bytes.
1eaf0 0a 2a 2a 20 5e 54 68 65 20 76 61 6c 75 65 20 72  .** ^The value r
1eb00 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74  eturned by sqlit
1eb10 65 33 5f 6d 73 69 7a 65 28 58 29 20 6d 69 67 68  e3_msize(X) migh
1eb20 74 20 62 65 20 6c 61 72 67 65 72 20 74 68 61 6e  t be larger than
1eb30 20 74 68 65 20 6e 75 6d 62 65 72 0a 2a 2a 20 6f   the number.** o
1eb40 66 20 62 79 74 65 73 20 72 65 71 75 65 73 74 65  f bytes requeste
1eb50 64 20 77 68 65 6e 20 58 20 77 61 73 20 61 6c 6c  d when X was all
1eb60 6f 63 61 74 65 64 2e 20 20 5e 49 66 20 58 20 69  ocated.  ^If X i
1eb70 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
1eb80 20 74 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33   then.** sqlite3
1eb90 5f 6d 73 69 7a 65 28 58 29 20 72 65 74 75 72 6e  _msize(X) return
1eba0 73 20 7a 65 72 6f 2e 20 20 49 66 20 58 20 70 6f  s zero.  If X po
1ebb0 69 6e 74 73 20 74 6f 20 73 6f 6d 65 74 68 69 6e  ints to somethin
1ebc0 67 20 74 68 61 74 20 69 73 20 6e 6f 74 0a 2a 2a  g that is not.**
1ebd0 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f   the beginning o
1ebe0 66 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  f memory allocat
1ebf0 69 6f 6e 2c 20 6f 72 20 69 66 20 69 74 20 70 6f  ion, or if it po
1ec00 69 6e 74 73 20 74 6f 20 61 20 66 6f 72 6d 65 72  ints to a former
1ec10 6c 79 0a 2a 2a 20 76 61 6c 69 64 20 6d 65 6d 6f  ly.** valid memo
1ec20 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 68  ry allocation th
1ec30 61 74 20 68 61 73 20 6e 6f 77 20 62 65 65 6e 20  at has now been 
1ec40 66 72 65 65 64 2c 20 74 68 65 6e 20 74 68 65 20  freed, then the 
1ec50 62 65 68 61 76 69 6f 72 0a 2a 2a 20 6f 66 20 73  behavior.** of s
1ec60 71 6c 69 74 65 33 5f 6d 73 69 7a 65 28 58 29 20  qlite3_msize(X) 
1ec70 69 73 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64  is undefined and
1ec80 20 70 6f 73 73 69 62 6c 79 20 68 61 72 6d 66 75   possibly harmfu
1ec90 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6d 65  l..**.** ^The me
1eca0 6d 6f 72 79 20 72 65 74 75 72 6e 65 64 20 62 79  mory returned by
1ecb0 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28   sqlite3_malloc(
1ecc0 29 2c 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  ), sqlite3_reall
1ecd0 6f 63 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33  oc(),.** sqlite3
1ece0 5f 6d 61 6c 6c 6f 63 36 34 28 29 2c 20 61 6e 64  _malloc64(), and
1ecf0 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
1ed00 36 34 28 29 0a 2a 2a 20 69 73 20 61 6c 77 61 79  64().** is alway
1ed10 73 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 74 20  s aligned to at 
1ed20 6c 65 61 73 74 20 61 6e 20 38 20 62 79 74 65 20  least an 8 byte 
1ed30 62 6f 75 6e 64 61 72 79 2c 20 6f 72 20 74 6f 20  boundary, or to 
1ed40 61 0a 2a 2a 20 34 20 62 79 74 65 20 62 6f 75 6e  a.** 4 byte boun
1ed50 64 61 72 79 20 69 66 20 74 68 65 20 5b 53 51 4c  dary if the [SQL
1ed60 49 54 45 5f 34 5f 42 59 54 45 5f 41 4c 49 47 4e  ITE_4_BYTE_ALIGN
1ed70 45 44 5f 4d 41 4c 4c 4f 43 5d 20 63 6f 6d 70 69  ED_MALLOC] compi
1ed80 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74 69 6f  le-time.** optio
1ed90 6e 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a  n is used..**.**
1eda0 20 49 6e 20 53 51 4c 69 74 65 20 76 65 72 73 69   In SQLite versi
1edb0 6f 6e 20 33 2e 35 2e 30 20 61 6e 64 20 33 2e 35  on 3.5.0 and 3.5
1edc0 2e 31 2c 20 69 74 20 77 61 73 20 70 6f 73 73 69  .1, it was possi
1edd0 62 6c 65 20 74 6f 20 64 65 66 69 6e 65 0a 2a 2a  ble to define.**
1ede0 20 74 68 65 20 53 51 4c 49 54 45 5f 4f 4d 49 54   the SQLITE_OMIT
1edf0 5f 4d 45 4d 4f 52 59 5f 41 4c 4c 4f 43 41 54 49  _MEMORY_ALLOCATI
1ee00 4f 4e 20 77 68 69 63 68 20 77 6f 75 6c 64 20 63  ON which would c
1ee10 61 75 73 65 20 74 68 65 20 62 75 69 6c 74 2d 69  ause the built-i
1ee20 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74  n.** implementat
1ee30 69 6f 6e 20 6f 66 20 74 68 65 73 65 20 72 6f 75  ion of these rou
1ee40 74 69 6e 65 73 20 74 6f 20 62 65 20 6f 6d 69 74  tines to be omit
1ee50 74 65 64 2e 20 20 54 68 61 74 20 63 61 70 61 62  ted.  That capab
1ee60 69 6c 69 74 79 0a 2a 2a 20 69 73 20 6e 6f 20 6c  ility.** is no l
1ee70 6f 6e 67 65 72 20 70 72 6f 76 69 64 65 64 2e 20  onger provided. 
1ee80 20 4f 6e 6c 79 20 62 75 69 6c 74 2d 69 6e 20 6d   Only built-in m
1ee90 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 73  emory allocators
1eea0 20 63 61 6e 20 62 65 20 75 73 65 64 2e 0a 2a 2a   can be used..**
1eeb0 0a 2a 2a 20 50 72 69 6f 72 20 74 6f 20 53 51 4c  .** Prior to SQL
1eec0 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 37 2e  ite version 3.7.
1eed0 31 30 2c 20 74 68 65 20 57 69 6e 64 6f 77 73 20  10, the Windows 
1eee0 4f 53 20 69 6e 74 65 72 66 61 63 65 20 6c 61 79  OS interface lay
1eef0 65 72 20 63 61 6c 6c 65 64 0a 2a 2a 20 74 68 65  er called.** the
1ef00 20 73 79 73 74 65 6d 20 6d 61 6c 6c 6f 63 28 29   system malloc()
1ef10 20 61 6e 64 20 66 72 65 65 28 29 20 64 69 72 65   and free() dire
1ef20 63 74 6c 79 20 77 68 65 6e 20 63 6f 6e 76 65 72  ctly when conver
1ef30 74 69 6e 67 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65  ting.** filename
1ef40 73 20 62 65 74 77 65 65 6e 20 74 68 65 20 55 54  s between the UT
1ef50 46 2d 38 20 65 6e 63 6f 64 69 6e 67 20 75 73 65  F-8 encoding use
1ef60 64 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20 61  d by SQLite.** a
1ef70 6e 64 20 77 68 61 74 65 76 65 72 20 66 69 6c 65  nd whatever file
1ef80 6e 61 6d 65 20 65 6e 63 6f 64 69 6e 67 20 69 73  name encoding is
1ef90 20 75 73 65 64 20 62 79 20 74 68 65 20 70 61 72   used by the par
1efa0 74 69 63 75 6c 61 72 20 57 69 6e 64 6f 77 73 0a  ticular Windows.
1efb0 2a 2a 20 69 6e 73 74 61 6c 6c 61 74 69 6f 6e 2e  ** installation.
1efc0 20 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74    Memory allocat
1efd0 69 6f 6e 20 65 72 72 6f 72 73 20 77 65 72 65 20  ion errors were 
1efe0 64 65 74 65 63 74 65 64 2c 20 62 75 74 0a 2a 2a  detected, but.**
1eff0 20 74 68 65 79 20 77 65 72 65 20 72 65 70 6f 72   they were repor
1f000 74 65 64 20 62 61 63 6b 20 61 73 20 5b 53 51 4c  ted back as [SQL
1f010 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 6f 72  ITE_CANTOPEN] or
1f020 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52  .** [SQLITE_IOER
1f030 52 5d 20 72 61 74 68 65 72 20 74 68 61 6e 20 5b  R] rather than [
1f040 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a  SQLITE_NOMEM]..*
1f050 2a 0a 2a 2a 20 54 68 65 20 70 6f 69 6e 74 65 72  *.** The pointer
1f060 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 5b 73   arguments to [s
1f070 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 61  qlite3_free()] a
1f080 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c  nd [sqlite3_real
1f090 6c 6f 63 28 29 5d 0a 2a 2a 20 6d 75 73 74 20 62  loc()].** must b
1f0a0 65 20 65 69 74 68 65 72 20 4e 55 4c 4c 20 6f 72  e either NULL or
1f0b0 20 65 6c 73 65 20 70 6f 69 6e 74 65 72 73 20 6f   else pointers o
1f0c0 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 61 20 70  btained from a p
1f0d0 72 69 6f 72 0a 2a 2a 20 69 6e 76 6f 63 61 74 69  rior.** invocati
1f0e0 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d  on of [sqlite3_m
1f0f0 61 6c 6c 6f 63 28 29 5d 20 6f 72 20 5b 73 71 6c  alloc()] or [sql
1f100 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 20  ite3_realloc()] 
1f110 74 68 61 74 20 68 61 76 65 0a 2a 2a 20 6e 6f 74  that have.** not
1f120 20 79 65 74 20 62 65 65 6e 20 72 65 6c 65 61 73   yet been releas
1f130 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70  ed..**.** The ap
1f140 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e  plication must n
1f150 6f 74 20 72 65 61 64 20 6f 72 20 77 72 69 74 65  ot read or write
1f160 20 61 6e 79 20 70 61 72 74 20 6f 66 0a 2a 2a 20   any part of.** 
1f170 61 20 62 6c 6f 63 6b 20 6f 66 20 6d 65 6d 6f 72  a block of memor
1f180 79 20 61 66 74 65 72 20 69 74 20 68 61 73 20 62  y after it has b
1f190 65 65 6e 20 72 65 6c 65 61 73 65 64 20 75 73 69  een released usi
1f1a0 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66  ng.** [sqlite3_f
1f1b0 72 65 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  ree()] or [sqlit
1f1c0 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 2e 0a 2a  e3_realloc()]..*
1f1d0 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69  /.SQLITE_API voi
1f1e0 64 20 2a 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  d *sqlite3_mallo
1f1f0 63 28 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41  c(int);.SQLITE_A
1f200 50 49 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  PI void *sqlite3
1f210 5f 6d 61 6c 6c 6f 63 36 34 28 73 71 6c 69 74 65  _malloc64(sqlite
1f220 33 5f 75 69 6e 74 36 34 29 3b 0a 53 51 4c 49 54  3_uint64);.SQLIT
1f230 45 5f 41 50 49 20 76 6f 69 64 20 2a 73 71 6c 69  E_API void *sqli
1f240 74 65 33 5f 72 65 61 6c 6c 6f 63 28 76 6f 69 64  te3_realloc(void
1f250 2a 2c 20 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f  *, int);.SQLITE_
1f260 41 50 49 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  API void *sqlite
1f270 33 5f 72 65 61 6c 6c 6f 63 36 34 28 76 6f 69 64  3_realloc64(void
1f280 2a 2c 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36  *, sqlite3_uint6
1f290 34 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76  4);.SQLITE_API v
1f2a0 6f 69 64 20 73 71 6c 69 74 65 33 5f 66 72 65 65  oid sqlite3_free
1f2b0 28 76 6f 69 64 2a 29 3b 0a 53 51 4c 49 54 45 5f  (void*);.SQLITE_
1f2c0 41 50 49 20 73 71 6c 69 74 65 33 5f 75 69 6e 74  API sqlite3_uint
1f2d0 36 34 20 73 71 6c 69 74 65 33 5f 6d 73 69 7a 65  64 sqlite3_msize
1f2e0 28 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  (void*);../*.** 
1f2f0 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79  CAPI3REF: Memory
1f300 20 41 6c 6c 6f 63 61 74 6f 72 20 53 74 61 74 69   Allocator Stati
1f310 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  stics.**.** SQLi
1f320 74 65 20 70 72 6f 76 69 64 65 73 20 74 68 65 73  te provides thes
1f330 65 20 74 77 6f 20 69 6e 74 65 72 66 61 63 65 73  e two interfaces
1f340 20 66 6f 72 20 72 65 70 6f 72 74 69 6e 67 20 6f   for reporting o
1f350 6e 20 74 68 65 20 73 74 61 74 75 73 0a 2a 2a 20  n the status.** 
1f360 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
1f370 6d 61 6c 6c 6f 63 28 29 5d 2c 20 5b 73 71 6c 69  malloc()], [sqli
1f380 74 65 33 5f 66 72 65 65 28 29 5d 2c 20 61 6e 64  te3_free()], and
1f390 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f   [sqlite3_reallo
1f3a0 63 28 29 5d 0a 2a 2a 20 72 6f 75 74 69 6e 65 73  c()].** routines
1f3b0 2c 20 77 68 69 63 68 20 66 6f 72 6d 20 74 68 65  , which form the
1f3c0 20 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79   built-in memory
1f3d0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73   allocation subs
1f3e0 79 73 74 65 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ystem..**.** ^Th
1f3f0 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  e [sqlite3_memor
1f400 79 5f 75 73 65 64 28 29 5d 20 72 6f 75 74 69 6e  y_used()] routin
1f410 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75  e returns the nu
1f420 6d 62 65 72 20 6f 66 20 62 79 74 65 73 0a 2a 2a  mber of bytes.**
1f430 20 6f 66 20 6d 65 6d 6f 72 79 20 63 75 72 72 65   of memory curre
1f440 6e 74 6c 79 20 6f 75 74 73 74 61 6e 64 69 6e 67  ntly outstanding
1f450 20 28 6d 61 6c 6c 6f 63 65 64 20 62 75 74 20 6e   (malloced but n
1f460 6f 74 20 66 72 65 65 64 29 2e 0a 2a 2a 20 5e 54  ot freed)..** ^T
1f470 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  he [sqlite3_memo
1f480 72 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d 20  ry_highwater()] 
1f490 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
1f4a0 74 68 65 20 6d 61 78 69 6d 75 6d 0a 2a 2a 20 76  the maximum.** v
1f4b0 61 6c 75 65 20 6f 66 20 5b 73 71 6c 69 74 65 33  alue of [sqlite3
1f4c0 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20  _memory_used()] 
1f4d0 73 69 6e 63 65 20 74 68 65 20 68 69 67 68 2d 77  since the high-w
1f4e0 61 74 65 72 20 6d 61 72 6b 0a 2a 2a 20 77 61 73  ater mark.** was
1f4f0 20 6c 61 73 74 20 72 65 73 65 74 2e 20 20 5e 54   last reset.  ^T
1f500 68 65 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e  he values return
1f510 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6d  ed by [sqlite3_m
1f520 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 61 6e  emory_used()] an
1f530 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65  d.** [sqlite3_me
1f540 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 29  mory_highwater()
1f550 5d 20 69 6e 63 6c 75 64 65 20 61 6e 79 20 6f 76  ] include any ov
1f560 65 72 68 65 61 64 0a 2a 2a 20 61 64 64 65 64 20  erhead.** added 
1f570 62 79 20 53 51 4c 69 74 65 20 69 6e 20 69 74 73  by SQLite in its
1f580 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
1f590 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  of [sqlite3_mall
1f5a0 6f 63 28 29 5d 2c 0a 2a 2a 20 62 75 74 20 6e 6f  oc()],.** but no
1f5b0 74 20 6f 76 65 72 68 65 61 64 20 61 64 64 65 64  t overhead added
1f5c0 20 62 79 20 74 68 65 20 61 6e 79 20 75 6e 64 65   by the any unde
1f5d0 72 6c 79 69 6e 67 20 73 79 73 74 65 6d 20 6c 69  rlying system li
1f5e0 62 72 61 72 79 0a 2a 2a 20 72 6f 75 74 69 6e 65  brary.** routine
1f5f0 73 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f  s that [sqlite3_
1f600 6d 61 6c 6c 6f 63 28 29 5d 20 6d 61 79 20 63 61  malloc()] may ca
1f610 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6d  ll..**.** ^The m
1f620 65 6d 6f 72 79 20 68 69 67 68 2d 77 61 74 65 72  emory high-water
1f630 20 6d 61 72 6b 20 69 73 20 72 65 73 65 74 20 74   mark is reset t
1f640 6f 20 74 68 65 20 63 75 72 72 65 6e 74 20 76 61  o the current va
1f650 6c 75 65 20 6f 66 0a 2a 2a 20 5b 73 71 6c 69 74  lue of.** [sqlit
1f660 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29  e3_memory_used()
1f670 5d 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66  ] if and only if
1f680 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 74   the parameter t
1f690 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65  o.** [sqlite3_me
1f6a0 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 29  mory_highwater()
1f6b0 5d 20 69 73 20 74 72 75 65 2e 20 20 5e 54 68 65  ] is true.  ^The
1f6c0 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 0a   value returned.
1f6d0 2a 2a 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6d  ** by [sqlite3_m
1f6e0 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28  emory_highwater(
1f6f0 31 29 5d 20 69 73 20 74 68 65 20 68 69 67 68 2d  1)] is the high-
1f700 77 61 74 65 72 20 6d 61 72 6b 0a 2a 2a 20 70 72  water mark.** pr
1f710 69 6f 72 20 74 6f 20 74 68 65 20 72 65 73 65 74  ior to the reset
1f720 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
1f730 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71  sqlite3_int64 sq
1f740 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65  lite3_memory_use
1f750 64 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f  d(void);.SQLITE_
1f760 41 50 49 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  API sqlite3_int6
1f770 34 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79  4 sqlite3_memory
1f780 5f 68 69 67 68 77 61 74 65 72 28 69 6e 74 20 72  _highwater(int r
1f790 65 73 65 74 46 6c 61 67 29 3b 0a 0a 2f 2a 0a 2a  esetFlag);../*.*
1f7a0 2a 20 43 41 50 49 33 52 45 46 3a 20 50 73 65 75  * CAPI3REF: Pseu
1f7b0 64 6f 2d 52 61 6e 64 6f 6d 20 4e 75 6d 62 65 72  do-Random Number
1f7c0 20 47 65 6e 65 72 61 74 6f 72 0a 2a 2a 0a 2a 2a   Generator.**.**
1f7d0 20 53 51 4c 69 74 65 20 63 6f 6e 74 61 69 6e 73   SQLite contains
1f7e0 20 61 20 68 69 67 68 2d 71 75 61 6c 69 74 79 20   a high-quality 
1f7f0 70 73 65 75 64 6f 2d 72 61 6e 64 6f 6d 20 6e 75  pseudo-random nu
1f800 6d 62 65 72 20 67 65 6e 65 72 61 74 6f 72 20 28  mber generator (
1f810 50 52 4e 47 29 20 75 73 65 64 20 74 6f 0a 2a 2a  PRNG) used to.**
1f820 20 73 65 6c 65 63 74 20 72 61 6e 64 6f 6d 20 5b   select random [
1f830 52 4f 57 49 44 20 7c 20 52 4f 57 49 44 73 5d 20  ROWID | ROWIDs] 
1f840 77 68 65 6e 20 69 6e 73 65 72 74 69 6e 67 20 6e  when inserting n
1f850 65 77 20 72 65 63 6f 72 64 73 20 69 6e 74 6f 20  ew records into 
1f860 61 20 74 61 62 6c 65 20 74 68 61 74 0a 2a 2a 20  a table that.** 
1f870 61 6c 72 65 61 64 79 20 75 73 65 73 20 74 68 65  already uses the
1f880 20 6c 61 72 67 65 73 74 20 70 6f 73 73 69 62 6c   largest possibl
1f890 65 20 5b 52 4f 57 49 44 5d 2e 20 20 54 68 65 20  e [ROWID].  The 
1f8a0 50 52 4e 47 20 69 73 20 61 6c 73 6f 20 75 73 65  PRNG is also use
1f8b0 64 20 66 6f 72 0a 2a 2a 20 74 68 65 20 62 75 69  d for.** the bui
1f8c0 6c 64 2d 69 6e 20 72 61 6e 64 6f 6d 28 29 20 61  ld-in random() a
1f8d0 6e 64 20 72 61 6e 64 6f 6d 62 6c 6f 62 28 29 20  nd randomblob() 
1f8e0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20  SQL functions.  
1f8f0 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 61  This interface a
1f900 6c 6c 6f 77 73 0a 2a 2a 20 61 70 70 6c 69 63 61  llows.** applica
1f910 74 69 6f 6e 73 20 74 6f 20 61 63 63 65 73 73 20  tions to access 
1f920 74 68 65 20 73 61 6d 65 20 50 52 4e 47 20 66 6f  the same PRNG fo
1f930 72 20 6f 74 68 65 72 20 70 75 72 70 6f 73 65 73  r other purposes
1f940 2e 0a 2a 2a 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20  ..**.** ^A call 
1f950 74 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  to this routine 
1f960 73 74 6f 72 65 73 20 4e 20 62 79 74 65 73 20 6f  stores N bytes o
1f970 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74  f randomness int
1f980 6f 20 62 75 66 66 65 72 20 50 2e 0a 2a 2a 20 5e  o buffer P..** ^
1f990 54 68 65 20 50 20 70 61 72 61 6d 65 74 65 72 20  The P parameter 
1f9a0 63 61 6e 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f  can be a NULL po
1f9b0 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  inter..**.** ^If
1f9c0 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 68 61   this routine ha
1f9d0 73 20 6e 6f 74 20 62 65 65 6e 20 70 72 65 76 69  s not been previ
1f9e0 6f 75 73 6c 79 20 63 61 6c 6c 65 64 20 6f 72 20  ously called or 
1f9f0 69 66 20 74 68 65 20 70 72 65 76 69 6f 75 73 0a  if the previous.
1fa00 2a 2a 20 63 61 6c 6c 20 68 61 64 20 4e 20 6c 65  ** call had N le
1fa10 73 73 20 74 68 61 6e 20 6f 6e 65 20 6f 72 20 61  ss than one or a
1fa20 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 66 6f   NULL pointer fo
1fa30 72 20 50 2c 20 74 68 65 6e 20 74 68 65 20 50 52  r P, then the PR
1fa40 4e 47 20 69 73 0a 2a 2a 20 73 65 65 64 65 64 20  NG is.** seeded 
1fa50 75 73 69 6e 67 20 72 61 6e 64 6f 6d 6e 65 73 73  using randomness
1fa60 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 74   obtained from t
1fa70 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 20 6d  he xRandomness m
1fa80 65 74 68 6f 64 20 6f 66 0a 2a 2a 20 74 68 65 20  ethod of.** the 
1fa90 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33  default [sqlite3
1faa0 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a  _vfs] object..**
1fab0 20 5e 49 66 20 74 68 65 20 70 72 65 76 69 6f 75   ^If the previou
1fac0 73 20 63 61 6c 6c 20 74 6f 20 74 68 69 73 20 72  s call to this r
1fad0 6f 75 74 69 6e 65 20 68 61 64 20 61 6e 20 4e 20  outine had an N 
1fae0 6f 66 20 31 20 6f 72 20 6d 6f 72 65 20 61 6e 64  of 1 or more and
1faf0 20 61 0a 2a 2a 20 6e 6f 6e 2d 4e 55 4c 4c 20 50   a.** non-NULL P
1fb00 20 74 68 65 6e 20 74 68 65 20 70 73 65 75 64 6f   then the pseudo
1fb10 2d 72 61 6e 64 6f 6d 6e 65 73 73 20 69 73 20 67  -randomness is g
1fb20 65 6e 65 72 61 74 65 64 0a 2a 2a 20 69 6e 74 65  enerated.** inte
1fb30 72 6e 61 6c 6c 79 20 61 6e 64 20 77 69 74 68 6f  rnally and witho
1fb40 75 74 20 72 65 63 6f 75 72 73 65 20 74 6f 20 74  ut recourse to t
1fb50 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d  he [sqlite3_vfs]
1fb60 20 78 52 61 6e 64 6f 6d 6e 65 73 73 0a 2a 2a 20   xRandomness.** 
1fb70 6d 65 74 68 6f 64 2e 0a 2a 2f 0a 53 51 4c 49 54  method..*/.SQLIT
1fb80 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74  E_API void sqlit
1fb90 65 33 5f 72 61 6e 64 6f 6d 6e 65 73 73 28 69 6e  e3_randomness(in
1fba0 74 20 4e 2c 20 76 6f 69 64 20 2a 50 29 3b 0a 0a  t N, void *P);..
1fbb0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1fbc0 43 6f 6d 70 69 6c 65 2d 54 69 6d 65 20 41 75 74  Compile-Time Aut
1fbd0 68 6f 72 69 7a 61 74 69 6f 6e 20 43 61 6c 6c 62  horization Callb
1fbe0 61 63 6b 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  acks.** METHOD: 
1fbf0 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54  sqlite3.**.** ^T
1fc00 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 67 69  his routine regi
1fc10 73 74 65 72 73 20 61 6e 20 61 75 74 68 6f 72 69  sters an authori
1fc20 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 77 69 74  zer callback wit
1fc30 68 20 61 20 70 61 72 74 69 63 75 6c 61 72 0a 2a  h a particular.*
1fc40 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  * [database conn
1fc50 65 63 74 69 6f 6e 5d 2c 20 73 75 70 70 6c 69 65  ection], supplie
1fc60 64 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61  d in the first a
1fc70 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65  rgument..** ^The
1fc80 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
1fc90 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20  back is invoked 
1fca0 61 73 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  as SQL statement
1fcb0 73 20 61 72 65 20 62 65 69 6e 67 20 63 6f 6d 70  s are being comp
1fcc0 69 6c 65 64 0a 2a 2a 20 62 79 20 5b 73 71 6c 69  iled.** by [sqli
1fcd0 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f  te3_prepare()] o
1fce0 72 20 69 74 73 20 76 61 72 69 61 6e 74 73 20 5b  r its variants [
1fcf0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
1fd00 76 32 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74  v2()],.** [sqlit
1fd10 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 20  e3_prepare16()] 
1fd20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  and [sqlite3_pre
1fd30 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 20 20 5e  pare16_v2()].  ^
1fd40 41 74 20 76 61 72 69 6f 75 73 0a 2a 2a 20 70 6f  At various.** po
1fd50 69 6e 74 73 20 64 75 72 69 6e 67 20 74 68 65 20  ints during the 
1fd60 63 6f 6d 70 69 6c 61 74 69 6f 6e 20 70 72 6f 63  compilation proc
1fd70 65 73 73 2c 20 61 73 20 6c 6f 67 69 63 20 69 73  ess, as logic is
1fd80 20 62 65 69 6e 67 20 63 72 65 61 74 65 64 0a 2a   being created.*
1fd90 2a 20 74 6f 20 70 65 72 66 6f 72 6d 20 76 61 72  * to perform var
1fda0 69 6f 75 73 20 61 63 74 69 6f 6e 73 2c 20 74 68  ious actions, th
1fdb0 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
1fdc0 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64  lback is invoked
1fdd0 20 74 6f 0a 2a 2a 20 73 65 65 20 69 66 20 74 68   to.** see if th
1fde0 6f 73 65 20 61 63 74 69 6f 6e 73 20 61 72 65 20  ose actions are 
1fdf0 61 6c 6c 6f 77 65 64 2e 20 20 5e 54 68 65 20 61  allowed.  ^The a
1fe00 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
1fe10 63 6b 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74  ck should.** ret
1fe20 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20  urn [SQLITE_OK] 
1fe30 74 6f 20 61 6c 6c 6f 77 20 74 68 65 20 61 63 74  to allow the act
1fe40 69 6f 6e 2c 20 5b 53 51 4c 49 54 45 5f 49 47 4e  ion, [SQLITE_IGN
1fe50 4f 52 45 5d 20 74 6f 20 64 69 73 61 6c 6c 6f 77  ORE] to disallow
1fe60 20 74 68 65 0a 2a 2a 20 73 70 65 63 69 66 69 63   the.** specific
1fe70 20 61 63 74 69 6f 6e 20 62 75 74 20 61 6c 6c 6f   action but allo
1fe80 77 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  w the SQL statem
1fe90 65 6e 74 20 74 6f 20 63 6f 6e 74 69 6e 75 65 20  ent to continue 
1fea0 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70 69 6c 65  to be.** compile
1feb0 64 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 45  d, or [SQLITE_DE
1fec0 4e 59 5d 20 74 6f 20 63 61 75 73 65 20 74 68 65  NY] to cause the
1fed0 20 65 6e 74 69 72 65 20 53 51 4c 20 73 74 61 74   entire SQL stat
1fee0 65 6d 65 6e 74 20 74 6f 20 62 65 0a 2a 2a 20 72  ement to be.** r
1fef0 65 6a 65 63 74 65 64 20 77 69 74 68 20 61 6e 20  ejected with an 
1ff00 65 72 72 6f 72 2e 20 20 5e 49 66 20 74 68 65 20  error.  ^If the 
1ff10 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
1ff20 61 63 6b 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61  ack returns.** a
1ff30 6e 79 20 76 61 6c 75 65 20 6f 74 68 65 72 20 74  ny value other t
1ff40 68 61 6e 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f  han [SQLITE_IGNO
1ff50 52 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  RE], [SQLITE_OK]
1ff60 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e  , or [SQLITE_DEN
1ff70 59 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 5b  Y].** then the [
1ff80 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
1ff90 76 32 28 29 5d 20 6f 72 20 65 71 75 69 76 61 6c  v2()] or equival
1ffa0 65 6e 74 20 63 61 6c 6c 20 74 68 61 74 20 74 72  ent call that tr
1ffb0 69 67 67 65 72 65 64 0a 2a 2a 20 74 68 65 20 61  iggered.** the a
1ffc0 75 74 68 6f 72 69 7a 65 72 20 77 69 6c 6c 20 66  uthorizer will f
1ffd0 61 69 6c 20 77 69 74 68 20 61 6e 20 65 72 72 6f  ail with an erro
1ffe0 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 0a 2a 2a  r message..**.**
1fff0 20 57 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61   When the callba
20000 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49  ck returns [SQLI
20010 54 45 5f 4f 4b 5d 2c 20 74 68 61 74 20 6d 65 61  TE_OK], that mea
20020 6e 73 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e  ns the operation
20030 0a 2a 2a 20 72 65 71 75 65 73 74 65 64 20 69 73  .** requested is
20040 20 6f 6b 2e 20 20 5e 57 68 65 6e 20 74 68 65 20   ok.  ^When the 
20050 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73  callback returns
20060 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 2c 20   [SQLITE_DENY], 
20070 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
20080 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72  prepare_v2()] or
20090 20 65 71 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c   equivalent call
200a0 20 74 68 61 74 20 74 72 69 67 67 65 72 65 64 20   that triggered 
200b0 74 68 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65  the.** authorize
200c0 72 20 77 69 6c 6c 20 66 61 69 6c 20 77 69 74 68  r will fail with
200d0 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67   an error messag
200e0 65 20 65 78 70 6c 61 69 6e 69 6e 67 20 74 68 61  e explaining tha
200f0 74 0a 2a 2a 20 61 63 63 65 73 73 20 69 73 20 64  t.** access is d
20100 65 6e 69 65 64 2e 20 0a 2a 2a 0a 2a 2a 20 5e 54  enied. .**.** ^T
20110 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
20120 65 72 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72  er to the author
20130 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73  izer callback is
20140 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 74   a copy of the t
20150 68 69 72 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65  hird.** paramete
20160 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33  r to the sqlite3
20170 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28  _set_authorizer(
20180 29 20 69 6e 74 65 72 66 61 63 65 2e 20 5e 54 68  ) interface. ^Th
20190 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
201a0 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c  er.** to the cal
201b0 6c 62 61 63 6b 20 69 73 20 61 6e 20 69 6e 74 65  lback is an inte
201c0 67 65 72 20 5b 53 51 4c 49 54 45 5f 43 4f 50 59  ger [SQLITE_COPY
201d0 20 7c 20 61 63 74 69 6f 6e 20 63 6f 64 65 5d 20   | action code] 
201e0 74 68 61 74 20 73 70 65 63 69 66 69 65 73 0a 2a  that specifies.*
201f0 2a 20 74 68 65 20 70 61 72 74 69 63 75 6c 61 72  * the particular
20200 20 61 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 75   action to be au
20210 74 68 6f 72 69 7a 65 64 2e 20 5e 54 68 65 20 74  thorized. ^The t
20220 68 69 72 64 20 74 68 72 6f 75 67 68 20 73 69 78  hird through six
20230 74 68 20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a  th parameters.**
20240 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b   to the callback
20250 20 61 72 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e   are zero-termin
20260 61 74 65 64 20 73 74 72 69 6e 67 73 20 74 68 61  ated strings tha
20270 74 20 63 6f 6e 74 61 69 6e 20 61 64 64 69 74 69  t contain additi
20280 6f 6e 61 6c 0a 2a 2a 20 64 65 74 61 69 6c 73 20  onal.** details 
20290 61 62 6f 75 74 20 74 68 65 20 61 63 74 69 6f 6e  about the action
202a0 20 74 6f 20 62 65 20 61 75 74 68 6f 72 69 7a 65   to be authorize
202b0 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  d..**.** ^If the
202c0 20 61 63 74 69 6f 6e 20 63 6f 64 65 20 69 73 20   action code is 
202d0 5b 53 51 4c 49 54 45 5f 52 45 41 44 5d 0a 2a 2a  [SQLITE_READ].**
202e0 20 61 6e 64 20 74 68 65 20 63 61 6c 6c 62 61 63   and the callbac
202f0 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54  k returns [SQLIT
20300 45 5f 49 47 4e 4f 52 45 5d 20 74 68 65 6e 20 74  E_IGNORE] then t
20310 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20  he.** [prepared 
20320 73 74 61 74 65 6d 65 6e 74 5d 20 73 74 61 74 65  statement] state
20330 6d 65 6e 74 20 69 73 20 63 6f 6e 73 74 72 75 63  ment is construc
20340 74 65 64 20 74 6f 20 73 75 62 73 74 69 74 75 74  ted to substitut
20350 65 0a 2a 2a 20 61 20 4e 55 4c 4c 20 76 61 6c 75  e.** a NULL valu
20360 65 20 69 6e 20 70 6c 61 63 65 20 6f 66 20 74 68  e in place of th
20370 65 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74  e table column t
20380 68 61 74 20 77 6f 75 6c 64 20 68 61 76 65 0a 2a  hat would have.*
20390 2a 20 62 65 65 6e 20 72 65 61 64 20 69 66 20 5b  * been read if [
203a0 53 51 4c 49 54 45 5f 4f 4b 5d 20 68 61 64 20 62  SQLITE_OK] had b
203b0 65 65 6e 20 72 65 74 75 72 6e 65 64 2e 20 20 54  een returned.  T
203c0 68 65 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52  he [SQLITE_IGNOR
203d0 45 5d 0a 2a 2a 20 72 65 74 75 72 6e 20 63 61 6e  E].** return can
203e0 20 62 65 20 75 73 65 64 20 74 6f 20 64 65 6e 79   be used to deny
203f0 20 61 6e 20 75 6e 74 72 75 73 74 65 64 20 75 73   an untrusted us
20400 65 72 20 61 63 63 65 73 73 20 74 6f 20 69 6e 64  er access to ind
20410 69 76 69 64 75 61 6c 0a 2a 2a 20 63 6f 6c 75 6d  ividual.** colum
20420 6e 73 20 6f 66 20 61 20 74 61 62 6c 65 2e 0a 2a  ns of a table..*
20430 2a 20 5e 49 66 20 74 68 65 20 61 63 74 69 6f 6e  * ^If the action
20440 20 63 6f 64 65 20 69 73 20 5b 53 51 4c 49 54 45   code is [SQLITE
20450 5f 44 45 4c 45 54 45 5d 20 61 6e 64 20 74 68 65  _DELETE] and the
20460 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e   callback return
20470 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 47 4e  s.** [SQLITE_IGN
20480 4f 52 45 5d 20 74 68 65 6e 20 74 68 65 20 5b 44  ORE] then the [D
20490 45 4c 45 54 45 5d 20 6f 70 65 72 61 74 69 6f 6e  ELETE] operation
204a0 20 70 72 6f 63 65 65 64 73 20 62 75 74 20 74 68   proceeds but th
204b0 65 0a 2a 2a 20 5b 74 72 75 6e 63 61 74 65 20 6f  e.** [truncate o
204c0 70 74 69 6d 69 7a 61 74 69 6f 6e 5d 20 69 73 20  ptimization] is 
204d0 64 69 73 61 62 6c 65 64 20 61 6e 64 20 61 6c 6c  disabled and all
204e0 20 72 6f 77 73 20 61 72 65 20 64 65 6c 65 74 65   rows are delete
204f0 64 20 69 6e 64 69 76 69 64 75 61 6c 6c 79 2e 0a  d individually..
20500 2a 2a 0a 2a 2a 20 41 6e 20 61 75 74 68 6f 72 69  **.** An authori
20510 7a 65 72 20 69 73 20 75 73 65 64 20 77 68 65 6e  zer is used when
20520 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
20530 65 20 7c 20 70 72 65 70 61 72 69 6e 67 5d 0a 2a  e | preparing].*
20540 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  * SQL statements
20550 20 66 72 6f 6d 20 61 6e 20 75 6e 74 72 75 73 74   from an untrust
20560 65 64 20 73 6f 75 72 63 65 2c 20 74 6f 20 65 6e  ed source, to en
20570 73 75 72 65 20 74 68 61 74 20 74 68 65 20 53 51  sure that the SQ
20580 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20  L statements.** 
20590 64 6f 20 6e 6f 74 20 74 72 79 20 74 6f 20 61 63  do not try to ac
205a0 63 65 73 73 20 64 61 74 61 20 74 68 65 79 20 61  cess data they a
205b0 72 65 20 6e 6f 74 20 61 6c 6c 6f 77 65 64 20 74  re not allowed t
205c0 6f 20 73 65 65 2c 20 6f 72 20 74 68 61 74 20 74  o see, or that t
205d0 68 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a 20 74 72  hey do not.** tr
205e0 79 20 74 6f 20 65 78 65 63 75 74 65 20 6d 61 6c  y to execute mal
205f0 69 63 69 6f 75 73 20 73 74 61 74 65 6d 65 6e 74  icious statement
20600 73 20 74 68 61 74 20 64 61 6d 61 67 65 20 74 68  s that damage th
20610 65 20 64 61 74 61 62 61 73 65 2e 20 20 46 6f 72  e database.  For
20620 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 61 6e 20  .** example, an 
20630 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 61 79 20  application may 
20640 61 6c 6c 6f 77 20 61 20 75 73 65 72 20 74 6f 20  allow a user to 
20650 65 6e 74 65 72 20 61 72 62 69 74 72 61 72 79 0a  enter arbitrary.
20660 2a 2a 20 53 51 4c 20 71 75 65 72 69 65 73 20 66  ** SQL queries f
20670 6f 72 20 65 76 61 6c 75 61 74 69 6f 6e 20 62 79  or evaluation by
20680 20 61 20 64 61 74 61 62 61 73 65 2e 20 20 42 75   a database.  Bu
20690 74 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  t the applicatio
206a0 6e 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 77 61  n does.** not wa
206b0 6e 74 20 74 68 65 20 75 73 65 72 20 74 6f 20 62  nt the user to b
206c0 65 20 61 62 6c 65 20 74 6f 20 6d 61 6b 65 20 61  e able to make a
206d0 72 62 69 74 72 61 72 79 20 63 68 61 6e 67 65 73  rbitrary changes
206e0 20 74 6f 20 74 68 65 0a 2a 2a 20 64 61 74 61 62   to the.** datab
206f0 61 73 65 2e 20 20 41 6e 20 61 75 74 68 6f 72 69  ase.  An authori
20700 7a 65 72 20 63 6f 75 6c 64 20 74 68 65 6e 20 62  zer could then b
20710 65 20 70 75 74 20 69 6e 20 70 6c 61 63 65 20 77  e put in place w
20720 68 69 6c 65 20 74 68 65 0a 2a 2a 20 75 73 65 72  hile the.** user
20730 2d 65 6e 74 65 72 65 64 20 53 51 4c 20 69 73 20  -entered SQL is 
20740 62 65 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70  being [sqlite3_p
20750 72 65 70 61 72 65 20 7c 20 70 72 65 70 61 72 65  repare | prepare
20760 64 5d 20 74 68 61 74 0a 2a 2a 20 64 69 73 61 6c  d] that.** disal
20770 6c 6f 77 73 20 65 76 65 72 79 74 68 69 6e 67 20  lows everything 
20780 65 78 63 65 70 74 20 5b 53 45 4c 45 43 54 5d 20  except [SELECT] 
20790 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a  statements..**.*
207a0 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74  * Applications t
207b0 68 61 74 20 6e 65 65 64 20 74 6f 20 70 72 6f 63  hat need to proc
207c0 65 73 73 20 53 51 4c 20 66 72 6f 6d 20 75 6e 74  ess SQL from unt
207d0 72 75 73 74 65 64 20 73 6f 75 72 63 65 73 0a 2a  rusted sources.*
207e0 2a 20 6d 69 67 68 74 20 61 6c 73 6f 20 63 6f 6e  * might also con
207f0 73 69 64 65 72 20 6c 6f 77 65 72 69 6e 67 20 72  sider lowering r
20800 65 73 6f 75 72 63 65 20 6c 69 6d 69 74 73 20 75  esource limits u
20810 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6c 69  sing [sqlite3_li
20820 6d 69 74 28 29 5d 0a 2a 2a 20 61 6e 64 20 6c 69  mit()].** and li
20830 6d 69 74 69 6e 67 20 64 61 74 61 62 61 73 65 20  miting database 
20840 73 69 7a 65 20 75 73 69 6e 67 20 74 68 65 20 5b  size using the [
20850 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e 74 5d 20  max_page_count] 
20860 5b 50 52 41 47 4d 41 5d 0a 2a 2a 20 69 6e 20 61  [PRAGMA].** in a
20870 64 64 69 74 69 6f 6e 20 74 6f 20 75 73 69 6e 67  ddition to using
20880 20 61 6e 20 61 75 74 68 6f 72 69 7a 65 72 2e 0a   an authorizer..
20890 2a 2a 0a 2a 2a 20 5e 28 4f 6e 6c 79 20 61 20 73  **.** ^(Only a s
208a0 69 6e 67 6c 65 20 61 75 74 68 6f 72 69 7a 65 72  ingle authorizer
208b0 20 63 61 6e 20 62 65 20 69 6e 20 70 6c 61 63 65   can be in place
208c0 20 6f 6e 20 61 20 64 61 74 61 62 61 73 65 20 63   on a database c
208d0 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 61 74 20  onnection.** at 
208e0 61 20 74 69 6d 65 2e 20 20 45 61 63 68 20 63 61  a time.  Each ca
208f0 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 65  ll to sqlite3_se
20900 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 6f 76 65  t_authorizer ove
20910 72 72 69 64 65 73 20 74 68 65 0a 2a 2a 20 70 72  rrides the.** pr
20920 65 76 69 6f 75 73 20 63 61 6c 6c 2e 29 5e 20 20  evious call.)^  
20930 5e 44 69 73 61 62 6c 65 20 74 68 65 20 61 75 74  ^Disable the aut
20940 68 6f 72 69 7a 65 72 20 62 79 20 69 6e 73 74 61  horizer by insta
20950 6c 6c 69 6e 67 20 61 20 4e 55 4c 4c 20 63 61 6c  lling a NULL cal
20960 6c 62 61 63 6b 2e 0a 2a 2a 20 54 68 65 20 61 75  lback..** The au
20970 74 68 6f 72 69 7a 65 72 20 69 73 20 64 69 73 61  thorizer is disa
20980 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 2e  bled by default.
20990 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f  .**.** The autho
209a0 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d  rizer callback m
209b0 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68  ust not do anyth
209c0 69 6e 67 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f  ing that will mo
209d0 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 61 74 61  dify.** the data
209e0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
209f0 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65  that invoked the
20a00 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
20a10 62 61 63 6b 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68  back..** Note th
20a20 61 74 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  at [sqlite3_prep
20a30 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73  are_v2()] and [s
20a40 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 62  qlite3_step()] b
20a50 6f 74 68 20 6d 6f 64 69 66 79 20 74 68 65 69 72  oth modify their
20a60 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e  .** database con
20a70 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20 74 68 65  nections for the
20a80 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64   meaning of "mod
20a90 69 66 79 22 20 69 6e 20 74 68 69 73 20 70 61 72  ify" in this par
20aa0 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a 20 5e 57  agraph..**.** ^W
20ab0 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  hen [sqlite3_pre
20ac0 70 61 72 65 5f 76 32 28 29 5d 20 69 73 20 75 73  pare_v2()] is us
20ad0 65 64 20 74 6f 20 70 72 65 70 61 72 65 20 61 20  ed to prepare a 
20ae0 73 74 61 74 65 6d 65 6e 74 2c 20 74 68 65 0a 2a  statement, the.*
20af0 2a 20 73 74 61 74 65 6d 65 6e 74 20 6d 69 67 68  * statement migh
20b00 74 20 62 65 20 72 65 2d 70 72 65 70 61 72 65 64  t be re-prepared
20b10 20 64 75 72 69 6e 67 20 5b 73 71 6c 69 74 65 33   during [sqlite3
20b20 5f 73 74 65 70 28 29 5d 20 64 75 65 20 74 6f 20  _step()] due to 
20b30 61 20 0a 2a 2a 20 73 63 68 65 6d 61 20 63 68 61  a .** schema cha
20b40 6e 67 65 2e 20 20 48 65 6e 63 65 2c 20 74 68 65  nge.  Hence, the
20b50 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f   application sho
20b60 75 6c 64 20 65 6e 73 75 72 65 20 74 68 61 74 20  uld ensure that 
20b70 74 68 65 0a 2a 2a 20 63 6f 72 72 65 63 74 20 61  the.** correct a
20b80 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
20b90 63 6b 20 72 65 6d 61 69 6e 73 20 69 6e 20 70 6c  ck remains in pl
20ba0 61 63 65 20 64 75 72 69 6e 67 20 74 68 65 20 5b  ace during the [
20bb0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e  sqlite3_step()].
20bc0 0a 2a 2a 0a 2a 2a 20 5e 4e 6f 74 65 20 74 68 61  .**.** ^Note tha
20bd0 74 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72  t the authorizer
20be0 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76   callback is inv
20bf0 6f 6b 65 64 20 6f 6e 6c 79 20 64 75 72 69 6e 67  oked only during
20c00 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  .** [sqlite3_pre
20c10 70 61 72 65 28 29 5d 20 6f 72 20 69 74 73 20 76  pare()] or its v
20c20 61 72 69 61 6e 74 73 2e 20 20 41 75 74 68 6f 72  ariants.  Author
20c30 69 7a 61 74 69 6f 6e 20 69 73 20 6e 6f 74 0a 2a  ization is not.*
20c40 2a 20 70 65 72 66 6f 72 6d 65 64 20 64 75 72 69  * performed duri
20c50 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 65 76 61  ng statement eva
20c60 6c 75 61 74 69 6f 6e 20 69 6e 20 5b 73 71 6c 69  luation in [sqli
20c70 74 65 33 5f 73 74 65 70 28 29 5d 2c 20 75 6e 6c  te3_step()], unl
20c80 65 73 73 0a 2a 2a 20 61 73 20 73 74 61 74 65 64  ess.** as stated
20c90 20 69 6e 20 74 68 65 20 70 72 65 76 69 6f 75 73   in the previous
20ca0 20 70 61 72 61 67 72 61 70 68 2c 20 73 71 6c 69   paragraph, sqli
20cb0 74 65 33 5f 73 74 65 70 28 29 20 69 6e 76 6f 6b  te3_step() invok
20cc0 65 73 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 70 72  es.** sqlite3_pr
20cd0 65 70 61 72 65 5f 76 32 28 29 20 74 6f 20 72 65  epare_v2() to re
20ce0 70 72 65 70 61 72 65 20 61 20 73 74 61 74 65 6d  prepare a statem
20cf0 65 6e 74 20 61 66 74 65 72 20 61 20 73 63 68 65  ent after a sche
20d00 6d 61 20 63 68 61 6e 67 65 2e 0a 2a 2f 0a 53 51  ma change..*/.SQ
20d10 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
20d20 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69  ite3_set_authori
20d30 7a 65 72 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c  zer(.  sqlite3*,
20d40 0a 20 20 69 6e 74 20 28 2a 78 41 75 74 68 29 28  .  int (*xAuth)(
20d50 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20  void*,int,const 
20d60 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72  char*,const char
20d70 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f  *,const char*,co
20d80 6e 73 74 20 63 68 61 72 2a 29 2c 0a 20 20 76 6f  nst char*),.  vo
20d90 69 64 20 2a 70 55 73 65 72 44 61 74 61 0a 29 3b  id *pUserData.);
20da0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
20db0 3a 20 41 75 74 68 6f 72 69 7a 65 72 20 52 65 74  : Authorizer Ret
20dc0 75 72 6e 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20  urn Codes.**.** 
20dd0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74  The [sqlite3_set
20de0 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c 20 61 75  _authorizer | au
20df0 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
20e00 6b 20 66 75 6e 63 74 69 6f 6e 5d 20 6d 75 73 74  k function] must
20e10 0a 2a 2a 20 72 65 74 75 72 6e 20 65 69 74 68 65  .** return eithe
20e20 72 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72  r [SQLITE_OK] or
20e30 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 74 77   one of these tw
20e40 6f 20 63 6f 6e 73 74 61 6e 74 73 20 69 6e 20 6f  o constants in o
20e50 72 64 65 72 0a 2a 2a 20 74 6f 20 73 69 67 6e 61  rder.** to signa
20e60 6c 20 53 51 4c 69 74 65 20 77 68 65 74 68 65 72  l SQLite whether
20e70 20 6f 72 20 6e 6f 74 20 74 68 65 20 61 63 74 69   or not the acti
20e80 6f 6e 20 69 73 20 70 65 72 6d 69 74 74 65 64 2e  on is permitted.
20e90 20 20 53 65 65 20 74 68 65 0a 2a 2a 20 5b 73 71    See the.** [sq
20ea0 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72  lite3_set_author
20eb0 69 7a 65 72 20 7c 20 61 75 74 68 6f 72 69 7a 65  izer | authorize
20ec0 72 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 5d  r documentation]
20ed0 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a   for additional.
20ee0 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a  ** information..
20ef0 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20  **.** Note that 
20f00 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 20 69 73  SQLITE_IGNORE is
20f10 20 61 6c 73 6f 20 75 73 65 64 20 61 73 20 61 20   also used as a 
20f20 5b 63 6f 6e 66 6c 69 63 74 20 72 65 73 6f 6c 75  [conflict resolu
20f30 74 69 6f 6e 20 6d 6f 64 65 5d 0a 2a 2a 20 72 65  tion mode].** re
20f40 74 75 72 6e 65 64 20 66 72 6f 6d 20 74 68 65 20  turned from the 
20f50 5b 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 6f 6e  [sqlite3_vtab_on
20f60 5f 63 6f 6e 66 6c 69 63 74 28 29 5d 20 69 6e 74  _conflict()] int
20f70 65 72 66 61 63 65 2e 0a 2a 2f 0a 23 64 65 66 69  erface..*/.#defi
20f80 6e 65 20 53 51 4c 49 54 45 5f 44 45 4e 59 20 20  ne SQLITE_DENY  
20f90 20 31 20 20 20 2f 2a 20 41 62 6f 72 74 20 74 68   1   /* Abort th
20fa0 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  e SQL statement 
20fb0 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20 2a 2f  with an error */
20fc0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
20fd0 49 47 4e 4f 52 45 20 32 20 20 20 2f 2a 20 44 6f  IGNORE 2   /* Do
20fe0 6e 27 74 20 61 6c 6c 6f 77 20 61 63 63 65 73 73  n't allow access
20ff0 2c 20 62 75 74 20 64 6f 6e 27 74 20 67 65 6e 65  , but don't gene
21000 72 61 74 65 20 61 6e 20 65 72 72 6f 72 20 2a 2f  rate an error */
21010 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
21020 3a 20 41 75 74 68 6f 72 69 7a 65 72 20 41 63 74  : Authorizer Act
21030 69 6f 6e 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20  ion Codes.**.** 
21040 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74  The [sqlite3_set
21050 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 5d 20 69  _authorizer()] i
21060 6e 74 65 72 66 61 63 65 20 72 65 67 69 73 74 65  nterface registe
21070 72 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75  rs a callback fu
21080 6e 63 74 69 6f 6e 0a 2a 2a 20 74 68 61 74 20 69  nction.** that i
21090 73 20 69 6e 76 6f 6b 65 64 20 74 6f 20 61 75 74  s invoked to aut
210a0 68 6f 72 69 7a 65 20 63 65 72 74 61 69 6e 20 53  horize certain S
210b0 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 61 63 74  QL statement act
210c0 69 6f 6e 73 2e 20 20 54 68 65 0a 2a 2a 20 73 65  ions.  The.** se
210d0 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74  cond parameter t
210e0 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69  o the callback i
210f0 73 20 61 6e 20 69 6e 74 65 67 65 72 20 63 6f 64  s an integer cod
21100 65 20 74 68 61 74 20 73 70 65 63 69 66 69 65 73  e that specifies
21110 0a 2a 2a 20 77 68 61 74 20 61 63 74 69 6f 6e 20  .** what action 
21120 69 73 20 62 65 69 6e 67 20 61 75 74 68 6f 72 69  is being authori
21130 7a 65 64 2e 20 20 54 68 65 73 65 20 61 72 65 20  zed.  These are 
21140 74 68 65 20 69 6e 74 65 67 65 72 20 61 63 74 69  the integer acti
21150 6f 6e 20 63 6f 64 65 73 20 74 68 61 74 0a 2a 2a  on codes that.**
21160 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   the authorizer 
21170 63 61 6c 6c 62 61 63 6b 20 6d 61 79 20 62 65 20  callback may be 
21180 70 61 73 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  passed..**.** Th
21190 65 73 65 20 61 63 74 69 6f 6e 20 63 6f 64 65 20  ese action code 
211a0 76 61 6c 75 65 73 20 73 69 67 6e 69 66 79 20 77  values signify w
211b0 68 61 74 20 6b 69 6e 64 20 6f 66 20 6f 70 65 72  hat kind of oper
211c0 61 74 69 6f 6e 20 69 73 20 74 6f 20 62 65 0a 2a  ation is to be.*
211d0 2a 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 20 54  * authorized.  T
211e0 68 65 20 33 72 64 20 61 6e 64 20 34 74 68 20 70  he 3rd and 4th p
211f0 61 72 61 6d 65 74 65 72 73 20 74 6f 20 74 68 65  arameters to the
21200 20 61 75 74 68 6f 72 69 7a 61 74 69 6f 6e 0a 2a   authorization.*
21210 2a 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  * callback funct
21220 69 6f 6e 20 77 69 6c 6c 20 62 65 20 70 61 72 61  ion will be para
21230 6d 65 74 65 72 73 20 6f 72 20 4e 55 4c 4c 20 64  meters or NULL d
21240 65 70 65 6e 64 69 6e 67 20 6f 6e 20 77 68 69 63  epending on whic
21250 68 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 63 6f  h of these.** co
21260 64 65 73 20 69 73 20 75 73 65 64 20 61 73 20 74  des is used as t
21270 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
21280 74 65 72 2e 20 20 5e 28 54 68 65 20 35 74 68 20  ter.  ^(The 5th 
21290 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
212a0 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 72 20 63  .** authorizer c
212b0 61 6c 6c 62 61 63 6b 20 69 73 20 74 68 65 20 6e  allback is the n
212c0 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61 62  ame of the datab
212d0 61 73 65 20 28 22 6d 61 69 6e 22 2c 20 22 74 65  ase ("main", "te
212e0 6d 70 22 2c 0a 2a 2a 20 65 74 63 2e 29 20 69 66  mp",.** etc.) if
212f0 20 61 70 70 6c 69 63 61 62 6c 65 2e 29 5e 20 20   applicable.)^  
21300 5e 54 68 65 20 36 74 68 20 70 61 72 61 6d 65 74  ^The 6th paramet
21310 65 72 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72  er to the author
21320 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a  izer callback.**
21330 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20   is the name of 
21340 74 68 65 20 69 6e 6e 65 72 2d 6d 6f 73 74 20 74  the inner-most t
21350 72 69 67 67 65 72 20 6f 72 20 76 69 65 77 20 74  rigger or view t
21360 68 61 74 20 69 73 20 72 65 73 70 6f 6e 73 69 62  hat is responsib
21370 6c 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 61 63  le for.** the ac
21380 63 65 73 73 20 61 74 74 65 6d 70 74 20 6f 72 20  cess attempt or 
21390 4e 55 4c 4c 20 69 66 20 74 68 69 73 20 61 63 63  NULL if this acc
213a0 65 73 73 20 61 74 74 65 6d 70 74 20 69 73 20 64  ess attempt is d
213b0 69 72 65 63 74 6c 79 20 66 72 6f 6d 0a 2a 2a 20  irectly from.** 
213c0 74 6f 70 2d 6c 65 76 65 6c 20 53 51 4c 20 63 6f  top-level SQL co
213d0 64 65 2e 0a 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a  de..*/./********
213e0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
213f0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
21400 2a 2a 2a 20 33 72 64 20 2a 2a 2a 2a 2a 2a 2a 2a  *** 3rd ********
21410 2a 2a 2a 2a 20 34 74 68 20 2a 2a 2a 2a 2a 2a 2a  **** 4th *******
21420 2a 2a 2a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ****/.#define SQ
21430 4c 49 54 45 5f 43 52 45 41 54 45 5f 49 4e 44 45  LITE_CREATE_INDE
21440 58 20 20 20 20 20 20 20 20 20 20 31 20 20 20 2f  X          1   /
21450 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20  * Index Name    
21460 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20    Table Name    
21470 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
21480 49 54 45 5f 43 52 45 41 54 45 5f 54 41 42 4c 45  ITE_CREATE_TABLE
21490 20 20 20 20 20 20 20 20 20 20 32 20 20 20 2f 2a            2   /*
214a0 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
214b0 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
214c0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
214d0 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 49  TE_CREATE_TEMP_I
214e0 4e 44 45 58 20 20 20 20 20 33 20 20 20 2f 2a 20  NDEX     3   /* 
214f0 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20  Index Name      
21500 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
21510 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
21520 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 54 41  E_CREATE_TEMP_TA
21530 42 4c 45 20 20 20 20 20 34 20 20 20 2f 2a 20 54  BLE     4   /* T
21540 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e  able Name      N
21550 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
21560 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
21570 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 54 52 49  _CREATE_TEMP_TRI
21580 47 47 45 52 20 20 20 35 20 20 20 2f 2a 20 54 72  GGER   5   /* Tr
21590 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61  igger Name    Ta
215a0 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f  ble Name      */
215b0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
215c0 43 52 45 41 54 45 5f 54 45 4d 50 5f 56 49 45 57  CREATE_TEMP_VIEW
215d0 20 20 20 20 20 20 36 20 20 20 2f 2a 20 56 69 65        6   /* Vie
215e0 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c  w Name       NUL
215f0 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
21600 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
21610 52 45 41 54 45 5f 54 52 49 47 47 45 52 20 20 20  REATE_TRIGGER   
21620 20 20 20 20 20 37 20 20 20 2f 2a 20 54 72 69 67       7   /* Trig
21630 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c  ger Name    Tabl
21640 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23  e Name      */.#
21650 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52  define SQLITE_CR
21660 45 41 54 45 5f 56 49 45 57 20 20 20 20 20 20 20  EATE_VIEW       
21670 20 20 20 20 38 20 20 20 2f 2a 20 56 69 65 77 20      8   /* View 
21680 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20  Name       NULL 
21690 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
216a0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 4c  efine SQLITE_DEL
216b0 45 54 45 20 20 20 20 20 20 20 20 20 20 20 20 20  ETE             
216c0 20 20 20 39 20 20 20 2f 2a 20 54 61 62 6c 65 20     9   /* Table 
216d0 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20  Name      NULL  
216e0 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
216f0 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50  fine SQLITE_DROP
21700 5f 49 4e 44 45 58 20 20 20 20 20 20 20 20 20 20  _INDEX          
21710 20 31 30 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e   10   /* Index N
21720 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e  ame      Table N
21730 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66  ame      */.#def
21740 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f  ine SQLITE_DROP_
21750 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 20  TABLE           
21760 31 31 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61  11   /* Table Na
21770 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  me      NULL    
21780 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
21790 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54  ne SQLITE_DROP_T
217a0 45 4d 50 5f 49 4e 44 45 58 20 20 20 20 20 20 31  EMP_INDEX      1
217b0 32 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d  2   /* Index Nam
217c0 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d  e      Table Nam
217d0 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  e      */.#defin
217e0 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45  e SQLITE_DROP_TE
217f0 4d 50 5f 54 41 42 4c 45 20 20 20 20 20 20 31 33  MP_TABLE      13
21800 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
21810 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
21820 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
21830 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d   SQLITE_DROP_TEM
21840 50 5f 54 52 49 47 47 45 52 20 20 20 20 31 34 20  P_TRIGGER    14 
21850 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d    /* Trigger Nam
21860 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20  e    Table Name 
21870 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
21880 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50  SQLITE_DROP_TEMP
21890 5f 56 49 45 57 20 20 20 20 20 20 20 31 35 20 20  _VIEW       15  
218a0 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20   /* View Name   
218b0 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
218c0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
218d0 51 4c 49 54 45 5f 44 52 4f 50 5f 54 52 49 47 47  QLITE_DROP_TRIGG
218e0 45 52 20 20 20 20 20 20 20 20 20 31 36 20 20 20  ER         16   
218f0 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20  /* Trigger Name 
21900 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20     Table Name   
21910 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
21920 4c 49 54 45 5f 44 52 4f 50 5f 56 49 45 57 20 20  LITE_DROP_VIEW  
21930 20 20 20 20 20 20 20 20 20 20 31 37 20 20 20 2f            17   /
21940 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20  * View Name     
21950 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
21960 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
21970 49 54 45 5f 49 4e 53 45 52 54 20 20 20 20 20 20  ITE_INSERT      
21980 20 20 20 20 20 20 20 20 20 31 38 20 20 20 2f 2a           18   /*
21990 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
219a0 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
219b0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
219c0 54 45 5f 50 52 41 47 4d 41 20 20 20 20 20 20 20  TE_PRAGMA       
219d0 20 20 20 20 20 20 20 20 31 39 20 20 20 2f 2a 20          19   /* 
219e0 50 72 61 67 6d 61 20 4e 61 6d 65 20 20 20 20 20  Pragma Name     
219f0 31 73 74 20 61 72 67 20 6f 72 20 4e 55 4c 4c 20  1st arg or NULL 
21a00 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
21a10 45 5f 52 45 41 44 20 20 20 20 20 20 20 20 20 20  E_READ          
21a20 20 20 20 20 20 20 20 32 30 20 20 20 2f 2a 20 54         20   /* T
21a30 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 43  able Name      C
21a40 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20 20 2a  olumn Name     *
21a50 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
21a60 5f 53 45 4c 45 43 54 20 20 20 20 20 20 20 20 20  _SELECT         
21a70 20 20 20 20 20 20 32 31 20 20 20 2f 2a 20 4e 55        21   /* NU
21a80 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 4e 55  LL            NU
21a90 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
21aa0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
21ab0 54 52 41 4e 53 41 43 54 49 4f 4e 20 20 20 20 20  TRANSACTION     
21ac0 20 20 20 20 20 32 32 20 20 20 2f 2a 20 4f 70 65       22   /* Ope
21ad0 72 61 74 69 6f 6e 20 20 20 20 20 20 20 4e 55 4c  ration       NUL
21ae0 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
21af0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55  #define SQLITE_U
21b00 50 44 41 54 45 20 20 20 20 20 20 20 20 20 20 20  PDATE           
21b10 20 20 20 20 32 33 20 20 20 2f 2a 20 54 61 62 6c      23   /* Tabl
21b20 65 20 4e 61 6d 65 20 20 20 20 20 20 43 6f 6c 75  e Name      Colu
21b30 6d 6e 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23  mn Name     */.#
21b40 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 54  define SQLITE_AT
21b50 54 41 43 48 20 20 20 20 20 20 20 20 20 20 20 20  TACH            
21b60 20 20 20 32 34 20 20 20 2f 2a 20 46 69 6c 65 6e     24   /* Filen
21b70 61 6d 65 20 20 20 20 20 20 20 20 4e 55 4c 4c 20  ame        NULL 
21b80 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
21b90 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 54  efine SQLITE_DET
21ba0 41 43 48 20 20 20 20 20 20 20 20 20 20 20 20 20  ACH             
21bb0 20 20 32 35 20 20 20 2f 2a 20 44 61 74 61 62 61    25   /* Databa
21bc0 73 65 20 4e 61 6d 65 20 20 20 4e 55 4c 4c 20 20  se Name   NULL  
21bd0 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
21be0 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4c 54 45  fine SQLITE_ALTE
21bf0 52 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20 20  R_TABLE         
21c00 20 32 36 20 20 20 2f 2a 20 44 61 74 61 62 61 73   26   /* Databas
21c10 65 20 4e 61 6d 65 20 20 20 54 61 62 6c 65 20 4e  e Name   Table N
21c20 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66  ame      */.#def
21c30 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 49 4e 44  ine SQLITE_REIND
21c40 45 58 20 20 20 20 20 20 20 20 20 20 20 20 20 20  EX              
21c50 32 37 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61  27   /* Index Na
21c60 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  me      NULL    
21c70 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
21c80 6e 65 20 53 51 4c 49 54 45 5f 41 4e 41 4c 59 5a  ne SQLITE_ANALYZ
21c90 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32  E              2
21ca0 38 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  8   /* Table Nam
21cb0 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20  e      NULL     
21cc0 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
21cd0 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f  e SQLITE_CREATE_
21ce0 56 54 41 42 4c 45 20 20 20 20 20 20 20 20 32 39  VTABLE        29
21cf0 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
21d00 20 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e 61 6d        Module Nam
21d10 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65  e     */.#define
21d20 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56 54 41   SQLITE_DROP_VTA
21d30 42 4c 45 20 20 20 20 20 20 20 20 20 20 33 30 20  BLE          30 
21d40 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20    /* Table Name 
21d50 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e 61 6d 65       Module Name
21d60 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
21d70 53 51 4c 49 54 45 5f 46 55 4e 43 54 49 4f 4e 20  SQLITE_FUNCTION 
21d80 20 20 20 20 20 20 20 20 20 20 20 20 33 31 20 20              31  
21d90 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20 20   /* NULL        
21da0 20 20 20 20 46 75 6e 63 74 69 6f 6e 20 4e 61 6d      Function Nam
21db0 65 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  e   */.#define S
21dc0 51 4c 49 54 45 5f 53 41 56 45 50 4f 49 4e 54 20  QLITE_SAVEPOINT 
21dd0 20 20 20 20 20 20 20 20 20 20 20 33 32 20 20 20             32   
21de0 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20 20 20 20  /* Operation    
21df0 20 20 20 53 61 76 65 70 6f 69 6e 74 20 4e 61 6d     Savepoint Nam
21e00 65 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  e  */.#define SQ
21e10 4c 49 54 45 5f 43 4f 50 59 20 20 20 20 20 20 20  LITE_COPY       
21e20 20 20 20 20 20 20 20 20 20 20 20 30 20 20 20 2f             0   /
21e30 2a 20 4e 6f 20 6c 6f 6e 67 65 72 20 75 73 65 64  * No longer used
21e40 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
21e50 54 45 5f 52 45 43 55 52 53 49 56 45 20 20 20 20  TE_RECURSIVE    
21e60 20 20 20 20 20 20 20 20 33 33 20 20 20 2f 2a 20          33   /* 
21e70 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
21e80 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
21e90 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  */../*.** CAPI3R
21ea0 45 46 3a 20 54 72 61 63 69 6e 67 20 41 6e 64 20  EF: Tracing And 
21eb0 50 72 6f 66 69 6c 69 6e 67 20 46 75 6e 63 74 69  Profiling Functi
21ec0 6f 6e 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  ons.** METHOD: s
21ed0 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 54 68 65  qlite3.**.** The
21ee0 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20  se routines are 
21ef0 64 65 70 72 65 63 61 74 65 64 2e 20 55 73 65 20  deprecated. Use 
21f00 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 74 72 61  the [sqlite3_tra
21f10 63 65 5f 76 32 28 29 5d 20 69 6e 74 65 72 66 61  ce_v2()] interfa
21f20 63 65 0a 2a 2a 20 69 6e 73 74 65 61 64 20 6f 66  ce.** instead of
21f30 20 74 68 65 20 72 6f 75 74 69 6e 65 73 20 64 65   the routines de
21f40 73 63 72 69 62 65 64 20 68 65 72 65 2e 0a 2a 2a  scribed here..**
21f50 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
21f60 65 73 20 72 65 67 69 73 74 65 72 20 63 61 6c 6c  es register call
21f70 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 73 20 74  back functions t
21f80 68 61 74 20 63 61 6e 20 62 65 20 75 73 65 64 20  hat can be used 
21f90 66 6f 72 0a 2a 2a 20 74 72 61 63 69 6e 67 20 61  for.** tracing a
21fa0 6e 64 20 70 72 6f 66 69 6c 69 6e 67 20 74 68 65  nd profiling the
21fb0 20 65 78 65 63 75 74 69 6f 6e 20 6f 66 20 53 51   execution of SQ
21fc0 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a  L statements..**
21fd0 0a 2a 2a 20 5e 54 68 65 20 63 61 6c 6c 62 61 63  .** ^The callbac
21fe0 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 67 69 73  k function regis
21ff0 74 65 72 65 64 20 62 79 20 73 71 6c 69 74 65 33  tered by sqlite3
22000 5f 74 72 61 63 65 28 29 20 69 73 20 69 6e 76 6f  _trace() is invo
22010 6b 65 64 20 61 74 0a 2a 2a 20 76 61 72 69 6f 75  ked at.** variou
22020 73 20 74 69 6d 65 73 20 77 68 65 6e 20 61 6e 20  s times when an 
22030 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 73  SQL statement is
22040 20 62 65 69 6e 67 20 72 75 6e 20 62 79 20 5b 73   being run by [s
22050 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a  qlite3_step()]..
22060 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
22070 74 72 61 63 65 28 29 20 63 61 6c 6c 62 61 63 6b  trace() callback
22080 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 69 74 68   is invoked with
22090 20 61 20 55 54 46 2d 38 20 72 65 6e 64 65 72 69   a UTF-8 renderi
220a0 6e 67 20 6f 66 20 74 68 65 0a 2a 2a 20 53 51 4c  ng of the.** SQL
220b0 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20   statement text 
220c0 61 73 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  as the statement
220d0 20 66 69 72 73 74 20 62 65 67 69 6e 73 20 65 78   first begins ex
220e0 65 63 75 74 69 6e 67 2e 0a 2a 2a 20 5e 28 41 64  ecuting..** ^(Ad
220f0 64 69 74 69 6f 6e 61 6c 20 73 71 6c 69 74 65 33  ditional sqlite3
22100 5f 74 72 61 63 65 28 29 20 63 61 6c 6c 62 61 63  _trace() callbac
22110 6b 73 20 6d 69 67 68 74 20 6f 63 63 75 72 0a 2a  ks might occur.*
22120 2a 20 61 73 20 65 61 63 68 20 74 72 69 67 67 65  * as each trigge
22130 72 65 64 20 73 75 62 70 72 6f 67 72 61 6d 20 69  red subprogram i
22140 73 20 65 6e 74 65 72 65 64 2e 20 20 54 68 65 20  s entered.  The 
22150 63 61 6c 6c 62 61 63 6b 73 20 66 6f 72 20 74 72  callbacks for tr
22160 69 67 67 65 72 73 0a 2a 2a 20 63 6f 6e 74 61 69  iggers.** contai
22170 6e 20 61 20 55 54 46 2d 38 20 53 51 4c 20 63 6f  n a UTF-8 SQL co
22180 6d 6d 65 6e 74 20 74 68 61 74 20 69 64 65 6e 74  mment that ident
22190 69 66 69 65 73 20 74 68 65 20 74 72 69 67 67 65  ifies the trigge
221a0 72 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b  r.)^.**.** The [
221b0 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 53 49 5a  SQLITE_TRACE_SIZ
221c0 45 5f 4c 49 4d 49 54 5d 20 63 6f 6d 70 69 6c 65  E_LIMIT] compile
221d0 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 63 61 6e  -time option can
221e0 20 62 65 20 75 73 65 64 20 74 6f 20 6c 69 6d 69   be used to limi
221f0 74 0a 2a 2a 20 74 68 65 20 6c 65 6e 67 74 68 20  t.** the length 
22200 6f 66 20 5b 62 6f 75 6e 64 20 70 61 72 61 6d 65  of [bound parame
22210 74 65 72 5d 20 65 78 70 61 6e 73 69 6f 6e 20 69  ter] expansion i
22220 6e 20 74 68 65 20 6f 75 74 70 75 74 20 6f 66 20  n the output of 
22230 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 2e  sqlite3_trace().
22240 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 61 6c 6c  .**.** ^The call
22250 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65  back function re
22260 67 69 73 74 65 72 65 64 20 62 79 20 73 71 6c 69  gistered by sqli
22270 74 65 33 5f 70 72 6f 66 69 6c 65 28 29 20 69 73  te3_profile() is
22280 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61 73 20 65   invoked.** as e
22290 61 63 68 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ach SQL statemen
222a0 74 20 66 69 6e 69 73 68 65 73 2e 20 20 5e 54 68  t finishes.  ^Th
222b0 65 20 70 72 6f 66 69 6c 65 20 63 61 6c 6c 62 61  e profile callba
222c0 63 6b 20 63 6f 6e 74 61 69 6e 73 0a 2a 2a 20 74  ck contains.** t
222d0 68 65 20 6f 72 69 67 69 6e 61 6c 20 73 74 61 74  he original stat
222e0 65 6d 65 6e 74 20 74 65 78 74 20 61 6e 64 20 61  ement text and a
222f0 6e 20 65 73 74 69 6d 61 74 65 20 6f 66 20 77 61  n estimate of wa
22300 6c 6c 2d 63 6c 6f 63 6b 20 74 69 6d 65 0a 2a 2a  ll-clock time.**
22310 20 6f 66 20 68 6f 77 20 6c 6f 6e 67 20 74 68 61   of how long tha
22320 74 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 6f 6b  t statement took
22330 20 74 6f 20 72 75 6e 2e 20 20 5e 54 68 65 20 70   to run.  ^The p
22340 72 6f 66 69 6c 65 20 63 61 6c 6c 62 61 63 6b 0a  rofile callback.
22350 2a 2a 20 74 69 6d 65 20 69 73 20 69 6e 20 75 6e  ** time is in un
22360 69 74 73 20 6f 66 20 6e 61 6e 6f 73 65 63 6f 6e  its of nanosecon
22370 64 73 2c 20 68 6f 77 65 76 65 72 20 74 68 65 20  ds, however the 
22380 63 75 72 72 65 6e 74 20 69 6d 70 6c 65 6d 65 6e  current implemen
22390 74 61 74 69 6f 6e 0a 2a 2a 20 69 73 20 6f 6e 6c  tation.** is onl
223a0 79 20 63 61 70 61 62 6c 65 20 6f 66 20 6d 69 6c  y capable of mil
223b0 6c 69 73 65 63 6f 6e 64 20 72 65 73 6f 6c 75 74  lisecond resolut
223c0 69 6f 6e 20 73 6f 20 74 68 65 20 73 69 78 20 6c  ion so the six l
223d0 65 61 73 74 20 73 69 67 6e 69 66 69 63 61 6e 74  east significant
223e0 0a 2a 2a 20 64 69 67 69 74 73 20 69 6e 20 74 68  .** digits in th
223f0 65 20 74 69 6d 65 20 61 72 65 20 6d 65 61 6e 69  e time are meani
22400 6e 67 6c 65 73 73 2e 20 20 46 75 74 75 72 65 20  ngless.  Future 
22410 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69  versions of SQLi
22420 74 65 0a 2a 2a 20 6d 69 67 68 74 20 70 72 6f 76  te.** might prov
22430 69 64 65 20 67 72 65 61 74 65 72 20 72 65 73 6f  ide greater reso
22440 6c 75 74 69 6f 6e 20 6f 6e 20 74 68 65 20 70 72  lution on the pr
22450 6f 66 69 6c 65 72 20 63 61 6c 6c 62 61 63 6b 2e  ofiler callback.
22460 20 20 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33    The.** sqlite3
22470 5f 70 72 6f 66 69 6c 65 28 29 20 66 75 6e 63 74  _profile() funct
22480 69 6f 6e 20 69 73 20 63 6f 6e 73 69 64 65 72 65  ion is considere
22490 64 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 61  d experimental a
224a0 6e 64 20 69 73 0a 2a 2a 20 73 75 62 6a 65 63 74  nd is.** subject
224b0 20 74 6f 20 63 68 61 6e 67 65 20 69 6e 20 66 75   to change in fu
224c0 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66  ture versions of
224d0 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 53 51 4c 49   SQLite..*/.SQLI
224e0 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 44 45  TE_API SQLITE_DE
224f0 50 52 45 43 41 54 45 44 20 76 6f 69 64 20 2a 73  PRECATED void *s
22500 71 6c 69 74 65 33 5f 74 72 61 63 65 28 73 71 6c  qlite3_trace(sql
22510 69 74 65 33 2a 2c 0a 20 20 20 76 6f 69 64 28 2a  ite3*,.   void(*
22520 78 54 72 61 63 65 29 28 76 6f 69 64 2a 2c 63 6f  xTrace)(void*,co
22530 6e 73 74 20 63 68 61 72 2a 29 2c 20 76 6f 69 64  nst char*), void
22540 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 53  *);.SQLITE_API S
22550 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44  QLITE_DEPRECATED
22560 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 70   void *sqlite3_p
22570 72 6f 66 69 6c 65 28 73 71 6c 69 74 65 33 2a 2c  rofile(sqlite3*,
22580 0a 20 20 20 76 6f 69 64 28 2a 78 50 72 6f 66 69  .   void(*xProfi
22590 6c 65 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20  le)(void*,const 
225a0 63 68 61 72 2a 2c 73 71 6c 69 74 65 33 5f 75 69  char*,sqlite3_ui
225b0 6e 74 36 34 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a  nt64), void*);..
225c0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
225d0 53 51 4c 20 54 72 61 63 65 20 45 76 65 6e 74 20  SQL Trace Event 
225e0 43 6f 64 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44  Codes.** KEYWORD
225f0 53 3a 20 53 51 4c 49 54 45 5f 54 52 41 43 45 0a  S: SQLITE_TRACE.
22600 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73  **.** These cons
22610 74 61 6e 74 73 20 69 64 65 6e 74 69 66 79 20 63  tants identify c
22620 6c 61 73 73 65 73 20 6f 66 20 65 76 65 6e 74 73  lasses of events
22630 20 74 68 61 74 20 63 61 6e 20 62 65 20 6d 6f 6e   that can be mon
22640 69 74 6f 72 65 64 0a 2a 2a 20 75 73 69 6e 67 20  itored.** using 
22650 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 74 72 61  the [sqlite3_tra
22660 63 65 5f 76 32 28 29 5d 20 74 72 61 63 69 6e 67  ce_v2()] tracing
22670 20 6c 6f 67 69 63 2e 20 20 54 68 65 20 74 68 69   logic.  The thi
22680 72 64 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74  rd argument.** t
22690 6f 20 5b 73 71 6c 69 74 65 33 5f 74 72 61 63 65  o [sqlite3_trace
226a0 5f 76 32 28 29 5d 20 69 73 20 61 6e 20 4f 52 2d  _v2()] is an OR-
226b0 65 64 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 6f  ed combination o
226c0 66 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6f 66  f one or more of
226d0 0a 2a 2a 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e  .** the followin
226e0 67 20 63 6f 6e 73 74 61 6e 74 73 2e 20 20 5e 54  g constants.  ^T
226f0 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
22700 74 20 74 6f 20 74 68 65 20 74 72 61 63 65 20 63  t to the trace c
22710 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 6f 6e  allback.** is on
22720 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69  e of the followi
22730 6e 67 20 63 6f 6e 73 74 61 6e 74 73 2e 0a 2a 2a  ng constants..**
22740 0a 2a 2a 20 4e 65 77 20 74 72 61 63 69 6e 67 20  .** New tracing 
22750 63 6f 6e 73 74 61 6e 74 73 20 6d 61 79 20 62 65  constants may be
22760 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65   added in future
22770 20 72 65 6c 65 61 73 65 73 2e 0a 2a 2a 0a 2a 2a   releases..**.**
22780 20 5e 41 20 74 72 61 63 65 20 63 61 6c 6c 62 61   ^A trace callba
22790 63 6b 20 68 61 73 20 66 6f 75 72 20 61 72 67 75  ck has four argu
227a0 6d 65 6e 74 73 3a 20 78 43 61 6c 6c 62 61 63 6b  ments: xCallback
227b0 28 54 2c 43 2c 50 2c 58 29 2e 0a 2a 2a 20 5e 54  (T,C,P,X)..** ^T
227c0 68 65 20 54 20 61 72 67 75 6d 65 6e 74 20 69 73  he T argument is
227d0 20 6f 6e 65 20 6f 66 20 74 68 65 20 69 6e 74 65   one of the inte
227e0 67 65 72 20 74 79 70 65 20 63 6f 64 65 73 20 61  ger type codes a
227f0 62 6f 76 65 2e 0a 2a 2a 20 5e 54 68 65 20 43 20  bove..** ^The C 
22800 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 63 6f  argument is a co
22810 70 79 20 6f 66 20 74 68 65 20 63 6f 6e 74 65 78  py of the contex
22820 74 20 70 6f 69 6e 74 65 72 20 70 61 73 73 65 64  t pointer passed
22830 20 69 6e 20 61 73 20 74 68 65 0a 2a 2a 20 66 6f   in as the.** fo
22840 75 72 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f  urth argument to
22850 20 5b 73 71 6c 69 74 65 33 5f 74 72 61 63 65 5f   [sqlite3_trace_
22860 76 32 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 50 20  v2()]..** The P 
22870 61 6e 64 20 58 20 61 72 67 75 6d 65 6e 74 73 20  and X arguments 
22880 61 72 65 20 70 6f 69 6e 74 65 72 73 20 77 68 6f  are pointers who
22890 73 65 20 6d 65 61 6e 69 6e 67 73 20 64 65 70 65  se meanings depe
228a0 6e 64 20 6f 6e 20 54 2e 0a 2a 2a 0a 2a 2a 20 3c  nd on T..**.** <
228b0 64 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  dl>.** [[SQLITE_
228c0 54 52 41 43 45 5f 53 54 4d 54 5d 5d 20 3c 64 74  TRACE_STMT]] <dt
228d0 3e 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 53 54  >SQLITE_TRACE_ST
228e0 4d 54 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 5e  MT</dt>.** <dd>^
228f0 41 6e 20 53 51 4c 49 54 45 5f 54 52 41 43 45 5f  An SQLITE_TRACE_
22900 53 54 4d 54 20 63 61 6c 6c 62 61 63 6b 20 69 73  STMT callback is
22910 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 61 20   invoked when a 
22920 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
22930 6e 74 0a 2a 2a 20 66 69 72 73 74 20 62 65 67 69  nt.** first begi
22940 6e 73 20 72 75 6e 6e 69 6e 67 20 61 6e 64 20 70  ns running and p
22950 6f 73 73 69 62 6c 79 20 61 74 20 6f 74 68 65 72  ossibly at other
22960 20 74 69 6d 65 73 20 64 75 72 69 6e 67 20 74 68   times during th
22970 65 0a 2a 2a 20 65 78 65 63 75 74 69 6f 6e 20 6f  e.** execution o
22980 66 20 74 68 65 20 70 72 65 70 61 72 65 64 20 73  f the prepared s
22990 74 61 74 65 6d 65 6e 74 2c 20 73 75 63 68 20 61  tatement, such a
229a0 73 20 61 74 20 74 68 65 20 73 74 61 72 74 20 6f  s at the start o
229b0 66 20 65 61 63 68 0a 2a 2a 20 74 72 69 67 67 65  f each.** trigge
229c0 72 20 73 75 62 70 72 6f 67 72 61 6d 2e 20 5e 54  r subprogram. ^T
229d0 68 65 20 50 20 61 72 67 75 6d 65 6e 74 20 69 73  he P argument is
229e0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   a pointer to th
229f0 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73  e.** [prepared s
22a00 74 61 74 65 6d 65 6e 74 5d 2e 20 5e 54 68 65 20  tatement]. ^The 
22a10 58 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20  X argument is a 
22a20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 73 74 72  pointer to a str
22a30 69 6e 67 20 77 68 69 63 68 0a 2a 2a 20 69 73 20  ing which.** is 
22a40 74 68 65 20 75 6e 65 78 70 61 6e 64 65 64 20 53  the unexpanded S
22a50 51 4c 20 74 65 78 74 20 6f 66 20 74 68 65 20 70  QL text of the p
22a60 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
22a70 74 20 6f 72 20 61 6e 20 53 51 4c 20 63 6f 6d 6d  t or an SQL comm
22a80 65 6e 74 20 0a 2a 2a 20 74 68 61 74 20 69 6e 64  ent .** that ind
22a90 69 63 61 74 65 73 20 74 68 65 20 69 6e 76 6f 63  icates the invoc
22aa0 61 74 69 6f 6e 20 6f 66 20 61 20 74 72 69 67 67  ation of a trigg
22ab0 65 72 2e 20 20 5e 54 68 65 20 63 61 6c 6c 62 61  er.  ^The callba
22ac0 63 6b 20 63 61 6e 20 63 6f 6d 70 75 74 65 0a 2a  ck can compute.*
22ad0 2a 20 74 68 65 20 73 61 6d 65 20 74 65 78 74 20  * the same text 
22ae0 74 68 61 74 20 77 6f 75 6c 64 20 68 61 76 65 20  that would have 
22af0 62 65 65 6e 20 72 65 74 75 72 6e 65 64 20 62 79  been returned by
22b00 20 74 68 65 20 6c 65 67 61 63 79 20 5b 73 71 6c   the legacy [sql
22b10 69 74 65 33 5f 74 72 61 63 65 28 29 5d 0a 2a 2a  ite3_trace()].**
22b20 20 69 6e 74 65 72 66 61 63 65 20 62 79 20 75 73   interface by us
22b30 69 6e 67 20 74 68 65 20 58 20 61 72 67 75 6d 65  ing the X argume
22b40 6e 74 20 77 68 65 6e 20 58 20 62 65 67 69 6e 73  nt when X begins
22b50 20 77 69 74 68 20 22 2d 2d 22 20 61 6e 64 20 69   with "--" and i
22b60 6e 76 6f 6b 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69  nvoking.** [sqli
22b70 74 65 33 5f 65 78 70 61 6e 64 65 64 5f 73 71 6c  te3_expanded_sql
22b80 28 50 29 5d 20 6f 74 68 65 72 77 69 73 65 2e 0a  (P)] otherwise..
22b90 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 54  **.** [[SQLITE_T
22ba0 52 41 43 45 5f 50 52 4f 46 49 4c 45 5d 5d 20 3c  RACE_PROFILE]] <
22bb0 64 74 3e 53 51 4c 49 54 45 5f 54 52 41 43 45 5f  dt>SQLITE_TRACE_
22bc0 50 52 4f 46 49 4c 45 3c 2f 64 74 3e 0a 2a 2a 20  PROFILE</dt>.** 
22bd0 3c 64 64 3e 5e 41 6e 20 53 51 4c 49 54 45 5f 54  <dd>^An SQLITE_T
22be0 52 41 43 45 5f 50 52 4f 46 49 4c 45 20 63 61 6c  RACE_PROFILE cal
22bf0 6c 62 61 63 6b 20 70 72 6f 76 69 64 65 73 20 61  lback provides a
22c00 70 70 72 6f 78 69 6d 61 74 65 6c 79 20 74 68 65  pproximately the
22c10 20 73 61 6d 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61   same.** informa
22c20 74 69 6f 6e 20 61 73 20 69 73 20 70 72 6f 76 69  tion as is provi
22c30 64 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69  ded by the [sqli
22c40 74 65 33 5f 70 72 6f 66 69 6c 65 28 29 5d 20 63  te3_profile()] c
22c50 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 5e 54 68 65  allback..** ^The
22c60 20 50 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61   P argument is a
22c70 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20   pointer to the 
22c80 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
22c90 65 6e 74 5d 20 61 6e 64 20 74 68 65 0a 2a 2a 20  ent] and the.** 
22ca0 58 20 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e 74  X argument point
22cb0 73 20 74 6f 20 61 20 36 34 2d 62 69 74 20 69 6e  s to a 64-bit in
22cc0 74 65 67 65 72 20 77 68 69 63 68 20 69 73 20 74  teger which is t
22cd0 68 65 20 65 73 74 69 6d 61 74 65 64 20 6f 66 0a  he estimated of.
22ce0 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ** the number of
22cf0 20 6e 61 6e 6f 73 65 63 6f 6e 64 20 74 68 61 74   nanosecond that
22d00 20 74 68 65 20 70 72 65 70 61 72 65 64 20 73 74   the prepared st
22d10 61 74 65 6d 65 6e 74 20 74 6f 6f 6b 20 74 6f 20  atement took to 
22d20 72 75 6e 2e 0a 2a 2a 20 5e 54 68 65 20 53 51 4c  run..** ^The SQL
22d30 49 54 45 5f 54 52 41 43 45 5f 50 52 4f 46 49 4c  ITE_TRACE_PROFIL
22d40 45 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e  E callback is in
22d50 76 6f 6b 65 64 20 77 68 65 6e 20 74 68 65 20 73  voked when the s
22d60 74 61 74 65 6d 65 6e 74 20 66 69 6e 69 73 68 65  tatement finishe
22d70 73 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  s..**.** [[SQLIT
22d80 45 5f 54 52 41 43 45 5f 52 4f 57 5d 5d 20 3c 64  E_TRACE_ROW]] <d
22d90 74 3e 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 52  t>SQLITE_TRACE_R
22da0 4f 57 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 5e  OW</dt>.** <dd>^
22db0 41 6e 20 53 51 4c 49 54 45 5f 54 52 41 43 45 5f  An SQLITE_TRACE_
22dc0 52 4f 57 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  ROW callback is 
22dd0 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72  invoked whenever
22de0 20 61 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73   a prepared.** s
22df0 74 61 74 65 6d 65 6e 74 20 67 65 6e 65 72 61 74  tatement generat
22e00 65 73 20 61 20 73 69 6e 67 6c 65 20 72 6f 77 20  es a single row 
22e10 6f 66 20 72 65 73 75 6c 74 2e 20 20 0a 2a 2a 20  of result.  .** 
22e20 5e 54 68 65 20 50 20 61 72 67 75 6d 65 6e 74 20  ^The P argument 
22e30 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
22e40 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
22e50 61 74 65 6d 65 6e 74 5d 20 61 6e 64 20 74 68 65  atement] and the
22e60 0a 2a 2a 20 58 20 61 72 67 75 6d 65 6e 74 20 69  .** X argument i
22e70 73 20 75 6e 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20  s unused..**.** 
22e80 5b 5b 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 43  [[SQLITE_TRACE_C
22e90 4c 4f 53 45 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  LOSE]] <dt>SQLIT
22ea0 45 5f 54 52 41 43 45 5f 43 4c 4f 53 45 3c 2f 64  E_TRACE_CLOSE</d
22eb0 74 3e 0a 2a 2a 20 3c 64 64 3e 5e 41 6e 20 53 51  t>.** <dd>^An SQ
22ec0 4c 49 54 45 5f 54 52 41 43 45 5f 43 4c 4f 53 45  LITE_TRACE_CLOSE
22ed0 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76   callback is inv
22ee0 6f 6b 65 64 20 77 68 65 6e 20 61 20 64 61 74 61  oked when a data
22ef0 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69  base.** connecti
22f00 6f 6e 20 63 6c 6f 73 65 73 2e 0a 2a 2a 20 5e 54  on closes..** ^T
22f10 68 65 20 50 20 61 72 67 75 6d 65 6e 74 20 69 73  he P argument is
22f20 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   a pointer to th
22f30 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
22f40 65 63 74 69 6f 6e 5d 20 6f 62 6a 65 63 74 0a 2a  ection] object.*
22f50 2a 20 61 6e 64 20 74 68 65 20 58 20 61 72 67 75  * and the X argu
22f60 6d 65 6e 74 20 69 73 20 75 6e 75 73 65 64 2e 0a  ment is unused..
22f70 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66  ** </dl>.*/.#def
22f80 69 6e 65 20 53 51 4c 49 54 45 5f 54 52 41 43 45  ine SQLITE_TRACE
22f90 5f 53 54 4d 54 20 20 20 20 20 20 20 30 78 30 31  _STMT       0x01
22fa0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
22fb0 54 52 41 43 45 5f 50 52 4f 46 49 4c 45 20 20 20  TRACE_PROFILE   
22fc0 20 30 78 30 32 0a 23 64 65 66 69 6e 65 20 53 51   0x02.#define SQ
22fd0 4c 49 54 45 5f 54 52 41 43 45 5f 52 4f 57 20 20  LITE_TRACE_ROW  
22fe0 20 20 20 20 20 20 30 78 30 34 0a 23 64 65 66 69        0x04.#defi
22ff0 6e 65 20 53 51 4c 49 54 45 5f 54 52 41 43 45 5f  ne SQLITE_TRACE_
23000 43 4c 4f 53 45 20 20 20 20 20 20 30 78 30 38 0a  CLOSE      0x08.
23010 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
23020 20 53 51 4c 20 54 72 61 63 65 20 48 6f 6f 6b 0a   SQL Trace Hook.
23030 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
23040 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  e3.**.** ^The sq
23050 6c 69 74 65 33 5f 74 72 61 63 65 5f 76 32 28 44  lite3_trace_v2(D
23060 2c 4d 2c 58 2c 50 29 20 69 6e 74 65 72 66 61 63  ,M,X,P) interfac
23070 65 20 72 65 67 69 73 74 65 72 73 20 61 20 74 72  e registers a tr
23080 61 63 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20  ace callback.** 
23090 66 75 6e 63 74 69 6f 6e 20 58 20 61 67 61 69 6e  function X again
230a0 73 74 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  st [database con
230b0 6e 65 63 74 69 6f 6e 5d 20 44 2c 20 75 73 69 6e  nection] D, usin
230c0 67 20 70 72 6f 70 65 72 74 79 20 6d 61 73 6b 20  g property mask 
230d0 4d 0a 2a 2a 20 61 6e 64 20 63 6f 6e 74 65 78 74  M.** and context
230e0 20 70 6f 69 6e 74 65 72 20 50 2e 20 20 5e 49 66   pointer P.  ^If
230f0 20 74 68 65 20 58 20 63 61 6c 6c 62 61 63 6b 20   the X callback 
23100 69 73 0a 2a 2a 20 4e 55 4c 4c 20 6f 72 20 69 66  is.** NULL or if
23110 20 74 68 65 20 4d 20 6d 61 73 6b 20 69 73 20 7a   the M mask is z
23120 65 72 6f 2c 20 74 68 65 6e 20 74 72 61 63 69 6e  ero, then tracin
23130 67 20 69 73 20 64 69 73 61 62 6c 65 64 2e 20 20  g is disabled.  
23140 54 68 65 0a 2a 2a 20 4d 20 61 72 67 75 6d 65 6e  The.** M argumen
23150 74 20 73 68 6f 75 6c 64 20 62 65 20 74 68 65 20  t should be the 
23160 62 69 74 77 69 73 65 20 4f 52 2d 65 64 20 63 6f  bitwise OR-ed co
23170 6d 62 69 6e 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20  mbination of.** 
23180 7a 65 72 6f 20 6f 72 20 6d 6f 72 65 20 5b 53 51  zero or more [SQ
23190 4c 49 54 45 5f 54 52 41 43 45 5d 20 63 6f 6e 73  LITE_TRACE] cons
231a0 74 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 45 61  tants..**.** ^Ea
231b0 63 68 20 63 61 6c 6c 20 74 6f 20 65 69 74 68 65  ch call to eithe
231c0 72 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28  r sqlite3_trace(
231d0 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 74 72 61  ) or sqlite3_tra
231e0 63 65 5f 76 32 28 29 20 6f 76 65 72 72 69 64 65  ce_v2() override
231f0 73 20 0a 2a 2a 20 28 63 61 6e 63 65 6c 73 29 20  s .** (cancels) 
23200 61 6e 79 20 70 72 69 6f 72 20 63 61 6c 6c 73 20  any prior calls 
23210 74 6f 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65  to sqlite3_trace
23220 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 74 72  () or sqlite3_tr
23230 61 63 65 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20  ace_v2()..**.** 
23240 5e 54 68 65 20 58 20 63 61 6c 6c 62 61 63 6b 20  ^The X callback 
23250 69 73 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65  is invoked whene
23260 76 65 72 20 61 6e 79 20 6f 66 20 74 68 65 20 65  ver any of the e
23270 76 65 6e 74 73 20 69 64 65 6e 74 69 66 69 65 64  vents identified
23280 20 62 79 20 0a 2a 2a 20 6d 61 73 6b 20 4d 20 6f   by .** mask M o
23290 63 63 75 72 2e 20 20 5e 54 68 65 20 69 6e 74 65  ccur.  ^The inte
232a0 67 65 72 20 72 65 74 75 72 6e 20 76 61 6c 75 65  ger return value
232b0 20 66 72 6f 6d 20 74 68 65 20 63 61 6c 6c 62 61   from the callba
232c0 63 6b 20 69 73 20 63 75 72 72 65 6e 74 6c 79 0a  ck is currently.
232d0 2a 2a 20 69 67 6e 6f 72 65 64 2c 20 74 68 6f 75  ** ignored, thou
232e0 67 68 20 74 68 69 73 20 6d 61 79 20 63 68 61 6e  gh this may chan
232f0 67 65 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c  ge in future rel
23300 65 61 73 65 73 2e 20 20 43 61 6c 6c 62 61 63 6b  eases.  Callback
23310 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  .** implementati
23320 6f 6e 73 20 73 68 6f 75 6c 64 20 72 65 74 75 72  ons should retur
23330 6e 20 7a 65 72 6f 20 74 6f 20 65 6e 73 75 72 65  n zero to ensure
23340 20 66 75 74 75 72 65 20 63 6f 6d 70 61 74 69 62   future compatib
23350 69 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 41 20  ility..**.** ^A 
23360 74 72 61 63 65 20 63 61 6c 6c 62 61 63 6b 20 69  trace callback i
23370 73 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 66  s invoked with f
23380 6f 75 72 20 61 72 67 75 6d 65 6e 74 73 3a 20 63  our arguments: c
23390 61 6c 6c 62 61 63 6b 28 54 2c 43 2c 50 2c 58 29  allback(T,C,P,X)
233a0 2e 0a 2a 2a 20 5e 54 68 65 20 54 20 61 72 67 75  ..** ^The T argu
233b0 6d 65 6e 74 20 69 73 20 6f 6e 65 20 6f 66 20 74  ment is one of t
233c0 68 65 20 5b 53 51 4c 49 54 45 5f 54 52 41 43 45  he [SQLITE_TRACE
233d0 5d 0a 2a 2a 20 63 6f 6e 73 74 61 6e 74 73 20 74  ].** constants t
233e0 6f 20 69 6e 64 69 63 61 74 65 20 77 68 79 20 74  o indicate why t
233f0 68 65 20 63 61 6c 6c 62 61 63 6b 20 77 61 73 20  he callback was 
23400 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 20 5e 54 68 65  invoked..** ^The
23410 20 43 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61   C argument is a
23420 20 63 6f 70 79 20 6f 66 20 74 68 65 20 63 6f 6e   copy of the con
23430 74 65 78 74 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a  text pointer..**
23440 20 54 68 65 20 50 20 61 6e 64 20 58 20 61 72 67   The P and X arg
23450 75 6d 65 6e 74 73 20 61 72 65 20 70 6f 69 6e 74  uments are point
23460 65 72 73 20 77 68 6f 73 65 20 6d 65 61 6e 69 6e  ers whose meanin
23470 67 73 20 64 65 70 65 6e 64 20 6f 6e 20 54 2e 0a  gs depend on T..
23480 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
23490 33 5f 74 72 61 63 65 5f 76 32 28 29 20 69 6e 74  3_trace_v2() int
234a0 65 72 66 61 63 65 20 69 73 20 69 6e 74 65 6e 64  erface is intend
234b0 65 64 20 74 6f 20 72 65 70 6c 61 63 65 20 74 68  ed to replace th
234c0 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65  e legacy.** inte
234d0 72 66 61 63 65 73 20 5b 73 71 6c 69 74 65 33 5f  rfaces [sqlite3_
234e0 74 72 61 63 65 28 29 5d 20 61 6e 64 20 5b 73 71  trace()] and [sq
234f0 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 29 5d  lite3_profile()]
23500 2c 20 62 6f 74 68 20 6f 66 20 77 68 69 63 68 0a  , both of which.
23510 2a 2a 20 61 72 65 20 64 65 70 72 65 63 61 74 65  ** are deprecate
23520 64 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  d..*/.SQLITE_API
23530 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 72 61   int sqlite3_tra
23540 63 65 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33  ce_v2(.  sqlite3
23550 2a 2c 0a 20 20 75 6e 73 69 67 6e 65 64 20 75 4d  *,.  unsigned uM
23560 61 73 6b 2c 0a 20 20 69 6e 74 28 2a 78 43 61 6c  ask,.  int(*xCal
23570 6c 62 61 63 6b 29 28 75 6e 73 69 67 6e 65 64 2c  lback)(unsigned,
23580 76 6f 69 64 2a 2c 76 6f 69 64 2a 2c 76 6f 69 64  void*,void*,void
23590 2a 29 2c 0a 20 20 76 6f 69 64 20 2a 70 43 74 78  *),.  void *pCtx
235a0 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .);../*.** CAPI3
235b0 52 45 46 3a 20 51 75 65 72 79 20 50 72 6f 67 72  REF: Query Progr
235c0 65 73 73 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a  ess Callbacks.**
235d0 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
235e0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
235f0 74 65 33 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e  te3_progress_han
23600 64 6c 65 72 28 44 2c 4e 2c 58 2c 50 29 20 69 6e  dler(D,N,X,P) in
23610 74 65 72 66 61 63 65 20 63 61 75 73 65 73 20 74  terface causes t
23620 68 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66  he callback.** f
23630 75 6e 63 74 69 6f 6e 20 58 20 74 6f 20 62 65 20  unction X to be 
23640 69 6e 76 6f 6b 65 64 20 70 65 72 69 6f 64 69 63  invoked periodic
23650 61 6c 6c 79 20 64 75 72 69 6e 67 20 6c 6f 6e 67  ally during long
23660 20 72 75 6e 6e 69 6e 67 20 63 61 6c 6c 73 20 74   running calls t
23670 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78  o.** [sqlite3_ex
23680 65 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  ec()], [sqlite3_
23690 73 74 65 70 28 29 5d 20 61 6e 64 20 5b 73 71 6c  step()] and [sql
236a0 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29  ite3_get_table()
236b0 5d 20 66 6f 72 0a 2a 2a 20 64 61 74 61 62 61 73  ] for.** databas
236c0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2e 20  e connection D. 
236d0 20 41 6e 20 65 78 61 6d 70 6c 65 20 75 73 65 20   An example use 
236e0 66 6f 72 20 74 68 69 73 0a 2a 2a 20 69 6e 74 65  for this.** inte
236f0 72 66 61 63 65 20 69 73 20 74 6f 20 6b 65 65 70  rface is to keep
23700 20 61 20 47 55 49 20 75 70 64 61 74 65 64 20 64   a GUI updated d
23710 75 72 69 6e 67 20 61 20 6c 61 72 67 65 20 71 75  uring a large qu
23720 65 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ery..**.** ^The 
23730 70 61 72 61 6d 65 74 65 72 20 50 20 69 73 20 70  parameter P is p
23740 61 73 73 65 64 20 74 68 72 6f 75 67 68 20 61 73  assed through as
23750 20 74 68 65 20 6f 6e 6c 79 20 70 61 72 61 6d 65   the only parame
23760 74 65 72 20 74 6f 20 74 68 65 20 0a 2a 2a 20 63  ter to the .** c
23770 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
23780 20 58 2e 20 20 5e 54 68 65 20 70 61 72 61 6d 65   X.  ^The parame
23790 74 65 72 20 4e 20 69 73 20 74 68 65 20 61 70 70  ter N is the app
237a0 72 6f 78 69 6d 61 74 65 20 6e 75 6d 62 65 72 20  roximate number 
237b0 6f 66 20 0a 2a 2a 20 5b 76 69 72 74 75 61 6c 20  of .** [virtual 
237c0 6d 61 63 68 69 6e 65 20 69 6e 73 74 72 75 63 74  machine instruct
237d0 69 6f 6e 73 5d 20 74 68 61 74 20 61 72 65 20 65  ions] that are e
237e0 76 61 6c 75 61 74 65 64 20 62 65 74 77 65 65 6e  valuated between
237f0 20 73 75 63 63 65 73 73 69 76 65 0a 2a 2a 20 69   successive.** i
23800 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 68  nvocations of th
23810 65 20 63 61 6c 6c 62 61 63 6b 20 58 2e 20 20 5e  e callback X.  ^
23820 49 66 20 4e 20 69 73 20 6c 65 73 73 20 74 68 61  If N is less tha
23830 6e 20 6f 6e 65 20 74 68 65 6e 20 74 68 65 20 70  n one then the p
23840 72 6f 67 72 65 73 73 0a 2a 2a 20 68 61 6e 64 6c  rogress.** handl
23850 65 72 20 69 73 20 64 69 73 61 62 6c 65 64 2e 0a  er is disabled..
23860 2a 2a 0a 2a 2a 20 5e 4f 6e 6c 79 20 61 20 73 69  **.** ^Only a si
23870 6e 67 6c 65 20 70 72 6f 67 72 65 73 73 20 68 61  ngle progress ha
23880 6e 64 6c 65 72 20 6d 61 79 20 62 65 20 64 65 66  ndler may be def
23890 69 6e 65 64 20 61 74 20 6f 6e 65 20 74 69 6d 65  ined at one time
238a0 20 70 65 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73   per.** [databas
238b0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 3b 20 73  e connection]; s
238c0 65 74 74 69 6e 67 20 61 20 6e 65 77 20 70 72 6f  etting a new pro
238d0 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20 63 61  gress handler ca
238e0 6e 63 65 6c 73 20 74 68 65 0a 2a 2a 20 6f 6c 64  ncels the.** old
238f0 20 6f 6e 65 2e 20 20 5e 53 65 74 74 69 6e 67 20   one.  ^Setting 
23900 70 61 72 61 6d 65 74 65 72 20 58 20 74 6f 20 4e  parameter X to N
23910 55 4c 4c 20 64 69 73 61 62 6c 65 73 20 74 68 65  ULL disables the
23920 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65   progress handle
23930 72 2e 0a 2a 2a 20 5e 54 68 65 20 70 72 6f 67 72  r..** ^The progr
23940 65 73 73 20 68 61 6e 64 6c 65 72 20 69 73 20 61  ess handler is a
23950 6c 73 6f 20 64 69 73 61 62 6c 65 64 20 62 79 20  lso disabled by 
23960 73 65 74 74 69 6e 67 20 4e 20 74 6f 20 61 20 76  setting N to a v
23970 61 6c 75 65 20 6c 65 73 73 0a 2a 2a 20 74 68 61  alue less.** tha
23980 6e 20 31 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  n 1..**.** ^If t
23990 68 65 20 70 72 6f 67 72 65 73 73 20 63 61 6c 6c  he progress call
239a0 62 61 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e  back returns non
239b0 2d 7a 65 72 6f 2c 20 74 68 65 20 6f 70 65 72 61  -zero, the opera
239c0 74 69 6f 6e 20 69 73 0a 2a 2a 20 69 6e 74 65 72  tion is.** inter
239d0 72 75 70 74 65 64 2e 20 20 54 68 69 73 20 66 65  rupted.  This fe
239e0 61 74 75 72 65 20 63 61 6e 20 62 65 20 75 73 65  ature can be use
239f0 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 61  d to implement a
23a00 0a 2a 2a 20 22 43 61 6e 63 65 6c 22 20 62 75 74  .** "Cancel" but
23a10 74 6f 6e 20 6f 6e 20 61 20 47 55 49 20 70 72 6f  ton on a GUI pro
23a20 67 72 65 73 73 20 64 69 61 6c 6f 67 20 62 6f 78  gress dialog box
23a30 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 6f 67  ..**.** The prog
23a40 72 65 73 73 20 68 61 6e 64 6c 65 72 20 63 61 6c  ress handler cal
23a50 6c 62 61 63 6b 20 6d 75 73 74 20 6e 6f 74 20 64  lback must not d
23a60 6f 20 61 6e 79 74 68 69 6e 67 20 74 68 61 74 20  o anything that 
23a70 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74  will modify.** t
23a80 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
23a90 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f  ection that invo
23aa0 6b 65 64 20 74 68 65 20 70 72 6f 67 72 65 73 73  ked the progress
23ab0 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 4e 6f 74   handler..** Not
23ac0 65 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f  e that [sqlite3_
23ad0 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e  prepare_v2()] an
23ae0 64 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  d [sqlite3_step(
23af0 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79 20 74  )] both modify t
23b00 68 65 69 72 0a 2a 2a 20 64 61 74 61 62 61 73 65  heir.** database
23b10 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72   connections for
23b20 20 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20   the meaning of 
23b30 22 6d 6f 64 69 66 79 22 20 69 6e 20 74 68 69 73  "modify" in this
23b40 20 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a   paragraph..**.*
23b50 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69  /.SQLITE_API voi
23b60 64 20 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 65  d sqlite3_progre
23b70 73 73 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69 74  ss_handler(sqlit
23b80 65 33 2a 2c 20 69 6e 74 2c 20 69 6e 74 28 2a 29  e3*, int, int(*)
23b90 28 76 6f 69 64 2a 29 2c 20 76 6f 69 64 2a 29 3b  (void*), void*);
23ba0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
23bb0 3a 20 4f 70 65 6e 69 6e 67 20 41 20 4e 65 77 20  : Opening A New 
23bc0 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74  Database Connect
23bd0 69 6f 6e 0a 2a 2a 20 43 4f 4e 53 54 52 55 43 54  ion.** CONSTRUCT
23be0 4f 52 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a  OR: sqlite3.**.*
23bf0 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65  * ^These routine
23c00 73 20 6f 70 65 6e 20 61 6e 20 53 51 4c 69 74 65  s open an SQLite
23c10 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 61   database file a
23c20 73 20 73 70 65 63 69 66 69 65 64 20 62 79 20 74  s specified by t
23c30 68 65 20 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20  he .** filename 
23c40 61 72 67 75 6d 65 6e 74 2e 20 5e 54 68 65 20 66  argument. ^The f
23c50 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74  ilename argument
23c60 20 69 73 20 69 6e 74 65 72 70 72 65 74 65 64 20   is interpreted 
23c70 61 73 20 55 54 46 2d 38 20 66 6f 72 0a 2a 2a 20  as UTF-8 for.** 
23c80 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 61  sqlite3_open() a
23c90 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  nd sqlite3_open_
23ca0 76 32 28 29 20 61 6e 64 20 61 73 20 55 54 46 2d  v2() and as UTF-
23cb0 31 36 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65  16 in the native
23cc0 20 62 79 74 65 0a 2a 2a 20 6f 72 64 65 72 20 66   byte.** order f
23cd0 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  or sqlite3_open1
23ce0 36 28 29 2e 20 5e 28 41 20 5b 64 61 74 61 62 61  6(). ^(A [databa
23cf0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68  se connection] h
23d00 61 6e 64 6c 65 20 69 73 20 75 73 75 61 6c 6c 79  andle is usually
23d10 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 69 6e 20  .** returned in 
23d20 2a 70 70 44 62 2c 20 65 76 65 6e 20 69 66 20 61  *ppDb, even if a
23d30 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2e 20  n error occurs. 
23d40 20 54 68 65 20 6f 6e 6c 79 20 65 78 63 65 70 74   The only except
23d50 69 6f 6e 20 69 73 20 74 68 61 74 0a 2a 2a 20 69  ion is that.** i
23d60 66 20 53 51 4c 69 74 65 20 69 73 20 75 6e 61 62  f SQLite is unab
23d70 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d  le to allocate m
23d80 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68  emory to hold th
23d90 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65  e [sqlite3] obje
23da0 63 74 2c 0a 2a 2a 20 61 20 4e 55 4c 4c 20 77 69  ct,.** a NULL wi
23db0 6c 6c 20 62 65 20 77 72 69 74 74 65 6e 20 69 6e  ll be written in
23dc0 74 6f 20 2a 70 70 44 62 20 69 6e 73 74 65 61 64  to *ppDb instead
23dd0 20 6f 66 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   of a pointer to
23de0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 0a 2a   the [sqlite3].*
23df0 2a 20 6f 62 6a 65 63 74 2e 29 5e 20 5e 28 49 66  * object.)^ ^(If
23e00 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73   the database is
23e10 20 6f 70 65 6e 65 64 20 28 61 6e 64 2f 6f 72 20   opened (and/or 
23e20 63 72 65 61 74 65 64 29 20 73 75 63 63 65 73 73  created) success
23e30 66 75 6c 6c 79 2c 20 74 68 65 6e 0a 2a 2a 20 5b  fully, then.** [
23e40 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 73 20 72 65  SQLITE_OK] is re
23e50 74 75 72 6e 65 64 2e 20 20 4f 74 68 65 72 77 69  turned.  Otherwi
23e60 73 65 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64  se an [error cod
23e70 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 29  e] is returned.)
23e80 5e 20 5e 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  ^ ^The.** [sqlit
23e90 65 33 5f 65 72 72 6d 73 67 28 29 5d 20 6f 72 20  e3_errmsg()] or 
23ea0 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31  [sqlite3_errmsg1
23eb0 36 28 29 5d 20 72 6f 75 74 69 6e 65 73 20 63 61  6()] routines ca
23ec0 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f 62 74  n be used to obt
23ed0 61 69 6e 0a 2a 2a 20 61 6e 20 45 6e 67 6c 69 73  ain.** an Englis
23ee0 68 20 6c 61 6e 67 75 61 67 65 20 64 65 73 63 72  h language descr
23ef0 69 70 74 69 6f 6e 20 6f 66 20 74 68 65 20 65 72  iption of the er
23f00 72 6f 72 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20  ror following a 
23f10 66 61 69 6c 75 72 65 20 6f 66 20 61 6e 79 0a 2a  failure of any.*
23f20 2a 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33  * of the sqlite3
23f30 5f 6f 70 65 6e 28 29 20 72 6f 75 74 69 6e 65 73  _open() routines
23f40 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 64 65 66  ..**.** ^The def
23f50 61 75 6c 74 20 65 6e 63 6f 64 69 6e 67 20 77 69  ault encoding wi
23f60 6c 6c 20 62 65 20 55 54 46 2d 38 20 66 6f 72 20  ll be UTF-8 for 
23f70 64 61 74 61 62 61 73 65 73 20 63 72 65 61 74 65  databases create
23f80 64 20 75 73 69 6e 67 0a 2a 2a 20 73 71 6c 69 74  d using.** sqlit
23f90 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c  e3_open() or sql
23fa0 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 20  ite3_open_v2(). 
23fb0 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20 65 6e   ^The default en
23fc0 63 6f 64 69 6e 67 20 66 6f 72 20 64 61 74 61 62  coding for datab
23fd0 61 73 65 73 0a 2a 2a 20 63 72 65 61 74 65 64 20  ases.** created 
23fe0 75 73 69 6e 67 20 73 71 6c 69 74 65 33 5f 6f 70  using sqlite3_op
23ff0 65 6e 31 36 28 29 20 77 69 6c 6c 20 62 65 20 55  en16() will be U
24000 54 46 2d 31 36 20 69 6e 20 74 68 65 20 6e 61 74  TF-16 in the nat
24010 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e 0a  ive byte order..
24020 2a 2a 0a 2a 2a 20 57 68 65 74 68 65 72 20 6f 72  **.** Whether or
24030 20 6e 6f 74 20 61 6e 20 65 72 72 6f 72 20 6f 63   not an error oc
24040 63 75 72 73 20 77 68 65 6e 20 69 74 20 69 73 20  curs when it is 
24050 6f 70 65 6e 65 64 2c 20 72 65 73 6f 75 72 63 65  opened, resource
24060 73 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20  s.** associated 
24070 77 69 74 68 20 74 68 65 20 5b 64 61 74 61 62 61  with the [databa
24080 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68  se connection] h
24090 61 6e 64 6c 65 20 73 68 6f 75 6c 64 20 62 65 20  andle should be 
240a0 72 65 6c 65 61 73 65 64 20 62 79 0a 2a 2a 20 70  released by.** p
240b0 61 73 73 69 6e 67 20 69 74 20 74 6f 20 5b 73 71  assing it to [sq
240c0 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 20 77  lite3_close()] w
240d0 68 65 6e 20 69 74 20 69 73 20 6e 6f 20 6c 6f 6e  hen it is no lon
240e0 67 65 72 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a  ger required..**
240f0 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
24100 6f 70 65 6e 5f 76 32 28 29 20 69 6e 74 65 72 66  open_v2() interf
24110 61 63 65 20 77 6f 72 6b 73 20 6c 69 6b 65 20 73  ace works like s
24120 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 0a 2a 2a  qlite3_open().**
24130 20 65 78 63 65 70 74 20 74 68 61 74 20 69 74 20   except that it 
24140 61 63 63 65 70 74 73 20 74 77 6f 20 61 64 64 69  accepts two addi
24150 74 69 6f 6e 61 6c 20 70 61 72 61 6d 65 74 65 72  tional parameter
24160 73 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c  s for additional
24170 20 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 6f 76 65 72   control.** over
24180 20 74 68 65 20 6e 65 77 20 64 61 74 61 62 61 73   the new databas
24190 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 5e  e connection.  ^
241a0 28 54 68 65 20 66 6c 61 67 73 20 70 61 72 61 6d  (The flags param
241b0 65 74 65 72 20 74 6f 0a 2a 2a 20 73 71 6c 69 74  eter to.** sqlit
241c0 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 63 61 6e  e3_open_v2() can
241d0 20 74 61 6b 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20   take one of.** 
241e0 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68  the following th
241f0 72 65 65 20 76 61 6c 75 65 73 2c 20 6f 70 74 69  ree values, opti
24200 6f 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e 65 64 20  onally combined 
24210 77 69 74 68 20 74 68 65 20 0a 2a 2a 20 5b 53 51  with the .** [SQ
24220 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45  LITE_OPEN_NOMUTE
24230 58 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  X], [SQLITE_OPEN
24240 5f 46 55 4c 4c 4d 55 54 45 58 5d 2c 20 5b 53 51  _FULLMUTEX], [SQ
24250 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44  LITE_OPEN_SHARED
24260 43 41 43 48 45 5d 2c 0a 2a 2a 20 5b 53 51 4c 49  CACHE],.** [SQLI
24270 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43  TE_OPEN_PRIVATEC
24280 41 43 48 45 5d 2c 20 61 6e 64 2f 6f 72 20 5b 53  ACHE], and/or [S
24290 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20  QLITE_OPEN_URI] 
242a0 66 6c 61 67 73 3a 29 5e 0a 2a 2a 0a 2a 2a 20 3c  flags:)^.**.** <
242b0 64 6c 3e 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51  dl>.** ^(<dt>[SQ
242c0 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e  LITE_OPEN_READON
242d0 4c 59 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  LY]</dt>.** <dd>
242e0 54 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20  The database is 
242f0 6f 70 65 6e 65 64 20 69 6e 20 72 65 61 64 2d 6f  opened in read-o
24300 6e 6c 79 20 6d 6f 64 65 2e 20 20 49 66 20 74 68  nly mode.  If th
24310 65 20 64 61 74 61 62 61 73 65 20 64 6f 65 73 20  e database does 
24320 6e 6f 74 0a 2a 2a 20 61 6c 72 65 61 64 79 20 65  not.** already e
24330 78 69 73 74 2c 20 61 6e 20 65 72 72 6f 72 20 69  xist, an error i
24340 73 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e  s returned.</dd>
24350 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b  )^.**.** ^(<dt>[
24360 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44  SQLITE_OPEN_READ
24370 57 52 49 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c  WRITE]</dt>.** <
24380 64 64 3e 54 68 65 20 64 61 74 61 62 61 73 65 20  dd>The database 
24390 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65  is opened for re
243a0 61 64 69 6e 67 20 61 6e 64 20 77 72 69 74 69 6e  ading and writin
243b0 67 20 69 66 20 70 6f 73 73 69 62 6c 65 2c 20 6f  g if possible, o
243c0 72 20 72 65 61 64 69 6e 67 0a 2a 2a 20 6f 6e 6c  r reading.** onl
243d0 79 20 69 66 20 74 68 65 20 66 69 6c 65 20 69 73  y if the file is
243e0 20 77 72 69 74 65 20 70 72 6f 74 65 63 74 65 64   write protected
243f0 20 62 79 20 74 68 65 20 6f 70 65 72 61 74 69 6e   by the operatin
24400 67 20 73 79 73 74 65 6d 2e 20 20 49 6e 20 65 69  g system.  In ei
24410 74 68 65 72 0a 2a 2a 20 63 61 73 65 20 74 68 65  ther.** case the
24420 20 64 61 74 61 62 61 73 65 20 6d 75 73 74 20 61   database must a
24430 6c 72 65 61 64 79 20 65 78 69 73 74 2c 20 6f 74  lready exist, ot
24440 68 65 72 77 69 73 65 20 61 6e 20 65 72 72 6f 72  herwise an error
24450 20 69 73 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64   is returned.</d
24460 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74  d>)^.**.** ^(<dt
24470 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45  >[SQLITE_OPEN_RE
24480 41 44 57 52 49 54 45 5d 20 7c 20 5b 53 51 4c 49  ADWRITE] | [SQLI
24490 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 3c  TE_OPEN_CREATE]<
244a0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
244b0 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e  database is open
244c0 65 64 20 66 6f 72 20 72 65 61 64 69 6e 67 20 61  ed for reading a
244d0 6e 64 20 77 72 69 74 69 6e 67 2c 20 61 6e 64 20  nd writing, and 
244e0 69 73 20 63 72 65 61 74 65 64 20 69 66 0a 2a 2a  is created if.**
244f0 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 61 6c 72   it does not alr
24500 65 61 64 79 20 65 78 69 73 74 2e 20 54 68 69 73  eady exist. This
24510 20 69 73 20 74 68 65 20 62 65 68 61 76 69 6f 72   is the behavior
24520 20 74 68 61 74 20 69 73 20 61 6c 77 61 79 73 20   that is always 
24530 75 73 65 64 20 66 6f 72 0a 2a 2a 20 73 71 6c 69  used for.** sqli
24540 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73  te3_open() and s
24550 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e  qlite3_open16().
24560 3c 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e  </dd>)^.** </dl>
24570 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 33 72  .**.** If the 3r
24580 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  d parameter to s
24590 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
245a0 20 69 73 20 6e 6f 74 20 6f 6e 65 20 6f 66 20 74   is not one of t
245b0 68 65 0a 2a 2a 20 63 6f 6d 62 69 6e 61 74 69 6f  he.** combinatio
245c0 6e 73 20 73 68 6f 77 6e 20 61 62 6f 76 65 20 6f  ns shown above o
245d0 70 74 69 6f 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e  ptionally combin
245e0 65 64 20 77 69 74 68 20 6f 74 68 65 72 0a 2a 2a  ed with other.**
245f0 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45   [SQLITE_OPEN_RE
24600 41 44 4f 4e 4c 59 20 7c 20 53 51 4c 49 54 45 5f  ADONLY | SQLITE_
24610 4f 50 45 4e 5f 2a 20 62 69 74 73 5d 0a 2a 2a 20  OPEN_* bits].** 
24620 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f  then the behavio
24630 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a  r is undefined..
24640 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 5b 53  **.** ^If the [S
24650 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54  QLITE_OPEN_NOMUT
24660 45 58 5d 20 66 6c 61 67 20 69 73 20 73 65 74 2c  EX] flag is set,
24670 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 61   then the databa
24680 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a  se connection.**
24690 20 6f 70 65 6e 73 20 69 6e 20 74 68 65 20 6d 75   opens in the mu
246a0 6c 74 69 2d 74 68 72 65 61 64 20 5b 74 68 72 65  lti-thread [thre
246b0 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61 73 20 6c  ading mode] as l
246c0 6f 6e 67 20 61 73 20 74 68 65 20 73 69 6e 67 6c  ong as the singl
246d0 65 2d 74 68 72 65 61 64 0a 2a 2a 20 6d 6f 64 65  e-thread.** mode
246e0 20 68 61 73 20 6e 6f 74 20 62 65 65 6e 20 73 65   has not been se
246f0 74 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  t at compile-tim
24700 65 20 6f 72 20 73 74 61 72 74 2d 74 69 6d 65 2e  e or start-time.
24710 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 5b 53 51    ^If the.** [SQ
24720 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55  LITE_OPEN_FULLMU
24730 54 45 58 5d 20 66 6c 61 67 20 69 73 20 73 65 74  TEX] flag is set
24740 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 61   then the databa
24750 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6f 70  se connection op
24760 65 6e 73 0a 2a 2a 20 69 6e 20 74 68 65 20 73 65  ens.** in the se
24770 72 69 61 6c 69 7a 65 64 20 5b 74 68 72 65 61 64  rialized [thread
24780 69 6e 67 20 6d 6f 64 65 5d 20 75 6e 6c 65 73 73  ing mode] unless
24790 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 20 77   single-thread w
247a0 61 73 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79  as.** previously
247b0 20 73 65 6c 65 63 74 65 64 20 61 74 20 63 6f 6d   selected at com
247c0 70 69 6c 65 2d 74 69 6d 65 20 6f 72 20 73 74 61  pile-time or sta
247d0 72 74 2d 74 69 6d 65 2e 0a 2a 2a 20 5e 54 68 65  rt-time..** ^The
247e0 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48   [SQLITE_OPEN_SH
247f0 41 52 45 44 43 41 43 48 45 5d 20 66 6c 61 67 20  AREDCACHE] flag 
24800 63 61 75 73 65 73 20 74 68 65 20 64 61 74 61 62  causes the datab
24810 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74  ase connection t
24820 6f 20 62 65 0a 2a 2a 20 65 6c 69 67 69 62 6c 65  o be.** eligible
24830 20 74 6f 20 75 73 65 20 5b 73 68 61 72 65 64 20   to use [shared 
24840 63 61 63 68 65 20 6d 6f 64 65 5d 2c 20 72 65 67  cache mode], reg
24850 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68  ardless of wheth
24860 65 72 20 6f 72 20 6e 6f 74 20 73 68 61 72 65 64  er or not shared
24870 0a 2a 2a 20 63 61 63 68 65 20 69 73 20 65 6e 61  .** cache is ena
24880 62 6c 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69  bled using [sqli
24890 74 65 33 5f 65 6e 61 62 6c 65 5f 73 68 61 72 65  te3_enable_share
248a0 64 5f 63 61 63 68 65 28 29 5d 2e 20 20 5e 54 68  d_cache()].  ^Th
248b0 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45  e.** [SQLITE_OPE
248c0 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45 5d 20  N_PRIVATECACHE] 
248d0 66 6c 61 67 20 63 61 75 73 65 73 20 74 68 65 20  flag causes the 
248e0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
248f0 69 6f 6e 20 74 6f 20 6e 6f 74 0a 2a 2a 20 70 61  ion to not.** pa
24900 72 74 69 63 69 70 61 74 65 20 69 6e 20 5b 73 68  rticipate in [sh
24910 61 72 65 64 20 63 61 63 68 65 20 6d 6f 64 65 5d  ared cache mode]
24920 20 65 76 65 6e 20 69 66 20 69 74 20 69 73 20 65   even if it is e
24930 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54  nabled..**.** ^T
24940 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
24950 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f  ter to sqlite3_o
24960 70 65 6e 5f 76 32 28 29 20 69 73 20 74 68 65 20  pen_v2() is the 
24970 6e 61 6d 65 20 6f 66 20 74 68 65 0a 2a 2a 20 5b  name of the.** [
24980 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a  sqlite3_vfs] obj
24990 65 63 74 20 74 68 61 74 20 64 65 66 69 6e 65 73  ect that defines
249a0 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73   the operating s
249b0 79 73 74 65 6d 20 69 6e 74 65 72 66 61 63 65 20  ystem interface 
249c0 74 68 61 74 0a 2a 2a 20 74 68 65 20 6e 65 77 20  that.** the new 
249d0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
249e0 69 6f 6e 20 73 68 6f 75 6c 64 20 75 73 65 2e 20  ion should use. 
249f0 20 5e 49 66 20 74 68 65 20 66 6f 75 72 74 68 20   ^If the fourth 
24a00 70 61 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20  parameter is.** 
24a10 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74  a NULL pointer t
24a20 68 65 6e 20 74 68 65 20 64 65 66 61 75 6c 74 20  hen the default 
24a30 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62  [sqlite3_vfs] ob
24a40 6a 65 63 74 20 69 73 20 75 73 65 64 2e 0a 2a 2a  ject is used..**
24a50 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 6c 65  .** ^If the file
24a60 6e 61 6d 65 20 69 73 20 22 3a 6d 65 6d 6f 72 79  name is ":memory
24a70 3a 22 2c 20 74 68 65 6e 20 61 20 70 72 69 76 61  :", then a priva
24a80 74 65 2c 20 74 65 6d 70 6f 72 61 72 79 20 69 6e  te, temporary in
24a90 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65  -memory database
24aa0 0a 2a 2a 20 69 73 20 63 72 65 61 74 65 64 20 66  .** is created f
24ab0 6f 72 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f  or the connectio
24ac0 6e 2e 20 20 5e 54 68 69 73 20 69 6e 2d 6d 65 6d  n.  ^This in-mem
24ad0 6f 72 79 20 64 61 74 61 62 61 73 65 20 77 69 6c  ory database wil
24ae0 6c 20 76 61 6e 69 73 68 20 77 68 65 6e 0a 2a 2a  l vanish when.**
24af0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
24b00 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73  nnection is clos
24b10 65 64 2e 20 20 46 75 74 75 72 65 20 76 65 72 73  ed.  Future vers
24b20 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d  ions of SQLite m
24b30 69 67 68 74 0a 2a 2a 20 6d 61 6b 65 20 75 73 65  ight.** make use
24b40 20 6f 66 20 61 64 64 69 74 69 6f 6e 61 6c 20 73   of additional s
24b50 70 65 63 69 61 6c 20 66 69 6c 65 6e 61 6d 65 73  pecial filenames
24b60 20 74 68 61 74 20 62 65 67 69 6e 20 77 69 74 68   that begin with
24b70 20 74 68 65 20 22 3a 22 20 63 68 61 72 61 63 74   the ":" charact
24b80 65 72 2e 0a 2a 2a 20 49 74 20 69 73 20 72 65 63  er..** It is rec
24b90 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 77 68  ommended that wh
24ba0 65 6e 20 61 20 64 61 74 61 62 61 73 65 20 66 69  en a database fi
24bb0 6c 65 6e 61 6d 65 20 61 63 74 75 61 6c 6c 79 20  lename actually 
24bc0 64 6f 65 73 20 62 65 67 69 6e 20 77 69 74 68 0a  does begin with.
24bd0 2a 2a 20 61 20 22 3a 22 20 63 68 61 72 61 63 74  ** a ":" charact
24be0 65 72 20 79 6f 75 20 73 68 6f 75 6c 64 20 70 72  er you should pr
24bf0 65 66 69 78 20 74 68 65 20 66 69 6c 65 6e 61 6d  efix the filenam
24c00 65 20 77 69 74 68 20 61 20 70 61 74 68 6e 61 6d  e with a pathnam
24c10 65 20 73 75 63 68 20 61 73 0a 2a 2a 20 22 2e 2f  e such as.** "./
24c20 22 20 74 6f 20 61 76 6f 69 64 20 61 6d 62 69 67  " to avoid ambig
24c30 75 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  uity..**.** ^If 
24c40 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 20  the filename is 
24c50 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 2c  an empty string,
24c60 20 74 68 65 6e 20 61 20 70 72 69 76 61 74 65 2c   then a private,
24c70 20 74 65 6d 70 6f 72 61 72 79 0a 2a 2a 20 6f 6e   temporary.** on
24c80 2d 64 69 73 6b 20 64 61 74 61 62 61 73 65 20 77  -disk database w
24c90 69 6c 6c 20 62 65 20 63 72 65 61 74 65 64 2e 20  ill be created. 
24ca0 20 5e 54 68 69 73 20 70 72 69 76 61 74 65 20 64   ^This private d
24cb0 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62 65 0a  atabase will be.
24cc0 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  ** automatically
24cd0 20 64 65 6c 65 74 65 64 20 61 73 20 73 6f 6f 6e   deleted as soon
24ce0 20 61 73 20 74 68 65 20 64 61 74 61 62 61 73 65   as the database
24cf0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63   connection is c
24d00 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 55  losed..**.** [[U
24d10 52 49 20 66 69 6c 65 6e 61 6d 65 73 20 69 6e 20  RI filenames in 
24d20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 5d  sqlite3_open()]]
24d30 20 3c 68 33 3e 55 52 49 20 46 69 6c 65 6e 61 6d   <h3>URI Filenam
24d40 65 73 3c 2f 68 33 3e 0a 2a 2a 0a 2a 2a 20 5e 49  es</h3>.**.** ^I
24d50 66 20 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65 5d  f [URI filename]
24d60 20 69 6e 74 65 72 70 72 65 74 61 74 69 6f 6e 20   interpretation 
24d70 69 73 20 65 6e 61 62 6c 65 64 2c 20 61 6e 64 20  is enabled, and 
24d80 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67  the filename arg
24d90 75 6d 65 6e 74 0a 2a 2a 20 62 65 67 69 6e 73 20  ument.** begins 
24da0 77 69 74 68 20 22 66 69 6c 65 3a 22 2c 20 74 68  with "file:", th
24db0 65 6e 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20  en the filename 
24dc0 69 73 20 69 6e 74 65 72 70 72 65 74 65 64 20 61  is interpreted a
24dd0 73 20 61 20 55 52 49 2e 20 5e 55 52 49 0a 2a 2a  s a URI. ^URI.**
24de0 20 66 69 6c 65 6e 61 6d 65 20 69 6e 74 65 72 70   filename interp
24df0 72 65 74 61 74 69 6f 6e 20 69 73 20 65 6e 61 62  retation is enab
24e00 6c 65 64 20 69 66 20 74 68 65 20 5b 53 51 4c 49  led if the [SQLI
24e10 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 66 6c 61  TE_OPEN_URI] fla
24e20 67 20 69 73 0a 2a 2a 20 73 65 74 20 69 6e 20 74  g is.** set in t
24e30 68 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65  he fourth argume
24e40 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70  nt to sqlite3_op
24e50 65 6e 5f 76 32 28 29 2c 20 6f 72 20 69 66 20 69  en_v2(), or if i
24e60 74 20 68 61 73 0a 2a 2a 20 62 65 65 6e 20 65 6e  t has.** been en
24e70 61 62 6c 65 64 20 67 6c 6f 62 61 6c 6c 79 20 75  abled globally u
24e80 73 69 6e 67 20 74 68 65 20 5b 53 51 4c 49 54 45  sing the [SQLITE
24e90 5f 43 4f 4e 46 49 47 5f 55 52 49 5d 20 6f 70 74  _CONFIG_URI] opt
24ea0 69 6f 6e 20 77 69 74 68 20 74 68 65 0a 2a 2a 20  ion with the.** 
24eb0 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
24ec0 29 5d 20 6d 65 74 68 6f 64 20 6f 72 20 62 79 20  )] method or by 
24ed0 74 68 65 20 5b 53 51 4c 49 54 45 5f 55 53 45 5f  the [SQLITE_USE_
24ee0 55 52 49 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  URI] compile-tim
24ef0 65 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 41 73 20  e option..** As 
24f00 6f 66 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f  of SQLite versio
24f10 6e 20 33 2e 37 2e 37 2c 20 55 52 49 20 66 69 6c  n 3.7.7, URI fil
24f20 65 6e 61 6d 65 20 69 6e 74 65 72 70 72 65 74 61  ename interpreta
24f30 74 69 6f 6e 20 69 73 20 74 75 72 6e 65 64 20 6f  tion is turned o
24f40 66 66 0a 2a 2a 20 62 79 20 64 65 66 61 75 6c 74  ff.** by default
24f50 2c 20 62 75 74 20 66 75 74 75 72 65 20 72 65 6c  , but future rel
24f60 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 20  eases of SQLite 
24f70 6d 69 67 68 74 20 65 6e 61 62 6c 65 20 55 52 49  might enable URI
24f80 20 66 69 6c 65 6e 61 6d 65 0a 2a 2a 20 69 6e 74   filename.** int
24f90 65 72 70 72 65 74 61 74 69 6f 6e 20 62 79 20 64  erpretation by d
24fa0 65 66 61 75 6c 74 2e 20 20 53 65 65 20 22 5b 55  efault.  See "[U
24fb0 52 49 20 66 69 6c 65 6e 61 6d 65 73 5d 22 20 66  RI filenames]" f
24fc0 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a  or additional.**
24fd0 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a   information..**
24fe0 0a 2a 2a 20 55 52 49 20 66 69 6c 65 6e 61 6d 65  .** URI filename
24ff0 73 20 61 72 65 20 70 61 72 73 65 64 20 61 63 63  s are parsed acc
25000 6f 72 64 69 6e 67 20 74 6f 20 52 46 43 20 33 39  ording to RFC 39
25010 38 36 2e 20 5e 49 66 20 74 68 65 20 55 52 49 20  86. ^If the URI 
25020 63 6f 6e 74 61 69 6e 73 20 61 6e 0a 2a 2a 20 61  contains an.** a
25030 75 74 68 6f 72 69 74 79 2c 20 74 68 65 6e 20 69  uthority, then i
25040 74 20 6d 75 73 74 20 62 65 20 65 69 74 68 65 72  t must be either
25050 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67   an empty string
25060 20 6f 72 20 74 68 65 20 73 74 72 69 6e 67 20 0a   or the string .
25070 2a 2a 20 22 6c 6f 63 61 6c 68 6f 73 74 22 2e 20  ** "localhost". 
25080 5e 49 66 20 74 68 65 20 61 75 74 68 6f 72 69 74  ^If the authorit
25090 79 20 69 73 20 6e 6f 74 20 61 6e 20 65 6d 70 74  y is not an empt
250a0 79 20 73 74 72 69 6e 67 20 6f 72 20 22 6c 6f 63  y string or "loc
250b0 61 6c 68 6f 73 74 22 2c 20 61 6e 20 0a 2a 2a 20  alhost", an .** 
250c0 65 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65  error is returne
250d0 64 20 74 6f 20 74 68 65 20 63 61 6c 6c 65 72 2e  d to the caller.
250e0 20 5e 54 68 65 20 66 72 61 67 6d 65 6e 74 20 63   ^The fragment c
250f0 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 20 55 52  omponent of a UR
25100 49 2c 20 69 66 20 0a 2a 2a 20 70 72 65 73 65 6e  I, if .** presen
25110 74 2c 20 69 73 20 69 67 6e 6f 72 65 64 2e 0a 2a  t, is ignored..*
25120 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 75 73 65  *.** ^SQLite use
25130 73 20 74 68 65 20 70 61 74 68 20 63 6f 6d 70 6f  s the path compo
25140 6e 65 6e 74 20 6f 66 20 74 68 65 20 55 52 49 20  nent of the URI 
25150 61 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  as the name of t
25160 68 65 20 64 69 73 6b 20 66 69 6c 65 0a 2a 2a 20  he disk file.** 
25170 77 68 69 63 68 20 63 6f 6e 74 61 69 6e 73 20 74  which contains t
25180 68 65 20 64 61 74 61 62 61 73 65 2e 20 5e 49 66  he database. ^If
25190 20 74 68 65 20 70 61 74 68 20 62 65 67 69 6e 73   the path begins
251a0 20 77 69 74 68 20 61 20 27 2f 27 20 63 68 61 72   with a '/' char
251b0 61 63 74 65 72 2c 20 0a 2a 2a 20 74 68 65 6e 20  acter, .** then 
251c0 69 74 20 69 73 20 69 6e 74 65 72 70 72 65 74 65  it is interprete
251d0 64 20 61 73 20 61 6e 20 61 62 73 6f 6c 75 74 65  d as an absolute
251e0 20 70 61 74 68 2e 20 5e 49 66 20 74 68 65 20 70   path. ^If the p
251f0 61 74 68 20 64 6f 65 73 20 6e 6f 74 20 62 65 67  ath does not beg
25200 69 6e 20 0a 2a 2a 20 77 69 74 68 20 61 20 27 2f  in .** with a '/
25210 27 20 28 6d 65 61 6e 69 6e 67 20 74 68 61 74 20  ' (meaning that 
25220 74 68 65 20 61 75 74 68 6f 72 69 74 79 20 73 65  the authority se
25230 63 74 69 6f 6e 20 69 73 20 6f 6d 69 74 74 65 64  ction is omitted
25240 20 66 72 6f 6d 20 74 68 65 20 55 52 49 29 0a 2a   from the URI).*
25250 2a 20 74 68 65 6e 20 74 68 65 20 70 61 74 68 20  * then the path 
25260 69 73 20 69 6e 74 65 72 70 72 65 74 65 64 20 61  is interpreted a
25270 73 20 61 20 72 65 6c 61 74 69 76 65 20 70 61 74  s a relative pat
25280 68 2e 20 0a 2a 2a 20 5e 28 4f 6e 20 77 69 6e 64  h. .** ^(On wind
25290 6f 77 73 2c 20 74 68 65 20 66 69 72 73 74 20 63  ows, the first c
252a0 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 6e 20 61  omponent of an a
252b0 62 73 6f 6c 75 74 65 20 70 61 74 68 20 0a 2a 2a  bsolute path .**
252c0 20 69 73 20 61 20 64 72 69 76 65 20 73 70 65 63   is a drive spec
252d0 69 66 69 63 61 74 69 6f 6e 20 28 65 2e 67 2e 20  ification (e.g. 
252e0 22 43 3a 22 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b  "C:").)^.**.** [
252f0 5b 63 6f 72 65 20 55 52 49 20 71 75 65 72 79 20  [core URI query 
25300 70 61 72 61 6d 65 74 65 72 73 5d 5d 0a 2a 2a 20  parameters]].** 
25310 54 68 65 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e  The query compon
25320 65 6e 74 20 6f 66 20 61 20 55 52 49 20 6d 61 79  ent of a URI may
25330 20 63 6f 6e 74 61 69 6e 20 70 61 72 61 6d 65 74   contain paramet
25340 65 72 73 20 74 68 61 74 20 61 72 65 20 69 6e 74  ers that are int
25350 65 72 70 72 65 74 65 64 0a 2a 2a 20 65 69 74 68  erpreted.** eith
25360 65 72 20 62 79 20 53 51 4c 69 74 65 20 69 74 73  er by SQLite its
25370 65 6c 66 2c 20 6f 72 20 62 79 20 61 20 5b 56 46  elf, or by a [VF
25380 53 20 7c 20 63 75 73 74 6f 6d 20 56 46 53 20 69  S | custom VFS i
25390 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 5d 2e 0a  mplementation]..
253a0 2a 2a 20 53 51 4c 69 74 65 20 61 6e 64 20 69 74  ** SQLite and it
253b0 73 20 62 75 69 6c 74 2d 69 6e 20 5b 56 46 53 65  s built-in [VFSe
253c0 73 5d 20 69 6e 74 65 72 70 72 65 74 20 74 68 65  s] interpret the
253d0 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 71 75  .** following qu
253e0 65 72 79 20 70 61 72 61 6d 65 74 65 72 73 3a 0a  ery parameters:.
253f0 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 20  **.** <ul>.**   
25400 3c 6c 69 3e 20 3c 62 3e 76 66 73 3c 2f 62 3e 3a  <li> <b>vfs</b>:
25410 20 5e 54 68 65 20 22 76 66 73 22 20 70 61 72 61   ^The "vfs" para
25420 6d 65 74 65 72 20 6d 61 79 20 62 65 20 75 73 65  meter may be use
25430 64 20 74 6f 20 73 70 65 63 69 66 79 20 74 68 65  d to specify the
25440 20 6e 61 6d 65 20 6f 66 0a 2a 2a 20 20 20 20 20   name of.**     
25450 61 20 56 46 53 20 6f 62 6a 65 63 74 20 74 68 61  a VFS object tha
25460 74 20 70 72 6f 76 69 64 65 73 20 74 68 65 20 6f  t provides the o
25470 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20  perating system 
25480 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 20 73  interface that s
25490 68 6f 75 6c 64 0a 2a 2a 20 20 20 20 20 62 65 20  hould.**     be 
254a0 75 73 65 64 20 74 6f 20 61 63 63 65 73 73 20 74  used to access t
254b0 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
254c0 20 6f 6e 20 64 69 73 6b 2e 20 5e 49 66 20 74 68   on disk. ^If th
254d0 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 73 65 74  is option is set
254e0 20 74 6f 0a 2a 2a 20 20 20 20 20 61 6e 20 65 6d   to.**     an em
254f0 70 74 79 20 73 74 72 69 6e 67 20 74 68 65 20 64  pty string the d
25500 65 66 61 75 6c 74 20 56 46 53 20 6f 62 6a 65 63  efault VFS objec
25510 74 20 69 73 20 75 73 65 64 2e 20 5e 53 70 65 63  t is used. ^Spec
25520 69 66 79 69 6e 67 20 61 6e 20 75 6e 6b 6e 6f 77  ifying an unknow
25530 6e 0a 2a 2a 20 20 20 20 20 56 46 53 20 69 73 20  n.**     VFS is 
25540 61 6e 20 65 72 72 6f 72 2e 20 5e 49 66 20 73 71  an error. ^If sq
25550 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
25560 69 73 20 75 73 65 64 20 61 6e 64 20 74 68 65 20  is used and the 
25570 76 66 73 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a  vfs option is.**
25580 20 20 20 20 20 70 72 65 73 65 6e 74 2c 20 74 68       present, th
25590 65 6e 20 74 68 65 20 56 46 53 20 73 70 65 63 69  en the VFS speci
255a0 66 69 65 64 20 62 79 20 74 68 65 20 6f 70 74 69  fied by the opti
255b0 6f 6e 20 74 61 6b 65 73 20 70 72 65 63 65 64 65  on takes precede
255c0 6e 63 65 20 6f 76 65 72 0a 2a 2a 20 20 20 20 20  nce over.**     
255d0 74 68 65 20 76 61 6c 75 65 20 70 61 73 73 65 64  the value passed
255e0 20 61 73 20 74 68 65 20 66 6f 75 72 74 68 20 70   as the fourth p
255f0 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
25600 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a  te3_open_v2()..*
25610 2a 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e 6d  *.**   <li> <b>m
25620 6f 64 65 3c 2f 62 3e 3a 20 5e 28 54 68 65 20 6d  ode</b>: ^(The m
25630 6f 64 65 20 70 61 72 61 6d 65 74 65 72 20 6d 61  ode parameter ma
25640 79 20 62 65 20 73 65 74 20 74 6f 20 65 69 74 68  y be set to eith
25650 65 72 20 22 72 6f 22 2c 20 22 72 77 22 2c 0a 2a  er "ro", "rw",.*
25660 2a 20 20 20 20 20 22 72 77 63 22 2c 20 6f 72 20  *     "rwc", or 
25670 22 6d 65 6d 6f 72 79 22 2e 20 41 74 74 65 6d 70  "memory". Attemp
25680 74 69 6e 67 20 74 6f 20 73 65 74 20 69 74 20 74  ting to set it t
25690 6f 20 61 6e 79 20 6f 74 68 65 72 20 76 61 6c 75  o any other valu
256a0 65 20 69 73 0a 2a 2a 20 20 20 20 20 61 6e 20 65  e is.**     an e
256b0 72 72 6f 72 29 5e 2e 20 0a 2a 2a 20 20 20 20 20  rror)^. .**     
256c0 5e 49 66 20 22 72 6f 22 20 69 73 20 73 70 65 63  ^If "ro" is spec
256d0 69 66 69 65 64 2c 20 74 68 65 6e 20 74 68 65 20  ified, then the 
256e0 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e  database is open
256f0 65 64 20 66 6f 72 20 72 65 61 64 2d 6f 6e 6c 79  ed for read-only
25700 20 0a 2a 2a 20 20 20 20 20 61 63 63 65 73 73 2c   .**     access,
25710 20 6a 75 73 74 20 61 73 20 69 66 20 74 68 65 20   just as if the 
25720 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41  [SQLITE_OPEN_REA
25730 44 4f 4e 4c 59 5d 20 66 6c 61 67 20 68 61 64 20  DONLY] flag had 
25740 62 65 65 6e 20 73 65 74 20 69 6e 20 74 68 65 20  been set in the 
25750 0a 2a 2a 20 20 20 20 20 74 68 69 72 64 20 61 72  .**     third ar
25760 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65  gument to sqlite
25770 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 5e 49 66  3_open_v2(). ^If
25780 20 74 68 65 20 6d 6f 64 65 20 6f 70 74 69 6f 6e   the mode option
25790 20 69 73 20 73 65 74 20 74 6f 20 0a 2a 2a 20 20   is set to .**  
257a0 20 20 20 22 72 77 22 2c 20 74 68 65 6e 20 74 68     "rw", then th
257b0 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70  e database is op
257c0 65 6e 65 64 20 66 6f 72 20 72 65 61 64 2d 77 72  ened for read-wr
257d0 69 74 65 20 28 62 75 74 20 6e 6f 74 20 63 72 65  ite (but not cre
257e0 61 74 65 29 20 0a 2a 2a 20 20 20 20 20 61 63 63  ate) .**     acc
257f0 65 73 73 2c 20 61 73 20 69 66 20 53 51 4c 49 54  ess, as if SQLIT
25800 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45  E_OPEN_READWRITE
25810 20 28 62 75 74 20 6e 6f 74 20 53 51 4c 49 54 45   (but not SQLITE
25820 5f 4f 50 45 4e 5f 43 52 45 41 54 45 29 20 68 61  _OPEN_CREATE) ha
25830 64 20 0a 2a 2a 20 20 20 20 20 62 65 65 6e 20 73  d .**     been s
25840 65 74 2e 20 5e 56 61 6c 75 65 20 22 72 77 63 22  et. ^Value "rwc"
25850 20 69 73 20 65 71 75 69 76 61 6c 65 6e 74 20 74   is equivalent t
25860 6f 20 73 65 74 74 69 6e 67 20 62 6f 74 68 20 0a  o setting both .
25870 2a 2a 20 20 20 20 20 53 51 4c 49 54 45 5f 4f 50  **     SQLITE_OP
25880 45 4e 5f 52 45 41 44 57 52 49 54 45 20 61 6e 64  EN_READWRITE and
25890 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45   SQLITE_OPEN_CRE
258a0 41 54 45 2e 20 20 5e 49 66 20 74 68 65 20 6d 6f  ATE.  ^If the mo
258b0 64 65 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20  de option is.** 
258c0 20 20 20 20 73 65 74 20 74 6f 20 22 6d 65 6d 6f      set to "memo
258d0 72 79 22 20 74 68 65 6e 20 61 20 70 75 72 65 20  ry" then a pure 
258e0 5b 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62  [in-memory datab
258f0 61 73 65 5d 20 74 68 61 74 20 6e 65 76 65 72 20  ase] that never 
25900 72 65 61 64 73 0a 2a 2a 20 20 20 20 20 6f 72 20  reads.**     or 
25910 77 72 69 74 65 73 20 66 72 6f 6d 20 64 69 73 6b  writes from disk
25920 20 69 73 20 75 73 65 64 2e 20 5e 49 74 20 69 73   is used. ^It is
25930 20 61 6e 20 65 72 72 6f 72 20 74 6f 20 73 70 65   an error to spe
25940 63 69 66 79 20 61 20 76 61 6c 75 65 20 66 6f 72  cify a value for
25950 0a 2a 2a 20 20 20 20 20 74 68 65 20 6d 6f 64 65  .**     the mode
25960 20 70 61 72 61 6d 65 74 65 72 20 74 68 61 74 20   parameter that 
25970 69 73 20 6c 65 73 73 20 72 65 73 74 72 69 63 74  is less restrict
25980 69 76 65 20 74 68 61 6e 20 74 68 61 74 20 73 70  ive than that sp
25990 65 63 69 66 69 65 64 20 62 79 0a 2a 2a 20 20 20  ecified by.**   
259a0 20 20 74 68 65 20 66 6c 61 67 73 20 70 61 73 73    the flags pass
259b0 65 64 20 69 6e 20 74 68 65 20 74 68 69 72 64 20  ed in the third 
259c0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
259d0 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a  ite3_open_v2()..
259e0 2a 2a 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e  **.**   <li> <b>
259f0 63 61 63 68 65 3c 2f 62 3e 3a 20 5e 54 68 65 20  cache</b>: ^The 
25a00 63 61 63 68 65 20 70 61 72 61 6d 65 74 65 72 20  cache parameter 
25a10 6d 61 79 20 62 65 20 73 65 74 20 74 6f 20 65 69  may be set to ei
25a20 74 68 65 72 20 22 73 68 61 72 65 64 22 20 6f 72  ther "shared" or
25a30 0a 2a 2a 20 20 20 20 20 22 70 72 69 76 61 74 65  .**     "private
25a40 22 2e 20 5e 53 65 74 74 69 6e 67 20 69 74 20 74  ". ^Setting it t
25a50 6f 20 22 73 68 61 72 65 64 22 20 69 73 20 65 71  o "shared" is eq
25a60 75 69 76 61 6c 65 6e 74 20 74 6f 20 73 65 74 74  uivalent to sett
25a70 69 6e 67 20 74 68 65 0a 2a 2a 20 20 20 20 20 53  ing the.**     S
25a80 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45  QLITE_OPEN_SHARE
25a90 44 43 41 43 48 45 20 62 69 74 20 69 6e 20 74 68  DCACHE bit in th
25aa0 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74  e flags argument
25ab0 20 70 61 73 73 65 64 20 74 6f 0a 2a 2a 20 20 20   passed to.**   
25ac0 20 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76    sqlite3_open_v
25ad0 32 28 29 2e 20 5e 53 65 74 74 69 6e 67 20 74 68  2(). ^Setting th
25ae0 65 20 63 61 63 68 65 20 70 61 72 61 6d 65 74 65  e cache paramete
25af0 72 20 74 6f 20 22 70 72 69 76 61 74 65 22 20 69  r to "private" i
25b00 73 20 0a 2a 2a 20 20 20 20 20 65 71 75 69 76 61  s .**     equiva
25b10 6c 65 6e 74 20 74 6f 20 73 65 74 74 69 6e 67 20  lent to setting 
25b20 74 68 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  the SQLITE_OPEN_
25b30 50 52 49 56 41 54 45 43 41 43 48 45 20 62 69 74  PRIVATECACHE bit
25b40 2e 0a 2a 2a 20 20 20 20 20 5e 49 66 20 73 71 6c  ..**     ^If sql
25b50 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69  ite3_open_v2() i
25b60 73 20 75 73 65 64 20 61 6e 64 20 74 68 65 20 22  s used and the "
25b70 63 61 63 68 65 22 20 70 61 72 61 6d 65 74 65 72  cache" parameter
25b80 20 69 73 20 70 72 65 73 65 6e 74 20 69 6e 0a 2a   is present in.*
25b90 2a 20 20 20 20 20 61 20 55 52 49 20 66 69 6c 65  *     a URI file
25ba0 6e 61 6d 65 2c 20 69 74 73 20 76 61 6c 75 65 20  name, its value 
25bb0 6f 76 65 72 72 69 64 65 73 20 61 6e 79 20 62 65  overrides any be
25bc0 68 61 76 69 6f 72 20 72 65 71 75 65 73 74 65 64  havior requested
25bd0 20 62 79 20 73 65 74 74 69 6e 67 0a 2a 2a 20 20   by setting.**  
25be0 20 20 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50     SQLITE_OPEN_P
25bf0 52 49 56 41 54 45 43 41 43 48 45 20 6f 72 20 53  RIVATECACHE or S
25c00 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45  QLITE_OPEN_SHARE
25c10 44 43 41 43 48 45 20 66 6c 61 67 2e 0a 2a 2a 0a  DCACHE flag..**.
25c20 2a 2a 20 20 3c 6c 69 3e 20 3c 62 3e 70 73 6f 77  **  <li> <b>psow
25c30 3c 2f 62 3e 3a 20 5e 54 68 65 20 70 73 6f 77 20  </b>: ^The psow 
25c40 70 61 72 61 6d 65 74 65 72 20 69 6e 64 69 63 61  parameter indica
25c50 74 65 73 20 77 68 65 74 68 65 72 20 6f 72 20 6e  tes whether or n
25c60 6f 74 20 74 68 65 0a 2a 2a 20 20 20 20 20 5b 70  ot the.**     [p
25c70 6f 77 65 72 73 61 66 65 20 6f 76 65 72 77 72 69  owersafe overwri
25c80 74 65 5d 20 70 72 6f 70 65 72 74 79 20 64 6f 65  te] property doe
25c90 73 20 6f 72 20 64 6f 65 73 20 6e 6f 74 20 61 70  s or does not ap
25ca0 70 6c 79 20 74 6f 20 74 68 65 0a 2a 2a 20 20 20  ply to the.**   
25cb0 20 20 73 74 6f 72 61 67 65 20 6d 65 64 69 61 20    storage media 
25cc0 6f 6e 20 77 68 69 63 68 20 74 68 65 20 64 61 74  on which the dat
25cd0 61 62 61 73 65 20 66 69 6c 65 20 72 65 73 69 64  abase file resid
25ce0 65 73 2e 0a 2a 2a 0a 2a 2a 20 20 3c 6c 69 3e 20  es..**.**  <li> 
25cf0 3c 62 3e 6e 6f 6c 6f 63 6b 3c 2f 62 3e 3a 20 5e  <b>nolock</b>: ^
25d00 54 68 65 20 6e 6f 6c 6f 63 6b 20 70 61 72 61 6d  The nolock param
25d10 65 74 65 72 20 69 73 20 61 20 62 6f 6f 6c 65 61  eter is a boolea
25d20 6e 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65  n query paramete
25d30 72 0a 2a 2a 20 20 20 20 20 77 68 69 63 68 20 69  r.**     which i
25d40 66 20 73 65 74 20 64 69 73 61 62 6c 65 73 20 66  f set disables f
25d50 69 6c 65 20 6c 6f 63 6b 69 6e 67 20 69 6e 20 72  ile locking in r
25d60 6f 6c 6c 62 61 63 6b 20 6a 6f 75 72 6e 61 6c 20  ollback journal 
25d70 6d 6f 64 65 73 2e 20 20 54 68 69 73 0a 2a 2a 20  modes.  This.** 
25d80 20 20 20 20 69 73 20 75 73 65 66 75 6c 20 66 6f      is useful fo
25d90 72 20 61 63 63 65 73 73 69 6e 67 20 61 20 64 61  r accessing a da
25da0 74 61 62 61 73 65 20 6f 6e 20 61 20 66 69 6c 65  tabase on a file
25db0 73 79 73 74 65 6d 20 74 68 61 74 20 64 6f 65 73  system that does
25dc0 20 6e 6f 74 0a 2a 2a 20 20 20 20 20 73 75 70 70   not.**     supp
25dd0 6f 72 74 20 6c 6f 63 6b 69 6e 67 2e 20 20 43 61  ort locking.  Ca
25de0 75 74 69 6f 6e 3a 20 20 44 61 74 61 62 61 73 65  ution:  Database
25df0 20 63 6f 72 72 75 70 74 69 6f 6e 20 6d 69 67 68   corruption migh
25e00 74 20 72 65 73 75 6c 74 20 69 66 20 74 77 6f 0a  t result if two.
25e10 2a 2a 20 20 20 20 20 6f 72 20 6d 6f 72 65 20 70  **     or more p
25e20 72 6f 63 65 73 73 65 73 20 77 72 69 74 65 20 74  rocesses write t
25e30 6f 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62  o the same datab
25e40 61 73 65 20 61 6e 64 20 61 6e 79 20 6f 6e 65 20  ase and any one 
25e50 6f 66 20 74 68 6f 73 65 0a 2a 2a 20 20 20 20 20  of those.**     
25e60 70 72 6f 63 65 73 73 65 73 20 75 73 65 73 20 6e  processes uses n
25e70 6f 6c 6f 63 6b 3d 31 2e 0a 2a 2a 0a 2a 2a 20 20  olock=1..**.**  
25e80 3c 6c 69 3e 20 3c 62 3e 69 6d 6d 75 74 61 62 6c  <li> <b>immutabl
25e90 65 3c 2f 62 3e 3a 20 5e 54 68 65 20 69 6d 6d 75  e</b>: ^The immu
25ea0 74 61 62 6c 65 20 70 61 72 61 6d 65 74 65 72 20  table parameter 
25eb0 69 73 20 61 20 62 6f 6f 6c 65 61 6e 20 71 75 65  is a boolean que
25ec0 72 79 0a 2a 2a 20 20 20 20 20 70 61 72 61 6d 65  ry.**     parame
25ed0 74 65 72 20 74 68 61 74 20 69 6e 64 69 63 61 74  ter that indicat
25ee0 65 73 20 74 68 61 74 20 74 68 65 20 64 61 74 61  es that the data
25ef0 62 61 73 65 20 66 69 6c 65 20 69 73 20 73 74 6f  base file is sto
25f00 72 65 64 20 6f 6e 0a 2a 2a 20 20 20 20 20 72 65  red on.**     re
25f10 61 64 2d 6f 6e 6c 79 20 6d 65 64 69 61 2e 20 20  ad-only media.  
25f20 5e 57 68 65 6e 20 69 6d 6d 75 74 61 62 6c 65 20  ^When immutable 
25f30 69 73 20 73 65 74 2c 20 53 51 4c 69 74 65 20 61  is set, SQLite a
25f40 73 73 75 6d 65 73 20 74 68 61 74 20 74 68 65 0a  ssumes that the.
25f50 2a 2a 20 20 20 20 20 64 61 74 61 62 61 73 65 20  **     database 
25f60 66 69 6c 65 20 63 61 6e 6e 6f 74 20 62 65 20 63  file cannot be c
25f70 68 61 6e 67 65 64 2c 20 65 76 65 6e 20 62 79 20  hanged, even by 
25f80 61 20 70 72 6f 63 65 73 73 20 77 69 74 68 20 68  a process with h
25f90 69 67 68 65 72 0a 2a 2a 20 20 20 20 20 70 72 69  igher.**     pri
25fa0 76 69 6c 65 67 65 2c 20 61 6e 64 20 73 6f 20 74  vilege, and so t
25fb0 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f  he database is o
25fc0 70 65 6e 65 64 20 72 65 61 64 2d 6f 6e 6c 79 20  pened read-only 
25fd0 61 6e 64 20 61 6c 6c 20 6c 6f 63 6b 69 6e 67 0a  and all locking.
25fe0 2a 2a 20 20 20 20 20 61 6e 64 20 63 68 61 6e 67  **     and chang
25ff0 65 20 64 65 74 65 63 74 69 6f 6e 20 69 73 20 64  e detection is d
26000 69 73 61 62 6c 65 64 2e 20 20 43 61 75 74 69 6f  isabled.  Cautio
26010 6e 3a 20 53 65 74 74 69 6e 67 20 74 68 65 20 69  n: Setting the i
26020 6d 6d 75 74 61 62 6c 65 0a 2a 2a 20 20 20 20 20  mmutable.**     
26030 70 72 6f 70 65 72 74 79 20 6f 6e 20 61 20 64 61  property on a da
26040 74 61 62 61 73 65 20 66 69 6c 65 20 74 68 61 74  tabase file that
26050 20 64 6f 65 73 20 69 6e 20 66 61 63 74 20 63 68   does in fact ch
26060 61 6e 67 65 20 63 61 6e 20 72 65 73 75 6c 74 0a  ange can result.
26070 2a 2a 20 20 20 20 20 69 6e 20 69 6e 63 6f 72 72  **     in incorr
26080 65 63 74 20 71 75 65 72 79 20 72 65 73 75 6c 74  ect query result
26090 73 20 61 6e 64 2f 6f 72 20 5b 53 51 4c 49 54 45  s and/or [SQLITE
260a0 5f 43 4f 52 52 55 50 54 5d 20 65 72 72 6f 72 73  _CORRUPT] errors
260b0 2e 0a 2a 2a 20 20 20 20 20 53 65 65 20 61 6c 73  ..**     See als
260c0 6f 3a 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  o: [SQLITE_IOCAP
260d0 5f 49 4d 4d 55 54 41 42 4c 45 5d 2e 0a 2a 2a 20  _IMMUTABLE]..** 
260e0 20 20 20 20 20 20 0a 2a 2a 20 3c 2f 75 6c 3e 0a        .** </ul>.
260f0 2a 2a 0a 2a 2a 20 5e 53 70 65 63 69 66 79 69 6e  **.** ^Specifyin
26100 67 20 61 6e 20 75 6e 6b 6e 6f 77 6e 20 70 61 72  g an unknown par
26110 61 6d 65 74 65 72 20 69 6e 20 74 68 65 20 71 75  ameter in the qu
26120 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66  ery component of
26130 20 61 20 55 52 49 20 69 73 20 6e 6f 74 20 61 6e   a URI is not an
26140 0a 2a 2a 20 65 72 72 6f 72 2e 20 20 46 75 74 75  .** error.  Futu
26150 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53  re versions of S
26160 51 4c 69 74 65 20 6d 69 67 68 74 20 75 6e 64 65  QLite might unde
26170 72 73 74 61 6e 64 20 61 64 64 69 74 69 6f 6e 61  rstand additiona
26180 6c 20 71 75 65 72 79 0a 2a 2a 20 70 61 72 61 6d  l query.** param
26190 65 74 65 72 73 2e 20 20 53 65 65 20 22 5b 71 75  eters.  See "[qu
261a0 65 72 79 20 70 61 72 61 6d 65 74 65 72 73 20 77  ery parameters w
261b0 69 74 68 20 73 70 65 63 69 61 6c 20 6d 65 61 6e  ith special mean
261c0 69 6e 67 20 74 6f 20 53 51 4c 69 74 65 5d 22 20  ing to SQLite]" 
261d0 66 6f 72 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 61  for.** additiona
261e0 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a  l information..*
261f0 2a 0a 2a 2a 20 5b 5b 55 52 49 20 66 69 6c 65 6e  *.** [[URI filen
26200 61 6d 65 20 65 78 61 6d 70 6c 65 73 5d 5d 20 3c  ame examples]] <
26210 68 33 3e 55 52 49 20 66 69 6c 65 6e 61 6d 65 20  h3>URI filename 
26220 65 78 61 6d 70 6c 65 73 3c 2f 68 33 3e 0a 2a 2a  examples</h3>.**
26230 0a 2a 2a 20 3c 74 61 62 6c 65 20 62 6f 72 64 65  .** <table borde
26240 72 3d 22 31 22 20 61 6c 69 67 6e 3d 63 65 6e 74  r="1" align=cent
26250 65 72 20 63 65 6c 6c 70 61 64 64 69 6e 67 3d 35  er cellpadding=5
26260 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20 55 52  >.** <tr><th> UR
26270 49 20 66 69 6c 65 6e 61 6d 65 73 20 3c 74 68 3e  I filenames <th>
26280 20 52 65 73 75 6c 74 73 0a 2a 2a 20 3c 74 72 3e   Results.** <tr>
26290 3c 74 64 3e 20 66 69 6c 65 3a 64 61 74 61 2e 64  <td> file:data.d
262a0 62 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20  b <td> .**      
262b0 20 20 20 20 4f 70 65 6e 20 74 68 65 20 66 69 6c      Open the fil
262c0 65 20 22 64 61 74 61 2e 64 62 22 20 69 6e 20 74  e "data.db" in t
262d0 68 65 20 63 75 72 72 65 6e 74 20 64 69 72 65 63  he current direc
262e0 74 6f 72 79 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64  tory..** <tr><td
262f0 3e 20 66 69 6c 65 3a 2f 68 6f 6d 65 2f 66 72 65  > file:/home/fre
26300 64 2f 64 61 74 61 2e 64 62 3c 62 72 3e 0a 2a 2a  d/data.db<br>.**
26310 20 20 20 20 20 20 20 20 20 20 66 69 6c 65 3a 2f            file:/
26320 2f 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61  //home/fred/data
26330 2e 64 62 20 3c 62 72 3e 20 0a 2a 2a 20 20 20 20  .db <br> .**    
26340 20 20 20 20 20 20 66 69 6c 65 3a 2f 2f 6c 6f 63        file://loc
26350 61 6c 68 6f 73 74 2f 68 6f 6d 65 2f 66 72 65 64  alhost/home/fred
26360 2f 64 61 74 61 2e 64 62 20 3c 62 72 3e 20 3c 74  /data.db <br> <t
26370 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  d> .**          
26380 4f 70 65 6e 20 74 68 65 20 64 61 74 61 62 61 73  Open the databas
26390 65 20 66 69 6c 65 20 22 2f 68 6f 6d 65 2f 66 72  e file "/home/fr
263a0 65 64 2f 64 61 74 61 2e 64 62 22 2e 0a 2a 2a 20  ed/data.db"..** 
263b0 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f 2f  <tr><td> file://
263c0 64 61 72 6b 73 74 61 72 2f 68 6f 6d 65 2f 66 72  darkstar/home/fr
263d0 65 64 2f 64 61 74 61 2e 64 62 20 3c 74 64 3e 20  ed/data.db <td> 
263e0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 41 6e 20  .**          An 
263f0 65 72 72 6f 72 2e 20 22 64 61 72 6b 73 74 61 72  error. "darkstar
26400 22 20 69 73 20 6e 6f 74 20 61 20 72 65 63 6f 67  " is not a recog
26410 6e 69 7a 65 64 20 61 75 74 68 6f 72 69 74 79 2e  nized authority.
26420 0a 2a 2a 20 3c 74 72 3e 3c 74 64 20 73 74 79 6c  .** <tr><td styl
26430 65 3d 22 77 68 69 74 65 2d 73 70 61 63 65 3a 6e  e="white-space:n
26440 6f 77 72 61 70 22 3e 20 0a 2a 2a 20 20 20 20 20  owrap"> .**     
26450 20 20 20 20 20 66 69 6c 65 3a 2f 2f 2f 43 3a 2f       file:///C:/
26460 44 6f 63 75 6d 65 6e 74 73 25 32 30 61 6e 64 25  Documents%20and%
26470 32 30 53 65 74 74 69 6e 67 73 2f 66 72 65 64 2f  20Settings/fred/
26480 44 65 73 6b 74 6f 70 2f 64 61 74 61 2e 64 62 0a  Desktop/data.db.
26490 2a 2a 20 20 20 20 20 3c 74 64 3e 20 57 69 6e 64  **     <td> Wind
264a0 6f 77 73 20 6f 6e 6c 79 3a 20 4f 70 65 6e 20 74  ows only: Open t
264b0 68 65 20 66 69 6c 65 20 22 64 61 74 61 2e 64 62  he file "data.db
264c0 22 20 6f 6e 20 66 72 65 64 27 73 20 64 65 73 6b  " on fred's desk
264d0 74 6f 70 20 6f 6e 20 64 72 69 76 65 0a 2a 2a 20  top on drive.** 
264e0 20 20 20 20 20 20 20 20 20 43 3a 2e 20 4e 6f 74           C:. Not
264f0 65 20 74 68 61 74 20 74 68 65 20 25 32 30 20 65  e that the %20 e
26500 73 63 61 70 69 6e 67 20 69 6e 20 74 68 69 73 20  scaping in this 
26510 65 78 61 6d 70 6c 65 20 69 73 20 6e 6f 74 20 73  example is not s
26520 74 72 69 63 74 6c 79 20 0a 2a 2a 20 20 20 20 20  trictly .**     
26530 20 20 20 20 20 6e 65 63 65 73 73 61 72 79 20 2d       necessary -
26540 20 73 70 61 63 65 20 63 68 61 72 61 63 74 65 72   space character
26550 73 20 63 61 6e 20 62 65 20 75 73 65 64 20 6c 69  s can be used li
26560 74 65 72 61 6c 6c 79 0a 2a 2a 20 20 20 20 20 20  terally.**      
26570 20 20 20 20 69 6e 20 55 52 49 20 66 69 6c 65 6e      in URI filen
26580 61 6d 65 73 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64  ames..** <tr><td
26590 3e 20 66 69 6c 65 3a 64 61 74 61 2e 64 62 3f 6d  > file:data.db?m
265a0 6f 64 65 3d 72 6f 26 63 61 63 68 65 3d 70 72 69  ode=ro&cache=pri
265b0 76 61 74 65 20 3c 74 64 3e 20 0a 2a 2a 20 20 20  vate <td> .**   
265c0 20 20 20 20 20 20 20 4f 70 65 6e 20 66 69 6c 65         Open file
265d0 20 22 64 61 74 61 2e 64 62 22 20 69 6e 20 74 68   "data.db" in th
265e0 65 20 63 75 72 72 65 6e 74 20 64 69 72 65 63 74  e current direct
265f0 6f 72 79 20 66 6f 72 20 72 65 61 64 2d 6f 6e 6c  ory for read-onl
26600 79 20 61 63 63 65 73 73 2e 0a 2a 2a 20 20 20 20  y access..**    
26610 20 20 20 20 20 20 52 65 67 61 72 64 6c 65 73 73        Regardless
26620 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e   of whether or n
26630 6f 74 20 73 68 61 72 65 64 2d 63 61 63 68 65 20  ot shared-cache 
26640 6d 6f 64 65 20 69 73 20 65 6e 61 62 6c 65 64 20  mode is enabled 
26650 62 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 64  by.**          d
26660 65 66 61 75 6c 74 2c 20 75 73 65 20 61 20 70 72  efault, use a pr
26670 69 76 61 74 65 20 63 61 63 68 65 2e 0a 2a 2a 20  ivate cache..** 
26680 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f 68  <tr><td> file:/h
26690 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62  ome/fred/data.db
266a0 3f 76 66 73 3d 75 6e 69 78 2d 64 6f 74 66 69 6c  ?vfs=unix-dotfil
266b0 65 20 3c 74 64 3e 0a 2a 2a 20 20 20 20 20 20 20  e <td>.**       
266c0 20 20 20 4f 70 65 6e 20 66 69 6c 65 20 22 2f 68     Open file "/h
266d0 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62  ome/fred/data.db
266e0 22 2e 20 55 73 65 20 74 68 65 20 73 70 65 63 69  ". Use the speci
266f0 61 6c 20 56 46 53 20 22 75 6e 69 78 2d 64 6f 74  al VFS "unix-dot
26700 66 69 6c 65 22 0a 2a 2a 20 20 20 20 20 20 20 20  file".**        
26710 20 20 74 68 61 74 20 75 73 65 73 20 64 6f 74 2d    that uses dot-
26720 66 69 6c 65 73 20 69 6e 20 70 6c 61 63 65 20 6f  files in place o
26730 66 20 70 6f 73 69 78 20 61 64 76 69 73 6f 72 79  f posix advisory
26740 20 6c 6f 63 6b 69 6e 67 2e 0a 2a 2a 20 3c 74 72   locking..** <tr
26750 3e 3c 74 64 3e 20 66 69 6c 65 3a 64 61 74 61 2e  ><td> file:data.
26760 64 62 3f 6d 6f 64 65 3d 72 65 61 64 6f 6e 6c 79  db?mode=readonly
26770 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20   <td> .**       
26780 20 20 20 41 6e 20 65 72 72 6f 72 2e 20 22 72 65     An error. "re
26790 61 64 6f 6e 6c 79 22 20 69 73 20 6e 6f 74 20 61  adonly" is not a
267a0 20 76 61 6c 69 64 20 6f 70 74 69 6f 6e 20 66 6f   valid option fo
267b0 72 20 74 68 65 20 22 6d 6f 64 65 22 20 70 61 72  r the "mode" par
267c0 61 6d 65 74 65 72 2e 0a 2a 2a 20 3c 2f 74 61 62  ameter..** </tab
267d0 6c 65 3e 0a 2a 2a 0a 2a 2a 20 5e 55 52 49 20 68  le>.**.** ^URI h
267e0 65 78 61 64 65 63 69 6d 61 6c 20 65 73 63 61 70  exadecimal escap
267f0 65 20 73 65 71 75 65 6e 63 65 73 20 28 25 48 48  e sequences (%HH
26800 29 20 61 72 65 20 73 75 70 70 6f 72 74 65 64 20  ) are supported 
26810 77 69 74 68 69 6e 20 74 68 65 20 70 61 74 68 20  within the path 
26820 61 6e 64 0a 2a 2a 20 71 75 65 72 79 20 63 6f 6d  and.** query com
26830 70 6f 6e 65 6e 74 73 20 6f 66 20 61 20 55 52 49  ponents of a URI
26840 2e 20 41 20 68 65 78 61 64 65 63 69 6d 61 6c 20  . A hexadecimal 
26850 65 73 63 61 70 65 20 73 65 71 75 65 6e 63 65 20  escape sequence 
26860 63 6f 6e 73 69 73 74 73 20 6f 66 20 61 0a 2a 2a  consists of a.**
26870 20 70 65 72 63 65 6e 74 20 73 69 67 6e 20 2d 20   percent sign - 
26880 22 25 22 20 2d 20 66 6f 6c 6c 6f 77 65 64 20 62  "%" - followed b
26890 79 20 65 78 61 63 74 6c 79 20 74 77 6f 20 68 65  y exactly two he
268a0 78 61 64 65 63 69 6d 61 6c 20 64 69 67 69 74 73  xadecimal digits
268b0 20 0a 2a 2a 20 73 70 65 63 69 66 79 69 6e 67 20   .** specifying 
268c0 61 6e 20 6f 63 74 65 74 20 76 61 6c 75 65 2e 20  an octet value. 
268d0 5e 42 65 66 6f 72 65 20 74 68 65 20 70 61 74 68  ^Before the path
268e0 20 6f 72 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e   or query compon
268f0 65 6e 74 73 20 6f 66 20 61 0a 2a 2a 20 55 52 49  ents of a.** URI
26900 20 66 69 6c 65 6e 61 6d 65 20 61 72 65 20 69 6e   filename are in
26910 74 65 72 70 72 65 74 65 64 2c 20 74 68 65 79 20  terpreted, they 
26920 61 72 65 20 65 6e 63 6f 64 65 64 20 75 73 69 6e  are encoded usin
26930 67 20 55 54 46 2d 38 20 61 6e 64 20 61 6c 6c 20  g UTF-8 and all 
26940 0a 2a 2a 20 68 65 78 61 64 65 63 69 6d 61 6c 20  .** hexadecimal 
26950 65 73 63 61 70 65 20 73 65 71 75 65 6e 63 65 73  escape sequences
26960 20 72 65 70 6c 61 63 65 64 20 62 79 20 61 20 73   replaced by a s
26970 69 6e 67 6c 65 20 62 79 74 65 20 63 6f 6e 74 61  ingle byte conta
26980 69 6e 69 6e 67 20 74 68 65 0a 2a 2a 20 63 6f 72  ining the.** cor
26990 72 65 73 70 6f 6e 64 69 6e 67 20 6f 63 74 65 74  responding octet
269a0 2e 20 49 66 20 74 68 69 73 20 70 72 6f 63 65 73  . If this proces
269b0 73 20 67 65 6e 65 72 61 74 65 73 20 61 6e 20 69  s generates an i
269c0 6e 76 61 6c 69 64 20 55 54 46 2d 38 20 65 6e 63  nvalid UTF-8 enc
269d0 6f 64 69 6e 67 2c 0a 2a 2a 20 74 68 65 20 72 65  oding,.** the re
269e0 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69  sults are undefi
269f0 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f  ned..**.** <b>No
26a00 74 65 20 74 6f 20 57 69 6e 64 6f 77 73 20 75 73  te to Windows us
26a10 65 72 73 3a 3c 2f 62 3e 20 20 54 68 65 20 65 6e  ers:</b>  The en
26a20 63 6f 64 69 6e 67 20 75 73 65 64 20 66 6f 72 20  coding used for 
26a30 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67  the filename arg
26a40 75 6d 65 6e 74 0a 2a 2a 20 6f 66 20 73 71 6c 69  ument.** of sqli
26a50 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73  te3_open() and s
26a60 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
26a70 20 6d 75 73 74 20 62 65 20 55 54 46 2d 38 2c 20   must be UTF-8, 
26a80 6e 6f 74 20 77 68 61 74 65 76 65 72 0a 2a 2a 20  not whatever.** 
26a90 63 6f 64 65 70 61 67 65 20 69 73 20 63 75 72 72  codepage is curr
26aa0 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 2e 20 20  ently defined.  
26ab0 46 69 6c 65 6e 61 6d 65 73 20 63 6f 6e 74 61 69  Filenames contai
26ac0 6e 69 6e 67 20 69 6e 74 65 72 6e 61 74 69 6f 6e  ning internation
26ad0 61 6c 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 73  al.** characters
26ae0 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74   must be convert
26af0 65 64 20 74 6f 20 55 54 46 2d 38 20 70 72 69 6f  ed to UTF-8 prio
26b00 72 20 74 6f 20 70 61 73 73 69 6e 67 20 74 68 65  r to passing the
26b10 6d 20 69 6e 74 6f 0a 2a 2a 20 73 71 6c 69 74 65  m into.** sqlite
26b20 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c 69  3_open() or sqli
26b30 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a  te3_open_v2()..*
26b40 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74 6f 20  *.** <b>Note to 
26b50 57 69 6e 64 6f 77 73 20 52 75 6e 74 69 6d 65 20  Windows Runtime 
26b60 75 73 65 72 73 3a 3c 2f 62 3e 20 20 54 68 65 20  users:</b>  The 
26b70 74 65 6d 70 6f 72 61 72 79 20 64 69 72 65 63 74  temporary direct
26b80 6f 72 79 20 6d 75 73 74 20 62 65 20 73 65 74 0a  ory must be set.
26b90 2a 2a 20 70 72 69 6f 72 20 74 6f 20 63 61 6c 6c  ** prior to call
26ba0 69 6e 67 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ing sqlite3_open
26bb0 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70  () or sqlite3_op
26bc0 65 6e 5f 76 32 28 29 2e 20 20 4f 74 68 65 72 77  en_v2().  Otherw
26bd0 69 73 65 2c 20 76 61 72 69 6f 75 73 0a 2a 2a 20  ise, various.** 
26be0 66 65 61 74 75 72 65 73 20 74 68 61 74 20 72 65  features that re
26bf0 71 75 69 72 65 20 74 68 65 20 75 73 65 20 6f 66  quire the use of
26c00 20 74 65 6d 70 6f 72 61 72 79 20 66 69 6c 65 73   temporary files
26c10 20 6d 61 79 20 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a   may fail..**.**
26c20 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69   See also: [sqli
26c30 74 65 33 5f 74 65 6d 70 5f 64 69 72 65 63 74 6f  te3_temp_directo
26c40 72 79 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  ry].*/.SQLITE_AP
26c50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70  I int sqlite3_op
26c60 65 6e 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72  en(.  const char
26c70 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a   *filename,   /*
26c80 20 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61   Database filena
26c90 6d 65 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20  me (UTF-8) */.  
26ca0 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 20 20  sqlite3 **ppDb  
26cb0 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20          /* OUT: 
26cc0 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65  SQLite db handle
26cd0 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50   */.);.SQLITE_AP
26ce0 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70  I int sqlite3_op
26cf0 65 6e 31 36 28 0a 20 20 63 6f 6e 73 74 20 76 6f  en16(.  const vo
26d00 69 64 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20  id *filename,   
26d10 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c 65  /* Database file
26d20 6e 61 6d 65 20 28 55 54 46 2d 31 36 29 20 2a 2f  name (UTF-16) */
26d30 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44  .  sqlite3 **ppD
26d40 62 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55  b          /* OU
26d50 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e  T: SQLite db han
26d60 64 6c 65 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45  dle */.);.SQLITE
26d70 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
26d80 5f 6f 70 65 6e 5f 76 32 28 0a 20 20 63 6f 6e 73  _open_v2(.  cons
26d90 74 20 63 68 61 72 20 2a 66 69 6c 65 6e 61 6d 65  t char *filename
26da0 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20  ,   /* Database 
26db0 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 38 29  filename (UTF-8)
26dc0 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a   */.  sqlite3 **
26dd0 70 70 44 62 2c 20 20 20 20 20 20 20 20 20 2f 2a  ppDb,         /*
26de0 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20   OUT: SQLite db 
26df0 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 69 6e 74 20  handle */.  int 
26e00 66 6c 61 67 73 2c 20 20 20 20 20 20 20 20 20 20  flags,          
26e10 20 20 20 20 2f 2a 20 46 6c 61 67 73 20 2a 2f 0a      /* Flags */.
26e20 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 56    const char *zV
26e30 66 73 20 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d  fs        /* Nam
26e40 65 20 6f 66 20 56 46 53 20 6d 6f 64 75 6c 65 20  e of VFS module 
26e50 74 6f 20 75 73 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a  to use */.);../*
26e60 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 62  .** CAPI3REF: Ob
26e70 74 61 69 6e 20 56 61 6c 75 65 73 20 46 6f 72 20  tain Values For 
26e80 55 52 49 20 50 61 72 61 6d 65 74 65 72 73 0a 2a  URI Parameters.*
26e90 2a 0a 2a 2a 20 54 68 65 73 65 20 61 72 65 20 75  *.** These are u
26ea0 74 69 6c 69 74 79 20 72 6f 75 74 69 6e 65 73 2c  tility routines,
26eb0 20 75 73 65 66 75 6c 20 74 6f 20 56 46 53 20 69   useful to VFS i
26ec0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 2c 20  mplementations, 
26ed0 74 68 61 74 20 63 68 65 63 6b 0a 2a 2a 20 74 6f  that check.** to
26ee0 20 73 65 65 20 69 66 20 61 20 64 61 74 61 62 61   see if a databa
26ef0 73 65 20 66 69 6c 65 20 77 61 73 20 61 20 55 52  se file was a UR
26f00 49 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 65 64  I that contained
26f10 20 61 20 73 70 65 63 69 66 69 63 20 71 75 65 72   a specific quer
26f20 79 20 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 2c  y .** parameter,
26f30 20 61 6e 64 20 69 66 20 73 6f 20 6f 62 74 61 69   and if so obtai
26f40 6e 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20  ns the value of 
26f50 74 68 61 74 20 71 75 65 72 79 20 70 61 72 61 6d  that query param
26f60 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 46  eter..**.** If F
26f70 20 69 73 20 74 68 65 20 64 61 74 61 62 61 73 65   is the database
26f80 20 66 69 6c 65 6e 61 6d 65 20 70 6f 69 6e 74 65   filename pointe
26f90 72 20 70 61 73 73 65 64 20 69 6e 74 6f 20 74 68  r passed into th
26fa0 65 20 78 4f 70 65 6e 28 29 20 6d 65 74 68 6f 64  e xOpen() method
26fb0 20 6f 66 20 0a 2a 2a 20 61 20 56 46 53 20 69 6d   of .** a VFS im
26fc0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 68 65  plementation whe
26fd0 6e 20 74 68 65 20 66 6c 61 67 73 20 70 61 72 61  n the flags para
26fe0 6d 65 74 65 72 20 74 6f 20 78 4f 70 65 6e 28 29  meter to xOpen()
26ff0 20 68 61 73 20 6f 6e 65 20 6f 72 20 0a 2a 2a 20   has one or .** 
27000 6d 6f 72 65 20 6f 66 20 74 68 65 20 5b 53 51 4c  more of the [SQL
27010 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 6f 72  ITE_OPEN_URI] or
27020 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41   [SQLITE_OPEN_MA
27030 49 4e 5f 44 42 5d 20 62 69 74 73 20 73 65 74 20  IN_DB] bits set 
27040 61 6e 64 0a 2a 2a 20 50 20 69 73 20 74 68 65 20  and.** P is the 
27050 6e 61 6d 65 20 6f 66 20 74 68 65 20 71 75 65 72  name of the quer
27060 79 20 70 61 72 61 6d 65 74 65 72 2c 20 74 68 65  y parameter, the
27070 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75 72 69  n.** sqlite3_uri
27080 5f 70 61 72 61 6d 65 74 65 72 28 46 2c 50 29 20  _parameter(F,P) 
27090 72 65 74 75 72 6e 73 20 74 68 65 20 76 61 6c 75  returns the valu
270a0 65 20 6f 66 20 74 68 65 20 50 0a 2a 2a 20 70 61  e of the P.** pa
270b0 72 61 6d 65 74 65 72 20 69 66 20 69 74 20 65 78  rameter if it ex
270c0 69 73 74 73 20 6f 72 20 61 20 4e 55 4c 4c 20 70  ists or a NULL p
270d0 6f 69 6e 74 65 72 20 69 66 20 50 20 64 6f 65 73  ointer if P does
270e0 20 6e 6f 74 20 61 70 70 65 61 72 20 61 73 20 61   not appear as a
270f0 20 0a 2a 2a 20 71 75 65 72 79 20 70 61 72 61 6d   .** query param
27100 65 74 65 72 20 6f 6e 20 46 2e 20 20 49 66 20 50  eter on F.  If P
27110 20 69 73 20 61 20 71 75 65 72 79 20 70 61 72 61   is a query para
27120 6d 65 74 65 72 20 6f 66 20 46 0a 2a 2a 20 68 61  meter of F.** ha
27130 73 20 6e 6f 20 65 78 70 6c 69 63 69 74 20 76 61  s no explicit va
27140 6c 75 65 2c 20 74 68 65 6e 20 73 71 6c 69 74 65  lue, then sqlite
27150 33 5f 75 72 69 5f 70 61 72 61 6d 65 74 65 72 28  3_uri_parameter(
27160 46 2c 50 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20  F,P) returns.** 
27170 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  a pointer to an 
27180 65 6d 70 74 79 20 73 74 72 69 6e 67 2e 0a 2a 2a  empty string..**
27190 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
271a0 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c  uri_boolean(F,P,
271b0 42 29 20 72 6f 75 74 69 6e 65 20 61 73 73 75 6d  B) routine assum
271c0 65 73 20 74 68 61 74 20 50 20 69 73 20 61 20 62  es that P is a b
271d0 6f 6f 6c 65 61 6e 0a 2a 2a 20 70 61 72 61 6d 65  oolean.** parame
271e0 74 65 72 20 61 6e 64 20 72 65 74 75 72 6e 73 20  ter and returns 
271f0 74 72 75 65 20 28 31 29 20 6f 72 20 66 61 6c 73  true (1) or fals
27200 65 20 28 30 29 20 61 63 63 6f 72 64 69 6e 67 20  e (0) according 
27210 74 6f 20 74 68 65 20 76 61 6c 75 65 0a 2a 2a 20  to the value.** 
27220 6f 66 20 50 2e 20 20 54 68 65 20 73 71 6c 69 74  of P.  The sqlit
27230 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46  e3_uri_boolean(F
27240 2c 50 2c 42 29 20 72 6f 75 74 69 6e 65 20 72 65  ,P,B) routine re
27250 74 75 72 6e 73 20 74 72 75 65 20 28 31 29 20 69  turns true (1) i
27260 66 20 74 68 65 0a 2a 2a 20 76 61 6c 75 65 20 6f  f the.** value o
27270 66 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65  f query paramete
27280 72 20 50 20 69 73 20 6f 6e 65 20 6f 66 20 22 79  r P is one of "y
27290 65 73 22 2c 20 22 74 72 75 65 22 2c 20 6f 72 20  es", "true", or 
272a0 22 6f 6e 22 20 69 6e 20 61 6e 79 0a 2a 2a 20 63  "on" in any.** c
272b0 61 73 65 20 6f 72 20 69 66 20 74 68 65 20 76 61  ase or if the va
272c0 6c 75 65 20 62 65 67 69 6e 73 20 77 69 74 68 20  lue begins with 
272d0 61 20 6e 6f 6e 2d 7a 65 72 6f 20 6e 75 6d 62 65  a non-zero numbe
272e0 72 2e 20 20 54 68 65 20 0a 2a 2a 20 73 71 6c 69  r.  The .** sqli
272f0 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28  te3_uri_boolean(
27300 46 2c 50 2c 42 29 20 72 6f 75 74 69 6e 65 73 20  F,P,B) routines 
27310 72 65 74 75 72 6e 73 20 66 61 6c 73 65 20 28 30  returns false (0
27320 29 20 69 66 20 74 68 65 20 76 61 6c 75 65 20 6f  ) if the value o
27330 66 0a 2a 2a 20 71 75 65 72 79 20 70 61 72 61 6d  f.** query param
27340 65 74 65 72 20 50 20 69 73 20 6f 6e 65 20 6f 66  eter P is one of
27350 20 22 6e 6f 22 2c 20 22 66 61 6c 73 65 22 2c 20   "no", "false", 
27360 6f 72 20 22 6f 66 66 22 20 69 6e 20 61 6e 79 20  or "off" in any 
27370 63 61 73 65 20 6f 72 0a 2a 2a 20 69 66 20 74 68  case or.** if th
27380 65 20 76 61 6c 75 65 20 62 65 67 69 6e 73 20 77  e value begins w
27390 69 74 68 20 61 20 6e 75 6d 65 72 69 63 20 7a 65  ith a numeric ze
273a0 72 6f 2e 20 20 49 66 20 50 20 69 73 20 6e 6f 74  ro.  If P is not
273b0 20 61 20 71 75 65 72 79 0a 2a 2a 20 70 61 72 61   a query.** para
273c0 6d 65 74 65 72 20 6f 6e 20 46 20 6f 72 20 69 66  meter on F or if
273d0 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 50 20   the value of P 
273e0 69 73 20 64 6f 65 73 20 6e 6f 74 20 6d 61 74 63  is does not matc
273f0 68 20 61 6e 79 20 6f 66 20 74 68 65 0a 2a 2a 20  h any of the.** 
27400 61 62 6f 76 65 2c 20 74 68 65 6e 20 73 71 6c 69  above, then sqli
27410 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28  te3_uri_boolean(
27420 46 2c 50 2c 42 29 20 72 65 74 75 72 6e 73 20 28  F,P,B) returns (
27430 42 21 3d 30 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  B!=0)..**.** The
27440 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 69 6e 74   sqlite3_uri_int
27450 36 34 28 46 2c 50 2c 44 29 20 72 6f 75 74 69 6e  64(F,P,D) routin
27460 65 20 63 6f 6e 76 65 72 74 73 20 74 68 65 20 76  e converts the v
27470 61 6c 75 65 20 6f 66 20 50 20 69 6e 74 6f 20 61  alue of P into a
27480 0a 2a 2a 20 36 34 2d 62 69 74 20 73 69 67 6e 65  .** 64-bit signe
27490 64 20 69 6e 74 65 67 65 72 20 61 6e 64 20 72 65  d integer and re
274a0 74 75 72 6e 73 20 74 68 61 74 20 69 6e 74 65 67  turns that integ
274b0 65 72 2c 20 6f 72 20 44 20 69 66 20 50 20 64 6f  er, or D if P do
274c0 65 73 20 6e 6f 74 0a 2a 2a 20 65 78 69 73 74 2e  es not.** exist.
274d0 20 20 49 66 20 74 68 65 20 76 61 6c 75 65 20 6f    If the value o
274e0 66 20 50 20 69 73 20 73 6f 6d 65 74 68 69 6e 67  f P is something
274f0 20 6f 74 68 65 72 20 74 68 61 6e 20 61 6e 20 69   other than an i
27500 6e 74 65 67 65 72 2c 20 74 68 65 6e 0a 2a 2a 20  nteger, then.** 
27510 7a 65 72 6f 20 69 73 20 72 65 74 75 72 6e 65 64  zero is returned
27520 2e 0a 2a 2a 20 0a 2a 2a 20 49 66 20 46 20 69 73  ..** .** If F is
27530 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c   a NULL pointer,
27540 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 75 72   then sqlite3_ur
27550 69 5f 70 61 72 61 6d 65 74 65 72 28 46 2c 50 29  i_parameter(F,P)
27560 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 20 61 6e   returns NULL an
27570 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75 72 69  d.** sqlite3_uri
27580 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20  _boolean(F,P,B) 
27590 72 65 74 75 72 6e 73 20 42 2e 20 20 49 66 20 46  returns B.  If F
275a0 20 69 73 20 6e 6f 74 20 61 20 4e 55 4c 4c 20 70   is not a NULL p
275b0 6f 69 6e 74 65 72 20 61 6e 64 0a 2a 2a 20 69 73  ointer and.** is
275c0 20 6e 6f 74 20 61 20 64 61 74 61 62 61 73 65 20   not a database 
275d0 66 69 6c 65 20 70 61 74 68 6e 61 6d 65 20 70 6f  file pathname po
275e0 69 6e 74 65 72 20 74 68 61 74 20 53 51 4c 69 74  inter that SQLit
275f0 65 20 70 61 73 73 65 64 20 69 6e 74 6f 20 74 68  e passed into th
27600 65 20 78 4f 70 65 6e 0a 2a 2a 20 56 46 53 20 6d  e xOpen.** VFS m
27610 65 74 68 6f 64 2c 20 74 68 65 6e 20 74 68 65 20  ethod, then the 
27620 62 65 68 61 76 69 6f 72 20 6f 66 20 74 68 69 73  behavior of this
27630 20 72 6f 75 74 69 6e 65 20 69 73 20 75 6e 64 65   routine is unde
27640 66 69 6e 65 64 20 61 6e 64 20 70 72 6f 62 61 62  fined and probab
27650 6c 79 0a 2a 2a 20 75 6e 64 65 73 69 72 61 62 6c  ly.** undesirabl
27660 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  e..*/.SQLITE_API
27670 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c   const char *sql
27680 69 74 65 33 5f 75 72 69 5f 70 61 72 61 6d 65 74  ite3_uri_paramet
27690 65 72 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  er(const char *z
276a0 46 69 6c 65 6e 61 6d 65 2c 20 63 6f 6e 73 74 20  Filename, const 
276b0 63 68 61 72 20 2a 7a 50 61 72 61 6d 29 3b 0a 53  char *zParam);.S
276c0 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
276d0 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61  lite3_uri_boolea
276e0 6e 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46  n(const char *zF
276f0 69 6c 65 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  ile, const char 
27700 2a 7a 50 61 72 61 6d 2c 20 69 6e 74 20 62 44 65  *zParam, int bDe
27710 66 61 75 6c 74 29 3b 0a 53 51 4c 49 54 45 5f 41  fault);.SQLITE_A
27720 50 49 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  PI sqlite3_int64
27730 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 69 6e 74   sqlite3_uri_int
27740 36 34 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20  64(const char*, 
27750 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 73 71 6c  const char*, sql
27760 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 0a 0a 2f  ite3_int64);.../
27770 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45  *.** CAPI3REF: E
27780 72 72 6f 72 20 43 6f 64 65 73 20 41 6e 64 20 4d  rror Codes And M
27790 65 73 73 61 67 65 73 0a 2a 2a 20 4d 45 54 48 4f  essages.** METHO
277a0 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a  D: sqlite3.**.**
277b0 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65   ^If the most re
277c0 63 65 6e 74 20 73 71 6c 69 74 65 33 5f 2a 20 41  cent sqlite3_* A
277d0 50 49 20 63 61 6c 6c 20 61 73 73 6f 63 69 61 74  PI call associat
277e0 65 64 20 77 69 74 68 20 0a 2a 2a 20 5b 64 61 74  ed with .** [dat
277f0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
27800 5d 20 44 20 66 61 69 6c 65 64 2c 20 74 68 65 6e  ] D failed, then
27810 20 74 68 65 20 73 71 6c 69 74 65 33 5f 65 72 72   the sqlite3_err
27820 63 6f 64 65 28 44 29 20 69 6e 74 65 72 66 61 63  code(D) interfac
27830 65 0a 2a 2a 20 72 65 74 75 72 6e 73 20 74 68 65  e.** returns the
27840 20 6e 75 6d 65 72 69 63 20 5b 72 65 73 75 6c 74   numeric [result
27850 20 63 6f 64 65 5d 20 6f 72 20 5b 65 78 74 65 6e   code] or [exten
27860 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 5d  ded result code]
27870 20 66 6f 72 20 74 68 61 74 0a 2a 2a 20 41 50 49   for that.** API
27880 20 63 61 6c 6c 2e 0a 2a 2a 20 49 66 20 74 68 65   call..** If the
27890 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 41 50 49   most recent API
278a0 20 63 61 6c 6c 20 77 61 73 20 73 75 63 63 65 73   call was succes
278b0 73 66 75 6c 2c 0a 2a 2a 20 74 68 65 6e 20 74 68  sful,.** then th
278c0 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66  e return value f
278d0 72 6f 6d 20 73 71 6c 69 74 65 33 5f 65 72 72 63  rom sqlite3_errc
278e0 6f 64 65 28 29 20 69 73 20 75 6e 64 65 66 69 6e  ode() is undefin
278f0 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  ed..** ^The sqli
27900 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 65 72 72  te3_extended_err
27910 63 6f 64 65 28 29 0a 2a 2a 20 69 6e 74 65 72 66  code().** interf
27920 61 63 65 20 69 73 20 74 68 65 20 73 61 6d 65 20  ace is the same 
27930 65 78 63 65 70 74 20 74 68 61 74 20 69 74 20 61  except that it a
27940 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20 74 68  lways returns th
27950 65 20 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20  e .** [extended 
27960 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 65 76 65  result code] eve
27970 6e 20 77 68 65 6e 20 65 78 74 65 6e 64 65 64 20  n when extended 
27980 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65  result codes are
27990 0a 2a 2a 20 64 69 73 61 62 6c 65 64 2e 0a 2a 2a  .** disabled..**
279a0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
279b0 5f 65 72 72 6d 73 67 28 29 20 61 6e 64 20 73 71  _errmsg() and sq
279c0 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29  lite3_errmsg16()
279d0 20 72 65 74 75 72 6e 20 45 6e 67 6c 69 73 68 2d   return English-
279e0 6c 61 6e 67 75 61 67 65 0a 2a 2a 20 74 65 78 74  language.** text
279f0 20 74 68 61 74 20 64 65 73 63 72 69 62 65 73 20   that describes 
27a00 74 68 65 20 65 72 72 6f 72 2c 20 61 73 20 65 69  the error, as ei
27a10 74 68 65 72 20 55 54 46 2d 38 20 6f 72 20 55 54  ther UTF-8 or UT
27a20 46 2d 31 36 20 72 65 73 70 65 63 74 69 76 65 6c  F-16 respectivel
27a30 79 2e 0a 2a 2a 20 5e 28 4d 65 6d 6f 72 79 20 74  y..** ^(Memory t
27a40 6f 20 68 6f 6c 64 20 74 68 65 20 65 72 72 6f 72  o hold the error
27a50 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67 20   message string 
27a60 69 73 20 6d 61 6e 61 67 65 64 20 69 6e 74 65 72  is managed inter
27a70 6e 61 6c 6c 79 2e 0a 2a 2a 20 54 68 65 20 61 70  nally..** The ap
27a80 70 6c 69 63 61 74 69 6f 6e 20 64 6f 65 73 20 6e  plication does n
27a90 6f 74 20 6e 65 65 64 20 74 6f 20 77 6f 72 72 79  ot need to worry
27aa0 20 61 62 6f 75 74 20 66 72 65 65 69 6e 67 20 74   about freeing t
27ab0 68 65 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 48 6f  he result..** Ho
27ac0 77 65 76 65 72 2c 20 74 68 65 20 65 72 72 6f 72  wever, the error
27ad0 20 73 74 72 69 6e 67 20 6d 69 67 68 74 20 62 65   string might be
27ae0 20 6f 76 65 72 77 72 69 74 74 65 6e 20 6f 72 20   overwritten or 
27af0 64 65 61 6c 6c 6f 63 61 74 65 64 20 62 79 0a 2a  deallocated by.*
27b00 2a 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c  * subsequent cal
27b10 6c 73 20 74 6f 20 6f 74 68 65 72 20 53 51 4c 69  ls to other SQLi
27b20 74 65 20 69 6e 74 65 72 66 61 63 65 20 66 75 6e  te interface fun
27b30 63 74 69 6f 6e 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20  ctions.)^.**.** 
27b40 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 72 72  ^The sqlite3_err
27b50 73 74 72 28 29 20 69 6e 74 65 72 66 61 63 65 20  str() interface 
27b60 72 65 74 75 72 6e 73 20 74 68 65 20 45 6e 67 6c  returns the Engl
27b70 69 73 68 2d 6c 61 6e 67 75 61 67 65 20 74 65 78  ish-language tex
27b80 74 0a 2a 2a 20 74 68 61 74 20 64 65 73 63 72 69  t.** that descri
27b90 62 65 73 20 74 68 65 20 5b 72 65 73 75 6c 74 20  bes the [result 
27ba0 63 6f 64 65 5d 2c 20 61 73 20 55 54 46 2d 38 2e  code], as UTF-8.
27bb0 0a 2a 2a 20 5e 28 4d 65 6d 6f 72 79 20 74 6f 20  .** ^(Memory to 
27bc0 68 6f 6c 64 20 74 68 65 20 65 72 72 6f 72 20 6d  hold the error m
27bd0 65 73 73 61 67 65 20 73 74 72 69 6e 67 20 69 73  essage string is
27be0 20 6d 61 6e 61 67 65 64 20 69 6e 74 65 72 6e 61   managed interna
27bf0 6c 6c 79 0a 2a 2a 20 61 6e 64 20 6d 75 73 74 20  lly.** and must 
27c00 6e 6f 74 20 62 65 20 66 72 65 65 64 20 62 79 20  not be freed by 
27c10 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 29  the application)
27c20 5e 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68  ^..**.** When th
27c30 65 20 73 65 72 69 61 6c 69 7a 65 64 20 5b 74 68  e serialized [th
27c40 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 69 73  reading mode] is
27c50 20 69 6e 20 75 73 65 2c 20 69 74 20 6d 69 67 68   in use, it migh
27c60 74 20 62 65 20 74 68 65 0a 2a 2a 20 63 61 73 65  t be the.** case
27c70 20 74 68 61 74 20 61 20 73 65 63 6f 6e 64 20 65   that a second e
27c80 72 72 6f 72 20 6f 63 63 75 72 73 20 6f 6e 20 61  rror occurs on a
27c90 20 73 65 70 61 72 61 74 65 20 74 68 72 65 61 64   separate thread
27ca0 20 69 6e 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74   in between.** t
27cb0 68 65 20 74 69 6d 65 20 6f 66 20 74 68 65 20 66  he time of the f
27cc0 69 72 73 74 20 65 72 72 6f 72 20 61 6e 64 20 74  irst error and t
27cd0 68 65 20 63 61 6c 6c 20 74 6f 20 74 68 65 73 65  he call to these
27ce0 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20   interfaces..** 
27cf0 57 68 65 6e 20 74 68 61 74 20 68 61 70 70 65 6e  When that happen
27d00 73 2c 20 74 68 65 20 73 65 63 6f 6e 64 20 65 72  s, the second er
27d10 72 6f 72 20 77 69 6c 6c 20 62 65 20 72 65 70 6f  ror will be repo
27d20 72 74 65 64 20 73 69 6e 63 65 20 74 68 65 73 65  rted since these
27d30 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 61  .** interfaces a
27d40 6c 77 61 79 73 20 72 65 70 6f 72 74 20 74 68 65  lways report the
27d50 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 72 65 73   most recent res
27d60 75 6c 74 2e 20 20 54 6f 20 61 76 6f 69 64 0a 2a  ult.  To avoid.*
27d70 2a 20 74 68 69 73 2c 20 65 61 63 68 20 74 68 72  * this, each thr
27d80 65 61 64 20 63 61 6e 20 6f 62 74 61 69 6e 20 65  ead can obtain e
27d90 78 63 6c 75 73 69 76 65 20 75 73 65 20 6f 66 20  xclusive use of 
27da0 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
27db0 6e 6e 65 63 74 69 6f 6e 5d 20 44 0a 2a 2a 20 62  nnection] D.** b
27dc0 79 20 69 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c 69  y invoking [sqli
27dd0 74 65 33 5f 6d 75 74 65 78 5f 65 6e 74 65 72 5d  te3_mutex_enter]
27de0 28 5b 73 71 6c 69 74 65 33 5f 64 62 5f 6d 75 74  ([sqlite3_db_mut
27df0 65 78 5d 28 44 29 29 20 62 65 66 6f 72 65 20 62  ex](D)) before b
27e00 65 67 69 6e 6e 69 6e 67 0a 2a 2a 20 74 6f 20 75  eginning.** to u
27e10 73 65 20 44 20 61 6e 64 20 69 6e 76 6f 6b 69 6e  se D and invokin
27e20 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  g [sqlite3_mutex
27e30 5f 6c 65 61 76 65 5d 28 5b 73 71 6c 69 74 65 33  _leave]([sqlite3
27e40 5f 64 62 5f 6d 75 74 65 78 5d 28 44 29 29 20 61  _db_mutex](D)) a
27e50 66 74 65 72 0a 2a 2a 20 61 6c 6c 20 63 61 6c 6c  fter.** all call
27e60 73 20 74 6f 20 74 68 65 20 69 6e 74 65 72 66 61  s to the interfa
27e70 63 65 73 20 6c 69 73 74 65 64 20 68 65 72 65 20  ces listed here 
27e80 61 72 65 20 63 6f 6d 70 6c 65 74 65 64 2e 0a 2a  are completed..*
27e90 2a 0a 2a 2a 20 49 66 20 61 6e 20 69 6e 74 65 72  *.** If an inter
27ea0 66 61 63 65 20 66 61 69 6c 73 20 77 69 74 68 20  face fails with 
27eb0 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 2c 20 74  SQLITE_MISUSE, t
27ec0 68 61 74 20 6d 65 61 6e 73 20 74 68 65 20 69 6e  hat means the in
27ed0 74 65 72 66 61 63 65 0a 2a 2a 20 77 61 73 20 69  terface.** was i
27ee0 6e 76 6f 6b 65 64 20 69 6e 63 6f 72 72 65 63 74  nvoked incorrect
27ef0 6c 79 20 62 79 20 74 68 65 20 61 70 70 6c 69 63  ly by the applic
27f00 61 74 69 6f 6e 2e 20 20 49 6e 20 74 68 61 74 20  ation.  In that 
27f10 63 61 73 65 2c 20 74 68 65 0a 2a 2a 20 65 72 72  case, the.** err
27f20 6f 72 20 63 6f 64 65 20 61 6e 64 20 6d 65 73 73  or code and mess
27f30 61 67 65 20 6d 61 79 20 6f 72 20 6d 61 79 20 6e  age may or may n
27f40 6f 74 20 62 65 20 73 65 74 2e 0a 2a 2f 0a 53 51  ot be set..*/.SQ
27f50 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
27f60 69 74 65 33 5f 65 72 72 63 6f 64 65 28 73 71 6c  ite3_errcode(sql
27f70 69 74 65 33 20 2a 64 62 29 3b 0a 53 51 4c 49 54  ite3 *db);.SQLIT
27f80 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
27f90 33 5f 65 78 74 65 6e 64 65 64 5f 65 72 72 63 6f  3_extended_errco
27fa0 64 65 28 73 71 6c 69 74 65 33 20 2a 64 62 29 3b  de(sqlite3 *db);
27fb0 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73  .SQLITE_API cons
27fc0 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
27fd0 65 72 72 6d 73 67 28 73 71 6c 69 74 65 33 2a 29  errmsg(sqlite3*)
27fe0 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e  ;.SQLITE_API con
27ff0 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
28000 5f 65 72 72 6d 73 67 31 36 28 73 71 6c 69 74 65  _errmsg16(sqlite
28010 33 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  3*);.SQLITE_API 
28020 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69  const char *sqli
28030 74 65 33 5f 65 72 72 73 74 72 28 69 6e 74 29 3b  te3_errstr(int);
28040 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
28050 3a 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65  : Prepared State
28060 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b  ment Object.** K
28070 45 59 57 4f 52 44 53 3a 20 7b 70 72 65 70 61 72  EYWORDS: {prepar
28080 65 64 20 73 74 61 74 65 6d 65 6e 74 7d 20 7b 70  ed statement} {p
28090 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
280a0 74 73 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73  ts}.**.** An ins
280b0 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62  tance of this ob
280c0 6a 65 63 74 20 72 65 70 72 65 73 65 6e 74 73 20  ject represents 
280d0 61 20 73 69 6e 67 6c 65 20 53 51 4c 20 73 74 61  a single SQL sta
280e0 74 65 6d 65 6e 74 20 74 68 61 74 0a 2a 2a 20 68  tement that.** h
280f0 61 73 20 62 65 65 6e 20 63 6f 6d 70 69 6c 65 64  as been compiled
28100 20 69 6e 74 6f 20 62 69 6e 61 72 79 20 66 6f 72   into binary for
28110 6d 20 61 6e 64 20 69 73 20 72 65 61 64 79 20 74  m and is ready t
28120 6f 20 62 65 20 65 76 61 6c 75 61 74 65 64 2e 0a  o be evaluated..
28130 2a 2a 0a 2a 2a 20 54 68 69 6e 6b 20 6f 66 20 65  **.** Think of e
28140 61 63 68 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ach SQL statemen
28150 74 20 61 73 20 61 20 73 65 70 61 72 61 74 65 20  t as a separate 
28160 63 6f 6d 70 75 74 65 72 20 70 72 6f 67 72 61 6d  computer program
28170 2e 20 20 54 68 65 0a 2a 2a 20 6f 72 69 67 69 6e  .  The.** origin
28180 61 6c 20 53 51 4c 20 74 65 78 74 20 69 73 20 73  al SQL text is s
28190 6f 75 72 63 65 20 63 6f 64 65 2e 20 20 41 20 70  ource code.  A p
281a0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
281b0 74 20 6f 62 6a 65 63 74 20 0a 2a 2a 20 69 73 20  t object .** is 
281c0 74 68 65 20 63 6f 6d 70 69 6c 65 64 20 6f 62 6a  the compiled obj
281d0 65 63 74 20 63 6f 64 65 2e 20 20 41 6c 6c 20 53  ect code.  All S
281e0 51 4c 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65  QL must be conve
281f0 72 74 65 64 20 69 6e 74 6f 20 61 0a 2a 2a 20 70  rted into a.** p
28200 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
28210 74 20 62 65 66 6f 72 65 20 69 74 20 63 61 6e 20  t before it can 
28220 62 65 20 72 75 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68  be run..**.** Th
28230 65 20 6c 69 66 65 2d 63 79 63 6c 65 20 6f 66 20  e life-cycle of 
28240 61 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  a prepared state
28250 6d 65 6e 74 20 6f 62 6a 65 63 74 20 75 73 75 61  ment object usua
28260 6c 6c 79 20 67 6f 65 73 20 6c 69 6b 65 20 74 68  lly goes like th
28270 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a  is:.**.** <ol>.*
28280 2a 20 3c 6c 69 3e 20 43 72 65 61 74 65 20 74 68  * <li> Create th
28290 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  e prepared state
282a0 6d 65 6e 74 20 6f 62 6a 65 63 74 20 75 73 69 6e  ment object usin
282b0 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  g [sqlite3_prepa
282c0 72 65 5f 76 32 28 29 5d 2e 0a 2a 2a 20 3c 6c 69  re_v2()]..** <li
282d0 3e 20 42 69 6e 64 20 76 61 6c 75 65 73 20 74 6f  > Bind values to
282e0 20 5b 70 61 72 61 6d 65 74 65 72 73 5d 20 75 73   [parameters] us
282f0 69 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33 5f  ing the sqlite3_
28300 62 69 6e 64 5f 2a 28 29 0a 2a 2a 20 20 20 20 20  bind_*().**     
28310 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20   interfaces..** 
28320 3c 6c 69 3e 20 52 75 6e 20 74 68 65 20 53 51 4c  <li> Run the SQL
28330 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c   by calling [sql
28340 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 6e 65  ite3_step()] one
28350 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a   or more times..
28360 2a 2a 20 3c 6c 69 3e 20 52 65 73 65 74 20 74 68  ** <li> Reset th
28370 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  e prepared state
28380 6d 65 6e 74 20 75 73 69 6e 67 20 5b 73 71 6c 69  ment using [sqli
28390 74 65 33 5f 72 65 73 65 74 28 29 5d 20 74 68 65  te3_reset()] the
283a0 6e 20 67 6f 20 62 61 63 6b 0a 2a 2a 20 20 20 20  n go back.**    
283b0 20 20 74 6f 20 73 74 65 70 20 32 2e 20 20 44 6f    to step 2.  Do
283c0 20 74 68 69 73 20 7a 65 72 6f 20 6f 72 20 6d 6f   this zero or mo
283d0 72 65 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69  re times..** <li
283e0 3e 20 44 65 73 74 72 6f 79 20 74 68 65 20 6f 62  > Destroy the ob
283f0 6a 65 63 74 20 75 73 69 6e 67 20 5b 73 71 6c 69  ject using [sqli
28400 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 2e  te3_finalize()].
28410 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2f 0a 74 79 70  .** </ol>.*/.typ
28420 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69  edef struct sqli
28430 74 65 33 5f 73 74 6d 74 20 73 71 6c 69 74 65 33  te3_stmt sqlite3
28440 5f 73 74 6d 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  _stmt;../*.** CA
28450 50 49 33 52 45 46 3a 20 52 75 6e 2d 74 69 6d 65  PI3REF: Run-time
28460 20 4c 69 6d 69 74 73 0a 2a 2a 20 4d 45 54 48 4f   Limits.** METHO
28470 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a  D: sqlite3.**.**
28480 20 5e 28 54 68 69 73 20 69 6e 74 65 72 66 61 63   ^(This interfac
28490 65 20 61 6c 6c 6f 77 73 20 74 68 65 20 73 69 7a  e allows the siz
284a0 65 20 6f 66 20 76 61 72 69 6f 75 73 20 63 6f 6e  e of various con
284b0 73 74 72 75 63 74 73 20 74 6f 20 62 65 20 6c 69  structs to be li
284c0 6d 69 74 65 64 0a 2a 2a 20 6f 6e 20 61 20 63 6f  mited.** on a co
284d0 6e 6e 65 63 74 69 6f 6e 20 62 79 20 63 6f 6e 6e  nnection by conn
284e0 65 63 74 69 6f 6e 20 62 61 73 69 73 2e 20 20 54  ection basis.  T
284f0 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
28500 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 5b 64 61  er is the.** [da
28510 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
28520 6e 5d 20 77 68 6f 73 65 20 6c 69 6d 69 74 20 69  n] whose limit i
28530 73 20 74 6f 20 62 65 20 73 65 74 20 6f 72 20 71  s to be set or q
28540 75 65 72 69 65 64 2e 20 20 54 68 65 0a 2a 2a 20  ueried.  The.** 
28550 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
28560 20 69 73 20 6f 6e 65 20 6f 66 20 74 68 65 20 5b   is one of the [
28570 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73  limit categories
28580 5d 20 74 68 61 74 20 64 65 66 69 6e 65 20 61 0a  ] that define a.
28590 2a 2a 20 63 6c 61 73 73 20 6f 66 20 63 6f 6e 73  ** class of cons
285a0 74 72 75 63 74 73 20 74 6f 20 62 65 20 73 69 7a  tructs to be siz
285b0 65 20 6c 69 6d 69 74 65 64 2e 20 20 54 68 65 20  e limited.  The 
285c0 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20  third parameter 
285d0 69 73 20 74 68 65 0a 2a 2a 20 6e 65 77 20 6c 69  is the.** new li
285e0 6d 69 74 20 66 6f 72 20 74 68 61 74 20 63 6f 6e  mit for that con
285f0 73 74 72 75 63 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20  struct.)^.**.** 
28600 5e 49 66 20 74 68 65 20 6e 65 77 20 6c 69 6d 69  ^If the new limi
28610 74 20 69 73 20 61 20 6e 65 67 61 74 69 76 65 20  t is a negative 
28620 6e 75 6d 62 65 72 2c 20 74 68 65 20 6c 69 6d 69  number, the limi
28630 74 20 69 73 20 75 6e 63 68 61 6e 67 65 64 2e 0a  t is unchanged..
28640 2a 2a 20 5e 28 46 6f 72 20 65 61 63 68 20 6c 69  ** ^(For each li
28650 6d 69 74 20 63 61 74 65 67 6f 72 79 20 53 51 4c  mit category SQL
28660 49 54 45 5f 4c 49 4d 49 54 5f 3c 69 3e 4e 41 4d  ITE_LIMIT_<i>NAM
28670 45 3c 2f 69 3e 20 74 68 65 72 65 20 69 73 20 61  E</i> there is a
28680 20 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c 20 68   .** [limits | h
28690 61 72 64 20 75 70 70 65 72 20 62 6f 75 6e 64 5d  ard upper bound]
286a0 0a 2a 2a 20 73 65 74 20 61 74 20 63 6f 6d 70 69  .** set at compi
286b0 6c 65 2d 74 69 6d 65 20 62 79 20 61 20 43 20 70  le-time by a C p
286c0 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72  reprocessor macr
286d0 6f 20 63 61 6c 6c 65 64 0a 2a 2a 20 5b 6c 69 6d  o called.** [lim
286e0 69 74 73 20 7c 20 53 51 4c 49 54 45 5f 4d 41 58  its | SQLITE_MAX
286f0 5f 3c 69 3e 4e 41 4d 45 3c 2f 69 3e 5d 2e 0a 2a  _<i>NAME</i>]..*
28700 2a 20 28 54 68 65 20 22 5f 4c 49 4d 49 54 5f 22  * (The "_LIMIT_"
28710 20 69 6e 20 74 68 65 20 6e 61 6d 65 20 69 73 20   in the name is 
28720 63 68 61 6e 67 65 64 20 74 6f 20 22 5f 4d 41 58  changed to "_MAX
28730 5f 22 2e 29 29 5e 0a 2a 2a 20 5e 41 74 74 65 6d  _".))^.** ^Attem
28740 70 74 73 20 74 6f 20 69 6e 63 72 65 61 73 65 20  pts to increase 
28750 61 20 6c 69 6d 69 74 20 61 62 6f 76 65 20 69 74  a limit above it
28760 73 20 68 61 72 64 20 75 70 70 65 72 20 62 6f 75  s hard upper bou
28770 6e 64 20 61 72 65 0a 2a 2a 20 73 69 6c 65 6e 74  nd are.** silent
28780 6c 79 20 74 72 75 6e 63 61 74 65 64 20 74 6f 20  ly truncated to 
28790 74 68 65 20 68 61 72 64 20 75 70 70 65 72 20 62  the hard upper b
287a0 6f 75 6e 64 2e 0a 2a 2a 0a 2a 2a 20 5e 52 65 67  ound..**.** ^Reg
287b0 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68  ardless of wheth
287c0 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 6c 69  er or not the li
287d0 6d 69 74 20 77 61 73 20 63 68 61 6e 67 65 64 2c  mit was changed,
287e0 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c 69 74 65   the .** [sqlite
287f0 33 5f 6c 69 6d 69 74 28 29 5d 20 69 6e 74 65 72  3_limit()] inter
28800 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65  face returns the
28810 20 70 72 69 6f 72 20 76 61 6c 75 65 20 6f 66 20   prior value of 
28820 74 68 65 20 6c 69 6d 69 74 2e 0a 2a 2a 20 5e 48  the limit..** ^H
28830 65 6e 63 65 2c 20 74 6f 20 66 69 6e 64 20 74 68  ence, to find th
28840 65 20 63 75 72 72 65 6e 74 20 76 61 6c 75 65 20  e current value 
28850 6f 66 20 61 20 6c 69 6d 69 74 20 77 69 74 68 6f  of a limit witho
28860 75 74 20 63 68 61 6e 67 69 6e 67 20 69 74 2c 0a  ut changing it,.
28870 2a 2a 20 73 69 6d 70 6c 79 20 69 6e 76 6f 6b 65  ** simply invoke
28880 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 20   this interface 
28890 77 69 74 68 20 74 68 65 20 74 68 69 72 64 20 70  with the third p
288a0 61 72 61 6d 65 74 65 72 20 73 65 74 20 74 6f 20  arameter set to 
288b0 2d 31 2e 0a 2a 2a 0a 2a 2a 20 52 75 6e 2d 74 69  -1..**.** Run-ti
288c0 6d 65 20 6c 69 6d 69 74 73 20 61 72 65 20 69 6e  me limits are in
288d0 74 65 6e 64 65 64 20 66 6f 72 20 75 73 65 20 69  tended for use i
288e0 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 74  n applications t
288f0 68 61 74 20 6d 61 6e 61 67 65 0a 2a 2a 20 62 6f  hat manage.** bo
28900 74 68 20 74 68 65 69 72 20 6f 77 6e 20 69 6e 74  th their own int
28910 65 72 6e 61 6c 20 64 61 74 61 62 61 73 65 20 61  ernal database a
28920 6e 64 20 61 6c 73 6f 20 64 61 74 61 62 61 73 65  nd also database
28930 73 20 74 68 61 74 20 61 72 65 20 63 6f 6e 74 72  s that are contr
28940 6f 6c 6c 65 64 0a 2a 2a 20 62 79 20 75 6e 74 72  olled.** by untr
28950 75 73 74 65 64 20 65 78 74 65 72 6e 61 6c 20 73  usted external s
28960 6f 75 72 63 65 73 2e 20 20 41 6e 20 65 78 61 6d  ources.  An exam
28970 70 6c 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  ple application 
28980 6d 69 67 68 74 20 62 65 20 61 0a 2a 2a 20 77 65  might be a.** we
28990 62 20 62 72 6f 77 73 65 72 20 74 68 61 74 20 68  b browser that h
289a0 61 73 20 69 74 73 20 6f 77 6e 20 64 61 74 61 62  as its own datab
289b0 61 73 65 73 20 66 6f 72 20 73 74 6f 72 69 6e 67  ases for storing
289c0 20 68 69 73 74 6f 72 79 20 61 6e 64 0a 2a 2a 20   history and.** 
289d0 73 65 70 61 72 61 74 65 20 64 61 74 61 62 61 73  separate databas
289e0 65 73 20 63 6f 6e 74 72 6f 6c 6c 65 64 20 62 79  es controlled by
289f0 20 4a 61 76 61 53 63 72 69 70 74 20 61 70 70 6c   JavaScript appl
28a00 69 63 61 74 69 6f 6e 73 20 64 6f 77 6e 6c 6f 61  ications downloa
28a10 64 65 64 0a 2a 2a 20 6f 66 66 20 74 68 65 20 49  ded.** off the I
28a20 6e 74 65 72 6e 65 74 2e 20 20 54 68 65 20 69 6e  nternet.  The in
28a30 74 65 72 6e 61 6c 20 64 61 74 61 62 61 73 65 73  ternal databases
28a40 20 63 61 6e 20 62 65 20 67 69 76 65 6e 20 74 68   can be given th
28a50 65 0a 2a 2a 20 6c 61 72 67 65 2c 20 64 65 66 61  e.** large, defa
28a60 75 6c 74 20 6c 69 6d 69 74 73 2e 20 20 44 61 74  ult limits.  Dat
28a70 61 62 61 73 65 73 20 6d 61 6e 61 67 65 64 20 62  abases managed b
28a80 79 20 65 78 74 65 72 6e 61 6c 20 73 6f 75 72 63  y external sourc
28a90 65 73 20 63 61 6e 0a 2a 2a 20 62 65 20 67 69 76  es can.** be giv
28aa0 65 6e 20 6d 75 63 68 20 73 6d 61 6c 6c 65 72 20  en much smaller 
28ab0 6c 69 6d 69 74 73 20 64 65 73 69 67 6e 65 64 20  limits designed 
28ac0 74 6f 20 70 72 65 76 65 6e 74 20 61 20 64 65 6e  to prevent a den
28ad0 69 61 6c 20 6f 66 20 73 65 72 76 69 63 65 0a 2a  ial of service.*
28ae0 2a 20 61 74 74 61 63 6b 2e 20 20 44 65 76 65 6c  * attack.  Devel
28af0 6f 70 65 72 73 20 6d 69 67 68 74 20 61 6c 73 6f  opers might also
28b00 20 77 61 6e 74 20 74 6f 20 75 73 65 20 74 68 65   want to use the
28b10 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75   [sqlite3_set_au
28b20 74 68 6f 72 69 7a 65 72 28 29 5d 0a 2a 2a 20 69  thorizer()].** i
28b30 6e 74 65 72 66 61 63 65 20 74 6f 20 66 75 72 74  nterface to furt
28b40 68 65 72 20 63 6f 6e 74 72 6f 6c 20 75 6e 74 72  her control untr
28b50 75 73 74 65 64 20 53 51 4c 2e 20 20 54 68 65 20  usted SQL.  The 
28b60 73 69 7a 65 20 6f 66 20 74 68 65 20 64 61 74 61  size of the data
28b70 62 61 73 65 0a 2a 2a 20 63 72 65 61 74 65 64 20  base.** created 
28b80 62 79 20 61 6e 20 75 6e 74 72 75 73 74 65 64 20  by an untrusted 
28b90 73 63 72 69 70 74 20 63 61 6e 20 62 65 20 63 6f  script can be co
28ba0 6e 74 61 69 6e 65 64 20 75 73 69 6e 67 20 74 68  ntained using th
28bb0 65 0a 2a 2a 20 5b 6d 61 78 5f 70 61 67 65 5f 63  e.** [max_page_c
28bc0 6f 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d 2e 0a  ount] [PRAGMA]..
28bd0 2a 2a 0a 2a 2a 20 4e 65 77 20 72 75 6e 2d 74 69  **.** New run-ti
28be0 6d 65 20 6c 69 6d 69 74 20 63 61 74 65 67 6f 72  me limit categor
28bf0 69 65 73 20 6d 61 79 20 62 65 20 61 64 64 65 64  ies may be added
28c00 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61   in future relea
28c10 73 65 73 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  ses..*/.SQLITE_A
28c20 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 6c  PI int sqlite3_l
28c30 69 6d 69 74 28 73 71 6c 69 74 65 33 2a 2c 20 69  imit(sqlite3*, i
28c40 6e 74 20 69 64 2c 20 69 6e 74 20 6e 65 77 56 61  nt id, int newVa
28c50 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  l);../*.** CAPI3
28c60 52 45 46 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69  REF: Run-Time Li
28c70 6d 69 74 20 43 61 74 65 67 6f 72 69 65 73 0a 2a  mit Categories.*
28c80 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 6c 69 6d  * KEYWORDS: {lim
28c90 69 74 20 63 61 74 65 67 6f 72 79 7d 20 7b 2a 6c  it category} {*l
28ca0 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73 7d  imit categories}
28cb0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e  .**.** These con
28cc0 73 74 61 6e 74 73 20 64 65 66 69 6e 65 20 76 61  stants define va
28cd0 72 69 6f 75 73 20 70 65 72 66 6f 72 6d 61 6e 63  rious performanc
28ce0 65 20 6c 69 6d 69 74 73 0a 2a 2a 20 74 68 61 74  e limits.** that
28cf0 20 63 61 6e 20 62 65 20 6c 6f 77 65 72 65 64 20   can be lowered 
28d00 61 74 20 72 75 6e 2d 74 69 6d 65 20 75 73 69 6e  at run-time usin
28d10 67 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74  g [sqlite3_limit
28d20 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73 79 6e 6f  ()]..** The syno
28d30 70 73 69 73 20 6f 66 20 74 68 65 20 6d 65 61 6e  psis of the mean
28d40 69 6e 67 73 20 6f 66 20 74 68 65 20 76 61 72 69  ings of the vari
28d50 6f 75 73 20 6c 69 6d 69 74 73 20 69 73 20 73 68  ous limits is sh
28d60 6f 77 6e 20 62 65 6c 6f 77 2e 0a 2a 2a 20 41 64  own below..** Ad
28d70 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61  ditional informa
28d80 74 69 6f 6e 20 69 73 20 61 76 61 69 6c 61 62 6c  tion is availabl
28d90 65 20 61 74 20 5b 6c 69 6d 69 74 73 20 7c 20 4c  e at [limits | L
28da0 69 6d 69 74 73 20 69 6e 20 53 51 4c 69 74 65 5d  imits in SQLite]
28db0 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20  ..**.** <dl>.** 
28dc0 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c  [[SQLITE_LIMIT_L
28dd0 45 4e 47 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51  ENGTH]] ^(<dt>SQ
28de0 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54  LITE_LIMIT_LENGT
28df0 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  H</dt>.** <dd>Th
28e00 65 20 6d 61 78 69 6d 75 6d 20 73 69 7a 65 20 6f  e maximum size o
28e10 66 20 61 6e 79 20 73 74 72 69 6e 67 20 6f 72 20  f any string or 
28e20 42 4c 4f 42 20 6f 72 20 74 61 62 6c 65 20 72 6f  BLOB or table ro
28e30 77 2c 20 69 6e 20 62 79 74 65 73 2e 3c 64 64 3e  w, in bytes.<dd>
28e40 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  )^.**.** [[SQLIT
28e50 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47  E_LIMIT_SQL_LENG
28e60 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54  TH]] ^(<dt>SQLIT
28e70 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47  E_LIMIT_SQL_LENG
28e80 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  TH</dt>.** <dd>T
28e90 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74  he maximum lengt
28ea0 68 20 6f 66 20 61 6e 20 53 51 4c 20 73 74 61 74  h of an SQL stat
28eb0 65 6d 65 6e 74 2c 20 69 6e 20 62 79 74 65 73 2e  ement, in bytes.
28ec0 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b  </dd>)^.**.** [[
28ed0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c  SQLITE_LIMIT_COL
28ee0 55 4d 4e 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49  UMN]] ^(<dt>SQLI
28ef0 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 3c  TE_LIMIT_COLUMN<
28f00 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
28f10 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f  maximum number o
28f20 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 74  f columns in a t
28f30 61 62 6c 65 20 64 65 66 69 6e 69 74 69 6f 6e 20  able definition 
28f40 6f 72 20 69 6e 20 74 68 65 0a 2a 2a 20 72 65 73  or in the.** res
28f50 75 6c 74 20 73 65 74 20 6f 66 20 61 20 5b 53 45  ult set of a [SE
28f60 4c 45 43 54 5d 20 6f 72 20 74 68 65 20 6d 61 78  LECT] or the max
28f70 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 63  imum number of c
28f80 6f 6c 75 6d 6e 73 20 69 6e 20 61 6e 20 69 6e 64  olumns in an ind
28f90 65 78 0a 2a 2a 20 6f 72 20 69 6e 20 61 6e 20 4f  ex.** or in an O
28fa0 52 44 45 52 20 42 59 20 6f 72 20 47 52 4f 55 50  RDER BY or GROUP
28fb0 20 42 59 20 63 6c 61 75 73 65 2e 3c 2f 64 64 3e   BY clause.</dd>
28fc0 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  )^.**.** [[SQLIT
28fd0 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45 50  E_LIMIT_EXPR_DEP
28fe0 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54  TH]] ^(<dt>SQLIT
28ff0 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45 50  E_LIMIT_EXPR_DEP
29000 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  TH</dt>.** <dd>T
29010 68 65 20 6d 61 78 69 6d 75 6d 20 64 65 70 74 68  he maximum depth
29020 20 6f 66 20 74 68 65 20 70 61 72 73 65 20 74 72   of the parse tr
29030 65 65 20 6f 6e 20 61 6e 79 20 65 78 70 72 65 73  ee on any expres
29040 73 69 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a  sion.</dd>)^.**.
29050 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49  ** [[SQLITE_LIMI
29060 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43  T_COMPOUND_SELEC
29070 54 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45  T]] ^(<dt>SQLITE
29080 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f  _LIMIT_COMPOUND_
29090 53 45 4c 45 43 54 3c 2f 64 74 3e 0a 2a 2a 20 3c  SELECT</dt>.** <
290a0 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e  dd>The maximum n
290b0 75 6d 62 65 72 20 6f 66 20 74 65 72 6d 73 20 69  umber of terms i
290c0 6e 20 61 20 63 6f 6d 70 6f 75 6e 64 20 53 45 4c  n a compound SEL
290d0 45 43 54 20 73 74 61 74 65 6d 65 6e 74 2e 3c 2f  ECT statement.</
290e0 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  dd>)^.**.** [[SQ
290f0 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f  LITE_LIMIT_VDBE_
29100 4f 50 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54  OP]] ^(<dt>SQLIT
29110 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50 3c  E_LIMIT_VDBE_OP<
29120 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
29130 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f  maximum number o
29140 66 20 69 6e 73 74 72 75 63 74 69 6f 6e 73 20 69  f instructions i
29150 6e 20 61 20 76 69 72 74 75 61 6c 20 6d 61 63 68  n a virtual mach
29160 69 6e 65 20 70 72 6f 67 72 61 6d 0a 2a 2a 20 75  ine program.** u
29170 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74  sed to implement
29180 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   an SQL statemen
29190 74 2e 20 20 54 68 69 73 20 6c 69 6d 69 74 20 69  t.  This limit i
291a0 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79 0a  s not currently.
291b0 2a 2a 20 65 6e 66 6f 72 63 65 64 2c 20 74 68 6f  ** enforced, tho
291c0 75 67 68 20 74 68 61 74 20 6d 69 67 68 74 20 62  ugh that might b
291d0 65 20 61 64 64 65 64 20 69 6e 20 73 6f 6d 65 20  e added in some 
291e0 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 20 6f  future release o
291f0 66 0a 2a 2a 20 53 51 4c 69 74 65 2e 3c 2f 64 64  f.** SQLite.</dd
29200 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  >)^.**.** [[SQLI
29210 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f  TE_LIMIT_FUNCTIO
29220 4e 5f 41 52 47 5d 5d 20 5e 28 3c 64 74 3e 53 51  N_ARG]] ^(<dt>SQ
29230 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54  LITE_LIMIT_FUNCT
29240 49 4f 4e 5f 41 52 47 3c 2f 64 74 3e 0a 2a 2a 20  ION_ARG</dt>.** 
29250 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
29260 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65  number of argume
29270 6e 74 73 20 6f 6e 20 61 20 66 75 6e 63 74 69 6f  nts on a functio
29280 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20  n.</dd>)^.**.** 
29290 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41  [[SQLITE_LIMIT_A
292a0 54 54 41 43 48 45 44 5d 5d 20 5e 28 3c 64 74 3e  TTACHED]] ^(<dt>
292b0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54  SQLITE_LIMIT_ATT
292c0 41 43 48 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ACHED</dt>.** <d
292d0 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75  d>The maximum nu
292e0 6d 62 65 72 20 6f 66 20 5b 41 54 54 41 43 48 20  mber of [ATTACH 
292f0 7c 20 61 74 74 61 63 68 65 64 20 64 61 74 61 62  | attached datab
29300 61 73 65 73 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a  ases].)^</dd>.**
29310 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d  .** [[SQLITE_LIM
29320 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f  IT_LIKE_PATTERN_
29330 4c 45 4e 47 54 48 5d 5d 0a 2a 2a 20 5e 28 3c 64  LENGTH]].** ^(<d
29340 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c  t>SQLITE_LIMIT_L
29350 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47  IKE_PATTERN_LENG
29360 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  TH</dt>.** <dd>T
29370 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74  he maximum lengt
29380 68 20 6f 66 20 74 68 65 20 70 61 74 74 65 72 6e  h of the pattern
29390 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
293a0 20 5b 4c 49 4b 45 5d 20 6f 72 0a 2a 2a 20 5b 47   [LIKE] or.** [G
293b0 4c 4f 42 5d 20 6f 70 65 72 61 74 6f 72 73 2e 3c  LOB] operators.<
293c0 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  /dd>)^.**.** [[S
293d0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49  QLITE_LIMIT_VARI
293e0 41 42 4c 45 5f 4e 55 4d 42 45 52 5d 5d 0a 2a 2a  ABLE_NUMBER]].**
293f0 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49   ^(<dt>SQLITE_LI
29400 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d  MIT_VARIABLE_NUM
29410 42 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  BER</dt>.** <dd>
29420 54 68 65 20 6d 61 78 69 6d 75 6d 20 69 6e 64 65  The maximum inde
29430 78 20 6e 75 6d 62 65 72 20 6f 66 20 61 6e 79 20  x number of any 
29440 5b 70 61 72 61 6d 65 74 65 72 5d 20 69 6e 20 61  [parameter] in a
29450 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e  n SQL statement.
29460 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  )^.**.** [[SQLIT
29470 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45 52 5f  E_LIMIT_TRIGGER_
29480 44 45 50 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51  DEPTH]] ^(<dt>SQ
29490 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47  LITE_LIMIT_TRIGG
294a0 45 52 5f 44 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a  ER_DEPTH</dt>.**
294b0 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
294c0 20 64 65 70 74 68 20 6f 66 20 72 65 63 75 72 73   depth of recurs
294d0 69 6f 6e 20 66 6f 72 20 74 72 69 67 67 65 72 73  ion for triggers
294e0 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b  .</dd>)^.**.** [
294f0 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 57 4f  [SQLITE_LIMIT_WO
29500 52 4b 45 52 5f 54 48 52 45 41 44 53 5d 5d 20 5e  RKER_THREADS]] ^
29510 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49  (<dt>SQLITE_LIMI
29520 54 5f 57 4f 52 4b 45 52 5f 54 48 52 45 41 44 53  T_WORKER_THREADS
29530 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
29540 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20   maximum number 
29550 6f 66 20 61 75 78 69 6c 69 61 72 79 20 77 6f 72  of auxiliary wor
29560 6b 65 72 20 74 68 72 65 61 64 73 20 74 68 61 74  ker threads that
29570 20 61 20 73 69 6e 67 6c 65 0a 2a 2a 20 5b 70 72   a single.** [pr
29580 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
29590 5d 20 6d 61 79 20 73 74 61 72 74 2e 3c 2f 64 64  ] may start.</dd
295a0 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a  >)^.** </dl>.*/.
295b0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
295c0 49 4d 49 54 5f 4c 45 4e 47 54 48 20 20 20 20 20  IMIT_LENGTH     
295d0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30                 0
295e0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
295f0 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48  LIMIT_SQL_LENGTH
29600 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
29610 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  1.#define SQLITE
29620 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 20 20 20  _LIMIT_COLUMN   
29630 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
29640 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   2.#define SQLIT
29650 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45 50  E_LIMIT_EXPR_DEP
29660 54 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20  TH              
29670 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    3.#define SQLI
29680 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e  TE_LIMIT_COMPOUN
29690 44 5f 53 45 4c 45 43 54 20 20 20 20 20 20 20 20  D_SELECT        
296a0 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c     4.#define SQL
296b0 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f  ITE_LIMIT_VDBE_O
296c0 50 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  P               
296d0 20 20 20 20 35 0a 23 64 65 66 69 6e 65 20 53 51      5.#define SQ
296e0 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54  LITE_LIMIT_FUNCT
296f0 49 4f 4e 5f 41 52 47 20 20 20 20 20 20 20 20 20  ION_ARG         
29700 20 20 20 20 20 36 0a 23 64 65 66 69 6e 65 20 53       6.#define S
29710 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41  QLITE_LIMIT_ATTA
29720 43 48 45 44 20 20 20 20 20 20 20 20 20 20 20 20  CHED            
29730 20 20 20 20 20 20 37 0a 23 64 65 66 69 6e 65 20        7.#define 
29740 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b  SQLITE_LIMIT_LIK
29750 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48  E_PATTERN_LENGTH
29760 20 20 20 20 20 20 20 38 0a 23 64 65 66 69 6e 65         8.#define
29770 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41   SQLITE_LIMIT_VA
29780 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 20 20 20  RIABLE_NUMBER   
29790 20 20 20 20 20 20 20 20 39 0a 23 64 65 66 69 6e          9.#defin
297a0 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54  e SQLITE_LIMIT_T
297b0 52 49 47 47 45 52 5f 44 45 50 54 48 20 20 20 20  RIGGER_DEPTH    
297c0 20 20 20 20 20 20 20 20 31 30 0a 23 64 65 66 69          10.#defi
297d0 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
297e0 57 4f 52 4b 45 52 5f 54 48 52 45 41 44 53 20 20  WORKER_THREADS  
297f0 20 20 20 20 20 20 20 20 20 31 31 0a 0a 2f 2a 0a           11../*.
29800 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6d  ** CAPI3REF: Com
29810 70 69 6c 69 6e 67 20 41 6e 20 53 51 4c 20 53 74  piling An SQL St
29820 61 74 65 6d 65 6e 74 0a 2a 2a 20 4b 45 59 57 4f  atement.** KEYWO
29830 52 44 53 3a 20 7b 53 51 4c 20 73 74 61 74 65 6d  RDS: {SQL statem
29840 65 6e 74 20 63 6f 6d 70 69 6c 65 72 7d 0a 2a 2a  ent compiler}.**
29850 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
29860 0a 2a 2a 20 43 4f 4e 53 54 52 55 43 54 4f 52 3a  .** CONSTRUCTOR:
29870 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a   sqlite3_stmt.**
29880 0a 2a 2a 20 54 6f 20 65 78 65 63 75 74 65 20 61  .** To execute a
29890 6e 20 53 51 4c 20 71 75 65 72 79 2c 20 69 74 20  n SQL query, it 
298a0 6d 75 73 74 20 66 69 72 73 74 20 62 65 20 63 6f  must first be co
298b0 6d 70 69 6c 65 64 20 69 6e 74 6f 20 61 20 62 79  mpiled into a by
298c0 74 65 2d 63 6f 64 65 0a 2a 2a 20 70 72 6f 67 72  te-code.** progr
298d0 61 6d 20 75 73 69 6e 67 20 6f 6e 65 20 6f 66 20  am using one of 
298e0 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a  these routines..
298f0 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20  **.** The first 
29900 61 72 67 75 6d 65 6e 74 2c 20 22 64 62 22 2c 20  argument, "db", 
29910 69 73 20 61 20 5b 64 61 74 61 62 61 73 65 20 63  is a [database c
29920 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 62 74 61 69  onnection] obtai
29930 6e 65 64 20 66 72 6f 6d 20 61 0a 2a 2a 20 70 72  ned from a.** pr
29940 69 6f 72 20 73 75 63 63 65 73 73 66 75 6c 20 63  ior successful c
29950 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
29960 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65  open()], [sqlite
29970 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 6f 72 0a  3_open_v2()] or.
29980 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ** [sqlite3_open
29990 31 36 28 29 5d 2e 20 20 54 68 65 20 64 61 74 61  16()].  The data
299a0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
299b0 6d 75 73 74 20 6e 6f 74 20 68 61 76 65 20 62 65  must not have be
299c0 65 6e 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a  en closed..**.**
299d0 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   The second argu
299e0 6d 65 6e 74 2c 20 22 7a 53 71 6c 22 2c 20 69 73  ment, "zSql", is
299f0 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 74   the statement t
29a00 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64 2c 20 65  o be compiled, e
29a10 6e 63 6f 64 65 64 0a 2a 2a 20 61 73 20 65 69 74  ncoded.** as eit
29a20 68 65 72 20 55 54 46 2d 38 20 6f 72 20 55 54 46  her UTF-8 or UTF
29a30 2d 31 36 2e 20 20 54 68 65 20 73 71 6c 69 74 65  -16.  The sqlite
29a40 33 5f 70 72 65 70 61 72 65 28 29 20 61 6e 64 20  3_prepare() and 
29a50 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
29a60 76 32 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63  v2().** interfac
29a70 65 73 20 75 73 65 20 55 54 46 2d 38 2c 20 61 6e  es use UTF-8, an
29a80 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  d sqlite3_prepar
29a90 65 31 36 28 29 20 61 6e 64 20 73 71 6c 69 74 65  e16() and sqlite
29aa0 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29  3_prepare16_v2()
29ab0 0a 2a 2a 20 75 73 65 20 55 54 46 2d 31 36 2e 0a  .** use UTF-16..
29ac0 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6e 42  **.** ^If the nB
29ad0 79 74 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20  yte argument is 
29ae0 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 7a  negative, then z
29af0 53 71 6c 20 69 73 20 72 65 61 64 20 75 70 20 74  Sql is read up t
29b00 6f 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 7a  o the.** first z
29b10 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20  ero terminator. 
29b20 5e 49 66 20 6e 42 79 74 65 20 69 73 20 70 6f 73  ^If nByte is pos
29b30 69 74 69 76 65 2c 20 74 68 65 6e 20 69 74 20 69  itive, then it i
29b40 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20  s the.** number 
29b50 6f 66 20 62 79 74 65 73 20 72 65 61 64 20 66 72  of bytes read fr
29b60 6f 6d 20 7a 53 71 6c 2e 20 20 5e 49 66 20 6e 42  om zSql.  ^If nB
29b70 79 74 65 20 69 73 20 7a 65 72 6f 2c 20 74 68 65  yte is zero, the
29b80 6e 20 6e 6f 20 70 72 65 70 61 72 65 64 0a 2a 2a  n no prepared.**
29b90 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 67 65   statement is ge
29ba0 6e 65 72 61 74 65 64 2e 0a 2a 2a 20 49 66 20 74  nerated..** If t
29bb0 68 65 20 63 61 6c 6c 65 72 20 6b 6e 6f 77 73 20  he caller knows 
29bc0 74 68 61 74 20 74 68 65 20 73 75 70 70 6c 69 65  that the supplie
29bd0 64 20 73 74 72 69 6e 67 20 69 73 20 6e 75 6c 2d  d string is nul-
29be0 74 65 72 6d 69 6e 61 74 65 64 2c 20 74 68 65 6e  terminated, then
29bf0 0a 2a 2a 20 74 68 65 72 65 20 69 73 20 61 20 73  .** there is a s
29c00 6d 61 6c 6c 20 70 65 72 66 6f 72 6d 61 6e 63 65  mall performance
29c10 20 61 64 76 61 6e 74 61 67 65 20 74 6f 20 70 61   advantage to pa
29c20 73 73 69 6e 67 20 61 6e 20 6e 42 79 74 65 20 70  ssing an nByte p
29c30 61 72 61 6d 65 74 65 72 20 74 68 61 74 0a 2a 2a  arameter that.**
29c40 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   is the number o
29c50 66 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 69  f bytes in the i
29c60 6e 70 75 74 20 73 74 72 69 6e 67 20 3c 69 3e 69  nput string <i>i
29c70 6e 63 6c 75 64 69 6e 67 3c 2f 69 3e 0a 2a 2a 20  ncluding</i>.** 
29c80 74 68 65 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74  the nul-terminat
29c90 6f 72 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 70 7a  or..**.** ^If pz
29ca0 54 61 69 6c 20 69 73 20 6e 6f 74 20 4e 55 4c 4c  Tail is not NULL
29cb0 20 74 68 65 6e 20 2a 70 7a 54 61 69 6c 20 69 73   then *pzTail is
29cc0 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74 20 74   made to point t
29cd0 6f 20 74 68 65 20 66 69 72 73 74 20 62 79 74 65  o the first byte
29ce0 0a 2a 2a 20 70 61 73 74 20 74 68 65 20 65 6e 64  .** past the end
29cf0 20 6f 66 20 74 68 65 20 66 69 72 73 74 20 53 51   of the first SQ
29d00 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 7a  L statement in z
29d10 53 71 6c 2e 20 20 54 68 65 73 65 20 72 6f 75 74  Sql.  These rout
29d20 69 6e 65 73 20 6f 6e 6c 79 0a 2a 2a 20 63 6f 6d  ines only.** com
29d30 70 69 6c 65 20 74 68 65 20 66 69 72 73 74 20 73  pile the first s
29d40 74 61 74 65 6d 65 6e 74 20 69 6e 20 7a 53 71 6c  tatement in zSql
29d50 2c 20 73 6f 20 2a 70 7a 54 61 69 6c 20 69 73 20  , so *pzTail is 
29d60 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67 20 74 6f  left pointing to
29d70 0a 2a 2a 20 77 68 61 74 20 72 65 6d 61 69 6e 73  .** what remains
29d80 20 75 6e 63 6f 6d 70 69 6c 65 64 2e 0a 2a 2a 0a   uncompiled..**.
29d90 2a 2a 20 5e 2a 70 70 53 74 6d 74 20 69 73 20 6c  ** ^*ppStmt is l
29da0 65 66 74 20 70 6f 69 6e 74 69 6e 67 20 74 6f 20  eft pointing to 
29db0 61 20 63 6f 6d 70 69 6c 65 64 20 5b 70 72 65 70  a compiled [prep
29dc0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
29dd0 74 68 61 74 20 63 61 6e 20 62 65 0a 2a 2a 20 65  that can be.** e
29de0 78 65 63 75 74 65 64 20 75 73 69 6e 67 20 5b 73  xecuted using [s
29df0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 20  qlite3_step()]. 
29e00 20 5e 49 66 20 74 68 65 72 65 20 69 73 20 61 6e   ^If there is an
29e10 20 65 72 72 6f 72 2c 20 2a 70 70 53 74 6d 74 20   error, *ppStmt 
29e20 69 73 20 73 65 74 0a 2a 2a 20 74 6f 20 4e 55 4c  is set.** to NUL
29e30 4c 2e 20 20 5e 49 66 20 74 68 65 20 69 6e 70 75  L.  ^If the inpu
29e40 74 20 74 65 78 74 20 63 6f 6e 74 61 69 6e 73 20  t text contains 
29e50 6e 6f 20 53 51 4c 20 28 69 66 20 74 68 65 20 69  no SQL (if the i
29e60 6e 70 75 74 20 69 73 20 61 6e 20 65 6d 70 74 79  nput is an empty
29e70 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 72 20 61 20  .** string or a 
29e80 63 6f 6d 6d 65 6e 74 29 20 74 68 65 6e 20 2a 70  comment) then *p
29e90 70 53 74 6d 74 20 69 73 20 73 65 74 20 74 6f 20  pStmt is set to 
29ea0 4e 55 4c 4c 2e 0a 2a 2a 20 54 68 65 20 63 61 6c  NULL..** The cal
29eb0 6c 69 6e 67 20 70 72 6f 63 65 64 75 72 65 20 69  ling procedure i
29ec0 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f  s responsible fo
29ed0 72 20 64 65 6c 65 74 69 6e 67 20 74 68 65 20 63  r deleting the c
29ee0 6f 6d 70 69 6c 65 64 0a 2a 2a 20 53 51 4c 20 73  ompiled.** SQL s
29ef0 74 61 74 65 6d 65 6e 74 20 75 73 69 6e 67 20 5b  tatement using [
29f00 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
29f10 28 29 5d 20 61 66 74 65 72 20 69 74 20 68 61 73  ()] after it has
29f20 20 66 69 6e 69 73 68 65 64 20 77 69 74 68 20 69   finished with i
29f30 74 2e 0a 2a 2a 20 70 70 53 74 6d 74 20 6d 61 79  t..** ppStmt may
29f40 20 6e 6f 74 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a   not be NULL..**
29f50 0a 2a 2a 20 5e 4f 6e 20 73 75 63 63 65 73 73 2c  .** ^On success,
29f60 20 74 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65   the sqlite3_pre
29f70 70 61 72 65 28 29 20 66 61 6d 69 6c 79 20 6f 66  pare() family of
29f80 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
29f90 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 3b 0a 2a 2a   [SQLITE_OK];.**
29fa0 20 6f 74 68 65 72 77 69 73 65 20 61 6e 20 5b 65   otherwise an [e
29fb0 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65  rror code] is re
29fc0 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  turned..**.** Th
29fd0 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  e sqlite3_prepar
29fe0 65 5f 76 32 28 29 20 61 6e 64 20 73 71 6c 69 74  e_v2() and sqlit
29ff0 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
2a000 29 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65  ) interfaces are
2a010 0a 2a 2a 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20  .** recommended 
2a020 66 6f 72 20 61 6c 6c 20 6e 65 77 20 70 72 6f 67  for all new prog
2a030 72 61 6d 73 2e 20 54 68 65 20 74 77 6f 20 6f 6c  rams. The two ol
2a040 64 65 72 20 69 6e 74 65 72 66 61 63 65 73 20 61  der interfaces a
2a050 72 65 20 72 65 74 61 69 6e 65 64 0a 2a 2a 20 66  re retained.** f
2a060 6f 72 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d  or backwards com
2a070 70 61 74 69 62 69 6c 69 74 79 2c 20 62 75 74 20  patibility, but 
2a080 74 68 65 69 72 20 75 73 65 20 69 73 20 64 69 73  their use is dis
2a090 63 6f 75 72 61 67 65 64 2e 0a 2a 2a 20 5e 49 6e  couraged..** ^In
2a0a0 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66   the "v2" interf
2a0b0 61 63 65 73 2c 20 74 68 65 20 70 72 65 70 61 72  aces, the prepar
2a0c0 65 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20  ed statement.** 
2a0d0 74 68 61 74 20 69 73 20 72 65 74 75 72 6e 65 64  that is returned
2a0e0 20 28 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73   (the [sqlite3_s
2a0f0 74 6d 74 5d 20 6f 62 6a 65 63 74 29 20 63 6f 6e  tmt] object) con
2a100 74 61 69 6e 73 20 61 20 63 6f 70 79 20 6f 66 20  tains a copy of 
2a110 74 68 65 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 20  the.** original 
2a120 53 51 4c 20 74 65 78 74 2e 20 54 68 69 73 20 63  SQL text. This c
2a130 61 75 73 65 73 20 74 68 65 20 5b 73 71 6c 69 74  auses the [sqlit
2a140 65 33 5f 73 74 65 70 28 29 5d 20 69 6e 74 65 72  e3_step()] inter
2a150 66 61 63 65 20 74 6f 0a 2a 2a 20 62 65 68 61 76  face to.** behav
2a160 65 20 64 69 66 66 65 72 65 6e 74 6c 79 20 69 6e  e differently in
2a170 20 74 68 72 65 65 20 77 61 79 73 3a 0a 2a 2a 0a   three ways:.**.
2a180 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 0a  ** <ol>.** <li>.
2a190 2a 2a 20 5e 49 66 20 74 68 65 20 64 61 74 61 62  ** ^If the datab
2a1a0 61 73 65 20 73 63 68 65 6d 61 20 63 68 61 6e 67  ase schema chang
2a1b0 65 73 2c 20 69 6e 73 74 65 61 64 20 6f 66 20 72  es, instead of r
2a1c0 65 74 75 72 6e 69 6e 67 20 5b 53 51 4c 49 54 45  eturning [SQLITE
2a1d0 5f 53 43 48 45 4d 41 5d 20 61 73 20 69 74 0a 2a  _SCHEMA] as it.*
2a1e0 2a 20 61 6c 77 61 79 73 20 75 73 65 64 20 74 6f  * always used to
2a1f0 20 64 6f 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74   do, [sqlite3_st
2a200 65 70 28 29 5d 20 77 69 6c 6c 20 61 75 74 6f 6d  ep()] will autom
2a210 61 74 69 63 61 6c 6c 79 20 72 65 63 6f 6d 70 69  atically recompi
2a220 6c 65 20 74 68 65 20 53 51 4c 0a 2a 2a 20 73 74  le the SQL.** st
2a230 61 74 65 6d 65 6e 74 20 61 6e 64 20 74 72 79 20  atement and try 
2a240 74 6f 20 72 75 6e 20 69 74 20 61 67 61 69 6e 2e  to run it again.
2a250 20 41 73 20 6d 61 6e 79 20 61 73 20 5b 53 51 4c   As many as [SQL
2a260 49 54 45 5f 4d 41 58 5f 53 43 48 45 4d 41 5f 52  ITE_MAX_SCHEMA_R
2a270 45 54 52 59 5d 0a 2a 2a 20 72 65 74 72 69 65 73  ETRY].** retries
2a280 20 77 69 6c 6c 20 6f 63 63 75 72 20 62 65 66 6f   will occur befo
2a290 72 65 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  re sqlite3_step(
2a2a0 29 20 67 69 76 65 73 20 75 70 20 61 6e 64 20 72  ) gives up and r
2a2b0 65 74 75 72 6e 73 20 61 6e 20 65 72 72 6f 72 2e  eturns an error.
2a2c0 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20  .** </li>.**.** 
2a2d0 3c 6c 69 3e 0a 2a 2a 20 5e 57 68 65 6e 20 61 6e  <li>.** ^When an
2a2e0 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2c 20 5b   error occurs, [
2a2f0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
2a300 77 69 6c 6c 20 72 65 74 75 72 6e 20 6f 6e 65 20  will return one 
2a310 6f 66 20 74 68 65 20 64 65 74 61 69 6c 65 64 0a  of the detailed.
2a320 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d  ** [error codes]
2a330 20 6f 72 20 5b 65 78 74 65 6e 64 65 64 20 65 72   or [extended er
2a340 72 6f 72 20 63 6f 64 65 73 5d 2e 20 20 5e 54 68  ror codes].  ^Th
2a350 65 20 6c 65 67 61 63 79 20 62 65 68 61 76 69 6f  e legacy behavio
2a360 72 20 77 61 73 20 74 68 61 74 0a 2a 2a 20 5b 73  r was that.** [s
2a370 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77  qlite3_step()] w
2a380 6f 75 6c 64 20 6f 6e 6c 79 20 72 65 74 75 72 6e  ould only return
2a390 20 61 20 67 65 6e 65 72 69 63 20 5b 53 51 4c 49   a generic [SQLI
2a3a0 54 45 5f 45 52 52 4f 52 5d 20 72 65 73 75 6c 74  TE_ERROR] result
2a3b0 20 63 6f 64 65 0a 2a 2a 20 61 6e 64 20 74 68 65   code.** and the
2a3c0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 77 6f 75   application wou
2a3d0 6c 64 20 68 61 76 65 20 74 6f 20 6d 61 6b 65 20  ld have to make 
2a3e0 61 20 73 65 63 6f 6e 64 20 63 61 6c 6c 20 74 6f  a second call to
2a3f0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
2a400 29 5d 0a 2a 2a 20 69 6e 20 6f 72 64 65 72 20 74  )].** in order t
2a410 6f 20 66 69 6e 64 20 74 68 65 20 75 6e 64 65 72  o find the under
2a420 6c 79 69 6e 67 20 63 61 75 73 65 20 6f 66 20 74  lying cause of t
2a430 68 65 20 70 72 6f 62 6c 65 6d 2e 20 57 69 74 68  he problem. With
2a440 20 74 68 65 20 22 76 32 22 20 70 72 65 70 61 72   the "v2" prepar
2a450 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 2c  e.** interfaces,
2a460 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20   the underlying 
2a470 72 65 61 73 6f 6e 20 66 6f 72 20 74 68 65 20 65  reason for the e
2a480 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64  rror is returned
2a490 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e 0a 2a 2a   immediately..**
2a4a0 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69   </li>.**.** <li
2a4b0 3e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 73 70 65  >.** ^If the spe
2a4c0 63 69 66 69 63 20 76 61 6c 75 65 20 62 6f 75 6e  cific value boun
2a4d0 64 20 74 6f 20 5b 70 61 72 61 6d 65 74 65 72 20  d to [parameter 
2a4e0 7c 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72  | host parameter
2a4f0 5d 20 69 6e 20 74 68 65 20 0a 2a 2a 20 57 48 45  ] in the .** WHE
2a500 52 45 20 63 6c 61 75 73 65 20 6d 69 67 68 74 20  RE clause might 
2a510 69 6e 66 6c 75 65 6e 63 65 20 74 68 65 20 63 68  influence the ch
2a520 6f 69 63 65 20 6f 66 20 71 75 65 72 79 20 70 6c  oice of query pl
2a530 61 6e 20 66 6f 72 20 61 20 73 74 61 74 65 6d 65  an for a stateme
2a540 6e 74 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20  nt,.** then the 
2a550 73 74 61 74 65 6d 65 6e 74 20 77 69 6c 6c 20 62  statement will b
2a560 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  e automatically 
2a570 72 65 63 6f 6d 70 69 6c 65 64 2c 20 61 73 20 69  recompiled, as i
2a580 66 20 74 68 65 72 65 20 68 61 64 20 62 65 65 6e  f there had been
2a590 20 0a 2a 2a 20 61 20 73 63 68 65 6d 61 20 63 68   .** a schema ch
2a5a0 61 6e 67 65 2c 20 6f 6e 20 74 68 65 20 66 69 72  ange, on the fir
2a5b0 73 74 20 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  st  [sqlite3_ste
2a5c0 70 28 29 5d 20 63 61 6c 6c 20 66 6f 6c 6c 6f 77  p()] call follow
2a5d0 69 6e 67 20 61 6e 79 20 63 68 61 6e 67 65 0a 2a  ing any change.*
2a5e0 2a 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  * to the [sqlite
2a5f0 33 5f 62 69 6e 64 5f 74 65 78 74 20 7c 20 62 69  3_bind_text | bi
2a600 6e 64 69 6e 67 73 5d 20 6f 66 20 74 68 61 74 20  ndings] of that 
2a610 5b 70 61 72 61 6d 65 74 65 72 5d 2e 20 0a 2a 2a  [parameter]. .**
2a620 20 5e 54 68 65 20 73 70 65 63 69 66 69 63 20 76   ^The specific v
2a630 61 6c 75 65 20 6f 66 20 57 48 45 52 45 2d 63 6c  alue of WHERE-cl
2a640 61 75 73 65 20 5b 70 61 72 61 6d 65 74 65 72 5d  ause [parameter]
2a650 20 6d 69 67 68 74 20 69 6e 66 6c 75 65 6e 63 65   might influence
2a660 20 74 68 65 20 0a 2a 2a 20 63 68 6f 69 63 65 20   the .** choice 
2a670 6f 66 20 71 75 65 72 79 20 70 6c 61 6e 20 69 66  of query plan if
2a680 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 69   the parameter i
2a690 73 20 74 68 65 20 6c 65 66 74 2d 68 61 6e 64 20  s the left-hand 
2a6a0 73 69 64 65 20 6f 66 20 61 20 5b 4c 49 4b 45 5d  side of a [LIKE]
2a6b0 0a 2a 2a 20 6f 72 20 5b 47 4c 4f 42 5d 20 6f 70  .** or [GLOB] op
2a6c0 65 72 61 74 6f 72 20 6f 72 20 69 66 20 74 68 65  erator or if the
2a6d0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 63 6f   parameter is co
2a6e0 6d 70 61 72 65 64 20 74 6f 20 61 6e 20 69 6e 64  mpared to an ind
2a6f0 65 78 65 64 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 61  exed column.** a
2a700 6e 64 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 45  nd the [SQLITE_E
2a710 4e 41 42 4c 45 5f 53 54 41 54 33 5d 20 63 6f 6d  NABLE_STAT3] com
2a720 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
2a730 20 69 73 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 20   is enabled..** 
2a740 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a  </li>.** </ol>.*
2a750 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  /.SQLITE_API int
2a760 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
2a770 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
2a780 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44              /* D
2a790 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a  atabase handle *
2a7a0 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  /.  const char *
2a7b0 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53  zSql,       /* S
2a7c0 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54  QL statement, UT
2a7d0 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20  F-8 encoded */. 
2a7e0 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20   int nByte,     
2a7f0 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69           /* Maxi
2a800 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53  mum length of zS
2a810 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a  ql in bytes. */.
2a820 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a    sqlite3_stmt *
2a830 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54  *ppStmt,  /* OUT
2a840 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64  : Statement hand
2a850 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68  le */.  const ch
2a860 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20  ar **pzTail     
2a870 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20  /* OUT: Pointer 
2a880 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f  to unused portio
2a890 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a  n of zSql */.);.
2a8a0 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
2a8b0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
2a8c0 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  2(.  sqlite3 *db
2a8d0 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20  ,            /* 
2a8e0 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20  Database handle 
2a8f0 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  */.  const char 
2a900 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20  *zSql,       /* 
2a910 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55  SQL statement, U
2a920 54 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a  TF-8 encoded */.
2a930 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20    int nByte,    
2a940 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78            /* Max
2a950 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a  imum length of z
2a960 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f  Sql in bytes. */
2a970 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  .  sqlite3_stmt 
2a980 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55  **ppStmt,  /* OU
2a990 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e  T: Statement han
2a9a0 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  dle */.  const c
2a9b0 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20  har **pzTail    
2a9c0 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72   /* OUT: Pointer
2a9d0 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69   to unused porti
2a9e0 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b  on of zSql */.);
2a9f0 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
2aa00 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
2aa10 36 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  6(.  sqlite3 *db
2aa20 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20  ,            /* 
2aa30 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20  Database handle 
2aa40 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20  */.  const void 
2aa50 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20  *zSql,       /* 
2aa60 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55  SQL statement, U
2aa70 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f  TF-16 encoded */
2aa80 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20  .  int nByte,   
2aa90 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61             /* Ma
2aaa0 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20  ximum length of 
2aab0 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a  zSql in bytes. *
2aac0 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  /.  sqlite3_stmt
2aad0 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f   **ppStmt,  /* O
2aae0 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61  UT: Statement ha
2aaf0 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  ndle */.  const 
2ab00 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20  void **pzTail   
2ab10 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65    /* OUT: Pointe
2ab20 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74  r to unused port
2ab30 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29  ion of zSql */.)
2ab40 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  ;.SQLITE_API int
2ab50 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
2ab60 31 36 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33  16_v2(.  sqlite3
2ab70 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20   *db,           
2ab80 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e   /* Database han
2ab90 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76  dle */.  const v
2aba0 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20  oid *zSql,      
2abb0 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   /* SQL statemen
2abc0 74 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65  t, UTF-16 encode
2abd0 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65  d */.  int nByte
2abe0 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f  ,              /
2abf0 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68  * Maximum length
2ac00 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65   of zSql in byte
2ac10 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f  s. */.  sqlite3_
2ac20 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20  stmt **ppStmt,  
2ac30 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e  /* OUT: Statemen
2ac40 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f  t handle */.  co
2ac50 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69  nst void **pzTai
2ac60 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f  l     /* OUT: Po
2ac70 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20  inter to unused 
2ac80 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20  portion of zSql 
2ac90 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  */.);../*.** CAP
2aca0 49 33 52 45 46 3a 20 52 65 74 72 69 65 76 69 6e  I3REF: Retrievin
2acb0 67 20 53 74 61 74 65 6d 65 6e 74 20 53 51 4c 0a  g Statement SQL.
2acc0 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
2acd0 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54  e3_stmt.**.** ^T
2ace0 68 65 20 73 71 6c 69 74 65 33 5f 73 71 6c 28 50  he sqlite3_sql(P
2acf0 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ) interface retu
2ad00 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
2ad10 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 55   a copy of the U
2ad20 54 46 2d 38 0a 2a 2a 20 53 51 4c 20 74 65 78 74  TF-8.** SQL text
2ad30 20 75 73 65 64 20 74 6f 20 63 72 65 61 74 65 20   used to create 
2ad40 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2ad50 65 6e 74 5d 20 50 20 69 66 20 50 20 77 61 73 0a  ent] P if P was.
2ad60 2a 2a 20 63 72 65 61 74 65 64 20 62 79 20 65 69  ** created by ei
2ad70 74 68 65 72 20 5b 73 71 6c 69 74 65 33 5f 70 72  ther [sqlite3_pr
2ad80 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b  epare_v2()] or [
2ad90 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
2ada0 36 5f 76 32 28 29 5d 2e 0a 2a 2a 20 5e 54 68 65  6_v2()]..** ^The
2adb0 20 73 71 6c 69 74 65 33 5f 65 78 70 61 6e 64 65   sqlite3_expande
2adc0 64 5f 73 71 6c 28 50 29 20 69 6e 74 65 72 66 61  d_sql(P) interfa
2add0 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  ce returns a poi
2ade0 6e 74 65 72 20 74 6f 20 61 20 55 54 46 2d 38 0a  nter to a UTF-8.
2adf0 2a 2a 20 73 74 72 69 6e 67 20 63 6f 6e 74 61 69  ** string contai
2ae00 6e 69 6e 67 20 74 68 65 20 53 51 4c 20 74 65 78  ning the SQL tex
2ae10 74 20 6f 66 20 70 72 65 70 61 72 65 64 20 73 74  t of prepared st
2ae20 61 74 65 6d 65 6e 74 20 50 20 77 69 74 68 0a 2a  atement P with.*
2ae30 2a 20 5b 62 6f 75 6e 64 20 70 61 72 61 6d 65 74  * [bound paramet
2ae40 65 72 73 5d 20 65 78 70 61 6e 64 65 64 2e 0a 2a  ers] expanded..*
2ae50 2a 0a 2a 2a 20 5e 28 46 6f 72 20 65 78 61 6d 70  *.** ^(For examp
2ae60 6c 65 2c 20 69 66 20 61 20 70 72 65 70 61 72 65  le, if a prepare
2ae70 64 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 63  d statement is c
2ae80 72 65 61 74 65 64 20 75 73 69 6e 67 20 74 68 65  reated using the
2ae90 20 53 51 4c 0a 2a 2a 20 74 65 78 74 20 22 53 45   SQL.** text "SE
2aea0 4c 45 43 54 20 24 61 62 63 2c 3a 78 79 7a 22 20  LECT $abc,:xyz" 
2aeb0 61 6e 64 20 69 66 20 70 61 72 61 6d 65 74 65 72  and if parameter
2aec0 20 24 61 62 63 20 69 73 20 62 6f 75 6e 64 20 74   $abc is bound t
2aed0 6f 20 69 6e 74 65 67 65 72 20 32 33 34 35 0a 2a  o integer 2345.*
2aee0 2a 20 61 6e 64 20 70 61 72 61 6d 65 74 65 72 20  * and parameter 
2aef0 3a 78 79 7a 20 69 73 20 75 6e 62 6f 75 6e 64 2c  :xyz is unbound,
2af00 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 73 71   then sqlite3_sq
2af10 6c 28 29 20 77 69 6c 6c 20 72 65 74 75 72 6e 0a  l() will return.
2af20 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20  ** the original 
2af30 73 74 72 69 6e 67 2c 20 22 53 45 4c 45 43 54 20  string, "SELECT 
2af40 24 61 62 63 2c 3a 78 79 7a 22 20 62 75 74 20 73  $abc,:xyz" but s
2af50 71 6c 69 74 65 33 5f 65 78 70 61 6e 64 65 64 5f  qlite3_expanded_
2af60 73 71 6c 28 29 0a 2a 2a 20 77 69 6c 6c 20 72 65  sql().** will re
2af70 74 75 72 6e 20 22 53 45 4c 45 43 54 20 32 33 34  turn "SELECT 234
2af80 35 2c 4e 55 4c 4c 22 2e 29 5e 0a 2a 2a 0a 2a 2a  5,NULL".)^.**.**
2af90 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78   ^The sqlite3_ex
2afa0 70 61 6e 64 65 64 5f 73 71 6c 28 29 20 69 6e 74  panded_sql() int
2afb0 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 4e  erface returns N
2afc0 55 4c 4c 20 69 66 20 69 6e 73 75 66 66 69 63 69  ULL if insuffici
2afd0 65 6e 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20 69 73  ent memory.** is
2afe0 20 61 76 61 69 6c 61 62 6c 65 20 74 6f 20 68 6f   available to ho
2aff0 6c 64 20 74 68 65 20 72 65 73 75 6c 74 2c 20 6f  ld the result, o
2b000 72 20 69 66 20 74 68 65 20 72 65 73 75 6c 74 20  r if the result 
2b010 77 6f 75 6c 64 20 65 78 63 65 65 64 20 74 68 65  would exceed the
2b020 0a 2a 2a 20 74 68 65 20 6d 61 78 69 6d 75 6d 20  .** the maximum 
2b030 73 74 72 69 6e 67 20 6c 65 6e 67 74 68 20 64 65  string length de
2b040 74 65 72 6d 69 6e 65 64 20 62 79 20 74 68 65 20  termined by the 
2b050 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45  [SQLITE_LIMIT_LE
2b060 4e 47 54 48 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  NGTH]..**.** ^Th
2b070 65 20 5b 53 51 4c 49 54 45 5f 54 52 41 43 45 5f  e [SQLITE_TRACE_
2b080 53 49 5a 45 5f 4c 49 4d 49 54 5d 20 63 6f 6d 70  SIZE_LIMIT] comp
2b090 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20  ile-time option 
2b0a0 6c 69 6d 69 74 73 20 74 68 65 20 73 69 7a 65 20  limits the size 
2b0b0 6f 66 0a 2a 2a 20 62 6f 75 6e 64 20 70 61 72 61  of.** bound para
2b0c0 6d 65 74 65 72 20 65 78 70 61 6e 73 69 6f 6e 73  meter expansions
2b0d0 2e 20 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f  .  ^The [SQLITE_
2b0e0 4f 4d 49 54 5f 54 52 41 43 45 5d 20 63 6f 6d 70  OMIT_TRACE] comp
2b0f0 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74 69  ile-time.** opti
2b100 6f 6e 20 63 61 75 73 65 73 20 73 71 6c 69 74 65  on causes sqlite
2b110 33 5f 65 78 70 61 6e 64 65 64 5f 73 71 6c 28 29  3_expanded_sql()
2b120 20 74 6f 20 61 6c 77 61 79 73 20 72 65 74 75 72   to always retur
2b130 6e 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54  n NULL..**.** ^T
2b140 68 65 20 73 74 72 69 6e 67 20 72 65 74 75 72 6e  he string return
2b150 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 73 71  ed by sqlite3_sq
2b160 6c 28 50 29 20 69 73 20 6d 61 6e 61 67 65 64 20  l(P) is managed 
2b170 62 79 20 53 51 4c 69 74 65 20 61 6e 64 20 69 73  by SQLite and is
2b180 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  .** automaticall
2b190 79 20 66 72 65 65 64 20 77 68 65 6e 20 74 68 65  y freed when the
2b1a0 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
2b1b0 65 6e 74 20 69 73 20 66 69 6e 61 6c 69 7a 65 64  ent is finalized
2b1c0 2e 0a 2a 2a 20 5e 54 68 65 20 73 74 72 69 6e 67  ..** ^The string
2b1d0 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c   returned by sql
2b1e0 69 74 65 33 5f 65 78 70 61 6e 64 65 64 5f 73 71  ite3_expanded_sq
2b1f0 6c 28 50 29 2c 20 6f 6e 20 74 68 65 20 6f 74 68  l(P), on the oth
2b200 65 72 20 68 61 6e 64 2c 0a 2a 2a 20 69 73 20 6f  er hand,.** is o
2b210 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71  btained from [sq
2b220 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20  lite3_malloc()] 
2b230 61 6e 64 20 6d 75 73 74 20 62 65 20 66 72 65 65  and must be free
2b240 20 62 79 20 74 68 65 20 61 70 70 6c 69 63 61 74   by the applicat
2b250 69 6f 6e 0a 2a 2a 20 62 79 20 70 61 73 73 69 6e  ion.** by passin
2b260 67 20 69 74 20 74 6f 20 5b 73 71 6c 69 74 65 33  g it to [sqlite3
2b270 5f 66 72 65 65 28 29 5d 2e 0a 2a 2f 0a 53 51 4c  _free()]..*/.SQL
2b280 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68  ITE_API const ch
2b290 61 72 20 2a 73 71 6c 69 74 65 33 5f 73 71 6c 28  ar *sqlite3_sql(
2b2a0 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53  sqlite3_stmt *pS
2b2b0 74 6d 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  tmt);.SQLITE_API
2b2c0 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 65   char *sqlite3_e
2b2d0 78 70 61 6e 64 65 64 5f 73 71 6c 28 73 71 6c 69  xpanded_sql(sqli
2b2e0 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29  te3_stmt *pStmt)
2b2f0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2b300 46 3a 20 44 65 74 65 72 6d 69 6e 65 20 49 66 20  F: Determine If 
2b310 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74  An SQL Statement
2b320 20 57 72 69 74 65 73 20 54 68 65 20 44 61 74 61   Writes The Data
2b330 62 61 73 65 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  base.** METHOD: 
2b340 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a  sqlite3_stmt.**.
2b350 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
2b360 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 58 29  stmt_readonly(X)
2b370 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
2b380 6e 73 20 74 72 75 65 20 28 6e 6f 6e 2d 7a 65 72  ns true (non-zer
2b390 6f 29 20 69 66 0a 2a 2a 20 61 6e 64 20 6f 6e 6c  o) if.** and onl
2b3a0 79 20 69 66 20 74 68 65 20 5b 70 72 65 70 61 72  y if the [prepar
2b3b0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 58 20  ed statement] X 
2b3c0 6d 61 6b 65 73 20 6e 6f 20 64 69 72 65 63 74 20  makes no direct 
2b3d0 63 68 61 6e 67 65 73 20 74 6f 0a 2a 2a 20 74 68  changes to.** th
2b3e0 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65  e content of the
2b3f0 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 2e 0a   database file..
2b400 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20  **.** Note that 
2b410 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66  [application-def
2b420 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f  ined SQL functio
2b430 6e 73 5d 20 6f 72 0a 2a 2a 20 5b 76 69 72 74 75  ns] or.** [virtu
2b440 61 6c 20 74 61 62 6c 65 73 5d 20 6d 69 67 68 74  al tables] might
2b450 20 63 68 61 6e 67 65 20 74 68 65 20 64 61 74 61   change the data
2b460 62 61 73 65 20 69 6e 64 69 72 65 63 74 6c 79 20  base indirectly 
2b470 61 73 20 61 20 73 69 64 65 20 65 66 66 65 63 74  as a side effect
2b480 2e 20 20 0a 2a 2a 20 5e 28 46 6f 72 20 65 78 61  .  .** ^(For exa
2b490 6d 70 6c 65 2c 20 69 66 20 61 6e 20 61 70 70 6c  mple, if an appl
2b4a0 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 73 20  ication defines 
2b4b0 61 20 66 75 6e 63 74 69 6f 6e 20 22 65 76 61 6c  a function "eval
2b4c0 28 29 22 20 74 68 61 74 20 0a 2a 2a 20 63 61 6c  ()" that .** cal
2b4d0 6c 73 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63  ls [sqlite3_exec
2b4e0 28 29 5d 2c 20 74 68 65 6e 20 74 68 65 20 66 6f  ()], then the fo
2b4f0 6c 6c 6f 77 69 6e 67 20 53 51 4c 20 73 74 61 74  llowing SQL stat
2b500 65 6d 65 6e 74 20 77 6f 75 6c 64 0a 2a 2a 20 63  ement would.** c
2b510 68 61 6e 67 65 20 74 68 65 20 64 61 74 61 62 61  hange the databa
2b520 73 65 20 66 69 6c 65 20 74 68 72 6f 75 67 68 20  se file through 
2b530 73 69 64 65 2d 65 66 66 65 63 74 73 3a 0a 2a 2a  side-effects:.**
2b540 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
2b550 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 53 45 4c 45  <pre>.**    SELE
2b560 43 54 20 65 76 61 6c 28 27 44 45 4c 45 54 45 20  CT eval('DELETE 
2b570 46 52 4f 4d 20 74 31 27 29 20 46 52 4f 4d 20 74  FROM t1') FROM t
2b580 32 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c  2;.** </pre></bl
2b590 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20  ockquote>.**.** 
2b5a0 42 75 74 20 62 65 63 61 75 73 65 20 74 68 65 20  But because the 
2b5b0 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65  [SELECT] stateme
2b5c0 6e 74 20 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e  nt does not chan
2b5d0 67 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ge the database 
2b5e0 66 69 6c 65 0a 2a 2a 20 64 69 72 65 63 74 6c 79  file.** directly
2b5f0 2c 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72  , sqlite3_stmt_r
2b600 65 61 64 6f 6e 6c 79 28 29 20 77 6f 75 6c 64 20  eadonly() would 
2b610 73 74 69 6c 6c 20 72 65 74 75 72 6e 20 74 72 75  still return tru
2b620 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 72 61 6e  e.)^.**.** ^Tran
2b630 73 61 63 74 69 6f 6e 20 63 6f 6e 74 72 6f 6c 20  saction control 
2b640 73 74 61 74 65 6d 65 6e 74 73 20 73 75 63 68 20  statements such 
2b650 61 73 20 5b 42 45 47 49 4e 5d 2c 20 5b 43 4f 4d  as [BEGIN], [COM
2b660 4d 49 54 5d 2c 20 5b 52 4f 4c 4c 42 41 43 4b 5d  MIT], [ROLLBACK]
2b670 2c 0a 2a 2a 20 5b 53 41 56 45 50 4f 49 4e 54 5d  ,.** [SAVEPOINT]
2b680 2c 20 61 6e 64 20 5b 52 45 4c 45 41 53 45 5d 20  , and [RELEASE] 
2b690 63 61 75 73 65 20 73 71 6c 69 74 65 33 5f 73 74  cause sqlite3_st
2b6a0 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20 74 6f  mt_readonly() to
2b6b0 20 72 65 74 75 72 6e 20 74 72 75 65 2c 0a 2a 2a   return true,.**
2b6c0 20 73 69 6e 63 65 20 74 68 65 20 73 74 61 74 65   since the state
2b6d0 6d 65 6e 74 73 20 74 68 65 6d 73 65 6c 76 65 73  ments themselves
2b6e0 20 64 6f 20 6e 6f 74 20 61 63 74 75 61 6c 6c 79   do not actually
2b6f0 20 6d 6f 64 69 66 79 20 74 68 65 20 64 61 74 61   modify the data
2b700 62 61 73 65 20 62 75 74 0a 2a 2a 20 72 61 74 68  base but.** rath
2b710 65 72 20 74 68 65 79 20 63 6f 6e 74 72 6f 6c 20  er they control 
2b720 74 68 65 20 74 69 6d 69 6e 67 20 6f 66 20 77 68  the timing of wh
2b730 65 6e 20 6f 74 68 65 72 20 73 74 61 74 65 6d 65  en other stateme
2b740 6e 74 73 20 6d 6f 64 69 66 79 20 74 68 65 20 0a  nts modify the .
2b750 2a 2a 20 64 61 74 61 62 61 73 65 2e 20 20 5e 54  ** database.  ^T
2b760 68 65 20 5b 41 54 54 41 43 48 5d 20 61 6e 64 20  he [ATTACH] and 
2b770 5b 44 45 54 41 43 48 5d 20 73 74 61 74 65 6d 65  [DETACH] stateme
2b780 6e 74 73 20 61 6c 73 6f 20 63 61 75 73 65 0a 2a  nts also cause.*
2b790 2a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72  * sqlite3_stmt_r
2b7a0 65 61 64 6f 6e 6c 79 28 29 20 74 6f 20 72 65 74  eadonly() to ret
2b7b0 75 72 6e 20 74 72 75 65 20 73 69 6e 63 65 2c 20  urn true since, 
2b7c0 77 68 69 6c 65 20 74 68 6f 73 65 20 73 74 61 74  while those stat
2b7d0 65 6d 65 6e 74 73 0a 2a 2a 20 63 68 61 6e 67 65  ements.** change
2b7e0 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69   the configurati
2b7f0 6f 6e 20 6f 66 20 61 20 64 61 74 61 62 61 73 65  on of a database
2b800 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 20 74 68 65   connection, the
2b810 79 20 64 6f 20 6e 6f 74 20 6d 61 6b 65 20 0a 2a  y do not make .*
2b820 2a 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65  * changes to the
2b830 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20   content of the 
2b840 64 61 74 61 62 61 73 65 20 66 69 6c 65 73 20 6f  database files o
2b850 6e 20 64 69 73 6b 2e 0a 2a 2f 0a 53 51 4c 49 54  n disk..*/.SQLIT
2b860 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
2b870 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28  3_stmt_readonly(
2b880 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53  sqlite3_stmt *pS
2b890 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  tmt);../*.** CAP
2b8a0 49 33 52 45 46 3a 20 44 65 74 65 72 6d 69 6e 65  I3REF: Determine
2b8b0 20 49 66 20 41 20 50 72 65 70 61 72 65 64 20 53   If A Prepared S
2b8c0 74 61 74 65 6d 65 6e 74 20 48 61 73 20 42 65 65  tatement Has Bee
2b8d0 6e 20 52 65 73 65 74 0a 2a 2a 20 4d 45 54 48 4f  n Reset.** METHO
2b8e0 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a  D: sqlite3_stmt.
2b8f0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
2b900 65 33 5f 73 74 6d 74 5f 62 75 73 79 28 53 29 20  e3_stmt_busy(S) 
2b910 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
2b920 73 20 74 72 75 65 20 28 6e 6f 6e 2d 7a 65 72 6f  s true (non-zero
2b930 29 20 69 66 20 74 68 65 0a 2a 2a 20 5b 70 72 65  ) if the.** [pre
2b940 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2b950 20 53 20 68 61 73 20 62 65 65 6e 20 73 74 65 70   S has been step
2b960 70 65 64 20 61 74 20 6c 65 61 73 74 20 6f 6e 63  ped at least onc
2b970 65 20 75 73 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c  e using .** [sql
2b980 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 62 75  ite3_step(S)] bu
2b990 74 20 68 61 73 20 6e 65 69 74 68 65 72 20 72 75  t has neither ru
2b9a0 6e 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 20  n to completion 
2b9b0 28 72 65 74 75 72 6e 65 64 0a 2a 2a 20 5b 53 51  (returned.** [SQ
2b9c0 4c 49 54 45 5f 44 4f 4e 45 5d 20 66 72 6f 6d 20  LITE_DONE] from 
2b9d0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29  [sqlite3_step(S)
2b9e0 5d 29 20 6e 6f 72 0a 2a 2a 20 62 65 65 6e 20 72  ]) nor.** been r
2b9f0 65 73 65 74 20 75 73 69 6e 67 20 5b 73 71 6c 69  eset using [sqli
2ba00 74 65 33 5f 72 65 73 65 74 28 53 29 5d 2e 20 20  te3_reset(S)].  
2ba10 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 74 6d  ^The sqlite3_stm
2ba20 74 5f 62 75 73 79 28 53 29 0a 2a 2a 20 69 6e 74  t_busy(S).** int
2ba30 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 66  erface returns f
2ba40 61 6c 73 65 20 69 66 20 53 20 69 73 20 61 20 4e  alse if S is a N
2ba50 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 49 66  ULL pointer.  If
2ba60 20 53 20 69 73 20 6e 6f 74 20 61 20 0a 2a 2a 20   S is not a .** 
2ba70 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 61 6e 64  NULL pointer and
2ba80 20 69 73 20 6e 6f 74 20 61 20 70 6f 69 6e 74 65   is not a pointe
2ba90 72 20 74 6f 20 61 20 76 61 6c 69 64 20 5b 70 72  r to a valid [pr
2baa0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2bab0 5d 0a 2a 2a 20 6f 62 6a 65 63 74 2c 20 74 68 65  ].** object, the
2bac0 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69  n the behavior i
2bad0 73 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 20  s undefined and 
2bae0 70 72 6f 62 61 62 6c 79 20 75 6e 64 65 73 69 72  probably undesir
2baf0 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  able..**.** This
2bb00 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e 20 62   interface can b
2bb10 65 20 75 73 65 64 20 69 6e 20 63 6f 6d 62 69 6e  e used in combin
2bb20 61 74 69 6f 6e 20 5b 73 71 6c 69 74 65 33 5f 6e  ation [sqlite3_n
2bb30 65 78 74 5f 73 74 6d 74 28 29 5d 0a 2a 2a 20 74  ext_stmt()].** t
2bb40 6f 20 6c 6f 63 61 74 65 20 61 6c 6c 20 70 72 65  o locate all pre
2bb50 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73  pared statements
2bb60 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
2bb70 20 61 20 64 61 74 61 62 61 73 65 20 0a 2a 2a 20   a database .** 
2bb80 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20  connection that 
2bb90 61 72 65 20 69 6e 20 6e 65 65 64 20 6f 66 20 62  are in need of b
2bba0 65 69 6e 67 20 72 65 73 65 74 2e 20 20 54 68 69  eing reset.  Thi
2bbb0 73 20 63 61 6e 20 62 65 20 75 73 65 64 2c 0a 2a  s can be used,.*
2bbc0 2a 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20 69  * for example, i
2bbd0 6e 20 64 69 61 67 6e 6f 73 74 69 63 20 72 6f 75  n diagnostic rou
2bbe0 74 69 6e 65 73 20 74 6f 20 73 65 61 72 63 68 20  tines to search 
2bbf0 66 6f 72 20 70 72 65 70 61 72 65 64 20 0a 2a 2a  for prepared .**
2bc00 20 73 74 61 74 65 6d 65 6e 74 73 20 74 68 61 74   statements that
2bc10 20 61 72 65 20 68 6f 6c 64 69 6e 67 20 61 20 74   are holding a t
2bc20 72 61 6e 73 61 63 74 69 6f 6e 20 6f 70 65 6e 2e  ransaction open.
2bc30 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .*/.SQLITE_API i
2bc40 6e 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f  nt sqlite3_stmt_
2bc50 62 75 73 79 28 73 71 6c 69 74 65 33 5f 73 74 6d  busy(sqlite3_stm
2bc60 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  t*);../*.** CAPI
2bc70 33 52 45 46 3a 20 44 79 6e 61 6d 69 63 61 6c 6c  3REF: Dynamicall
2bc80 79 20 54 79 70 65 64 20 56 61 6c 75 65 20 4f 62  y Typed Value Ob
2bc90 6a 65 63 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  ject.** KEYWORDS
2bca0 3a 20 7b 70 72 6f 74 65 63 74 65 64 20 73 71 6c  : {protected sql
2bcb0 69 74 65 33 5f 76 61 6c 75 65 7d 20 7b 75 6e 70  ite3_value} {unp
2bcc0 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
2bcd0 5f 76 61 6c 75 65 7d 0a 2a 2a 0a 2a 2a 20 53 51  _value}.**.** SQ
2bce0 4c 69 74 65 20 75 73 65 73 20 74 68 65 20 73 71  Lite uses the sq
2bcf0 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
2bd00 63 74 20 74 6f 20 72 65 70 72 65 73 65 6e 74 20  ct to represent 
2bd10 61 6c 6c 20 76 61 6c 75 65 73 0a 2a 2a 20 74 68  all values.** th
2bd20 61 74 20 63 61 6e 20 62 65 20 73 74 6f 72 65 64  at can be stored
2bd30 20 69 6e 20 61 20 64 61 74 61 62 61 73 65 20 74   in a database t
2bd40 61 62 6c 65 2e 20 53 51 4c 69 74 65 20 75 73 65  able. SQLite use
2bd50 73 20 64 79 6e 61 6d 69 63 20 74 79 70 69 6e 67  s dynamic typing
2bd60 0a 2a 2a 20 66 6f 72 20 74 68 65 20 76 61 6c 75  .** for the valu
2bd70 65 73 20 69 74 20 73 74 6f 72 65 73 2e 20 20 5e  es it stores.  ^
2bd80 56 61 6c 75 65 73 20 73 74 6f 72 65 64 20 69 6e  Values stored in
2bd90 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
2bda0 62 6a 65 63 74 73 0a 2a 2a 20 63 61 6e 20 62 65  bjects.** can be
2bdb0 20 69 6e 74 65 67 65 72 73 2c 20 66 6c 6f 61 74   integers, float
2bdc0 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 73  ing point values
2bdd0 2c 20 73 74 72 69 6e 67 73 2c 20 42 4c 4f 42 73  , strings, BLOBs
2bde0 2c 20 6f 72 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a  , or NULL..**.**
2bdf0 20 41 6e 20 73 71 6c 69 74 65 33 5f 76 61 6c 75   An sqlite3_valu
2be00 65 20 6f 62 6a 65 63 74 20 6d 61 79 20 62 65 20  e object may be 
2be10 65 69 74 68 65 72 20 22 70 72 6f 74 65 63 74 65  either "protecte
2be20 64 22 20 6f 72 20 22 75 6e 70 72 6f 74 65 63 74  d" or "unprotect
2be30 65 64 22 2e 0a 2a 2a 20 53 6f 6d 65 20 69 6e 74  ed"..** Some int
2be40 65 72 66 61 63 65 73 20 72 65 71 75 69 72 65 20  erfaces require 
2be50 61 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  a protected sqli
2be60 74 65 33 5f 76 61 6c 75 65 2e 20 20 4f 74 68 65  te3_value.  Othe
2be70 72 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20  r interfaces.** 
2be80 77 69 6c 6c 20 61 63 63 65 70 74 20 65 69 74 68  will accept eith
2be90 65 72 20 61 20 70 72 6f 74 65 63 74 65 64 20 6f  er a protected o
2bea0 72 20 61 6e 20 75 6e 70 72 6f 74 65 63 74 65 64  r an unprotected
2beb0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 0a   sqlite3_value..
2bec0 2a 2a 20 45 76 65 72 79 20 69 6e 74 65 72 66 61  ** Every interfa
2bed0 63 65 20 74 68 61 74 20 61 63 63 65 70 74 73 20  ce that accepts 
2bee0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 61 72  sqlite3_value ar
2bef0 67 75 6d 65 6e 74 73 20 73 70 65 63 69 66 69 65  guments specifie
2bf00 73 0a 2a 2a 20 77 68 65 74 68 65 72 20 6f 72 20  s.** whether or 
2bf10 6e 6f 74 20 69 74 20 72 65 71 75 69 72 65 73 20  not it requires 
2bf20 61 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  a protected sqli
2bf30 74 65 33 5f 76 61 6c 75 65 2e 20 20 54 68 65 0a  te3_value.  The.
2bf40 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  ** [sqlite3_valu
2bf50 65 5f 64 75 70 28 29 5d 20 69 6e 74 65 72 66 61  e_dup()] interfa
2bf60 63 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 74  ce can be used t
2bf70 6f 20 63 6f 6e 73 74 72 75 63 74 20 61 20 6e 65  o construct a ne
2bf80 77 20 0a 2a 2a 20 70 72 6f 74 65 63 74 65 64 20  w .** protected 
2bf90 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 66 72  sqlite3_value fr
2bfa0 6f 6d 20 61 6e 20 75 6e 70 72 6f 74 65 63 74 65  om an unprotecte
2bfb0 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e  d sqlite3_value.
2bfc0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 65 72 6d 73  .**.** The terms
2bfd0 20 22 70 72 6f 74 65 63 74 65 64 22 20 61 6e 64   "protected" and
2bfe0 20 22 75 6e 70 72 6f 74 65 63 74 65 64 22 20 72   "unprotected" r
2bff0 65 66 65 72 20 74 6f 20 77 68 65 74 68 65 72 20  efer to whether 
2c000 6f 72 20 6e 6f 74 0a 2a 2a 20 61 20 6d 75 74 65  or not.** a mute
2c010 78 20 69 73 20 68 65 6c 64 2e 20 20 41 6e 20 69  x is held.  An i
2c020 6e 74 65 72 6e 61 6c 20 6d 75 74 65 78 20 69 73  nternal mutex is
2c030 20 68 65 6c 64 20 66 6f 72 20 61 20 70 72 6f 74   held for a prot
2c040 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33  ected.** sqlite3
2c050 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 62 75  _value object bu
2c060 74 20 6e 6f 20 6d 75 74 65 78 20 69 73 20 68 65  t no mutex is he
2c070 6c 64 20 66 6f 72 20 61 6e 20 75 6e 70 72 6f 74  ld for an unprot
2c080 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33  ected.** sqlite3
2c090 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 2e 20 20  _value object.  
2c0a0 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  If SQLite is com
2c0b0 70 69 6c 65 64 20 74 6f 20 62 65 20 73 69 6e 67  piled to be sing
2c0c0 6c 65 2d 74 68 72 65 61 64 65 64 0a 2a 2a 20 28  le-threaded.** (
2c0d0 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 54 48 52  with [SQLITE_THR
2c0e0 45 41 44 53 41 46 45 3d 30 5d 20 61 6e 64 20 77  EADSAFE=0] and w
2c0f0 69 74 68 20 5b 73 71 6c 69 74 65 33 5f 74 68 72  ith [sqlite3_thr
2c100 65 61 64 73 61 66 65 28 29 5d 20 72 65 74 75 72  eadsafe()] retur
2c110 6e 69 6e 67 20 30 29 0a 2a 2a 20 6f 72 20 69 66  ning 0).** or if
2c120 20 53 51 4c 69 74 65 20 69 73 20 72 75 6e 20 69   SQLite is run i
2c130 6e 20 6f 6e 65 20 6f 66 20 72 65 64 75 63 65 64  n one of reduced
2c140 20 6d 75 74 65 78 20 6d 6f 64 65 73 20 0a 2a 2a   mutex modes .**
2c150 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
2c160 53 49 4e 47 4c 45 54 48 52 45 41 44 5d 20 6f 72  SINGLETHREAD] or
2c170 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
2c180 4d 55 4c 54 49 54 48 52 45 41 44 5d 0a 2a 2a 20  MULTITHREAD].** 
2c190 74 68 65 6e 20 74 68 65 72 65 20 69 73 20 6e 6f  then there is no
2c1a0 20 64 69 73 74 69 6e 63 74 69 6f 6e 20 62 65 74   distinction bet
2c1b0 77 65 65 6e 20 70 72 6f 74 65 63 74 65 64 20 61  ween protected a
2c1c0 6e 64 20 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a  nd unprotected.*
2c1d0 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  * sqlite3_value 
2c1e0 6f 62 6a 65 63 74 73 20 61 6e 64 20 74 68 65 79  objects and they
2c1f0 20 63 61 6e 20 62 65 20 75 73 65 64 20 69 6e 74   can be used int
2c200 65 72 63 68 61 6e 67 65 61 62 6c 79 2e 20 20 48  erchangeably.  H
2c210 6f 77 65 76 65 72 2c 0a 2a 2a 20 66 6f 72 20 6d  owever,.** for m
2c220 61 78 69 6d 75 6d 20 63 6f 64 65 20 70 6f 72 74  aximum code port
2c230 61 62 69 6c 69 74 79 20 69 74 20 69 73 20 72 65  ability it is re
2c240 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 61  commended that a
2c250 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73  pplications.** s
2c260 74 69 6c 6c 20 6d 61 6b 65 20 74 68 65 20 64 69  till make the di
2c270 73 74 69 6e 63 74 69 6f 6e 20 62 65 74 77 65 65  stinction betwee
2c280 6e 20 70 72 6f 74 65 63 74 65 64 20 61 6e 64 20  n protected and 
2c290 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73  unprotected.** s
2c2a0 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
2c2b0 65 63 74 73 20 65 76 65 6e 20 77 68 65 6e 20 6e  ects even when n
2c2c0 6f 74 20 73 74 72 69 63 74 6c 79 20 72 65 71 75  ot strictly requ
2c2d0 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ired..**.** ^The
2c2e0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
2c2f0 62 6a 65 63 74 73 20 74 68 61 74 20 61 72 65 20  bjects that are 
2c300 70 61 73 73 65 64 20 61 73 20 70 61 72 61 6d 65  passed as parame
2c310 74 65 72 73 20 69 6e 74 6f 20 74 68 65 0a 2a 2a  ters into the.**
2c320 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
2c330 6f 66 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d  of [application-
2c340 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63  defined SQL func
2c350 74 69 6f 6e 73 5d 20 61 72 65 20 70 72 6f 74 65  tions] are prote
2c360 63 74 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 73 71  cted..** ^The sq
2c370 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
2c380 63 74 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a  ct returned by.*
2c390 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  * [sqlite3_colum
2c3a0 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 75 6e  n_value()] is un
2c3b0 70 72 6f 74 65 63 74 65 64 2e 0a 2a 2a 20 55 6e  protected..** Un
2c3c0 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
2c3d0 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20  3_value objects 
2c3e0 6d 61 79 20 6f 6e 6c 79 20 62 65 20 75 73 65 64  may only be used
2c3f0 20 77 69 74 68 0a 2a 2a 20 5b 73 71 6c 69 74 65   with.** [sqlite
2c400 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29  3_result_value()
2c410 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62  ] and [sqlite3_b
2c420 69 6e 64 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a  ind_value()]..**
2c430 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61   The [sqlite3_va
2c440 6c 75 65 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74  lue_blob | sqlit
2c450 65 33 5f 76 61 6c 75 65 5f 74 79 70 65 28 29 5d  e3_value_type()]
2c460 20 66 61 6d 69 6c 79 20 6f 66 0a 2a 2a 20 69 6e   family of.** in
2c470 74 65 72 66 61 63 65 73 20 72 65 71 75 69 72 65  terfaces require
2c480 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74   protected sqlit
2c490 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73  e3_value objects
2c4a0 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72  ..*/.typedef str
2c4b0 75 63 74 20 4d 65 6d 20 73 71 6c 69 74 65 33 5f  uct Mem sqlite3_
2c4c0 76 61 6c 75 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  value;../*.** CA
2c4d0 50 49 33 52 45 46 3a 20 53 51 4c 20 46 75 6e 63  PI3REF: SQL Func
2c4e0 74 69 6f 6e 20 43 6f 6e 74 65 78 74 20 4f 62 6a  tion Context Obj
2c4f0 65 63 74 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f  ect.**.** The co
2c500 6e 74 65 78 74 20 69 6e 20 77 68 69 63 68 20 61  ntext in which a
2c510 6e 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 65  n SQL function e
2c520 78 65 63 75 74 65 73 20 69 73 20 73 74 6f 72 65  xecutes is store
2c530 64 20 69 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69 74  d in an.** sqlit
2c540 65 33 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65 63  e3_context objec
2c550 74 2e 20 20 5e 41 20 70 6f 69 6e 74 65 72 20 74  t.  ^A pointer t
2c560 6f 20 61 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6e  o an sqlite3_con
2c570 74 65 78 74 20 6f 62 6a 65 63 74 0a 2a 2a 20 69  text object.** i
2c580 73 20 61 6c 77 61 79 73 20 66 69 72 73 74 20 70  s always first p
2c590 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 61 70 70  arameter to [app
2c5a0 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
2c5b0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 2e   SQL functions].
2c5c0 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74  .** The applicat
2c5d0 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20  ion-defined SQL 
2c5e0 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65  function impleme
2c5f0 6e 74 61 74 69 6f 6e 20 77 69 6c 6c 20 70 61 73  ntation will pas
2c600 73 20 74 68 69 73 0a 2a 2a 20 70 6f 69 6e 74 65  s this.** pointe
2c610 72 20 74 68 72 6f 75 67 68 20 69 6e 74 6f 20 63  r through into c
2c620 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33  alls to [sqlite3
2c630 5f 72 65 73 75 6c 74 5f 69 6e 74 20 7c 20 73 71  _result_int | sq
2c640 6c 69 74 65 33 5f 72 65 73 75 6c 74 28 29 5d 2c  lite3_result()],
2c650 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 61 67 67  .** [sqlite3_agg
2c660 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29  regate_context()
2c670 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 75 73 65 72  ], [sqlite3_user
2c680 5f 64 61 74 61 28 29 5d 2c 0a 2a 2a 20 5b 73 71  _data()],.** [sq
2c690 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62  lite3_context_db
2c6a0 5f 68 61 6e 64 6c 65 28 29 5d 2c 20 5b 73 71 6c  _handle()], [sql
2c6b0 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61  ite3_get_auxdata
2c6c0 28 29 5d 2c 0a 2a 2a 20 61 6e 64 2f 6f 72 20 5b  ()],.** and/or [
2c6d0 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64  sqlite3_set_auxd
2c6e0 61 74 61 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64  ata()]..*/.typed
2c6f0 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  ef struct sqlite
2c700 33 5f 63 6f 6e 74 65 78 74 20 73 71 6c 69 74 65  3_context sqlite
2c710 33 5f 63 6f 6e 74 65 78 74 3b 0a 0a 2f 2a 0a 2a  3_context;../*.*
2c720 2a 20 43 41 50 49 33 52 45 46 3a 20 42 69 6e 64  * CAPI3REF: Bind
2c730 69 6e 67 20 56 61 6c 75 65 73 20 54 6f 20 50 72  ing Values To Pr
2c740 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74  epared Statement
2c750 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  s.** KEYWORDS: {
2c760 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 7d 20  host parameter} 
2c770 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73  {host parameters
2c780 7d 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65  } {host paramete
2c790 72 20 6e 61 6d 65 7d 0a 2a 2a 20 4b 45 59 57 4f  r name}.** KEYWO
2c7a0 52 44 53 3a 20 7b 53 51 4c 20 70 61 72 61 6d 65  RDS: {SQL parame
2c7b0 74 65 72 7d 20 7b 53 51 4c 20 70 61 72 61 6d 65  ter} {SQL parame
2c7c0 74 65 72 73 7d 20 7b 70 61 72 61 6d 65 74 65 72  ters} {parameter
2c7d0 20 62 69 6e 64 69 6e 67 7d 0a 2a 2a 20 4d 45 54   binding}.** MET
2c7e0 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d  HOD: sqlite3_stm
2c7f0 74 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 74 68 65  t.**.** ^(In the
2c800 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74   SQL statement t
2c810 65 78 74 20 69 6e 70 75 74 20 74 6f 20 5b 73 71  ext input to [sq
2c820 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
2c830 28 29 5d 20 61 6e 64 20 69 74 73 20 76 61 72 69  ()] and its vari
2c840 61 6e 74 73 2c 0a 2a 2a 20 6c 69 74 65 72 61 6c  ants,.** literal
2c850 73 20 6d 61 79 20 62 65 20 72 65 70 6c 61 63 65  s may be replace
2c860 64 20 62 79 20 61 20 5b 70 61 72 61 6d 65 74 65  d by a [paramete
2c870 72 5d 20 74 68 61 74 20 6d 61 74 63 68 65 73 20  r] that matches 
2c880 6f 6e 65 20 6f 66 20 66 6f 6c 6c 6f 77 69 6e 67  one of following
2c890 0a 2a 2a 20 74 65 6d 70 6c 61 74 65 73 3a 0a 2a  .** templates:.*
2c8a0 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ul>.** <li
2c8b0 3e 20 20 3f 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 4e  >  ?.** <li>  ?N
2c8c0 4e 4e 0a 2a 2a 20 3c 6c 69 3e 20 20 3a 56 56 56  NN.** <li>  :VVV
2c8d0 0a 2a 2a 20 3c 6c 69 3e 20 20 40 56 56 56 0a 2a  .** <li>  @VVV.*
2c8e0 2a 20 3c 6c 69 3e 20 20 24 56 56 56 0a 2a 2a 20  * <li>  $VVV.** 
2c8f0 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74  </ul>.**.** In t
2c900 68 65 20 74 65 6d 70 6c 61 74 65 73 20 61 62 6f  he templates abo
2c910 76 65 2c 20 4e 4e 4e 20 72 65 70 72 65 73 65 6e  ve, NNN represen
2c920 74 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6c 69  ts an integer li
2c930 74 65 72 61 6c 2c 0a 2a 2a 20 61 6e 64 20 56 56  teral,.** and VV
2c940 56 20 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20  V represents an 
2c950 61 6c 70 68 61 6e 75 6d 65 72 69 63 20 69 64 65  alphanumeric ide
2c960 6e 74 69 66 69 65 72 2e 29 5e 20 20 5e 54 68 65  ntifier.)^  ^The
2c970 20 76 61 6c 75 65 73 20 6f 66 20 74 68 65 73 65   values of these
2c980 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 20 28  .** parameters (
2c990 61 6c 73 6f 20 63 61 6c 6c 65 64 20 22 68 6f 73  also called "hos
2c9a0 74 20 70 61 72 61 6d 65 74 65 72 20 6e 61 6d 65  t parameter name
2c9b0 73 22 20 6f 72 20 22 53 51 4c 20 70 61 72 61 6d  s" or "SQL param
2c9c0 65 74 65 72 73 22 29 0a 2a 2a 20 63 61 6e 20 62  eters").** can b
2c9d0 65 20 73 65 74 20 75 73 69 6e 67 20 74 68 65 20  e set using the 
2c9e0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29  sqlite3_bind_*()
2c9f0 20 72 6f 75 74 69 6e 65 73 20 64 65 66 69 6e 65   routines define
2ca00 64 20 68 65 72 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54  d here..**.** ^T
2ca10 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
2ca20 74 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33  t to the sqlite3
2ca30 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e  _bind_*() routin
2ca40 65 73 20 69 73 20 61 6c 77 61 79 73 0a 2a 2a 20  es is always.** 
2ca50 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
2ca60 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20   [sqlite3_stmt] 
2ca70 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20  object returned 
2ca80 66 72 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  from.** [sqlite3
2ca90 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f  _prepare_v2()] o
2caa0 72 20 69 74 73 20 76 61 72 69 61 6e 74 73 2e 0a  r its variants..
2cab0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e  **.** ^The secon
2cac0 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68  d argument is th
2cad0 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20 53  e index of the S
2cae0 51 4c 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  QL parameter to 
2caf0 62 65 20 73 65 74 2e 0a 2a 2a 20 5e 54 68 65 20  be set..** ^The 
2cb00 6c 65 66 74 6d 6f 73 74 20 53 51 4c 20 70 61 72  leftmost SQL par
2cb10 61 6d 65 74 65 72 20 68 61 73 20 61 6e 20 69 6e  ameter has an in
2cb20 64 65 78 20 6f 66 20 31 2e 20 20 5e 57 68 65 6e  dex of 1.  ^When
2cb30 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 64 0a   the same named.
2cb40 2a 2a 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72  ** SQL parameter
2cb50 20 69 73 20 75 73 65 64 20 6d 6f 72 65 20 74 68   is used more th
2cb60 61 6e 20 6f 6e 63 65 2c 20 73 65 63 6f 6e 64 20  an once, second 
2cb70 61 6e 64 20 73 75 62 73 65 71 75 65 6e 74 0a 2a  and subsequent.*
2cb80 2a 20 6f 63 63 75 72 72 65 6e 63 65 73 20 68 61  * occurrences ha
2cb90 76 65 20 74 68 65 20 73 61 6d 65 20 69 6e 64 65  ve the same inde
2cba0 78 20 61 73 20 74 68 65 20 66 69 72 73 74 20 6f  x as the first o
2cbb0 63 63 75 72 72 65 6e 63 65 2e 0a 2a 2a 20 5e 54  ccurrence..** ^T
2cbc0 68 65 20 69 6e 64 65 78 20 66 6f 72 20 6e 61 6d  he index for nam
2cbd0 65 64 20 70 61 72 61 6d 65 74 65 72 73 20 63 61  ed parameters ca
2cbe0 6e 20 62 65 20 6c 6f 6f 6b 65 64 20 75 70 20 75  n be looked up u
2cbf0 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c  sing the.** [sql
2cc00 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
2cc10 74 65 72 5f 69 6e 64 65 78 28 29 5d 20 41 50 49  ter_index()] API
2cc20 20 69 66 20 64 65 73 69 72 65 64 2e 20 20 5e 54   if desired.  ^T
2cc30 68 65 20 69 6e 64 65 78 0a 2a 2a 20 66 6f 72 20  he index.** for 
2cc40 22 3f 4e 4e 4e 22 20 70 61 72 61 6d 65 74 65 72  "?NNN" parameter
2cc50 73 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f  s is the value o
2cc60 66 20 4e 4e 4e 2e 0a 2a 2a 20 5e 54 68 65 20 4e  f NNN..** ^The N
2cc70 4e 4e 20 76 61 6c 75 65 20 6d 75 73 74 20 62 65  NN value must be
2cc80 20 62 65 74 77 65 65 6e 20 31 20 61 6e 64 20 74   between 1 and t
2cc90 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69  he [sqlite3_limi
2cca0 74 28 29 5d 0a 2a 2a 20 70 61 72 61 6d 65 74 65  t()].** paramete
2ccb0 72 20 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  r [SQLITE_LIMIT_
2ccc0 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 5d  VARIABLE_NUMBER]
2ccd0 20 28 64 65 66 61 75 6c 74 20 76 61 6c 75 65 3a   (default value:
2cce0 20 39 39 39 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68   999)..**.** ^Th
2ccf0 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74  e third argument
2cd00 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 74 6f   is the value to
2cd10 20 62 69 6e 64 20 74 6f 20 74 68 65 20 70 61 72   bind to the par
2cd20 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 74  ameter..** ^If t
2cd30 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  he third paramet
2cd40 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69  er to sqlite3_bi
2cd50 6e 64 5f 74 65 78 74 28 29 20 6f 72 20 73 71 6c  nd_text() or sql
2cd60 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36  ite3_bind_text16
2cd70 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33  ().** or sqlite3
2cd80 5f 62 69 6e 64 5f 62 6c 6f 62 28 29 20 69 73 20  _bind_blob() is 
2cd90 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74  a NULL pointer t
2cda0 68 65 6e 20 74 68 65 20 66 6f 75 72 74 68 20 70  hen the fourth p
2cdb0 61 72 61 6d 65 74 65 72 0a 2a 2a 20 69 73 20 69  arameter.** is i
2cdc0 67 6e 6f 72 65 64 20 61 6e 64 20 74 68 65 20 65  gnored and the e
2cdd0 6e 64 20 72 65 73 75 6c 74 20 69 73 20 74 68 65  nd result is the
2cde0 20 73 61 6d 65 20 61 73 20 73 71 6c 69 74 65 33   same as sqlite3
2cdf0 5f 62 69 6e 64 5f 6e 75 6c 6c 28 29 2e 0a 2a 2a  _bind_null()..**
2ce00 0a 2a 2a 20 5e 28 49 6e 20 74 68 6f 73 65 20 72  .** ^(In those r
2ce10 6f 75 74 69 6e 65 73 20 74 68 61 74 20 68 61 76  outines that hav
2ce20 65 20 61 20 66 6f 75 72 74 68 20 61 72 67 75 6d  e a fourth argum
2ce30 65 6e 74 2c 20 69 74 73 20 76 61 6c 75 65 20 69  ent, its value i
2ce40 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20  s the.** number 
2ce50 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 65 20  of bytes in the 
2ce60 70 61 72 61 6d 65 74 65 72 2e 20 20 54 6f 20 62  parameter.  To b
2ce70 65 20 63 6c 65 61 72 3a 20 74 68 65 20 76 61 6c  e clear: the val
2ce80 75 65 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d  ue is the.** num
2ce90 62 65 72 20 6f 66 20 3c 75 3e 62 79 74 65 73 3c  ber of <u>bytes<
2cea0 2f 75 3e 20 69 6e 20 74 68 65 20 76 61 6c 75 65  /u> in the value
2ceb0 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62 65 72  , not the number
2cec0 20 6f 66 20 63 68 61 72 61 63 74 65 72 73 2e 29   of characters.)
2ced0 5e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 6f 75  ^.** ^If the fou
2cee0 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  rth parameter to
2cef0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65   sqlite3_bind_te
2cf00 78 74 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  xt() or sqlite3_
2cf10 62 69 6e 64 5f 74 65 78 74 31 36 28 29 0a 2a 2a  bind_text16().**
2cf20 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68   is negative, th
2cf30 65 6e 20 74 68 65 20 6c 65 6e 67 74 68 20 6f 66  en the length of
2cf40 20 74 68 65 20 73 74 72 69 6e 67 20 69 73 0a 2a   the string is.*
2cf50 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  * the number of 
2cf60 62 79 74 65 73 20 75 70 20 74 6f 20 74 68 65 20  bytes up to the 
2cf70 66 69 72 73 74 20 7a 65 72 6f 20 74 65 72 6d 69  first zero termi
2cf80 6e 61 74 6f 72 2e 0a 2a 2a 20 49 66 20 74 68 65  nator..** If the
2cf90 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
2cfa0 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e  r to sqlite3_bin
2cfb0 64 5f 62 6c 6f 62 28 29 20 69 73 20 6e 65 67 61  d_blob() is nega
2cfc0 74 69 76 65 2c 20 74 68 65 6e 0a 2a 2a 20 74 68  tive, then.** th
2cfd0 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e  e behavior is un
2cfe0 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 49 66 20 61  defined..** If a
2cff0 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 20 66 6f   non-negative fo
2d000 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 69  urth parameter i
2d010 73 20 70 72 6f 76 69 64 65 64 20 74 6f 20 73 71  s provided to sq
2d020 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28  lite3_bind_text(
2d030 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f  ).** or sqlite3_
2d040 62 69 6e 64 5f 74 65 78 74 31 36 28 29 20 6f 72  bind_text16() or
2d050 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65   sqlite3_bind_te
2d060 78 74 36 34 28 29 20 74 68 65 6e 0a 2a 2a 20 74  xt64() then.** t
2d070 68 61 74 20 70 61 72 61 6d 65 74 65 72 20 6d 75  hat parameter mu
2d080 73 74 20 62 65 20 74 68 65 20 62 79 74 65 20 6f  st be the byte o
2d090 66 66 73 65 74 0a 2a 2a 20 77 68 65 72 65 20 74  ffset.** where t
2d0a0 68 65 20 4e 55 4c 20 74 65 72 6d 69 6e 61 74 6f  he NUL terminato
2d0b0 72 20 77 6f 75 6c 64 20 6f 63 63 75 72 20 61 73  r would occur as
2d0c0 73 75 6d 69 6e 67 20 74 68 65 20 73 74 72 69 6e  suming the strin
2d0d0 67 20 77 65 72 65 20 4e 55 4c 0a 2a 2a 20 74 65  g were NUL.** te
2d0e0 72 6d 69 6e 61 74 65 64 2e 20 20 49 66 20 61 6e  rminated.  If an
2d0f0 79 20 4e 55 4c 20 63 68 61 72 61 63 74 65 72 73  y NUL characters
2d100 20 6f 63 63 75 72 20 61 74 20 62 79 74 65 20 6f   occur at byte o
2d110 66 66 73 65 74 73 20 6c 65 73 73 20 74 68 61 6e  ffsets less than
2d120 20 0a 2a 2a 20 74 68 65 20 76 61 6c 75 65 20 6f   .** the value o
2d130 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72  f the fourth par
2d140 61 6d 65 74 65 72 20 74 68 65 6e 20 74 68 65 20  ameter then the 
2d150 72 65 73 75 6c 74 69 6e 67 20 73 74 72 69 6e 67  resulting string
2d160 20 76 61 6c 75 65 20 77 69 6c 6c 0a 2a 2a 20 63   value will.** c
2d170 6f 6e 74 61 69 6e 20 65 6d 62 65 64 64 65 64 20  ontain embedded 
2d180 4e 55 4c 73 2e 20 20 54 68 65 20 72 65 73 75 6c  NULs.  The resul
2d190 74 20 6f 66 20 65 78 70 72 65 73 73 69 6f 6e 73  t of expressions
2d1a0 20 69 6e 76 6f 6c 76 69 6e 67 20 73 74 72 69 6e   involving strin
2d1b0 67 73 0a 2a 2a 20 77 69 74 68 20 65 6d 62 65 64  gs.** with embed
2d1c0 64 65 64 20 4e 55 4c 73 20 69 73 20 75 6e 64 65  ded NULs is unde
2d1d0 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  fined..**.** ^Th
2d1e0 65 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74  e fifth argument
2d1f0 20 74 6f 20 74 68 65 20 42 4c 4f 42 20 61 6e 64   to the BLOB and
2d200 20 73 74 72 69 6e 67 20 62 69 6e 64 69 6e 67 20   string binding 
2d210 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 69 73  interfaces.** is
2d220 20 61 20 64 65 73 74 72 75 63 74 6f 72 20 75 73   a destructor us
2d230 65 64 20 74 6f 20 64 69 73 70 6f 73 65 20 6f 66  ed to dispose of
2d240 20 74 68 65 20 42 4c 4f 42 20 6f 72 0a 2a 2a 20   the BLOB or.** 
2d250 73 74 72 69 6e 67 20 61 66 74 65 72 20 53 51 4c  string after SQL
2d260 69 74 65 20 68 61 73 20 66 69 6e 69 73 68 65 64  ite has finished
2d270 20 77 69 74 68 20 69 74 2e 20 20 5e 54 68 65 20   with it.  ^The 
2d280 64 65 73 74 72 75 63 74 6f 72 20 69 73 20 63 61  destructor is ca
2d290 6c 6c 65 64 0a 2a 2a 20 74 6f 20 64 69 73 70 6f  lled.** to dispo
2d2a0 73 65 20 6f 66 20 74 68 65 20 42 4c 4f 42 20 6f  se of the BLOB o
2d2b0 72 20 73 74 72 69 6e 67 20 65 76 65 6e 20 69 66  r string even if
2d2c0 20 74 68 65 20 63 61 6c 6c 20 74 6f 20 62 69 6e   the call to bin
2d2d0 64 20 41 50 49 20 66 61 69 6c 73 2e 0a 2a 2a 20  d API fails..** 
2d2e0 5e 49 66 20 74 68 65 20 66 69 66 74 68 20 61 72  ^If the fifth ar
2d2f0 67 75 6d 65 6e 74 20 69 73 0a 2a 2a 20 74 68 65  gument is.** the
2d300 20 73 70 65 63 69 61 6c 20 76 61 6c 75 65 20 5b   special value [
2d310 53 51 4c 49 54 45 5f 53 54 41 54 49 43 5d 2c 20  SQLITE_STATIC], 
2d320 74 68 65 6e 20 53 51 4c 69 74 65 20 61 73 73 75  then SQLite assu
2d330 6d 65 73 20 74 68 61 74 20 74 68 65 0a 2a 2a 20  mes that the.** 
2d340 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 69  information is i
2d350 6e 20 73 74 61 74 69 63 2c 20 75 6e 6d 61 6e 61  n static, unmana
2d360 67 65 64 20 73 70 61 63 65 20 61 6e 64 20 64 6f  ged space and do
2d370 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62  es not need to b
2d380 65 20 66 72 65 65 64 2e 0a 2a 2a 20 5e 49 66 20  e freed..** ^If 
2d390 74 68 65 20 66 69 66 74 68 20 61 72 67 75 6d 65  the fifth argume
2d3a0 6e 74 20 68 61 73 20 74 68 65 20 76 61 6c 75 65  nt has the value
2d3b0 20 5b 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45   [SQLITE_TRANSIE
2d3c0 4e 54 5d 2c 20 74 68 65 6e 0a 2a 2a 20 53 51 4c  NT], then.** SQL
2d3d0 69 74 65 20 6d 61 6b 65 73 20 69 74 73 20 6f 77  ite makes its ow
2d3e0 6e 20 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f  n private copy o
2d3f0 66 20 74 68 65 20 64 61 74 61 20 69 6d 6d 65 64  f the data immed
2d400 69 61 74 65 6c 79 2c 20 62 65 66 6f 72 65 0a 2a  iately, before.*
2d410 2a 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69  * the sqlite3_bi
2d420 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 20 72  nd_*() routine r
2d430 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54  eturns..**.** ^T
2d440 68 65 20 73 69 78 74 68 20 61 72 67 75 6d 65 6e  he sixth argumen
2d450 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e  t to sqlite3_bin
2d460 64 5f 74 65 78 74 36 34 28 29 20 6d 75 73 74 20  d_text64() must 
2d470 62 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 5b 53 51  be one of.** [SQ
2d480 4c 49 54 45 5f 55 54 46 38 5d 2c 20 5b 53 51 4c  LITE_UTF8], [SQL
2d490 49 54 45 5f 55 54 46 31 36 5d 2c 20 5b 53 51 4c  ITE_UTF16], [SQL
2d4a0 49 54 45 5f 55 54 46 31 36 42 45 5d 2c 20 6f 72  ITE_UTF16BE], or
2d4b0 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45   [SQLITE_UTF16LE
2d4c0 5d 0a 2a 2a 20 74 6f 20 73 70 65 63 69 66 79 20  ].** to specify 
2d4d0 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 6f 66 20  the encoding of 
2d4e0 74 68 65 20 74 65 78 74 20 69 6e 20 74 68 65 20  the text in the 
2d4f0 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 2e  third parameter.
2d500 20 20 49 66 0a 2a 2a 20 74 68 65 20 73 69 78 74    If.** the sixt
2d510 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71  h argument to sq
2d520 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 36  lite3_bind_text6
2d530 34 28 29 20 69 73 20 6e 6f 74 20 6f 6e 65 20 6f  4() is not one o
2d540 66 20 74 68 65 0a 2a 2a 20 61 6c 6c 6f 77 65 64  f the.** allowed
2d550 20 76 61 6c 75 65 73 20 73 68 6f 77 6e 20 61 62   values shown ab
2d560 6f 76 65 2c 20 6f 72 20 69 66 20 74 68 65 20 74  ove, or if the t
2d570 65 78 74 20 65 6e 63 6f 64 69 6e 67 20 69 73 20  ext encoding is 
2d580 64 69 66 66 65 72 65 6e 74 0a 2a 2a 20 66 72 6f  different.** fro
2d590 6d 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 73  m the encoding s
2d5a0 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20  pecified by the 
2d5b0 73 69 78 74 68 20 70 61 72 61 6d 65 74 65 72 2c  sixth parameter,
2d5c0 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69   then the behavi
2d5d0 6f 72 0a 2a 2a 20 69 73 20 75 6e 64 65 66 69 6e  or.** is undefin
2d5e0 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ed..**.** ^The s
2d5f0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f  qlite3_bind_zero
2d600 62 6c 6f 62 28 29 20 72 6f 75 74 69 6e 65 20 62  blob() routine b
2d610 69 6e 64 73 20 61 20 42 4c 4f 42 20 6f 66 20 6c  inds a BLOB of l
2d620 65 6e 67 74 68 20 4e 20 74 68 61 74 0a 2a 2a 20  ength N that.** 
2d630 69 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20 7a  is filled with z
2d640 65 72 6f 65 73 2e 20 20 5e 41 20 7a 65 72 6f 62  eroes.  ^A zerob
2d650 6c 6f 62 20 75 73 65 73 20 61 20 66 69 78 65 64  lob uses a fixed
2d660 20 61 6d 6f 75 6e 74 20 6f 66 20 6d 65 6d 6f 72   amount of memor
2d670 79 0a 2a 2a 20 28 6a 75 73 74 20 61 6e 20 69 6e  y.** (just an in
2d680 74 65 67 65 72 20 74 6f 20 68 6f 6c 64 20 69 74  teger to hold it
2d690 73 20 73 69 7a 65 29 20 77 68 69 6c 65 20 69 74  s size) while it
2d6a0 20 69 73 20 62 65 69 6e 67 20 70 72 6f 63 65 73   is being proces
2d6b0 73 65 64 2e 0a 2a 2a 20 5a 65 72 6f 62 6c 6f 62  sed..** Zeroblob
2d6c0 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20 74  s are intended t
2d6d0 6f 20 73 65 72 76 65 20 61 73 20 70 6c 61 63 65  o serve as place
2d6e0 68 6f 6c 64 65 72 73 20 66 6f 72 20 42 4c 4f 42  holders for BLOB
2d6f0 73 20 77 68 6f 73 65 0a 2a 2a 20 63 6f 6e 74 65  s whose.** conte
2d700 6e 74 20 69 73 20 6c 61 74 65 72 20 77 72 69 74  nt is later writ
2d710 74 65 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71  ten using.** [sq
2d720 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 20  lite3_blob_open 
2d730 7c 20 69 6e 63 72 65 6d 65 6e 74 61 6c 20 42 4c  | incremental BL
2d740 4f 42 20 49 2f 4f 5d 20 72 6f 75 74 69 6e 65 73  OB I/O] routines
2d750 2e 0a 2a 2a 20 5e 41 20 6e 65 67 61 74 69 76 65  ..** ^A negative
2d760 20 76 61 6c 75 65 20 66 6f 72 20 74 68 65 20 7a   value for the z
2d770 65 72 6f 62 6c 6f 62 20 72 65 73 75 6c 74 73 20  eroblob results 
2d780 69 6e 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68  in a zero-length
2d790 20 42 4c 4f 42 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66   BLOB..**.** ^If
2d7a0 20 61 6e 79 20 6f 66 20 74 68 65 20 73 71 6c 69   any of the sqli
2d7b0 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75  te3_bind_*() rou
2d7c0 74 69 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64  tines are called
2d7d0 20 77 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69   with a NULL poi
2d7e0 6e 74 65 72 0a 2a 2a 20 66 6f 72 20 74 68 65 20  nter.** for the 
2d7f0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2d800 65 6e 74 5d 20 6f 72 20 77 69 74 68 20 61 20 70  ent] or with a p
2d810 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2d820 74 20 66 6f 72 20 77 68 69 63 68 0a 2a 2a 20 5b  t for which.** [
2d830 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
2d840 68 61 73 20 62 65 65 6e 20 63 61 6c 6c 65 64 20  has been called 
2d850 6d 6f 72 65 20 72 65 63 65 6e 74 6c 79 20 74 68  more recently th
2d860 61 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  an [sqlite3_rese
2d870 74 28 29 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74 68  t()],.** then th
2d880 65 20 63 61 6c 6c 20 77 69 6c 6c 20 72 65 74 75  e call will retu
2d890 72 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53  rn [SQLITE_MISUS
2d8a0 45 5d 2e 20 20 49 66 20 61 6e 79 20 73 71 6c 69  E].  If any sqli
2d8b0 74 65 33 5f 62 69 6e 64 5f 28 29 0a 2a 2a 20 72  te3_bind_().** r
2d8c0 6f 75 74 69 6e 65 20 69 73 20 70 61 73 73 65 64  outine is passed
2d8d0 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
2d8e0 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 68 61 73  tement] that has
2d8f0 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64 2c   been finalized,
2d900 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 69   the.** result i
2d910 73 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 20  s undefined and 
2d920 70 72 6f 62 61 62 6c 79 20 68 61 72 6d 66 75 6c  probably harmful
2d930 2e 0a 2a 2a 0a 2a 2a 20 5e 42 69 6e 64 69 6e 67  ..**.** ^Binding
2d940 73 20 61 72 65 20 6e 6f 74 20 63 6c 65 61 72 65  s are not cleare
2d950 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65  d by the [sqlite
2d960 33 5f 72 65 73 65 74 28 29 5d 20 72 6f 75 74 69  3_reset()] routi
2d970 6e 65 2e 0a 2a 2a 20 5e 55 6e 62 6f 75 6e 64 20  ne..** ^Unbound 
2d980 70 61 72 61 6d 65 74 65 72 73 20 61 72 65 20 69  parameters are i
2d990 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 4e 55  nterpreted as NU
2d9a0 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  LL..**.** ^The s
2d9b0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 20 72 6f  qlite3_bind_* ro
2d9c0 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 5b 53  utines return [S
2d9d0 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63  QLITE_OK] on suc
2d9e0 63 65 73 73 20 6f 72 20 61 6e 0a 2a 2a 20 5b 65  cess or an.** [e
2d9f0 72 72 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 6e  rror code] if an
2da00 79 74 68 69 6e 67 20 67 6f 65 73 20 77 72 6f 6e  ything goes wron
2da10 67 2e 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 54  g..** ^[SQLITE_T
2da20 4f 4f 42 49 47 5d 20 6d 69 67 68 74 20 62 65 20  OOBIG] might be 
2da30 72 65 74 75 72 6e 65 64 20 69 66 20 74 68 65 20  returned if the 
2da40 73 69 7a 65 20 6f 66 20 61 20 73 74 72 69 6e 67  size of a string
2da50 20 6f 72 20 42 4c 4f 42 0a 2a 2a 20 65 78 63 65   or BLOB.** exce
2da60 65 64 73 20 6c 69 6d 69 74 73 20 69 6d 70 6f 73  eds limits impos
2da70 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c  ed by [sqlite3_l
2da80 69 6d 69 74 5d 28 5b 53 51 4c 49 54 45 5f 4c 49  imit]([SQLITE_LI
2da90 4d 49 54 5f 4c 45 4e 47 54 48 5d 29 20 6f 72 0a  MIT_LENGTH]) or.
2daa0 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 41 58 5f 4c  ** [SQLITE_MAX_L
2dab0 45 4e 47 54 48 5d 2e 0a 2a 2a 20 5e 5b 53 51 4c  ENGTH]..** ^[SQL
2dac0 49 54 45 5f 52 41 4e 47 45 5d 20 69 73 20 72 65  ITE_RANGE] is re
2dad0 74 75 72 6e 65 64 20 69 66 20 74 68 65 20 70 61  turned if the pa
2dae0 72 61 6d 65 74 65 72 0a 2a 2a 20 69 6e 64 65 78  rameter.** index
2daf0 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65   is out of range
2db00 2e 20 20 5e 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45  .  ^[SQLITE_NOME
2db10 4d 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 69  M] is returned i
2db20 66 20 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 73  f malloc() fails
2db30 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
2db40 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  : [sqlite3_bind_
2db50 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28  parameter_count(
2db60 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  )],.** [sqlite3_
2db70 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e  bind_parameter_n
2db80 61 6d 65 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c  ame()], and [sql
2db90 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
2dba0 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f  ter_index()]..*/
2dbb0 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
2dbc0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
2dbd0 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  b(sqlite3_stmt*,
2dbe0 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64   int, const void
2dbf0 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f 69 64 28 2a  *, int n, void(*
2dc00 29 28 76 6f 69 64 2a 29 29 3b 0a 53 51 4c 49 54  )(void*));.SQLIT
2dc10 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
2dc20 33 5f 62 69 6e 64 5f 62 6c 6f 62 36 34 28 73 71  3_bind_blob64(sq
2dc30 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
2dc40 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 73  , const void*, s
2dc50 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 2c 0a 20  qlite3_uint64,. 
2dc60 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2dc70 20 20 20 20 20 20 20 76 6f 69 64 28 2a 29 28 76         void(*)(v
2dc80 6f 69 64 2a 29 29 3b 0a 53 51 4c 49 54 45 5f 41  oid*));.SQLITE_A
2dc90 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  PI int sqlite3_b
2dca0 69 6e 64 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74  ind_double(sqlit
2dcb0 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 64  e3_stmt*, int, d
2dcc0 6f 75 62 6c 65 29 3b 0a 53 51 4c 49 54 45 5f 41  ouble);.SQLITE_A
2dcd0 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  PI int sqlite3_b
2dce0 69 6e 64 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f  ind_int(sqlite3_
2dcf0 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 29  stmt*, int, int)
2dd00 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  ;.SQLITE_API int
2dd10 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 69 6e   sqlite3_bind_in
2dd20 74 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  t64(sqlite3_stmt
2dd30 2a 2c 20 69 6e 74 2c 20 73 71 6c 69 74 65 33 5f  *, int, sqlite3_
2dd40 69 6e 74 36 34 29 3b 0a 53 51 4c 49 54 45 5f 41  int64);.SQLITE_A
2dd50 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  PI int sqlite3_b
2dd60 69 6e 64 5f 6e 75 6c 6c 28 73 71 6c 69 74 65 33  ind_null(sqlite3
2dd70 5f 73 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a 53 51  _stmt*, int);.SQ
2dd80 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
2dd90 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 73  ite3_bind_text(s
2dda0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74  qlite3_stmt*,int
2ddb0 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 69 6e 74  ,const char*,int
2ddc0 2c 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29  ,void(*)(void*))
2ddd0 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  ;.SQLITE_API int
2dde0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65   sqlite3_bind_te
2ddf0 78 74 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d  xt16(sqlite3_stm
2de00 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76  t*, int, const v
2de10 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28  oid*, int, void(
2de20 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 53 51 4c 49  *)(void*));.SQLI
2de30 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
2de40 65 33 5f 62 69 6e 64 5f 74 65 78 74 36 34 28 73  e3_bind_text64(s
2de50 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
2de60 74 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20  t, const char*, 
2de70 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 2c 0a  sqlite3_uint64,.
2de80 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2de90 20 20 20 20 20 20 20 20 20 76 6f 69 64 28 2a 29           void(*)
2dea0 28 76 6f 69 64 2a 29 2c 20 75 6e 73 69 67 6e 65  (void*), unsigne
2deb0 64 20 63 68 61 72 20 65 6e 63 6f 64 69 6e 67 29  d char encoding)
2dec0 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  ;.SQLITE_API int
2ded0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61   sqlite3_bind_va
2dee0 6c 75 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  lue(sqlite3_stmt
2def0 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 73 71  *, int, const sq
2df00 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53  lite3_value*);.S
2df10 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
2df20 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62  lite3_bind_zerob
2df30 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  lob(sqlite3_stmt
2df40 2a 2c 20 69 6e 74 2c 20 69 6e 74 20 6e 29 3b 0a  *, int, int n);.
2df50 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
2df60 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f  qlite3_bind_zero
2df70 62 6c 6f 62 36 34 28 73 71 6c 69 74 65 33 5f 73  blob64(sqlite3_s
2df80 74 6d 74 2a 2c 20 69 6e 74 2c 20 73 71 6c 69 74  tmt*, int, sqlit
2df90 65 33 5f 75 69 6e 74 36 34 29 3b 0a 0a 2f 2a 0a  e3_uint64);../*.
2dfa0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d  ** CAPI3REF: Num
2dfb0 62 65 72 20 4f 66 20 53 51 4c 20 50 61 72 61 6d  ber Of SQL Param
2dfc0 65 74 65 72 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a  eters.** METHOD:
2dfd0 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a   sqlite3_stmt.**
2dfe0 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e  .** ^This routin
2dff0 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  e can be used to
2e000 20 66 69 6e 64 20 74 68 65 20 6e 75 6d 62 65 72   find the number
2e010 20 6f 66 20 5b 53 51 4c 20 70 61 72 61 6d 65 74   of [SQL paramet
2e020 65 72 73 5d 0a 2a 2a 20 69 6e 20 61 20 5b 70 72  ers].** in a [pr
2e030 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2e040 5d 2e 20 20 53 51 4c 20 70 61 72 61 6d 65 74 65  ].  SQL paramete
2e050 72 73 20 61 72 65 20 74 6f 6b 65 6e 73 20 6f 66  rs are tokens of
2e060 20 74 68 65 0a 2a 2a 20 66 6f 72 6d 20 22 3f 22   the.** form "?"
2e070 2c 20 22 3f 4e 4e 4e 22 2c 20 22 3a 41 41 41 22  , "?NNN", ":AAA"
2e080 2c 20 22 24 41 41 41 22 2c 20 6f 72 20 22 40 41  , "$AAA", or "@A
2e090 41 41 22 20 74 68 61 74 20 73 65 72 76 65 20 61  AA" that serve a
2e0a0 73 0a 2a 2a 20 70 6c 61 63 65 68 6f 6c 64 65 72  s.** placeholder
2e0b0 73 20 66 6f 72 20 76 61 6c 75 65 73 20 74 68 61  s for values tha
2e0c0 74 20 61 72 65 20 5b 73 71 6c 69 74 65 33 5f 62  t are [sqlite3_b
2e0d0 69 6e 64 5f 62 6c 6f 62 20 7c 20 62 6f 75 6e 64  ind_blob | bound
2e0e0 5d 0a 2a 2a 20 74 6f 20 74 68 65 20 70 61 72 61  ].** to the para
2e0f0 6d 65 74 65 72 73 20 61 74 20 61 20 6c 61 74 65  meters at a late
2e100 72 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28  r time..**.** ^(
2e110 54 68 69 73 20 72 6f 75 74 69 6e 65 20 61 63 74  This routine act
2e120 75 61 6c 6c 79 20 72 65 74 75 72 6e 73 20 74 68  ually returns th
2e130 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20 6c  e index of the l
2e140 61 72 67 65 73 74 20 28 72 69 67 68 74 6d 6f 73  argest (rightmos
2e150 74 29 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 2e  t).** parameter.
2e160 20 46 6f 72 20 61 6c 6c 20 66 6f 72 6d 73 20 65   For all forms e
2e170 78 63 65 70 74 20 3f 4e 4e 4e 2c 20 74 68 69 73  xcept ?NNN, this
2e180 20 77 69 6c 6c 20 63 6f 72 72 65 73 70 6f 6e 64   will correspond
2e190 20 74 6f 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65   to the.** numbe
2e1a0 72 20 6f 66 20 75 6e 69 71 75 65 20 70 61 72 61  r of unique para
2e1b0 6d 65 74 65 72 73 2e 20 20 49 66 20 70 61 72 61  meters.  If para
2e1c0 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20 3f 4e  meters of the ?N
2e1d0 4e 4e 20 66 6f 72 6d 20 61 72 65 20 75 73 65 64  NN form are used
2e1e0 2c 0a 2a 2a 20 74 68 65 72 65 20 6d 61 79 20 62  ,.** there may b
2e1f0 65 20 67 61 70 73 20 69 6e 20 74 68 65 20 6c 69  e gaps in the li
2e200 73 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  st.)^.**.** See 
2e210 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62  also: [sqlite3_b
2e220 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33  ind_blob|sqlite3
2e230 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71  _bind()],.** [sq
2e240 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
2e250 65 74 65 72 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e  eter_name()], an
2e260 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69  d.** [sqlite3_bi
2e270 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64  nd_parameter_ind
2e280 65 78 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45  ex()]..*/.SQLITE
2e290 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
2e2a0 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
2e2b0 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74  count(sqlite3_st
2e2c0 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  mt*);../*.** CAP
2e2d0 49 33 52 45 46 3a 20 4e 61 6d 65 20 4f 66 20 41  I3REF: Name Of A
2e2e0 20 48 6f 73 74 20 50 61 72 61 6d 65 74 65 72 0a   Host Parameter.
2e2f0 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
2e300 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54  e3_stmt.**.** ^T
2e310 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  he sqlite3_bind_
2e320 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 50  parameter_name(P
2e330 2c 4e 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  ,N) interface re
2e340 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 61 6d  turns.** the nam
2e350 65 20 6f 66 20 74 68 65 20 4e 2d 74 68 20 5b 53  e of the N-th [S
2e360 51 4c 20 70 61 72 61 6d 65 74 65 72 5d 20 69 6e  QL parameter] in
2e370 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
2e380 74 61 74 65 6d 65 6e 74 5d 20 50 2e 0a 2a 2a 20  tatement] P..** 
2e390 5e 28 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73  ^(SQL parameters
2e3a0 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 3f 4e   of the form "?N
2e3b0 4e 4e 22 20 6f 72 20 22 3a 41 41 41 22 20 6f 72  NN" or ":AAA" or
2e3c0 20 22 40 41 41 41 22 20 6f 72 20 22 24 41 41 41   "@AAA" or "$AAA
2e3d0 22 0a 2a 2a 20 68 61 76 65 20 61 20 6e 61 6d 65  ".** have a name
2e3e0 20 77 68 69 63 68 20 69 73 20 74 68 65 20 73 74   which is the st
2e3f0 72 69 6e 67 20 22 3f 4e 4e 4e 22 20 6f 72 20 22  ring "?NNN" or "
2e400 3a 41 41 41 22 20 6f 72 20 22 40 41 41 41 22 20  :AAA" or "@AAA" 
2e410 6f 72 20 22 24 41 41 41 22 0a 2a 2a 20 72 65 73  or "$AAA".** res
2e420 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 49 6e  pectively..** In
2e430 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68   other words, th
2e440 65 20 69 6e 69 74 69 61 6c 20 22 3a 22 20 6f 72  e initial ":" or
2e450 20 22 24 22 20 6f 72 20 22 40 22 20 6f 72 20 22   "$" or "@" or "
2e460 3f 22 0a 2a 2a 20 69 73 20 69 6e 63 6c 75 64 65  ?".** is include
2e470 64 20 61 73 20 70 61 72 74 20 6f 66 20 74 68 65  d as part of the
2e480 20 6e 61 6d 65 2e 29 5e 0a 2a 2a 20 5e 50 61 72   name.)^.** ^Par
2e490 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20 66  ameters of the f
2e4a0 6f 72 6d 20 22 3f 22 20 77 69 74 68 6f 75 74 20  orm "?" without 
2e4b0 61 20 66 6f 6c 6c 6f 77 69 6e 67 20 69 6e 74 65  a following inte
2e4c0 67 65 72 20 68 61 76 65 20 6e 6f 20 6e 61 6d 65  ger have no name
2e4d0 0a 2a 2a 20 61 6e 64 20 61 72 65 20 72 65 66 65  .** and are refe
2e4e0 72 72 65 64 20 74 6f 20 61 73 20 22 6e 61 6d 65  rred to as "name
2e4f0 6c 65 73 73 22 20 6f 72 20 22 61 6e 6f 6e 79 6d  less" or "anonym
2e500 6f 75 73 20 70 61 72 61 6d 65 74 65 72 73 22 2e  ous parameters".
2e510 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73  .**.** ^The firs
2e520 74 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72  t host parameter
2e530 20 68 61 73 20 61 6e 20 69 6e 64 65 78 20 6f 66   has an index of
2e540 20 31 2c 20 6e 6f 74 20 30 2e 0a 2a 2a 0a 2a 2a   1, not 0..**.**
2e550 20 5e 49 66 20 74 68 65 20 76 61 6c 75 65 20 4e   ^If the value N
2e560 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65   is out of range
2e570 20 6f 72 20 69 66 20 74 68 65 20 4e 2d 74 68 20   or if the N-th 
2e580 70 61 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20  parameter is.** 
2e590 6e 61 6d 65 6c 65 73 73 2c 20 74 68 65 6e 20 4e  nameless, then N
2e5a0 55 4c 4c 20 69 73 20 72 65 74 75 72 6e 65 64 2e  ULL is returned.
2e5b0 20 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20    ^The returned 
2e5c0 73 74 72 69 6e 67 20 69 73 0a 2a 2a 20 61 6c 77  string is.** alw
2e5d0 61 79 73 20 69 6e 20 55 54 46 2d 38 20 65 6e 63  ays in UTF-8 enc
2e5e0 6f 64 69 6e 67 20 65 76 65 6e 20 69 66 20 74 68  oding even if th
2e5f0 65 20 6e 61 6d 65 64 20 70 61 72 61 6d 65 74 65  e named paramete
2e600 72 20 77 61 73 0a 2a 2a 20 6f 72 69 67 69 6e 61  r was.** origina
2e610 6c 6c 79 20 73 70 65 63 69 66 69 65 64 20 61 73  lly specified as
2e620 20 55 54 46 2d 31 36 20 69 6e 20 5b 73 71 6c 69   UTF-16 in [sqli
2e630 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d  te3_prepare16()]
2e640 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   or.** [sqlite3_
2e650 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e  prepare16_v2()].
2e660 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a  .**.** See also:
2e670 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62   [sqlite3_bind_b
2e680 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64  lob|sqlite3_bind
2e690 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ()],.** [sqlite3
2e6a0 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
2e6b0 63 6f 75 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a  count()], and.**
2e6c0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
2e6d0 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29  arameter_index()
2e6e0 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  ]..*/.SQLITE_API
2e6f0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c   const char *sql
2e700 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
2e710 74 65 72 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33  ter_name(sqlite3
2e720 5f 73 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a 0a 2f  _stmt*, int);../
2e730 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49  *.** CAPI3REF: I
2e740 6e 64 65 78 20 4f 66 20 41 20 50 61 72 61 6d 65  ndex Of A Parame
2e750 74 65 72 20 57 69 74 68 20 41 20 47 69 76 65 6e  ter With A Given
2e760 20 4e 61 6d 65 0a 2a 2a 20 4d 45 54 48 4f 44 3a   Name.** METHOD:
2e770 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a   sqlite3_stmt.**
2e780 0a 2a 2a 20 5e 52 65 74 75 72 6e 20 74 68 65 20  .** ^Return the 
2e790 69 6e 64 65 78 20 6f 66 20 61 6e 20 53 51 4c 20  index of an SQL 
2e7a0 70 61 72 61 6d 65 74 65 72 20 67 69 76 65 6e 20  parameter given 
2e7b0 69 74 73 20 6e 61 6d 65 2e 20 20 5e 54 68 65 0a  its name.  ^The.
2e7c0 2a 2a 20 69 6e 64 65 78 20 76 61 6c 75 65 20 72  ** index value r
2e7d0 65 74 75 72 6e 65 64 20 69 73 20 73 75 69 74 61  eturned is suita
2e7e0 62 6c 65 20 66 6f 72 20 75 73 65 20 61 73 20 74  ble for use as t
2e7f0 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 70 61 72  he second.** par
2e800 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74  ameter to [sqlit
2e810 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c  e3_bind_blob|sql
2e820 69 74 65 33 5f 62 69 6e 64 28 29 5d 2e 20 20 5e  ite3_bind()].  ^
2e830 41 20 7a 65 72 6f 0a 2a 2a 20 69 73 20 72 65 74  A zero.** is ret
2e840 75 72 6e 65 64 20 69 66 20 6e 6f 20 6d 61 74 63  urned if no matc
2e850 68 69 6e 67 20 70 61 72 61 6d 65 74 65 72 20 69  hing parameter i
2e860 73 20 66 6f 75 6e 64 2e 20 20 5e 54 68 65 20 70  s found.  ^The p
2e870 61 72 61 6d 65 74 65 72 0a 2a 2a 20 6e 61 6d 65  arameter.** name
2e880 20 6d 75 73 74 20 62 65 20 67 69 76 65 6e 20 69   must be given i
2e890 6e 20 55 54 46 2d 38 20 65 76 65 6e 20 69 66 20  n UTF-8 even if 
2e8a0 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 73 74 61  the original sta
2e8b0 74 65 6d 65 6e 74 0a 2a 2a 20 77 61 73 20 70 72  tement.** was pr
2e8c0 65 70 61 72 65 64 20 66 72 6f 6d 20 55 54 46 2d  epared from UTF-
2e8d0 31 36 20 74 65 78 74 20 75 73 69 6e 67 20 5b 73  16 text using [s
2e8e0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
2e8f0 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65  _v2()]..**.** Se
2e900 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33  e also: [sqlite3
2e910 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74  _bind_blob|sqlit
2e920 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b  e3_bind()],.** [
2e930 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
2e940 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c  ameter_count()],
2e950 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   and.** [sqlite3
2e960 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
2e970 6e 61 6d 65 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49  name()]..*/.SQLI
2e980 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
2e990 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
2e9a0 72 5f 69 6e 64 65 78 28 73 71 6c 69 74 65 33 5f  r_index(sqlite3_
2e9b0 73 74 6d 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61  stmt*, const cha
2e9c0 72 20 2a 7a 4e 61 6d 65 29 3b 0a 0a 2f 2a 0a 2a  r *zName);../*.*
2e9d0 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 65  * CAPI3REF: Rese
2e9e0 74 20 41 6c 6c 20 42 69 6e 64 69 6e 67 73 20 4f  t All Bindings O
2e9f0 6e 20 41 20 50 72 65 70 61 72 65 64 20 53 74 61  n A Prepared Sta
2ea00 74 65 6d 65 6e 74 0a 2a 2a 20 4d 45 54 48 4f 44  tement.** METHOD
2ea10 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a  : sqlite3_stmt.*
2ea20 2a 0a 2a 2a 20 5e 43 6f 6e 74 72 61 72 79 20 74  *.** ^Contrary t
2ea30 6f 20 74 68 65 20 69 6e 74 75 69 74 69 6f 6e 20  o the intuition 
2ea40 6f 66 20 6d 61 6e 79 2c 20 5b 73 71 6c 69 74 65  of many, [sqlite
2ea50 33 5f 72 65 73 65 74 28 29 5d 20 64 6f 65 73 20  3_reset()] does 
2ea60 6e 6f 74 20 72 65 73 65 74 0a 2a 2a 20 74 68 65  not reset.** the
2ea70 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62   [sqlite3_bind_b
2ea80 6c 6f 62 20 7c 20 62 69 6e 64 69 6e 67 73 5d 20  lob | bindings] 
2ea90 6f 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  on a [prepared s
2eaa0 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 55  tatement]..** ^U
2eab0 73 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  se this routine 
2eac0 74 6f 20 72 65 73 65 74 20 61 6c 6c 20 68 6f 73  to reset all hos
2ead0 74 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20  t parameters to 
2eae0 4e 55 4c 4c 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  NULL..*/.SQLITE_
2eaf0 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
2eb00 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73 28 73  clear_bindings(s
2eb10 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a  qlite3_stmt*);..
2eb20 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
2eb30 4e 75 6d 62 65 72 20 4f 66 20 43 6f 6c 75 6d 6e  Number Of Column
2eb40 73 20 49 6e 20 41 20 52 65 73 75 6c 74 20 53 65  s In A Result Se
2eb50 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  t.** METHOD: sql
2eb60 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20  ite3_stmt.**.** 
2eb70 5e 52 65 74 75 72 6e 20 74 68 65 20 6e 75 6d 62  ^Return the numb
2eb80 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e  er of columns in
2eb90 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20   the result set 
2eba0 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 0a  returned by the.
2ebb0 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  ** [prepared sta
2ebc0 74 65 6d 65 6e 74 5d 2e 20 5e 54 68 69 73 20 72  tement]. ^This r
2ebd0 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 30  outine returns 0
2ebe0 20 69 66 20 70 53 74 6d 74 20 69 73 20 61 6e 20   if pStmt is an 
2ebf0 53 51 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74  SQL.** statement
2ec00 20 74 68 61 74 20 64 6f 65 73 20 6e 6f 74 20 72   that does not r
2ec10 65 74 75 72 6e 20 64 61 74 61 20 28 66 6f 72 20  eturn data (for 
2ec20 65 78 61 6d 70 6c 65 20 61 6e 20 5b 55 50 44 41  example an [UPDA
2ec30 54 45 5d 29 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  TE])..**.** See 
2ec40 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 64  also: [sqlite3_d
2ec50 61 74 61 5f 63 6f 75 6e 74 28 29 5d 0a 2a 2f 0a  ata_count()].*/.
2ec60 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
2ec70 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f  qlite3_column_co
2ec80 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  unt(sqlite3_stmt
2ec90 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a   *pStmt);../*.**
2eca0 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6c 75 6d   CAPI3REF: Colum
2ecb0 6e 20 4e 61 6d 65 73 20 49 6e 20 41 20 52 65 73  n Names In A Res
2ecc0 75 6c 74 20 53 65 74 0a 2a 2a 20 4d 45 54 48 4f  ult Set.** METHO
2ecd0 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a  D: sqlite3_stmt.
2ece0 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75  **.** ^These rou
2ecf0 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65  tines return the
2ed00 20 6e 61 6d 65 20 61 73 73 69 67 6e 65 64 20 74   name assigned t
2ed10 6f 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 63  o a particular c
2ed20 6f 6c 75 6d 6e 0a 2a 2a 20 69 6e 20 74 68 65 20  olumn.** in the 
2ed30 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 61 20  result set of a 
2ed40 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65  [SELECT] stateme
2ed50 6e 74 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65  nt.  ^The sqlite
2ed60 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 0a  3_column_name().
2ed70 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  ** interface ret
2ed80 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
2ed90 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  o a zero-termina
2eda0 74 65 64 20 55 54 46 2d 38 20 73 74 72 69 6e 67  ted UTF-8 string
2edb0 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  .** and sqlite3_
2edc0 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 20  column_name16() 
2edd0 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65  returns a pointe
2ede0 72 20 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d  r to a zero-term
2edf0 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d 31 36  inated.** UTF-16
2ee00 20 73 74 72 69 6e 67 2e 20 20 5e 54 68 65 20 66   string.  ^The f
2ee10 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69  irst parameter i
2ee20 73 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20  s the [prepared 
2ee30 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 74 68  statement].** th
2ee40 61 74 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68  at implements th
2ee50 65 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65  e [SELECT] state
2ee60 6d 65 6e 74 2e 20 5e 54 68 65 20 73 65 63 6f 6e  ment. ^The secon
2ee70 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74  d parameter is t
2ee80 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 6e 75 6d  he.** column num
2ee90 62 65 72 2e 20 20 5e 54 68 65 20 6c 65 66 74 6d  ber.  ^The leftm
2eea0 6f 73 74 20 63 6f 6c 75 6d 6e 20 69 73 20 6e 75  ost column is nu
2eeb0 6d 62 65 72 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e 54  mber 0..**.** ^T
2eec0 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 69  he returned stri
2eed0 6e 67 20 70 6f 69 6e 74 65 72 20 69 73 20 76 61  ng pointer is va
2eee0 6c 69 64 20 75 6e 74 69 6c 20 65 69 74 68 65 72  lid until either
2eef0 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
2ef00 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 69 73 20  tatement].** is 
2ef10 64 65 73 74 72 6f 79 65 64 20 62 79 20 5b 73 71  destroyed by [sq
2ef20 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
2ef30 5d 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 73  ] or until the s
2ef40 74 61 74 65 6d 65 6e 74 20 69 73 20 61 75 74 6f  tatement is auto
2ef50 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 72 65 70  matically.** rep
2ef60 72 65 70 61 72 65 64 20 62 79 20 74 68 65 20 66  repared by the f
2ef70 69 72 73 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71  irst call to [sq
2ef80 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 66 6f  lite3_step()] fo
2ef90 72 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 72  r a particular r
2efa0 75 6e 0a 2a 2a 20 6f 72 20 75 6e 74 69 6c 20 74  un.** or until t
2efb0 68 65 20 6e 65 78 74 20 63 61 6c 6c 20 74 6f 0a  he next call to.
2efc0 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  ** sqlite3_colum
2efd0 6e 5f 6e 61 6d 65 28 29 20 6f 72 20 73 71 6c 69  n_name() or sqli
2efe0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31  te3_column_name1
2eff0 36 28 29 20 6f 6e 20 74 68 65 20 73 61 6d 65 20  6() on the same 
2f000 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49  column..**.** ^I
2f010 66 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  f sqlite3_malloc
2f020 28 29 20 66 61 69 6c 73 20 64 75 72 69 6e 67 20  () fails during 
2f030 74 68 65 20 70 72 6f 63 65 73 73 69 6e 67 20 6f  the processing o
2f040 66 20 65 69 74 68 65 72 20 72 6f 75 74 69 6e 65  f either routine
2f050 0a 2a 2a 20 28 66 6f 72 20 65 78 61 6d 70 6c 65  .** (for example
2f060 20 64 75 72 69 6e 67 20 61 20 63 6f 6e 76 65 72   during a conver
2f070 73 69 6f 6e 20 66 72 6f 6d 20 55 54 46 2d 38 20  sion from UTF-8 
2f080 74 6f 20 55 54 46 2d 31 36 29 20 74 68 65 6e 20  to UTF-16) then 
2f090 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  a.** NULL pointe
2f0a0 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a  r is returned..*
2f0b0 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f  *.** ^The name o
2f0c0 66 20 61 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d  f a result colum
2f0d0 6e 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f  n is the value o
2f0e0 66 20 74 68 65 20 22 41 53 22 20 63 6c 61 75 73  f the "AS" claus
2f0f0 65 20 66 6f 72 0a 2a 2a 20 74 68 61 74 20 63 6f  e for.** that co
2f100 6c 75 6d 6e 2c 20 69 66 20 74 68 65 72 65 20 69  lumn, if there i
2f110 73 20 61 6e 20 41 53 20 63 6c 61 75 73 65 2e 20  s an AS clause. 
2f120 20 49 66 20 74 68 65 72 65 20 69 73 20 6e 6f 20   If there is no 
2f130 41 53 20 63 6c 61 75 73 65 0a 2a 2a 20 74 68 65  AS clause.** the
2f140 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  n the name of th
2f150 65 20 63 6f 6c 75 6d 6e 20 69 73 20 75 6e 73 70  e column is unsp
2f160 65 63 69 66 69 65 64 20 61 6e 64 20 6d 61 79 20  ecified and may 
2f170 63 68 61 6e 67 65 20 66 72 6f 6d 0a 2a 2a 20 6f  change from.** o
2f180 6e 65 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51  ne release of SQ
2f190 4c 69 74 65 20 74 6f 20 74 68 65 20 6e 65 78 74  Lite to the next
2f1a0 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
2f1b0 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69  const char *sqli
2f1c0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28  te3_column_name(
2f1d0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
2f1e0 6e 74 20 4e 29 3b 0a 53 51 4c 49 54 45 5f 41 50  nt N);.SQLITE_AP
2f1f0 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  I const void *sq
2f200 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d  lite3_column_nam
2f210 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  e16(sqlite3_stmt
2f220 2a 2c 20 69 6e 74 20 4e 29 3b 0a 0a 2f 2a 0a 2a  *, int N);../*.*
2f230 2a 20 43 41 50 49 33 52 45 46 3a 20 53 6f 75 72  * CAPI3REF: Sour
2f240 63 65 20 4f 66 20 44 61 74 61 20 49 6e 20 41 20  ce Of Data In A 
2f250 51 75 65 72 79 20 52 65 73 75 6c 74 0a 2a 2a 20  Query Result.** 
2f260 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f  METHOD: sqlite3_
2f270 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73  stmt.**.** ^Thes
2f280 65 20 72 6f 75 74 69 6e 65 73 20 70 72 6f 76 69  e routines provi
2f290 64 65 20 61 20 6d 65 61 6e 73 20 74 6f 20 64 65  de a means to de
2f2a0 74 65 72 6d 69 6e 65 20 74 68 65 20 64 61 74 61  termine the data
2f2b0 62 61 73 65 2c 20 74 61 62 6c 65 2c 20 61 6e 64  base, table, and
2f2c0 0a 2a 2a 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e  .** table column
2f2d0 20 74 68 61 74 20 69 73 20 74 68 65 20 6f 72 69   that is the ori
2f2e0 67 69 6e 20 6f 66 20 61 20 70 61 72 74 69 63 75  gin of a particu
2f2f0 6c 61 72 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d  lar result colum
2f300 6e 20 69 6e 0a 2a 2a 20 5b 53 45 4c 45 43 54 5d  n in.** [SELECT]
2f310 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 5e   statement..** ^
2f320 54 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  The name of the 
2f330 64 61 74 61 62 61 73 65 20 6f 72 20 74 61 62 6c  database or tabl
2f340 65 20 6f 72 20 63 6f 6c 75 6d 6e 20 63 61 6e 20  e or column can 
2f350 62 65 20 72 65 74 75 72 6e 65 64 20 61 73 0a 2a  be returned as.*
2f360 2a 20 65 69 74 68 65 72 20 61 20 55 54 46 2d 38  * either a UTF-8
2f370 20 6f 72 20 55 54 46 2d 31 36 20 73 74 72 69 6e   or UTF-16 strin
2f380 67 2e 20 20 5e 54 68 65 20 5f 64 61 74 61 62 61  g.  ^The _databa
2f390 73 65 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74  se_ routines ret
2f3a0 75 72 6e 0a 2a 2a 20 74 68 65 20 64 61 74 61 62  urn.** the datab
2f3b0 61 73 65 20 6e 61 6d 65 2c 20 74 68 65 20 5f 74  ase name, the _t
2f3c0 61 62 6c 65 5f 20 72 6f 75 74 69 6e 65 73 20 72  able_ routines r
2f3d0 65 74 75 72 6e 20 74 68 65 20 74 61 62 6c 65 20  eturn the table 
2f3e0 6e 61 6d 65 2c 20 61 6e 64 0a 2a 2a 20 74 68 65  name, and.** the
2f3f0 20 6f 72 69 67 69 6e 5f 20 72 6f 75 74 69 6e 65   origin_ routine
2f400 73 20 72 65 74 75 72 6e 20 74 68 65 20 63 6f 6c  s return the col
2f410 75 6d 6e 20 6e 61 6d 65 2e 0a 2a 2a 20 5e 54 68  umn name..** ^Th
2f420 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e  e returned strin
2f430 67 20 69 73 20 76 61 6c 69 64 20 75 6e 74 69 6c  g is valid until
2f440 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
2f450 74 61 74 65 6d 65 6e 74 5d 20 69 73 20 64 65 73  tatement] is des
2f460 74 72 6f 79 65 64 0a 2a 2a 20 75 73 69 6e 67 20  troyed.** using 
2f470 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
2f480 65 28 29 5d 20 6f 72 20 75 6e 74 69 6c 20 74 68  e()] or until th
2f490 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61  e statement is a
2f4a0 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20  utomatically.** 
2f4b0 72 65 70 72 65 70 61 72 65 64 20 62 79 20 74 68  reprepared by th
2f4c0 65 20 66 69 72 73 74 20 63 61 6c 6c 20 74 6f 20  e first call to 
2f4d0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
2f4e0 20 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61   for a particula
2f4f0 72 20 72 75 6e 0a 2a 2a 20 6f 72 20 75 6e 74 69  r run.** or unti
2f500 6c 20 74 68 65 20 73 61 6d 65 20 69 6e 66 6f 72  l the same infor
2f510 6d 61 74 69 6f 6e 20 69 73 20 72 65 71 75 65 73  mation is reques
2f520 74 65 64 0a 2a 2a 20 61 67 61 69 6e 20 69 6e 20  ted.** again in 
2f530 61 20 64 69 66 66 65 72 65 6e 74 20 65 6e 63 6f  a different enco
2f540 64 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ding..**.** ^The
2f550 20 6e 61 6d 65 73 20 72 65 74 75 72 6e 65 64 20   names returned 
2f560 61 72 65 20 74 68 65 20 6f 72 69 67 69 6e 61 6c  are the original
2f570 20 75 6e 2d 61 6c 69 61 73 65 64 20 6e 61 6d 65   un-aliased name
2f580 73 20 6f 66 20 74 68 65 0a 2a 2a 20 64 61 74 61  s of the.** data
2f590 62 61 73 65 2c 20 74 61 62 6c 65 2c 20 61 6e 64  base, table, and
2f5a0 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e   column..**.** ^
2f5b0 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
2f5c0 6e 74 20 74 6f 20 74 68 65 73 65 20 69 6e 74 65  nt to these inte
2f5d0 72 66 61 63 65 73 20 69 73 20 61 20 5b 70 72 65  rfaces is a [pre
2f5e0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2f5f0 2e 0a 2a 2a 20 5e 54 68 65 73 65 20 66 75 6e 63  ..** ^These func
2f600 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 69 6e 66  tions return inf
2f610 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 74  ormation about t
2f620 68 65 20 4e 74 68 20 72 65 73 75 6c 74 20 63 6f  he Nth result co
2f630 6c 75 6d 6e 20 72 65 74 75 72 6e 65 64 20 62 79  lumn returned by
2f640 0a 2a 2a 20 74 68 65 20 73 74 61 74 65 6d 65 6e  .** the statemen
2f650 74 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74 68  t, where N is th
2f660 65 20 73 65 63 6f 6e 64 20 66 75 6e 63 74 69 6f  e second functio
2f670 6e 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e  n argument..** ^
2f680 54 68 65 20 6c 65 66 74 2d 6d 6f 73 74 20 63 6f  The left-most co
2f690 6c 75 6d 6e 20 69 73 20 63 6f 6c 75 6d 6e 20 30  lumn is column 0
2f6a0 20 66 6f 72 20 74 68 65 73 65 20 72 6f 75 74 69   for these routi
2f6b0 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  nes..**.** ^If t
2f6c0 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 72 65  he Nth column re
2f6d0 74 75 72 6e 65 64 20 62 79 20 74 68 65 20 73 74  turned by the st
2f6e0 61 74 65 6d 65 6e 74 20 69 73 20 61 6e 20 65 78  atement is an ex
2f6f0 70 72 65 73 73 69 6f 6e 20 6f 72 0a 2a 2a 20 73  pression or.** s
2f700 75 62 71 75 65 72 79 20 61 6e 64 20 69 73 20 6e  ubquery and is n
2f710 6f 74 20 61 20 63 6f 6c 75 6d 6e 20 76 61 6c 75  ot a column valu
2f720 65 2c 20 74 68 65 6e 20 61 6c 6c 20 6f 66 20 74  e, then all of t
2f730 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 72  hese functions r
2f740 65 74 75 72 6e 0a 2a 2a 20 4e 55 4c 4c 2e 20 20  eturn.** NULL.  
2f750 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 20 6d  ^These routine m
2f760 69 67 68 74 20 61 6c 73 6f 20 72 65 74 75 72 6e  ight also return
2f770 20 4e 55 4c 4c 20 69 66 20 61 20 6d 65 6d 6f 72   NULL if a memor
2f780 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72  y allocation err
2f790 6f 72 0a 2a 2a 20 6f 63 63 75 72 73 2e 20 20 5e  or.** occurs.  ^
2f7a0 4f 74 68 65 72 77 69 73 65 2c 20 74 68 65 79 20  Otherwise, they 
2f7b0 72 65 74 75 72 6e 20 74 68 65 20 6e 61 6d 65 20  return the name 
2f7c0 6f 66 20 74 68 65 20 61 74 74 61 63 68 65 64 20  of the attached 
2f7d0 64 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65 2c  database, table,
2f7e0 0a 2a 2a 20 6f 72 20 63 6f 6c 75 6d 6e 20 74 68  .** or column th
2f7f0 61 74 20 71 75 65 72 79 20 72 65 73 75 6c 74 20  at query result 
2f800 63 6f 6c 75 6d 6e 20 77 61 73 20 65 78 74 72 61  column was extra
2f810 63 74 65 64 20 66 72 6f 6d 2e 0a 2a 2a 0a 2a 2a  cted from..**.**
2f820 20 5e 41 73 20 77 69 74 68 20 61 6c 6c 20 6f 74   ^As with all ot
2f830 68 65 72 20 53 51 4c 69 74 65 20 41 50 49 73 2c  her SQLite APIs,
2f840 20 74 68 6f 73 65 20 77 68 6f 73 65 20 6e 61 6d   those whose nam
2f850 65 73 20 65 6e 64 20 77 69 74 68 20 22 31 36 22  es end with "16"
2f860 20 72 65 74 75 72 6e 0a 2a 2a 20 55 54 46 2d 31   return.** UTF-1
2f870 36 20 65 6e 63 6f 64 65 64 20 73 74 72 69 6e 67  6 encoded string
2f880 73 20 61 6e 64 20 74 68 65 20 6f 74 68 65 72 20  s and the other 
2f890 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e  functions return
2f8a0 20 55 54 46 2d 38 2e 0a 2a 2a 0a 2a 2a 20 5e 54   UTF-8..**.** ^T
2f8b0 68 65 73 65 20 41 50 49 73 20 61 72 65 20 6f 6e  hese APIs are on
2f8c0 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 69 66 20  ly available if 
2f8d0 74 68 65 20 6c 69 62 72 61 72 79 20 77 61 73 20  the library was 
2f8e0 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68  compiled with th
2f8f0 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41  e.** [SQLITE_ENA
2f900 42 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d 45 54 41 44  BLE_COLUMN_METAD
2f910 41 54 41 5d 20 43 2d 70 72 65 70 72 6f 63 65 73  ATA] C-preproces
2f920 73 6f 72 20 73 79 6d 62 6f 6c 2e 0a 2a 2a 0a 2a  sor symbol..**.*
2f930 2a 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65  * If two or more
2f940 20 74 68 72 65 61 64 73 20 63 61 6c 6c 20 6f 6e   threads call on
2f950 65 20 6f 72 20 6d 6f 72 65 20 6f 66 20 74 68 65  e or more of the
2f960 73 65 20 72 6f 75 74 69 6e 65 73 20 61 67 61 69  se routines agai
2f970 6e 73 74 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20  nst the same.** 
2f980 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2f990 6e 74 20 61 6e 64 20 63 6f 6c 75 6d 6e 20 61 74  nt and column at
2f9a0 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 20 74   the same time t
2f9b0 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20  hen the results 
2f9c0 61 72 65 0a 2a 2a 20 75 6e 64 65 66 69 6e 65 64  are.** undefined
2f9d0 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 77 6f 20 6f  ..**.** If two o
2f9e0 72 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20 63  r more threads c
2f9f0 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a  all one or more.
2fa00 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ** [sqlite3_colu
2fa10 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65  mn_database_name
2fa20 20 7c 20 63 6f 6c 75 6d 6e 20 6d 65 74 61 64 61   | column metada
2fa30 74 61 20 69 6e 74 65 72 66 61 63 65 73 5d 0a 2a  ta interfaces].*
2fa40 2a 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20 5b  * for the same [
2fa50 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2fa60 6e 74 5d 20 61 6e 64 20 72 65 73 75 6c 74 20 63  nt] and result c
2fa70 6f 6c 75 6d 6e 0a 2a 2a 20 61 74 20 74 68 65 20  olumn.** at the 
2fa80 73 61 6d 65 20 74 69 6d 65 20 74 68 65 6e 20 74  same time then t
2fa90 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 75  he results are u
2faa0 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 53 51 4c  ndefined..*/.SQL
2fab0 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68  ITE_API const ch
2fac0 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ar *sqlite3_colu
2fad0 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65  mn_database_name
2fae0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69  (sqlite3_stmt*,i
2faf0 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  nt);.SQLITE_API 
2fb00 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
2fb10 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62  te3_column_datab
2fb20 61 73 65 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74  ase_name16(sqlit
2fb30 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 53  e3_stmt*,int);.S
2fb40 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20  QLITE_API const 
2fb50 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f  char *sqlite3_co
2fb60 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 28  lumn_table_name(
2fb70 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e  sqlite3_stmt*,in
2fb80 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63  t);.SQLITE_API c
2fb90 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
2fba0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f  e3_column_table_
2fbb0 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73  name16(sqlite3_s
2fbc0 74 6d 74 2a 2c 69 6e 74 29 3b 0a 53 51 4c 49 54  tmt*,int);.SQLIT
2fbd0 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72  E_API const char
2fbe0 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
2fbf0 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 28 73 71 6c  _origin_name(sql
2fc00 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b  ite3_stmt*,int);
2fc10 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73  .SQLITE_API cons
2fc20 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
2fc30 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61  column_origin_na
2fc40 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d  me16(sqlite3_stm
2fc50 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  t*,int);../*.** 
2fc60 43 41 50 49 33 52 45 46 3a 20 44 65 63 6c 61 72  CAPI3REF: Declar
2fc70 65 64 20 44 61 74 61 74 79 70 65 20 4f 66 20 41  ed Datatype Of A
2fc80 20 51 75 65 72 79 20 52 65 73 75 6c 74 0a 2a 2a   Query Result.**
2fc90 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
2fca0 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  _stmt.**.** ^(Th
2fcb0 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
2fcc0 72 20 69 73 20 61 20 5b 70 72 65 70 61 72 65 64  r is a [prepared
2fcd0 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20   statement]..** 
2fce0 49 66 20 74 68 69 73 20 73 74 61 74 65 6d 65 6e  If this statemen
2fcf0 74 20 69 73 20 61 20 5b 53 45 4c 45 43 54 5d 20  t is a [SELECT] 
2fd00 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 74 68  statement and th
2fd10 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20  e Nth column of 
2fd20 74 68 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20  the.** returned 
2fd30 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 74 68  result set of th
2fd40 61 74 20 5b 53 45 4c 45 43 54 5d 20 69 73 20 61  at [SELECT] is a
2fd50 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 28 6e   table column (n
2fd60 6f 74 20 61 6e 0a 2a 2a 20 65 78 70 72 65 73 73  ot an.** express
2fd70 69 6f 6e 20 6f 72 20 73 75 62 71 75 65 72 79 29  ion or subquery)
2fd80 20 74 68 65 6e 20 74 68 65 20 64 65 63 6c 61 72   then the declar
2fd90 65 64 20 74 79 70 65 20 6f 66 20 74 68 65 20 74  ed type of the t
2fda0 61 62 6c 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69  able.** column i
2fdb0 73 20 72 65 74 75 72 6e 65 64 2e 29 5e 20 20 5e  s returned.)^  ^
2fdc0 49 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d  If the Nth colum
2fdd0 6e 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20  n of the result 
2fde0 73 65 74 20 69 73 20 61 6e 0a 2a 2a 20 65 78 70  set is an.** exp
2fdf0 72 65 73 73 69 6f 6e 20 6f 72 20 73 75 62 71 75  ression or subqu
2fe00 65 72 79 2c 20 74 68 65 6e 20 61 20 4e 55 4c 4c  ery, then a NULL
2fe10 20 70 6f 69 6e 74 65 72 20 69 73 20 72 65 74 75   pointer is retu
2fe20 72 6e 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 72 65  rned..** ^The re
2fe30 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73  turned string is
2fe40 20 61 6c 77 61 79 73 20 55 54 46 2d 38 20 65 6e   always UTF-8 en
2fe50 63 6f 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 46  coded..**.** ^(F
2fe60 6f 72 20 65 78 61 6d 70 6c 65 2c 20 67 69 76 65  or example, give
2fe70 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 73  n the database s
2fe80 63 68 65 6d 61 3a 0a 2a 2a 0a 2a 2a 20 43 52 45  chema:.**.** CRE
2fe90 41 54 45 20 54 41 42 4c 45 20 74 31 28 63 31 20  ATE TABLE t1(c1 
2fea0 56 41 52 49 41 4e 54 29 3b 0a 2a 2a 0a 2a 2a 20  VARIANT);.**.** 
2feb0 61 6e 64 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e  and the followin
2fec0 67 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 62  g statement to b
2fed0 65 20 63 6f 6d 70 69 6c 65 64 3a 0a 2a 2a 0a 2a  e compiled:.**.*
2fee0 2a 20 53 45 4c 45 43 54 20 63 31 20 2b 20 31 2c  * SELECT c1 + 1,
2fef0 20 63 31 20 46 52 4f 4d 20 74 31 3b 0a 2a 2a 0a   c1 FROM t1;.**.
2ff00 2a 2a 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  ** this routine 
2ff10 77 6f 75 6c 64 20 72 65 74 75 72 6e 20 74 68 65  would return the
2ff20 20 73 74 72 69 6e 67 20 22 56 41 52 49 41 4e 54   string "VARIANT
2ff30 22 20 66 6f 72 20 74 68 65 20 73 65 63 6f 6e 64  " for the second
2ff40 20 72 65 73 75 6c 74 0a 2a 2a 20 63 6f 6c 75 6d   result.** colum
2ff50 6e 20 28 69 3d 3d 31 29 2c 20 61 6e 64 20 61 20  n (i==1), and a 
2ff60 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 66 6f 72  NULL pointer for
2ff70 20 74 68 65 20 66 69 72 73 74 20 72 65 73 75 6c   the first resul
2ff80 74 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d 30 29 2e  t column (i==0).
2ff90 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65  )^.**.** ^SQLite
2ffa0 20 75 73 65 73 20 64 79 6e 61 6d 69 63 20 72 75   uses dynamic ru
2ffb0 6e 2d 74 69 6d 65 20 74 79 70 69 6e 67 2e 20 20  n-time typing.  
2ffc0 5e 53 6f 20 6a 75 73 74 20 62 65 63 61 75 73 65  ^So just because
2ffd0 20 61 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20   a column.** is 
2ffe0 64 65 63 6c 61 72 65 64 20 74 6f 20 63 6f 6e 74  declared to cont
2fff0 61 69 6e 20 61 20 70 61 72 74 69 63 75 6c 61 72  ain a particular
30000 20 74 79 70 65 20 64 6f 65 73 20 6e 6f 74 20 6d   type does not m
30010 65 61 6e 20 74 68 61 74 20 74 68 65 0a 2a 2a 20  ean that the.** 
30020 64 61 74 61 20 73 74 6f 72 65 64 20 69 6e 20 74  data stored in t
30030 68 61 74 20 63 6f 6c 75 6d 6e 20 69 73 20 6f 66  hat column is of
30040 20 74 68 65 20 64 65 63 6c 61 72 65 64 20 74 79   the declared ty
30050 70 65 2e 20 20 53 51 4c 69 74 65 20 69 73 0a 2a  pe.  SQLite is.*
30060 2a 20 73 74 72 6f 6e 67 6c 79 20 74 79 70 65 64  * strongly typed
30070 2c 20 62 75 74 20 74 68 65 20 74 79 70 69 6e 67  , but the typing
30080 20 69 73 20 64 79 6e 61 6d 69 63 20 6e 6f 74 20   is dynamic not 
30090 73 74 61 74 69 63 2e 20 20 5e 54 79 70 65 0a 2a  static.  ^Type.*
300a0 2a 20 69 73 20 61 73 73 6f 63 69 61 74 65 64 20  * is associated 
300b0 77 69 74 68 20 69 6e 64 69 76 69 64 75 61 6c 20  with individual 
300c0 76 61 6c 75 65 73 2c 20 6e 6f 74 20 77 69 74 68  values, not with
300d0 20 74 68 65 20 63 6f 6e 74 61 69 6e 65 72 73 0a   the containers.
300e0 2a 2a 20 75 73 65 64 20 74 6f 20 68 6f 6c 64 20  ** used to hold 
300f0 74 68 6f 73 65 20 76 61 6c 75 65 73 2e 0a 2a 2f  those values..*/
30100 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73  .SQLITE_API cons
30110 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
30120 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 28  column_decltype(
30130 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e  sqlite3_stmt*,in
30140 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63  t);.SQLITE_API c
30150 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
30160 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79  e3_column_declty
30170 70 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d  pe16(sqlite3_stm
30180 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  t*,int);../*.** 
30190 43 41 50 49 33 52 45 46 3a 20 45 76 61 6c 75 61  CAPI3REF: Evalua
301a0 74 65 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d  te An SQL Statem
301b0 65 6e 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  ent.** METHOD: s
301c0 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a  qlite3_stmt.**.*
301d0 2a 20 41 66 74 65 72 20 61 20 5b 70 72 65 70 61  * After a [prepa
301e0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 68  red statement] h
301f0 61 73 20 62 65 65 6e 20 70 72 65 70 61 72 65 64  as been prepared
30200 20 75 73 69 6e 67 20 65 69 74 68 65 72 0a 2a 2a   using either.**
30210 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
30220 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69  e_v2()] or [sqli
30230 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32  te3_prepare16_v2
30240 28 29 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 74 68  ()] or one of th
30250 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65  e legacy.** inte
30260 72 66 61 63 65 73 20 5b 73 71 6c 69 74 65 33 5f  rfaces [sqlite3_
30270 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20 5b 73  prepare()] or [s
30280 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
30290 28 29 5d 2c 20 74 68 69 73 20 66 75 6e 63 74 69  ()], this functi
302a0 6f 6e 0a 2a 2a 20 6d 75 73 74 20 62 65 20 63 61  on.** must be ca
302b0 6c 6c 65 64 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  lled one or more
302c0 20 74 69 6d 65 73 20 74 6f 20 65 76 61 6c 75 61   times to evalua
302d0 74 65 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  te the statement
302e0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64 65 74 61  ..**.** The deta
302f0 69 6c 73 20 6f 66 20 74 68 65 20 62 65 68 61 76  ils of the behav
30300 69 6f 72 20 6f 66 20 74 68 65 20 73 71 6c 69 74  ior of the sqlit
30310 65 33 5f 73 74 65 70 28 29 20 69 6e 74 65 72 66  e3_step() interf
30320 61 63 65 20 64 65 70 65 6e 64 0a 2a 2a 20 6f 6e  ace depend.** on
30330 20 77 68 65 74 68 65 72 20 74 68 65 20 73 74 61   whether the sta
30340 74 65 6d 65 6e 74 20 77 61 73 20 70 72 65 70 61  tement was prepa
30350 72 65 64 20 75 73 69 6e 67 20 74 68 65 20 6e 65  red using the ne
30360 77 65 72 20 22 76 32 22 20 69 6e 74 65 72 66 61  wer "v2" interfa
30370 63 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70  ce.** [sqlite3_p
30380 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64  repare_v2()] and
30390 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
303a0 65 31 36 5f 76 32 28 29 5d 20 6f 72 20 74 68 65  e16_v2()] or the
303b0 20 6f 6c 64 65 72 20 6c 65 67 61 63 79 0a 2a 2a   older legacy.**
303c0 20 69 6e 74 65 72 66 61 63 65 20 5b 73 71 6c 69   interface [sqli
303d0 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 61  te3_prepare()] a
303e0 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  nd [sqlite3_prep
303f0 61 72 65 31 36 28 29 5d 2e 20 20 54 68 65 20 75  are16()].  The u
30400 73 65 20 6f 66 20 74 68 65 0a 2a 2a 20 6e 65 77  se of the.** new
30410 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 20   "v2" interface 
30420 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66  is recommended f
30430 6f 72 20 6e 65 77 20 61 70 70 6c 69 63 61 74 69  or new applicati
30440 6f 6e 73 20 62 75 74 20 74 68 65 20 6c 65 67 61  ons but the lega
30450 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20  cy.** interface 
30460 77 69 6c 6c 20 63 6f 6e 74 69 6e 75 65 20 74 6f  will continue to
30470 20 62 65 20 73 75 70 70 6f 72 74 65 64 2e 0a 2a   be supported..*
30480 2a 0a 2a 2a 20 5e 49 6e 20 74 68 65 20 6c 65 67  *.** ^In the leg
30490 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20 74  acy interface, t
304a0 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20  he return value 
304b0 77 69 6c 6c 20 62 65 20 65 69 74 68 65 72 20 5b  will be either [
304c0 53 51 4c 49 54 45 5f 42 55 53 59 5d 2c 0a 2a 2a  SQLITE_BUSY],.**
304d0 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c 20   [SQLITE_DONE], 
304e0 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 5b 53  [SQLITE_ROW], [S
304f0 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c 20 6f 72  QLITE_ERROR], or
30500 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d   [SQLITE_MISUSE]
30510 2e 0a 2a 2a 20 5e 57 69 74 68 20 74 68 65 20 22  ..** ^With the "
30520 76 32 22 20 69 6e 74 65 72 66 61 63 65 2c 20 61  v2" interface, a
30530 6e 79 20 6f 66 20 74 68 65 20 6f 74 68 65 72 20  ny of the other 
30540 5b 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 6f  [result codes] o
30550 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72  r.** [extended r
30560 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 6d 69 67  esult codes] mig
30570 68 74 20 62 65 20 72 65 74 75 72 6e 65 64 20 61  ht be returned a
30580 73 20 77 65 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 5b  s well..**.** ^[
30590 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 6d 65 61  SQLITE_BUSY] mea
305a0 6e 73 20 74 68 61 74 20 74 68 65 20 64 61 74 61  ns that the data
305b0 62 61 73 65 20 65 6e 67 69 6e 65 20 77 61 73 20  base engine was 
305c0 75 6e 61 62 6c 65 20 74 6f 20 61 63 71 75 69 72  unable to acquir
305d0 65 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73  e the.** databas
305e0 65 20 6c 6f 63 6b 73 20 69 74 20 6e 65 65 64 73  e locks it needs
305f0 20 74 6f 20 64 6f 20 69 74 73 20 6a 6f 62 2e 20   to do its job. 
30600 20 5e 49 66 20 74 68 65 20 73 74 61 74 65 6d 65   ^If the stateme
30610 6e 74 20 69 73 20 61 20 5b 43 4f 4d 4d 49 54 5d  nt is a [COMMIT]
30620 0a 2a 2a 20 6f 72 20 6f 63 63 75 72 73 20 6f 75  .** or occurs ou
30630 74 73 69 64 65 20 6f 66 20 61 6e 20 65 78 70 6c  tside of an expl
30640 69 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e  icit transaction
30650 2c 20 74 68 65 6e 20 79 6f 75 20 63 61 6e 20 72  , then you can r
30660 65 74 72 79 20 74 68 65 0a 2a 2a 20 73 74 61 74  etry the.** stat
30670 65 6d 65 6e 74 2e 20 20 49 66 20 74 68 65 20 73  ement.  If the s
30680 74 61 74 65 6d 65 6e 74 20 69 73 20 6e 6f 74 20  tatement is not 
30690 61 20 5b 43 4f 4d 4d 49 54 5d 20 61 6e 64 20 6f  a [COMMIT] and o
306a0 63 63 75 72 73 20 77 69 74 68 69 6e 20 61 6e 0a  ccurs within an.
306b0 2a 2a 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e  ** explicit tran
306c0 73 61 63 74 69 6f 6e 20 74 68 65 6e 20 79 6f 75  saction then you
306d0 20 73 68 6f 75 6c 64 20 72 6f 6c 6c 62 61 63 6b   should rollback
306e0 20 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e   the transaction
306f0 20 62 65 66 6f 72 65 0a 2a 2a 20 63 6f 6e 74 69   before.** conti
30700 6e 75 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53  nuing..**.** ^[S
30710 51 4c 49 54 45 5f 44 4f 4e 45 5d 20 6d 65 61 6e  QLITE_DONE] mean
30720 73 20 74 68 61 74 20 74 68 65 20 73 74 61 74 65  s that the state
30730 6d 65 6e 74 20 68 61 73 20 66 69 6e 69 73 68 65  ment has finishe
30740 64 20 65 78 65 63 75 74 69 6e 67 0a 2a 2a 20 73  d executing.** s
30750 75 63 63 65 73 73 66 75 6c 6c 79 2e 20 20 73 71  uccessfully.  sq
30760 6c 69 74 65 33 5f 73 74 65 70 28 29 20 73 68 6f  lite3_step() sho
30770 75 6c 64 20 6e 6f 74 20 62 65 20 63 61 6c 6c 65  uld not be calle
30780 64 20 61 67 61 69 6e 20 6f 6e 20 74 68 69 73 20  d again on this 
30790 76 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 69  virtual.** machi
307a0 6e 65 20 77 69 74 68 6f 75 74 20 66 69 72 73 74  ne without first
307b0 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65   calling [sqlite
307c0 33 5f 72 65 73 65 74 28 29 5d 20 74 6f 20 72 65  3_reset()] to re
307d0 73 65 74 20 74 68 65 20 76 69 72 74 75 61 6c 0a  set the virtual.
307e0 2a 2a 20 6d 61 63 68 69 6e 65 20 62 61 63 6b 20  ** machine back 
307f0 74 6f 20 69 74 73 20 69 6e 69 74 69 61 6c 20 73  to its initial s
30800 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  tate..**.** ^If 
30810 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  the SQL statemen
30820 74 20 62 65 69 6e 67 20 65 78 65 63 75 74 65 64  t being executed
30830 20 72 65 74 75 72 6e 73 20 61 6e 79 20 64 61 74   returns any dat
30840 61 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54 45 5f  a, then [SQLITE_
30850 52 4f 57 5d 0a 2a 2a 20 69 73 20 72 65 74 75 72  ROW].** is retur
30860 6e 65 64 20 65 61 63 68 20 74 69 6d 65 20 61 20  ned each time a 
30870 6e 65 77 20 72 6f 77 20 6f 66 20 64 61 74 61 20  new row of data 
30880 69 73 20 72 65 61 64 79 20 66 6f 72 20 70 72 6f  is ready for pro
30890 63 65 73 73 69 6e 67 20 62 79 20 74 68 65 0a 2a  cessing by the.*
308a0 2a 20 63 61 6c 6c 65 72 2e 20 54 68 65 20 76 61  * caller. The va
308b0 6c 75 65 73 20 6d 61 79 20 62 65 20 61 63 63 65  lues may be acce
308c0 73 73 65 64 20 75 73 69 6e 67 20 74 68 65 20 5b  ssed using the [
308d0 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75  column access fu
308e0 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 73 71 6c  nctions]..** sql
308f0 69 74 65 33 5f 73 74 65 70 28 29 20 69 73 20 63  ite3_step() is c
30900 61 6c 6c 65 64 20 61 67 61 69 6e 20 74 6f 20 72  alled again to r
30910 65 74 72 69 65 76 65 20 74 68 65 20 6e 65 78 74  etrieve the next
30920 20 72 6f 77 20 6f 66 20 64 61 74 61 2e 0a 2a 2a   row of data..**
30930 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 45 52 52  .** ^[SQLITE_ERR
30940 4f 52 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 61  OR] means that a
30950 20 72 75 6e 2d 74 69 6d 65 20 65 72 72 6f 72 20   run-time error 
30960 28 73 75 63 68 20 61 73 20 61 20 63 6f 6e 73 74  (such as a const
30970 72 61 69 6e 74 0a 2a 2a 20 76 69 6f 6c 61 74 69  raint.** violati
30980 6f 6e 29 20 68 61 73 20 6f 63 63 75 72 72 65 64  on) has occurred
30990 2e 20 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  .  sqlite3_step(
309a0 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20  ) should not be 
309b0 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e 0a  called again on.
309c0 2a 2a 20 74 68 65 20 56 4d 2e 20 4d 6f 72 65 20  ** the VM. More 
309d0 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 6d 61 79 20  information may 
309e0 62 65 20 66 6f 75 6e 64 20 62 79 20 63 61 6c 6c  be found by call
309f0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65 72 72  ing [sqlite3_err
30a00 6d 73 67 28 29 5d 2e 0a 2a 2a 20 5e 57 69 74 68  msg()]..** ^With
30a10 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65   the legacy inte
30a20 72 66 61 63 65 2c 20 61 20 6d 6f 72 65 20 73 70  rface, a more sp
30a30 65 63 69 66 69 63 20 65 72 72 6f 72 20 63 6f 64  ecific error cod
30a40 65 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 2c 0a  e (for example,.
30a50 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52  ** [SQLITE_INTER
30a60 52 55 50 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 53  RUPT], [SQLITE_S
30a70 43 48 45 4d 41 5d 2c 20 5b 53 51 4c 49 54 45 5f  CHEMA], [SQLITE_
30a80 43 4f 52 52 55 50 54 5d 2c 20 61 6e 64 20 73 6f  CORRUPT], and so
30a90 20 66 6f 72 74 68 29 0a 2a 2a 20 63 61 6e 20 62   forth).** can b
30aa0 65 20 6f 62 74 61 69 6e 65 64 20 62 79 20 63 61  e obtained by ca
30ab0 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72  lling [sqlite3_r
30ac0 65 73 65 74 28 29 5d 20 6f 6e 20 74 68 65 0a 2a  eset()] on the.*
30ad0 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  * [prepared stat
30ae0 65 6d 65 6e 74 5d 2e 20 20 5e 49 6e 20 74 68 65  ement].  ^In the
30af0 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 2c   "v2" interface,
30b00 0a 2a 2a 20 74 68 65 20 6d 6f 72 65 20 73 70 65  .** the more spe
30b10 63 69 66 69 63 20 65 72 72 6f 72 20 63 6f 64 65  cific error code
30b20 20 69 73 20 72 65 74 75 72 6e 65 64 20 64 69 72   is returned dir
30b30 65 63 74 6c 79 20 62 79 20 73 71 6c 69 74 65 33  ectly by sqlite3
30b40 5f 73 74 65 70 28 29 2e 0a 2a 2a 0a 2a 2a 20 5b  _step()..**.** [
30b50 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 6d  SQLITE_MISUSE] m
30b60 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 74 68  eans that the th
30b70 69 73 20 72 6f 75 74 69 6e 65 20 77 61 73 20 63  is routine was c
30b80 61 6c 6c 65 64 20 69 6e 61 70 70 72 6f 70 72 69  alled inappropri
30b90 61 74 65 6c 79 2e 0a 2a 2a 20 50 65 72 68 61 70  ately..** Perhap
30ba0 73 20 69 74 20 77 61 73 20 63 61 6c 6c 65 64 20  s it was called 
30bb0 6f 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  on a [prepared s
30bc0 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 68  tatement] that h
30bd0 61 73 0a 2a 2a 20 61 6c 72 65 61 64 79 20 62 65  as.** already be
30be0 65 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  en [sqlite3_fina
30bf0 6c 69 7a 65 20 7c 20 66 69 6e 61 6c 69 7a 65 64  lize | finalized
30c00 5d 20 6f 72 20 6f 6e 20 6f 6e 65 20 74 68 61 74  ] or on one that
30c10 20 68 61 64 0a 2a 2a 20 70 72 65 76 69 6f 75 73   had.** previous
30c20 6c 79 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c  ly returned [SQL
30c30 49 54 45 5f 45 52 52 4f 52 5d 20 6f 72 20 5b 53  ITE_ERROR] or [S
30c40 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20 20 4f 72  QLITE_DONE].  Or
30c50 20 69 74 20 63 6f 75 6c 64 0a 2a 2a 20 62 65 20   it could.** be 
30c60 74 68 65 20 63 61 73 65 20 74 68 61 74 20 74 68  the case that th
30c70 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20  e same database 
30c80 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 62 65  connection is be
30c90 69 6e 67 20 75 73 65 64 20 62 79 20 74 77 6f 20  ing used by two 
30ca0 6f 72 0a 2a 2a 20 6d 6f 72 65 20 74 68 72 65 61  or.** more threa
30cb0 64 73 20 61 74 20 74 68 65 20 73 61 6d 65 20 6d  ds at the same m
30cc0 6f 6d 65 6e 74 20 69 6e 20 74 69 6d 65 2e 0a 2a  oment in time..*
30cd0 2a 0a 2a 2a 20 46 6f 72 20 61 6c 6c 20 76 65 72  *.** For all ver
30ce0 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20  sions of SQLite 
30cf0 75 70 20 74 6f 20 61 6e 64 20 69 6e 63 6c 75 64  up to and includ
30d00 69 6e 67 20 33 2e 36 2e 32 33 2e 31 2c 20 61 20  ing 3.6.23.1, a 
30d10 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  call to.** [sqli
30d20 74 65 33 5f 72 65 73 65 74 28 29 5d 20 77 61 73  te3_reset()] was
30d30 20 72 65 71 75 69 72 65 64 20 61 66 74 65 72 20   required after 
30d40 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 72  sqlite3_step() r
30d50 65 74 75 72 6e 65 64 20 61 6e 79 74 68 69 6e 67  eturned anything
30d60 0a 2a 2a 20 6f 74 68 65 72 20 74 68 61 6e 20 5b  .** other than [
30d70 53 51 4c 49 54 45 5f 52 4f 57 5d 20 62 65 66 6f  SQLITE_ROW] befo
30d80 72 65 20 61 6e 79 20 73 75 62 73 65 71 75 65 6e  re any subsequen
30d90 74 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 0a  t invocation of.
30da0 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  ** sqlite3_step(
30db0 29 2e 20 20 46 61 69 6c 75 72 65 20 74 6f 20 72  ).  Failure to r
30dc0 65 73 65 74 20 74 68 65 20 70 72 65 70 61 72 65  eset the prepare
30dd0 64 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69 6e  d statement usin
30de0 67 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72  g .** [sqlite3_r
30df0 65 73 65 74 28 29 5d 20 77 6f 75 6c 64 20 72 65  eset()] would re
30e00 73 75 6c 74 20 69 6e 20 61 6e 20 5b 53 51 4c 49  sult in an [SQLI
30e10 54 45 5f 4d 49 53 55 53 45 5d 20 72 65 74 75 72  TE_MISUSE] retur
30e20 6e 20 66 72 6f 6d 0a 2a 2a 20 73 71 6c 69 74 65  n from.** sqlite
30e30 33 5f 73 74 65 70 28 29 2e 20 20 42 75 74 20 61  3_step().  But a
30e40 66 74 65 72 20 5b 76 65 72 73 69 6f 6e 20 33 2e  fter [version 3.
30e50 36 2e 32 33 2e 31 5d 20 28 5b 64 61 74 65 6f 66  6.23.1] ([dateof
30e60 3a 33 2e 36 2e 32 33 2e 31 5d 2c 0a 2a 2a 20 73  :3.6.23.1],.** s
30e70 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 62 65  qlite3_step() be
30e80 67 61 6e 0a 2a 2a 20 63 61 6c 6c 69 6e 67 20 5b  gan.** calling [
30e90 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
30ea0 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 69   automatically i
30eb0 6e 20 74 68 69 73 20 63 69 72 63 75 6d 73 74 61  n this circumsta
30ec0 6e 63 65 20 72 61 74 68 65 72 0a 2a 2a 20 74 68  nce rather.** th
30ed0 61 6e 20 72 65 74 75 72 6e 69 6e 67 20 5b 53 51  an returning [SQ
30ee0 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20 54  LITE_MISUSE].  T
30ef0 68 69 73 20 69 73 20 6e 6f 74 20 63 6f 6e 73 69  his is not consi
30f00 64 65 72 65 64 20 61 20 63 6f 6d 70 61 74 69 62  dered a compatib
30f10 69 6c 69 74 79 0a 2a 2a 20 62 72 65 61 6b 20 62  ility.** break b
30f20 65 63 61 75 73 65 20 61 6e 79 20 61 70 70 6c 69  ecause any appli
30f30 63 61 74 69 6f 6e 20 74 68 61 74 20 65 76 65 72  cation that ever
30f40 20 72 65 63 65 69 76 65 73 20 61 6e 20 53 51 4c   receives an SQL
30f50 49 54 45 5f 4d 49 53 55 53 45 20 65 72 72 6f 72  ITE_MISUSE error
30f60 0a 2a 2a 20 69 73 20 62 72 6f 6b 65 6e 20 62 79  .** is broken by
30f70 20 64 65 66 69 6e 69 74 69 6f 6e 2e 20 20 54 68   definition.  Th
30f80 65 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41  e [SQLITE_OMIT_A
30f90 55 54 4f 52 45 53 45 54 5d 20 63 6f 6d 70 69 6c  UTORESET] compil
30fa0 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 0a 2a 2a  e-time option.**
30fb0 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
30fc0 72 65 73 74 6f 72 65 20 74 68 65 20 6c 65 67 61  restore the lega
30fd0 63 79 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a  cy behavior..**.
30fe0 2a 2a 20 3c 62 3e 47 6f 6f 66 79 20 49 6e 74 65  ** <b>Goofy Inte
30ff0 72 66 61 63 65 20 41 6c 65 72 74 3a 3c 2f 62 3e  rface Alert:</b>
31000 20 49 6e 20 74 68 65 20 6c 65 67 61 63 79 20 69   In the legacy i
31010 6e 74 65 72 66 61 63 65 2c 20 74 68 65 20 73 71  nterface, the sq
31020 6c 69 74 65 33 5f 73 74 65 70 28 29 0a 2a 2a 20  lite3_step().** 
31030 41 50 49 20 61 6c 77 61 79 73 20 72 65 74 75 72  API always retur
31040 6e 73 20 61 20 67 65 6e 65 72 69 63 20 65 72 72  ns a generic err
31050 6f 72 20 63 6f 64 65 2c 20 5b 53 51 4c 49 54 45  or code, [SQLITE
31060 5f 45 52 52 4f 52 5d 2c 20 66 6f 6c 6c 6f 77 69  _ERROR], followi
31070 6e 67 20 61 6e 79 0a 2a 2a 20 65 72 72 6f 72 20  ng any.** error 
31080 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49  other than [SQLI
31090 54 45 5f 42 55 53 59 5d 20 61 6e 64 20 5b 53 51  TE_BUSY] and [SQ
310a0 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20 59  LITE_MISUSE].  Y
310b0 6f 75 20 6d 75 73 74 20 63 61 6c 6c 0a 2a 2a 20  ou must call.** 
310c0 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
310d0 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69  ] or [sqlite3_fi
310e0 6e 61 6c 69 7a 65 28 29 5d 20 69 6e 20 6f 72 64  nalize()] in ord
310f0 65 72 20 74 6f 20 66 69 6e 64 20 6f 6e 65 20 6f  er to find one o
31100 66 20 74 68 65 0a 2a 2a 20 73 70 65 63 69 66 69  f the.** specifi
31110 63 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d 20  c [error codes] 
31120 74 68 61 74 20 62 65 74 74 65 72 20 64 65 73 63  that better desc
31130 72 69 62 65 73 20 74 68 65 20 65 72 72 6f 72 2e  ribes the error.
31140 0a 2a 2a 20 57 65 20 61 64 6d 69 74 20 74 68 61  .** We admit tha
31150 74 20 74 68 69 73 20 69 73 20 61 20 67 6f 6f 66  t this is a goof
31160 79 20 64 65 73 69 67 6e 2e 20 20 54 68 65 20 70  y design.  The p
31170 72 6f 62 6c 65 6d 20 68 61 73 20 62 65 65 6e 20  roblem has been 
31180 66 69 78 65 64 0a 2a 2a 20 77 69 74 68 20 74 68  fixed.** with th
31190 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65  e "v2" interface
311a0 2e 20 20 49 66 20 79 6f 75 20 70 72 65 70 61 72  .  If you prepar
311b0 65 20 61 6c 6c 20 6f 66 20 79 6f 75 72 20 53 51  e all of your SQ
311c0 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20  L statements.** 
311d0 75 73 69 6e 67 20 65 69 74 68 65 72 20 5b 73 71  using either [sq
311e0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
311f0 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
31200 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20  prepare16_v2()] 
31210 69 6e 73 74 65 61 64 0a 2a 2a 20 6f 66 20 74 68  instead.** of th
31220 65 20 6c 65 67 61 63 79 20 5b 73 71 6c 69 74 65  e legacy [sqlite
31230 33 5f 70 72 65 70 61 72 65 28 29 5d 20 61 6e 64  3_prepare()] and
31240 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
31250 65 31 36 28 29 5d 20 69 6e 74 65 72 66 61 63 65  e16()] interface
31260 73 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 6d  s,.** then the m
31270 6f 72 65 20 73 70 65 63 69 66 69 63 20 5b 65 72  ore specific [er
31280 72 6f 72 20 63 6f 64 65 73 5d 20 61 72 65 20 72  ror codes] are r
31290 65 74 75 72 6e 65 64 20 64 69 72 65 63 74 6c 79  eturned directly
312a0 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 73  .** by sqlite3_s
312b0 74 65 70 28 29 2e 20 20 54 68 65 20 75 73 65 20  tep().  The use 
312c0 6f 66 20 74 68 65 20 22 76 32 22 20 69 6e 74 65  of the "v2" inte
312d0 72 66 61 63 65 20 69 73 20 72 65 63 6f 6d 6d 65  rface is recomme
312e0 6e 64 65 64 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  nded..*/.SQLITE_
312f0 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
31300 73 74 65 70 28 73 71 6c 69 74 65 33 5f 73 74 6d  step(sqlite3_stm
31310 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  t*);../*.** CAPI
31320 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 6f 66 20  3REF: Number of 
31330 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 72 65 73  columns in a res
31340 75 6c 74 20 73 65 74 0a 2a 2a 20 4d 45 54 48 4f  ult set.** METHO
31350 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a  D: sqlite3_stmt.
31360 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
31370 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29  e3_data_count(P)
31380 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
31390 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ns the number of
313a0 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 0a   columns in the.
313b0 2a 2a 20 63 75 72 72 65 6e 74 20 72 6f 77 20 6f  ** current row o
313c0 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74  f the result set
313d0 20 6f 66 20 5b 70 72 65 70 61 72 65 64 20 73 74   of [prepared st
313e0 61 74 65 6d 65 6e 74 5d 20 50 2e 0a 2a 2a 20 5e  atement] P..** ^
313f0 49 66 20 70 72 65 70 61 72 65 64 20 73 74 61 74  If prepared stat
31400 65 6d 65 6e 74 20 50 20 64 6f 65 73 20 6e 6f 74  ement P does not
31410 20 68 61 76 65 20 72 65 73 75 6c 74 73 20 72 65   have results re
31420 61 64 79 20 74 6f 20 72 65 74 75 72 6e 0a 2a 2a  ady to return.**
31430 20 28 76 69 61 20 63 61 6c 6c 73 20 74 6f 20 74   (via calls to t
31440 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  he [sqlite3_colu
31450 6d 6e 5f 69 6e 74 20 7c 20 73 71 6c 69 74 65 33  mn_int | sqlite3
31460 5f 63 6f 6c 75 6d 6e 5f 2a 28 29 5d 20 6f 66 0a  _column_*()] of.
31470 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 29 20 74  ** interfaces) t
31480 68 65 6e 20 73 71 6c 69 74 65 33 5f 64 61 74 61  hen sqlite3_data
31490 5f 63 6f 75 6e 74 28 50 29 20 72 65 74 75 72 6e  _count(P) return
314a0 73 20 30 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  s 0..** ^The sql
314b0 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28  ite3_data_count(
314c0 50 29 20 72 6f 75 74 69 6e 65 20 61 6c 73 6f 20  P) routine also 
314d0 72 65 74 75 72 6e 73 20 30 20 69 66 20 50 20 69  returns 0 if P i
314e0 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
314f0 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  ..** ^The sqlite
31500 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 20  3_data_count(P) 
31510 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
31520 30 20 69 66 20 74 68 65 20 70 72 65 76 69 6f 75  0 if the previou
31530 73 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71  s call to.** [sq
31540 6c 69 74 65 33 5f 73 74 65 70 5d 28 50 29 20 72  lite3_step](P) r
31550 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f  eturned [SQLITE_
31560 44 4f 4e 45 5d 2e 20 20 5e 54 68 65 20 73 71 6c  DONE].  ^The sql
31570 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28  ite3_data_count(
31580 50 29 0a 2a 2a 20 77 69 6c 6c 20 72 65 74 75 72  P).** will retur
31590 6e 20 6e 6f 6e 2d 7a 65 72 6f 20 69 66 20 70 72  n non-zero if pr
315a0 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20 5b  evious call to [
315b0 73 71 6c 69 74 65 33 5f 73 74 65 70 5d 28 50 29  sqlite3_step](P)
315c0 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 5b 53 51   returned.** [SQ
315d0 4c 49 54 45 5f 52 4f 57 5d 2c 20 65 78 63 65 70  LITE_ROW], excep
315e0 74 20 69 6e 20 74 68 65 20 63 61 73 65 20 6f 66  t in the case of
315f0 20 74 68 65 20 5b 50 52 41 47 4d 41 20 69 6e 63   the [PRAGMA inc
31600 72 65 6d 65 6e 74 61 6c 5f 76 61 63 75 75 6d 5d  remental_vacuum]
31610 0a 2a 2a 20 77 68 65 72 65 20 69 74 20 61 6c 77  .** where it alw
31620 61 79 73 20 72 65 74 75 72 6e 73 20 7a 65 72 6f  ays returns zero
31630 20 73 69 6e 63 65 20 65 61 63 68 20 73 74 65 70   since each step
31640 20 6f 66 20 74 68 61 74 20 6d 75 6c 74 69 2d 73   of that multi-s
31650 74 65 70 0a 2a 2a 20 70 72 61 67 6d 61 20 72 65  tep.** pragma re
31660 74 75 72 6e 73 20 30 20 63 6f 6c 75 6d 6e 73 20  turns 0 columns 
31670 6f 66 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 53  of data..**.** S
31680 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65  ee also: [sqlite
31690 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 29  3_column_count()
316a0 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ].*/.SQLITE_API 
316b0 69 6e 74 20 73 71 6c 69 74 65 33 5f 64 61 74 61  int sqlite3_data
316c0 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73  _count(sqlite3_s
316d0 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a  tmt *pStmt);../*
316e0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 75  .** CAPI3REF: Fu
316f0 6e 64 61 6d 65 6e 74 61 6c 20 44 61 74 61 74 79  ndamental Dataty
31700 70 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  pes.** KEYWORDS:
31710 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 2a 2a 0a   SQLITE_TEXT.**.
31720 2a 2a 20 5e 28 45 76 65 72 79 20 76 61 6c 75 65  ** ^(Every value
31730 20 69 6e 20 53 51 4c 69 74 65 20 68 61 73 20 6f   in SQLite has o
31740 6e 65 20 6f 66 20 66 69 76 65 20 66 75 6e 64 61  ne of five funda
31750 6d 65 6e 74 61 6c 20 64 61 74 61 74 79 70 65 73  mental datatypes
31760 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  :.**.** <ul>.** 
31770 3c 6c 69 3e 20 36 34 2d 62 69 74 20 73 69 67 6e  <li> 64-bit sign
31780 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 6c  ed integer.** <l
31790 69 3e 20 36 34 2d 62 69 74 20 49 45 45 45 20 66  i> 64-bit IEEE f
317a0 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 6e 75  loating point nu
317b0 6d 62 65 72 0a 2a 2a 20 3c 6c 69 3e 20 73 74 72  mber.** <li> str
317c0 69 6e 67 0a 2a 2a 20 3c 6c 69 3e 20 42 4c 4f 42  ing.** <li> BLOB
317d0 0a 2a 2a 20 3c 6c 69 3e 20 4e 55 4c 4c 0a 2a 2a  .** <li> NULL.**
317e0 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54   </ul>)^.**.** T
317f0 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61  hese constants a
31800 72 65 20 63 6f 64 65 73 20 66 6f 72 20 65 61 63  re codes for eac
31810 68 20 6f 66 20 74 68 6f 73 65 20 74 79 70 65 73  h of those types
31820 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61  ..**.** Note tha
31830 74 20 74 68 65 20 53 51 4c 49 54 45 5f 54 45 58  t the SQLITE_TEX
31840 54 20 63 6f 6e 73 74 61 6e 74 20 77 61 73 20 61  T constant was a
31850 6c 73 6f 20 75 73 65 64 20 69 6e 20 53 51 4c 69  lso used in SQLi
31860 74 65 20 76 65 72 73 69 6f 6e 20 32 0a 2a 2a 20  te version 2.** 
31870 66 6f 72 20 61 20 63 6f 6d 70 6c 65 74 65 6c 79  for a completely
31880 20 64 69 66 66 65 72 65 6e 74 20 6d 65 61 6e 69   different meani
31890 6e 67 2e 20 20 53 6f 66 74 77 61 72 65 20 74 68  ng.  Software th
318a0 61 74 20 6c 69 6e 6b 73 20 61 67 61 69 6e 73 74  at links against
318b0 20 62 6f 74 68 0a 2a 2a 20 53 51 4c 69 74 65 20   both.** SQLite 
318c0 76 65 72 73 69 6f 6e 20 32 20 61 6e 64 20 53 51  version 2 and SQ
318d0 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 20 73  Lite version 3 s
318e0 68 6f 75 6c 64 20 75 73 65 20 53 51 4c 49 54 45  hould use SQLITE
318f0 33 5f 54 45 58 54 2c 20 6e 6f 74 0a 2a 2a 20 53  3_TEXT, not.** S
31900 51 4c 49 54 45 5f 54 45 58 54 2e 0a 2a 2f 0a 23  QLITE_TEXT..*/.#
31910 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e  define SQLITE_IN
31920 54 45 47 45 52 20 20 31 0a 23 64 65 66 69 6e 65  TEGER  1.#define
31930 20 53 51 4c 49 54 45 5f 46 4c 4f 41 54 20 20 20   SQLITE_FLOAT   
31940 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   2.#define SQLIT
31950 45 5f 42 4c 4f 42 20 20 20 20 20 34 0a 23 64 65  E_BLOB     4.#de
31960 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 55 4c 4c  fine SQLITE_NULL
31970 20 20 20 20 20 35 0a 23 69 66 64 65 66 20 53 51       5.#ifdef SQ
31980 4c 49 54 45 5f 54 45 58 54 0a 23 20 75 6e 64 65  LITE_TEXT.# unde
31990 66 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 23 65  f SQLITE_TEXT.#e
319a0 6c 73 65 0a 23 20 64 65 66 69 6e 65 20 53 51 4c  lse.# define SQL
319b0 49 54 45 5f 54 45 58 54 20 20 20 20 20 33 0a 23  ITE_TEXT     3.#
319c0 65 6e 64 69 66 0a 23 64 65 66 69 6e 65 20 53 51  endif.#define SQ
319d0 4c 49 54 45 33 5f 54 45 58 54 20 20 20 20 20 33  LITE3_TEXT     3
319e0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
319f0 3a 20 52 65 73 75 6c 74 20 56 61 6c 75 65 73 20  : Result Values 
31a00 46 72 6f 6d 20 41 20 51 75 65 72 79 0a 2a 2a 20  From A Query.** 
31a10 4b 45 59 57 4f 52 44 53 3a 20 7b 63 6f 6c 75 6d  KEYWORDS: {colum
31a20 6e 20 61 63 63 65 73 73 20 66 75 6e 63 74 69 6f  n access functio
31a30 6e 73 7d 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  ns}.** METHOD: s
31a40 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a  qlite3_stmt.**.*
31a50 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65  * ^These routine
31a60 73 20 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d 61  s return informa
31a70 74 69 6f 6e 20 61 62 6f 75 74 20 61 20 73 69 6e  tion about a sin
31a80 67 6c 65 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68  gle column of th
31a90 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 72 65 73  e current.** res
31aa0 75 6c 74 20 72 6f 77 20 6f 66 20 61 20 71 75 65  ult row of a que
31ab0 72 79 2e 20 20 5e 49 6e 20 65 76 65 72 79 20 63  ry.  ^In every c
31ac0 61 73 65 20 74 68 65 20 66 69 72 73 74 20 61 72  ase the first ar
31ad0 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e  gument is a poin
31ae0 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 70  ter.** to the [p
31af0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
31b00 74 5d 20 74 68 61 74 20 69 73 20 62 65 69 6e 67  t] that is being
31b10 20 65 76 61 6c 75 61 74 65 64 20 28 74 68 65 20   evaluated (the 
31b20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 5d 0a  [sqlite3_stmt*].
31b30 2a 2a 20 74 68 61 74 20 77 61 73 20 72 65 74 75  ** that was retu
31b40 72 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74  rned from [sqlit
31b50 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
31b60 20 6f 72 20 6f 6e 65 20 6f 66 20 69 74 73 20 76   or one of its v
31b70 61 72 69 61 6e 74 73 29 0a 2a 2a 20 61 6e 64 20  ariants).** and 
31b80 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  the second argum
31b90 65 6e 74 20 69 73 20 74 68 65 20 69 6e 64 65 78  ent is the index
31ba0 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20 66   of the column f
31bb0 6f 72 20 77 68 69 63 68 20 69 6e 66 6f 72 6d 61  or which informa
31bc0 74 69 6f 6e 0a 2a 2a 20 73 68 6f 75 6c 64 20 62  tion.** should b
31bd0 65 20 72 65 74 75 72 6e 65 64 2e 20 5e 54 68 65  e returned. ^The
31be0 20 6c 65 66 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e   leftmost column
31bf0 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73   of the result s
31c00 65 74 20 68 61 73 20 74 68 65 20 69 6e 64 65 78  et has the index
31c10 20 30 2e 0a 2a 2a 20 5e 54 68 65 20 6e 75 6d 62   0..** ^The numb
31c20 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e  er of columns in
31c30 20 74 68 65 20 72 65 73 75 6c 74 20 63 61 6e 20   the result can 
31c40 62 65 20 64 65 74 65 72 6d 69 6e 65 64 20 75 73  be determined us
31c50 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ing.** [sqlite3_
31c60 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 29 5d 2e  column_count()].
31c70 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 53 51  .**.** If the SQ
31c80 4c 20 73 74 61 74 65 6d 65 6e 74 20 64 6f 65 73  L statement does
31c90 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79 20 70   not currently p
31ca0 6f 69 6e 74 20 74 6f 20 61 20 76 61 6c 69 64 20  oint to a valid 
31cb0 72 6f 77 2c 20 6f 72 20 69 66 20 74 68 65 0a 2a  row, or if the.*
31cc0 2a 20 63 6f 6c 75 6d 6e 20 69 6e 64 65 78 20 69  * column index i
31cd0 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 2c 20  s out of range, 
31ce0 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 75 6e  the result is un
31cf0 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 73  defined..** Thes
31d00 65 20 72 6f 75 74 69 6e 65 73 20 6d 61 79 20 6f  e routines may o
31d10 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64 20 77 68  nly be called wh
31d20 65 6e 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  en the most rece
31d30 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73  nt call to.** [s
31d40 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 68  qlite3_step()] h
31d50 61 73 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c  as returned [SQL
31d60 49 54 45 5f 52 4f 57 5d 20 61 6e 64 20 6e 65 69  ITE_ROW] and nei
31d70 74 68 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ther.** [sqlite3
31d80 5f 72 65 73 65 74 28 29 5d 20 6e 6f 72 20 5b 73  _reset()] nor [s
31d90 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
31da0 29 5d 20 68 61 76 65 20 62 65 65 6e 20 63 61 6c  )] have been cal
31db0 6c 65 64 20 73 75 62 73 65 71 75 65 6e 74 6c 79  led subsequently
31dc0 2e 0a 2a 2a 20 49 66 20 61 6e 79 20 6f 66 20 74  ..** If any of t
31dd0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72  hese routines ar
31de0 65 20 63 61 6c 6c 65 64 20 61 66 74 65 72 20 5b  e called after [
31df0 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
31e00 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   or.** [sqlite3_
31e10 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 61  finalize()] or a
31e20 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 73 74  fter [sqlite3_st
31e30 65 70 28 29 5d 20 68 61 73 20 72 65 74 75 72 6e  ep()] has return
31e40 65 64 0a 2a 2a 20 73 6f 6d 65 74 68 69 6e 67 20  ed.** something 
31e50 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49  other than [SQLI
31e60 54 45 5f 52 4f 57 5d 2c 20 74 68 65 20 72 65 73  TE_ROW], the res
31e70 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e  ults are undefin
31e80 65 64 2e 0a 2a 2a 20 49 66 20 5b 73 71 6c 69 74  ed..** If [sqlit
31e90 65 33 5f 73 74 65 70 28 29 5d 20 6f 72 20 5b 73  e3_step()] or [s
31ea0 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
31eb0 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  or [sqlite3_fina
31ec0 6c 69 7a 65 28 29 5d 0a 2a 2a 20 61 72 65 20 63  lize()].** are c
31ed0 61 6c 6c 65 64 20 66 72 6f 6d 20 61 20 64 69 66  alled from a dif
31ee0 66 65 72 65 6e 74 20 74 68 72 65 61 64 20 77 68  ferent thread wh
31ef0 69 6c 65 20 61 6e 79 20 6f 66 20 74 68 65 73 65  ile any of these
31f00 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 61 72 65   routines.** are
31f10 20 70 65 6e 64 69 6e 67 2c 20 74 68 65 6e 20 74   pending, then t
31f20 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 75  he results are u
31f30 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  ndefined..**.** 
31f40 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c  ^The sqlite3_col
31f50 75 6d 6e 5f 74 79 70 65 28 29 20 72 6f 75 74 69  umn_type() routi
31f60 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 0a 2a  ne returns the.*
31f70 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45  * [SQLITE_INTEGE
31f80 52 20 7c 20 64 61 74 61 74 79 70 65 20 63 6f 64  R | datatype cod
31f90 65 5d 20 66 6f 72 20 74 68 65 20 69 6e 69 74 69  e] for the initi
31fa0 61 6c 20 64 61 74 61 20 74 79 70 65 0a 2a 2a 20  al data type.** 
31fb0 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 63 6f  of the result co
31fc0 6c 75 6d 6e 2e 20 20 5e 54 68 65 20 72 65 74 75  lumn.  ^The retu
31fd0 72 6e 65 64 20 76 61 6c 75 65 20 69 73 20 6f 6e  rned value is on
31fe0 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 49 4e 54  e of [SQLITE_INT
31ff0 45 47 45 52 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54  EGER],.** [SQLIT
32000 45 5f 46 4c 4f 41 54 5d 2c 20 5b 53 51 4c 49 54  E_FLOAT], [SQLIT
32010 45 5f 54 45 58 54 5d 2c 20 5b 53 51 4c 49 54 45  E_TEXT], [SQLITE
32020 5f 42 4c 4f 42 5d 2c 20 6f 72 20 5b 53 51 4c 49  _BLOB], or [SQLI
32030 54 45 5f 4e 55 4c 4c 5d 2e 20 20 54 68 65 20 76  TE_NULL].  The v
32040 61 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64  alue.** returned
32050 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   by sqlite3_colu
32060 6d 6e 5f 74 79 70 65 28 29 20 69 73 20 6f 6e 6c  mn_type() is onl
32070 79 20 6d 65 61 6e 69 6e 67 66 75 6c 20 69 66 20  y meaningful if 
32080 6e 6f 20 74 79 70 65 0a 2a 2a 20 63 6f 6e 76 65  no type.** conve
32090 72 73 69 6f 6e 73 20 68 61 76 65 20 6f 63 63 75  rsions have occu
320a0 72 72 65 64 20 61 73 20 64 65 73 63 72 69 62 65  rred as describe
320b0 64 20 62 65 6c 6f 77 2e 20 20 41 66 74 65 72 20  d below.  After 
320c0 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f  a type conversio
320d0 6e 2c 0a 2a 2a 20 74 68 65 20 76 61 6c 75 65 20  n,.** the value 
320e0 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69  returned by sqli
320f0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28  te3_column_type(
32100 29 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 20  ) is undefined. 
32110 20 46 75 74 75 72 65 0a 2a 2a 20 76 65 72 73 69   Future.** versi
32120 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 61  ons of SQLite ma
32130 79 20 63 68 61 6e 67 65 20 74 68 65 20 62 65 68  y change the beh
32140 61 76 69 6f 72 20 6f 66 20 73 71 6c 69 74 65 33  avior of sqlite3
32150 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 0a 2a  _column_type().*
32160 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 74 79  * following a ty
32170 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a  pe conversion..*
32180 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73  *.** ^If the res
32190 75 6c 74 20 69 73 20 61 20 42 4c 4f 42 20 6f 72  ult is a BLOB or
321a0 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20 74 68   UTF-8 string th
321b0 65 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63  en the sqlite3_c
321c0 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 0a 2a 2a  olumn_bytes().**
321d0 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine 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 20 69 6e 20 74 68 61 74 20 42 4c 4f  ytes in that BLO
32200 42 20 6f 72 20 73 74 72 69 6e 67 2e 0a 2a 2a 20  B or string..** 
32210 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69  ^If the result i
32220 73 20 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e  s a UTF-16 strin
32230 67 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  g, then sqlite3_
32240 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 63  column_bytes() c
32250 6f 6e 76 65 72 74 73 0a 2a 2a 20 74 68 65 20 73  onverts.** the s
32260 74 72 69 6e 67 20 74 6f 20 55 54 46 2d 38 20 61  tring to UTF-8 a
32270 6e 64 20 74 68 65 6e 20 72 65 74 75 72 6e 73 20  nd then returns 
32280 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  the number of by
32290 74 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  tes..** ^If the 
322a0 72 65 73 75 6c 74 20 69 73 20 61 20 6e 75 6d 65  result is a nume
322b0 72 69 63 20 76 61 6c 75 65 20 74 68 65 6e 20 73  ric value then s
322c0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
322d0 74 65 73 28 29 20 75 73 65 73 0a 2a 2a 20 5b 73  tes() uses.** [s
322e0 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28  qlite3_snprintf(
322f0 29 5d 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68  )] to convert th
32300 61 74 20 76 61 6c 75 65 20 74 6f 20 61 20 55 54  at value to a UT
32310 46 2d 38 20 73 74 72 69 6e 67 20 61 6e 64 20 72  F-8 string and r
32320 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 75  eturns.** the nu
32330 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e  mber of bytes in
32340 20 74 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a   that string..**
32350 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20   ^If the result 
32360 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 73 71  is NULL, then sq
32370 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
32380 65 73 28 29 20 72 65 74 75 72 6e 73 20 7a 65 72  es() returns zer
32390 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  o..**.** ^If the
323a0 20 72 65 73 75 6c 74 20 69 73 20 61 20 42 4c 4f   result is a BLO
323b0 42 20 6f 72 20 55 54 46 2d 31 36 20 73 74 72 69  B or UTF-16 stri
323c0 6e 67 20 74 68 65 6e 20 74 68 65 20 73 71 6c 69  ng then the sqli
323d0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
323e0 31 36 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20  16().** routine 
323f0 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62  returns the numb
32400 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74  er of bytes in t
32410 68 61 74 20 42 4c 4f 42 20 6f 72 20 73 74 72 69  hat BLOB or stri
32420 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72  ng..** ^If the r
32430 65 73 75 6c 74 20 69 73 20 61 20 55 54 46 2d 38  esult is a UTF-8
32440 20 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 73 71   string, then sq
32450 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
32460 65 73 31 36 28 29 20 63 6f 6e 76 65 72 74 73 0a  es16() converts.
32470 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 20 74 6f  ** the string to
32480 20 55 54 46 2d 31 36 20 61 6e 64 20 74 68 65 6e   UTF-16 and then
32490 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d   returns the num
324a0 62 65 72 20 6f 66 20 62 79 74 65 73 2e 0a 2a 2a  ber of bytes..**
324b0 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20   ^If the result 
324c0 69 73 20 61 20 6e 75 6d 65 72 69 63 20 76 61 6c  is a numeric val
324d0 75 65 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  ue then sqlite3_
324e0 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29  column_bytes16()
324f0 20 75 73 65 73 0a 2a 2a 20 5b 73 71 6c 69 74 65   uses.** [sqlite
32500 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 74 6f  3_snprintf()] to
32510 20 63 6f 6e 76 65 72 74 20 74 68 61 74 20 76 61   convert that va
32520 6c 75 65 20 74 6f 20 61 20 55 54 46 2d 31 36 20  lue to a UTF-16 
32530 73 74 72 69 6e 67 20 61 6e 64 20 72 65 74 75 72  string and retur
32540 6e 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72  ns.** the number
32550 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 61   of bytes in tha
32560 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66  t string..** ^If
32570 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 4e   the result is N
32580 55 4c 4c 2c 20 74 68 65 6e 20 73 71 6c 69 74 65  ULL, then sqlite
32590 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36  3_column_bytes16
325a0 28 29 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e  () returns zero.
325b0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 76 61 6c 75  .**.** ^The valu
325c0 65 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b  es returned by [
325d0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
325e0 79 74 65 73 28 29 5d 20 61 6e 64 20 0a 2a 2a 20  ytes()] and .** 
325f0 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
32600 62 79 74 65 73 31 36 28 29 5d 20 64 6f 20 6e 6f  bytes16()] do no
32610 74 20 69 6e 63 6c 75 64 65 20 74 68 65 20 7a 65  t include the ze
32620 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 73 20 61  ro terminators a
32630 74 20 74 68 65 20 65 6e 64 0a 2a 2a 20 6f 66 20  t the end.** of 
32640 74 68 65 20 73 74 72 69 6e 67 2e 20 20 5e 46 6f  the string.  ^Fo
32650 72 20 63 6c 61 72 69 74 79 3a 20 74 68 65 20 76  r clarity: the v
32660 61 6c 75 65 73 20 72 65 74 75 72 6e 65 64 20 62  alues returned b
32670 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  y.** [sqlite3_co
32680 6c 75 6d 6e 5f 62 79 74 65 73 28 29 5d 20 61 6e  lumn_bytes()] an
32690 64 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  d [sqlite3_colum
326a0 6e 5f 62 79 74 65 73 31 36 28 29 5d 20 61 72 65  n_bytes16()] are
326b0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a   the number of.*
326c0 2a 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 73  * bytes in the s
326d0 74 72 69 6e 67 2c 20 6e 6f 74 20 74 68 65 20 6e  tring, not the n
326e0 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63 74  umber of charact
326f0 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 53 74 72 69  ers..**.** ^Stri
32700 6e 67 73 20 72 65 74 75 72 6e 65 64 20 62 79 20  ngs returned by 
32710 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
32720 65 78 74 28 29 20 61 6e 64 20 73 71 6c 69 74 65  ext() and sqlite
32730 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28  3_column_text16(
32740 29 2c 0a 2a 2a 20 65 76 65 6e 20 65 6d 70 74 79  ),.** even empty
32750 20 73 74 72 69 6e 67 73 2c 20 61 72 65 20 61 6c   strings, are al
32760 77 61 79 73 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  ways zero-termin
32770 61 74 65 64 2e 20 20 5e 54 68 65 20 72 65 74 75  ated.  ^The retu
32780 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 66 72 6f 6d  rn.** value from
32790 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
327a0 62 6c 6f 62 28 29 20 66 6f 72 20 61 20 7a 65 72  blob() for a zer
327b0 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f 42 20 69 73  o-length BLOB is
327c0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e   a NULL pointer.
327d0 0a 2a 2a 0a 2a 2a 20 3c 62 3e 57 61 72 6e 69 6e  .**.** <b>Warnin
327e0 67 3a 3c 2f 62 3e 20 5e 54 68 65 20 6f 62 6a 65  g:</b> ^The obje
327f0 63 74 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b  ct returned by [
32800 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76  sqlite3_column_v
32810 61 6c 75 65 28 29 5d 20 69 73 20 61 6e 0a 2a 2a  alue()] is an.**
32820 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71   [unprotected sq
32830 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
32840 65 63 74 2e 20 20 49 6e 20 61 20 6d 75 6c 74 69  ect.  In a multi
32850 74 68 72 65 61 64 65 64 20 65 6e 76 69 72 6f 6e  threaded environ
32860 6d 65 6e 74 2c 0a 2a 2a 20 61 6e 20 75 6e 70 72  ment,.** an unpr
32870 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
32880 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 6d 61 79  value object may
32890 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 20 73 61   only be used sa
328a0 66 65 6c 79 20 77 69 74 68 0a 2a 2a 20 5b 73 71  fely with.** [sq
328b0 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65  lite3_bind_value
328c0 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
328d0 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 5d  _result_value()]
328e0 2e 0a 2a 2a 20 49 66 20 74 68 65 20 5b 75 6e 70  ..** If the [unp
328f0 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
32900 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 72  _value] object r
32910 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73  eturned by.** [s
32920 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61  qlite3_column_va
32930 6c 75 65 28 29 5d 20 69 73 20 75 73 65 64 20 69  lue()] is used i
32940 6e 20 61 6e 79 20 6f 74 68 65 72 20 77 61 79 2c  n any other way,
32950 20 69 6e 63 6c 75 64 69 6e 67 20 63 61 6c 6c 73   including calls
32960 0a 2a 2a 20 74 6f 20 72 6f 75 74 69 6e 65 73 20  .** to routines 
32970 6c 69 6b 65 20 5b 73 71 6c 69 74 65 33 5f 76 61  like [sqlite3_va
32980 6c 75 65 5f 69 6e 74 28 29 5d 2c 20 5b 73 71 6c  lue_int()], [sql
32990 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28  ite3_value_text(
329a0 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74  )],.** or [sqlit
329b0 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 29  e3_value_bytes()
329c0 5d 2c 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  ], the behavior 
329d0 69 73 20 6e 6f 74 20 74 68 72 65 61 64 73 61 66  is not threadsaf
329e0 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  e..**.** These r
329f0 6f 75 74 69 6e 65 73 20 61 74 74 65 6d 70 74 20  outines attempt 
32a00 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 65 20 76  to convert the v
32a10 61 6c 75 65 20 77 68 65 72 65 20 61 70 70 72 6f  alue where appro
32a20 70 72 69 61 74 65 2e 20 20 5e 46 6f 72 0a 2a 2a  priate.  ^For.**
32a30 20 65 78 61 6d 70 6c 65 2c 20 69 66 20 74 68 65   example, if the
32a40 20 69 6e 74 65 72 6e 61 6c 20 72 65 70 72 65 73   internal repres
32a50 65 6e 74 61 74 69 6f 6e 20 69 73 20 46 4c 4f 41  entation is FLOA
32a60 54 20 61 6e 64 20 61 20 74 65 78 74 20 72 65 73  T and a text res
32a70 75 6c 74 0a 2a 2a 20 69 73 20 72 65 71 75 65 73  ult.** is reques
32a80 74 65 64 2c 20 5b 73 71 6c 69 74 65 33 5f 73 6e  ted, [sqlite3_sn
32a90 70 72 69 6e 74 66 28 29 5d 20 69 73 20 75 73 65  printf()] is use
32aa0 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 74 6f 20  d internally to 
32ab0 70 65 72 66 6f 72 6d 20 74 68 65 0a 2a 2a 20 63  perform the.** c
32ac0 6f 6e 76 65 72 73 69 6f 6e 20 61 75 74 6f 6d 61  onversion automa
32ad0 74 69 63 61 6c 6c 79 2e 20 20 5e 28 54 68 65 20  tically.  ^(The 
32ae0 66 6f 6c 6c 6f 77 69 6e 67 20 74 61 62 6c 65 20  following table 
32af0 64 65 74 61 69 6c 73 20 74 68 65 20 63 6f 6e 76  details the conv
32b00 65 72 73 69 6f 6e 73 0a 2a 2a 20 74 68 61 74 20  ersions.** that 
32b10 61 72 65 20 61 70 70 6c 69 65 64 3a 0a 2a 2a 0a  are applied:.**.
32b20 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a  ** <blockquote>.
32b30 2a 2a 20 3c 74 61 62 6c 65 20 62 6f 72 64 65 72  ** <table border
32b40 3d 22 31 22 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68  ="1">.** <tr><th
32b50 3e 20 49 6e 74 65 72 6e 61 6c 3c 62 72 3e 54 79  > Internal<br>Ty
32b60 70 65 20 3c 74 68 3e 20 52 65 71 75 65 73 74 65  pe <th> Requeste
32b70 64 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e 20 20  d<br>Type <th>  
32b80 43 6f 6e 76 65 72 73 69 6f 6e 0a 2a 2a 0a 2a 2a  Conversion.**.**
32b90 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20   <tr><td>  NULL 
32ba0 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20     <td> INTEGER 
32bb0 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73    <td> Result is
32bc0 20 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20   0.** <tr><td>  
32bd0 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 46 4c  NULL    <td>  FL
32be0 4f 41 54 20 20 20 20 3c 74 64 3e 20 52 65 73 75  OAT    <td> Resu
32bf0 6c 74 20 69 73 20 30 2e 30 0a 2a 2a 20 3c 74 72  lt is 0.0.** <tr
32c00 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c  ><td>  NULL    <
32c10 74 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74  td>   TEXT    <t
32c20 64 3e 20 52 65 73 75 6c 74 20 69 73 20 61 20 4e  d> Result is a N
32c30 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c  ULL pointer.** <
32c40 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20  tr><td>  NULL   
32c50 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20   <td>   BLOB    
32c60 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 61  <td> Result is a
32c70 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a   NULL pointer.**
32c80 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45   <tr><td> INTEGE
32c90 52 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20  R  <td>  FLOAT  
32ca0 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 66    <td> Convert f
32cb0 72 6f 6d 20 69 6e 74 65 67 65 72 20 74 6f 20 66  rom integer to f
32cc0 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  loat.** <tr><td>
32cd0 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20   INTEGER  <td>  
32ce0 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41 53   TEXT    <td> AS
32cf0 43 49 49 20 72 65 6e 64 65 72 69 6e 67 20 6f 66  CII rendering of
32d00 20 74 68 65 20 69 6e 74 65 67 65 72 0a 2a 2a 20   the integer.** 
32d10 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52  <tr><td> INTEGER
32d20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20    <td>   BLOB   
32d30 20 3c 74 64 3e 20 53 61 6d 65 20 61 73 20 49 4e   <td> Same as IN
32d40 54 45 47 45 52 2d 3e 54 45 58 54 0a 2a 2a 20 3c  TEGER->TEXT.** <
32d50 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20  tr><td>  FLOAT  
32d60 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20   <td> INTEGER   
32d70 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20 49  <td> [CAST] to I
32d80 4e 54 45 47 45 52 0a 2a 2a 20 3c 74 72 3e 3c 74  NTEGER.** <tr><t
32d90 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e  d>  FLOAT   <td>
32da0 20 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20     TEXT    <td> 
32db0 41 53 43 49 49 20 72 65 6e 64 65 72 69 6e 67 20  ASCII rendering 
32dc0 6f 66 20 74 68 65 20 66 6c 6f 61 74 0a 2a 2a 20  of the float.** 
32dd0 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20  <tr><td>  FLOAT 
32de0 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20    <td>   BLOB   
32df0 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20   <td> [CAST] to 
32e00 42 4c 4f 42 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  BLOB.** <tr><td>
32e10 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 49    TEXT    <td> I
32e20 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 5b 43  NTEGER   <td> [C
32e30 41 53 54 5d 20 74 6f 20 49 4e 54 45 47 45 52 0a  AST] to INTEGER.
32e40 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58  ** <tr><td>  TEX
32e50 54 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54  T    <td>  FLOAT
32e60 20 20 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20      <td> [CAST] 
32e70 74 6f 20 52 45 41 4c 0a 2a 2a 20 3c 74 72 3e 3c  to REAL.** <tr><
32e80 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64  td>  TEXT    <td
32e90 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e  >   BLOB    <td>
32ea0 20 4e 6f 20 63 68 61 6e 67 65 0a 2a 2a 20 3c 74   No change.** <t
32eb0 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20  r><td>  BLOB    
32ec0 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c  <td> INTEGER   <
32ed0 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20 49 4e  td> [CAST] to IN
32ee0 54 45 47 45 52 0a 2a 2a 20 3c 74 72 3e 3c 74 64  TEGER.** <tr><td
32ef0 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20  >  BLOB    <td> 
32f00 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 5b   FLOAT    <td> [
32f10 43 41 53 54 5d 20 74 6f 20 52 45 41 4c 0a 2a 2a  CAST] to REAL.**
32f20 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20   <tr><td>  BLOB 
32f30 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20     <td>   TEXT  
32f40 20 20 3c 74 64 3e 20 41 64 64 20 61 20 7a 65 72    <td> Add a zer
32f50 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20 69 66 20  o terminator if 
32f60 6e 65 65 64 65 64 0a 2a 2a 20 3c 2f 74 61 62 6c  needed.** </tabl
32f70 65 3e 0a 2a 2a 20 3c 2f 62 6c 6f 63 6b 71 75 6f  e>.** </blockquo
32f80 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65  te>)^.**.** Note
32f90 20 74 68 61 74 20 77 68 65 6e 20 74 79 70 65 20   that when type 
32fa0 63 6f 6e 76 65 72 73 69 6f 6e 73 20 6f 63 63 75  conversions occu
32fb0 72 2c 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75  r, pointers retu
32fc0 72 6e 65 64 20 62 79 20 70 72 69 6f 72 0a 2a 2a  rned by prior.**
32fd0 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65   calls to sqlite
32fe0 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c  3_column_blob(),
32ff0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
33000 74 65 78 74 28 29 2c 20 61 6e 64 2f 6f 72 0a 2a  text(), and/or.*
33010 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  * sqlite3_column
33020 5f 74 65 78 74 31 36 28 29 20 6d 61 79 20 62 65  _text16() may be
33030 20 69 6e 76 61 6c 69 64 61 74 65 64 2e 0a 2a 2a   invalidated..**
33040 20 54 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e   Type conversion
33050 73 20 61 6e 64 20 70 6f 69 6e 74 65 72 20 69 6e  s and pointer in
33060 76 61 6c 69 64 61 74 69 6f 6e 73 20 6d 69 67 68  validations migh
33070 74 20 6f 63 63 75 72 0a 2a 2a 20 69 6e 20 74 68  t occur.** in th
33080 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 63 61 73 65  e following case
33090 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  s:.**.** <ul>.**
330a0 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74 69 61   <li> The initia
330b0 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 61 20 42  l content is a B
330c0 4c 4f 42 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  LOB and sqlite3_
330d0 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 6f 72  column_text() or
330e0 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 74 65 33  .**      sqlite3
330f0 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29  _column_text16()
33100 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 41 20 7a   is called.  A z
33110 65 72 6f 2d 74 65 72 6d 69 6e 61 74 6f 72 20 6d  ero-terminator m
33120 69 67 68 74 0a 2a 2a 20 20 20 20 20 20 6e 65 65  ight.**      nee
33130 64 20 74 6f 20 62 65 20 61 64 64 65 64 20 74 6f  d to be added to
33140 20 74 68 65 20 73 74 72 69 6e 67 2e 3c 2f 6c 69   the string.</li
33150 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e  >.** <li> The in
33160 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73  itial content is
33170 20 55 54 46 2d 38 20 74 65 78 74 20 61 6e 64 20   UTF-8 text and 
33180 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
33190 79 74 65 73 31 36 28 29 20 6f 72 0a 2a 2a 20 20  ytes16() or.**  
331a0 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75      sqlite3_colu
331b0 6d 6e 5f 74 65 78 74 31 36 28 29 20 69 73 20 63  mn_text16() is c
331c0 61 6c 6c 65 64 2e 20 20 54 68 65 20 63 6f 6e 74  alled.  The cont
331d0 65 6e 74 20 6d 75 73 74 20 62 65 20 63 6f 6e 76  ent must be conv
331e0 65 72 74 65 64 0a 2a 2a 20 20 20 20 20 20 74 6f  erted.**      to
331f0 20 55 54 46 2d 31 36 2e 3c 2f 6c 69 3e 0a 2a 2a   UTF-16.</li>.**
33200 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74 69 61   <li> The initia
33210 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 55 54 46  l content is UTF
33220 2d 31 36 20 74 65 78 74 20 61 6e 64 20 73 71 6c  -16 text and sql
33230 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
33240 73 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73  s() or.**      s
33250 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
33260 78 74 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20  xt() is called. 
33270 20 54 68 65 20 63 6f 6e 74 65 6e 74 20 6d 75 73   The content mus
33280 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64 0a 2a  t be converted.*
33290 2a 20 20 20 20 20 20 74 6f 20 55 54 46 2d 38 2e  *      to UTF-8.
332a0 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a  </li>.** </ul>.*
332b0 2a 0a 2a 2a 20 5e 43 6f 6e 76 65 72 73 69 6f 6e  *.** ^Conversion
332c0 73 20 62 65 74 77 65 65 6e 20 55 54 46 2d 31 36  s between UTF-16
332d0 62 65 20 61 6e 64 20 55 54 46 2d 31 36 6c 65 20  be and UTF-16le 
332e0 61 72 65 20 61 6c 77 61 79 73 20 64 6f 6e 65 20  are always done 
332f0 69 6e 20 70 6c 61 63 65 20 61 6e 64 20 64 6f 0a  in place and do.
33300 2a 2a 20 6e 6f 74 20 69 6e 76 61 6c 69 64 61 74  ** not invalidat
33310 65 20 61 20 70 72 69 6f 72 20 70 6f 69 6e 74 65  e a prior pointe
33320 72 2c 20 74 68 6f 75 67 68 20 6f 66 20 63 6f 75  r, though of cou
33330 72 73 65 20 74 68 65 20 63 6f 6e 74 65 6e 74 20  rse the content 
33340 6f 66 20 74 68 65 20 62 75 66 66 65 72 0a 2a 2a  of the buffer.**
33350 20 74 68 61 74 20 74 68 65 20 70 72 69 6f 72 20   that the prior 
33360 70 6f 69 6e 74 65 72 20 72 65 66 65 72 65 6e 63  pointer referenc
33370 65 73 20 77 69 6c 6c 20 68 61 76 65 20 62 65 65  es will have bee
33380 6e 20 6d 6f 64 69 66 69 65 64 2e 20 20 4f 74 68  n modified.  Oth
33390 65 72 20 6b 69 6e 64 73 0a 2a 2a 20 6f 66 20 63  er kinds.** of c
333a0 6f 6e 76 65 72 73 69 6f 6e 20 61 72 65 20 64 6f  onversion are do
333b0 6e 65 20 69 6e 20 70 6c 61 63 65 20 77 68 65 6e  ne in place when
333c0 20 69 74 20 69 73 20 70 6f 73 73 69 62 6c 65 2c   it is possible,
333d0 20 62 75 74 20 73 6f 6d 65 74 69 6d 65 73 20 74   but sometimes t
333e0 68 65 79 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 70  hey.** are not p
333f0 6f 73 73 69 62 6c 65 20 61 6e 64 20 69 6e 20 74  ossible and in t
33400 68 6f 73 65 20 63 61 73 65 73 20 70 72 69 6f 72  hose cases prior
33410 20 70 6f 69 6e 74 65 72 73 20 61 72 65 20 69 6e   pointers are in
33420 76 61 6c 69 64 61 74 65 64 2e 0a 2a 2a 0a 2a 2a  validated..**.**
33430 20 54 68 65 20 73 61 66 65 73 74 20 70 6f 6c 69   The safest poli
33440 63 79 20 69 73 20 74 6f 20 69 6e 76 6f 6b 65 20  cy is to invoke 
33450 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a  these routines.*
33460 2a 20 69 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20  * in one of the 
33470 66 6f 6c 6c 6f 77 69 6e 67 20 77 61 79 73 3a 0a  following ways:.
33480 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 3c  **.** <ul>.**  <
33490 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  li>sqlite3_colum
334a0 6e 5f 74 65 78 74 28 29 20 66 6f 6c 6c 6f 77 65  n_text() followe
334b0 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c  d by sqlite3_col
334c0 75 6d 6e 5f 62 79 74 65 73 28 29 3c 2f 6c 69 3e  umn_bytes()</li>
334d0 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33  .**  <li>sqlite3
334e0 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66  _column_blob() f
334f0 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74  ollowed by sqlit
33500 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
33510 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73  )</li>.**  <li>s
33520 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
33530 78 74 31 36 28 29 20 66 6f 6c 6c 6f 77 65 64 20  xt16() followed 
33540 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  by sqlite3_colum
33550 6e 5f 62 79 74 65 73 31 36 28 29 3c 2f 6c 69 3e  n_bytes16()</li>
33560 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20  .** </ul>.**.** 
33570 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20  In other words, 
33580 79 6f 75 20 73 68 6f 75 6c 64 20 63 61 6c 6c 20  you should call 
33590 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
335a0 65 78 74 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65  ext(),.** sqlite
335b0 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c  3_column_blob(),
335c0 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   or sqlite3_colu
335d0 6d 6e 5f 74 65 78 74 31 36 28 29 20 66 69 72 73  mn_text16() firs
335e0 74 20 74 6f 20 66 6f 72 63 65 20 74 68 65 20 72  t to force the r
335f0 65 73 75 6c 74 0a 2a 2a 20 69 6e 74 6f 20 74 68  esult.** into th
33600 65 20 64 65 73 69 72 65 64 20 66 6f 72 6d 61 74  e desired format
33610 2c 20 74 68 65 6e 20 69 6e 76 6f 6b 65 20 73 71  , then invoke sq
33620 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
33630 65 73 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74  es() or.** sqlit
33640 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
33650 36 28 29 20 74 6f 20 66 69 6e 64 20 74 68 65 20  6() to find the 
33660 73 69 7a 65 20 6f 66 20 74 68 65 20 72 65 73 75  size of the resu
33670 6c 74 2e 20 20 44 6f 20 6e 6f 74 20 6d 69 78 20  lt.  Do not mix 
33680 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 73 71 6c 69  calls.** to sqli
33690 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
336a0 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c  ) or sqlite3_col
336b0 75 6d 6e 5f 62 6c 6f 62 28 29 20 77 69 74 68 20  umn_blob() with 
336c0 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 73 71 6c 69  calls to.** sqli
336d0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
336e0 31 36 28 29 2c 20 61 6e 64 20 64 6f 20 6e 6f 74  16(), and do not
336f0 20 6d 69 78 20 63 61 6c 6c 73 20 74 6f 20 73 71   mix calls to sq
33700 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
33710 74 31 36 28 29 0a 2a 2a 20 77 69 74 68 20 63 61  t16().** with ca
33720 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  lls to sqlite3_c
33730 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 2e 0a 2a  olumn_bytes()..*
33740 2a 0a 2a 2a 20 5e 54 68 65 20 70 6f 69 6e 74 65  *.** ^The pointe
33750 72 73 20 72 65 74 75 72 6e 65 64 20 61 72 65 20  rs returned are 
33760 76 61 6c 69 64 20 75 6e 74 69 6c 20 61 20 74 79  valid until a ty
33770 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20 6f 63  pe conversion oc
33780 63 75 72 73 20 61 73 0a 2a 2a 20 64 65 73 63 72  curs as.** descr
33790 69 62 65 64 20 61 62 6f 76 65 2c 20 6f 72 20 75  ibed above, or u
337a0 6e 74 69 6c 20 5b 73 71 6c 69 74 65 33 5f 73 74  ntil [sqlite3_st
337b0 65 70 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  ep()] or [sqlite
337c0 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a  3_reset()] or.**
337d0 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
337e0 7a 65 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 2e  ze()] is called.
337f0 20 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20 73 70    ^The memory sp
33800 61 63 65 20 75 73 65 64 20 74 6f 20 68 6f 6c 64  ace used to hold
33810 20 73 74 72 69 6e 67 73 0a 2a 2a 20 61 6e 64 20   strings.** and 
33820 42 4c 4f 42 73 20 69 73 20 66 72 65 65 64 20 61  BLOBs is freed a
33830 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20 44  utomatically.  D
33840 6f 20 3c 65 6d 3e 6e 6f 74 3c 2f 65 6d 3e 20 70  o <em>not</em> p
33850 61 73 73 20 74 68 65 20 70 6f 69 6e 74 65 72 73  ass the pointers
33860 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 66 72 6f   returned.** fro
33870 6d 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  m [sqlite3_colum
33880 6e 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c 69  n_blob()], [sqli
33890 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
338a0 29 5d 2c 20 65 74 63 2e 20 69 6e 74 6f 0a 2a 2a  )], etc. into.**
338b0 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
338c0 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 61 20  ]..**.** ^(If a 
338d0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
338e0 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 64  n error occurs d
338f0 75 72 69 6e 67 20 74 68 65 20 65 76 61 6c 75 61  uring the evalua
33900 74 69 6f 6e 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f  tion of any.** o
33910 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  f these routines
33920 2c 20 61 20 64 65 66 61 75 6c 74 20 76 61 6c 75  , a default valu
33930 65 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20  e is returned.  
33940 54 68 65 20 64 65 66 61 75 6c 74 20 76 61 6c 75  The default valu
33950 65 0a 2a 2a 20 69 73 20 65 69 74 68 65 72 20 74  e.** is either t
33960 68 65 20 69 6e 74 65 67 65 72 20 30 2c 20 74 68  he integer 0, th
33970 65 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74  e floating point
33980 20 6e 75 6d 62 65 72 20 30 2e 30 2c 20 6f 72 20   number 0.0, or 
33990 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65  a NULL.** pointe
339a0 72 2e 20 20 53 75 62 73 65 71 75 65 6e 74 20 63  r.  Subsequent c
339b0 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33  alls to [sqlite3
339c0 5f 65 72 72 63 6f 64 65 28 29 5d 20 77 69 6c 6c  _errcode()] will
339d0 20 72 65 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49   return.** [SQLI
339e0 54 45 5f 4e 4f 4d 45 4d 5d 2e 29 5e 0a 2a 2f 0a  TE_NOMEM].)^.*/.
339f0 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74  SQLITE_API const
33a00 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63   void *sqlite3_c
33a10 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 73 71 6c 69 74  olumn_blob(sqlit
33a20 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
33a30 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  ol);.SQLITE_API 
33a40 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  int sqlite3_colu
33a50 6d 6e 5f 62 79 74 65 73 28 73 71 6c 69 74 65 33  mn_bytes(sqlite3
33a60 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
33a70 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  );.SQLITE_API in
33a80 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  t sqlite3_column
33a90 5f 62 79 74 65 73 31 36 28 73 71 6c 69 74 65 33  _bytes16(sqlite3
33aa0 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
33ab0 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 64 6f  );.SQLITE_API do
33ac0 75 62 6c 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c  uble sqlite3_col
33ad0 75 6d 6e 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74  umn_double(sqlit
33ae0 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
33af0 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  ol);.SQLITE_API 
33b00 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  int sqlite3_colu
33b10 6d 6e 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 73  mn_int(sqlite3_s
33b20 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
33b30 0a 53 51 4c 49 54 45 5f 41 50 49 20 73 71 6c 69  .SQLITE_API sqli
33b40 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65  te3_int64 sqlite
33b50 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 36 34 28 73  3_column_int64(s
33b60 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
33b70 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f  t iCol);.SQLITE_
33b80 41 50 49 20 63 6f 6e 73 74 20 75 6e 73 69 67 6e  API const unsign
33b90 65 64 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  ed char *sqlite3
33ba0 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 73 71 6c  _column_text(sql
33bb0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
33bc0 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50  iCol);.SQLITE_AP
33bd0 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  I const void *sq
33be0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
33bf0 74 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  t16(sqlite3_stmt
33c00 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51  *, int iCol);.SQ
33c10 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
33c20 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65  ite3_column_type
33c30 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
33c40 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54  int iCol);.SQLIT
33c50 45 5f 41 50 49 20 73 71 6c 69 74 65 33 5f 76 61  E_API sqlite3_va
33c60 6c 75 65 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  lue *sqlite3_col
33c70 75 6d 6e 5f 76 61 6c 75 65 28 73 71 6c 69 74 65  umn_value(sqlite
33c80 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
33c90 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  l);../*.** CAPI3
33ca0 52 45 46 3a 20 44 65 73 74 72 6f 79 20 41 20 50  REF: Destroy A P
33cb0 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e  repared Statemen
33cc0 74 20 4f 62 6a 65 63 74 0a 2a 2a 20 44 45 53 54  t Object.** DEST
33cd0 52 55 43 54 4f 52 3a 20 73 71 6c 69 74 65 33 5f  RUCTOR: sqlite3_
33ce0 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  stmt.**.** ^The 
33cf0 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
33d00 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63  () function is c
33d10 61 6c 6c 65 64 20 74 6f 20 64 65 6c 65 74 65 20  alled to delete 
33d20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  a [prepared stat
33d30 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 49 66 20 74  ement]..** ^If t
33d40 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 65  he most recent e
33d50 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20 74 68 65  valuation of the
33d60 20 73 74 61 74 65 6d 65 6e 74 20 65 6e 63 6f 75   statement encou
33d70 6e 74 65 72 65 64 20 6e 6f 20 65 72 72 6f 72 73  ntered no errors
33d80 0a 2a 2a 20 6f 72 20 69 66 20 74 68 65 20 73 74  .** or if the st
33d90 61 74 65 6d 65 6e 74 20 69 73 20 6e 65 76 65 72  atement is never
33da0 20 62 65 65 6e 20 65 76 61 6c 75 61 74 65 64 2c   been evaluated,
33db0 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 66 69   then sqlite3_fi
33dc0 6e 61 6c 69 7a 65 28 29 20 72 65 74 75 72 6e 73  nalize() returns
33dd0 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f 4b 2e 20 20  .** SQLITE_OK.  
33de0 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63  ^If the most rec
33df0 65 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f  ent evaluation o
33e00 66 20 73 74 61 74 65 6d 65 6e 74 20 53 20 66 61  f statement S fa
33e10 69 6c 65 64 2c 20 74 68 65 6e 0a 2a 2a 20 73 71  iled, then.** sq
33e20 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 53  lite3_finalize(S
33e30 29 20 72 65 74 75 72 6e 73 20 74 68 65 20 61 70  ) returns the ap
33e40 70 72 6f 70 72 69 61 74 65 20 5b 65 72 72 6f 72  propriate [error
33e50 20 63 6f 64 65 5d 20 6f 72 0a 2a 2a 20 5b 65 78   code] or.** [ex
33e60 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64  tended error cod
33e70 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  e]..**.** ^The s
33e80 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
33e90 53 29 20 72 6f 75 74 69 6e 65 20 63 61 6e 20 62  S) routine can b
33ea0 65 20 63 61 6c 6c 65 64 20 61 74 20 61 6e 79 20  e called at any 
33eb0 70 6f 69 6e 74 20 64 75 72 69 6e 67 0a 2a 2a 20  point during.** 
33ec0 74 68 65 20 6c 69 66 65 20 63 79 63 6c 65 20 6f  the life cycle o
33ed0 66 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  f [prepared stat
33ee0 65 6d 65 6e 74 5d 20 53 3a 0a 2a 2a 20 62 65 66  ement] S:.** bef
33ef0 6f 72 65 20 73 74 61 74 65 6d 65 6e 74 20 53 20  ore statement S 
33f00 69 73 20 65 76 65 72 20 65 76 61 6c 75 61 74 65  is ever evaluate
33f10 64 2c 20 61 66 74 65 72 0a 2a 2a 20 6f 6e 65 20  d, after.** one 
33f20 6f 72 20 6d 6f 72 65 20 63 61 6c 6c 73 20 74 6f  or more calls to
33f30 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
33f40 29 5d 2c 20 6f 72 20 61 66 74 65 72 20 61 6e 79  )], or after any
33f50 20 63 61 6c 6c 0a 2a 2a 20 74 6f 20 5b 73 71 6c   call.** to [sql
33f60 69 74 65 33 5f 73 74 65 70 28 29 5d 20 72 65 67  ite3_step()] reg
33f70 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68  ardless of wheth
33f80 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 73 74  er or not the st
33f90 61 74 65 6d 65 6e 74 20 68 61 73 0a 2a 2a 20 63  atement has.** c
33fa0 6f 6d 70 6c 65 74 65 64 20 65 78 65 63 75 74 69  ompleted executi
33fb0 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 76 6f 6b  on..**.** ^Invok
33fc0 69 6e 67 20 73 71 6c 69 74 65 33 5f 66 69 6e 61  ing sqlite3_fina
33fd0 6c 69 7a 65 28 29 20 6f 6e 20 61 20 4e 55 4c 4c  lize() on a NULL
33fe0 20 70 6f 69 6e 74 65 72 20 69 73 20 61 20 68 61   pointer is a ha
33ff0 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2a  rmless no-op..**
34000 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74  .** The applicat
34010 69 6f 6e 20 6d 75 73 74 20 66 69 6e 61 6c 69 7a  ion must finaliz
34020 65 20 65 76 65 72 79 20 5b 70 72 65 70 61 72 65  e every [prepare
34030 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 6e 20  d statement] in 
34040 6f 72 64 65 72 20 74 6f 20 61 76 6f 69 64 0a 2a  order to avoid.*
34050 2a 20 72 65 73 6f 75 72 63 65 20 6c 65 61 6b 73  * resource leaks
34060 2e 20 20 49 74 20 69 73 20 61 20 67 72 69 65 76  .  It is a griev
34070 6f 75 73 20 65 72 72 6f 72 20 66 6f 72 20 74 68  ous error for th
34080 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f  e application to
34090 20 74 72 79 20 74 6f 20 75 73 65 0a 2a 2a 20 61   try to use.** a
340a0 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
340b0 65 6e 74 20 61 66 74 65 72 20 69 74 20 68 61 73  ent after it has
340c0 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64 2e   been finalized.
340d0 20 20 41 6e 79 20 75 73 65 20 6f 66 20 61 20 70    Any use of a p
340e0 72 65 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 65  repared.** state
340f0 6d 65 6e 74 20 61 66 74 65 72 20 69 74 20 68 61  ment after it ha
34100 73 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64  s been finalized
34110 20 63 61 6e 20 72 65 73 75 6c 74 20 69 6e 20 75   can result in u
34120 6e 64 65 66 69 6e 65 64 20 61 6e 64 0a 2a 2a 20  ndefined and.** 
34130 75 6e 64 65 73 69 72 61 62 6c 65 20 62 65 68 61  undesirable beha
34140 76 69 6f 72 20 73 75 63 68 20 61 73 20 73 65 67  vior such as seg
34150 66 61 75 6c 74 73 20 61 6e 64 20 68 65 61 70 20  faults and heap 
34160 63 6f 72 72 75 70 74 69 6f 6e 2e 0a 2a 2f 0a 53  corruption..*/.S
34170 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
34180 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 73  lite3_finalize(s
34190 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74  qlite3_stmt *pSt
341a0 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  mt);../*.** CAPI
341b0 33 52 45 46 3a 20 52 65 73 65 74 20 41 20 50 72  3REF: Reset A Pr
341c0 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74  epared Statement
341d0 20 4f 62 6a 65 63 74 0a 2a 2a 20 4d 45 54 48 4f   Object.** METHO
341e0 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a  D: sqlite3_stmt.
341f0 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
34200 33 5f 72 65 73 65 74 28 29 20 66 75 6e 63 74 69  3_reset() functi
34210 6f 6e 20 69 73 20 63 61 6c 6c 65 64 20 74 6f 20  on is called to 
34220 72 65 73 65 74 20 61 20 5b 70 72 65 70 61 72 65  reset a [prepare
34230 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20  d statement].** 
34240 6f 62 6a 65 63 74 20 62 61 63 6b 20 74 6f 20 69  object back to i
34250 74 73 20 69 6e 69 74 69 61 6c 20 73 74 61 74 65  ts initial state
34260 2c 20 72 65 61 64 79 20 74 6f 20 62 65 20 72 65  , ready to be re
34270 2d 65 78 65 63 75 74 65 64 2e 0a 2a 2a 20 5e 41  -executed..** ^A
34280 6e 79 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ny SQL statement
34290 20 76 61 72 69 61 62 6c 65 73 20 74 68 61 74 20   variables that 
342a0 68 61 64 20 76 61 6c 75 65 73 20 62 6f 75 6e 64  had values bound
342b0 20 74 6f 20 74 68 65 6d 20 75 73 69 6e 67 0a 2a   to them using.*
342c0 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62  * the [sqlite3_b
342d0 69 6e 64 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74  ind_blob | sqlit
342e0 65 33 5f 62 69 6e 64 5f 2a 28 29 20 41 50 49 5d  e3_bind_*() API]
342f0 20 72 65 74 61 69 6e 20 74 68 65 69 72 20 76 61   retain their va
34300 6c 75 65 73 2e 0a 2a 2a 20 55 73 65 20 5b 73 71  lues..** Use [sq
34310 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64  lite3_clear_bind
34320 69 6e 67 73 28 29 5d 20 74 6f 20 72 65 73 65 74  ings()] to reset
34330 20 74 68 65 20 62 69 6e 64 69 6e 67 73 2e 0a 2a   the bindings..*
34340 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74  *.** ^The [sqlit
34350 65 33 5f 72 65 73 65 74 28 53 29 5d 20 69 6e 74  e3_reset(S)] int
34360 65 72 66 61 63 65 20 72 65 73 65 74 73 20 74 68  erface resets th
34370 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
34380 65 6d 65 6e 74 5d 20 53 0a 2a 2a 20 62 61 63 6b  ement] S.** back
34390 20 74 6f 20 74 68 65 20 62 65 67 69 6e 6e 69 6e   to the beginnin
343a0 67 20 6f 66 20 69 74 73 20 70 72 6f 67 72 61 6d  g of its program
343b0 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
343c0 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c  most recent call
343d0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65   to [sqlite3_ste
343e0 70 28 53 29 5d 20 66 6f 72 20 74 68 65 0a 2a 2a  p(S)] for the.**
343f0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
34400 6d 65 6e 74 5d 20 53 20 72 65 74 75 72 6e 65 64  ment] S returned
34410 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 6f 72   [SQLITE_ROW] or
34420 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c 0a   [SQLITE_DONE],.
34430 2a 2a 20 6f 72 20 69 66 20 5b 73 71 6c 69 74 65  ** or if [sqlite
34440 33 5f 73 74 65 70 28 53 29 5d 20 68 61 73 20 6e  3_step(S)] has n
34450 65 76 65 72 20 62 65 66 6f 72 65 20 62 65 65 6e  ever before been
34460 20 63 61 6c 6c 65 64 20 6f 6e 20 53 2c 0a 2a 2a   called on S,.**
34470 20 74 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 72   then [sqlite3_r
34480 65 73 65 74 28 53 29 5d 20 72 65 74 75 72 6e 73  eset(S)] returns
34490 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a   [SQLITE_OK]..**
344a0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73 74  .** ^If the most
344b0 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20   recent call to 
344c0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29  [sqlite3_step(S)
344d0 5d 20 66 6f 72 20 74 68 65 0a 2a 2a 20 5b 70 72  ] for the.** [pr
344e0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
344f0 5d 20 53 20 69 6e 64 69 63 61 74 65 64 20 61 6e  ] S indicated an
34500 20 65 72 72 6f 72 2c 20 74 68 65 6e 0a 2a 2a 20   error, then.** 
34510 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53  [sqlite3_reset(S
34520 29 5d 20 72 65 74 75 72 6e 73 20 61 6e 20 61 70  )] returns an ap
34530 70 72 6f 70 72 69 61 74 65 20 5b 65 72 72 6f 72  propriate [error
34540 20 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54   code]..**.** ^T
34550 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  he [sqlite3_rese
34560 74 28 53 29 5d 20 69 6e 74 65 72 66 61 63 65 20  t(S)] interface 
34570 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67 65 20  does not change 
34580 74 68 65 20 76 61 6c 75 65 73 0a 2a 2a 20 6f 66  the values.** of
34590 20 61 6e 79 20 5b 73 71 6c 69 74 65 33 5f 62 69   any [sqlite3_bi
345a0 6e 64 5f 62 6c 6f 62 7c 62 69 6e 64 69 6e 67 73  nd_blob|bindings
345b0 5d 20 6f 6e 20 74 68 65 20 5b 70 72 65 70 61 72  ] on the [prepar
345c0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 2e  ed statement] S.
345d0 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .*/.SQLITE_API i
345e0 6e 74 20 73 71 6c 69 74 65 33 5f 72 65 73 65 74  nt sqlite3_reset
345f0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70  (sqlite3_stmt *p
34600 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  Stmt);../*.** CA
34610 50 49 33 52 45 46 3a 20 43 72 65 61 74 65 20 4f  PI3REF: Create O
34620 72 20 52 65 64 65 66 69 6e 65 20 53 51 4c 20 46  r Redefine SQL F
34630 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 4b 45 59 57  unctions.** KEYW
34640 4f 52 44 53 3a 20 7b 66 75 6e 63 74 69 6f 6e 20  ORDS: {function 
34650 63 72 65 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65  creation routine
34660 73 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  s}.** KEYWORDS: 
34670 7b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66  {application-def
34680 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f  ined SQL functio
34690 6e 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  n}.** KEYWORDS: 
346a0 7b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66  {application-def
346b0 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f  ined SQL functio
346c0 6e 73 7d 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  ns}.** METHOD: s
346d0 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68  qlite3.**.** ^Th
346e0 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 28 63  ese functions (c
346f0 6f 6c 6c 65 63 74 69 76 65 6c 79 20 6b 6e 6f 77  ollectively know
34700 6e 20 61 73 20 22 66 75 6e 63 74 69 6f 6e 20 63  n as "function c
34710 72 65 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73  reation routines
34720 22 29 0a 2a 2a 20 61 72 65 20 75 73 65 64 20 74  ").** are used t
34730 6f 20 61 64 64 20 53 51 4c 20 66 75 6e 63 74 69  o add SQL functi
34740 6f 6e 73 20 6f 72 20 61 67 67 72 65 67 61 74 65  ons or aggregate
34750 73 20 6f 72 20 74 6f 20 72 65 64 65 66 69 6e 65  s or to redefine
34760 20 74 68 65 20 62 65 68 61 76 69 6f 72 0a 2a 2a   the behavior.**
34770 20 6f 66 20 65 78 69 73 74 69 6e 67 20 53 51 4c   of existing SQL
34780 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20 61 67   functions or ag
34790 67 72 65 67 61 74 65 73 2e 20 20 54 68 65 20 6f  gregates.  The o
347a0 6e 6c 79 20 64 69 66 66 65 72 65 6e 63 65 73 20  nly differences 
347b0 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65 73 65  between.** these
347c0 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 74 68   routines are th
347d0 65 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 20  e text encoding 
347e0 65 78 70 65 63 74 65 64 20 66 6f 72 0a 2a 2a 20  expected for.** 
347f0 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  the second param
34800 65 74 65 72 20 28 74 68 65 20 6e 61 6d 65 20 6f  eter (the name o
34810 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 62  f the function b
34820 65 69 6e 67 20 63 72 65 61 74 65 64 29 0a 2a 2a  eing created).**
34830 20 61 6e 64 20 74 68 65 20 70 72 65 73 65 6e 63   and the presenc
34840 65 20 6f 72 20 61 62 73 65 6e 63 65 20 6f 66 20  e or absence of 
34850 61 20 64 65 73 74 72 75 63 74 6f 72 20 63 61 6c  a destructor cal
34860 6c 62 61 63 6b 20 66 6f 72 0a 2a 2a 20 74 68 65  lback for.** the
34870 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74   application dat
34880 61 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a  a pointer..**.**
34890 20 5e 54 68 65 20 66 69 72 73 74 20 70 61 72 61   ^The first para
348a0 6d 65 74 65 72 20 69 73 20 74 68 65 20 5b 64 61  meter is the [da
348b0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
348c0 6e 5d 20 74 6f 20 77 68 69 63 68 20 74 68 65 20  n] to which the 
348d0 53 51 4c 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  SQL.** function 
348e0 69 73 20 74 6f 20 62 65 20 61 64 64 65 64 2e 20  is to be added. 
348f0 20 5e 49 66 20 61 6e 20 61 70 70 6c 69 63 61 74   ^If an applicat
34900 69 6f 6e 20 75 73 65 73 20 6d 6f 72 65 20 74 68  ion uses more th
34910 61 6e 20 6f 6e 65 20 64 61 74 61 62 61 73 65 0a  an one database.
34920 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68  ** connection th
34930 65 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  en application-d
34940 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74  efined SQL funct
34950 69 6f 6e 73 20 6d 75 73 74 20 62 65 20 61 64 64  ions must be add
34960 65 64 0a 2a 2a 20 74 6f 20 65 61 63 68 20 64 61  ed.** to each da
34970 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
34980 6e 20 73 65 70 61 72 61 74 65 6c 79 2e 0a 2a 2a  n separately..**
34990 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64 20  .** ^The second 
349a0 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65  parameter is the
349b0 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 53 51 4c   name of the SQL
349c0 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20   function to be 
349d0 63 72 65 61 74 65 64 20 6f 72 0a 2a 2a 20 72 65  created or.** re
349e0 64 65 66 69 6e 65 64 2e 20 20 5e 54 68 65 20 6c  defined.  ^The l
349f0 65 6e 67 74 68 20 6f 66 20 74 68 65 20 6e 61 6d  ength of the nam
34a00 65 20 69 73 20 6c 69 6d 69 74 65 64 20 74 6f 20  e is limited to 
34a10 32 35 35 20 62 79 74 65 73 20 69 6e 20 61 20 55  255 bytes in a U
34a20 54 46 2d 38 0a 2a 2a 20 72 65 70 72 65 73 65 6e  TF-8.** represen
34a30 74 61 74 69 6f 6e 2c 20 65 78 63 6c 75 73 69 76  tation, exclusiv
34a40 65 20 6f 66 20 74 68 65 20 7a 65 72 6f 2d 74 65  e of the zero-te
34a50 72 6d 69 6e 61 74 6f 72 2e 20 20 5e 4e 6f 74 65  rminator.  ^Note
34a60 20 74 68 61 74 20 74 68 65 20 6e 61 6d 65 0a 2a   that the name.*
34a70 2a 20 6c 65 6e 67 74 68 20 6c 69 6d 69 74 20 69  * length limit i
34a80 73 20 69 6e 20 55 54 46 2d 38 20 62 79 74 65 73  s in UTF-8 bytes
34a90 2c 20 6e 6f 74 20 63 68 61 72 61 63 74 65 72 73  , not characters
34aa0 20 6e 6f 72 20 55 54 46 2d 31 36 20 62 79 74 65   nor UTF-16 byte
34ab0 73 2e 20 20 0a 2a 2a 20 5e 41 6e 79 20 61 74 74  s.  .** ^Any att
34ac0 65 6d 70 74 20 74 6f 20 63 72 65 61 74 65 20 61  empt to create a
34ad0 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 61   function with a
34ae0 20 6c 6f 6e 67 65 72 20 6e 61 6d 65 0a 2a 2a 20   longer name.** 
34af0 77 69 6c 6c 20 72 65 73 75 6c 74 20 69 6e 20 5b  will result in [
34b00 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 62  SQLITE_MISUSE] b
34b10 65 69 6e 67 20 72 65 74 75 72 6e 65 64 2e 0a 2a  eing returned..*
34b20 2a 0a 2a 2a 20 5e 54 68 65 20 74 68 69 72 64 20  *.** ^The third 
34b30 70 61 72 61 6d 65 74 65 72 20 28 6e 41 72 67 29  parameter (nArg)
34b40 0a 2a 2a 20 69 73 20 74 68 65 20 6e 75 6d 62 65  .** is the numbe
34b50 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 74  r of arguments t
34b60 68 61 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63  hat the SQL func
34b70 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65  tion or.** aggre
34b80 67 61 74 65 20 74 61 6b 65 73 2e 20 5e 49 66 20  gate takes. ^If 
34b90 74 68 69 73 20 70 61 72 61 6d 65 74 65 72 20 69  this parameter i
34ba0 73 20 2d 31 2c 20 74 68 65 6e 20 74 68 65 20 53  s -1, then the S
34bb0 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a  QL function or.*
34bc0 2a 20 61 67 67 72 65 67 61 74 65 20 6d 61 79 20  * aggregate may 
34bd0 74 61 6b 65 20 61 6e 79 20 6e 75 6d 62 65 72 20  take any number 
34be0 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 62 65 74  of arguments bet
34bf0 77 65 65 6e 20 30 20 61 6e 64 20 74 68 65 20 6c  ween 0 and the l
34c00 69 6d 69 74 0a 2a 2a 20 73 65 74 20 62 79 20 5b  imit.** set by [
34c10 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 5d 28 5b  sqlite3_limit]([
34c20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e  SQLITE_LIMIT_FUN
34c30 43 54 49 4f 4e 5f 41 52 47 5d 29 2e 20 20 49 66  CTION_ARG]).  If
34c40 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 70 61   the third.** pa
34c50 72 61 6d 65 74 65 72 20 69 73 20 6c 65 73 73 20  rameter is less 
34c60 74 68 61 6e 20 2d 31 20 6f 72 20 67 72 65 61 74  than -1 or great
34c70 65 72 20 74 68 61 6e 20 31 32 37 20 74 68 65 6e  er than 127 then
34c80 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73   the behavior is
34c90 0a 2a 2a 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a  .** undefined..*
34ca0 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 72 74 68  *.** ^The fourth
34cb0 20 70 61 72 61 6d 65 74 65 72 2c 20 65 54 65 78   parameter, eTex
34cc0 74 52 65 70 2c 20 73 70 65 63 69 66 69 65 73 20  tRep, specifies 
34cd0 77 68 61 74 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  what.** [SQLITE_
34ce0 55 54 46 38 20 7c 20 74 65 78 74 20 65 6e 63 6f  UTF8 | text enco
34cf0 64 69 6e 67 5d 20 74 68 69 73 20 53 51 4c 20 66  ding] this SQL f
34d00 75 6e 63 74 69 6f 6e 20 70 72 65 66 65 72 73 20  unction prefers 
34d10 66 6f 72 0a 2a 2a 20 69 74 73 20 70 61 72 61 6d  for.** its param
34d20 65 74 65 72 73 2e 20 20 54 68 65 20 61 70 70 6c  eters.  The appl
34d30 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 73  ication should s
34d40 65 74 20 74 68 69 73 20 70 61 72 61 6d 65 74 65  et this paramete
34d50 72 20 74 6f 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  r to.** [SQLITE_
34d60 55 54 46 31 36 4c 45 5d 20 69 66 20 74 68 65 20  UTF16LE] if the 
34d70 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65  function impleme
34d80 6e 74 61 74 69 6f 6e 20 69 6e 76 6f 6b 65 73 20  ntation invokes 
34d90 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  .** [sqlite3_val
34da0 75 65 5f 74 65 78 74 31 36 6c 65 28 29 5d 20 6f  ue_text16le()] o
34db0 6e 20 61 6e 20 69 6e 70 75 74 2c 20 6f 72 20 5b  n an input, or [
34dc0 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45 5d 20  SQLITE_UTF16BE] 
34dd0 69 66 20 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d  if the.** implem
34de0 65 6e 74 61 74 69 6f 6e 20 69 6e 76 6f 6b 65 73  entation invokes
34df0 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
34e00 74 65 78 74 31 36 62 65 28 29 5d 20 6f 6e 20 61  text16be()] on a
34e10 6e 20 69 6e 70 75 74 2c 20 6f 72 0a 2a 2a 20 5b  n input, or.** [
34e20 53 51 4c 49 54 45 5f 55 54 46 31 36 5d 20 69 66  SQLITE_UTF16] if
34e30 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
34e40 74 65 78 74 31 36 28 29 5d 20 69 73 20 75 73 65  text16()] is use
34e50 64 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55 54  d, or [SQLITE_UT
34e60 46 38 5d 0a 2a 2a 20 6f 74 68 65 72 77 69 73 65  F8].** otherwise
34e70 2e 20 20 5e 54 68 65 20 73 61 6d 65 20 53 51 4c  .  ^The same SQL
34e80 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79 20 62 65   function may be
34e90 20 72 65 67 69 73 74 65 72 65 64 20 6d 75 6c 74   registered mult
34ea0 69 70 6c 65 20 74 69 6d 65 73 20 75 73 69 6e 67  iple times using
34eb0 0a 2a 2a 20 64 69 66 66 65 72 65 6e 74 20 70 72  .** different pr
34ec0 65 66 65 72 72 65 64 20 74 65 78 74 20 65 6e 63  eferred text enc
34ed0 6f 64 69 6e 67 73 2c 20 77 69 74 68 20 64 69 66  odings, with dif
34ee0 66 65 72 65 6e 74 20 69 6d 70 6c 65 6d 65 6e 74  ferent implement
34ef0 61 74 69 6f 6e 73 20 66 6f 72 0a 2a 2a 20 65 61  ations for.** ea
34f00 63 68 20 65 6e 63 6f 64 69 6e 67 2e 0a 2a 2a 20  ch encoding..** 
34f10 5e 57 68 65 6e 20 6d 75 6c 74 69 70 6c 65 20 69  ^When multiple i
34f20 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f  mplementations o
34f30 66 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74  f the same funct
34f40 69 6f 6e 20 61 72 65 20 61 76 61 69 6c 61 62 6c  ion are availabl
34f50 65 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 77 69 6c  e, SQLite.** wil
34f60 6c 20 70 69 63 6b 20 74 68 65 20 6f 6e 65 20 74  l pick the one t
34f70 68 61 74 20 69 6e 76 6f 6c 76 65 73 20 74 68 65  hat involves the
34f80 20 6c 65 61 73 74 20 61 6d 6f 75 6e 74 20 6f 66   least amount of
34f90 20 64 61 74 61 20 63 6f 6e 76 65 72 73 69 6f 6e   data conversion
34fa0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75  ..**.** ^The fou
34fb0 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 6d 61  rth parameter ma
34fc0 79 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 62 65 20  y optionally be 
34fd0 4f 52 65 64 20 77 69 74 68 20 5b 53 51 4c 49 54  ORed with [SQLIT
34fe0 45 5f 44 45 54 45 52 4d 49 4e 49 53 54 49 43 5d  E_DETERMINISTIC]
34ff0 0a 2a 2a 20 74 6f 20 73 69 67 6e 61 6c 20 74 68  .** to signal th
35000 61 74 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20  at the function 
35010 77 69 6c 6c 20 61 6c 77 61 79 73 20 72 65 74 75  will always retu
35020 72 6e 20 74 68 65 20 73 61 6d 65 20 72 65 73 75  rn the same resu
35030 6c 74 20 67 69 76 65 6e 0a 2a 2a 20 74 68 65 20  lt given.** the 
35040 73 61 6d 65 20 69 6e 70 75 74 73 20 77 69 74 68  same inputs with
35050 69 6e 20 61 20 73 69 6e 67 6c 65 20 53 51 4c 20  in a single SQL 
35060 73 74 61 74 65 6d 65 6e 74 2e 20 20 4d 6f 73 74  statement.  Most
35070 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61   SQL functions a
35080 72 65 0a 2a 2a 20 64 65 74 65 72 6d 69 6e 69 73  re.** determinis
35090 74 69 63 2e 20 20 54 68 65 20 62 75 69 6c 74 2d  tic.  The built-
350a0 69 6e 20 5b 72 61 6e 64 6f 6d 28 29 5d 20 53 51  in [random()] SQ
350b0 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 61 6e  L function is an
350c0 20 65 78 61 6d 70 6c 65 20 6f 66 20 61 0a 2a 2a   example of a.**
350d0 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 69   function that i
350e0 73 20 6e 6f 74 20 64 65 74 65 72 6d 69 6e 69 73  s not determinis
350f0 74 69 63 2e 20 20 54 68 65 20 53 51 4c 69 74 65  tic.  The SQLite
35100 20 71 75 65 72 79 20 70 6c 61 6e 6e 65 72 20 69   query planner i
35110 73 20 61 62 6c 65 20 74 6f 0a 2a 2a 20 70 65 72  s able to.** per
35120 66 6f 72 6d 20 61 64 64 69 74 69 6f 6e 61 6c 20  form additional 
35130 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 73 20 6f 6e  optimizations on
35140 20 64 65 74 65 72 6d 69 6e 69 73 74 69 63 20 66   deterministic f
35150 75 6e 63 74 69 6f 6e 73 2c 20 73 6f 20 75 73 65  unctions, so use
35160 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 53 51 4c 49  .** of the [SQLI
35170 54 45 5f 44 45 54 45 52 4d 49 4e 49 53 54 49 43  TE_DETERMINISTIC
35180 5d 20 66 6c 61 67 20 69 73 20 72 65 63 6f 6d 6d  ] flag is recomm
35190 65 6e 64 65 64 20 77 68 65 72 65 20 70 6f 73 73  ended where poss
351a0 69 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  ible..**.** ^(Th
351b0 65 20 66 69 66 74 68 20 70 61 72 61 6d 65 74 65  e fifth paramete
351c0 72 20 69 73 20 61 6e 20 61 72 62 69 74 72 61 72  r is an arbitrar
351d0 79 20 70 6f 69 6e 74 65 72 2e 20 20 54 68 65 20  y pointer.  The 
351e0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f  implementation o
351f0 66 20 74 68 65 0a 2a 2a 20 66 75 6e 63 74 69 6f  f the.** functio
35200 6e 20 63 61 6e 20 67 61 69 6e 20 61 63 63 65 73  n can gain acces
35210 73 20 74 6f 20 74 68 69 73 20 70 6f 69 6e 74 65  s to this pointe
35220 72 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  r using [sqlite3
35230 5f 75 73 65 72 5f 64 61 74 61 28 29 5d 2e 29 5e  _user_data()].)^
35240 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 69 78 74  .**.** ^The sixt
35250 68 2c 20 73 65 76 65 6e 74 68 20 61 6e 64 20 65  h, seventh and e
35260 69 67 68 74 68 20 70 61 72 61 6d 65 74 65 72 73  ighth parameters
35270 2c 20 78 46 75 6e 63 2c 20 78 53 74 65 70 20 61  , xFunc, xStep a
35280 6e 64 20 78 46 69 6e 61 6c 2c 20 61 72 65 0a 2a  nd xFinal, are.*
35290 2a 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 43 2d  * pointers to C-
352a0 6c 61 6e 67 75 61 67 65 20 66 75 6e 63 74 69 6f  language functio
352b0 6e 73 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e  ns that implemen
352c0 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69  t the SQL functi
352d0 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61  on or.** aggrega
352e0 74 65 2e 20 5e 41 20 73 63 61 6c 61 72 20 53 51  te. ^A scalar SQ
352f0 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69  L function requi
35300 72 65 73 20 61 6e 20 69 6d 70 6c 65 6d 65 6e 74  res an implement
35310 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 78 46 75  ation of the xFu
35320 6e 63 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 6f  nc.** callback o
35330 6e 6c 79 3b 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  nly; NULL pointe
35340 72 73 20 6d 75 73 74 20 62 65 20 70 61 73 73 65  rs must be passe
35350 64 20 61 73 20 74 68 65 20 78 53 74 65 70 20 61  d as the xStep a
35360 6e 64 20 78 46 69 6e 61 6c 0a 2a 2a 20 70 61 72  nd xFinal.** par
35370 61 6d 65 74 65 72 73 2e 20 5e 41 6e 20 61 67 67  ameters. ^An agg
35380 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74  regate SQL funct
35390 69 6f 6e 20 72 65 71 75 69 72 65 73 20 61 6e 20  ion requires an 
353a0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f  implementation o
353b0 66 20 78 53 74 65 70 0a 2a 2a 20 61 6e 64 20 78  f xStep.** and x
353c0 46 69 6e 61 6c 20 61 6e 64 20 4e 55 4c 4c 20 70  Final and NULL p
353d0 6f 69 6e 74 65 72 20 6d 75 73 74 20 62 65 20 70  ointer must be p
353e0 61 73 73 65 64 20 66 6f 72 20 78 46 75 6e 63 2e  assed for xFunc.
353f0 20 5e 54 6f 20 64 65 6c 65 74 65 20 61 6e 20 65   ^To delete an e
35400 78 69 73 74 69 6e 67 0a 2a 2a 20 53 51 4c 20 66  xisting.** SQL f
35410 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67 72 65  unction or aggre
35420 67 61 74 65 2c 20 70 61 73 73 20 4e 55 4c 4c 20  gate, pass NULL 
35430 70 6f 69 6e 74 65 72 73 20 66 6f 72 20 61 6c 6c  pointers for all
35440 20 74 68 72 65 65 20 66 75 6e 63 74 69 6f 6e 0a   three function.
35450 2a 2a 20 63 61 6c 6c 62 61 63 6b 73 2e 0a 2a 2a  ** callbacks..**
35460 0a 2a 2a 20 5e 28 49 66 20 74 68 65 20 6e 69 6e  .** ^(If the nin
35470 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
35480 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
35490 75 6e 63 74 69 6f 6e 5f 76 32 28 29 20 69 73 20  unction_v2() is 
354a0 6e 6f 74 20 4e 55 4c 4c 2c 0a 2a 2a 20 74 68 65  not NULL,.** the
354b0 6e 20 69 74 20 69 73 20 64 65 73 74 72 75 63 74  n it is destruct
354c0 6f 72 20 66 6f 72 20 74 68 65 20 61 70 70 6c 69  or for the appli
354d0 63 61 74 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e  cation data poin
354e0 74 65 72 2e 20 0a 2a 2a 20 54 68 65 20 64 65 73  ter. .** The des
354f0 74 72 75 63 74 6f 72 20 69 73 20 69 6e 76 6f 6b  tructor is invok
35500 65 64 20 77 68 65 6e 20 74 68 65 20 66 75 6e 63  ed when the func
35510 74 69 6f 6e 20 69 73 20 64 65 6c 65 74 65 64 2c  tion is deleted,
35520 20 65 69 74 68 65 72 20 62 79 20 62 65 69 6e 67   either by being
35530 0a 2a 2a 20 6f 76 65 72 6c 6f 61 64 65 64 20 6f  .** overloaded o
35540 72 20 77 68 65 6e 20 74 68 65 20 64 61 74 61 62  r when the datab
35550 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63  ase connection c
35560 6c 6f 73 65 73 2e 29 5e 0a 2a 2a 20 5e 54 68 65  loses.)^.** ^The
35570 20 64 65 73 74 72 75 63 74 6f 72 20 69 73 20 61   destructor is a
35580 6c 73 6f 20 69 6e 76 6f 6b 65 64 20 69 66 20 74  lso invoked if t
35590 68 65 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71  he call to.** sq
355a0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
355b0 63 74 69 6f 6e 5f 76 32 28 29 20 66 61 69 6c 73  ction_v2() fails
355c0 2e 0a 2a 2a 20 5e 57 68 65 6e 20 74 68 65 20 64  ..** ^When the d
355d0 65 73 74 72 75 63 74 6f 72 20 63 61 6c 6c 62 61  estructor callba
355e0 63 6b 20 6f 66 20 74 68 65 20 74 65 6e 74 68 20  ck of the tenth 
355f0 70 61 72 61 6d 65 74 65 72 20 69 73 20 69 6e 76  parameter is inv
35600 6f 6b 65 64 2c 20 69 74 0a 2a 2a 20 69 73 20 70  oked, it.** is p
35610 61 73 73 65 64 20 61 20 73 69 6e 67 6c 65 20 61  assed a single a
35620 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73  rgument which is
35630 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 61   a copy of the a
35640 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20  pplication data 
35650 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 77 68 69 63  .** pointer whic
35660 68 20 77 61 73 20 74 68 65 20 66 69 66 74 68 20  h was the fifth 
35670 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
35680 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
35690 74 69 6f 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a  tion_v2()..**.**
356a0 20 5e 49 74 20 69 73 20 70 65 72 6d 69 74 74 65   ^It is permitte
356b0 64 20 74 6f 20 72 65 67 69 73 74 65 72 20 6d 75  d to register mu
356c0 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74  ltiple implement
356d0 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61  ations of the sa
356e0 6d 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20  me.** functions 
356f0 77 69 74 68 20 74 68 65 20 73 61 6d 65 20 6e 61  with the same na
35700 6d 65 20 62 75 74 20 77 69 74 68 20 65 69 74 68  me but with eith
35710 65 72 20 64 69 66 66 65 72 69 6e 67 20 6e 75 6d  er differing num
35720 62 65 72 73 20 6f 66 0a 2a 2a 20 61 72 67 75 6d  bers of.** argum
35730 65 6e 74 73 20 6f 72 20 64 69 66 66 65 72 69 6e  ents or differin
35740 67 20 70 72 65 66 65 72 72 65 64 20 74 65 78 74  g preferred text
35750 20 65 6e 63 6f 64 69 6e 67 73 2e 20 20 5e 53 51   encodings.  ^SQ
35760 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 0a 2a 2a  Lite will use.**
35770 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74   the implementat
35780 69 6f 6e 20 74 68 61 74 20 6d 6f 73 74 20 63 6c  ion that most cl
35790 6f 73 65 6c 79 20 6d 61 74 63 68 65 73 20 74 68  osely matches th
357a0 65 20 77 61 79 20 69 6e 20 77 68 69 63 68 20 74  e way in which t
357b0 68 65 0a 2a 2a 20 53 51 4c 20 66 75 6e 63 74 69  he.** SQL functi
357c0 6f 6e 20 69 73 20 75 73 65 64 2e 20 20 5e 41 20  on is used.  ^A 
357d0 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65  function impleme
357e0 6e 74 61 74 69 6f 6e 20 77 69 74 68 20 61 20 6e  ntation with a n
357f0 6f 6e 2d 6e 65 67 61 74 69 76 65 0a 2a 2a 20 6e  on-negative.** n
35800 41 72 67 20 70 61 72 61 6d 65 74 65 72 20 69 73  Arg parameter is
35810 20 61 20 62 65 74 74 65 72 20 6d 61 74 63 68 20   a better match 
35820 74 68 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20  than a function 
35830 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77  implementation w
35840 69 74 68 0a 2a 2a 20 61 20 6e 65 67 61 74 69 76  ith.** a negativ
35850 65 20 6e 41 72 67 2e 20 20 5e 41 20 66 75 6e 63  e nArg.  ^A func
35860 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20 70  tion where the p
35870 72 65 66 65 72 72 65 64 20 74 65 78 74 20 65 6e  referred text en
35880 63 6f 64 69 6e 67 0a 2a 2a 20 6d 61 74 63 68 65  coding.** matche
35890 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 65  s the database e
358a0 6e 63 6f 64 69 6e 67 20 69 73 20 61 20 62 65 74  ncoding is a bet
358b0 74 65 72 0a 2a 2a 20 6d 61 74 63 68 20 74 68 61  ter.** match tha
358c0 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 68 65  n a function whe
358d0 72 65 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20  re the encoding 
358e0 69 73 20 64 69 66 66 65 72 65 6e 74 2e 20 20 0a  is different.  .
358f0 2a 2a 20 5e 41 20 66 75 6e 63 74 69 6f 6e 20 77  ** ^A function w
35900 68 65 72 65 20 74 68 65 20 65 6e 63 6f 64 69 6e  here the encodin
35910 67 20 64 69 66 66 65 72 65 6e 63 65 20 69 73 20  g difference is 
35920 62 65 74 77 65 65 6e 20 55 54 46 31 36 6c 65 20  between UTF16le 
35930 61 6e 64 20 55 54 46 31 36 62 65 0a 2a 2a 20 69  and UTF16be.** i
35940 73 20 61 20 63 6c 6f 73 65 72 20 6d 61 74 63 68  s a closer match
35950 20 74 68 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e   than a function
35960 20 77 68 65 72 65 20 74 68 65 20 65 6e 63 6f 64   where the encod
35970 69 6e 67 20 64 69 66 66 65 72 65 6e 63 65 20 69  ing difference i
35980 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20 55 54 46  s.** between UTF
35990 38 20 61 6e 64 20 55 54 46 31 36 2e 0a 2a 2a 0a  8 and UTF16..**.
359a0 2a 2a 20 5e 42 75 69 6c 74 2d 69 6e 20 66 75 6e  ** ^Built-in fun
359b0 63 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 6f 76  ctions may be ov
359c0 65 72 6c 6f 61 64 65 64 20 62 79 20 6e 65 77 20  erloaded by new 
359d0 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
359e0 6e 65 64 20 66 75 6e 63 74 69 6f 6e 73 2e 0a 2a  ned functions..*
359f0 2a 0a 2a 2a 20 5e 41 6e 20 61 70 70 6c 69 63 61  *.** ^An applica
35a00 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
35a10 63 74 69 6f 6e 20 69 73 20 70 65 72 6d 69 74 74  ction is permitt
35a20 65 64 20 74 6f 20 63 61 6c 6c 20 6f 74 68 65 72  ed to call other
35a30 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74 65 72  .** SQLite inter
35a40 66 61 63 65 73 2e 20 20 48 6f 77 65 76 65 72 2c  faces.  However,
35a50 20 73 75 63 68 20 63 61 6c 6c 73 20 6d 75 73 74   such calls must
35a60 20 6e 6f 74 0a 2a 2a 20 63 6c 6f 73 65 20 74 68   not.** close th
35a70 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
35a80 63 74 69 6f 6e 20 6e 6f 72 20 66 69 6e 61 6c 69  ction nor finali
35a90 7a 65 20 6f 72 20 72 65 73 65 74 20 74 68 65 20  ze or reset the 
35aa0 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74 61 74  prepared.** stat
35ab0 65 6d 65 6e 74 20 69 6e 20 77 68 69 63 68 20 74  ement in which t
35ac0 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72  he function is r
35ad0 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 53 51 4c 49 54  unning..*/.SQLIT
35ae0 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
35af0 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
35b00 6e 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  n(.  sqlite3 *db
35b10 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  ,.  const char *
35b20 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20  zFunctionName,. 
35b30 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74   int nArg,.  int
35b40 20 65 54 65 78 74 52 65 70 2c 0a 20 20 76 6f 69   eTextRep,.  voi
35b50 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64 20  d *pApp,.  void 
35b60 28 2a 78 46 75 6e 63 29 28 73 71 6c 69 74 65 33  (*xFunc)(sqlite3
35b70 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71  _context*,int,sq
35b80 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a  lite3_value**),.
35b90 20 20 76 6f 69 64 20 28 2a 78 53 74 65 70 29 28    void (*xStep)(
35ba0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
35bb0 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c  ,int,sqlite3_val
35bc0 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a  ue**),.  void (*
35bd0 78 46 69 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f  xFinal)(sqlite3_
35be0 63 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a 53 51 4c  context*).);.SQL
35bf0 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
35c00 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
35c10 69 6f 6e 31 36 28 0a 20 20 73 71 6c 69 74 65 33  ion16(.  sqlite3
35c20 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20 76 6f   *db,.  const vo
35c30 69 64 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d  id *zFunctionNam
35c40 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20  e,.  int nArg,. 
35c50 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 0a 20   int eTextRep,. 
35c60 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20 76   void *pApp,.  v
35c70 6f 69 64 20 28 2a 78 46 75 6e 63 29 28 73 71 6c  oid (*xFunc)(sql
35c80 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e  ite3_context*,in
35c90 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  t,sqlite3_value*
35ca0 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53 74  *),.  void (*xSt
35cb0 65 70 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ep)(sqlite3_cont
35cc0 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33  ext*,int,sqlite3
35cd0 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69  _value**),.  voi
35ce0 64 20 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69  d (*xFinal)(sqli
35cf0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 0a 29 3b  te3_context*).);
35d00 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
35d10 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
35d20 75 6e 63 74 69 6f 6e 5f 76 32 28 0a 20 20 73 71  unction_v2(.  sq
35d30 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e  lite3 *db,.  con
35d40 73 74 20 63 68 61 72 20 2a 7a 46 75 6e 63 74 69  st char *zFuncti
35d50 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41  onName,.  int nA
35d60 72 67 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52  rg,.  int eTextR
35d70 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70 70  ep,.  void *pApp
35d80 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 75 6e 63  ,.  void (*xFunc
35d90 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  )(sqlite3_contex
35da0 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76  t*,int,sqlite3_v
35db0 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20  alue**),.  void 
35dc0 28 2a 78 53 74 65 70 29 28 73 71 6c 69 74 65 33  (*xStep)(sqlite3
35dd0 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71  _context*,int,sq
35de0 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a  lite3_value**),.
35df0 20 20 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29    void (*xFinal)
35e00 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
35e10 2a 29 2c 0a 20 20 76 6f 69 64 28 2a 78 44 65 73  *),.  void(*xDes
35e20 74 72 6f 79 29 28 76 6f 69 64 2a 29 0a 29 3b 0a  troy)(void*).);.
35e30 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
35e40 20 54 65 78 74 20 45 6e 63 6f 64 69 6e 67 73 0a   Text Encodings.
35e50 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73  **.** These cons
35e60 74 61 6e 74 20 64 65 66 69 6e 65 20 69 6e 74 65  tant define inte
35e70 67 65 72 20 63 6f 64 65 73 20 74 68 61 74 20 72  ger codes that r
35e80 65 70 72 65 73 65 6e 74 20 74 68 65 20 76 61 72  epresent the var
35e90 69 6f 75 73 0a 2a 2a 20 74 65 78 74 20 65 6e 63  ious.** text enc
35ea0 6f 64 69 6e 67 73 20 73 75 70 70 6f 72 74 65 64  odings supported
35eb0 20 62 79 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 23   by SQLite..*/.#
35ec0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54  define SQLITE_UT
35ed0 46 38 20 20 20 20 20 20 20 20 20 20 20 31 20 20  F8           1  
35ee0 20 20 2f 2a 20 49 4d 50 3a 20 52 2d 33 37 35 31    /* IMP: R-3751
35ef0 34 2d 33 35 35 36 36 20 2a 2f 0a 23 64 65 66 69  4-35566 */.#defi
35f00 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 4c  ne SQLITE_UTF16L
35f10 45 20 20 20 20 20 20 20 20 32 20 20 20 20 2f 2a  E        2    /*
35f20 20 49 4d 50 3a 20 52 2d 30 33 33 37 31 2d 33 37   IMP: R-03371-37
35f30 36 33 37 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  637 */.#define S
35f40 51 4c 49 54 45 5f 55 54 46 31 36 42 45 20 20 20  QLITE_UTF16BE   
35f50 20 20 20 20 20 33 20 20 20 20 2f 2a 20 49 4d 50       3    /* IMP
35f60 3a 20 52 2d 35 31 39 37 31 2d 33 34 31 35 34 20  : R-51971-34154 
35f70 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
35f80 45 5f 55 54 46 31 36 20 20 20 20 20 20 20 20 20  E_UTF16         
35f90 20 34 20 20 20 20 2f 2a 20 55 73 65 20 6e 61 74   4    /* Use nat
35fa0 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 20 2a  ive byte order *
35fb0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
35fc0 5f 41 4e 59 20 20 20 20 20 20 20 20 20 20 20 20  _ANY            
35fd0 35 20 20 20 20 2f 2a 20 44 65 70 72 65 63 61 74  5    /* Deprecat
35fe0 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ed */.#define SQ
35ff0 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e  LITE_UTF16_ALIGN
36000 45 44 20 20 38 20 20 20 20 2f 2a 20 73 71 6c 69  ED  8    /* sqli
36010 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
36020 74 69 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a 0a 2f 2a  tion only */../*
36030 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 75  .** CAPI3REF: Fu
36040 6e 63 74 69 6f 6e 20 46 6c 61 67 73 0a 2a 2a 0a  nction Flags.**.
36050 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e  ** These constan
36060 74 73 20 6d 61 79 20 62 65 20 4f 52 65 64 20 74  ts may be ORed t
36070 6f 67 65 74 68 65 72 20 77 69 74 68 20 74 68 65  ogether with the
36080 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46   .** [SQLITE_UTF
36090 38 20 7c 20 70 72 65 66 65 72 72 65 64 20 74 65  8 | preferred te
360a0 78 74 20 65 6e 63 6f 64 69 6e 67 5d 20 61 73 20  xt encoding] as 
360b0 74 68 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d  the fourth argum
360c0 65 6e 74 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74  ent.** to [sqlit
360d0 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
360e0 6f 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  on()], [sqlite3_
360f0 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31  create_function1
36100 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c  6()], or.** [sql
36110 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
36120 74 69 6f 6e 5f 76 32 28 29 5d 2e 0a 2a 2f 0a 23  tion_v2()]..*/.#
36130 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45  define SQLITE_DE
36140 54 45 52 4d 49 4e 49 53 54 49 43 20 20 20 20 30  TERMINISTIC    0
36150 78 38 30 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  x800../*.** CAPI
36160 33 52 45 46 3a 20 44 65 70 72 65 63 61 74 65 64  3REF: Deprecated
36170 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 44 45   Functions.** DE
36180 50 52 45 43 41 54 45 44 0a 2a 2a 0a 2a 2a 20 54  PRECATED.**.** T
36190 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 61  hese functions a
361a0 72 65 20 5b 64 65 70 72 65 63 61 74 65 64 5d 2e  re [deprecated].
361b0 20 20 49 6e 20 6f 72 64 65 72 20 74 6f 20 6d 61    In order to ma
361c0 69 6e 74 61 69 6e 0a 2a 2a 20 62 61 63 6b 77 61  intain.** backwa
361d0 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  rds compatibilit
361e0 79 20 77 69 74 68 20 6f 6c 64 65 72 20 63 6f 64  y with older cod
361f0 65 2c 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f  e, these functio
36200 6e 73 20 63 6f 6e 74 69 6e 75 65 20 0a 2a 2a 20  ns continue .** 
36210 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64 2e  to be supported.
36220 20 20 48 6f 77 65 76 65 72 2c 20 6e 65 77 20 61    However, new a
36230 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f 75  pplications shou
36240 6c 64 20 61 76 6f 69 64 0a 2a 2a 20 74 68 65 20  ld avoid.** the 
36250 75 73 65 20 6f 66 20 74 68 65 73 65 20 66 75 6e  use of these fun
36260 63 74 69 6f 6e 73 2e 20 20 54 6f 20 65 6e 63 6f  ctions.  To enco
36270 75 72 61 67 65 20 70 72 6f 67 72 61 6d 6d 65 72  urage programmer
36280 73 20 74 6f 20 61 76 6f 69 64 0a 2a 2a 20 74 68  s to avoid.** th
36290 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 2c 20 77  ese functions, w
362a0 65 20 77 69 6c 6c 20 6e 6f 74 20 65 78 70 6c 61  e will not expla
362b0 69 6e 20 77 68 61 74 20 74 68 65 79 20 64 6f 2e  in what they do.
362c0 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c 49  .*/.#ifndef SQLI
362d0 54 45 5f 4f 4d 49 54 5f 44 45 50 52 45 43 41 54  TE_OMIT_DEPRECAT
362e0 45 44 0a 53 51 4c 49 54 45 5f 41 50 49 20 53 51  ED.SQLITE_API SQ
362f0 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20  LITE_DEPRECATED 
36300 69 6e 74 20 73 71 6c 69 74 65 33 5f 61 67 67 72  int sqlite3_aggr
36310 65 67 61 74 65 5f 63 6f 75 6e 74 28 73 71 6c 69  egate_count(sqli
36320 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 53  te3_context*);.S
36330 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45  QLITE_API SQLITE
36340 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e 74 20  _DEPRECATED int 
36350 73 71 6c 69 74 65 33 5f 65 78 70 69 72 65 64 28  sqlite3_expired(
36360 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a  sqlite3_stmt*);.
36370 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54  SQLITE_API SQLIT
36380 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e 74  E_DEPRECATED int
36390 20 73 71 6c 69 74 65 33 5f 74 72 61 6e 73 66 65   sqlite3_transfe
363a0 72 5f 62 69 6e 64 69 6e 67 73 28 73 71 6c 69 74  r_bindings(sqlit
363b0 65 33 5f 73 74 6d 74 2a 2c 20 73 71 6c 69 74 65  e3_stmt*, sqlite
363c0 33 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c 49 54 45  3_stmt*);.SQLITE
363d0 5f 41 50 49 20 53 51 4c 49 54 45 5f 44 45 50 52  _API SQLITE_DEPR
363e0 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74  ECATED int sqlit
363f0 65 33 5f 67 6c 6f 62 61 6c 5f 72 65 63 6f 76 65  e3_global_recove
36400 72 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f  r(void);.SQLITE_
36410 41 50 49 20 53 51 4c 49 54 45 5f 44 45 50 52 45  API SQLITE_DEPRE
36420 43 41 54 45 44 20 76 6f 69 64 20 73 71 6c 69 74  CATED void sqlit
36430 65 33 5f 74 68 72 65 61 64 5f 63 6c 65 61 6e 75  e3_thread_cleanu
36440 70 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f  p(void);.SQLITE_
36450 41 50 49 20 53 51 4c 49 54 45 5f 44 45 50 52 45  API SQLITE_DEPRE
36460 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65  CATED int sqlite
36470 33 5f 6d 65 6d 6f 72 79 5f 61 6c 61 72 6d 28 76  3_memory_alarm(v
36480 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c  oid(*)(void*,sql
36490 69 74 65 33 5f 69 6e 74 36 34 2c 69 6e 74 29 2c  ite3_int64,int),
364a0 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  .               
364b0 20 20 20 20 20 20 20 76 6f 69 64 2a 2c 73 71 6c         void*,sql
364c0 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 23 65 6e  ite3_int64);.#en
364d0 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  dif../*.** CAPI3
364e0 52 45 46 3a 20 4f 62 74 61 69 6e 69 6e 67 20 53  REF: Obtaining S
364f0 51 4c 20 56 61 6c 75 65 73 0a 2a 2a 20 4d 45 54  QL Values.** MET
36500 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 76 61 6c  HOD: sqlite3_val
36510 75 65 0a 2a 2a 0a 2a 2a 20 54 68 65 20 43 2d 6c  ue.**.** The C-l
36520 61 6e 67 75 61 67 65 20 69 6d 70 6c 65 6d 65 6e  anguage implemen
36530 74 61 74 69 6f 6e 20 6f 66 20 53 51 4c 20 66 75  tation of SQL fu
36540 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 72  nctions and aggr
36550 65 67 61 74 65 73 20 75 73 65 73 0a 2a 2a 20 74  egates uses.** t
36560 68 69 73 20 73 65 74 20 6f 66 20 69 6e 74 65 72  his set of inter
36570 66 61 63 65 20 72 6f 75 74 69 6e 65 73 20 74 6f  face routines to
36580 20 61 63 63 65 73 73 20 74 68 65 20 70 61 72 61   access the para
36590 6d 65 74 65 72 20 76 61 6c 75 65 73 20 6f 6e 0a  meter values on.
365a0 2a 2a 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20  ** the function 
365b0 6f 72 20 61 67 67 72 65 67 61 74 65 2e 20 20 0a  or aggregate.  .
365c0 2a 2a 0a 2a 2a 20 54 68 65 20 78 46 75 6e 63 20  **.** The xFunc 
365d0 28 66 6f 72 20 73 63 61 6c 61 72 20 66 75 6e 63  (for scalar func
365e0 74 69 6f 6e 73 29 20 6f 72 20 78 53 74 65 70 20  tions) or xStep 
365f0 28 66 6f 72 20 61 67 67 72 65 67 61 74 65 73 29  (for aggregates)
36600 20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 74   parameters.** t
36610 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  o [sqlite3_creat
36620 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 20 61 6e  e_function()] an
36630 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  d [sqlite3_creat
36640 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 0a  e_function16()].
36650 2a 2a 20 64 65 66 69 6e 65 20 63 61 6c 6c 62 61  ** define callba
36660 63 6b 73 20 74 68 61 74 20 69 6d 70 6c 65 6d 65  cks that impleme
36670 6e 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74  nt the SQL funct
36680 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 65 67 61  ions and aggrega
36690 74 65 73 2e 0a 2a 2a 20 54 68 65 20 33 72 64 20  tes..** The 3rd 
366a0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
366b0 73 65 20 63 61 6c 6c 62 61 63 6b 73 20 69 73 20  se callbacks is 
366c0 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e  an array of poin
366d0 74 65 72 73 20 74 6f 0a 2a 2a 20 5b 70 72 6f 74  ters to.** [prot
366e0 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
366f0 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 20 20 54  lue] objects.  T
36700 68 65 72 65 20 69 73 20 6f 6e 65 20 5b 73 71 6c  here is one [sql
36710 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
36720 63 74 20 66 6f 72 0a 2a 2a 20 65 61 63 68 20 70  ct for.** each p
36730 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
36740 53 51 4c 20 66 75 6e 63 74 69 6f 6e 2e 20 20 54  SQL function.  T
36750 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72  hese routines ar
36760 65 20 75 73 65 64 20 74 6f 0a 2a 2a 20 65 78 74  e used to.** ext
36770 72 61 63 74 20 76 61 6c 75 65 73 20 66 72 6f 6d  ract values from
36780 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61   the [sqlite3_va
36790 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a  lue] objects..**
367a0 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
367b0 65 73 20 77 6f 72 6b 20 6f 6e 6c 79 20 77 69 74  es work only wit
367c0 68 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c  h [protected sql
367d0 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
367e0 63 74 73 2e 0a 2a 2a 20 41 6e 79 20 61 74 74 65  cts..** Any atte
367f0 6d 70 74 20 74 6f 20 75 73 65 20 74 68 65 73 65  mpt to use these
36800 20 72 6f 75 74 69 6e 65 73 20 6f 6e 20 61 6e 20   routines on an 
36810 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c  [unprotected sql
36820 69 74 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20 6f  ite3_value].** o
36830 62 6a 65 63 74 20 72 65 73 75 6c 74 73 20 69 6e  bject results in
36840 20 75 6e 64 65 66 69 6e 65 64 20 62 65 68 61 76   undefined behav
36850 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73  ior..**.** ^Thes
36860 65 20 72 6f 75 74 69 6e 65 73 20 77 6f 72 6b 20  e routines work 
36870 6a 75 73 74 20 6c 69 6b 65 20 74 68 65 20 63 6f  just like the co
36880 72 72 65 73 70 6f 6e 64 69 6e 67 20 5b 63 6f 6c  rresponding [col
36890 75 6d 6e 20 61 63 63 65 73 73 20 66 75 6e 63 74  umn access funct
368a0 69 6f 6e 73 5d 0a 2a 2a 20 65 78 63 65 70 74 20  ions].** except 
368b0 74 68 61 74 20 74 68 65 73 65 20 72 6f 75 74 69  that these routi
368c0 6e 65 73 20 74 61 6b 65 20 61 20 73 69 6e 67 6c  nes take a singl
368d0 65 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c  e [protected sql
368e0 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
368f0 63 74 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 69 6e  ct.** pointer in
36900 73 74 65 61 64 20 6f 66 20 61 20 5b 73 71 6c 69  stead of a [sqli
36910 74 65 33 5f 73 74 6d 74 2a 5d 20 70 6f 69 6e 74  te3_stmt*] point
36920 65 72 20 61 6e 64 20 61 6e 20 69 6e 74 65 67 65  er and an intege
36930 72 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e  r column number.
36940 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
36950 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36  te3_value_text16
36960 28 29 20 69 6e 74 65 72 66 61 63 65 20 65 78 74  () interface ext
36970 72 61 63 74 73 20 61 20 55 54 46 2d 31 36 20 73  racts a UTF-16 s
36980 74 72 69 6e 67 0a 2a 2a 20 69 6e 20 74 68 65 20  tring.** in the 
36990 6e 61 74 69 76 65 20 62 79 74 65 2d 6f 72 64 65  native byte-orde
369a0 72 20 6f 66 20 74 68 65 20 68 6f 73 74 20 6d 61  r of the host ma
369b0 63 68 69 6e 65 2e 20 20 5e 54 68 65 0a 2a 2a 20  chine.  ^The.** 
369c0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
369d0 78 74 31 36 62 65 28 29 20 61 6e 64 20 73 71 6c  xt16be() and sql
369e0 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31  ite3_value_text1
369f0 36 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65 73  6le() interfaces
36a00 0a 2a 2a 20 65 78 74 72 61 63 74 20 55 54 46 2d  .** extract UTF-
36a10 31 36 20 73 74 72 69 6e 67 73 20 61 73 20 62 69  16 strings as bi
36a20 67 2d 65 6e 64 69 61 6e 20 61 6e 64 20 6c 69 74  g-endian and lit
36a30 74 6c 65 2d 65 6e 64 69 61 6e 20 72 65 73 70 65  tle-endian respe
36a40 63 74 69 76 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e  ctively..**.** ^
36a50 28 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c  (The sqlite3_val
36a60 75 65 5f 6e 75 6d 65 72 69 63 5f 74 79 70 65 28  ue_numeric_type(
36a70 29 20 69 6e 74 65 72 66 61 63 65 20 61 74 74 65  ) interface atte
36a80 6d 70 74 73 20 74 6f 20 61 70 70 6c 79 0a 2a 2a  mpts to apply.**
36a90 20 6e 75 6d 65 72 69 63 20 61 66 66 69 6e 69 74   numeric affinit
36aa0 79 20 74 6f 20 74 68 65 20 76 61 6c 75 65 2e 20  y to the value. 
36ab0 20 54 68 69 73 20 6d 65 61 6e 73 20 74 68 61 74   This means that
36ac0 20 61 6e 20 61 74 74 65 6d 70 74 20 69 73 0a 2a   an attempt is.*
36ad0 2a 20 6d 61 64 65 20 74 6f 20 63 6f 6e 76 65 72  * made to conver
36ae0 74 20 74 68 65 20 76 61 6c 75 65 20 74 6f 20 61  t the value to a
36af0 6e 20 69 6e 74 65 67 65 72 20 6f 72 20 66 6c 6f  n integer or flo
36b00 61 74 69 6e 67 20 70 6f 69 6e 74 2e 20 20 49 66  ating point.  If
36b10 0a 2a 2a 20 73 75 63 68 20 61 20 63 6f 6e 76 65  .** such a conve
36b20 72 73 69 6f 6e 20 69 73 20 70 6f 73 73 69 62 6c  rsion is possibl
36b30 65 20 77 69 74 68 6f 75 74 20 6c 6f 73 73 20 6f  e without loss o
36b40 66 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 28 69  f information (i
36b50 6e 20 6f 74 68 65 72 0a 2a 2a 20 77 6f 72 64 73  n other.** words
36b60 2c 20 69 66 20 74 68 65 20 76 61 6c 75 65 20 69  , if the value i
36b70 73 20 61 20 73 74 72 69 6e 67 20 74 68 61 74 20  s a string that 
36b80 6c 6f 6f 6b 73 20 6c 69 6b 65 20 61 20 6e 75 6d  looks like a num
36b90 62 65 72 29 0a 2a 2a 20 74 68 65 6e 20 74 68 65  ber).** then the
36ba0 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 70   conversion is p
36bb0 65 72 66 6f 72 6d 65 64 2e 20 20 4f 74 68 65 72  erformed.  Other
36bc0 77 69 73 65 20 6e 6f 20 63 6f 6e 76 65 72 73 69  wise no conversi
36bd0 6f 6e 20 6f 63 63 75 72 73 2e 0a 2a 2a 20 54 68  on occurs..** Th
36be0 65 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45  e [SQLITE_INTEGE
36bf0 52 20 7c 20 64 61 74 61 74 79 70 65 5d 20 61 66  R | datatype] af
36c00 74 65 72 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69  ter conversion i
36c10 73 20 72 65 74 75 72 6e 65 64 2e 29 5e 0a 2a 2a  s returned.)^.**
36c20 0a 2a 2a 20 50 6c 65 61 73 65 20 70 61 79 20 70  .** Please pay p
36c30 61 72 74 69 63 75 6c 61 72 20 61 74 74 65 6e 74  articular attent
36c40 69 6f 6e 20 74 6f 20 74 68 65 20 66 61 63 74 20  ion to the fact 
36c50 74 68 61 74 20 74 68 65 20 70 6f 69 6e 74 65 72  that the pointer
36c60 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 66 72 6f   returned.** fro
36c70 6d 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  m [sqlite3_value
36c80 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c 69 74  _blob()], [sqlit
36c90 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 29 5d  e3_value_text()]
36ca0 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  , or.** [sqlite3
36cb0 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29 5d  _value_text16()]
36cc0 20 63 61 6e 20 62 65 20 69 6e 76 61 6c 69 64 61   can be invalida
36cd0 74 65 64 20 62 79 20 61 20 73 75 62 73 65 71 75  ted by a subsequ
36ce0 65 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b  ent call to.** [
36cf0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79  sqlite3_value_by
36d00 74 65 73 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  tes()], [sqlite3
36d10 5f 76 61 6c 75 65 5f 62 79 74 65 73 31 36 28 29  _value_bytes16()
36d20 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  ], [sqlite3_valu
36d30 65 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72  e_text()],.** or
36d40 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
36d50 74 65 78 74 31 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a  text16()]..**.**
36d60 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
36d70 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66  must be called f
36d80 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72  rom the same thr
36d90 65 61 64 20 61 73 0a 2a 2a 20 74 68 65 20 53 51  ead as.** the SQ
36da0 4c 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20  L function that 
36db0 73 75 70 70 6c 69 65 64 20 74 68 65 20 5b 73 71  supplied the [sq
36dc0 6c 69 74 65 33 5f 76 61 6c 75 65 2a 5d 20 70 61  lite3_value*] pa
36dd0 72 61 6d 65 74 65 72 73 2e 0a 2a 2f 0a 53 51 4c  rameters..*/.SQL
36de0 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f  ITE_API const vo
36df0 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75  id *sqlite3_valu
36e00 65 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 76  e_blob(sqlite3_v
36e10 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41  alue*);.SQLITE_A
36e20 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 76  PI int sqlite3_v
36e30 61 6c 75 65 5f 62 79 74 65 73 28 73 71 6c 69 74  alue_bytes(sqlit
36e40 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49  e3_value*);.SQLI
36e50 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
36e60 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 31 36  e3_value_bytes16
36e70 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
36e80 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 64 6f 75  ;.SQLITE_API dou
36e90 62 6c 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ble sqlite3_valu
36ea0 65 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33  e_double(sqlite3
36eb0 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45  _value*);.SQLITE
36ec0 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
36ed0 5f 76 61 6c 75 65 5f 69 6e 74 28 73 71 6c 69 74  _value_int(sqlit
36ee0 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49  e3_value*);.SQLI
36ef0 54 45 5f 41 50 49 20 73 71 6c 69 74 65 33 5f 69  TE_API sqlite3_i
36f00 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 76 61 6c  nt64 sqlite3_val
36f10 75 65 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33  ue_int64(sqlite3
36f20 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45  _value*);.SQLITE
36f30 5f 41 50 49 20 63 6f 6e 73 74 20 75 6e 73 69 67  _API const unsig
36f40 6e 65 64 20 63 68 61 72 20 2a 73 71 6c 69 74 65  ned char *sqlite
36f50 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 73 71 6c  3_value_text(sql
36f60 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51  ite3_value*);.SQ
36f70 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76  LITE_API const v
36f80 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c  oid *sqlite3_val
36f90 75 65 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65  ue_text16(sqlite
36fa0 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54  3_value*);.SQLIT
36fb0 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64  E_API const void
36fc0 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   *sqlite3_value_
36fd0 74 65 78 74 31 36 6c 65 28 73 71 6c 69 74 65 33  text16le(sqlite3
36fe0 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45  _value*);.SQLITE
36ff0 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20  _API const void 
37000 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  *sqlite3_value_t
37010 65 78 74 31 36 62 65 28 73 71 6c 69 74 65 33 5f  ext16be(sqlite3_
37020 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f  value*);.SQLITE_
37030 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
37040 76 61 6c 75 65 5f 74 79 70 65 28 73 71 6c 69 74  value_type(sqlit
37050 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49  e3_value*);.SQLI
37060 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
37070 65 33 5f 76 61 6c 75 65 5f 6e 75 6d 65 72 69 63  e3_value_numeric
37080 5f 74 79 70 65 28 73 71 6c 69 74 65 33 5f 76 61  _type(sqlite3_va
37090 6c 75 65 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  lue*);../*.** CA
370a0 50 49 33 52 45 46 3a 20 46 69 6e 64 69 6e 67 20  PI3REF: Finding 
370b0 54 68 65 20 53 75 62 74 79 70 65 20 4f 66 20 53  The Subtype Of S
370c0 51 4c 20 56 61 6c 75 65 73 0a 2a 2a 20 4d 45 54  QL Values.** MET
370d0 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 76 61 6c  HOD: sqlite3_val
370e0 75 65 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  ue.**.** The sql
370f0 69 74 65 33 5f 76 61 6c 75 65 5f 73 75 62 74 79  ite3_value_subty
37100 70 65 28 56 29 20 66 75 6e 63 74 69 6f 6e 20 72  pe(V) function r
37110 65 74 75 72 6e 73 20 74 68 65 20 73 75 62 74 79  eturns the subty
37120 70 65 20 66 6f 72 0a 2a 2a 20 61 6e 20 5b 61 70  pe for.** an [ap
37130 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
37140 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 20  d SQL function] 
37150 61 72 67 75 6d 65 6e 74 20 56 2e 20 20 54 68 65  argument V.  The
37160 20 73 75 62 74 79 70 65 0a 2a 2a 20 69 6e 66 6f   subtype.** info
37170 72 6d 61 74 69 6f 6e 20 63 61 6e 20 62 65 20 75  rmation can be u
37180 73 65 64 20 74 6f 20 70 61 73 73 20 61 20 6c 69  sed to pass a li
37190 6d 69 74 65 64 20 61 6d 6f 75 6e 74 20 6f 66 20  mited amount of 
371a0 63 6f 6e 74 65 78 74 20 66 72 6f 6d 0a 2a 2a 20  context from.** 
371b0 6f 6e 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  one SQL function
371c0 20 74 6f 20 61 6e 6f 74 68 65 72 2e 20 20 55 73   to another.  Us
371d0 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 72  e the [sqlite3_r
371e0 65 73 75 6c 74 5f 73 75 62 74 79 70 65 28 29 5d  esult_subtype()]
371f0 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 74 6f 20 73  .** routine to s
37200 65 74 20 74 68 65 20 73 75 62 74 79 70 65 20 66  et the subtype f
37210 6f 72 20 74 68 65 20 72 65 74 75 72 6e 20 76 61  or the return va
37220 6c 75 65 20 6f 66 20 61 6e 20 53 51 4c 20 66 75  lue of an SQL fu
37230 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51  nction..**.** SQ
37240 4c 69 74 65 20 6d 61 6b 65 73 20 6e 6f 20 75 73  Lite makes no us
37250 65 20 6f 66 20 73 75 62 74 79 70 65 20 69 74 73  e of subtype its
37260 65 6c 66 2e 20 20 49 74 20 6d 65 72 65 6c 79 20  elf.  It merely 
37270 70 61 73 73 65 73 20 74 68 65 20 73 75 62 74 79  passes the subty
37280 70 65 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20 72  pe.** from the r
37290 65 73 75 6c 74 20 6f 66 20 6f 6e 65 20 5b 61 70  esult of one [ap
372a0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
372b0 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 20  d SQL function] 
372c0 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 69 6e 70 75  into the.** inpu
372d0 74 20 6f 66 20 61 6e 6f 74 68 65 72 2e 0a 2a 2f  t of another..*/
372e0 0a 53 51 4c 49 54 45 5f 41 50 49 20 75 6e 73 69  .SQLITE_API unsi
372f0 67 6e 65 64 20 69 6e 74 20 73 71 6c 69 74 65 33  gned int sqlite3
37300 5f 76 61 6c 75 65 5f 73 75 62 74 79 70 65 28 73  _value_subtype(s
37310 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
37320 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
37330 20 43 6f 70 79 20 41 6e 64 20 46 72 65 65 20 53   Copy And Free S
37340 51 4c 20 56 61 6c 75 65 73 0a 2a 2a 20 4d 45 54  QL Values.** MET
37350 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 76 61 6c  HOD: sqlite3_val
37360 75 65 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  ue.**.** ^The sq
37370 6c 69 74 65 33 5f 76 61 6c 75 65 5f 64 75 70 28  lite3_value_dup(
37380 56 29 20 69 6e 74 65 72 66 61 63 65 20 6d 61 6b  V) interface mak
37390 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  es a copy of the
373a0 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d   [sqlite3_value]
373b0 0a 2a 2a 20 6f 62 6a 65 63 74 20 44 20 61 6e 64  .** object D and
373c0 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
373d0 65 72 20 74 6f 20 74 68 61 74 20 63 6f 70 79 2e  er to that copy.
373e0 20 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f    ^The [sqlite3_
373f0 76 61 6c 75 65 5d 20 72 65 74 75 72 6e 65 64 0a  value] returned.
37400 2a 2a 20 69 73 20 61 20 5b 70 72 6f 74 65 63 74  ** is a [protect
37410 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
37420 5d 20 6f 62 6a 65 63 74 20 65 76 65 6e 20 69 66  ] object even if
37430 20 74 68 65 20 69 6e 70 75 74 20 69 73 20 6e 6f   the input is no
37440 74 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  t..** ^The sqlit
37450 65 33 5f 76 61 6c 75 65 5f 64 75 70 28 56 29 20  e3_value_dup(V) 
37460 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
37470 73 20 4e 55 4c 4c 20 69 66 20 56 20 69 73 20 4e  s NULL if V is N
37480 55 4c 4c 20 6f 72 20 69 66 20 61 0a 2a 2a 20 6d  ULL or if a.** m
37490 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
374a0 20 66 61 69 6c 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54   fails..**.** ^T
374b0 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  he sqlite3_value
374c0 5f 66 72 65 65 28 56 29 20 69 6e 74 65 72 66 61  _free(V) interfa
374d0 63 65 20 66 72 65 65 73 20 61 6e 20 5b 73 71 6c  ce frees an [sql
374e0 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
374f0 63 74 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79  ct.** previously
37500 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b   obtained from [
37510 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 64 75  sqlite3_value_du
37520 70 28 29 5d 2e 20 20 5e 49 66 20 56 20 69 73 20  p()].  ^If V is 
37530 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a  a NULL pointer.*
37540 2a 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 76  * then sqlite3_v
37550 61 6c 75 65 5f 66 72 65 65 28 56 29 20 69 73 20  alue_free(V) is 
37560 61 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70  a harmless no-op
37570 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
37580 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 2a 73  sqlite3_value *s
37590 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 64 75 70  qlite3_value_dup
375a0 28 63 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f 76  (const sqlite3_v
375b0 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41  alue*);.SQLITE_A
375c0 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  PI void sqlite3_
375d0 76 61 6c 75 65 5f 66 72 65 65 28 73 71 6c 69 74  value_free(sqlit
375e0 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 0a 2f 2a 0a  e3_value*);../*.
375f0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 62 74  ** CAPI3REF: Obt
37600 61 69 6e 20 41 67 67 72 65 67 61 74 65 20 46 75  ain Aggregate Fu
37610 6e 63 74 69 6f 6e 20 43 6f 6e 74 65 78 74 0a 2a  nction Context.*
37620 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65  * METHOD: sqlite
37630 33 5f 63 6f 6e 74 65 78 74 0a 2a 2a 0a 2a 2a 20  3_context.**.** 
37640 49 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  Implementations 
37650 6f 66 20 61 67 67 72 65 67 61 74 65 20 53 51 4c  of aggregate SQL
37660 20 66 75 6e 63 74 69 6f 6e 73 20 75 73 65 20 74   functions use t
37670 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 74  his.** routine t
37680 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72  o allocate memor
37690 79 20 66 6f 72 20 73 74 6f 72 69 6e 67 20 74 68  y for storing th
376a0 65 69 72 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a  eir state..**.**
376b0 20 5e 54 68 65 20 66 69 72 73 74 20 74 69 6d 65   ^The first time
376c0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 61 67 67   the sqlite3_agg
376d0 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 43  regate_context(C
376e0 2c 4e 29 20 72 6f 75 74 69 6e 65 20 69 73 20 63  ,N) routine is c
376f0 61 6c 6c 65 64 20 0a 2a 2a 20 66 6f 72 20 61 20  alled .** for a 
37700 70 61 72 74 69 63 75 6c 61 72 20 61 67 67 72 65  particular aggre
37710 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 2c 20 53  gate function, S
37720 51 4c 69 74 65 0a 2a 2a 20 61 6c 6c 6f 63 61 74  QLite.** allocat
37730 65 73 20 4e 20 6f 66 20 6d 65 6d 6f 72 79 2c 20  es N of memory, 
37740 7a 65 72 6f 65 73 20 6f 75 74 20 74 68 61 74 20  zeroes out that 
37750 6d 65 6d 6f 72 79 2c 20 61 6e 64 20 72 65 74 75  memory, and retu
37760 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a  rns a pointer.**
37770 20 74 6f 20 74 68 65 20 6e 65 77 20 6d 65 6d 6f   to the new memo
37780 72 79 2e 20 5e 4f 6e 20 73 65 63 6f 6e 64 20 61  ry. ^On second a
37790 6e 64 20 73 75 62 73 65 71 75 65 6e 74 20 63 61  nd subsequent ca
377a0 6c 6c 73 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65  lls to.** sqlite
377b0 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74  3_aggregate_cont
377c0 65 78 74 28 29 20 66 6f 72 20 74 68 65 20 73 61  ext() for the sa
377d0 6d 65 20 61 67 67 72 65 67 61 74 65 20 66 75 6e  me aggregate fun
377e0 63 74 69 6f 6e 20 69 6e 73 74 61 6e 63 65 2c 0a  ction instance,.
377f0 2a 2a 20 74 68 65 20 73 61 6d 65 20 62 75 66 66  ** the same buff
37800 65 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20  er is returned. 
37810 20 53 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61   Sqlite3_aggrega
37820 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 69 73 20  te_context() is 
37830 6e 6f 72 6d 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c  normally.** call
37840 65 64 20 6f 6e 63 65 20 66 6f 72 20 65 61 63 68  ed once for each
37850 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 74   invocation of t
37860 68 65 20 78 53 74 65 70 20 63 61 6c 6c 62 61 63  he xStep callbac
37870 6b 20 61 6e 64 20 74 68 65 6e 20 6f 6e 65 0a 2a  k and then one.*
37880 2a 20 6c 61 73 74 20 74 69 6d 65 20 77 68 65 6e  * last time when
37890 20 74 68 65 20 78 46 69 6e 61 6c 20 63 61 6c 6c   the xFinal call
378a0 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 2e  back is invoked.
378b0 20 20 5e 28 57 68 65 6e 20 6e 6f 20 72 6f 77 73    ^(When no rows
378c0 20 6d 61 74 63 68 0a 2a 2a 20 61 6e 20 61 67 67   match.** an agg
378d0 72 65 67 61 74 65 20 71 75 65 72 79 2c 20 74 68  regate query, th
378e0 65 20 78 53 74 65 70 28 29 20 63 61 6c 6c 62 61  e xStep() callba
378f0 63 6b 20 6f 66 20 74 68 65 20 61 67 67 72 65 67  ck of the aggreg
37900 61 74 65 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20  ate function.** 
37910 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69  implementation i
37920 73 20 6e 65 76 65 72 20 63 61 6c 6c 65 64 20 61  s never called a
37930 6e 64 20 78 46 69 6e 61 6c 28 29 20 69 73 20 63  nd xFinal() is c
37940 61 6c 6c 65 64 20 65 78 61 63 74 6c 79 20 6f 6e  alled exactly on
37950 63 65 2e 0a 2a 2a 20 49 6e 20 74 68 6f 73 65 20  ce..** In those 
37960 63 61 73 65 73 2c 20 73 71 6c 69 74 65 33 5f 61  cases, sqlite3_a
37970 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74  ggregate_context
37980 28 29 20 6d 69 67 68 74 20 62 65 20 63 61 6c 6c  () might be call
37990 65 64 20 66 6f 72 20 74 68 65 0a 2a 2a 20 66 69  ed for the.** fi
379a0 72 73 74 20 74 69 6d 65 20 66 72 6f 6d 20 77 69  rst time from wi
379b0 74 68 69 6e 20 78 46 69 6e 61 6c 28 29 2e 29 5e  thin xFinal().)^
379c0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
379d0 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f  te3_aggregate_co
379e0 6e 74 65 78 74 28 43 2c 4e 29 20 72 6f 75 74 69  ntext(C,N) routi
379f0 6e 65 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c  ne returns a NUL
37a00 4c 20 70 6f 69 6e 74 65 72 20 0a 2a 2a 20 77 68  L pointer .** wh
37a10 65 6e 20 66 69 72 73 74 20 63 61 6c 6c 65 64 20  en first called 
37a20 69 66 20 4e 20 69 73 20 6c 65 73 73 20 74 68 61  if N is less tha
37a30 6e 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 7a 65  n or equal to ze
37a40 72 6f 20 6f 72 20 69 66 20 61 20 6d 65 6d 6f 72  ro or if a memor
37a50 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 20 65 72  y.** allocate er
37a60 72 6f 72 20 6f 63 63 75 72 73 2e 0a 2a 2a 0a 2a  ror occurs..**.*
37a70 2a 20 5e 28 54 68 65 20 61 6d 6f 75 6e 74 20 6f  * ^(The amount o
37a80 66 20 73 70 61 63 65 20 61 6c 6c 6f 63 61 74 65  f space allocate
37a90 64 20 62 79 20 73 71 6c 69 74 65 33 5f 61 67 67  d by sqlite3_agg
37aa0 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 43  regate_context(C
37ab0 2c 4e 29 20 69 73 0a 2a 2a 20 64 65 74 65 72 6d  ,N) is.** determ
37ac0 69 6e 65 64 20 62 79 20 74 68 65 20 4e 20 70 61  ined by the N pa
37ad0 72 61 6d 65 74 65 72 20 6f 6e 20 66 69 72 73 74  rameter on first
37ae0 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c   successful call
37af0 2e 20 20 43 68 61 6e 67 69 6e 67 20 74 68 65 0a  .  Changing the.
37b00 2a 2a 20 76 61 6c 75 65 20 6f 66 20 4e 20 69 6e  ** value of N in
37b10 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c   subsequent call
37b20 20 74 6f 20 73 71 6c 69 74 65 33 5f 61 67 67 72   to sqlite3_aggr
37b30 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20  egate_context() 
37b40 77 69 74 68 69 6e 0a 2a 2a 20 74 68 65 20 73 61  within.** the sa
37b50 6d 65 20 61 67 67 72 65 67 61 74 65 20 66 75 6e  me aggregate fun
37b60 63 74 69 6f 6e 20 69 6e 73 74 61 6e 63 65 20 77  ction instance w
37b70 69 6c 6c 20 6e 6f 74 20 72 65 73 69 7a 65 20 74  ill not resize t
37b80 68 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c  he memory.** all
37b90 6f 63 61 74 69 6f 6e 2e 29 5e 20 20 57 69 74 68  ocation.)^  With
37ba0 69 6e 20 74 68 65 20 78 46 69 6e 61 6c 20 63 61  in the xFinal ca
37bb0 6c 6c 62 61 63 6b 2c 20 69 74 20 69 73 20 63 75  llback, it is cu
37bc0 73 74 6f 6d 61 72 79 20 74 6f 20 73 65 74 0a 2a  stomary to set.*
37bd0 2a 20 4e 3d 30 20 69 6e 20 63 61 6c 6c 73 20 74  * N=0 in calls t
37be0 6f 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67  o sqlite3_aggreg
37bf0 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29  ate_context(C,N)
37c00 20 73 6f 20 74 68 61 74 20 6e 6f 20 0a 2a 2a 20   so that no .** 
37c10 70 6f 69 6e 74 6c 65 73 73 20 6d 65 6d 6f 72 79  pointless memory
37c20 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 6f 63 63   allocations occ
37c30 75 72 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74  ur..**.** ^SQLit
37c40 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  e automatically 
37c50 66 72 65 65 73 20 74 68 65 20 6d 65 6d 6f 72 79  frees the memory
37c60 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 0a 2a   allocated by .*
37c70 2a 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67  * sqlite3_aggreg
37c80 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 77 68  ate_context() wh
37c90 65 6e 20 74 68 65 20 61 67 67 72 65 67 61 74 65  en the aggregate
37ca0 20 71 75 65 72 79 20 63 6f 6e 63 6c 75 64 65 73   query concludes
37cb0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73  ..**.** The firs
37cc0 74 20 70 61 72 61 6d 65 74 65 72 20 6d 75 73 74  t parameter must
37cd0 20 62 65 20 61 20 63 6f 70 79 20 6f 66 20 74 68   be a copy of th
37ce0 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  e.** [sqlite3_co
37cf0 6e 74 65 78 74 20 7c 20 53 51 4c 20 66 75 6e 63  ntext | SQL func
37d00 74 69 6f 6e 20 63 6f 6e 74 65 78 74 5d 20 74 68  tion context] th
37d10 61 74 20 69 73 20 74 68 65 20 66 69 72 73 74 20  at is the first 
37d20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74 6f 20  parameter.** to 
37d30 74 68 65 20 78 53 74 65 70 20 6f 72 20 78 46 69  the xStep or xFi
37d40 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 20 72 6f 75  nal callback rou
37d50 74 69 6e 65 20 74 68 61 74 20 69 6d 70 6c 65 6d  tine that implem
37d60 65 6e 74 73 20 74 68 65 20 61 67 67 72 65 67 61  ents the aggrega
37d70 74 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e 0a  te.** function..
37d80 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69  **.** This routi
37d90 6e 65 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65  ne must be calle
37da0 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20  d from the same 
37db0 74 68 72 65 61 64 20 69 6e 20 77 68 69 63 68 0a  thread in which.
37dc0 2a 2a 20 74 68 65 20 61 67 67 72 65 67 61 74 65  ** the aggregate
37dd0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73   SQL function is
37de0 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 53 51 4c   running..*/.SQL
37df0 49 54 45 5f 41 50 49 20 76 6f 69 64 20 2a 73 71  ITE_API void *sq
37e00 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f  lite3_aggregate_
37e10 63 6f 6e 74 65 78 74 28 73 71 6c 69 74 65 33 5f  context(sqlite3_
37e20 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 6e 42  context*, int nB
37e30 79 74 65 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  ytes);../*.** CA
37e40 50 49 33 52 45 46 3a 20 55 73 65 72 20 44 61 74  PI3REF: User Dat
37e50 61 20 46 6f 72 20 46 75 6e 63 74 69 6f 6e 73 0a  a For Functions.
37e60 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
37e70 65 33 5f 63 6f 6e 74 65 78 74 0a 2a 2a 0a 2a 2a  e3_context.**.**
37e80 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 75 73   ^The sqlite3_us
37e90 65 72 5f 64 61 74 61 28 29 20 69 6e 74 65 72 66  er_data() interf
37ea0 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 63 6f  ace returns a co
37eb0 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 70 6f 69  py of.** the poi
37ec0 6e 74 65 72 20 74 68 61 74 20 77 61 73 20 74 68  nter that was th
37ed0 65 20 70 55 73 65 72 44 61 74 61 20 70 61 72 61  e pUserData para
37ee0 6d 65 74 65 72 20 28 74 68 65 20 35 74 68 20 70  meter (the 5th p
37ef0 61 72 61 6d 65 74 65 72 29 0a 2a 2a 20 6f 66 20  arameter).** of 
37f00 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  the [sqlite3_cre
37f10 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 0a  ate_function()].
37f20 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  ** and [sqlite3_
37f30 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31  create_function1
37f40 36 28 29 5d 20 72 6f 75 74 69 6e 65 73 20 74 68  6()] routines th
37f50 61 74 20 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a  at originally.**
37f60 20 72 65 67 69 73 74 65 72 65 64 20 74 68 65 20   registered the 
37f70 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69  application defi
37f80 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a  ned function..**
37f90 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65  .** This routine
37fa0 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20   must be called 
37fb0 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68  from the same th
37fc0 72 65 61 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a  read in which.**
37fd0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
37fe0 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
37ff0 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f  n is running..*/
38000 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64  .SQLITE_API void
38010 20 2a 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64   *sqlite3_user_d
38020 61 74 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ata(sqlite3_cont
38030 65 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  ext*);../*.** CA
38040 50 49 33 52 45 46 3a 20 44 61 74 61 62 61 73 65  PI3REF: Database
38050 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 46 6f 72 20   Connection For 
38060 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 4d 45 54  Functions.** MET
38070 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 63 6f 6e  HOD: sqlite3_con
38080 74 65 78 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  text.**.** ^The 
38090 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f  sqlite3_context_
380a0 64 62 5f 68 61 6e 64 6c 65 28 29 20 69 6e 74 65  db_handle() inte
380b0 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20  rface returns a 
380c0 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 70  copy of.** the p
380d0 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 64  ointer to the [d
380e0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
380f0 6f 6e 5d 20 28 74 68 65 20 31 73 74 20 70 61 72  on] (the 1st par
38100 61 6d 65 74 65 72 29 0a 2a 2a 20 6f 66 20 74 68  ameter).** of th
38110 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  e [sqlite3_creat
38120 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a  e_function()].**
38130 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72   and [sqlite3_cr
38140 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28  eate_function16(
38150 29 5d 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74  )] routines that
38160 20 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20 72   originally.** r
38170 65 67 69 73 74 65 72 65 64 20 74 68 65 20 61 70  egistered the ap
38180 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65  plication define
38190 64 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2f 0a 53  d function..*/.S
381a0 51 4c 49 54 45 5f 41 50 49 20 73 71 6c 69 74 65  QLITE_API sqlite
381b0 33 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  3 *sqlite3_conte
381c0 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 73 71 6c  xt_db_handle(sql
381d0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a  ite3_context*);.
381e0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
381f0 20 46 75 6e 63 74 69 6f 6e 20 41 75 78 69 6c 69   Function Auxili
38200 61 72 79 20 44 61 74 61 0a 2a 2a 20 4d 45 54 48  ary Data.** METH
38210 4f 44 3a 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74  OD: sqlite3_cont
38220 65 78 74 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ext.**.** These 
38230 66 75 6e 63 74 69 6f 6e 73 20 6d 61 79 20 62 65  functions may be
38240 20 75 73 65 64 20 62 79 20 28 6e 6f 6e 2d 61 67   used by (non-ag
38250 67 72 65 67 61 74 65 29 20 53 51 4c 20 66 75 6e  gregate) SQL fun
38260 63 74 69 6f 6e 73 20 74 6f 0a 2a 2a 20 61 73 73  ctions to.** ass
38270 6f 63 69 61 74 65 20 6d 65 74 61 64 61 74 61 20  ociate metadata 
38280 77 69 74 68 20 61 72 67 75 6d 65 6e 74 20 76 61  with argument va
38290 6c 75 65 73 2e 20 49 66 20 74 68 65 20 73 61 6d  lues. If the sam
382a0 65 20 76 61 6c 75 65 20 69 73 20 70 61 73 73 65  e value is passe
382b0 64 20 74 6f 0a 2a 2a 20 6d 75 6c 74 69 70 6c 65  d to.** multiple
382c0 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20   invocations of 
382d0 74 68 65 20 73 61 6d 65 20 53 51 4c 20 66 75 6e  the same SQL fun
382e0 63 74 69 6f 6e 20 64 75 72 69 6e 67 20 71 75 65  ction during que
382f0 72 79 20 65 78 65 63 75 74 69 6f 6e 2c 20 75 6e  ry execution, un
38300 64 65 72 0a 2a 2a 20 73 6f 6d 65 20 63 69 72 63  der.** some circ
38310 75 6d 73 74 61 6e 63 65 73 20 74 68 65 20 61 73  umstances the as
38320 73 6f 63 69 61 74 65 64 20 6d 65 74 61 64 61 74  sociated metadat
38330 61 20 6d 61 79 20 62 65 20 70 72 65 73 65 72 76  a may be preserv
38340 65 64 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65 0a  ed.  An example.
38350 2a 2a 20 6f 66 20 77 68 65 72 65 20 74 68 69 73  ** of where this
38360 20 6d 69 67 68 74 20 62 65 20 75 73 65 66 75 6c   might be useful
38370 20 69 73 20 69 6e 20 61 20 72 65 67 75 6c 61 72   is in a regular
38380 2d 65 78 70 72 65 73 73 69 6f 6e 20 6d 61 74 63  -expression matc
38390 68 69 6e 67 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  hing.** function
383a0 2e 20 54 68 65 20 63 6f 6d 70 69 6c 65 64 20 76  . The compiled v
383b0 65 72 73 69 6f 6e 20 6f 66 20 74 68 65 20 72 65  ersion of the re
383c0 67 75 6c 61 72 20 65 78 70 72 65 73 73 69 6f 6e  gular expression
383d0 20 63 61 6e 20 62 65 20 73 74 6f 72 65 64 20 61   can be stored a
383e0 73 0a 2a 2a 20 6d 65 74 61 64 61 74 61 20 61 73  s.** metadata as
383f0 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68  sociated with th
38400 65 20 70 61 74 74 65 72 6e 20 73 74 72 69 6e 67  e pattern string
38410 2e 20 20 0a 2a 2a 20 54 68 65 6e 20 61 73 20 6c  .  .** Then as l
38420 6f 6e 67 20 61 73 20 74 68 65 20 70 61 74 74 65  ong as the patte
38430 72 6e 20 73 74 72 69 6e 67 20 72 65 6d 61 69 6e  rn string remain
38440 73 20 74 68 65 20 73 61 6d 65 2c 0a 2a 2a 20 74  s the same,.** t
38450 68 65 20 63 6f 6d 70 69 6c 65 64 20 72 65 67 75  he compiled regu
38460 6c 61 72 20 65 78 70 72 65 73 73 69 6f 6e 20 63  lar expression c
38470 61 6e 20 62 65 20 72 65 75 73 65 64 20 6f 6e 20  an be reused on 
38480 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 69 6e 76 6f  multiple.** invo
38490 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73  cations of the s
384a0 61 6d 65 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a  ame function..**
384b0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
384c0 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29 20 69  _get_auxdata() i
384d0 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
384e0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   a pointer to th
384f0 65 20 6d 65 74 61 64 61 74 61 0a 2a 2a 20 61 73  e metadata.** as
38500 73 6f 63 69 61 74 65 64 20 62 79 20 74 68 65 20  sociated by the 
38510 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64  sqlite3_set_auxd
38520 61 74 61 28 29 20 66 75 6e 63 74 69 6f 6e 20 77  ata() function w
38530 69 74 68 20 74 68 65 20 4e 74 68 20 61 72 67 75  ith the Nth argu
38540 6d 65 6e 74 0a 2a 2a 20 76 61 6c 75 65 20 74 6f  ment.** value to
38550 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
38560 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
38570 6e 2e 20 5e 49 66 20 74 68 65 72 65 20 69 73 20  n. ^If there is 
38580 6e 6f 20 6d 65 74 61 64 61 74 61 0a 2a 2a 20 61  no metadata.** a
38590 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74  ssociated with t
385a0 68 65 20 66 75 6e 63 74 69 6f 6e 20 61 72 67 75  he function argu
385b0 6d 65 6e 74 2c 20 74 68 69 73 20 73 71 6c 69 74  ment, this sqlit
385c0 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29  e3_get_auxdata()
385d0 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 72 65   interface.** re
385e0 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69  turns a NULL poi
385f0 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  nter..**.** ^The
38600 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78   sqlite3_set_aux
38610 64 61 74 61 28 43 2c 4e 2c 50 2c 58 29 20 69 6e  data(C,N,P,X) in
38620 74 65 72 66 61 63 65 20 73 61 76 65 73 20 50 20  terface saves P 
38630 61 73 20 6d 65 74 61 64 61 74 61 20 66 6f 72 20  as metadata for 
38640 74 68 65 20 4e 2d 74 68 0a 2a 2a 20 61 72 67 75  the N-th.** argu
38650 6d 65 6e 74 20 6f 66 20 74 68 65 20 61 70 70 6c  ment of the appl
38660 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
38670 66 75 6e 63 74 69 6f 6e 2e 20 20 5e 53 75 62 73  function.  ^Subs
38680 65 71 75 65 6e 74 0a 2a 2a 20 63 61 6c 6c 73 20  equent.** calls 
38690 74 6f 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61  to sqlite3_get_a
386a0 75 78 64 61 74 61 28 43 2c 4e 29 20 72 65 74 75  uxdata(C,N) retu
386b0 72 6e 20 50 20 66 72 6f 6d 20 74 68 65 20 6d 6f  rn P from the mo
386c0 73 74 20 72 65 63 65 6e 74 0a 2a 2a 20 73 71 6c  st recent.** sql
386d0 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61  ite3_set_auxdata
386e0 28 43 2c 4e 2c 50 2c 58 29 20 63 61 6c 6c 20 69  (C,N,P,X) call i
386f0 66 20 74 68 65 20 6d 65 74 61 64 61 74 61 20 69  f the metadata i
38700 73 20 73 74 69 6c 6c 20 76 61 6c 69 64 20 6f 72  s still valid or
38710 0a 2a 2a 20 4e 55 4c 4c 20 69 66 20 74 68 65 20  .** NULL if the 
38720 6d 65 74 61 64 61 74 61 20 68 61 73 20 62 65 65  metadata has bee
38730 6e 20 64 69 73 63 61 72 64 65 64 2e 0a 2a 2a 20  n discarded..** 
38740 5e 41 66 74 65 72 20 65 61 63 68 20 63 61 6c 6c  ^After each call
38750 20 74 6f