System.Data.SQLite
Hex Artifact Content
Not logged in

Artifact 524292bbc18a7fb6e39cbfc3524fea602bf963dc:


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 20  -in (UTC) and a 
1090: 53 48 41 31 0a 2a 2a 20 6f 72 20 53 48 41 33 2d  SHA1.** or SHA3-
10a0: 32 35 36 20 68 61 73 68 20 6f 66 20 74 68 65 20  256 hash of the 
10b0: 65 6e 74 69 72 65 20 73 6f 75 72 63 65 20 74 72  entire source tr
10c0: 65 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  ee..**.** See al
10d0: 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 6c 69 62  so: [sqlite3_lib
10e0: 76 65 72 73 69 6f 6e 28 29 5d 2c 0a 2a 2a 20 5b  version()],.** [
10f0: 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69  sqlite3_libversi
1100: 6f 6e 5f 6e 75 6d 62 65 72 28 29 5d 2c 20 5b 73  on_number()], [s
1110: 71 6c 69 74 65 33 5f 73 6f 75 72 63 65 69 64 28  qlite3_sourceid(
1120: 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 5f 76  )],.** [sqlite_v
1130: 65 72 73 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73  ersion()] and [s
1140: 71 6c 69 74 65 5f 73 6f 75 72 63 65 5f 69 64 28  qlite_source_id(
1150: 29 5d 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  )]..*/.#define S
1160: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 20 20 20  QLITE_VERSION   
1170: 20 20 20 20 20 22 33 2e 31 39 2e 32 22 0a 23 64       "3.19.2".#d
1180: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 56 45 52  efine SQLITE_VER
1190: 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 33 30 31 39  SION_NUMBER 3019
11a0: 30 30 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  002.#define SQLI
11b0: 54 45 5f 53 4f 55 52 43 45 5f 49 44 20 20 20 20  TE_SOURCE_ID    
11c0: 20 20 22 32 30 31 37 2d 30 35 2d 32 35 20 31 36    "2017-05-25 16
11d0: 3a 35 30 3a 32 37 20 65 64 62 34 65 38 31 39 62  :50:27 edb4e819b
11e0: 30 63 30 35 38 63 37 64 37 34 64 32 37 65 62 64  0c058c7d74d27ebd
11f0: 31 34 63 63 35 63 65 62 32 62 61 64 36 61 36 31  14cc5ceb2bad6a61
1200: 34 34 61 34 38 36 61 39 37 30 31 38 32 62 37 61  44a486a970182b7a
1210: 66 65 33 66 38 62 39 22 0a 0a 2f 2a 0a 2a 2a 20  fe3f8b9"../*.** 
1220: 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 54 69  CAPI3REF: Run-Ti
1230: 6d 65 20 4c 69 62 72 61 72 79 20 56 65 72 73 69  me Library Versi
1240: 6f 6e 20 4e 75 6d 62 65 72 73 0a 2a 2a 20 4b 45  on Numbers.** KE
1250: 59 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 33 5f  YWORDS: sqlite3_
1260: 76 65 72 73 69 6f 6e 20 73 71 6c 69 74 65 33 5f  version sqlite3_
1270: 73 6f 75 72 63 65 69 64 0a 2a 2a 0a 2a 2a 20 54  sourceid.**.** T
1280: 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 20  hese interfaces 
1290: 70 72 6f 76 69 64 65 20 74 68 65 20 73 61 6d 65  provide the same
12a0: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 73 20   information as 
12b0: 74 68 65 20 5b 53 51 4c 49 54 45 5f 56 45 52 53  the [SQLITE_VERS
12c0: 49 4f 4e 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45  ION],.** [SQLITE
12d0: 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d  _VERSION_NUMBER]
12e0: 2c 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 53 4f  , and [SQLITE_SO
12f0: 55 52 43 45 5f 49 44 5d 20 43 20 70 72 65 70 72  URCE_ID] C prepr
1300: 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 73 0a 2a  ocessor macros.*
1310: 2a 20 62 75 74 20 61 72 65 20 61 73 73 6f 63 69  * but are associ
1320: 61 74 65 64 20 77 69 74 68 20 74 68 65 20 6c 69  ated with the li
1330: 62 72 61 72 79 20 69 6e 73 74 65 61 64 20 6f 66  brary instead of
1340: 20 74 68 65 20 68 65 61 64 65 72 20 66 69 6c 65   the header file
1350: 2e 20 20 5e 28 43 61 75 74 69 6f 75 73 0a 2a 2a  .  ^(Cautious.**
1360: 20 70 72 6f 67 72 61 6d 6d 65 72 73 20 6d 69 67   programmers mig
1370: 68 74 20 69 6e 63 6c 75 64 65 20 61 73 73 65 72  ht include asser
1380: 74 28 29 20 73 74 61 74 65 6d 65 6e 74 73 20 69  t() statements i
1390: 6e 20 74 68 65 69 72 20 61 70 70 6c 69 63 61 74  n their applicat
13a0: 69 6f 6e 20 74 6f 0a 2a 2a 20 76 65 72 69 66 79  ion to.** verify
13b0: 20 74 68 61 74 20 76 61 6c 75 65 73 20 72 65 74   that values ret
13c0: 75 72 6e 65 64 20 62 79 20 74 68 65 73 65 20 69  urned by these i
13d0: 6e 74 65 72 66 61 63 65 73 20 6d 61 74 63 68 20  nterfaces match 
13e0: 74 68 65 20 6d 61 63 72 6f 73 20 69 6e 0a 2a 2a  the macros in.**
13f0: 20 74 68 65 20 68 65 61 64 65 72 2c 20 61 6e 64   the header, and
1400: 20 74 68 75 73 20 65 6e 73 75 72 65 20 74 68 61   thus ensure tha
1410: 74 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  t the applicatio
1420: 6e 20 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64  n is.** compiled
1430: 20 77 69 74 68 20 6d 61 74 63 68 69 6e 67 20 6c   with matching l
1440: 69 62 72 61 72 79 20 61 6e 64 20 68 65 61 64 65  ibrary and heade
1450: 72 20 66 69 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 3c  r files..**.** <
1460: 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e  blockquote><pre>
1470: 0a 2a 2a 20 61 73 73 65 72 74 28 20 73 71 6c 69  .** assert( sqli
1480: 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e  te3_libversion_n
1490: 75 6d 62 65 72 28 29 3d 3d 53 51 4c 49 54 45 5f  umber()==SQLITE_
14a0: 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 29  VERSION_NUMBER )
14b0: 3b 0a 2a 2a 20 61 73 73 65 72 74 28 20 73 74 72  ;.** assert( str
14c0: 63 6d 70 28 73 71 6c 69 74 65 33 5f 73 6f 75 72  cmp(sqlite3_sour
14d0: 63 65 69 64 28 29 2c 53 51 4c 49 54 45 5f 53 4f  ceid(),SQLITE_SO
14e0: 55 52 43 45 5f 49 44 29 3d 3d 30 20 29 3b 0a 2a  URCE_ID)==0 );.*
14f0: 2a 20 61 73 73 65 72 74 28 20 73 74 72 63 6d 70  * assert( strcmp
1500: 28 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73  (sqlite3_libvers
1510: 69 6f 6e 28 29 2c 53 51 4c 49 54 45 5f 56 45 52  ion(),SQLITE_VER
1520: 53 49 4f 4e 29 3d 3d 30 20 29 3b 0a 2a 2a 20 3c  SION)==0 );.** <
1530: 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
1540: 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  e>)^.**.** ^The 
1550: 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b  sqlite3_version[
1560: 5d 20 73 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e  ] string constan
1570: 74 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 20 74  t contains the t
1580: 65 78 74 20 6f 66 20 5b 53 51 4c 49 54 45 5f 56  ext of [SQLITE_V
1590: 45 52 53 49 4f 4e 5d 0a 2a 2a 20 6d 61 63 72 6f  ERSION].** macro
15a0: 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  .  ^The sqlite3_
15b0: 6c 69 62 76 65 72 73 69 6f 6e 28 29 20 66 75 6e  libversion() fun
15c0: 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 61 20  ction returns a 
15d0: 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 0a 2a  pointer to the.*
15e0: 2a 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33  * to the sqlite3
15f0: 5f 76 65 72 73 69 6f 6e 5b 5d 20 73 74 72 69 6e  _version[] strin
1600: 67 20 63 6f 6e 73 74 61 6e 74 2e 20 20 54 68 65  g constant.  The
1610: 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73   sqlite3_libvers
1620: 69 6f 6e 28 29 0a 2a 2a 20 66 75 6e 63 74 69 6f  ion().** functio
1630: 6e 20 69 73 20 70 72 6f 76 69 64 65 64 20 66 6f  n is provided fo
1640: 72 20 75 73 65 20 69 6e 20 44 4c 4c 73 20 73 69  r use in DLLs si
1650: 6e 63 65 20 44 4c 4c 20 75 73 65 72 73 20 75 73  nce DLL users us
1660: 75 61 6c 6c 79 20 64 6f 20 6e 6f 74 20 68 61 76  ually do not hav
1670: 65 0a 2a 2a 20 64 69 72 65 63 74 20 61 63 63 65  e.** direct acce
1680: 73 73 20 74 6f 20 73 74 72 69 6e 67 20 63 6f 6e  ss to string con
1690: 73 74 61 6e 74 73 20 77 69 74 68 69 6e 20 74 68  stants within th
16a0: 65 20 44 4c 4c 2e 20 20 5e 54 68 65 0a 2a 2a 20  e DLL.  ^The.** 
16b0: 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69  sqlite3_libversi
16c0: 6f 6e 5f 6e 75 6d 62 65 72 28 29 20 66 75 6e 63  on_number() func
16d0: 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 61 6e 20  tion returns an 
16e0: 69 6e 74 65 67 65 72 20 65 71 75 61 6c 20 74 6f  integer equal to
16f0: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 56 45 52 53  .** [SQLITE_VERS
1700: 49 4f 4e 5f 4e 55 4d 42 45 52 5d 2e 20 20 5e 54  ION_NUMBER].  ^T
1710: 68 65 20 73 71 6c 69 74 65 33 5f 73 6f 75 72 63  he sqlite3_sourc
1720: 65 69 64 28 29 20 66 75 6e 63 74 69 6f 6e 20 72  eid() function r
1730: 65 74 75 72 6e 73 20 0a 2a 2a 20 61 20 70 6f 69  eturns .** a poi
1740: 6e 74 65 72 20 74 6f 20 61 20 73 74 72 69 6e 67  nter to a string
1750: 20 63 6f 6e 73 74 61 6e 74 20 77 68 6f 73 65 20   constant whose 
1760: 76 61 6c 75 65 20 69 73 20 74 68 65 20 73 61 6d  value is the sam
1770: 65 20 61 73 20 74 68 65 20 0a 2a 2a 20 5b 53 51  e as the .** [SQ
1780: 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 5d 20  LITE_SOURCE_ID] 
1790: 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d  C preprocessor m
17a0: 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  acro..**.** See 
17b0: 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 5f 76 65  also: [sqlite_ve
17c0: 72 73 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71  rsion()] and [sq
17d0: 6c 69 74 65 5f 73 6f 75 72 63 65 5f 69 64 28 29  lite_source_id()
17e0: 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  ]..*/.SQLITE_API
17f0: 20 53 51 4c 49 54 45 5f 45 58 54 45 52 4e 20 63   SQLITE_EXTERN c
1800: 6f 6e 73 74 20 63 68 61 72 20 73 71 6c 69 74 65  onst char sqlite
1810: 33 5f 76 65 72 73 69 6f 6e 5b 5d 3b 0a 53 51 4c  3_version[];.SQL
1820: 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68  ITE_API const ch
1830: 61 72 20 2a 73 71 6c 69 74 65 33 5f 6c 69 62 76  ar *sqlite3_libv
1840: 65 72 73 69 6f 6e 28 76 6f 69 64 29 3b 0a 53 51  ersion(void);.SQ
1850: 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63  LITE_API const c
1860: 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 73 6f 75  har *sqlite3_sou
1870: 72 63 65 69 64 28 76 6f 69 64 29 3b 0a 53 51 4c  rceid(void);.SQL
1880: 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
1890: 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e  te3_libversion_n
18a0: 75 6d 62 65 72 28 76 6f 69 64 29 3b 0a 0a 2f 2a  umber(void);../*
18b0: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 75  .** CAPI3REF: Ru
18c0: 6e 2d 54 69 6d 65 20 4c 69 62 72 61 72 79 20 43  n-Time Library C
18d0: 6f 6d 70 69 6c 61 74 69 6f 6e 20 4f 70 74 69 6f  ompilation Optio
18e0: 6e 73 20 44 69 61 67 6e 6f 73 74 69 63 73 0a 2a  ns Diagnostics.*
18f0: 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
1900: 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f  3_compileoption_
1910: 75 73 65 64 28 29 20 66 75 6e 63 74 69 6f 6e 20  used() function 
1920: 72 65 74 75 72 6e 73 20 30 20 6f 72 20 31 20 0a  returns 0 or 1 .
1930: 2a 2a 20 69 6e 64 69 63 61 74 69 6e 67 20 77 68  ** indicating wh
1940: 65 74 68 65 72 20 74 68 65 20 73 70 65 63 69 66  ether the specif
1950: 69 65 64 20 6f 70 74 69 6f 6e 20 77 61 73 20 64  ied option was d
1960: 65 66 69 6e 65 64 20 61 74 20 0a 2a 2a 20 63 6f  efined at .** co
1970: 6d 70 69 6c 65 20 74 69 6d 65 2e 20 20 5e 54 68  mpile time.  ^Th
1980: 65 20 53 51 4c 49 54 45 5f 20 70 72 65 66 69 78  e SQLITE_ prefix
1990: 20 6d 61 79 20 62 65 20 6f 6d 69 74 74 65 64 20   may be omitted 
19a0: 66 72 6f 6d 20 74 68 65 20 0a 2a 2a 20 6f 70 74  from the .** opt
19b0: 69 6f 6e 20 6e 61 6d 65 20 70 61 73 73 65 64 20  ion name passed 
19c0: 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69  to sqlite3_compi
19d0: 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28 29 2e  leoption_used().
19e0: 20 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71    .**.** ^The sq
19f0: 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74  lite3_compileopt
1a00: 69 6f 6e 5f 67 65 74 28 29 20 66 75 6e 63 74 69  ion_get() functi
1a10: 6f 6e 20 61 6c 6c 6f 77 73 20 69 74 65 72 61 74  on allows iterat
1a20: 69 6e 67 0a 2a 2a 20 6f 76 65 72 20 74 68 65 20  ing.** over the 
1a30: 6c 69 73 74 20 6f 66 20 6f 70 74 69 6f 6e 73 20  list of options 
1a40: 74 68 61 74 20 77 65 72 65 20 64 65 66 69 6e 65  that were define
1a50: 64 20 61 74 20 63 6f 6d 70 69 6c 65 20 74 69 6d  d at compile tim
1a60: 65 20 62 79 0a 2a 2a 20 72 65 74 75 72 6e 69 6e  e by.** returnin
1a70: 67 20 74 68 65 20 4e 2d 74 68 20 63 6f 6d 70 69  g the N-th compi
1a80: 6c 65 20 74 69 6d 65 20 6f 70 74 69 6f 6e 20 73  le time option s
1a90: 74 72 69 6e 67 2e 20 20 5e 49 66 20 4e 20 69 73  tring.  ^If N is
1aa0: 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 2c 0a 2a   out of range,.*
1ab0: 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c  * sqlite3_compil
1ac0: 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29 20 72 65  eoption_get() re
1ad0: 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69  turns a NULL poi
1ae0: 6e 74 65 72 2e 20 20 5e 54 68 65 20 53 51 4c 49  nter.  ^The SQLI
1af0: 54 45 5f 20 0a 2a 2a 20 70 72 65 66 69 78 20 69  TE_ .** prefix i
1b00: 73 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 61  s omitted from a
1b10: 6e 79 20 73 74 72 69 6e 67 73 20 72 65 74 75 72  ny strings retur
1b20: 6e 65 64 20 62 79 20 0a 2a 2a 20 73 71 6c 69 74  ned by .** sqlit
1b30: 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e  e3_compileoption
1b40: 5f 67 65 74 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 53  _get()..**.** ^S
1b50: 75 70 70 6f 72 74 20 66 6f 72 20 74 68 65 20 64  upport for the d
1b60: 69 61 67 6e 6f 73 74 69 63 20 66 75 6e 63 74 69  iagnostic functi
1b70: 6f 6e 73 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70  ons sqlite3_comp
1b80: 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28 29  ileoption_used()
1b90: 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  .** and sqlite3_
1ba0: 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65  compileoption_ge
1bb0: 74 28 29 20 6d 61 79 20 62 65 20 6f 6d 69 74 74  t() may be omitt
1bc0: 65 64 20 62 79 20 73 70 65 63 69 66 79 69 6e 67  ed by specifying
1bd0: 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45   the .** [SQLITE
1be0: 5f 4f 4d 49 54 5f 43 4f 4d 50 49 4c 45 4f 50 54  _OMIT_COMPILEOPT
1bf0: 49 4f 4e 5f 44 49 41 47 53 5d 20 6f 70 74 69 6f  ION_DIAGS] optio
1c00: 6e 20 61 74 20 63 6f 6d 70 69 6c 65 20 74 69 6d  n at compile tim
1c10: 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  e..**.** See als
1c20: 6f 3a 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  o: SQL functions
1c30: 20 5b 73 71 6c 69 74 65 5f 63 6f 6d 70 69 6c 65   [sqlite_compile
1c40: 6f 70 74 69 6f 6e 5f 75 73 65 64 28 29 5d 20 61  option_used()] a
1c50: 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 5f 63 6f  nd.** [sqlite_co
1c60: 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28  mpileoption_get(
1c70: 29 5d 20 61 6e 64 20 74 68 65 20 5b 63 6f 6d 70  )] and the [comp
1c80: 69 6c 65 5f 6f 70 74 69 6f 6e 73 20 70 72 61 67  ile_options prag
1c90: 6d 61 5d 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 20  ma]..*/.#ifndef 
1ca0: 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 43 4f 4d 50  SQLITE_OMIT_COMP
1cb0: 49 4c 45 4f 50 54 49 4f 4e 5f 44 49 41 47 53 0a  ILEOPTION_DIAGS.
1cc0: 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
1cd0: 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70  qlite3_compileop
1ce0: 74 69 6f 6e 5f 75 73 65 64 28 63 6f 6e 73 74 20  tion_used(const 
1cf0: 63 68 61 72 20 2a 7a 4f 70 74 4e 61 6d 65 29 3b  char *zOptName);
1d00: 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73  .SQLITE_API cons
1d10: 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
1d20: 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65  compileoption_ge
1d30: 74 28 69 6e 74 20 4e 29 3b 0a 23 65 6e 64 69 66  t(int N);.#endif
1d40: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1d50: 3a 20 54 65 73 74 20 54 6f 20 53 65 65 20 49 66  : Test To See If
1d60: 20 54 68 65 20 4c 69 62 72 61 72 79 20 49 73 20   The Library Is 
1d70: 54 68 72 65 61 64 73 61 66 65 0a 2a 2a 0a 2a 2a  Threadsafe.**.**
1d80: 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 74 68   ^The sqlite3_th
1d90: 72 65 61 64 73 61 66 65 28 29 20 66 75 6e 63 74  readsafe() funct
1da0: 69 6f 6e 20 72 65 74 75 72 6e 73 20 7a 65 72 6f  ion returns zero
1db0: 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a   if and only if.
1dc0: 2a 2a 20 53 51 4c 69 74 65 20 77 61 73 20 63 6f  ** SQLite was co
1dd0: 6d 70 69 6c 65 64 20 77 69 74 68 20 6d 75 74 65  mpiled with mute
1de0: 78 69 6e 67 20 63 6f 64 65 20 6f 6d 69 74 74 65  xing code omitte
1df0: 64 20 64 75 65 20 74 6f 20 74 68 65 0a 2a 2a 20  d due to the.** 
1e00: 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41  [SQLITE_THREADSA
1e10: 46 45 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  FE] compile-time
1e20: 20 6f 70 74 69 6f 6e 20 62 65 69 6e 67 20 73 65   option being se
1e30: 74 20 74 6f 20 30 2e 0a 2a 2a 0a 2a 2a 20 53 51  t to 0..**.** SQ
1e40: 4c 69 74 65 20 63 61 6e 20 62 65 20 63 6f 6d 70  Lite can be comp
1e50: 69 6c 65 64 20 77 69 74 68 20 6f 72 20 77 69 74  iled with or wit
1e60: 68 6f 75 74 20 6d 75 74 65 78 65 73 2e 20 20 57  hout mutexes.  W
1e70: 68 65 6e 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49  hen.** the [SQLI
1e80: 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20 43  TE_THREADSAFE] C
1e90: 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61   preprocessor ma
1ea0: 63 72 6f 20 69 73 20 31 20 6f 72 20 32 2c 20 6d  cro is 1 or 2, m
1eb0: 75 74 65 78 65 73 0a 2a 2a 20 61 72 65 20 65 6e  utexes.** are en
1ec0: 61 62 6c 65 64 20 61 6e 64 20 53 51 4c 69 74 65  abled and SQLite
1ed0: 20 69 73 20 74 68 72 65 61 64 73 61 66 65 2e 20   is threadsafe. 
1ee0: 20 57 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 53 51   When the.** [SQ
1ef0: 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d  LITE_THREADSAFE]
1f00: 20 6d 61 63 72 6f 20 69 73 20 30 2c 20 0a 2a 2a   macro is 0, .**
1f10: 20 74 68 65 20 6d 75 74 65 78 65 73 20 61 72 65   the mutexes are
1f20: 20 6f 6d 69 74 74 65 64 2e 20 20 57 69 74 68 6f   omitted.  Witho
1f30: 75 74 20 74 68 65 20 6d 75 74 65 78 65 73 2c 20  ut the mutexes, 
1f40: 69 74 20 69 73 20 6e 6f 74 20 73 61 66 65 0a 2a  it is not safe.*
1f50: 2a 20 74 6f 20 75 73 65 20 53 51 4c 69 74 65 20  * to use SQLite 
1f60: 63 6f 6e 63 75 72 72 65 6e 74 6c 79 20 66 72 6f  concurrently fro
1f70: 6d 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20  m more than one 
1f80: 74 68 72 65 61 64 2e 0a 2a 2a 0a 2a 2a 20 45 6e  thread..**.** En
1f90: 61 62 6c 69 6e 67 20 6d 75 74 65 78 65 73 20 69  abling mutexes i
1fa0: 6e 63 75 72 73 20 61 20 6d 65 61 73 75 72 61 62  ncurs a measurab
1fb0: 6c 65 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 70  le performance p
1fc0: 65 6e 61 6c 74 79 2e 0a 2a 2a 20 53 6f 20 69 66  enalty..** So if
1fd0: 20 73 70 65 65 64 20 69 73 20 6f 66 20 75 74 6d   speed is of utm
1fe0: 6f 73 74 20 69 6d 70 6f 72 74 61 6e 63 65 2c 20  ost importance, 
1ff0: 69 74 20 6d 61 6b 65 73 20 73 65 6e 73 65 20 74  it makes sense t
2000: 6f 20 64 69 73 61 62 6c 65 0a 2a 2a 20 74 68 65  o disable.** the
2010: 20 6d 75 74 65 78 65 73 2e 20 20 42 75 74 20 66   mutexes.  But f
2020: 6f 72 20 6d 61 78 69 6d 75 6d 20 73 61 66 65 74  or maximum safet
2030: 79 2c 20 6d 75 74 65 78 65 73 20 73 68 6f 75 6c  y, mutexes shoul
2040: 64 20 62 65 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a  d be enabled..**
2050: 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20 62 65   ^The default be
2060: 68 61 76 69 6f 72 20 69 73 20 66 6f 72 20 6d 75  havior is for mu
2070: 74 65 78 65 73 20 74 6f 20 62 65 20 65 6e 61 62  texes to be enab
2080: 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  led..**.** This 
2090: 69 6e 74 65 72 66 61 63 65 20 63 61 6e 20 62 65  interface can be
20a0: 20 75 73 65 64 20 62 79 20 61 6e 20 61 70 70 6c   used by an appl
20b0: 69 63 61 74 69 6f 6e 20 74 6f 20 6d 61 6b 65 20  ication to make 
20c0: 73 75 72 65 20 74 68 61 74 20 74 68 65 0a 2a 2a  sure that the.**
20d0: 20 76 65 72 73 69 6f 6e 20 6f 66 20 53 51 4c 69   version of SQLi
20e0: 74 65 20 74 68 61 74 20 69 74 20 69 73 20 6c 69  te that it is li
20f0: 6e 6b 69 6e 67 20 61 67 61 69 6e 73 74 20 77 61  nking against wa
2100: 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a  s compiled with.
2110: 2a 2a 20 74 68 65 20 64 65 73 69 72 65 64 20 73  ** the desired s
2120: 65 74 74 69 6e 67 20 6f 66 20 74 68 65 20 5b 53  etting of the [S
2130: 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
2140: 5d 20 6d 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 54  ] macro..**.** T
2150: 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 6f 6e  his interface on
2160: 6c 79 20 72 65 70 6f 72 74 73 20 6f 6e 20 74 68  ly reports on th
2170: 65 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6d  e compile-time m
2180: 75 74 65 78 20 73 65 74 74 69 6e 67 0a 2a 2a 20  utex setting.** 
2190: 6f 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54  of the [SQLITE_T
21a0: 48 52 45 41 44 53 41 46 45 5d 20 66 6c 61 67 2e  HREADSAFE] flag.
21b0: 20 20 49 66 20 53 51 4c 69 74 65 20 69 73 20 63    If SQLite is c
21c0: 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20  ompiled with.** 
21d0: 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
21e0: 45 3d 31 20 6f 72 20 3d 32 20 74 68 65 6e 20 6d  E=1 or =2 then m
21f0: 75 74 65 78 65 73 20 61 72 65 20 65 6e 61 62 6c  utexes are enabl
2200: 65 64 20 62 79 20 64 65 66 61 75 6c 74 20 62 75  ed by default bu
2210: 74 0a 2a 2a 20 63 61 6e 20 62 65 20 66 75 6c 6c  t.** can be full
2220: 79 20 6f 72 20 70 61 72 74 69 61 6c 6c 79 20 64  y or partially d
2230: 69 73 61 62 6c 65 64 20 75 73 69 6e 67 20 61 20  isabled using a 
2240: 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
2250: 5f 63 6f 6e 66 69 67 28 29 5d 0a 2a 2a 20 77 69  _config()].** wi
2260: 74 68 20 74 68 65 20 76 65 72 62 73 20 5b 53 51  th the verbs [SQ
2270: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47  LITE_CONFIG_SING
2280: 4c 45 54 48 52 45 41 44 5d 2c 20 5b 53 51 4c 49  LETHREAD], [SQLI
2290: 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54  TE_CONFIG_MULTIT
22a0: 48 52 45 41 44 5d 2c 0a 2a 2a 20 6f 72 20 5b 53  HREAD],.** or [S
22b0: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52  QLITE_CONFIG_SER
22c0: 49 41 4c 49 5a 45 44 5d 2e 20 20 5e 28 54 68 65  IALIZED].  ^(The
22d0: 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66   return value of
22e0: 20 74 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   the.** sqlite3_
22f0: 74 68 72 65 61 64 73 61 66 65 28 29 20 66 75 6e  threadsafe() fun
2300: 63 74 69 6f 6e 20 73 68 6f 77 73 20 6f 6e 6c 79  ction shows only
2310: 20 74 68 65 20 63 6f 6d 70 69 6c 65 2d 74 69 6d   the compile-tim
2320: 65 20 73 65 74 74 69 6e 67 20 6f 66 0a 2a 2a 20  e setting of.** 
2330: 74 68 72 65 61 64 20 73 61 66 65 74 79 2c 20 6e  thread safety, n
2340: 6f 74 20 61 6e 79 20 72 75 6e 2d 74 69 6d 65 20  ot any run-time 
2350: 63 68 61 6e 67 65 73 20 74 6f 20 74 68 61 74 20  changes to that 
2360: 73 65 74 74 69 6e 67 20 6d 61 64 65 20 62 79 0a  setting made by.
2370: 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  ** sqlite3_confi
2380: 67 28 29 2e 20 49 6e 20 6f 74 68 65 72 20 77 6f  g(). In other wo
2390: 72 64 73 2c 20 74 68 65 20 72 65 74 75 72 6e 20  rds, the return 
23a0: 76 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74  value from sqlit
23b0: 65 33 5f 74 68 72 65 61 64 73 61 66 65 28 29 0a  e3_threadsafe().
23c0: 2a 2a 20 69 73 20 75 6e 63 68 61 6e 67 65 64 20  ** is unchanged 
23d0: 62 79 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69  by calls to sqli
23e0: 74 65 33 5f 63 6f 6e 66 69 67 28 29 2e 29 5e 0a  te3_config().)^.
23f0: 2a 2a 0a 2a 2a 20 53 65 65 20 74 68 65 20 5b 74  **.** See the [t
2400: 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 64  hreading mode] d
2410: 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72  ocumentation for
2420: 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f   additional info
2430: 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a 53 51 4c 49  rmation..*/.SQLI
2440: 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
2450: 65 33 5f 74 68 72 65 61 64 73 61 66 65 28 76 6f  e3_threadsafe(vo
2460: 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  id);../*.** CAPI
2470: 33 52 45 46 3a 20 44 61 74 61 62 61 73 65 20 43  3REF: Database C
2480: 6f 6e 6e 65 63 74 69 6f 6e 20 48 61 6e 64 6c 65  onnection Handle
2490: 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 64  .** KEYWORDS: {d
24a0: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
24b0: 6f 6e 7d 20 7b 64 61 74 61 62 61 73 65 20 63 6f  on} {database co
24c0: 6e 6e 65 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a  nnections}.**.**
24d0: 20 45 61 63 68 20 6f 70 65 6e 20 53 51 4c 69 74   Each open SQLit
24e0: 65 20 64 61 74 61 62 61 73 65 20 69 73 20 72 65  e database is re
24f0: 70 72 65 73 65 6e 74 65 64 20 62 79 20 61 20 70  presented by a p
2500: 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73  ointer to an ins
2510: 74 61 6e 63 65 20 6f 66 0a 2a 2a 20 74 68 65 20  tance of.** the 
2520: 6f 70 61 71 75 65 20 73 74 72 75 63 74 75 72 65  opaque structure
2530: 20 6e 61 6d 65 64 20 22 73 71 6c 69 74 65 33 22   named "sqlite3"
2540: 2e 20 20 49 74 20 69 73 20 75 73 65 66 75 6c 20  .  It is useful 
2550: 74 6f 20 74 68 69 6e 6b 20 6f 66 20 61 6e 20 73  to think of an s
2560: 71 6c 69 74 65 33 0a 2a 2a 20 70 6f 69 6e 74 65  qlite3.** pointe
2570: 72 20 61 73 20 61 6e 20 6f 62 6a 65 63 74 2e 20  r as an object. 
2580: 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70   The [sqlite3_op
2590: 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  en()], [sqlite3_
25a0: 6f 70 65 6e 31 36 28 29 5d 2c 20 61 6e 64 0a 2a  open16()], and.*
25b0: 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  * [sqlite3_open_
25c0: 76 32 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73  v2()] interfaces
25d0: 20 61 72 65 20 69 74 73 20 63 6f 6e 73 74 72 75   are its constru
25e0: 63 74 6f 72 73 2c 20 61 6e 64 20 5b 73 71 6c 69  ctors, and [sqli
25f0: 74 65 33 5f 63 6c 6f 73 65 28 29 5d 0a 2a 2a 20  te3_close()].** 
2600: 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f  and [sqlite3_clo
2610: 73 65 5f 76 32 28 29 5d 20 61 72 65 20 69 74 73  se_v2()] are its
2620: 20 64 65 73 74 72 75 63 74 6f 72 73 2e 20 20 54   destructors.  T
2630: 68 65 72 65 20 61 72 65 20 6d 61 6e 79 20 6f 74  here are many ot
2640: 68 65 72 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  her.** interface
2650: 73 20 28 73 75 63 68 20 61 73 0a 2a 2a 20 5b 73  s (such as.** [s
2660: 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
2670: 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63  2()], [sqlite3_c
2680: 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29  reate_function()
2690: 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74  ], and.** [sqlit
26a0: 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28  e3_busy_timeout(
26b0: 29 5d 20 74 6f 20 6e 61 6d 65 20 62 75 74 20 74  )] to name but t
26c0: 68 72 65 65 29 20 74 68 61 74 20 61 72 65 20 6d  hree) that are m
26d0: 65 74 68 6f 64 73 20 6f 6e 20 61 6e 0a 2a 2a 20  ethods on an.** 
26e0: 73 71 6c 69 74 65 33 20 6f 62 6a 65 63 74 2e 0a  sqlite3 object..
26f0: 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63  */.typedef struc
2700: 74 20 73 71 6c 69 74 65 33 20 73 71 6c 69 74 65  t sqlite3 sqlite
2710: 33 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  3;../*.** CAPI3R
2720: 45 46 3a 20 36 34 2d 42 69 74 20 49 6e 74 65 67  EF: 64-Bit Integ
2730: 65 72 20 54 79 70 65 73 0a 2a 2a 20 4b 45 59 57  er Types.** KEYW
2740: 4f 52 44 53 3a 20 73 71 6c 69 74 65 5f 69 6e 74  ORDS: sqlite_int
2750: 36 34 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34  64 sqlite_uint64
2760: 0a 2a 2a 0a 2a 2a 20 42 65 63 61 75 73 65 20 74  .**.** Because t
2770: 68 65 72 65 20 69 73 20 6e 6f 20 63 72 6f 73 73  here is no cross
2780: 2d 70 6c 61 74 66 6f 72 6d 20 77 61 79 20 74 6f  -platform way to
2790: 20 73 70 65 63 69 66 79 20 36 34 2d 62 69 74 20   specify 64-bit 
27a0: 69 6e 74 65 67 65 72 20 74 79 70 65 73 0a 2a 2a  integer types.**
27b0: 20 53 51 4c 69 74 65 20 69 6e 63 6c 75 64 65 73   SQLite includes
27c0: 20 74 79 70 65 64 65 66 73 20 66 6f 72 20 36 34   typedefs for 64
27d0: 2d 62 69 74 20 73 69 67 6e 65 64 20 61 6e 64 20  -bit signed and 
27e0: 75 6e 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72  unsigned integer
27f0: 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  s..**.** The sql
2800: 69 74 65 33 5f 69 6e 74 36 34 20 61 6e 64 20 73  ite3_int64 and s
2810: 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 20 61 72  qlite3_uint64 ar
2820: 65 20 74 68 65 20 70 72 65 66 65 72 72 65 64 20  e the preferred 
2830: 74 79 70 65 20 64 65 66 69 6e 69 74 69 6f 6e 73  type definitions
2840: 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 5f  ..** The sqlite_
2850: 69 6e 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65  int64 and sqlite
2860: 5f 75 69 6e 74 36 34 20 74 79 70 65 73 20 61 72  _uint64 types ar
2870: 65 20 73 75 70 70 6f 72 74 65 64 20 66 6f 72 20  e supported for 
2880: 62 61 63 6b 77 61 72 64 73 0a 2a 2a 20 63 6f 6d  backwards.** com
2890: 70 61 74 69 62 69 6c 69 74 79 20 6f 6e 6c 79 2e  patibility only.
28a0: 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
28b0: 74 65 33 5f 69 6e 74 36 34 20 61 6e 64 20 73 71  te3_int64 and sq
28c0: 6c 69 74 65 5f 69 6e 74 36 34 20 74 79 70 65 73  lite_int64 types
28d0: 20 63 61 6e 20 73 74 6f 72 65 20 69 6e 74 65 67   can store integ
28e0: 65 72 20 76 61 6c 75 65 73 0a 2a 2a 20 62 65 74  er values.** bet
28f0: 77 65 65 6e 20 2d 39 32 32 33 33 37 32 30 33 36  ween -9223372036
2900: 38 35 34 37 37 35 38 30 38 20 61 6e 64 20 2b 39  854775808 and +9
2910: 32 32 33 33 37 32 30 33 36 38 35 34 37 37 35 38  2233720368547758
2920: 30 37 20 69 6e 63 6c 75 73 69 76 65 2e 20 20 5e  07 inclusive.  ^
2930: 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75  The.** sqlite3_u
2940: 69 6e 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65  int64 and sqlite
2950: 5f 75 69 6e 74 36 34 20 74 79 70 65 73 20 63 61  _uint64 types ca
2960: 6e 20 73 74 6f 72 65 20 69 6e 74 65 67 65 72 20  n store integer 
2970: 76 61 6c 75 65 73 20 0a 2a 2a 20 62 65 74 77 65  values .** betwe
2980: 65 6e 20 30 20 61 6e 64 20 2b 31 38 34 34 36 37  en 0 and +184467
2990: 34 34 30 37 33 37 30 39 35 35 31 36 31 35 20 69  44073709551615 i
29a0: 6e 63 6c 75 73 69 76 65 2e 0a 2a 2f 0a 23 69 66  nclusive..*/.#if
29b0: 64 65 66 20 53 51 4c 49 54 45 5f 49 4e 54 36 34  def SQLITE_INT64
29c0: 5f 54 59 50 45 0a 20 20 74 79 70 65 64 65 66 20  _TYPE.  typedef 
29d0: 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 50  SQLITE_INT64_TYP
29e0: 45 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a  E sqlite_int64;.
29f0: 23 20 69 66 64 65 66 20 53 51 4c 49 54 45 5f 55  # ifdef SQLITE_U
2a00: 49 4e 54 36 34 5f 54 59 50 45 0a 20 20 20 20 74  INT64_TYPE.    t
2a10: 79 70 65 64 65 66 20 53 51 4c 49 54 45 5f 55 49  ypedef SQLITE_UI
2a20: 4e 54 36 34 5f 54 59 50 45 20 73 71 6c 69 74 65  NT64_TYPE sqlite
2a30: 5f 75 69 6e 74 36 34 3b 0a 23 20 65 6c 73 65 20  _uint64;.# else 
2a40: 20 0a 20 20 20 20 74 79 70 65 64 65 66 20 75 6e   .    typedef un
2a50: 73 69 67 6e 65 64 20 53 51 4c 49 54 45 5f 49 4e  signed SQLITE_IN
2a60: 54 36 34 5f 54 59 50 45 20 73 71 6c 69 74 65 5f  T64_TYPE sqlite_
2a70: 75 69 6e 74 36 34 3b 0a 23 20 65 6e 64 69 66 0a  uint64;.# endif.
2a80: 23 65 6c 69 66 20 64 65 66 69 6e 65 64 28 5f 4d  #elif defined(_M
2a90: 53 43 5f 56 45 52 29 20 7c 7c 20 64 65 66 69 6e  SC_VER) || defin
2aa0: 65 64 28 5f 5f 42 4f 52 4c 41 4e 44 43 5f 5f 29  ed(__BORLANDC__)
2ab0: 0a 20 20 74 79 70 65 64 65 66 20 5f 5f 69 6e 74  .  typedef __int
2ac0: 36 34 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b  64 sqlite_int64;
2ad0: 0a 20 20 74 79 70 65 64 65 66 20 75 6e 73 69 67  .  typedef unsig
2ae0: 6e 65 64 20 5f 5f 69 6e 74 36 34 20 73 71 6c 69  ned __int64 sqli
2af0: 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6c 73 65  te_uint64;.#else
2b00: 0a 20 20 74 79 70 65 64 65 66 20 6c 6f 6e 67 20  .  typedef long 
2b10: 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69 74 65 5f  long int sqlite_
2b20: 69 6e 74 36 34 3b 0a 20 20 74 79 70 65 64 65 66  int64;.  typedef
2b30: 20 75 6e 73 69 67 6e 65 64 20 6c 6f 6e 67 20 6c   unsigned long l
2b40: 6f 6e 67 20 69 6e 74 20 73 71 6c 69 74 65 5f 75  ong int sqlite_u
2b50: 69 6e 74 36 34 3b 0a 23 65 6e 64 69 66 0a 74 79  int64;.#endif.ty
2b60: 70 65 64 65 66 20 73 71 6c 69 74 65 5f 69 6e 74  pedef sqlite_int
2b70: 36 34 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  64 sqlite3_int64
2b80: 3b 0a 74 79 70 65 64 65 66 20 73 71 6c 69 74 65  ;.typedef sqlite
2b90: 5f 75 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f  _uint64 sqlite3_
2ba0: 75 69 6e 74 36 34 3b 0a 0a 2f 2a 0a 2a 2a 20 49  uint64;../*.** I
2bb0: 66 20 63 6f 6d 70 69 6c 69 6e 67 20 66 6f 72 20  f compiling for 
2bc0: 61 20 70 72 6f 63 65 73 73 6f 72 20 74 68 61 74  a processor that
2bd0: 20 6c 61 63 6b 73 20 66 6c 6f 61 74 69 6e 67 20   lacks floating 
2be0: 70 6f 69 6e 74 20 73 75 70 70 6f 72 74 2c 0a 2a  point support,.*
2bf0: 2a 20 73 75 62 73 74 69 74 75 74 65 20 69 6e 74  * substitute int
2c00: 65 67 65 72 20 66 6f 72 20 66 6c 6f 61 74 69 6e  eger for floatin
2c10: 67 2d 70 6f 69 6e 74 2e 0a 2a 2f 0a 23 69 66 64  g-point..*/.#ifd
2c20: 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 46  ef SQLITE_OMIT_F
2c30: 4c 4f 41 54 49 4e 47 5f 50 4f 49 4e 54 0a 23 20  LOATING_POINT.# 
2c40: 64 65 66 69 6e 65 20 64 6f 75 62 6c 65 20 73 71  define double sq
2c50: 6c 69 74 65 33 5f 69 6e 74 36 34 0a 23 65 6e 64  lite3_int64.#end
2c60: 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  if../*.** CAPI3R
2c70: 45 46 3a 20 43 6c 6f 73 69 6e 67 20 41 20 44 61  EF: Closing A Da
2c80: 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f  tabase Connectio
2c90: 6e 0a 2a 2a 20 44 45 53 54 52 55 43 54 4f 52 3a  n.** DESTRUCTOR:
2ca0: 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e   sqlite3.**.** ^
2cb0: 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73  The sqlite3_clos
2cc0: 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  e() and sqlite3_
2cd0: 63 6c 6f 73 65 5f 76 32 28 29 20 72 6f 75 74 69  close_v2() routi
2ce0: 6e 65 73 20 61 72 65 20 64 65 73 74 72 75 63 74  nes are destruct
2cf0: 6f 72 73 0a 2a 2a 20 66 6f 72 20 74 68 65 20 5b  ors.** for the [
2d00: 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 2e  sqlite3] object.
2d10: 0a 2a 2a 20 5e 43 61 6c 6c 73 20 74 6f 20 73 71  .** ^Calls to sq
2d20: 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 20 61 6e  lite3_close() an
2d30: 64 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f  d sqlite3_close_
2d40: 76 32 28 29 20 72 65 74 75 72 6e 20 5b 53 51 4c  v2() return [SQL
2d50: 49 54 45 5f 4f 4b 5d 20 69 66 0a 2a 2a 20 74 68  ITE_OK] if.** th
2d60: 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65  e [sqlite3] obje
2d70: 63 74 20 69 73 20 73 75 63 63 65 73 73 66 75 6c  ct is successful
2d80: 6c 79 20 64 65 73 74 72 6f 79 65 64 20 61 6e 64  ly destroyed and
2d90: 20 61 6c 6c 20 61 73 73 6f 63 69 61 74 65 64 0a   all associated.
2da0: 2a 2a 20 72 65 73 6f 75 72 63 65 73 20 61 72 65  ** resources are
2db0: 20 64 65 61 6c 6c 6f 63 61 74 65 64 2e 0a 2a 2a   deallocated..**
2dc0: 0a 2a 2a 20 5e 49 66 20 74 68 65 20 64 61 74 61  .** ^If the data
2dd0: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
2de0: 69 73 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  is associated wi
2df0: 74 68 20 75 6e 66 69 6e 61 6c 69 7a 65 64 20 70  th unfinalized p
2e00: 72 65 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 65  repared.** state
2e10: 6d 65 6e 74 73 20 6f 72 20 75 6e 66 69 6e 69 73  ments or unfinis
2e20: 68 65 64 20 73 71 6c 69 74 65 33 5f 62 61 63 6b  hed sqlite3_back
2e30: 75 70 20 6f 62 6a 65 63 74 73 20 74 68 65 6e 20  up objects then 
2e40: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 0a  sqlite3_close().
2e50: 2a 2a 20 77 69 6c 6c 20 6c 65 61 76 65 20 74 68  ** will leave th
2e60: 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
2e70: 63 74 69 6f 6e 20 6f 70 65 6e 20 61 6e 64 20 72  ction open and r
2e80: 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 42 55  eturn [SQLITE_BU
2e90: 53 59 5d 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69  SY]..** ^If sqli
2ea0: 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 69  te3_close_v2() i
2eb0: 73 20 63 61 6c 6c 65 64 20 77 69 74 68 20 75 6e  s called with un
2ec0: 66 69 6e 61 6c 69 7a 65 64 20 70 72 65 70 61 72  finalized prepar
2ed0: 65 64 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a  ed statements.**
2ee0: 20 61 6e 64 2f 6f 72 20 75 6e 66 69 6e 69 73 68   and/or unfinish
2ef0: 65 64 20 73 71 6c 69 74 65 33 5f 62 61 63 6b 75  ed sqlite3_backu
2f00: 70 73 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74  ps, then the dat
2f10: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
2f20: 20 62 65 63 6f 6d 65 73 0a 2a 2a 20 61 6e 20 75   becomes.** an u
2f30: 6e 75 73 61 62 6c 65 20 22 7a 6f 6d 62 69 65 22  nusable "zombie"
2f40: 20 77 68 69 63 68 20 77 69 6c 6c 20 61 75 74 6f   which will auto
2f50: 6d 61 74 69 63 61 6c 6c 79 20 62 65 20 64 65 61  matically be dea
2f60: 6c 6c 6f 63 61 74 65 64 20 77 68 65 6e 20 74 68  llocated when th
2f70: 65 0a 2a 2a 20 6c 61 73 74 20 70 72 65 70 61 72  e.** last prepar
2f80: 65 64 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  ed statement is 
2f90: 66 69 6e 61 6c 69 7a 65 64 20 6f 72 20 74 68 65  finalized or the
2fa0: 20 6c 61 73 74 20 73 71 6c 69 74 65 33 5f 62 61   last sqlite3_ba
2fb0: 63 6b 75 70 20 69 73 0a 2a 2a 20 66 69 6e 69 73  ckup is.** finis
2fc0: 68 65 64 2e 20 20 54 68 65 20 73 71 6c 69 74 65  hed.  The sqlite
2fd0: 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 69 6e 74  3_close_v2() int
2fe0: 65 72 66 61 63 65 20 69 73 20 69 6e 74 65 6e 64  erface is intend
2ff0: 65 64 20 66 6f 72 20 75 73 65 20 77 69 74 68 0a  ed for use with.
3000: 2a 2a 20 68 6f 73 74 20 6c 61 6e 67 75 61 67 65  ** host language
3010: 73 20 74 68 61 74 20 61 72 65 20 67 61 72 62 61  s that are garba
3020: 67 65 20 63 6f 6c 6c 65 63 74 65 64 2c 20 61 6e  ge collected, an
3030: 64 20 77 68 65 72 65 20 74 68 65 20 6f 72 64 65  d where the orde
3040: 72 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 64 65  r in which.** de
3050: 73 74 72 75 63 74 6f 72 73 20 61 72 65 20 63 61  structors are ca
3060: 6c 6c 65 64 20 69 73 20 61 72 62 69 74 72 61 72  lled is arbitrar
3070: 79 2e 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63 61  y..**.** Applica
3080: 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 5b 73 71  tions should [sq
3090: 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 20 7c  lite3_finalize |
30a0: 20 66 69 6e 61 6c 69 7a 65 5d 20 61 6c 6c 20 5b   finalize] all [
30b0: 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
30c0: 6e 74 73 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65  nts],.** [sqlite
30d0: 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 20 7c 20 63  3_blob_close | c
30e0: 6c 6f 73 65 5d 20 61 6c 6c 20 5b 42 4c 4f 42 20  lose] all [BLOB 
30f0: 68 61 6e 64 6c 65 73 5d 2c 20 61 6e 64 20 0a 2a  handles], and .*
3100: 2a 20 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b 75  * [sqlite3_backu
3110: 70 5f 66 69 6e 69 73 68 20 7c 20 66 69 6e 69 73  p_finish | finis
3120: 68 5d 20 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f  h] all [sqlite3_
3130: 62 61 63 6b 75 70 5d 20 6f 62 6a 65 63 74 73 20  backup] objects 
3140: 61 73 73 6f 63 69 61 74 65 64 0a 2a 2a 20 77 69  associated.** wi
3150: 74 68 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d  th the [sqlite3]
3160: 20 6f 62 6a 65 63 74 20 70 72 69 6f 72 20 74 6f   object prior to
3170: 20 61 74 74 65 6d 70 74 69 6e 67 20 74 6f 20 63   attempting to c
3180: 6c 6f 73 65 20 74 68 65 20 6f 62 6a 65 63 74 2e  lose the object.
3190: 20 20 5e 49 66 0a 2a 2a 20 73 71 6c 69 74 65 33    ^If.** sqlite3
31a0: 5f 63 6c 6f 73 65 5f 76 32 28 29 20 69 73 20 63  _close_v2() is c
31b0: 61 6c 6c 65 64 20 6f 6e 20 61 20 5b 64 61 74 61  alled on a [data
31c0: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
31d0: 20 74 68 61 74 20 73 74 69 6c 6c 20 68 61 73 0a   that still has.
31e0: 2a 2a 20 6f 75 74 73 74 61 6e 64 69 6e 67 20 5b  ** outstanding [
31f0: 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
3200: 6e 74 73 5d 2c 20 5b 42 4c 4f 42 20 68 61 6e 64  nts], [BLOB hand
3210: 6c 65 73 5d 2c 20 61 6e 64 2f 6f 72 0a 2a 2a 20  les], and/or.** 
3220: 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5d  [sqlite3_backup]
3230: 20 6f 62 6a 65 63 74 73 20 74 68 65 6e 20 69 74   objects then it
3240: 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
3250: 5f 4f 4b 5d 20 61 6e 64 20 74 68 65 20 64 65 61  _OK] and the dea
3260: 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20  llocation.** of 
3270: 72 65 73 6f 75 72 63 65 73 20 69 73 20 64 65 66  resources is def
3280: 65 72 72 65 64 20 75 6e 74 69 6c 20 61 6c 6c 20  erred until all 
3290: 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
32a0: 65 6e 74 73 5d 2c 20 5b 42 4c 4f 42 20 68 61 6e  ents], [BLOB han
32b0: 64 6c 65 73 5d 2c 0a 2a 2a 20 61 6e 64 20 5b 73  dles],.** and [s
32c0: 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5d 20 6f  qlite3_backup] o
32d0: 62 6a 65 63 74 73 20 61 72 65 20 61 6c 73 6f 20  bjects are also 
32e0: 64 65 73 74 72 6f 79 65 64 2e 0a 2a 2a 0a 2a 2a  destroyed..**.**
32f0: 20 5e 49 66 20 61 6e 20 5b 73 71 6c 69 74 65 33   ^If an [sqlite3
3300: 5d 20 6f 62 6a 65 63 74 20 69 73 20 64 65 73 74  ] object is dest
3310: 72 6f 79 65 64 20 77 68 69 6c 65 20 61 20 74 72  royed while a tr
3320: 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 6f 70 65  ansaction is ope
3330: 6e 2c 0a 2a 2a 20 74 68 65 20 74 72 61 6e 73 61  n,.** the transa
3340: 63 74 69 6f 6e 20 69 73 20 61 75 74 6f 6d 61 74  ction is automat
3350: 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64 20 62 61  ically rolled ba
3360: 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 43 20  ck..**.** The C 
3370: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71  parameter to [sq
3380: 6c 69 74 65 33 5f 63 6c 6f 73 65 28 43 29 5d 20  lite3_close(C)] 
3390: 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f  and [sqlite3_clo
33a0: 73 65 5f 76 32 28 43 29 5d 0a 2a 2a 20 6d 75 73  se_v2(C)].** mus
33b0: 74 20 62 65 20 65 69 74 68 65 72 20 61 20 4e 55  t be either a NU
33c0: 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 6f 72  LL.** pointer or
33d0: 20 61 6e 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62   an [sqlite3] ob
33e0: 6a 65 63 74 20 70 6f 69 6e 74 65 72 20 6f 62 74  ject pointer obt
33f0: 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73  ained.** from [s
3400: 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20  qlite3_open()], 
3410: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28  [sqlite3_open16(
3420: 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74  )], or.** [sqlit
3430: 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c 20 61  e3_open_v2()], a
3440: 6e 64 20 6e 6f 74 20 70 72 65 76 69 6f 75 73 6c  nd not previousl
3450: 79 20 63 6c 6f 73 65 64 2e 0a 2a 2a 20 5e 43 61  y closed..** ^Ca
3460: 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 63 6c  lling sqlite3_cl
3470: 6f 73 65 28 29 20 6f 72 20 73 71 6c 69 74 65 33  ose() or sqlite3
3480: 5f 63 6c 6f 73 65 5f 76 32 28 29 20 77 69 74 68  _close_v2() with
3490: 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a   a NULL pointer.
34a0: 2a 2a 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61  ** argument is a
34b0: 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e   harmless no-op.
34c0: 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .*/.SQLITE_API i
34d0: 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  nt sqlite3_close
34e0: 28 73 71 6c 69 74 65 33 2a 29 3b 0a 53 51 4c 49  (sqlite3*);.SQLI
34f0: 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
3500: 65 33 5f 63 6c 6f 73 65 5f 76 32 28 73 71 6c 69  e3_close_v2(sqli
3510: 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68  te3*);../*.** Th
3520: 65 20 74 79 70 65 20 66 6f 72 20 61 20 63 61 6c  e type for a cal
3530: 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 2e 0a  lback function..
3540: 2a 2a 20 54 68 69 73 20 69 73 20 6c 65 67 61 63  ** This is legac
3550: 79 20 61 6e 64 20 64 65 70 72 65 63 61 74 65 64  y and deprecated
3560: 2e 20 20 49 74 20 69 73 20 69 6e 63 6c 75 64 65  .  It is include
3570: 64 20 66 6f 72 20 68 69 73 74 6f 72 69 63 61 6c  d for historical
3580: 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  .** compatibilit
3590: 79 20 61 6e 64 20 69 73 20 6e 6f 74 20 64 6f 63  y and is not doc
35a0: 75 6d 65 6e 74 65 64 2e 0a 2a 2f 0a 74 79 70 65  umented..*/.type
35b0: 64 65 66 20 69 6e 74 20 28 2a 73 71 6c 69 74 65  def int (*sqlite
35c0: 33 5f 63 61 6c 6c 62 61 63 6b 29 28 76 6f 69 64  3_callback)(void
35d0: 2a 2c 69 6e 74 2c 63 68 61 72 2a 2a 2c 20 63 68  *,int,char**, ch
35e0: 61 72 2a 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  ar**);../*.** CA
35f0: 50 49 33 52 45 46 3a 20 4f 6e 65 2d 53 74 65 70  PI3REF: One-Step
3600: 20 51 75 65 72 79 20 45 78 65 63 75 74 69 6f 6e   Query Execution
3610: 20 49 6e 74 65 72 66 61 63 65 0a 2a 2a 20 4d 45   Interface.** ME
3620: 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a  THOD: sqlite3.**
3630: 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
3640: 65 78 65 63 28 29 20 69 6e 74 65 72 66 61 63 65  exec() interface
3650: 20 69 73 20 61 20 63 6f 6e 76 65 6e 69 65 6e 63   is a convenienc
3660: 65 20 77 72 61 70 70 65 72 20 61 72 6f 75 6e 64  e wrapper around
3670: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  .** [sqlite3_pre
3680: 70 61 72 65 5f 76 32 28 29 5d 2c 20 5b 73 71 6c  pare_v2()], [sql
3690: 69 74 65 33 5f 73 74 65 70 28 29 5d 2c 20 61 6e  ite3_step()], an
36a0: 64 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  d [sqlite3_final
36b0: 69 7a 65 28 29 5d 2c 0a 2a 2a 20 74 68 61 74 20  ize()],.** that 
36c0: 61 6c 6c 6f 77 73 20 61 6e 20 61 70 70 6c 69 63  allows an applic
36d0: 61 74 69 6f 6e 20 74 6f 20 72 75 6e 20 6d 75 6c  ation to run mul
36e0: 74 69 70 6c 65 20 73 74 61 74 65 6d 65 6e 74 73  tiple statements
36f0: 20 6f 66 20 53 51 4c 0a 2a 2a 20 77 69 74 68 6f   of SQL.** witho
3700: 75 74 20 68 61 76 69 6e 67 20 74 6f 20 75 73 65  ut having to use
3710: 20 61 20 6c 6f 74 20 6f 66 20 43 20 63 6f 64 65   a lot of C code
3720: 2e 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  . .**.** ^The sq
3730: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 6e 74  lite3_exec() int
3740: 65 72 66 61 63 65 20 72 75 6e 73 20 7a 65 72 6f  erface runs zero
3750: 20 6f 72 20 6d 6f 72 65 20 55 54 46 2d 38 20 65   or more UTF-8 e
3760: 6e 63 6f 64 65 64 2c 0a 2a 2a 20 73 65 6d 69 63  ncoded,.** semic
3770: 6f 6c 6f 6e 2d 73 65 70 61 72 61 74 65 20 53 51  olon-separate SQ
3780: 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 70 61 73  L statements pas
3790: 73 65 64 20 69 6e 74 6f 20 69 74 73 20 32 6e 64  sed into its 2nd
37a0: 20 61 72 67 75 6d 65 6e 74 2c 0a 2a 2a 20 69 6e   argument,.** in
37b0: 20 74 68 65 20 63 6f 6e 74 65 78 74 20 6f 66 20   the context of 
37c0: 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
37d0: 6e 6e 65 63 74 69 6f 6e 5d 20 70 61 73 73 65 64  nnection] passed
37e0: 20 69 6e 20 61 73 20 69 74 73 20 31 73 74 0a 2a   in as its 1st.*
37f0: 2a 20 61 72 67 75 6d 65 6e 74 2e 20 20 5e 49 66  * argument.  ^If
3800: 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75   the callback fu
3810: 6e 63 74 69 6f 6e 20 6f 66 20 74 68 65 20 33 72  nction of the 3r
3820: 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a  d argument to.**
3830: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20   sqlite3_exec() 
3840: 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68 65  is not NULL, the
3850: 6e 20 69 74 20 69 73 20 69 6e 76 6f 6b 65 64 20  n it is invoked 
3860: 66 6f 72 20 65 61 63 68 20 72 65 73 75 6c 74 20  for each result 
3870: 72 6f 77 0a 2a 2a 20 63 6f 6d 69 6e 67 20 6f 75  row.** coming ou
3880: 74 20 6f 66 20 74 68 65 20 65 76 61 6c 75 61 74  t of the evaluat
3890: 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ed SQL statement
38a0: 73 2e 20 20 5e 54 68 65 20 34 74 68 20 61 72 67  s.  ^The 4th arg
38b0: 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 73 71 6c 69  ument to.** sqli
38c0: 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 72 65  te3_exec() is re
38d0: 6c 61 79 65 64 20 74 68 72 6f 75 67 68 20 74 6f  layed through to
38e0: 20 74 68 65 20 31 73 74 20 61 72 67 75 6d 65 6e   the 1st argumen
38f0: 74 20 6f 66 20 65 61 63 68 0a 2a 2a 20 63 61 6c  t of each.** cal
3900: 6c 62 61 63 6b 20 69 6e 76 6f 63 61 74 69 6f 6e  lback invocation
3910: 2e 20 20 5e 49 66 20 74 68 65 20 63 61 6c 6c 62  .  ^If the callb
3920: 61 63 6b 20 70 6f 69 6e 74 65 72 20 74 6f 20 73  ack pointer to s
3930: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a  qlite3_exec().**
3940: 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 6e   is NULL, then n
3950: 6f 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 65 76  o callback is ev
3960: 65 72 20 69 6e 76 6f 6b 65 64 20 61 6e 64 20 72  er invoked and r
3970: 65 73 75 6c 74 20 72 6f 77 73 20 61 72 65 0a 2a  esult rows are.*
3980: 2a 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a  * ignored..**.**
3990: 20 5e 49 66 20 61 6e 20 65 72 72 6f 72 20 6f 63   ^If an error oc
39a0: 63 75 72 73 20 77 68 69 6c 65 20 65 76 61 6c 75  curs while evalu
39b0: 61 74 69 6e 67 20 74 68 65 20 53 51 4c 20 73 74  ating the SQL st
39c0: 61 74 65 6d 65 6e 74 73 20 70 61 73 73 65 64 20  atements passed 
39d0: 69 6e 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  into.** sqlite3_
39e0: 65 78 65 63 28 29 2c 20 74 68 65 6e 20 65 78 65  exec(), then exe
39f0: 63 75 74 69 6f 6e 20 6f 66 20 74 68 65 20 63 75  cution of the cu
3a00: 72 72 65 6e 74 20 73 74 61 74 65 6d 65 6e 74 20  rrent statement 
3a10: 73 74 6f 70 73 20 61 6e 64 0a 2a 2a 20 73 75 62  stops and.** sub
3a20: 73 65 71 75 65 6e 74 20 73 74 61 74 65 6d 65 6e  sequent statemen
3a30: 74 73 20 61 72 65 20 73 6b 69 70 70 65 64 2e 20  ts are skipped. 
3a40: 20 5e 49 66 20 74 68 65 20 35 74 68 20 70 61 72   ^If the 5th par
3a50: 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
3a60: 33 5f 65 78 65 63 28 29 0a 2a 2a 20 69 73 20 6e  3_exec().** is n
3a70: 6f 74 20 4e 55 4c 4c 20 74 68 65 6e 20 61 6e 79  ot NULL then any
3a80: 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 69   error message i
3a90: 73 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 6d  s written into m
3aa0: 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 0a 2a  emory obtained.*
3ab0: 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  * from [sqlite3_
3ac0: 6d 61 6c 6c 6f 63 28 29 5d 20 61 6e 64 20 70 61  malloc()] and pa
3ad0: 73 73 65 64 20 62 61 63 6b 20 74 68 72 6f 75 67  ssed back throug
3ae0: 68 20 74 68 65 20 35 74 68 20 70 61 72 61 6d 65  h the 5th parame
3af0: 74 65 72 2e 0a 2a 2a 20 54 6f 20 61 76 6f 69 64  ter..** To avoid
3b00: 20 6d 65 6d 6f 72 79 20 6c 65 61 6b 73 2c 20 74   memory leaks, t
3b10: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73  he application s
3b20: 68 6f 75 6c 64 20 69 6e 76 6f 6b 65 20 5b 73 71  hould invoke [sq
3b30: 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 0a 2a 2a  lite3_free()].**
3b40: 20 6f 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67   on error messag
3b50: 65 20 73 74 72 69 6e 67 73 20 72 65 74 75 72 6e  e strings return
3b60: 65 64 20 74 68 72 6f 75 67 68 20 74 68 65 20 35  ed through the 5
3b70: 74 68 20 70 61 72 61 6d 65 74 65 72 20 6f 66 0a  th parameter of.
3b80: 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  ** sqlite3_exec(
3b90: 29 20 61 66 74 65 72 20 74 68 65 20 65 72 72 6f  ) after the erro
3ba0: 72 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67  r message string
3bb0: 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 6e 65   is no longer ne
3bc0: 65 64 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  eded..** ^If the
3bd0: 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 74   5th parameter t
3be0: 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  o sqlite3_exec()
3bf0: 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 61 6e 64   is not NULL and
3c00: 20 6e 6f 20 65 72 72 6f 72 73 0a 2a 2a 20 6f 63   no errors.** oc
3c10: 63 75 72 2c 20 74 68 65 6e 20 73 71 6c 69 74 65  cur, then sqlite
3c20: 33 5f 65 78 65 63 28 29 20 73 65 74 73 20 74 68  3_exec() sets th
3c30: 65 20 70 6f 69 6e 74 65 72 20 69 6e 20 69 74 73  e pointer in its
3c40: 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 74   5th parameter t
3c50: 6f 0a 2a 2a 20 4e 55 4c 4c 20 62 65 66 6f 72 65  o.** NULL before
3c60: 20 72 65 74 75 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a   returning..**.*
3c70: 2a 20 5e 49 66 20 61 6e 20 73 71 6c 69 74 65 33  * ^If an sqlite3
3c80: 5f 65 78 65 63 28 29 20 63 61 6c 6c 62 61 63 6b  _exec() callback
3c90: 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72   returns non-zer
3ca0: 6f 2c 20 74 68 65 20 73 71 6c 69 74 65 33 5f 65  o, the sqlite3_e
3cb0: 78 65 63 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65  xec().** routine
3cc0: 20 72 65 74 75 72 6e 73 20 53 51 4c 49 54 45 5f   returns SQLITE_
3cd0: 41 42 4f 52 54 20 77 69 74 68 6f 75 74 20 69 6e  ABORT without in
3ce0: 76 6f 6b 69 6e 67 20 74 68 65 20 63 61 6c 6c 62  voking the callb
3cf0: 61 63 6b 20 61 67 61 69 6e 20 61 6e 64 0a 2a 2a  ack again and.**
3d00: 20 77 69 74 68 6f 75 74 20 72 75 6e 6e 69 6e 67   without running
3d10: 20 61 6e 79 20 73 75 62 73 65 71 75 65 6e 74 20   any subsequent 
3d20: 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a  SQL statements..
3d30: 2a 2a 0a 2a 2a 20 5e 54 68 65 20 32 6e 64 20 61  **.** ^The 2nd a
3d40: 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 73  rgument to the s
3d50: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 63 61  qlite3_exec() ca
3d60: 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
3d70: 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72  is the.** number
3d80: 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74   of columns in t
3d90: 68 65 20 72 65 73 75 6c 74 2e 20 20 5e 54 68 65  he result.  ^The
3da0: 20 33 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f   3rd argument to
3db0: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65   the sqlite3_exe
3dc0: 63 28 29 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20  c().** callback 
3dd0: 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70  is an array of p
3de0: 6f 69 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e  ointers to strin
3df0: 67 73 20 6f 62 74 61 69 6e 65 64 20 61 73 20 69  gs obtained as i
3e00: 66 20 66 72 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74  f from.** [sqlit
3e10: 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29  e3_column_text()
3e20: 5d 2c 20 6f 6e 65 20 66 6f 72 20 65 61 63 68 20  ], one for each 
3e30: 63 6f 6c 75 6d 6e 2e 20 20 5e 49 66 20 61 6e 20  column.  ^If an 
3e40: 65 6c 65 6d 65 6e 74 20 6f 66 20 61 0a 2a 2a 20  element of a.** 
3e50: 72 65 73 75 6c 74 20 72 6f 77 20 69 73 20 4e 55  result row is NU
3e60: 4c 4c 20 74 68 65 6e 20 74 68 65 20 63 6f 72 72  LL then the corr
3e70: 65 73 70 6f 6e 64 69 6e 67 20 73 74 72 69 6e 67  esponding string
3e80: 20 70 6f 69 6e 74 65 72 20 66 6f 72 20 74 68 65   pointer for the
3e90: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 63  .** sqlite3_exec
3ea0: 28 29 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61  () callback is a
3eb0: 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20   NULL pointer.  
3ec0: 5e 54 68 65 20 34 74 68 20 61 72 67 75 6d 65 6e  ^The 4th argumen
3ed0: 74 20 74 6f 20 74 68 65 0a 2a 2a 20 73 71 6c 69  t to the.** sqli
3ee0: 74 65 33 5f 65 78 65 63 28 29 20 63 61 6c 6c 62  te3_exec() callb
3ef0: 61 63 6b 20 69 73 20 61 6e 20 61 72 72 61 79 20  ack is an array 
3f00: 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 73  of pointers to s
3f10: 74 72 69 6e 67 73 20 77 68 65 72 65 20 65 61 63  trings where eac
3f20: 68 0a 2a 2a 20 65 6e 74 72 79 20 72 65 70 72 65  h.** entry repre
3f30: 73 65 6e 74 73 20 74 68 65 20 6e 61 6d 65 20 6f  sents the name o
3f40: 66 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20  f corresponding 
3f50: 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 61 73  result column as
3f60: 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f   obtained.** fro
3f70: 6d 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  m [sqlite3_colum
3f80: 6e 5f 6e 61 6d 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a  n_name()]..**.**
3f90: 20 5e 49 66 20 74 68 65 20 32 6e 64 20 70 61 72   ^If the 2nd par
3fa0: 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
3fb0: 33 5f 65 78 65 63 28 29 20 69 73 20 61 20 4e 55  3_exec() is a NU
3fc0: 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 61 20 70 6f  LL pointer, a po
3fd0: 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 61 6e 20 65  inter.** to an e
3fe0: 6d 70 74 79 20 73 74 72 69 6e 67 2c 20 6f 72 20  mpty string, or 
3ff0: 61 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20 63  a pointer that c
4000: 6f 6e 74 61 69 6e 73 20 6f 6e 6c 79 20 77 68 69  ontains only whi
4010: 74 65 73 70 61 63 65 20 61 6e 64 2f 6f 72 20 0a  tespace and/or .
4020: 2a 2a 20 53 51 4c 20 63 6f 6d 6d 65 6e 74 73 2c  ** SQL comments,
4030: 20 74 68 65 6e 20 6e 6f 20 53 51 4c 20 73 74 61   then no SQL sta
4040: 74 65 6d 65 6e 74 73 20 61 72 65 20 65 76 61 6c  tements are eval
4050: 75 61 74 65 64 20 61 6e 64 20 74 68 65 20 64 61  uated and the da
4060: 74 61 62 61 73 65 0a 2a 2a 20 69 73 20 6e 6f 74  tabase.** is not
4070: 20 63 68 61 6e 67 65 64 2e 0a 2a 2a 0a 2a 2a 20   changed..**.** 
4080: 52 65 73 74 72 69 63 74 69 6f 6e 73 3a 0a 2a 2a  Restrictions:.**
4090: 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
40a0: 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   The application
40b0: 20 6d 75 73 74 20 65 6e 73 75 72 65 20 74 68 61   must ensure tha
40c0: 74 20 74 68 65 20 31 73 74 20 70 61 72 61 6d 65  t the 1st parame
40d0: 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65  ter to sqlite3_e
40e0: 78 65 63 28 29 0a 2a 2a 20 20 20 20 20 20 69 73  xec().**      is
40f0: 20 61 20 76 61 6c 69 64 20 61 6e 64 20 6f 70 65   a valid and ope
4100: 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  n [database conn
4110: 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 20 3c 6c 69 3e  ection]..** <li>
4120: 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   The application
4130: 20 6d 75 73 74 20 6e 6f 74 20 63 6c 6f 73 65 20   must not close 
4140: 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
4150: 6e 6e 65 63 74 69 6f 6e 5d 20 73 70 65 63 69 66  nnection] specif
4160: 69 65 64 20 62 79 0a 2a 2a 20 20 20 20 20 20 74  ied by.**      t
4170: 68 65 20 31 73 74 20 70 61 72 61 6d 65 74 65 72  he 1st parameter
4180: 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63   to sqlite3_exec
4190: 28 29 20 77 68 69 6c 65 20 73 71 6c 69 74 65 33  () while sqlite3
41a0: 5f 65 78 65 63 28 29 20 69 73 20 72 75 6e 6e 69  _exec() is runni
41b0: 6e 67 2e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20  ng..** <li> The 
41c0: 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74  application must
41d0: 20 6e 6f 74 20 6d 6f 64 69 66 79 20 74 68 65 20   not modify the 
41e0: 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 65  SQL statement te
41f0: 78 74 20 70 61 73 73 65 64 20 69 6e 74 6f 0a 2a  xt passed into.*
4200: 2a 20 20 20 20 20 20 74 68 65 20 32 6e 64 20 70  *      the 2nd p
4210: 61 72 61 6d 65 74 65 72 20 6f 66 20 73 71 6c 69  arameter of sqli
4220: 74 65 33 5f 65 78 65 63 28 29 20 77 68 69 6c 65  te3_exec() while
4230: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20   sqlite3_exec() 
4240: 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 3c  is running..** <
4250: 2f 75 6c 3e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  /ul>.*/.SQLITE_A
4260: 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 65  PI int sqlite3_e
4270: 78 65 63 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c  xec(.  sqlite3*,
4280: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4290: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
42a0: 20 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64 61 74    /* An open dat
42b0: 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  abase */.  const
42c0: 20 63 68 61 72 20 2a 73 71 6c 2c 20 20 20 20 20   char *sql,     
42d0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
42e0: 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 74 6f 20        /* SQL to 
42f0: 62 65 20 65 76 61 6c 75 61 74 65 64 20 2a 2f 0a  be evaluated */.
4300: 20 20 69 6e 74 20 28 2a 63 61 6c 6c 62 61 63 6b    int (*callback
4310: 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68 61 72  )(void*,int,char
4320: 2a 2a 2c 63 68 61 72 2a 2a 29 2c 20 20 2f 2a 20  **,char**),  /* 
4330: 43 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  Callback functio
4340: 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 2c 20 20  n */.  void *,  
4350: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4360: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4370: 20 20 2f 2a 20 31 73 74 20 61 72 67 75 6d 65 6e    /* 1st argumen
4380: 74 20 74 6f 20 63 61 6c 6c 62 61 63 6b 20 2a 2f  t to callback */
4390: 0a 20 20 63 68 61 72 20 2a 2a 65 72 72 6d 73 67  .  char **errmsg
43a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
43b0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
43c0: 20 45 72 72 6f 72 20 6d 73 67 20 77 72 69 74 74   Error msg writt
43d0: 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a 0a 2f  en here */.);../
43e0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
43f0: 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a 20 4b  esult Codes.** K
4400: 45 59 57 4f 52 44 53 3a 20 7b 72 65 73 75 6c 74  EYWORDS: {result
4410: 20 63 6f 64 65 20 64 65 66 69 6e 69 74 69 6f 6e   code definition
4420: 73 7d 0a 2a 2a 0a 2a 2a 20 4d 61 6e 79 20 53 51  s}.**.** Many SQ
4430: 4c 69 74 65 20 66 75 6e 63 74 69 6f 6e 73 20 72  Lite functions r
4440: 65 74 75 72 6e 20 61 6e 20 69 6e 74 65 67 65 72  eturn an integer
4450: 20 72 65 73 75 6c 74 20 63 6f 64 65 20 66 72 6f   result code fro
4460: 6d 20 74 68 65 20 73 65 74 20 73 68 6f 77 6e 0a  m the set shown.
4470: 2a 2a 20 68 65 72 65 20 69 6e 20 6f 72 64 65 72  ** here in order
4480: 20 74 6f 20 69 6e 64 69 63 61 74 65 20 73 75 63   to indicate suc
4490: 63 65 73 73 20 6f 72 20 66 61 69 6c 75 72 65 2e  cess or failure.
44a0: 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 65 72 72 6f 72  .**.** New error
44b0: 20 63 6f 64 65 73 20 6d 61 79 20 62 65 20 61 64   codes may be ad
44c0: 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 76 65  ded in future ve
44d0: 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65  rsions of SQLite
44e0: 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
44f0: 3a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75  : [extended resu
4500: 6c 74 20 63 6f 64 65 20 64 65 66 69 6e 69 74 69  lt code definiti
4510: 6f 6e 73 5d 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  ons].*/.#define 
4520: 53 51 4c 49 54 45 5f 4f 4b 20 20 20 20 20 20 20  SQLITE_OK       
4530: 20 20 20 20 30 20 20 20 2f 2a 20 53 75 63 63 65      0   /* Succe
4540: 73 73 66 75 6c 20 72 65 73 75 6c 74 20 2a 2f 0a  ssful result */.
4550: 2f 2a 20 62 65 67 69 6e 6e 69 6e 67 2d 6f 66 2d  /* beginning-of-
4560: 65 72 72 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a 23  error-codes */.#
4570: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 52  define SQLITE_ER
4580: 52 4f 52 20 20 20 20 20 20 20 20 31 20 20 20 2f  ROR        1   /
4590: 2a 20 53 51 4c 20 65 72 72 6f 72 20 6f 72 20 6d  * SQL error or m
45a0: 69 73 73 69 6e 67 20 64 61 74 61 62 61 73 65 20  issing database 
45b0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
45c0: 45 5f 49 4e 54 45 52 4e 41 4c 20 20 20 20 20 32  E_INTERNAL     2
45d0: 20 20 20 2f 2a 20 49 6e 74 65 72 6e 61 6c 20 6c     /* Internal l
45e0: 6f 67 69 63 20 65 72 72 6f 72 20 69 6e 20 53 51  ogic error in SQ
45f0: 4c 69 74 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20  Lite */.#define 
4600: 53 51 4c 49 54 45 5f 50 45 52 4d 20 20 20 20 20  SQLITE_PERM     
4610: 20 20 20 20 33 20 20 20 2f 2a 20 41 63 63 65 73      3   /* Acces
4620: 73 20 70 65 72 6d 69 73 73 69 6f 6e 20 64 65 6e  s permission den
4630: 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ied */.#define S
4640: 51 4c 49 54 45 5f 41 42 4f 52 54 20 20 20 20 20  QLITE_ABORT     
4650: 20 20 20 34 20 20 20 2f 2a 20 43 61 6c 6c 62 61     4   /* Callba
4660: 63 6b 20 72 6f 75 74 69 6e 65 20 72 65 71 75 65  ck routine reque
4670: 73 74 65 64 20 61 6e 20 61 62 6f 72 74 20 2a 2f  sted an abort */
4680: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4690: 42 55 53 59 20 20 20 20 20 20 20 20 20 35 20 20  BUSY         5  
46a0: 20 2f 2a 20 54 68 65 20 64 61 74 61 62 61 73 65   /* The database
46b0: 20 66 69 6c 65 20 69 73 20 6c 6f 63 6b 65 64 20   file is locked 
46c0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
46d0: 45 5f 4c 4f 43 4b 45 44 20 20 20 20 20 20 20 36  E_LOCKED       6
46e0: 20 20 20 2f 2a 20 41 20 74 61 62 6c 65 20 69 6e     /* A table in
46f0: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73   the database is
4700: 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64 65 66 69   locked */.#defi
4710: 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20  ne SQLITE_NOMEM 
4720: 20 20 20 20 20 20 20 37 20 20 20 2f 2a 20 41 20         7   /* A 
4730: 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 65 64 20  malloc() failed 
4740: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
4750: 45 5f 52 45 41 44 4f 4e 4c 59 20 20 20 20 20 38  E_READONLY     8
4760: 20 20 20 2f 2a 20 41 74 74 65 6d 70 74 20 74 6f     /* Attempt to
4770: 20 77 72 69 74 65 20 61 20 72 65 61 64 6f 6e 6c   write a readonl
4780: 79 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 23 64  y database */.#d
4790: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54  efine SQLITE_INT
47a0: 45 52 52 55 50 54 20 20 20 20 39 20 20 20 2f 2a  ERRUPT    9   /*
47b0: 20 4f 70 65 72 61 74 69 6f 6e 20 74 65 72 6d 69   Operation termi
47c0: 6e 61 74 65 64 20 62 79 20 73 71 6c 69 74 65 33  nated by sqlite3
47d0: 5f 69 6e 74 65 72 72 75 70 74 28 29 2a 2f 0a 23  _interrupt()*/.#
47e0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
47f0: 45 52 52 20 20 20 20 20 20 20 31 30 20 20 20 2f  ERR       10   /
4800: 2a 20 53 6f 6d 65 20 6b 69 6e 64 20 6f 66 20 64  * Some kind of d
4810: 69 73 6b 20 49 2f 4f 20 65 72 72 6f 72 20 6f 63  isk I/O error oc
4820: 63 75 72 72 65 64 20 2a 2f 0a 23 64 65 66 69 6e  curred */.#defin
4830: 65 20 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54  e SQLITE_CORRUPT
4840: 20 20 20 20 20 31 31 20 20 20 2f 2a 20 54 68 65       11   /* The
4850: 20 64 61 74 61 62 61 73 65 20 64 69 73 6b 20 69   database disk i
4860: 6d 61 67 65 20 69 73 20 6d 61 6c 66 6f 72 6d 65  mage is malforme
4870: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  d */.#define SQL
4880: 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 20 20 20 20  ITE_NOTFOUND    
4890: 31 32 20 20 20 2f 2a 20 55 6e 6b 6e 6f 77 6e 20  12   /* Unknown 
48a0: 6f 70 63 6f 64 65 20 69 6e 20 73 71 6c 69 74 65  opcode in sqlite
48b0: 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29  3_file_control()
48c0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
48d0: 54 45 5f 46 55 4c 4c 20 20 20 20 20 20 20 20 31  TE_FULL        1
48e0: 33 20 20 20 2f 2a 20 49 6e 73 65 72 74 69 6f 6e  3   /* Insertion
48f0: 20 66 61 69 6c 65 64 20 62 65 63 61 75 73 65 20   failed because 
4900: 64 61 74 61 62 61 73 65 20 69 73 20 66 75 6c 6c  database is full
4910: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4920: 54 45 5f 43 41 4e 54 4f 50 45 4e 20 20 20 20 31  TE_CANTOPEN    1
4930: 34 20 20 20 2f 2a 20 55 6e 61 62 6c 65 20 74 6f  4   /* Unable to
4940: 20 6f 70 65 6e 20 74 68 65 20 64 61 74 61 62 61   open the databa
4950: 73 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65 66 69  se file */.#defi
4960: 6e 65 20 53 51 4c 49 54 45 5f 50 52 4f 54 4f 43  ne SQLITE_PROTOC
4970: 4f 4c 20 20 20 20 31 35 20 20 20 2f 2a 20 44 61  OL    15   /* Da
4980: 74 61 62 61 73 65 20 6c 6f 63 6b 20 70 72 6f 74  tabase lock prot
4990: 6f 63 6f 6c 20 65 72 72 6f 72 20 2a 2f 0a 23 64  ocol error */.#d
49a0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 4d 50  efine SQLITE_EMP
49b0: 54 59 20 20 20 20 20 20 20 31 36 20 20 20 2f 2a  TY       16   /*
49c0: 20 44 61 74 61 62 61 73 65 20 69 73 20 65 6d 70   Database is emp
49d0: 74 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ty */.#define SQ
49e0: 4c 49 54 45 5f 53 43 48 45 4d 41 20 20 20 20 20  LITE_SCHEMA     
49f0: 20 31 37 20 20 20 2f 2a 20 54 68 65 20 64 61 74   17   /* The dat
4a00: 61 62 61 73 65 20 73 63 68 65 6d 61 20 63 68 61  abase schema cha
4a10: 6e 67 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20  nged */.#define 
4a20: 53 51 4c 49 54 45 5f 54 4f 4f 42 49 47 20 20 20  SQLITE_TOOBIG   
4a30: 20 20 20 31 38 20 20 20 2f 2a 20 53 74 72 69 6e     18   /* Strin
4a40: 67 20 6f 72 20 42 4c 4f 42 20 65 78 63 65 65 64  g or BLOB exceed
4a50: 73 20 73 69 7a 65 20 6c 69 6d 69 74 20 2a 2f 0a  s size limit */.
4a60: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
4a70: 4f 4e 53 54 52 41 49 4e 54 20 20 31 39 20 20 20  ONSTRAINT  19   
4a80: 2f 2a 20 41 62 6f 72 74 20 64 75 65 20 74 6f 20  /* Abort due to 
4a90: 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c 61  constraint viola
4aa0: 74 69 6f 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20  tion */.#define 
4ab0: 53 51 4c 49 54 45 5f 4d 49 53 4d 41 54 43 48 20  SQLITE_MISMATCH 
4ac0: 20 20 20 32 30 20 20 20 2f 2a 20 44 61 74 61 20     20   /* Data 
4ad0: 74 79 70 65 20 6d 69 73 6d 61 74 63 68 20 2a 2f  type mismatch */
4ae0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4af0: 4d 49 53 55 53 45 20 20 20 20 20 20 32 31 20 20  MISUSE      21  
4b00: 20 2f 2a 20 4c 69 62 72 61 72 79 20 75 73 65 64   /* Library used
4b10: 20 69 6e 63 6f 72 72 65 63 74 6c 79 20 2a 2f 0a   incorrectly */.
4b20: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e  #define SQLITE_N
4b30: 4f 4c 46 53 20 20 20 20 20 20 20 32 32 20 20 20  OLFS       22   
4b40: 2f 2a 20 55 73 65 73 20 4f 53 20 66 65 61 74 75  /* Uses OS featu
4b50: 72 65 73 20 6e 6f 74 20 73 75 70 70 6f 72 74 65  res not supporte
4b60: 64 20 6f 6e 20 68 6f 73 74 20 2a 2f 0a 23 64 65  d on host */.#de
4b70: 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 55 54 48  fine SQLITE_AUTH
4b80: 20 20 20 20 20 20 20 20 32 33 20 20 20 2f 2a 20          23   /* 
4b90: 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 64 65  Authorization de
4ba0: 6e 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20  nied */.#define 
4bb0: 53 51 4c 49 54 45 5f 46 4f 52 4d 41 54 20 20 20  SQLITE_FORMAT   
4bc0: 20 20 20 32 34 20 20 20 2f 2a 20 41 75 78 69 6c     24   /* Auxil
4bd0: 69 61 72 79 20 64 61 74 61 62 61 73 65 20 66 6f  iary database fo
4be0: 72 6d 61 74 20 65 72 72 6f 72 20 2a 2f 0a 23 64  rmat error */.#d
4bf0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 41 4e  efine SQLITE_RAN
4c00: 47 45 20 20 20 20 20 20 20 32 35 20 20 20 2f 2a  GE       25   /*
4c10: 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74   2nd parameter t
4c20: 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 20 6f  o sqlite3_bind o
4c30: 75 74 20 6f 66 20 72 61 6e 67 65 20 2a 2f 0a 23  ut of range */.#
4c40: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f  define SQLITE_NO
4c50: 54 41 44 42 20 20 20 20 20 20 32 36 20 20 20 2f  TADB      26   /
4c60: 2a 20 46 69 6c 65 20 6f 70 65 6e 65 64 20 74 68  * File opened th
4c70: 61 74 20 69 73 20 6e 6f 74 20 61 20 64 61 74 61  at is not a data
4c80: 62 61 73 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65  base file */.#de
4c90: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 49  fine SQLITE_NOTI
4ca0: 43 45 20 20 20 20 20 20 32 37 20 20 20 2f 2a 20  CE      27   /* 
4cb0: 4e 6f 74 69 66 69 63 61 74 69 6f 6e 73 20 66 72  Notifications fr
4cc0: 6f 6d 20 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29  om sqlite3_log()
4cd0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4ce0: 54 45 5f 57 41 52 4e 49 4e 47 20 20 20 20 20 32  TE_WARNING     2
4cf0: 38 20 20 20 2f 2a 20 57 61 72 6e 69 6e 67 73 20  8   /* Warnings 
4d00: 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6c 6f 67  from sqlite3_log
4d10: 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  () */.#define SQ
4d20: 4c 49 54 45 5f 52 4f 57 20 20 20 20 20 20 20 20  LITE_ROW        
4d30: 20 31 30 30 20 20 2f 2a 20 73 71 6c 69 74 65 33   100  /* sqlite3
4d40: 5f 73 74 65 70 28 29 20 68 61 73 20 61 6e 6f 74  _step() has anot
4d50: 68 65 72 20 72 6f 77 20 72 65 61 64 79 20 2a 2f  her row ready */
4d60: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4d70: 44 4f 4e 45 20 20 20 20 20 20 20 20 31 30 31 20  DONE        101 
4d80: 20 2f 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70   /* sqlite3_step
4d90: 28 29 20 68 61 73 20 66 69 6e 69 73 68 65 64 20  () has finished 
4da0: 65 78 65 63 75 74 69 6e 67 20 2a 2f 0a 2f 2a 20  executing */./* 
4db0: 65 6e 64 2d 6f 66 2d 65 72 72 6f 72 2d 63 6f 64  end-of-error-cod
4dc0: 65 73 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  es */../*.** CAP
4dd0: 49 33 52 45 46 3a 20 45 78 74 65 6e 64 65 64 20  I3REF: Extended 
4de0: 52 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a 20  Result Codes.** 
4df0: 4b 45 59 57 4f 52 44 53 3a 20 7b 65 78 74 65 6e  KEYWORDS: {exten
4e00: 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 20  ded result code 
4e10: 64 65 66 69 6e 69 74 69 6f 6e 73 7d 0a 2a 2a 0a  definitions}.**.
4e20: 2a 2a 20 49 6e 20 69 74 73 20 64 65 66 61 75 6c  ** In its defaul
4e30: 74 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 2c  t configuration,
4e40: 20 53 51 4c 69 74 65 20 41 50 49 20 72 6f 75 74   SQLite API rout
4e50: 69 6e 65 73 20 72 65 74 75 72 6e 20 6f 6e 65 20  ines return one 
4e60: 6f 66 20 33 30 20 69 6e 74 65 67 65 72 0a 2a 2a  of 30 integer.**
4e70: 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 2e   [result codes].
4e80: 20 20 48 6f 77 65 76 65 72 2c 20 65 78 70 65 72    However, exper
4e90: 69 65 6e 63 65 20 68 61 73 20 73 68 6f 77 6e 20  ience has shown 
4ea0: 74 68 61 74 20 6d 61 6e 79 20 6f 66 0a 2a 2a 20  that many of.** 
4eb0: 74 68 65 73 65 20 72 65 73 75 6c 74 20 63 6f 64  these result cod
4ec0: 65 73 20 61 72 65 20 74 6f 6f 20 63 6f 61 72 73  es are too coars
4ed0: 65 2d 67 72 61 69 6e 65 64 2e 20 20 54 68 65 79  e-grained.  They
4ee0: 20 64 6f 20 6e 6f 74 20 70 72 6f 76 69 64 65 20   do not provide 
4ef0: 61 73 0a 2a 2a 20 6d 75 63 68 20 69 6e 66 6f 72  as.** much infor
4f00: 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 70 72 6f  mation about pro
4f10: 62 6c 65 6d 73 20 61 73 20 70 72 6f 67 72 61 6d  blems as program
4f20: 6d 65 72 73 20 6d 69 67 68 74 20 6c 69 6b 65 2e  mers might like.
4f30: 20 20 49 6e 20 61 6e 20 65 66 66 6f 72 74 20 74    In an effort t
4f40: 6f 0a 2a 2a 20 61 64 64 72 65 73 73 20 74 68 69  o.** address thi
4f50: 73 2c 20 6e 65 77 65 72 20 76 65 72 73 69 6f 6e  s, newer version
4f60: 73 20 6f 66 20 53 51 4c 69 74 65 20 28 76 65 72  s of SQLite (ver
4f70: 73 69 6f 6e 20 33 2e 33 2e 38 20 5b 64 61 74 65  sion 3.3.8 [date
4f80: 6f 66 3a 33 2e 33 2e 38 5d 0a 2a 2a 20 61 6e 64  of:3.3.8].** and
4f90: 20 6c 61 74 65 72 29 20 69 6e 63 6c 75 64 65 0a   later) include.
4fa0: 2a 2a 20 73 75 70 70 6f 72 74 20 66 6f 72 20 61  ** support for a
4fb0: 64 64 69 74 69 6f 6e 61 6c 20 72 65 73 75 6c 74  dditional result
4fc0: 20 63 6f 64 65 73 20 74 68 61 74 20 70 72 6f 76   codes that prov
4fd0: 69 64 65 20 6d 6f 72 65 20 64 65 74 61 69 6c 65  ide more detaile
4fe0: 64 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a  d information.**
4ff0: 20 61 62 6f 75 74 20 65 72 72 6f 72 73 2e 20 54   about errors. T
5000: 68 65 73 65 20 5b 65 78 74 65 6e 64 65 64 20 72  hese [extended r
5010: 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 61 72 65  esult codes] are
5020: 20 65 6e 61 62 6c 65 64 20 6f 72 20 64 69 73 61   enabled or disa
5030: 62 6c 65 64 0a 2a 2a 20 6f 6e 20 61 20 70 65 72  bled.** on a per
5040: 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
5050: 74 69 6f 6e 20 62 61 73 69 73 20 75 73 69 6e 67  tion basis using
5060: 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
5070: 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74  _extended_result
5080: 5f 63 6f 64 65 73 28 29 5d 20 41 50 49 2e 20 20  _codes()] API.  
5090: 4f 72 2c 20 74 68 65 20 65 78 74 65 6e 64 65 64  Or, the extended
50a0: 20 63 6f 64 65 20 66 6f 72 0a 2a 2a 20 74 68 65   code for.** the
50b0: 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 65 72 72   most recent err
50c0: 6f 72 20 63 61 6e 20 62 65 20 6f 62 74 61 69 6e  or can be obtain
50d0: 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c  ed using.** [sql
50e0: 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 65 72  ite3_extended_er
50f0: 72 63 6f 64 65 28 29 5d 2e 0a 2a 2f 0a 23 64 65  rcode()]..*/.#de
5100: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
5110: 52 5f 52 45 41 44 20 20 20 20 20 20 20 20 20 20  R_READ          
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 31 3c 3c 38 29 29 0a 23 64 65 66  R | (1<<8)).#def
5140: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5150: 5f 53 48 4f 52 54 5f 52 45 41 44 20 20 20 20 20  _SHORT_READ     
5160: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5170: 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69   | (2<<8)).#defi
5180: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5190: 57 52 49 54 45 20 20 20 20 20 20 20 20 20 20 20  WRITE           
51a0: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
51b0: 7c 20 28 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (3<<8)).#defin
51c0: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 46  e SQLITE_IOERR_F
51d0: 53 59 4e 43 20 20 20 20 20 20 20 20 20 20 20 20  SYNC            
51e0: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c   (SQLITE_IOERR |
51f0: 20 28 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (4<<8)).#define
5200: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44 49   SQLITE_IOERR_DI
5210: 52 5f 46 53 59 4e 43 20 20 20 20 20 20 20 20 20  R_FSYNC         
5220: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
5230: 28 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (5<<8)).#define 
5240: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 54 52 55  SQLITE_IOERR_TRU
5250: 4e 43 41 54 45 20 20 20 20 20 20 20 20 20 20 28  NCATE          (
5260: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
5270: 36 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  6<<8)).#define S
5280: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 46 53 54 41  QLITE_IOERR_FSTA
5290: 54 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53  T             (S
52a0: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 37  QLITE_IOERR | (7
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 55 4e 4c 4f 43  LITE_IOERR_UNLOC
52d0: 4b 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51  K            (SQ
52e0: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 38 3c  LITE_IOERR | (8<
52f0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5300: 49 54 45 5f 49 4f 45 52 52 5f 52 44 4c 4f 43 4b  ITE_IOERR_RDLOCK
5310: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
5320: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 39 3c 3c  ITE_IOERR | (9<<
5330: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5340: 54 45 5f 49 4f 45 52 52 5f 44 45 4c 45 54 45 20  TE_IOERR_DELETE 
5350: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
5360: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 30 3c 3c  TE_IOERR | (10<<
5370: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5380: 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44  TE_IOERR_BLOCKED
5390: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
53a0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 31 3c 3c  TE_IOERR | (11<<
53b0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
53c0: 54 45 5f 49 4f 45 52 52 5f 4e 4f 4d 45 4d 20 20  TE_IOERR_NOMEM  
53d0: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
53e0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 32 3c 3c  TE_IOERR | (12<<
53f0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5400: 54 45 5f 49 4f 45 52 52 5f 41 43 43 45 53 53 20  TE_IOERR_ACCESS 
5410: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
5420: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 33 3c 3c  TE_IOERR | (13<<
5430: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5440: 54 45 5f 49 4f 45 52 52 5f 43 48 45 43 4b 52 45  TE_IOERR_CHECKRE
5450: 53 45 52 56 45 44 4c 4f 43 4b 20 28 53 51 4c 49  SERVEDLOCK (SQLI
5460: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 34 3c 3c  TE_IOERR | (14<<
5470: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5480: 54 45 5f 49 4f 45 52 52 5f 4c 4f 43 4b 20 20 20  TE_IOERR_LOCK   
5490: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
54a0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 35 3c 3c  TE_IOERR | (15<<
54b0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
54c0: 54 45 5f 49 4f 45 52 52 5f 43 4c 4f 53 45 20 20  TE_IOERR_CLOSE  
54d0: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
54e0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 36 3c 3c  TE_IOERR | (16<<
54f0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5500: 54 45 5f 49 4f 45 52 52 5f 44 49 52 5f 43 4c 4f  TE_IOERR_DIR_CLO
5510: 53 45 20 20 20 20 20 20 20 20 20 28 53 51 4c 49  SE         (SQLI
5520: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 37 3c 3c  TE_IOERR | (17<<
5530: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5540: 54 45 5f 49 4f 45 52 52 5f 53 48 4d 4f 50 45 4e  TE_IOERR_SHMOPEN
5550: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
5560: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 38 3c 3c  TE_IOERR | (18<<
5570: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5580: 54 45 5f 49 4f 45 52 52 5f 53 48 4d 53 49 5a 45  TE_IOERR_SHMSIZE
5590: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
55a0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 39 3c 3c  TE_IOERR | (19<<
55b0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
55c0: 54 45 5f 49 4f 45 52 52 5f 53 48 4d 4c 4f 43 4b  TE_IOERR_SHMLOCK
55d0: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
55e0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 30 3c 3c  TE_IOERR | (20<<
55f0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5600: 54 45 5f 49 4f 45 52 52 5f 53 48 4d 4d 41 50 20  TE_IOERR_SHMMAP 
5610: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
5620: 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 31 3c 3c  TE_IOERR | (21<<
5630: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5640: 54 45 5f 49 4f 45 52 52 5f 53 45 45 4b 20 20 20  TE_IOERR_SEEK   
5650: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
5660: 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 32 3c 3c  TE_IOERR | (22<<
5670: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5680: 54 45 5f 49 4f 45 52 52 5f 44 45 4c 45 54 45 5f  TE_IOERR_DELETE_
5690: 4e 4f 45 4e 54 20 20 20 20 20 20 28 53 51 4c 49  NOENT      (SQLI
56a0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 33 3c 3c  TE_IOERR | (23<<
56b0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
56c0: 54 45 5f 49 4f 45 52 52 5f 4d 4d 41 50 20 20 20  TE_IOERR_MMAP   
56d0: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
56e0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 34 3c 3c  TE_IOERR | (24<<
56f0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5700: 54 45 5f 49 4f 45 52 52 5f 47 45 54 54 45 4d 50  TE_IOERR_GETTEMP
5710: 50 41 54 48 20 20 20 20 20 20 20 28 53 51 4c 49  PATH       (SQLI
5720: 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 35 3c 3c  TE_IOERR | (25<<
5730: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5740: 54 45 5f 49 4f 45 52 52 5f 43 4f 4e 56 50 41 54  TE_IOERR_CONVPAT
5750: 48 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49  H          (SQLI
5760: 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 36 3c 3c  TE_IOERR | (26<<
5770: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5780: 54 45 5f 49 4f 45 52 52 5f 56 4e 4f 44 45 20 20  TE_IOERR_VNODE  
5790: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
57a0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 37 3c 3c  TE_IOERR | (27<<
57b0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
57c0: 54 45 5f 49 4f 45 52 52 5f 41 55 54 48 20 20 20  TE_IOERR_AUTH   
57d0: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
57e0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 38 3c 3c  TE_IOERR | (28<<
57f0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5800: 54 45 5f 4c 4f 43 4b 45 44 5f 53 48 41 52 45 44  TE_LOCKED_SHARED
5810: 43 41 43 48 45 20 20 20 20 20 20 28 53 51 4c 49  CACHE      (SQLI
5820: 54 45 5f 4c 4f 43 4b 45 44 20 7c 20 20 28 31 3c  TE_LOCKED |  (1<
5830: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5840: 49 54 45 5f 42 55 53 59 5f 52 45 43 4f 56 45 52  ITE_BUSY_RECOVER
5850: 59 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c  Y           (SQL
5860: 49 54 45 5f 42 55 53 59 20 20 20 7c 20 20 28 31  ITE_BUSY   |  (1
5870: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5880: 4c 49 54 45 5f 42 55 53 59 5f 53 4e 41 50 53 48  LITE_BUSY_SNAPSH
5890: 4f 54 20 20 20 20 20 20 20 20 20 20 20 28 53 51  OT           (SQ
58a0: 4c 49 54 45 5f 42 55 53 59 20 20 20 7c 20 20 28  LITE_BUSY   |  (
58b0: 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  2<<8)).#define S
58c0: 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5f 4e  QLITE_CANTOPEN_N
58d0: 4f 54 45 4d 50 44 49 52 20 20 20 20 20 20 28 53  OTEMPDIR      (S
58e0: 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 7c  QLITE_CANTOPEN |
58f0: 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (1<<8)).#define
5900: 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e   SQLITE_CANTOPEN
5910: 5f 49 53 44 49 52 20 20 20 20 20 20 20 20 20 20  _ISDIR          
5920: 28 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e  (SQLITE_CANTOPEN
5930: 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69   | (2<<8)).#defi
5940: 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50  ne SQLITE_CANTOP
5950: 45 4e 5f 46 55 4c 4c 50 41 54 48 20 20 20 20 20  EN_FULLPATH     
5960: 20 20 28 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50    (SQLITE_CANTOP
5970: 45 4e 20 7c 20 28 33 3c 3c 38 29 29 0a 23 64 65  EN | (3<<8)).#de
5980: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e 54  fine SQLITE_CANT
5990: 4f 50 45 4e 5f 43 4f 4e 56 50 41 54 48 20 20 20  OPEN_CONVPATH   
59a0: 20 20 20 20 28 53 51 4c 49 54 45 5f 43 41 4e 54      (SQLITE_CANT
59b0: 4f 50 45 4e 20 7c 20 28 34 3c 3c 38 29 29 0a 23  OPEN | (4<<8)).#
59c0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
59d0: 52 52 55 50 54 5f 56 54 41 42 20 20 20 20 20 20  RRUPT_VTAB      
59e0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f        (SQLITE_CO
59f0: 52 52 55 50 54 20 7c 20 28 31 3c 3c 38 29 29 0a  RRUPT | (1<<8)).
5a00: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52  #define SQLITE_R
5a10: 45 41 44 4f 4e 4c 59 5f 52 45 43 4f 56 45 52 59  EADONLY_RECOVERY
5a20: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 52         (SQLITE_R
5a30: 45 41 44 4f 4e 4c 59 20 7c 20 28 31 3c 3c 38 29  EADONLY | (1<<8)
5a40: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5a50: 5f 52 45 41 44 4f 4e 4c 59 5f 43 41 4e 54 4c 4f  _READONLY_CANTLO
5a60: 43 4b 20 20 20 20 20 20 20 28 53 51 4c 49 54 45  CK       (SQLITE
5a70: 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28 32 3c 3c  _READONLY | (2<<
5a80: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5a90: 54 45 5f 52 45 41 44 4f 4e 4c 59 5f 52 4f 4c 4c  TE_READONLY_ROLL
5aa0: 42 41 43 4b 20 20 20 20 20 20 20 28 53 51 4c 49  BACK       (SQLI
5ab0: 54 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28 33  TE_READONLY | (3
5ac0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5ad0: 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5f 44 42  LITE_READONLY_DB
5ae0: 4d 4f 56 45 44 20 20 20 20 20 20 20 20 28 53 51  MOVED        (SQ
5af0: 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20  LITE_READONLY | 
5b00: 28 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (4<<8)).#define 
5b10: 53 51 4c 49 54 45 5f 41 42 4f 52 54 5f 52 4f 4c  SQLITE_ABORT_ROL
5b20: 4c 42 41 43 4b 20 20 20 20 20 20 20 20 20 20 28  LBACK          (
5b30: 53 51 4c 49 54 45 5f 41 42 4f 52 54 20 7c 20 28  SQLITE_ABORT | (
5b40: 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  2<<8)).#define S
5b50: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54  QLITE_CONSTRAINT
5b60: 5f 43 48 45 43 4b 20 20 20 20 20 20 20 20 28 53  _CHECK        (S
5b70: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54  QLITE_CONSTRAINT
5b80: 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69   | (1<<8)).#defi
5b90: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52  ne SQLITE_CONSTR
5ba0: 41 49 4e 54 5f 43 4f 4d 4d 49 54 48 4f 4f 4b 20  AINT_COMMITHOOK 
5bb0: 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52    (SQLITE_CONSTR
5bc0: 41 49 4e 54 20 7c 20 28 32 3c 3c 38 29 29 0a 23  AINT | (2<<8)).#
5bd0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
5be0: 4e 53 54 52 41 49 4e 54 5f 46 4f 52 45 49 47 4e  NSTRAINT_FOREIGN
5bf0: 4b 45 59 20 20 20 28 53 51 4c 49 54 45 5f 43 4f  KEY   (SQLITE_CO
5c00: 4e 53 54 52 41 49 4e 54 20 7c 20 28 33 3c 3c 38  NSTRAINT | (3<<8
5c10: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5c20: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 46 55 4e  E_CONSTRAINT_FUN
5c30: 43 54 49 4f 4e 20 20 20 20 20 28 53 51 4c 49 54  CTION     (SQLIT
5c40: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28  E_CONSTRAINT | (
5c50: 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  4<<8)).#define S
5c60: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54  QLITE_CONSTRAINT
5c70: 5f 4e 4f 54 4e 55 4c 4c 20 20 20 20 20 20 28 53  _NOTNULL      (S
5c80: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54  QLITE_CONSTRAINT
5c90: 20 7c 20 28 35 3c 3c 38 29 29 0a 23 64 65 66 69   | (5<<8)).#defi
5ca0: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52  ne SQLITE_CONSTR
5cb0: 41 49 4e 54 5f 50 52 49 4d 41 52 59 4b 45 59 20  AINT_PRIMARYKEY 
5cc0: 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52    (SQLITE_CONSTR
5cd0: 41 49 4e 54 20 7c 20 28 36 3c 3c 38 29 29 0a 23  AINT | (6<<8)).#
5ce0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
5cf0: 4e 53 54 52 41 49 4e 54 5f 54 52 49 47 47 45 52  NSTRAINT_TRIGGER
5d00: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f        (SQLITE_CO
5d10: 4e 53 54 52 41 49 4e 54 20 7c 20 28 37 3c 3c 38  NSTRAINT | (7<<8
5d20: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5d30: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 55 4e 49  E_CONSTRAINT_UNI
5d40: 51 55 45 20 20 20 20 20 20 20 28 53 51 4c 49 54  QUE       (SQLIT
5d50: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28  E_CONSTRAINT | (
5d60: 38 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  8<<8)).#define S
5d70: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54  QLITE_CONSTRAINT
5d80: 5f 56 54 41 42 20 20 20 20 20 20 20 20 20 28 53  _VTAB         (S
5d90: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54  QLITE_CONSTRAINT
5da0: 20 7c 20 28 39 3c 3c 38 29 29 0a 23 64 65 66 69   | (9<<8)).#defi
5db0: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52  ne SQLITE_CONSTR
5dc0: 41 49 4e 54 5f 52 4f 57 49 44 20 20 20 20 20 20  AINT_ROWID      
5dd0: 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52    (SQLITE_CONSTR
5de0: 41 49 4e 54 20 7c 28 31 30 3c 3c 38 29 29 0a 23  AINT |(10<<8)).#
5df0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f  define SQLITE_NO
5e00: 54 49 43 45 5f 52 45 43 4f 56 45 52 5f 57 41 4c  TICE_RECOVER_WAL
5e10: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 4e 4f        (SQLITE_NO
5e20: 54 49 43 45 20 7c 20 28 31 3c 3c 38 29 29 0a 23  TICE | (1<<8)).#
5e30: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f  define SQLITE_NO
5e40: 54 49 43 45 5f 52 45 43 4f 56 45 52 5f 52 4f 4c  TICE_RECOVER_ROL
5e50: 4c 42 41 43 4b 20 28 53 51 4c 49 54 45 5f 4e 4f  LBACK (SQLITE_NO
5e60: 54 49 43 45 20 7c 20 28 32 3c 3c 38 29 29 0a 23  TICE | (2<<8)).#
5e70: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 57 41  define SQLITE_WA
5e80: 52 4e 49 4e 47 5f 41 55 54 4f 49 4e 44 45 58 20  RNING_AUTOINDEX 
5e90: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 57 41        (SQLITE_WA
5ea0: 52 4e 49 4e 47 20 7c 20 28 31 3c 3c 38 29 29 0a  RNING | (1<<8)).
5eb0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
5ec0: 55 54 48 5f 55 53 45 52 20 20 20 20 20 20 20 20  UTH_USER        
5ed0: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 41         (SQLITE_A
5ee0: 55 54 48 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64  UTH | (1<<8)).#d
5ef0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 4b 5f  efine SQLITE_OK_
5f00: 4c 4f 41 44 5f 50 45 52 4d 41 4e 45 4e 54 4c 59  LOAD_PERMANENTLY
5f10: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 4f 4b 20       (SQLITE_OK 
5f20: 7c 20 28 31 3c 3c 38 29 29 0a 0a 2f 2a 0a 2a 2a  | (1<<8))../*.**
5f30: 20 43 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73   CAPI3REF: Flags
5f40: 20 46 6f 72 20 46 69 6c 65 20 4f 70 65 6e 20 4f   For File Open O
5f50: 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20  perations.**.** 
5f60: 54 68 65 73 65 20 62 69 74 20 76 61 6c 75 65 73  These bit values
5f70: 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20 66 6f   are intended fo
5f80: 72 20 75 73 65 20 69 6e 20 74 68 65 0a 2a 2a 20  r use in the.** 
5f90: 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  3rd parameter to
5fa0: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70   the [sqlite3_op
5fb0: 65 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72 66 61  en_v2()] interfa
5fc0: 63 65 20 61 6e 64 0a 2a 2a 20 69 6e 20 74 68 65  ce and.** in the
5fd0: 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74   4th parameter t
5fe0: 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  o the [sqlite3_v
5ff0: 66 73 2e 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64  fs.xOpen] method
6000: 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
6010: 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c  ITE_OPEN_READONL
6020: 59 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30  Y         0x0000
6030: 30 30 30 31 20 20 2f 2a 20 4f 6b 20 66 6f 72 20  0001  /* Ok for 
6040: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
6050: 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ) */.#define SQL
6060: 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49  ITE_OPEN_READWRI
6070: 54 45 20 20 20 20 20 20 20 20 30 78 30 30 30 30  TE        0x0000
6080: 30 30 30 32 20 20 2f 2a 20 4f 6b 20 66 6f 72 20  0002  /* Ok for 
6090: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
60a0: 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ) */.#define SQL
60b0: 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 20  ITE_OPEN_CREATE 
60c0: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
60d0: 30 30 30 34 20 20 2f 2a 20 4f 6b 20 66 6f 72 20  0004  /* Ok for 
60e0: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
60f0: 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ) */.#define SQL
6100: 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f  ITE_OPEN_DELETEO
6110: 4e 43 4c 4f 53 45 20 20 20 20 30 78 30 30 30 30  NCLOSE    0x0000
6120: 30 30 30 38 20 20 2f 2a 20 56 46 53 20 6f 6e 6c  0008  /* VFS onl
6130: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  y */.#define SQL
6140: 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49  ITE_OPEN_EXCLUSI
6150: 56 45 20 20 20 20 20 20 20 20 30 78 30 30 30 30  VE        0x0000
6160: 30 30 31 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c  0010  /* VFS onl
6170: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  y */.#define SQL
6180: 49 54 45 5f 4f 50 45 4e 5f 41 55 54 4f 50 52 4f  ITE_OPEN_AUTOPRO
6190: 58 59 20 20 20 20 20 20 20 20 30 78 30 30 30 30  XY        0x0000
61a0: 30 30 32 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c  0020  /* VFS onl
61b0: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  y */.#define SQL
61c0: 49 54 45 5f 4f 50 45 4e 5f 55 52 49 20 20 20 20  ITE_OPEN_URI    
61d0: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
61e0: 30 30 34 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20  0040  /* Ok for 
61f0: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
6200: 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ) */.#define SQL
6210: 49 54 45 5f 4f 50 45 4e 5f 4d 45 4d 4f 52 59 20  ITE_OPEN_MEMORY 
6220: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
6230: 30 30 38 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20  0080  /* Ok for 
6240: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
6250: 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ) */.#define SQL
6260: 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42  ITE_OPEN_MAIN_DB
6270: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
6280: 30 31 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c  0100  /* VFS onl
6290: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  y */.#define SQL
62a0: 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42  ITE_OPEN_TEMP_DB
62b0: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
62c0: 30 32 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c  0200  /* VFS onl
62d0: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  y */.#define SQL
62e0: 49 54 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 45  ITE_OPEN_TRANSIE
62f0: 4e 54 5f 44 42 20 20 20 20 20 30 78 30 30 30 30  NT_DB     0x0000
6300: 30 34 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c  0400  /* VFS onl
6310: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  y */.#define SQL
6320: 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f  ITE_OPEN_MAIN_JO
6330: 55 52 4e 41 4c 20 20 20 20 20 30 78 30 30 30 30  URNAL     0x0000
6340: 30 38 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c  0800  /* VFS onl
6350: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  y */.#define SQL
6360: 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f  ITE_OPEN_TEMP_JO
6370: 55 52 4e 41 4c 20 20 20 20 20 30 78 30 30 30 30  URNAL     0x0000
6380: 31 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c  1000  /* VFS onl
6390: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  y */.#define SQL
63a0: 49 54 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55 52  ITE_OPEN_SUBJOUR
63b0: 4e 41 4c 20 20 20 20 20 20 20 30 78 30 30 30 30  NAL       0x0000
63c0: 32 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c  2000  /* VFS onl
63d0: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  y */.#define SQL
63e0: 49 54 45 5f 4f 50 45 4e 5f 4d 41 53 54 45 52 5f  ITE_OPEN_MASTER_
63f0: 4a 4f 55 52 4e 41 4c 20 20 20 30 78 30 30 30 30  JOURNAL   0x0000
6400: 34 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c  4000  /* VFS onl
6410: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  y */.#define SQL
6420: 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58  ITE_OPEN_NOMUTEX
6430: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
6440: 38 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20  8000  /* Ok for 
6450: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
6460: 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ) */.#define SQL
6470: 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54  ITE_OPEN_FULLMUT
6480: 45 58 20 20 20 20 20 20 20 20 30 78 30 30 30 31  EX        0x0001
6490: 30 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20  0000  /* Ok for 
64a0: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
64b0: 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ) */.#define SQL
64c0: 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43  ITE_OPEN_SHAREDC
64d0: 41 43 48 45 20 20 20 20 20 20 30 78 30 30 30 32  ACHE      0x0002
64e0: 30 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20  0000  /* Ok for 
64f0: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
6500: 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ) */.#define SQL
6510: 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45  ITE_OPEN_PRIVATE
6520: 43 41 43 48 45 20 20 20 20 20 30 78 30 30 30 34  CACHE     0x0004
6530: 30 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20  0000  /* Ok for 
6540: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
6550: 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ) */.#define SQL
6560: 49 54 45 5f 4f 50 45 4e 5f 57 41 4c 20 20 20 20  ITE_OPEN_WAL    
6570: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 38            0x0008
6580: 30 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c  0000  /* VFS onl
6590: 79 20 2a 2f 0a 0a 2f 2a 20 52 65 73 65 72 76 65  y */../* Reserve
65a0: 64 3a 20 20 20 20 20 20 20 20 20 20 20 20 20 20  d:              
65b0: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 46             0x00F
65c0: 30 30 30 30 30 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20  00000 */../*.** 
65d0: 43 41 50 49 33 52 45 46 3a 20 44 65 76 69 63 65  CAPI3REF: Device
65e0: 20 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73   Characteristics
65f0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 44 65 76 69  .**.** The xDevi
6600: 63 65 43 68 61 72 61 63 74 65 72 69 73 74 69 63  ceCharacteristic
6610: 73 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20  s method of the 
6620: 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68  [sqlite3_io_meth
6630: 6f 64 73 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 72  ods].** object r
6640: 65 74 75 72 6e 73 20 61 6e 20 69 6e 74 65 67 65  eturns an intege
6650: 72 20 77 68 69 63 68 20 69 73 20 61 20 76 65 63  r which is a vec
6660: 74 6f 72 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20  tor of these.** 
6670: 62 69 74 20 76 61 6c 75 65 73 20 65 78 70 72 65  bit values expre
6680: 73 73 69 6e 67 20 49 2f 4f 20 63 68 61 72 61 63  ssing I/O charac
6690: 74 65 72 69 73 74 69 63 73 20 6f 66 20 74 68 65  teristics of the
66a0: 20 6d 61 73 73 20 73 74 6f 72 61 67 65 0a 2a 2a   mass storage.**
66b0: 20 64 65 76 69 63 65 20 74 68 61 74 20 68 6f 6c   device that hol
66c0: 64 73 20 74 68 65 20 66 69 6c 65 20 74 68 61 74  ds the file that
66d0: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f   the [sqlite3_io
66e0: 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 72 65 66  _methods].** ref
66f0: 65 72 73 20 74 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68  ers to..**.** Th
6700: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
6710: 54 4f 4d 49 43 20 70 72 6f 70 65 72 74 79 20 6d  TOMIC property m
6720: 65 61 6e 73 20 74 68 61 74 20 61 6c 6c 20 77 72  eans that all wr
6730: 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73  ites of.** any s
6740: 69 7a 65 20 61 72 65 20 61 74 6f 6d 69 63 2e 20  ize are atomic. 
6750: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41   The SQLITE_IOCA
6760: 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75  P_ATOMICnnn valu
6770: 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20  es.** mean that 
6780: 77 72 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73  writes of blocks
6790: 20 74 68 61 74 20 61 72 65 20 6e 6e 6e 20 62 79   that are nnn by
67a0: 74 65 73 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a  tes in size and.
67b0: 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65 64 20 74  ** are aligned t
67c0: 6f 20 61 6e 20 61 64 64 72 65 73 73 20 77 68 69  o an address whi
67d0: 63 68 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72  ch is an integer
67e0: 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20   multiple of.** 
67f0: 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e 20  nnn are atomic. 
6800: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41   The SQLITE_IOCA
6810: 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 76 61  P_SAFE_APPEND va
6820: 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61  lue means.** tha
6830: 74 20 77 68 65 6e 20 64 61 74 61 20 69 73 20 61  t when data is a
6840: 70 70 65 6e 64 65 64 20 74 6f 20 61 20 66 69 6c  ppended to a fil
6850: 65 2c 20 74 68 65 20 64 61 74 61 20 69 73 20 61  e, the data is a
6860: 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74  ppended.** first
6870: 20 74 68 65 6e 20 74 68 65 20 73 69 7a 65 20 6f   then the size o
6880: 66 20 74 68 65 20 66 69 6c 65 20 69 73 20 65 78  f the file is ex
6890: 74 65 6e 64 65 64 2c 20 6e 65 76 65 72 20 74 68  tended, never th
68a0: 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20 61  e other.** way a
68b0: 72 6f 75 6e 64 2e 20 20 54 68 65 20 53 51 4c 49  round.  The SQLI
68c0: 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54  TE_IOCAP_SEQUENT
68d0: 49 41 4c 20 70 72 6f 70 65 72 74 79 20 6d 65 61  IAL property mea
68e0: 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72  ns that.** infor
68f0: 6d 61 74 69 6f 6e 20 69 73 20 77 72 69 74 74 65  mation is writte
6900: 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20 74 68 65  n to disk in the
6910: 20 73 61 6d 65 20 6f 72 64 65 72 20 61 73 20 63   same order as c
6920: 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74  alls.** to xWrit
6930: 65 28 29 2e 20 20 54 68 65 20 53 51 4c 49 54 45  e().  The SQLITE
6940: 5f 49 4f 43 41 50 5f 50 4f 57 45 52 53 41 46 45  _IOCAP_POWERSAFE
6950: 5f 4f 56 45 52 57 52 49 54 45 20 70 72 6f 70 65  _OVERWRITE prope
6960: 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74 0a 2a  rty means that.*
6970: 2a 20 61 66 74 65 72 20 72 65 62 6f 6f 74 20 66  * after reboot f
6980: 6f 6c 6c 6f 77 69 6e 67 20 61 20 63 72 61 73 68  ollowing a crash
6990: 20 6f 72 20 70 6f 77 65 72 20 6c 6f 73 73 2c 20   or power loss, 
69a0: 74 68 65 20 6f 6e 6c 79 20 62 79 74 65 73 20 69  the only bytes i
69b0: 6e 20 61 0a 2a 2a 20 66 69 6c 65 20 74 68 61 74  n a.** file that
69c0: 20 77 65 72 65 20 77 72 69 74 74 65 6e 20 61 74   were written at
69d0: 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
69e0: 20 6c 65 76 65 6c 20 6d 69 67 68 74 20 68 61 76   level might hav
69f0: 65 20 63 68 61 6e 67 65 64 0a 2a 2a 20 61 6e 64  e changed.** and
6a00: 20 74 68 61 74 20 61 64 6a 61 63 65 6e 74 20 62   that adjacent b
6a10: 79 74 65 73 2c 20 65 76 65 6e 20 62 79 74 65 73  ytes, even bytes
6a20: 20 77 69 74 68 69 6e 20 74 68 65 20 73 61 6d 65   within the same
6a30: 20 73 65 63 74 6f 72 20 61 72 65 0a 2a 2a 20 67   sector are.** g
6a40: 75 61 72 61 6e 74 65 65 64 20 74 6f 20 62 65 20  uaranteed to be 
6a50: 75 6e 63 68 61 6e 67 65 64 2e 20 20 54 68 65 20  unchanged.  The 
6a60: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 55 4e 44  SQLITE_IOCAP_UND
6a70: 45 4c 45 54 41 42 4c 45 5f 57 48 45 4e 5f 4f 50  ELETABLE_WHEN_OP
6a80: 45 4e 0a 2a 2a 20 66 6c 61 67 20 69 6e 64 69 63  EN.** flag indic
6a90: 61 74 65 73 20 74 68 61 74 20 61 20 66 69 6c 65  ates that a file
6aa0: 20 63 61 6e 6e 6f 74 20 62 65 20 64 65 6c 65 74   cannot be delet
6ab0: 65 64 20 77 68 65 6e 20 6f 70 65 6e 2e 20 20 54  ed when open.  T
6ac0: 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 49 4f 43  he.** SQLITE_IOC
6ad0: 41 50 5f 49 4d 4d 55 54 41 42 4c 45 20 66 6c 61  AP_IMMUTABLE fla
6ae0: 67 20 69 6e 64 69 63 61 74 65 73 20 74 68 61 74  g indicates that
6af0: 20 74 68 65 20 66 69 6c 65 20 69 73 20 6f 6e 0a   the file is on.
6b00: 2a 2a 20 72 65 61 64 2d 6f 6e 6c 79 20 6d 65 64  ** read-only med
6b10: 69 61 20 61 6e 64 20 63 61 6e 6e 6f 74 20 62 65  ia and cannot be
6b20: 20 63 68 61 6e 67 65 64 20 65 76 65 6e 20 62 79   changed even by
6b30: 20 70 72 6f 63 65 73 73 65 73 20 77 69 74 68 0a   processes with.
6b40: 2a 2a 20 65 6c 65 76 61 74 65 64 20 70 72 69 76  ** elevated priv
6b50: 69 6c 65 67 65 73 2e 0a 2a 2f 0a 23 64 65 66 69  ileges..*/.#defi
6b60: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
6b70: 41 54 4f 4d 49 43 20 20 20 20 20 20 20 20 20 20  ATOMIC          
6b80: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30         0x0000000
6b90: 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  1.#define SQLITE
6ba0: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 35 31 32  _IOCAP_ATOMIC512
6bb0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78                0x
6bc0: 30 30 30 30 30 30 30 32 0a 23 64 65 66 69 6e 65  00000002.#define
6bd0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
6be0: 4f 4d 49 43 31 4b 20 20 20 20 20 20 20 20 20 20  OMIC1K          
6bf0: 20 20 20 20 20 30 78 30 30 30 30 30 30 30 34 0a       0x00000004.
6c00: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
6c10: 4f 43 41 50 5f 41 54 4f 4d 49 43 32 4b 20 20 20  OCAP_ATOMIC2K   
6c20: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30              0x00
6c30: 30 30 30 30 30 38 0a 23 64 65 66 69 6e 65 20 53  000008.#define S
6c40: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
6c50: 49 43 34 4b 20 20 20 20 20 20 20 20 20 20 20 20  IC4K            
6c60: 20 20 20 30 78 30 30 30 30 30 30 31 30 0a 23 64     0x00000010.#d
6c70: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
6c80: 41 50 5f 41 54 4f 4d 49 43 38 4b 20 20 20 20 20  AP_ATOMIC8K     
6c90: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
6ca0: 30 30 32 30 0a 23 64 65 66 69 6e 65 20 53 51 4c  0020.#define SQL
6cb0: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
6cc0: 31 36 4b 20 20 20 20 20 20 20 20 20 20 20 20 20  16K             
6cd0: 20 30 78 30 30 30 30 30 30 34 30 0a 23 64 65 66   0x00000040.#def
6ce0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
6cf0: 5f 41 54 4f 4d 49 43 33 32 4b 20 20 20 20 20 20  _ATOMIC32K      
6d00: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
6d10: 38 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  80.#define SQLIT
6d20: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 36 34  E_IOCAP_ATOMIC64
6d30: 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30  K              0
6d40: 78 30 30 30 30 30 31 30 30 0a 23 64 65 66 69 6e  x00000100.#defin
6d50: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53  e SQLITE_IOCAP_S
6d60: 41 46 45 5f 41 50 50 45 4e 44 20 20 20 20 20 20  AFE_APPEND      
6d70: 20 20 20 20 20 20 30 78 30 30 30 30 30 32 30 30        0x00000200
6d80: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6d90: 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c  IOCAP_SEQUENTIAL
6da0: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30               0x0
6db0: 30 30 30 30 34 30 30 0a 23 64 65 66 69 6e 65 20  0000400.#define 
6dc0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 55 4e 44  SQLITE_IOCAP_UND
6dd0: 45 4c 45 54 41 42 4c 45 5f 57 48 45 4e 5f 4f 50  ELETABLE_WHEN_OP
6de0: 45 4e 20 20 30 78 30 30 30 30 30 38 30 30 0a 23  EN  0x00000800.#
6df0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
6e00: 43 41 50 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56  CAP_POWERSAFE_OV
6e10: 45 52 57 52 49 54 45 20 20 20 20 30 78 30 30 30  ERWRITE    0x000
6e20: 30 31 30 30 30 0a 23 64 65 66 69 6e 65 20 53 51  01000.#define SQ
6e30: 4c 49 54 45 5f 49 4f 43 41 50 5f 49 4d 4d 55 54  LITE_IOCAP_IMMUT
6e40: 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 20 20  ABLE            
6e50: 20 20 30 78 30 30 30 30 32 30 30 30 0a 0a 2f 2a    0x00002000../*
6e60: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 69  .** CAPI3REF: Fi
6e70: 6c 65 20 4c 6f 63 6b 69 6e 67 20 4c 65 76 65 6c  le Locking Level
6e80: 73 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75  s.**.** SQLite u
6e90: 73 65 73 20 6f 6e 65 20 6f 66 20 74 68 65 73 65  ses one of these
6ea0: 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20   integer values 
6eb0: 61 73 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a  as the second.**
6ec0: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 63 61 6c   argument to cal
6ed0: 6c 73 20 69 74 20 6d 61 6b 65 73 20 74 6f 20 74  ls it makes to t
6ee0: 68 65 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20 78  he xLock() and x
6ef0: 55 6e 6c 6f 63 6b 28 29 20 6d 65 74 68 6f 64 73  Unlock() methods
6f00: 0a 2a 2a 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74  .** of an [sqlit
6f10: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f  e3_io_methods] o
6f20: 62 6a 65 63 74 2e 0a 2a 2f 0a 23 64 65 66 69 6e  bject..*/.#defin
6f30: 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f  e SQLITE_LOCK_NO
6f40: 4e 45 20 20 20 20 20 20 20 20 20 20 30 0a 23 64  NE          0.#d
6f50: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43  efine SQLITE_LOC
6f60: 4b 5f 53 48 41 52 45 44 20 20 20 20 20 20 20 20  K_SHARED        
6f70: 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  1.#define SQLITE
6f80: 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44 20 20  _LOCK_RESERVED  
6f90: 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51      2.#define SQ
6fa0: 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e  LITE_LOCK_PENDIN
6fb0: 47 20 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e  G       3.#defin
6fc0: 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58  e SQLITE_LOCK_EX
6fd0: 43 4c 55 53 49 56 45 20 20 20 20 20 34 0a 0a 2f  CLUSIVE     4../
6fe0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53  *.** CAPI3REF: S
6ff0: 79 6e 63 68 72 6f 6e 69 7a 61 74 69 6f 6e 20 54  ynchronization T
7000: 79 70 65 20 46 6c 61 67 73 0a 2a 2a 0a 2a 2a 20  ype Flags.**.** 
7010: 57 68 65 6e 20 53 51 4c 69 74 65 20 69 6e 76 6f  When SQLite invo
7020: 6b 65 73 20 74 68 65 20 78 53 79 6e 63 28 29 20  kes the xSync() 
7030: 6d 65 74 68 6f 64 20 6f 66 20 61 6e 0a 2a 2a 20  method of an.** 
7040: 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68  [sqlite3_io_meth
7050: 6f 64 73 5d 20 6f 62 6a 65 63 74 20 69 74 20 75  ods] object it u
7060: 73 65 73 20 61 20 63 6f 6d 62 69 6e 61 74 69 6f  ses a combinatio
7070: 6e 20 6f 66 0a 2a 2a 20 74 68 65 73 65 20 69 6e  n of.** these in
7080: 74 65 67 65 72 20 76 61 6c 75 65 73 20 61 73 20  teger values as 
7090: 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  the second argum
70a0: 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20  ent..**.** When 
70b0: 74 68 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f  the SQLITE_SYNC_
70c0: 44 41 54 41 4f 4e 4c 59 20 66 6c 61 67 20 69 73  DATAONLY flag is
70d0: 20 75 73 65 64 2c 20 69 74 20 6d 65 61 6e 73 20   used, it means 
70e0: 74 68 61 74 20 74 68 65 0a 2a 2a 20 73 79 6e 63  that the.** sync
70f0: 20 6f 70 65 72 61 74 69 6f 6e 20 6f 6e 6c 79 20   operation only 
7100: 6e 65 65 64 73 20 74 6f 20 66 6c 75 73 68 20 64  needs to flush d
7110: 61 74 61 20 74 6f 20 6d 61 73 73 20 73 74 6f 72  ata to mass stor
7120: 61 67 65 2e 20 20 49 6e 6f 64 65 0a 2a 2a 20 69  age.  Inode.** i
7130: 6e 66 6f 72 6d 61 74 69 6f 6e 20 6e 65 65 64 20  nformation need 
7140: 6e 6f 74 20 62 65 20 66 6c 75 73 68 65 64 2e 20  not be flushed. 
7150: 49 66 20 74 68 65 20 6c 6f 77 65 72 20 66 6f 75  If the lower fou
7160: 72 20 62 69 74 73 20 6f 66 20 74 68 65 20 66 6c  r bits of the fl
7170: 61 67 0a 2a 2a 20 65 71 75 61 6c 20 53 51 4c 49  ag.** equal SQLI
7180: 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 2c 20  TE_SYNC_NORMAL, 
7190: 74 68 61 74 20 6d 65 61 6e 73 20 74 6f 20 75 73  that means to us
71a0: 65 20 6e 6f 72 6d 61 6c 20 66 73 79 6e 63 28 29  e normal fsync()
71b0: 20 73 65 6d 61 6e 74 69 63 73 2e 0a 2a 2a 20 49   semantics..** I
71c0: 66 20 74 68 65 20 6c 6f 77 65 72 20 66 6f 75 72  f the lower four
71d0: 20 62 69 74 73 20 65 71 75 61 6c 20 53 51 4c 49   bits equal SQLI
71e0: 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 2c 20 74 68  TE_SYNC_FULL, th
71f0: 61 74 20 6d 65 61 6e 73 0a 2a 2a 20 74 6f 20 75  at means.** to u
7200: 73 65 20 4d 61 63 20 4f 53 20 58 20 73 74 79 6c  se Mac OS X styl
7210: 65 20 66 75 6c 6c 73 79 6e 63 20 69 6e 73 74 65  e fullsync inste
7220: 61 64 20 6f 66 20 66 73 79 6e 63 28 29 2e 0a 2a  ad of fsync()..*
7230: 2a 0a 2a 2a 20 44 6f 20 6e 6f 74 20 63 6f 6e 66  *.** Do not conf
7240: 75 73 65 20 74 68 65 20 53 51 4c 49 54 45 5f 53  use the SQLITE_S
7250: 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53  YNC_NORMAL and S
7260: 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20  QLITE_SYNC_FULL 
7270: 66 6c 61 67 73 0a 2a 2a 20 77 69 74 68 20 74 68  flags.** with th
7280: 65 20 5b 50 52 41 47 4d 41 20 73 79 6e 63 68 72  e [PRAGMA synchr
7290: 6f 6e 6f 75 73 5d 3d 4e 4f 52 4d 41 4c 20 61 6e  onous]=NORMAL an
72a0: 64 20 5b 50 52 41 47 4d 41 20 73 79 6e 63 68 72  d [PRAGMA synchr
72b0: 6f 6e 6f 75 73 5d 3d 46 55 4c 4c 0a 2a 2a 20 73  onous]=FULL.** s
72c0: 65 74 74 69 6e 67 73 2e 20 20 54 68 65 20 5b 73  ettings.  The [s
72d0: 79 6e 63 68 72 6f 6e 6f 75 73 20 70 72 61 67 6d  ynchronous pragm
72e0: 61 5d 20 64 65 74 65 72 6d 69 6e 65 73 20 77 68  a] determines wh
72f0: 65 6e 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 0a  en calls to the.
7300: 2a 2a 20 78 53 79 6e 63 20 56 46 53 20 6d 65 74  ** xSync VFS met
7310: 68 6f 64 20 6f 63 63 75 72 20 61 6e 64 20 61 70  hod occur and ap
7320: 70 6c 69 65 73 20 75 6e 69 66 6f 72 6d 6c 79 20  plies uniformly 
7330: 61 63 72 6f 73 73 20 61 6c 6c 20 70 6c 61 74 66  across all platf
7340: 6f 72 6d 73 2e 0a 2a 2a 20 54 68 65 20 53 51 4c  orms..** The SQL
7350: 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20  ITE_SYNC_NORMAL 
7360: 61 6e 64 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f  and SQLITE_SYNC_
7370: 46 55 4c 4c 20 66 6c 61 67 73 20 64 65 74 65 72  FULL flags deter
7380: 6d 69 6e 65 20 68 6f 77 0a 2a 2a 20 65 6e 65 72  mine how.** ener
7390: 67 65 74 69 63 20 6f 72 20 72 69 67 6f 72 6f 75  getic or rigorou
73a0: 73 20 6f 72 20 66 6f 72 63 65 66 75 6c 20 74 68  s or forceful th
73b0: 65 20 73 79 6e 63 20 6f 70 65 72 61 74 69 6f 6e  e sync operation
73c0: 73 20 61 72 65 20 61 6e 64 0a 2a 2a 20 6f 6e 6c  s are and.** onl
73d0: 79 20 6d 61 6b 65 20 61 20 64 69 66 66 65 72 65  y make a differe
73e0: 6e 63 65 20 6f 6e 20 4d 61 63 20 4f 53 58 20 66  nce on Mac OSX f
73f0: 6f 72 20 74 68 65 20 64 65 66 61 75 6c 74 20 53  or the default S
7400: 51 4c 69 74 65 20 63 6f 64 65 2e 0a 2a 2a 20 28  QLite code..** (
7410: 54 68 69 72 64 2d 70 61 72 74 79 20 56 46 53 20  Third-party VFS 
7420: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
7430: 6d 69 67 68 74 20 61 6c 73 6f 20 6d 61 6b 65 20  might also make 
7440: 74 68 65 20 64 69 73 74 69 6e 63 74 69 6f 6e 0a  the distinction.
7450: 2a 2a 20 62 65 74 77 65 65 6e 20 53 51 4c 49 54  ** between SQLIT
7460: 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e  E_SYNC_NORMAL an
7470: 64 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55  d SQLITE_SYNC_FU
7480: 4c 4c 2c 20 62 75 74 20 61 6d 6f 6e 67 20 74 68  LL, but among th
7490: 65 0a 2a 2a 20 6f 70 65 72 61 74 69 6e 67 20 73  e.** operating s
74a0: 79 73 74 65 6d 73 20 6e 61 74 69 76 65 6c 79 20  ystems natively 
74b0: 73 75 70 70 6f 72 74 65 64 20 62 79 20 53 51 4c  supported by SQL
74c0: 69 74 65 2c 20 6f 6e 6c 79 20 4d 61 63 20 4f 53  ite, only Mac OS
74d0: 58 0a 2a 2a 20 63 61 72 65 73 20 61 62 6f 75 74  X.** cares about
74e0: 20 74 68 65 20 64 69 66 66 65 72 65 6e 63 65 2e   the difference.
74f0: 29 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ).*/.#define SQL
7500: 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20  ITE_SYNC_NORMAL 
7510: 20 20 20 20 20 20 20 30 78 30 30 30 30 32 0a 23         0x00002.#
7520: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 59  define SQLITE_SY
7530: 4e 43 5f 46 55 4c 4c 20 20 20 20 20 20 20 20 20  NC_FULL         
7540: 20 30 78 30 30 30 30 33 0a 23 64 65 66 69 6e 65   0x00003.#define
7550: 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54   SQLITE_SYNC_DAT
7560: 41 4f 4e 4c 59 20 20 20 20 20 20 30 78 30 30 30  AONLY      0x000
7570: 31 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  10../*.** CAPI3R
7580: 45 46 3a 20 4f 53 20 49 6e 74 65 72 66 61 63 65  EF: OS Interface
7590: 20 4f 70 65 6e 20 46 69 6c 65 20 48 61 6e 64 6c   Open File Handl
75a0: 65 0a 2a 2a 0a 2a 2a 20 41 6e 20 5b 73 71 6c 69  e.**.** An [sqli
75b0: 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74  te3_file] object
75c0: 20 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20 6f   represents an o
75d0: 70 65 6e 20 66 69 6c 65 20 69 6e 20 74 68 65 20  pen file in the 
75e0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  .** [sqlite3_vfs
75f0: 20 7c 20 4f 53 20 69 6e 74 65 72 66 61 63 65 20   | OS interface 
7600: 6c 61 79 65 72 5d 2e 20 20 49 6e 64 69 76 69 64  layer].  Individ
7610: 75 61 6c 20 4f 53 20 69 6e 74 65 72 66 61 63 65  ual OS interface
7620: 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  .** implementati
7630: 6f 6e 73 20 77 69 6c 6c 0a 2a 2a 20 77 61 6e 74  ons will.** want
7640: 20 74 6f 20 73 75 62 63 6c 61 73 73 20 74 68 69   to subclass thi
7650: 73 20 6f 62 6a 65 63 74 20 62 79 20 61 70 70 65  s object by appe
7660: 6e 64 69 6e 67 20 61 64 64 69 74 69 6f 6e 61 6c  nding additional
7670: 20 66 69 65 6c 64 73 0a 2a 2a 20 66 6f 72 20 74   fields.** for t
7680: 68 65 69 72 20 6f 77 6e 20 75 73 65 2e 20 20 54  heir own use.  T
7690: 68 65 20 70 4d 65 74 68 6f 64 73 20 65 6e 74 72  he pMethods entr
76a0: 79 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  y is a pointer t
76b0: 6f 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  o an.** [sqlite3
76c0: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a  _io_methods] obj
76d0: 65 63 74 20 74 68 61 74 20 64 65 66 69 6e 65 73  ect that defines
76e0: 20 6d 65 74 68 6f 64 73 20 66 6f 72 20 70 65 72   methods for per
76f0: 66 6f 72 6d 69 6e 67 0a 2a 2a 20 49 2f 4f 20 6f  forming.** I/O o
7700: 70 65 72 61 74 69 6f 6e 73 20 6f 6e 20 74 68 65  perations on the
7710: 20 6f 70 65 6e 20 66 69 6c 65 2e 0a 2a 2f 0a 74   open file..*/.t
7720: 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71  ypedef struct sq
7730: 6c 69 74 65 33 5f 66 69 6c 65 20 73 71 6c 69 74  lite3_file sqlit
7740: 65 33 5f 66 69 6c 65 3b 0a 73 74 72 75 63 74 20  e3_file;.struct 
7750: 73 71 6c 69 74 65 33 5f 66 69 6c 65 20 7b 0a 20  sqlite3_file {. 
7760: 20 63 6f 6e 73 74 20 73 74 72 75 63 74 20 73 71   const struct sq
7770: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
7780: 20 2a 70 4d 65 74 68 6f 64 73 3b 20 20 2f 2a 20   *pMethods;  /* 
7790: 4d 65 74 68 6f 64 73 20 66 6f 72 20 61 6e 20 6f  Methods for an o
77a0: 70 65 6e 20 66 69 6c 65 20 2a 2f 0a 7d 3b 0a 0a  pen file */.};..
77b0: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
77c0: 4f 53 20 49 6e 74 65 72 66 61 63 65 20 46 69 6c  OS Interface Fil
77d0: 65 20 56 69 72 74 75 61 6c 20 4d 65 74 68 6f 64  e Virtual Method
77e0: 73 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 45  s Object.**.** E
77f0: 76 65 72 79 20 66 69 6c 65 20 6f 70 65 6e 65 64  very file opened
7800: 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33   by the [sqlite3
7810: 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 6d 65 74 68  _vfs.xOpen] meth
7820: 6f 64 20 70 6f 70 75 6c 61 74 65 73 20 61 6e 0a  od populates an.
7830: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  ** [sqlite3_file
7840: 5d 20 6f 62 6a 65 63 74 20 28 6f 72 2c 20 6d 6f  ] object (or, mo
7850: 72 65 20 63 6f 6d 6d 6f 6e 6c 79 2c 20 61 20 73  re commonly, a s
7860: 75 62 63 6c 61 73 73 20 6f 66 20 74 68 65 0a 2a  ubclass of the.*
7870: 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d  * [sqlite3_file]
7880: 20 6f 62 6a 65 63 74 29 20 77 69 74 68 20 61 20   object) with a 
7890: 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e  pointer to an in
78a0: 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f  stance of this o
78b0: 62 6a 65 63 74 2e 0a 2a 2a 20 54 68 69 73 20 6f  bject..** This o
78c0: 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74 68  bject defines th
78d0: 65 20 6d 65 74 68 6f 64 73 20 75 73 65 64 20 74  e methods used t
78e0: 6f 20 70 65 72 66 6f 72 6d 20 76 61 72 69 6f 75  o perform variou
78f0: 73 20 6f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 20  s operations.** 
7900: 61 67 61 69 6e 73 74 20 74 68 65 20 6f 70 65 6e  against the open
7910: 20 66 69 6c 65 20 72 65 70 72 65 73 65 6e 74 65   file represente
7920: 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65  d by the [sqlite
7930: 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 2e 0a  3_file] object..
7940: 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 5b 73 71  **.** If the [sq
7950: 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d  lite3_vfs.xOpen]
7960: 20 6d 65 74 68 6f 64 20 73 65 74 73 20 74 68 65   method sets the
7970: 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d   sqlite3_file.pM
7980: 65 74 68 6f 64 73 20 65 6c 65 6d 65 6e 74 20 0a  ethods element .
7990: 2a 2a 20 74 6f 20 61 20 6e 6f 6e 2d 4e 55 4c 4c  ** to a non-NULL
79a0: 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 74   pointer, then t
79b0: 68 65 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  he sqlite3_io_me
79c0: 74 68 6f 64 73 2e 78 43 6c 6f 73 65 20 6d 65 74  thods.xClose met
79d0: 68 6f 64 0a 2a 2a 20 6d 61 79 20 62 65 20 69 6e  hod.** may be in
79e0: 76 6f 6b 65 64 20 65 76 65 6e 20 69 66 20 74 68  voked even if th
79f0: 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78  e [sqlite3_vfs.x
7a00: 4f 70 65 6e 5d 20 72 65 70 6f 72 74 65 64 20 74  Open] reported t
7a10: 68 61 74 20 69 74 20 66 61 69 6c 65 64 2e 20 20  hat it failed.  
7a20: 54 68 65 0a 2a 2a 20 6f 6e 6c 79 20 77 61 79 20  The.** only way 
7a30: 74 6f 20 70 72 65 76 65 6e 74 20 61 20 63 61 6c  to prevent a cal
7a40: 6c 20 74 6f 20 78 43 6c 6f 73 65 20 66 6f 6c 6c  l to xClose foll
7a50: 6f 77 69 6e 67 20 61 20 66 61 69 6c 65 64 20 5b  owing a failed [
7a60: 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65  sqlite3_vfs.xOpe
7a70: 6e 5d 0a 2a 2a 20 69 73 20 66 6f 72 20 74 68 65  n].** is for the
7a80: 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f   [sqlite3_vfs.xO
7a90: 70 65 6e 5d 20 74 6f 20 73 65 74 20 74 68 65 20  pen] to set the 
7aa0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65  sqlite3_file.pMe
7ab0: 74 68 6f 64 73 20 65 6c 65 6d 65 6e 74 0a 2a 2a  thods element.**
7ac0: 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20   to NULL..**.** 
7ad0: 54 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65  The flags argume
7ae0: 6e 74 20 74 6f 20 78 53 79 6e 63 20 6d 61 79 20  nt to xSync may 
7af0: 62 65 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54  be one of [SQLIT
7b00: 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 5d 20 6f  E_SYNC_NORMAL] o
7b10: 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 53 59 4e  r.** [SQLITE_SYN
7b20: 43 5f 46 55 4c 4c 5d 2e 20 20 54 68 65 20 66 69  C_FULL].  The fi
7b30: 72 73 74 20 63 68 6f 69 63 65 20 69 73 20 74 68  rst choice is th
7b40: 65 20 6e 6f 72 6d 61 6c 20 66 73 79 6e 63 28 29  e normal fsync()
7b50: 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20  ..** The second 
7b60: 63 68 6f 69 63 65 20 69 73 20 61 20 4d 61 63 20  choice is a Mac 
7b70: 4f 53 20 58 20 73 74 79 6c 65 20 66 75 6c 6c 73  OS X style fulls
7b80: 79 6e 63 2e 20 20 54 68 65 20 5b 53 51 4c 49 54  ync.  The [SQLIT
7b90: 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 5d  E_SYNC_DATAONLY]
7ba0: 0a 2a 2a 20 66 6c 61 67 20 6d 61 79 20 62 65 20  .** flag may be 
7bb0: 4f 52 65 64 20 69 6e 20 74 6f 20 69 6e 64 69 63  ORed in to indic
7bc0: 61 74 65 20 74 68 61 74 20 6f 6e 6c 79 20 74 68  ate that only th
7bd0: 65 20 64 61 74 61 20 6f 66 20 74 68 65 20 66 69  e data of the fi
7be0: 6c 65 0a 2a 2a 20 61 6e 64 20 6e 6f 74 20 69 74  le.** and not it
7bf0: 73 20 69 6e 6f 64 65 20 6e 65 65 64 73 20 74 6f  s inode needs to
7c00: 20 62 65 20 73 79 6e 63 65 64 2e 0a 2a 2a 0a 2a   be synced..**.*
7c10: 2a 20 54 68 65 20 69 6e 74 65 67 65 72 20 76 61  * The integer va
7c20: 6c 75 65 73 20 74 6f 20 78 4c 6f 63 6b 28 29 20  lues to xLock() 
7c30: 61 6e 64 20 78 55 6e 6c 6f 63 6b 28 29 20 61 72  and xUnlock() ar
7c40: 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 3c 75 6c 3e  e one of.** <ul>
7c50: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
7c60: 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 0a 2a 2a 20  _LOCK_NONE],.** 
7c70: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43  <li> [SQLITE_LOC
7c80: 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 3c 6c  K_SHARED],.** <l
7c90: 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  i> [SQLITE_LOCK_
7ca0: 52 45 53 45 52 56 45 44 5d 2c 0a 2a 2a 20 3c 6c  RESERVED],.** <l
7cb0: 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  i> [SQLITE_LOCK_
7cc0: 50 45 4e 44 49 4e 47 5d 2c 20 6f 72 0a 2a 2a 20  PENDING], or.** 
7cd0: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43  <li> [SQLITE_LOC
7ce0: 4b 5f 45 58 43 4c 55 53 49 56 45 5d 2e 0a 2a 2a  K_EXCLUSIVE]..**
7cf0: 20 3c 2f 75 6c 3e 0a 2a 2a 20 78 4c 6f 63 6b 28   </ul>.** xLock(
7d00: 29 20 69 6e 63 72 65 61 73 65 73 20 74 68 65 20  ) increases the 
7d10: 6c 6f 63 6b 2e 20 78 55 6e 6c 6f 63 6b 28 29 20  lock. xUnlock() 
7d20: 64 65 63 72 65 61 73 65 73 20 74 68 65 20 6c 6f  decreases the lo
7d30: 63 6b 2e 0a 2a 2a 20 54 68 65 20 78 43 68 65 63  ck..** The xChec
7d40: 6b 52 65 73 65 72 76 65 64 4c 6f 63 6b 28 29 20  kReservedLock() 
7d50: 6d 65 74 68 6f 64 20 63 68 65 63 6b 73 20 77 68  method checks wh
7d60: 65 74 68 65 72 20 61 6e 79 20 64 61 74 61 62 61  ether any databa
7d70: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 0a 2a  se connection,.*
7d80: 2a 20 65 69 74 68 65 72 20 69 6e 20 74 68 69 73  * either in this
7d90: 20 70 72 6f 63 65 73 73 20 6f 72 20 69 6e 20 73   process or in s
7da0: 6f 6d 65 20 6f 74 68 65 72 20 70 72 6f 63 65 73  ome other proces
7db0: 73 2c 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20  s, is holding a 
7dc0: 52 45 53 45 52 56 45 44 2c 0a 2a 2a 20 50 45 4e  RESERVED,.** PEN
7dd0: 44 49 4e 47 2c 20 6f 72 20 45 58 43 4c 55 53 49  DING, or EXCLUSI
7de0: 56 45 20 6c 6f 63 6b 20 6f 6e 20 74 68 65 20 66  VE lock on the f
7df0: 69 6c 65 2e 20 20 49 74 20 72 65 74 75 72 6e 73  ile.  It returns
7e00: 20 74 72 75 65 0a 2a 2a 20 69 66 20 73 75 63 68   true.** if such
7e10: 20 61 20 6c 6f 63 6b 20 65 78 69 73 74 73 20 61   a lock exists a
7e20: 6e 64 20 66 61 6c 73 65 20 6f 74 68 65 72 77 69  nd false otherwi
7e30: 73 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 46  se..**.** The xF
7e40: 69 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d 65 74  ileControl() met
7e50: 68 6f 64 20 69 73 20 61 20 67 65 6e 65 72 69 63  hod is a generic
7e60: 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 20   interface that 
7e70: 61 6c 6c 6f 77 73 20 63 75 73 74 6f 6d 0a 2a 2a  allows custom.**
7e80: 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74   VFS implementat
7e90: 69 6f 6e 73 20 74 6f 20 64 69 72 65 63 74 6c 79  ions to directly
7ea0: 20 63 6f 6e 74 72 6f 6c 20 61 6e 20 6f 70 65 6e   control an open
7eb0: 20 66 69 6c 65 20 75 73 69 6e 67 20 74 68 65 0a   file using the.
7ec0: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  ** [sqlite3_file
7ed0: 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 69 6e 74 65  _control()] inte
7ee0: 72 66 61 63 65 2e 20 20 54 68 65 20 73 65 63 6f  rface.  The seco
7ef0: 6e 64 20 22 6f 70 22 20 61 72 67 75 6d 65 6e 74  nd "op" argument
7f00: 20 69 73 20 61 6e 0a 2a 2a 20 69 6e 74 65 67 65   is an.** intege
7f10: 72 20 6f 70 63 6f 64 65 2e 20 20 54 68 65 20 74  r opcode.  The t
7f20: 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73  hird argument is
7f30: 20 61 20 67 65 6e 65 72 69 63 20 70 6f 69 6e 74   a generic point
7f40: 65 72 20 69 6e 74 65 6e 64 65 64 20 74 6f 0a 2a  er intended to.*
7f50: 2a 20 70 6f 69 6e 74 20 74 6f 20 61 20 73 74 72  * point to a str
7f60: 75 63 74 75 72 65 20 74 68 61 74 20 6d 61 79 20  ucture that may 
7f70: 63 6f 6e 74 61 69 6e 20 61 72 67 75 6d 65 6e 74  contain argument
7f80: 73 20 6f 72 20 73 70 61 63 65 20 69 6e 20 77 68  s or space in wh
7f90: 69 63 68 20 74 6f 0a 2a 2a 20 77 72 69 74 65 20  ich to.** write 
7fa0: 72 65 74 75 72 6e 20 76 61 6c 75 65 73 2e 20 20  return values.  
7fb0: 50 6f 74 65 6e 74 69 61 6c 20 75 73 65 73 20 66  Potential uses f
7fc0: 6f 72 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 28  or xFileControl(
7fd0: 29 20 6d 69 67 68 74 20 62 65 0a 2a 2a 20 66 75  ) might be.** fu
7fe0: 6e 63 74 69 6f 6e 73 20 74 6f 20 65 6e 61 62 6c  nctions to enabl
7ff0: 65 20 62 6c 6f 63 6b 69 6e 67 20 6c 6f 63 6b 73  e blocking locks
8000: 20 77 69 74 68 20 74 69 6d 65 6f 75 74 73 2c 20   with timeouts, 
8010: 74 6f 20 63 68 61 6e 67 65 20 74 68 65 0a 2a 2a  to change the.**
8020: 20 6c 6f 63 6b 69 6e 67 20 73 74 72 61 74 65 67   locking strateg
8030: 79 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 74  y (for example t
8040: 6f 20 75 73 65 20 64 6f 74 2d 66 69 6c 65 20 6c  o use dot-file l
8050: 6f 63 6b 73 29 2c 20 74 6f 20 69 6e 71 75 69 72  ocks), to inquir
8060: 65 0a 2a 2a 20 61 62 6f 75 74 20 74 68 65 20 73  e.** about the s
8070: 74 61 74 75 73 20 6f 66 20 61 20 6c 6f 63 6b 2c  tatus of a lock,
8080: 20 6f 72 20 74 6f 20 62 72 65 61 6b 20 73 74 61   or to break sta
8090: 6c 65 20 6c 6f 63 6b 73 2e 20 20 54 68 65 20 53  le locks.  The S
80a0: 51 4c 69 74 65 0a 2a 2a 20 63 6f 72 65 20 72 65  QLite.** core re
80b0: 73 65 72 76 65 73 20 61 6c 6c 20 6f 70 63 6f 64  serves all opcod
80c0: 65 73 20 6c 65 73 73 20 74 68 61 6e 20 31 30 30  es less than 100
80d0: 20 66 6f 72 20 69 74 73 20 6f 77 6e 20 75 73 65   for its own use
80e0: 2e 0a 2a 2a 20 41 20 5b 66 69 6c 65 20 63 6f 6e  ..** A [file con
80f0: 74 72 6f 6c 20 6f 70 63 6f 64 65 73 20 7c 20 6c  trol opcodes | l
8100: 69 73 74 20 6f 66 20 6f 70 63 6f 64 65 73 5d 20  ist of opcodes] 
8110: 6c 65 73 73 20 74 68 61 6e 20 31 30 30 20 69 73  less than 100 is
8120: 20 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20 41   available..** A
8130: 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74  pplications that
8140: 20 64 65 66 69 6e 65 20 61 20 63 75 73 74 6f 6d   define a custom
8150: 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65   xFileControl me
8160: 74 68 6f 64 20 73 68 6f 75 6c 64 20 75 73 65 20  thod should use 
8170: 6f 70 63 6f 64 65 73 0a 2a 2a 20 67 72 65 61 74  opcodes.** great
8180: 65 72 20 74 68 61 6e 20 31 30 30 20 74 6f 20 61  er than 100 to a
8190: 76 6f 69 64 20 63 6f 6e 66 6c 69 63 74 73 2e 20  void conflicts. 
81a0: 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74   VFS implementat
81b0: 69 6f 6e 73 20 73 68 6f 75 6c 64 0a 2a 2a 20 72  ions should.** r
81c0: 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f  eturn [SQLITE_NO
81d0: 54 46 4f 55 4e 44 5d 20 66 6f 72 20 66 69 6c 65  TFOUND] for file
81e0: 20 63 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64 65 73   control opcodes
81f0: 20 74 68 61 74 20 74 68 65 79 20 64 6f 20 6e 6f   that they do no
8200: 74 0a 2a 2a 20 72 65 63 6f 67 6e 69 7a 65 2e 0a  t.** recognize..
8210: 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 65 63 74 6f  **.** The xSecto
8220: 72 53 69 7a 65 28 29 20 6d 65 74 68 6f 64 20 72  rSize() method r
8230: 65 74 75 72 6e 73 20 74 68 65 20 73 65 63 74 6f  eturns the secto
8240: 72 20 73 69 7a 65 20 6f 66 20 74 68 65 0a 2a 2a  r size of the.**
8250: 20 64 65 76 69 63 65 20 74 68 61 74 20 75 6e 64   device that und
8260: 65 72 6c 69 65 73 20 74 68 65 20 66 69 6c 65 2e  erlies the file.
8270: 20 20 54 68 65 20 73 65 63 74 6f 72 20 73 69 7a    The sector siz
8280: 65 20 69 73 20 74 68 65 0a 2a 2a 20 6d 69 6e 69  e is the.** mini
8290: 6d 75 6d 20 77 72 69 74 65 20 74 68 61 74 20 63  mum write that c
82a0: 61 6e 20 62 65 20 70 65 72 66 6f 72 6d 65 64 20  an be performed 
82b0: 77 69 74 68 6f 75 74 20 64 69 73 74 75 72 62 69  without disturbi
82c0: 6e 67 0a 2a 2a 20 6f 74 68 65 72 20 62 79 74 65  ng.** other byte
82d0: 73 20 69 6e 20 74 68 65 20 66 69 6c 65 2e 20 20  s in the file.  
82e0: 54 68 65 20 78 44 65 76 69 63 65 43 68 61 72 61  The xDeviceChara
82f0: 63 74 65 72 69 73 74 69 63 73 28 29 0a 2a 2a 20  cteristics().** 
8300: 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 61  method returns a
8310: 20 62 69 74 20 76 65 63 74 6f 72 20 64 65 73 63   bit vector desc
8320: 72 69 62 69 6e 67 20 62 65 68 61 76 69 6f 72 73  ribing behaviors
8330: 20 6f 66 20 74 68 65 0a 2a 2a 20 75 6e 64 65 72   of the.** under
8340: 6c 79 69 6e 67 20 64 65 76 69 63 65 3a 0a 2a 2a  lying device:.**
8350: 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <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 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  TOMIC].** <li> [
8380: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
8390: 4d 49 43 35 31 32 5d 0a 2a 2a 20 3c 6c 69 3e 20  MIC512].** <li> 
83a0: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54  [SQLITE_IOCAP_AT
83b0: 4f 4d 49 43 31 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20  OMIC1K].** <li> 
83c0: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54  [SQLITE_IOCAP_AT
83d0: 4f 4d 49 43 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20  OMIC2K].** <li> 
83e0: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54  [SQLITE_IOCAP_AT
83f0: 4f 4d 49 43 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20  OMIC4K].** <li> 
8400: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54  [SQLITE_IOCAP_AT
8410: 4f 4d 49 43 38 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20  OMIC8K].** <li> 
8420: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54  [SQLITE_IOCAP_AT
8430: 4f 4d 49 43 31 36 4b 5d 0a 2a 2a 20 3c 6c 69 3e  OMIC16K].** <li>
8440: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
8450: 54 4f 4d 49 43 33 32 4b 5d 0a 2a 2a 20 3c 6c 69  TOMIC32K].** <li
8460: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
8470: 41 54 4f 4d 49 43 36 34 4b 5d 0a 2a 2a 20 3c 6c  ATOMIC64K].** <l
8480: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  i> [SQLITE_IOCAP
8490: 5f 53 41 46 45 5f 41 50 50 45 4e 44 5d 0a 2a 2a  _SAFE_APPEND].**
84a0: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f   <li> [SQLITE_IO
84b0: 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 5d 0a  CAP_SEQUENTIAL].
84c0: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
84d0: 49 4f 43 41 50 5f 55 4e 44 45 4c 45 54 41 42 4c  IOCAP_UNDELETABL
84e0: 45 5f 57 48 45 4e 5f 4f 50 45 4e 5d 0a 2a 2a 20  E_WHEN_OPEN].** 
84f0: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43  <li> [SQLITE_IOC
8500: 41 50 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45  AP_POWERSAFE_OVE
8510: 52 57 52 49 54 45 5d 0a 2a 2a 20 3c 6c 69 3e 20  RWRITE].** <li> 
8520: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 49 4d  [SQLITE_IOCAP_IM
8530: 4d 55 54 41 42 4c 45 5d 0a 2a 2a 20 3c 2f 75 6c  MUTABLE].** </ul
8540: 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49  >.**.** The SQLI
8550: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20  TE_IOCAP_ATOMIC 
8560: 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74  property means t
8570: 68 61 74 20 61 6c 6c 20 77 72 69 74 65 73 20 6f  hat all writes o
8580: 66 0a 2a 2a 20 61 6e 79 20 73 69 7a 65 20 61 72  f.** any size ar
8590: 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53  e atomic.  The S
85a0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
85b0: 49 43 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a 20  ICnnn values.** 
85c0: 6d 65 61 6e 20 74 68 61 74 20 77 72 69 74 65 73  mean that writes
85d0: 20 6f 66 20 62 6c 6f 63 6b 73 20 74 68 61 74 20   of blocks that 
85e0: 61 72 65 20 6e 6e 6e 20 62 79 74 65 73 20 69 6e  are nnn bytes in
85f0: 20 73 69 7a 65 20 61 6e 64 0a 2a 2a 20 61 72 65   size and.** are
8600: 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 61   aligned to an a
8610: 64 64 72 65 73 73 20 77 68 69 63 68 20 69 73 20  ddress which is 
8620: 61 6e 20 69 6e 74 65 67 65 72 20 6d 75 6c 74 69  an integer multi
8630: 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 72  ple of.** nnn ar
8640: 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53  e atomic.  The S
8650: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45  QLITE_IOCAP_SAFE
8660: 5f 41 50 50 45 4e 44 20 76 61 6c 75 65 20 6d 65  _APPEND value me
8670: 61 6e 73 0a 2a 2a 20 74 68 61 74 20 77 68 65 6e  ans.** that when
8680: 20 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 65   data is appende
8690: 64 20 74 6f 20 61 20 66 69 6c 65 2c 20 74 68 65  d to a file, the
86a0: 20 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 65   data is appende
86b0: 64 0a 2a 2a 20 66 69 72 73 74 20 74 68 65 6e 20  d.** first then 
86c0: 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20  the size of the 
86d0: 66 69 6c 65 20 69 73 20 65 78 74 65 6e 64 65 64  file is extended
86e0: 2c 20 6e 65 76 65 72 20 74 68 65 20 6f 74 68 65  , never the othe
86f0: 72 0a 2a 2a 20 77 61 79 20 61 72 6f 75 6e 64 2e  r.** way around.
8700: 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43    The SQLITE_IOC
8710: 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 70 72  AP_SEQUENTIAL pr
8720: 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61  operty means tha
8730: 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  t.** information
8740: 20 69 73 20 77 72 69 74 74 65 6e 20 74 6f 20 64   is written to d
8750: 69 73 6b 20 69 6e 20 74 68 65 20 73 61 6d 65 20  isk in the same 
8760: 6f 72 64 65 72 20 61 73 20 63 61 6c 6c 73 0a 2a  order as calls.*
8770: 2a 20 74 6f 20 78 57 72 69 74 65 28 29 2e 0a 2a  * to xWrite()..*
8780: 2a 0a 2a 2a 20 49 66 20 78 52 65 61 64 28 29 20  *.** If xRead() 
8790: 72 65 74 75 72 6e 73 20 53 51 4c 49 54 45 5f 49  returns SQLITE_I
87a0: 4f 45 52 52 5f 53 48 4f 52 54 5f 52 45 41 44 20  OERR_SHORT_READ 
87b0: 69 74 20 6d 75 73 74 20 61 6c 73 6f 20 66 69 6c  it must also fil
87c0: 6c 0a 2a 2a 20 69 6e 20 74 68 65 20 75 6e 72 65  l.** in the unre
87d0: 61 64 20 70 6f 72 74 69 6f 6e 73 20 6f 66 20 74  ad portions of t
87e0: 68 65 20 62 75 66 66 65 72 20 77 69 74 68 20 7a  he buffer with z
87f0: 65 72 6f 73 2e 20 20 41 20 56 46 53 20 74 68 61  eros.  A VFS tha
8800: 74 0a 2a 2a 20 66 61 69 6c 73 20 74 6f 20 7a 65  t.** fails to ze
8810: 72 6f 2d 66 69 6c 6c 20 73 68 6f 72 74 20 72 65  ro-fill short re
8820: 61 64 73 20 6d 69 67 68 74 20 73 65 65 6d 20 74  ads might seem t
8830: 6f 20 77 6f 72 6b 2e 20 20 48 6f 77 65 76 65 72  o work.  However
8840: 2c 0a 2a 2a 20 66 61 69 6c 75 72 65 20 74 6f 20  ,.** failure to 
8850: 7a 65 72 6f 2d 66 69 6c 6c 20 73 68 6f 72 74 20  zero-fill short 
8860: 72 65 61 64 73 20 77 69 6c 6c 20 65 76 65 6e 74  reads will event
8870: 75 61 6c 6c 79 20 6c 65 61 64 20 74 6f 0a 2a 2a  ually lead to.**
8880: 20 64 61 74 61 62 61 73 65 20 63 6f 72 72 75 70   database corrup
8890: 74 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 65 64 65 66  tion..*/.typedef
88a0: 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
88b0: 69 6f 5f 6d 65 74 68 6f 64 73 20 73 71 6c 69 74  io_methods sqlit
88c0: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 3b 0a 73  e3_io_methods;.s
88d0: 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6f  truct sqlite3_io
88e0: 5f 6d 65 74 68 6f 64 73 20 7b 0a 20 20 69 6e 74  _methods {.  int
88f0: 20 69 56 65 72 73 69 6f 6e 3b 0a 20 20 69 6e 74   iVersion;.  int
8900: 20 28 2a 78 43 6c 6f 73 65 29 28 73 71 6c 69 74   (*xClose)(sqlit
8910: 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74  e3_file*);.  int
8920: 20 28 2a 78 52 65 61 64 29 28 73 71 6c 69 74 65   (*xRead)(sqlite
8930: 33 5f 66 69 6c 65 2a 2c 20 76 6f 69 64 2a 2c 20  3_file*, void*, 
8940: 69 6e 74 20 69 41 6d 74 2c 20 73 71 6c 69 74 65  int iAmt, sqlite
8950: 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 29 3b 0a  3_int64 iOfst);.
8960: 20 20 69 6e 74 20 28 2a 78 57 72 69 74 65 29 28    int (*xWrite)(
8970: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 63  sqlite3_file*, c
8980: 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 20  onst void*, int 
8990: 69 41 6d 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e  iAmt, sqlite3_in
89a0: 74 36 34 20 69 4f 66 73 74 29 3b 0a 20 20 69 6e  t64 iOfst);.  in
89b0: 74 20 28 2a 78 54 72 75 6e 63 61 74 65 29 28 73  t (*xTruncate)(s
89c0: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71  qlite3_file*, sq
89d0: 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 69 7a 65  lite3_int64 size
89e0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 79 6e 63  );.  int (*xSync
89f0: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
8a00: 20 69 6e 74 20 66 6c 61 67 73 29 3b 0a 20 20 69   int flags);.  i
8a10: 6e 74 20 28 2a 78 46 69 6c 65 53 69 7a 65 29 28  nt (*xFileSize)(
8a20: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73  sqlite3_file*, s
8a30: 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a 70 53  qlite3_int64 *pS
8a40: 69 7a 65 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4c  ize);.  int (*xL
8a50: 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ock)(sqlite3_fil
8a60: 65 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20  e*, int);.  int 
8a70: 28 2a 78 55 6e 6c 6f 63 6b 29 28 73 71 6c 69 74  (*xUnlock)(sqlit
8a80: 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a  e3_file*, int);.
8a90: 20 20 69 6e 74 20 28 2a 78 43 68 65 63 6b 52 65    int (*xCheckRe
8aa0: 73 65 72 76 65 64 4c 6f 63 6b 29 28 73 71 6c 69  servedLock)(sqli
8ab0: 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 2a  te3_file*, int *
8ac0: 70 52 65 73 4f 75 74 29 3b 0a 20 20 69 6e 74 20  pResOut);.  int 
8ad0: 28 2a 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 29 28  (*xFileControl)(
8ae0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69  sqlite3_file*, i
8af0: 6e 74 20 6f 70 2c 20 76 6f 69 64 20 2a 70 41 72  nt op, void *pAr
8b00: 67 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 65 63  g);.  int (*xSec
8b10: 74 6f 72 53 69 7a 65 29 28 73 71 6c 69 74 65 33  torSize)(sqlite3
8b20: 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28  _file*);.  int (
8b30: 2a 78 44 65 76 69 63 65 43 68 61 72 61 63 74 65  *xDeviceCharacte
8b40: 72 69 73 74 69 63 73 29 28 73 71 6c 69 74 65 33  ristics)(sqlite3
8b50: 5f 66 69 6c 65 2a 29 3b 0a 20 20 2f 2a 20 4d 65  _file*);.  /* Me
8b60: 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20  thods above are 
8b70: 76 61 6c 69 64 20 66 6f 72 20 76 65 72 73 69 6f  valid for versio
8b80: 6e 20 31 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78  n 1 */.  int (*x
8b90: 53 68 6d 4d 61 70 29 28 73 71 6c 69 74 65 33 5f  ShmMap)(sqlite3_
8ba0: 66 69 6c 65 2a 2c 20 69 6e 74 20 69 50 67 2c 20  file*, int iPg, 
8bb0: 69 6e 74 20 70 67 73 7a 2c 20 69 6e 74 2c 20 76  int pgsz, int, v
8bc0: 6f 69 64 20 76 6f 6c 61 74 69 6c 65 2a 2a 29 3b  oid volatile**);
8bd0: 0a 20 20 69 6e 74 20 28 2a 78 53 68 6d 4c 6f 63  .  int (*xShmLoc
8be0: 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  k)(sqlite3_file*
8bf0: 2c 20 69 6e 74 20 6f 66 66 73 65 74 2c 20 69 6e  , int offset, in
8c00: 74 20 6e 2c 20 69 6e 74 20 66 6c 61 67 73 29 3b  t n, int flags);
8c10: 0a 20 20 76 6f 69 64 20 28 2a 78 53 68 6d 42 61  .  void (*xShmBa
8c20: 72 72 69 65 72 29 28 73 71 6c 69 74 65 33 5f 66  rrier)(sqlite3_f
8c30: 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78  ile*);.  int (*x
8c40: 53 68 6d 55 6e 6d 61 70 29 28 73 71 6c 69 74 65  ShmUnmap)(sqlite
8c50: 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 64 65 6c  3_file*, int del
8c60: 65 74 65 46 6c 61 67 29 3b 0a 20 20 2f 2a 20 4d  eteFlag);.  /* M
8c70: 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65  ethods above are
8c80: 20 76 61 6c 69 64 20 66 6f 72 20 76 65 72 73 69   valid for versi
8c90: 6f 6e 20 32 20 2a 2f 0a 20 20 69 6e 74 20 28 2a  on 2 */.  int (*
8ca0: 78 46 65 74 63 68 29 28 73 71 6c 69 74 65 33 5f  xFetch)(sqlite3_
8cb0: 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69  file*, sqlite3_i
8cc0: 6e 74 36 34 20 69 4f 66 73 74 2c 20 69 6e 74 20  nt64 iOfst, int 
8cd0: 69 41 6d 74 2c 20 76 6f 69 64 20 2a 2a 70 70 29  iAmt, void **pp)
8ce0: 3b 0a 20 20 69 6e 74 20 28 2a 78 55 6e 66 65 74  ;.  int (*xUnfet
8cf0: 63 68 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ch)(sqlite3_file
8d00: 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  *, sqlite3_int64
8d10: 20 69 4f 66 73 74 2c 20 76 6f 69 64 20 2a 70 29   iOfst, void *p)
8d20: 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61  ;.  /* Methods a
8d30: 62 6f 76 65 20 61 72 65 20 76 61 6c 69 64 20 66  bove are valid f
8d40: 6f 72 20 76 65 72 73 69 6f 6e 20 33 20 2a 2f 0a  or version 3 */.
8d50: 20 20 2f 2a 20 41 64 64 69 74 69 6f 6e 61 6c 20    /* Additional 
8d60: 6d 65 74 68 6f 64 73 20 6d 61 79 20 62 65 20 61  methods may be a
8d70: 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72  dded in future r
8d80: 65 6c 65 61 73 65 73 20 2a 2f 0a 7d 3b 0a 0a 2f  eleases */.};../
8d90: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53  *.** CAPI3REF: S
8da0: 74 61 6e 64 61 72 64 20 46 69 6c 65 20 43 6f 6e  tandard File Con
8db0: 74 72 6f 6c 20 4f 70 63 6f 64 65 73 0a 2a 2a 20  trol Opcodes.** 
8dc0: 4b 45 59 57 4f 52 44 53 3a 20 7b 66 69 6c 65 20  KEYWORDS: {file 
8dd0: 63 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64 65 73 7d  control opcodes}
8de0: 20 7b 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f   {file control o
8df0: 70 63 6f 64 65 7d 0a 2a 2a 0a 2a 2a 20 54 68 65  pcode}.**.** The
8e00: 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74  se integer const
8e10: 61 6e 74 73 20 61 72 65 20 6f 70 63 6f 64 65 73  ants are opcodes
8e20: 20 66 6f 72 20 74 68 65 20 78 46 69 6c 65 43 6f   for the xFileCo
8e30: 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 0a 2a 2a 20  ntrol method.** 
8e40: 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
8e50: 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65  io_methods] obje
8e60: 63 74 20 61 6e 64 20 66 6f 72 20 74 68 65 20 5b  ct and for the [
8e70: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e  sqlite3_file_con
8e80: 74 72 6f 6c 28 29 5d 0a 2a 2a 20 69 6e 74 65 72  trol()].** inter
8e90: 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  face..**.** <ul>
8ea0: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
8eb0: 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45  _FCNTL_LOCKSTATE
8ec0: 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54  ]].** The [SQLIT
8ed0: 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54  E_FCNTL_LOCKSTAT
8ee0: 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65  E] opcode is use
8ef0: 64 20 66 6f 72 20 64 65 62 75 67 67 69 6e 67 2e  d for debugging.
8f00: 20 20 54 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65    This.** opcode
8f10: 20 63 61 75 73 65 73 20 74 68 65 20 78 46 69 6c   causes the xFil
8f20: 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20  eControl method 
8f30: 74 6f 20 77 72 69 74 65 20 74 68 65 20 63 75 72  to write the cur
8f40: 72 65 6e 74 20 73 74 61 74 65 20 6f 66 0a 2a 2a  rent state of.**
8f50: 20 74 68 65 20 6c 6f 63 6b 20 28 6f 6e 65 20 6f   the lock (one o
8f60: 66 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e  f [SQLITE_LOCK_N
8f70: 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f  ONE], [SQLITE_LO
8f80: 43 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 5b  CK_SHARED],.** [
8f90: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45  SQLITE_LOCK_RESE
8fa0: 52 56 45 44 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c  RVED], [SQLITE_L
8fb0: 4f 43 4b 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f 72  OCK_PENDING], or
8fc0: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58   [SQLITE_LOCK_EX
8fd0: 43 4c 55 53 49 56 45 5d 29 0a 2a 2a 20 69 6e 74  CLUSIVE]).** int
8fe0: 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 74 68 61  o an integer tha
8ff0: 74 20 74 68 65 20 70 41 72 67 20 61 72 67 75 6d  t the pArg argum
9000: 65 6e 74 20 70 6f 69 6e 74 73 20 74 6f 2e 20 54  ent points to. T
9010: 68 69 73 20 63 61 70 61 62 69 6c 69 74 79 0a 2a  his capability.*
9020: 2a 20 69 73 20 75 73 65 64 20 64 75 72 69 6e 67  * is used during
9030: 20 74 65 73 74 69 6e 67 20 61 6e 64 20 69 73 20   testing and is 
9040: 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 77  only available w
9050: 68 65 6e 20 74 68 65 20 53 51 4c 49 54 45 5f 54  hen the SQLITE_T
9060: 45 53 54 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74  EST.** compile-t
9070: 69 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20 75 73  ime option is us
9080: 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  ed..**.** <li>[[
9090: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a  SQLITE_FCNTL_SIZ
90a0: 45 5f 48 49 4e 54 5d 5d 0a 2a 2a 20 54 68 65 20  E_HINT]].** The 
90b0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49  [SQLITE_FCNTL_SI
90c0: 5a 45 5f 48 49 4e 54 5d 20 6f 70 63 6f 64 65 20  ZE_HINT] opcode 
90d0: 69 73 20 75 73 65 64 20 62 79 20 53 51 4c 69 74  is used by SQLit
90e0: 65 20 74 6f 20 67 69 76 65 20 74 68 65 20 56 46  e to give the VF
90f0: 53 0a 2a 2a 20 6c 61 79 65 72 20 61 20 68 69 6e  S.** layer a hin
9100: 74 20 6f 66 20 68 6f 77 20 6c 61 72 67 65 20 74  t of how large t
9110: 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
9120: 20 77 69 6c 6c 20 67 72 6f 77 20 74 6f 20 62 65   will grow to be
9130: 20 64 75 72 69 6e 67 20 74 68 65 0a 2a 2a 20 63   during the.** c
9140: 75 72 72 65 6e 74 20 74 72 61 6e 73 61 63 74 69  urrent transacti
9150: 6f 6e 2e 20 20 54 68 69 73 20 68 69 6e 74 20 69  on.  This hint i
9160: 73 20 6e 6f 74 20 67 75 61 72 61 6e 74 65 65 64  s not guaranteed
9170: 20 74 6f 20 62 65 20 61 63 63 75 72 61 74 65 20   to be accurate 
9180: 62 75 74 20 69 74 0a 2a 2a 20 69 73 20 6f 66 74  but it.** is oft
9190: 65 6e 20 63 6c 6f 73 65 2e 20 20 54 68 65 20 75  en close.  The u
91a0: 6e 64 65 72 6c 79 69 6e 67 20 56 46 53 20 6d 69  nderlying VFS mi
91b0: 67 68 74 20 63 68 6f 6f 73 65 20 74 6f 20 70 72  ght choose to pr
91c0: 65 61 6c 6c 6f 63 61 74 65 20 64 61 74 61 62 61  eallocate databa
91d0: 73 65 0a 2a 2a 20 66 69 6c 65 20 73 70 61 63 65  se.** file space
91e0: 20 62 61 73 65 64 20 6f 6e 20 74 68 69 73 20 68   based on this h
91f0: 69 6e 74 20 69 6e 20 6f 72 64 65 72 20 74 6f 20  int in order to 
9200: 68 65 6c 70 20 77 72 69 74 65 73 20 74 6f 20 74  help writes to t
9210: 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 66  he database.** f
9220: 69 6c 65 20 72 75 6e 20 66 61 73 74 65 72 2e 0a  ile run faster..
9230: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
9240: 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53  TE_FCNTL_CHUNK_S
9250: 49 5a 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51  IZE]].** The [SQ
9260: 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b  LITE_FCNTL_CHUNK
9270: 5f 53 49 5a 45 5d 20 6f 70 63 6f 64 65 20 69 73  _SIZE] opcode is
9280: 20 75 73 65 64 20 74 6f 20 72 65 71 75 65 73 74   used to request
9290: 20 74 68 61 74 20 74 68 65 20 56 46 53 0a 2a 2a   that the VFS.**
92a0: 20 65 78 74 65 6e 64 73 20 61 6e 64 20 74 72 75   extends and tru
92b0: 6e 63 61 74 65 73 20 74 68 65 20 64 61 74 61 62  ncates the datab
92c0: 61 73 65 20 66 69 6c 65 20 69 6e 20 63 68 75 6e  ase file in chun
92d0: 6b 73 20 6f 66 20 61 20 73 69 7a 65 20 73 70 65  ks of a size spe
92e0: 63 69 66 69 65 64 0a 2a 2a 20 62 79 20 74 68 65  cified.** by the
92f0: 20 75 73 65 72 2e 20 54 68 65 20 66 6f 75 72 74   user. The fourt
9300: 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73  h argument to [s
9310: 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74  qlite3_file_cont
9320: 72 6f 6c 28 29 5d 20 73 68 6f 75 6c 64 20 0a 2a  rol()] should .*
9330: 2a 20 70 6f 69 6e 74 20 74 6f 20 61 6e 20 69 6e  * point to an in
9340: 74 65 67 65 72 20 28 74 79 70 65 20 69 6e 74 29  teger (type int)
9350: 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20   containing the 
9360: 6e 65 77 20 63 68 75 6e 6b 2d 73 69 7a 65 20 74  new chunk-size t
9370: 6f 20 75 73 65 0a 2a 2a 20 66 6f 72 20 74 68 65  o use.** for the
9380: 20 6e 6f 6d 69 6e 61 74 65 64 20 64 61 74 61 62   nominated datab
9390: 61 73 65 2e 20 41 6c 6c 6f 63 61 74 69 6e 67 20  ase. Allocating 
93a0: 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 73 70  database file sp
93b0: 61 63 65 20 69 6e 20 6c 61 72 67 65 0a 2a 2a 20  ace in large.** 
93c0: 63 68 75 6e 6b 73 20 28 73 61 79 20 31 4d 42 20  chunks (say 1MB 
93d0: 61 74 20 61 20 74 69 6d 65 29 2c 20 6d 61 79 20  at a time), may 
93e0: 72 65 64 75 63 65 20 66 69 6c 65 2d 73 79 73 74  reduce file-syst
93f0: 65 6d 20 66 72 61 67 6d 65 6e 74 61 74 69 6f 6e  em fragmentation
9400: 20 61 6e 64 0a 2a 2a 20 69 6d 70 72 6f 76 65 20   and.** improve 
9410: 70 65 72 66 6f 72 6d 61 6e 63 65 20 6f 6e 20 73  performance on s
9420: 6f 6d 65 20 73 79 73 74 65 6d 73 2e 0a 2a 2a 0a  ome systems..**.
9430: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
9440: 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54  FCNTL_FILE_POINT
9450: 45 52 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  ER]].** The [SQL
9460: 49 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50  ITE_FCNTL_FILE_P
9470: 4f 49 4e 54 45 52 5d 20 6f 70 63 6f 64 65 20 69  OINTER] opcode i
9480: 73 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e  s used to obtain
9490: 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f   a pointer.** to
94a0: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69   the [sqlite3_fi
94b0: 6c 65 5d 20 6f 62 6a 65 63 74 20 61 73 73 6f 63  le] object assoc
94c0: 69 61 74 65 64 20 77 69 74 68 20 61 20 70 61 72  iated with a par
94d0: 74 69 63 75 6c 61 72 20 64 61 74 61 62 61 73 65  ticular database
94e0: 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20  .** connection. 
94f0: 20 53 65 65 20 61 6c 73 6f 20 5b 53 51 4c 49 54   See also [SQLIT
9500: 45 5f 46 43 4e 54 4c 5f 4a 4f 55 52 4e 41 4c 5f  E_FCNTL_JOURNAL_
9510: 50 4f 49 4e 54 45 52 5d 2e 0a 2a 2a 0a 2a 2a 20  POINTER]..**.** 
9520: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e  <li>[[SQLITE_FCN
9530: 54 4c 5f 4a 4f 55 52 4e 41 4c 5f 50 4f 49 4e 54  TL_JOURNAL_POINT
9540: 45 52 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  ER]].** The [SQL
9550: 49 54 45 5f 46 43 4e 54 4c 5f 4a 4f 55 52 4e 41  ITE_FCNTL_JOURNA
9560: 4c 5f 50 4f 49 4e 54 45 52 5d 20 6f 70 63 6f 64  L_POINTER] opcod
9570: 65 20 69 73 20 75 73 65 64 20 74 6f 20 6f 62 74  e is used to obt
9580: 61 69 6e 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a  ain a pointer.**
9590: 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
95a0: 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 61 73  _file] object as
95b0: 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68  sociated with th
95c0: 65 20 6a 6f 75 72 6e 61 6c 20 66 69 6c 65 20 28  e journal file (
95d0: 65 69 74 68 65 72 0a 2a 2a 20 74 68 65 20 5b 72  either.** the [r
95e0: 6f 6c 6c 62 61 63 6b 20 6a 6f 75 72 6e 61 6c 5d  ollback journal]
95f0: 20 6f 72 20 74 68 65 20 5b 77 72 69 74 65 2d 61   or the [write-a
9600: 68 65 61 64 20 6c 6f 67 5d 29 20 66 6f 72 20 61  head log]) for a
9610: 20 70 61 72 74 69 63 75 6c 61 72 20 64 61 74 61   particular data
9620: 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69  base.** connecti
9630: 6f 6e 2e 20 20 53 65 65 20 61 6c 73 6f 20 5b 53  on.  See also [S
9640: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45  QLITE_FCNTL_FILE
9650: 5f 50 4f 49 4e 54 45 52 5d 2e 0a 2a 2a 0a 2a 2a  _POINTER]..**.**
9660: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
9670: 4e 54 4c 5f 53 59 4e 43 5f 4f 4d 49 54 54 45 44  NTL_SYNC_OMITTED
9680: 5d 5d 0a 2a 2a 20 4e 6f 20 6c 6f 6e 67 65 72 20  ]].** No longer 
9690: 69 6e 20 75 73 65 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  in use..**.** <l
96a0: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
96b0: 5f 53 59 4e 43 5d 5d 0a 2a 2a 20 54 68 65 20 5b  _SYNC]].** The [
96c0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e  SQLITE_FCNTL_SYN
96d0: 43 5d 20 6f 70 63 6f 64 65 20 69 73 20 67 65 6e  C] opcode is gen
96e0: 65 72 61 74 65 64 20 69 6e 74 65 72 6e 61 6c 6c  erated internall
96f0: 79 20 62 79 20 53 51 4c 69 74 65 20 61 6e 64 0a  y by SQLite and.
9700: 2a 2a 20 73 65 6e 74 20 74 6f 20 74 68 65 20 56  ** sent to the V
9710: 46 53 20 69 6d 6d 65 64 69 61 74 65 6c 79 20 62  FS immediately b
9720: 65 66 6f 72 65 20 74 68 65 20 78 53 79 6e 63 20  efore the xSync 
9730: 6d 65 74 68 6f 64 20 69 73 20 69 6e 76 6f 6b 65  method is invoke
9740: 64 20 6f 6e 20 61 0a 2a 2a 20 64 61 74 61 62 61  d on a.** databa
9750: 73 65 20 66 69 6c 65 20 64 65 73 63 72 69 70 74  se file descript
9760: 6f 72 2e 20 4f 72 2c 20 69 66 20 74 68 65 20 78  or. Or, if the x
9770: 53 79 6e 63 20 6d 65 74 68 6f 64 20 69 73 20 6e  Sync method is n
9780: 6f 74 20 69 6e 76 6f 6b 65 64 20 0a 2a 2a 20 62  ot invoked .** b
9790: 65 63 61 75 73 65 20 74 68 65 20 75 73 65 72 20  ecause the user 
97a0: 68 61 73 20 63 6f 6e 66 69 67 75 72 65 64 20 53  has configured S
97b0: 51 4c 69 74 65 20 77 69 74 68 20 0a 2a 2a 20 5b  QLite with .** [
97c0: 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f  PRAGMA synchrono
97d0: 75 73 20 7c 20 50 52 41 47 4d 41 20 73 79 6e 63  us | PRAGMA sync
97e0: 68 72 6f 6e 6f 75 73 3d 4f 46 46 5d 20 69 74 20  hronous=OFF] it 
97f0: 69 73 20 69 6e 76 6f 6b 65 64 20 69 6e 20 70 6c  is invoked in pl
9800: 61 63 65 20 0a 2a 2a 20 6f 66 20 74 68 65 20 78  ace .** of the x
9810: 53 79 6e 63 20 6d 65 74 68 6f 64 2e 20 49 6e 20  Sync method. In 
9820: 6d 6f 73 74 20 63 61 73 65 73 2c 20 74 68 65 20  most cases, the 
9830: 70 6f 69 6e 74 65 72 20 61 72 67 75 6d 65 6e 74  pointer argument
9840: 20 70 61 73 73 65 64 20 77 69 74 68 0a 2a 2a 20   passed with.** 
9850: 74 68 69 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f  this file-contro
9860: 6c 20 69 73 20 4e 55 4c 4c 2e 20 48 6f 77 65 76  l is NULL. Howev
9870: 65 72 2c 20 69 66 20 74 68 65 20 64 61 74 61 62  er, if the datab
9880: 61 73 65 20 66 69 6c 65 20 69 73 20 62 65 69 6e  ase file is bein
9890: 67 20 73 79 6e 63 65 64 0a 2a 2a 20 61 73 20 70  g synced.** as p
98a0: 61 72 74 20 6f 66 20 61 20 6d 75 6c 74 69 2d 64  art of a multi-d
98b0: 61 74 61 62 61 73 65 20 63 6f 6d 6d 69 74 2c 20  atabase commit, 
98c0: 74 68 65 20 61 72 67 75 6d 65 6e 74 20 70 6f 69  the argument poi
98d0: 6e 74 73 20 74 6f 20 61 20 6e 75 6c 2d 74 65 72  nts to a nul-ter
98e0: 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e  minated.** strin
98f0: 67 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65  g containing the
9900: 20 74 72 61 6e 73 61 63 74 69 6f 6e 73 20 6d 61   transactions ma
9910: 73 74 65 72 2d 6a 6f 75 72 6e 61 6c 20 66 69 6c  ster-journal fil
9920: 65 20 6e 61 6d 65 2e 20 56 46 53 65 73 20 74 68  e name. VFSes th
9930: 61 74 20 0a 2a 2a 20 64 6f 20 6e 6f 74 20 6e 65  at .** do not ne
9940: 65 64 20 74 68 69 73 20 73 69 67 6e 61 6c 20 73  ed this signal s
9950: 68 6f 75 6c 64 20 73 69 6c 65 6e 74 6c 79 20 69  hould silently i
9960: 67 6e 6f 72 65 20 74 68 69 73 20 6f 70 63 6f 64  gnore this opcod
9970: 65 2e 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20  e. Applications 
9980: 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e 6f 74 20 63  .** should not c
9990: 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  all [sqlite3_fil
99a0: 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 77 69 74  e_control()] wit
99b0: 68 20 74 68 69 73 20 6f 70 63 6f 64 65 20 61 73  h this opcode as
99c0: 20 64 6f 69 6e 67 20 73 6f 20 6d 61 79 20 0a 2a   doing so may .*
99d0: 2a 20 64 69 73 72 75 70 74 20 74 68 65 20 6f 70  * disrupt the op
99e0: 65 72 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 73  eration of the s
99f0: 70 65 63 69 61 6c 69 7a 65 64 20 56 46 53 65 73  pecialized VFSes
9a00: 20 74 68 61 74 20 64 6f 20 72 65 71 75 69 72 65   that do require
9a10: 20 69 74 2e 20 20 0a 2a 2a 0a 2a 2a 20 3c 6c 69   it.  .**.** <li
9a20: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
9a30: 43 4f 4d 4d 49 54 5f 50 48 41 53 45 54 57 4f 5d  COMMIT_PHASETWO]
9a40: 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45  ].** The [SQLITE
9a50: 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 50 48  _FCNTL_COMMIT_PH
9a60: 41 53 45 54 57 4f 5d 20 6f 70 63 6f 64 65 20 69  ASETWO] opcode i
9a70: 73 20 67 65 6e 65 72 61 74 65 64 20 69 6e 74 65  s generated inte
9a80: 72 6e 61 6c 6c 79 20 62 79 20 53 51 4c 69 74 65  rnally by SQLite
9a90: 0a 2a 2a 20 61 6e 64 20 73 65 6e 74 20 74 6f 20  .** and sent to 
9aa0: 74 68 65 20 56 46 53 20 61 66 74 65 72 20 61 20  the VFS after a 
9ab0: 74 72 61 6e 73 61 63 74 69 6f 6e 20 68 61 73 20  transaction has 
9ac0: 62 65 65 6e 20 63 6f 6d 6d 69 74 74 65 64 20 69  been committed i
9ad0: 6d 6d 65 64 69 61 74 65 6c 79 0a 2a 2a 20 62 75  mmediately.** bu
9ae0: 74 20 62 65 66 6f 72 65 20 74 68 65 20 64 61 74  t before the dat
9af0: 61 62 61 73 65 20 69 73 20 75 6e 6c 6f 63 6b 65  abase is unlocke
9b00: 64 2e 20 56 46 53 65 73 20 74 68 61 74 20 64 6f  d. VFSes that do
9b10: 20 6e 6f 74 20 6e 65 65 64 20 74 68 69 73 20 73   not need this s
9b20: 69 67 6e 61 6c 0a 2a 2a 20 73 68 6f 75 6c 64 20  ignal.** should 
9b30: 73 69 6c 65 6e 74 6c 79 20 69 67 6e 6f 72 65 20  silently ignore 
9b40: 74 68 69 73 20 6f 70 63 6f 64 65 2e 20 41 70 70  this opcode. App
9b50: 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64  lications should
9b60: 20 6e 6f 74 20 63 61 6c 6c 0a 2a 2a 20 5b 73 71   not call.** [sq
9b70: 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72  lite3_file_contr
9b80: 6f 6c 28 29 5d 20 77 69 74 68 20 74 68 69 73 20  ol()] with this 
9b90: 6f 70 63 6f 64 65 20 61 73 20 64 6f 69 6e 67 20  opcode as doing 
9ba0: 73 6f 20 6d 61 79 20 64 69 73 72 75 70 74 20 74  so may disrupt t
9bb0: 68 65 20 0a 2a 2a 20 6f 70 65 72 61 74 69 6f 6e  he .** operation
9bc0: 20 6f 66 20 74 68 65 20 73 70 65 63 69 61 6c 69   of the speciali
9bd0: 7a 65 64 20 56 46 53 65 73 20 74 68 61 74 20 64  zed VFSes that d
9be0: 6f 20 72 65 71 75 69 72 65 20 69 74 2e 20 20 0a  o require it.  .
9bf0: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
9c00: 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 41  TE_FCNTL_WIN32_A
9c10: 56 5f 52 45 54 52 59 5d 5d 0a 2a 2a 20 5e 54 68  V_RETRY]].** ^Th
9c20: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
9c30: 57 49 4e 33 32 5f 41 56 5f 52 45 54 52 59 5d 20  WIN32_AV_RETRY] 
9c40: 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 74  opcode is used t
9c50: 6f 20 63 6f 6e 66 69 67 75 72 65 20 61 75 74 6f  o configure auto
9c60: 6d 61 74 69 63 0a 2a 2a 20 72 65 74 72 79 20 63  matic.** retry c
9c70: 6f 75 6e 74 73 20 61 6e 64 20 69 6e 74 65 72 76  ounts and interv
9c80: 61 6c 73 20 66 6f 72 20 63 65 72 74 61 69 6e 20  als for certain 
9c90: 64 69 73 6b 20 49 2f 4f 20 6f 70 65 72 61 74 69  disk I/O operati
9ca0: 6f 6e 73 20 66 6f 72 20 74 68 65 0a 2a 2a 20 77  ons for the.** w
9cb0: 69 6e 64 6f 77 73 20 5b 56 46 53 5d 20 69 6e 20  indows [VFS] in 
9cc0: 6f 72 64 65 72 20 74 6f 20 70 72 6f 76 69 64 65  order to provide
9cd0: 20 72 6f 62 75 73 74 6e 65 73 73 20 69 6e 20 74   robustness in t
9ce0: 68 65 20 70 72 65 73 65 6e 63 65 20 6f 66 0a 2a  he presence of.*
9cf0: 2a 20 61 6e 74 69 2d 76 69 72 75 73 20 70 72 6f  * anti-virus pro
9d00: 67 72 61 6d 73 2e 20 20 42 79 20 64 65 66 61 75  grams.  By defau
9d10: 6c 74 2c 20 74 68 65 20 77 69 6e 64 6f 77 73 20  lt, the windows 
9d20: 56 46 53 20 77 69 6c 6c 20 72 65 74 72 79 20 66  VFS will retry f
9d30: 69 6c 65 20 72 65 61 64 2c 0a 2a 2a 20 66 69 6c  ile read,.** fil
9d40: 65 20 77 72 69 74 65 2c 20 61 6e 64 20 66 69 6c  e write, and fil
9d50: 65 20 64 65 6c 65 74 65 20 6f 70 65 72 61 74 69  e delete operati
9d60: 6f 6e 73 20 75 70 20 74 6f 20 31 30 20 74 69 6d  ons up to 10 tim
9d70: 65 73 2c 20 77 69 74 68 20 61 20 64 65 6c 61 79  es, with a delay
9d80: 0a 2a 2a 20 6f 66 20 32 35 20 6d 69 6c 6c 69 73  .** of 25 millis
9d90: 65 63 6f 6e 64 73 20 62 65 66 6f 72 65 20 74 68  econds before th
9da0: 65 20 66 69 72 73 74 20 72 65 74 72 79 20 61 6e  e first retry an
9db0: 64 20 77 69 74 68 20 74 68 65 20 64 65 6c 61 79  d with the delay
9dc0: 20 69 6e 63 72 65 61 73 69 6e 67 0a 2a 2a 20 62   increasing.** b
9dd0: 79 20 61 6e 20 61 64 64 69 74 69 6f 6e 61 6c 20  y an additional 
9de0: 32 35 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20  25 milliseconds 
9df0: 77 69 74 68 20 65 61 63 68 20 73 75 62 73 65 71  with each subseq
9e00: 75 65 6e 74 20 72 65 74 72 79 2e 20 20 54 68 69  uent retry.  Thi
9e10: 73 0a 2a 2a 20 6f 70 63 6f 64 65 20 61 6c 6c 6f  s.** opcode allo
9e20: 77 73 20 74 68 65 73 65 20 74 77 6f 20 76 61 6c  ws these two val
9e30: 75 65 73 20 28 31 30 20 72 65 74 72 69 65 73 20  ues (10 retries 
9e40: 61 6e 64 20 32 35 20 6d 69 6c 6c 69 73 65 63 6f  and 25 milliseco
9e50: 6e 64 73 20 6f 66 20 64 65 6c 61 79 29 0a 2a 2a  nds of delay).**
9e60: 20 74 6f 20 62 65 20 61 64 6a 75 73 74 65 64 2e   to be adjusted.
9e70: 20 20 54 68 65 20 76 61 6c 75 65 73 20 61 72 65    The values are
9e80: 20 63 68 61 6e 67 65 64 20 66 6f 72 20 61 6c 6c   changed for all
9e90: 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
9ea0: 74 69 6f 6e 73 0a 2a 2a 20 77 69 74 68 69 6e 20  tions.** within 
9eb0: 74 68 65 20 73 61 6d 65 20 70 72 6f 63 65 73 73  the same process
9ec0: 2e 20 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20  .  The argument 
9ed0: 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
9ee0: 61 6e 20 61 72 72 61 79 20 6f 66 20 74 77 6f 0a  an array of two.
9ef0: 2a 2a 20 69 6e 74 65 67 65 72 73 20 77 68 65 72  ** integers wher
9f00: 65 20 74 68 65 20 66 69 72 73 74 20 69 6e 74 65  e the first inte
9f10: 67 65 72 20 69 73 20 74 68 65 20 6e 65 77 20 72  ger is the new r
9f20: 65 74 72 79 20 63 6f 75 6e 74 20 61 6e 64 20 74  etry count and t
9f30: 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 69 6e 74  he second.** int
9f40: 65 67 65 72 20 69 73 20 74 68 65 20 64 65 6c 61  eger is the dela
9f50: 79 2e 20 20 49 66 20 65 69 74 68 65 72 20 69 6e  y.  If either in
9f60: 74 65 67 65 72 20 69 73 20 6e 65 67 61 74 69 76  teger is negativ
9f70: 65 2c 20 74 68 65 6e 20 74 68 65 20 73 65 74 74  e, then the sett
9f80: 69 6e 67 0a 2a 2a 20 69 73 20 6e 6f 74 20 63 68  ing.** is not ch
9f90: 61 6e 67 65 64 20 62 75 74 20 69 6e 73 74 65 61  anged but instea
9fa0: 64 20 74 68 65 20 70 72 69 6f 72 20 76 61 6c 75  d the prior valu
9fb0: 65 20 6f 66 20 74 68 61 74 20 73 65 74 74 69 6e  e of that settin
9fc0: 67 20 69 73 20 77 72 69 74 74 65 6e 0a 2a 2a 20  g is written.** 
9fd0: 69 6e 74 6f 20 74 68 65 20 61 72 72 61 79 20 65  into the array e
9fe0: 6e 74 72 79 2c 20 61 6c 6c 6f 77 69 6e 67 20 74  ntry, allowing t
9ff0: 68 65 20 63 75 72 72 65 6e 74 20 72 65 74 72 79  he current retry
a000: 20 73 65 74 74 69 6e 67 73 20 74 6f 20 62 65 0a   settings to be.
a010: 2a 2a 20 69 6e 74 65 72 72 6f 67 61 74 65 64 2e  ** interrogated.
a020: 20 20 54 68 65 20 7a 44 62 4e 61 6d 65 20 70 61    The zDbName pa
a030: 72 61 6d 65 74 65 72 20 69 73 20 69 67 6e 6f 72  rameter is ignor
a040: 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  ed..**.** <li>[[
a050: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 45 52  SQLITE_FCNTL_PER
a060: 53 49 53 54 5f 57 41 4c 5d 5d 0a 2a 2a 20 5e 54  SIST_WAL]].** ^T
a070: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
a080: 5f 50 45 52 53 49 53 54 5f 57 41 4c 5d 20 6f 70  _PERSIST_WAL] op
a090: 63 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f 20  code is used to 
a0a0: 73 65 74 20 6f 72 20 71 75 65 72 79 20 74 68 65  set or query the
a0b0: 0a 2a 2a 20 70 65 72 73 69 73 74 65 6e 74 20 5b  .** persistent [
a0c0: 57 41 4c 20 7c 20 57 72 69 74 65 20 41 68 65 61  WAL | Write Ahea
a0d0: 64 20 4c 6f 67 5d 20 73 65 74 74 69 6e 67 2e 20  d Log] setting. 
a0e0: 20 42 79 20 64 65 66 61 75 6c 74 2c 20 74 68 65   By default, the
a0f0: 20 61 75 78 69 6c 69 61 72 79 0a 2a 2a 20 77 72   auxiliary.** wr
a100: 69 74 65 20 61 68 65 61 64 20 6c 6f 67 20 61 6e  ite ahead log an
a110: 64 20 73 68 61 72 65 64 20 6d 65 6d 6f 72 79 20  d shared memory 
a120: 66 69 6c 65 73 20 75 73 65 64 20 66 6f 72 20 74  files used for t
a130: 72 61 6e 73 61 63 74 69 6f 6e 20 63 6f 6e 74 72  ransaction contr
a140: 6f 6c 0a 2a 2a 20 61 72 65 20 61 75 74 6f 6d 61  ol.** are automa
a150: 74 69 63 61 6c 6c 79 20 64 65 6c 65 74 65 64 20  tically deleted 
a160: 77 68 65 6e 20 74 68 65 20 6c 61 74 65 73 74 20  when the latest 
a170: 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 74 68  connection to th
a180: 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6c  e database.** cl
a190: 6f 73 65 73 2e 20 20 53 65 74 74 69 6e 67 20 70  oses.  Setting p
a1a0: 65 72 73 69 73 74 65 6e 74 20 57 41 4c 20 6d 6f  ersistent WAL mo
a1b0: 64 65 20 63 61 75 73 65 73 20 74 68 6f 73 65 20  de causes those 
a1c0: 66 69 6c 65 73 20 74 6f 20 70 65 72 73 69 73 74  files to persist
a1d0: 20 61 66 74 65 72 0a 2a 2a 20 63 6c 6f 73 65 2e   after.** close.
a1e0: 20 20 50 65 72 73 69 73 74 69 6e 67 20 74 68 65    Persisting the
a1f0: 20 66 69 6c 65 73 20 69 73 20 75 73 65 66 75 6c   files is useful
a200: 20 77 68 65 6e 20 6f 74 68 65 72 20 70 72 6f 63   when other proc
a210: 65 73 73 65 73 20 74 68 61 74 20 64 6f 20 6e 6f  esses that do no
a220: 74 0a 2a 2a 20 68 61 76 65 20 77 72 69 74 65 20  t.** have write 
a230: 70 65 72 6d 69 73 73 69 6f 6e 20 6f 6e 20 74 68  permission on th
a240: 65 20 64 69 72 65 63 74 6f 72 79 20 63 6f 6e 74  e directory cont
a250: 61 69 6e 69 6e 67 20 74 68 65 20 64 61 74 61 62  aining the datab
a260: 61 73 65 20 66 69 6c 65 20 77 61 6e 74 0a 2a 2a  ase file want.**
a270: 20 74 6f 20 72 65 61 64 20 74 68 65 20 64 61 74   to read the dat
a280: 61 62 61 73 65 20 66 69 6c 65 2c 20 61 73 20 74  abase file, as t
a290: 68 65 20 57 41 4c 20 61 6e 64 20 73 68 61 72 65  he WAL and share
a2a0: 64 20 6d 65 6d 6f 72 79 20 66 69 6c 65 73 20 6d  d memory files m
a2b0: 75 73 74 20 65 78 69 73 74 0a 2a 2a 20 69 6e 20  ust exist.** in 
a2c0: 6f 72 64 65 72 20 66 6f 72 20 74 68 65 20 64 61  order for the da
a2d0: 74 61 62 61 73 65 20 74 6f 20 62 65 20 72 65 61  tabase to be rea
a2e0: 64 61 62 6c 65 2e 20 20 54 68 65 20 66 6f 75 72  dable.  The four
a2f0: 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a  th parameter to.
a300: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  ** [sqlite3_file
a310: 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 66 6f 72 20  _control()] for 
a320: 74 68 69 73 20 6f 70 63 6f 64 65 20 73 68 6f 75  this opcode shou
a330: 6c 64 20 62 65 20 61 20 70 6f 69 6e 74 65 72 20  ld be a pointer 
a340: 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 2e 0a 2a  to an integer..*
a350: 2a 20 54 68 61 74 20 69 6e 74 65 67 65 72 20 69  * That integer i
a360: 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65 20 70  s 0 to disable p
a370: 65 72 73 69 73 74 65 6e 74 20 57 41 4c 20 6d 6f  ersistent WAL mo
a380: 64 65 20 6f 72 20 31 20 74 6f 20 65 6e 61 62 6c  de or 1 to enabl
a390: 65 20 70 65 72 73 69 73 74 65 6e 74 0a 2a 2a 20  e persistent.** 
a3a0: 57 41 4c 20 6d 6f 64 65 2e 20 20 49 66 20 74 68  WAL mode.  If th
a3b0: 65 20 69 6e 74 65 67 65 72 20 69 73 20 2d 31 2c  e integer is -1,
a3c0: 20 74 68 65 6e 20 69 74 20 69 73 20 6f 76 65 72   then it is over
a3d0: 77 72 69 74 74 65 6e 20 77 69 74 68 20 74 68 65  written with the
a3e0: 20 63 75 72 72 65 6e 74 0a 2a 2a 20 57 41 4c 20   current.** WAL 
a3f0: 70 65 72 73 69 73 74 65 6e 63 65 20 73 65 74 74  persistence sett
a400: 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  ing..**.** <li>[
a410: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 4f  [SQLITE_FCNTL_PO
a420: 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54  WERSAFE_OVERWRIT
a430: 45 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c  E]].** ^The [SQL
a440: 49 54 45 5f 46 43 4e 54 4c 5f 50 4f 57 45 52 53  ITE_FCNTL_POWERS
a450: 41 46 45 5f 4f 56 45 52 57 52 49 54 45 5d 20 6f  AFE_OVERWRITE] o
a460: 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f  pcode is used to
a470: 20 73 65 74 20 6f 72 20 71 75 65 72 79 20 74 68   set or query th
a480: 65 0a 2a 2a 20 70 65 72 73 69 73 74 65 6e 74 20  e.** persistent 
a490: 22 70 6f 77 65 72 73 61 66 65 2d 6f 76 65 72 77  "powersafe-overw
a4a0: 72 69 74 65 22 20 6f 72 20 22 50 53 4f 57 22 20  rite" or "PSOW" 
a4b0: 73 65 74 74 69 6e 67 2e 20 20 54 68 65 20 50 53  setting.  The PS
a4c0: 4f 57 20 73 65 74 74 69 6e 67 0a 2a 2a 20 64 65  OW setting.** de
a4d0: 74 65 72 6d 69 6e 65 73 20 74 68 65 20 5b 53 51  termines the [SQ
a4e0: 4c 49 54 45 5f 49 4f 43 41 50 5f 50 4f 57 45 52  LITE_IOCAP_POWER
a4f0: 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45 5d 20  SAFE_OVERWRITE] 
a500: 62 69 74 20 6f 66 20 74 68 65 0a 2a 2a 20 78 44  bit of the.** xD
a510: 65 76 69 63 65 43 68 61 72 61 63 74 65 72 69 73  eviceCharacteris
a520: 74 69 63 73 20 6d 65 74 68 6f 64 73 2e 20 54 68  tics methods. Th
a530: 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
a540: 65 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  er to.** [sqlite
a550: 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29  3_file_control()
a560: 5d 20 66 6f 72 20 74 68 69 73 20 6f 70 63 6f 64  ] for this opcod
a570: 65 20 73 68 6f 75 6c 64 20 62 65 20 61 20 70 6f  e should be a po
a580: 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65  inter to an inte
a590: 67 65 72 2e 0a 2a 2a 20 54 68 61 74 20 69 6e 74  ger..** That int
a5a0: 65 67 65 72 20 69 73 20 30 20 74 6f 20 64 69 73  eger is 0 to dis
a5b0: 61 62 6c 65 20 7a 65 72 6f 2d 64 61 6d 61 67 65  able zero-damage
a5c0: 20 6d 6f 64 65 20 6f 72 20 31 20 74 6f 20 65 6e   mode or 1 to en
a5d0: 61 62 6c 65 20 7a 65 72 6f 2d 64 61 6d 61 67 65  able zero-damage
a5e0: 0a 2a 2a 20 6d 6f 64 65 2e 20 20 49 66 20 74 68  .** mode.  If th
a5f0: 65 20 69 6e 74 65 67 65 72 20 69 73 20 2d 31 2c  e integer is -1,
a600: 20 74 68 65 6e 20 69 74 20 69 73 20 6f 76 65 72   then it is over
a610: 77 72 69 74 74 65 6e 20 77 69 74 68 20 74 68 65  written with the
a620: 20 63 75 72 72 65 6e 74 0a 2a 2a 20 7a 65 72 6f   current.** zero
a630: 2d 64 61 6d 61 67 65 20 6d 6f 64 65 20 73 65 74  -damage mode set
a640: 74 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  ting..**.** <li>
a650: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f  [[SQLITE_FCNTL_O
a660: 56 45 52 57 52 49 54 45 5d 5d 0a 2a 2a 20 5e 54  VERWRITE]].** ^T
a670: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
a680: 5f 4f 56 45 52 57 52 49 54 45 5d 20 6f 70 63 6f  _OVERWRITE] opco
a690: 64 65 20 69 73 20 69 6e 76 6f 6b 65 64 20 62 79  de is invoked by
a6a0: 20 53 51 4c 69 74 65 20 61 66 74 65 72 20 6f 70   SQLite after op
a6b0: 65 6e 69 6e 67 0a 2a 2a 20 61 20 77 72 69 74 65  ening.** a write
a6c0: 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 74 6f 20   transaction to 
a6d0: 69 6e 64 69 63 61 74 65 20 74 68 61 74 2c 20 75  indicate that, u
a6e0: 6e 6c 65 73 73 20 69 74 20 69 73 20 72 6f 6c 6c  nless it is roll
a6f0: 65 64 20 62 61 63 6b 20 66 6f 72 20 73 6f 6d 65  ed back for some
a700: 0a 2a 2a 20 72 65 61 73 6f 6e 2c 20 74 68 65 20  .** reason, the 
a710: 65 6e 74 69 72 65 20 64 61 74 61 62 61 73 65 20  entire database 
a720: 66 69 6c 65 20 77 69 6c 6c 20 62 65 20 6f 76 65  file will be ove
a730: 72 77 72 69 74 74 65 6e 20 62 79 20 74 68 65 20  rwritten by the 
a740: 63 75 72 72 65 6e 74 20 0a 2a 2a 20 74 72 61 6e  current .** tran
a750: 73 61 63 74 69 6f 6e 2e 20 54 68 69 73 20 69 73  saction. This is
a760: 20 75 73 65 64 20 62 79 20 56 41 43 55 55 4d 20   used by VACUUM 
a770: 6f 70 65 72 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a  operations..**.*
a780: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
a790: 43 4e 54 4c 5f 56 46 53 4e 41 4d 45 5d 5d 0a 2a  CNTL_VFSNAME]].*
a7a0: 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  * ^The [SQLITE_F
a7b0: 43 4e 54 4c 5f 56 46 53 4e 41 4d 45 5d 20 6f 70  CNTL_VFSNAME] op
a7c0: 63 6f 64 65 20 63 61 6e 20 62 65 20 75 73 65 64  code can be used
a7d0: 20 74 6f 20 6f 62 74 61 69 6e 20 74 68 65 20 6e   to obtain the n
a7e0: 61 6d 65 73 20 6f 66 0a 2a 2a 20 61 6c 6c 20 5b  ames of.** all [
a7f0: 56 46 53 65 73 5d 20 69 6e 20 74 68 65 20 56 46  VFSes] in the VF
a800: 53 20 73 74 61 63 6b 2e 20 20 54 68 65 20 6e 61  S stack.  The na
a810: 6d 65 73 20 61 72 65 20 6f 66 20 61 6c 6c 20 56  mes are of all V
a820: 46 53 20 73 68 69 6d 73 20 61 6e 64 20 74 68 65  FS shims and the
a830: 0a 2a 2a 20 66 69 6e 61 6c 20 62 6f 74 74 6f 6d  .** final bottom
a840: 2d 6c 65 76 65 6c 20 56 46 53 20 61 72 65 20 77  -level VFS are w
a850: 72 69 74 74 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f  ritten into memo
a860: 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  ry obtained from
a870: 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61   .** [sqlite3_ma
a880: 6c 6c 6f 63 28 29 5d 20 61 6e 64 20 74 68 65 20  lloc()] and the 
a890: 72 65 73 75 6c 74 20 69 73 20 73 74 6f 72 65 64  result is stored
a8a0: 20 69 6e 20 74 68 65 20 63 68 61 72 2a 20 76 61   in the char* va
a8b0: 72 69 61 62 6c 65 0a 2a 2a 20 74 68 61 74 20 74  riable.** that t
a8c0: 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
a8d0: 74 65 72 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f  ter of [sqlite3_
a8e0: 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20  file_control()] 
a8f0: 70 6f 69 6e 74 73 20 74 6f 2e 0a 2a 2a 20 54 68  points to..** Th
a900: 65 20 63 61 6c 6c 65 72 20 69 73 20 72 65 73 70  e caller is resp
a910: 6f 6e 73 69 62 6c 65 20 66 6f 72 20 66 72 65 65  onsible for free
a920: 69 6e 67 20 74 68 65 20 6d 65 6d 6f 72 79 20 77  ing the memory w
a930: 68 65 6e 20 64 6f 6e 65 2e 20 20 41 73 20 77 69  hen done.  As wi
a940: 74 68 0a 2a 2a 20 61 6c 6c 20 66 69 6c 65 2d 63  th.** all file-c
a950: 6f 6e 74 72 6f 6c 20 61 63 74 69 6f 6e 73 2c 20  ontrol actions, 
a960: 74 68 65 72 65 20 69 73 20 6e 6f 20 67 75 61 72  there is no guar
a970: 61 6e 74 65 65 20 74 68 61 74 20 74 68 69 73 20  antee that this 
a980: 77 69 6c 6c 20 61 63 74 75 61 6c 6c 79 0a 2a 2a  will actually.**
a990: 20 64 6f 20 61 6e 79 74 68 69 6e 67 2e 20 20 43   do anything.  C
a9a0: 61 6c 6c 65 72 73 20 73 68 6f 75 6c 64 20 69 6e  allers should in
a9b0: 69 74 69 61 6c 69 7a 65 20 74 68 65 20 63 68 61  itialize the cha
a9c0: 72 2a 20 76 61 72 69 61 62 6c 65 20 74 6f 20 61  r* variable to a
a9d0: 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72   NULL.** pointer
a9e0: 20 69 6e 20 63 61 73 65 20 74 68 69 73 20 66 69   in case this fi
a9f0: 6c 65 2d 63 6f 6e 74 72 6f 6c 20 69 73 20 6e 6f  le-control is no
aa00: 74 20 69 6d 70 6c 65 6d 65 6e 74 65 64 2e 20 20  t implemented.  
aa10: 54 68 69 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f  This file-contro
aa20: 6c 0a 2a 2a 20 69 73 20 69 6e 74 65 6e 64 65 64  l.** is intended
aa30: 20 66 6f 72 20 64 69 61 67 6e 6f 73 74 69 63 20   for diagnostic 
aa40: 75 73 65 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20  use only..**.** 
aa50: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e  <li>[[SQLITE_FCN
aa60: 54 4c 5f 56 46 53 5f 50 4f 49 4e 54 45 52 5d 5d  TL_VFS_POINTER]]
aa70: 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45  .** ^The [SQLITE
aa80: 5f 46 43 4e 54 4c 5f 56 46 53 5f 50 4f 49 4e 54  _FCNTL_VFS_POINT
aa90: 45 52 5d 20 6f 70 63 6f 64 65 20 66 69 6e 64 73  ER] opcode finds
aaa0: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   a pointer to th
aab0: 65 20 74 6f 70 2d 6c 65 76 65 6c 0a 2a 2a 20 5b  e top-level.** [
aac0: 56 46 53 65 73 5d 20 63 75 72 72 65 6e 74 6c 79  VFSes] currently
aad0: 20 69 6e 20 75 73 65 2e 20 20 5e 28 54 68 65 20   in use.  ^(The 
aae0: 61 72 67 75 6d 65 6e 74 20 58 20 69 6e 0a 2a 2a  argument X in.**
aaf0: 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f   sqlite3_file_co
ab00: 6e 74 72 6f 6c 28 64 62 2c 53 51 4c 49 54 45 5f  ntrol(db,SQLITE_
ab10: 46 43 4e 54 4c 5f 56 46 53 5f 50 4f 49 4e 54 45  FCNTL_VFS_POINTE
ab20: 52 2c 58 29 20 6d 75 73 74 20 62 65 0a 2a 2a 20  R,X) must be.** 
ab30: 6f 66 20 74 79 70 65 20 22 5b 73 71 6c 69 74 65  of type "[sqlite
ab40: 33 5f 76 66 73 5d 20 2a 2a 22 2e 20 20 54 68 69  3_vfs] **".  Thi
ab50: 73 20 6f 70 63 6f 64 65 73 20 77 69 6c 6c 20 73  s opcodes will s
ab60: 65 74 20 2a 58 0a 2a 2a 20 74 6f 20 61 20 70 6f  et *X.** to a po
ab70: 69 6e 74 65 72 20 74 6f 20 74 68 65 20 74 6f 70  inter to the top
ab80: 2d 6c 65 76 65 6c 20 56 46 53 2e 29 5e 0a 2a 2a  -level VFS.)^.**
ab90: 20 5e 57 68 65 6e 20 74 68 65 72 65 20 61 72 65   ^When there are
aba0: 20 6d 75 6c 74 69 70 6c 65 20 56 46 53 20 73 68   multiple VFS sh
abb0: 69 6d 73 20 69 6e 20 74 68 65 20 73 74 61 63 6b  ims in the stack
abc0: 2c 20 74 68 69 73 20 6f 70 63 6f 64 65 20 66 69  , this opcode fi
abd0: 6e 64 73 20 74 68 65 0a 2a 2a 20 75 70 70 65 72  nds the.** upper
abe0: 2d 6d 6f 73 74 20 73 68 69 6d 20 6f 6e 6c 79 2e  -most shim only.
abf0: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
ac00: 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41  ITE_FCNTL_PRAGMA
ac10: 5d 5d 0a 2a 2a 20 5e 57 68 65 6e 65 76 65 72 20  ]].** ^Whenever 
ac20: 61 20 5b 50 52 41 47 4d 41 5d 20 73 74 61 74 65  a [PRAGMA] state
ac30: 6d 65 6e 74 20 69 73 20 70 61 72 73 65 64 2c 20  ment is parsed, 
ac40: 61 6e 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  an [SQLITE_FCNTL
ac50: 5f 50 52 41 47 4d 41 5d 20 0a 2a 2a 20 66 69 6c  _PRAGMA] .** fil
ac60: 65 20 63 6f 6e 74 72 6f 6c 20 69 73 20 73 65 6e  e control is sen
ac70: 74 20 74 6f 20 74 68 65 20 6f 70 65 6e 20 5b 73  t to the open [s
ac80: 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a  qlite3_file] obj
ac90: 65 63 74 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e  ect correspondin
aca0: 67 0a 2a 2a 20 74 6f 20 74 68 65 20 64 61 74 61  g.** to the data
acb0: 62 61 73 65 20 66 69 6c 65 20 74 6f 20 77 68 69  base file to whi
acc0: 63 68 20 74 68 65 20 70 72 61 67 6d 61 20 73 74  ch the pragma st
acd0: 61 74 65 6d 65 6e 74 20 72 65 66 65 72 73 2e 20  atement refers. 
ace0: 5e 54 68 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a  ^The argument.**
acf0: 20 74 6f 20 74 68 65 20 5b 53 51 4c 49 54 45 5f   to the [SQLITE_
ad00: 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69  FCNTL_PRAGMA] fi
ad10: 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73 20 61 6e  le control is an
ad20: 20 61 72 72 61 79 20 6f 66 0a 2a 2a 20 70 6f 69   array of.** poi
ad30: 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73  nters to strings
ad40: 20 28 63 68 61 72 2a 2a 29 20 69 6e 20 77 68 69   (char**) in whi
ad50: 63 68 20 74 68 65 20 73 65 63 6f 6e 64 20 65 6c  ch the second el
ad60: 65 6d 65 6e 74 20 6f 66 20 74 68 65 20 61 72 72  ement of the arr
ad70: 61 79 0a 2a 2a 20 69 73 20 74 68 65 20 6e 61 6d  ay.** is the nam
ad80: 65 20 6f 66 20 74 68 65 20 70 72 61 67 6d 61 20  e of the pragma 
ad90: 61 6e 64 20 74 68 65 20 74 68 69 72 64 20 65 6c  and the third el
ada0: 65 6d 65 6e 74 20 69 73 20 74 68 65 20 61 72 67  ement is the arg
adb0: 75 6d 65 6e 74 20 74 6f 20 74 68 65 0a 2a 2a 20  ument to the.** 
adc0: 70 72 61 67 6d 61 20 6f 72 20 4e 55 4c 4c 20 69  pragma or NULL i
add0: 66 20 74 68 65 20 70 72 61 67 6d 61 20 68 61 73  f the pragma has
ade0: 20 6e 6f 20 61 72 67 75 6d 65 6e 74 2e 20 20 5e   no argument.  ^
adf0: 54 68 65 20 68 61 6e 64 6c 65 72 20 66 6f 72 20  The handler for 
ae00: 61 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43  an.** [SQLITE_FC
ae10: 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65  NTL_PRAGMA] file
ae20: 20 63 6f 6e 74 72 6f 6c 20 63 61 6e 20 6f 70 74   control can opt
ae30: 69 6f 6e 61 6c 6c 79 20 6d 61 6b 65 20 74 68 65  ionally make the
ae40: 20 66 69 72 73 74 20 65 6c 65 6d 65 6e 74 0a 2a   first element.*
ae50: 2a 20 6f 66 20 74 68 65 20 63 68 61 72 2a 2a 20  * of the char** 
ae60: 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e 74 20 74  argument point t
ae70: 6f 20 61 20 73 74 72 69 6e 67 20 6f 62 74 61 69  o a string obtai
ae80: 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  ned from [sqlite
ae90: 33 5f 6d 70 72 69 6e 74 66 28 29 5d 0a 2a 2a 20  3_mprintf()].** 
aea0: 6f 72 20 74 68 65 20 65 71 75 69 76 61 6c 65 6e  or the equivalen
aeb0: 74 20 61 6e 64 20 74 68 61 74 20 73 74 72 69 6e  t and that strin
aec0: 67 20 77 69 6c 6c 20 62 65 63 6f 6d 65 20 74 68  g will become th
aed0: 65 20 72 65 73 75 6c 74 20 6f 66 20 74 68 65 20  e result of the 
aee0: 70 72 61 67 6d 61 20 6f 72 0a 2a 2a 20 74 68 65  pragma or.** the
aef0: 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 69   error message i
af00: 66 20 74 68 65 20 70 72 61 67 6d 61 20 66 61 69  f the pragma fai
af10: 6c 73 2e 20 5e 49 66 20 74 68 65 0a 2a 2a 20 5b  ls. ^If the.** [
af20: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41  SQLITE_FCNTL_PRA
af30: 47 4d 41 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f  GMA] file contro
af40: 6c 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54  l returns [SQLIT
af50: 45 5f 4e 4f 54 46 4f 55 4e 44 5d 2c 20 74 68 65  E_NOTFOUND], the
af60: 6e 20 6e 6f 72 6d 61 6c 20 0a 2a 2a 20 5b 50 52  n normal .** [PR
af70: 41 47 4d 41 5d 20 70 72 6f 63 65 73 73 69 6e 67  AGMA] processing
af80: 20 63 6f 6e 74 69 6e 75 65 73 2e 20 20 5e 49 66   continues.  ^If
af90: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e   the [SQLITE_FCN
afa0: 54 4c 5f 50 52 41 47 4d 41 5d 0a 2a 2a 20 66 69  TL_PRAGMA].** fi
afb0: 6c 65 20 63 6f 6e 74 72 6f 6c 20 72 65 74 75 72  le control retur
afc0: 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20  ns [SQLITE_OK], 
afd0: 74 68 65 6e 20 74 68 65 20 70 61 72 73 65 72 20  then the parser 
afe0: 61 73 73 75 6d 65 73 20 74 68 61 74 20 74 68 65  assumes that the
aff0: 0a 2a 2a 20 56 46 53 20 68 61 73 20 68 61 6e 64  .** VFS has hand
b000: 6c 65 64 20 74 68 65 20 50 52 41 47 4d 41 20 69  led the PRAGMA i
b010: 74 73 65 6c 66 20 61 6e 64 20 74 68 65 20 70 61  tself and the pa
b020: 72 73 65 72 20 67 65 6e 65 72 61 74 65 73 20 61  rser generates a
b030: 20 6e 6f 2d 6f 70 0a 2a 2a 20 70 72 65 70 61 72   no-op.** prepar
b040: 65 64 20 73 74 61 74 65 6d 65 6e 74 20 69 66 20  ed statement if 
b050: 72 65 73 75 6c 74 20 73 74 72 69 6e 67 20 69 73  result string is
b060: 20 4e 55 4c 4c 2c 20 6f 72 20 74 68 61 74 20 72   NULL, or that r
b070: 65 74 75 72 6e 73 20 61 20 63 6f 70 79 0a 2a 2a  eturns a copy.**
b080: 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73   of the result s
b090: 74 72 69 6e 67 20 69 66 20 74 68 65 20 73 74 72  tring if the str
b0a0: 69 6e 67 20 69 73 20 6e 6f 6e 2d 4e 55 4c 4c 2e  ing is non-NULL.
b0b0: 0a 2a 2a 20 5e 49 66 20 74 68 65 20 5b 53 51 4c  .** ^If the [SQL
b0c0: 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41  ITE_FCNTL_PRAGMA
b0d0: 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 72  ] file control r
b0e0: 65 74 75 72 6e 73 0a 2a 2a 20 61 6e 79 20 72 65  eturns.** any re
b0f0: 73 75 6c 74 20 63 6f 64 65 20 6f 74 68 65 72 20  sult code other 
b100: 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  than [SQLITE_OK]
b110: 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4e 4f 54 46   or [SQLITE_NOTF
b120: 4f 55 4e 44 5d 2c 20 74 68 61 74 20 6d 65 61 6e  OUND], that mean
b130: 73 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 56 46  s.** that the VF
b140: 53 20 65 6e 63 6f 75 6e 74 65 72 65 64 20 61 6e  S encountered an
b150: 20 65 72 72 6f 72 20 77 68 69 6c 65 20 68 61 6e   error while han
b160: 64 6c 69 6e 67 20 74 68 65 20 5b 50 52 41 47 4d  dling the [PRAGM
b170: 41 5d 20 61 6e 64 20 74 68 65 0a 2a 2a 20 63 6f  A] and the.** co
b180: 6d 70 69 6c 61 74 69 6f 6e 20 6f 66 20 74 68 65  mpilation of the
b190: 20 50 52 41 47 4d 41 20 66 61 69 6c 73 20 77 69   PRAGMA fails wi
b1a0: 74 68 20 61 6e 20 65 72 72 6f 72 2e 20 20 5e 54  th an error.  ^T
b1b0: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
b1c0: 5f 50 52 41 47 4d 41 5d 0a 2a 2a 20 66 69 6c 65  _PRAGMA].** file
b1d0: 20 63 6f 6e 74 72 6f 6c 20 6f 63 63 75 72 73 20   control occurs 
b1e0: 61 74 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67  at the beginning
b1f0: 20 6f 66 20 70 72 61 67 6d 61 20 73 74 61 74 65   of pragma state
b200: 6d 65 6e 74 20 61 6e 61 6c 79 73 69 73 20 61 6e  ment analysis an
b210: 64 20 73 6f 0a 2a 2a 20 69 74 20 69 73 20 61 62  d so.** it is ab
b220: 6c 65 20 74 6f 20 6f 76 65 72 72 69 64 65 20 62  le to override b
b230: 75 69 6c 74 2d 69 6e 20 5b 50 52 41 47 4d 41 5d  uilt-in [PRAGMA]
b240: 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a   statements..**.
b250: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
b260: 46 43 4e 54 4c 5f 42 55 53 59 48 41 4e 44 4c 45  FCNTL_BUSYHANDLE
b270: 52 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c  R]].** ^The [SQL
b280: 49 54 45 5f 46 43 4e 54 4c 5f 42 55 53 59 48 41  ITE_FCNTL_BUSYHA
b290: 4e 44 4c 45 52 5d 0a 2a 2a 20 66 69 6c 65 2d 63  NDLER].** file-c
b2a0: 6f 6e 74 72 6f 6c 20 6d 61 79 20 62 65 20 69 6e  ontrol may be in
b2b0: 76 6f 6b 65 64 20 62 79 20 53 51 4c 69 74 65 20  voked by SQLite 
b2c0: 6f 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  on the database 
b2d0: 66 69 6c 65 20 68 61 6e 64 6c 65 0a 2a 2a 20 73  file handle.** s
b2e0: 68 6f 72 74 6c 79 20 61 66 74 65 72 20 69 74 20  hortly after it 
b2f0: 69 73 20 6f 70 65 6e 65 64 20 69 6e 20 6f 72 64  is opened in ord
b300: 65 72 20 74 6f 20 70 72 6f 76 69 64 65 20 61 20  er to provide a 
b310: 63 75 73 74 6f 6d 20 56 46 53 20 77 69 74 68 20  custom VFS with 
b320: 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20 74 68 65  access.** to the
b330: 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 62 75 73   connections bus
b340: 79 2d 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61  y-handler callba
b350: 63 6b 2e 20 54 68 65 20 61 72 67 75 6d 65 6e 74  ck. The argument
b360: 20 69 73 20 6f 66 20 74 79 70 65 20 28 76 6f 69   is of type (voi
b370: 64 20 2a 2a 29 0a 2a 2a 20 2d 20 61 6e 20 61 72  d **).** - an ar
b380: 72 61 79 20 6f 66 20 74 77 6f 20 28 76 6f 69 64  ray of two (void
b390: 20 2a 29 20 76 61 6c 75 65 73 2e 20 54 68 65 20   *) values. The 
b3a0: 66 69 72 73 74 20 28 76 6f 69 64 20 2a 29 20 61  first (void *) a
b3b0: 63 74 75 61 6c 6c 79 20 70 6f 69 6e 74 73 0a 2a  ctually points.*
b3c0: 2a 20 74 6f 20 61 20 66 75 6e 63 74 69 6f 6e 20  * to a function 
b3d0: 6f 66 20 74 79 70 65 20 28 69 6e 74 20 28 2a 29  of type (int (*)
b3e0: 28 76 6f 69 64 20 2a 29 29 2e 20 49 6e 20 6f 72  (void *)). In or
b3f0: 64 65 72 20 74 6f 20 69 6e 76 6f 6b 65 20 74 68  der to invoke th
b400: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a  e connections.**
b410: 20 62 75 73 79 2d 68 61 6e 64 6c 65 72 2c 20 74   busy-handler, t
b420: 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f  his function sho
b430: 75 6c 64 20 62 65 20 69 6e 76 6f 6b 65 64 20 77  uld be invoked w
b440: 69 74 68 20 74 68 65 20 73 65 63 6f 6e 64 20 28  ith the second (
b450: 76 6f 69 64 20 2a 29 20 69 6e 0a 2a 2a 20 74 68  void *) in.** th
b460: 65 20 61 72 72 61 79 20 61 73 20 74 68 65 20 6f  e array as the o
b470: 6e 6c 79 20 61 72 67 75 6d 65 6e 74 2e 20 49 66  nly argument. If
b480: 20 69 74 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d   it returns non-
b490: 7a 65 72 6f 2c 20 74 68 65 6e 20 74 68 65 20 6f  zero, then the o
b4a0: 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 73 68 6f 75  peration.** shou
b4b0: 6c 64 20 62 65 20 72 65 74 72 69 65 64 2e 20 49  ld be retried. I
b4c0: 66 20 69 74 20 72 65 74 75 72 6e 73 20 7a 65 72  f it returns zer
b4d0: 6f 2c 20 74 68 65 20 63 75 73 74 6f 6d 20 56 46  o, the custom VF
b4e0: 53 20 73 68 6f 75 6c 64 20 61 62 61 6e 64 6f 6e  S should abandon
b4f0: 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 20   the.** current 
b500: 6f 70 65 72 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  operation..**.**
b510: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
b520: 4e 54 4c 5f 54 45 4d 50 46 49 4c 45 4e 41 4d 45  NTL_TEMPFILENAME
b530: 5d 5d 0a 2a 2a 20 5e 41 70 70 6c 69 63 61 74 69  ]].** ^Applicati
b540: 6f 6e 20 63 61 6e 20 69 6e 76 6f 6b 65 20 74 68  on can invoke th
b550: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
b560: 54 45 4d 50 46 49 4c 45 4e 41 4d 45 5d 20 66 69  TEMPFILENAME] fi
b570: 6c 65 2d 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 74 6f  le-control.** to
b580: 20 68 61 76 65 20 53 51 4c 69 74 65 20 67 65 6e   have SQLite gen
b590: 65 72 61 74 65 20 61 0a 2a 2a 20 74 65 6d 70 6f  erate a.** tempo
b5a0: 72 61 72 79 20 66 69 6c 65 6e 61 6d 65 20 75 73  rary filename us
b5b0: 69 6e 67 20 74 68 65 20 73 61 6d 65 20 61 6c 67  ing the same alg
b5c0: 6f 72 69 74 68 6d 20 74 68 61 74 20 69 73 20 66  orithm that is f
b5d0: 6f 6c 6c 6f 77 65 64 20 74 6f 20 67 65 6e 65 72  ollowed to gener
b5e0: 61 74 65 0a 2a 2a 20 74 65 6d 70 6f 72 61 72 79  ate.** temporary
b5f0: 20 66 69 6c 65 6e 61 6d 65 73 20 66 6f 72 20 54   filenames for T
b600: 45 4d 50 20 74 61 62 6c 65 73 20 61 6e 64 20 6f  EMP tables and o
b610: 74 68 65 72 20 69 6e 74 65 72 6e 61 6c 20 75 73  ther internal us
b620: 65 73 2e 20 20 54 68 65 0a 2a 2a 20 61 72 67 75  es.  The.** argu
b630: 6d 65 6e 74 20 73 68 6f 75 6c 64 20 62 65 20 61  ment should be a
b640: 20 63 68 61 72 2a 2a 20 77 68 69 63 68 20 77 69   char** which wi
b650: 6c 6c 20 62 65 20 66 69 6c 6c 65 64 20 77 69 74  ll be filled wit
b660: 68 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 0a 2a  h the filename.*
b670: 2a 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 6d  * written into m
b680: 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66  emory obtained f
b690: 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  rom [sqlite3_mal
b6a0: 6c 6f 63 28 29 5d 2e 20 20 54 68 65 20 63 61 6c  loc()].  The cal
b6b0: 6c 65 72 20 73 68 6f 75 6c 64 0a 2a 2a 20 69 6e  ler should.** in
b6c0: 76 6f 6b 65 20 5b 73 71 6c 69 74 65 33 5f 66 72  voke [sqlite3_fr
b6d0: 65 65 28 29 5d 20 6f 6e 20 74 68 65 20 72 65 73  ee()] on the res
b6e0: 75 6c 74 20 74 6f 20 61 76 6f 69 64 20 61 20 6d  ult to avoid a m
b6f0: 65 6d 6f 72 79 20 6c 65 61 6b 2e 0a 2a 2a 0a 2a  emory leak..**.*
b700: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
b710: 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45 5d 5d  CNTL_MMAP_SIZE]]
b720: 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  .** The [SQLITE_
b730: 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45 5d  FCNTL_MMAP_SIZE]
b740: 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73   file control is
b750: 20 75 73 65 64 20 74 6f 20 71 75 65 72 79 20 6f   used to query o
b760: 72 20 73 65 74 20 74 68 65 0a 2a 2a 20 6d 61 78  r set the.** max
b770: 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 62  imum number of b
b780: 79 74 65 73 20 74 68 61 74 20 77 69 6c 6c 20 62  ytes that will b
b790: 65 20 75 73 65 64 20 66 6f 72 20 6d 65 6d 6f 72  e used for memor
b7a0: 79 2d 6d 61 70 70 65 64 20 49 2f 4f 2e 0a 2a 2a  y-mapped I/O..**
b7b0: 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73   The argument is
b7c0: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20   a pointer to a 
b7d0: 76 61 6c 75 65 20 6f 66 20 74 79 70 65 20 73 71  value of type sq
b7e0: 6c 69 74 65 33 5f 69 6e 74 36 34 20 74 68 61 74  lite3_int64 that
b7f0: 0a 2a 2a 20 69 73 20 61 6e 20 61 64 76 69 73 6f  .** is an adviso
b800: 72 79 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65  ry maximum numbe
b810: 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68  r of bytes in th
b820: 65 20 66 69 6c 65 20 74 6f 20 6d 65 6d 6f 72 79  e file to memory
b830: 20 6d 61 70 2e 20 20 54 68 65 0a 2a 2a 20 70 6f   map.  The.** po
b840: 69 6e 74 65 72 20 69 73 20 6f 76 65 72 77 72 69  inter is overwri
b850: 74 74 65 6e 20 77 69 74 68 20 74 68 65 20 6f 6c  tten with the ol
b860: 64 20 76 61 6c 75 65 2e 20 20 54 68 65 20 6c 69  d value.  The li
b870: 6d 69 74 20 69 73 20 6e 6f 74 20 63 68 61 6e 67  mit is not chang
b880: 65 64 20 69 66 0a 2a 2a 20 74 68 65 20 76 61 6c  ed if.** the val
b890: 75 65 20 6f 72 69 67 69 6e 61 6c 6c 79 20 70 6f  ue originally po
b8a0: 69 6e 74 65 64 20 74 6f 20 69 73 20 6e 65 67 61  inted to is nega
b8b0: 74 69 76 65 2c 20 61 6e 64 20 73 6f 20 74 68 65  tive, and so the
b8c0: 20 63 75 72 72 65 6e 74 20 6c 69 6d 69 74 20 0a   current limit .
b8d0: 2a 2a 20 63 61 6e 20 62 65 20 71 75 65 72 69 65  ** can be querie
b8e0: 64 20 62 79 20 70 61 73 73 69 6e 67 20 69 6e 20  d by passing in 
b8f0: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 6e  a pointer to a n
b900: 65 67 61 74 69 76 65 20 6e 75 6d 62 65 72 2e 20  egative number. 
b910: 20 54 68 69 73 0a 2a 2a 20 66 69 6c 65 2d 63 6f   This.** file-co
b920: 6e 74 72 6f 6c 20 69 73 20 75 73 65 64 20 69 6e  ntrol is used in
b930: 74 65 72 6e 61 6c 6c 79 20 74 6f 20 69 6d 70 6c  ternally to impl
b940: 65 6d 65 6e 74 20 5b 50 52 41 47 4d 41 20 6d 6d  ement [PRAGMA mm
b950: 61 70 5f 73 69 7a 65 5d 2e 0a 2a 2a 0a 2a 2a 20  ap_size]..**.** 
b960: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e  <li>[[SQLITE_FCN
b970: 54 4c 5f 54 52 41 43 45 5d 5d 0a 2a 2a 20 54 68  TL_TRACE]].** Th
b980: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
b990: 54 52 41 43 45 5d 20 66 69 6c 65 20 63 6f 6e 74  TRACE] file cont
b9a0: 72 6f 6c 20 70 72 6f 76 69 64 65 73 20 61 64 76  rol provides adv
b9b0: 69 73 6f 72 79 20 69 6e 66 6f 72 6d 61 74 69 6f  isory informatio
b9c0: 6e 0a 2a 2a 20 74 6f 20 74 68 65 20 56 46 53 20  n.** to the VFS 
b9d0: 61 62 6f 75 74 20 77 68 61 74 20 74 68 65 20 68  about what the h
b9e0: 69 67 68 65 72 20 6c 61 79 65 72 73 20 6f 66 20  igher layers of 
b9f0: 74 68 65 20 53 51 4c 69 74 65 20 73 74 61 63 6b  the SQLite stack
ba00: 20 61 72 65 20 64 6f 69 6e 67 2e 0a 2a 2a 20 54   are doing..** T
ba10: 68 69 73 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c  his file control
ba20: 20 69 73 20 75 73 65 64 20 62 79 20 73 6f 6d 65   is used by some
ba30: 20 56 46 53 20 61 63 74 69 76 69 74 79 20 74 72   VFS activity tr
ba40: 61 63 69 6e 67 20 5b 73 68 69 6d 73 5d 2e 0a 2a  acing [shims]..*
ba50: 2a 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 69  * The argument i
ba60: 73 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  s a zero-termina
ba70: 74 65 64 20 73 74 72 69 6e 67 2e 20 20 48 69 67  ted string.  Hig
ba80: 68 65 72 20 6c 61 79 65 72 73 20 69 6e 20 74 68  her layers in th
ba90: 65 0a 2a 2a 20 53 51 4c 69 74 65 20 73 74 61 63  e.** SQLite stac
baa0: 6b 20 6d 61 79 20 67 65 6e 65 72 61 74 65 20 69  k may generate i
bab0: 6e 73 74 61 6e 63 65 73 20 6f 66 20 74 68 69 73  nstances of this
bac0: 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 66   file control if
bad0: 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  .** the [SQLITE_
bae0: 55 53 45 5f 46 43 4e 54 4c 5f 54 52 41 43 45 5d  USE_FCNTL_TRACE]
baf0: 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
bb00: 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 2e  tion is enabled.
bb10: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
bb20: 49 54 45 5f 46 43 4e 54 4c 5f 48 41 53 5f 4d 4f  ITE_FCNTL_HAS_MO
bb30: 56 45 44 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51  VED]].** The [SQ
bb40: 4c 49 54 45 5f 46 43 4e 54 4c 5f 48 41 53 5f 4d  LITE_FCNTL_HAS_M
bb50: 4f 56 45 44 5d 20 66 69 6c 65 20 63 6f 6e 74 72  OVED] file contr
bb60: 6f 6c 20 69 6e 74 65 72 70 72 65 74 73 20 69 74  ol interprets it
bb70: 73 20 61 72 67 75 6d 65 6e 74 20 61 73 20 61 0a  s argument as a.
bb80: 2a 2a 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e  ** pointer to an
bb90: 20 69 6e 74 65 67 65 72 20 61 6e 64 20 69 74 20   integer and it 
bba0: 77 72 69 74 65 73 20 61 20 62 6f 6f 6c 65 61 6e  writes a boolean
bbb0: 20 69 6e 74 6f 20 74 68 61 74 20 69 6e 74 65 67   into that integ
bbc0: 65 72 20 64 65 70 65 6e 64 69 6e 67 0a 2a 2a 20  er depending.** 
bbd0: 6f 6e 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f  on whether or no
bbe0: 74 20 74 68 65 20 66 69 6c 65 20 68 61 73 20 62  t the file has b
bbf0: 65 65 6e 20 72 65 6e 61 6d 65 64 2c 20 6d 6f 76  een renamed, mov
bc00: 65 64 2c 20 6f 72 20 64 65 6c 65 74 65 64 20 73  ed, or deleted s
bc10: 69 6e 63 65 20 69 74 0a 2a 2a 20 77 61 73 20 66  ince it.** was f
bc20: 69 72 73 74 20 6f 70 65 6e 65 64 2e 0a 2a 2a 0a  irst opened..**.
bc30: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
bc40: 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 47 45 54 5f  FCNTL_WIN32_GET_
bc50: 48 41 4e 44 4c 45 5d 5d 0a 2a 2a 20 54 68 65 20  HANDLE]].** The 
bc60: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49  [SQLITE_FCNTL_WI
bc70: 4e 33 32 5f 47 45 54 5f 48 41 4e 44 4c 45 5d 20  N32_GET_HANDLE] 
bc80: 6f 70 63 6f 64 65 20 63 61 6e 20 62 65 20 75 73  opcode can be us
bc90: 65 64 20 74 6f 20 6f 62 74 61 69 6e 20 74 68 65  ed to obtain the
bca0: 0a 2a 2a 20 75 6e 64 65 72 6c 79 69 6e 67 20 6e  .** underlying n
bcb0: 61 74 69 76 65 20 66 69 6c 65 20 68 61 6e 64 6c  ative file handl
bcc0: 65 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74  e associated wit
bcd0: 68 20 61 20 66 69 6c 65 20 68 61 6e 64 6c 65 2e  h a file handle.
bce0: 20 20 54 68 69 73 20 66 69 6c 65 0a 2a 2a 20 63    This file.** c
bcf0: 6f 6e 74 72 6f 6c 20 69 6e 74 65 72 70 72 65 74  ontrol interpret
bd00: 73 20 69 74 73 20 61 72 67 75 6d 65 6e 74 20 61  s its argument a
bd10: 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
bd20: 20 6e 61 74 69 76 65 20 66 69 6c 65 20 68 61 6e   native file han
bd30: 64 6c 65 20 61 6e 64 0a 2a 2a 20 77 72 69 74 65  dle and.** write
bd40: 73 20 74 68 65 20 72 65 73 75 6c 74 69 6e 67 20  s the resulting 
bd50: 76 61 6c 75 65 20 74 68 65 72 65 2e 0a 2a 2a 0a  value there..**.
bd60: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
bd70: 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 53 45 54 5f  FCNTL_WIN32_SET_
bd80: 48 41 4e 44 4c 45 5d 5d 0a 2a 2a 20 54 68 65 20  HANDLE]].** The 
bd90: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49  [SQLITE_FCNTL_WI
bda0: 4e 33 32 5f 53 45 54 5f 48 41 4e 44 4c 45 5d 20  N32_SET_HANDLE] 
bdb0: 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 66  opcode is used f
bdc0: 6f 72 20 64 65 62 75 67 67 69 6e 67 2e 20 20 54  or debugging.  T
bdd0: 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 20 63 61  his.** opcode ca
bde0: 75 73 65 73 20 74 68 65 20 78 46 69 6c 65 43 6f  uses the xFileCo
bdf0: 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 74 6f 20  ntrol method to 
be00: 73 77 61 70 20 74 68 65 20 66 69 6c 65 20 68 61  swap the file ha
be10: 6e 64 6c 65 20 77 69 74 68 20 74 68 65 20 6f 6e  ndle with the on
be20: 65 0a 2a 2a 20 70 6f 69 6e 74 65 64 20 74 6f 20  e.** pointed to 
be30: 62 79 20 74 68 65 20 70 41 72 67 20 61 72 67 75  by the pArg argu
be40: 6d 65 6e 74 2e 20 20 54 68 69 73 20 63 61 70 61  ment.  This capa
be50: 62 69 6c 69 74 79 20 69 73 20 75 73 65 64 20 64  bility is used d
be60: 75 72 69 6e 67 20 74 65 73 74 69 6e 67 0a 2a 2a  uring testing.**
be70: 20 61 6e 64 20 6f 6e 6c 79 20 6e 65 65 64 73 20   and only needs 
be80: 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64 20  to be supported 
be90: 77 68 65 6e 20 53 51 4c 49 54 45 5f 54 45 53 54  when SQLITE_TEST
bea0: 20 69 73 20 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a   is defined..**.
beb0: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
bec0: 46 43 4e 54 4c 5f 57 41 4c 5f 42 4c 4f 43 4b 5d  FCNTL_WAL_BLOCK]
bed0: 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45  ].** The [SQLITE
bee0: 5f 46 43 4e 54 4c 5f 57 41 4c 5f 42 4c 4f 43 4b  _FCNTL_WAL_BLOCK
bef0: 5d 20 69 73 20 61 20 73 69 67 6e 61 6c 20 74 6f  ] is a signal to
bf00: 20 74 68 65 20 56 46 53 20 6c 61 79 65 72 20 74   the VFS layer t
bf10: 68 61 74 20 69 74 20 6d 69 67 68 74 0a 2a 2a 20  hat it might.** 
bf20: 62 65 20 61 64 76 61 6e 74 61 67 65 6f 75 73 20  be advantageous 
bf30: 74 6f 20 62 6c 6f 63 6b 20 6f 6e 20 74 68 65 20  to block on the 
bf40: 6e 65 78 74 20 57 41 4c 20 6c 6f 63 6b 20 69 66  next WAL lock if
bf50: 20 74 68 65 20 6c 6f 63 6b 20 69 73 20 6e 6f 74   the lock is not
bf60: 20 69 6d 6d 65 64 69 61 74 65 6c 79 0a 2a 2a 20   immediately.** 
bf70: 61 76 61 69 6c 61 62 6c 65 2e 20 20 54 68 65 20  available.  The 
bf80: 57 41 4c 20 73 75 62 73 79 73 74 65 6d 20 69 73  WAL subsystem is
bf90: 73 75 65 73 20 74 68 69 73 20 73 69 67 6e 61 6c  sues this signal
bfa0: 20 64 75 72 69 6e 67 20 72 61 72 65 0a 2a 2a 20   during rare.** 
bfb0: 63 69 72 63 75 6d 73 74 61 6e 63 65 73 20 69 6e  circumstances in
bfc0: 20 6f 72 64 65 72 20 74 6f 20 66 69 78 20 61 20   order to fix a 
bfd0: 70 72 6f 62 6c 65 6d 20 77 69 74 68 20 70 72 69  problem with pri
bfe0: 6f 72 69 74 79 20 69 6e 76 65 72 73 69 6f 6e 2e  ority inversion.
bff0: 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73  .** Applications
c000: 20 73 68 6f 75 6c 64 20 3c 65 6d 3e 6e 6f 74 3c   should <em>not<
c010: 2f 65 6d 3e 20 75 73 65 20 74 68 69 73 20 66 69  /em> use this fi
c020: 6c 65 2d 63 6f 6e 74 72 6f 6c 2e 0a 2a 2a 0a 2a  le-control..**.*
c030: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
c040: 43 4e 54 4c 5f 5a 49 50 56 46 53 5d 5d 0a 2a 2a  CNTL_ZIPVFS]].**
c050: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e   The [SQLITE_FCN
c060: 54 4c 5f 5a 49 50 56 46 53 5d 20 6f 70 63 6f 64  TL_ZIPVFS] opcod
c070: 65 20 69 73 20 69 6d 70 6c 65 6d 65 6e 74 65 64  e is implemented
c080: 20 62 79 20 7a 69 70 76 66 73 20 6f 6e 6c 79 2e   by zipvfs only.
c090: 20 41 6c 6c 20 6f 74 68 65 72 0a 2a 2a 20 56 46   All other.** VF
c0a0: 53 20 73 68 6f 75 6c 64 20 72 65 74 75 72 6e 20  S should return 
c0b0: 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 20  SQLITE_NOTFOUND 
c0c0: 66 6f 72 20 74 68 69 73 20 6f 70 63 6f 64 65 2e  for this opcode.
c0d0: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
c0e0: 49 54 45 5f 46 43 4e 54 4c 5f 52 42 55 5d 5d 0a  ITE_FCNTL_RBU]].
c0f0: 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  ** The [SQLITE_F
c100: 43 4e 54 4c 5f 52 42 55 5d 20 6f 70 63 6f 64 65  CNTL_RBU] opcode
c110: 20 69 73 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20   is implemented 
c120: 62 79 20 74 68 65 20 73 70 65 63 69 61 6c 20 56  by the special V
c130: 46 53 20 75 73 65 64 20 62 79 0a 2a 2a 20 74 68  FS used by.** th
c140: 65 20 52 42 55 20 65 78 74 65 6e 73 69 6f 6e 20  e RBU extension 
c150: 6f 6e 6c 79 2e 20 20 41 6c 6c 20 6f 74 68 65 72  only.  All other
c160: 20 56 46 53 20 73 68 6f 75 6c 64 20 72 65 74 75   VFS should retu
c170: 72 6e 20 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55  rn SQLITE_NOTFOU
c180: 4e 44 20 66 6f 72 0a 2a 2a 20 74 68 69 73 20 6f  ND for.** this o
c190: 70 63 6f 64 65 2e 20 20 0a 2a 2a 20 3c 2f 75 6c  pcode.  .** </ul
c1a0: 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  >.*/.#define SQL
c1b0: 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54  ITE_FCNTL_LOCKST
c1c0: 41 54 45 20 20 20 20 20 20 20 20 20 20 20 20 20  ATE             
c1d0: 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    1.#define SQLI
c1e0: 54 45 5f 46 43 4e 54 4c 5f 47 45 54 5f 4c 4f 43  TE_FCNTL_GET_LOC
c1f0: 4b 50 52 4f 58 59 46 49 4c 45 20 20 20 20 20 20  KPROXYFILE      
c200: 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   2.#define SQLIT
c210: 45 5f 46 43 4e 54 4c 5f 53 45 54 5f 4c 4f 43 4b  E_FCNTL_SET_LOCK
c220: 50 52 4f 58 59 46 49 4c 45 20 20 20 20 20 20 20  PROXYFILE       
c230: 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  3.#define SQLITE
c240: 5f 46 43 4e 54 4c 5f 4c 41 53 54 5f 45 52 52 4e  _FCNTL_LAST_ERRN
c250: 4f 20 20 20 20 20 20 20 20 20 20 20 20 20 20 34  O              4
c260: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
c270: 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e 54 20  FCNTL_SIZE_HINT 
c280: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 35 0a                5.
c290: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
c2a0: 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45 20  CNTL_CHUNK_SIZE 
c2b0: 20 20 20 20 20 20 20 20 20 20 20 20 20 36 0a 23               6.#
c2c0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
c2d0: 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52  NTL_FILE_POINTER
c2e0: 20 20 20 20 20 20 20 20 20 20 20 20 37 0a 23 64              7.#d
c2f0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
c300: 54 4c 5f 53 59 4e 43 5f 4f 4d 49 54 54 45 44 20  TL_SYNC_OMITTED 
c310: 20 20 20 20 20 20 20 20 20 20 20 38 0a 23 64 65             8.#de
c320: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
c330: 4c 5f 57 49 4e 33 32 5f 41 56 5f 52 45 54 52 59  L_WIN32_AV_RETRY
c340: 20 20 20 20 20 20 20 20 20 20 39 0a 23 64 65 66            9.#def
c350: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
c360: 5f 50 45 52 53 49 53 54 5f 57 41 4c 20 20 20 20  _PERSIST_WAL    
c370: 20 20 20 20 20 20 20 20 31 30 0a 23 64 65 66 69          10.#defi
c380: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
c390: 4f 56 45 52 57 52 49 54 45 20 20 20 20 20 20 20  OVERWRITE       
c3a0: 20 20 20 20 20 20 20 31 31 0a 23 64 65 66 69 6e         11.#defin
c3b0: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56  e SQLITE_FCNTL_V
c3c0: 46 53 4e 41 4d 45 20 20 20 20 20 20 20 20 20 20  FSNAME          
c3d0: 20 20 20 20 20 20 31 32 0a 23 64 65 66 69 6e 65        12.#define
c3e0: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 4f   SQLITE_FCNTL_PO
c3f0: 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54  WERSAFE_OVERWRIT
c400: 45 20 20 20 20 31 33 0a 23 64 65 66 69 6e 65 20  E    13.#define 
c410: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41  SQLITE_FCNTL_PRA
c420: 47 4d 41 20 20 20 20 20 20 20 20 20 20 20 20 20  GMA             
c430: 20 20 20 20 31 34 0a 23 64 65 66 69 6e 65 20 53      14.#define S
c440: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 55 53 59  QLITE_FCNTL_BUSY
c450: 48 41 4e 44 4c 45 52 20 20 20 20 20 20 20 20 20  HANDLER         
c460: 20 20 20 31 35 0a 23 64 65 66 69 6e 65 20 53 51     15.#define SQ
c470: 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 45 4d 50 46  LITE_FCNTL_TEMPF
c480: 49 4c 45 4e 41 4d 45 20 20 20 20 20 20 20 20 20  ILENAME         
c490: 20 20 31 36 0a 23 64 65 66 69 6e 65 20 53 51 4c    16.#define SQL
c4a0: 49 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53  ITE_FCNTL_MMAP_S
c4b0: 49 5a 45 20 20 20 20 20 20 20 20 20 20 20 20 20  IZE             
c4c0: 20 31 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   18.#define SQLI
c4d0: 54 45 5f 46 43 4e 54 4c 5f 54 52 41 43 45 20 20  TE_FCNTL_TRACE  
c4e0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
c4f0: 31 39 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  19.#define SQLIT
c500: 45 5f 46 43 4e 54 4c 5f 48 41 53 5f 4d 4f 56 45  E_FCNTL_HAS_MOVE
c510: 44 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32  D              2
c520: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
c530: 5f 46 43 4e 54 4c 5f 53 59 4e 43 20 20 20 20 20  _FCNTL_SYNC     
c540: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 31                21
c550: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
c560: 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 50 48 41  FCNTL_COMMIT_PHA
c570: 53 45 54 57 4f 20 20 20 20 20 20 20 20 32 32 0a  SETWO        22.
c580: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
c590: 43 4e 54 4c 5f 57 49 4e 33 32 5f 53 45 54 5f 48  CNTL_WIN32_SET_H
c5a0: 41 4e 44 4c 45 20 20 20 20 20 20 20 32 33 0a 23  ANDLE       23.#
c5b0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
c5c0: 4e 54 4c 5f 57 41 4c 5f 42 4c 4f 43 4b 20 20 20  NTL_WAL_BLOCK   
c5d0: 20 20 20 20 20 20 20 20 20 20 20 32 34 0a 23 64             24.#d
c5e0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
c5f0: 54 4c 5f 5a 49 50 56 46 53 20 20 20 20 20 20 20  TL_ZIPVFS       
c600: 20 20 20 20 20 20 20 20 20 20 32 35 0a 23 64 65            25.#de
c610: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
c620: 4c 5f 52 42 55 20 20 20 20 20 20 20 20 20 20 20  L_RBU           
c630: 20 20 20 20 20 20 20 20 20 32 36 0a 23 64 65 66           26.#def
c640: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
c650: 5f 56 46 53 5f 50 4f 49 4e 54 45 52 20 20 20 20  _VFS_POINTER    
c660: 20 20 20 20 20 20 20 20 32 37 0a 23 64 65 66 69          27.#defi
c670: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
c680: 4a 4f 55 52 4e 41 4c 5f 50 4f 49 4e 54 45 52 20  JOURNAL_POINTER 
c690: 20 20 20 20 20 20 20 32 38 0a 23 64 65 66 69 6e         28.#defin
c6a0: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57  e SQLITE_FCNTL_W
c6b0: 49 4e 33 32 5f 47 45 54 5f 48 41 4e 44 4c 45 20  IN32_GET_HANDLE 
c6c0: 20 20 20 20 20 20 32 39 0a 23 64 65 66 69 6e 65        29.#define
c6d0: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 44   SQLITE_FCNTL_PD
c6e0: 42 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  B               
c6f0: 20 20 20 20 20 33 30 0a 0a 2f 2a 20 64 65 70 72       30../* depr
c700: 65 63 61 74 65 64 20 6e 61 6d 65 73 20 2a 2f 0a  ecated names */.
c710: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 47  #define SQLITE_G
c720: 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45  ET_LOCKPROXYFILE
c730: 20 20 20 20 20 20 53 51 4c 49 54 45 5f 46 43 4e        SQLITE_FCN
c740: 54 4c 5f 47 45 54 5f 4c 4f 43 4b 50 52 4f 58 59  TL_GET_LOCKPROXY
c750: 46 49 4c 45 0a 23 64 65 66 69 6e 65 20 53 51 4c  FILE.#define SQL
c760: 49 54 45 5f 53 45 54 5f 4c 4f 43 4b 50 52 4f 58  ITE_SET_LOCKPROX
c770: 59 46 49 4c 45 20 20 20 20 20 20 53 51 4c 49 54  YFILE      SQLIT
c780: 45 5f 46 43 4e 54 4c 5f 53 45 54 5f 4c 4f 43 4b  E_FCNTL_SET_LOCK
c790: 50 52 4f 58 59 46 49 4c 45 0a 23 64 65 66 69 6e  PROXYFILE.#defin
c7a0: 65 20 53 51 4c 49 54 45 5f 4c 41 53 54 5f 45 52  e SQLITE_LAST_ER
c7b0: 52 4e 4f 20 20 20 20 20 20 20 20 20 20 20 20 20  RNO             
c7c0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 41 53  SQLITE_FCNTL_LAS
c7d0: 54 5f 45 52 52 4e 4f 0a 0a 0a 2f 2a 0a 2a 2a 20  T_ERRNO.../*.** 
c7e0: 43 41 50 49 33 52 45 46 3a 20 4d 75 74 65 78 20  CAPI3REF: Mutex 
c7f0: 48 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20 54 68 65  Handle.**.** The
c800: 20 6d 75 74 65 78 20 6d 6f 64 75 6c 65 20 77 69   mutex module wi
c810: 74 68 69 6e 20 53 51 4c 69 74 65 20 64 65 66 69  thin SQLite defi
c820: 6e 65 73 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74  nes [sqlite3_mut
c830: 65 78 5d 20 74 6f 20 62 65 20 61 6e 0a 2a 2a 20  ex] to be an.** 
c840: 61 62 73 74 72 61 63 74 20 74 79 70 65 20 66 6f  abstract type fo
c850: 72 20 61 20 6d 75 74 65 78 20 6f 62 6a 65 63 74  r a mutex object
c860: 2e 20 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f  .  The SQLite co
c870: 72 65 20 6e 65 76 65 72 20 6c 6f 6f 6b 73 0a 2a  re never looks.*
c880: 2a 20 61 74 20 74 68 65 20 69 6e 74 65 72 6e 61  * at the interna
c890: 6c 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e  l representation
c8a0: 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f   of an [sqlite3_
c8b0: 6d 75 74 65 78 5d 2e 20 20 49 74 20 6f 6e 6c 79  mutex].  It only
c8c0: 0a 2a 2a 20 64 65 61 6c 73 20 77 69 74 68 20 70  .** deals with p
c8d0: 6f 69 6e 74 65 72 73 20 74 6f 20 74 68 65 20 5b  ointers to the [
c8e0: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 20 6f  sqlite3_mutex] o
c8f0: 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 4d 75 74  bject..**.** Mut
c900: 65 78 65 73 20 61 72 65 20 63 72 65 61 74 65 64  exes are created
c910: 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
c920: 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29 5d 2e 0a  mutex_alloc()]..
c930: 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63  */.typedef struc
c940: 74 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 20  t sqlite3_mutex 
c950: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 3b 0a 0a  sqlite3_mutex;..
c960: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
c970: 4c 6f 61 64 61 62 6c 65 20 45 78 74 65 6e 73 69  Loadable Extensi
c980: 6f 6e 20 54 68 75 6e 6b 0a 2a 2a 0a 2a 2a 20 41  on Thunk.**.** A
c990: 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20   pointer to the 
c9a0: 6f 70 61 71 75 65 20 73 71 6c 69 74 65 33 5f 61  opaque sqlite3_a
c9b0: 70 69 5f 72 6f 75 74 69 6e 65 73 20 73 74 72 75  pi_routines stru
c9c0: 63 74 75 72 65 20 69 73 20 70 61 73 73 65 64 20  cture is passed 
c9d0: 61 73 0a 2a 2a 20 74 68 65 20 74 68 69 72 64 20  as.** the third 
c9e0: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 65 6e 74  parameter to ent
c9f0: 72 79 20 70 6f 69 6e 74 73 20 6f 66 20 5b 6c 6f  ry points of [lo
ca00: 61 64 61 62 6c 65 20 65 78 74 65 6e 73 69 6f 6e  adable extension
ca10: 73 5d 2e 20 20 54 68 69 73 0a 2a 2a 20 73 74 72  s].  This.** str
ca20: 75 63 74 75 72 65 20 6d 75 73 74 20 62 65 20 74  ucture must be t
ca30: 79 70 65 64 65 66 65 64 20 69 6e 20 6f 72 64 65  ypedefed in orde
ca40: 72 20 74 6f 20 77 6f 72 6b 20 61 72 6f 75 6e 64  r to work around
ca50: 20 63 6f 6d 70 69 6c 65 72 20 77 61 72 6e 69 6e   compiler warnin
ca60: 67 73 0a 2a 2a 20 6f 6e 20 73 6f 6d 65 20 70 6c  gs.** on some pl
ca70: 61 74 66 6f 72 6d 73 2e 0a 2a 2f 0a 74 79 70 65  atforms..*/.type
ca80: 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
ca90: 65 33 5f 61 70 69 5f 72 6f 75 74 69 6e 65 73 20  e3_api_routines 
caa0: 73 71 6c 69 74 65 33 5f 61 70 69 5f 72 6f 75 74  sqlite3_api_rout
cab0: 69 6e 65 73 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ines;../*.** CAP
cac0: 49 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66  I3REF: OS Interf
cad0: 61 63 65 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a  ace Object.**.**
cae0: 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20   An instance of 
caf0: 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 20  the sqlite3_vfs 
cb00: 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74  object defines t
cb10: 68 65 20 69 6e 74 65 72 66 61 63 65 20 62 65 74  he interface bet
cb20: 77 65 65 6e 0a 2a 2a 20 74 68 65 20 53 51 4c 69  ween.** the SQLi
cb30: 74 65 20 63 6f 72 65 20 61 6e 64 20 74 68 65 20  te core and the 
cb40: 75 6e 64 65 72 6c 79 69 6e 67 20 6f 70 65 72 61  underlying opera
cb50: 74 69 6e 67 20 73 79 73 74 65 6d 2e 20 20 54 68  ting system.  Th
cb60: 65 20 22 76 66 73 22 0a 2a 2a 20 69 6e 20 74 68  e "vfs".** in th
cb70: 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 6f 62  e name of the ob
cb80: 6a 65 63 74 20 73 74 61 6e 64 73 20 66 6f 72 20  ject stands for 
cb90: 22 76 69 72 74 75 61 6c 20 66 69 6c 65 20 73 79  "virtual file sy
cba0: 73 74 65 6d 22 2e 20 20 53 65 65 0a 2a 2a 20 74  stem".  See.** t
cbb0: 68 65 20 5b 56 46 53 20 7c 20 56 46 53 20 64 6f  he [VFS | VFS do
cbc0: 63 75 6d 65 6e 74 61 74 69 6f 6e 5d 20 66 6f 72  cumentation] for
cbd0: 20 66 75 72 74 68 65 72 20 69 6e 66 6f 72 6d 61   further informa
cbe0: 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  tion..**.** The 
cbf0: 76 61 6c 75 65 20 6f 66 20 74 68 65 20 69 56 65  value of the iVe
cc00: 72 73 69 6f 6e 20 66 69 65 6c 64 20 69 73 20 69  rsion field is i
cc10: 6e 69 74 69 61 6c 6c 79 20 31 20 62 75 74 20 6d  nitially 1 but m
cc20: 61 79 20 62 65 20 6c 61 72 67 65 72 20 69 6e 0a  ay be larger in.
cc30: 2a 2a 20 66 75 74 75 72 65 20 76 65 72 73 69 6f  ** future versio
cc40: 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 41  ns of SQLite.  A
cc50: 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73  dditional fields
cc60: 20 6d 61 79 20 62 65 20 61 70 70 65 6e 64 65 64   may be appended
cc70: 20 74 6f 20 74 68 69 73 0a 2a 2a 20 6f 62 6a 65   to this.** obje
cc80: 63 74 20 77 68 65 6e 20 74 68 65 20 69 56 65 72  ct when the iVer
cc90: 73 69 6f 6e 20 76 61 6c 75 65 20 69 73 20 69 6e  sion value is in
cca0: 63 72 65 61 73 65 64 2e 20 20 4e 6f 74 65 20 74  creased.  Note t
ccb0: 68 61 74 20 74 68 65 20 73 74 72 75 63 74 75 72  hat the structur
ccc0: 65 0a 2a 2a 20 6f 66 20 74 68 65 20 73 71 6c 69  e.** of the sqli
ccd0: 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 20 63  te3_vfs object c
cce0: 68 61 6e 67 65 73 20 69 6e 20 74 68 65 20 74 72  hanges in the tr
ccf0: 61 6e 73 61 63 74 69 6f 6e 20 62 65 74 77 65 65  ansaction betwee
cd00: 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 76 65 72 73  n.** SQLite vers
cd10: 69 6f 6e 20 33 2e 35 2e 39 20 61 6e 64 20 33 2e  ion 3.5.9 and 3.
cd20: 36 2e 30 20 61 6e 64 20 79 65 74 20 74 68 65 20  6.0 and yet the 
cd30: 69 56 65 72 73 69 6f 6e 20 66 69 65 6c 64 20 77  iVersion field w
cd40: 61 73 20 6e 6f 74 0a 2a 2a 20 6d 6f 64 69 66 69  as not.** modifi
cd50: 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 7a  ed..**.** The sz
cd60: 4f 73 46 69 6c 65 20 66 69 65 6c 64 20 69 73 20  OsFile field is 
cd70: 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20  the size of the 
cd80: 73 75 62 63 6c 61 73 73 65 64 20 5b 73 71 6c 69  subclassed [sqli
cd90: 74 65 33 5f 66 69 6c 65 5d 0a 2a 2a 20 73 74 72  te3_file].** str
cda0: 75 63 74 75 72 65 20 75 73 65 64 20 62 79 20 74  ucture used by t
cdb0: 68 69 73 20 56 46 53 2e 20 20 6d 78 50 61 74 68  his VFS.  mxPath
cdc0: 6e 61 6d 65 20 69 73 20 74 68 65 20 6d 61 78 69  name is the maxi
cdd0: 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 0a 2a 2a  mum length of.**
cde0: 20 61 20 70 61 74 68 6e 61 6d 65 20 69 6e 20 74   a pathname in t
cdf0: 68 69 73 20 56 46 53 2e 0a 2a 2a 0a 2a 2a 20 52  his VFS..**.** R
ce00: 65 67 69 73 74 65 72 65 64 20 73 71 6c 69 74 65  egistered sqlite
ce10: 33 5f 76 66 73 20 6f 62 6a 65 63 74 73 20 61 72  3_vfs objects ar
ce20: 65 20 6b 65 70 74 20 6f 6e 20 61 20 6c 69 6e 6b  e kept on a link
ce30: 65 64 20 6c 69 73 74 20 66 6f 72 6d 65 64 20 62  ed list formed b
ce40: 79 0a 2a 2a 20 74 68 65 20 70 4e 65 78 74 20 70  y.** the pNext p
ce50: 6f 69 6e 74 65 72 2e 20 20 54 68 65 20 5b 73 71  ointer.  The [sq
ce60: 6c 69 74 65 33 5f 76 66 73 5f 72 65 67 69 73 74  lite3_vfs_regist
ce70: 65 72 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71  er()].** and [sq
ce80: 6c 69 74 65 33 5f 76 66 73 5f 75 6e 72 65 67 69  lite3_vfs_unregi
ce90: 73 74 65 72 28 29 5d 20 69 6e 74 65 72 66 61 63  ster()] interfac
cea0: 65 73 20 6d 61 6e 61 67 65 20 74 68 69 73 20 6c  es manage this l
ceb0: 69 73 74 0a 2a 2a 20 69 6e 20 61 20 74 68 72 65  ist.** in a thre
cec0: 61 64 2d 73 61 66 65 20 77 61 79 2e 20 20 54 68  ad-safe way.  Th
ced0: 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f 66  e [sqlite3_vfs_f
cee0: 69 6e 64 28 29 5d 20 69 6e 74 65 72 66 61 63 65  ind()] interface
cef0: 0a 2a 2a 20 73 65 61 72 63 68 65 73 20 74 68 65  .** searches the
cf00: 20 6c 69 73 74 2e 20 20 4e 65 69 74 68 65 72 20   list.  Neither 
cf10: 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
cf20: 63 6f 64 65 20 6e 6f 72 20 74 68 65 20 56 46 53  code nor the VFS
cf30: 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  .** implementati
cf40: 6f 6e 20 73 68 6f 75 6c 64 20 75 73 65 20 74 68  on should use th
cf50: 65 20 70 4e 65 78 74 20 70 6f 69 6e 74 65 72 2e  e pNext pointer.
cf60: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 4e 65 78 74  .**.** The pNext
cf70: 20 66 69 65 6c 64 20 69 73 20 74 68 65 20 6f 6e   field is the on
cf80: 6c 79 20 66 69 65 6c 64 20 69 6e 20 74 68 65 20  ly field in the 
cf90: 73 71 6c 69 74 65 33 5f 76 66 73 0a 2a 2a 20 73  sqlite3_vfs.** s
cfa0: 74 72 75 63 74 75 72 65 20 74 68 61 74 20 53 51  tructure that SQ
cfb0: 4c 69 74 65 20 77 69 6c 6c 20 65 76 65 72 20 6d  Lite will ever m
cfc0: 6f 64 69 66 79 2e 20 20 53 51 4c 69 74 65 20 77  odify.  SQLite w
cfd0: 69 6c 6c 20 6f 6e 6c 79 20 61 63 63 65 73 73 0a  ill only access.
cfe0: 2a 2a 20 6f 72 20 6d 6f 64 69 66 79 20 74 68 69  ** or modify thi
cff0: 73 20 66 69 65 6c 64 20 77 68 69 6c 65 20 68 6f  s field while ho
d000: 6c 64 69 6e 67 20 61 20 70 61 72 74 69 63 75 6c  lding a particul
d010: 61 72 20 73 74 61 74 69 63 20 6d 75 74 65 78 2e  ar static mutex.
d020: 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74  .** The applicat
d030: 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 65 76 65 72  ion should never
d040: 20 6d 6f 64 69 66 79 20 61 6e 79 74 68 69 6e 67   modify anything
d050: 20 77 69 74 68 69 6e 20 74 68 65 20 73 71 6c 69   within the sqli
d060: 74 65 33 5f 76 66 73 0a 2a 2a 20 6f 62 6a 65 63  te3_vfs.** objec
d070: 74 20 6f 6e 63 65 20 74 68 65 20 6f 62 6a 65 63  t once the objec
d080: 74 20 68 61 73 20 62 65 65 6e 20 72 65 67 69 73  t has been regis
d090: 74 65 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  tered..**.** The
d0a0: 20 7a 4e 61 6d 65 20 66 69 65 6c 64 20 68 6f 6c   zName field hol
d0b0: 64 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  ds the name of t
d0c0: 68 65 20 56 46 53 20 6d 6f 64 75 6c 65 2e 20 20  he VFS module.  
d0d0: 54 68 65 20 6e 61 6d 65 20 6d 75 73 74 0a 2a 2a  The name must.**
d0e0: 20 62 65 20 75 6e 69 71 75 65 20 61 63 72 6f 73   be unique acros
d0f0: 73 20 61 6c 6c 20 56 46 53 20 6d 6f 64 75 6c 65  s all VFS module
d100: 73 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 73 71 6c 69 74  s..**.** [[sqlit
d110: 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 5d 0a 2a  e3_vfs.xOpen]].*
d120: 2a 20 5e 53 51 4c 69 74 65 20 67 75 61 72 61 6e  * ^SQLite guaran
d130: 74 65 65 73 20 74 68 61 74 20 74 68 65 20 7a 46  tees that the zF
d140: 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65  ilename paramete
d150: 72 20 74 6f 20 78 4f 70 65 6e 0a 2a 2a 20 69 73  r to xOpen.** is
d160: 20 65 69 74 68 65 72 20 61 20 4e 55 4c 4c 20 70   either a NULL p
d170: 6f 69 6e 74 65 72 20 6f 72 20 73 74 72 69 6e 67  ointer or string
d180: 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f   obtained.** fro
d190: 6d 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 28  m xFullPathname(
d1a0: 29 20 77 69 74 68 20 61 6e 20 6f 70 74 69 6f 6e  ) with an option
d1b0: 61 6c 20 73 75 66 66 69 78 20 61 64 64 65 64 2e  al suffix added.
d1c0: 0a 2a 2a 20 5e 49 66 20 61 20 73 75 66 66 69 78  .** ^If a suffix
d1d0: 20 69 73 20 61 64 64 65 64 20 74 6f 20 74 68 65   is added to the
d1e0: 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d   zFilename param
d1f0: 65 74 65 72 2c 20 69 74 20 77 69 6c 6c 0a 2a 2a  eter, it will.**
d200: 20 63 6f 6e 73 69 73 74 20 6f 66 20 61 20 73 69   consist of a si
d210: 6e 67 6c 65 20 22 2d 22 20 63 68 61 72 61 63 74  ngle "-" charact
d220: 65 72 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 6e  er followed by n
d230: 6f 20 6d 6f 72 65 20 74 68 61 6e 0a 2a 2a 20 31  o more than.** 1
d240: 31 20 61 6c 70 68 61 6e 75 6d 65 72 69 63 20 61  1 alphanumeric a
d250: 6e 64 2f 6f 72 20 22 2d 22 20 63 68 61 72 61 63  nd/or "-" charac
d260: 74 65 72 73 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65  ters..** ^SQLite
d270: 20 66 75 72 74 68 65 72 20 67 75 61 72 61 6e 74   further guarant
d280: 65 65 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 20  ees that.** the 
d290: 73 74 72 69 6e 67 20 77 69 6c 6c 20 62 65 20 76  string will be v
d2a0: 61 6c 69 64 20 61 6e 64 20 75 6e 63 68 61 6e 67  alid and unchang
d2b0: 65 64 20 75 6e 74 69 6c 20 78 43 6c 6f 73 65 28  ed until xClose(
d2c0: 29 20 69 73 0a 2a 2a 20 63 61 6c 6c 65 64 2e 20  ) is.** called. 
d2d0: 42 65 63 61 75 73 65 20 6f 66 20 74 68 65 20 70  Because of the p
d2e0: 72 65 76 69 6f 75 73 20 73 65 6e 74 65 6e 63 65  revious sentence
d2f0: 2c 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65  ,.** the [sqlite
d300: 33 5f 66 69 6c 65 5d 20 63 61 6e 20 73 61 66 65  3_file] can safe
d310: 6c 79 20 73 74 6f 72 65 20 61 20 70 6f 69 6e 74  ly store a point
d320: 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 66 69 6c  er to the.** fil
d330: 65 6e 61 6d 65 20 69 66 20 69 74 20 6e 65 65 64  ename if it need
d340: 73 20 74 6f 20 72 65 6d 65 6d 62 65 72 20 74 68  s to remember th
d350: 65 20 66 69 6c 65 6e 61 6d 65 20 66 6f 72 20 73  e filename for s
d360: 6f 6d 65 20 72 65 61 73 6f 6e 2e 0a 2a 2a 20 49  ome reason..** I
d370: 66 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20  f the zFilename 
d380: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 78 4f 70  parameter to xOp
d390: 65 6e 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69  en is a NULL poi
d3a0: 6e 74 65 72 20 74 68 65 6e 20 78 4f 70 65 6e 0a  nter then xOpen.
d3b0: 2a 2a 20 6d 75 73 74 20 69 6e 76 65 6e 74 20 69  ** must invent i
d3c0: 74 73 20 6f 77 6e 20 74 65 6d 70 6f 72 61 72 79  ts own temporary
d3d0: 20 6e 61 6d 65 20 66 6f 72 20 74 68 65 20 66 69   name for the fi
d3e0: 6c 65 2e 20 20 5e 57 68 65 6e 65 76 65 72 20 74  le.  ^Whenever t
d3f0: 68 65 20 0a 2a 2a 20 78 46 69 6c 65 6e 61 6d 65  he .** xFilename
d400: 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 4e 55   parameter is NU
d410: 4c 4c 20 69 74 20 77 69 6c 6c 20 61 6c 73 6f 20  LL it will also 
d420: 62 65 20 74 68 65 20 63 61 73 65 20 74 68 61 74  be the case that
d430: 20 74 68 65 0a 2a 2a 20 66 6c 61 67 73 20 70 61   the.** flags pa
d440: 72 61 6d 65 74 65 72 20 77 69 6c 6c 20 69 6e 63  rameter will inc
d450: 6c 75 64 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45  lude [SQLITE_OPE
d460: 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d  N_DELETEONCLOSE]
d470: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c 61 67  ..**.** The flag
d480: 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 4f  s argument to xO
d490: 70 65 6e 28 29 20 69 6e 63 6c 75 64 65 73 20 61  pen() includes a
d4a0: 6c 6c 20 62 69 74 73 20 73 65 74 20 69 6e 0a 2a  ll bits set in.*
d4b0: 2a 20 74 68 65 20 66 6c 61 67 73 20 61 72 67 75  * the flags argu
d4c0: 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33  ment to [sqlite3
d4d0: 5f 6f 70 65 6e 5f 76 32 28 29 5d 2e 20 20 4f 72  _open_v2()].  Or
d4e0: 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65   if [sqlite3_ope
d4f0: 6e 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69  n()].** or [sqli
d500: 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 20 69 73  te3_open16()] is
d510: 20 75 73 65 64 2c 20 74 68 65 6e 20 66 6c 61 67   used, then flag
d520: 73 20 69 6e 63 6c 75 64 65 73 20 61 74 20 6c 65  s includes at le
d530: 61 73 74 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f  ast.** [SQLITE_O
d540: 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 20 7c  PEN_READWRITE] |
d550: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52   [SQLITE_OPEN_CR
d560: 45 41 54 45 5d 2e 20 0a 2a 2a 20 49 66 20 78 4f  EATE]. .** If xO
d570: 70 65 6e 28 29 20 6f 70 65 6e 73 20 61 20 66 69  pen() opens a fi
d580: 6c 65 20 72 65 61 64 2d 6f 6e 6c 79 20 74 68 65  le read-only the
d590: 6e 20 69 74 20 73 65 74 73 20 2a 70 4f 75 74 46  n it sets *pOutF
d5a0: 6c 61 67 73 20 74 6f 0a 2a 2a 20 69 6e 63 6c 75  lags to.** inclu
d5b0: 64 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  de [SQLITE_OPEN_
d5c0: 52 45 41 44 4f 4e 4c 59 5d 2e 20 20 4f 74 68 65  READONLY].  Othe
d5d0: 72 20 62 69 74 73 20 69 6e 20 2a 70 4f 75 74 46  r bits in *pOutF
d5e0: 6c 61 67 73 20 6d 61 79 20 62 65 20 73 65 74 2e  lags may be set.
d5f0: 0a 2a 2a 0a 2a 2a 20 5e 28 53 51 4c 69 74 65 20  .**.** ^(SQLite 
d600: 77 69 6c 6c 20 61 6c 73 6f 20 61 64 64 20 6f 6e  will also add on
d610: 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69  e of the followi
d620: 6e 67 20 66 6c 61 67 73 20 74 6f 20 74 68 65 20  ng flags to the 
d630: 78 4f 70 65 6e 28 29 0a 2a 2a 20 63 61 6c 6c 2c  xOpen().** call,
d640: 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68   depending on th
d650: 65 20 6f 62 6a 65 63 74 20 62 65 69 6e 67 20 6f  e object being o
d660: 70 65 6e 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c  pened:.**.** <ul
d670: 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49  >.** <li>  [SQLI
d680: 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 5d  TE_OPEN_MAIN_DB]
d690: 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54  .** <li>  [SQLIT
d6a0: 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52  E_OPEN_MAIN_JOUR
d6b0: 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53  NAL].** <li>  [S
d6c0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f  QLITE_OPEN_TEMP_
d6d0: 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51  DB].** <li>  [SQ
d6e0: 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a  LITE_OPEN_TEMP_J
d6f0: 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20  OURNAL].** <li> 
d700: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 52   [SQLITE_OPEN_TR
d710: 41 4e 53 49 45 4e 54 5f 44 42 5d 0a 2a 2a 20 3c  ANSIENT_DB].** <
d720: 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45  li>  [SQLITE_OPE
d730: 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a  N_SUBJOURNAL].**
d740: 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f   <li>  [SQLITE_O
d750: 50 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55 52 4e  PEN_MASTER_JOURN
d760: 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51  AL].** <li>  [SQ
d770: 4c 49 54 45 5f 4f 50 45 4e 5f 57 41 4c 5d 0a 2a  LITE_OPEN_WAL].*
d780: 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20  * </ul>)^.**.** 
d790: 54 68 65 20 66 69 6c 65 20 49 2f 4f 20 69 6d 70  The file I/O imp
d7a0: 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 63 61 6e 20  lementation can 
d7b0: 75 73 65 20 74 68 65 20 6f 62 6a 65 63 74 20 74  use the object t
d7c0: 79 70 65 20 66 6c 61 67 73 20 74 6f 0a 2a 2a 20  ype flags to.** 
d7d0: 63 68 61 6e 67 65 20 74 68 65 20 77 61 79 20 69  change the way i
d7e0: 74 20 64 65 61 6c 73 20 77 69 74 68 20 66 69 6c  t deals with fil
d7f0: 65 73 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c 65  es.  For example
d800: 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  , an application
d810: 0a 2a 2a 20 74 68 61 74 20 64 6f 65 73 20 6e 6f  .** that does no
d820: 74 20 63 61 72 65 20 61 62 6f 75 74 20 63 72 61  t care about cra
d830: 73 68 20 72 65 63 6f 76 65 72 79 20 6f 72 20 72  sh recovery or r
d840: 6f 6c 6c 62 61 63 6b 20 6d 69 67 68 74 20 6d 61  ollback might ma
d850: 6b 65 0a 2a 2a 20 74 68 65 20 6f 70 65 6e 20 6f  ke.** the open o
d860: 66 20 61 20 6a 6f 75 72 6e 61 6c 20 66 69 6c 65  f a journal file
d870: 20 61 20 6e 6f 2d 6f 70 2e 20 20 57 72 69 74 65   a no-op.  Write
d880: 73 20 74 6f 20 74 68 69 73 20 6a 6f 75 72 6e 61  s to this journa
d890: 6c 20 77 6f 75 6c 64 0a 2a 2a 20 61 6c 73 6f 20  l would.** also 
d8a0: 62 65 20 6e 6f 2d 6f 70 73 2c 20 61 6e 64 20 61  be no-ops, and a
d8b0: 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20 72 65  ny attempt to re
d8c0: 61 64 20 74 68 65 20 6a 6f 75 72 6e 61 6c 20 77  ad the journal w
d8d0: 6f 75 6c 64 20 72 65 74 75 72 6e 0a 2a 2a 20 53  ould return.** S
d8e0: 51 4c 49 54 45 5f 49 4f 45 52 52 2e 20 20 4f 72  QLITE_IOERR.  Or
d8f0: 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74   the implementat
d900: 69 6f 6e 20 6d 69 67 68 74 20 72 65 63 6f 67 6e  ion might recogn
d910: 69 7a 65 20 74 68 61 74 20 61 20 64 61 74 61 62  ize that a datab
d920: 61 73 65 0a 2a 2a 20 66 69 6c 65 20 77 69 6c 6c  ase.** file will
d930: 20 62 65 20 64 6f 69 6e 67 20 70 61 67 65 2d 61   be doing page-a
d940: 6c 69 67 6e 65 64 20 73 65 63 74 6f 72 20 72 65  ligned sector re
d950: 61 64 73 20 61 6e 64 20 77 72 69 74 65 73 20 69  ads and writes i
d960: 6e 20 61 20 72 61 6e 64 6f 6d 0a 2a 2a 20 6f 72  n a random.** or
d970: 64 65 72 20 61 6e 64 20 73 65 74 20 75 70 20 69  der and set up i
d980: 74 73 20 49 2f 4f 20 73 75 62 73 79 73 74 65 6d  ts I/O subsystem
d990: 20 61 63 63 6f 72 64 69 6e 67 6c 79 2e 0a 2a 2a   accordingly..**
d9a0: 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 69 67 68 74  .** SQLite might
d9b0: 20 61 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66   also add one of
d9c0: 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66   the following f
d9d0: 6c 61 67 73 20 74 6f 20 74 68 65 20 78 4f 70 65  lags to the xOpe
d9e0: 6e 20 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20  n method:.**.** 
d9f0: 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  <ul>.** <li> [SQ
da00: 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45  LITE_OPEN_DELETE
da10: 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 3c 6c 69 3e  ONCLOSE].** <li>
da20: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58   [SQLITE_OPEN_EX
da30: 43 4c 55 53 49 56 45 5d 0a 2a 2a 20 3c 2f 75 6c  CLUSIVE].** </ul
da40: 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  >.**.** The [SQL
da50: 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f  ITE_OPEN_DELETEO
da60: 4e 43 4c 4f 53 45 5d 20 66 6c 61 67 20 6d 65 61  NCLOSE] flag mea
da70: 6e 73 20 74 68 65 20 66 69 6c 65 20 73 68 6f 75  ns the file shou
da80: 6c 64 20 62 65 0a 2a 2a 20 64 65 6c 65 74 65 64  ld be.** deleted
da90: 20 77 68 65 6e 20 69 74 20 69 73 20 63 6c 6f 73   when it is clos
daa0: 65 64 2e 20 20 5e 54 68 65 20 5b 53 51 4c 49 54  ed.  ^The [SQLIT
dab0: 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43  E_OPEN_DELETEONC
dac0: 4c 4f 53 45 5d 0a 2a 2a 20 77 69 6c 6c 20 62 65  LOSE].** will be
dad0: 20 73 65 74 20 66 6f 72 20 54 45 4d 50 20 64 61   set for TEMP da
dae0: 74 61 62 61 73 65 73 20 61 6e 64 20 74 68 65 69  tabases and thei
daf0: 72 20 6a 6f 75 72 6e 61 6c 73 2c 20 74 72 61 6e  r journals, tran
db00: 73 69 65 6e 74 0a 2a 2a 20 64 61 74 61 62 61 73  sient.** databas
db10: 65 73 2c 20 61 6e 64 20 73 75 62 6a 6f 75 72 6e  es, and subjourn
db20: 61 6c 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  als..**.** ^The 
db30: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43  [SQLITE_OPEN_EXC
db40: 4c 55 53 49 56 45 5d 20 66 6c 61 67 20 69 73 20  LUSIVE] flag is 
db50: 61 6c 77 61 79 73 20 75 73 65 64 20 69 6e 20 63  always used in c
db60: 6f 6e 6a 75 6e 63 74 69 6f 6e 0a 2a 2a 20 77 69  onjunction.** wi
db70: 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f  th the [SQLITE_O
db80: 50 45 4e 5f 43 52 45 41 54 45 5d 20 66 6c 61 67  PEN_CREATE] flag
db90: 2c 20 77 68 69 63 68 20 61 72 65 20 62 6f 74 68  , which are both
dba0: 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 61 6e 61   directly.** ana
dbb0: 6c 6f 67 6f 75 73 20 74 6f 20 74 68 65 20 4f 5f  logous to the O_
dbc0: 45 58 43 4c 20 61 6e 64 20 4f 5f 43 52 45 41 54  EXCL and O_CREAT
dbd0: 20 66 6c 61 67 73 20 6f 66 20 74 68 65 20 50 4f   flags of the PO
dbe0: 53 49 58 20 6f 70 65 6e 28 29 0a 2a 2a 20 41 50  SIX open().** AP
dbf0: 49 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 4f  I.  The SQLITE_O
dc00: 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 20 66 6c  PEN_EXCLUSIVE fl
dc10: 61 67 2c 20 77 68 65 6e 20 70 61 69 72 65 64 20  ag, when paired 
dc20: 77 69 74 68 20 74 68 65 20 0a 2a 2a 20 53 51 4c  with the .** SQL
dc30: 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 2c  ITE_OPEN_CREATE,
dc40: 20 69 73 20 75 73 65 64 20 74 6f 20 69 6e 64 69   is used to indi
dc50: 63 61 74 65 20 74 68 61 74 20 66 69 6c 65 20 73  cate that file s
dc60: 68 6f 75 6c 64 20 61 6c 77 61 79 73 0a 2a 2a 20  hould always.** 
dc70: 62 65 20 63 72 65 61 74 65 64 2c 20 61 6e 64 20  be created, and 
dc80: 74 68 61 74 20 69 74 20 69 73 20 61 6e 20 65 72  that it is an er
dc90: 72 6f 72 20 69 66 20 69 74 20 61 6c 72 65 61 64  ror if it alread
dca0: 79 20 65 78 69 73 74 73 2e 0a 2a 2a 20 49 74 20  y exists..** It 
dcb0: 69 73 20 3c 69 3e 6e 6f 74 3c 2f 69 3e 20 75 73  is <i>not</i> us
dcc0: 65 64 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74  ed to indicate t
dcd0: 68 65 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 62  he file should b
dce0: 65 20 6f 70 65 6e 65 64 20 0a 2a 2a 20 66 6f 72  e opened .** for
dcf0: 20 65 78 63 6c 75 73 69 76 65 20 61 63 63 65 73   exclusive acces
dd00: 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 74 20 6c 65 61  s..**.** ^At lea
dd10: 73 74 20 73 7a 4f 73 46 69 6c 65 20 62 79 74 65  st szOsFile byte
dd20: 73 20 6f 66 20 6d 65 6d 6f 72 79 20 61 72 65 20  s of memory are 
dd30: 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 53 51 4c  allocated by SQL
dd40: 69 74 65 0a 2a 2a 20 74 6f 20 68 6f 6c 64 20 74  ite.** to hold t
dd50: 68 65 20 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  he  [sqlite3_fil
dd60: 65 5d 20 73 74 72 75 63 74 75 72 65 20 70 61 73  e] structure pas
dd70: 73 65 64 20 61 73 20 74 68 65 20 74 68 69 72 64  sed as the third
dd80: 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  .** argument to 
dd90: 78 4f 70 65 6e 2e 20 20 54 68 65 20 78 4f 70 65  xOpen.  The xOpe
dda0: 6e 20 6d 65 74 68 6f 64 20 64 6f 65 73 20 6e 6f  n method does no
ddb0: 74 20 68 61 76 65 20 74 6f 0a 2a 2a 20 61 6c 6c  t have to.** all
ddc0: 6f 63 61 74 65 20 74 68 65 20 73 74 72 75 63 74  ocate the struct
ddd0: 75 72 65 3b 20 69 74 20 73 68 6f 75 6c 64 20 6a  ure; it should j
dde0: 75 73 74 20 66 69 6c 6c 20 69 74 20 69 6e 2e 20  ust fill it in. 
ddf0: 20 4e 6f 74 65 20 74 68 61 74 0a 2a 2a 20 74 68   Note that.** th
de00: 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 6d  e xOpen method m
de10: 75 73 74 20 73 65 74 20 74 68 65 20 73 71 6c 69  ust set the sqli
de20: 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64  te3_file.pMethod
de30: 73 20 74 6f 20 65 69 74 68 65 72 0a 2a 2a 20 61  s to either.** a
de40: 20 76 61 6c 69 64 20 5b 73 71 6c 69 74 65 33 5f   valid [sqlite3_
de50: 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65  io_methods] obje
de60: 63 74 20 6f 72 20 74 6f 20 4e 55 4c 4c 2e 20 20  ct or to NULL.  
de70: 78 4f 70 65 6e 20 6d 75 73 74 20 64 6f 0a 2a 2a  xOpen must do.**
de80: 20 74 68 69 73 20 65 76 65 6e 20 69 66 20 74 68   this even if th
de90: 65 20 6f 70 65 6e 20 66 61 69 6c 73 2e 20 20 53  e open fails.  S
dea0: 51 4c 69 74 65 20 65 78 70 65 63 74 73 20 74 68  QLite expects th
deb0: 61 74 20 74 68 65 20 73 71 6c 69 74 65 33 5f 66  at the sqlite3_f
dec0: 69 6c 65 2e 70 4d 65 74 68 6f 64 73 0a 2a 2a 20  ile.pMethods.** 
ded0: 65 6c 65 6d 65 6e 74 20 77 69 6c 6c 20 62 65 20  element will be 
dee0: 76 61 6c 69 64 20 61 66 74 65 72 20 78 4f 70 65  valid after xOpe
def0: 6e 20 72 65 74 75 72 6e 73 20 72 65 67 61 72 64  n returns regard
df00: 6c 65 73 73 20 6f 66 20 74 68 65 20 73 75 63 63  less of the succ
df10: 65 73 73 0a 2a 2a 20 6f 72 20 66 61 69 6c 75 72  ess.** or failur
df20: 65 20 6f 66 20 74 68 65 20 78 4f 70 65 6e 20 63  e of the xOpen c
df30: 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 73 71 6c  all..**.** [[sql
df40: 69 74 65 33 5f 76 66 73 2e 78 41 63 63 65 73 73  ite3_vfs.xAccess
df50: 5d 5d 0a 2a 2a 20 5e 54 68 65 20 66 6c 61 67 73  ]].** ^The flags
df60: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 41 63   argument to xAc
df70: 63 65 73 73 28 29 20 6d 61 79 20 62 65 20 5b 53  cess() may be [S
df80: 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49  QLITE_ACCESS_EXI
df90: 53 54 53 5d 0a 2a 2a 20 74 6f 20 74 65 73 74 20  STS].** to test 
dfa0: 66 6f 72 20 74 68 65 20 65 78 69 73 74 65 6e 63  for the existenc
dfb0: 65 20 6f 66 20 61 20 66 69 6c 65 2c 20 6f 72 20  e of a file, or 
dfc0: 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52  [SQLITE_ACCESS_R
dfd0: 45 41 44 57 52 49 54 45 5d 20 74 6f 0a 2a 2a 20  EADWRITE] to.** 
dfe0: 74 65 73 74 20 77 68 65 74 68 65 72 20 61 20 66  test whether a f
dff0: 69 6c 65 20 69 73 20 72 65 61 64 61 62 6c 65 20  ile is readable 
e000: 61 6e 64 20 77 72 69 74 61 62 6c 65 2c 20 6f 72  and writable, or
e010: 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f   [SQLITE_ACCESS_
e020: 52 45 41 44 5d 0a 2a 2a 20 74 6f 20 74 65 73 74  READ].** to test
e030: 20 77 68 65 74 68 65 72 20 61 20 66 69 6c 65 20   whether a file 
e040: 69 73 20 61 74 20 6c 65 61 73 74 20 72 65 61 64  is at least read
e050: 61 62 6c 65 2e 20 20 20 54 68 65 20 66 69 6c 65  able.   The file
e060: 20 63 61 6e 20 62 65 20 61 0a 2a 2a 20 64 69 72   can be a.** dir
e070: 65 63 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 53  ectory..**.** ^S
e080: 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 77 61 79  QLite will alway
e090: 73 20 61 6c 6c 6f 63 61 74 65 20 61 74 20 6c 65  s allocate at le
e0a0: 61 73 74 20 6d 78 50 61 74 68 6e 61 6d 65 2b 31  ast mxPathname+1
e0b0: 20 62 79 74 65 73 20 66 6f 72 20 74 68 65 0a 2a   bytes for the.*
e0c0: 2a 20 6f 75 74 70 75 74 20 62 75 66 66 65 72 20  * output buffer 
e0d0: 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 2e 20 20  xFullPathname.  
e0e0: 54 68 65 20 65 78 61 63 74 20 73 69 7a 65 20 6f  The exact size o
e0f0: 66 20 74 68 65 20 6f 75 74 70 75 74 20 62 75 66  f the output buf
e100: 66 65 72 0a 2a 2a 20 69 73 20 61 6c 73 6f 20 70  fer.** is also p
e110: 61 73 73 65 64 20 61 73 20 61 20 70 61 72 61 6d  assed as a param
e120: 65 74 65 72 20 74 6f 20 62 6f 74 68 20 20 6d 65  eter to both  me
e130: 74 68 6f 64 73 2e 20 49 66 20 74 68 65 20 6f 75  thods. If the ou
e140: 74 70 75 74 20 62 75 66 66 65 72 0a 2a 2a 20 69  tput buffer.** i
e150: 73 20 6e 6f 74 20 6c 61 72 67 65 20 65 6e 6f 75  s not large enou
e160: 67 68 2c 20 5b 53 51 4c 49 54 45 5f 43 41 4e 54  gh, [SQLITE_CANT
e170: 4f 50 45 4e 5d 20 73 68 6f 75 6c 64 20 62 65 20  OPEN] should be 
e180: 72 65 74 75 72 6e 65 64 2e 20 53 69 6e 63 65 20  returned. Since 
e190: 74 68 69 73 20 69 73 0a 2a 2a 20 68 61 6e 64 6c  this is.** handl
e1a0: 65 64 20 61 73 20 61 20 66 61 74 61 6c 20 65 72  ed as a fatal er
e1b0: 72 6f 72 20 62 79 20 53 51 4c 69 74 65 2c 20 76  ror by SQLite, v
e1c0: 66 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  fs implementatio
e1d0: 6e 73 20 73 68 6f 75 6c 64 20 65 6e 64 65 61 76  ns should endeav
e1e0: 6f 72 0a 2a 2a 20 74 6f 20 70 72 65 76 65 6e 74  or.** to prevent
e1f0: 20 74 68 69 73 20 62 79 20 73 65 74 74 69 6e 67   this by setting
e200: 20 6d 78 50 61 74 68 6e 61 6d 65 20 74 6f 20 61   mxPathname to a
e210: 20 73 75 66 66 69 63 69 65 6e 74 6c 79 20 6c 61   sufficiently la
e220: 72 67 65 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a  rge value..**.**
e230: 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73   The xRandomness
e240: 28 29 2c 20 78 53 6c 65 65 70 28 29 2c 20 78 43  (), xSleep(), xC
e250: 75 72 72 65 6e 74 54 69 6d 65 28 29 2c 20 61 6e  urrentTime(), an
e260: 64 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e  d xCurrentTimeIn
e270: 74 36 34 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61  t64().** interfa
e280: 63 65 73 20 61 72 65 20 6e 6f 74 20 73 74 72 69  ces are not stri
e290: 63 74 6c 79 20 61 20 70 61 72 74 20 6f 66 20 74  ctly a part of t
e2a0: 68 65 20 66 69 6c 65 73 79 73 74 65 6d 2c 20 62  he filesystem, b
e2b0: 75 74 20 74 68 65 79 20 61 72 65 0a 2a 2a 20 69  ut they are.** i
e2c0: 6e 63 6c 75 64 65 64 20 69 6e 20 74 68 65 20 56  ncluded in the V
e2d0: 46 53 20 73 74 72 75 63 74 75 72 65 20 66 6f 72  FS structure for
e2e0: 20 63 6f 6d 70 6c 65 74 65 6e 65 73 73 2e 0a 2a   completeness..*
e2f0: 2a 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73  * The xRandomnes
e300: 73 28 29 20 66 75 6e 63 74 69 6f 6e 20 61 74 74  s() function att
e310: 65 6d 70 74 73 20 74 6f 20 72 65 74 75 72 6e 20  empts to return 
e320: 6e 42 79 74 65 73 20 62 79 74 65 73 0a 2a 2a 20  nBytes bytes.** 
e330: 6f 66 20 67 6f 6f 64 2d 71 75 61 6c 69 74 79 20  of good-quality 
e340: 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f 20  randomness into 
e350: 7a 4f 75 74 2e 20 20 54 68 65 20 72 65 74 75 72  zOut.  The retur
e360: 6e 20 76 61 6c 75 65 20 69 73 0a 2a 2a 20 74 68  n value is.** th
e370: 65 20 61 63 74 75 61 6c 20 6e 75 6d 62 65 72 20  e actual number 
e380: 6f 66 20 62 79 74 65 73 20 6f 66 20 72 61 6e 64  of bytes of rand
e390: 6f 6d 6e 65 73 73 20 6f 62 74 61 69 6e 65 64 2e  omness obtained.
e3a0: 0a 2a 2a 20 54 68 65 20 78 53 6c 65 65 70 28 29  .** The xSleep()
e3b0: 20 6d 65 74 68 6f 64 20 63 61 75 73 65 73 20 74   method causes t
e3c0: 68 65 20 63 61 6c 6c 69 6e 67 20 74 68 72 65 61  he calling threa
e3d0: 64 20 74 6f 20 73 6c 65 65 70 20 66 6f 72 20 61  d to sleep for a
e3e0: 74 0a 2a 2a 20 6c 65 61 73 74 20 74 68 65 20 6e  t.** least the n
e3f0: 75 6d 62 65 72 20 6f 66 20 6d 69 63 72 6f 73 65  umber of microse
e400: 63 6f 6e 64 73 20 67 69 76 65 6e 2e 20 20 5e 54  conds given.  ^T
e410: 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d 65 28  he xCurrentTime(
e420: 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 72 65 74 75  ).** method retu
e430: 72 6e 73 20 61 20 4a 75 6c 69 61 6e 20 44 61 79  rns a Julian Day
e440: 20 4e 75 6d 62 65 72 20 66 6f 72 20 74 68 65 20   Number for the 
e450: 63 75 72 72 65 6e 74 20 64 61 74 65 20 61 6e 64  current date and
e460: 20 74 69 6d 65 20 61 73 0a 2a 2a 20 61 20 66 6c   time as.** a fl
e470: 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c  oating point val
e480: 75 65 2e 0a 2a 2a 20 5e 54 68 65 20 78 43 75 72  ue..** ^The xCur
e490: 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 20  rentTimeInt64() 
e4a0: 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 2c 20  method returns, 
e4b0: 61 73 20 61 6e 20 69 6e 74 65 67 65 72 2c 20 74  as an integer, t
e4c0: 68 65 20 4a 75 6c 69 61 6e 0a 2a 2a 20 44 61 79  he Julian.** Day
e4d0: 20 4e 75 6d 62 65 72 20 6d 75 6c 74 69 70 6c 69   Number multipli
e4e0: 65 64 20 62 79 20 38 36 34 30 30 30 30 30 20 28  ed by 86400000 (
e4f0: 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69  the number of mi
e500: 6c 6c 69 73 65 63 6f 6e 64 73 20 69 6e 20 0a 2a  lliseconds in .*
e510: 2a 20 61 20 32 34 2d 68 6f 75 72 20 64 61 79 29  * a 24-hour day)
e520: 2e 20 20 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77  .  .** ^SQLite w
e530: 69 6c 6c 20 75 73 65 20 74 68 65 20 78 43 75 72  ill use the xCur
e540: 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 20  rentTimeInt64() 
e550: 6d 65 74 68 6f 64 20 74 6f 20 67 65 74 20 74 68  method to get th
e560: 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 64 61 74  e current.** dat
e570: 65 20 61 6e 64 20 74 69 6d 65 20 69 66 20 74 68  e and time if th
e580: 61 74 20 6d 65 74 68 6f 64 20 69 73 20 61 76 61  at method is ava
e590: 69 6c 61 62 6c 65 20 28 69 66 20 69 56 65 72 73  ilable (if iVers
e5a0: 69 6f 6e 20 69 73 20 32 20 6f 72 20 0a 2a 2a 20  ion is 2 or .** 
e5b0: 67 72 65 61 74 65 72 20 61 6e 64 20 74 68 65 20  greater and the 
e5c0: 66 75 6e 63 74 69 6f 6e 20 70 6f 69 6e 74 65 72  function pointer
e5d0: 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 29 20 61 6e   is not NULL) an
e5e0: 64 20 77 69 6c 6c 20 66 61 6c 6c 20 62 61 63 6b  d will fall back
e5f0: 0a 2a 2a 20 74 6f 20 78 43 75 72 72 65 6e 74 54  .** to xCurrentT
e600: 69 6d 65 28 29 20 69 66 20 78 43 75 72 72 65 6e  ime() if xCurren
e610: 74 54 69 6d 65 49 6e 74 36 34 28 29 20 69 73 20  tTimeInt64() is 
e620: 75 6e 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 0a  unavailable..**.
e630: 2a 2a 20 5e 54 68 65 20 78 53 65 74 53 79 73 74  ** ^The xSetSyst
e640: 65 6d 43 61 6c 6c 28 29 2c 20 78 47 65 74 53 79  emCall(), xGetSy
e650: 73 74 65 6d 43 61 6c 6c 28 29 2c 20 61 6e 64 20  stemCall(), and 
e660: 78 4e 65 73 74 53 79 73 74 65 6d 43 61 6c 6c 28  xNestSystemCall(
e670: 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20  ) interfaces.** 
e680: 61 72 65 20 6e 6f 74 20 75 73 65 64 20 62 79 20  are not used by 
e690: 74 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 2e  the SQLite core.
e6a0: 20 20 54 68 65 73 65 20 6f 70 74 69 6f 6e 61 6c    These optional
e6b0: 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20   interfaces are 
e6c0: 70 72 6f 76 69 64 65 64 0a 2a 2a 20 62 79 20 73  provided.** by s
e6d0: 6f 6d 65 20 56 46 53 65 73 20 74 6f 20 66 61 63  ome VFSes to fac
e6e0: 69 6c 69 74 61 74 65 20 74 65 73 74 69 6e 67 20  ilitate testing 
e6f0: 6f 66 20 74 68 65 20 56 46 53 20 63 6f 64 65 2e  of the VFS code.
e700: 20 42 79 20 6f 76 65 72 72 69 64 69 6e 67 20 0a   By overriding .
e710: 2a 2a 20 73 79 73 74 65 6d 20 63 61 6c 6c 73 20  ** system calls 
e720: 77 69 74 68 20 66 75 6e 63 74 69 6f 6e 73 20 75  with functions u
e730: 6e 64 65 72 20 69 74 73 20 63 6f 6e 74 72 6f 6c  nder its control
e740: 2c 20 61 20 74 65 73 74 20 70 72 6f 67 72 61 6d  , a test program
e750: 20 63 61 6e 0a 2a 2a 20 73 69 6d 75 6c 61 74 65   can.** simulate
e760: 20 66 61 75 6c 74 73 20 61 6e 64 20 65 72 72 6f   faults and erro
e770: 72 20 63 6f 6e 64 69 74 69 6f 6e 73 20 74 68 61  r conditions tha
e780: 74 20 77 6f 75 6c 64 20 6f 74 68 65 72 77 69 73  t would otherwis
e790: 65 20 62 65 20 64 69 66 66 69 63 75 6c 74 0a 2a  e be difficult.*
e7a0: 2a 20 6f 72 20 69 6d 70 6f 73 73 69 62 6c 65 20  * or impossible 
e7b0: 74 6f 20 69 6e 64 75 63 65 2e 20 20 54 68 65 20  to induce.  The 
e7c0: 73 65 74 20 6f 66 20 73 79 73 74 65 6d 20 63 61  set of system ca
e7d0: 6c 6c 73 20 74 68 61 74 20 63 61 6e 20 62 65 20  lls that can be 
e7e0: 6f 76 65 72 72 69 64 64 65 6e 0a 2a 2a 20 76 61  overridden.** va
e7f0: 72 69 65 73 20 66 72 6f 6d 20 6f 6e 65 20 56 46  ries from one VF
e800: 53 20 74 6f 20 61 6e 6f 74 68 65 72 2c 20 61 6e  S to another, an
e810: 64 20 66 72 6f 6d 20 6f 6e 65 20 76 65 72 73 69  d from one versi
e820: 6f 6e 20 6f 66 20 74 68 65 20 73 61 6d 65 20 56  on of the same V
e830: 46 53 20 74 6f 20 74 68 65 0a 2a 2a 20 6e 65 78  FS to the.** nex
e840: 74 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73  t.  Applications
e850: 20 74 68 61 74 20 75 73 65 20 74 68 65 73 65 20   that use these 
e860: 69 6e 74 65 72 66 61 63 65 73 20 6d 75 73 74 20  interfaces must 
e870: 62 65 20 70 72 65 70 61 72 65 64 20 66 6f 72 20  be prepared for 
e880: 61 6e 79 0a 2a 2a 20 6f 72 20 61 6c 6c 20 6f 66  any.** or all of
e890: 20 74 68 65 73 65 20 69 6e 74 65 72 66 61 63 65   these interface
e8a0: 73 20 74 6f 20 62 65 20 4e 55 4c 4c 20 6f 72 20  s to be NULL or 
e8b0: 66 6f 72 20 74 68 65 69 72 20 62 65 68 61 76 69  for their behavi
e8c0: 6f 72 20 74 6f 20 63 68 61 6e 67 65 0a 2a 2a 20  or to change.** 
e8d0: 66 72 6f 6d 20 6f 6e 65 20 72 65 6c 65 61 73 65  from one release
e8e0: 20 74 6f 20 74 68 65 20 6e 65 78 74 2e 20 20 41   to the next.  A
e8f0: 70 70 6c 69 63 61 74 69 6f 6e 73 20 6d 75 73 74  pplications must
e900: 20 6e 6f 74 20 61 74 74 65 6d 70 74 20 74 6f 20   not attempt to 
e910: 61 63 63 65 73 73 0a 2a 2a 20 61 6e 79 20 6f 66  access.** any of
e920: 20 74 68 65 73 65 20 6d 65 74 68 6f 64 73 20 69   these methods i
e930: 66 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20 6f  f the iVersion o
e940: 66 20 74 68 65 20 56 46 53 20 69 73 20 6c 65 73  f the VFS is les
e950: 73 20 74 68 61 6e 20 33 2e 0a 2a 2f 0a 74 79 70  s than 3..*/.typ
e960: 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69  edef struct sqli
e970: 74 65 33 5f 76 66 73 20 73 71 6c 69 74 65 33 5f  te3_vfs sqlite3_
e980: 76 66 73 3b 0a 74 79 70 65 64 65 66 20 76 6f 69  vfs;.typedef voi
e990: 64 20 28 2a 73 71 6c 69 74 65 33 5f 73 79 73 63  d (*sqlite3_sysc
e9a0: 61 6c 6c 5f 70 74 72 29 28 76 6f 69 64 29 3b 0a  all_ptr)(void);.
e9b0: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76  struct sqlite3_v
e9c0: 66 73 20 7b 0a 20 20 69 6e 74 20 69 56 65 72 73  fs {.  int iVers
e9d0: 69 6f 6e 3b 20 20 20 20 20 20 20 20 20 20 20 20  ion;            
e9e0: 2f 2a 20 53 74 72 75 63 74 75 72 65 20 76 65 72  /* Structure ver
e9f0: 73 69 6f 6e 20 6e 75 6d 62 65 72 20 28 63 75 72  sion number (cur
ea00: 72 65 6e 74 6c 79 20 33 29 20 2a 2f 0a 20 20 69  rently 3) */.  i
ea10: 6e 74 20 73 7a 4f 73 46 69 6c 65 3b 20 20 20 20  nt szOsFile;    
ea20: 20 20 20 20 20 20 20 20 2f 2a 20 53 69 7a 65 20          /* Size 
ea30: 6f 66 20 73 75 62 63 6c 61 73 73 65 64 20 73 71  of subclassed sq
ea40: 6c 69 74 65 33 5f 66 69 6c 65 20 2a 2f 0a 20 20  lite3_file */.  
ea50: 69 6e 74 20 6d 78 50 61 74 68 6e 61 6d 65 3b 20  int mxPathname; 
ea60: 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69           /* Maxi
ea70: 6d 75 6d 20 66 69 6c 65 20 70 61 74 68 6e 61 6d  mum file pathnam
ea80: 65 20 6c 65 6e 67 74 68 20 2a 2f 0a 20 20 73 71  e length */.  sq
ea90: 6c 69 74 65 33 5f 76 66 73 20 2a 70 4e 65 78 74  lite3_vfs *pNext
eaa0: 3b 20 20 20 20 20 20 2f 2a 20 4e 65 78 74 20 72  ;      /* Next r
eab0: 65 67 69 73 74 65 72 65 64 20 56 46 53 20 2a 2f  egistered VFS */
eac0: 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
ead0: 4e 61 6d 65 3b 20 20 20 20 20 20 20 2f 2a 20 4e  Name;       /* N
eae0: 61 6d 65 20 6f 66 20 74 68 69 73 20 76 69 72 74  ame of this virt
eaf0: 75 61 6c 20 66 69 6c 65 20 73 79 73 74 65 6d 20  ual file system 
eb00: 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 44  */.  void *pAppD
eb10: 61 74 61 3b 20 20 20 20 20 20 20 20 20 20 2f 2a  ata;          /*
eb20: 20 50 6f 69 6e 74 65 72 20 74 6f 20 61 70 70 6c   Pointer to appl
eb30: 69 63 61 74 69 6f 6e 2d 73 70 65 63 69 66 69 63  ication-specific
eb40: 20 64 61 74 61 20 2a 2f 0a 20 20 69 6e 74 20 28   data */.  int (
eb50: 2a 78 4f 70 65 6e 29 28 73 71 6c 69 74 65 33 5f  *xOpen)(sqlite3_
eb60: 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  vfs*, const char
eb70: 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69 74 65 33   *zName, sqlite3
eb80: 5f 66 69 6c 65 2a 2c 0a 20 20 20 20 20 20 20 20  _file*,.        
eb90: 20 20 20 20 20 20 20 69 6e 74 20 66 6c 61 67 73         int flags
eba0: 2c 20 69 6e 74 20 2a 70 4f 75 74 46 6c 61 67 73  , int *pOutFlags
ebb0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65 6c 65  );.  int (*xDele
ebc0: 74 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  te)(sqlite3_vfs*
ebd0: 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e  , const char *zN
ebe0: 61 6d 65 2c 20 69 6e 74 20 73 79 6e 63 44 69 72  ame, int syncDir
ebf0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 41 63 63 65  );.  int (*xAcce
ec00: 73 73 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  ss)(sqlite3_vfs*
ec10: 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e  , const char *zN
ec20: 61 6d 65 2c 20 69 6e 74 20 66 6c 61 67 73 2c 20  ame, int flags, 
ec30: 69 6e 74 20 2a 70 52 65 73 4f 75 74 29 3b 0a 20  int *pResOut);. 
ec40: 20 69 6e 74 20 28 2a 78 46 75 6c 6c 50 61 74 68   int (*xFullPath
ec50: 6e 61 6d 65 29 28 73 71 6c 69 74 65 33 5f 76 66  name)(sqlite3_vf
ec60: 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  s*, const char *
ec70: 7a 4e 61 6d 65 2c 20 69 6e 74 20 6e 4f 75 74 2c  zName, int nOut,
ec80: 20 63 68 61 72 20 2a 7a 4f 75 74 29 3b 0a 20 20   char *zOut);.  
ec90: 76 6f 69 64 20 2a 28 2a 78 44 6c 4f 70 65 6e 29  void *(*xDlOpen)
eca0: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63  (sqlite3_vfs*, c
ecb0: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c 65  onst char *zFile
ecc0: 6e 61 6d 65 29 3b 0a 20 20 76 6f 69 64 20 28 2a  name);.  void (*
ecd0: 78 44 6c 45 72 72 6f 72 29 28 73 71 6c 69 74 65  xDlError)(sqlite
ece0: 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6e 42 79 74  3_vfs*, int nByt
ecf0: 65 2c 20 63 68 61 72 20 2a 7a 45 72 72 4d 73 67  e, char *zErrMsg
ed00: 29 3b 0a 20 20 76 6f 69 64 20 28 2a 28 2a 78 44  );.  void (*(*xD
ed10: 6c 53 79 6d 29 28 73 71 6c 69 74 65 33 5f 76 66  lSym)(sqlite3_vf
ed20: 73 2a 2c 76 6f 69 64 2a 2c 20 63 6f 6e 73 74 20  s*,void*, const 
ed30: 63 68 61 72 20 2a 7a 53 79 6d 62 6f 6c 29 29 28  char *zSymbol))(
ed40: 76 6f 69 64 29 3b 0a 20 20 76 6f 69 64 20 28 2a  void);.  void (*
ed50: 78 44 6c 43 6c 6f 73 65 29 28 73 71 6c 69 74 65  xDlClose)(sqlite
ed60: 33 5f 76 66 73 2a 2c 20 76 6f 69 64 2a 29 3b 0a  3_vfs*, void*);.
ed70: 20 20 69 6e 74 20 28 2a 78 52 61 6e 64 6f 6d 6e    int (*xRandomn
ed80: 65 73 73 29 28 73 71 6c 69 74 65 33 5f 76 66 73  ess)(sqlite3_vfs
ed90: 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 63 68  *, int nByte, ch
eda0: 61 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 69 6e 74  ar *zOut);.  int
edb0: 20 28 2a 78 53 6c 65 65 70 29 28 73 71 6c 69 74   (*xSleep)(sqlit
edc0: 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6d 69 63  e3_vfs*, int mic
edd0: 72 6f 73 65 63 6f 6e 64 73 29 3b 0a 20 20 69 6e  roseconds);.  in
ede0: 74 20 28 2a 78 43 75 72 72 65 6e 74 54 69 6d 65  t (*xCurrentTime
edf0: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
ee00: 64 6f 75 62 6c 65 2a 29 3b 0a 20 20 69 6e 74 20  double*);.  int 
ee10: 28 2a 78 47 65 74 4c 61 73 74 45 72 72 6f 72 29  (*xGetLastError)
ee20: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69  (sqlite3_vfs*, i
ee30: 6e 74 2c 20 63 68 61 72 20 2a 29 3b 0a 20 20 2f  nt, char *);.  /
ee40: 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 68 6f  *.  ** The metho
ee50: 64 73 20 61 62 6f 76 65 20 61 72 65 20 69 6e 20  ds above are in 
ee60: 76 65 72 73 69 6f 6e 20 31 20 6f 66 20 74 68 65  version 1 of the
ee70: 20 73 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a 65   sqlite_vfs obje
ee80: 63 74 0a 20 20 2a 2a 20 64 65 66 69 6e 69 74 69  ct.  ** definiti
ee90: 6f 6e 2e 20 20 54 68 6f 73 65 20 74 68 61 74 20  on.  Those that 
eea0: 66 6f 6c 6c 6f 77 20 61 72 65 20 61 64 64 65 64  follow are added
eeb0: 20 69 6e 20 76 65 72 73 69 6f 6e 20 32 20 6f 72   in version 2 or
eec0: 20 6c 61 74 65 72 0a 20 20 2a 2f 0a 20 20 69 6e   later.  */.  in
eed0: 74 20 28 2a 78 43 75 72 72 65 6e 74 54 69 6d 65  t (*xCurrentTime
eee0: 49 6e 74 36 34 29 28 73 71 6c 69 74 65 33 5f 76  Int64)(sqlite3_v
eef0: 66 73 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74  fs*, sqlite3_int
ef00: 36 34 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20  64*);.  /*.  ** 
ef10: 54 68 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76  The methods abov
ef20: 65 20 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e  e are in version
ef30: 73 20 31 20 61 6e 64 20 32 20 6f 66 20 74 68 65  s 1 and 2 of the
ef40: 20 73 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a 65   sqlite_vfs obje
ef50: 63 74 2e 0a 20 20 2a 2a 20 54 68 6f 73 65 20 62  ct..  ** Those b
ef60: 65 6c 6f 77 20 61 72 65 20 66 6f 72 20 76 65 72  elow are for ver
ef70: 73 69 6f 6e 20 33 20 61 6e 64 20 67 72 65 61 74  sion 3 and great
ef80: 65 72 2e 0a 20 20 2a 2f 0a 20 20 69 6e 74 20 28  er..  */.  int (
ef90: 2a 78 53 65 74 53 79 73 74 65 6d 43 61 6c 6c 29  *xSetSystemCall)
efa0: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63  (sqlite3_vfs*, c
efb0: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65  onst char *zName
efc0: 2c 20 73 71 6c 69 74 65 33 5f 73 79 73 63 61 6c  , sqlite3_syscal
efd0: 6c 5f 70 74 72 29 3b 0a 20 20 73 71 6c 69 74 65  l_ptr);.  sqlite
efe0: 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72 20 28 2a  3_syscall_ptr (*
eff0: 78 47 65 74 53 79 73 74 65 6d 43 61 6c 6c 29 28  xGetSystemCall)(
f000: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f  sqlite3_vfs*, co
f010: 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29  nst char *zName)
f020: 3b 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  ;.  const char *
f030: 28 2a 78 4e 65 78 74 53 79 73 74 65 6d 43 61 6c  (*xNextSystemCal
f040: 6c 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  l)(sqlite3_vfs*,
f050: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61   const char *zNa
f060: 6d 65 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54  me);.  /*.  ** T
f070: 68 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65  he methods above
f080: 20 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e 73   are in versions
f090: 20 31 20 74 68 72 6f 75 67 68 20 33 20 6f 66 20   1 through 3 of 
f0a0: 74 68 65 20 73 71 6c 69 74 65 5f 76 66 73 20 6f  the sqlite_vfs o
f0b0: 62 6a 65 63 74 2e 0a 20 20 2a 2a 20 4e 65 77 20  bject..  ** New 
f0c0: 66 69 65 6c 64 73 20 6d 61 79 20 62 65 20 61 70  fields may be ap
f0d0: 70 65 6e 64 65 64 20 69 6e 20 66 75 74 75 72 65  pended in future
f0e0: 20 76 65 72 73 69 6f 6e 73 2e 20 20 54 68 65 20   versions.  The 
f0f0: 69 56 65 72 73 69 6f 6e 0a 20 20 2a 2a 20 76 61  iVersion.  ** va
f100: 6c 75 65 20 77 69 6c 6c 20 69 6e 63 72 65 6d 65  lue will increme
f110: 6e 74 20 77 68 65 6e 65 76 65 72 20 74 68 69 73  nt whenever this
f120: 20 68 61 70 70 65 6e 73 2e 20 0a 20 20 2a 2f 0a   happens. .  */.
f130: 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  };../*.** CAPI3R
f140: 45 46 3a 20 46 6c 61 67 73 20 66 6f 72 20 74 68  EF: Flags for th
f150: 65 20 78 41 63 63 65 73 73 20 56 46 53 20 6d 65  e xAccess VFS me
f160: 74 68 6f 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  thod.**.** These
f170: 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e   integer constan
f180: 74 73 20 63 61 6e 20 62 65 20 75 73 65 64 20 61  ts can be used a
f190: 73 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61  s the third para
f1a0: 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 74 68 65 20  meter to.** the 
f1b0: 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 20 6f  xAccess method o
f1c0: 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 76 66  f an [sqlite3_vf
f1d0: 73 5d 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 79  s] object.  They
f1e0: 20 64 65 74 65 72 6d 69 6e 65 0a 2a 2a 20 77 68   determine.** wh
f1f0: 61 74 20 6b 69 6e 64 20 6f 66 20 70 65 72 6d 69  at kind of permi
f200: 73 73 69 6f 6e 73 20 74 68 65 20 78 41 63 63 65  ssions the xAcce
f210: 73 73 20 6d 65 74 68 6f 64 20 69 73 20 6c 6f 6f  ss method is loo
f220: 6b 69 6e 67 20 66 6f 72 2e 0a 2a 2a 20 57 69 74  king for..** Wit
f230: 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f  h SQLITE_ACCESS_
f240: 45 58 49 53 54 53 2c 20 74 68 65 20 78 41 63 63  EXISTS, the xAcc
f250: 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 73 69  ess method.** si
f260: 6d 70 6c 79 20 63 68 65 63 6b 73 20 77 68 65 74  mply checks whet
f270: 68 65 72 20 74 68 65 20 66 69 6c 65 20 65 78 69  her the file exi
f280: 73 74 73 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c  sts..** With SQL
f290: 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57  ITE_ACCESS_READW
f2a0: 52 49 54 45 2c 20 74 68 65 20 78 41 63 63 65 73  RITE, the xAcces
f2b0: 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65 63  s method.** chec
f2c0: 6b 73 20 77 68 65 74 68 65 72 20 74 68 65 20 6e  ks whether the n
f2d0: 61 6d 65 64 20 64 69 72 65 63 74 6f 72 79 20 69  amed directory i
f2e0: 73 20 62 6f 74 68 20 72 65 61 64 61 62 6c 65 20  s both readable 
f2f0: 61 6e 64 20 77 72 69 74 61 62 6c 65 0a 2a 2a 20  and writable.** 
f300: 28 69 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c  (in other words,
f310: 20 69 66 20 66 69 6c 65 73 20 63 61 6e 20 62 65   if files can be
f320: 20 61 64 64 65 64 2c 20 72 65 6d 6f 76 65 64 2c   added, removed,
f330: 20 61 6e 64 20 72 65 6e 61 6d 65 64 20 77 69 74   and renamed wit
f340: 68 69 6e 0a 2a 2a 20 74 68 65 20 64 69 72 65 63  hin.** the direc
f350: 74 6f 72 79 29 2e 0a 2a 2a 20 54 68 65 20 53 51  tory)..** The SQ
f360: 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44  LITE_ACCESS_READ
f370: 57 52 49 54 45 20 63 6f 6e 73 74 61 6e 74 20 69  WRITE constant i
f380: 73 20 63 75 72 72 65 6e 74 6c 79 20 75 73 65 64  s currently used
f390: 20 6f 6e 6c 79 20 62 79 20 74 68 65 0a 2a 2a 20   only by the.** 
f3a0: 5b 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65  [temp_store_dire
f3b0: 63 74 6f 72 79 20 70 72 61 67 6d 61 5d 2c 20 74  ctory pragma], t
f3c0: 68 6f 75 67 68 20 74 68 69 73 20 63 6f 75 6c 64  hough this could
f3d0: 20 63 68 61 6e 67 65 20 69 6e 20 61 20 66 75 74   change in a fut
f3e0: 75 72 65 0a 2a 2a 20 72 65 6c 65 61 73 65 20 6f  ure.** release o
f3f0: 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 57 69 74  f SQLite..** Wit
f400: 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f  h SQLITE_ACCESS_
f410: 52 45 41 44 2c 20 74 68 65 20 78 41 63 63 65 73  READ, the xAcces
f420: 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65 63  s method.** chec
f430: 6b 73 20 77 68 65 74 68 65 72 20 74 68 65 20 66  ks whether the f
f440: 69 6c 65 20 69 73 20 72 65 61 64 61 62 6c 65 2e  ile is readable.
f450: 20 20 54 68 65 20 53 51 4c 49 54 45 5f 41 43 43    The SQLITE_ACC
f460: 45 53 53 5f 52 45 41 44 20 63 6f 6e 73 74 61 6e  ESS_READ constan
f470: 74 20 69 73 0a 2a 2a 20 63 75 72 72 65 6e 74 6c  t is.** currentl
f480: 79 20 75 6e 75 73 65 64 2c 20 74 68 6f 75 67 68  y unused, though
f490: 20 69 74 20 6d 69 67 68 74 20 62 65 20 75 73 65   it might be use
f4a0: 64 20 69 6e 20 61 20 66 75 74 75 72 65 20 72 65  d in a future re
f4b0: 6c 65 61 73 65 20 6f 66 0a 2a 2a 20 53 51 4c 69  lease of.** SQLi
f4c0: 74 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  te..*/.#define S
f4d0: 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49  QLITE_ACCESS_EXI
f4e0: 53 54 53 20 20 20 20 30 0a 23 64 65 66 69 6e 65  STS    0.#define
f4f0: 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52   SQLITE_ACCESS_R
f500: 45 41 44 57 52 49 54 45 20 31 20 20 20 2f 2a 20  EADWRITE 1   /* 
f510: 55 73 65 64 20 62 79 20 50 52 41 47 4d 41 20 74  Used by PRAGMA t
f520: 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 63 74  emp_store_direct
f530: 6f 72 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ory */.#define S
f540: 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41  QLITE_ACCESS_REA
f550: 44 20 20 20 20 20 20 32 20 20 20 2f 2a 20 55 6e  D      2   /* Un
f560: 75 73 65 64 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43  used */../*.** C
f570: 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73 20 66  API3REF: Flags f
f580: 6f 72 20 74 68 65 20 78 53 68 6d 4c 6f 63 6b 20  or the xShmLock 
f590: 56 46 53 20 6d 65 74 68 6f 64 0a 2a 2a 0a 2a 2a  VFS method.**.**
f5a0: 20 54 68 65 73 65 20 69 6e 74 65 67 65 72 20 63   These integer c
f5b0: 6f 6e 73 74 61 6e 74 73 20 64 65 66 69 6e 65 20  onstants define 
f5c0: 74 68 65 20 76 61 72 69 6f 75 73 20 6c 6f 63 6b  the various lock
f5d0: 69 6e 67 20 6f 70 65 72 61 74 69 6f 6e 73 0a 2a  ing operations.*
f5e0: 2a 20 61 6c 6c 6f 77 65 64 20 62 79 20 74 68 65  * allowed by the
f5f0: 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64   xShmLock method
f600: 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f   of [sqlite3_io_
f610: 6d 65 74 68 6f 64 73 5d 2e 20 20 54 68 65 0a 2a  methods].  The.*
f620: 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 72 65 20  * following are 
f630: 74 68 65 20 6f 6e 6c 79 20 6c 65 67 61 6c 20 63  the only legal c
f640: 6f 6d 62 69 6e 61 74 69 6f 6e 73 20 6f 66 20 66  ombinations of f
f650: 6c 61 67 73 20 74 6f 20 74 68 65 0a 2a 2a 20 78  lags to the.** x
f660: 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 3a 0a  ShmLock method:.
f670: 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c  **.** <ul>.** <l
f680: 69 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4c  i>  SQLITE_SHM_L
f690: 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d  OCK | SQLITE_SHM
f6a0: 5f 53 48 41 52 45 44 0a 2a 2a 20 3c 6c 69 3e 20  _SHARED.** <li> 
f6b0: 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b   SQLITE_SHM_LOCK
f6c0: 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45 58   | SQLITE_SHM_EX
f6d0: 43 4c 55 53 49 56 45 0a 2a 2a 20 3c 6c 69 3e 20  CLUSIVE.** <li> 
f6e0: 20 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f   SQLITE_SHM_UNLO
f6f0: 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f  CK | SQLITE_SHM_
f700: 53 48 41 52 45 44 0a 2a 2a 20 3c 6c 69 3e 20 20  SHARED.** <li>  
f710: 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43  SQLITE_SHM_UNLOC
f720: 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45  K | SQLITE_SHM_E
f730: 58 43 4c 55 53 49 56 45 0a 2a 2a 20 3c 2f 75 6c  XCLUSIVE.** </ul
f740: 3e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 75 6e 6c  >.**.** When unl
f750: 6f 63 6b 69 6e 67 2c 20 74 68 65 20 73 61 6d 65  ocking, the same
f760: 20 53 48 41 52 45 44 20 6f 72 20 45 58 43 4c 55   SHARED or EXCLU
f770: 53 49 56 45 20 66 6c 61 67 20 6d 75 73 74 20 62  SIVE flag must b
f780: 65 20 73 75 70 70 6c 69 65 64 20 61 73 0a 2a 2a  e supplied as.**
f790: 20 77 61 73 20 67 69 76 65 6e 20 6f 6e 20 74 68   was given on th
f7a0: 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20  e corresponding 
f7b0: 6c 6f 63 6b 2e 20 20 0a 2a 2a 0a 2a 2a 20 54 68  lock.  .**.** Th
f7c0: 65 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f  e xShmLock metho
f7d0: 64 20 63 61 6e 20 74 72 61 6e 73 69 74 69 6f 6e  d can transition
f7e0: 20 62 65 74 77 65 65 6e 20 75 6e 6c 6f 63 6b 65   between unlocke
f7f0: 64 20 61 6e 64 20 53 48 41 52 45 44 20 6f 72 0a  d and SHARED or.
f800: 2a 2a 20 62 65 74 77 65 65 6e 20 75 6e 6c 6f 63  ** between unloc
f810: 6b 65 64 20 61 6e 64 20 45 58 43 4c 55 53 49 56  ked and EXCLUSIV
f820: 45 2e 20 20 49 74 20 63 61 6e 6e 6f 74 20 74 72  E.  It cannot tr
f830: 61 6e 73 69 74 69 6f 6e 20 62 65 74 77 65 65 6e  ansition between
f840: 20 53 48 41 52 45 44 0a 2a 2a 20 61 6e 64 20 45   SHARED.** and E
f850: 58 43 4c 55 53 49 56 45 2e 0a 2a 2f 0a 23 64 65  XCLUSIVE..*/.#de
f860: 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f  fine SQLITE_SHM_
f870: 55 4e 4c 4f 43 4b 20 20 20 20 20 20 20 31 0a 23  UNLOCK       1.#
f880: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48  define SQLITE_SH
f890: 4d 5f 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 32  M_LOCK         2
f8a0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
f8b0: 53 48 4d 5f 53 48 41 52 45 44 20 20 20 20 20 20  SHM_SHARED      
f8c0: 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   4.#define SQLIT
f8d0: 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 45 20  E_SHM_EXCLUSIVE 
f8e0: 20 20 20 38 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49     8../*.** CAPI
f8f0: 33 52 45 46 3a 20 4d 61 78 69 6d 75 6d 20 78 53  3REF: Maximum xS
f900: 68 6d 4c 6f 63 6b 20 69 6e 64 65 78 0a 2a 2a 0a  hmLock index.**.
f910: 2a 2a 20 54 68 65 20 78 53 68 6d 4c 6f 63 6b 20  ** The xShmLock 
f920: 6d 65 74 68 6f 64 20 6f 6e 20 5b 73 71 6c 69 74  method on [sqlit
f930: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6d  e3_io_methods] m
f940: 61 79 20 75 73 65 20 76 61 6c 75 65 73 0a 2a 2a  ay use values.**
f950: 20 62 65 74 77 65 65 6e 20 30 20 61 6e 64 20 74   between 0 and t
f960: 68 69 73 20 75 70 70 65 72 20 62 6f 75 6e 64 20  his upper bound 
f970: 61 73 20 69 74 73 20 22 6f 66 66 73 65 74 22 20  as its "offset" 
f980: 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 54 68 65  argument..** The
f990: 20 53 51 4c 69 74 65 20 63 6f 72 65 20 77 69 6c   SQLite core wil
f9a0: 6c 20 6e 65 76 65 72 20 61 74 74 65 6d 70 74 20  l never attempt 
f9b0: 74 6f 20 61 63 71 75 69 72 65 20 6f 72 20 72 65  to acquire or re
f9c0: 6c 65 61 73 65 20 61 0a 2a 2a 20 6c 6f 63 6b 20  lease a.** lock 
f9d0: 6f 75 74 73 69 64 65 20 6f 66 20 74 68 69 73 20  outside of this 
f9e0: 72 61 6e 67 65 0a 2a 2f 0a 23 64 65 66 69 6e 65  range.*/.#define
f9f0: 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4e 4c 4f 43   SQLITE_SHM_NLOC
fa00: 4b 20 20 20 20 20 20 20 20 38 0a 0a 0a 2f 2a 0a  K        8.../*.
fa10: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e 69  ** CAPI3REF: Ini
fa20: 74 69 61 6c 69 7a 65 20 54 68 65 20 53 51 4c 69  tialize The SQLi
fa30: 74 65 20 4c 69 62 72 61 72 79 0a 2a 2a 0a 2a 2a  te Library.**.**
fa40: 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e   ^The sqlite3_in
fa50: 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74 69  itialize() routi
fa60: 6e 65 20 69 6e 69 74 69 61 6c 69 7a 65 73 20 74  ne initializes t
fa70: 68 65 0a 2a 2a 20 53 51 4c 69 74 65 20 6c 69 62  he.** SQLite lib
fa80: 72 61 72 79 2e 20 20 5e 54 68 65 20 73 71 6c 69  rary.  ^The sqli
fa90: 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 72  te3_shutdown() r
faa0: 6f 75 74 69 6e 65 0a 2a 2a 20 64 65 61 6c 6c 6f  outine.** deallo
fab0: 63 61 74 65 73 20 61 6e 79 20 72 65 73 6f 75 72  cates any resour
fac0: 63 65 73 20 74 68 61 74 20 77 65 72 65 20 61 6c  ces that were al
fad0: 6c 6f 63 61 74 65 64 20 62 79 20 73 71 6c 69 74  located by sqlit
fae0: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 2e  e3_initialize().
faf0: 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
fb00: 65 73 20 61 72 65 20 64 65 73 69 67 6e 65 64 20  es are designed 
fb10: 74 6f 20 61 69 64 20 69 6e 20 70 72 6f 63 65 73  to aid in proces
fb20: 73 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e  s initialization
fb30: 20 61 6e 64 0a 2a 2a 20 73 68 75 74 64 6f 77 6e   and.** shutdown
fb40: 20 6f 6e 20 65 6d 62 65 64 64 65 64 20 73 79 73   on embedded sys
fb50: 74 65 6d 73 2e 20 20 57 6f 72 6b 73 74 61 74 69  tems.  Workstati
fb60: 6f 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20  on applications 
fb70: 75 73 69 6e 67 0a 2a 2a 20 53 51 4c 69 74 65 20  using.** SQLite 
fb80: 6e 6f 72 6d 61 6c 6c 79 20 64 6f 20 6e 6f 74 20  normally do not 
fb90: 6e 65 65 64 20 74 6f 20 69 6e 76 6f 6b 65 20 65  need to invoke e
fba0: 69 74 68 65 72 20 6f 66 20 74 68 65 73 65 20 72  ither of these r
fbb0: 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 41  outines..**.** A
fbc0: 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33   call to sqlite3
fbd0: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73  _initialize() is
fbe0: 20 61 6e 20 22 65 66 66 65 63 74 69 76 65 22 20   an "effective" 
fbf0: 63 61 6c 6c 20 69 66 20 69 74 20 69 73 0a 2a 2a  call if it is.**
fc00: 20 74 68 65 20 66 69 72 73 74 20 74 69 6d 65 20   the first time 
fc10: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
fc20: 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 20  ze() is invoked 
fc30: 64 75 72 69 6e 67 20 74 68 65 20 6c 69 66 65 74  during the lifet
fc40: 69 6d 65 20 6f 66 0a 2a 2a 20 74 68 65 20 70 72  ime of.** the pr
fc50: 6f 63 65 73 73 2c 20 6f 72 20 69 66 20 69 74 20  ocess, or if it 
fc60: 69 73 20 74 68 65 20 66 69 72 73 74 20 74 69 6d  is the first tim
fc70: 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  e sqlite3_initia
fc80: 6c 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65  lize() is invoke
fc90: 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61  d.** following a
fca0: 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33   call to sqlite3
fcb0: 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 5e 28  _shutdown().  ^(
fcc0: 4f 6e 6c 79 20 61 6e 20 65 66 66 65 63 74 69 76  Only an effectiv
fcd0: 65 20 63 61 6c 6c 0a 2a 2a 20 6f 66 20 73 71 6c  e call.** of sql
fce0: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
fcf0: 29 20 64 6f 65 73 20 61 6e 79 20 69 6e 69 74 69  ) does any initi
fd00: 61 6c 69 7a 61 74 69 6f 6e 2e 20 20 41 6c 6c 20  alization.  All 
fd10: 6f 74 68 65 72 20 63 61 6c 6c 73 0a 2a 2a 20 61  other calls.** a
fd20: 72 65 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f  re harmless no-o
fd30: 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 41 20 63 61  ps.)^.**.** A ca
fd40: 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68  ll to sqlite3_sh
fd50: 75 74 64 6f 77 6e 28 29 20 69 73 20 61 6e 20 22  utdown() is an "
fd60: 65 66 66 65 63 74 69 76 65 22 20 63 61 6c 6c 20  effective" call 
fd70: 69 66 20 69 74 20 69 73 20 74 68 65 20 66 69 72  if it is the fir
fd80: 73 74 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 73 71  st.** call to sq
fd90: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
fda0: 20 73 69 6e 63 65 20 74 68 65 20 6c 61 73 74 20   since the last 
fdb0: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
fdc0: 7a 65 28 29 2e 20 20 5e 28 4f 6e 6c 79 0a 2a 2a  ze().  ^(Only.**
fdd0: 20 61 6e 20 65 66 66 65 63 74 69 76 65 20 63 61   an effective ca
fde0: 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68  ll to sqlite3_sh
fdf0: 75 74 64 6f 77 6e 28 29 20 64 6f 65 73 20 61 6e  utdown() does an
fe00: 79 20 64 65 69 6e 69 74 69 61 6c 69 7a 61 74 69  y deinitializati
fe10: 6f 6e 2e 0a 2a 2a 20 41 6c 6c 20 6f 74 68 65 72  on..** All other
fe20: 20 76 61 6c 69 64 20 63 61 6c 6c 73 20 74 6f 20   valid calls to 
fe30: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
fe40: 28 29 20 61 72 65 20 68 61 72 6d 6c 65 73 73 20  () are harmless 
fe50: 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20  no-ops.)^.**.** 
fe60: 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  The sqlite3_init
fe70: 69 61 6c 69 7a 65 28 29 20 69 6e 74 65 72 66 61  ialize() interfa
fe80: 63 65 20 69 73 20 74 68 72 65 61 64 73 61 66 65  ce is threadsafe
fe90: 2c 20 62 75 74 20 73 71 6c 69 74 65 33 5f 73 68  , but sqlite3_sh
fea0: 75 74 64 6f 77 6e 28 29 0a 2a 2a 20 69 73 20 6e  utdown().** is n
feb0: 6f 74 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33  ot.  The sqlite3
fec0: 5f 73 68 75 74 64 6f 77 6e 28 29 20 69 6e 74 65  _shutdown() inte
fed0: 72 66 61 63 65 20 6d 75 73 74 20 6f 6e 6c 79 20  rface must only 
fee0: 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 61  be called from a
fef0: 0a 2a 2a 20 73 69 6e 67 6c 65 20 74 68 72 65 61  .** single threa
ff00: 64 2e 20 20 41 6c 6c 20 6f 70 65 6e 20 5b 64 61  d.  All open [da
ff10: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
ff20: 6e 73 5d 20 6d 75 73 74 20 62 65 20 63 6c 6f 73  ns] must be clos
ff30: 65 64 20 61 6e 64 20 61 6c 6c 0a 2a 2a 20 6f 74  ed and all.** ot
ff40: 68 65 72 20 53 51 4c 69 74 65 20 72 65 73 6f 75  her SQLite resou
ff50: 72 63 65 73 20 6d 75 73 74 20 62 65 20 64 65 61  rces must be dea
ff60: 6c 6c 6f 63 61 74 65 64 20 70 72 69 6f 72 20 74  llocated prior t
ff70: 6f 20 69 6e 76 6f 6b 69 6e 67 0a 2a 2a 20 73 71  o invoking.** sq
ff80: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
ff90: 2e 0a 2a 2a 0a 2a 2a 20 41 6d 6f 6e 67 20 6f 74  ..**.** Among ot
ffa0: 68 65 72 20 74 68 69 6e 67 73 2c 20 5e 73 71 6c  her things, ^sql
ffb0: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
ffc0: 29 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 0a 2a 2a  ) will invoke.**
ffd0: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74   sqlite3_os_init
ffe0: 28 29 2e 20 20 53 69 6d 69 6c 61 72 6c 79 2c 20  ().  Similarly, 
fff0: 5e 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77  ^sqlite3_shutdow
10000 6e 28 29 0a 2a 2a 20 77 69 6c 6c 20 69 6e 76 6f  n().** will invo
10010 6b 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e  ke sqlite3_os_en
10020 64 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  d()..**.** ^The 
10030 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
10040 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74  ze() routine ret
10050 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  urns [SQLITE_OK]
10060 20 6f 6e 20 73 75 63 63 65 73 73 2e 0a 2a 2a 20   on success..** 
10070 5e 49 66 20 66 6f 72 20 73 6f 6d 65 20 72 65 61  ^If for some rea
10080 73 6f 6e 2c 20 73 71 6c 69 74 65 33 5f 69 6e 69  son, sqlite3_ini
10090 74 69 61 6c 69 7a 65 28 29 20 69 73 20 75 6e 61  tialize() is una
100a0 62 6c 65 20 74 6f 20 69 6e 69 74 69 61 6c 69 7a  ble to initializ
100b0 65 0a 2a 2a 20 74 68 65 20 6c 69 62 72 61 72 79  e.** the library
100c0 20 28 70 65 72 68 61 70 73 20 69 74 20 69 73 20   (perhaps it is 
100d0 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61  unable to alloca
100e0 74 65 20 61 20 6e 65 65 64 65 64 20 72 65 73 6f  te a needed reso
100f0 75 72 63 65 20 73 75 63 68 0a 2a 2a 20 61 73 20  urce such.** as 
10100 61 20 6d 75 74 65 78 29 20 69 74 20 72 65 74 75  a mutex) it retu
10110 72 6e 73 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f  rns an [error co
10120 64 65 5d 20 6f 74 68 65 72 20 74 68 61 6e 20 5b  de] other than [
10130 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a  SQLITE_OK]..**.*
10140 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69  * ^The sqlite3_i
10150 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74  nitialize() rout
10160 69 6e 65 20 69 73 20 63 61 6c 6c 65 64 20 69 6e  ine is called in
10170 74 65 72 6e 61 6c 6c 79 20 62 79 20 6d 61 6e 79  ternally by many
10180 20 6f 74 68 65 72 0a 2a 2a 20 53 51 4c 69 74 65   other.** SQLite
10190 20 69 6e 74 65 72 66 61 63 65 73 20 73 6f 20 74   interfaces so t
101a0 68 61 74 20 61 6e 20 61 70 70 6c 69 63 61 74 69  hat an applicati
101b0 6f 6e 20 75 73 75 61 6c 6c 79 20 64 6f 65 73 20  on usually does 
101c0 6e 6f 74 20 6e 65 65 64 20 74 6f 0a 2a 2a 20 69  not need to.** i
101d0 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 69 6e  nvoke sqlite3_in
101e0 69 74 69 61 6c 69 7a 65 28 29 20 64 69 72 65 63  itialize() direc
101f0 74 6c 79 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c  tly.  For exampl
10200 65 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  e, [sqlite3_open
10210 28 29 5d 0a 2a 2a 20 63 61 6c 6c 73 20 73 71 6c  ()].** calls sql
10220 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
10230 29 20 73 6f 20 74 68 65 20 53 51 4c 69 74 65 20  ) so the SQLite 
10240 6c 69 62 72 61 72 79 20 77 69 6c 6c 20 62 65 20  library will be 
10250 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a  automatically.**
10260 20 69 6e 69 74 69 61 6c 69 7a 65 64 20 77 68 65   initialized whe
10270 6e 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  n [sqlite3_open(
10280 29 5d 20 69 73 20 63 61 6c 6c 65 64 20 69 66 20  )] is called if 
10290 69 74 20 68 61 73 20 6e 6f 74 20 62 65 20 69 6e  it has not be in
102a0 69 74 69 61 6c 69 7a 65 64 0a 2a 2a 20 61 6c 72  itialized.** alr
102b0 65 61 64 79 2e 20 20 5e 48 6f 77 65 76 65 72 2c  eady.  ^However,
102c0 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f   if SQLite is co
102d0 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68 65 20  mpiled with the 
102e0 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54  [SQLITE_OMIT_AUT
102f0 4f 49 4e 49 54 5d 0a 2a 2a 20 63 6f 6d 70 69 6c  OINIT].** compil
10300 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2c 20 74  e-time option, t
10310 68 65 6e 20 74 68 65 20 61 75 74 6f 6d 61 74 69  hen the automati
10320 63 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74  c calls to sqlit
10330 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 0a  e3_initialize().
10340 2a 2a 20 61 72 65 20 6f 6d 69 74 74 65 64 20 61  ** are omitted a
10350 6e 64 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  nd the applicati
10360 6f 6e 20 6d 75 73 74 20 63 61 6c 6c 20 73 71 6c  on must call sql
10370 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
10380 29 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 70 72  ) directly.** pr
10390 69 6f 72 20 74 6f 20 75 73 69 6e 67 20 61 6e 79  ior to using any
103a0 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e   other SQLite in
103b0 74 65 72 66 61 63 65 2e 20 20 46 6f 72 20 6d 61  terface.  For ma
103c0 78 69 6d 75 6d 20 70 6f 72 74 61 62 69 6c 69 74  ximum portabilit
103d0 79 2c 0a 2a 2a 20 69 74 20 69 73 20 72 65 63 6f  y,.** it is reco
103e0 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 61 70 70  mmended that app
103f0 6c 69 63 61 74 69 6f 6e 73 20 61 6c 77 61 79 73  lications always
10400 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f   invoke sqlite3_
10410 69 6e 69 74 69 61 6c 69 7a 65 28 29 0a 2a 2a 20  initialize().** 
10420 64 69 72 65 63 74 6c 79 20 70 72 69 6f 72 20 74  directly prior t
10430 6f 20 75 73 69 6e 67 20 61 6e 79 20 6f 74 68 65  o using any othe
10440 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61  r SQLite interfa
10450 63 65 2e 20 20 46 75 74 75 72 65 20 72 65 6c 65  ce.  Future rele
10460 61 73 65 73 0a 2a 2a 20 6f 66 20 53 51 4c 69 74  ases.** of SQLit
10470 65 20 6d 61 79 20 72 65 71 75 69 72 65 20 74 68  e may require th
10480 69 73 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f  is.  In other wo
10490 72 64 73 2c 20 74 68 65 20 62 65 68 61 76 69 6f  rds, the behavio
104a0 72 20 65 78 68 69 62 69 74 65 64 0a 2a 2a 20 77  r exhibited.** w
104b0 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20 63 6f  hen SQLite is co
104c0 6d 70 69 6c 65 64 20 77 69 74 68 20 5b 53 51 4c  mpiled with [SQL
104d0 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e 49  ITE_OMIT_AUTOINI
104e0 54 5d 20 6d 69 67 68 74 20 62 65 63 6f 6d 65 20  T] might become 
104f0 74 68 65 0a 2a 2a 20 64 65 66 61 75 6c 74 20 62  the.** default b
10500 65 68 61 76 69 6f 72 20 69 6e 20 73 6f 6d 65 20  ehavior in some 
10510 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 20 6f  future release o
10520 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20  f SQLite..**.** 
10530 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69  The sqlite3_os_i
10540 6e 69 74 28 29 20 72 6f 75 74 69 6e 65 20 64 6f  nit() routine do
10550 65 73 20 6f 70 65 72 61 74 69 6e 67 2d 73 79 73  es operating-sys
10560 74 65 6d 20 73 70 65 63 69 66 69 63 0a 2a 2a 20  tem specific.** 
10570 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 6f  initialization o
10580 66 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62  f the SQLite lib
10590 72 61 72 79 2e 20 20 54 68 65 20 73 71 6c 69 74  rary.  The sqlit
105a0 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 72  e3_os_end().** r
105b0 6f 75 74 69 6e 65 20 75 6e 64 6f 65 73 20 74 68  outine undoes th
105c0 65 20 65 66 66 65 63 74 20 6f 66 20 73 71 6c 69  e effect of sqli
105d0 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 2e 20 20  te3_os_init().  
105e0 54 79 70 69 63 61 6c 20 74 61 73 6b 73 0a 2a 2a  Typical tasks.**
105f0 20 70 65 72 66 6f 72 6d 65 64 20 62 79 20 74 68   performed by th
10600 65 73 65 20 72 6f 75 74 69 6e 65 73 20 69 6e 63  ese routines inc
10610 6c 75 64 65 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  lude allocation 
10620 6f 72 20 64 65 61 6c 6c 6f 63 61 74 69 6f 6e 0a  or deallocation.
10630 2a 2a 20 6f 66 20 73 74 61 74 69 63 20 72 65 73  ** of static res
10640 6f 75 72 63 65 73 2c 20 69 6e 69 74 69 61 6c 69  ources, initiali
10650 7a 61 74 69 6f 6e 20 6f 66 20 67 6c 6f 62 61 6c  zation of global
10660 20 76 61 72 69 61 62 6c 65 73 2c 0a 2a 2a 20 73   variables,.** s
10670 65 74 74 69 6e 67 20 75 70 20 61 20 64 65 66 61  etting up a defa
10680 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  ult [sqlite3_vfs
10690 5d 20 6d 6f 64 75 6c 65 2c 20 6f 72 20 73 65 74  ] module, or set
106a0 74 69 6e 67 20 75 70 0a 2a 2a 20 61 20 64 65 66  ting up.** a def
106b0 61 75 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 69  ault configurati
106c0 6f 6e 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  on using [sqlite
106d0 33 5f 63 6f 6e 66 69 67 28 29 5d 2e 0a 2a 2a 0a  3_config()]..**.
106e0 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  ** The applicati
106f0 6f 6e 20 73 68 6f 75 6c 64 20 6e 65 76 65 72 20  on should never 
10700 69 6e 76 6f 6b 65 20 65 69 74 68 65 72 20 73 71  invoke either sq
10710 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 0a  lite3_os_init().
10720 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73  ** or sqlite3_os
10730 5f 65 6e 64 28 29 20 64 69 72 65 63 74 6c 79 2e  _end() directly.
10740 20 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f    The applicatio
10750 6e 20 73 68 6f 75 6c 64 20 6f 6e 6c 79 20 69 6e  n should only in
10760 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  voke.** sqlite3_
10770 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 61 6e 64  initialize() and
10780 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77   sqlite3_shutdow
10790 6e 28 29 2e 20 20 54 68 65 20 73 71 6c 69 74 65  n().  The sqlite
107a0 33 5f 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a 20 69  3_os_init().** i
107b0 6e 74 65 72 66 61 63 65 20 69 73 20 63 61 6c 6c  nterface is call
107c0 65 64 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  ed automatically
107d0 20 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 69 74   by sqlite3_init
107e0 69 61 6c 69 7a 65 28 29 20 61 6e 64 0a 2a 2a 20  ialize() and.** 
107f0 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29  sqlite3_os_end()
10800 20 69 73 20 63 61 6c 6c 65 64 20 62 79 20 73 71   is called by sq
10810 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
10820 2e 20 20 41 70 70 72 6f 70 72 69 61 74 65 0a 2a  .  Appropriate.*
10830 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  * implementation
10840 73 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73  s for sqlite3_os
10850 5f 69 6e 69 74 28 29 20 61 6e 64 20 73 71 6c 69  _init() and sqli
10860 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20  te3_os_end().** 
10870 61 72 65 20 62 75 69 6c 74 20 69 6e 74 6f 20 53  are built into S
10880 51 4c 69 74 65 20 77 68 65 6e 20 69 74 20 69 73  QLite when it is
10890 20 63 6f 6d 70 69 6c 65 64 20 66 6f 72 20 55 6e   compiled for Un
108a0 69 78 2c 20 57 69 6e 64 6f 77 73 2c 20 6f 72 20  ix, Windows, or 
108b0 4f 53 2f 32 2e 0a 2a 2a 20 57 68 65 6e 20 5b 63  OS/2..** When [c
108c0 75 73 74 6f 6d 20 62 75 69 6c 64 73 20 7c 20 62  ustom builds | b
108d0 75 69 6c 74 20 66 6f 72 20 6f 74 68 65 72 20 70  uilt for other p
108e0 6c 61 74 66 6f 72 6d 73 5d 0a 2a 2a 20 28 75 73  latforms].** (us
108f0 69 6e 67 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  ing the [SQLITE_
10900 4f 53 5f 4f 54 48 45 52 3d 31 5d 20 63 6f 6d 70  OS_OTHER=1] comp
10910 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74 69  ile-time.** opti
10920 6f 6e 29 20 74 68 65 20 61 70 70 6c 69 63 61 74  on) the applicat
10930 69 6f 6e 20 6d 75 73 74 20 73 75 70 70 6c 79 20  ion must supply 
10940 61 20 73 75 69 74 61 62 6c 65 20 69 6d 70 6c 65  a suitable imple
10950 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 0a 2a 2a  mentation for.**
10960 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74   sqlite3_os_init
10970 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f  () and sqlite3_o
10980 73 5f 65 6e 64 28 29 2e 20 20 41 6e 20 61 70 70  s_end().  An app
10990 6c 69 63 61 74 69 6f 6e 2d 73 75 70 70 6c 69 65  lication-supplie
109a0 64 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74  d.** implementat
109b0 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f  ion of sqlite3_o
109c0 73 5f 69 6e 69 74 28 29 20 6f 72 20 73 71 6c 69  s_init() or sqli
109d0 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20  te3_os_end().** 
109e0 6d 75 73 74 20 72 65 74 75 72 6e 20 5b 53 51 4c  must return [SQL
109f0 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65  ITE_OK] on succe
10a00 73 73 20 61 6e 64 20 73 6f 6d 65 20 6f 74 68 65  ss and some othe
10a10 72 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 75  r [error code] u
10a20 70 6f 6e 0a 2a 2a 20 66 61 69 6c 75 72 65 2e 0a  pon.** failure..
10a30 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  */.SQLITE_API in
10a40 74 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  t sqlite3_initia
10a50 6c 69 7a 65 28 76 6f 69 64 29 3b 0a 53 51 4c 49  lize(void);.SQLI
10a60 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
10a70 65 33 5f 73 68 75 74 64 6f 77 6e 28 76 6f 69 64  e3_shutdown(void
10a80 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  );.SQLITE_API in
10a90 74 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69  t sqlite3_os_ini
10aa0 74 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f  t(void);.SQLITE_
10ab0 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
10ac0 6f 73 5f 65 6e 64 28 76 6f 69 64 29 3b 0a 0a 2f  os_end(void);../
10ad0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
10ae0 6f 6e 66 69 67 75 72 69 6e 67 20 54 68 65 20 53  onfiguring The S
10af0 51 4c 69 74 65 20 4c 69 62 72 61 72 79 0a 2a 2a  QLite Library.**
10b00 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
10b10 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61  config() interfa
10b20 63 65 20 69 73 20 75 73 65 64 20 74 6f 20 6d 61  ce is used to ma
10b30 6b 65 20 67 6c 6f 62 61 6c 20 63 6f 6e 66 69 67  ke global config
10b40 75 72 61 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67  uration.** chang
10b50 65 73 20 74 6f 20 53 51 4c 69 74 65 20 69 6e 20  es to SQLite in 
10b60 6f 72 64 65 72 20 74 6f 20 74 75 6e 65 20 53 51  order to tune SQ
10b70 4c 69 74 65 20 74 6f 20 74 68 65 20 73 70 65 63  Lite to the spec
10b80 69 66 69 63 20 6e 65 65 64 73 20 6f 66 0a 2a 2a  ific needs of.**
10b90 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
10ba0 2e 20 20 54 68 65 20 64 65 66 61 75 6c 74 20 63  .  The default c
10bb0 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 69 73 20  onfiguration is 
10bc0 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20  recommended for 
10bd0 6d 6f 73 74 0a 2a 2a 20 61 70 70 6c 69 63 61 74  most.** applicat
10be0 69 6f 6e 73 20 61 6e 64 20 73 6f 20 74 68 69 73  ions and so this
10bf0 20 72 6f 75 74 69 6e 65 20 69 73 20 75 73 75 61   routine is usua
10c00 6c 6c 79 20 6e 6f 74 20 6e 65 63 65 73 73 61 72  lly not necessar
10c10 79 2e 20 20 49 74 20 69 73 0a 2a 2a 20 70 72 6f  y.  It is.** pro
10c20 76 69 64 65 64 20 74 6f 20 73 75 70 70 6f 72 74  vided to support
10c30 20 72 61 72 65 20 61 70 70 6c 69 63 61 74 69 6f   rare applicatio
10c40 6e 73 20 77 69 74 68 20 75 6e 75 73 75 61 6c 20  ns with unusual 
10c50 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e  needs..**.** <b>
10c60 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66  The sqlite3_conf
10c70 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 20 69  ig() interface i
10c80 73 20 6e 6f 74 20 74 68 72 65 61 64 73 61 66 65  s not threadsafe
10c90 2e 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f  . The applicatio
10ca0 6e 0a 2a 2a 20 6d 75 73 74 20 65 6e 73 75 72 65  n.** must ensure
10cb0 20 74 68 61 74 20 6e 6f 20 6f 74 68 65 72 20 53   that no other S
10cc0 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 73  QLite interfaces
10cd0 20 61 72 65 20 69 6e 76 6f 6b 65 64 20 62 79 20   are invoked by 
10ce0 6f 74 68 65 72 0a 2a 2a 20 74 68 72 65 61 64 73  other.** threads
10cf0 20 77 68 69 6c 65 20 73 71 6c 69 74 65 33 5f 63   while sqlite3_c
10d00 6f 6e 66 69 67 28 29 20 69 73 20 72 75 6e 6e 69  onfig() is runni
10d10 6e 67 2e 3c 2f 62 3e 0a 2a 2a 0a 2a 2a 20 54 68  ng.</b>.**.** Th
10d20 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67  e sqlite3_config
10d30 28 29 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20  () interface.** 
10d40 6d 61 79 20 6f 6e 6c 79 20 62 65 20 69 6e 76 6f  may only be invo
10d50 6b 65 64 20 70 72 69 6f 72 20 74 6f 20 6c 69 62  ked prior to lib
10d60 72 61 72 79 20 69 6e 69 74 69 61 6c 69 7a 61 74  rary initializat
10d70 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71  ion using.** [sq
10d80 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
10d90 28 29 5d 20 6f 72 20 61 66 74 65 72 20 73 68 75  ()] or after shu
10da0 74 64 6f 77 6e 20 62 79 20 5b 73 71 6c 69 74 65  tdown by [sqlite
10db0 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 2e 0a 2a  3_shutdown()]..*
10dc0 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 63 6f  * ^If sqlite3_co
10dd0 6e 66 69 67 28 29 20 69 73 20 63 61 6c 6c 65 64  nfig() is called
10de0 20 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f   after [sqlite3_
10df0 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20 61 6e  initialize()] an
10e00 64 20 62 65 66 6f 72 65 0a 2a 2a 20 5b 73 71 6c  d before.** [sql
10e10 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d  ite3_shutdown()]
10e20 20 74 68 65 6e 20 69 74 20 77 69 6c 6c 20 72 65   then it will re
10e30 74 75 72 6e 20 53 51 4c 49 54 45 5f 4d 49 53 55  turn SQLITE_MISU
10e40 53 45 2e 0a 2a 2a 20 4e 6f 74 65 2c 20 68 6f 77  SE..** Note, how
10e50 65 76 65 72 2c 20 74 68 61 74 20 5e 73 71 6c 69  ever, that ^sqli
10e60 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 63 61 6e  te3_config() can
10e70 20 62 65 20 63 61 6c 6c 65 64 20 61 73 20 70 61   be called as pa
10e80 72 74 20 6f 66 20 74 68 65 0a 2a 2a 20 69 6d 70  rt of the.** imp
10e90 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61  lementation of a
10ea0 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  n application-de
10eb0 66 69 6e 65 64 20 5b 73 71 6c 69 74 65 33 5f 6f  fined [sqlite3_o
10ec0 73 5f 69 6e 69 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a  s_init()]..**.**
10ed0 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   The first argum
10ee0 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  ent to sqlite3_c
10ef0 6f 6e 66 69 67 28 29 20 69 73 20 61 6e 20 69 6e  onfig() is an in
10f00 74 65 67 65 72 0a 2a 2a 20 5b 63 6f 6e 66 69 67  teger.** [config
10f10 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d 20  uration option] 
10f20 74 68 61 74 20 64 65 74 65 72 6d 69 6e 65 73 0a  that determines.
10f30 2a 2a 20 77 68 61 74 20 70 72 6f 70 65 72 74 79  ** what property
10f40 20 6f 66 20 53 51 4c 69 74 65 20 69 73 20 74 6f   of SQLite is to
10f50 20 62 65 20 63 6f 6e 66 69 67 75 72 65 64 2e 20   be configured. 
10f60 20 53 75 62 73 65 71 75 65 6e 74 20 61 72 67 75   Subsequent argu
10f70 6d 65 6e 74 73 0a 2a 2a 20 76 61 72 79 20 64 65  ments.** vary de
10f80 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 5b  pending on the [
10f90 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
10fa0 74 69 6f 6e 5d 0a 2a 2a 20 69 6e 20 74 68 65 20  tion].** in the 
10fb0 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a  first argument..
10fc0 2a 2a 0a 2a 2a 20 5e 57 68 65 6e 20 61 20 63 6f  **.** ^When a co
10fd0 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
10fe0 6f 6e 20 69 73 20 73 65 74 2c 20 73 71 6c 69 74  on is set, sqlit
10ff0 65 33 5f 63 6f 6e 66 69 67 28 29 20 72 65 74 75  e3_config() retu
11000 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e  rns [SQLITE_OK].
11010 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6f 70 74 69  .** ^If the opti
11020 6f 6e 20 69 73 20 75 6e 6b 6e 6f 77 6e 20 6f 72  on is unknown or
11030 20 53 51 4c 69 74 65 20 69 73 20 75 6e 61 62 6c   SQLite is unabl
11040 65 20 74 6f 20 73 65 74 20 74 68 65 20 6f 70 74  e to set the opt
11050 69 6f 6e 0a 2a 2a 20 74 68 65 6e 20 74 68 69 73  ion.** then this
11060 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
11070 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72   a non-zero [err
11080 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2f 0a 53 51 4c  or code]..*/.SQL
11090 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
110a0 74 65 33 5f 63 6f 6e 66 69 67 28 69 6e 74 2c 20  te3_config(int, 
110b0 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ...);../*.** CAP
110c0 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 65  I3REF: Configure
110d0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
110e0 74 69 6f 6e 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a  tions.** METHOD:
110f0 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 54   sqlite3.**.** T
11100 68 65 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f  he sqlite3_db_co
11110 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61 63 65  nfig() interface
11120 20 69 73 20 75 73 65 64 20 74 6f 20 6d 61 6b 65   is used to make
11130 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 0a 2a   configuration.*
11140 2a 20 63 68 61 6e 67 65 73 20 74 6f 20 61 20 5b  * changes to a [
11150 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
11160 69 6f 6e 5d 2e 20 20 54 68 65 20 69 6e 74 65 72  ion].  The inter
11170 66 61 63 65 20 69 73 20 73 69 6d 69 6c 61 72 20  face is similar 
11180 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  to.** [sqlite3_c
11190 6f 6e 66 69 67 28 29 5d 20 65 78 63 65 70 74 20  onfig()] except 
111a0 74 68 61 74 20 74 68 65 20 63 68 61 6e 67 65 73  that the changes
111b0 20 61 70 70 6c 79 20 74 6f 20 61 20 73 69 6e 67   apply to a sing
111c0 6c 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20  le.** [database 
111d0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 73 70 65  connection] (spe
111e0 63 69 66 69 65 64 20 69 6e 20 74 68 65 20 66 69  cified in the fi
111f0 72 73 74 20 61 72 67 75 6d 65 6e 74 29 2e 0a 2a  rst argument)..*
11200 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20  *.** The second 
11210 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69  argument to sqli
11220 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 44 2c  te3_db_config(D,
11230 56 2c 2e 2e 2e 29 20 20 69 73 20 74 68 65 0a 2a  V,...)  is the.*
11240 2a 20 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46  * [SQLITE_DBCONF
11250 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 7c 20 63  IG_LOOKASIDE | c
11260 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 76 65 72  onfiguration ver
11270 62 5d 20 2d 20 61 6e 20 69 6e 74 65 67 65 72 20  b] - an integer 
11280 63 6f 64 65 20 0a 2a 2a 20 74 68 61 74 20 69 6e  code .** that in
11290 64 69 63 61 74 65 73 20 77 68 61 74 20 61 73 70  dicates what asp
112a0 65 63 74 20 6f 66 20 74 68 65 20 5b 64 61 74 61  ect of the [data
112b0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
112c0 20 69 73 20 62 65 69 6e 67 20 63 6f 6e 66 69 67   is being config
112d0 75 72 65 64 2e 0a 2a 2a 20 53 75 62 73 65 71 75  ured..** Subsequ
112e0 65 6e 74 20 61 72 67 75 6d 65 6e 74 73 20 76 61  ent arguments va
112f0 72 79 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20  ry depending on 
11300 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  the configuratio
11310 6e 20 76 65 72 62 2e 0a 2a 2a 0a 2a 2a 20 5e 43  n verb..**.** ^C
11320 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f  alls to sqlite3_
11330 64 62 5f 63 6f 6e 66 69 67 28 29 20 72 65 74 75  db_config() retu
11340 72 6e 20 53 51 4c 49 54 45 5f 4f 4b 20 69 66 20  rn SQLITE_OK if 
11350 61 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a 20 74  and only if.** t
11360 68 65 20 63 61 6c 6c 20 69 73 20 63 6f 6e 73 69  he call is consi
11370 64 65 72 65 64 20 73 75 63 63 65 73 73 66 75 6c  dered successful
11380 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
11390 69 6e 74 20 73 71 6c 69 74 65 33 5f 64 62 5f 63  int sqlite3_db_c
113a0 6f 6e 66 69 67 28 73 71 6c 69 74 65 33 2a 2c 20  onfig(sqlite3*, 
113b0 69 6e 74 20 6f 70 2c 20 2e 2e 2e 29 3b 0a 0a 2f  int op, ...);../
113c0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d  *.** CAPI3REF: M
113d0 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f 6e  emory Allocation
113e0 20 52 6f 75 74 69 6e 65 73 0a 2a 2a 0a 2a 2a 20   Routines.**.** 
113f0 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  An instance of t
11400 68 69 73 20 6f 62 6a 65 63 74 20 64 65 66 69 6e  his object defin
11410 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  es the interface
11420 20 62 65 74 77 65 65 6e 20 53 51 4c 69 74 65 0a   between SQLite.
11430 2a 2a 20 61 6e 64 20 6c 6f 77 2d 6c 65 76 65 6c  ** and low-level
11440 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
11450 6f 6e 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a  on routines..**.
11460 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 74 20 69  ** This object i
11470 73 20 75 73 65 64 20 69 6e 20 6f 6e 6c 79 20 6f  s used in only o
11480 6e 65 20 70 6c 61 63 65 20 69 6e 20 74 68 65 20  ne place in the 
11490 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65  SQLite interface
114a0 2e 0a 2a 2a 20 41 20 70 6f 69 6e 74 65 72 20 74  ..** A pointer t
114b0 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66  o an instance of
114c0 20 74 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20   this object is 
114d0 74 68 65 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a  the argument to.
114e0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  ** [sqlite3_conf
114f0 69 67 28 29 5d 20 77 68 65 6e 20 74 68 65 20 63  ig()] when the c
11500 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
11510 69 6f 6e 20 69 73 0a 2a 2a 20 5b 53 51 4c 49 54  ion is.** [SQLIT
11520 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d  E_CONFIG_MALLOC]
11530 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46   or [SQLITE_CONF
11540 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 5d 2e 20 20  IG_GETMALLOC].  
11550 0a 2a 2a 20 42 79 20 63 72 65 61 74 69 6e 67 20  .** By creating 
11560 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  an instance of t
11570 68 69 73 20 6f 62 6a 65 63 74 0a 2a 2a 20 61 6e  his object.** an
11580 64 20 70 61 73 73 69 6e 67 20 69 74 20 74 6f 20  d passing it to 
11590 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 5d  [sqlite3_config]
115a0 28 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  ([SQLITE_CONFIG_
115b0 4d 41 4c 4c 4f 43 5d 29 0a 2a 2a 20 64 75 72 69  MALLOC]).** duri
115c0 6e 67 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ng configuration
115d0 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  , an application
115e0 20 63 61 6e 20 73 70 65 63 69 66 79 20 61 6e 20   can specify an 
115f0 61 6c 74 65 72 6e 61 74 69 76 65 0a 2a 2a 20 6d  alternative.** m
11600 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
11610 20 73 75 62 73 79 73 74 65 6d 20 66 6f 72 20 53   subsystem for S
11620 51 4c 69 74 65 20 74 6f 20 75 73 65 20 66 6f 72  QLite to use for
11630 20 61 6c 6c 20 6f 66 20 69 74 73 0a 2a 2a 20 64   all of its.** d
11640 79 6e 61 6d 69 63 20 6d 65 6d 6f 72 79 20 6e 65  ynamic memory ne
11650 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20  eds..**.** Note 
11660 74 68 61 74 20 53 51 4c 69 74 65 20 63 6f 6d 65  that SQLite come
11670 73 20 77 69 74 68 20 73 65 76 65 72 61 6c 20 5b  s with several [
11680 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20  built-in memory 
11690 61 6c 6c 6f 63 61 74 6f 72 73 5d 0a 2a 2a 20 74  allocators].** t
116a0 68 61 74 20 61 72 65 20 70 65 72 66 65 63 74 6c  hat are perfectl
116b0 79 20 61 64 65 71 75 61 74 65 20 66 6f 72 20 74  y adequate for t
116c0 68 65 20 6f 76 65 72 77 68 65 6c 6d 69 6e 67 20  he overwhelming 
116d0 6d 61 6a 6f 72 69 74 79 20 6f 66 20 61 70 70 6c  majority of appl
116e0 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 61 6e 64 20  ications.** and 
116f0 74 68 61 74 20 74 68 69 73 20 6f 62 6a 65 63 74  that this object
11700 20 69 73 20 6f 6e 6c 79 20 75 73 65 66 75 6c 20   is only useful 
11710 74 6f 20 61 20 74 69 6e 79 20 6d 69 6e 6f 72 69  to a tiny minori
11720 74 79 20 6f 66 20 61 70 70 6c 69 63 61 74 69 6f  ty of applicatio
11730 6e 73 0a 2a 2a 20 77 69 74 68 20 73 70 65 63 69  ns.** with speci
11740 61 6c 69 7a 65 64 20 6d 65 6d 6f 72 79 20 61 6c  alized memory al
11750 6c 6f 63 61 74 69 6f 6e 20 72 65 71 75 69 72 65  location require
11760 6d 65 6e 74 73 2e 20 20 54 68 69 73 20 6f 62 6a  ments.  This obj
11770 65 63 74 20 69 73 0a 2a 2a 20 61 6c 73 6f 20 75  ect is.** also u
11780 73 65 64 20 64 75 72 69 6e 67 20 74 65 73 74 69  sed during testi
11790 6e 67 20 6f 66 20 53 51 4c 69 74 65 20 69 6e 20  ng of SQLite in 
117a0 6f 72 64 65 72 20 74 6f 20 73 70 65 63 69 66 79  order to specify
117b0 20 61 6e 20 61 6c 74 65 72 6e 61 74 69 76 65 0a   an alternative.
117c0 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  ** memory alloca
117d0 74 6f 72 20 74 68 61 74 20 73 69 6d 75 6c 61 74  tor that simulat
117e0 65 73 20 6d 65 6d 6f 72 79 20 6f 75 74 2d 6f 66  es memory out-of
117f0 2d 6d 65 6d 6f 72 79 20 63 6f 6e 64 69 74 69 6f  -memory conditio
11800 6e 73 20 69 6e 0a 2a 2a 20 6f 72 64 65 72 20 74  ns in.** order t
11810 6f 20 76 65 72 69 66 79 20 74 68 61 74 20 53 51  o verify that SQ
11820 4c 69 74 65 20 72 65 63 6f 76 65 72 73 20 67 72  Lite recovers gr
11830 61 63 65 66 75 6c 6c 79 20 66 72 6f 6d 20 73 75  acefully from su
11840 63 68 0a 2a 2a 20 63 6f 6e 64 69 74 69 6f 6e 73  ch.** conditions
11850 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 4d 61 6c  ..**.** The xMal
11860 6c 6f 63 2c 20 78 52 65 61 6c 6c 6f 63 2c 20 61  loc, xRealloc, a
11870 6e 64 20 78 46 72 65 65 20 6d 65 74 68 6f 64 73  nd xFree methods
11880 20 6d 75 73 74 20 77 6f 72 6b 20 6c 69 6b 65 20   must work like 
11890 74 68 65 0a 2a 2a 20 6d 61 6c 6c 6f 63 28 29 2c  the.** malloc(),
118a0 20 72 65 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66   realloc() and f
118b0 72 65 65 28 29 20 66 75 6e 63 74 69 6f 6e 73 20  ree() functions 
118c0 66 72 6f 6d 20 74 68 65 20 73 74 61 6e 64 61 72  from the standar
118d0 64 20 43 20 6c 69 62 72 61 72 79 2e 0a 2a 2a 20  d C library..** 
118e0 5e 53 51 4c 69 74 65 20 67 75 61 72 61 6e 74 65  ^SQLite guarante
118f0 65 73 20 74 68 61 74 20 74 68 65 20 73 65 63 6f  es that the seco
11900 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a  nd argument to.*
11910 2a 20 78 52 65 61 6c 6c 6f 63 20 69 73 20 61 6c  * xRealloc is al
11920 77 61 79 73 20 61 20 76 61 6c 75 65 20 72 65 74  ways a value ret
11930 75 72 6e 65 64 20 62 79 20 61 20 70 72 69 6f 72  urned by a prior
11940 20 63 61 6c 6c 20 74 6f 20 78 52 6f 75 6e 64 75   call to xRoundu
11950 70 2e 0a 2a 2a 0a 2a 2a 20 78 53 69 7a 65 20 73  p..**.** xSize s
11960 68 6f 75 6c 64 20 72 65 74 75 72 6e 20 74 68 65  hould return the
11970 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65 20   allocated size 
11980 6f 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  of a memory allo
11990 63 61 74 69 6f 6e 0a 2a 2a 20 70 72 65 76 69 6f  cation.** previo
119a0 75 73 6c 79 20 6f 62 74 61 69 6e 65 64 20 66 72  usly obtained fr
119b0 6f 6d 20 78 4d 61 6c 6c 6f 63 20 6f 72 20 78 52  om xMalloc or xR
119c0 65 61 6c 6c 6f 63 2e 20 20 54 68 65 20 61 6c 6c  ealloc.  The all
119d0 6f 63 61 74 65 64 20 73 69 7a 65 0a 2a 2a 20 69  ocated size.** i
119e0 73 20 61 6c 77 61 79 73 20 61 74 20 6c 65 61 73  s always at leas
119f0 74 20 61 73 20 62 69 67 20 61 73 20 74 68 65 20  t as big as the 
11a00 72 65 71 75 65 73 74 65 64 20 73 69 7a 65 20 62  requested size b
11a10 75 74 20 6d 61 79 20 62 65 20 6c 61 72 67 65 72  ut may be larger
11a20 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 52 6f 75  ..**.** The xRou
11a30 6e 64 75 70 20 6d 65 74 68 6f 64 20 72 65 74 75  ndup method retu
11a40 72 6e 73 20 77 68 61 74 20 77 6f 75 6c 64 20 62  rns what would b
11a50 65 20 74 68 65 20 61 6c 6c 6f 63 61 74 65 64 20  e the allocated 
11a60 73 69 7a 65 20 6f 66 0a 2a 2a 20 61 20 6d 65 6d  size of.** a mem
11a70 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 67  ory allocation g
11a80 69 76 65 6e 20 61 20 70 61 72 74 69 63 75 6c 61  iven a particula
11a90 72 20 72 65 71 75 65 73 74 65 64 20 73 69 7a 65  r requested size
11aa0 2e 20 20 4d 6f 73 74 20 6d 65 6d 6f 72 79 0a 2a  .  Most memory.*
11ab0 2a 20 61 6c 6c 6f 63 61 74 6f 72 73 20 72 6f 75  * allocators rou
11ac0 6e 64 20 75 70 20 6d 65 6d 6f 72 79 20 61 6c 6c  nd up memory all
11ad0 6f 63 61 74 69 6f 6e 73 20 61 74 20 6c 65 61 73  ocations at leas
11ae0 74 20 74 6f 20 74 68 65 20 6e 65 78 74 20 6d 75  t to the next mu
11af0 6c 74 69 70 6c 65 0a 2a 2a 20 6f 66 20 38 2e 20  ltiple.** of 8. 
11b00 20 53 6f 6d 65 20 61 6c 6c 6f 63 61 74 6f 72 73   Some allocators
11b10 20 72 6f 75 6e 64 20 75 70 20 74 6f 20 61 20 6c   round up to a l
11b20 61 72 67 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f  arger multiple o
11b30 72 20 74 6f 20 61 20 70 6f 77 65 72 20 6f 66 20  r to a power of 
11b40 32 2e 0a 2a 2a 20 45 76 65 72 79 20 6d 65 6d 6f  2..** Every memo
11b50 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 65  ry allocation re
11b60 71 75 65 73 74 20 63 6f 6d 69 6e 67 20 69 6e 20  quest coming in 
11b70 74 68 72 6f 75 67 68 20 5b 73 71 6c 69 74 65 33  through [sqlite3
11b80 5f 6d 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 6f 72  _malloc()].** or
11b90 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f   [sqlite3_reallo
11ba0 63 28 29 5d 20 66 69 72 73 74 20 63 61 6c 6c 73  c()] first calls
11bb0 20 78 52 6f 75 6e 64 75 70 2e 20 20 49 66 20 78   xRoundup.  If x
11bc0 52 6f 75 6e 64 75 70 20 72 65 74 75 72 6e 73 20  Roundup returns 
11bd0 30 2c 20 0a 2a 2a 20 74 68 61 74 20 63 61 75 73  0, .** that caus
11be0 65 73 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e  es the correspon
11bf0 64 69 6e 67 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  ding memory allo
11c00 63 61 74 69 6f 6e 20 74 6f 20 66 61 69 6c 2e 0a  cation to fail..
11c10 2a 2a 0a 2a 2a 20 54 68 65 20 78 49 6e 69 74 20  **.** The xInit 
11c20 6d 65 74 68 6f 64 20 69 6e 69 74 69 61 6c 69 7a  method initializ
11c30 65 73 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c  es the memory al
11c40 6c 6f 63 61 74 6f 72 2e 20 20 46 6f 72 20 65 78  locator.  For ex
11c50 61 6d 70 6c 65 2c 0a 2a 2a 20 69 74 20 6d 69 67  ample,.** it mig
11c60 68 74 20 61 6c 6c 6f 63 61 74 65 20 61 6e 79 20  ht allocate any 
11c70 72 65 71 75 69 72 65 20 6d 75 74 65 78 65 73 20  require mutexes 
11c80 6f 72 20 69 6e 69 74 69 61 6c 69 7a 65 20 69 6e  or initialize in
11c90 74 65 72 6e 61 6c 20 64 61 74 61 0a 2a 2a 20 73  ternal data.** s
11ca0 74 72 75 63 74 75 72 65 73 2e 20 20 54 68 65 20  tructures.  The 
11cb0 78 53 68 75 74 64 6f 77 6e 20 6d 65 74 68 6f 64  xShutdown method
11cc0 20 69 73 20 69 6e 76 6f 6b 65 64 20 28 69 6e 64   is invoked (ind
11cd0 69 72 65 63 74 6c 79 29 20 62 79 0a 2a 2a 20 5b  irectly) by.** [
11ce0 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
11cf0 28 29 5d 20 61 6e 64 20 73 68 6f 75 6c 64 20 64  ()] and should d
11d00 65 61 6c 6c 6f 63 61 74 65 20 61 6e 79 20 72 65  eallocate any re
11d10 73 6f 75 72 63 65 73 20 61 63 71 75 69 72 65 64  sources acquired
11d20 0a 2a 2a 20 62 79 20 78 49 6e 69 74 2e 20 20 54  .** by xInit.  T
11d30 68 65 20 70 41 70 70 44 61 74 61 20 70 6f 69 6e  he pAppData poin
11d40 74 65 72 20 69 73 20 75 73 65 64 20 61 73 20 74  ter is used as t
11d50 68 65 20 6f 6e 6c 79 20 70 61 72 61 6d 65 74 65  he only paramete
11d60 72 20 74 6f 0a 2a 2a 20 78 49 6e 69 74 20 61 6e  r to.** xInit an
11d70 64 20 78 53 68 75 74 64 6f 77 6e 2e 0a 2a 2a 0a  d xShutdown..**.
11d80 2a 2a 20 53 51 4c 69 74 65 20 68 6f 6c 64 73 20  ** SQLite holds 
11d90 74 68 65 20 5b 53 51 4c 49 54 45 5f 4d 55 54 45  the [SQLITE_MUTE
11da0 58 5f 53 54 41 54 49 43 5f 4d 41 53 54 45 52 5d  X_STATIC_MASTER]
11db0 20 6d 75 74 65 78 20 77 68 65 6e 20 69 74 20 69   mutex when it i
11dc0 6e 76 6f 6b 65 73 0a 2a 2a 20 74 68 65 20 78 49  nvokes.** the xI
11dd0 6e 69 74 20 6d 65 74 68 6f 64 2c 20 73 6f 20 74  nit method, so t
11de0 68 65 20 78 49 6e 69 74 20 6d 65 74 68 6f 64 20  he xInit method 
11df0 6e 65 65 64 20 6e 6f 74 20 62 65 20 74 68 72 65  need not be thre
11e00 61 64 73 61 66 65 2e 20 20 54 68 65 0a 2a 2a 20  adsafe.  The.** 
11e10 78 53 68 75 74 64 6f 77 6e 20 6d 65 74 68 6f 64  xShutdown method
11e20 20 69 73 20 6f 6e 6c 79 20 63 61 6c 6c 65 64 20   is only called 
11e30 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 73 68  from [sqlite3_sh
11e40 75 74 64 6f 77 6e 28 29 5d 20 73 6f 20 69 74 20  utdown()] so it 
11e50 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 6e 65 65 64  does.** not need
11e60 20 74 6f 20 62 65 20 74 68 72 65 61 64 73 61 66   to be threadsaf
11e70 65 20 65 69 74 68 65 72 2e 20 20 46 6f 72 20 61  e either.  For a
11e80 6c 6c 20 6f 74 68 65 72 20 6d 65 74 68 6f 64 73  ll other methods
11e90 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 68 6f 6c 64  , SQLite.** hold
11ea0 73 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4d 55  s the [SQLITE_MU
11eb0 54 45 58 5f 53 54 41 54 49 43 5f 4d 45 4d 5d 20  TEX_STATIC_MEM] 
11ec0 6d 75 74 65 78 20 61 73 20 6c 6f 6e 67 20 61 73  mutex as long as
11ed0 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f   the.** [SQLITE_
11ee0 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53  CONFIG_MEMSTATUS
11ef0 5d 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  ] configuration 
11f00 6f 70 74 69 6f 6e 20 69 73 20 74 75 72 6e 65 64  option is turned
11f10 20 6f 6e 20 28 77 68 69 63 68 0a 2a 2a 20 69 74   on (which.** it
11f20 20 69 73 20 62 79 20 64 65 66 61 75 6c 74 29 20   is by default) 
11f30 61 6e 64 20 73 6f 20 74 68 65 20 6d 65 74 68 6f  and so the metho
11f40 64 73 20 61 72 65 20 61 75 74 6f 6d 61 74 69 63  ds are automatic
11f50 61 6c 6c 79 20 73 65 72 69 61 6c 69 7a 65 64 2e  ally serialized.
11f60 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20 69 66 20  .** However, if 
11f70 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
11f80 45 4d 53 54 41 54 55 53 5d 20 69 73 20 64 69 73  EMSTATUS] is dis
11f90 61 62 6c 65 64 2c 20 74 68 65 6e 20 74 68 65 20  abled, then the 
11fa0 6f 74 68 65 72 0a 2a 2a 20 6d 65 74 68 6f 64 73  other.** methods
11fb0 20 6d 75 73 74 20 62 65 20 74 68 72 65 61 64 73   must be threads
11fc0 61 66 65 20 6f 72 20 65 6c 73 65 20 6d 61 6b 65  afe or else make
11fd0 20 74 68 65 69 72 20 6f 77 6e 20 61 72 72 61 6e   their own arran
11fe0 67 65 6d 65 6e 74 73 20 66 6f 72 0a 2a 2a 20 73  gements for.** s
11ff0 65 72 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a  erialization..**
12000 0a 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  .** SQLite will 
12010 6e 65 76 65 72 20 69 6e 76 6f 6b 65 20 78 49 6e  never invoke xIn
12020 69 74 28 29 20 6d 6f 72 65 20 74 68 61 6e 20 6f  it() more than o
12030 6e 63 65 20 77 69 74 68 6f 75 74 20 61 6e 20 69  nce without an i
12040 6e 74 65 72 76 65 6e 69 6e 67 0a 2a 2a 20 63 61  ntervening.** ca
12050 6c 6c 20 74 6f 20 78 53 68 75 74 64 6f 77 6e 28  ll to xShutdown(
12060 29 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74  )..*/.typedef st
12070 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d  ruct sqlite3_mem
12080 5f 6d 65 74 68 6f 64 73 20 73 71 6c 69 74 65 33  _methods sqlite3
12090 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 3b 0a 73 74  _mem_methods;.st
120a0 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d  ruct sqlite3_mem
120b0 5f 6d 65 74 68 6f 64 73 20 7b 0a 20 20 76 6f 69  _methods {.  voi
120c0 64 20 2a 28 2a 78 4d 61 6c 6c 6f 63 29 28 69 6e  d *(*xMalloc)(in
120d0 74 29 3b 20 20 20 20 20 20 20 20 20 2f 2a 20 4d  t);         /* M
120e0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
120f0 20 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a 20 20 76   function */.  v
12100 6f 69 64 20 28 2a 78 46 72 65 65 29 28 76 6f 69  oid (*xFree)(voi
12110 64 2a 29 3b 20 20 20 20 20 20 20 20 20 20 2f 2a  d*);          /*
12120 20 46 72 65 65 20 61 20 70 72 69 6f 72 20 61 6c   Free a prior al
12130 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f  location */.  vo
12140 69 64 20 2a 28 2a 78 52 65 61 6c 6c 6f 63 29 28  id *(*xRealloc)(
12150 76 6f 69 64 2a 2c 69 6e 74 29 3b 20 20 2f 2a 20  void*,int);  /* 
12160 52 65 73 69 7a 65 20 61 6e 20 61 6c 6c 6f 63 61  Resize an alloca
12170 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20 28 2a  tion */.  int (*
12180 78 53 69 7a 65 29 28 76 6f 69 64 2a 29 3b 20 20  xSize)(void*);  
12190 20 20 20 20 20 20 20 20 20 2f 2a 20 52 65 74 75           /* Retu
121a0 72 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20 61  rn the size of a
121b0 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a  n allocation */.
121c0 20 20 69 6e 74 20 28 2a 78 52 6f 75 6e 64 75 70    int (*xRoundup
121d0 29 28 69 6e 74 29 3b 20 20 20 20 20 20 20 20 20  )(int);         
121e0 20 2f 2a 20 52 6f 75 6e 64 20 75 70 20 72 65 71   /* Round up req
121f0 75 65 73 74 20 73 69 7a 65 20 74 6f 20 61 6c 6c  uest size to all
12200 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20 2a 2f 0a  ocation size */.
12210 20 20 69 6e 74 20 28 2a 78 49 6e 69 74 29 28 76    int (*xInit)(v
12220 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 20 20 20  oid*);          
12230 20 2f 2a 20 49 6e 69 74 69 61 6c 69 7a 65 20 74   /* Initialize t
12240 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  he memory alloca
12250 74 6f 72 20 2a 2f 0a 20 20 76 6f 69 64 20 28 2a  tor */.  void (*
12260 78 53 68 75 74 64 6f 77 6e 29 28 76 6f 69 64 2a  xShutdown)(void*
12270 29 3b 20 20 20 20 20 20 2f 2a 20 44 65 69 6e 69  );      /* Deini
12280 74 69 61 6c 69 7a 65 20 74 68 65 20 6d 65 6d 6f  tialize the memo
12290 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a  ry allocator */.
122a0 20 20 76 6f 69 64 20 2a 70 41 70 70 44 61 74 61    void *pAppData
122b0 3b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ;               
122c0 20 2f 2a 20 41 72 67 75 6d 65 6e 74 20 74 6f 20   /* Argument to 
122d0 78 49 6e 69 74 28 29 20 61 6e 64 20 78 53 68 75  xInit() and xShu
122e0 74 64 6f 77 6e 28 29 20 2a 2f 0a 7d 3b 0a 0a 2f  tdown() */.};../
122f0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
12300 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 4f 70 74  onfiguration Opt
12310 69 6f 6e 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  ions.** KEYWORDS
12320 3a 20 7b 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  : {configuration
12330 20 6f 70 74 69 6f 6e 7d 0a 2a 2a 0a 2a 2a 20 54   option}.**.** T
12340 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61  hese constants a
12350 72 65 20 74 68 65 20 61 76 61 69 6c 61 62 6c 65  re the available
12360 20 69 6e 74 65 67 65 72 20 63 6f 6e 66 69 67 75   integer configu
12370 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 74  ration options t
12380 68 61 74 0a 2a 2a 20 63 61 6e 20 62 65 20 70 61  hat.** can be pa
12390 73 73 65 64 20 61 73 20 74 68 65 20 66 69 72 73  ssed as the firs
123a0 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  t argument to th
123b0 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  e [sqlite3_confi
123c0 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a  g()] interface..
123d0 2a 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66 69 67  **.** New config
123e0 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20  uration options 
123f0 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20  may be added in 
12400 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20  future releases 
12410 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 45 78  of SQLite..** Ex
12420 69 73 74 69 6e 67 20 63 6f 6e 66 69 67 75 72 61  isting configura
12430 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 69 67  tion options mig
12440 68 74 20 62 65 20 64 69 73 63 6f 6e 74 69 6e 75  ht be discontinu
12450 65 64 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e  ed.  Application
12460 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 63 68 65 63  s.** should chec
12470 6b 20 74 68 65 20 72 65 74 75 72 6e 20 63 6f 64  k the return cod
12480 65 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  e from [sqlite3_
12490 63 6f 6e 66 69 67 28 29 5d 20 74 6f 20 6d 61 6b  config()] to mak
124a0 65 20 73 75 72 65 20 74 68 61 74 0a 2a 2a 20 74  e sure that.** t
124b0 68 65 20 63 61 6c 6c 20 77 6f 72 6b 65 64 2e 20  he call worked. 
124c0 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f   The [sqlite3_co
124d0 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63  nfig()] interfac
124e0 65 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 61 0a  e will return a.
124f0 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72  ** non-zero [err
12500 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 20 64 69  or code] if a di
12510 73 63 6f 6e 74 69 6e 75 65 64 20 6f 72 20 75 6e  scontinued or un
12520 73 75 70 70 6f 72 74 65 64 20 63 6f 6e 66 69 67  supported config
12530 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a  uration option.*
12540 2a 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a  * is invoked..**
12550 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 51  .** <dl>.** [[SQ
12560 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47  LITE_CONFIG_SING
12570 4c 45 54 48 52 45 41 44 5d 5d 20 3c 64 74 3e 53  LETHREAD]] <dt>S
12580 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e  QLITE_CONFIG_SIN
12590 47 4c 45 54 48 52 45 41 44 3c 2f 64 74 3e 0a 2a  GLETHREAD</dt>.*
125a0 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20  * <dd>There are 
125b0 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20  no arguments to 
125c0 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54  this option.  ^T
125d0 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20  his option sets 
125e0 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e  the.** [threadin
125f0 67 20 6d 6f 64 65 5d 20 74 6f 20 53 69 6e 67 6c  g mode] to Singl
12600 65 2d 74 68 72 65 61 64 2e 20 20 49 6e 20 6f 74  e-thread.  In ot
12610 68 65 72 20 77 6f 72 64 73 2c 20 69 74 20 64 69  her words, it di
12620 73 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20 6d 75  sables.** all mu
12630 74 65 78 69 6e 67 20 61 6e 64 20 70 75 74 73 20  texing and puts 
12640 53 51 4c 69 74 65 20 69 6e 74 6f 20 61 20 6d 6f  SQLite into a mo
12650 64 65 20 77 68 65 72 65 20 69 74 20 63 61 6e 20  de where it can 
12660 6f 6e 6c 79 20 62 65 20 75 73 65 64 0a 2a 2a 20  only be used.** 
12670 62 79 20 61 20 73 69 6e 67 6c 65 20 74 68 72 65  by a single thre
12680 61 64 2e 20 20 20 5e 49 66 20 53 51 4c 69 74 65  ad.   ^If SQLite
12690 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74   is compiled wit
126a0 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45  h.** the [SQLITE
126b0 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20 53 51  _THREADSAFE | SQ
126c0 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d  LITE_THREADSAFE=
126d0 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  0] compile-time 
126e0 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69  option then.** i
126f0 74 20 69 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c  t is not possibl
12700 65 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65 20  e to change the 
12710 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d  [threading mode]
12720 20 66 72 6f 6d 20 69 74 73 20 64 65 66 61 75 6c   from its defaul
12730 74 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 53 69  t.** value of Si
12740 6e 67 6c 65 2d 74 68 72 65 61 64 20 61 6e 64 20  ngle-thread and 
12750 73 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  so [sqlite3_conf
12760 69 67 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72  ig()] will retur
12770 6e 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52  n .** [SQLITE_ER
12780 52 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64 20 77  ROR] if called w
12790 69 74 68 20 74 68 65 20 53 51 4c 49 54 45 5f 43  ith the SQLITE_C
127a0 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45  ONFIG_SINGLETHRE
127b0 41 44 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74  AD.** configurat
127c0 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e  ion option.</dd>
127d0 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
127e0 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45  CONFIG_MULTITHRE
127f0 41 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  AD]] <dt>SQLITE_
12800 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45  CONFIG_MULTITHRE
12810 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  AD</dt>.** <dd>T
12820 68 65 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75  here are no argu
12830 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70  ments to this op
12840 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74  tion.  ^This opt
12850 69 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20  ion sets the.** 
12860 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d  [threading mode]
12870 20 74 6f 20 4d 75 6c 74 69 2d 74 68 72 65 61 64   to Multi-thread
12880 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64  .  In other word
12890 73 2c 20 69 74 20 64 69 73 61 62 6c 65 73 0a 2a  s, it disables.*
128a0 2a 20 6d 75 74 65 78 69 6e 67 20 6f 6e 20 5b 64  * mutexing on [d
128b0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
128c0 6f 6e 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65  on] and [prepare
128d0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 62 6a  d statement] obj
128e0 65 63 74 73 2e 0a 2a 2a 20 54 68 65 20 61 70 70  ects..** The app
128f0 6c 69 63 61 74 69 6f 6e 20 69 73 20 72 65 73 70  lication is resp
12900 6f 6e 73 69 62 6c 65 20 66 6f 72 20 73 65 72 69  onsible for seri
12910 61 6c 69 7a 69 6e 67 20 61 63 63 65 73 73 20 74  alizing access t
12920 6f 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63  o.** [database c
12930 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 61 6e 64 20  onnections] and 
12940 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
12950 65 6e 74 73 5d 2e 20 20 42 75 74 20 6f 74 68 65  ents].  But othe
12960 72 20 6d 75 74 65 78 65 73 0a 2a 2a 20 61 72 65  r mutexes.** are
12970 20 65 6e 61 62 6c 65 64 20 73 6f 20 74 68 61 74   enabled so that
12980 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 62 65 20   SQLite will be 
12990 73 61 66 65 20 74 6f 20 75 73 65 20 69 6e 20 61  safe to use in a
129a0 20 6d 75 6c 74 69 2d 74 68 72 65 61 64 65 64 0a   multi-threaded.
129b0 2a 2a 20 65 6e 76 69 72 6f 6e 6d 65 6e 74 20 61  ** environment a
129c0 73 20 6c 6f 6e 67 20 61 73 20 6e 6f 20 74 77 6f  s long as no two
129d0 20 74 68 72 65 61 64 73 20 61 74 74 65 6d 70 74   threads attempt
129e0 20 74 6f 20 75 73 65 20 74 68 65 20 73 61 6d 65   to use the same
129f0 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f  .** [database co
12a00 6e 6e 65 63 74 69 6f 6e 5d 20 61 74 20 74 68 65  nnection] at the
12a10 20 73 61 6d 65 20 74 69 6d 65 2e 20 20 5e 49 66   same time.  ^If
12a20 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69   SQLite is compi
12a30 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20  led with.** the 
12a40 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41  [SQLITE_THREADSA
12a50 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45  FE | SQLITE_THRE
12a60 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c  ADSAFE=0] compil
12a70 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68  e-time option th
12a80 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20  en.** it is not 
12a90 70 6f 73 73 69 62 6c 65 20 74 6f 20 73 65 74 20  possible to set 
12aa0 74 68 65 20 4d 75 6c 74 69 2d 74 68 72 65 61 64  the Multi-thread
12ab0 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65   [threading mode
12ac0 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  ] and.** [sqlite
12ad0 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c  3_config()] will
12ae0 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
12af0 45 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64  ERROR] if called
12b00 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 53 51 4c   with the.** SQL
12b10 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49  ITE_CONFIG_MULTI
12b20 54 48 52 45 41 44 20 63 6f 6e 66 69 67 75 72 61  THREAD configura
12b30 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64  tion option.</dd
12b40 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
12b50 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a  _CONFIG_SERIALIZ
12b60 45 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  ED]] <dt>SQLITE_
12b70 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45  CONFIG_SERIALIZE
12b80 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  D</dt>.** <dd>Th
12b90 65 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d  ere are no argum
12ba0 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74  ents to this opt
12bb0 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74 69  ion.  ^This opti
12bc0 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b  on sets the.** [
12bd0 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20  threading mode] 
12be0 74 6f 20 53 65 72 69 61 6c 69 7a 65 64 2e 20 49  to Serialized. I
12bf0 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74  n other words, t
12c00 68 69 73 20 6f 70 74 69 6f 6e 20 65 6e 61 62 6c  his option enabl
12c10 65 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65 78 65  es.** all mutexe
12c20 73 20 69 6e 63 6c 75 64 69 6e 67 20 74 68 65 20  s including the 
12c30 72 65 63 75 72 73 69 76 65 0a 2a 2a 20 6d 75 74  recursive.** mut
12c40 65 78 65 73 20 6f 6e 20 5b 64 61 74 61 62 61 73  exes on [databas
12c50 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e  e connection] an
12c60 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  d [prepared stat
12c70 65 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 73 2e 0a  ement] objects..
12c80 2a 2a 20 49 6e 20 74 68 69 73 20 6d 6f 64 65 20  ** In this mode 
12c90 28 77 68 69 63 68 20 69 73 20 74 68 65 20 64 65  (which is the de
12ca0 66 61 75 6c 74 20 77 68 65 6e 20 53 51 4c 69 74  fault when SQLit
12cb0 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69  e is compiled wi
12cc0 74 68 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 54 48  th.** [SQLITE_TH
12cd0 52 45 41 44 53 41 46 45 3d 31 5d 29 20 74 68 65  READSAFE=1]) the
12ce0 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 20   SQLite library 
12cf0 77 69 6c 6c 20 69 74 73 65 6c 66 20 73 65 72 69  will itself seri
12d00 61 6c 69 7a 65 20 61 63 63 65 73 73 0a 2a 2a 20  alize access.** 
12d10 74 6f 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  to [database con
12d20 6e 65 63 74 69 6f 6e 73 5d 20 61 6e 64 20 5b 70  nections] and [p
12d30 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
12d40 74 73 5d 20 73 6f 20 74 68 61 74 20 74 68 65 0a  ts] so that the.
12d50 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69  ** application i
12d60 73 20 66 72 65 65 20 74 6f 20 75 73 65 20 74 68  s free to use th
12d70 65 20 73 61 6d 65 20 5b 64 61 74 61 62 61 73 65  e same [database
12d80 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 72 20   connection] or 
12d90 74 68 65 0a 2a 2a 20 73 61 6d 65 20 5b 70 72 65  the.** same [pre
12da0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
12db0 20 69 6e 20 64 69 66 66 65 72 65 6e 74 20 74 68   in different th
12dc0 72 65 61 64 73 20 61 74 20 74 68 65 20 73 61 6d  reads at the sam
12dd0 65 20 74 69 6d 65 2e 0a 2a 2a 20 5e 49 66 20 53  e time..** ^If S
12de0 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65  QLite is compile
12df0 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53  d with.** the [S
12e00 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
12e10 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44   | SQLITE_THREAD
12e20 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d  SAFE=0] compile-
12e30 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e  time option then
12e40 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20 70 6f  .** it is not po
12e50 73 73 69 62 6c 65 20 74 6f 20 73 65 74 20 74 68  ssible to set th
12e60 65 20 53 65 72 69 61 6c 69 7a 65 64 20 5b 74 68  e Serialized [th
12e70 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61 6e  reading mode] an
12e80 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  d.** [sqlite3_co
12e90 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20 72 65 74  nfig()] will ret
12ea0 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  urn [SQLITE_ERRO
12eb0 52 5d 20 69 66 20 63 61 6c 6c 65 64 20 77 69 74  R] if called wit
12ec0 68 20 74 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f  h the.** SQLITE_
12ed0 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45  CONFIG_SERIALIZE
12ee0 44 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  D configuration 
12ef0 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a  option.</dd>.**.
12f00 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
12f10 49 47 5f 4d 41 4c 4c 4f 43 5d 5d 20 3c 64 74 3e  IG_MALLOC]] <dt>
12f20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41  SQLITE_CONFIG_MA
12f30 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  LLOC</dt>.** <dd
12f40 3e 20 5e 28 54 68 65 20 53 51 4c 49 54 45 5f 43  > ^(The SQLITE_C
12f50 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 20 6f 70 74  ONFIG_MALLOC opt
12f60 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67  ion takes a sing
12f70 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63  le argument whic
12f80 68 20 69 73 20 0a 2a 2a 20 61 20 70 6f 69 6e 74  h is .** a point
12f90 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63  er to an instanc
12fa0 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  e of the [sqlite
12fb0 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73  3_mem_methods] s
12fc0 74 72 75 63 74 75 72 65 2e 0a 2a 2a 20 54 68 65  tructure..** The
12fd0 20 61 72 67 75 6d 65 6e 74 20 73 70 65 63 69 66   argument specif
12fe0 69 65 73 0a 2a 2a 20 61 6c 74 65 72 6e 61 74 69  ies.** alternati
12ff0 76 65 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d  ve low-level mem
13000 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72  ory allocation r
13010 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20 75 73  outines to be us
13020 65 64 20 69 6e 20 70 6c 61 63 65 20 6f 66 0a 2a  ed in place of.*
13030 2a 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c  * the memory all
13040 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73  ocation routines
13050 20 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69   built into SQLi
13060 74 65 2e 29 5e 20 5e 53 51 4c 69 74 65 20 6d 61  te.)^ ^SQLite ma
13070 6b 65 73 0a 2a 2a 20 69 74 73 20 6f 77 6e 20 70  kes.** its own p
13080 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20 74  rivate copy of t
13090 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68  he content of th
130a0 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d  e [sqlite3_mem_m
130b0 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72  ethods] structur
130c0 65 0a 2a 2a 20 62 65 66 6f 72 65 20 74 68 65 20  e.** before the 
130d0 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
130e0 29 5d 20 63 61 6c 6c 20 72 65 74 75 72 6e 73 2e  )] call returns.
130f0 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
13100 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d  LITE_CONFIG_GETM
13110 41 4c 4c 4f 43 5d 5d 20 3c 64 74 3e 53 51 4c 49  ALLOC]] <dt>SQLI
13120 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c  TE_CONFIG_GETMAL
13130 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  LOC</dt>.** <dd>
13140 20 5e 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f   ^(The SQLITE_CO
13150 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 20 6f  NFIG_GETMALLOC o
13160 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69  ption takes a si
13170 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68  ngle argument wh
13180 69 63 68 0a 2a 2a 20 69 73 20 61 20 70 6f 69 6e  ich.** is a poin
13190 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e  ter to an instan
131a0 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  ce of the [sqlit
131b0 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20  e3_mem_methods] 
131c0 73 74 72 75 63 74 75 72 65 2e 0a 2a 2a 20 54 68  structure..** Th
131d0 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d  e [sqlite3_mem_m
131e0 65 74 68 6f 64 73 5d 0a 2a 2a 20 73 74 72 75 63  ethods].** struc
131f0 74 75 72 65 20 69 73 20 66 69 6c 6c 65 64 20 77  ture is filled w
13200 69 74 68 20 74 68 65 20 63 75 72 72 65 6e 74 6c  ith the currentl
13210 79 20 64 65 66 69 6e 65 64 20 6d 65 6d 6f 72 79  y defined memory
13220 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74   allocation rout
13230 69 6e 65 73 2e 29 5e 0a 2a 2a 20 54 68 69 73 20  ines.)^.** This 
13240 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 73  option can be us
13250 65 64 20 74 6f 20 6f 76 65 72 6c 6f 61 64 20 74  ed to overload t
13260 68 65 20 64 65 66 61 75 6c 74 20 6d 65 6d 6f 72  he default memor
13270 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20  y allocation.** 
13280 72 6f 75 74 69 6e 65 73 20 77 69 74 68 20 61 20  routines with a 
13290 77 72 61 70 70 65 72 20 74 68 61 74 20 73 69 6d  wrapper that sim
132a0 75 6c 61 74 69 6f 6e 73 20 6d 65 6d 6f 72 79 20  ulations memory 
132b0 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 75  allocation failu
132c0 72 65 20 6f 72 0a 2a 2a 20 74 72 61 63 6b 73 20  re or.** tracks 
132d0 6d 65 6d 6f 72 79 20 75 73 61 67 65 2c 20 66 6f  memory usage, fo
132e0 72 20 65 78 61 6d 70 6c 65 2e 20 3c 2f 64 64 3e  r example. </dd>
132f0 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
13300 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53  CONFIG_MEMSTATUS
13310 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
13320 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 3c 2f  NFIG_MEMSTATUS</
13330 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 65  dt>.** <dd> ^The
13340 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d   SQLITE_CONFIG_M
13350 45 4d 53 54 41 54 55 53 20 6f 70 74 69 6f 6e 20  EMSTATUS option 
13360 74 61 6b 65 73 20 73 69 6e 67 6c 65 20 61 72 67  takes single arg
13370 75 6d 65 6e 74 20 6f 66 20 74 79 70 65 20 69 6e  ument of type in
13380 74 2c 0a 2a 2a 20 69 6e 74 65 72 70 72 65 74 65  t,.** interprete
13390 64 20 61 73 20 61 20 62 6f 6f 6c 65 61 6e 2c 20  d as a boolean, 
133a0 77 68 69 63 68 20 65 6e 61 62 6c 65 73 20 6f 72  which enables or
133b0 20 64 69 73 61 62 6c 65 73 20 74 68 65 20 63 6f   disables the co
133c0 6c 6c 65 63 74 69 6f 6e 20 6f 66 0a 2a 2a 20 6d  llection of.** m
133d0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
133e0 20 73 74 61 74 69 73 74 69 63 73 2e 20 5e 28 57   statistics. ^(W
133f0 68 65 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  hen memory alloc
13400 61 74 69 6f 6e 20 73 74 61 74 69 73 74 69 63 73  ation statistics
13410 20 61 72 65 0a 2a 2a 20 64 69 73 61 62 6c 65 64   are.** disabled
13420 2c 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  , the following 
13430 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65  SQLite interface
13440 73 20 62 65 63 6f 6d 65 20 6e 6f 6e 2d 6f 70 65  s become non-ope
13450 72 61 74 69 6f 6e 61 6c 3a 0a 2a 2a 20 20 20 3c  rational:.**   <
13460 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73  ul>.**   <li> [s
13470 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73  qlite3_memory_us
13480 65 64 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20  ed()].**   <li> 
13490 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f  [sqlite3_memory_
134a0 68 69 67 68 77 61 74 65 72 28 29 5d 0a 2a 2a 20  highwater()].** 
134b0 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f    <li> [sqlite3_
134c0 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 36  soft_heap_limit6
134d0 34 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b  4()].**   <li> [
134e0 73 71 6c 69 74 65 33 5f 73 74 61 74 75 73 36 34  sqlite3_status64
134f0 28 29 5d 0a 2a 2a 20 20 20 3c 2f 75 6c 3e 29 5e  ()].**   </ul>)^
13500 0a 2a 2a 20 5e 4d 65 6d 6f 72 79 20 61 6c 6c 6f  .** ^Memory allo
13510 63 61 74 69 6f 6e 20 73 74 61 74 69 73 74 69 63  cation statistic
13520 73 20 61 72 65 20 65 6e 61 62 6c 65 64 20 62 79  s are enabled by
13530 20 64 65 66 61 75 6c 74 20 75 6e 6c 65 73 73 20   default unless 
13540 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20 63 6f 6d  SQLite is.** com
13550 70 69 6c 65 64 20 77 69 74 68 20 5b 53 51 4c 49  piled with [SQLI
13560 54 45 5f 44 45 46 41 55 4c 54 5f 4d 45 4d 53 54  TE_DEFAULT_MEMST
13570 41 54 55 53 5d 3d 30 20 69 6e 20 77 68 69 63 68  ATUS]=0 in which
13580 20 63 61 73 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20   case memory.** 
13590 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 69  allocation stati
135a0 73 74 69 63 73 20 61 72 65 20 64 69 73 61 62 6c  stics are disabl
135b0 65 64 20 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a  ed by default..*
135c0 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  * </dd>.**.** [[
135d0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43  SQLITE_CONFIG_SC
135e0 52 41 54 43 48 5d 5d 20 3c 64 74 3e 53 51 4c 49  RATCH]] <dt>SQLI
135f0 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43  TE_CONFIG_SCRATC
13600 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  H</dt>.** <dd> ^
13610 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  The SQLITE_CONFI
13620 47 5f 53 43 52 41 54 43 48 20 6f 70 74 69 6f 6e  G_SCRATCH option
13630 20 73 70 65 63 69 66 69 65 73 20 61 20 73 74 61   specifies a sta
13640 74 69 63 20 6d 65 6d 6f 72 79 20 62 75 66 66 65  tic memory buffe
13650 72 0a 2a 2a 20 74 68 61 74 20 53 51 4c 69 74 65  r.** that SQLite
13660 20 63 61 6e 20 75 73 65 20 66 6f 72 20 73 63 72   can use for scr
13670 61 74 63 68 20 6d 65 6d 6f 72 79 2e 20 20 5e 28  atch memory.  ^(
13680 54 68 65 72 65 20 61 72 65 20 74 68 72 65 65 20  There are three 
13690 61 72 67 75 6d 65 6e 74 73 0a 2a 2a 20 74 6f 20  arguments.** to 
136a0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43  SQLITE_CONFIG_SC
136b0 52 41 54 43 48 3a 20 20 41 20 70 6f 69 6e 74 65  RATCH:  A pointe
136c0 72 20 61 6e 20 38 2d 62 79 74 65 0a 2a 2a 20 61  r an 8-byte.** a
136d0 6c 69 67 6e 65 64 20 6d 65 6d 6f 72 79 20 62 75  ligned memory bu
136e0 66 66 65 72 20 66 72 6f 6d 20 77 68 69 63 68 20  ffer from which 
136f0 74 68 65 20 73 63 72 61 74 63 68 20 61 6c 6c 6f  the scratch allo
13700 63 61 74 69 6f 6e 73 20 77 69 6c 6c 20 62 65 0a  cations will be.
13710 2a 2a 20 64 72 61 77 6e 2c 20 74 68 65 20 73 69  ** drawn, the si
13720 7a 65 20 6f 66 20 65 61 63 68 20 73 63 72 61 74  ze of each scrat
13730 63 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 28 73  ch allocation (s
13740 7a 29 2c 0a 2a 2a 20 61 6e 64 20 74 68 65 20 6d  z),.** and the m
13750 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66  aximum number of
13760 20 73 63 72 61 74 63 68 20 61 6c 6c 6f 63 61 74   scratch allocat
13770 69 6f 6e 73 20 28 4e 29 2e 29 5e 0a 2a 2a 20 54  ions (N).)^.** T
13780 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
13790 74 20 6d 75 73 74 20 62 65 20 61 20 70 6f 69 6e  t must be a poin
137a0 74 65 72 20 74 6f 20 61 6e 20 38 2d 62 79 74 65  ter to an 8-byte
137b0 20 61 6c 69 67 6e 65 64 20 62 75 66 66 65 72 0a   aligned buffer.
137c0 2a 2a 20 6f 66 20 61 74 20 6c 65 61 73 74 20 73  ** of at least s
137d0 7a 2a 4e 20 62 79 74 65 73 20 6f 66 20 6d 65 6d  z*N bytes of mem
137e0 6f 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20  ory..** ^SQLite 
137f0 77 69 6c 6c 20 6e 6f 74 20 75 73 65 20 6d 6f 72  will not use mor
13800 65 20 74 68 61 6e 20 6f 6e 65 20 73 63 72 61 74  e than one scrat
13810 63 68 20 62 75 66 66 65 72 73 20 70 65 72 20 74  ch buffers per t
13820 68 72 65 61 64 2e 0a 2a 2a 20 5e 53 51 4c 69 74  hread..** ^SQLit
13830 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 72 65 71  e will never req
13840 75 65 73 74 20 61 20 73 63 72 61 74 63 68 20 62  uest a scratch b
13850 75 66 66 65 72 20 74 68 61 74 20 69 73 20 6d 6f  uffer that is mo
13860 72 65 20 74 68 61 6e 20 36 0a 2a 2a 20 74 69 6d  re than 6.** tim
13870 65 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20  es the database 
13880 70 61 67 65 20 73 69 7a 65 2e 0a 2a 2a 20 5e 49  page size..** ^I
13890 66 20 53 51 4c 69 74 65 20 6e 65 65 64 73 20 6e  f SQLite needs n
138a0 65 65 64 73 20 61 64 64 69 74 69 6f 6e 61 6c 0a  eeds additional.
138b0 2a 2a 20 73 63 72 61 74 63 68 20 6d 65 6d 6f 72  ** scratch memor
138c0 79 20 62 65 79 6f 6e 64 20 77 68 61 74 20 69 73  y beyond what is
138d0 20 70 72 6f 76 69 64 65 64 20 62 79 20 74 68 69   provided by thi
138e0 73 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  s configuration 
138f0 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 20 0a 2a 2a  option, then .**
13900 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
13910 28 29 5d 20 77 69 6c 6c 20 62 65 20 75 73 65 64  ()] will be used
13920 20 74 6f 20 6f 62 74 61 69 6e 20 74 68 65 20 6d   to obtain the m
13930 65 6d 6f 72 79 20 6e 65 65 64 65 64 2e 3c 70 3e  emory needed.<p>
13940 0a 2a 2a 20 5e 57 68 65 6e 20 74 68 65 20 61 70  .** ^When the ap
13950 70 6c 69 63 61 74 69 6f 6e 20 70 72 6f 76 69 64  plication provid
13960 65 73 20 61 6e 79 20 61 6d 6f 75 6e 74 20 6f 66  es any amount of
13970 20 73 63 72 61 74 63 68 20 6d 65 6d 6f 72 79 20   scratch memory 
13980 75 73 69 6e 67 0a 2a 2a 20 53 51 4c 49 54 45 5f  using.** SQLITE_
13990 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 2c 20  CONFIG_SCRATCH, 
139a0 53 51 4c 69 74 65 20 61 76 6f 69 64 73 20 75 6e  SQLite avoids un
139b0 6e 65 63 65 73 73 61 72 79 20 6c 61 72 67 65 0a  necessary large.
139c0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  ** [sqlite3_mall
139d0 6f 63 7c 68 65 61 70 20 61 6c 6c 6f 63 61 74 69  oc|heap allocati
139e0 6f 6e 73 5d 2e 0a 2a 2a 20 54 68 69 73 20 63 61  ons]..** This ca
139f0 6e 20 68 65 6c 70 20 5b 52 6f 62 73 6f 6e 20 70  n help [Robson p
13a00 72 6f 6f 66 7c 70 72 65 76 65 6e 74 20 6d 65 6d  roof|prevent mem
13a10 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66  ory allocation f
13a20 61 69 6c 75 72 65 73 5d 20 64 75 65 20 74 6f 20  ailures] due to 
13a30 68 65 61 70 0a 2a 2a 20 66 72 61 67 6d 65 6e 74  heap.** fragment
13a40 61 74 69 6f 6e 20 69 6e 20 6c 6f 77 2d 6d 65 6d  ation in low-mem
13a50 6f 72 79 20 65 6d 62 65 64 64 65 64 20 73 79 73  ory embedded sys
13a60 74 65 6d 73 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a  tems..** </dd>.*
13a70 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
13a80 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 5d 5d  NFIG_PAGECACHE]]
13a90 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
13aa0 49 47 5f 50 41 47 45 43 41 43 48 45 3c 2f 64 74  IG_PAGECACHE</dt
13ab0 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 65 20 53  >.** <dd> ^The S
13ac0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47  QLITE_CONFIG_PAG
13ad0 45 43 41 43 48 45 20 6f 70 74 69 6f 6e 20 73 70  ECACHE option sp
13ae0 65 63 69 66 69 65 73 20 61 20 6d 65 6d 6f 72 79  ecifies a memory
13af0 20 70 6f 6f 6c 0a 2a 2a 20 74 68 61 74 20 53 51   pool.** that SQ
13b00 4c 69 74 65 20 63 61 6e 20 75 73 65 20 66 6f 72  Lite can use for
13b10 20 74 68 65 20 64 61 74 61 62 61 73 65 20 70 61   the database pa
13b20 67 65 20 63 61 63 68 65 20 77 69 74 68 20 74 68  ge cache with th
13b30 65 20 64 65 66 61 75 6c 74 20 70 61 67 65 0a 2a  e default page.*
13b40 2a 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e  * cache implemen
13b50 74 61 74 69 6f 6e 2e 20 20 0a 2a 2a 20 54 68 69  tation.  .** Thi
13b60 73 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  s configuration 
13b70 6f 70 74 69 6f 6e 20 69 73 20 61 20 6e 6f 2d 6f  option is a no-o
13b80 70 20 69 66 20 61 6e 20 61 70 70 6c 69 63 61 74  p if an applicat
13b90 69 6f 6e 2d 64 65 66 69 6e 65 20 70 61 67 65 0a  ion-define page.
13ba0 2a 2a 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65  ** cache impleme
13bb0 6e 74 61 74 69 6f 6e 20 69 73 20 6c 6f 61 64 65  ntation is loade
13bc0 64 20 75 73 69 6e 67 20 74 68 65 20 5b 53 51 4c  d using the [SQL
13bd0 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48  ITE_CONFIG_PCACH
13be0 45 32 5d 2e 0a 2a 2a 20 5e 54 68 65 72 65 20 61  E2]..** ^There a
13bf0 72 65 20 74 68 72 65 65 20 61 72 67 75 6d 65 6e  re three argumen
13c00 74 73 20 74 6f 20 53 51 4c 49 54 45 5f 43 4f 4e  ts to SQLITE_CON
13c10 46 49 47 5f 50 41 47 45 43 41 43 48 45 3a 20 41  FIG_PAGECACHE: A
13c20 20 70 6f 69 6e 74 65 72 20 74 6f 0a 2a 2a 20 38   pointer to.** 8
13c30 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 20 6d 65  -byte aligned me
13c40 6d 6f 72 79 20 28 70 4d 65 6d 29 2c 20 74 68 65  mory (pMem), the
13c50 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20 70 61   size of each pa
13c60 67 65 20 63 61 63 68 65 20 6c 69 6e 65 20 28 73  ge cache line (s
13c70 7a 29 2c 0a 2a 2a 20 61 6e 64 20 74 68 65 20 6e  z),.** and the n
13c80 75 6d 62 65 72 20 6f 66 20 63 61 63 68 65 20 6c  umber of cache l
13c90 69 6e 65 73 20 28 4e 29 2e 0a 2a 2a 20 54 68 65  ines (N)..** The
13ca0 20 73 7a 20 61 72 67 75 6d 65 6e 74 20 73 68 6f   sz argument sho
13cb0 75 6c 64 20 62 65 20 74 68 65 20 73 69 7a 65 20  uld be the size 
13cc0 6f 66 20 74 68 65 20 6c 61 72 67 65 73 74 20 64  of the largest d
13cd0 61 74 61 62 61 73 65 20 70 61 67 65 0a 2a 2a 20  atabase page.** 
13ce0 28 61 20 70 6f 77 65 72 20 6f 66 20 74 77 6f 20  (a power of two 
13cf0 62 65 74 77 65 65 6e 20 35 31 32 20 61 6e 64 20  between 512 and 
13d00 36 35 35 33 36 29 20 70 6c 75 73 20 73 6f 6d 65  65536) plus some
13d10 20 65 78 74 72 61 20 62 79 74 65 73 20 66 6f 72   extra bytes for
13d20 20 65 61 63 68 0a 2a 2a 20 70 61 67 65 20 68 65   each.** page he
13d30 61 64 65 72 2e 20 20 5e 54 68 65 20 6e 75 6d 62  ader.  ^The numb
13d40 65 72 20 6f 66 20 65 78 74 72 61 20 62 79 74 65  er of extra byte
13d50 73 20 6e 65 65 64 65 64 20 62 79 20 74 68 65 20  s needed by the 
13d60 70 61 67 65 20 68 65 61 64 65 72 0a 2a 2a 20 63  page header.** c
13d70 61 6e 20 62 65 20 64 65 74 65 72 6d 69 6e 65 64  an be determined
13d80 20 75 73 69 6e 67 20 5b 53 51 4c 49 54 45 5f 43   using [SQLITE_C
13d90 4f 4e 46 49 47 5f 50 43 41 43 48 45 5f 48 44 52  ONFIG_PCACHE_HDR
13da0 53 5a 5d 2e 0a 2a 2a 20 5e 49 74 20 69 73 20 68  SZ]..** ^It is h
13db0 61 72 6d 6c 65 73 73 2c 20 61 70 61 72 74 20 66  armless, apart f
13dc0 72 6f 6d 20 74 68 65 20 77 61 73 74 65 64 20 6d  rom the wasted m
13dd0 65 6d 6f 72 79 2c 0a 2a 2a 20 66 6f 72 20 74 68  emory,.** for th
13de0 65 20 73 7a 20 70 61 72 61 6d 65 74 65 72 20 74  e sz parameter t
13df0 6f 20 62 65 20 6c 61 72 67 65 72 20 74 68 61 6e  o be larger than
13e00 20 6e 65 63 65 73 73 61 72 79 2e 20 20 54 68 65   necessary.  The
13e10 20 70 4d 65 6d 0a 2a 2a 20 61 72 67 75 6d 65 6e   pMem.** argumen
13e20 74 20 6d 75 73 74 20 62 65 20 65 69 74 68 65 72  t must be either
13e30 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
13e40 6f 72 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  or a pointer to 
13e50 61 6e 20 38 2d 62 79 74 65 0a 2a 2a 20 61 6c 69  an 8-byte.** ali
13e60 67 6e 65 64 20 62 6c 6f 63 6b 20 6f 66 20 6d 65  gned block of me
13e70 6d 6f 72 79 20 6f 66 20 61 74 20 6c 65 61 73 74  mory of at least
13e80 20 73 7a 2a 4e 20 62 79 74 65 73 2c 20 6f 74 68   sz*N bytes, oth
13e90 65 72 77 69 73 65 0a 2a 2a 20 73 75 62 73 65 71  erwise.** subseq
13ea0 75 65 6e 74 20 62 65 68 61 76 69 6f 72 20 69 73  uent behavior is
13eb0 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 5e   undefined..** ^
13ec0 57 68 65 6e 20 70 4d 65 6d 20 69 73 20 6e 6f 74  When pMem is not
13ed0 20 4e 55 4c 4c 2c 20 53 51 4c 69 74 65 20 77 69   NULL, SQLite wi
13ee0 6c 6c 20 73 74 72 69 76 65 20 74 6f 20 75 73 65  ll strive to use
13ef0 20 74 68 65 20 6d 65 6d 6f 72 79 20 70 72 6f 76   the memory prov
13f00 69 64 65 64 0a 2a 2a 20 74 6f 20 73 61 74 69 73  ided.** to satis
13f10 66 79 20 70 61 67 65 20 63 61 63 68 65 20 6e 65  fy page cache ne
13f20 65 64 73 2c 20 66 61 6c 6c 69 6e 67 20 62 61 63  eds, falling bac
13f30 6b 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6d 61  k to [sqlite3_ma
13f40 6c 6c 6f 63 28 29 5d 20 69 66 0a 2a 2a 20 61 20  lloc()] if.** a 
13f50 70 61 67 65 20 63 61 63 68 65 20 6c 69 6e 65 20  page cache line 
13f60 69 73 20 6c 61 72 67 65 72 20 74 68 61 6e 20 73  is larger than s
13f70 7a 20 62 79 74 65 73 20 6f 72 20 69 66 20 61 6c  z bytes or if al
13f80 6c 20 6f 66 20 74 68 65 20 70 4d 65 6d 20 62 75  l of the pMem bu
13f90 66 66 65 72 0a 2a 2a 20 69 73 20 65 78 68 61 75  ffer.** is exhau
13fa0 73 74 65 64 2e 0a 2a 2a 20 5e 49 66 20 70 4d 65  sted..** ^If pMe
13fb0 6d 20 69 73 20 4e 55 4c 4c 20 61 6e 64 20 4e 20  m is NULL and N 
13fc0 69 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65  is non-zero, the
13fd0 6e 20 65 61 63 68 20 64 61 74 61 62 61 73 65 20  n each database 
13fe0 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 64 6f  connection.** do
13ff0 65 73 20 61 6e 20 69 6e 69 74 69 61 6c 20 62 75  es an initial bu
14000 6c 6b 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 6f  lk allocation fo
14010 72 20 70 61 67 65 20 63 61 63 68 65 20 6d 65 6d  r page cache mem
14020 6f 72 79 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c  ory.** from [sql
14030 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 73  ite3_malloc()] s
14040 75 66 66 69 63 69 65 6e 74 20 66 6f 72 20 4e 20  ufficient for N 
14050 63 61 63 68 65 20 6c 69 6e 65 73 20 69 66 20 4e  cache lines if N
14060 20 69 73 20 70 6f 73 69 74 69 76 65 20 6f 72 0a   is positive or.
14070 2a 2a 20 6f 66 20 2d 31 30 32 34 2a 4e 20 62 79  ** of -1024*N by
14080 74 65 73 20 69 66 20 4e 20 69 73 20 6e 65 67 61  tes if N is nega
14090 74 69 76 65 2c 20 2e 20 5e 49 66 20 61 64 64 69  tive, . ^If addi
140a0 74 69 6f 6e 61 6c 0a 2a 2a 20 70 61 67 65 20 63  tional.** page c
140b0 61 63 68 65 20 6d 65 6d 6f 72 79 20 69 73 20 6e  ache memory is n
140c0 65 65 64 65 64 20 62 65 79 6f 6e 64 20 77 68 61  eeded beyond wha
140d0 74 20 69 73 20 70 72 6f 76 69 64 65 64 20 62 79  t is provided by
140e0 20 74 68 65 20 69 6e 69 74 69 61 6c 0a 2a 2a 20   the initial.** 
140f0 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20 74 68 65 6e  allocation, then
14100 20 53 51 4c 69 74 65 20 67 6f 65 73 20 74 6f 20   SQLite goes to 
14110 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
14120 29 5d 20 73 65 70 61 72 61 74 65 6c 79 20 66 6f  )] separately fo
14130 72 20 65 61 63 68 0a 2a 2a 20 61 64 64 69 74 69  r each.** additi
14140 6f 6e 61 6c 20 63 61 63 68 65 20 6c 69 6e 65 2e  onal cache line.
14150 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53   </dd>.**.** [[S
14160 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41  QLITE_CONFIG_HEA
14170 50 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  P]] <dt>SQLITE_C
14180 4f 4e 46 49 47 5f 48 45 41 50 3c 2f 64 74 3e 0a  ONFIG_HEAP</dt>.
14190 2a 2a 20 3c 64 64 3e 20 5e 54 68 65 20 53 51 4c  ** <dd> ^The SQL
141a0 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 20  ITE_CONFIG_HEAP 
141b0 6f 70 74 69 6f 6e 20 73 70 65 63 69 66 69 65 73  option specifies
141c0 20 61 20 73 74 61 74 69 63 20 6d 65 6d 6f 72 79   a static memory
141d0 20 62 75 66 66 65 72 20 0a 2a 2a 20 74 68 61 74   buffer .** that
141e0 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65   SQLite will use
141f0 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73 20   for all of its 
14200 64 79 6e 61 6d 69 63 20 6d 65 6d 6f 72 79 20 61  dynamic memory a
14210 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 0a  llocation needs.
14220 2a 2a 20 62 65 79 6f 6e 64 20 74 68 6f 73 65 20  ** beyond those 
14230 70 72 6f 76 69 64 65 64 20 66 6f 72 20 62 79 20  provided for by 
14240 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53  [SQLITE_CONFIG_S
14250 43 52 41 54 43 48 5d 20 61 6e 64 0a 2a 2a 20 5b  CRATCH] and.** [
14260 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41  SQLITE_CONFIG_PA
14270 47 45 43 41 43 48 45 5d 2e 0a 2a 2a 20 5e 54 68  GECACHE]..** ^Th
14280 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
14290 48 45 41 50 20 6f 70 74 69 6f 6e 20 69 73 20 6f  HEAP option is o
142a0 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 69 66  nly available if
142b0 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69   SQLite is compi
142c0 6c 65 64 0a 2a 2a 20 77 69 74 68 20 65 69 74 68  led.** with eith
142d0 65 72 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c  er [SQLITE_ENABL
142e0 45 5f 4d 45 4d 53 59 53 33 5d 20 6f 72 20 5b 53  E_MEMSYS3] or [S
142f0 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d  QLITE_ENABLE_MEM
14300 53 59 53 35 5d 20 61 6e 64 20 72 65 74 75 72 6e  SYS5] and return
14310 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52  s.** [SQLITE_ERR
14320 4f 52 5d 20 69 66 20 69 6e 76 6f 6b 65 64 20 6f  OR] if invoked o
14330 74 68 65 72 77 69 73 65 2e 0a 2a 2a 20 5e 54 68  therwise..** ^Th
14340 65 72 65 20 61 72 65 20 74 68 72 65 65 20 61 72  ere are three ar
14350 67 75 6d 65 6e 74 73 20 74 6f 20 53 51 4c 49 54  guments to SQLIT
14360 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 3a 0a 2a  E_CONFIG_HEAP:.*
14370 2a 20 41 6e 20 38 2d 62 79 74 65 20 61 6c 69 67  * An 8-byte alig
14380 6e 65 64 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  ned pointer to t
14390 68 65 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20 74 68  he memory,.** th
143a0 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  e number of byte
143b0 73 20 69 6e 20 74 68 65 20 6d 65 6d 6f 72 79 20  s in the memory 
143c0 62 75 66 66 65 72 2c 20 61 6e 64 20 74 68 65 20  buffer, and the 
143d0 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69  minimum allocati
143e0 6f 6e 20 73 69 7a 65 2e 0a 2a 2a 20 5e 49 66 20  on size..** ^If 
143f0 74 68 65 20 66 69 72 73 74 20 70 6f 69 6e 74 65  the first pointe
14400 72 20 28 74 68 65 20 6d 65 6d 6f 72 79 20 70 6f  r (the memory po
14410 69 6e 74 65 72 29 20 69 73 20 4e 55 4c 4c 2c 20  inter) is NULL, 
14420 74 68 65 6e 20 53 51 4c 69 74 65 20 72 65 76 65  then SQLite reve
14430 72 74 73 0a 2a 2a 20 74 6f 20 75 73 69 6e 67 20  rts.** to using 
14440 69 74 73 20 64 65 66 61 75 6c 74 20 6d 65 6d 6f  its default memo
14450 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 28 74 68  ry allocator (th
14460 65 20 73 79 73 74 65 6d 20 6d 61 6c 6c 6f 63 28  e system malloc(
14470 29 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  ) implementation
14480 29 2c 0a 2a 2a 20 75 6e 64 6f 69 6e 67 20 61 6e  ),.** undoing an
14490 79 20 70 72 69 6f 72 20 69 6e 76 6f 63 61 74 69  y prior invocati
144a0 6f 6e 20 6f 66 20 5b 53 51 4c 49 54 45 5f 43 4f  on of [SQLITE_CO
144b0 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 2e 20 20 5e  NFIG_MALLOC].  ^
144c0 49 66 20 74 68 65 0a 2a 2a 20 6d 65 6d 6f 72 79  If the.** memory
144d0 20 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74 20   pointer is not 
144e0 4e 55 4c 4c 20 74 68 65 6e 20 74 68 65 20 61 6c  NULL then the al
144f0 74 65 72 6e 61 74 69 76 65 20 6d 65 6d 6f 72 79  ternative memory
14500 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72 20 69 73  .** allocator is
14510 20 65 6e 67 61 67 65 64 20 74 6f 20 68 61 6e 64   engaged to hand
14520 6c 65 20 61 6c 6c 20 6f 66 20 53 51 4c 69 74 65  le all of SQLite
14530 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  s memory allocat
14540 69 6f 6e 20 6e 65 65 64 73 2e 0a 2a 2a 20 54 68  ion needs..** Th
14550 65 20 66 69 72 73 74 20 70 6f 69 6e 74 65 72 20  e first pointer 
14560 28 74 68 65 20 6d 65 6d 6f 72 79 20 70 6f 69 6e  (the memory poin
14570 74 65 72 29 20 6d 75 73 74 20 62 65 20 61 6c 69  ter) must be ali
14580 67 6e 65 64 20 74 6f 20 61 6e 20 38 2d 62 79 74  gned to an 8-byt
14590 65 0a 2a 2a 20 62 6f 75 6e 64 61 72 79 20 6f 72  e.** boundary or
145a0 20 73 75 62 73 65 71 75 65 6e 74 20 62 65 68 61   subsequent beha
145b0 76 69 6f 72 20 6f 66 20 53 51 4c 69 74 65 20 77  vior of SQLite w
145c0 69 6c 6c 20 62 65 20 75 6e 64 65 66 69 6e 65 64  ill be undefined
145d0 2e 0a 2a 2a 20 54 68 65 20 6d 69 6e 69 6d 75 6d  ..** The minimum
145e0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65   allocation size
145f0 20 69 73 20 63 61 70 70 65 64 20 61 74 20 32 2a   is capped at 2*
14600 2a 31 32 2e 20 52 65 61 73 6f 6e 61 62 6c 65 20  *12. Reasonable 
14610 76 61 6c 75 65 73 0a 2a 2a 20 66 6f 72 20 74 68  values.** for th
14620 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61  e minimum alloca
14630 74 69 6f 6e 20 73 69 7a 65 20 61 72 65 20 32 2a  tion size are 2*
14640 2a 35 20 74 68 72 6f 75 67 68 20 32 2a 2a 38 2e  *5 through 2**8.
14650 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
14660 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45  LITE_CONFIG_MUTE
14670 58 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  X]] <dt>SQLITE_C
14680 4f 4e 46 49 47 5f 4d 55 54 45 58 3c 2f 64 74 3e  ONFIG_MUTEX</dt>
14690 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 53  .** <dd> ^(The S
146a0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54  QLITE_CONFIG_MUT
146b0 45 58 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  EX option takes 
146c0 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e  a single argumen
146d0 74 20 77 68 69 63 68 20 69 73 20 61 0a 2a 2a 20  t which is a.** 
146e0 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e  pointer to an in
146f0 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73  stance of the [s
14700 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74  qlite3_mutex_met
14710 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e  hods] structure.
14720 0a 2a 2a 20 54 68 65 20 61 72 67 75 6d 65 6e 74  .** The argument
14730 20 73 70 65 63 69 66 69 65 73 20 61 6c 74 65 72   specifies alter
14740 6e 61 74 69 76 65 20 6c 6f 77 2d 6c 65 76 65 6c  native low-level
14750 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73 20   mutex routines 
14760 74 6f 20 62 65 20 75 73 65 64 0a 2a 2a 20 69 6e  to be used.** in
14770 20 70 6c 61 63 65 20 74 68 65 20 6d 75 74 65 78   place the mutex
14780 20 72 6f 75 74 69 6e 65 73 20 62 75 69 6c 74 20   routines built 
14790 69 6e 74 6f 20 53 51 4c 69 74 65 2e 29 5e 20 20  into SQLite.)^  
147a0 5e 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 61 20  ^SQLite makes a 
147b0 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 63  copy of.** the c
147c0 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 5b 73  ontent of the [s
147d0 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74  qlite3_mutex_met
147e0 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 20  hods] structure 
147f0 62 65 66 6f 72 65 20 74 68 65 20 63 61 6c 6c 20  before the call 
14800 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  to.** [sqlite3_c
14810 6f 6e 66 69 67 28 29 5d 20 72 65 74 75 72 6e 73  onfig()] returns
14820 2e 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20  . ^If SQLite is 
14830 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a  compiled with.**
14840 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52   the [SQLITE_THR
14850 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45  EADSAFE | SQLITE
14860 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63  _THREADSAFE=0] c
14870 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
14880 6f 6e 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 65  on then.** the e
14890 6e 74 69 72 65 20 6d 75 74 65 78 69 6e 67 20 73  ntire mutexing s
148a0 75 62 73 79 73 74 65 6d 20 69 73 20 6f 6d 69 74  ubsystem is omit
148b0 74 65 64 20 66 72 6f 6d 20 74 68 65 20 62 75 69  ted from the bui
148c0 6c 64 20 61 6e 64 20 68 65 6e 63 65 20 63 61 6c  ld and hence cal
148d0 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  ls to.** [sqlite
148e0 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 74 68  3_config()] with
148f0 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46   the SQLITE_CONF
14900 49 47 5f 4d 55 54 45 58 20 63 6f 6e 66 69 67 75  IG_MUTEX configu
14910 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 77 69  ration option wi
14920 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51  ll.** return [SQ
14930 4c 49 54 45 5f 45 52 52 4f 52 5d 2e 3c 2f 64 64  LITE_ERROR].</dd
14940 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
14950 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58  _CONFIG_GETMUTEX
14960 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
14970 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 3c 2f 64  NFIG_GETMUTEX</d
14980 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65  t>.** <dd> ^(The
14990 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47   SQLITE_CONFIG_G
149a0 45 54 4d 55 54 45 58 20 6f 70 74 69 6f 6e 20 74  ETMUTEX option t
149b0 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72  akes a single ar
149c0 67 75 6d 65 6e 74 20 77 68 69 63 68 0a 2a 2a 20  gument which.** 
149d0 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
149e0 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  an instance of t
149f0 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  he [sqlite3_mute
14a00 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63  x_methods] struc
14a10 74 75 72 65 2e 20 20 54 68 65 0a 2a 2a 20 5b 73  ture.  The.** [s
14a20 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74  qlite3_mutex_met
14a30 68 6f 64 73 5d 0a 2a 2a 20 73 74 72 75 63 74 75  hods].** structu
14a40 72 65 20 69 73 20 66 69 6c 6c 65 64 20 77 69 74  re is filled wit
14a50 68 20 74 68 65 20 63 75 72 72 65 6e 74 6c 79 20  h the currently 
14a60 64 65 66 69 6e 65 64 20 6d 75 74 65 78 20 72 6f  defined mutex ro
14a70 75 74 69 6e 65 73 2e 29 5e 0a 2a 2a 20 54 68 69  utines.)^.** Thi
14a80 73 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20  s option can be 
14a90 75 73 65 64 20 74 6f 20 6f 76 65 72 6c 6f 61 64  used to overload
14aa0 20 74 68 65 20 64 65 66 61 75 6c 74 20 6d 75 74   the default mut
14ab0 65 78 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a  ex allocation.**
14ac0 20 72 6f 75 74 69 6e 65 73 20 77 69 74 68 20 61   routines with a
14ad0 20 77 72 61 70 70 65 72 20 75 73 65 64 20 74 6f   wrapper used to
14ae0 20 74 72 61 63 6b 20 6d 75 74 65 78 20 75 73 61   track mutex usa
14af0 67 65 20 66 6f 72 20 70 65 72 66 6f 72 6d 61 6e  ge for performan
14b00 63 65 0a 2a 2a 20 70 72 6f 66 69 6c 69 6e 67 20  ce.** profiling 
14b10 6f 72 20 74 65 73 74 69 6e 67 2c 20 66 6f 72 20  or testing, for 
14b20 65 78 61 6d 70 6c 65 2e 20 20 20 5e 49 66 20 53  example.   ^If S
14b30 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65  QLite is compile
14b40 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53  d with.** the [S
14b50 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
14b60 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44   | SQLITE_THREAD
14b70 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d  SAFE=0] compile-
14b80 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e  time option then
14b90 0a 2a 2a 20 74 68 65 20 65 6e 74 69 72 65 20 6d  .** the entire m
14ba0 75 74 65 78 69 6e 67 20 73 75 62 73 79 73 74 65  utexing subsyste
14bb0 6d 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f  m is omitted fro
14bc0 6d 20 74 68 65 20 62 75 69 6c 64 20 61 6e 64 20  m the build and 
14bd0 68 65 6e 63 65 20 63 61 6c 6c 73 20 74 6f 0a 2a  hence calls to.*
14be0 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  * [sqlite3_confi
14bf0 67 28 29 5d 20 77 69 74 68 20 74 68 65 20 53 51  g()] with the SQ
14c00 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d  LITE_CONFIG_GETM
14c10 55 54 45 58 20 63 6f 6e 66 69 67 75 72 61 74 69  UTEX configurati
14c20 6f 6e 20 6f 70 74 69 6f 6e 20 77 69 6c 6c 0a 2a  on option will.*
14c30 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  * return [SQLITE
14c40 5f 45 52 52 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a  _ERROR].</dd>.**
14c50 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
14c60 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 5d 20  FIG_LOOKASIDE]] 
14c70 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
14c80 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64 74 3e  G_LOOKASIDE</dt>
14c90 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 53  .** <dd> ^(The S
14ca0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f  QLITE_CONFIG_LOO
14cb0 4b 41 53 49 44 45 20 6f 70 74 69 6f 6e 20 74 61  KASIDE option ta
14cc0 6b 65 73 20 74 77 6f 20 61 72 67 75 6d 65 6e 74  kes two argument
14cd0 73 20 74 68 61 74 20 64 65 74 65 72 6d 69 6e 65  s that determine
14ce0 0a 2a 2a 20 74 68 65 20 64 65 66 61 75 6c 74 20  .** the default 
14cf0 73 69 7a 65 20 6f 66 20 6c 6f 6f 6b 61 73 69 64  size of lookasid
14d00 65 20 6d 65 6d 6f 72 79 20 6f 6e 20 65 61 63 68  e memory on each
14d10 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
14d20 63 74 69 6f 6e 5d 2e 0a 2a 2a 20 54 68 65 20 66  ction]..** The f
14d30 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73  irst argument is
14d40 20 74 68 65 0a 2a 2a 20 73 69 7a 65 20 6f 66 20   the.** size of 
14d50 65 61 63 68 20 6c 6f 6f 6b 61 73 69 64 65 20 62  each lookaside b
14d60 75 66 66 65 72 20 73 6c 6f 74 20 61 6e 64 20 74  uffer slot and t
14d70 68 65 20 73 65 63 6f 6e 64 20 69 73 20 74 68 65  he second is the
14d80 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 73 6c   number of.** sl
14d90 6f 74 73 20 61 6c 6c 6f 63 61 74 65 64 20 74 6f  ots allocated to
14da0 20 65 61 63 68 20 64 61 74 61 62 61 73 65 20 63   each database c
14db0 6f 6e 6e 65 63 74 69 6f 6e 2e 29 5e 20 20 5e 28  onnection.)^  ^(
14dc0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f  SQLITE_CONFIG_LO
14dd0 4f 4b 41 53 49 44 45 0a 2a 2a 20 73 65 74 73 20  OKASIDE.** sets 
14de0 74 68 65 20 3c 69 3e 64 65 66 61 75 6c 74 3c 2f  the <i>default</
14df0 69 3e 20 6c 6f 6f 6b 61 73 69 64 65 20 73 69 7a  i> lookaside siz
14e00 65 2e 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 44  e. The [SQLITE_D
14e10 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44  BCONFIG_LOOKASID
14e20 45 5d 0a 2a 2a 20 6f 70 74 69 6f 6e 20 74 6f 20  E].** option to 
14e30 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66  [sqlite3_db_conf
14e40 69 67 28 29 5d 20 63 61 6e 20 62 65 20 75 73 65  ig()] can be use
14e50 64 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65 20  d to change the 
14e60 6c 6f 6f 6b 61 73 69 64 65 0a 2a 2a 20 63 6f 6e  lookaside.** con
14e70 66 69 67 75 72 61 74 69 6f 6e 20 6f 6e 20 69 6e  figuration on in
14e80 64 69 76 69 64 75 61 6c 20 63 6f 6e 6e 65 63 74  dividual connect
14e90 69 6f 6e 73 2e 29 5e 20 3c 2f 64 64 3e 0a 2a 2a  ions.)^ </dd>.**
14ea0 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
14eb0 46 49 47 5f 50 43 41 43 48 45 32 5d 5d 20 3c 64  FIG_PCACHE2]] <d
14ec0 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
14ed0 50 43 41 43 48 45 32 3c 2f 64 74 3e 0a 2a 2a 20  PCACHE2</dt>.** 
14ee0 3c 64 64 3e 20 5e 28 54 68 65 20 53 51 4c 49 54  <dd> ^(The SQLIT
14ef0 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32  E_CONFIG_PCACHE2
14f00 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20   option takes a 
14f10 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20  single argument 
14f20 77 68 69 63 68 20 69 73 20 0a 2a 2a 20 61 20 70  which is .** a p
14f30 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 5b 73 71  ointer to an [sq
14f40 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74  lite3_pcache_met
14f50 68 6f 64 73 32 5d 20 6f 62 6a 65 63 74 2e 20 20  hods2] object.  
14f60 54 68 69 73 20 6f 62 6a 65 63 74 20 73 70 65 63  This object spec
14f70 69 66 69 65 73 0a 2a 2a 20 74 68 65 20 69 6e 74  ifies.** the int
14f80 65 72 66 61 63 65 20 74 6f 20 61 20 63 75 73 74  erface to a cust
14f90 6f 6d 20 70 61 67 65 20 63 61 63 68 65 20 69 6d  om page cache im
14fa0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 29 5e 0a  plementation.)^.
14fb0 2a 2a 20 5e 53 51 4c 69 74 65 20 6d 61 6b 65 73  ** ^SQLite makes
14fc0 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 5b   a copy of the [
14fd0 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d  sqlite3_pcache_m
14fe0 65 74 68 6f 64 73 32 5d 20 6f 62 6a 65 63 74 2e  ethods2] object.
14ff0 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
15000 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50  LITE_CONFIG_GETP
15010 43 41 43 48 45 32 5d 5d 20 3c 64 74 3e 53 51 4c  CACHE2]] <dt>SQL
15020 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43  ITE_CONFIG_GETPC
15030 41 43 48 45 32 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ACHE2</dt>.** <d
15040 64 3e 20 5e 28 54 68 65 20 53 51 4c 49 54 45 5f  d> ^(The SQLITE_
15050 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45  CONFIG_GETPCACHE
15060 32 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61  2 option takes a
15070 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74   single argument
15080 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 61 20 70   which.** is a p
15090 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 5b 73 71  ointer to an [sq
150a0 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74  lite3_pcache_met
150b0 68 6f 64 73 32 5d 20 6f 62 6a 65 63 74 2e 20 20  hods2] object.  
150c0 53 51 4c 69 74 65 20 63 6f 70 69 65 73 20 6f 66  SQLite copies of
150d0 0a 2a 2a 20 74 68 65 20 63 75 72 72 65 6e 74 20  .** the current 
150e0 70 61 67 65 20 63 61 63 68 65 20 69 6d 70 6c 65  page cache imple
150f0 6d 65 6e 74 61 74 69 6f 6e 20 69 6e 74 6f 20 74  mentation into t
15100 68 61 74 20 6f 62 6a 65 63 74 2e 29 5e 20 3c 2f  hat object.)^ </
15110 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
15120 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 5d 5d 20  TE_CONFIG_LOG]] 
15130 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
15140 47 5f 4c 4f 47 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  G_LOG</dt>.** <d
15150 64 3e 20 54 68 65 20 53 51 4c 49 54 45 5f 43 4f  d> The SQLITE_CO
15160 4e 46 49 47 5f 4c 4f 47 20 6f 70 74 69 6f 6e 20  NFIG_LOG option 
15170 69 73 20 75 73 65 64 20 74 6f 20 63 6f 6e 66 69  is used to confi
15180 67 75 72 65 20 74 68 65 20 53 51 4c 69 74 65 0a  gure the SQLite.
15190 2a 2a 20 67 6c 6f 62 61 6c 20 5b 65 72 72 6f 72  ** global [error
151a0 20 6c 6f 67 5d 2e 0a 2a 2a 20 28 5e 54 68 65 20   log]..** (^The 
151b0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f  SQLITE_CONFIG_LO
151c0 47 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 74  G option takes t
151d0 77 6f 20 61 72 67 75 6d 65 6e 74 73 3a 20 61 20  wo arguments: a 
151e0 70 6f 69 6e 74 65 72 20 74 6f 20 61 0a 2a 2a 20  pointer to a.** 
151f0 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 61 20  function with a 
15200 63 61 6c 6c 20 73 69 67 6e 61 74 75 72 65 20 6f  call signature o
15210 66 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c  f void(*)(void*,
15220 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29  int,const char*)
15230 2c 20 0a 2a 2a 20 61 6e 64 20 61 20 70 6f 69 6e  , .** and a poin
15240 74 65 72 20 74 6f 20 76 6f 69 64 2e 20 5e 49 66  ter to void. ^If
15250 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 70 6f   the function po
15260 69 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e 55 4c  inter is not NUL
15270 4c 2c 20 69 74 20 69 73 0a 2a 2a 20 69 6e 76 6f  L, it is.** invo
15280 6b 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  ked by [sqlite3_
15290 6c 6f 67 28 29 5d 20 74 6f 20 70 72 6f 63 65 73  log()] to proces
152a0 73 20 65 61 63 68 20 6c 6f 67 67 69 6e 67 20 65  s each logging e
152b0 76 65 6e 74 2e 20 20 5e 49 66 20 74 68 65 0a 2a  vent.  ^If the.*
152c0 2a 20 66 75 6e 63 74 69 6f 6e 20 70 6f 69 6e 74  * function point
152d0 65 72 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 20  er is NULL, the 
152e0 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20  [sqlite3_log()] 
152f0 69 6e 74 65 72 66 61 63 65 20 62 65 63 6f 6d 65  interface become
15300 73 20 61 20 6e 6f 2d 6f 70 2e 0a 2a 2a 20 5e 54  s a no-op..** ^T
15310 68 65 20 76 6f 69 64 20 70 6f 69 6e 74 65 72 20  he void pointer 
15320 74 68 61 74 20 69 73 20 74 68 65 20 73 65 63 6f  that is the seco
15330 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 53  nd argument to S
15340 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47  QLITE_CONFIG_LOG
15350 20 69 73 0a 2a 2a 20 70 61 73 73 65 64 20 74 68   is.** passed th
15360 72 6f 75 67 68 20 61 73 20 74 68 65 20 66 69 72  rough as the fir
15370 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  st parameter to 
15380 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
15390 64 65 66 69 6e 65 64 20 6c 6f 67 67 65 72 0a 2a  defined logger.*
153a0 2a 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 6e 65  * function whene
153b0 76 65 72 20 74 68 61 74 20 66 75 6e 63 74 69 6f  ver that functio
153c0 6e 20 69 73 20 69 6e 76 6f 6b 65 64 2e 20 20 5e  n is invoked.  ^
153d0 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  The second param
153e0 65 74 65 72 20 74 6f 0a 2a 2a 20 74 68 65 20 6c  eter to.** the l
153f0 6f 67 67 65 72 20 66 75 6e 63 74 69 6f 6e 20 69  ogger function i
15400 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20  s a copy of the 
15410 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
15420 74 6f 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e  to the correspon
15430 64 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ding.** [sqlite3
15440 5f 6c 6f 67 28 29 5d 20 63 61 6c 6c 20 61 6e 64  _log()] call and
15450 20 69 73 20 69 6e 74 65 6e 64 65 64 20 74 6f 20   is intended to 
15460 62 65 20 61 20 5b 72 65 73 75 6c 74 20 63 6f 64  be a [result cod
15470 65 5d 20 6f 72 20 61 6e 0a 2a 2a 20 5b 65 78 74  e] or an.** [ext
15480 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
15490 65 5d 2e 20 20 5e 54 68 65 20 74 68 69 72 64 20  e].  ^The third 
154a0 70 61 72 61 6d 65 74 65 72 20 70 61 73 73 65 64  parameter passed
154b0 20 74 6f 20 74 68 65 20 6c 6f 67 67 65 72 20 69   to the logger i
154c0 73 0a 2a 2a 20 6c 6f 67 20 6d 65 73 73 61 67 65  s.** log message
154d0 20 61 66 74 65 72 20 66 6f 72 6d 61 74 74 69 6e   after formattin
154e0 67 20 76 69 61 20 5b 73 71 6c 69 74 65 33 5f 73  g via [sqlite3_s
154f0 6e 70 72 69 6e 74 66 28 29 5d 2e 0a 2a 2a 20 54  nprintf()]..** T
15500 68 65 20 53 51 4c 69 74 65 20 6c 6f 67 67 69 6e  he SQLite loggin
15510 67 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 6e  g interface is n
15520 6f 74 20 72 65 65 6e 74 72 61 6e 74 3b 20 74 68  ot reentrant; th
15530 65 20 6c 6f 67 67 65 72 20 66 75 6e 63 74 69 6f  e logger functio
15540 6e 0a 2a 2a 20 73 75 70 70 6c 69 65 64 20 62 79  n.** supplied by
15550 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
15560 20 6d 75 73 74 20 6e 6f 74 20 69 6e 76 6f 6b 65   must not invoke
15570 20 61 6e 79 20 53 51 4c 69 74 65 20 69 6e 74 65   any SQLite inte
15580 72 66 61 63 65 2e 0a 2a 2a 20 49 6e 20 61 20 6d  rface..** In a m
15590 75 6c 74 69 2d 74 68 72 65 61 64 65 64 20 61 70  ulti-threaded ap
155a0 70 6c 69 63 61 74 69 6f 6e 2c 20 74 68 65 20 61  plication, the a
155b0 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
155c0 65 64 20 6c 6f 67 67 65 72 0a 2a 2a 20 66 75 6e  ed logger.** fun
155d0 63 74 69 6f 6e 20 6d 75 73 74 20 62 65 20 74 68  ction must be th
155e0 72 65 61 64 73 61 66 65 2e 20 3c 2f 64 64 3e 0a  readsafe. </dd>.
155f0 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
15600 4f 4e 46 49 47 5f 55 52 49 5d 5d 20 3c 64 74 3e  ONFIG_URI]] <dt>
15610 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52  SQLITE_CONFIG_UR
15620 49 0a 2a 2a 20 3c 64 64 3e 5e 28 54 68 65 20 53  I.** <dd>^(The S
15630 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49  QLITE_CONFIG_URI
15640 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20   option takes a 
15650 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20  single argument 
15660 6f 66 20 74 79 70 65 20 69 6e 74 2e 0a 2a 2a 20  of type int..** 
15670 49 66 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65  If non-zero, the
15680 6e 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 20 69  n URI handling i
15690 73 20 67 6c 6f 62 61 6c 6c 79 20 65 6e 61 62 6c  s globally enabl
156a0 65 64 2e 20 49 66 20 74 68 65 20 70 61 72 61 6d  ed. If the param
156b0 65 74 65 72 20 69 73 20 7a 65 72 6f 2c 0a 2a 2a  eter is zero,.**
156c0 20 74 68 65 6e 20 55 52 49 20 68 61 6e 64 6c 69   then URI handli
156d0 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20 64  ng is globally d
156e0 69 73 61 62 6c 65 64 2e 29 5e 20 5e 49 66 20 55  isabled.)^ ^If U
156f0 52 49 20 68 61 6e 64 6c 69 6e 67 20 69 73 20 67  RI handling is g
15700 6c 6f 62 61 6c 6c 79 0a 2a 2a 20 65 6e 61 62 6c  lobally.** enabl
15710 65 64 2c 20 61 6c 6c 20 66 69 6c 65 6e 61 6d 65  ed, all filename
15720 73 20 70 61 73 73 65 64 20 74 6f 20 5b 73 71 6c  s passed to [sql
15730 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73  ite3_open()], [s
15740 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
15750 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f  ],.** [sqlite3_o
15760 70 65 6e 31 36 28 29 5d 20 6f 72 0a 2a 2a 20 73  pen16()] or.** s
15770 70 65 63 69 66 69 65 64 20 61 73 20 70 61 72 74  pecified as part
15780 20 6f 66 20 5b 41 54 54 41 43 48 5d 20 63 6f 6d   of [ATTACH] com
15790 6d 61 6e 64 73 20 61 72 65 20 69 6e 74 65 72 70  mands are interp
157a0 72 65 74 65 64 20 61 73 20 55 52 49 73 2c 20 72  reted as URIs, r
157b0 65 67 61 72 64 6c 65 73 73 0a 2a 2a 20 6f 66 20  egardless.** of 
157c0 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74  whether or not t
157d0 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  he [SQLITE_OPEN_
157e0 55 52 49 5d 20 66 6c 61 67 20 69 73 20 73 65 74  URI] flag is set
157f0 20 77 68 65 6e 20 74 68 65 20 64 61 74 61 62 61   when the databa
15800 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e  se.** connection
15810 20 69 73 20 6f 70 65 6e 65 64 2e 20 5e 49 66 20   is opened. ^If 
15820 69 74 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20 64  it is globally d
15830 69 73 61 62 6c 65 64 2c 20 66 69 6c 65 6e 61 6d  isabled, filenam
15840 65 73 20 61 72 65 0a 2a 2a 20 6f 6e 6c 79 20 69  es are.** only i
15850 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 55 52  nterpreted as UR
15860 49 73 20 69 66 20 74 68 65 20 53 51 4c 49 54 45  Is if the SQLITE
15870 5f 4f 50 45 4e 5f 55 52 49 20 66 6c 61 67 20 69  _OPEN_URI flag i
15880 73 20 73 65 74 20 77 68 65 6e 20 74 68 65 0a 2a  s set when the.*
15890 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  * database conne
158a0 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e 65 64 2e  ction is opened.
158b0 20 5e 28 42 79 20 64 65 66 61 75 6c 74 2c 20 55   ^(By default, U
158c0 52 49 20 68 61 6e 64 6c 69 6e 67 20 69 73 20 67  RI handling is g
158d0 6c 6f 62 61 6c 6c 79 0a 2a 2a 20 64 69 73 61 62  lobally.** disab
158e0 6c 65 64 2e 20 54 68 65 20 64 65 66 61 75 6c 74  led. The default
158f0 20 76 61 6c 75 65 20 6d 61 79 20 62 65 20 63 68   value may be ch
15900 61 6e 67 65 64 20 62 79 20 63 6f 6d 70 69 6c 69  anged by compili
15910 6e 67 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b  ng with the.** [
15920 53 51 4c 49 54 45 5f 55 53 45 5f 55 52 49 5d 20  SQLITE_USE_URI] 
15930 73 79 6d 62 6f 6c 20 64 65 66 69 6e 65 64 2e 29  symbol defined.)
15940 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  ^.**.** [[SQLITE
15950 5f 43 4f 4e 46 49 47 5f 43 4f 56 45 52 49 4e 47  _CONFIG_COVERING
15960 5f 49 4e 44 45 58 5f 53 43 41 4e 5d 5d 20 3c 64  _INDEX_SCAN]] <d
15970 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
15980 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53  COVERING_INDEX_S
15990 43 41 4e 0a 2a 2a 20 3c 64 64 3e 5e 54 68 65 20  CAN.** <dd>^The 
159a0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f  SQLITE_CONFIG_CO
159b0 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41  VERING_INDEX_SCA
159c0 4e 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61  N option takes a
159d0 20 73 69 6e 67 6c 65 20 69 6e 74 65 67 65 72 0a   single integer.
159e0 2a 2a 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63  ** argument whic
159f0 68 20 69 73 20 69 6e 74 65 72 70 72 65 74 65 64  h is interpreted
15a00 20 61 73 20 61 20 62 6f 6f 6c 65 61 6e 20 69 6e   as a boolean in
15a10 20 6f 72 64 65 72 20 74 6f 20 65 6e 61 62 6c 65   order to enable
15a20 20 6f 72 20 64 69 73 61 62 6c 65 0a 2a 2a 20 74   or disable.** t
15a30 68 65 20 75 73 65 20 6f 66 20 63 6f 76 65 72 69  he use of coveri
15a40 6e 67 20 69 6e 64 69 63 65 73 20 66 6f 72 20 66  ng indices for f
15a50 75 6c 6c 20 74 61 62 6c 65 20 73 63 61 6e 73 20  ull table scans 
15a60 69 6e 20 74 68 65 20 71 75 65 72 79 20 6f 70 74  in the query opt
15a70 69 6d 69 7a 65 72 2e 0a 2a 2a 20 5e 54 68 65 20  imizer..** ^The 
15a80 64 65 66 61 75 6c 74 20 73 65 74 74 69 6e 67 20  default setting 
15a90 69 73 20 64 65 74 65 72 6d 69 6e 65 64 0a 2a 2a  is determined.**
15aa0 20 62 79 20 74 68 65 20 5b 53 51 4c 49 54 45 5f   by the [SQLITE_
15ab0 41 4c 4c 4f 57 5f 43 4f 56 45 52 49 4e 47 5f 49  ALLOW_COVERING_I
15ac0 4e 44 45 58 5f 53 43 41 4e 5d 20 63 6f 6d 70 69  NDEX_SCAN] compi
15ad0 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2c 20  le-time option, 
15ae0 6f 72 20 69 73 20 22 6f 6e 22 0a 2a 2a 20 69 66  or is "on".** if
15af0 20 74 68 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69   that compile-ti
15b00 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20 6f 6d 69  me option is omi
15b10 74 74 65 64 2e 0a 2a 2a 20 54 68 65 20 61 62 69  tted..** The abi
15b20 6c 69 74 79 20 74 6f 20 64 69 73 61 62 6c 65 20  lity to disable 
15b30 74 68 65 20 75 73 65 20 6f 66 20 63 6f 76 65 72  the use of cover
15b40 69 6e 67 20 69 6e 64 69 63 65 73 20 66 6f 72 20  ing indices for 
15b50 66 75 6c 6c 20 74 61 62 6c 65 20 73 63 61 6e 73  full table scans
15b60 0a 2a 2a 20 69 73 20 62 65 63 61 75 73 65 20 73  .** is because s
15b70 6f 6d 65 20 69 6e 63 6f 72 72 65 63 74 6c 79 20  ome incorrectly 
15b80 63 6f 64 65 64 20 6c 65 67 61 63 79 20 61 70 70  coded legacy app
15b90 6c 69 63 61 74 69 6f 6e 73 20 6d 69 67 68 74 20  lications might 
15ba0 6d 61 6c 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 77  malfunction.** w
15bb0 68 65 6e 20 74 68 65 20 6f 70 74 69 6d 69 7a 61  hen the optimiza
15bc0 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 2e  tion is enabled.
15bd0 20 20 50 72 6f 76 69 64 69 6e 67 20 74 68 65 20    Providing the 
15be0 61 62 69 6c 69 74 79 20 74 6f 0a 2a 2a 20 64 69  ability to.** di
15bf0 73 61 62 6c 65 20 74 68 65 20 6f 70 74 69 6d 69  sable the optimi
15c00 7a 61 74 69 6f 6e 20 61 6c 6c 6f 77 73 20 74 68  zation allows th
15c10 65 20 6f 6c 64 65 72 2c 20 62 75 67 67 79 20 61  e older, buggy a
15c20 70 70 6c 69 63 61 74 69 6f 6e 20 63 6f 64 65 20  pplication code 
15c30 74 6f 20 77 6f 72 6b 0a 2a 2a 20 77 69 74 68 6f  to work.** witho
15c40 75 74 20 63 68 61 6e 67 65 20 65 76 65 6e 20 77  ut change even w
15c50 69 74 68 20 6e 65 77 65 72 20 76 65 72 73 69 6f  ith newer versio
15c60 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a  ns of SQLite..**
15c70 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
15c80 46 49 47 5f 50 43 41 43 48 45 5d 5d 20 5b 5b 53  FIG_PCACHE]] [[S
15c90 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
15ca0 50 43 41 43 48 45 5d 5d 0a 2a 2a 20 3c 64 74 3e  PCACHE]].** <dt>
15cb0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43  SQLITE_CONFIG_PC
15cc0 41 43 48 45 20 61 6e 64 20 53 51 4c 49 54 45 5f  ACHE and SQLITE_
15cd0 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45  CONFIG_GETPCACHE
15ce0 0a 2a 2a 20 3c 64 64 3e 20 54 68 65 73 65 20 6f  .** <dd> These o
15cf0 70 74 69 6f 6e 73 20 61 72 65 20 6f 62 73 6f 6c  ptions are obsol
15d00 65 74 65 20 61 6e 64 20 73 68 6f 75 6c 64 20 6e  ete and should n
15d10 6f 74 20 62 65 20 75 73 65 64 20 62 79 20 6e 65  ot be used by ne
15d20 77 20 63 6f 64 65 2e 0a 2a 2a 20 54 68 65 79 20  w code..** They 
15d30 61 72 65 20 72 65 74 61 69 6e 65 64 20 66 6f 72  are retained for
15d40 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61   backwards compa
15d50 74 69 62 69 6c 69 74 79 20 62 75 74 20 61 72 65  tibility but are
15d60 20 6e 6f 77 20 6e 6f 2d 6f 70 73 2e 0a 2a 2a 20   now no-ops..** 
15d70 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
15d80 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 51 4c 4c  LITE_CONFIG_SQLL
15d90 4f 47 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  OG]].** <dt>SQLI
15da0 54 45 5f 43 4f 4e 46 49 47 5f 53 51 4c 4c 4f 47  TE_CONFIG_SQLLOG
15db0 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 6f 70 74  .** <dd>This opt
15dc0 69 6f 6e 20 69 73 20 6f 6e 6c 79 20 61 76 61 69  ion is only avai
15dd0 6c 61 62 6c 65 20 69 66 20 73 71 6c 69 74 65 20  lable if sqlite 
15de0 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  is compiled with
15df0 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f   the.** [SQLITE_
15e00 45 4e 41 42 4c 45 5f 53 51 4c 4c 4f 47 5d 20 70  ENABLE_SQLLOG] p
15e10 72 65 2d 70 72 6f 63 65 73 73 6f 72 20 6d 61 63  re-processor mac
15e20 72 6f 20 64 65 66 69 6e 65 64 2e 20 54 68 65 20  ro defined. The 
15e30 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 73  first argument s
15e40 68 6f 75 6c 64 0a 2a 2a 20 62 65 20 61 20 70 6f  hould.** be a po
15e50 69 6e 74 65 72 20 74 6f 20 61 20 66 75 6e 63 74  inter to a funct
15e60 69 6f 6e 20 6f 66 20 74 79 70 65 20 76 6f 69 64  ion of type void
15e70 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65  (*)(void*,sqlite
15e80 33 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20  3*,const char*, 
15e90 69 6e 74 29 2e 0a 2a 2a 20 54 68 65 20 73 65 63  int)..** The sec
15ea0 6f 6e 64 20 73 68 6f 75 6c 64 20 62 65 20 6f 66  ond should be of
15eb0 20 74 79 70 65 20 28 76 6f 69 64 2a 29 2e 20 54   type (void*). T
15ec0 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69  he callback is i
15ed0 6e 76 6f 6b 65 64 20 62 79 20 74 68 65 20 6c 69  nvoked by the li
15ee0 62 72 61 72 79 0a 2a 2a 20 69 6e 20 74 68 72 65  brary.** in thre
15ef0 65 20 73 65 70 61 72 61 74 65 20 63 69 72 63 75  e separate circu
15f00 6d 73 74 61 6e 63 65 73 2c 20 69 64 65 6e 74 69  mstances, identi
15f10 66 69 65 64 20 62 79 20 74 68 65 20 76 61 6c 75  fied by the valu
15f20 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65 0a  e passed as the.
15f30 2a 2a 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  ** fourth parame
15f40 74 65 72 2e 20 49 66 20 74 68 65 20 66 6f 75 72  ter. If the four
15f50 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  th parameter is 
15f60 30 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74 61  0, then the data
15f70 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a  base connection.
15f80 2a 2a 20 70 61 73 73 65 64 20 61 73 20 74 68 65  ** passed as the
15f90 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
15fa0 20 68 61 73 20 6a 75 73 74 20 62 65 65 6e 20 6f   has just been o
15fb0 70 65 6e 65 64 2e 20 54 68 65 20 74 68 69 72 64  pened. The third
15fc0 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 70 6f 69   argument.** poi
15fd0 6e 74 73 20 74 6f 20 61 20 62 75 66 66 65 72 20  nts to a buffer 
15fe0 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 6e  containing the n
15ff0 61 6d 65 20 6f 66 20 74 68 65 20 6d 61 69 6e 20  ame of the main 
16000 64 61 74 61 62 61 73 65 20 66 69 6c 65 2e 20 49  database file. I
16010 66 20 74 68 65 0a 2a 2a 20 66 6f 75 72 74 68 20  f the.** fourth 
16020 70 61 72 61 6d 65 74 65 72 20 69 73 20 31 2c 20  parameter is 1, 
16030 74 68 65 6e 20 74 68 65 20 53 51 4c 20 73 74 61  then the SQL sta
16040 74 65 6d 65 6e 74 20 74 68 61 74 20 74 68 65 20  tement that the 
16050 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 0a  third parameter.
16060 2a 2a 20 70 6f 69 6e 74 73 20 74 6f 20 68 61 73  ** points to has
16070 20 6a 75 73 74 20 62 65 65 6e 20 65 78 65 63 75   just been execu
16080 74 65 64 2e 20 4f 72 2c 20 69 66 20 74 68 65 20  ted. Or, if the 
16090 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
160a0 20 69 73 20 32 2c 20 74 68 65 6e 0a 2a 2a 20 74   is 2, then.** t
160b0 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 65  he connection be
160c0 69 6e 67 20 70 61 73 73 65 64 20 61 73 20 74 68  ing passed as th
160d0 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
160e0 65 72 20 69 73 20 62 65 69 6e 67 20 63 6c 6f 73  er is being clos
160f0 65 64 2e 20 54 68 65 0a 2a 2a 20 74 68 69 72 64  ed. The.** third
16100 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 70 61   parameter is pa
16110 73 73 65 64 20 4e 55 4c 4c 20 49 6e 20 74 68 69  ssed NULL In thi
16120 73 20 63 61 73 65 2e 20 20 41 6e 20 65 78 61 6d  s case.  An exam
16130 70 6c 65 20 6f 66 20 75 73 69 6e 67 20 74 68 69  ple of using thi
16140 73 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69  s.** configurati
16150 6f 6e 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65  on option can be
16160 20 73 65 65 6e 20 69 6e 20 74 68 65 20 22 74 65   seen in the "te
16170 73 74 5f 73 71 6c 6c 6f 67 2e 63 22 20 73 6f 75  st_sqllog.c" sou
16180 72 63 65 20 66 69 6c 65 20 69 6e 0a 2a 2a 20 74  rce file in.** t
16190 68 65 20 63 61 6e 6f 6e 69 63 61 6c 20 53 51 4c  he canonical SQL
161a0 69 74 65 20 73 6f 75 72 63 65 20 74 72 65 65 2e  ite source tree.
161b0 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
161c0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41 50  LITE_CONFIG_MMAP
161d0 5f 53 49 5a 45 5d 5d 0a 2a 2a 20 3c 64 74 3e 53  _SIZE]].** <dt>S
161e0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41  QLITE_CONFIG_MMA
161f0 50 5f 53 49 5a 45 0a 2a 2a 20 3c 64 64 3e 5e 53  P_SIZE.** <dd>^S
16200 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41  QLITE_CONFIG_MMA
16210 50 5f 53 49 5a 45 20 74 61 6b 65 73 20 74 77 6f  P_SIZE takes two
16220 20 36 34 2d 62 69 74 20 69 6e 74 65 67 65 72 20   64-bit integer 
16230 28 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 20  (sqlite3_int64) 
16240 76 61 6c 75 65 73 0a 2a 2a 20 74 68 61 74 20 61  values.** that a
16250 72 65 20 74 68 65 20 64 65 66 61 75 6c 74 20 6d  re the default m
16260 6d 61 70 20 73 69 7a 65 20 6c 69 6d 69 74 20 28  map size limit (
16270 74 68 65 20 64 65 66 61 75 6c 74 20 73 65 74 74  the default sett
16280 69 6e 67 20 66 6f 72 0a 2a 2a 20 5b 50 52 41 47  ing for.** [PRAG
16290 4d 41 20 6d 6d 61 70 5f 73 69 7a 65 5d 29 20 61  MA mmap_size]) a
162a0 6e 64 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 61  nd the maximum a
162b0 6c 6c 6f 77 65 64 20 6d 6d 61 70 20 73 69 7a 65  llowed mmap size
162c0 20 6c 69 6d 69 74 2e 0a 2a 2a 20 5e 54 68 65 20   limit..** ^The 
162d0 64 65 66 61 75 6c 74 20 73 65 74 74 69 6e 67 20  default setting 
162e0 63 61 6e 20 62 65 20 6f 76 65 72 72 69 64 64 65  can be overridde
162f0 6e 20 62 79 20 65 61 63 68 20 64 61 74 61 62 61  n by each databa
16300 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 75 73  se connection us
16310 69 6e 67 0a 2a 2a 20 65 69 74 68 65 72 20 74 68  ing.** either th
16320 65 20 5b 50 52 41 47 4d 41 20 6d 6d 61 70 5f 73  e [PRAGMA mmap_s
16330 69 7a 65 5d 20 63 6f 6d 6d 61 6e 64 2c 20 6f 72  ize] command, or
16340 20 62 79 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a   by using the.**
16350 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4d   [SQLITE_FCNTL_M
16360 4d 41 50 5f 53 49 5a 45 5d 20 66 69 6c 65 20 63  MAP_SIZE] file c
16370 6f 6e 74 72 6f 6c 2e 20 20 5e 28 54 68 65 20 6d  ontrol.  ^(The m
16380 61 78 69 6d 75 6d 20 61 6c 6c 6f 77 65 64 20 6d  aximum allowed m
16390 6d 61 70 20 73 69 7a 65 0a 2a 2a 20 77 69 6c 6c  map size.** will
163a0 20 62 65 20 73 69 6c 65 6e 74 6c 79 20 74 72 75   be silently tru
163b0 6e 63 61 74 65 64 20 69 66 20 6e 65 63 65 73 73  ncated if necess
163c0 61 72 79 20 73 6f 20 74 68 61 74 20 69 74 20 64  ary so that it d
163d0 6f 65 73 20 6e 6f 74 20 65 78 63 65 65 64 20 74  oes not exceed t
163e0 68 65 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74 69  he.** compile-ti
163f0 6d 65 20 6d 61 78 69 6d 75 6d 20 6d 6d 61 70 20  me maximum mmap 
16400 73 69 7a 65 20 73 65 74 20 62 79 20 74 68 65 0a  size set by the.
16410 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 41 58 5f 4d  ** [SQLITE_MAX_M
16420 4d 41 50 5f 53 49 5a 45 5d 20 63 6f 6d 70 69 6c  MAP_SIZE] compil
16430 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2e 29 5e  e-time option.)^
16440 0a 2a 2a 20 5e 49 66 20 65 69 74 68 65 72 20 61  .** ^If either a
16450 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 69 73 20  rgument to this 
16460 6f 70 74 69 6f 6e 20 69 73 20 6e 65 67 61 74 69  option is negati
16470 76 65 2c 20 74 68 65 6e 20 74 68 61 74 20 61 72  ve, then that ar
16480 67 75 6d 65 6e 74 20 69 73 0a 2a 2a 20 63 68 61  gument is.** cha
16490 6e 67 65 64 20 74 6f 20 69 74 73 20 63 6f 6d 70  nged to its comp
164a0 69 6c 65 2d 74 69 6d 65 20 64 65 66 61 75 6c 74  ile-time default
164b0 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  ..**.** [[SQLITE
164c0 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f 48 45  _CONFIG_WIN32_HE
164d0 41 50 53 49 5a 45 5d 5d 0a 2a 2a 20 3c 64 74 3e  APSIZE]].** <dt>
164e0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 57 49  SQLITE_CONFIG_WI
164f0 4e 33 32 5f 48 45 41 50 53 49 5a 45 0a 2a 2a 20  N32_HEAPSIZE.** 
16500 3c 64 64 3e 5e 54 68 65 20 53 51 4c 49 54 45 5f  <dd>^The SQLITE_
16510 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f 48 45 41  CONFIG_WIN32_HEA
16520 50 53 49 5a 45 20 6f 70 74 69 6f 6e 20 69 73 20  PSIZE option is 
16530 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 69  only available i
16540 66 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20 63  f SQLite is.** c
16550 6f 6d 70 69 6c 65 64 20 66 6f 72 20 57 69 6e 64  ompiled for Wind
16560 6f 77 73 20 77 69 74 68 20 74 68 65 20 5b 53 51  ows with the [SQ
16570 4c 49 54 45 5f 57 49 4e 33 32 5f 4d 41 4c 4c 4f  LITE_WIN32_MALLO
16580 43 5d 20 70 72 65 2d 70 72 6f 63 65 73 73 6f 72  C] pre-processor
16590 20 6d 61 63 72 6f 0a 2a 2a 20 64 65 66 69 6e 65   macro.** define
165a0 64 2e 20 5e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  d. ^SQLITE_CONFI
165b0 47 5f 57 49 4e 33 32 5f 48 45 41 50 53 49 5a 45  G_WIN32_HEAPSIZE
165c0 20 74 61 6b 65 73 20 61 20 33 32 2d 62 69 74 20   takes a 32-bit 
165d0 75 6e 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72  unsigned integer
165e0 20 76 61 6c 75 65 0a 2a 2a 20 74 68 61 74 20 73   value.** that s
165f0 70 65 63 69 66 69 65 73 20 74 68 65 20 6d 61 78  pecifies the max
16600 69 6d 75 6d 20 73 69 7a 65 20 6f 66 20 74 68 65  imum size of the
16610 20 63 72 65 61 74 65 64 20 68 65 61 70 2e 0a 2a   created heap..*
16620 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
16630 4e 46 49 47 5f 50 43 41 43 48 45 5f 48 44 52 53  NFIG_PCACHE_HDRS
16640 5a 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  Z]].** <dt>SQLIT
16650 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 5f  E_CONFIG_PCACHE_
16660 48 44 52 53 5a 0a 2a 2a 20 3c 64 64 3e 5e 54 68  HDRSZ.** <dd>^Th
16670 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
16680 50 43 41 43 48 45 5f 48 44 52 53 5a 20 6f 70 74  PCACHE_HDRSZ opt
16690 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67  ion takes a sing
166a0 6c 65 20 70 61 72 61 6d 65 74 65 72 20 77 68 69  le parameter whi
166b0 63 68 0a 2a 2a 20 69 73 20 61 20 70 6f 69 6e 74  ch.** is a point
166c0 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72  er to an integer
166d0 20 61 6e 64 20 77 72 69 74 65 73 20 69 6e 74 6f   and writes into
166e0 20 74 68 61 74 20 69 6e 74 65 67 65 72 20 74 68   that integer th
166f0 65 20 6e 75 6d 62 65 72 20 6f 66 20 65 78 74 72  e number of extr
16700 61 0a 2a 2a 20 62 79 74 65 73 20 70 65 72 20 70  a.** bytes per p
16710 61 67 65 20 72 65 71 75 69 72 65 64 20 66 6f 72  age required for
16720 20 65 61 63 68 20 70 61 67 65 20 69 6e 20 5b 53   each page in [S
16730 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47  QLITE_CONFIG_PAG
16740 45 43 41 43 48 45 5d 2e 0a 2a 2a 20 54 68 65 20  ECACHE]..** The 
16750 61 6d 6f 75 6e 74 20 6f 66 20 65 78 74 72 61 20  amount of extra 
16760 73 70 61 63 65 20 72 65 71 75 69 72 65 64 20 63  space required c
16770 61 6e 20 63 68 61 6e 67 65 20 64 65 70 65 6e 64  an change depend
16780 69 6e 67 20 6f 6e 20 74 68 65 20 63 6f 6d 70 69  ing on the compi
16790 6c 65 72 2c 0a 2a 2a 20 74 61 72 67 65 74 20 70  ler,.** target p
167a0 6c 61 74 66 6f 72 6d 2c 20 61 6e 64 20 53 51 4c  latform, and SQL
167b0 69 74 65 20 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a  ite version..**.
167c0 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
167d0 49 47 5f 50 4d 41 53 5a 5d 5d 0a 2a 2a 20 3c 64  IG_PMASZ]].** <d
167e0 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
167f0 50 4d 41 53 5a 0a 2a 2a 20 3c 64 64 3e 5e 54 68  PMASZ.** <dd>^Th
16800 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
16810 50 4d 41 53 5a 20 6f 70 74 69 6f 6e 20 74 61 6b  PMASZ option tak
16820 65 73 20 61 20 73 69 6e 67 6c 65 20 70 61 72 61  es a single para
16830 6d 65 74 65 72 20 77 68 69 63 68 0a 2a 2a 20 69  meter which.** i
16840 73 20 61 6e 20 75 6e 73 69 67 6e 65 64 20 69 6e  s an unsigned in
16850 74 65 67 65 72 20 61 6e 64 20 73 65 74 73 20 74  teger and sets t
16860 68 65 20 22 4d 69 6e 69 6d 75 6d 20 50 4d 41 20  he "Minimum PMA 
16870 53 69 7a 65 22 20 66 6f 72 20 74 68 65 20 6d 75  Size" for the mu
16880 6c 74 69 74 68 72 65 61 64 65 64 0a 2a 2a 20 73  ltithreaded.** s
16890 6f 72 74 65 72 20 74 6f 20 74 68 61 74 20 69 6e  orter to that in
168a0 74 65 67 65 72 2e 20 20 54 68 65 20 64 65 66 61  teger.  The defa
168b0 75 6c 74 20 6d 69 6e 69 6d 75 6d 20 50 4d 41 20  ult minimum PMA 
168c0 53 69 7a 65 20 69 73 20 73 65 74 20 62 79 20 74  Size is set by t
168d0 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 53 4f  he.** [SQLITE_SO
168e0 52 54 45 52 5f 50 4d 41 53 5a 5d 20 63 6f 6d 70  RTER_PMASZ] comp
168f0 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2e  ile-time option.
16900 20 20 4e 65 77 20 74 68 72 65 61 64 73 20 61 72    New threads ar
16910 65 20 6c 61 75 6e 63 68 65 64 0a 2a 2a 20 74 6f  e launched.** to
16920 20 68 65 6c 70 20 77 69 74 68 20 73 6f 72 74 20   help with sort 
16930 6f 70 65 72 61 74 69 6f 6e 73 20 77 68 65 6e 20  operations when 
16940 6d 75 6c 74 69 74 68 72 65 61 64 65 64 20 73 6f  multithreaded so
16950 72 74 69 6e 67 0a 2a 2a 20 69 73 20 65 6e 61 62  rting.** is enab
16960 6c 65 64 20 28 75 73 69 6e 67 20 74 68 65 20 5b  led (using the [
16970 50 52 41 47 4d 41 20 74 68 72 65 61 64 73 5d 20  PRAGMA threads] 
16980 63 6f 6d 6d 61 6e 64 29 20 61 6e 64 20 74 68 65  command) and the
16990 20 61 6d 6f 75 6e 74 20 6f 66 20 63 6f 6e 74 65   amount of conte
169a0 6e 74 0a 2a 2a 20 74 6f 20 62 65 20 73 6f 72 74  nt.** to be sort
169b0 65 64 20 65 78 63 65 65 64 73 20 74 68 65 20 70  ed exceeds the p
169c0 61 67 65 20 73 69 7a 65 20 74 69 6d 65 73 20 74  age size times t
169d0 68 65 20 6d 69 6e 69 6d 75 6d 20 6f 66 20 74 68  he minimum of th
169e0 65 0a 2a 2a 20 5b 50 52 41 47 4d 41 20 63 61 63  e.** [PRAGMA cac
169f0 68 65 5f 73 69 7a 65 5d 20 73 65 74 74 69 6e 67  he_size] setting
16a00 20 61 6e 64 20 74 68 69 73 20 76 61 6c 75 65 2e   and this value.
16a10 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
16a20 43 4f 4e 46 49 47 5f 53 54 4d 54 4a 52 4e 4c 5f  CONFIG_STMTJRNL_
16a30 53 50 49 4c 4c 5d 5d 0a 2a 2a 20 3c 64 74 3e 53  SPILL]].** <dt>S
16a40 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 54 4d  QLITE_CONFIG_STM
16a50 54 4a 52 4e 4c 5f 53 50 49 4c 4c 0a 2a 2a 20 3c  TJRNL_SPILL.** <
16a60 64 64 3e 5e 54 68 65 20 53 51 4c 49 54 45 5f 43  dd>^The SQLITE_C
16a70 4f 4e 46 49 47 5f 53 54 4d 54 4a 52 4e 4c 5f 53  ONFIG_STMTJRNL_S
16a80 50 49 4c 4c 20 6f 70 74 69 6f 6e 20 74 61 6b 65  PILL option take
16a90 73 20 61 20 73 69 6e 67 6c 65 20 70 61 72 61 6d  s a single param
16aa0 65 74 65 72 20 77 68 69 63 68 0a 2a 2a 20 62 65  eter which.** be
16ab0 63 6f 6d 65 73 20 74 68 65 20 5b 73 74 61 74 65  comes the [state
16ac0 6d 65 6e 74 20 6a 6f 75 72 6e 61 6c 5d 20 73 70  ment journal] sp
16ad0 69 6c 6c 2d 74 6f 2d 64 69 73 6b 20 74 68 72 65  ill-to-disk thre
16ae0 73 68 6f 6c 64 2e 20 20 0a 2a 2a 20 5b 53 74 61  shold.  .** [Sta
16af0 74 65 6d 65 6e 74 20 6a 6f 75 72 6e 61 6c 73 5d  tement journals]
16b00 20 61 72 65 20 68 65 6c 64 20 69 6e 20 6d 65 6d   are held in mem
16b10 6f 72 79 20 75 6e 74 69 6c 20 74 68 65 69 72 20  ory until their 
16b20 73 69 7a 65 20 28 69 6e 20 62 79 74 65 73 29 0a  size (in bytes).
16b30 2a 2a 20 65 78 63 65 65 64 73 20 74 68 69 73 20  ** exceeds this 
16b40 74 68 72 65 73 68 6f 6c 64 2c 20 61 74 20 77 68  threshold, at wh
16b50 69 63 68 20 70 6f 69 6e 74 20 74 68 65 79 20 61  ich point they a
16b60 72 65 20 77 72 69 74 74 65 6e 20 74 6f 20 64 69  re written to di
16b70 73 6b 2e 0a 2a 2a 20 4f 72 20 69 66 20 74 68 65  sk..** Or if the
16b80 20 74 68 72 65 73 68 6f 6c 64 20 69 73 20 2d 31   threshold is -1
16b90 2c 20 73 74 61 74 65 6d 65 6e 74 20 6a 6f 75 72  , statement jour
16ba0 6e 61 6c 73 20 61 72 65 20 61 6c 77 61 79 73 20  nals are always 
16bb0 68 65 6c 64 0a 2a 2a 20 65 78 63 6c 75 73 69 76  held.** exclusiv
16bc0 65 6c 79 20 69 6e 20 6d 65 6d 6f 72 79 2e 0a 2a  ely in memory..*
16bd0 2a 20 53 69 6e 63 65 20 6d 61 6e 79 20 73 74 61  * Since many sta
16be0 74 65 6d 65 6e 74 20 6a 6f 75 72 6e 61 6c 73 20  tement journals 
16bf0 6e 65 76 65 72 20 62 65 63 6f 6d 65 20 6c 61 72  never become lar
16c00 67 65 2c 20 73 65 74 74 69 6e 67 20 74 68 65 20  ge, setting the 
16c10 73 70 69 6c 6c 0a 2a 2a 20 74 68 72 65 73 68 6f  spill.** thresho
16c20 6c 64 20 74 6f 20 61 20 76 61 6c 75 65 20 73 75  ld to a value su
16c30 63 68 20 61 73 20 36 34 4b 69 42 20 63 61 6e 20  ch as 64KiB can 
16c40 67 72 65 61 74 6c 79 20 72 65 64 75 63 65 20 74  greatly reduce t
16c50 68 65 20 61 6d 6f 75 6e 74 20 6f 66 0a 2a 2a 20  he amount of.** 
16c60 49 2f 4f 20 72 65 71 75 69 72 65 64 20 74 6f 20  I/O required to 
16c70 73 75 70 70 6f 72 74 20 73 74 61 74 65 6d 65 6e  support statemen
16c80 74 20 72 6f 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 54  t rollback..** T
16c90 68 65 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65  he default value
16ca0 20 66 6f 72 20 74 68 69 73 20 73 65 74 74 69 6e   for this settin
16cb0 67 20 69 73 20 63 6f 6e 74 72 6f 6c 6c 65 64 20  g is controlled 
16cc0 62 79 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54  by the.** [SQLIT
16cd0 45 5f 53 54 4d 54 4a 52 4e 4c 5f 53 50 49 4c 4c  E_STMTJRNL_SPILL
16ce0 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
16cf0 70 74 69 6f 6e 2e 0a 2a 2a 20 3c 2f 64 6c 3e 0a  ption..** </dl>.
16d00 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
16d10 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54  E_CONFIG_SINGLET
16d20 48 52 45 41 44 20 20 31 20 20 2f 2a 20 6e 69 6c  HREAD  1  /* nil
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 4d 55 4c 54 49 54  TE_CONFIG_MULTIT
16d50 48 52 45 41 44 20 20 20 32 20 20 2f 2a 20 6e 69  HREAD   2  /* ni
16d60 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  l */.#define SQL
16d70 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41  ITE_CONFIG_SERIA
16d80 4c 49 5a 45 44 20 20 20 20 33 20 20 2f 2a 20 6e  LIZED    3  /* n
16d90 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  il */.#define SQ
16da0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c  LITE_CONFIG_MALL
16db0 4f 43 20 20 20 20 20 20 20 20 34 20 20 2f 2a 20  OC        4  /* 
16dc0 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68  sqlite3_mem_meth
16dd0 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20  ods* */.#define 
16de0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
16df0 54 4d 41 4c 4c 4f 43 20 20 20 20 20 35 20 20 2f  TMALLOC     5  /
16e00 2a 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65  * sqlite3_mem_me
16e10 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e  thods* */.#defin
16e20 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
16e30 53 43 52 41 54 43 48 20 20 20 20 20 20 20 36 20  SCRATCH       6 
16e40 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 73   /* void*, int s
16e50 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23 64 65 66  z, int N */.#def
16e60 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
16e70 47 5f 50 41 47 45 43 41 43 48 45 20 20 20 20 20  G_PAGECACHE     
16e80 37 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74  7  /* void*, int
16e90 20 73 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23 64   sz, int N */.#d
16ea0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
16eb0 46 49 47 5f 48 45 41 50 20 20 20 20 20 20 20 20  FIG_HEAP        
16ec0 20 20 38 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69    8  /* void*, i
16ed0 6e 74 20 6e 42 79 74 65 2c 20 69 6e 74 20 6d 69  nt nByte, int mi
16ee0 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  n */.#define SQL
16ef0 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54  ITE_CONFIG_MEMST
16f00 41 54 55 53 20 20 20 20 20 39 20 20 2f 2a 20 62  ATUS     9  /* b
16f10 6f 6f 6c 65 61 6e 20 2a 2f 0a 23 64 65 66 69 6e  oolean */.#defin
16f20 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
16f30 4d 55 54 45 58 20 20 20 20 20 20 20 20 31 30 20  MUTEX        10 
16f40 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74 65   /* sqlite3_mute
16f50 78 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64  x_methods* */.#d
16f60 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
16f70 46 49 47 5f 47 45 54 4d 55 54 45 58 20 20 20 20  FIG_GETMUTEX    
16f80 20 31 31 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f   11  /* sqlite3_
16f90 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 2a 20 2a  mutex_methods* *
16fa0 2f 0a 2f 2a 20 70 72 65 76 69 6f 75 73 6c 79 20  /./* previously 
16fb0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 48  SQLITE_CONFIG_CH
16fc0 55 4e 4b 41 4c 4c 4f 43 20 31 32 20 77 68 69 63  UNKALLOC 12 whic
16fd0 68 20 69 73 20 6e 6f 77 20 75 6e 75 73 65 64 2e  h is now unused.
16fe0 20 2a 2f 20 0a 23 64 65 66 69 6e 65 20 53 51 4c   */ .#define SQL
16ff0 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41  ITE_CONFIG_LOOKA
17000 53 49 44 45 20 20 20 20 31 33 20 20 2f 2a 20 69  SIDE    13  /* i
17010 6e 74 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e  nt int */.#defin
17020 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
17030 50 43 41 43 48 45 20 20 20 20 20 20 20 31 34 20  PCACHE       14 
17040 20 2f 2a 20 6e 6f 2d 6f 70 20 2a 2f 0a 23 64 65   /* no-op */.#de
17050 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
17060 49 47 5f 47 45 54 50 43 41 43 48 45 20 20 20 20  IG_GETPCACHE    
17070 31 35 20 20 2f 2a 20 6e 6f 2d 6f 70 20 2a 2f 0a  15  /* no-op */.
17080 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
17090 4f 4e 46 49 47 5f 4c 4f 47 20 20 20 20 20 20 20  ONFIG_LOG       
170a0 20 20 20 31 36 20 20 2f 2a 20 78 46 75 6e 63 2c     16  /* xFunc,
170b0 20 76 6f 69 64 2a 20 2a 2f 0a 23 64 65 66 69 6e   void* */.#defin
170c0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
170d0 55 52 49 20 20 20 20 20 20 20 20 20 20 31 37 20  URI          17 
170e0 20 2f 2a 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69   /* int */.#defi
170f0 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
17100 5f 50 43 41 43 48 45 32 20 20 20 20 20 20 31 38  _PCACHE2      18
17110 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 70 63 61    /* sqlite3_pca
17120 63 68 65 5f 6d 65 74 68 6f 64 73 32 2a 20 2a 2f  che_methods2* */
17130 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
17140 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45  CONFIG_GETPCACHE
17150 32 20 20 20 31 39 20 20 2f 2a 20 73 71 6c 69 74  2   19  /* sqlit
17160 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64  e3_pcache_method
17170 73 32 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  s2* */.#define S
17180 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56  QLITE_CONFIG_COV
17190 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e  ERING_INDEX_SCAN
171a0 20 32 30 20 20 2f 2a 20 69 6e 74 20 2a 2f 0a 23   20  /* int */.#
171b0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
171c0 4e 46 49 47 5f 53 51 4c 4c 4f 47 20 20 20 20 20  NFIG_SQLLOG     
171d0 20 20 32 31 20 20 2f 2a 20 78 53 71 6c 6c 6f 67    21  /* xSqllog
171e0 2c 20 76 6f 69 64 2a 20 2a 2f 0a 23 64 65 66 69  , void* */.#defi
171f0 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
17200 5f 4d 4d 41 50 5f 53 49 5a 45 20 20 20 20 32 32  _MMAP_SIZE    22
17210 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 69 6e 74    /* sqlite3_int
17220 36 34 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  64, sqlite3_int6
17230 34 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  4 */.#define SQL
17240 49 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32  ITE_CONFIG_WIN32
17250 5f 48 45 41 50 53 49 5a 45 20 20 20 20 20 20 32  _HEAPSIZE      2
17260 33 20 20 2f 2a 20 69 6e 74 20 6e 42 79 74 65 20  3  /* int nByte 
17270 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
17280 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 5f  E_CONFIG_PCACHE_
17290 48 44 52 53 5a 20 20 20 20 20 20 20 20 32 34 20  HDRSZ        24 
172a0 20 2f 2a 20 69 6e 74 20 2a 70 73 7a 20 2a 2f 0a   /* int *psz */.
172b0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
172c0 4f 4e 46 49 47 5f 50 4d 41 53 5a 20 20 20 20 20  ONFIG_PMASZ     
172d0 20 20 20 20 20 20 20 20 20 20 32 35 20 20 2f 2a            25  /*
172e0 20 75 6e 73 69 67 6e 65 64 20 69 6e 74 20 73 7a   unsigned int sz
172f0 50 6d 61 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  Pma */.#define S
17300 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 54 4d  QLITE_CONFIG_STM
17310 54 4a 52 4e 4c 5f 53 50 49 4c 4c 20 20 20 20 20  TJRNL_SPILL     
17320 20 32 36 20 20 2f 2a 20 69 6e 74 20 6e 42 79 74   26  /* int nByt
17330 65 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  e */../*.** CAPI
17340 33 52 45 46 3a 20 44 61 74 61 62 61 73 65 20 43  3REF: Database C
17350 6f 6e 6e 65 63 74 69 6f 6e 20 43 6f 6e 66 69 67  onnection Config
17360 75 72 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 0a  uration Options.
17370 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73  **.** These cons
17380 74 61 6e 74 73 20 61 72 65 20 74 68 65 20 61 76  tants are the av
17390 61 69 6c 61 62 6c 65 20 69 6e 74 65 67 65 72 20  ailable integer 
173a0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
173b0 74 69 6f 6e 73 20 74 68 61 74 0a 2a 2a 20 63 61  tions that.** ca
173c0 6e 20 62 65 20 70 61 73 73 65 64 20 61 73 20 74  n be passed as t
173d0 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
173e0 6e 74 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74  nt to the [sqlit
173f0 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20  e3_db_config()] 
17400 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a  interface..**.**
17410 20 4e 65 77 20 63 6f 6e 66 69 67 75 72 61 74 69   New configurati
17420 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 61 79 20 62  on options may b
17430 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72  e added in futur
17440 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51  e releases of SQ
17450 4c 69 74 65 2e 0a 2a 2a 20 45 78 69 73 74 69 6e  Lite..** Existin
17460 67 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  g configuration 
17470 6f 70 74 69 6f 6e 73 20 6d 69 67 68 74 20 62 65  options might be
17480 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 2e 20 20   discontinued.  
17490 41 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20  Applications.** 
174a0 73 68 6f 75 6c 64 20 63 68 65 63 6b 20 74 68 65  should check the
174b0 20 72 65 74 75 72 6e 20 63 6f 64 65 20 66 72 6f   return code fro
174c0 6d 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f  m [sqlite3_db_co
174d0 6e 66 69 67 28 29 5d 20 74 6f 20 6d 61 6b 65 20  nfig()] to make 
174e0 73 75 72 65 20 74 68 61 74 0a 2a 2a 20 74 68 65  sure that.** the
174f0 20 63 61 6c 6c 20 77 6f 72 6b 65 64 2e 20 20 5e   call worked.  ^
17500 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f  The [sqlite3_db_
17510 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66  config()] interf
17520 61 63 65 20 77 69 6c 6c 20 72 65 74 75 72 6e 20  ace will return 
17530 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65  a.** non-zero [e
17540 72 72 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 20  rror code] if a 
17550 64 69 73 63 6f 6e 74 69 6e 75 65 64 20 6f 72 20  discontinued or 
17560 75 6e 73 75 70 70 6f 72 74 65 64 20 63 6f 6e 66  unsupported conf
17570 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
17580 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a  .** is invoked..
17590 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64  **.** <dl>.** <d
175a0 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49  t>SQLITE_DBCONFI
175b0 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64 74 3e  G_LOOKASIDE</dt>
175c0 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f  .** <dd> ^This o
175d0 70 74 69 6f 6e 20 74 61 6b 65 73 20 74 68 72 65  ption takes thre
175e0 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 67  e additional arg
175f0 75 6d 65 6e 74 73 20 74 68 61 74 20 64 65 74 65  uments that dete
17600 72 6d 69 6e 65 20 74 68 65 20 0a 2a 2a 20 5b 6c  rmine the .** [l
17610 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20  ookaside memory 
17620 61 6c 6c 6f 63 61 74 6f 72 5d 20 63 6f 6e 66 69  allocator] confi
17630 67 75 72 61 74 69 6f 6e 20 66 6f 72 20 74 68 65  guration for the
17640 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
17650 63 74 69 6f 6e 5d 2e 0a 2a 2a 20 5e 54 68 65 20  ction]..** ^The 
17660 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 28  first argument (
17670 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65  the third parame
17680 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  ter to [sqlite3_
17690 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69 73 20  db_config()] is 
176a0 61 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74 6f 20  a.** pointer to 
176b0 61 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20  a memory buffer 
176c0 74 6f 20 75 73 65 20 66 6f 72 20 6c 6f 6f 6b 61  to use for looka
176d0 73 69 64 65 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20  side memory..** 
176e0 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d  ^The first argum
176f0 65 6e 74 20 61 66 74 65 72 20 74 68 65 20 53 51  ent after the SQ
17700 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f  LITE_DBCONFIG_LO
17710 4f 4b 41 53 49 44 45 20 76 65 72 62 0a 2a 2a 20  OKASIDE verb.** 
17720 6d 61 79 20 62 65 20 4e 55 4c 4c 20 69 6e 20 77  may be NULL in w
17730 68 69 63 68 20 63 61 73 65 20 53 51 4c 69 74 65  hich case SQLite
17740 20 77 69 6c 6c 20 61 6c 6c 6f 63 61 74 65 20 74   will allocate t
17750 68 65 0a 2a 2a 20 6c 6f 6f 6b 61 73 69 64 65 20  he.** lookaside 
17760 62 75 66 66 65 72 20 69 74 73 65 6c 66 20 75 73  buffer itself us
17770 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  ing [sqlite3_mal
17780 6c 6f 63 28 29 5d 2e 20 5e 54 68 65 20 73 65 63  loc()]. ^The sec
17790 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20  ond argument is 
177a0 74 68 65 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 65  the.** size of e
177b0 61 63 68 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75  ach lookaside bu
177c0 66 66 65 72 20 73 6c 6f 74 2e 20 20 5e 54 68 65  ffer slot.  ^The
177d0 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20   third argument 
177e0 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  is the number of
177f0 0a 2a 2a 20 73 6c 6f 74 73 2e 20 20 54 68 65 20  .** slots.  The 
17800 73 69 7a 65 20 6f 66 20 74 68 65 20 62 75 66 66  size of the buff
17810 65 72 20 69 6e 20 74 68 65 20 66 69 72 73 74 20  er in the first 
17820 61 72 67 75 6d 65 6e 74 20 6d 75 73 74 20 62 65  argument must be
17830 20 67 72 65 61 74 65 72 20 74 68 61 6e 0a 2a 2a   greater than.**
17840 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 74 68 65   or equal to the
17850 20 70 72 6f 64 75 63 74 20 6f 66 20 74 68 65 20   product of the 
17860 73 65 63 6f 6e 64 20 61 6e 64 20 74 68 69 72 64  second and third
17870 20 61 72 67 75 6d 65 6e 74 73 2e 20 20 54 68 65   arguments.  The
17880 20 62 75 66 66 65 72 0a 2a 2a 20 6d 75 73 74 20   buffer.** must 
17890 62 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e  be aligned to an
178a0 20 38 2d 62 79 74 65 20 62 6f 75 6e 64 61 72 79   8-byte boundary
178b0 2e 20 20 5e 49 66 20 74 68 65 20 73 65 63 6f 6e  .  ^If the secon
178c0 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a  d argument to.**
178d0 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47   SQLITE_DBCONFIG
178e0 5f 4c 4f 4f 4b 41 53 49 44 45 20 69 73 20 6e 6f  _LOOKASIDE is no
178f0 74 20 61 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20  t a multiple of 
17900 38 2c 20 69 74 20 69 73 20 69 6e 74 65 72 6e 61  8, it is interna
17910 6c 6c 79 0a 2a 2a 20 72 6f 75 6e 64 65 64 20 64  lly.** rounded d
17920 6f 77 6e 20 74 6f 20 74 68 65 20 6e 65 78 74 20  own to the next 
17930 73 6d 61 6c 6c 65 72 20 6d 75 6c 74 69 70 6c 65  smaller multiple
17940 20 6f 66 20 38 2e 20 20 5e 28 54 68 65 20 6c 6f   of 8.  ^(The lo
17950 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 0a 2a  okaside memory.*
17960 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  * configuration 
17970 66 6f 72 20 61 20 64 61 74 61 62 61 73 65 20 63  for a database c
17980 6f 6e 6e 65 63 74 69 6f 6e 20 63 61 6e 20 6f 6e  onnection can on
17990 6c 79 20 62 65 20 63 68 61 6e 67 65 64 20 77 68  ly be changed wh
179a0 65 6e 20 74 68 61 74 0a 2a 2a 20 63 6f 6e 6e 65  en that.** conne
179b0 63 74 69 6f 6e 20 69 73 20 6e 6f 74 20 63 75 72  ction is not cur
179c0 72 65 6e 74 6c 79 20 75 73 69 6e 67 20 6c 6f 6f  rently using loo
179d0 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 2c 20 6f  kaside memory, o
179e0 72 20 69 6e 20 6f 74 68 65 72 20 77 6f 72 64 73  r in other words
179f0 0a 2a 2a 20 77 68 65 6e 20 74 68 65 20 22 63 75  .** when the "cu
17a00 72 72 65 6e 74 20 76 61 6c 75 65 22 20 72 65 74  rrent value" ret
17a10 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c  urned by.** [sql
17a20 69 74 65 33 5f 64 62 5f 73 74 61 74 75 73 5d 28  ite3_db_status](
17a30 44 2c 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  D,[SQLITE_CONFIG
17a40 5f 4c 4f 4f 4b 41 53 49 44 45 5d 2c 2e 2e 2e 29  _LOOKASIDE],...)
17a50 20 69 73 20 7a 65 72 6f 2e 0a 2a 2a 20 41 6e 79   is zero..** Any
17a60 20 61 74 74 65 6d 70 74 20 74 6f 20 63 68 61 6e   attempt to chan
17a70 67 65 20 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65  ge the lookaside
17a80 20 6d 65 6d 6f 72 79 20 63 6f 6e 66 69 67 75 72   memory configur
17a90 61 74 69 6f 6e 20 77 68 65 6e 20 6c 6f 6f 6b 61  ation when looka
17aa0 73 69 64 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 69  side.** memory i
17ab0 73 20 69 6e 20 75 73 65 20 6c 65 61 76 65 73 20  s in use leaves 
17ac0 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  the configuratio
17ad0 6e 20 75 6e 63 68 61 6e 67 65 64 20 61 6e 64 20  n unchanged and 
17ae0 72 65 74 75 72 6e 73 20 0a 2a 2a 20 5b 53 51 4c  returns .** [SQL
17af0 49 54 45 5f 42 55 53 59 5d 2e 29 5e 3c 2f 64 64  ITE_BUSY].)^</dd
17b00 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  >.**.** <dt>SQLI
17b10 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42  TE_DBCONFIG_ENAB
17b20 4c 45 5f 46 4b 45 59 3c 2f 64 74 3e 0a 2a 2a 20  LE_FKEY</dt>.** 
17b30 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f  <dd> ^This optio
17b40 6e 20 69 73 20 75 73 65 64 20 74 6f 20 65 6e 61  n is used to ena
17b50 62 6c 65 20 6f 72 20 64 69 73 61 62 6c 65 20 74  ble or disable t
17b60 68 65 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 6f  he enforcement o
17b70 66 0a 2a 2a 20 5b 66 6f 72 65 69 67 6e 20 6b 65  f.** [foreign ke
17b80 79 20 63 6f 6e 73 74 72 61 69 6e 74 73 5d 2e 20  y constraints]. 
17b90 20 54 68 65 72 65 20 73 68 6f 75 6c 64 20 62 65   There should be
17ba0 20 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20   two additional 
17bb0 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20 54 68  arguments..** Th
17bc0 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
17bd0 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77   is an integer w
17be0 68 69 63 68 20 69 73 20 30 20 74 6f 20 64 69 73  hich is 0 to dis
17bf0 61 62 6c 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d  able FK enforcem
17c00 65 6e 74 2c 0a 2a 2a 20 70 6f 73 69 74 69 76 65  ent,.** positive
17c10 20 74 6f 20 65 6e 61 62 6c 65 20 46 4b 20 65 6e   to enable FK en
17c20 66 6f 72 63 65 6d 65 6e 74 20 6f 72 20 6e 65 67  forcement or neg
17c30 61 74 69 76 65 20 74 6f 20 6c 65 61 76 65 20 46  ative to leave F
17c40 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 0a 2a 2a  K enforcement.**
17c50 20 75 6e 63 68 61 6e 67 65 64 2e 20 20 54 68 65   unchanged.  The
17c60 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
17c70 72 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  r is a pointer t
17c80 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 69 6e 74  o an integer int
17c90 6f 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 77 72  o which.** is wr
17ca0 69 74 74 65 6e 20 30 20 6f 72 20 31 20 74 6f 20  itten 0 or 1 to 
17cb0 69 6e 64 69 63 61 74 65 20 77 68 65 74 68 65 72  indicate whether
17cc0 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20   FK enforcement 
17cd0 69 73 20 6f 66 66 20 6f 72 20 6f 6e 0a 2a 2a 20  is off or on.** 
17ce0 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 69 73 20 63  following this c
17cf0 61 6c 6c 2e 20 20 54 68 65 20 73 65 63 6f 6e 64  all.  The second
17d00 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62   parameter may b
17d10 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  e a NULL pointer
17d20 2c 20 69 6e 0a 2a 2a 20 77 68 69 63 68 20 63 61  , in.** which ca
17d30 73 65 20 74 68 65 20 46 4b 20 65 6e 66 6f 72 63  se the FK enforc
17d40 65 6d 65 6e 74 20 73 65 74 74 69 6e 67 20 69 73  ement setting is
17d50 20 6e 6f 74 20 72 65 70 6f 72 74 65 64 20 62 61   not reported ba
17d60 63 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ck. </dd>.**.** 
17d70 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e  <dt>SQLITE_DBCON
17d80 46 49 47 5f 45 4e 41 42 4c 45 5f 54 52 49 47 47  FIG_ENABLE_TRIGG
17d90 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  ER</dt>.** <dd> 
17da0 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20  ^This option is 
17db0 75 73 65 64 20 74 6f 20 65 6e 61 62 6c 65 20 6f  used to enable o
17dc0 72 20 64 69 73 61 62 6c 65 20 5b 43 52 45 41 54  r disable [CREAT
17dd0 45 20 54 52 49 47 47 45 52 20 7c 20 74 72 69 67  E TRIGGER | trig
17de0 67 65 72 73 5d 2e 0a 2a 2a 20 54 68 65 72 65 20  gers]..** There 
17df0 73 68 6f 75 6c 64 20 62 65 20 74 77 6f 20 61 64  should be two ad
17e00 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e  ditional argumen
17e10 74 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74  ts..** The first
17e20 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 6e 20   argument is an 
17e30 69 6e 74 65 67 65 72 20 77 68 69 63 68 20 69 73  integer which is
17e40 20 30 20 74 6f 20 64 69 73 61 62 6c 65 20 74 72   0 to disable tr
17e50 69 67 67 65 72 73 2c 0a 2a 2a 20 70 6f 73 69 74  iggers,.** posit
17e60 69 76 65 20 74 6f 20 65 6e 61 62 6c 65 20 74 72  ive to enable tr
17e70 69 67 67 65 72 73 20 6f 72 20 6e 65 67 61 74 69  iggers or negati
17e80 76 65 20 74 6f 20 6c 65 61 76 65 20 74 68 65 20  ve to leave the 
17e90 73 65 74 74 69 6e 67 20 75 6e 63 68 61 6e 67 65  setting unchange
17ea0 64 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64  d..** The second
17eb0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20   parameter is a 
17ec0 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e  pointer to an in
17ed0 74 65 67 65 72 20 69 6e 74 6f 20 77 68 69 63 68  teger into which
17ee0 0a 2a 2a 20 69 73 20 77 72 69 74 74 65 6e 20 30  .** is written 0
17ef0 20 6f 72 20 31 20 74 6f 20 69 6e 64 69 63 61 74   or 1 to indicat
17f00 65 20 77 68 65 74 68 65 72 20 74 72 69 67 67 65  e whether trigge
17f10 72 73 20 61 72 65 20 64 69 73 61 62 6c 65 64 20  rs are disabled 
17f20 6f 72 20 65 6e 61 62 6c 65 64 0a 2a 2a 20 66 6f  or enabled.** fo
17f30 6c 6c 6f 77 69 6e 67 20 74 68 69 73 20 63 61 6c  llowing this cal
17f40 6c 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 70  l.  The second p
17f50 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20  arameter may be 
17f60 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20  a NULL pointer, 
17f70 69 6e 0a 2a 2a 20 77 68 69 63 68 20 63 61 73 65  in.** which case
17f80 20 74 68 65 20 74 72 69 67 67 65 72 20 73 65 74   the trigger set
17f90 74 69 6e 67 20 69 73 20 6e 6f 74 20 72 65 70 6f  ting is not repo
17fa0 72 74 65 64 20 62 61 63 6b 2e 20 3c 2f 64 64 3e  rted back. </dd>
17fb0 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  .**.** <dt>SQLIT
17fc0 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c  E_DBCONFIG_ENABL
17fd0 45 5f 46 54 53 33 5f 54 4f 4b 45 4e 49 5a 45 52  E_FTS3_TOKENIZER
17fe0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54  </dt>.** <dd> ^T
17ff0 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 75 73  his option is us
18000 65 64 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20  ed to enable or 
18010 64 69 73 61 62 6c 65 20 74 68 65 20 74 77 6f 2d  disable the two-
18020 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 76 65 72 73  argument.** vers
18030 69 6f 6e 20 6f 66 20 74 68 65 20 5b 66 74 73 33  ion of the [fts3
18040 5f 74 6f 6b 65 6e 69 7a 65 72 28 29 5d 20 66 75  _tokenizer()] fu
18050 6e 63 74 69 6f 6e 20 77 68 69 63 68 20 69 73 20  nction which is 
18060 70 61 72 74 20 6f 66 20 74 68 65 0a 2a 2a 20 5b  part of the.** [
18070 46 54 53 33 5d 20 66 75 6c 6c 2d 74 65 78 74 20  FTS3] full-text 
18080 73 65 61 72 63 68 20 65 6e 67 69 6e 65 20 65 78  search engine ex
18090 74 65 6e 73 69 6f 6e 2e 0a 2a 2a 20 54 68 65 72  tension..** Ther
180a0 65 20 73 68 6f 75 6c 64 20 62 65 20 74 77 6f 20  e should be two 
180b0 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d  additional argum
180c0 65 6e 74 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72  ents..** The fir
180d0 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61  st argument is a
180e0 6e 20 69 6e 74 65 67 65 72 20 77 68 69 63 68 20  n integer which 
180f0 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65 20  is 0 to disable 
18100 66 74 73 33 5f 74 6f 6b 65 6e 69 7a 65 72 28 29  fts3_tokenizer()
18110 20 6f 72 0a 2a 2a 20 70 6f 73 69 74 69 76 65 20   or.** positive 
18120 74 6f 20 65 6e 61 62 6c 65 20 66 74 73 33 5f 74  to enable fts3_t
18130 6f 6b 65 6e 69 7a 65 72 28 29 20 6f 72 20 6e 65  okenizer() or ne
18140 67 61 74 69 76 65 20 74 6f 20 6c 65 61 76 65 20  gative to leave 
18150 74 68 65 20 73 65 74 74 69 6e 67 0a 2a 2a 20 75  the setting.** u
18160 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 20 54 68 65  nchanged..** The
18170 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
18180 72 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  r is a pointer t
18190 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 69 6e 74  o an integer int
181a0 6f 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 77 72  o which.** is wr
181b0 69 74 74 65 6e 20 30 20 6f 72 20 31 20 74 6f 20  itten 0 or 1 to 
181c0 69 6e 64 69 63 61 74 65 20 77 68 65 74 68 65 72  indicate whether
181d0 20 66 74 73 33 5f 74 6f 6b 65 6e 69 7a 65 72 20   fts3_tokenizer 
181e0 69 73 20 64 69 73 61 62 6c 65 64 20 6f 72 20 65  is disabled or e
181f0 6e 61 62 6c 65 64 0a 2a 2a 20 66 6f 6c 6c 6f 77  nabled.** follow
18200 69 6e 67 20 74 68 69 73 20 63 61 6c 6c 2e 20 20  ing this call.  
18210 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  The second param
18220 65 74 65 72 20 6d 61 79 20 62 65 20 61 20 4e 55  eter may be a NU
18230 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69 6e 0a 2a  LL pointer, in.*
18240 2a 20 77 68 69 63 68 20 63 61 73 65 20 74 68 65  * which case the
18250 20 6e 65 77 20 73 65 74 74 69 6e 67 20 69 73 20   new setting is 
18260 6e 6f 74 20 72 65 70 6f 72 74 65 64 20 62 61 63  not reported bac
18270 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c  k. </dd>.**.** <
18280 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46  dt>SQLITE_DBCONF
18290 49 47 5f 45 4e 41 42 4c 45 5f 4c 4f 41 44 5f 45  IG_ENABLE_LOAD_E
182a0 58 54 45 4e 53 49 4f 4e 3c 2f 64 74 3e 0a 2a 2a  XTENSION</dt>.**
182b0 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69   <dd> ^This opti
182c0 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20 65 6e  on is used to en
182d0 61 62 6c 65 20 6f 72 20 64 69 73 61 62 6c 65 20  able or disable 
182e0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 61  the [sqlite3_loa
182f0 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d 0a 2a  d_extension()].*
18300 2a 20 69 6e 74 65 72 66 61 63 65 20 69 6e 64 65  * interface inde
18310 70 65 6e 64 65 6e 74 6c 79 20 6f 66 20 74 68 65  pendently of the
18320 20 5b 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e   [load_extension
18330 28 29 5d 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ()] SQL function
18340 2e 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65  ..** The [sqlite
18350 33 5f 65 6e 61 62 6c 65 5f 6c 6f 61 64 5f 65 78  3_enable_load_ex
18360 74 65 6e 73 69 6f 6e 28 29 5d 20 41 50 49 20 65  tension()] API e
18370 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62 6c  nables or disabl
18380 65 73 20 62 6f 74 68 20 74 68 65 0a 2a 2a 20 43  es both the.** C
18390 2d 41 50 49 20 5b 73 71 6c 69 74 65 33 5f 6c 6f  -API [sqlite3_lo
183a0 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d 20  ad_extension()] 
183b0 61 6e 64 20 74 68 65 20 53 51 4c 20 66 75 6e 63  and the SQL func
183c0 74 69 6f 6e 20 5b 6c 6f 61 64 5f 65 78 74 65 6e  tion [load_exten
183d0 73 69 6f 6e 28 29 5d 2e 0a 2a 2a 20 54 68 65 72  sion()]..** Ther
183e0 65 20 73 68 6f 75 6c 64 20 62 65 20 74 77 6f 20  e should be two 
183f0 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d  additional argum
18400 65 6e 74 73 2e 0a 2a 2a 20 57 68 65 6e 20 74 68  ents..** When th
18410 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
18420 20 74 6f 20 74 68 69 73 20 69 6e 74 65 72 66 61   to this interfa
18430 63 65 20 69 73 20 31 2c 20 74 68 65 6e 20 6f 6e  ce is 1, then on
18440 6c 79 20 74 68 65 20 43 2d 41 50 49 20 69 73 0a  ly the C-API is.
18450 2a 2a 20 65 6e 61 62 6c 65 64 20 61 6e 64 20 74  ** enabled and t
18460 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  he SQL function 
18470 72 65 6d 61 69 6e 73 20 64 69 73 61 62 6c 65 64  remains disabled
18480 2e 20 20 49 66 20 74 68 65 20 66 69 72 73 74 20  .  If the first 
18490 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 74  argument to.** t
184a0 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 69 73  his interface is
184b0 20 30 2c 20 74 68 65 6e 20 62 6f 74 68 20 74 68   0, then both th
184c0 65 20 43 2d 41 50 49 20 61 6e 64 20 74 68 65 20  e C-API and the 
184d0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 61 72 65  SQL function are
184e0 20 64 69 73 61 62 6c 65 64 2e 0a 2a 2a 20 49 66   disabled..** If
184f0 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
18500 65 6e 74 20 69 73 20 2d 31 2c 20 74 68 65 6e 20  ent is -1, then 
18510 6e 6f 20 63 68 61 6e 67 65 73 20 61 72 65 20 6d  no changes are m
18520 61 64 65 20 74 6f 20 73 74 61 74 65 20 6f 66 20  ade to state of 
18530 65 69 74 68 65 72 20 74 68 65 0a 2a 2a 20 43 2d  either the.** C-
18540 41 50 49 20 6f 72 20 74 68 65 20 53 51 4c 20 66  API or the SQL f
18550 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 54 68 65 20  unction..** The 
18560 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
18570 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
18580 20 61 6e 20 69 6e 74 65 67 65 72 20 69 6e 74 6f   an integer into
18590 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 77 72 69   which.** is wri
185a0 74 74 65 6e 20 30 20 6f 72 20 31 20 74 6f 20 69  tten 0 or 1 to i
185b0 6e 64 69 63 61 74 65 20 77 68 65 74 68 65 72 20  ndicate whether 
185c0 5b 73 71 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 78  [sqlite3_load_ex
185d0 74 65 6e 73 69 6f 6e 28 29 5d 20 69 6e 74 65 72  tension()] inter
185e0 66 61 63 65 0a 2a 2a 20 69 73 20 64 69 73 61 62  face.** is disab
185f0 6c 65 64 20 6f 72 20 65 6e 61 62 6c 65 64 20 66  led or enabled f
18600 6f 6c 6c 6f 77 69 6e 67 20 74 68 69 73 20 63 61  ollowing this ca
18610 6c 6c 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20  ll.  The second 
18620 70 61 72 61 6d 65 74 65 72 20 6d 61 79 0a 2a 2a  parameter may.**
18630 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   be a NULL point
18640 65 72 2c 20 69 6e 20 77 68 69 63 68 20 63 61 73  er, in which cas
18650 65 20 74 68 65 20 6e 65 77 20 73 65 74 74 69 6e  e the new settin
18660 67 20 69 73 20 6e 6f 74 20 72 65 70 6f 72 74 65  g is not reporte
18670 64 20 62 61 63 6b 2e 0a 2a 2a 20 3c 2f 64 64 3e  d back..** </dd>
18680 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  .**.** <dt>SQLIT
18690 45 5f 44 42 43 4f 4e 46 49 47 5f 4d 41 49 4e 44  E_DBCONFIG_MAIND
186a0 42 4e 41 4d 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  BNAME</dt>.** <d
186b0 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20  d> ^This option 
186c0 69 73 20 75 73 65 64 20 74 6f 20 63 68 61 6e 67  is used to chang
186d0 65 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  e the name of th
186e0 65 20 22 6d 61 69 6e 22 20 64 61 74 61 62 61 73  e "main" databas
186f0 65 0a 2a 2a 20 73 63 68 65 6d 61 2e 20 20 5e 54  e.** schema.  ^T
18700 68 65 20 73 6f 6c 65 20 61 72 67 75 6d 65 6e 74  he sole argument
18710 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
18720 20 61 20 63 6f 6e 73 74 61 6e 74 20 55 54 46 38   a constant UTF8
18730 20 73 74 72 69 6e 67 0a 2a 2a 20 77 68 69 63 68   string.** which
18740 20 77 69 6c 6c 20 62 65 63 6f 6d 65 20 74 68 65   will become the
18750 20 6e 65 77 20 73 63 68 65 6d 61 20 6e 61 6d 65   new schema name
18760 20 69 6e 20 70 6c 61 63 65 20 6f 66 20 22 6d 61   in place of "ma
18770 69 6e 22 2e 20 20 5e 53 51 4c 69 74 65 0a 2a 2a  in".  ^SQLite.**
18780 20 64 6f 65 73 20 6e 6f 74 20 6d 61 6b 65 20 61   does not make a
18790 20 63 6f 70 79 20 6f 66 20 74 68 65 20 6e 65 77   copy of the new
187a0 20 6d 61 69 6e 20 73 63 68 65 6d 61 20 6e 61 6d   main schema nam
187b0 65 20 73 74 72 69 6e 67 2c 20 73 6f 20 74 68 65  e string, so the
187c0 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20   application.** 
187d0 6d 75 73 74 20 65 6e 73 75 72 65 20 74 68 61 74  must ensure that
187e0 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 70 61   the argument pa
187f0 73 73 65 64 20 69 6e 74 6f 20 74 68 69 73 20 44  ssed into this D
18800 42 43 4f 4e 46 49 47 20 6f 70 74 69 6f 6e 20 69  BCONFIG option i
18810 73 20 75 6e 63 68 61 6e 67 65 64 0a 2a 2a 20 75  s unchanged.** u
18820 6e 74 69 6c 20 61 66 74 65 72 20 74 68 65 20 64  ntil after the d
18830 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
18840 6f 6e 20 63 6c 6f 73 65 73 2e 0a 2a 2a 20 3c 2f  on closes..** </
18850 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51  dd>.**.** <dt>SQ
18860 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4e 4f  LITE_DBCONFIG_NO
18870 5f 43 4b 50 54 5f 4f 4e 5f 43 4c 4f 53 45 3c 2f  _CKPT_ON_CLOSE</
18880 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 55 73 75 61  dt>.** <dd> Usua
18890 6c 6c 79 2c 20 77 68 65 6e 20 61 20 64 61 74 61  lly, when a data
188a0 62 61 73 65 20 69 6e 20 77 61 6c 20 6d 6f 64 65  base in wal mode
188b0 20 69 73 20 63 6c 6f 73 65 64 20 6f 72 20 64 65   is closed or de
188c0 74 61 63 68 65 64 20 66 72 6f 6d 20 61 20 0a 2a  tached from a .*
188d0 2a 20 64 61 74 61 62 61 73 65 20 68 61 6e 64 6c  * database handl
188e0 65 2c 20 53 51 4c 69 74 65 20 63 68 65 63 6b 73  e, SQLite checks
188f0 20 69 66 20 74 68 69 73 20 77 69 6c 6c 20 6d 65   if this will me
18900 61 6e 20 74 68 61 74 20 74 68 65 72 65 20 61 72  an that there ar
18910 65 20 6e 6f 77 20 6e 6f 20 0a 2a 2a 20 63 6f 6e  e now no .** con
18920 6e 65 63 74 69 6f 6e 73 20 61 74 20 61 6c 6c 20  nections at all 
18930 74 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 2e  to the database.
18940 20 49 66 20 73 6f 2c 20 69 74 20 70 65 72 66 6f   If so, it perfo
18950 72 6d 73 20 61 20 63 68 65 63 6b 70 6f 69 6e 74  rms a checkpoint
18960 20 0a 2a 2a 20 6f 70 65 72 61 74 69 6f 6e 20 62   .** operation b
18970 65 66 6f 72 65 20 63 6c 6f 73 69 6e 67 20 74 68  efore closing th
18980 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 54 68  e connection. Th
18990 69 73 20 6f 70 74 69 6f 6e 20 6d 61 79 20 62 65  is option may be
189a0 20 75 73 65 64 20 74 6f 0a 2a 2a 20 6f 76 65 72   used to.** over
189b0 72 69 64 65 20 74 68 69 73 20 62 65 68 61 76 69  ride this behavi
189c0 6f 75 72 2e 20 54 68 65 20 66 69 72 73 74 20 70  our. The first p
189d0 61 72 61 6d 65 74 65 72 20 70 61 73 73 65 64 20  arameter passed 
189e0 74 6f 20 74 68 69 73 20 6f 70 65 72 61 74 69 6f  to this operatio
189f0 6e 0a 2a 2a 20 69 73 20 61 6e 20 69 6e 74 65 67  n.** is an integ
18a00 65 72 20 2d 20 6e 6f 6e 2d 7a 65 72 6f 20 74 6f  er - non-zero to
18a10 20 64 69 73 61 62 6c 65 20 63 68 65 63 6b 70 6f   disable checkpo
18a20 69 6e 74 73 2d 6f 6e 2d 63 6c 6f 73 65 2c 20 6f  ints-on-close, o
18a30 72 20 7a 65 72 6f 20 28 74 68 65 0a 2a 2a 20 64  r zero (the.** d
18a40 65 66 61 75 6c 74 29 20 74 6f 20 65 6e 61 62 6c  efault) to enabl
18a50 65 20 74 68 65 6d 2e 20 54 68 65 20 73 65 63 6f  e them. The seco
18a60 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  nd parameter is 
18a70 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  a pointer to an 
18a80 69 6e 74 65 67 65 72 0a 2a 2a 20 69 6e 74 6f 20  integer.** into 
18a90 77 68 69 63 68 20 69 73 20 77 72 69 74 74 65 6e  which is written
18aa0 20 30 20 6f 72 20 31 20 74 6f 20 69 6e 64 69 63   0 or 1 to indic
18ab0 61 74 65 20 77 68 65 74 68 65 72 20 63 68 65 63  ate whether chec
18ac0 6b 70 6f 69 6e 74 73 2d 6f 6e 2d 63 6c 6f 73 65  kpoints-on-close
18ad0 0a 2a 2a 20 68 61 76 65 20 62 65 65 6e 20 64 69  .** have been di
18ae0 73 61 62 6c 65 64 20 2d 20 30 20 69 66 20 74 68  sabled - 0 if th
18af0 65 79 20 61 72 65 20 6e 6f 74 20 64 69 73 61 62  ey are not disab
18b00 6c 65 64 2c 20 31 20 69 66 20 74 68 65 79 20 61  led, 1 if they a
18b10 72 65 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a  re..** </dd>.**.
18b20 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66  ** </dl>.*/.#def
18b30 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e  ine SQLITE_DBCON
18b40 46 49 47 5f 4d 41 49 4e 44 42 4e 41 4d 45 20 20  FIG_MAINDBNAME  
18b50 20 20 20 20 20 20 20 20 20 20 31 30 30 30 20 2f            1000 /
18b60 2a 20 63 6f 6e 73 74 20 63 68 61 72 2a 20 2a 2f  * const char* */
18b70 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
18b80 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49  DBCONFIG_LOOKASI
18b90 44 45 20 20 20 20 20 20 20 20 20 20 20 20 20 31  DE             1
18ba0 30 30 31 20 2f 2a 20 76 6f 69 64 2a 20 69 6e 74  001 /* void* int
18bb0 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20   int */.#define 
18bc0 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
18bd0 45 4e 41 42 4c 45 5f 46 4b 45 59 20 20 20 20 20  ENABLE_FKEY     
18be0 20 20 20 20 20 20 31 30 30 32 20 2f 2a 20 69 6e        1002 /* in
18bf0 74 20 69 6e 74 2a 20 2a 2f 0a 23 64 65 66 69 6e  t int* */.#defin
18c00 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49  e SQLITE_DBCONFI
18c10 47 5f 45 4e 41 42 4c 45 5f 54 52 49 47 47 45 52  G_ENABLE_TRIGGER
18c20 20 20 20 20 20 20 20 20 31 30 30 33 20 2f 2a 20          1003 /* 
18c30 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23 64 65 66  int int* */.#def
18c40 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e  ine SQLITE_DBCON
18c50 46 49 47 5f 45 4e 41 42 4c 45 5f 46 54 53 33 5f  FIG_ENABLE_FTS3_
18c60 54 4f 4b 45 4e 49 5a 45 52 20 31 30 30 34 20 2f  TOKENIZER 1004 /
18c70 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23 64  * int int* */.#d
18c80 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43  efine SQLITE_DBC
18c90 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 4c 4f 41  ONFIG_ENABLE_LOA
18ca0 44 5f 45 58 54 45 4e 53 49 4f 4e 20 31 30 30 35  D_EXTENSION 1005
18cb0 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a   /* int int* */.
18cc0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
18cd0 42 43 4f 4e 46 49 47 5f 4e 4f 5f 43 4b 50 54 5f  BCONFIG_NO_CKPT_
18ce0 4f 4e 5f 43 4c 4f 53 45 20 20 20 20 20 20 31 30  ON_CLOSE      10
18cf0 30 36 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a  06 /* int int* *
18d00 2f 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  /.../*.** CAPI3R
18d10 45 46 3a 20 45 6e 61 62 6c 65 20 4f 72 20 44 69  EF: Enable Or Di
18d20 73 61 62 6c 65 20 45 78 74 65 6e 64 65 64 20 52  sable Extended R
18d30 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a 20 4d  esult Codes.** M
18d40 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a  ETHOD: sqlite3.*
18d50 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
18d60 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c  3_extended_resul
18d70 74 5f 63 6f 64 65 73 28 29 20 72 6f 75 74 69 6e  t_codes() routin
18d80 65 20 65 6e 61 62 6c 65 73 20 6f 72 20 64 69 73  e enables or dis
18d90 61 62 6c 65 73 20 74 68 65 0a 2a 2a 20 5b 65 78  ables the.** [ex
18da0 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f  tended result co
18db0 64 65 73 5d 20 66 65 61 74 75 72 65 20 6f 66 20  des] feature of 
18dc0 53 51 4c 69 74 65 2e 20 5e 54 68 65 20 65 78 74  SQLite. ^The ext
18dd0 65 6e 64 65 64 20 72 65 73 75 6c 74 0a 2a 2a 20  ended result.** 
18de0 63 6f 64 65 73 20 61 72 65 20 64 69 73 61 62 6c  codes are disabl
18df0 65 64 20 62 79 20 64 65 66 61 75 6c 74 20 66 6f  ed by default fo
18e00 72 20 68 69 73 74 6f 72 69 63 61 6c 20 63 6f 6d  r historical com
18e10 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2f 0a 53  patibility..*/.S
18e20 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
18e30 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 72  lite3_extended_r
18e40 65 73 75 6c 74 5f 63 6f 64 65 73 28 73 71 6c 69  esult_codes(sqli
18e50 74 65 33 2a 2c 20 69 6e 74 20 6f 6e 6f 66 66 29  te3*, int onoff)
18e60 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
18e70 46 3a 20 4c 61 73 74 20 49 6e 73 65 72 74 20 52  F: Last Insert R
18e80 6f 77 69 64 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  owid.** METHOD: 
18e90 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 45  sqlite3.**.** ^E
18ea0 61 63 68 20 65 6e 74 72 79 20 69 6e 20 6d 6f 73  ach entry in mos
18eb0 74 20 53 51 4c 69 74 65 20 74 61 62 6c 65 73 20  t SQLite tables 
18ec0 28 65 78 63 65 70 74 20 66 6f 72 20 5b 57 49 54  (except for [WIT
18ed0 48 4f 55 54 20 52 4f 57 49 44 5d 20 74 61 62 6c  HOUT ROWID] tabl
18ee0 65 73 29 0a 2a 2a 20 68 61 73 20 61 20 75 6e 69  es).** has a uni
18ef0 71 75 65 20 36 34 2d 62 69 74 20 73 69 67 6e 65  que 64-bit signe
18f00 64 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6b 65 79  d.** integer key
18f10 20 63 61 6c 6c 65 64 20 74 68 65 20 5b 52 4f 57   called the [ROW
18f20 49 44 20 7c 20 22 72 6f 77 69 64 22 5d 2e 20 5e  ID | "rowid"]. ^
18f30 54 68 65 20 72 6f 77 69 64 20 69 73 20 61 6c 77  The rowid is alw
18f40 61 79 73 20 61 76 61 69 6c 61 62 6c 65 0a 2a 2a  ays available.**
18f50 20 61 73 20 61 6e 20 75 6e 64 65 63 6c 61 72 65   as an undeclare
18f60 64 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 64 20 52  d column named R
18f70 4f 57 49 44 2c 20 4f 49 44 2c 20 6f 72 20 5f 52  OWID, OID, or _R
18f80 4f 57 49 44 5f 20 61 73 20 6c 6f 6e 67 20 61 73  OWID_ as long as
18f90 20 74 68 6f 73 65 0a 2a 2a 20 6e 61 6d 65 73 20   those.** names 
18fa0 61 72 65 20 6e 6f 74 20 61 6c 73 6f 20 75 73 65  are not also use
18fb0 64 20 62 79 20 65 78 70 6c 69 63 69 74 6c 79 20  d by explicitly 
18fc0 64 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 73  declared columns
18fd0 2e 20 5e 49 66 0a 2a 2a 20 74 68 65 20 74 61 62  . ^If.** the tab
18fe0 6c 65 20 68 61 73 20 61 20 63 6f 6c 75 6d 6e 20  le has a column 
18ff0 6f 66 20 74 79 70 65 20 5b 49 4e 54 45 47 45 52  of type [INTEGER
19000 20 50 52 49 4d 41 52 59 20 4b 45 59 5d 20 74 68   PRIMARY KEY] th
19010 65 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e 0a 2a  en that column.*
19020 2a 20 69 73 20 61 6e 6f 74 68 65 72 20 61 6c 69  * is another ali
19030 61 73 20 66 6f 72 20 74 68 65 20 72 6f 77 69 64  as for the rowid
19040 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
19050 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74  ite3_last_insert
19060 5f 72 6f 77 69 64 28 44 29 20 69 6e 74 65 72 66  _rowid(D) interf
19070 61 63 65 20 75 73 75 61 6c 6c 79 20 72 65 74 75  ace usually retu
19080 72 6e 73 20 74 68 65 20 5b 72 6f 77 69 64 5d 20  rns the [rowid] 
19090 6f 66 0a 2a 2a 20 74 68 65 20 6d 6f 73 74 20 72  of.** the most r
190a0 65 63 65 6e 74 20 73 75 63 63 65 73 73 66 75 6c  ecent successful
190b0 20 5b 49 4e 53 45 52 54 5d 20 69 6e 74 6f 20 61   [INSERT] into a
190c0 20 72 6f 77 69 64 20 74 61 62 6c 65 20 6f 72 20   rowid table or 
190d0 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 5d 0a  [virtual table].
190e0 2a 2a 20 6f 6e 20 64 61 74 61 62 61 73 65 20 63  ** on database c
190f0 6f 6e 6e 65 63 74 69 6f 6e 20 44 2e 20 5e 49 6e  onnection D. ^In
19100 73 65 72 74 73 20 69 6e 74 6f 20 5b 57 49 54 48  serts into [WITH
19110 4f 55 54 20 52 4f 57 49 44 5d 20 74 61 62 6c 65  OUT ROWID] table
19120 73 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 72 65 63  s are not.** rec
19130 6f 72 64 65 64 2e 20 5e 49 66 20 6e 6f 20 73 75  orded. ^If no su
19140 63 63 65 73 73 66 75 6c 20 5b 49 4e 53 45 52 54  ccessful [INSERT
19150 5d 73 20 69 6e 74 6f 20 72 6f 77 69 64 20 74 61  ]s into rowid ta
19160 62 6c 65 73 20 68 61 76 65 20 65 76 65 72 20 6f  bles have ever o
19170 63 63 75 72 72 65 64 20 0a 2a 2a 20 6f 6e 20 74  ccurred .** on t
19180 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
19190 65 63 74 69 6f 6e 20 44 2c 20 74 68 65 6e 20 73  ection D, then s
191a0 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65  qlite3_last_inse
191b0 72 74 5f 72 6f 77 69 64 28 44 29 20 72 65 74 75  rt_rowid(D) retu
191c0 72 6e 73 20 0a 2a 2a 20 7a 65 72 6f 2e 0a 2a 2a  rns .** zero..**
191d0 0a 2a 2a 20 41 73 20 77 65 6c 6c 20 61 73 20 62  .** As well as b
191e0 65 69 6e 67 20 73 65 74 20 61 75 74 6f 6d 61 74  eing set automat
191f0 69 63 61 6c 6c 79 20 61 73 20 72 6f 77 73 20 61  ically as rows a
19200 72 65 20 69 6e 73 65 72 74 65 64 20 69 6e 74 6f  re inserted into
19210 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 74 61 62   database.** tab
19220 6c 65 73 2c 20 74 68 65 20 76 61 6c 75 65 20 72  les, the value r
19230 65 74 75 72 6e 65 64 20 62 79 20 74 68 69 73 20  eturned by this 
19240 66 75 6e 63 74 69 6f 6e 20 6d 61 79 20 62 65 20  function may be 
19250 73 65 74 20 65 78 70 6c 69 63 69 74 6c 79 20 62  set explicitly b
19260 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 65  y.** [sqlite3_se
19270 74 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f  t_last_insert_ro
19280 77 69 64 28 29 5d 0a 2a 2a 0a 2a 2a 20 53 6f 6d  wid()].**.** Som
19290 65 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20  e virtual table 
192a0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
192b0 6d 61 79 20 49 4e 53 45 52 54 20 72 6f 77 73 20  may INSERT rows 
192c0 69 6e 74 6f 20 72 6f 77 69 64 20 74 61 62 6c 65  into rowid table
192d0 73 20 61 73 0a 2a 2a 20 70 61 72 74 20 6f 66 20  s as.** part of 
192e0 63 6f 6d 6d 69 74 74 69 6e 67 20 61 20 74 72 61  committing a tra
192f0 6e 73 61 63 74 69 6f 6e 20 28 65 2e 67 2e 20 74  nsaction (e.g. t
19300 6f 20 66 6c 75 73 68 20 64 61 74 61 20 61 63 63  o flush data acc
19310 75 6d 75 6c 61 74 65 64 20 69 6e 20 6d 65 6d 6f  umulated in memo
19320 72 79 0a 2a 2a 20 74 6f 20 64 69 73 6b 29 2e 20  ry.** to disk). 
19330 49 6e 20 74 68 69 73 20 63 61 73 65 20 73 75 62  In this case sub
19340 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f  sequent calls to
19350 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72   this function r
19360 65 74 75 72 6e 20 74 68 65 20 72 6f 77 69 64 0a  eturn the rowid.
19370 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  ** associated wi
19380 74 68 20 74 68 65 73 65 20 69 6e 74 65 72 6e 61  th these interna
19390 6c 20 49 4e 53 45 52 54 20 6f 70 65 72 61 74 69  l INSERT operati
193a0 6f 6e 73 2c 20 77 68 69 63 68 20 6c 65 61 64 73  ons, which leads
193b0 20 74 6f 20 0a 2a 2a 20 75 6e 69 6e 74 75 69 74   to .** unintuit
193c0 69 76 65 20 72 65 73 75 6c 74 73 2e 20 56 69 72  ive results. Vir
193d0 74 75 61 6c 20 74 61 62 6c 65 20 69 6d 70 6c 65  tual table imple
193e0 6d 65 6e 74 61 74 69 6f 6e 73 20 74 68 61 74 20  mentations that 
193f0 64 6f 20 77 72 69 74 65 20 74 6f 20 72 6f 77 69  do write to rowi
19400 64 0a 2a 2a 20 74 61 62 6c 65 73 20 69 6e 20 74  d.** tables in t
19410 68 69 73 20 77 61 79 20 63 61 6e 20 61 76 6f 69  his way can avoi
19420 64 20 74 68 69 73 20 70 72 6f 62 6c 65 6d 20 62  d this problem b
19430 79 20 72 65 73 74 6f 72 69 6e 67 20 74 68 65 20  y restoring the 
19440 6f 72 69 67 69 6e 61 6c 20 0a 2a 2a 20 72 6f 77  original .** row
19450 69 64 20 76 61 6c 75 65 20 75 73 69 6e 67 20 5b  id value using [
19460 73 71 6c 69 74 65 33 5f 73 65 74 5f 6c 61 73 74  sqlite3_set_last
19470 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 5d  _insert_rowid()]
19480 20 62 65 66 6f 72 65 20 72 65 74 75 72 6e 69 6e   before returnin
19490 67 20 0a 2a 2a 20 63 6f 6e 74 72 6f 6c 20 74 6f  g .** control to
194a0 20 74 68 65 20 75 73 65 72 2e 0a 2a 2a 0a 2a 2a   the user..**.**
194b0 20 5e 28 49 66 20 61 6e 20 5b 49 4e 53 45 52 54   ^(If an [INSERT
194c0 5d 20 6f 63 63 75 72 73 20 77 69 74 68 69 6e 20  ] occurs within 
194d0 61 20 74 72 69 67 67 65 72 20 74 68 65 6e 20 74  a trigger then t
194e0 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69 6c 6c  his routine will
194f0 20 0a 2a 2a 20 72 65 74 75 72 6e 20 74 68 65 20   .** return the 
19500 5b 72 6f 77 69 64 5d 20 6f 66 20 74 68 65 20 69  [rowid] of the i
19510 6e 73 65 72 74 65 64 20 72 6f 77 20 61 73 20 6c  nserted row as l
19520 6f 6e 67 20 61 73 20 74 68 65 20 74 72 69 67 67  ong as the trigg
19530 65 72 20 69 73 20 0a 2a 2a 20 72 75 6e 6e 69 6e  er is .** runnin
19540 67 2e 20 4f 6e 63 65 20 74 68 65 20 74 72 69 67  g. Once the trig
19550 67 65 72 20 70 72 6f 67 72 61 6d 20 65 6e 64 73  ger program ends
19560 2c 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75  , the value retu
19570 72 6e 65 64 20 0a 2a 2a 20 62 79 20 74 68 69 73  rned .** by this
19580 20 72 6f 75 74 69 6e 65 20 72 65 76 65 72 74 73   routine reverts
19590 20 74 6f 20 77 68 61 74 20 69 74 20 77 61 73 20   to what it was 
195a0 62 65 66 6f 72 65 20 74 68 65 20 74 72 69 67 67  before the trigg
195b0 65 72 20 77 61 73 20 66 69 72 65 64 2e 29 5e 0a  er was fired.)^.
195c0 2a 2a 0a 2a 2a 20 5e 41 6e 20 5b 49 4e 53 45 52  **.** ^An [INSER
195d0 54 5d 20 74 68 61 74 20 66 61 69 6c 73 20 64 75  T] that fails du
195e0 65 20 74 6f 20 61 20 63 6f 6e 73 74 72 61 69 6e  e to a constrain
195f0 74 20 76 69 6f 6c 61 74 69 6f 6e 20 69 73 20 6e  t violation is n
19600 6f 74 20 61 0a 2a 2a 20 73 75 63 63 65 73 73 66  ot a.** successf
19610 75 6c 20 5b 49 4e 53 45 52 54 5d 20 61 6e 64 20  ul [INSERT] and 
19620 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67 65 20  does not change 
19630 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e  the value return
19640 65 64 20 62 79 20 74 68 69 73 0a 2a 2a 20 72 6f  ed by this.** ro
19650 75 74 69 6e 65 2e 20 20 5e 54 68 75 73 20 49 4e  utine.  ^Thus IN
19660 53 45 52 54 20 4f 52 20 46 41 49 4c 2c 20 49 4e  SERT OR FAIL, IN
19670 53 45 52 54 20 4f 52 20 49 47 4e 4f 52 45 2c 20  SERT OR IGNORE, 
19680 49 4e 53 45 52 54 20 4f 52 20 52 4f 4c 4c 42 41  INSERT OR ROLLBA
19690 43 4b 2c 0a 2a 2a 20 61 6e 64 20 49 4e 53 45 52  CK,.** and INSER
196a0 54 20 4f 52 20 41 42 4f 52 54 20 6d 61 6b 65 20  T OR ABORT make 
196b0 6e 6f 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68  no changes to th
196c0 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f  e return value o
196d0 66 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e  f this.** routin
196e0 65 20 77 68 65 6e 20 74 68 65 69 72 20 69 6e 73  e when their ins
196f0 65 72 74 69 6f 6e 20 66 61 69 6c 73 2e 20 20 5e  ertion fails.  ^
19700 28 57 68 65 6e 20 49 4e 53 45 52 54 20 4f 52 20  (When INSERT OR 
19710 52 45 50 4c 41 43 45 0a 2a 2a 20 65 6e 63 6f 75  REPLACE.** encou
19720 6e 74 65 72 73 20 61 20 63 6f 6e 73 74 72 61 69  nters a constrai
19730 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 2c 20 69 74  nt violation, it
19740 20 64 6f 65 73 20 6e 6f 74 20 66 61 69 6c 2e 20   does not fail. 
19750 20 54 68 65 0a 2a 2a 20 49 4e 53 45 52 54 20 63   The.** INSERT c
19760 6f 6e 74 69 6e 75 65 73 20 74 6f 20 63 6f 6d 70  ontinues to comp
19770 6c 65 74 69 6f 6e 20 61 66 74 65 72 20 64 65 6c  letion after del
19780 65 74 69 6e 67 20 72 6f 77 73 20 74 68 61 74 20  eting rows that 
19790 63 61 75 73 65 64 0a 2a 2a 20 74 68 65 20 63 6f  caused.** the co
197a0 6e 73 74 72 61 69 6e 74 20 70 72 6f 62 6c 65 6d  nstraint problem
197b0 20 73 6f 20 49 4e 53 45 52 54 20 4f 52 20 52 45   so INSERT OR RE
197c0 50 4c 41 43 45 20 77 69 6c 6c 20 61 6c 77 61 79  PLACE will alway
197d0 73 20 63 68 61 6e 67 65 0a 2a 2a 20 74 68 65 20  s change.** the 
197e0 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20  return value of 
197f0 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 2e 29  this interface.)
19800 5e 0a 2a 2a 0a 2a 2a 20 5e 46 6f 72 20 74 68 65  ^.**.** ^For the
19810 20 70 75 72 70 6f 73 65 73 20 6f 66 20 74 68 69   purposes of thi
19820 73 20 72 6f 75 74 69 6e 65 2c 20 61 6e 20 5b 49  s routine, an [I
19830 4e 53 45 52 54 5d 20 69 73 20 63 6f 6e 73 69 64  NSERT] is consid
19840 65 72 65 64 20 74 6f 0a 2a 2a 20 62 65 20 73 75  ered to.** be su
19850 63 63 65 73 73 66 75 6c 20 65 76 65 6e 20 69 66  ccessful even if
19860 20 69 74 20 69 73 20 73 75 62 73 65 71 75 65 6e   it is subsequen
19870 74 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b 2e  tly rolled back.
19880 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63  .**.** This func
19890 74 69 6f 6e 20 69 73 20 61 63 63 65 73 73 69 62  tion is accessib
198a0 6c 65 20 74 6f 20 53 51 4c 20 73 74 61 74 65 6d  le to SQL statem
198b0 65 6e 74 73 20 76 69 61 20 74 68 65 0a 2a 2a 20  ents via the.** 
198c0 5b 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77  [last_insert_row
198d0 69 64 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f  id() SQL functio
198e0 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73  n]..**.** If a s
198f0 65 70 61 72 61 74 65 20 74 68 72 65 61 64 20 70  eparate thread p
19900 65 72 66 6f 72 6d 73 20 61 20 6e 65 77 20 5b 49  erforms a new [I
19910 4e 53 45 52 54 5d 20 6f 6e 20 74 68 65 20 73 61  NSERT] on the sa
19920 6d 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63  me.** database c
19930 6f 6e 6e 65 63 74 69 6f 6e 20 77 68 69 6c 65 20  onnection while 
19940 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73  the [sqlite3_las
19950 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29  t_insert_rowid()
19960 5d 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73  ].** function is
19970 20 72 75 6e 6e 69 6e 67 20 61 6e 64 20 74 68 75   running and thu
19980 73 20 63 68 61 6e 67 65 73 20 74 68 65 20 6c 61  s changes the la
19990 73 74 20 69 6e 73 65 72 74 20 5b 72 6f 77 69 64  st insert [rowid
199a0 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 76  ],.** then the v
199b0 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79  alue returned by
199c0 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69   [sqlite3_last_i
199d0 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 5d 20 69  nsert_rowid()] i
199e0 73 0a 2a 2a 20 75 6e 70 72 65 64 69 63 74 61 62  s.** unpredictab
199f0 6c 65 20 61 6e 64 20 6d 69 67 68 74 20 6e 6f 74  le and might not
19a00 20 65 71 75 61 6c 20 65 69 74 68 65 72 20 74 68   equal either th
19a10 65 20 6f 6c 64 20 6f 72 20 74 68 65 20 6e 65 77  e old or the new
19a20 0a 2a 2a 20 6c 61 73 74 20 69 6e 73 65 72 74 20  .** last insert 
19a30 5b 72 6f 77 69 64 5d 2e 0a 2a 2f 0a 53 51 4c 49  [rowid]..*/.SQLI
19a40 54 45 5f 41 50 49 20 73 71 6c 69 74 65 33 5f 69  TE_API sqlite3_i
19a50 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6c 61 73  nt64 sqlite3_las
19a60 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 73  t_insert_rowid(s
19a70 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  qlite3*);../*.**
19a80 20 43 41 50 49 33 52 45 46 3a 20 53 65 74 20 74   CAPI3REF: Set t
19a90 68 65 20 4c 61 73 74 20 49 6e 73 65 72 74 20 52  he Last Insert R
19aa0 6f 77 69 64 20 76 61 6c 75 65 2e 0a 2a 2a 20 4d  owid value..** M
19ab0 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a  ETHOD: sqlite3.*
19ac0 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
19ad0 5f 73 65 74 5f 6c 61 73 74 5f 69 6e 73 65 72 74  _set_last_insert
19ae0 5f 72 6f 77 69 64 28 44 2c 20 52 29 20 6d 65 74  _rowid(D, R) met
19af0 68 6f 64 20 61 6c 6c 6f 77 73 20 74 68 65 20 61  hod allows the a
19b00 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f 0a 2a 2a  pplication to.**
19b10 20 73 65 74 20 74 68 65 20 76 61 6c 75 65 20 72   set the value r
19b20 65 74 75 72 6e 65 64 20 62 79 20 63 61 6c 6c 69  eturned by calli
19b30 6e 67 20 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f  ng sqlite3_last_
19b40 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 44 29 20  insert_rowid(D) 
19b50 74 6f 20 52 20 0a 2a 2a 20 77 69 74 68 6f 75 74  to R .** without
19b60 20 69 6e 73 65 72 74 69 6e 67 20 61 20 72 6f 77   inserting a row
19b70 20 69 6e 74 6f 20 74 68 65 20 64 61 74 61 62 61   into the databa
19b80 73 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  se..*/.SQLITE_AP
19b90 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 73  I void sqlite3_s
19ba0 65 74 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72  et_last_insert_r
19bb0 6f 77 69 64 28 73 71 6c 69 74 65 33 2a 2c 73 71  owid(sqlite3*,sq
19bc0 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 0a 2f  lite3_int64);../
19bd0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
19be0 6f 75 6e 74 20 54 68 65 20 4e 75 6d 62 65 72 20  ount The Number 
19bf0 4f 66 20 52 6f 77 73 20 4d 6f 64 69 66 69 65 64  Of Rows Modified
19c00 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
19c10 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20  te3.**.** ^This 
19c20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73  function returns
19c30 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 72   the number of r
19c40 6f 77 73 20 6d 6f 64 69 66 69 65 64 2c 20 69 6e  ows modified, in
19c50 73 65 72 74 65 64 20 6f 72 0a 2a 2a 20 64 65 6c  serted or.** del
19c60 65 74 65 64 20 62 79 20 74 68 65 20 6d 6f 73 74  eted by the most
19c70 20 72 65 63 65 6e 74 6c 79 20 63 6f 6d 70 6c 65   recently comple
19c80 74 65 64 20 49 4e 53 45 52 54 2c 20 55 50 44 41  ted INSERT, UPDA
19c90 54 45 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20  TE or DELETE.** 
19ca0 73 74 61 74 65 6d 65 6e 74 20 6f 6e 20 74 68 65  statement on the
19cb0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
19cc0 74 69 6f 6e 20 73 70 65 63 69 66 69 65 64 20 62  tion specified b
19cd0 79 20 74 68 65 20 6f 6e 6c 79 20 70 61 72 61 6d  y the only param
19ce0 65 74 65 72 2e 0a 2a 2a 20 5e 45 78 65 63 75 74  eter..** ^Execut
19cf0 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 74 79  ing any other ty
19d00 70 65 20 6f 66 20 53 51 4c 20 73 74 61 74 65 6d  pe of SQL statem
19d10 65 6e 74 20 64 6f 65 73 20 6e 6f 74 20 6d 6f 64  ent does not mod
19d20 69 66 79 20 74 68 65 20 76 61 6c 75 65 0a 2a 2a  ify the value.**
19d30 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 69   returned by thi
19d40 73 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a  s function..**.*
19d50 2a 20 5e 4f 6e 6c 79 20 63 68 61 6e 67 65 73 20  * ^Only changes 
19d60 6d 61 64 65 20 64 69 72 65 63 74 6c 79 20 62 79  made directly by
19d70 20 74 68 65 20 49 4e 53 45 52 54 2c 20 55 50 44   the INSERT, UPD
19d80 41 54 45 20 6f 72 20 44 45 4c 45 54 45 20 73 74  ATE or DELETE st
19d90 61 74 65 6d 65 6e 74 20 61 72 65 0a 2a 2a 20 63  atement are.** c
19da0 6f 6e 73 69 64 65 72 65 64 20 2d 20 61 75 78 69  onsidered - auxi
19db0 6c 69 61 72 79 20 63 68 61 6e 67 65 73 20 63 61  liary changes ca
19dc0 75 73 65 64 20 62 79 20 5b 43 52 45 41 54 45 20  used by [CREATE 
19dd0 54 52 49 47 47 45 52 20 7c 20 74 72 69 67 67 65  TRIGGER | trigge
19de0 72 73 5d 2c 20 0a 2a 2a 20 5b 66 6f 72 65 69 67  rs], .** [foreig
19df0 6e 20 6b 65 79 20 61 63 74 69 6f 6e 73 5d 20 6f  n key actions] o
19e00 72 20 5b 52 45 50 4c 41 43 45 5d 20 63 6f 6e 73  r [REPLACE] cons
19e10 74 72 61 69 6e 74 20 72 65 73 6f 6c 75 74 69 6f  traint resolutio
19e20 6e 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65  n are not counte
19e30 64 2e 0a 2a 2a 20 0a 2a 2a 20 43 68 61 6e 67 65  d..** .** Change
19e40 73 20 74 6f 20 61 20 76 69 65 77 20 74 68 61 74  s to a view that
19e50 20 61 72 65 20 69 6e 74 65 72 63 65 70 74 65 64   are intercepted
19e60 20 62 79 20 0a 2a 2a 20 5b 49 4e 53 54 45 41 44   by .** [INSTEAD
19e70 20 4f 46 20 74 72 69 67 67 65 72 20 7c 20 49 4e   OF trigger | IN
19e80 53 54 45 41 44 20 4f 46 20 74 72 69 67 67 65 72  STEAD OF trigger
19e90 73 5d 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74  s] are not count
19ea0 65 64 2e 20 5e 54 68 65 20 76 61 6c 75 65 20 0a  ed. ^The value .
19eb0 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 79 20 73  ** returned by s
19ec0 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29  qlite3_changes()
19ed0 20 69 6d 6d 65 64 69 61 74 65 6c 79 20 61 66 74   immediately aft
19ee0 65 72 20 61 6e 20 49 4e 53 45 52 54 2c 20 55 50  er an INSERT, UP
19ef0 44 41 54 45 20 6f 72 20 0a 2a 2a 20 44 45 4c 45  DATE or .** DELE
19f00 54 45 20 73 74 61 74 65 6d 65 6e 74 20 72 75 6e  TE statement run
19f10 20 6f 6e 20 61 20 76 69 65 77 20 69 73 20 61 6c   on a view is al
19f20 77 61 79 73 20 7a 65 72 6f 2e 20 4f 6e 6c 79 20  ways zero. Only 
19f30 63 68 61 6e 67 65 73 20 6d 61 64 65 20 74 6f 20  changes made to 
19f40 72 65 61 6c 20 0a 2a 2a 20 74 61 62 6c 65 73 20  real .** tables 
19f50 61 72 65 20 63 6f 75 6e 74 65 64 2e 0a 2a 2a 0a  are counted..**.
19f60 2a 2a 20 54 68 69 6e 67 73 20 61 72 65 20 6d 6f  ** Things are mo
19f70 72 65 20 63 6f 6d 70 6c 69 63 61 74 65 64 20 69  re complicated i
19f80 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 68  f the sqlite3_ch
19f90 61 6e 67 65 73 28 29 20 66 75 6e 63 74 69 6f 6e  anges() function
19fa0 20 69 73 0a 2a 2a 20 65 78 65 63 75 74 65 64 20   is.** executed 
19fb0 77 68 69 6c 65 20 61 20 74 72 69 67 67 65 72 20  while a trigger 
19fc0 70 72 6f 67 72 61 6d 20 69 73 20 72 75 6e 6e 69  program is runni
19fd0 6e 67 2e 20 54 68 69 73 20 6d 61 79 20 68 61 70  ng. This may hap
19fe0 70 65 6e 20 69 66 20 74 68 65 0a 2a 2a 20 70 72  pen if the.** pr
19ff0 6f 67 72 61 6d 20 75 73 65 73 20 74 68 65 20 5b  ogram uses the [
1a000 63 68 61 6e 67 65 73 28 29 20 53 51 4c 20 66 75  changes() SQL fu
1a010 6e 63 74 69 6f 6e 5d 2c 20 6f 72 20 69 66 20 73  nction], or if s
1a020 6f 6d 65 20 6f 74 68 65 72 20 63 61 6c 6c 62 61  ome other callba
1a030 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69  ck.** function i
1a040 6e 76 6f 6b 65 73 20 73 71 6c 69 74 65 33 5f 63  nvokes sqlite3_c
1a050 68 61 6e 67 65 73 28 29 20 64 69 72 65 63 74 6c  hanges() directl
1a060 79 2e 20 45 73 73 65 6e 74 69 61 6c 6c 79 3a 0a  y. Essentially:.
1a070 2a 2a 20 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20  ** .** <ul>.**  
1a080 20 3c 6c 69 3e 20 5e 28 42 65 66 6f 72 65 20 65   <li> ^(Before e
1a090 6e 74 65 72 69 6e 67 20 61 20 74 72 69 67 67 65  ntering a trigge
1a0a0 72 20 70 72 6f 67 72 61 6d 20 74 68 65 20 76 61  r program the va
1a0b0 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 0a  lue returned by.
1a0c0 2a 2a 20 20 20 20 20 20 20 20 73 71 6c 69 74 65  **        sqlite
1a0d0 33 5f 63 68 61 6e 67 65 73 28 29 20 66 75 6e 63  3_changes() func
1a0e0 74 69 6f 6e 20 69 73 20 73 61 76 65 64 2e 20 41  tion is saved. A
1a0f0 66 74 65 72 20 74 68 65 20 74 72 69 67 67 65 72  fter the trigger
1a100 20 70 72 6f 67 72 61 6d 20 0a 2a 2a 20 20 20 20   program .**    
1a110 20 20 20 20 68 61 73 20 66 69 6e 69 73 68 65 64      has finished
1a120 2c 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 76  , the original v
1a130 61 6c 75 65 20 69 73 20 72 65 73 74 6f 72 65 64  alue is restored
1a140 2e 29 5e 0a 2a 2a 20 0a 2a 2a 20 20 20 3c 6c 69  .)^.** .**   <li
1a150 3e 20 5e 28 57 69 74 68 69 6e 20 61 20 74 72 69  > ^(Within a tri
1a160 67 67 65 72 20 70 72 6f 67 72 61 6d 20 65 61 63  gger program eac
1a170 68 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45  h INSERT, UPDATE
1a180 20 61 6e 64 20 44 45 4c 45 54 45 20 0a 2a 2a 20   and DELETE .** 
1a190 20 20 20 20 20 20 20 73 74 61 74 65 6d 65 6e 74         statement
1a1a0 20 73 65 74 73 20 74 68 65 20 76 61 6c 75 65 20   sets the value 
1a1b0 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69  returned by sqli
1a1c0 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20 0a 2a  te3_changes() .*
1a1d0 2a 20 20 20 20 20 20 20 20 75 70 6f 6e 20 63 6f  *        upon co
1a1e0 6d 70 6c 65 74 69 6f 6e 20 61 73 20 6e 6f 72 6d  mpletion as norm
1a1f0 61 6c 2e 20 4f 66 20 63 6f 75 72 73 65 2c 20 74  al. Of course, t
1a200 68 69 73 20 76 61 6c 75 65 20 77 69 6c 6c 20 6e  his value will n
1a210 6f 74 20 69 6e 63 6c 75 64 65 20 0a 2a 2a 20 20  ot include .**  
1a220 20 20 20 20 20 20 61 6e 79 20 63 68 61 6e 67 65        any change
1a230 73 20 70 65 72 66 6f 72 6d 65 64 20 62 79 20 73  s performed by s
1a240 75 62 2d 74 72 69 67 67 65 72 73 2c 20 61 73 20  ub-triggers, as 
1a250 74 68 65 20 73 71 6c 69 74 65 33 5f 63 68 61 6e  the sqlite3_chan
1a260 67 65 73 28 29 20 0a 2a 2a 20 20 20 20 20 20 20  ges() .**       
1a270 20 76 61 6c 75 65 20 77 69 6c 6c 20 62 65 20 73   value will be s
1a280 61 76 65 64 20 61 6e 64 20 72 65 73 74 6f 72 65  aved and restore
1a290 64 20 61 66 74 65 72 20 65 61 63 68 20 73 75 62  d after each sub
1a2a0 2d 74 72 69 67 67 65 72 20 68 61 73 20 72 75 6e  -trigger has run
1a2b0 2e 29 5e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 20  .)^.** </ul>.** 
1a2c0 0a 2a 2a 20 5e 54 68 69 73 20 6d 65 61 6e 73 20  .** ^This means 
1a2d0 74 68 61 74 20 69 66 20 74 68 65 20 63 68 61 6e  that if the chan
1a2e0 67 65 73 28 29 20 53 51 4c 20 66 75 6e 63 74 69  ges() SQL functi
1a2f0 6f 6e 20 28 6f 72 20 73 69 6d 69 6c 61 72 29 20  on (or similar) 
1a300 69 73 20 75 73 65 64 0a 2a 2a 20 62 79 20 74 68  is used.** by th
1a310 65 20 66 69 72 73 74 20 49 4e 53 45 52 54 2c 20  e first INSERT, 
1a320 55 50 44 41 54 45 20 6f 72 20 44 45 4c 45 54 45  UPDATE or DELETE
1a330 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68 69   statement withi
1a340 6e 20 61 20 74 72 69 67 67 65 72 2c 20 69 74 20  n a trigger, it 
1a350 0a 2a 2a 20 72 65 74 75 72 6e 73 20 74 68 65 20  .** returns the 
1a360 76 61 6c 75 65 20 61 73 20 73 65 74 20 77 68 65  value as set whe
1a370 6e 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 73 74  n the calling st
1a380 61 74 65 6d 65 6e 74 20 62 65 67 61 6e 20 65 78  atement began ex
1a390 65 63 75 74 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20  ecuting..** ^If 
1a3a0 69 74 20 69 73 20 75 73 65 64 20 62 79 20 74 68  it is used by th
1a3b0 65 20 73 65 63 6f 6e 64 20 6f 72 20 73 75 62 73  e second or subs
1a3c0 65 71 75 65 6e 74 20 73 75 63 68 20 73 74 61 74  equent such stat
1a3d0 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 61 20 74  ement within a t
1a3e0 72 69 67 67 65 72 20 0a 2a 2a 20 70 72 6f 67 72  rigger .** progr
1a3f0 61 6d 2c 20 74 68 65 20 76 61 6c 75 65 20 72 65  am, the value re
1a400 74 75 72 6e 65 64 20 72 65 66 6c 65 63 74 73 20  turned reflects 
1a410 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f  the number of ro
1a420 77 73 20 6d 6f 64 69 66 69 65 64 20 62 79 20 74  ws modified by t
1a430 68 65 20 0a 2a 2a 20 70 72 65 76 69 6f 75 73 20  he .** previous 
1a440 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 20 6f  INSERT, UPDATE o
1a450 72 20 44 45 4c 45 54 45 20 73 74 61 74 65 6d 65  r DELETE stateme
1a460 6e 74 20 77 69 74 68 69 6e 20 74 68 65 20 73 61  nt within the sa
1a470 6d 65 20 74 72 69 67 67 65 72 2e 0a 2a 2a 0a 2a  me trigger..**.*
1a480 2a 20 53 65 65 20 61 6c 73 6f 20 74 68 65 20 5b  * See also the [
1a490 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68  sqlite3_total_ch
1a4a0 61 6e 67 65 73 28 29 5d 20 69 6e 74 65 72 66 61  anges()] interfa
1a4b0 63 65 2c 20 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e  ce, the.** [coun
1a4c0 74 5f 63 68 61 6e 67 65 73 20 70 72 61 67 6d 61  t_changes pragma
1a4d0 5d 2c 20 61 6e 64 20 74 68 65 20 5b 63 68 61 6e  ], and the [chan
1a4e0 67 65 73 28 29 20 53 51 4c 20 66 75 6e 63 74 69  ges() SQL functi
1a4f0 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20  on]..**.** If a 
1a500 73 65 70 61 72 61 74 65 20 74 68 72 65 61 64 20  separate thread 
1a510 6d 61 6b 65 73 20 63 68 61 6e 67 65 73 20 6f 6e  makes changes on
1a520 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61   the same databa
1a530 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a  se connection.**
1a540 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f   while [sqlite3_
1a550 63 68 61 6e 67 65 73 28 29 5d 20 69 73 20 72 75  changes()] is ru
1a560 6e 6e 69 6e 67 20 74 68 65 6e 20 74 68 65 20 76  nning then the v
1a570 61 6c 75 65 20 72 65 74 75 72 6e 65 64 0a 2a 2a  alue returned.**
1a580 20 69 73 20 75 6e 70 72 65 64 69 63 74 61 62 6c   is unpredictabl
1a590 65 20 61 6e 64 20 6e 6f 74 20 6d 65 61 6e 69 6e  e and not meanin
1a5a0 67 66 75 6c 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  gful..*/.SQLITE_
1a5b0 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
1a5c0 63 68 61 6e 67 65 73 28 73 71 6c 69 74 65 33 2a  changes(sqlite3*
1a5d0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
1a5e0 45 46 3a 20 54 6f 74 61 6c 20 4e 75 6d 62 65 72  EF: Total Number
1a5f0 20 4f 66 20 52 6f 77 73 20 4d 6f 64 69 66 69 65   Of Rows Modifie
1a600 64 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  d.** METHOD: sql
1a610 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73  ite3.**.** ^This
1a620 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e   function return
1a630 73 20 74 68 65 20 74 6f 74 61 6c 20 6e 75 6d 62  s the total numb
1a640 65 72 20 6f 66 20 72 6f 77 73 20 69 6e 73 65 72  er of rows inser
1a650 74 65 64 2c 20 6d 6f 64 69 66 69 65 64 20 6f 72  ted, modified or
1a660 0a 2a 2a 20 64 65 6c 65 74 65 64 20 62 79 20 61  .** deleted by a
1a670 6c 6c 20 5b 49 4e 53 45 52 54 5d 2c 20 5b 55 50  ll [INSERT], [UP
1a680 44 41 54 45 5d 20 6f 72 20 5b 44 45 4c 45 54 45  DATE] or [DELETE
1a690 5d 20 73 74 61 74 65 6d 65 6e 74 73 20 63 6f 6d  ] statements com
1a6a0 70 6c 65 74 65 64 0a 2a 2a 20 73 69 6e 63 65 20  pleted.** since 
1a6b0 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
1a6c0 6e 65 63 74 69 6f 6e 20 77 61 73 20 6f 70 65 6e  nection was open
1a6d0 65 64 2c 20 69 6e 63 6c 75 64 69 6e 67 20 74 68  ed, including th
1a6e0 6f 73 65 20 65 78 65 63 75 74 65 64 20 61 73 0a  ose executed as.
1a6f0 2a 2a 20 70 61 72 74 20 6f 66 20 74 72 69 67 67  ** part of trigg
1a700 65 72 20 70 72 6f 67 72 61 6d 73 2e 20 5e 45 78  er programs. ^Ex
1a710 65 63 75 74 69 6e 67 20 61 6e 79 20 6f 74 68 65  ecuting any othe
1a720 72 20 74 79 70 65 20 6f 66 20 53 51 4c 20 73 74  r type of SQL st
1a730 61 74 65 6d 65 6e 74 0a 2a 2a 20 64 6f 65 73 20  atement.** does 
1a740 6e 6f 74 20 61 66 66 65 63 74 20 74 68 65 20 76  not affect the v
1a750 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79  alue returned by
1a760 20 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63   sqlite3_total_c
1a770 68 61 6e 67 65 73 28 29 2e 0a 2a 2a 20 0a 2a 2a  hanges()..** .**
1a780 20 5e 43 68 61 6e 67 65 73 20 6d 61 64 65 20 61   ^Changes made a
1a790 73 20 70 61 72 74 20 6f 66 20 5b 66 6f 72 65 69  s part of [forei
1a7a0 67 6e 20 6b 65 79 20 61 63 74 69 6f 6e 73 5d 20  gn key actions] 
1a7b0 61 72 65 20 69 6e 63 6c 75 64 65 64 20 69 6e 20  are included in 
1a7c0 74 68 65 0a 2a 2a 20 63 6f 75 6e 74 2c 20 62 75  the.** count, bu
1a7d0 74 20 74 68 6f 73 65 20 6d 61 64 65 20 61 73 20  t those made as 
1a7e0 70 61 72 74 20 6f 66 20 52 45 50 4c 41 43 45 20  part of REPLACE 
1a7f0 63 6f 6e 73 74 72 61 69 6e 74 20 72 65 73 6f 6c  constraint resol
1a800 75 74 69 6f 6e 20 61 72 65 0a 2a 2a 20 6e 6f 74  ution are.** not
1a810 2e 20 5e 43 68 61 6e 67 65 73 20 74 6f 20 61 20  . ^Changes to a 
1a820 76 69 65 77 20 74 68 61 74 20 61 72 65 20 69 6e  view that are in
1a830 74 65 72 63 65 70 74 65 64 20 62 79 20 49 4e 53  tercepted by INS
1a840 54 45 41 44 20 4f 46 20 74 72 69 67 67 65 72 73  TEAD OF triggers
1a850 20 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 63 6f 75   .** are not cou
1a860 6e 74 65 64 2e 0a 2a 2a 20 0a 2a 2a 20 53 65 65  nted..** .** See
1a870 20 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69 74   also the [sqlit
1a880 65 33 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 6e  e3_changes()] in
1a890 74 65 72 66 61 63 65 2c 20 74 68 65 0a 2a 2a 20  terface, the.** 
1a8a0 5b 63 6f 75 6e 74 5f 63 68 61 6e 67 65 73 20 70  [count_changes p
1a8b0 72 61 67 6d 61 5d 2c 20 61 6e 64 20 74 68 65 20  ragma], and the 
1a8c0 5b 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29  [total_changes()
1a8d0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a   SQL function]..
1a8e0 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70 61 72  **.** If a separ
1a8f0 61 74 65 20 74 68 72 65 61 64 20 6d 61 6b 65 73  ate thread makes
1a900 20 63 68 61 6e 67 65 73 20 6f 6e 20 74 68 65 20   changes on the 
1a910 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f  same database co
1a920 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c  nnection.** whil
1a930 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c  e [sqlite3_total
1a940 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 73 20 72  _changes()] is r
1a950 75 6e 6e 69 6e 67 20 74 68 65 6e 20 74 68 65 20  unning then the 
1a960 76 61 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65  value.** returne
1a970 64 20 69 73 20 75 6e 70 72 65 64 69 63 74 61 62  d is unpredictab
1a980 6c 65 20 61 6e 64 20 6e 6f 74 20 6d 65 61 6e 69  le and not meani
1a990 6e 67 66 75 6c 2e 0a 2a 2f 0a 53 51 4c 49 54 45  ngful..*/.SQLITE
1a9a0 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
1a9b0 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 73  _total_changes(s
1a9c0 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  qlite3*);../*.**
1a9d0 20 43 41 50 49 33 52 45 46 3a 20 49 6e 74 65 72   CAPI3REF: Inter
1a9e0 72 75 70 74 20 41 20 4c 6f 6e 67 2d 52 75 6e 6e  rupt A Long-Runn
1a9f0 69 6e 67 20 51 75 65 72 79 0a 2a 2a 20 4d 45 54  ing Query.** MET
1aa00 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a  HOD: sqlite3.**.
1aa10 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f  ** ^This functio
1aa20 6e 20 63 61 75 73 65 73 20 61 6e 79 20 70 65 6e  n causes any pen
1aa30 64 69 6e 67 20 64 61 74 61 62 61 73 65 20 6f 70  ding database op
1aa40 65 72 61 74 69 6f 6e 20 74 6f 20 61 62 6f 72 74  eration to abort
1aa50 20 61 6e 64 0a 2a 2a 20 72 65 74 75 72 6e 20 61   and.** return a
1aa60 74 20 69 74 73 20 65 61 72 6c 69 65 73 74 20 6f  t its earliest o
1aa70 70 70 6f 72 74 75 6e 69 74 79 2e 20 54 68 69 73  pportunity. This
1aa80 20 72 6f 75 74 69 6e 65 20 69 73 20 74 79 70 69   routine is typi
1aa90 63 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64 20  cally.** called 
1aaa0 69 6e 20 72 65 73 70 6f 6e 73 65 20 74 6f 20 61  in response to a
1aab0 20 75 73 65 72 20 61 63 74 69 6f 6e 20 73 75 63   user action suc
1aac0 68 20 61 73 20 70 72 65 73 73 69 6e 67 20 22 43  h as pressing "C
1aad0 61 6e 63 65 6c 22 0a 2a 2a 20 6f 72 20 43 74 72  ancel".** or Ctr
1aae0 6c 2d 43 20 77 68 65 72 65 20 74 68 65 20 75 73  l-C where the us
1aaf0 65 72 20 77 61 6e 74 73 20 61 20 6c 6f 6e 67 20  er wants a long 
1ab00 71 75 65 72 79 20 6f 70 65 72 61 74 69 6f 6e 20  query operation 
1ab10 74 6f 20 68 61 6c 74 0a 2a 2a 20 69 6d 6d 65 64  to halt.** immed
1ab20 69 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49  iately..**.** ^I
1ab30 74 20 69 73 20 73 61 66 65 20 74 6f 20 63 61 6c  t is safe to cal
1ab40 6c 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 66  l this routine f
1ab50 72 6f 6d 20 61 20 74 68 72 65 61 64 20 64 69 66  rom a thread dif
1ab60 66 65 72 65 6e 74 20 66 72 6f 6d 20 74 68 65 0a  ferent from the.
1ab70 2a 2a 20 74 68 72 65 61 64 20 74 68 61 74 20 69  ** thread that i
1ab80 73 20 63 75 72 72 65 6e 74 6c 79 20 72 75 6e 6e  s currently runn
1ab90 69 6e 67 20 74 68 65 20 64 61 74 61 62 61 73 65  ing the database
1aba0 20 6f 70 65 72 61 74 69 6f 6e 2e 20 20 42 75 74   operation.  But
1abb0 20 69 74 0a 2a 2a 20 69 73 20 6e 6f 74 20 73 61   it.** is not sa
1abc0 66 65 20 74 6f 20 63 61 6c 6c 20 74 68 69 73 20  fe to call this 
1abd0 72 6f 75 74 69 6e 65 20 77 69 74 68 20 61 20 5b  routine with a [
1abe0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1abf0 69 6f 6e 5d 20 74 68 61 74 0a 2a 2a 20 69 73 20  ion] that.** is 
1ac00 63 6c 6f 73 65 64 20 6f 72 20 6d 69 67 68 74 20  closed or might 
1ac10 63 6c 6f 73 65 20 62 65 66 6f 72 65 20 73 71 6c  close before sql
1ac20 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29  ite3_interrupt()
1ac30 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20   returns..**.** 
1ac40 5e 49 66 20 61 6e 20 53 51 4c 20 6f 70 65 72 61  ^If an SQL opera
1ac50 74 69 6f 6e 20 69 73 20 76 65 72 79 20 6e 65 61  tion is very nea
1ac60 72 6c 79 20 66 69 6e 69 73 68 65 64 20 61 74 20  rly finished at 
1ac70 74 68 65 20 74 69 6d 65 20 77 68 65 6e 0a 2a 2a  the time when.**
1ac80 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75   sqlite3_interru
1ac90 70 74 28 29 20 69 73 20 63 61 6c 6c 65 64 2c 20  pt() is called, 
1aca0 74 68 65 6e 20 69 74 20 6d 69 67 68 74 20 6e 6f  then it might no
1acb0 74 20 68 61 76 65 20 61 6e 20 6f 70 70 6f 72 74  t have an opport
1acc0 75 6e 69 74 79 0a 2a 2a 20 74 6f 20 62 65 20 69  unity.** to be i
1acd0 6e 74 65 72 72 75 70 74 65 64 20 61 6e 64 20 6d  nterrupted and m
1ace0 69 67 68 74 20 63 6f 6e 74 69 6e 75 65 20 74 6f  ight continue to
1acf0 20 63 6f 6d 70 6c 65 74 69 6f 6e 2e 0a 2a 2a 0a   completion..**.
1ad00 2a 2a 20 5e 41 6e 20 53 51 4c 20 6f 70 65 72 61  ** ^An SQL opera
1ad10 74 69 6f 6e 20 74 68 61 74 20 69 73 20 69 6e 74  tion that is int
1ad20 65 72 72 75 70 74 65 64 20 77 69 6c 6c 20 72 65  errupted will re
1ad30 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 49 4e 54  turn [SQLITE_INT
1ad40 45 52 52 55 50 54 5d 2e 0a 2a 2a 20 5e 49 66 20  ERRUPT]..** ^If 
1ad50 74 68 65 20 69 6e 74 65 72 72 75 70 74 65 64 20  the interrupted 
1ad60 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 69 73  SQL operation is
1ad70 20 61 6e 20 49 4e 53 45 52 54 2c 20 55 50 44 41   an INSERT, UPDA
1ad80 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a  TE, or DELETE.**
1ad90 20 74 68 61 74 20 69 73 20 69 6e 73 69 64 65 20   that is inside 
1ada0 61 6e 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e  an explicit tran
1adb0 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68  saction, then th
1adc0 65 20 65 6e 74 69 72 65 20 74 72 61 6e 73 61 63  e entire transac
1add0 74 69 6f 6e 0a 2a 2a 20 77 69 6c 6c 20 62 65 20  tion.** will be 
1ade0 72 6f 6c 6c 65 64 20 62 61 63 6b 20 61 75 74 6f  rolled back auto
1adf0 6d 61 74 69 63 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a  matically..**.**
1ae00 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e   ^The sqlite3_in
1ae10 74 65 72 72 75 70 74 28 44 29 20 63 61 6c 6c 20  terrupt(D) call 
1ae20 69 73 20 69 6e 20 65 66 66 65 63 74 20 75 6e 74  is in effect unt
1ae30 69 6c 20 61 6c 6c 20 63 75 72 72 65 6e 74 6c 79  il all currently
1ae40 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51 4c 20   running.** SQL 
1ae50 73 74 61 74 65 6d 65 6e 74 73 20 6f 6e 20 5b 64  statements on [d
1ae60 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1ae70 6f 6e 5d 20 44 20 63 6f 6d 70 6c 65 74 65 2e 20  on] D complete. 
1ae80 20 5e 41 6e 79 20 6e 65 77 20 53 51 4c 20 73 74   ^Any new SQL st
1ae90 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74  atements.** that
1aea0 20 61 72 65 20 73 74 61 72 74 65 64 20 61 66 74   are started aft
1aeb0 65 72 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69  er the sqlite3_i
1aec0 6e 74 65 72 72 75 70 74 28 29 20 63 61 6c 6c 20  nterrupt() call 
1aed0 61 6e 64 20 62 65 66 6f 72 65 20 74 68 65 20 0a  and before the .
1aee0 2a 2a 20 72 75 6e 6e 69 6e 67 20 73 74 61 74 65  ** running state
1aef0 6d 65 6e 74 73 20 72 65 61 63 68 65 73 20 7a 65  ments reaches ze
1af00 72 6f 20 61 72 65 20 69 6e 74 65 72 72 75 70 74  ro are interrupt
1af10 65 64 20 61 73 20 69 66 20 74 68 65 79 20 68 61  ed as if they ha
1af20 64 20 62 65 65 6e 0a 2a 2a 20 72 75 6e 6e 69 6e  d been.** runnin
1af30 67 20 70 72 69 6f 72 20 74 6f 20 74 68 65 20 73  g prior to the s
1af40 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
1af50 28 29 20 63 61 6c 6c 2e 20 20 5e 4e 65 77 20 53  () call.  ^New S
1af60 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a  QL statements.**
1af70 20 74 68 61 74 20 61 72 65 20 73 74 61 72 74 65   that are starte
1af80 64 20 61 66 74 65 72 20 74 68 65 20 72 75 6e 6e  d after the runn
1af90 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 63 6f  ing statement co
1afa0 75 6e 74 20 72 65 61 63 68 65 73 20 7a 65 72 6f  unt reaches zero
1afb0 20 61 72 65 0a 2a 2a 20 6e 6f 74 20 65 66 66 65   are.** not effe
1afc0 63 74 65 64 20 62 79 20 74 68 65 20 73 71 6c 69  cted by the sqli
1afd0 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 2e  te3_interrupt().
1afe0 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 6f 20 73  .** ^A call to s
1aff0 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
1b000 28 44 29 20 74 68 61 74 20 6f 63 63 75 72 73 20  (D) that occurs 
1b010 77 68 65 6e 20 74 68 65 72 65 20 61 72 65 20 6e  when there are n
1b020 6f 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51 4c  o running.** SQL
1b030 20 73 74 61 74 65 6d 65 6e 74 73 20 69 73 20 61   statements is a
1b040 20 6e 6f 2d 6f 70 20 61 6e 64 20 68 61 73 20 6e   no-op and has n
1b050 6f 20 65 66 66 65 63 74 20 6f 6e 20 53 51 4c 20  o effect on SQL 
1b060 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68  statements.** th
1b070 61 74 20 61 72 65 20 73 74 61 72 74 65 64 20 61  at are started a
1b080 66 74 65 72 20 74 68 65 20 73 71 6c 69 74 65 33  fter the sqlite3
1b090 5f 69 6e 74 65 72 72 75 70 74 28 29 20 63 61 6c  _interrupt() cal
1b0a0 6c 20 72 65 74 75 72 6e 73 2e 0a 2a 2f 0a 53 51  l returns..*/.SQ
1b0b0 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71  LITE_API void sq
1b0c0 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28  lite3_interrupt(
1b0d0 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a  sqlite3*);../*.*
1b0e0 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 74 65  * CAPI3REF: Dete
1b0f0 72 6d 69 6e 65 20 49 66 20 41 6e 20 53 51 4c 20  rmine If An SQL 
1b100 53 74 61 74 65 6d 65 6e 74 20 49 73 20 43 6f 6d  Statement Is Com
1b110 70 6c 65 74 65 0a 2a 2a 0a 2a 2a 20 54 68 65 73  plete.**.** Thes
1b120 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 75  e routines are u
1b130 73 65 66 75 6c 20 64 75 72 69 6e 67 20 63 6f 6d  seful during com
1b140 6d 61 6e 64 2d 6c 69 6e 65 20 69 6e 70 75 74 20  mand-line input 
1b150 74 6f 20 64 65 74 65 72 6d 69 6e 65 20 69 66 20  to determine if 
1b160 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 6c 79  the.** currently
1b170 20 65 6e 74 65 72 65 64 20 74 65 78 74 20 73 65   entered text se
1b180 65 6d 73 20 74 6f 20 66 6f 72 6d 20 61 20 63 6f  ems to form a co
1b190 6d 70 6c 65 74 65 20 53 51 4c 20 73 74 61 74 65  mplete SQL state
1b1a0 6d 65 6e 74 20 6f 72 0a 2a 2a 20 69 66 20 61 64  ment or.** if ad
1b1b0 64 69 74 69 6f 6e 61 6c 20 69 6e 70 75 74 20 69  ditional input i
1b1c0 73 20 6e 65 65 64 65 64 20 62 65 66 6f 72 65 20  s needed before 
1b1d0 73 65 6e 64 69 6e 67 20 74 68 65 20 74 65 78 74  sending the text
1b1e0 20 69 6e 74 6f 0a 2a 2a 20 53 51 4c 69 74 65 20   into.** SQLite 
1b1f0 66 6f 72 20 70 61 72 73 69 6e 67 2e 20 20 5e 54  for parsing.  ^T
1b200 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65  hese routines re
1b210 74 75 72 6e 20 31 20 69 66 20 74 68 65 20 69 6e  turn 1 if the in
1b220 70 75 74 20 73 74 72 69 6e 67 0a 2a 2a 20 61 70  put string.** ap
1b230 70 65 61 72 73 20 74 6f 20 62 65 20 61 20 63 6f  pears to be a co
1b240 6d 70 6c 65 74 65 20 53 51 4c 20 73 74 61 74 65  mplete SQL state
1b250 6d 65 6e 74 2e 20 20 5e 41 20 73 74 61 74 65 6d  ment.  ^A statem
1b260 65 6e 74 20 69 73 20 6a 75 64 67 65 64 20 74 6f  ent is judged to
1b270 20 62 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 20   be.** complete 
1b280 69 66 20 69 74 20 65 6e 64 73 20 77 69 74 68 20  if it ends with 
1b290 61 20 73 65 6d 69 63 6f 6c 6f 6e 20 74 6f 6b 65  a semicolon toke
1b2a0 6e 20 61 6e 64 20 69 73 20 6e 6f 74 20 61 20 70  n and is not a p
1b2b0 72 65 66 69 78 20 6f 66 20 61 0a 2a 2a 20 77 65  refix of a.** we
1b2c0 6c 6c 2d 66 6f 72 6d 65 64 20 43 52 45 41 54 45  ll-formed CREATE
1b2d0 20 54 52 49 47 47 45 52 20 73 74 61 74 65 6d 65   TRIGGER stateme
1b2e0 6e 74 2e 20 20 5e 53 65 6d 69 63 6f 6c 6f 6e 73  nt.  ^Semicolons
1b2f0 20 74 68 61 74 20 61 72 65 20 65 6d 62 65 64 64   that are embedd
1b300 65 64 20 77 69 74 68 69 6e 0a 2a 2a 20 73 74 72  ed within.** str
1b310 69 6e 67 20 6c 69 74 65 72 61 6c 73 20 6f 72 20  ing literals or 
1b320 71 75 6f 74 65 64 20 69 64 65 6e 74 69 66 69 65  quoted identifie
1b330 72 20 6e 61 6d 65 73 20 6f 72 20 63 6f 6d 6d 65  r names or comme
1b340 6e 74 73 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 69  nts are not.** i
1b350 6e 64 65 70 65 6e 64 65 6e 74 20 74 6f 6b 65 6e  ndependent token
1b360 73 20 28 74 68 65 79 20 61 72 65 20 70 61 72 74  s (they are part
1b370 20 6f 66 20 74 68 65 20 74 6f 6b 65 6e 20 69 6e   of the token in
1b380 20 77 68 69 63 68 20 74 68 65 79 20 61 72 65 0a   which they are.
1b390 2a 2a 20 65 6d 62 65 64 64 65 64 29 20 61 6e 64  ** embedded) and
1b3a0 20 74 68 75 73 20 64 6f 20 6e 6f 74 20 63 6f 75   thus do not cou
1b3b0 6e 74 20 61 73 20 61 20 73 74 61 74 65 6d 65 6e  nt as a statemen
1b3c0 74 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20 5e  t terminator.  ^
1b3d0 57 68 69 74 65 73 70 61 63 65 0a 2a 2a 20 61 6e  Whitespace.** an
1b3e0 64 20 63 6f 6d 6d 65 6e 74 73 20 74 68 61 74 20  d comments that 
1b3f0 66 6f 6c 6c 6f 77 20 74 68 65 20 66 69 6e 61 6c  follow the final
1b400 20 73 65 6d 69 63 6f 6c 6f 6e 20 61 72 65 20 69   semicolon are i
1b410 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54  gnored..**.** ^T
1b420 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65  hese routines re
1b430 74 75 72 6e 20 30 20 69 66 20 74 68 65 20 73 74  turn 0 if the st
1b440 61 74 65 6d 65 6e 74 20 69 73 20 69 6e 63 6f 6d  atement is incom
1b450 70 6c 65 74 65 2e 20 20 5e 49 66 20 61 0a 2a 2a  plete.  ^If a.**
1b460 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
1b470 6f 6e 20 66 61 69 6c 73 2c 20 74 68 65 6e 20 53  on fails, then S
1b480 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20 69 73 20 72  QLITE_NOMEM is r
1b490 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  eturned..**.** ^
1b4a0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 64  These routines d
1b4b0 6f 20 6e 6f 74 20 70 61 72 73 65 20 74 68 65 20  o not parse the 
1b4c0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 74  SQL statements t
1b4d0 68 75 73 0a 2a 2a 20 77 69 6c 6c 20 6e 6f 74 20  hus.** will not 
1b4e0 64 65 74 65 63 74 20 73 79 6e 74 61 63 74 69 63  detect syntactic
1b4f0 61 6c 6c 79 20 69 6e 63 6f 72 72 65 63 74 20 53  ally incorrect S
1b500 51 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 53  QL..**.** ^(If S
1b510 51 4c 69 74 65 20 68 61 73 20 6e 6f 74 20 62 65  QLite has not be
1b520 65 6e 20 69 6e 69 74 69 61 6c 69 7a 65 64 20 75  en initialized u
1b530 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 69 6e  sing [sqlite3_in
1b540 69 74 69 61 6c 69 7a 65 28 29 5d 20 70 72 69 6f  itialize()] prio
1b550 72 20 0a 2a 2a 20 74 6f 20 69 6e 76 6f 6b 69 6e  r .** to invokin
1b560 67 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65  g sqlite3_comple
1b570 74 65 31 36 28 29 20 74 68 65 6e 20 73 71 6c 69  te16() then sqli
1b580 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
1b590 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61   is invoked.** a
1b5a0 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62 79 20  utomatically by 
1b5b0 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65  sqlite3_complete
1b5c0 31 36 28 29 2e 20 20 49 66 20 74 68 61 74 20 69  16().  If that i
1b5d0 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 66 61  nitialization fa
1b5e0 69 6c 73 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65  ils,.** then the
1b5f0 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66 72   return value fr
1b600 6f 6d 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c  om sqlite3_compl
1b610 65 74 65 31 36 28 29 20 77 69 6c 6c 20 62 65 20  ete16() will be 
1b620 6e 6f 6e 2d 7a 65 72 6f 0a 2a 2a 20 72 65 67 61  non-zero.** rega
1b630 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65  rdless of whethe
1b640 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 69 6e 70  r or not the inp
1b650 75 74 20 53 51 4c 20 69 73 20 63 6f 6d 70 6c 65  ut SQL is comple
1b660 74 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  te.)^.**.** The 
1b670 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 65  input to [sqlite
1b680 33 5f 63 6f 6d 70 6c 65 74 65 28 29 5d 20 6d 75  3_complete()] mu
1b690 73 74 20 62 65 20 61 20 7a 65 72 6f 2d 74 65 72  st be a zero-ter
1b6a0 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d 38  minated.** UTF-8
1b6b0 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54   string..**.** T
1b6c0 68 65 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c  he input to [sql
1b6d0 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28  ite3_complete16(
1b6e0 29 5d 20 6d 75 73 74 20 62 65 20 61 20 7a 65 72  )] must be a zer
1b6f0 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20  o-terminated.** 
1b700 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20 69 6e  UTF-16 string in
1b710 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64   native byte ord
1b720 65 72 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  er..*/.SQLITE_AP
1b730 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f  I int sqlite3_co
1b740 6d 70 6c 65 74 65 28 63 6f 6e 73 74 20 63 68 61  mplete(const cha
1b750 72 20 2a 73 71 6c 29 3b 0a 53 51 4c 49 54 45 5f  r *sql);.SQLITE_
1b760 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
1b770 63 6f 6d 70 6c 65 74 65 31 36 28 63 6f 6e 73 74  complete16(const
1b780 20 76 6f 69 64 20 2a 73 71 6c 29 3b 0a 0a 2f 2a   void *sql);../*
1b790 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65  .** CAPI3REF: Re
1b7a0 67 69 73 74 65 72 20 41 20 43 61 6c 6c 62 61 63  gister A Callbac
1b7b0 6b 20 54 6f 20 48 61 6e 64 6c 65 20 53 51 4c 49  k To Handle SQLI
1b7c0 54 45 5f 42 55 53 59 20 45 72 72 6f 72 73 0a 2a  TE_BUSY Errors.*
1b7d0 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 62 75 73  * KEYWORDS: {bus
1b7e0 79 2d 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61  y-handler callba
1b7f0 63 6b 7d 20 7b 62 75 73 79 20 68 61 6e 64 6c 65  ck} {busy handle
1b800 72 7d 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  r}.** METHOD: sq
1b810 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  lite3.**.** ^The
1b820 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61   sqlite3_busy_ha
1b830 6e 64 6c 65 72 28 44 2c 58 2c 50 29 20 72 6f 75  ndler(D,X,P) rou
1b840 74 69 6e 65 20 73 65 74 73 20 61 20 63 61 6c 6c  tine sets a call
1b850 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 58 0a  back function X.
1b860 2a 2a 20 74 68 61 74 20 6d 69 67 68 74 20 62 65  ** that might be
1b870 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 61 72   invoked with ar
1b880 67 75 6d 65 6e 74 20 50 20 77 68 65 6e 65 76 65  gument P wheneve
1b890 72 0a 2a 2a 20 61 6e 20 61 74 74 65 6d 70 74 20  r.** an attempt 
1b8a0 69 73 20 6d 61 64 65 20 74 6f 20 61 63 63 65 73  is made to acces
1b8b0 73 20 61 20 64 61 74 61 62 61 73 65 20 74 61 62  s a database tab
1b8c0 6c 65 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  le associated wi
1b8d0 74 68 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20  th.** [database 
1b8e0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 77 68  connection] D wh
1b8f0 65 6e 20 61 6e 6f 74 68 65 72 20 74 68 72 65 61  en another threa
1b900 64 0a 2a 2a 20 6f 72 20 70 72 6f 63 65 73 73 20  d.** or process 
1b910 68 61 73 20 74 68 65 20 74 61 62 6c 65 20 6c 6f  has the table lo
1b920 63 6b 65 64 2e 0a 2a 2a 20 54 68 65 20 73 71 6c  cked..** The sql
1b930 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65  ite3_busy_handle
1b940 72 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73  r() interface is
1b950 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65   used to impleme
1b960 6e 74 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  nt.** [sqlite3_b
1b970 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d 20 61  usy_timeout()] a
1b980 6e 64 20 5b 50 52 41 47 4d 41 20 62 75 73 79 5f  nd [PRAGMA busy_
1b990 74 69 6d 65 6f 75 74 5d 2e 0a 2a 2a 0a 2a 2a 20  timeout]..**.** 
1b9a0 5e 49 66 20 74 68 65 20 62 75 73 79 20 63 61 6c  ^If the busy cal
1b9b0 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c 2c 20 74  lback is NULL, t
1b9c0 68 65 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  hen [SQLITE_BUSY
1b9d0 5d 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64  ].** is returned
1b9e0 20 69 6d 6d 65 64 69 61 74 65 6c 79 20 75 70 6f   immediately upo
1b9f0 6e 20 65 6e 63 6f 75 6e 74 65 72 69 6e 67 20 74  n encountering t
1ba00 68 65 20 6c 6f 63 6b 2e 20 20 5e 49 66 20 74 68  he lock.  ^If th
1ba10 65 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 0a  e busy callback.
1ba20 2a 2a 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20  ** is not NULL, 
1ba30 74 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63  then the callbac
1ba40 6b 20 6d 69 67 68 74 20 62 65 20 69 6e 76 6f 6b  k might be invok
1ba50 65 64 20 77 69 74 68 20 74 77 6f 20 61 72 67 75  ed with two argu
1ba60 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ments..**.** ^Th
1ba70 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
1ba80 20 74 6f 20 74 68 65 20 62 75 73 79 20 68 61 6e   to the busy han
1ba90 64 6c 65 72 20 69 73 20 61 20 63 6f 70 79 20 6f  dler is a copy o
1baa0 66 20 74 68 65 20 76 6f 69 64 2a 20 70 6f 69 6e  f the void* poin
1bab0 74 65 72 20 77 68 69 63 68 0a 2a 2a 20 69 73 20  ter which.** is 
1bac0 74 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65  the third argume
1bad0 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 75  nt to sqlite3_bu
1bae0 73 79 5f 68 61 6e 64 6c 65 72 28 29 2e 20 20 5e  sy_handler().  ^
1baf0 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  The second argum
1bb00 65 6e 74 20 74 6f 0a 2a 2a 20 74 68 65 20 62 75  ent to.** the bu
1bb10 73 79 20 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62  sy handler callb
1bb20 61 63 6b 20 69 73 20 74 68 65 20 6e 75 6d 62 65  ack is the numbe
1bb30 72 20 6f 66 20 74 69 6d 65 73 20 74 68 61 74 20  r of times that 
1bb40 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72  the busy handler
1bb50 20 68 61 73 0a 2a 2a 20 62 65 65 6e 20 69 6e 76   has.** been inv
1bb60 6f 6b 65 64 20 70 72 65 76 69 6f 75 73 6c 79 20  oked previously 
1bb70 66 6f 72 20 74 68 65 20 73 61 6d 65 20 6c 6f 63  for the same loc
1bb80 6b 69 6e 67 20 65 76 65 6e 74 2e 20 20 5e 49 66  king event.  ^If
1bb90 20 74 68 65 0a 2a 2a 20 62 75 73 79 20 63 61 6c   the.** busy cal
1bba0 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 30 2c  lback returns 0,
1bbb0 20 74 68 65 6e 20 6e 6f 20 61 64 64 69 74 69 6f   then no additio
1bbc0 6e 61 6c 20 61 74 74 65 6d 70 74 73 20 61 72 65  nal attempts are
1bbd0 20 6d 61 64 65 20 74 6f 0a 2a 2a 20 61 63 63 65   made to.** acce
1bbe0 73 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ss the database 
1bbf0 61 6e 64 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  and [SQLITE_BUSY
1bc00 5d 20 69 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a  ] is returned.**
1bc10 20 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74   to the applicat
1bc20 69 6f 6e 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ion..** ^If the 
1bc30 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73  callback returns
1bc40 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20   non-zero, then 
1bc50 61 6e 6f 74 68 65 72 20 61 74 74 65 6d 70 74 0a  another attempt.
1bc60 2a 2a 20 69 73 20 6d 61 64 65 20 74 6f 20 61 63  ** is made to ac
1bc70 63 65 73 73 20 74 68 65 20 64 61 74 61 62 61 73  cess the databas
1bc80 65 20 61 6e 64 20 74 68 65 20 63 79 63 6c 65 20  e and the cycle 
1bc90 72 65 70 65 61 74 73 2e 0a 2a 2a 0a 2a 2a 20 54  repeats..**.** T
1bca0 68 65 20 70 72 65 73 65 6e 63 65 20 6f 66 20 61  he presence of a
1bcb0 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 64 6f   busy handler do
1bcc0 65 73 20 6e 6f 74 20 67 75 61 72 61 6e 74 65 65  es not guarantee
1bcd0 20 74 68 61 74 20 69 74 20 77 69 6c 6c 20 62 65   that it will be
1bce0 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 77 68 65 6e   invoked.** when
1bcf0 20 74 68 65 72 65 20 69 73 20 6c 6f 63 6b 20 63   there is lock c
1bd00 6f 6e 74 65 6e 74 69 6f 6e 2e 20 5e 49 66 20 53  ontention. ^If S
1bd10 51 4c 69 74 65 20 64 65 74 65 72 6d 69 6e 65 73  QLite determines
1bd20 20 74 68 61 74 20 69 6e 76 6f 6b 69 6e 67 20 74   that invoking t
1bd30 68 65 20 62 75 73 79 0a 2a 2a 20 68 61 6e 64 6c  he busy.** handl
1bd40 65 72 20 63 6f 75 6c 64 20 72 65 73 75 6c 74 20  er could result 
1bd50 69 6e 20 61 20 64 65 61 64 6c 6f 63 6b 2c 20 69  in a deadlock, i
1bd60 74 20 77 69 6c 6c 20 67 6f 20 61 68 65 61 64 20  t will go ahead 
1bd70 61 6e 64 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  and return [SQLI
1bd80 54 45 5f 42 55 53 59 5d 0a 2a 2a 20 74 6f 20 74  TE_BUSY].** to t
1bd90 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69  he application i
1bda0 6e 73 74 65 61 64 20 6f 66 20 69 6e 76 6f 6b 69  nstead of invoki
1bdb0 6e 67 20 74 68 65 20 0a 2a 2a 20 62 75 73 79 20  ng the .** busy 
1bdc0 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 43 6f 6e 73  handler..** Cons
1bdd0 69 64 65 72 20 61 20 73 63 65 6e 61 72 69 6f 20  ider a scenario 
1bde0 77 68 65 72 65 20 6f 6e 65 20 70 72 6f 63 65 73  where one proces
1bdf0 73 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 72  s is holding a r
1be00 65 61 64 20 6c 6f 63 6b 20 74 68 61 74 0a 2a 2a  ead lock that.**
1be10 20 69 74 20 69 73 20 74 72 79 69 6e 67 20 74 6f   it is trying to
1be20 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61 20 72 65   promote to a re
1be30 73 65 72 76 65 64 20 6c 6f 63 6b 20 61 6e 64 0a  served lock and.
1be40 2a 2a 20 61 20 73 65 63 6f 6e 64 20 70 72 6f 63  ** a second proc
1be50 65 73 73 20 69 73 20 68 6f 6c 64 69 6e 67 20 61  ess is holding a
1be60 20 72 65 73 65 72 76 65 64 20 6c 6f 63 6b 20 74   reserved lock t
1be70 68 61 74 20 69 74 20 69 73 20 74 72 79 69 6e 67  hat it is trying
1be80 0a 2a 2a 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74  .** to promote t
1be90 6f 20 61 6e 20 65 78 63 6c 75 73 69 76 65 20 6c  o an exclusive l
1bea0 6f 63 6b 2e 20 20 54 68 65 20 66 69 72 73 74 20  ock.  The first 
1beb0 70 72 6f 63 65 73 73 20 63 61 6e 6e 6f 74 20 70  process cannot p
1bec0 72 6f 63 65 65 64 0a 2a 2a 20 62 65 63 61 75 73  roceed.** becaus
1bed0 65 20 69 74 20 69 73 20 62 6c 6f 63 6b 65 64 20  e it is blocked 
1bee0 62 79 20 74 68 65 20 73 65 63 6f 6e 64 20 61 6e  by the second an
1bef0 64 20 74 68 65 20 73 65 63 6f 6e 64 20 70 72 6f  d the second pro
1bf00 63 65 73 73 20 63 61 6e 6e 6f 74 0a 2a 2a 20 70  cess cannot.** p
1bf10 72 6f 63 65 65 64 20 62 65 63 61 75 73 65 20 69  roceed because i
1bf20 74 20 69 73 20 62 6c 6f 63 6b 65 64 20 62 79 20  t is blocked by 
1bf30 74 68 65 20 66 69 72 73 74 2e 20 20 49 66 20 62  the first.  If b
1bf40 6f 74 68 20 70 72 6f 63 65 73 73 65 73 0a 2a 2a  oth processes.**
1bf50 20 69 6e 76 6f 6b 65 20 74 68 65 20 62 75 73 79   invoke the busy
1bf60 20 68 61 6e 64 6c 65 72 73 2c 20 6e 65 69 74 68   handlers, neith
1bf70 65 72 20 77 69 6c 6c 20 6d 61 6b 65 20 61 6e 79  er will make any
1bf80 20 70 72 6f 67 72 65 73 73 2e 20 20 54 68 65 72   progress.  Ther
1bf90 65 66 6f 72 65 2c 0a 2a 2a 20 53 51 4c 69 74 65  efore,.** SQLite
1bfa0 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
1bfb0 5f 42 55 53 59 5d 20 66 6f 72 20 74 68 65 20 66  _BUSY] for the f
1bfc0 69 72 73 74 20 70 72 6f 63 65 73 73 2c 20 68 6f  irst process, ho
1bfd0 70 69 6e 67 20 74 68 61 74 20 74 68 69 73 0a 2a  ping that this.*
1bfe0 2a 20 77 69 6c 6c 20 69 6e 64 75 63 65 20 74 68  * will induce th
1bff0 65 20 66 69 72 73 74 20 70 72 6f 63 65 73 73 20  e first process 
1c000 74 6f 20 72 65 6c 65 61 73 65 20 69 74 73 20 72  to release its r
1c010 65 61 64 20 6c 6f 63 6b 20 61 6e 64 20 61 6c 6c  ead lock and all
1c020 6f 77 0a 2a 2a 20 74 68 65 20 73 65 63 6f 6e 64  ow.** the second
1c030 20 70 72 6f 63 65 73 73 20 74 6f 20 70 72 6f 63   process to proc
1c040 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  eed..**.** ^The 
1c050 64 65 66 61 75 6c 74 20 62 75 73 79 20 63 61 6c  default busy cal
1c060 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c 2e 0a 2a  lback is NULL..*
1c070 2a 0a 2a 2a 20 5e 28 54 68 65 72 65 20 63 61 6e  *.** ^(There can
1c080 20 6f 6e 6c 79 20 62 65 20 61 20 73 69 6e 67 6c   only be a singl
1c090 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 64  e busy handler d
1c0a0 65 66 69 6e 65 64 20 66 6f 72 20 65 61 63 68 0a  efined for each.
1c0b0 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ** [database con
1c0c0 6e 65 63 74 69 6f 6e 5d 2e 20 20 53 65 74 74 69  nection].  Setti
1c0d0 6e 67 20 61 20 6e 65 77 20 62 75 73 79 20 68 61  ng a new busy ha
1c0e0 6e 64 6c 65 72 20 63 6c 65 61 72 73 20 61 6e 79  ndler clears any
1c0f0 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 73  .** previously s
1c100 65 74 20 68 61 6e 64 6c 65 72 2e 29 5e 20 20 5e  et handler.)^  ^
1c110 4e 6f 74 65 20 74 68 61 74 20 63 61 6c 6c 69 6e  Note that callin
1c120 67 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f  g [sqlite3_busy_
1c130 74 69 6d 65 6f 75 74 28 29 5d 0a 2a 2a 20 6f 72  timeout()].** or
1c140 20 65 76 61 6c 75 61 74 69 6e 67 20 5b 50 52 41   evaluating [PRA
1c150 47 4d 41 20 62 75 73 79 5f 74 69 6d 65 6f 75 74  GMA busy_timeout
1c160 3d 4e 5d 20 77 69 6c 6c 20 63 68 61 6e 67 65 20  =N] will change 
1c170 74 68 65 0a 2a 2a 20 62 75 73 79 20 68 61 6e 64  the.** busy hand
1c180 6c 65 72 20 61 6e 64 20 74 68 75 73 20 63 6c 65  ler and thus cle
1c190 61 72 20 61 6e 79 20 70 72 65 76 69 6f 75 73 6c  ar any previousl
1c1a0 79 20 73 65 74 20 62 75 73 79 20 68 61 6e 64 6c  y set busy handl
1c1b0 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 62 75  er..**.** The bu
1c1c0 73 79 20 63 61 6c 6c 62 61 63 6b 20 73 68 6f 75  sy callback shou
1c1d0 6c 64 20 6e 6f 74 20 74 61 6b 65 20 61 6e 79 20  ld not take any 
1c1e0 61 63 74 69 6f 6e 73 20 77 68 69 63 68 20 6d 6f  actions which mo
1c1f0 64 69 66 79 20 74 68 65 0a 2a 2a 20 64 61 74 61  dify the.** data
1c200 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
1c210 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65  that invoked the
1c220 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 20 20   busy handler.  
1c230 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 0a  In other words,.
1c240 2a 2a 20 74 68 65 20 62 75 73 79 20 68 61 6e 64  ** the busy hand
1c250 6c 65 72 20 69 73 20 6e 6f 74 20 72 65 65 6e 74  ler is not reent
1c260 72 61 6e 74 2e 20 20 41 6e 79 20 73 75 63 68 20  rant.  Any such 
1c270 61 63 74 69 6f 6e 73 0a 2a 2a 20 72 65 73 75 6c  actions.** resul
1c280 74 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 62  t in undefined b
1c290 65 68 61 76 69 6f 72 2e 0a 2a 2a 20 0a 2a 2a 20  ehavior..** .** 
1c2a0 41 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 6d  A busy handler m
1c2b0 75 73 74 20 6e 6f 74 20 63 6c 6f 73 65 20 74 68  ust not close th
1c2c0 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
1c2d0 63 74 69 6f 6e 0a 2a 2a 20 6f 72 20 5b 70 72 65  ction.** or [pre
1c2e0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
1c2f0 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68   that invoked th
1c300 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a  e busy handler..
1c310 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  */.SQLITE_API in
1c320 74 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68  t sqlite3_busy_h
1c330 61 6e 64 6c 65 72 28 73 71 6c 69 74 65 33 2a 2c  andler(sqlite3*,
1c340 69 6e 74 28 2a 29 28 76 6f 69 64 2a 2c 69 6e 74  int(*)(void*,int
1c350 29 2c 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  ),void*);../*.**
1c360 20 43 41 50 49 33 52 45 46 3a 20 53 65 74 20 41   CAPI3REF: Set A
1c370 20 42 75 73 79 20 54 69 6d 65 6f 75 74 0a 2a 2a   Busy Timeout.**
1c380 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
1c390 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75  .**.** ^This rou
1c3a0 74 69 6e 65 20 73 65 74 73 20 61 20 5b 73 71 6c  tine sets a [sql
1c3b0 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65  ite3_busy_handle
1c3c0 72 20 7c 20 62 75 73 79 20 68 61 6e 64 6c 65 72  r | busy handler
1c3d0 5d 20 74 68 61 74 20 73 6c 65 65 70 73 0a 2a 2a  ] that sleeps.**
1c3e0 20 66 6f 72 20 61 20 73 70 65 63 69 66 69 65 64   for a specified
1c3f0 20 61 6d 6f 75 6e 74 20 6f 66 20 74 69 6d 65 20   amount of time 
1c400 77 68 65 6e 20 61 20 74 61 62 6c 65 20 69 73 20  when a table is 
1c410 6c 6f 63 6b 65 64 2e 20 20 5e 54 68 65 20 68 61  locked.  ^The ha
1c420 6e 64 6c 65 72 0a 2a 2a 20 77 69 6c 6c 20 73 6c  ndler.** will sl
1c430 65 65 70 20 6d 75 6c 74 69 70 6c 65 20 74 69 6d  eep multiple tim
1c440 65 73 20 75 6e 74 69 6c 20 61 74 20 6c 65 61 73  es until at leas
1c450 74 20 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63 6f  t "ms" milliseco
1c460 6e 64 73 20 6f 66 20 73 6c 65 65 70 69 6e 67 0a  nds of sleeping.
1c470 2a 2a 20 68 61 76 65 20 61 63 63 75 6d 75 6c 61  ** have accumula
1c480 74 65 64 2e 20 20 5e 41 66 74 65 72 20 61 74 20  ted.  ^After at 
1c490 6c 65 61 73 74 20 22 6d 73 22 20 6d 69 6c 6c 69  least "ms" milli
1c4a0 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70  seconds of sleep
1c4b0 69 6e 67 2c 0a 2a 2a 20 74 68 65 20 68 61 6e 64  ing,.** the hand
1c4c0 6c 65 72 20 72 65 74 75 72 6e 73 20 30 20 77 68  ler returns 0 wh
1c4d0 69 63 68 20 63 61 75 73 65 73 20 5b 73 71 6c 69  ich causes [sqli
1c4e0 74 65 33 5f 73 74 65 70 28 29 5d 20 74 6f 20 72  te3_step()] to r
1c4f0 65 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45  eturn.** [SQLITE
1c500 5f 42 55 53 59 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 43  _BUSY]..**.** ^C
1c510 61 6c 6c 69 6e 67 20 74 68 69 73 20 72 6f 75 74  alling this rout
1c520 69 6e 65 20 77 69 74 68 20 61 6e 20 61 72 67 75  ine with an argu
1c530 6d 65 6e 74 20 6c 65 73 73 20 74 68 61 6e 20 6f  ment less than o
1c540 72 20 65 71 75 61 6c 20 74 6f 20 7a 65 72 6f 0a  r equal to zero.
1c550 2a 2a 20 74 75 72 6e 73 20 6f 66 66 20 61 6c 6c  ** turns off all
1c560 20 62 75 73 79 20 68 61 6e 64 6c 65 72 73 2e 0a   busy handlers..
1c570 2a 2a 0a 2a 2a 20 5e 28 54 68 65 72 65 20 63 61  **.** ^(There ca
1c580 6e 20 6f 6e 6c 79 20 62 65 20 61 20 73 69 6e 67  n only be a sing
1c590 6c 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20  le busy handler 
1c5a0 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61 72  for a particular
1c5b0 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f  .** [database co
1c5c0 6e 6e 65 63 74 69 6f 6e 5d 20 61 74 20 61 6e 79  nnection] at any
1c5d0 20 67 69 76 65 6e 20 6d 6f 6d 65 6e 74 2e 20 20   given moment.  
1c5e0 49 66 20 61 6e 6f 74 68 65 72 20 62 75 73 79 20  If another busy 
1c5f0 68 61 6e 64 6c 65 72 0a 2a 2a 20 77 61 73 20 64  handler.** was d
1c600 65 66 69 6e 65 64 20 20 28 75 73 69 6e 67 20 5b  efined  (using [
1c610 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e  sqlite3_busy_han
1c620 64 6c 65 72 28 29 5d 29 20 70 72 69 6f 72 20 74  dler()]) prior t
1c630 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 74 68 69  o calling.** thi
1c640 73 20 72 6f 75 74 69 6e 65 2c 20 74 68 61 74 20  s routine, that 
1c650 6f 74 68 65 72 20 62 75 73 79 20 68 61 6e 64 6c  other busy handl
1c660 65 72 20 69 73 20 63 6c 65 61 72 65 64 2e 29 5e  er is cleared.)^
1c670 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a  .**.** See also:
1c680 20 20 5b 50 52 41 47 4d 41 20 62 75 73 79 5f 74    [PRAGMA busy_t
1c690 69 6d 65 6f 75 74 5d 0a 2a 2f 0a 53 51 4c 49 54  imeout].*/.SQLIT
1c6a0 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
1c6b0 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 73  3_busy_timeout(s
1c6c0 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6d 73 29  qlite3*, int ms)
1c6d0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
1c6e0 46 3a 20 43 6f 6e 76 65 6e 69 65 6e 63 65 20 52  F: Convenience R
1c6f0 6f 75 74 69 6e 65 73 20 46 6f 72 20 52 75 6e 6e  outines For Runn
1c700 69 6e 67 20 51 75 65 72 69 65 73 0a 2a 2a 20 4d  ing Queries.** M
1c710 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a  ETHOD: sqlite3.*
1c720 2a 0a 2a 2a 20 54 68 69 73 20 69 73 20 61 20 6c  *.** This is a l
1c730 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 20  egacy interface 
1c740 74 68 61 74 20 69 73 20 70 72 65 73 65 72 76 65  that is preserve
1c750 64 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73 20  d for backwards 
1c760 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a  compatibility..*
1c770 2a 20 55 73 65 20 6f 66 20 74 68 69 73 20 69 6e  * Use of this in
1c780 74 65 72 66 61 63 65 20 69 73 20 6e 6f 74 20 72  terface is not r
1c790 65 63 6f 6d 6d 65 6e 64 65 64 2e 0a 2a 2a 0a 2a  ecommended..**.*
1c7a0 2a 20 44 65 66 69 6e 69 74 69 6f 6e 3a 20 41 20  * Definition: A 
1c7b0 3c 62 3e 72 65 73 75 6c 74 20 74 61 62 6c 65 3c  <b>result table<
1c7c0 2f 62 3e 20 69 73 20 6d 65 6d 6f 72 79 20 64 61  /b> is memory da
1c7d0 74 61 20 73 74 72 75 63 74 75 72 65 20 63 72 65  ta structure cre
1c7e0 61 74 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 5b  ated by the.** [
1c7f0 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c  sqlite3_get_tabl
1c800 65 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 20  e()] interface. 
1c810 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20   A result table 
1c820 72 65 63 6f 72 64 73 20 74 68 65 0a 2a 2a 20 63  records the.** c
1c830 6f 6d 70 6c 65 74 65 20 71 75 65 72 79 20 72 65  omplete query re
1c840 73 75 6c 74 73 20 66 72 6f 6d 20 6f 6e 65 20 6f  sults from one o
1c850 72 20 6d 6f 72 65 20 71 75 65 72 69 65 73 2e 0a  r more queries..
1c860 2a 2a 0a 2a 2a 20 54 68 65 20 74 61 62 6c 65 20  **.** The table 
1c870 63 6f 6e 63 65 70 74 75 61 6c 6c 79 20 68 61 73  conceptually has
1c880 20 61 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77   a number of row
1c890 73 20 61 6e 64 20 63 6f 6c 75 6d 6e 73 2e 20 20  s and columns.  
1c8a0 42 75 74 0a 2a 2a 20 74 68 65 73 65 20 6e 75 6d  But.** these num
1c8b0 62 65 72 73 20 61 72 65 20 6e 6f 74 20 70 61 72  bers are not par
1c8c0 74 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20  t of the result 
1c8d0 74 61 62 6c 65 20 69 74 73 65 6c 66 2e 20 20 54  table itself.  T
1c8e0 68 65 73 65 0a 2a 2a 20 6e 75 6d 62 65 72 73 20  hese.** numbers 
1c8f0 61 72 65 20 6f 62 74 61 69 6e 65 64 20 73 65 70  are obtained sep
1c900 61 72 61 74 65 6c 79 2e 20 20 4c 65 74 20 4e 20  arately.  Let N 
1c910 62 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  be the number of
1c920 20 72 6f 77 73 0a 2a 2a 20 61 6e 64 20 4d 20 62   rows.** and M b
1c930 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  e the number of 
1c940 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 0a 2a 2a 20 41  columns..**.** A
1c950 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69 73   result table is
1c960 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69   an array of poi
1c970 6e 74 65 72 73 20 74 6f 20 7a 65 72 6f 2d 74 65  nters to zero-te
1c980 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73  rminated UTF-8 s
1c990 74 72 69 6e 67 73 2e 0a 2a 2a 20 54 68 65 72 65  trings..** There
1c9a0 20 61 72 65 20 28 4e 2b 31 29 2a 4d 20 65 6c 65   are (N+1)*M ele
1c9b0 6d 65 6e 74 73 20 69 6e 20 74 68 65 20 61 72 72  ments in the arr
1c9c0 61 79 2e 20 20 54 68 65 20 66 69 72 73 74 20 4d  ay.  The first M
1c9d0 20 70 6f 69 6e 74 65 72 73 20 70 6f 69 6e 74 0a   pointers point.
1c9e0 2a 2a 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69  ** to zero-termi
1c9f0 6e 61 74 65 64 20 73 74 72 69 6e 67 73 20 74 68  nated strings th
1ca00 61 74 20 20 63 6f 6e 74 61 69 6e 20 74 68 65 20  at  contain the 
1ca10 6e 61 6d 65 73 20 6f 66 20 74 68 65 20 63 6f 6c  names of the col
1ca20 75 6d 6e 73 2e 0a 2a 2a 20 54 68 65 20 72 65 6d  umns..** The rem
1ca30 61 69 6e 69 6e 67 20 65 6e 74 72 69 65 73 20 61  aining entries a
1ca40 6c 6c 20 70 6f 69 6e 74 20 74 6f 20 71 75 65 72  ll point to quer
1ca50 79 20 72 65 73 75 6c 74 73 2e 20 20 4e 55 4c 4c  y results.  NULL
1ca60 20 76 61 6c 75 65 73 20 72 65 73 75 6c 74 0a 2a   values result.*
1ca70 2a 20 69 6e 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  * in NULL pointe
1ca80 72 73 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20 76  rs.  All other v
1ca90 61 6c 75 65 73 20 61 72 65 20 69 6e 20 74 68 65  alues are in the
1caa0 69 72 20 55 54 46 2d 38 20 7a 65 72 6f 2d 74 65  ir UTF-8 zero-te
1cab0 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74 72 69  rminated.** stri
1cac0 6e 67 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f  ng representatio
1cad0 6e 20 61 73 20 72 65 74 75 72 6e 65 64 20 62 79  n as returned by
1cae0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
1caf0 5f 74 65 78 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  _text()]..**.** 
1cb00 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 6d  A result table m
1cb10 69 67 68 74 20 63 6f 6e 73 69 73 74 20 6f 66 20  ight consist of 
1cb20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6d 65 6d 6f  one or more memo
1cb30 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 2e 0a  ry allocations..
1cb40 2a 2a 20 49 74 20 69 73 20 6e 6f 74 20 73 61 66  ** It is not saf
1cb50 65 20 74 6f 20 70 61 73 73 20 61 20 72 65 73 75  e to pass a resu
1cb60 6c 74 20 74 61 62 6c 65 20 64 69 72 65 63 74 6c  lt table directl
1cb70 79 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72  y to [sqlite3_fr
1cb80 65 65 28 29 5d 2e 0a 2a 2a 20 41 20 72 65 73 75  ee()]..** A resu
1cb90 6c 74 20 74 61 62 6c 65 20 73 68 6f 75 6c 64 20  lt table should 
1cba0 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 75  be deallocated u
1cbb0 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 72  sing [sqlite3_fr
1cbc0 65 65 5f 74 61 62 6c 65 28 29 5d 2e 0a 2a 2a 0a  ee_table()]..**.
1cbd0 2a 2a 20 5e 28 41 73 20 61 6e 20 65 78 61 6d 70  ** ^(As an examp
1cbe0 6c 65 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  le of the result
1cbf0 20 74 61 62 6c 65 20 66 6f 72 6d 61 74 2c 20 73   table format, s
1cc00 75 70 70 6f 73 65 20 61 20 71 75 65 72 79 20 72  uppose a query r
1cc10 65 73 75 6c 74 0a 2a 2a 20 69 73 20 61 73 20 66  esult.** is as f
1cc20 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62  ollows:.**.** <b
1cc30 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a  lockquote><pre>.
1cc40 2a 2a 20 20 20 20 20 20 20 20 4e 61 6d 65 20 20  **        Name  
1cc50 20 20 20 20 20 20 7c 20 41 67 65 0a 2a 2a 20 20        | Age.**  
1cc60 20 20 20 20 20 20 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d        ----------
1cc70 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 0a 2a 2a  -------------.**
1cc80 20 20 20 20 20 20 20 20 41 6c 69 63 65 20 20 20          Alice   
1cc90 20 20 20 20 7c 20 34 33 0a 2a 2a 20 20 20 20 20      | 43.**     
1cca0 20 20 20 42 6f 62 20 20 20 20 20 20 20 20 20 7c     Bob         |
1ccb0 20 32 38 0a 2a 2a 20 20 20 20 20 20 20 20 43 69   28.**        Ci
1ccc0 6e 64 79 20 20 20 20 20 20 20 7c 20 32 31 0a 2a  ndy       | 21.*
1ccd0 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71  * </pre></blockq
1cce0 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 72  uote>.**.** Ther
1ccf0 65 20 61 72 65 20 74 77 6f 20 63 6f 6c 75 6d 6e  e are two column
1cd00 20 28 4d 3d 3d 32 29 20 61 6e 64 20 74 68 72 65   (M==2) and thre
1cd10 65 20 72 6f 77 73 20 28 4e 3d 3d 33 29 2e 20 20  e rows (N==3).  
1cd20 54 68 75 73 20 74 68 65 0a 2a 2a 20 72 65 73 75  Thus the.** resu
1cd30 6c 74 20 74 61 62 6c 65 20 68 61 73 20 38 20 65  lt table has 8 e
1cd40 6e 74 72 69 65 73 2e 20 20 53 75 70 70 6f 73 65  ntries.  Suppose
1cd50 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c   the result tabl
1cd60 65 20 69 73 20 73 74 6f 72 65 64 0a 2a 2a 20 69  e is stored.** i
1cd70 6e 20 61 6e 20 61 72 72 61 79 20 6e 61 6d 65 73  n an array names
1cd80 20 61 7a 52 65 73 75 6c 74 2e 20 20 54 68 65 6e   azResult.  Then
1cd90 20 61 7a 52 65 73 75 6c 74 20 68 6f 6c 64 73 20   azResult holds 
1cda0 74 68 69 73 20 63 6f 6e 74 65 6e 74 3a 0a 2a 2a  this content:.**
1cdb0 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
1cdc0 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20 20 20  <pre>.**        
1cdd0 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 30 5d 20  azResult&#91;0] 
1cde0 3d 20 22 4e 61 6d 65 22 3b 0a 2a 2a 20 20 20 20  = "Name";.**    
1cdf0 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31      azResult&#91
1ce00 3b 31 5d 20 3d 20 22 41 67 65 22 3b 0a 2a 2a 20  ;1] = "Age";.** 
1ce10 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26         azResult&
1ce20 23 39 31 3b 32 5d 20 3d 20 22 41 6c 69 63 65 22  #91;2] = "Alice"
1ce30 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65  ;.**        azRe
1ce40 73 75 6c 74 26 23 39 31 3b 33 5d 20 3d 20 22 34  sult&#91;3] = "4
1ce50 33 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a  3";.**        az
1ce60 52 65 73 75 6c 74 26 23 39 31 3b 34 5d 20 3d 20  Result&#91;4] = 
1ce70 22 42 6f 62 22 3b 0a 2a 2a 20 20 20 20 20 20 20  "Bob";.**       
1ce80 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 35 5d   azResult&#91;5]
1ce90 20 3d 20 22 32 38 22 3b 0a 2a 2a 20 20 20 20 20   = "28";.**     
1cea0 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b     azResult&#91;
1ceb0 36 5d 20 3d 20 22 43 69 6e 64 79 22 3b 0a 2a 2a  6] = "Cindy";.**
1cec0 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74          azResult
1ced0 26 23 39 31 3b 37 5d 20 3d 20 22 32 31 22 3b 0a  &#91;7] = "21";.
1cee0 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b  ** </pre></block
1cef0 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  quote>)^.**.** ^
1cf00 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f  The sqlite3_get_
1cf10 74 61 62 6c 65 28 29 20 66 75 6e 63 74 69 6f 6e  table() function
1cf20 20 65 76 61 6c 75 61 74 65 73 20 6f 6e 65 20 6f   evaluates one o
1cf30 72 20 6d 6f 72 65 0a 2a 2a 20 73 65 6d 69 63 6f  r more.** semico
1cf40 6c 6f 6e 2d 73 65 70 61 72 61 74 65 64 20 53 51  lon-separated SQ
1cf50 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 69 6e 20  L statements in 
1cf60 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  the zero-termina
1cf70 74 65 64 20 55 54 46 2d 38 0a 2a 2a 20 73 74 72  ted UTF-8.** str
1cf80 69 6e 67 20 6f 66 20 69 74 73 20 32 6e 64 20 70  ing of its 2nd p
1cf90 61 72 61 6d 65 74 65 72 20 61 6e 64 20 72 65 74  arameter and ret
1cfa0 75 72 6e 73 20 61 20 72 65 73 75 6c 74 20 74 61  urns a result ta
1cfb0 62 6c 65 20 74 6f 20 74 68 65 0a 2a 2a 20 70 6f  ble to the.** po
1cfc0 69 6e 74 65 72 20 67 69 76 65 6e 20 69 6e 20 69  inter given in i
1cfd0 74 73 20 33 72 64 20 70 61 72 61 6d 65 74 65 72  ts 3rd parameter
1cfe0 2e 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 74 68  ..**.** After th
1cff0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 68 61  e application ha
1d000 73 20 66 69 6e 69 73 68 65 64 20 77 69 74 68 20  s finished with 
1d010 74 68 65 20 72 65 73 75 6c 74 20 66 72 6f 6d 20  the result from 
1d020 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c  sqlite3_get_tabl
1d030 65 28 29 2c 0a 2a 2a 20 69 74 20 6d 75 73 74 20  e(),.** it must 
1d040 70 61 73 73 20 74 68 65 20 72 65 73 75 6c 74 20  pass the result 
1d050 74 61 62 6c 65 20 70 6f 69 6e 74 65 72 20 74 6f  table pointer to
1d060 20 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61   sqlite3_free_ta
1d070 62 6c 65 28 29 20 69 6e 20 6f 72 64 65 72 20 74  ble() in order t
1d080 6f 0a 2a 2a 20 72 65 6c 65 61 73 65 20 74 68 65  o.** release the
1d090 20 6d 65 6d 6f 72 79 20 74 68 61 74 20 77 61 73   memory that was
1d0a0 20 6d 61 6c 6c 6f 63 65 64 2e 20 20 42 65 63 61   malloced.  Beca
1d0b0 75 73 65 20 6f 66 20 74 68 65 20 77 61 79 20 74  use of the way t
1d0c0 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d  he.** [sqlite3_m
1d0d0 61 6c 6c 6f 63 28 29 5d 20 68 61 70 70 65 6e 73  alloc()] happens
1d0e0 20 77 69 74 68 69 6e 20 73 71 6c 69 74 65 33 5f   within sqlite3_
1d0f0 67 65 74 5f 74 61 62 6c 65 28 29 2c 20 74 68 65  get_table(), the
1d100 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 66 75 6e 63   calling.** func
1d110 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 74 72  tion must not tr
1d120 79 20 74 6f 20 63 61 6c 6c 20 5b 73 71 6c 69 74  y to call [sqlit
1d130 65 33 5f 66 72 65 65 28 29 5d 20 64 69 72 65 63  e3_free()] direc
1d140 74 6c 79 2e 20 20 4f 6e 6c 79 0a 2a 2a 20 5b 73  tly.  Only.** [s
1d150 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c  qlite3_free_tabl
1d160 65 28 29 5d 20 69 73 20 61 62 6c 65 20 74 6f 20  e()] is able to 
1d170 72 65 6c 65 61 73 65 20 74 68 65 20 6d 65 6d 6f  release the memo
1d180 72 79 20 70 72 6f 70 65 72 6c 79 20 61 6e 64 20  ry properly and 
1d190 73 61 66 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 68  safely..**.** Th
1d1a0 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61  e sqlite3_get_ta
1d1b0 62 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65 20  ble() interface 
1d1c0 69 73 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 61  is implemented a
1d1d0 73 20 61 20 77 72 61 70 70 65 72 20 61 72 6f 75  s a wrapper arou
1d1e0 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65  nd.** [sqlite3_e
1d1f0 78 65 63 28 29 5d 2e 20 20 54 68 65 20 73 71 6c  xec()].  The sql
1d200 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29  ite3_get_table()
1d210 20 72 6f 75 74 69 6e 65 20 64 6f 65 73 20 6e 6f   routine does no
1d220 74 20 68 61 76 65 20 61 63 63 65 73 73 0a 2a 2a  t have access.**
1d230 20 74 6f 20 61 6e 79 20 69 6e 74 65 72 6e 61 6c   to any internal
1d240 20 64 61 74 61 20 73 74 72 75 63 74 75 72 65 73   data structures
1d250 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 49 74 20   of SQLite.  It 
1d260 75 73 65 73 20 6f 6e 6c 79 20 74 68 65 20 70 75  uses only the pu
1d270 62 6c 69 63 0a 2a 2a 20 69 6e 74 65 72 66 61 63  blic.** interfac
1d280 65 20 64 65 66 69 6e 65 64 20 68 65 72 65 2e 20  e defined here. 
1d290 20 41 73 20 61 20 63 6f 6e 73 65 71 75 65 6e 63   As a consequenc
1d2a0 65 2c 20 65 72 72 6f 72 73 20 74 68 61 74 20 6f  e, errors that o
1d2b0 63 63 75 72 20 69 6e 20 74 68 65 0a 2a 2a 20 77  ccur in the.** w
1d2c0 72 61 70 70 65 72 20 6c 61 79 65 72 20 6f 75 74  rapper layer out
1d2d0 73 69 64 65 20 6f 66 20 74 68 65 20 69 6e 74 65  side of the inte
1d2e0 72 6e 61 6c 20 5b 73 71 6c 69 74 65 33 5f 65 78  rnal [sqlite3_ex
1d2f0 65 63 28 29 5d 20 63 61 6c 6c 20 61 72 65 20 6e  ec()] call are n
1d300 6f 74 0a 2a 2a 20 72 65 66 6c 65 63 74 65 64 20  ot.** reflected 
1d310 69 6e 20 73 75 62 73 65 71 75 65 6e 74 20 63 61  in subsequent ca
1d320 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  lls to [sqlite3_
1d330 65 72 72 63 6f 64 65 28 29 5d 20 6f 72 0a 2a 2a  errcode()] or.**
1d340 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67   [sqlite3_errmsg
1d350 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  ()]..*/.SQLITE_A
1d360 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 67  PI int sqlite3_g
1d370 65 74 5f 74 61 62 6c 65 28 0a 20 20 73 71 6c 69  et_table(.  sqli
1d380 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20  te3 *db,        
1d390 20 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64 61 74    /* An open dat
1d3a0 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  abase */.  const
1d3b0 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20   char *zSql,    
1d3c0 20 2f 2a 20 53 51 4c 20 74 6f 20 62 65 20 65 76   /* SQL to be ev
1d3d0 61 6c 75 61 74 65 64 20 2a 2f 0a 20 20 63 68 61  aluated */.  cha
1d3e0 72 20 2a 2a 2a 70 61 7a 52 65 73 75 6c 74 2c 20  r ***pazResult, 
1d3f0 20 20 20 2f 2a 20 52 65 73 75 6c 74 73 20 6f 66     /* Results of
1d400 20 74 68 65 20 71 75 65 72 79 20 2a 2f 0a 20 20   the query */.  
1d410 69 6e 74 20 2a 70 6e 52 6f 77 2c 20 20 20 20 20  int *pnRow,     
1d420 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20        /* Number 
1d430 6f 66 20 72 65 73 75 6c 74 20 72 6f 77 73 20 77  of result rows w
1d440 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 20  ritten here */. 
1d450 20 69 6e 74 20 2a 70 6e 43 6f 6c 75 6d 6e 2c 20   int *pnColumn, 
1d460 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72         /* Number
1d470 20 6f 66 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d   of result colum
1d480 6e 73 20 77 72 69 74 74 65 6e 20 68 65 72 65 20  ns written here 
1d490 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 70 7a 45 72  */.  char **pzEr
1d4a0 72 6d 73 67 20 20 20 20 20 20 20 2f 2a 20 45 72  rmsg       /* Er
1d4b0 72 6f 72 20 6d 73 67 20 77 72 69 74 74 65 6e 20  ror msg written 
1d4c0 68 65 72 65 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54  here */.);.SQLIT
1d4d0 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74  E_API void sqlit
1d4e0 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 63 68  e3_free_table(ch
1d4f0 61 72 20 2a 2a 72 65 73 75 6c 74 29 3b 0a 0a 2f  ar **result);../
1d500 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46  *.** CAPI3REF: F
1d510 6f 72 6d 61 74 74 65 64 20 53 74 72 69 6e 67 20  ormatted String 
1d520 50 72 69 6e 74 69 6e 67 20 46 75 6e 63 74 69 6f  Printing Functio
1d530 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  ns.**.** These r
1d540 6f 75 74 69 6e 65 73 20 61 72 65 20 77 6f 72 6b  outines are work
1d550 2d 61 6c 69 6b 65 73 20 6f 66 20 74 68 65 20 22  -alikes of the "
1d560 70 72 69 6e 74 66 28 29 22 20 66 61 6d 69 6c 79  printf()" family
1d570 20 6f 66 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a   of functions.**
1d580 20 66 72 6f 6d 20 74 68 65 20 73 74 61 6e 64 61   from the standa
1d590 72 64 20 43 20 6c 69 62 72 61 72 79 2e 0a 2a 2a  rd C library..**
1d5a0 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
1d5b0 75 6e 64 65 72 73 74 61 6e 64 20 6d 6f 73 74 20  understand most 
1d5c0 6f 66 20 74 68 65 20 63 6f 6d 6d 6f 6e 20 4b 26  of the common K&
1d5d0 52 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74  R formatting opt
1d5e0 69 6f 6e 73 2c 0a 2a 2a 20 70 6c 75 73 20 73 6f  ions,.** plus so
1d5f0 6d 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 6e 6f  me additional no
1d600 6e 2d 73 74 61 6e 64 61 72 64 20 66 6f 72 6d 61  n-standard forma
1d610 74 73 2c 20 64 65 74 61 69 6c 65 64 20 62 65 6c  ts, detailed bel
1d620 6f 77 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74  ow..** Note that
1d630 20 73 6f 6d 65 20 6f 66 20 74 68 65 20 6d 6f 72   some of the mor
1d640 65 20 6f 62 73 63 75 72 65 20 66 6f 72 6d 61 74  e obscure format
1d650 74 69 6e 67 20 6f 70 74 69 6f 6e 73 20 66 72 6f  ting options fro
1d660 6d 20 72 65 63 65 6e 74 0a 2a 2a 20 43 2d 6c 69  m recent.** C-li
1d670 62 72 61 72 79 20 73 74 61 6e 64 61 72 64 73 20  brary standards 
1d680 61 72 65 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d  are omitted from
1d690 20 74 68 69 73 20 69 6d 70 6c 65 6d 65 6e 74 61   this implementa
1d6a0 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  tion..**.** ^The
1d6b0 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66   sqlite3_mprintf
1d6c0 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 76  () and sqlite3_v
1d6d0 6d 70 72 69 6e 74 66 28 29 20 72 6f 75 74 69 6e  mprintf() routin
1d6e0 65 73 20 77 72 69 74 65 20 74 68 65 69 72 0a 2a  es write their.*
1d6f0 2a 20 72 65 73 75 6c 74 73 20 69 6e 74 6f 20 6d  * results into m
1d700 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66  emory obtained f
1d710 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  rom [sqlite3_mal
1d720 6c 6f 63 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73  loc()]..** The s
1d730 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20  trings returned 
1d740 62 79 20 74 68 65 73 65 20 74 77 6f 20 72 6f 75  by these two rou
1d750 74 69 6e 65 73 20 73 68 6f 75 6c 64 20 62 65 0a  tines should be.
1d760 2a 2a 20 72 65 6c 65 61 73 65 64 20 62 79 20 5b  ** released by [
1d770 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e  sqlite3_free()].
1d780 20 20 5e 42 6f 74 68 20 72 6f 75 74 69 6e 65 73    ^Both routines
1d790 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 4e 55 4c   return a.** NUL
1d7a0 4c 20 70 6f 69 6e 74 65 72 20 69 66 20 5b 73 71  L pointer if [sq
1d7b0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20  lite3_malloc()] 
1d7c0 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c  is unable to all
1d7d0 6f 63 61 74 65 20 65 6e 6f 75 67 68 0a 2a 2a 20  ocate enough.** 
1d7e0 6d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74  memory to hold t
1d7f0 68 65 20 72 65 73 75 6c 74 69 6e 67 20 73 74 72  he resulting str
1d800 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65  ing..**.** ^(The
1d810 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74   sqlite3_snprint
1d820 66 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20 73  f() routine is s
1d830 69 6d 69 6c 61 72 20 74 6f 20 22 73 6e 70 72 69  imilar to "snpri
1d840 6e 74 66 28 29 22 20 66 72 6f 6d 0a 2a 2a 20 74  ntf()" from.** t
1d850 68 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69  he standard C li
1d860 62 72 61 72 79 2e 20 20 54 68 65 20 72 65 73 75  brary.  The resu
1d870 6c 74 20 69 73 20 77 72 69 74 74 65 6e 20 69 6e  lt is written in
1d880 74 6f 20 74 68 65 0a 2a 2a 20 62 75 66 66 65 72  to the.** buffer
1d890 20 73 75 70 70 6c 69 65 64 20 61 73 20 74 68 65   supplied as the
1d8a0 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
1d8b0 72 20 77 68 6f 73 65 20 73 69 7a 65 20 69 73 20  r whose size is 
1d8c0 67 69 76 65 6e 20 62 79 0a 2a 2a 20 74 68 65 20  given by.** the 
1d8d0 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 2e  first parameter.
1d8e0 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 6f   Note that the o
1d8f0 72 64 65 72 20 6f 66 20 74 68 65 0a 2a 2a 20 66  rder of the.** f
1d900 69 72 73 74 20 74 77 6f 20 70 61 72 61 6d 65 74  irst two paramet
1d910 65 72 73 20 69 73 20 72 65 76 65 72 73 65 64 20  ers is reversed 
1d920 66 72 6f 6d 20 73 6e 70 72 69 6e 74 66 28 29 2e  from snprintf().
1d930 29 5e 20 20 54 68 69 73 20 69 73 20 61 6e 0a 2a  )^  This is an.*
1d940 2a 20 68 69 73 74 6f 72 69 63 61 6c 20 61 63 63  * historical acc
1d950 69 64 65 6e 74 20 74 68 61 74 20 63 61 6e 6e 6f  ident that canno
1d960 74 20 62 65 20 66 69 78 65 64 20 77 69 74 68 6f  t be fixed witho
1d970 75 74 20 62 72 65 61 6b 69 6e 67 0a 2a 2a 20 62  ut breaking.** b
1d980 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69  ackwards compati
1d990 62 69 6c 69 74 79 2e 20 20 5e 28 4e 6f 74 65 20  bility.  ^(Note 
1d9a0 61 6c 73 6f 20 74 68 61 74 20 73 71 6c 69 74 65  also that sqlite
1d9b0 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20  3_snprintf().** 
1d9c0 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65  returns a pointe
1d9d0 72 20 74 6f 20 69 74 73 20 62 75 66 66 65 72 20  r to its buffer 
1d9e0 69 6e 73 74 65 61 64 20 6f 66 20 74 68 65 20 6e  instead of the n
1d9f0 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 63 68 61 72  umber of.** char
1da00 61 63 74 65 72 73 20 61 63 74 75 61 6c 6c 79 20  acters actually 
1da10 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 74 68 65  written into the
1da20 20 62 75 66 66 65 72 2e 29 5e 20 20 57 65 20 61   buffer.)^  We a
1da30 64 6d 69 74 20 74 68 61 74 0a 2a 2a 20 74 68 65  dmit that.** the
1da40 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61   number of chara
1da50 63 74 65 72 73 20 77 72 69 74 74 65 6e 20 77 6f  cters written wo
1da60 75 6c 64 20 62 65 20 61 20 6d 6f 72 65 20 75 73  uld be a more us
1da70 65 66 75 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 76  eful return.** v
1da80 61 6c 75 65 20 62 75 74 20 77 65 20 63 61 6e 6e  alue but we cann
1da90 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20 69 6d  ot change the im
1daa0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
1dab0 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66  sqlite3_snprintf
1dac0 28 29 0a 2a 2a 20 6e 6f 77 20 77 69 74 68 6f 75  ().** now withou
1dad0 74 20 62 72 65 61 6b 69 6e 67 20 63 6f 6d 70 61  t breaking compa
1dae0 74 69 62 69 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a 20  tibility..**.** 
1daf0 5e 41 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20  ^As long as the 
1db00 62 75 66 66 65 72 20 73 69 7a 65 20 69 73 20 67  buffer size is g
1db10 72 65 61 74 65 72 20 74 68 61 6e 20 7a 65 72 6f  reater than zero
1db20 2c 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e  , sqlite3_snprin
1db30 74 66 28 29 0a 2a 2a 20 67 75 61 72 61 6e 74 65  tf().** guarante
1db40 65 73 20 74 68 61 74 20 74 68 65 20 62 75 66 66  es that the buff
1db50 65 72 20 69 73 20 61 6c 77 61 79 73 20 7a 65 72  er is always zer
1db60 6f 2d 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 5e  o-terminated.  ^
1db70 54 68 65 20 66 69 72 73 74 0a 2a 2a 20 70 61 72  The first.** par
1db80 61 6d 65 74 65 72 20 22 6e 22 20 69 73 20 74 68  ameter "n" is th
1db90 65 20 74 6f 74 61 6c 20 73 69 7a 65 20 6f 66 20  e total size of 
1dba0 74 68 65 20 62 75 66 66 65 72 2c 20 69 6e 63 6c  the buffer, incl
1dbb0 75 64 69 6e 67 20 73 70 61 63 65 20 66 6f 72 0a  uding space for.
1dbc0 2a 2a 20 74 68 65 20 7a 65 72 6f 20 74 65 72 6d  ** the zero term
1dbd0 69 6e 61 74 6f 72 2e 20 20 53 6f 20 74 68 65 20  inator.  So the 
1dbe0 6c 6f 6e 67 65 73 74 20 73 74 72 69 6e 67 20 74  longest string t
1dbf0 68 61 74 20 63 61 6e 20 62 65 20 63 6f 6d 70 6c  hat can be compl
1dc00 65 74 65 6c 79 0a 2a 2a 20 77 72 69 74 74 65 6e  etely.** written
1dc10 20 77 69 6c 6c 20 62 65 20 6e 2d 31 20 63 68 61   will be n-1 cha
1dc20 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e  racters..**.** ^
1dc30 54 68 65 20 73 71 6c 69 74 65 33 5f 76 73 6e 70  The sqlite3_vsnp
1dc40 72 69 6e 74 66 28 29 20 72 6f 75 74 69 6e 65 20  rintf() routine 
1dc50 69 73 20 61 20 76 61 72 61 72 67 73 20 76 65 72  is a varargs ver
1dc60 73 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f  sion of sqlite3_
1dc70 73 6e 70 72 69 6e 74 66 28 29 2e 0a 2a 2a 0a 2a  snprintf()..**.*
1dc80 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
1dc90 20 61 6c 6c 20 69 6d 70 6c 65 6d 65 6e 74 20 73   all implement s
1dca0 6f 6d 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 66  ome additional f
1dcb0 6f 72 6d 61 74 74 69 6e 67 0a 2a 2a 20 6f 70 74  ormatting.** opt
1dcc0 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20 75 73  ions that are us
1dcd0 65 66 75 6c 20 66 6f 72 20 63 6f 6e 73 74 72 75  eful for constru
1dce0 63 74 69 6e 67 20 53 51 4c 20 73 74 61 74 65 6d  cting SQL statem
1dcf0 65 6e 74 73 2e 0a 2a 2a 20 41 6c 6c 20 6f 66 20  ents..** All of 
1dd00 74 68 65 20 75 73 75 61 6c 20 70 72 69 6e 74 66  the usual printf
1dd10 28 29 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70  () formatting op
1dd20 74 69 6f 6e 73 20 61 70 70 6c 79 2e 20 20 49 6e  tions apply.  In
1dd30 20 61 64 64 69 74 69 6f 6e 2c 20 74 68 65 72 65   addition, there
1dd40 0a 2a 2a 20 69 73 20 61 72 65 20 22 25 71 22 2c  .** is are "%q",
1dd50 20 22 25 51 22 2c 20 22 25 77 22 20 61 6e 64 20   "%Q", "%w" and 
1dd60 22 25 7a 22 20 6f 70 74 69 6f 6e 73 2e 0a 2a 2a  "%z" options..**
1dd70 0a 2a 2a 20 5e 28 54 68 65 20 25 71 20 6f 70 74  .** ^(The %q opt
1dd80 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20 25  ion works like %
1dd90 73 20 69 6e 20 74 68 61 74 20 69 74 20 73 75 62  s in that it sub
1dda0 73 74 69 74 75 74 65 73 20 61 20 6e 75 6c 2d 74  stitutes a nul-t
1ddb0 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74 72  erminated.** str
1ddc0 69 6e 67 20 66 72 6f 6d 20 74 68 65 20 61 72 67  ing from the arg
1ddd0 75 6d 65 6e 74 20 6c 69 73 74 2e 20 20 42 75 74  ument list.  But
1dde0 20 25 71 20 61 6c 73 6f 20 64 6f 75 62 6c 65 73   %q also doubles
1ddf0 20 65 76 65 72 79 20 27 5c 27 27 20 63 68 61 72   every '\'' char
1de00 61 63 74 65 72 2e 0a 2a 2a 20 25 71 20 69 73 20  acter..** %q is 
1de10 64 65 73 69 67 6e 65 64 20 66 6f 72 20 75 73 65  designed for use
1de20 20 69 6e 73 69 64 65 20 61 20 73 74 72 69 6e 67   inside a string
1de30 20 6c 69 74 65 72 61 6c 2e 29 5e 20 20 42 79 20   literal.)^  By 
1de40 64 6f 75 62 6c 69 6e 67 20 65 61 63 68 20 27 5c  doubling each '\
1de50 27 27 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 20  ''.** character 
1de60 69 74 20 65 73 63 61 70 65 73 20 74 68 61 74 20  it escapes that 
1de70 63 68 61 72 61 63 74 65 72 20 61 6e 64 20 61 6c  character and al
1de80 6c 6f 77 73 20 69 74 20 74 6f 20 62 65 20 69 6e  lows it to be in
1de90 73 65 72 74 65 64 20 69 6e 74 6f 0a 2a 2a 20 74  serted into.** t
1dea0 68 65 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a  he string..**.**
1deb0 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 61 73   For example, as
1dec0 73 75 6d 65 20 74 68 65 20 73 74 72 69 6e 67 20  sume the string 
1ded0 76 61 72 69 61 62 6c 65 20 7a 54 65 78 74 20 63  variable zText c
1dee0 6f 6e 74 61 69 6e 73 20 74 65 78 74 20 61 73 20  ontains text as 
1def0 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c  follows:.**.** <
1df00 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e  blockquote><pre>
1df10 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 54 65 78 74  .**  char *zText
1df20 20 3d 20 22 49 74 27 73 20 61 20 68 61 70 70 79   = "It's a happy
1df30 20 64 61 79 21 22 3b 0a 2a 2a 20 3c 2f 70 72 65   day!";.** </pre
1df40 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a  ></blockquote>.*
1df50 2a 0a 2a 2a 20 4f 6e 65 20 63 61 6e 20 75 73 65  *.** One can use
1df60 20 74 68 69 73 20 74 65 78 74 20 69 6e 20 61 6e   this text in an
1df70 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 61   SQL statement a
1df80 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a  s follows:.**.**
1df90 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72   <blockquote><pr
1dfa0 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 53 51  e>.**  char *zSQ
1dfb0 4c 20 3d 20 73 71 6c 69 74 65 33 5f 6d 70 72 69  L = sqlite3_mpri
1dfc0 6e 74 66 28 22 49 4e 53 45 52 54 20 49 4e 54 4f  ntf("INSERT INTO
1dfd0 20 74 61 62 6c 65 20 56 41 4c 55 45 53 28 27 25   table VALUES('%
1dfe0 71 27 29 22 2c 20 7a 54 65 78 74 29 3b 0a 2a 2a  q')", zText);.**
1dff0 20 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 64    sqlite3_exec(d
1e000 62 2c 20 7a 53 51 4c 2c 20 30 2c 20 30 2c 20 30  b, zSQL, 0, 0, 0
1e010 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 66  );.**  sqlite3_f
1e020 72 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c 2f  ree(zSQL);.** </
1e030 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  pre></blockquote
1e040 3e 0a 2a 2a 0a 2a 2a 20 42 65 63 61 75 73 65 20  >.**.** Because 
1e050 74 68 65 20 25 71 20 66 6f 72 6d 61 74 20 73 74  the %q format st
1e060 72 69 6e 67 20 69 73 20 75 73 65 64 2c 20 74 68  ring is used, th
1e070 65 20 27 5c 27 27 20 63 68 61 72 61 63 74 65 72  e '\'' character
1e080 20 69 6e 20 7a 54 65 78 74 0a 2a 2a 20 69 73 20   in zText.** is 
1e090 65 73 63 61 70 65 64 20 61 6e 64 20 74 68 65 20  escaped and the 
1e0a0 53 51 4c 20 67 65 6e 65 72 61 74 65 64 20 69 73  SQL generated is
1e0b0 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a   as follows:.**.
1e0c0 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c  ** <blockquote><
1e0d0 70 72 65 3e 0a 2a 2a 20 20 49 4e 53 45 52 54 20  pre>.**  INSERT 
1e0e0 49 4e 54 4f 20 74 61 62 6c 65 31 20 56 41 4c 55  INTO table1 VALU
1e0f0 45 53 28 27 49 74 27 27 73 20 61 20 68 61 70 70  ES('It''s a happ
1e100 79 20 64 61 79 21 27 29 0a 2a 2a 20 3c 2f 70 72  y day!').** </pr
1e110 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a  e></blockquote>.
1e120 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 73 20 63 6f  **.** This is co
1e130 72 72 65 63 74 2e 20 20 48 61 64 20 77 65 20 75  rrect.  Had we u
1e140 73 65 64 20 25 73 20 69 6e 73 74 65 61 64 20 6f  sed %s instead o
1e150 66 20 25 71 2c 20 74 68 65 20 67 65 6e 65 72 61  f %q, the genera
1e160 74 65 64 20 53 51 4c 0a 2a 2a 20 77 6f 75 6c 64  ted SQL.** would
1e170 20 68 61 76 65 20 6c 6f 6f 6b 65 64 20 6c 69 6b   have looked lik
1e180 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62  e this:.**.** <b
1e190 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a  lockquote><pre>.
1e1a0 2a 2a 20 20 49 4e 53 45 52 54 20 49 4e 54 4f 20  **  INSERT INTO 
1e1b0 74 61 62 6c 65 31 20 56 41 4c 55 45 53 28 27 49  table1 VALUES('I
1e1c0 74 27 73 20 61 20 68 61 70 70 79 20 64 61 79 21  t's a happy day!
1e1d0 27 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62  ');.** </pre></b
1e1e0 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a  lockquote>.**.**
1e1f0 20 54 68 69 73 20 73 65 63 6f 6e 64 20 65 78 61   This second exa
1e200 6d 70 6c 65 20 69 73 20 61 6e 20 53 51 4c 20 73  mple is an SQL s
1e210 79 6e 74 61 78 20 65 72 72 6f 72 2e 20 20 41 73  yntax error.  As
1e220 20 61 20 67 65 6e 65 72 61 6c 20 72 75 6c 65 20   a general rule 
1e230 79 6f 75 20 73 68 6f 75 6c 64 0a 2a 2a 20 61 6c  you should.** al
1e240 77 61 79 73 20 75 73 65 20 25 71 20 69 6e 73 74  ways use %q inst
1e250 65 61 64 20 6f 66 20 25 73 20 77 68 65 6e 20 69  ead of %s when i
1e260 6e 73 65 72 74 69 6e 67 20 74 65 78 74 20 69 6e  nserting text in
1e270 74 6f 20 61 20 73 74 72 69 6e 67 20 6c 69 74 65  to a string lite
1e280 72 61 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65  ral..**.** ^(The
1e290 20 25 51 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73   %Q option works
1e2a0 20 6c 69 6b 65 20 25 71 20 65 78 63 65 70 74 20   like %q except 
1e2b0 69 74 20 61 6c 73 6f 20 61 64 64 73 20 73 69 6e  it also adds sin
1e2c0 67 6c 65 20 71 75 6f 74 65 73 20 61 72 6f 75 6e  gle quotes aroun
1e2d0 64 0a 2a 2a 20 74 68 65 20 6f 75 74 73 69 64 65  d.** the outside
1e2e0 20 6f 66 20 74 68 65 20 74 6f 74 61 6c 20 73 74   of the total st
1e2f0 72 69 6e 67 2e 20 20 41 64 64 69 74 69 6f 6e 61  ring.  Additiona
1e300 6c 6c 79 2c 20 69 66 20 74 68 65 20 70 61 72 61  lly, if the para
1e310 6d 65 74 65 72 20 69 6e 20 74 68 65 0a 2a 2a 20  meter in the.** 
1e320 61 72 67 75 6d 65 6e 74 20 6c 69 73 74 20 69 73  argument list is
1e330 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c   a NULL pointer,
1e340 20 25 51 20 73 75 62 73 74 69 74 75 74 65 73 20   %Q substitutes 
1e350 74 68 65 20 74 65 78 74 20 22 4e 55 4c 4c 22 20  the text "NULL" 
1e360 28 77 69 74 68 6f 75 74 0a 2a 2a 20 73 69 6e 67  (without.** sing
1e370 6c 65 20 71 75 6f 74 65 73 29 2e 29 5e 20 20 53  le quotes).)^  S
1e380 6f 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20  o, for example, 
1e390 6f 6e 65 20 63 6f 75 6c 64 20 73 61 79 3a 0a 2a  one could say:.*
1e3a0 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65  *.** <blockquote
1e3b0 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20  ><pre>.**  char 
1e3c0 2a 7a 53 51 4c 20 3d 20 73 71 6c 69 74 65 33 5f  *zSQL = sqlite3_
1e3d0 6d 70 72 69 6e 74 66 28 22 49 4e 53 45 52 54 20  mprintf("INSERT 
1e3e0 49 4e 54 4f 20 74 61 62 6c 65 20 56 41 4c 55 45  INTO table VALUE
1e3f0 53 28 25 51 29 22 2c 20 7a 54 65 78 74 29 3b 0a  S(%Q)", zText);.
1e400 2a 2a 20 20 73 71 6c 69 74 65 33 5f 65 78 65 63  **  sqlite3_exec
1e410 28 64 62 2c 20 7a 53 51 4c 2c 20 30 2c 20 30 2c  (db, zSQL, 0, 0,
1e420 20 30 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33   0);.**  sqlite3
1e430 5f 66 72 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20  _free(zSQL);.** 
1e440 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f  </pre></blockquo
1e450 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f  te>.**.** The co
1e460 64 65 20 61 62 6f 76 65 20 77 69 6c 6c 20 72 65  de above will re
1e470 6e 64 65 72 20 61 20 63 6f 72 72 65 63 74 20 53  nder a correct S
1e480 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20  QL statement in 
1e490 74 68 65 20 7a 53 51 4c 0a 2a 2a 20 76 61 72 69  the zSQL.** vari
1e4a0 61 62 6c 65 20 65 76 65 6e 20 69 66 20 74 68 65  able even if the
1e4b0 20 7a 54 65 78 74 20 76 61 72 69 61 62 6c 65 20   zText variable 
1e4c0 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  is a NULL pointe
1e4d0 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 22  r..**.** ^(The "
1e4e0 25 77 22 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f  %w" formatting o
1e4f0 70 74 69 6f 6e 20 69 73 20 6c 69 6b 65 20 22 25  ption is like "%
1e500 71 22 20 65 78 63 65 70 74 20 74 68 61 74 20 69  q" except that i
1e510 74 20 65 78 70 65 63 74 73 20 74 6f 0a 2a 2a 20  t expects to.** 
1e520 62 65 20 63 6f 6e 74 61 69 6e 65 64 20 77 69 74  be contained wit
1e530 68 69 6e 20 64 6f 75 62 6c 65 2d 71 75 6f 74 65  hin double-quote
1e540 73 20 69 6e 73 74 65 61 64 20 6f 66 20 73 69 6e  s instead of sin
1e550 67 6c 65 20 71 75 6f 74 65 73 2c 20 61 6e 64 20  gle quotes, and 
1e560 69 74 0a 2a 2a 20 65 73 63 61 70 65 73 20 74 68  it.** escapes th
1e570 65 20 64 6f 75 62 6c 65 2d 71 75 6f 74 65 20 63  e double-quote c
1e580 68 61 72 61 63 74 65 72 20 69 6e 73 74 65 61 64  haracter instead
1e590 20 6f 66 20 74 68 65 20 73 69 6e 67 6c 65 2d 71   of the single-q
1e5a0 75 6f 74 65 0a 2a 2a 20 63 68 61 72 61 63 74 65  uote.** characte
1e5b0 72 2e 29 5e 20 20 54 68 65 20 22 25 77 22 20 66  r.)^  The "%w" f
1e5c0 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e  ormatting option
1e5d0 20 69 73 20 69 6e 74 65 6e 64 65 64 20 66 6f 72   is intended for
1e5e0 20 73 61 66 65 6c 79 20 69 6e 73 65 72 74 69 6e   safely insertin
1e5f0 67 0a 2a 2a 20 74 61 62 6c 65 20 61 6e 64 20 63  g.** table and c
1e600 6f 6c 75 6d 6e 20 6e 61 6d 65 73 20 69 6e 74 6f  olumn names into
1e610 20 61 20 63 6f 6e 73 74 72 75 63 74 65 64 20 53   a constructed S
1e620 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a  QL statement..**
1e630 0a 2a 2a 20 5e 28 54 68 65 20 22 25 7a 22 20 66  .** ^(The "%z" f
1e640 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e  ormatting option
1e650 20 77 6f 72 6b 73 20 6c 69 6b 65 20 22 25 73 22   works like "%s"
1e660 20 62 75 74 20 77 69 74 68 20 74 68 65 0a 2a 2a   but with the.**
1e670 20 61 64 64 69 74 69 6f 6e 20 74 68 61 74 20 61   addition that a
1e680 66 74 65 72 20 74 68 65 20 73 74 72 69 6e 67 20  fter the string 
1e690 68 61 73 20 62 65 65 6e 20 72 65 61 64 20 61 6e  has been read an
1e6a0 64 20 63 6f 70 69 65 64 20 69 6e 74 6f 0a 2a 2a  d copied into.**
1e6b0 20 74 68 65 20 72 65 73 75 6c 74 2c 20 5b 73 71   the result, [sq
1e6c0 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 69 73  lite3_free()] is
1e6d0 20 63 61 6c 6c 65 64 20 6f 6e 20 74 68 65 20 69   called on the i
1e6e0 6e 70 75 74 20 73 74 72 69 6e 67 2e 29 5e 0a 2a  nput string.)^.*
1e6f0 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 68 61  /.SQLITE_API cha
1e700 72 20 2a 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e  r *sqlite3_mprin
1e710 74 66 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c 2e  tf(const char*,.
1e720 2e 2e 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..);.SQLITE_API 
1e730 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 76 6d  char *sqlite3_vm
1e740 70 72 69 6e 74 66 28 63 6f 6e 73 74 20 63 68 61  printf(const cha
1e750 72 2a 2c 20 76 61 5f 6c 69 73 74 29 3b 0a 53 51  r*, va_list);.SQ
1e760 4c 49 54 45 5f 41 50 49 20 63 68 61 72 20 2a 73  LITE_API char *s
1e770 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28  qlite3_snprintf(
1e780 69 6e 74 2c 63 68 61 72 2a 2c 63 6f 6e 73 74 20  int,char*,const 
1e790 63 68 61 72 2a 2c 20 2e 2e 2e 29 3b 0a 53 51 4c  char*, ...);.SQL
1e7a0 49 54 45 5f 41 50 49 20 63 68 61 72 20 2a 73 71  ITE_API char *sq
1e7b0 6c 69 74 65 33 5f 76 73 6e 70 72 69 6e 74 66 28  lite3_vsnprintf(
1e7c0 69 6e 74 2c 63 68 61 72 2a 2c 63 6f 6e 73 74 20  int,char*,const 
1e7d0 63 68 61 72 2a 2c 20 76 61 5f 6c 69 73 74 29 3b  char*, va_list);
1e7e0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1e7f0 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74  : Memory Allocat
1e800 69 6f 6e 20 53 75 62 73 79 73 74 65 6d 0a 2a 2a  ion Subsystem.**
1e810 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20 63  .** The SQLite c
1e820 6f 72 65 20 75 73 65 73 20 74 68 65 73 65 20 74  ore uses these t
1e830 68 72 65 65 20 72 6f 75 74 69 6e 65 73 20 66 6f  hree routines fo
1e840 72 20 61 6c 6c 20 6f 66 20 69 74 73 20 6f 77 6e  r all of its own
1e850 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c 20 6d 65 6d  .** internal mem
1e860 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e  ory allocation n
1e870 65 65 64 73 2e 20 22 43 6f 72 65 22 20 69 6e 20  eeds. "Core" in 
1e880 74 68 65 20 70 72 65 76 69 6f 75 73 20 73 65 6e  the previous sen
1e890 74 65 6e 63 65 0a 2a 2a 20 64 6f 65 73 20 6e 6f  tence.** does no
1e8a0 74 20 69 6e 63 6c 75 64 65 20 6f 70 65 72 61 74  t include operat
1e8b0 69 6e 67 2d 73 79 73 74 65 6d 20 73 70 65 63 69  ing-system speci
1e8c0 66 69 63 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e  fic VFS implemen
1e8d0 74 61 74 69 6f 6e 2e 20 20 54 68 65 0a 2a 2a 20  tation.  The.** 
1e8e0 57 69 6e 64 6f 77 73 20 56 46 53 20 75 73 65 73  Windows VFS uses
1e8f0 20 6e 61 74 69 76 65 20 6d 61 6c 6c 6f 63 28 29   native malloc()
1e900 20 61 6e 64 20 66 72 65 65 28 29 20 66 6f 72 20   and free() for 
1e910 73 6f 6d 65 20 6f 70 65 72 61 74 69 6f 6e 73 2e  some operations.
1e920 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
1e930 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 72 6f 75  te3_malloc() rou
1e940 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20 70  tine returns a p
1e950 6f 69 6e 74 65 72 20 74 6f 20 61 20 62 6c 6f 63  ointer to a bloc
1e960 6b 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79 20 61  k.** of memory a
1e970 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73 20  t least N bytes 
1e980 69 6e 20 6c 65 6e 67 74 68 2c 20 77 68 65 72 65  in length, where
1e990 20 4e 20 69 73 20 74 68 65 20 70 61 72 61 6d 65   N is the parame
1e9a0 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69  ter..** ^If sqli
1e9b0 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 69 73 20  te3_malloc() is 
1e9c0 75 6e 61 62 6c 65 20 74 6f 20 6f 62 74 61 69 6e  unable to obtain
1e9d0 20 73 75 66 66 69 63 69 65 6e 74 20 66 72 65 65   sufficient free
1e9e0 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20 69 74 20 72  .** memory, it r
1e9f0 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f  eturns a NULL po
1ea00 69 6e 74 65 72 2e 20 20 5e 49 66 20 74 68 65 20  inter.  ^If the 
1ea10 70 61 72 61 6d 65 74 65 72 20 4e 20 74 6f 0a 2a  parameter N to.*
1ea20 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  * sqlite3_malloc
1ea30 28 29 20 69 73 20 7a 65 72 6f 20 6f 72 20 6e 65  () is zero or ne
1ea40 67 61 74 69 76 65 20 74 68 65 6e 20 73 71 6c 69  gative then sqli
1ea50 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 72 65 74  te3_malloc() ret
1ea60 75 72 6e 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70  urns.** a NULL p
1ea70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ointer..**.** ^T
1ea80 68 65 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  he sqlite3_mallo
1ea90 63 36 34 28 4e 29 20 72 6f 75 74 69 6e 65 20 77  c64(N) routine w
1eaa0 6f 72 6b 73 20 6a 75 73 74 20 6c 69 6b 65 0a 2a  orks just like.*
1eab0 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  * sqlite3_malloc
1eac0 28 4e 29 20 65 78 63 65 70 74 20 74 68 61 74 20  (N) except that 
1ead0 4e 20 69 73 20 61 6e 20 75 6e 73 69 67 6e 65 64  N is an unsigned
1eae0 20 36 34 2d 62 69 74 20 69 6e 74 65 67 65 72 20   64-bit integer 
1eaf0 69 6e 73 74 65 61 64 0a 2a 2a 20 6f 66 20 61 20  instead.** of a 
1eb00 73 69 67 6e 65 64 20 33 32 2d 62 69 74 20 69 6e  signed 32-bit in
1eb10 74 65 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61  teger..**.** ^Ca
1eb20 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 66 72  lling sqlite3_fr
1eb30 65 65 28 29 20 77 69 74 68 20 61 20 70 6f 69 6e  ee() with a poin
1eb40 74 65 72 20 70 72 65 76 69 6f 75 73 6c 79 20 72  ter previously r
1eb50 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71  eturned.** by sq
1eb60 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f  lite3_malloc() o
1eb70 72 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  r sqlite3_reallo
1eb80 63 28 29 20 72 65 6c 65 61 73 65 73 20 74 68 61  c() releases tha
1eb90 74 20 6d 65 6d 6f 72 79 20 73 6f 0a 2a 2a 20 74  t memory so.** t
1eba0 68 61 74 20 69 74 20 6d 69 67 68 74 20 62 65 20  hat it might be 
1ebb0 72 65 75 73 65 64 2e 20 20 5e 54 68 65 20 73 71  reused.  ^The sq
1ebc0 6c 69 74 65 33 5f 66 72 65 65 28 29 20 72 6f 75  lite3_free() rou
1ebd0 74 69 6e 65 20 69 73 0a 2a 2a 20 61 20 6e 6f 2d  tine is.** a no-
1ebe0 6f 70 20 69 66 20 69 73 20 63 61 6c 6c 65 64 20  op if is called 
1ebf0 77 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  with a NULL poin
1ec00 74 65 72 2e 20 20 50 61 73 73 69 6e 67 20 61 20  ter.  Passing a 
1ec10 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20  NULL pointer.** 
1ec20 74 6f 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28  to sqlite3_free(
1ec30 29 20 69 73 20 68 61 72 6d 6c 65 73 73 2e 20 20  ) is harmless.  
1ec40 41 66 74 65 72 20 62 65 69 6e 67 20 66 72 65 65  After being free
1ec50 64 2c 20 6d 65 6d 6f 72 79 0a 2a 2a 20 73 68 6f  d, memory.** sho
1ec60 75 6c 64 20 6e 65 69 74 68 65 72 20 62 65 20 72  uld neither be r
1ec70 65 61 64 20 6e 6f 72 20 77 72 69 74 74 65 6e 2e  ead nor written.
1ec80 20 20 45 76 65 6e 20 72 65 61 64 69 6e 67 20 70    Even reading p
1ec90 72 65 76 69 6f 75 73 6c 79 20 66 72 65 65 64 0a  reviously freed.
1eca0 2a 2a 20 6d 65 6d 6f 72 79 20 6d 69 67 68 74 20  ** memory might 
1ecb0 72 65 73 75 6c 74 20 69 6e 20 61 20 73 65 67 6d  result in a segm
1ecc0 65 6e 74 61 74 69 6f 6e 20 66 61 75 6c 74 20 6f  entation fault o
1ecd0 72 20 6f 74 68 65 72 20 73 65 76 65 72 65 20 65  r other severe e
1ece0 72 72 6f 72 2e 0a 2a 2a 20 4d 65 6d 6f 72 79 20  rror..** Memory 
1ecf0 63 6f 72 72 75 70 74 69 6f 6e 2c 20 61 20 73 65  corruption, a se
1ed00 67 6d 65 6e 74 61 74 69 6f 6e 20 66 61 75 6c 74  gmentation fault
1ed10 2c 20 6f 72 20 6f 74 68 65 72 20 73 65 76 65 72  , or other sever
1ed20 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 69 67 68 74  e error.** might
1ed30 20 72 65 73 75 6c 74 20 69 66 20 73 71 6c 69 74   result if sqlit
1ed40 65 33 5f 66 72 65 65 28 29 20 69 73 20 63 61 6c  e3_free() is cal
1ed50 6c 65 64 20 77 69 74 68 20 61 20 6e 6f 6e 2d 4e  led with a non-N
1ed60 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 61 74  ULL pointer that
1ed70 0a 2a 2a 20 77 61 73 20 6e 6f 74 20 6f 62 74 61  .** was not obta
1ed80 69 6e 65 64 20 66 72 6f 6d 20 73 71 6c 69 74 65  ined from sqlite
1ed90 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 20 73 71  3_malloc() or sq
1eda0 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e  lite3_realloc().
1edb0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
1edc0 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29  te3_realloc(X,N)
1edd0 20 69 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d   interface attem
1ede0 70 74 73 20 74 6f 20 72 65 73 69 7a 65 20 61 0a  pts to resize a.
1edf0 2a 2a 20 70 72 69 6f 72 20 6d 65 6d 6f 72 79 20  ** prior memory 
1ee00 61 6c 6c 6f 63 61 74 69 6f 6e 20 58 20 74 6f 20  allocation X to 
1ee10 62 65 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79  be at least N by
1ee20 74 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  tes..** ^If the 
1ee30 58 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  X parameter to s
1ee40 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58  qlite3_realloc(X
1ee50 2c 4e 29 0a 2a 2a 20 69 73 20 61 20 4e 55 4c 4c  ,N).** is a NULL
1ee60 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 69 74   pointer then it
1ee70 73 20 62 65 68 61 76 69 6f 72 20 69 73 20 69 64  s behavior is id
1ee80 65 6e 74 69 63 61 6c 20 74 6f 20 63 61 6c 6c 69  entical to calli
1ee90 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61  ng.** sqlite3_ma
1eea0 6c 6c 6f 63 28 4e 29 2e 0a 2a 2a 20 5e 49 66 20  lloc(N)..** ^If 
1eeb0 74 68 65 20 4e 20 70 61 72 61 6d 65 74 65 72 20  the N parameter 
1eec0 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  to sqlite3_reall
1eed0 6f 63 28 58 2c 4e 29 20 69 73 20 7a 65 72 6f 20  oc(X,N) is zero 
1eee0 6f 72 0a 2a 2a 20 6e 65 67 61 74 69 76 65 20 74  or.** negative t
1eef0 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72  hen the behavior
1ef00 20 69 73 20 65 78 61 63 74 6c 79 20 74 68 65 20   is exactly the 
1ef10 73 61 6d 65 20 61 73 20 63 61 6c 6c 69 6e 67 0a  same as calling.
1ef20 2a 2a 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28  ** sqlite3_free(
1ef30 58 29 2e 0a 2a 2a 20 5e 73 71 6c 69 74 65 33 5f  X)..** ^sqlite3_
1ef40 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 20 72 65 74  realloc(X,N) ret
1ef50 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
1ef60 6f 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  o a memory alloc
1ef70 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 61 74 20 6c  ation.** of at l
1ef80 65 61 73 74 20 4e 20 62 79 74 65 73 20 69 6e 20  east N bytes in 
1ef90 73 69 7a 65 20 6f 72 20 4e 55 4c 4c 20 69 66 20  size or NULL if 
1efa0 69 6e 73 75 66 66 69 63 69 65 6e 74 20 6d 65 6d  insufficient mem
1efb0 6f 72 79 20 69 73 20 61 76 61 69 6c 61 62 6c 65  ory is available
1efc0 2e 0a 2a 2a 20 5e 49 66 20 4d 20 69 73 20 74 68  ..** ^If M is th
1efd0 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 70 72  e size of the pr
1efe0 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20  ior allocation, 
1eff0 74 68 65 6e 20 6d 69 6e 28 4e 2c 4d 29 20 62 79  then min(N,M) by
1f000 74 65 73 0a 2a 2a 20 6f 66 20 74 68 65 20 70 72  tes.** of the pr
1f010 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 61  ior allocation a
1f020 72 65 20 63 6f 70 69 65 64 20 69 6e 74 6f 20 74  re copied into t
1f030 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20  he beginning of 
1f040 62 75 66 66 65 72 20 72 65 74 75 72 6e 65 64 0a  buffer returned.
1f050 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 72 65  ** by sqlite3_re
1f060 61 6c 6c 6f 63 28 58 2c 4e 29 20 61 6e 64 20 74  alloc(X,N) and t
1f070 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74  he prior allocat
1f080 69 6f 6e 20 69 73 20 66 72 65 65 64 2e 0a 2a 2a  ion is freed..**
1f090 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 72 65 61   ^If sqlite3_rea
1f0a0 6c 6c 6f 63 28 58 2c 4e 29 20 72 65 74 75 72 6e  lloc(X,N) return
1f0b0 73 20 4e 55 4c 4c 20 61 6e 64 20 4e 20 69 73 20  s NULL and N is 
1f0c0 70 6f 73 69 74 69 76 65 2c 20 74 68 65 6e 20 74  positive, then t
1f0d0 68 65 0a 2a 2a 20 70 72 69 6f 72 20 61 6c 6c 6f  he.** prior allo
1f0e0 63 61 74 69 6f 6e 20 69 73 20 6e 6f 74 20 66 72  cation is not fr
1f0f0 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  eed..**.** ^The 
1f100 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 36  sqlite3_realloc6
1f110 34 28 58 2c 4e 29 20 69 6e 74 65 72 66 61 63 65  4(X,N) interface
1f120 73 20 77 6f 72 6b 73 20 74 68 65 20 73 61 6d 65  s works the same
1f130 20 61 73 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72   as.** sqlite3_r
1f140 65 61 6c 6c 6f 63 28 58 2c 4e 29 20 65 78 63 65  ealloc(X,N) exce
1f150 70 74 20 74 68 61 74 20 4e 20 69 73 20 61 20 36  pt that N is a 6
1f160 34 2d 62 69 74 20 75 6e 73 69 67 6e 65 64 20 69  4-bit unsigned i
1f170 6e 74 65 67 65 72 20 69 6e 73 74 65 61 64 0a 2a  nteger instead.*
1f180 2a 20 6f 66 20 61 20 33 32 2d 62 69 74 20 73 69  * of a 32-bit si
1f190 67 6e 65 64 20 69 6e 74 65 67 65 72 2e 0a 2a 2a  gned integer..**
1f1a0 0a 2a 2a 20 5e 49 66 20 58 20 69 73 20 61 20 6d  .** ^If X is a m
1f1b0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
1f1c0 20 70 72 65 76 69 6f 75 73 6c 79 20 6f 62 74 61   previously obta
1f1d0 69 6e 65 64 20 66 72 6f 6d 20 73 71 6c 69 74 65  ined from sqlite
1f1e0 33 5f 6d 61 6c 6c 6f 63 28 29 2c 0a 2a 2a 20 73  3_malloc(),.** s
1f1f0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 36 34 28  qlite3_malloc64(
1f200 29 2c 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  ), sqlite3_reall
1f210 6f 63 28 29 2c 20 6f 72 20 73 71 6c 69 74 65 33  oc(), or sqlite3
1f220 5f 72 65 61 6c 6c 6f 63 36 34 28 29 2c 20 74 68  _realloc64(), th
1f230 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 73  en.** sqlite3_ms
1f240 69 7a 65 28 58 29 20 72 65 74 75 72 6e 73 20 74  ize(X) returns t
1f250 68 65 20 73 69 7a 65 20 6f 66 20 74 68 61 74 20  he size of that 
1f260 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
1f270 6e 20 69 6e 20 62 79 74 65 73 2e 0a 2a 2a 20 5e  n in bytes..** ^
1f280 54 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e  The value return
1f290 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 6d 73  ed by sqlite3_ms
1f2a0 69 7a 65 28 58 29 20 6d 69 67 68 74 20 62 65 20  ize(X) might be 
1f2b0 6c 61 72 67 65 72 20 74 68 61 6e 20 74 68 65 20  larger than the 
1f2c0 6e 75 6d 62 65 72 0a 2a 2a 20 6f 66 20 62 79 74  number.** of byt
1f2d0 65 73 20 72 65 71 75 65 73 74 65 64 20 77 68 65  es requested whe
1f2e0 6e 20 58 20 77 61 73 20 61 6c 6c 6f 63 61 74 65  n X was allocate
1f2f0 64 2e 20 20 5e 49 66 20 58 20 69 73 20 61 20 4e  d.  ^If X is a N
1f300 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e  ULL pointer then
1f310 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 73 69 7a  .** sqlite3_msiz
1f320 65 28 58 29 20 72 65 74 75 72 6e 73 20 7a 65 72  e(X) returns zer
1f330 6f 2e 20 20 49 66 20 58 20 70 6f 69 6e 74 73 20  o.  If X points 
1f340 74 6f 20 73 6f 6d 65 74 68 69 6e 67 20 74 68 61  to something tha
1f350 74 20 69 73 20 6e 6f 74 0a 2a 2a 20 74 68 65 20  t is not.** the 
1f360 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 6d 65 6d  beginning of mem
1f370 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20  ory allocation, 
1f380 6f 72 20 69 66 20 69 74 20 70 6f 69 6e 74 73 20  or if it points 
1f390 74 6f 20 61 20 66 6f 72 6d 65 72 6c 79 0a 2a 2a  to a formerly.**
1f3a0 20 76 61 6c 69 64 20 6d 65 6d 6f 72 79 20 61 6c   valid memory al
1f3b0 6c 6f 63 61 74 69 6f 6e 20 74 68 61 74 20 68 61  location that ha
1f3c0 73 20 6e 6f 77 20 62 65 65 6e 20 66 72 65 65 64  s now been freed
1f3d0 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76  , then the behav
1f3e0 69 6f 72 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65  ior.** of sqlite
1f3f0 33 5f 6d 73 69 7a 65 28 58 29 20 69 73 20 75 6e  3_msize(X) is un
1f400 64 65 66 69 6e 65 64 20 61 6e 64 20 70 6f 73 73  defined and poss
1f410 69 62 6c 79 20 68 61 72 6d 66 75 6c 2e 0a 2a 2a  ibly harmful..**
1f420 0a 2a 2a 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20  .** ^The memory 
1f430 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69  returned by sqli
1f440 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 2c 20 73 71  te3_malloc(), sq
1f450 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2c  lite3_realloc(),
1f460 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  .** sqlite3_mall
1f470 6f 63 36 34 28 29 2c 20 61 6e 64 20 73 71 6c 69  oc64(), and sqli
1f480 74 65 33 5f 72 65 61 6c 6c 6f 63 36 34 28 29 0a  te3_realloc64().
1f490 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 61 6c 69  ** is always ali
1f4a0 67 6e 65 64 20 74 6f 20 61 74 20 6c 65 61 73 74  gned to at least
1f4b0 20 61 6e 20 38 20 62 79 74 65 20 62 6f 75 6e 64   an 8 byte bound
1f4c0 61 72 79 2c 20 6f 72 20 74 6f 20 61 0a 2a 2a 20  ary, or to a.** 
1f4d0 34 20 62 79 74 65 20 62 6f 75 6e 64 61 72 79 20  4 byte boundary 
1f4e0 69 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 34  if the [SQLITE_4
1f4f0 5f 42 59 54 45 5f 41 4c 49 47 4e 45 44 5f 4d 41  _BYTE_ALIGNED_MA
1f500 4c 4c 4f 43 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  LLOC] compile-ti
1f510 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e 20 69 73 20  me.** option is 
1f520 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 53  used..**.** In S
1f530 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e  QLite version 3.
1f540 35 2e 30 20 61 6e 64 20 33 2e 35 2e 31 2c 20 69  5.0 and 3.5.1, i
1f550 74 20 77 61 73 20 70 6f 73 73 69 62 6c 65 20 74  t was possible t
1f560 6f 20 64 65 66 69 6e 65 0a 2a 2a 20 74 68 65 20  o define.** the 
1f570 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 4d 45 4d 4f  SQLITE_OMIT_MEMO
1f580 52 59 5f 41 4c 4c 4f 43 41 54 49 4f 4e 20 77 68  RY_ALLOCATION wh
1f590 69 63 68 20 77 6f 75 6c 64 20 63 61 75 73 65 20  ich would cause 
1f5a0 74 68 65 20 62 75 69 6c 74 2d 69 6e 0a 2a 2a 20  the built-in.** 
1f5b0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f  implementation o
1f5c0 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  f these routines
1f5d0 20 74 6f 20 62 65 20 6f 6d 69 74 74 65 64 2e 20   to be omitted. 
1f5e0 20 54 68 61 74 20 63 61 70 61 62 69 6c 69 74 79   That capability
1f5f0 0a 2a 2a 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72  .** is no longer
1f600 20 70 72 6f 76 69 64 65 64 2e 20 20 4f 6e 6c 79   provided.  Only
1f610 20 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79   built-in memory
1f620 20 61 6c 6c 6f 63 61 74 6f 72 73 20 63 61 6e 20   allocators can 
1f630 62 65 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 50  be used..**.** P
1f640 72 69 6f 72 20 74 6f 20 53 51 4c 69 74 65 20 76  rior to SQLite v
1f650 65 72 73 69 6f 6e 20 33 2e 37 2e 31 30 2c 20 74  ersion 3.7.10, t
1f660 68 65 20 57 69 6e 64 6f 77 73 20 4f 53 20 69 6e  he Windows OS in
1f670 74 65 72 66 61 63 65 20 6c 61 79 65 72 20 63 61  terface layer ca
1f680 6c 6c 65 64 0a 2a 2a 20 74 68 65 20 73 79 73 74  lled.** the syst
1f690 65 6d 20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20  em malloc() and 
1f6a0 66 72 65 65 28 29 20 64 69 72 65 63 74 6c 79 20  free() directly 
1f6b0 77 68 65 6e 20 63 6f 6e 76 65 72 74 69 6e 67 0a  when converting.
1f6c0 2a 2a 20 66 69 6c 65 6e 61 6d 65 73 20 62 65 74  ** filenames bet
1f6d0 77 65 65 6e 20 74 68 65 20 55 54 46 2d 38 20 65  ween the UTF-8 e
1f6e0 6e 63 6f 64 69 6e 67 20 75 73 65 64 20 62 79 20  ncoding used by 
1f6f0 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 77 68  SQLite.** and wh
1f700 61 74 65 76 65 72 20 66 69 6c 65 6e 61 6d 65 20  atever filename 
1f710 65 6e 63 6f 64 69 6e 67 20 69 73 20 75 73 65 64  encoding is used
1f720 20 62 79 20 74 68 65 20 70 61 72 74 69 63 75 6c   by the particul
1f730 61 72 20 57 69 6e 64 6f 77 73 0a 2a 2a 20 69 6e  ar Windows.** in
1f740 73 74 61 6c 6c 61 74 69 6f 6e 2e 20 20 4d 65 6d  stallation.  Mem
1f750 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65  ory allocation e
1f760 72 72 6f 72 73 20 77 65 72 65 20 64 65 74 65 63  rrors were detec
1f770 74 65 64 2c 20 62 75 74 0a 2a 2a 20 74 68 65 79  ted, but.** they
1f780 20 77 65 72 65 20 72 65 70 6f 72 74 65 64 20 62   were reported b
1f790 61 63 6b 20 61 73 20 5b 53 51 4c 49 54 45 5f 43  ack as [SQLITE_C
1f7a0 41 4e 54 4f 50 45 4e 5d 20 6f 72 0a 2a 2a 20 5b  ANTOPEN] or.** [
1f7b0 53 51 4c 49 54 45 5f 49 4f 45 52 52 5d 20 72 61  SQLITE_IOERR] ra
1f7c0 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54  ther than [SQLIT
1f7d0 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20  E_NOMEM]..**.** 
1f7e0 54 68 65 20 70 6f 69 6e 74 65 72 20 61 72 67 75  The pointer argu
1f7f0 6d 65 6e 74 73 20 74 6f 20 5b 73 71 6c 69 74 65  ments to [sqlite
1f800 33 5f 66 72 65 65 28 29 5d 20 61 6e 64 20 5b 73  3_free()] and [s
1f810 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
1f820 5d 0a 2a 2a 20 6d 75 73 74 20 62 65 20 65 69 74  ].** must be eit
1f830 68 65 72 20 4e 55 4c 4c 20 6f 72 20 65 6c 73 65  her NULL or else
1f840 20 70 6f 69 6e 74 65 72 73 20 6f 62 74 61 69 6e   pointers obtain
1f850 65 64 20 66 72 6f 6d 20 61 20 70 72 69 6f 72 0a  ed from a prior.
1f860 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66  ** invocation of
1f870 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
1f880 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
1f890 72 65 61 6c 6c 6f 63 28 29 5d 20 74 68 61 74 20  realloc()] that 
1f8a0 68 61 76 65 0a 2a 2a 20 6e 6f 74 20 79 65 74 20  have.** not yet 
1f8b0 62 65 65 6e 20 72 65 6c 65 61 73 65 64 2e 0a 2a  been released..*
1f8c0 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61  *.** The applica
1f8d0 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 72 65  tion must not re
1f8e0 61 64 20 6f 72 20 77 72 69 74 65 20 61 6e 79 20  ad or write any 
1f8f0 70 61 72 74 20 6f 66 0a 2a 2a 20 61 20 62 6c 6f  part of.** a blo
1f900 63 6b 20 6f 66 20 6d 65 6d 6f 72 79 20 61 66 74  ck of memory aft
1f910 65 72 20 69 74 20 68 61 73 20 62 65 65 6e 20 72  er it has been r
1f920 65 6c 65 61 73 65 64 20 75 73 69 6e 67 0a 2a 2a  eleased using.**
1f930 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
1f940 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65  ] or [sqlite3_re
1f950 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 53 51 4c  alloc()]..*/.SQL
1f960 49 54 45 5f 41 50 49 20 76 6f 69 64 20 2a 73 71  ITE_API void *sq
1f970 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 69 6e 74  lite3_malloc(int
1f980 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f  );.SQLITE_API vo
1f990 69 64 20 2a 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  id *sqlite3_mall
1f9a0 6f 63 36 34 28 73 71 6c 69 74 65 33 5f 75 69 6e  oc64(sqlite3_uin
1f9b0 74 36 34 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  t64);.SQLITE_API
1f9c0 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 72   void *sqlite3_r
1f9d0 65 61 6c 6c 6f 63 28 76 6f 69 64 2a 2c 20 69 6e  ealloc(void*, in
1f9e0 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76  t);.SQLITE_API v
1f9f0 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 72 65 61  oid *sqlite3_rea
1fa00 6c 6c 6f 63 36 34 28 76 6f 69 64 2a 2c 20 73 71  lloc64(void*, sq
1fa10 6c 69 74 65 33 5f 75 69 6e 74 36 34 29 3b 0a 53  lite3_uint64);.S
1fa20 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73  QLITE_API void s
1fa30 71 6c 69 74 65 33 5f 66 72 65 65 28 76 6f 69 64  qlite3_free(void
1fa40 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 73  *);.SQLITE_API s
1fa50 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 20 73 71  qlite3_uint64 sq
1fa60 6c 69 74 65 33 5f 6d 73 69 7a 65 28 76 6f 69 64  lite3_msize(void
1fa70 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
1fa80 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f  REF: Memory Allo
1fa90 63 61 74 6f 72 20 53 74 61 74 69 73 74 69 63 73  cator Statistics
1faa0 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 70 72  .**.** SQLite pr
1fab0 6f 76 69 64 65 73 20 74 68 65 73 65 20 74 77 6f  ovides these two
1fac0 20 69 6e 74 65 72 66 61 63 65 73 20 66 6f 72 20   interfaces for 
1fad0 72 65 70 6f 72 74 69 6e 67 20 6f 6e 20 74 68 65  reporting on the
1fae0 20 73 74 61 74 75 73 0a 2a 2a 20 6f 66 20 74 68   status.** of th
1faf0 65 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  e [sqlite3_mallo
1fb00 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 66  c()], [sqlite3_f
1fb10 72 65 65 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c  ree()], and [sql
1fb20 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a  ite3_realloc()].
1fb30 2a 2a 20 72 6f 75 74 69 6e 65 73 2c 20 77 68 69  ** routines, whi
1fb40 63 68 20 66 6f 72 6d 20 74 68 65 20 62 75 69 6c  ch form the buil
1fb50 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  t-in memory allo
1fb60 63 61 74 69 6f 6e 20 73 75 62 73 79 73 74 65 6d  cation subsystem
1fb70 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71  ..**.** ^The [sq
1fb80 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65  lite3_memory_use
1fb90 64 28 29 5d 20 72 6f 75 74 69 6e 65 20 72 65 74  d()] routine ret
1fba0 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20  urns the number 
1fbb0 6f 66 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 6d  of bytes.** of m
1fbc0 65 6d 6f 72 79 20 63 75 72 72 65 6e 74 6c 79 20  emory currently 
1fbd0 6f 75 74 73 74 61 6e 64 69 6e 67 20 28 6d 61 6c  outstanding (mal
1fbe0 6c 6f 63 65 64 20 62 75 74 20 6e 6f 74 20 66 72  loced but not fr
1fbf0 65 65 64 29 2e 0a 2a 2a 20 5e 54 68 65 20 5b 73  eed)..** ^The [s
1fc00 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69  qlite3_memory_hi
1fc10 67 68 77 61 74 65 72 28 29 5d 20 72 6f 75 74 69  ghwater()] routi
1fc20 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6d  ne returns the m
1fc30 61 78 69 6d 75 6d 0a 2a 2a 20 76 61 6c 75 65 20  aximum.** value 
1fc40 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  of [sqlite3_memo
1fc50 72 79 5f 75 73 65 64 28 29 5d 20 73 69 6e 63 65  ry_used()] since
1fc60 20 74 68 65 20 68 69 67 68 2d 77 61 74 65 72 20   the high-water 
1fc70 6d 61 72 6b 0a 2a 2a 20 77 61 73 20 6c 61 73 74  mark.** was last
1fc80 20 72 65 73 65 74 2e 20 20 5e 54 68 65 20 76 61   reset.  ^The va
1fc90 6c 75 65 73 20 72 65 74 75 72 6e 65 64 20 62 79  lues returned by
1fca0 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79   [sqlite3_memory
1fcb0 5f 75 73 65 64 28 29 5d 20 61 6e 64 0a 2a 2a 20  _used()] and.** 
1fcc0 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f  [sqlite3_memory_
1fcd0 68 69 67 68 77 61 74 65 72 28 29 5d 20 69 6e 63  highwater()] inc
1fce0 6c 75 64 65 20 61 6e 79 20 6f 76 65 72 68 65 61  lude any overhea
1fcf0 64 0a 2a 2a 20 61 64 64 65 64 20 62 79 20 53 51  d.** added by SQ
1fd00 4c 69 74 65 20 69 6e 20 69 74 73 20 69 6d 70 6c  Lite in its impl
1fd10 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 5b 73  ementation of [s
1fd20 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
1fd30 2c 0a 2a 2a 20 62 75 74 20 6e 6f 74 20 6f 76 65  ,.** but not ove
1fd40 72 68 65 61 64 20 61 64 64 65 64 20 62 79 20 74  rhead added by t
1fd50 68 65 20 61 6e 79 20 75 6e 64 65 72 6c 79 69 6e  he any underlyin
1fd60 67 20 73 79 73 74 65 6d 20 6c 69 62 72 61 72 79  g system library
1fd70 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 74 68 61  .** routines tha
1fd80 74 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  t [sqlite3_mallo
1fd90 63 28 29 5d 20 6d 61 79 20 63 61 6c 6c 2e 0a 2a  c()] may call..*
1fda0 2a 0a 2a 2a 20 5e 54 68 65 20 6d 65 6d 6f 72 79  *.** ^The memory
1fdb0 20 68 69 67 68 2d 77 61 74 65 72 20 6d 61 72 6b   high-water mark
1fdc0 20 69 73 20 72 65 73 65 74 20 74 6f 20 74 68 65   is reset to the
1fdd0 20 63 75 72 72 65 6e 74 20 76 61 6c 75 65 20 6f   current value o
1fde0 66 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65  f.** [sqlite3_me
1fdf0 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 69 66 20  mory_used()] if 
1fe00 61 6e 64 20 6f 6e 6c 79 20 69 66 20 74 68 65 20  and only if the 
1fe10 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20  parameter to.** 
1fe20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f  [sqlite3_memory_
1fe30 68 69 67 68 77 61 74 65 72 28 29 5d 20 69 73 20  highwater()] is 
1fe40 74 72 75 65 2e 20 20 5e 54 68 65 20 76 61 6c 75  true.  ^The valu
1fe50 65 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79  e returned.** by
1fe60 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79   [sqlite3_memory
1fe70 5f 68 69 67 68 77 61 74 65 72 28 31 29 5d 20 69  _highwater(1)] i
1fe80 73 20 74 68 65 20 68 69 67 68 2d 77 61 74 65 72  s the high-water
1fe90 20 6d 61 72 6b 0a 2a 2a 20 70 72 69 6f 72 20 74   mark.** prior t
1fea0 6f 20 74 68 65 20 72 65 73 65 74 2e 0a 2a 2f 0a  o the reset..*/.
1feb0 53 51 4c 49 54 45 5f 41 50 49 20 73 71 6c 69 74  SQLITE_API sqlit
1fec0 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33  e3_int64 sqlite3
1fed0 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 76 6f 69  _memory_used(voi
1fee0 64 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 73  d);.SQLITE_API s
1fef0 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c  qlite3_int64 sql
1ff00 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68  ite3_memory_high
1ff10 77 61 74 65 72 28 69 6e 74 20 72 65 73 65 74 46  water(int resetF
1ff20 6c 61 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  lag);../*.** CAP
1ff30 49 33 52 45 46 3a 20 50 73 65 75 64 6f 2d 52 61  I3REF: Pseudo-Ra
1ff40 6e 64 6f 6d 20 4e 75 6d 62 65 72 20 47 65 6e 65  ndom Number Gene
1ff50 72 61 74 6f 72 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  rator.**.** SQLi
1ff60 74 65 20 63 6f 6e 74 61 69 6e 73 20 61 20 68 69  te contains a hi
1ff70 67 68 2d 71 75 61 6c 69 74 79 20 70 73 65 75 64  gh-quality pseud
1ff80 6f 2d 72 61 6e 64 6f 6d 20 6e 75 6d 62 65 72 20  o-random number 
1ff90 67 65 6e 65 72 61 74 6f 72 20 28 50 52 4e 47 29  generator (PRNG)
1ffa0 20 75 73 65 64 20 74 6f 0a 2a 2a 20 73 65 6c 65   used to.** sele
1ffb0 63 74 20 72 61 6e 64 6f 6d 20 5b 52 4f 57 49 44  ct random [ROWID
1ffc0 20 7c 20 52 4f 57 49 44 73 5d 20 77 68 65 6e 20   | ROWIDs] when 
1ffd0 69 6e 73 65 72 74 69 6e 67 20 6e 65 77 20 72 65  inserting new re
1ffe0 63 6f 72 64 73 20 69 6e 74 6f 20 61 20 74 61 62  cords into a tab
1fff0 6c 65 20 74 68 61 74 0a 2a 2a 20 61 6c 72 65 61  le that.** alrea
20000 64 79 20 75 73 65 73 20 74 68 65 20 6c 61 72 67  dy uses the larg
20010 65 73 74 20 70 6f 73 73 69 62 6c 65 20 5b 52 4f  est possible [RO
20020 57 49 44 5d 2e 20 20 54 68 65 20 50 52 4e 47 20  WID].  The PRNG 
20030 69 73 20 61 6c 73 6f 20 75 73 65 64 20 66 6f 72  is also used for
20040 0a 2a 2a 20 74 68 65 20 62 75 69 6c 64 2d 69 6e  .** the build-in
20050 20 72 61 6e 64 6f 6d 28 29 20 61 6e 64 20 72 61   random() and ra
20060 6e 64 6f 6d 62 6c 6f 62 28 29 20 53 51 4c 20 66  ndomblob() SQL f
20070 75 6e 63 74 69 6f 6e 73 2e 20 20 54 68 69 73 20  unctions.  This 
20080 69 6e 74 65 72 66 61 63 65 20 61 6c 6c 6f 77 73  interface allows
20090 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  .** applications
200a0 20 74 6f 20 61 63 63 65 73 73 20 74 68 65 20 73   to access the s
200b0 61 6d 65 20 50 52 4e 47 20 66 6f 72 20 6f 74 68  ame PRNG for oth
200c0 65 72 20 70 75 72 70 6f 73 65 73 2e 0a 2a 2a 0a  er purposes..**.
200d0 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 6f 20 74 68  ** ^A call to th
200e0 69 73 20 72 6f 75 74 69 6e 65 20 73 74 6f 72 65  is routine store
200f0 73 20 4e 20 62 79 74 65 73 20 6f 66 20 72 61 6e  s N bytes of ran
20100 64 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 62 75 66  domness into buf
20110 66 65 72 20 50 2e 0a 2a 2a 20 5e 54 68 65 20 50  fer P..** ^The P
20120 20 70 61 72 61 6d 65 74 65 72 20 63 61 6e 20 62   parameter can b
20130 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  e a NULL pointer
20140 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 69 73  ..**.** ^If this
20150 20 72 6f 75 74 69 6e 65 20 68 61 73 20 6e 6f 74   routine has not
20160 20 62 65 65 6e 20 70 72 65 76 69 6f 75 73 6c 79   been previously
20170 20 63 61 6c 6c 65 64 20 6f 72 20 69 66 20 74 68   called or if th
20180 65 20 70 72 65 76 69 6f 75 73 0a 2a 2a 20 63 61  e previous.** ca
20190 6c 6c 20 68 61 64 20 4e 20 6c 65 73 73 20 74 68  ll had N less th
201a0 61 6e 20 6f 6e 65 20 6f 72 20 61 20 4e 55 4c 4c  an one or a NULL
201b0 20 70 6f 69 6e 74 65 72 20 66 6f 72 20 50 2c 20   pointer for P, 
201c0 74 68 65 6e 20 74 68 65 20 50 52 4e 47 20 69 73  then the PRNG is
201d0 0a 2a 2a 20 73 65 65 64 65 64 20 75 73 69 6e 67  .** seeded using
201e0 20 72 61 6e 64 6f 6d 6e 65 73 73 20 6f 62 74 61   randomness obta
201f0 69 6e 65 64 20 66 72 6f 6d 20 74 68 65 20 78 52  ined from the xR
20200 61 6e 64 6f 6d 6e 65 73 73 20 6d 65 74 68 6f 64  andomness method
20210 20 6f 66 0a 2a 2a 20 74 68 65 20 64 65 66 61 75   of.** the defau
20220 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d  lt [sqlite3_vfs]
20230 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 5e 49 66 20   object..** ^If 
20240 74 68 65 20 70 72 65 76 69 6f 75 73 20 63 61 6c  the previous cal
20250 6c 20 74 6f 20 74 68 69 73 20 72 6f 75 74 69 6e  l to this routin
20260 65 20 68 61 64 20 61 6e 20 4e 20 6f 66 20 31 20  e had an N of 1 
20270 6f 72 20 6d 6f 72 65 20 61 6e 64 20 61 0a 2a 2a  or more and a.**
20280 20 6e 6f 6e 2d 4e 55 4c 4c 20 50 20 74 68 65 6e   non-NULL P then
20290 20 74 68 65 20 70 73 65 75 64 6f 2d 72 61 6e 64   the pseudo-rand
202a0 6f 6d 6e 65 73 73 20 69 73 20 67 65 6e 65 72 61  omness is genera
202b0 74 65 64 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c 6c  ted.** internall
202c0 79 20 61 6e 64 20 77 69 74 68 6f 75 74 20 72 65  y and without re
202d0 63 6f 75 72 73 65 20 74 6f 20 74 68 65 20 5b 73  course to the [s
202e0 71 6c 69 74 65 33 5f 76 66 73 5d 20 78 52 61 6e  qlite3_vfs] xRan
202f0 64 6f 6d 6e 65 73 73 0a 2a 2a 20 6d 65 74 68 6f  domness.** metho
20300 64 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  d..*/.SQLITE_API
20310 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 61   void sqlite3_ra
20320 6e 64 6f 6d 6e 65 73 73 28 69 6e 74 20 4e 2c 20  ndomness(int N, 
20330 76 6f 69 64 20 2a 50 29 3b 0a 0a 2f 2a 0a 2a 2a  void *P);../*.**
20340 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6d 70 69   CAPI3REF: Compi
20350 6c 65 2d 54 69 6d 65 20 41 75 74 68 6f 72 69 7a  le-Time Authoriz
20360 61 74 69 6f 6e 20 43 61 6c 6c 62 61 63 6b 73 0a  ation Callbacks.
20370 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
20380 65 33 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  e3.** KEYWORDS: 
20390 7b 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c  {authorizer call
203a0 62 61 63 6b 7d 0a 2a 2a 0a 2a 2a 20 5e 54 68 69  back}.**.** ^Thi
203b0 73 20 72 6f 75 74 69 6e 65 20 72 65 67 69 73 74  s routine regist
203c0 65 72 73 20 61 6e 20 61 75 74 68 6f 72 69 7a 65  ers an authorize
203d0 72 20 63 61 6c 6c 62 61 63 6b 20 77 69 74 68 20  r callback with 
203e0 61 20 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20  a particular.** 
203f0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
20400 74 69 6f 6e 5d 2c 20 73 75 70 70 6c 69 65 64 20  tion], supplied 
20410 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67  in the first arg
20420 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 61  ument..** ^The a
20430 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
20440 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 61 73  ck is invoked as
20450 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20   SQL statements 
20460 61 72 65 20 62 65 69 6e 67 20 63 6f 6d 70 69 6c  are being compil
20470 65 64 0a 2a 2a 20 62 79 20 5b 73 71 6c 69 74 65  ed.** by [sqlite
20480 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20  3_prepare()] or 
20490 69 74 73 20 76 61 72 69 61 6e 74 73 20 5b 73 71  its variants [sq
204a0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
204b0 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ()],.** [sqlite3
204c0 5f 70 72 65 70 61 72 65 31 36 28 29 5d 20 61 6e  _prepare16()] an
204d0 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  d [sqlite3_prepa
204e0 72 65 31 36 5f 76 32 28 29 5d 2e 20 20 5e 41 74  re16_v2()].  ^At
204f0 20 76 61 72 69 6f 75 73 0a 2a 2a 20 70 6f 69 6e   various.** poin
20500 74 73 20 64 75 72 69 6e 67 20 74 68 65 20 63 6f  ts during the co
20510 6d 70 69 6c 61 74 69 6f 6e 20 70 72 6f 63 65 73  mpilation proces
20520 73 2c 20 61 73 20 6c 6f 67 69 63 20 69 73 20 62  s, as logic is b
20530 65 69 6e 67 20 63 72 65 61 74 65 64 0a 2a 2a 20  eing created.** 
20540 74 6f 20 70 65 72 66 6f 72 6d 20 76 61 72 69 6f  to perform vario
20550 75 73 20 61 63 74 69 6f 6e 73 2c 20 74 68 65 20  us actions, the 
20560 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
20570 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 74  ack is invoked t
20580 6f 0a 2a 2a 20 73 65 65 20 69 66 20 74 68 6f 73  o.** see if thos
20590 65 20 61 63 74 69 6f 6e 73 20 61 72 65 20 61 6c  e actions are al
205a0 6c 6f 77 65 64 2e 20 20 5e 54 68 65 20 61 75 74  lowed.  ^The aut
205b0 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
205c0 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 75 72   should.** retur
205d0 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 74 6f  n [SQLITE_OK] to
205e0 20 61 6c 6c 6f 77 20 74 68 65 20 61 63 74 69 6f   allow the actio
205f0 6e 2c 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52  n, [SQLITE_IGNOR
20600 45 5d 20 74 6f 20 64 69 73 61 6c 6c 6f 77 20 74  E] to disallow t
20610 68 65 0a 2a 2a 20 73 70 65 63 69 66 69 63 20 61  he.** specific a
20620 63 74 69 6f 6e 20 62 75 74 20 61 6c 6c 6f 77 20  ction but allow 
20630 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  the SQL statemen
20640 74 20 74 6f 20 63 6f 6e 74 69 6e 75 65 20 74 6f  t to continue to
20650 20 62 65 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 2c   be.** compiled,
20660 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59   or [SQLITE_DENY
20670 5d 20 74 6f 20 63 61 75 73 65 20 74 68 65 20 65  ] to cause the e
20680 6e 74 69 72 65 20 53 51 4c 20 73 74 61 74 65 6d  ntire SQL statem
20690 65 6e 74 20 74 6f 20 62 65 0a 2a 2a 20 72 65 6a  ent to be.** rej
206a0 65 63 74 65 64 20 77 69 74 68 20 61 6e 20 65 72  ected with an er
206b0 72 6f 72 2e 20 20 5e 49 66 20 74 68 65 20 61 75  ror.  ^If the au
206c0 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
206d0 6b 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 6e 79  k returns.** any
206e0 20 76 61 6c 75 65 20 6f 74 68 65 72 20 74 68 61   value other tha
206f0 6e 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45  n [SQLITE_IGNORE
20700 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20  ], [SQLITE_OK], 
20710 6f 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d  or [SQLITE_DENY]
20720 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 5b 73 71  .** then the [sq
20730 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
20740 28 29 5d 20 6f 72 20 65 71 75 69 76 61 6c 65 6e  ()] or equivalen
20750 74 20 63 61 6c 6c 20 74 68 61 74 20 74 72 69 67  t call that trig
20760 67 65 72 65 64 0a 2a 2a 20 74 68 65 20 61 75 74  gered.** the aut
20770 68 6f 72 69 7a 65 72 20 77 69 6c 6c 20 66 61 69  horizer will fai
20780 6c 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20  l with an error 
20790 6d 65 73 73 61 67 65 2e 0a 2a 2a 0a 2a 2a 20 57  message..**.** W
207a0 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  hen the callback
207b0 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
207c0 5f 4f 4b 5d 2c 20 74 68 61 74 20 6d 65 61 6e 73  _OK], that means
207d0 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 0a 2a   the operation.*
207e0 2a 20 72 65 71 75 65 73 74 65 64 20 69 73 20 6f  * requested is o
207f0 6b 2e 20 20 5e 57 68 65 6e 20 74 68 65 20 63 61  k.  ^When the ca
20800 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b  llback returns [
20810 53 51 4c 49 54 45 5f 44 45 4e 59 5d 2c 20 74 68  SQLITE_DENY], th
20820 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72  e.** [sqlite3_pr
20830 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 65  epare_v2()] or e
20840 71 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c 20 74  quivalent call t
20850 68 61 74 20 74 72 69 67 67 65 72 65 64 20 74 68  hat triggered th
20860 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 72 20  e.** authorizer 
20870 77 69 6c 6c 20 66 61 69 6c 20 77 69 74 68 20 61  will fail with a
20880 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20  n error message 
20890 65 78 70 6c 61 69 6e 69 6e 67 20 74 68 61 74 0a  explaining that.
208a0 2a 2a 20 61 63 63 65 73 73 20 69 73 20 64 65 6e  ** access is den
208b0 69 65 64 2e 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ied. .**.** ^The
208c0 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
208d0 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a   to the authoriz
208e0 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61  er callback is a
208f0 20 63 6f 70 79 20 6f 66 20 74 68 65 20 74 68 69   copy of the thi
20900 72 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20  rd.** parameter 
20910 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73  to the sqlite3_s
20920 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 20  et_authorizer() 
20930 69 6e 74 65 72 66 61 63 65 2e 20 5e 54 68 65 20  interface. ^The 
20940 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
20950 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c 62  .** to the callb
20960 61 63 6b 20 69 73 20 61 6e 20 69 6e 74 65 67 65  ack is an intege
20970 72 20 5b 53 51 4c 49 54 45 5f 43 4f 50 59 20 7c  r [SQLITE_COPY |
20980 20 61 63 74 69 6f 6e 20 63 6f 64 65 5d 20 74 68   action code] th
20990 61 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20  at specifies.** 
209a0 74 68 65 20 70 61 72 74 69 63 75 6c 61 72 20 61  the particular a
209b0 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 75 74 68  ction to be auth
209c0 6f 72 69 7a 65 64 2e 20 5e 54 68 65 20 74 68 69  orized. ^The thi
209d0 72 64 20 74 68 72 6f 75 67 68 20 73 69 78 74 68  rd through sixth
209e0 20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 74   parameters.** t
209f0 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 61  o the callback a
20a00 72 65 20 65 69 74 68 65 72 20 4e 55 4c 4c 20 70  re either NULL p
20a10 6f 69 6e 74 65 72 73 20 6f 72 20 7a 65 72 6f 2d  ointers or zero-
20a20 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72 69 6e  terminated strin
20a30 67 73 0a 2a 2a 20 74 68 61 74 20 63 6f 6e 74 61  gs.** that conta
20a40 69 6e 20 61 64 64 69 74 69 6f 6e 61 6c 20 64 65  in additional de
20a50 74 61 69 6c 73 20 61 62 6f 75 74 20 74 68 65 20  tails about the 
20a60 61 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 75 74  action to be aut
20a70 68 6f 72 69 7a 65 64 2e 0a 2a 2a 20 41 70 70 6c  horized..** Appl
20a80 69 63 61 74 69 6f 6e 73 20 6d 75 73 74 20 61 6c  ications must al
20a90 77 61 79 73 20 62 65 20 70 72 65 70 61 72 65 64  ways be prepared
20aa0 20 74 6f 20 65 6e 63 6f 75 6e 74 65 72 20 61 20   to encounter a 
20ab0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 6e 20  NULL pointer in 
20ac0 61 6e 79 0a 2a 2a 20 6f 66 20 74 68 65 20 74 68  any.** of the th
20ad0 69 72 64 20 74 68 72 6f 75 67 68 20 74 68 65 20  ird through the 
20ae0 73 69 78 74 68 20 70 61 72 61 6d 65 74 65 72 73  sixth parameters
20af0 20 6f 66 20 74 68 65 20 61 75 74 68 6f 72 69 7a   of the authoriz
20b00 61 74 69 6f 6e 20 63 61 6c 6c 62 61 63 6b 2e 0a  ation callback..
20b10 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 61 63  **.** ^If the ac
20b20 74 69 6f 6e 20 63 6f 64 65 20 69 73 20 5b 53 51  tion code is [SQ
20b30 4c 49 54 45 5f 52 45 41 44 5d 0a 2a 2a 20 61 6e  LITE_READ].** an
20b40 64 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72  d the callback r
20b50 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 49  eturns [SQLITE_I
20b60 47 4e 4f 52 45 5d 20 74 68 65 6e 20 74 68 65 0a  GNORE] then the.
20b70 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  ** [prepared sta
20b80 74 65 6d 65 6e 74 5d 20 73 74 61 74 65 6d 65 6e  tement] statemen
20b90 74 20 69 73 20 63 6f 6e 73 74 72 75 63 74 65 64  t is constructed
20ba0 20 74 6f 20 73 75 62 73 74 69 74 75 74 65 0a 2a   to substitute.*
20bb0 2a 20 61 20 4e 55 4c 4c 20 76 61 6c 75 65 20 69  * a NULL value i
20bc0 6e 20 70 6c 61 63 65 20 6f 66 20 74 68 65 20 74  n place of the t
20bd0 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74  able column that
20be0 20 77 6f 75 6c 64 20 68 61 76 65 0a 2a 2a 20 62   would have.** b
20bf0 65 65 6e 20 72 65 61 64 20 69 66 20 5b 53 51 4c  een read if [SQL
20c00 49 54 45 5f 4f 4b 5d 20 68 61 64 20 62 65 65 6e  ITE_OK] had been
20c10 20 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65 20   returned.  The 
20c20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 0a  [SQLITE_IGNORE].
20c30 2a 2a 20 72 65 74 75 72 6e 20 63 61 6e 20 62 65  ** return can be
20c40 20 75 73 65 64 20 74 6f 20 64 65 6e 79 20 61 6e   used to deny an
20c50 20 75 6e 74 72 75 73 74 65 64 20 75 73 65 72 20   untrusted user 
20c60 61 63 63 65 73 73 20 74 6f 20 69 6e 64 69 76 69  access to indivi
20c70 64 75 61 6c 0a 2a 2a 20 63 6f 6c 75 6d 6e 73 20  dual.** columns 
20c80 6f 66 20 61 20 74 61 62 6c 65 2e 0a 2a 2a 20 5e  of a table..** ^
20c90 57 68 65 6e 20 61 20 74 61 62 6c 65 20 69 73 20  When a table is 
20ca0 72 65 66 65 72 65 6e 63 65 64 20 62 79 20 61 20  referenced by a 
20cb0 5b 53 45 4c 45 43 54 5d 20 62 75 74 20 6e 6f 20  [SELECT] but no 
20cc0 63 6f 6c 75 6d 6e 20 76 61 6c 75 65 73 20 61 72  column values ar
20cd0 65 0a 2a 2a 20 65 78 74 72 61 63 74 65 64 20 66  e.** extracted f
20ce0 72 6f 6d 20 74 68 61 74 20 74 61 62 6c 65 20 28  rom that table (
20cf0 66 6f 72 20 65 78 61 6d 70 6c 65 20 69 6e 20 61  for example in a
20d00 20 71 75 65 72 79 20 6c 69 6b 65 0a 2a 2a 20 22   query like.** "
20d10 53 45 4c 45 43 54 20 63 6f 75 6e 74 28 2a 29 20  SELECT count(*) 
20d20 46 52 4f 4d 20 74 61 62 22 29 20 74 68 65 6e 20  FROM tab") then 
20d30 74 68 65 20 5b 53 51 4c 49 54 45 5f 52 45 41 44  the [SQLITE_READ
20d40 5d 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  ] authorizer cal
20d50 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 69 6e 76 6f  lback.** is invo
20d60 6b 65 64 20 6f 6e 63 65 20 66 6f 72 20 74 68 61  ked once for tha
20d70 74 20 74 61 62 6c 65 20 77 69 74 68 20 61 20 63  t table with a c
20d80 6f 6c 75 6d 6e 20 6e 61 6d 65 20 74 68 61 74 20  olumn name that 
20d90 69 73 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69  is an empty stri
20da0 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 61  ng..** ^If the a
20db0 63 74 69 6f 6e 20 63 6f 64 65 20 69 73 20 5b 53  ction code is [S
20dc0 51 4c 49 54 45 5f 44 45 4c 45 54 45 5d 20 61 6e  QLITE_DELETE] an
20dd0 64 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72  d the callback r
20de0 65 74 75 72 6e 73 0a 2a 2a 20 5b 53 51 4c 49 54  eturns.** [SQLIT
20df0 45 5f 49 47 4e 4f 52 45 5d 20 74 68 65 6e 20 74  E_IGNORE] then t
20e00 68 65 20 5b 44 45 4c 45 54 45 5d 20 6f 70 65 72  he [DELETE] oper
20e10 61 74 69 6f 6e 20 70 72 6f 63 65 65 64 73 20 62  ation proceeds b
20e20 75 74 20 74 68 65 0a 2a 2a 20 5b 74 72 75 6e 63  ut the.** [trunc
20e30 61 74 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e  ate optimization
20e40 5d 20 69 73 20 64 69 73 61 62 6c 65 64 20 61 6e  ] is disabled an
20e50 64 20 61 6c 6c 20 72 6f 77 73 20 61 72 65 20 64  d all rows are d
20e60 65 6c 65 74 65 64 20 69 6e 64 69 76 69 64 75 61  eleted individua
20e70 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 61 75  lly..**.** An au
20e80 74 68 6f 72 69 7a 65 72 20 69 73 20 75 73 65 64  thorizer is used
20e90 20 77 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70   when [sqlite3_p
20ea0 72 65 70 61 72 65 20 7c 20 70 72 65 70 61 72 69  repare | prepari
20eb0 6e 67 5d 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65  ng].** SQL state
20ec0 6d 65 6e 74 73 20 66 72 6f 6d 20 61 6e 20 75 6e  ments from an un
20ed0 74 72 75 73 74 65 64 20 73 6f 75 72 63 65 2c 20  trusted source, 
20ee0 74 6f 20 65 6e 73 75 72 65 20 74 68 61 74 20 74  to ensure that t
20ef0 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
20f00 73 0a 2a 2a 20 64 6f 20 6e 6f 74 20 74 72 79 20  s.** do not try 
20f10 74 6f 20 61 63 63 65 73 73 20 64 61 74 61 20 74  to access data t
20f20 68 65 79 20 61 72 65 20 6e 6f 74 20 61 6c 6c 6f  hey are not allo
20f30 77 65 64 20 74 6f 20 73 65 65 2c 20 6f 72 20 74  wed to see, or t
20f40 68 61 74 20 74 68 65 79 20 64 6f 20 6e 6f 74 0a  hat they do not.
20f50 2a 2a 20 74 72 79 20 74 6f 20 65 78 65 63 75 74  ** try to execut
20f60 65 20 6d 61 6c 69 63 69 6f 75 73 20 73 74 61 74  e malicious stat
20f70 65 6d 65 6e 74 73 20 74 68 61 74 20 64 61 6d 61  ements that dama
20f80 67 65 20 74 68 65 20 64 61 74 61 62 61 73 65 2e  ge the database.
20f90 20 20 46 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c 65    For.** example
20fa0 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  , an application
20fb0 20 6d 61 79 20 61 6c 6c 6f 77 20 61 20 75 73 65   may allow a use
20fc0 72 20 74 6f 20 65 6e 74 65 72 20 61 72 62 69 74  r to enter arbit
20fd0 72 61 72 79 0a 2a 2a 20 53 51 4c 20 71 75 65 72  rary.** SQL quer
20fe0 69 65 73 20 66 6f 72 20 65 76 61 6c 75 61 74 69  ies for evaluati
20ff0 6f 6e 20 62 79 20 61 20 64 61 74 61 62 61 73 65  on by a database
21000 2e 20 20 42 75 74 20 74 68 65 20 61 70 70 6c 69  .  But the appli
21010 63 61 74 69 6f 6e 20 64 6f 65 73 0a 2a 2a 20 6e  cation does.** n
21020 6f 74 20 77 61 6e 74 20 74 68 65 20 75 73 65 72  ot want the user
21030 20 74 6f 20 62 65 20 61 62 6c 65 20 74 6f 20 6d   to be able to m
21040 61 6b 65 20 61 72 62 69 74 72 61 72 79 20 63 68  ake arbitrary ch
21050 61 6e 67 65 73 20 74 6f 20 74 68 65 0a 2a 2a 20  anges to the.** 
21060 64 61 74 61 62 61 73 65 2e 20 20 41 6e 20 61 75  database.  An au
21070 74 68 6f 72 69 7a 65 72 20 63 6f 75 6c 64 20 74  thorizer could t
21080 68 65 6e 20 62 65 20 70 75 74 20 69 6e 20 70 6c  hen be put in pl
21090 61 63 65 20 77 68 69 6c 65 20 74 68 65 0a 2a 2a  ace while the.**
210a0 20 75 73 65 72 2d 65 6e 74 65 72 65 64 20 53 51   user-entered SQ
210b0 4c 20 69 73 20 62 65 69 6e 67 20 5b 73 71 6c 69  L is being [sqli
210c0 74 65 33 5f 70 72 65 70 61 72 65 20 7c 20 70 72  te3_prepare | pr
210d0 65 70 61 72 65 64 5d 20 74 68 61 74 0a 2a 2a 20  epared] that.** 
210e0 64 69 73 61 6c 6c 6f 77 73 20 65 76 65 72 79 74  disallows everyt
210f0 68 69 6e 67 20 65 78 63 65 70 74 20 5b 53 45 4c  hing except [SEL
21100 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 73 2e  ECT] statements.
21110 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69  .**.** Applicati
21120 6f 6e 73 20 74 68 61 74 20 6e 65 65 64 20 74 6f  ons that need to
21130 20 70 72 6f 63 65 73 73 20 53 51 4c 20 66 72 6f   process SQL fro
21140 6d 20 75 6e 74 72 75 73 74 65 64 20 73 6f 75 72  m untrusted sour
21150 63 65 73 0a 2a 2a 20 6d 69 67 68 74 20 61 6c 73  ces.** might als
21160 6f 20 63 6f 6e 73 69 64 65 72 20 6c 6f 77 65 72  o consider lower
21170 69 6e 67 20 72 65 73 6f 75 72 63 65 20 6c 69 6d  ing resource lim
21180 69 74 73 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  its using [sqlit
21190 65 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 61  e3_limit()].** a
211a0 6e 64 20 6c 69 6d 69 74 69 6e 67 20 64 61 74 61  nd limiting data
211b0 62 61 73 65 20 73 69 7a 65 20 75 73 69 6e 67 20  base size using 
211c0 74 68 65 20 5b 6d 61 78 5f 70 61 67 65 5f 63 6f  the [max_page_co
211d0 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d 0a 2a 2a  unt] [PRAGMA].**
211e0 20 69 6e 20 61 64 64 69 74 69 6f 6e 20 74 6f 20   in addition to 
211f0 75 73 69 6e 67 20 61 6e 20 61 75 74 68 6f 72 69  using an authori
21200 7a 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 4f 6e 6c  zer..**.** ^(Onl
21210 79 20 61 20 73 69 6e 67 6c 65 20 61 75 74 68 6f  y a single autho
21220 72 69 7a 65 72 20 63 61 6e 20 62 65 20 69 6e 20  rizer can be in 
21230 70 6c 61 63 65 20 6f 6e 20 61 20 64 61 74 61 62  place on a datab
21240 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a  ase connection.*
21250 2a 20 61 74 20 61 20 74 69 6d 65 2e 20 20 45 61  * at a time.  Ea
21260 63 68 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74  ch call to sqlit
21270 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65  e3_set_authorize
21280 72 20 6f 76 65 72 72 69 64 65 73 20 74 68 65 0a  r overrides the.
21290 2a 2a 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c  ** previous call
212a0 2e 29 5e 20 20 5e 44 69 73 61 62 6c 65 20 74 68  .)^  ^Disable th
212b0 65 20 61 75 74 68 6f 72 69 7a 65 72 20 62 79 20  e authorizer by 
212c0 69 6e 73 74 61 6c 6c 69 6e 67 20 61 20 4e 55 4c  installing a NUL
212d0 4c 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 54  L callback..** T
212e0 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 69 73  he authorizer is
212f0 20 64 69 73 61 62 6c 65 64 20 62 79 20 64 65 66   disabled by def
21300 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ault..**.** The 
21310 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
21320 61 63 6b 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20  ack must not do 
21330 61 6e 79 74 68 69 6e 67 20 74 68 61 74 20 77 69  anything that wi
21340 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65  ll modify.** the
21350 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
21360 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65  tion that invoke
21370 64 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72  d the authorizer
21380 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 4e 6f   callback..** No
21390 74 65 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33  te that [sqlite3
213a0 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61  _prepare_v2()] a
213b0 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  nd [sqlite3_step
213c0 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79 20  ()] both modify 
213d0 74 68 65 69 72 0a 2a 2a 20 64 61 74 61 62 61 73  their.** databas
213e0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f  e connections fo
213f0 72 20 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66  r the meaning of
21400 20 22 6d 6f 64 69 66 79 22 20 69 6e 20 74 68 69   "modify" in thi
21410 73 20 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a  s paragraph..**.
21420 2a 2a 20 5e 57 68 65 6e 20 5b 73 71 6c 69 74 65  ** ^When [sqlite
21430 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
21440 69 73 20 75 73 65 64 20 74 6f 20 70 72 65 70 61  is used to prepa
21450 72 65 20 61 20 73 74 61 74 65 6d 65 6e 74 2c 20  re a statement, 
21460 74 68 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74  the.** statement
21470 20 6d 69 67 68 74 20 62 65 20 72 65 2d 70 72 65   might be re-pre
21480 70 61 72 65 64 20 64 75 72 69 6e 67 20 5b 73 71  pared during [sq
21490 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 64 75  lite3_step()] du
214a0 65 20 74 6f 20 61 20 0a 2a 2a 20 73 63 68 65 6d  e to a .** schem
214b0 61 20 63 68 61 6e 67 65 2e 20 20 48 65 6e 63 65  a change.  Hence
214c0 2c 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  , the applicatio
214d0 6e 20 73 68 6f 75 6c 64 20 65 6e 73 75 72 65 20  n should ensure 
214e0 74 68 61 74 20 74 68 65 0a 2a 2a 20 63 6f 72 72  that the.** corr
214f0 65 63 74 20 61 75 74 68 6f 72 69 7a 65 72 20 63  ect authorizer c
21500 61 6c 6c 62 61 63 6b 20 72 65 6d 61 69 6e 73 20  allback remains 
21510 69 6e 20 70 6c 61 63 65 20 64 75 72 69 6e 67 20  in place during 
21520 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  the [sqlite3_ste
21530 70 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 4e 6f 74  p()]..**.** ^Not
21540 65 20 74 68 61 74 20 74 68 65 20 61 75 74 68 6f  e that the autho
21550 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69  rizer callback i
21560 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 6c 79 20 64  s invoked only d
21570 75 72 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65  uring.** [sqlite
21580 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20  3_prepare()] or 
21590 69 74 73 20 76 61 72 69 61 6e 74 73 2e 20 20 41  its variants.  A
215a0 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 69 73 20  uthorization is 
215b0 6e 6f 74 0a 2a 2a 20 70 65 72 66 6f 72 6d 65 64  not.** performed
215c0 20 64 75 72 69 6e 67 20 73 74 61 74 65 6d 65 6e   during statemen
215d0 74 20 65 76 61 6c 75 61 74 69 6f 6e 20 69 6e 20  t evaluation in 
215e0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
215f0 2c 20 75 6e 6c 65 73 73 0a 2a 2a 20 61 73 20 73  , unless.** as s
21600 74 61 74 65 64 20 69 6e 20 74 68 65 20 70 72 65  tated in the pre
21610 76 69 6f 75 73 20 70 61 72 61 67 72 61 70 68 2c  vious paragraph,
21620 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20   sqlite3_step() 
21630 69 6e 76 6f 6b 65 73 0a 2a 2a 20 73 71 6c 69 74  invokes.** sqlit
21640 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 20  e3_prepare_v2() 
21650 74 6f 20 72 65 70 72 65 70 61 72 65 20 61 20 73  to reprepare a s
21660 74 61 74 65 6d 65 6e 74 20 61 66 74 65 72 20 61  tatement after a
21670 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65 2e 0a   schema change..
21680 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  */.SQLITE_API in
21690 74 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75  t sqlite3_set_au
216a0 74 68 6f 72 69 7a 65 72 28 0a 20 20 73 71 6c 69  thorizer(.  sqli
216b0 74 65 33 2a 2c 0a 20 20 69 6e 74 20 28 2a 78 41  te3*,.  int (*xA
216c0 75 74 68 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63  uth)(void*,int,c
216d0 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74  onst char*,const
216e0 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61   char*,const cha
216f0 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c  r*,const char*),
21700 0a 20 20 76 6f 69 64 20 2a 70 55 73 65 72 44 61  .  void *pUserDa
21710 74 61 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ta.);../*.** CAP
21720 49 33 52 45 46 3a 20 41 75 74 68 6f 72 69 7a 65  I3REF: Authorize
21730 72 20 52 65 74 75 72 6e 20 43 6f 64 65 73 0a 2a  r Return Codes.*
21740 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65  *.** The [sqlite
21750 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72  3_set_authorizer
21760 20 7c 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61   | authorizer ca
21770 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 5d  llback function]
21780 20 6d 75 73 74 0a 2a 2a 20 72 65 74 75 72 6e 20   must.** return 
21790 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 4f  either [SQLITE_O
217a0 4b 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65  K] or one of the
217b0 73 65 20 74 77 6f 20 63 6f 6e 73 74 61 6e 74 73  se two constants
217c0 20 69 6e 20 6f 72 64 65 72 0a 2a 2a 20 74 6f 20   in order.** to 
217d0 73 69 67 6e 61 6c 20 53 51 4c 69 74 65 20 77 68  signal SQLite wh
217e0 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65  ether or not the
217f0 20 61 63 74 69 6f 6e 20 69 73 20 70 65 72 6d 69   action is permi
21800 74 74 65 64 2e 20 20 53 65 65 20 74 68 65 0a 2a  tted.  See the.*
21810 2a 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  * [sqlite3_set_a
21820 75 74 68 6f 72 69 7a 65 72 20 7c 20 61 75 74 68  uthorizer | auth
21830 6f 72 69 7a 65 72 20 64 6f 63 75 6d 65 6e 74 61  orizer documenta
21840 74 69 6f 6e 5d 20 66 6f 72 20 61 64 64 69 74 69  tion] for additi
21850 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74  onal.** informat
21860 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20  ion..**.** Note 
21870 74 68 61 74 20 53 51 4c 49 54 45 5f 49 47 4e 4f  that SQLITE_IGNO
21880 52 45 20 69 73 20 61 6c 73 6f 20 75 73 65 64 20  RE is also used 
21890 61 73 20 61 20 5b 63 6f 6e 66 6c 69 63 74 20 72  as a [conflict r
218a0 65 73 6f 6c 75 74 69 6f 6e 20 6d 6f 64 65 5d 0a  esolution mode].
218b0 2a 2a 20 72 65 74 75 72 6e 65 64 20 66 72 6f 6d  ** returned from
218c0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 74   the [sqlite3_vt
218d0 61 62 5f 6f 6e 5f 63 6f 6e 66 6c 69 63 74 28 29  ab_on_conflict()
218e0 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2f 0a  ] interface..*/.
218f0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
21900 45 4e 59 20 20 20 31 20 20 20 2f 2a 20 41 62 6f  ENY   1   /* Abo
21910 72 74 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  rt the SQL state
21920 6d 65 6e 74 20 77 69 74 68 20 61 6e 20 65 72 72  ment with an err
21930 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  or */.#define SQ
21940 4c 49 54 45 5f 49 47 4e 4f 52 45 20 32 20 20 20  LITE_IGNORE 2   
21950 2f 2a 20 44 6f 6e 27 74 20 61 6c 6c 6f 77 20 61  /* Don't allow a
21960 63 63 65 73 73 2c 20 62 75 74 20 64 6f 6e 27 74  ccess, but don't
21970 20 67 65 6e 65 72 61 74 65 20 61 6e 20 65 72 72   generate an err
21980 6f 72 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  or */../*.** CAP
21990 49 33 52 45 46 3a 20 41 75 74 68 6f 72 69 7a 65  I3REF: Authorize
219a0 72 20 41 63 74 69 6f 6e 20 43 6f 64 65 73 0a 2a  r Action Codes.*
219b0 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65  *.** The [sqlite
219c0 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72  3_set_authorizer
219d0 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65  ()] interface re
219e0 67 69 73 74 65 72 73 20 61 20 63 61 6c 6c 62 61  gisters a callba
219f0 63 6b 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 74  ck function.** t
21a00 68 61 74 20 69 73 20 69 6e 76 6f 6b 65 64 20 74  hat is invoked t
21a10 6f 20 61 75 74 68 6f 72 69 7a 65 20 63 65 72 74  o authorize cert
21a20 61 69 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ain SQL statemen
21a30 74 20 61 63 74 69 6f 6e 73 2e 20 20 54 68 65 0a  t actions.  The.
21a40 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  ** second parame
21a50 74 65 72 20 74 6f 20 74 68 65 20 63 61 6c 6c 62  ter to the callb
21a60 61 63 6b 20 69 73 20 61 6e 20 69 6e 74 65 67 65  ack is an intege
21a70 72 20 63 6f 64 65 20 74 68 61 74 20 73 70 65 63  r code that spec
21a80 69 66 69 65 73 0a 2a 2a 20 77 68 61 74 20 61 63  ifies.** what ac
21a90 74 69 6f 6e 20 69 73 20 62 65 69 6e 67 20 61 75  tion is being au
21aa0 74 68 6f 72 69 7a 65 64 2e 20 20 54 68 65 73 65  thorized.  These
21ab0 20 61 72 65 20 74 68 65 20 69 6e 74 65 67 65 72   are the integer
21ac0 20 61 63 74 69 6f 6e 20 63 6f 64 65 73 20 74 68   action codes th
21ad0 61 74 0a 2a 2a 20 74 68 65 20 61 75 74 68 6f 72  at.** the author
21ae0 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d 61  izer callback ma
21af0 79 20 62 65 20 70 61 73 73 65 64 2e 0a 2a 2a 0a  y be passed..**.
21b00 2a 2a 20 54 68 65 73 65 20 61 63 74 69 6f 6e 20  ** These action 
21b10 63 6f 64 65 20 76 61 6c 75 65 73 20 73 69 67 6e  code values sign
21b20 69 66 79 20 77 68 61 74 20 6b 69 6e 64 20 6f 66  ify what kind of
21b30 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 74 6f   operation is to
21b40 20 62 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65   be.** authorize
21b50 64 2e 20 20 54 68 65 20 33 72 64 20 61 6e 64 20  d.  The 3rd and 
21b60 34 74 68 20 70 61 72 61 6d 65 74 65 72 73 20 74  4th parameters t
21b70 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a 61 74  o the authorizat
21b80 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20  ion.** callback 
21b90 66 75 6e 63 74 69 6f 6e 20 77 69 6c 6c 20 62 65  function will be
21ba0 20 70 61 72 61 6d 65 74 65 72 73 20 6f 72 20 4e   parameters or N
21bb0 55 4c 4c 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e  ULL depending on
21bc0 20 77 68 69 63 68 20 6f 66 20 74 68 65 73 65 0a   which of these.
21bd0 2a 2a 20 63 6f 64 65 73 20 69 73 20 75 73 65 64  ** codes is used
21be0 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70   as the second p
21bf0 61 72 61 6d 65 74 65 72 2e 20 20 5e 28 54 68 65  arameter.  ^(The
21c00 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 74   5th parameter t
21c10 6f 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f 72 69  o the.** authori
21c20 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  zer callback is 
21c30 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
21c40 64 61 74 61 62 61 73 65 20 28 22 6d 61 69 6e 22  database ("main"
21c50 2c 20 22 74 65 6d 70 22 2c 0a 2a 2a 20 65 74 63  , "temp",.** etc
21c60 2e 29 20 69 66 20 61 70 70 6c 69 63 61 62 6c 65  .) if applicable
21c70 2e 29 5e 20 20 5e 54 68 65 20 36 74 68 20 70 61  .)^  ^The 6th pa
21c80 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61  rameter to the a
21c90 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
21ca0 63 6b 0a 2a 2a 20 69 73 20 74 68 65 20 6e 61 6d  ck.** is the nam
21cb0 65 20 6f 66 20 74 68 65 20 69 6e 6e 65 72 2d 6d  e of the inner-m
21cc0 6f 73 74 20 74 72 69 67 67 65 72 20 6f 72 20 76  ost trigger or v
21cd0 69 65 77 20 74 68 61 74 20 69 73 20 72 65 73 70  iew that is resp
21ce0 6f 6e 73 69 62 6c 65 20 66 6f 72 0a 2a 2a 20 74  onsible for.** t
21cf0 68 65 20 61 63 63 65 73 73 20 61 74 74 65 6d 70  he access attemp
21d00 74 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 69  t or NULL if thi
21d10 73 20 61 63 63 65 73 73 20 61 74 74 65 6d 70 74  s access attempt
21d20 20 69 73 20 64 69 72 65 63 74 6c 79 20 66 72 6f   is directly fro
21d30 6d 0a 2a 2a 20 74 6f 70 2d 6c 65 76 65 6c 20 53  m.** top-level S
21d40 51 4c 20 63 6f 64 65 2e 0a 2a 2f 0a 2f 2a 2a 2a  QL code..*/./***
21d50 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
21d60 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
21d70 2a 2a 2a 2a 2a 2a 2a 2a 20 33 72 64 20 2a 2a 2a  ******** 3rd ***
21d80 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 34 74 68 20 2a 2a  ********* 4th **
21d90 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 23 64 65 66 69  *********/.#defi
21da0 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45  ne SQLITE_CREATE
21db0 5f 49 4e 44 45 58 20 20 20 20 20 20 20 20 20 20  _INDEX          
21dc0 31 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d  1   /* Index Nam
21dd0 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d  e      Table Nam
21de0 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  e      */.#defin
21df0 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f  e SQLITE_CREATE_
21e00 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 32  TABLE          2
21e10 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
21e20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
21e30 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
21e40 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54   SQLITE_CREATE_T
21e50 45 4d 50 5f 49 4e 44 45 58 20 20 20 20 20 33 20  EMP_INDEX     3 
21e60 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20    /* Index Name 
21e70 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20       Table Name 
21e80 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
21e90 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45  SQLITE_CREATE_TE
21ea0 4d 50 5f 54 41 42 4c 45 20 20 20 20 20 34 20 20  MP_TABLE     4  
21eb0 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
21ec0 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
21ed0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
21ee0 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d  QLITE_CREATE_TEM
21ef0 50 5f 54 52 49 47 47 45 52 20 20 20 35 20 20 20  P_TRIGGER   5   
21f00 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20  /* Trigger Name 
21f10 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20     Table Name   
21f20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
21f30 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50  LITE_CREATE_TEMP
21f40 5f 56 49 45 57 20 20 20 20 20 20 36 20 20 20 2f  _VIEW      6   /
21f50 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20  * View Name     
21f60 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
21f70 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
21f80 49 54 45 5f 43 52 45 41 54 45 5f 54 52 49 47 47  ITE_CREATE_TRIGG
21f90 45 52 20 20 20 20 20 20 20 20 37 20 20 20 2f 2a  ER        7   /*
21fa0 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20   Trigger Name   
21fb0 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
21fc0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
21fd0 54 45 5f 43 52 45 41 54 45 5f 56 49 45 57 20 20  TE_CREATE_VIEW  
21fe0 20 20 20 20 20 20 20 20 20 38 20 20 20 2f 2a 20           8   /* 
21ff0 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20  View Name       
22000 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
22010 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
22020 45 5f 44 45 4c 45 54 45 20 20 20 20 20 20 20 20  E_DELETE        
22030 20 20 20 20 20 20 20 20 39 20 20 20 2f 2a 20 54          9   /* T
22040 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e  able Name      N
22050 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
22060 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
22070 5f 44 52 4f 50 5f 49 4e 44 45 58 20 20 20 20 20  _DROP_INDEX     
22080 20 20 20 20 20 20 31 30 20 20 20 2f 2a 20 49 6e        10   /* In
22090 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61  dex Name      Ta
220a0 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f  ble Name      */
220b0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
220c0 44 52 4f 50 5f 54 41 42 4c 45 20 20 20 20 20 20  DROP_TABLE      
220d0 20 20 20 20 20 31 31 20 20 20 2f 2a 20 54 61 62       11   /* Tab
220e0 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c  le Name      NUL
220f0 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
22100 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
22110 52 4f 50 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20  ROP_TEMP_INDEX  
22120 20 20 20 20 31 32 20 20 20 2f 2a 20 49 6e 64 65      12   /* Inde
22130 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c  x Name      Tabl
22140 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23  e Name      */.#
22150 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52  define SQLITE_DR
22160 4f 50 5f 54 45 4d 50 5f 54 41 42 4c 45 20 20 20  OP_TEMP_TABLE   
22170 20 20 20 31 33 20 20 20 2f 2a 20 54 61 62 6c 65     13   /* Table
22180 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20   Name      NULL 
22190 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
221a0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f  efine SQLITE_DRO
221b0 50 5f 54 45 4d 50 5f 54 52 49 47 47 45 52 20 20  P_TEMP_TRIGGER  
221c0 20 20 31 34 20 20 20 2f 2a 20 54 72 69 67 67 65    14   /* Trigge
221d0 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20  r Name    Table 
221e0 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65  Name      */.#de
221f0 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50  fine SQLITE_DROP
22200 5f 54 45 4d 50 5f 56 49 45 57 20 20 20 20 20 20  _TEMP_VIEW      
22210 20 31 35 20 20 20 2f 2a 20 56 69 65 77 20 4e 61   15   /* View Na
22220 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  me       NULL   
22230 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
22240 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f  ine SQLITE_DROP_
22250 54 52 49 47 47 45 52 20 20 20 20 20 20 20 20 20  TRIGGER         
22260 31 36 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20  16   /* Trigger 
22270 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61  Name    Table Na
22280 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  me      */.#defi
22290 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56  ne SQLITE_DROP_V
222a0 49 45 57 20 20 20 20 20 20 20 20 20 20 20 20 31  IEW            1
222b0 37 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65  7   /* View Name
222c0 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20         NULL     
222d0 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
222e0 65 20 53 51 4c 49 54 45 5f 49 4e 53 45 52 54 20  e SQLITE_INSERT 
222f0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31 38                18
22300 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
22310 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
22320 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
22330 20 53 51 4c 49 54 45 5f 50 52 41 47 4d 41 20 20   SQLITE_PRAGMA  
22340 20 20 20 20 20 20 20 20 20 20 20 20 20 31 39 20               19 
22350 20 20 2f 2a 20 50 72 61 67 6d 61 20 4e 61 6d 65    /* Pragma Name
22360 20 20 20 20 20 31 73 74 20 61 72 67 20 6f 72 20       1st arg or 
22370 4e 55 4c 4c 20 2a 2f 0a 23 64 65 66 69 6e 65 20  NULL */.#define 
22380 53 51 4c 49 54 45 5f 52 45 41 44 20 20 20 20 20  SQLITE_READ     
22390 20 20 20 20 20 20 20 20 20 20 20 20 32 30 20 20              20  
223a0 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
223b0 20 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20      Column Name 
223c0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
223d0 51 4c 49 54 45 5f 53 45 4c 45 43 54 20 20 20 20  QLITE_SELECT    
223e0 20 20 20 20 20 20 20 20 20 20 20 32 31 20 20 20             21   
223f0 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20  /* NULL         
22400 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
22410 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
22420 4c 49 54 45 5f 54 52 41 4e 53 41 43 54 49 4f 4e  LITE_TRANSACTION
22430 20 20 20 20 20 20 20 20 20 20 32 32 20 20 20 2f            22   /
22440 2a 20 4f 70 65 72 61 74 69 6f 6e 20 20 20 20 20  * Operation     
22450 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
22460 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
22470 49 54 45 5f 55 50 44 41 54 45 20 20 20 20 20 20  ITE_UPDATE      
22480 20 20 20 20 20 20 20 20 20 32 33 20 20 20 2f 2a           23   /*
22490 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
224a0 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20   Column Name    
224b0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
224c0 54 45 5f 41 54 54 41 43 48 20 20 20 20 20 20 20  TE_ATTACH       
224d0 20 20 20 20 20 20 20 20 32 34 20 20 20 2f 2a 20          24   /* 
224e0 46 69 6c 65 6e 61 6d 65 20 20 20 20 20 20 20 20  Filename        
224f0 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
22500 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
22510 45 5f 44 45 54 41 43 48 20 20 20 20 20 20 20 20  E_DETACH        
22520 20 20 20 20 20 20 20 32 35 20 20 20 2f 2a 20 44         25   /* D
22530 61 74 61 62 61 73 65 20 4e 61 6d 65 20 20 20 4e  atabase Name   N
22540 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
22550 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
22560 5f 41 4c 54 45 52 5f 54 41 42 4c 45 20 20 20 20  _ALTER_TABLE    
22570 20 20 20 20 20 20 32 36 20 20 20 2f 2a 20 44 61        26   /* Da
22580 74 61 62 61 73 65 20 4e 61 6d 65 20 20 20 54 61  tabase Name   Ta
22590 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f  ble Name      */
225a0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
225b0 52 45 49 4e 44 45 58 20 20 20 20 20 20 20 20 20  REINDEX         
225c0 20 20 20 20 20 32 37 20 20 20 2f 2a 20 49 6e 64       27   /* Ind
225d0 65 78 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c  ex Name      NUL
225e0 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
225f0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
22600 4e 41 4c 59 5a 45 20 20 20 20 20 20 20 20 20 20  NALYZE          
22610 20 20 20 20 32 38 20 20 20 2f 2a 20 54 61 62 6c      28   /* Tabl
22620 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c  e Name      NULL
22630 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
22640 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52  define SQLITE_CR
22650 45 41 54 45 5f 56 54 41 42 4c 45 20 20 20 20 20  EATE_VTABLE     
22660 20 20 20 32 39 20 20 20 2f 2a 20 54 61 62 6c 65     29   /* Table
22670 20 4e 61 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c   Name      Modul
22680 65 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64  e Name     */.#d
22690 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f  efine SQLITE_DRO
226a0 50 5f 56 54 41 42 4c 45 20 20 20 20 20 20 20 20  P_VTABLE        
226b0 20 20 33 30 20 20 20 2f 2a 20 54 61 62 6c 65 20    30   /* Table 
226c0 4e 61 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c 65  Name      Module
226d0 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65   Name     */.#de
226e0 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 55 4e 43  fine SQLITE_FUNC
226f0 54 49 4f 4e 20 20 20 20 20 20 20 20 20 20 20 20  TION            
22700 20 33 31 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20   31   /* NULL   
22710 20 20 20 20 20 20 20 20 20 46 75 6e 63 74 69 6f           Functio
22720 6e 20 4e 61 6d 65 20 20 20 2a 2f 0a 23 64 65 66  n Name   */.#def
22730 69 6e 65 20 53 51 4c 49 54 45 5f 53 41 56 45 50  ine SQLITE_SAVEP
22740 4f 49 4e 54 20 20 20 20 20 20 20 20 20 20 20 20  OINT            
22750 33 32 20 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f  32   /* Operatio
22760 6e 20 20 20 20 20 20 20 53 61 76 65 70 6f 69 6e  n       Savepoin
22770 74 20 4e 61 6d 65 20 20 2a 2f 0a 23 64 65 66 69  t Name  */.#defi
22780 6e 65 20 53 51 4c 49 54 45 5f 43 4f 50 59 20 20  ne SQLITE_COPY  
22790 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
227a0 30 20 20 20 2f 2a 20 4e 6f 20 6c 6f 6e 67 65 72  0   /* No longer
227b0 20 75 73 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65   used */.#define
227c0 20 53 51 4c 49 54 45 5f 52 45 43 55 52 53 49 56   SQLITE_RECURSIV
227d0 45 20 20 20 20 20 20 20 20 20 20 20 20 33 33 20  E            33 
227e0 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20    /* NULL       
227f0 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
22800 20 20 20 20 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43       */../*.** C
22810 41 50 49 33 52 45 46 3a 20 54 72 61 63 69 6e 67  API3REF: Tracing
22820 20 41 6e 64 20 50 72 6f 66 69 6c 69 6e 67 20 46   And Profiling F
22830 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 4d 45 54 48  unctions.** METH
22840 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a  OD: sqlite3.**.*
22850 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
22860 20 61 72 65 20 64 65 70 72 65 63 61 74 65 64 2e   are deprecated.
22870 20 55 73 65 20 74 68 65 20 5b 73 71 6c 69 74 65   Use the [sqlite
22880 33 5f 74 72 61 63 65 5f 76 32 28 29 5d 20 69 6e  3_trace_v2()] in
22890 74 65 72 66 61 63 65 0a 2a 2a 20 69 6e 73 74 65  terface.** inste
228a0 61 64 20 6f 66 20 74 68 65 20 72 6f 75 74 69 6e  ad of the routin
228b0 65 73 20 64 65 73 63 72 69 62 65 64 20 68 65 72  es described her
228c0 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  e..**.** These r
228d0 6f 75 74 69 6e 65 73 20 72 65 67 69 73 74 65 72  outines register
228e0 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
228f0 6f 6e 73 20 74 68 61 74 20 63 61 6e 20 62 65 20  ons that can be 
22900 75 73 65 64 20 66 6f 72 0a 2a 2a 20 74 72 61 63  used for.** trac
22910 69 6e 67 20 61 6e 64 20 70 72 6f 66 69 6c 69 6e  ing and profilin
22920 67 20 74 68 65 20 65 78 65 63 75 74 69 6f 6e 20  g the execution 
22930 6f 66 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  of SQL statement
22940 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 61  s..**.** ^The ca
22950 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
22960 72 65 67 69 73 74 65 72 65 64 20 62 79 20 73 71  registered by sq
22970 6c 69 74 65 33 5f 74 72 61 63 65 28 29 20 69 73  lite3_trace() is
22980 20 69 6e 76 6f 6b 65 64 20 61 74 0a 2a 2a 20 76   invoked at.** v
22990 61 72 69 6f 75 73 20 74 69 6d 65 73 20 77 68 65  arious times whe
229a0 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65  n an SQL stateme
229b0 6e 74 20 69 73 20 62 65 69 6e 67 20 72 75 6e 20  nt is being run 
229c0 62 79 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  by [sqlite3_step
229d0 28 29 5d 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ()]..** ^The sql
229e0 69 74 65 33 5f 74 72 61 63 65 28 29 20 63 61 6c  ite3_trace() cal
229f0 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64  lback is invoked
22a00 20 77 69 74 68 20 61 20 55 54 46 2d 38 20 72 65   with a UTF-8 re
22a10 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65 0a 2a  ndering of the.*
22a20 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  * SQL statement 
22a30 74 65 78 74 20 61 73 20 74 68 65 20 73 74 61 74  text as the stat
22a40 65 6d 65 6e 74 20 66 69 72 73 74 20 62 65 67 69  ement first begi
22a50 6e 73 20 65 78 65 63 75 74 69 6e 67 2e 0a 2a 2a  ns executing..**
22a60 20 5e 28 41 64 64 69 74 69 6f 6e 61 6c 20 73 71   ^(Additional sq
22a70 6c 69 74 65 33 5f 74 72 61 63 65 28 29 20 63 61  lite3_trace() ca
22a80 6c 6c 62 61 63 6b 73 20 6d 69 67 68 74 20 6f 63  llbacks might oc
22a90 63 75 72 0a 2a 2a 20 61 73 20 65 61 63 68 20 74  cur.** as each t
22aa0 72 69 67 67 65 72 65 64 20 73 75 62 70 72 6f 67  riggered subprog
22ab0 72 61 6d 20 69 73 20 65 6e 74 65 72 65 64 2e 20  ram is entered. 
22ac0 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 73 20 66   The callbacks f
22ad0 6f 72 20 74 72 69 67 67 65 72 73 0a 2a 2a 20 63  or triggers.** c
22ae0 6f 6e 74 61 69 6e 20 61 20 55 54 46 2d 38 20 53  ontain a UTF-8 S
22af0 51 4c 20 63 6f 6d 6d 65 6e 74 20 74 68 61 74 20  QL comment that 
22b00 69 64 65 6e 74 69 66 69 65 73 20 74 68 65 20 74  identifies the t
22b10 72 69 67 67 65 72 2e 29 5e 0a 2a 2a 0a 2a 2a 20  rigger.)^.**.** 
22b20 54 68 65 20 5b 53 51 4c 49 54 45 5f 54 52 41 43  The [SQLITE_TRAC
22b30 45 5f 53 49 5a 45 5f 4c 49 4d 49 54 5d 20 63 6f  E_SIZE_LIMIT] co
22b40 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
22b50 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  n can be used to
22b60 20 6c 69 6d 69 74 0a 2a 2a 20 74 68 65 20 6c 65   limit.** the le
22b70 6e 67 74 68 20 6f 66 20 5b 62 6f 75 6e 64 20 70  ngth of [bound p
22b80 61 72 61 6d 65 74 65 72 5d 20 65 78 70 61 6e 73  arameter] expans
22b90 69 6f 6e 20 69 6e 20 74 68 65 20 6f 75 74 70 75  ion in the outpu
22ba0 74 20 6f 66 20 73 71 6c 69 74 65 33 5f 74 72 61  t of sqlite3_tra
22bb0 63 65 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ce()..**.** ^The
22bc0 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
22bd0 6f 6e 20 72 65 67 69 73 74 65 72 65 64 20 62 79  on registered by
22be0 20 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65   sqlite3_profile
22bf0 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a  () is invoked.**
22c00 20 61 73 20 65 61 63 68 20 53 51 4c 20 73 74 61   as each SQL sta
22c10 74 65 6d 65 6e 74 20 66 69 6e 69 73 68 65 73 2e  tement finishes.
22c20 20 20 5e 54 68 65 20 70 72 6f 66 69 6c 65 20 63    ^The profile c
22c30 61 6c 6c 62 61 63 6b 20 63 6f 6e 74 61 69 6e 73  allback contains
22c40 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e 61 6c  .** the original
22c50 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20   statement text 
22c60 61 6e 64 20 61 6e 20 65 73 74 69 6d 61 74 65 20  and an estimate 
22c70 6f 66 20 77 61 6c 6c 2d 63 6c 6f 63 6b 20 74 69  of wall-clock ti
22c80 6d 65 0a 2a 2a 20 6f 66 20 68 6f 77 20 6c 6f 6e  me.** of how lon
22c90 67 20 74 68 61 74 20 73 74 61 74 65 6d 65 6e 74  g that statement
22ca0 20 74 6f 6f 6b 20 74 6f 20 72 75 6e 2e 20 20 5e   took to run.  ^
22cb0 54 68 65 20 70 72 6f 66 69 6c 65 20 63 61 6c 6c  The profile call
22cc0 62 61 63 6b 0a 2a 2a 20 74 69 6d 65 20 69 73 20  back.** time is 
22cd0 69 6e 20 75 6e 69 74 73 20 6f 66 20 6e 61 6e 6f  in units of nano
22ce0 73 65 63 6f 6e 64 73 2c 20 68 6f 77 65 76 65 72  seconds, however
22cf0 20 74 68 65 20 63 75 72 72 65 6e 74 20 69 6d 70   the current imp
22d00 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20 69  lementation.** i
22d10 73 20 6f 6e 6c 79 20 63 61 70 61 62 6c 65 20 6f  s only capable o
22d20 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 20 72 65  f millisecond re
22d30 73 6f 6c 75 74 69 6f 6e 20 73 6f 20 74 68 65 20  solution so the 
22d40 73 69 78 20 6c 65 61 73 74 20 73 69 67 6e 69 66  six least signif
22d50 69 63 61 6e 74 0a 2a 2a 20 64 69 67 69 74 73 20  icant.** digits 
22d60 69 6e 20 74 68 65 20 74 69 6d 65 20 61 72 65 20  in the time are 
22d70 6d 65 61 6e 69 6e 67 6c 65 73 73 2e 20 20 46 75  meaningless.  Fu
22d80 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66  ture versions of
22d90 20 53 51 4c 69 74 65 0a 2a 2a 20 6d 69 67 68 74   SQLite.** might
22da0 20 70 72 6f 76 69 64 65 20 67 72 65 61 74 65 72   provide greater
22db0 20 72 65 73 6f 6c 75 74 69 6f 6e 20 6f 6e 20 74   resolution on t
22dc0 68 65 20 70 72 6f 66 69 6c 65 72 20 63 61 6c 6c  he profiler call
22dd0 62 61 63 6b 2e 20 20 54 68 65 0a 2a 2a 20 73 71  back.  The.** sq
22de0 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 29 20  lite3_profile() 
22df0 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 6f 6e 73  function is cons
22e00 69 64 65 72 65 64 20 65 78 70 65 72 69 6d 65 6e  idered experimen
22e10 74 61 6c 20 61 6e 64 20 69 73 0a 2a 2a 20 73 75  tal and is.** su
22e20 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67 65 20  bject to change 
22e30 69 6e 20 66 75 74 75 72 65 20 76 65 72 73 69 6f  in future versio
22e40 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f  ns of SQLite..*/
22e50 0a 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49  .SQLITE_API SQLI
22e60 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 76 6f  TE_DEPRECATED vo
22e70 69 64 20 2a 73 71 6c 69 74 65 33 5f 74 72 61 63  id *sqlite3_trac
22e80 65 28 73 71 6c 69 74 65 33 2a 2c 0a 20 20 20 76  e(sqlite3*,.   v
22e90 6f 69 64 28 2a 78 54 72 61 63 65 29 28 76 6f 69  oid(*xTrace)(voi
22ea0 64 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c  d*,const char*),
22eb0 20 76 6f 69 64 2a 29 3b 0a 53 51 4c 49 54 45 5f   void*);.SQLITE_
22ec0 41 50 49 20 53 51 4c 49 54 45 5f 44 45 50 52 45  API SQLITE_DEPRE
22ed0 43 41 54 45 44 20 76 6f 69 64 20 2a 73 71 6c 69  CATED void *sqli
22ee0 74 65 33 5f 70 72 6f 66 69 6c 65 28 73 71 6c 69  te3_profile(sqli
22ef0 74 65 33 2a 2c 0a 20 20 20 76 6f 69 64 28 2a 78  te3*,.   void(*x
22f00 50 72 6f 66 69 6c 65 29 28 76 6f 69 64 2a 2c 63  Profile)(void*,c
22f10 6f 6e 73 74 20 63 68 61 72 2a 2c 73 71 6c 69 74  onst char*,sqlit
22f20 65 33 5f 75 69 6e 74 36 34 29 2c 20 76 6f 69 64  e3_uint64), void
22f30 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
22f40 52 45 46 3a 20 53 51 4c 20 54 72 61 63 65 20 45  REF: SQL Trace E
22f50 76 65 6e 74 20 43 6f 64 65 73 0a 2a 2a 20 4b 45  vent Codes.** KE
22f60 59 57 4f 52 44 53 3a 20 53 51 4c 49 54 45 5f 54  YWORDS: SQLITE_T
22f70 52 41 43 45 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  RACE.**.** These
22f80 20 63 6f 6e 73 74 61 6e 74 73 20 69 64 65 6e 74   constants ident
22f90 69 66 79 20 63 6c 61 73 73 65 73 20 6f 66 20 65  ify classes of e
22fa0 76 65 6e 74 73 20 74 68 61 74 20 63 61 6e 20 62  vents that can b
22fb0 65 20 6d 6f 6e 69 74 6f 72 65 64 0a 2a 2a 20 75  e monitored.** u
22fc0 73 69 6e 67 20 74 68 65 20 5b 73 71 6c 69 74 65  sing the [sqlite
22fd0 33 5f 74 72 61 63 65 5f 76 32 28 29 5d 20 74 72  3_trace_v2()] tr
22fe0 61 63 69 6e 67 20 6c 6f 67 69 63 2e 20 20 54 68  acing logic.  Th
22ff0 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74  e third argument
23000 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  .** to [sqlite3_
23010 74 72 61 63 65 5f 76 32 28 29 5d 20 69 73 20 61  trace_v2()] is a
23020 6e 20 4f 52 2d 65 64 20 63 6f 6d 62 69 6e 61 74  n OR-ed combinat
23030 69 6f 6e 20 6f 66 20 6f 6e 65 20 6f 72 20 6d 6f  ion of one or mo
23040 72 65 20 6f 66 0a 2a 2a 20 74 68 65 20 66 6f 6c  re of.** the fol
23050 6c 6f 77 69 6e 67 20 63 6f 6e 73 74 61 6e 74 73  lowing constants
23060 2e 20 20 5e 54 68 65 20 66 69 72 73 74 20 61 72  .  ^The first ar
23070 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 74 72  gument to the tr
23080 61 63 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20  ace callback.** 
23090 69 73 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f  is one of the fo
230a0 6c 6c 6f 77 69 6e 67 20 63 6f 6e 73 74 61 6e 74  llowing constant
230b0 73 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 74 72 61  s..**.** New tra
230c0 63 69 6e 67 20 63 6f 6e 73 74 61 6e 74 73 20 6d  cing constants m
230d0 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66  ay be added in f
230e0 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 2e 0a  uture releases..
230f0 2a 2a 0a 2a 2a 20 5e 41 20 74 72 61 63 65 20 63  **.** ^A trace c
23100 61 6c 6c 62 61 63 6b 20 68 61 73 20 66 6f 75 72  allback has four
23110 20 61 72 67 75 6d 65 6e 74 73 3a 20 78 43 61 6c   arguments: xCal
23120 6c 62 61 63 6b 28 54 2c 43 2c 50 2c 58 29 2e 0a  lback(T,C,P,X)..
23130 2a 2a 20 5e 54 68 65 20 54 20 61 72 67 75 6d 65  ** ^The T argume
23140 6e 74 20 69 73 20 6f 6e 65 20 6f 66 20 74 68 65  nt is one of the
23150 20 69 6e 74 65 67 65 72 20 74 79 70 65 20 63 6f   integer type co
23160 64 65 73 20 61 62 6f 76 65 2e 0a 2a 2a 20 5e 54  des above..** ^T
23170 68 65 20 43 20 61 72 67 75 6d 65 6e 74 20 69 73  he C argument is
23180 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 63   a copy of the c
23190 6f 6e 74 65 78 74 20 70 6f 69 6e 74 65 72 20 70  ontext pointer p
231a0 61 73 73 65 64 20 69 6e 20 61 73 20 74 68 65 0a  assed in as the.
231b0 2a 2a 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65  ** fourth argume
231c0 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 74  nt to [sqlite3_t
231d0 72 61 63 65 5f 76 32 28 29 5d 2e 0a 2a 2a 20 54  race_v2()]..** T
231e0 68 65 20 50 20 61 6e 64 20 58 20 61 72 67 75 6d  he P and X argum
231f0 65 6e 74 73 20 61 72 65 20 70 6f 69 6e 74 65 72  ents are pointer
23200 73 20 77 68 6f 73 65 20 6d 65 61 6e 69 6e 67 73  s whose meanings
23210 20 64 65 70 65 6e 64 20 6f 6e 20 54 2e 0a 2a 2a   depend on T..**
23220 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 51  .** <dl>.** [[SQ
23230 4c 49 54 45 5f 54 52 41 43 45 5f 53 54 4d 54 5d  LITE_TRACE_STMT]
23240 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 54 52 41  ] <dt>SQLITE_TRA
23250 43 45 5f 53 54 4d 54 3c 2f 64 74 3e 0a 2a 2a 20  CE_STMT</dt>.** 
23260 3c 64 64 3e 5e 41 6e 20 53 51 4c 49 54 45 5f 54  <dd>^An SQLITE_T
23270 52 41 43 45 5f 53 54 4d 54 20 63 61 6c 6c 62 61  RACE_STMT callba
23280 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 68  ck is invoked wh
23290 65 6e 20 61 20 70 72 65 70 61 72 65 64 20 73 74  en a prepared st
232a0 61 74 65 6d 65 6e 74 0a 2a 2a 20 66 69 72 73 74  atement.** first
232b0 20 62 65 67 69 6e 73 20 72 75 6e 6e 69 6e 67 20   begins running 
232c0 61 6e 64 20 70 6f 73 73 69 62 6c 79 20 61 74 20  and possibly at 
232d0 6f 74 68 65 72 20 74 69 6d 65 73 20 64 75 72 69  other times duri
232e0 6e 67 20 74 68 65 0a 2a 2a 20 65 78 65 63 75 74  ng the.** execut
232f0 69 6f 6e 20 6f 66 20 74 68 65 20 70 72 65 70 61  ion of the prepa
23300 72 65 64 20 73 74 61 74 65 6d 65 6e 74 2c 20 73  red statement, s
23310 75 63 68 20 61 73 20 61 74 20 74 68 65 20 73 74  uch as at the st
23320 61 72 74 20 6f 66 20 65 61 63 68 0a 2a 2a 20 74  art of each.** t
23330 72 69 67 67 65 72 20 73 75 62 70 72 6f 67 72 61  rigger subprogra
23340 6d 2e 20 5e 54 68 65 20 50 20 61 72 67 75 6d 65  m. ^The P argume
23350 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20  nt is a pointer 
23360 74 6f 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61  to the.** [prepa
23370 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20  red statement]. 
23380 5e 54 68 65 20 58 20 61 72 67 75 6d 65 6e 74 20  ^The X argument 
23390 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
233a0 61 20 73 74 72 69 6e 67 20 77 68 69 63 68 0a 2a  a string which.*
233b0 2a 20 69 73 20 74 68 65 20 75 6e 65 78 70 61 6e  * is the unexpan
233c0 64 65 64 20 53 51 4c 20 74 65 78 74 20 6f 66 20  ded SQL text of 
233d0 74 68 65 20 70 72 65 70 61 72 65 64 20 73 74 61  the prepared sta
233e0 74 65 6d 65 6e 74 20 6f 72 20 61 6e 20 53 51 4c  tement or an SQL
233f0 20 63 6f 6d 6d 65 6e 74 20 0a 2a 2a 20 74 68 61   comment .** tha
23400 74 20 69 6e 64 69 63 61 74 65 73 20 74 68 65 20  t indicates the 
23410 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 61 20  invocation of a 
23420 74 72 69 67 67 65 72 2e 20 20 5e 54 68 65 20 63  trigger.  ^The c
23430 61 6c 6c 62 61 63 6b 20 63 61 6e 20 63 6f 6d 70  allback can comp
23440 75 74 65 0a 2a 2a 20 74 68 65 20 73 61 6d 65 20  ute.** the same 
23450 74 65 78 74 20 74 68 61 74 20 77 6f 75 6c 64 20  text that would 
23460 68 61 76 65 20 62 65 65 6e 20 72 65 74 75 72 6e  have been return
23470 65 64 20 62 79 20 74 68 65 20 6c 65 67 61 63 79  ed by the legacy
23480 20 5b 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28   [sqlite3_trace(
23490 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20  )].** interface 
234a0 62 79 20 75 73 69 6e 67 20 74 68 65 20 58 20 61  by using the X a
234b0 72 67 75 6d 65 6e 74 20 77 68 65 6e 20 58 20 62  rgument when X b
234c0 65 67 69 6e 73 20 77 69 74 68 20 22 2d 2d 22 20  egins with "--" 
234d0 61 6e 64 20 69 6e 76 6f 6b 69 6e 67 0a 2a 2a 20  and invoking.** 
234e0 5b 73 71 6c 69 74 65 33 5f 65 78 70 61 6e 64 65  [sqlite3_expande
234f0 64 5f 73 71 6c 28 50 29 5d 20 6f 74 68 65 72 77  d_sql(P)] otherw
23500 69 73 65 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  ise..**.** [[SQL
23510 49 54 45 5f 54 52 41 43 45 5f 50 52 4f 46 49 4c  ITE_TRACE_PROFIL
23520 45 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 54  E]] <dt>SQLITE_T
23530 52 41 43 45 5f 50 52 4f 46 49 4c 45 3c 2f 64 74  RACE_PROFILE</dt
23540 3e 0a 2a 2a 20 3c 64 64 3e 5e 41 6e 20 53 51 4c  >.** <dd>^An SQL
23550 49 54 45 5f 54 52 41 43 45 5f 50 52 4f 46 49 4c  ITE_TRACE_PROFIL
23560 45 20 63 61 6c 6c 62 61 63 6b 20 70 72 6f 76 69  E callback provi
23570 64 65 73 20 61 70 70 72 6f 78 69 6d 61 74 65 6c  des approximatel
23580 79 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 69 6e  y the same.** in
23590 66 6f 72 6d 61 74 69 6f 6e 20 61 73 20 69 73 20  formation as is 
235a0 70 72 6f 76 69 64 65 64 20 62 79 20 74 68 65 20  provided by the 
235b0 5b 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65  [sqlite3_profile
235c0 28 29 5d 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a  ()] callback..**
235d0 20 5e 54 68 65 20 50 20 61 72 67 75 6d 65 6e 74   ^The P argument
235e0 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
235f0 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
23600 74 61 74 65 6d 65 6e 74 5d 20 61 6e 64 20 74 68  tatement] and th
23610 65 0a 2a 2a 20 58 20 61 72 67 75 6d 65 6e 74 20  e.** X argument 
23620 70 6f 69 6e 74 73 20 74 6f 20 61 20 36 34 2d 62  points to a 64-b
23630 69 74 20 69 6e 74 65 67 65 72 20 77 68 69 63 68  it integer which
23640 20 69 73 20 74 68 65 20 65 73 74 69 6d 61 74 65   is the estimate
23650 64 20 6f 66 0a 2a 2a 20 74 68 65 20 6e 75 6d 62  d of.** the numb
23660 65 72 20 6f 66 20 6e 61 6e 6f 73 65 63 6f 6e 64  er of nanosecond
23670 20 74 68 61 74 20 74 68 65 20 70 72 65 70 61 72   that the prepar
23680 65 64 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 6f  ed statement too
23690 6b 20 74 6f 20 72 75 6e 2e 0a 2a 2a 20 5e 54 68  k to run..** ^Th
236a0 65 20 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 50  e SQLITE_TRACE_P
236b0 52 4f 46 49 4c 45 20 63 61 6c 6c 62 61 63 6b 20  ROFILE callback 
236c0 69 73 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20  is invoked when 
236d0 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 66 69  the statement fi
236e0 6e 69 73 68 65 73 2e 0a 2a 2a 0a 2a 2a 20 5b 5b  nishes..**.** [[
236f0 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 52 4f 57  SQLITE_TRACE_ROW
23700 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 54 52  ]] <dt>SQLITE_TR
23710 41 43 45 5f 52 4f 57 3c 2f 64 74 3e 0a 2a 2a 20  ACE_ROW</dt>.** 
23720 3c 64 64 3e 5e 41 6e 20 53 51 4c 49 54 45 5f 54  <dd>^An SQLITE_T
23730 52 41 43 45 5f 52 4f 57 20 63 61 6c 6c 62 61 63  RACE_ROW callbac
23740 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 68 65  k is invoked whe
23750 6e 65 76 65 72 20 61 20 70 72 65 70 61 72 65 64  never a prepared
23760 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 67 65  .** statement ge
23770 6e 65 72 61 74 65 73 20 61 20 73 69 6e 67 6c 65  nerates a single
23780 20 72 6f 77 20 6f 66 20 72 65 73 75 6c 74 2e 20   row of result. 
23790 20 0a 2a 2a 20 5e 54 68 65 20 50 20 61 72 67 75   .** ^The P argu
237a0 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65  ment is a pointe
237b0 72 20 74 6f 20 74 68 65 20 5b 70 72 65 70 61 72  r to the [prepar
237c0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 61 6e  ed statement] an
237d0 64 20 74 68 65 0a 2a 2a 20 58 20 61 72 67 75 6d  d the.** X argum
237e0 65 6e 74 20 69 73 20 75 6e 75 73 65 64 2e 0a 2a  ent is unused..*
237f0 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 54 52  *.** [[SQLITE_TR
23800 41 43 45 5f 43 4c 4f 53 45 5d 5d 20 3c 64 74 3e  ACE_CLOSE]] <dt>
23810 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 43 4c 4f  SQLITE_TRACE_CLO
23820 53 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 5e  SE</dt>.** <dd>^
23830 41 6e 20 53 51 4c 49 54 45 5f 54 52 41 43 45 5f  An SQLITE_TRACE_
23840 43 4c 4f 53 45 20 63 61 6c 6c 62 61 63 6b 20 69  CLOSE callback i
23850 73 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 61  s invoked when a
23860 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e   database.** con
23870 6e 65 63 74 69 6f 6e 20 63 6c 6f 73 65 73 2e 0a  nection closes..
23880 2a 2a 20 5e 54 68 65 20 50 20 61 72 67 75 6d 65  ** ^The P argume
23890 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20  nt is a pointer 
238a0 74 6f 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  to the [database
238b0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 62 6a   connection] obj
238c0 65 63 74 0a 2a 2a 20 61 6e 64 20 74 68 65 20 58  ect.** and the X
238d0 20 61 72 67 75 6d 65 6e 74 20 69 73 20 75 6e 75   argument is unu
238e0 73 65 64 2e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f  sed..** </dl>.*/
238f0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
23900 54 52 41 43 45 5f 53 54 4d 54 20 20 20 20 20 20  TRACE_STMT      
23910 20 30 78 30 31 0a 23 64 65 66 69 6e 65 20 53 51   0x01.#define SQ
23920 4c 49 54 45 5f 54 52 41 43 45 5f 50 52 4f 46 49  LITE_TRACE_PROFI
23930 4c 45 20 20 20 20 30 78 30 32 0a 23 64 65 66 69  LE    0x02.#defi
23940 6e 65 20 53 51 4c 49 54 45 5f 54 52 41 43 45 5f  ne SQLITE_TRACE_
23950 52 4f 57 20 20 20 20 20 20 20 20 30 78 30 34 0a  ROW        0x04.
23960 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54  #define SQLITE_T
23970 52 41 43 45 5f 43 4c 4f 53 45 20 20 20 20 20 20  RACE_CLOSE      
23980 30 78 30 38 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  0x08../*.** CAPI
23990 33 52 45 46 3a 20 53 51 4c 20 54 72 61 63 65 20  3REF: SQL Trace 
239a0 48 6f 6f 6b 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  Hook.** METHOD: 
239b0 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54  sqlite3.**.** ^T
239c0 68 65 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65  he sqlite3_trace
239d0 5f 76 32 28 44 2c 4d 2c 58 2c 50 29 20 69 6e 74  _v2(D,M,X,P) int
239e0 65 72 66 61 63 65 20 72 65 67 69 73 74 65 72 73  erface registers
239f0 20 61 20 74 72 61 63 65 20 63 61 6c 6c 62 61 63   a trace callbac
23a00 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 58 20  k.** function X 
23a10 61 67 61 69 6e 73 74 20 5b 64 61 74 61 62 61 73  against [databas
23a20 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 2c  e connection] D,
23a30 20 75 73 69 6e 67 20 70 72 6f 70 65 72 74 79 20   using property 
23a40 6d 61 73 6b 20 4d 0a 2a 2a 20 61 6e 64 20 63 6f  mask M.** and co
23a50 6e 74 65 78 74 20 70 6f 69 6e 74 65 72 20 50 2e  ntext pointer P.
23a60 20 20 5e 49 66 20 74 68 65 20 58 20 63 61 6c 6c    ^If the X call
23a70 62 61 63 6b 20 69 73 0a 2a 2a 20 4e 55 4c 4c 20  back is.** NULL 
23a80 6f 72 20 69 66 20 74 68 65 20 4d 20 6d 61 73 6b  or if the M mask
23a90 20 69 73 20 7a 65 72 6f 2c 20 74 68 65 6e 20 74   is zero, then t
23aa0 72 61 63 69 6e 67 20 69 73 20 64 69 73 61 62 6c  racing is disabl
23ab0 65 64 2e 20 20 54 68 65 0a 2a 2a 20 4d 20 61 72  ed.  The.** M ar
23ac0 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 62 65  gument should be
23ad0 20 74 68 65 20 62 69 74 77 69 73 65 20 4f 52 2d   the bitwise OR-
23ae0 65 64 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 6f  ed combination o
23af0 66 0a 2a 2a 20 7a 65 72 6f 20 6f 72 20 6d 6f 72  f.** zero or mor
23b00 65 20 5b 53 51 4c 49 54 45 5f 54 52 41 43 45 5d  e [SQLITE_TRACE]
23b10 20 63 6f 6e 73 74 61 6e 74 73 2e 0a 2a 2a 0a 2a   constants..**.*
23b20 2a 20 5e 45 61 63 68 20 63 61 6c 6c 20 74 6f 20  * ^Each call to 
23b30 65 69 74 68 65 72 20 73 71 6c 69 74 65 33 5f 74  either sqlite3_t
23b40 72 61 63 65 28 29 20 6f 72 20 73 71 6c 69 74 65  race() or sqlite
23b50 33 5f 74 72 61 63 65 5f 76 32 28 29 20 6f 76 65  3_trace_v2() ove
23b60 72 72 69 64 65 73 20 0a 2a 2a 20 28 63 61 6e 63  rrides .** (canc
23b70 65 6c 73 29 20 61 6e 79 20 70 72 69 6f 72 20 63  els) any prior c
23b80 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f  alls to sqlite3_
23b90 74 72 61 63 65 28 29 20 6f 72 20 73 71 6c 69 74  trace() or sqlit
23ba0 65 33 5f 74 72 61 63 65 5f 76 32 28 29 2e 0a 2a  e3_trace_v2()..*
23bb0 2a 0a 2a 2a 20 5e 54 68 65 20 58 20 63 61 6c 6c  *.** ^The X call
23bc0 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20  back is invoked 
23bd0 77 68 65 6e 65 76 65 72 20 61 6e 79 20 6f 66 20  whenever any of 
23be0 74 68 65 20 65 76 65 6e 74 73 20 69 64 65 6e 74  the events ident
23bf0 69 66 69 65 64 20 62 79 20 0a 2a 2a 20 6d 61 73  ified by .** mas
23c00 6b 20 4d 20 6f 63 63 75 72 2e 20 20 5e 54 68 65  k M occur.  ^The
23c10 20 69 6e 74 65 67 65 72 20 72 65 74 75 72 6e 20   integer return 
23c20 76 61 6c 75 65 20 66 72 6f 6d 20 74 68 65 20 63  value from the c
23c30 61 6c 6c 62 61 63 6b 20 69 73 20 63 75 72 72 65  allback is curre
23c40 6e 74 6c 79 0a 2a 2a 20 69 67 6e 6f 72 65 64 2c  ntly.** ignored,
23c50 20 74 68 6f 75 67 68 20 74 68 69 73 20 6d 61 79   though this may
23c60 20 63 68 61 6e 67 65 20 69 6e 20 66 75 74 75 72   change in futur
23c70 65 20 72 65 6c 65 61 73 65 73 2e 20 20 43 61 6c  e releases.  Cal
23c80 6c 62 61 63 6b 0a 2a 2a 20 69 6d 70 6c 65 6d 65  lback.** impleme
23c90 6e 74 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20  ntations should 
23ca0 72 65 74 75 72 6e 20 7a 65 72 6f 20 74 6f 20 65  return zero to e
23cb0 6e 73 75 72 65 20 66 75 74 75 72 65 20 63 6f 6d  nsure future com
23cc0 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a 0a 2a  patibility..**.*
23cd0 2a 20 5e 41 20 74 72 61 63 65 20 63 61 6c 6c 62  * ^A trace callb
23ce0 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 77  ack is invoked w
23cf0 69 74 68 20 66 6f 75 72 20 61 72 67 75 6d 65 6e  ith four argumen
23d00 74 73 3a 20 63 61 6c 6c 62 61 63 6b 28 54 2c 43  ts: callback(T,C
23d10 2c 50 2c 58 29 2e 0a 2a 2a 20 5e 54 68 65 20 54  ,P,X)..** ^The T
23d20 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6f 6e 65   argument is one
23d30 20 6f 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f   of the [SQLITE_
23d40 54 52 41 43 45 5d 0a 2a 2a 20 63 6f 6e 73 74 61  TRACE].** consta
23d50 6e 74 73 20 74 6f 20 69 6e 64 69 63 61 74 65 20  nts to indicate 
23d60 77 68 79 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  why the callback
23d70 20 77 61 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a   was invoked..**
23d80 20 5e 54 68 65 20 43 20 61 72 67 75 6d 65 6e 74   ^The C argument
23d90 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68   is a copy of th
23da0 65 20 63 6f 6e 74 65 78 74 20 70 6f 69 6e 74 65  e context pointe
23db0 72 2e 0a 2a 2a 20 54 68 65 20 50 20 61 6e 64 20  r..** The P and 
23dc0 58 20 61 72 67 75 6d 65 6e 74 73 20 61 72 65 20  X arguments are 
23dd0 70 6f 69 6e 74 65 72 73 20 77 68 6f 73 65 20 6d  pointers whose m
23de0 65 61 6e 69 6e 67 73 20 64 65 70 65 6e 64 20 6f  eanings depend o
23df0 6e 20 54 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  n T..**.** The s
23e00 71 6c 69 74 65 33 5f 74 72 61 63 65 5f 76 32 28  qlite3_trace_v2(
23e10 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 69  ) interface is i
23e20 6e 74 65 6e 64 65 64 20 74 6f 20 72 65 70 6c 61  ntended to repla
23e30 63 65 20 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a  ce the legacy.**
23e40 20 69 6e 74 65 72 66 61 63 65 73 20 5b 73 71 6c   interfaces [sql
23e50 69 74 65 33 5f 74 72 61 63 65 28 29 5d 20 61 6e  ite3_trace()] an
23e60 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 6f 66 69  d [sqlite3_profi
23e70 6c 65 28 29 5d 2c 20 62 6f 74 68 20 6f 66 20 77  le()], both of w
23e80 68 69 63 68 0a 2a 2a 20 61 72 65 20 64 65 70 72  hich.** are depr
23e90 65 63 61 74 65 64 2e 0a 2a 2f 0a 53 51 4c 49 54  ecated..*/.SQLIT
23ea0 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
23eb0 33 5f 74 72 61 63 65 5f 76 32 28 0a 20 20 73 71  3_trace_v2(.  sq
23ec0 6c 69 74 65 33 2a 2c 0a 20 20 75 6e 73 69 67 6e  lite3*,.  unsign
23ed0 65 64 20 75 4d 61 73 6b 2c 0a 20 20 69 6e 74 28  ed uMask,.  int(
23ee0 2a 78 43 61 6c 6c 62 61 63 6b 29 28 75 6e 73 69  *xCallback)(unsi
23ef0 67 6e 65 64 2c 76 6f 69 64 2a 2c 76 6f 69 64 2a  gned,void*,void*
23f00 2c 76 6f 69 64 2a 29 2c 0a 20 20 76 6f 69 64 20  ,void*),.  void 
23f10 2a 70 43 74 78 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  *pCtx.);../*.** 
23f20 43 41 50 49 33 52 45 46 3a 20 51 75 65 72 79 20  CAPI3REF: Query 
23f30 50 72 6f 67 72 65 73 73 20 43 61 6c 6c 62 61 63  Progress Callbac
23f40 6b 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  ks.** METHOD: sq
23f50 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  lite3.**.** ^The
23f60 20 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 73   sqlite3_progres
23f70 73 5f 68 61 6e 64 6c 65 72 28 44 2c 4e 2c 58 2c  s_handler(D,N,X,
23f80 50 29 20 69 6e 74 65 72 66 61 63 65 20 63 61 75  P) interface cau
23f90 73 65 73 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  ses the callback
23fa0 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 58 20 74  .** function X t
23fb0 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 70 65 72  o be invoked per
23fc0 69 6f 64 69 63 61 6c 6c 79 20 64 75 72 69 6e 67  iodically during
23fd0 20 6c 6f 6e 67 20 72 75 6e 6e 69 6e 67 20 63 61   long running ca
23fe0 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  lls to.** [sqlit
23ff0 65 33 5f 65 78 65 63 28 29 5d 2c 20 5b 73 71 6c  e3_exec()], [sql
24000 69 74 65 33 5f 73 74 65 70 28 29 5d 20 61 6e 64  ite3_step()] and
24010 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61   [sqlite3_get_ta
24020 62 6c 65 28 29 5d 20 66 6f 72 0a 2a 2a 20 64 61  ble()] for.** da
24030 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
24040 6e 20 44 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65  n D.  An example
24050 20 75 73 65 20 66 6f 72 20 74 68 69 73 0a 2a 2a   use for this.**
24060 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 74 6f   interface is to
24070 20 6b 65 65 70 20 61 20 47 55 49 20 75 70 64 61   keep a GUI upda
24080 74 65 64 20 64 75 72 69 6e 67 20 61 20 6c 61 72  ted during a lar
24090 67 65 20 71 75 65 72 79 2e 0a 2a 2a 0a 2a 2a 20  ge query..**.** 
240a0 5e 54 68 65 20 70 61 72 61 6d 65 74 65 72 20 50  ^The parameter P
240b0 20 69 73 20 70 61 73 73 65 64 20 74 68 72 6f 75   is passed throu
240c0 67 68 20 61 73 20 74 68 65 20 6f 6e 6c 79 20 70  gh as the only p
240d0 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
240e0 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  .** callback fun
240f0 63 74 69 6f 6e 20 58 2e 20 20 5e 54 68 65 20 70  ction X.  ^The p
24100 61 72 61 6d 65 74 65 72 20 4e 20 69 73 20 74 68  arameter N is th
24110 65 20 61 70 70 72 6f 78 69 6d 61 74 65 20 6e 75  e approximate nu
24120 6d 62 65 72 20 6f 66 20 0a 2a 2a 20 5b 76 69 72  mber of .** [vir
24130 74 75 61 6c 20 6d 61 63 68 69 6e 65 20 69 6e 73  tual machine ins
24140 74 72 75 63 74 69 6f 6e 73 5d 20 74 68 61 74 20  tructions] that 
24150 61 72 65 20 65 76 61 6c 75 61 74 65 64 20 62 65  are evaluated be
24160 74 77 65 65 6e 20 73 75 63 63 65 73 73 69 76 65  tween successive
24170 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20  .** invocations 
24180 6f 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  of the callback 
24190 58 2e 20 20 5e 49 66 20 4e 20 69 73 20 6c 65 73  X.  ^If N is les
241a0 73 20 74 68 61 6e 20 6f 6e 65 20 74 68 65 6e 20  s than one then 
241b0 74 68 65 20 70 72 6f 67 72 65 73 73 0a 2a 2a 20  the progress.** 
241c0 68 61 6e 64 6c 65 72 20 69 73 20 64 69 73 61 62  handler is disab
241d0 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 6c 79  led..**.** ^Only
241e0 20 61 20 73 69 6e 67 6c 65 20 70 72 6f 67 72 65   a single progre
241f0 73 73 20 68 61 6e 64 6c 65 72 20 6d 61 79 20 62  ss handler may b
24200 65 20 64 65 66 69 6e 65 64 20 61 74 20 6f 6e 65  e defined at one
24210 20 74 69 6d 65 20 70 65 72 0a 2a 2a 20 5b 64 61   time per.** [da
24220 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
24230 6e 5d 3b 20 73 65 74 74 69 6e 67 20 61 20 6e 65  n]; setting a ne
24240 77 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c  w progress handl
24250 65 72 20 63 61 6e 63 65 6c 73 20 74 68 65 0a 2a  er cancels the.*
24260 2a 20 6f 6c 64 20 6f 6e 65 2e 20 20 5e 53 65 74  * old one.  ^Set
24270 74 69 6e 67 20 70 61 72 61 6d 65 74 65 72 20 58  ting parameter X
24280 20 74 6f 20 4e 55 4c 4c 20 64 69 73 61 62 6c 65   to NULL disable
24290 73 20 74 68 65 20 70 72 6f 67 72 65 73 73 20 68  s the progress h
242a0 61 6e 64 6c 65 72 2e 0a 2a 2a 20 5e 54 68 65 20  andler..** ^The 
242b0 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72  progress handler
242c0 20 69 73 20 61 6c 73 6f 20 64 69 73 61 62 6c 65   is also disable
242d0 64 20 62 79 20 73 65 74 74 69 6e 67 20 4e 20 74  d by setting N t
242e0 6f 20 61 20 76 61 6c 75 65 20 6c 65 73 73 0a 2a  o a value less.*
242f0 2a 20 74 68 61 6e 20 31 2e 0a 2a 2a 0a 2a 2a 20  * than 1..**.** 
24300 5e 49 66 20 74 68 65 20 70 72 6f 67 72 65 73 73  ^If the progress
24310 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e   callback return
24320 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 20  s non-zero, the 
24330 6f 70 65 72 61 74 69 6f 6e 20 69 73 0a 2a 2a 20  operation is.** 
24340 69 6e 74 65 72 72 75 70 74 65 64 2e 20 20 54 68  interrupted.  Th
24350 69 73 20 66 65 61 74 75 72 65 20 63 61 6e 20 62  is feature can b
24360 65 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d  e used to implem
24370 65 6e 74 20 61 0a 2a 2a 20 22 43 61 6e 63 65 6c  ent a.** "Cancel
24380 22 20 62 75 74 74 6f 6e 20 6f 6e 20 61 20 47 55  " button on a GU
24390 49 20 70 72 6f 67 72 65 73 73 20 64 69 61 6c 6f  I progress dialo
243a0 67 20 62 6f 78 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  g box..**.** The
243b0 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65   progress handle
243c0 72 20 63 61 6c 6c 62 61 63 6b 20 6d 75 73 74 20  r callback must 
243d0 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e 67 20  not do anything 
243e0 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66 79  that will modify
243f0 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65  .** the database
24400 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74   connection that
24410 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 70 72 6f   invoked the pro
24420 67 72 65 73 73 20 68 61 6e 64 6c 65 72 2e 0a 2a  gress handler..*
24430 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b 73 71 6c  * Note that [sql
24440 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
24450 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
24460 73 74 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64  step()] both mod
24470 69 66 79 20 74 68 65 69 72 0a 2a 2a 20 64 61 74  ify their.** dat
24480 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
24490 73 20 66 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e  s for the meanin
244a0 67 20 6f 66 20 22 6d 6f 64 69 66 79 22 20 69 6e  g of "modify" in
244b0 20 74 68 69 73 20 70 61 72 61 67 72 61 70 68 2e   this paragraph.
244c0 0a 2a 2a 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  .**.*/.SQLITE_AP
244d0 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 70  I void sqlite3_p
244e0 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65 72 28  rogress_handler(
244f0 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 2c 20 69  sqlite3*, int, i
24500 6e 74 28 2a 29 28 76 6f 69 64 2a 29 2c 20 76 6f  nt(*)(void*), vo
24510 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  id*);../*.** CAP
24520 49 33 52 45 46 3a 20 4f 70 65 6e 69 6e 67 20 41  I3REF: Opening A
24530 20 4e 65 77 20 44 61 74 61 62 61 73 65 20 43 6f   New Database Co
24540 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 43 4f 4e 53  nnection.** CONS
24550 54 52 55 43 54 4f 52 3a 20 73 71 6c 69 74 65 33  TRUCTOR: sqlite3
24560 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f  .**.** ^These ro
24570 75 74 69 6e 65 73 20 6f 70 65 6e 20 61 6e 20 53  utines open an S
24580 51 4c 69 74 65 20 64 61 74 61 62 61 73 65 20 66  QLite database f
24590 69 6c 65 20 61 73 20 73 70 65 63 69 66 69 65 64  ile as specified
245a0 20 62 79 20 74 68 65 20 0a 2a 2a 20 66 69 6c 65   by the .** file
245b0 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 2e 20 5e  name argument. ^
245c0 54 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67  The filename arg
245d0 75 6d 65 6e 74 20 69 73 20 69 6e 74 65 72 70 72  ument is interpr
245e0 65 74 65 64 20 61 73 20 55 54 46 2d 38 20 66 6f  eted as UTF-8 fo
245f0 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65  r.** sqlite3_ope
24600 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  n() and sqlite3_
24610 6f 70 65 6e 5f 76 32 28 29 20 61 6e 64 20 61 73  open_v2() and as
24620 20 55 54 46 2d 31 36 20 69 6e 20 74 68 65 20 6e   UTF-16 in the n
24630 61 74 69 76 65 20 62 79 74 65 0a 2a 2a 20 6f 72  ative byte.** or
24640 64 65 72 20 66 6f 72 20 73 71 6c 69 74 65 33 5f  der for sqlite3_
24650 6f 70 65 6e 31 36 28 29 2e 20 5e 28 41 20 5b 64  open16(). ^(A [d
24660 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
24670 6f 6e 5d 20 68 61 6e 64 6c 65 20 69 73 20 75 73  on] handle is us
24680 75 61 6c 6c 79 0a 2a 2a 20 72 65 74 75 72 6e 65  ually.** returne
24690 64 20 69 6e 20 2a 70 70 44 62 2c 20 65 76 65 6e  d in *ppDb, even
246a0 20 69 66 20 61 6e 20 65 72 72 6f 72 20 6f 63 63   if an error occ
246b0 75 72 73 2e 20 20 54 68 65 20 6f 6e 6c 79 20 65  urs.  The only e
246c0 78 63 65 70 74 69 6f 6e 20 69 73 20 74 68 61 74  xception is that
246d0 0a 2a 2a 20 69 66 20 53 51 4c 69 74 65 20 69 73  .** if SQLite is
246e0 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63   unable to alloc
246f0 61 74 65 20 6d 65 6d 6f 72 79 20 74 6f 20 68 6f  ate memory to ho
24700 6c 64 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d  ld the [sqlite3]
24710 20 6f 62 6a 65 63 74 2c 0a 2a 2a 20 61 20 4e 55   object,.** a NU
24720 4c 4c 20 77 69 6c 6c 20 62 65 20 77 72 69 74 74  LL will be writt
24730 65 6e 20 69 6e 74 6f 20 2a 70 70 44 62 20 69 6e  en into *ppDb in
24740 73 74 65 61 64 20 6f 66 20 61 20 70 6f 69 6e 74  stead of a point
24750 65 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74  er to the [sqlit
24760 65 33 5d 0a 2a 2a 20 6f 62 6a 65 63 74 2e 29 5e  e3].** object.)^
24770 20 5e 28 49 66 20 74 68 65 20 64 61 74 61 62 61   ^(If the databa
24780 73 65 20 69 73 20 6f 70 65 6e 65 64 20 28 61 6e  se is opened (an
24790 64 2f 6f 72 20 63 72 65 61 74 65 64 29 20 73 75  d/or created) su
247a0 63 63 65 73 73 66 75 6c 6c 79 2c 20 74 68 65 6e  ccessfully, then
247b0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20  .** [SQLITE_OK] 
247c0 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 4f 74  is returned.  Ot
247d0 68 65 72 77 69 73 65 20 61 6e 20 5b 65 72 72 6f  herwise an [erro
247e0 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72  r code] is retur
247f0 6e 65 64 2e 29 5e 20 5e 54 68 65 0a 2a 2a 20 5b  ned.)^ ^The.** [
24800 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29  sqlite3_errmsg()
24810 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 65 72  ] or [sqlite3_er
24820 72 6d 73 67 31 36 28 29 5d 20 72 6f 75 74 69 6e  rmsg16()] routin
24830 65 73 20 63 61 6e 20 62 65 20 75 73 65 64 20 74  es can be used t
24840 6f 20 6f 62 74 61 69 6e 0a 2a 2a 20 61 6e 20 45  o obtain.** an E
24850 6e 67 6c 69 73 68 20 6c 61 6e 67 75 61 67 65 20  nglish language 
24860 64 65 73 63 72 69 70 74 69 6f 6e 20 6f 66 20 74  description of t
24870 68 65 20 65 72 72 6f 72 20 66 6f 6c 6c 6f 77 69  he error followi
24880 6e 67 20 61 20 66 61 69 6c 75 72 65 20 6f 66 20  ng a failure of 
24890 61 6e 79 0a 2a 2a 20 6f 66 20 74 68 65 20 73 71  any.** of the sq
248a0 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 72 6f 75  lite3_open() rou
248b0 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  tines..**.** ^Th
248c0 65 20 64 65 66 61 75 6c 74 20 65 6e 63 6f 64 69  e default encodi
248d0 6e 67 20 77 69 6c 6c 20 62 65 20 55 54 46 2d 38  ng will be UTF-8
248e0 20 66 6f 72 20 64 61 74 61 62 61 73 65 73 20 63   for databases c
248f0 72 65 61 74 65 64 20 75 73 69 6e 67 0a 2a 2a 20  reated using.** 
24900 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f  sqlite3_open() o
24910 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
24920 32 28 29 2e 20 20 5e 54 68 65 20 64 65 66 61 75  2().  ^The defau
24930 6c 74 20 65 6e 63 6f 64 69 6e 67 20 66 6f 72 20  lt encoding for 
24940 64 61 74 61 62 61 73 65 73 0a 2a 2a 20 63 72 65  databases.** cre
24950 61 74 65 64 20 75 73 69 6e 67 20 73 71 6c 69 74  ated using sqlit
24960 65 33 5f 6f 70 65 6e 31 36 28 29 20 77 69 6c 6c  e3_open16() will
24970 20 62 65 20 55 54 46 2d 31 36 20 69 6e 20 74 68   be UTF-16 in th
24980 65 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72  e native byte or
24990 64 65 72 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 74 68  der..**.** Wheth
249a0 65 72 20 6f 72 20 6e 6f 74 20 61 6e 20 65 72 72  er or not an err
249b0 6f 72 20 6f 63 63 75 72 73 20 77 68 65 6e 20 69  or occurs when i
249c0 74 20 69 73 20 6f 70 65 6e 65 64 2c 20 72 65 73  t is opened, res
249d0 6f 75 72 63 65 73 0a 2a 2a 20 61 73 73 6f 63 69  ources.** associ
249e0 61 74 65 64 20 77 69 74 68 20 74 68 65 20 5b 64  ated with the [d
249f0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
24a00 6f 6e 5d 20 68 61 6e 64 6c 65 20 73 68 6f 75 6c  on] handle shoul
24a10 64 20 62 65 20 72 65 6c 65 61 73 65 64 20 62 79  d be released by
24a20 0a 2a 2a 20 70 61 73 73 69 6e 67 20 69 74 20 74  .** passing it t
24a30 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  o [sqlite3_close
24a40 28 29 5d 20 77 68 65 6e 20 69 74 20 69 73 20 6e  ()] when it is n
24a50 6f 20 6c 6f 6e 67 65 72 20 72 65 71 75 69 72 65  o longer require
24a60 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  d..**.** The sql
24a70 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69  ite3_open_v2() i
24a80 6e 74 65 72 66 61 63 65 20 77 6f 72 6b 73 20 6c  nterface works l
24a90 69 6b 65 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ike sqlite3_open
24aa0 28 29 0a 2a 2a 20 65 78 63 65 70 74 20 74 68 61  ().** except tha
24ab0 74 20 69 74 20 61 63 63 65 70 74 73 20 74 77 6f  t it accepts two
24ac0 20 61 64 64 69 74 69 6f 6e 61 6c 20 70 61 72 61   additional para
24ad0 6d 65 74 65 72 73 20 66 6f 72 20 61 64 64 69 74  meters for addit
24ae0 69 6f 6e 61 6c 20 63 6f 6e 74 72 6f 6c 0a 2a 2a  ional control.**
24af0 20 6f 76 65 72 20 74 68 65 20 6e 65 77 20 64 61   over the new da
24b00 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
24b10 6e 2e 20 20 5e 28 54 68 65 20 66 6c 61 67 73 20  n.  ^(The flags 
24b20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20  parameter to.** 
24b30 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
24b40 29 20 63 61 6e 20 74 61 6b 65 20 6f 6e 65 20 6f  ) can take one o
24b50 66 0a 2a 2a 20 74 68 65 20 66 6f 6c 6c 6f 77 69  f.** the followi
24b60 6e 67 20 74 68 72 65 65 20 76 61 6c 75 65 73 2c  ng three values,
24b70 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 63 6f 6d 62   optionally comb
24b80 69 6e 65 64 20 77 69 74 68 20 74 68 65 20 0a 2a  ined with the .*
24b90 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e  * [SQLITE_OPEN_N
24ba0 4f 4d 55 54 45 58 5d 2c 20 5b 53 51 4c 49 54 45  OMUTEX], [SQLITE
24bb0 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d  _OPEN_FULLMUTEX]
24bc0 2c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53  , [SQLITE_OPEN_S
24bd0 48 41 52 45 44 43 41 43 48 45 5d 2c 0a 2a 2a 20  HAREDCACHE],.** 
24be0 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49  [SQLITE_OPEN_PRI
24bf0 56 41 54 45 43 41 43 48 45 5d 2c 20 61 6e 64 2f  VATECACHE], and/
24c00 6f 72 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  or [SQLITE_OPEN_
24c10 55 52 49 5d 20 66 6c 61 67 73 3a 29 5e 0a 2a 2a  URI] flags:)^.**
24c20 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5e 28 3c 64  .** <dl>.** ^(<d
24c30 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52  t>[SQLITE_OPEN_R
24c40 45 41 44 4f 4e 4c 59 5d 3c 2f 64 74 3e 0a 2a 2a  EADONLY]</dt>.**
24c50 20 3c 64 64 3e 54 68 65 20 64 61 74 61 62 61 73   <dd>The databas
24c60 65 20 69 73 20 6f 70 65 6e 65 64 20 69 6e 20 72  e is opened in r
24c70 65 61 64 2d 6f 6e 6c 79 20 6d 6f 64 65 2e 20 20  ead-only mode.  
24c80 49 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  If the database 
24c90 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 61 6c 72 65  does not.** alre
24ca0 61 64 79 20 65 78 69 73 74 2c 20 61 6e 20 65 72  ady exist, an er
24cb0 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e  ror is returned.
24cc0 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28  </dd>)^.**.** ^(
24cd0 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  <dt>[SQLITE_OPEN
24ce0 5f 52 45 41 44 57 52 49 54 45 5d 3c 2f 64 74 3e  _READWRITE]</dt>
24cf0 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 74 61  .** <dd>The data
24d00 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66  base is opened f
24d10 6f 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20 77  or reading and w
24d20 72 69 74 69 6e 67 20 69 66 20 70 6f 73 73 69 62  riting if possib
24d30 6c 65 2c 20 6f 72 20 72 65 61 64 69 6e 67 0a 2a  le, or reading.*
24d40 2a 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 66 69  * only if the fi
24d50 6c 65 20 69 73 20 77 72 69 74 65 20 70 72 6f 74  le is write prot
24d60 65 63 74 65 64 20 62 79 20 74 68 65 20 6f 70 65  ected by the ope
24d70 72 61 74 69 6e 67 20 73 79 73 74 65 6d 2e 20 20  rating system.  
24d80 49 6e 20 65 69 74 68 65 72 0a 2a 2a 20 63 61 73  In either.** cas
24d90 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6d  e the database m
24da0 75 73 74 20 61 6c 72 65 61 64 79 20 65 78 69 73  ust already exis
24db0 74 2c 20 6f 74 68 65 72 77 69 73 65 20 61 6e 20  t, otherwise an 
24dc0 65 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65  error is returne
24dd0 64 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20  d.</dd>)^.**.** 
24de0 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50  ^(<dt>[SQLITE_OP
24df0 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 20 7c 20  EN_READWRITE] | 
24e00 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45  [SQLITE_OPEN_CRE
24e10 41 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  ATE]</dt>.** <dd
24e20 3e 54 68 65 20 64 61 74 61 62 61 73 65 20 69 73  >The database is
24e30 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64   opened for read
24e40 69 6e 67 20 61 6e 64 20 77 72 69 74 69 6e 67 2c  ing and writing,
24e50 20 61 6e 64 20 69 73 20 63 72 65 61 74 65 64 20   and is created 
24e60 69 66 0a 2a 2a 20 69 74 20 64 6f 65 73 20 6e 6f  if.** it does no
24e70 74 20 61 6c 72 65 61 64 79 20 65 78 69 73 74 2e  t already exist.
24e80 20 54 68 69 73 20 69 73 20 74 68 65 20 62 65 68   This is the beh
24e90 61 76 69 6f 72 20 74 68 61 74 20 69 73 20 61 6c  avior that is al
24ea0 77 61 79 73 20 75 73 65 64 20 66 6f 72 0a 2a 2a  ways used for.**
24eb0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20   sqlite3_open() 
24ec0 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  and sqlite3_open
24ed0 31 36 28 29 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 20  16().</dd>)^.** 
24ee0 3c 2f 64 6c 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 74  </dl>.**.** If t
24ef0 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 72  he 3rd parameter
24f00 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e   to sqlite3_open
24f10 5f 76 32 28 29 20 69 73 20 6e 6f 74 20 6f 6e 65  _v2() is not one
24f20 20 6f 66 20 74 68 65 0a 2a 2a 20 63 6f 6d 62 69   of the.** combi
24f30 6e 61 74 69 6f 6e 73 20 73 68 6f 77 6e 20 61 62  nations shown ab
24f40 6f 76 65 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 63  ove optionally c
24f50 6f 6d 62 69 6e 65 64 20 77 69 74 68 20 6f 74 68  ombined with oth
24f60 65 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50  er.** [SQLITE_OP
24f70 45 4e 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 53 51  EN_READONLY | SQ
24f80 4c 49 54 45 5f 4f 50 45 4e 5f 2a 20 62 69 74 73  LITE_OPEN_* bits
24f90 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 62 65  ].** then the be
24fa0 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69  havior is undefi
24fb0 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  ned..**.** ^If t
24fc0 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  he [SQLITE_OPEN_
24fd0 4e 4f 4d 55 54 45 58 5d 20 66 6c 61 67 20 69 73  NOMUTEX] flag is
24fe0 20 73 65 74 2c 20 74 68 65 6e 20 74 68 65 20 64   set, then the d
24ff0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
25000 6f 6e 0a 2a 2a 20 6f 70 65 6e 73 20 69 6e 20 74  on.** opens in t
25010 68 65 20 6d 75 6c 74 69 2d 74 68 72 65 61 64 20  he multi-thread 
25020 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d  [threading mode]
25030 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20   as long as the 
25040 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 0a 2a 2a  single-thread.**
25050 20 6d 6f 64 65 20 68 61 73 20 6e 6f 74 20 62 65   mode has not be
25060 65 6e 20 73 65 74 20 61 74 20 63 6f 6d 70 69 6c  en set at compil
25070 65 2d 74 69 6d 65 20 6f 72 20 73 74 61 72 74 2d  e-time or start-
25080 74 69 6d 65 2e 20 20 5e 49 66 20 74 68 65 0a 2a  time.  ^If the.*
25090 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46  * [SQLITE_OPEN_F
250a0 55 4c 4c 4d 55 54 45 58 5d 20 66 6c 61 67 20 69  ULLMUTEX] flag i
250b0 73 20 73 65 74 20 74 68 65 6e 20 74 68 65 20 64  s set then the d
250c0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
250d0 6f 6e 20 6f 70 65 6e 73 0a 2a 2a 20 69 6e 20 74  on opens.** in t
250e0 68 65 20 73 65 72 69 61 6c 69 7a 65 64 20 5b 74  he serialized [t
250f0 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 75  hreading mode] u
25100 6e 6c 65 73 73 20 73 69 6e 67 6c 65 2d 74 68 72  nless single-thr
25110 65 61 64 20 77 61 73 0a 2a 2a 20 70 72 65 76 69  ead was.** previ
25120 6f 75 73 6c 79 20 73 65 6c 65 63 74 65 64 20 61  ously selected a
25130 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  t compile-time o
25140 72 20 73 74 61 72 74 2d 74 69 6d 65 2e 0a 2a 2a  r start-time..**
25150 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50   ^The [SQLITE_OP
25160 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45 5d 20  EN_SHAREDCACHE] 
25170 66 6c 61 67 20 63 61 75 73 65 73 20 74 68 65 20  flag causes the 
25180 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
25190 69 6f 6e 20 74 6f 20 62 65 0a 2a 2a 20 65 6c 69  ion to be.** eli
251a0 67 69 62 6c 65 20 74 6f 20 75 73 65 20 5b 73 68  gible to use [sh
251b0 61 72 65 64 20 63 61 63 68 65 20 6d 6f 64 65 5d  ared cache mode]
251c0 2c 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20  , regardless of 
251d0 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 73  whether or not s
251e0 68 61 72 65 64 0a 2a 2a 20 63 61 63 68 65 20 69  hared.** cache i
251f0 73 20 65 6e 61 62 6c 65 64 20 75 73 69 6e 67 20  s enabled using 
25200 5b 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f  [sqlite3_enable_
25210 73 68 61 72 65 64 5f 63 61 63 68 65 28 29 5d 2e  shared_cache()].
25220 20 20 5e 54 68 65 0a 2a 2a 20 5b 53 51 4c 49 54    ^The.** [SQLIT
25230 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41  E_OPEN_PRIVATECA
25240 43 48 45 5d 20 66 6c 61 67 20 63 61 75 73 65 73  CHE] flag causes
25250 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
25260 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 6e 6f 74 0a  nnection to not.
25270 2a 2a 20 70 61 72 74 69 63 69 70 61 74 65 20 69  ** participate i
25280 6e 20 5b 73 68 61 72 65 64 20 63 61 63 68 65 20  n [shared cache 
25290 6d 6f 64 65 5d 20 65 76 65 6e 20 69 66 20 69 74  mode] even if it
252a0 20 69 73 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 0a   is enabled..**.
252b0 2a 2a 20 5e 54 68 65 20 66 6f 75 72 74 68 20 70  ** ^The fourth p
252c0 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
252d0 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73  te3_open_v2() is
252e0 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
252f0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  .** [sqlite3_vfs
25300 5d 20 6f 62 6a 65 63 74 20 74 68 61 74 20 64 65  ] object that de
25310 66 69 6e 65 73 20 74 68 65 20 6f 70 65 72 61 74  fines the operat
25320 69 6e 67 20 73 79 73 74 65 6d 20 69 6e 74 65 72  ing system inter
25330 66 61 63 65 20 74 68 61 74 0a 2a 2a 20 74 68 65  face that.** the
25340 20 6e 65 77 20 64 61 74 61 62 61 73 65 20 63 6f   new database co
25350 6e 6e 65 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20  nnection should 
25360 75 73 65 2e 20 20 5e 49 66 20 74 68 65 20 66 6f  use.  ^If the fo
25370 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 69  urth parameter i
25380 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  s.** a NULL poin
25390 74 65 72 20 74 68 65 6e 20 74 68 65 20 64 65 66  ter then the def
253a0 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66  ault [sqlite3_vf
253b0 73 5d 20 6f 62 6a 65 63 74 20 69 73 20 75 73 65  s] object is use
253c0 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  d..**.** ^If the
253d0 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 22 3a 6d   filename is ":m
253e0 65 6d 6f 72 79 3a 22 2c 20 74 68 65 6e 20 61 20  emory:", then a 
253f0 70 72 69 76 61 74 65 2c 20 74 65 6d 70 6f 72 61  private, tempora
25400 72 79 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74  ry in-memory dat
25410 61 62 61 73 65 0a 2a 2a 20 69 73 20 63 72 65 61  abase.** is crea
25420 74 65 64 20 66 6f 72 20 74 68 65 20 63 6f 6e 6e  ted for the conn
25430 65 63 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 69  ection.  ^This i
25440 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73  n-memory databas
25450 65 20 77 69 6c 6c 20 76 61 6e 69 73 68 20 77 68  e will vanish wh
25460 65 6e 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61  en.** the databa
25470 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  se connection is
25480 20 63 6c 6f 73 65 64 2e 20 20 46 75 74 75 72 65   closed.  Future
25490 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c   versions of SQL
254a0 69 74 65 20 6d 69 67 68 74 0a 2a 2a 20 6d 61 6b  ite might.** mak
254b0 65 20 75 73 65 20 6f 66 20 61 64 64 69 74 69 6f  e use of additio
254c0 6e 61 6c 20 73 70 65 63 69 61 6c 20 66 69 6c 65  nal special file
254d0 6e 61 6d 65 73 20 74 68 61 74 20 62 65 67 69 6e  names that begin
254e0 20 77 69 74 68 20 74 68 65 20 22 3a 22 20 63 68   with the ":" ch
254f0 61 72 61 63 74 65 72 2e 0a 2a 2a 20 49 74 20 69  aracter..** It i
25500 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68  s recommended th
25510 61 74 20 77 68 65 6e 20 61 20 64 61 74 61 62 61  at when a databa
25520 73 65 20 66 69 6c 65 6e 61 6d 65 20 61 63 74 75  se filename actu
25530 61 6c 6c 79 20 64 6f 65 73 20 62 65 67 69 6e 20  ally does begin 
25540 77 69 74 68 0a 2a 2a 20 61 20 22 3a 22 20 63 68  with.** a ":" ch
25550 61 72 61 63 74 65 72 20 79 6f 75 20 73 68 6f 75  aracter you shou
25560 6c 64 20 70 72 65 66 69 78 20 74 68 65 20 66 69  ld prefix the fi
25570 6c 65 6e 61 6d 65 20 77 69 74 68 20 61 20 70 61  lename with a pa
25580 74 68 6e 61 6d 65 20 73 75 63 68 20 61 73 0a 2a  thname such as.*
25590 2a 20 22 2e 2f 22 20 74 6f 20 61 76 6f 69 64 20  * "./" to avoid 
255a0 61 6d 62 69 67 75 69 74 79 2e 0a 2a 2a 0a 2a 2a  ambiguity..**.**
255b0 20 5e 49 66 20 74 68 65 20 66 69 6c 65 6e 61 6d   ^If the filenam
255c0 65 20 69 73 20 61 6e 20 65 6d 70 74 79 20 73 74  e is an empty st
255d0 72 69 6e 67 2c 20 74 68 65 6e 20 61 20 70 72 69  ring, then a pri
255e0 76 61 74 65 2c 20 74 65 6d 70 6f 72 61 72 79 0a  vate, temporary.
255f0 2a 2a 20 6f 6e 2d 64 69 73 6b 20 64 61 74 61 62  ** on-disk datab
25600 61 73 65 20 77 69 6c 6c 20 62 65 20 63 72 65 61  ase will be crea
25610 74 65 64 2e 20 20 5e 54 68 69 73 20 70 72 69 76  ted.  ^This priv
25620 61 74 65 20 64 61 74 61 62 61 73 65 20 77 69 6c  ate database wil
25630 6c 20 62 65 0a 2a 2a 20 61 75 74 6f 6d 61 74 69  l be.** automati
25640 63 61 6c 6c 79 20 64 65 6c 65 74 65 64 20 61 73  cally deleted as
25650 20 73 6f 6f 6e 20 61 73 20 74 68 65 20 64 61 74   soon as the dat
25660 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
25670 20 69 73 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a   is closed..**.*
25680 2a 20 5b 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65  * [[URI filename
25690 73 20 69 6e 20 73 71 6c 69 74 65 33 5f 6f 70 65  s in sqlite3_ope
256a0 6e 28 29 5d 5d 20 3c 68 33 3e 55 52 49 20 46 69  n()]] <h3>URI Fi
256b0 6c 65 6e 61 6d 65 73 3c 2f 68 33 3e 0a 2a 2a 0a  lenames</h3>.**.
256c0 2a 2a 20 5e 49 66 20 5b 55 52 49 20 66 69 6c 65  ** ^If [URI file
256d0 6e 61 6d 65 5d 20 69 6e 74 65 72 70 72 65 74 61  name] interpreta
256e0 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 2c  tion is enabled,
256f0 20 61 6e 64 20 74 68 65 20 66 69 6c 65 6e 61 6d   and the filenam
25700 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 62 65  e argument.** be
25710 67 69 6e 73 20 77 69 74 68 20 22 66 69 6c 65 3a  gins with "file:
25720 22 2c 20 74 68 65 6e 20 74 68 65 20 66 69 6c 65  ", then the file
25730 6e 61 6d 65 20 69 73 20 69 6e 74 65 72 70 72 65  name is interpre
25740 74 65 64 20 61 73 20 61 20 55 52 49 2e 20 5e 55  ted as a URI. ^U
25750 52 49 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 69  RI.** filename i
25760 6e 74 65 72 70 72 65 74 61 74 69 6f 6e 20 69 73  nterpretation is
25770 20 65 6e 61 62 6c 65 64 20 69 66 20 74 68 65 20   enabled if the 
25780 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49  [SQLITE_OPEN_URI
25790 5d 20 66 6c 61 67 20 69 73 0a 2a 2a 20 73 65 74  ] flag is.** set
257a0 20 69 6e 20 74 68 65 20 66 6f 75 72 74 68 20 61   in the fourth a
257b0 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74  rgument to sqlit
257c0 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2c 20 6f 72  e3_open_v2(), or
257d0 20 69 66 20 69 74 20 68 61 73 0a 2a 2a 20 62 65   if it has.** be
257e0 65 6e 20 65 6e 61 62 6c 65 64 20 67 6c 6f 62 61  en enabled globa
257f0 6c 6c 79 20 75 73 69 6e 67 20 74 68 65 20 5b 53  lly using the [S
25800 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49  QLITE_CONFIG_URI
25810 5d 20 6f 70 74 69 6f 6e 20 77 69 74 68 20 74 68  ] option with th
25820 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  e.** [sqlite3_co
25830 6e 66 69 67 28 29 5d 20 6d 65 74 68 6f 64 20 6f  nfig()] method o
25840 72 20 62 79 20 74 68 65 20 5b 53 51 4c 49 54 45  r by the [SQLITE
25850 5f 55 53 45 5f 55 52 49 5d 20 63 6f 6d 70 69 6c  _USE_URI] compil
25860 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2e 0a 2a  e-time option..*
25870 2a 20 41 73 20 6f 66 20 53 51 4c 69 74 65 20 76  * As of SQLite v
25880 65 72 73 69 6f 6e 20 33 2e 37 2e 37 2c 20 55 52  ersion 3.7.7, UR
25890 49 20 66 69 6c 65 6e 61 6d 65 20 69 6e 74 65 72  I filename inter
258a0 70 72 65 74 61 74 69 6f 6e 20 69 73 20 74 75 72  pretation is tur
258b0 6e 65 64 20 6f 66 66 0a 2a 2a 20 62 79 20 64 65  ned off.** by de
258c0 66 61 75 6c 74 2c 20 62 75 74 20 66 75 74 75 72  fault, but futur
258d0 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51  e releases of SQ
258e0 4c 69 74 65 20 6d 69 67 68 74 20 65 6e 61 62 6c  Lite might enabl
258f0 65 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 0a 2a  e URI filename.*
25900 2a 20 69 6e 74 65 72 70 72 65 74 61 74 69 6f 6e  * interpretation
25910 20 62 79 20 64 65 66 61 75 6c 74 2e 20 20 53 65   by default.  Se
25920 65 20 22 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65  e "[URI filename
25930 73 5d 22 20 66 6f 72 20 61 64 64 69 74 69 6f 6e  s]" for addition
25940 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f  al.** informatio
25950 6e 2e 0a 2a 2a 0a 2a 2a 20 55 52 49 20 66 69 6c  n..**.** URI fil
25960 65 6e 61 6d 65 73 20 61 72 65 20 70 61 72 73 65  enames are parse
25970 64 20 61 63 63 6f 72 64 69 6e 67 20 74 6f 20 52  d according to R
25980 46 43 20 33 39 38 36 2e 20 5e 49 66 20 74 68 65  FC 3986. ^If the
25990 20 55 52 49 20 63 6f 6e 74 61 69 6e 73 20 61 6e   URI contains an
259a0 0a 2a 2a 20 61 75 74 68 6f 72 69 74 79 2c 20 74  .** authority, t
259b0 68 65 6e 20 69 74 20 6d 75 73 74 20 62 65 20 65  hen it must be e
259c0 69 74 68 65 72 20 61 6e 20 65 6d 70 74 79 20 73  ither an empty s
259d0 74 72 69 6e 67 20 6f 72 20 74 68 65 20 73 74 72  tring or the str
259e0 69 6e 67 20 0a 2a 2a 20 22 6c 6f 63 61 6c 68 6f  ing .** "localho
259f0 73 74 22 2e 20 5e 49 66 20 74 68 65 20 61 75 74  st". ^If the aut
25a00 68 6f 72 69 74 79 20 69 73 20 6e 6f 74 20 61 6e  hority is not an
25a10 20 65 6d 70 74 79 20 73 74 72 69 6e 67 20 6f 72   empty string or
25a20 20 22 6c 6f 63 61 6c 68 6f 73 74 22 2c 20 61 6e   "localhost", an
25a30 20 0a 2a 2a 20 65 72 72 6f 72 20 69 73 20 72 65   .** error is re
25a40 74 75 72 6e 65 64 20 74 6f 20 74 68 65 20 63 61  turned to the ca
25a50 6c 6c 65 72 2e 20 5e 54 68 65 20 66 72 61 67 6d  ller. ^The fragm
25a60 65 6e 74 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66  ent component of
25a70 20 61 20 55 52 49 2c 20 69 66 20 0a 2a 2a 20 70   a URI, if .** p
25a80 72 65 73 65 6e 74 2c 20 69 73 20 69 67 6e 6f 72  resent, is ignor
25a90 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74  ed..**.** ^SQLit
25aa0 65 20 75 73 65 73 20 74 68 65 20 70 61 74 68 20  e uses the path 
25ab0 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 74 68 65  component of the
25ac0 20 55 52 49 20 61 73 20 74 68 65 20 6e 61 6d 65   URI as the name
25ad0 20 6f 66 20 74 68 65 20 64 69 73 6b 20 66 69 6c   of the disk fil
25ae0 65 0a 2a 2a 20 77 68 69 63 68 20 63 6f 6e 74 61  e.** which conta
25af0 69 6e 73 20 74 68 65 20 64 61 74 61 62 61 73 65  ins the database
25b00 2e 20 5e 49 66 20 74 68 65 20 70 61 74 68 20 62  . ^If the path b
25b10 65 67 69 6e 73 20 77 69 74 68 20 61 20 27 2f 27  egins with a '/'
25b20 20 63 68 61 72 61 63 74 65 72 2c 20 0a 2a 2a 20   character, .** 
25b30 74 68 65 6e 20 69 74 20 69 73 20 69 6e 74 65 72  then it is inter
25b40 70 72 65 74 65 64 20 61 73 20 61 6e 20 61 62 73  preted as an abs
25b50 6f 6c 75 74 65 20 70 61 74 68 2e 20 5e 49 66 20  olute path. ^If 
25b60 74 68 65 20 70 61 74 68 20 64 6f 65 73 20 6e 6f  the path does no
25b70 74 20 62 65 67 69 6e 20 0a 2a 2a 20 77 69 74 68  t begin .** with
25b80 20 61 20 27 2f 27 20 28 6d 65 61 6e 69 6e 67 20   a '/' (meaning 
25b90 74 68 61 74 20 74 68 65 20 61 75 74 68 6f 72 69  that the authori
25ba0 74 79 20 73 65 63 74 69 6f 6e 20 69 73 20 6f 6d  ty section is om
25bb0 69 74 74 65 64 20 66 72 6f 6d 20 74 68 65 20 55  itted from the U
25bc0 52 49 29 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20  RI).** then the 
25bd0 70 61 74 68 20 69 73 20 69 6e 74 65 72 70 72 65  path is interpre
25be0 74 65 64 20 61 73 20 61 20 72 65 6c 61 74 69 76  ted as a relativ
25bf0 65 20 70 61 74 68 2e 20 0a 2a 2a 20 5e 28 4f 6e  e path. .** ^(On
25c00 20 77 69 6e 64 6f 77 73 2c 20 74 68 65 20 66 69   windows, the fi
25c10 72 73 74 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66  rst component of
25c20 20 61 6e 20 61 62 73 6f 6c 75 74 65 20 70 61 74   an absolute pat
25c30 68 20 0a 2a 2a 20 69 73 20 61 20 64 72 69 76 65  h .** is a drive
25c40 20 73 70 65 63 69 66 69 63 61 74 69 6f 6e 20 28   specification (
25c50 65 2e 67 2e 20 22 43 3a 22 29 2e 29 5e 0a 2a 2a  e.g. "C:").)^.**
25c60 0a 2a 2a 20 5b 5b 63 6f 72 65 20 55 52 49 20 71  .** [[core URI q
25c70 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 73 5d  uery parameters]
25c80 5d 0a 2a 2a 20 54 68 65 20 71 75 65 72 79 20 63  ].** The query c
25c90 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 20 55 52  omponent of a UR
25ca0 49 20 6d 61 79 20 63 6f 6e 74 61 69 6e 20 70 61  I may contain pa
25cb0 72 61 6d 65 74 65 72 73 20 74 68 61 74 20 61 72  rameters that ar
25cc0 65 20 69 6e 74 65 72 70 72 65 74 65 64 0a 2a 2a  e interpreted.**
25cd0 20 65 69 74 68 65 72 20 62 79 20 53 51 4c 69 74   either by SQLit
25ce0 65 20 69 74 73 65 6c 66 2c 20 6f 72 20 62 79 20  e itself, or by 
25cf0 61 20 5b 56 46 53 20 7c 20 63 75 73 74 6f 6d 20  a [VFS | custom 
25d00 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  VFS implementati
25d10 6f 6e 5d 2e 0a 2a 2a 20 53 51 4c 69 74 65 20 61  on]..** SQLite a
25d20 6e 64 20 69 74 73 20 62 75 69 6c 74 2d 69 6e 20  nd its built-in 
25d30 5b 56 46 53 65 73 5d 20 69 6e 74 65 72 70 72 65  [VFSes] interpre
25d40 74 20 74 68 65 0a 2a 2a 20 66 6f 6c 6c 6f 77 69  t the.** followi
25d50 6e 67 20 71 75 65 72 79 20 70 61 72 61 6d 65 74  ng query paramet
25d60 65 72 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a  ers:.**.** <ul>.
25d70 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e 76 66 73  **   <li> <b>vfs
25d80 3c 2f 62 3e 3a 20 5e 54 68 65 20 22 76 66 73 22  </b>: ^The "vfs"
25d90 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62   parameter may b
25da0 65 20 75 73 65 64 20 74 6f 20 73 70 65 63 69 66  e used to specif
25db0 79 20 74 68 65 20 6e 61 6d 65 20 6f 66 0a 2a 2a  y the name of.**
25dc0 20 20 20 20 20 61 20 56 46 53 20 6f 62 6a 65 63       a VFS objec
25dd0 74 20 74 68 61 74 20 70 72 6f 76 69 64 65 73 20  t that provides 
25de0 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79  the operating sy
25df0 73 74 65 6d 20 69 6e 74 65 72 66 61 63 65 20 74  stem interface t
25e00 68 61 74 20 73 68 6f 75 6c 64 0a 2a 2a 20 20 20  hat should.**   
25e10 20 20 62 65 20 75 73 65 64 20 74 6f 20 61 63 63    be used to acc
25e20 65 73 73 20 74 68 65 20 64 61 74 61 62 61 73 65  ess the database
25e30 20 66 69 6c 65 20 6f 6e 20 64 69 73 6b 2e 20 5e   file on disk. ^
25e40 49 66 20 74 68 69 73 20 6f 70 74 69 6f 6e 20 69  If this option i
25e50 73 20 73 65 74 20 74 6f 0a 2a 2a 20 20 20 20 20  s set to.**     
25e60 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 20  an empty string 
25e70 74 68 65 20 64 65 66 61 75 6c 74 20 56 46 53 20  the default VFS 
25e80 6f 62 6a 65 63 74 20 69 73 20 75 73 65 64 2e 20  object is used. 
25e90 5e 53 70 65 63 69 66 79 69 6e 67 20 61 6e 20 75  ^Specifying an u
25ea0 6e 6b 6e 6f 77 6e 0a 2a 2a 20 20 20 20 20 56 46  nknown.**     VF
25eb0 53 20 69 73 20 61 6e 20 65 72 72 6f 72 2e 20 5e  S is an error. ^
25ec0 49 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  If sqlite3_open_
25ed0 76 32 28 29 20 69 73 20 75 73 65 64 20 61 6e 64  v2() is used and
25ee0 20 74 68 65 20 76 66 73 20 6f 70 74 69 6f 6e 20   the vfs option 
25ef0 69 73 0a 2a 2a 20 20 20 20 20 70 72 65 73 65 6e  is.**     presen
25f00 74 2c 20 74 68 65 6e 20 74 68 65 20 56 46 53 20  t, then the VFS 
25f10 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65  specified by the
25f20 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 70 72   option takes pr
25f30 65 63 65 64 65 6e 63 65 20 6f 76 65 72 0a 2a 2a  ecedence over.**
25f40 20 20 20 20 20 74 68 65 20 76 61 6c 75 65 20 70       the value p
25f50 61 73 73 65 64 20 61 73 20 74 68 65 20 66 6f 75  assed as the fou
25f60 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  rth parameter to
25f70 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
25f80 28 29 2e 0a 2a 2a 0a 2a 2a 20 20 20 3c 6c 69 3e  ()..**.**   <li>
25f90 20 3c 62 3e 6d 6f 64 65 3c 2f 62 3e 3a 20 5e 28   <b>mode</b>: ^(
25fa0 54 68 65 20 6d 6f 64 65 20 70 61 72 61 6d 65 74  The mode paramet
25fb0 65 72 20 6d 61 79 20 62 65 20 73 65 74 20 74 6f  er may be set to
25fc0 20 65 69 74 68 65 72 20 22 72 6f 22 2c 20 22 72   either "ro", "r
25fd0 77 22 2c 0a 2a 2a 20 20 20 20 20 22 72 77 63 22  w",.**     "rwc"
25fe0 2c 20 6f 72 20 22 6d 65 6d 6f 72 79 22 2e 20 41  , or "memory". A
25ff0 74 74 65 6d 70 74 69 6e 67 20 74 6f 20 73 65 74  ttempting to set
26000 20 69 74 20 74 6f 20 61 6e 79 20 6f 74 68 65 72   it to any other
26010 20 76 61 6c 75 65 20 69 73 0a 2a 2a 20 20 20 20   value is.**    
26020 20 61 6e 20 65 72 72 6f 72 29 5e 2e 20 0a 2a 2a   an error)^. .**
26030 20 20 20 20 20 5e 49 66 20 22 72 6f 22 20 69 73       ^If "ro" is
26040 20 73 70 65 63 69 66 69 65 64 2c 20 74 68 65 6e   specified, then
26050 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73   the database is
26060 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64   opened for read
26070 2d 6f 6e 6c 79 20 0a 2a 2a 20 20 20 20 20 61 63  -only .**     ac
26080 63 65 73 73 2c 20 6a 75 73 74 20 61 73 20 69 66  cess, just as if
26090 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45   the [SQLITE_OPE
260a0 4e 5f 52 45 41 44 4f 4e 4c 59 5d 20 66 6c 61 67  N_READONLY] flag
260b0 20 68 61 64 20 62 65 65 6e 20 73 65 74 20 69 6e   had been set in
260c0 20 74 68 65 20 0a 2a 2a 20 20 20 20 20 74 68 69   the .**     thi
260d0 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73  rd argument to s
260e0 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
260f0 2e 20 5e 49 66 20 74 68 65 20 6d 6f 64 65 20 6f  . ^If the mode o
26100 70 74 69 6f 6e 20 69 73 20 73 65 74 20 74 6f 20  ption is set to 
26110 0a 2a 2a 20 20 20 20 20 22 72 77 22 2c 20 74 68  .**     "rw", th
26120 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  en the database 
26130 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65  is opened for re
26140 61 64 2d 77 72 69 74 65 20 28 62 75 74 20 6e 6f  ad-write (but no
26150 74 20 63 72 65 61 74 65 29 20 0a 2a 2a 20 20 20  t create) .**   
26160 20 20 61 63 63 65 73 73 2c 20 61 73 20 69 66 20    access, as if 
26170 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44  SQLITE_OPEN_READ
26180 57 52 49 54 45 20 28 62 75 74 20 6e 6f 74 20 53  WRITE (but not S
26190 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54  QLITE_OPEN_CREAT
261a0 45 29 20 68 61 64 20 0a 2a 2a 20 20 20 20 20 62  E) had .**     b
261b0 65 65 6e 20 73 65 74 2e 20 5e 56 61 6c 75 65 20  een set. ^Value 
261c0 22 72 77 63 22 20 69 73 20 65 71 75 69 76 61 6c  "rwc" is equival
261d0 65 6e 74 20 74 6f 20 73 65 74 74 69 6e 67 20 62  ent to setting b
261e0 6f 74 68 20 0a 2a 2a 20 20 20 20 20 53 51 4c 49  oth .**     SQLI
261f0 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54  TE_OPEN_READWRIT
26200 45 20 61 6e 64 20 53 51 4c 49 54 45 5f 4f 50 45  E and SQLITE_OPE
26210 4e 5f 43 52 45 41 54 45 2e 20 20 5e 49 66 20 74  N_CREATE.  ^If t
26220 68 65 20 6d 6f 64 65 20 6f 70 74 69 6f 6e 20 69  he mode option i
26230 73 0a 2a 2a 20 20 20 20 20 73 65 74 20 74 6f 20  s.**     set to 
26240 22 6d 65 6d 6f 72 79 22 20 74 68 65 6e 20 61 20  "memory" then a 
26250 70 75 72 65 20 5b 69 6e 2d 6d 65 6d 6f 72 79 20  pure [in-memory 
26260 64 61 74 61 62 61 73 65 5d 20 74 68 61 74 20 6e  database] that n
26270 65 76 65 72 20 72 65 61 64 73 0a 2a 2a 20 20 20  ever reads.**   
26280 20 20 6f 72 20 77 72 69 74 65 73 20 66 72 6f 6d    or writes from
26290 20 64 69 73 6b 20 69 73 20 75 73 65 64 2e 20 5e   disk is used. ^
262a0 49 74 20 69 73 20 61 6e 20 65 72 72 6f 72 20 74  It is an error t
262b0 6f 20 73 70 65 63 69 66 79 20 61 20 76 61 6c 75  o specify a valu
262c0 65 20 66 6f 72 0a 2a 2a 20 20 20 20 20 74 68 65  e for.**     the
262d0 20 6d 6f 64 65 20 70 61 72 61 6d 65 74 65 72 20   mode parameter 
262e0 74 68 61 74 20 69 73 20 6c 65 73 73 20 72 65 73  that is less res
262f0 74 72 69 63 74 69 76 65 20 74 68 61 6e 20 74 68  trictive than th
26300 61 74 20 73 70 65 63 69 66 69 65 64 20 62 79 0a  at specified by.
26310 2a 2a 20 20 20 20 20 74 68 65 20 66 6c 61 67 73  **     the flags
26320 20 70 61 73 73 65 64 20 69 6e 20 74 68 65 20 74   passed in the t
26330 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74  hird parameter t
26340 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  o sqlite3_open_v
26350 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 20 20 3c 6c 69  2()..**.**   <li
26360 3e 20 3c 62 3e 63 61 63 68 65 3c 2f 62 3e 3a 20  > <b>cache</b>: 
26370 5e 54 68 65 20 63 61 63 68 65 20 70 61 72 61 6d  ^The cache param
26380 65 74 65 72 20 6d 61 79 20 62 65 20 73 65 74 20  eter may be set 
26390 74 6f 20 65 69 74 68 65 72 20 22 73 68 61 72 65  to either "share
263a0 64 22 20 6f 72 0a 2a 2a 20 20 20 20 20 22 70 72  d" or.**     "pr
263b0 69 76 61 74 65 22 2e 20 5e 53 65 74 74 69 6e 67  ivate". ^Setting
263c0 20 69 74 20 74 6f 20 22 73 68 61 72 65 64 22 20   it to "shared" 
263d0 69 73 20 65 71 75 69 76 61 6c 65 6e 74 20 74 6f  is equivalent to
263e0 20 73 65 74 74 69 6e 67 20 74 68 65 0a 2a 2a 20   setting the.** 
263f0 20 20 20 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f      SQLITE_OPEN_
26400 53 48 41 52 45 44 43 41 43 48 45 20 62 69 74 20  SHAREDCACHE bit 
26410 69 6e 20 74 68 65 20 66 6c 61 67 73 20 61 72 67  in the flags arg
26420 75 6d 65 6e 74 20 70 61 73 73 65 64 20 74 6f 0a  ument passed to.
26430 2a 2a 20 20 20 20 20 73 71 6c 69 74 65 33 5f 6f  **     sqlite3_o
26440 70 65 6e 5f 76 32 28 29 2e 20 5e 53 65 74 74 69  pen_v2(). ^Setti
26450 6e 67 20 74 68 65 20 63 61 63 68 65 20 70 61 72  ng the cache par
26460 61 6d 65 74 65 72 20 74 6f 20 22 70 72 69 76 61  ameter to "priva
26470 74 65 22 20 69 73 20 0a 2a 2a 20 20 20 20 20 65  te" is .**     e
26480 71 75 69 76 61 6c 65 6e 74 20 74 6f 20 73 65 74  quivalent to set
26490 74 69 6e 67 20 74 68 65 20 53 51 4c 49 54 45 5f  ting the SQLITE_
264a0 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48  OPEN_PRIVATECACH
264b0 45 20 62 69 74 2e 0a 2a 2a 20 20 20 20 20 5e 49  E bit..**     ^I
264c0 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  f sqlite3_open_v
264d0 32 28 29 20 69 73 20 75 73 65 64 20 61 6e 64 20  2() is used and 
264e0 74 68 65 20 22 63 61 63 68 65 22 20 70 61 72 61  the "cache" para
264f0 6d 65 74 65 72 20 69 73 20 70 72 65 73 65 6e 74  meter is present
26500 20 69 6e 0a 2a 2a 20 20 20 20 20 61 20 55 52 49   in.**     a URI
26510 20 66 69 6c 65 6e 61 6d 65 2c 20 69 74 73 20 76   filename, its v
26520 61 6c 75 65 20 6f 76 65 72 72 69 64 65 73 20 61  alue overrides a
26530 6e 79 20 62 65 68 61 76 69 6f 72 20 72 65 71 75  ny behavior requ
26540 65 73 74 65 64 20 62 79 20 73 65 74 74 69 6e 67  ested by setting
26550 0a 2a 2a 20 20 20 20 20 53 51 4c 49 54 45 5f 4f  .**     SQLITE_O
26560 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45  PEN_PRIVATECACHE
26570 20 6f 72 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f   or SQLITE_OPEN_
26580 53 48 41 52 45 44 43 41 43 48 45 20 66 6c 61 67  SHAREDCACHE flag
26590 2e 0a 2a 2a 0a 2a 2a 20 20 3c 6c 69 3e 20 3c 62  ..**.**  <li> <b
265a0 3e 70 73 6f 77 3c 2f 62 3e 3a 20 5e 54 68 65 20  >psow</b>: ^The 
265b0 70 73 6f 77 20 70 61 72 61 6d 65 74 65 72 20 69  psow parameter i
265c0 6e 64 69 63 61 74 65 73 20 77 68 65 74 68 65 72  ndicates whether
265d0 20 6f 72 20 6e 6f 74 20 74 68 65 0a 2a 2a 20 20   or not the.**  
265e0 20 20 20 5b 70 6f 77 65 72 73 61 66 65 20 6f 76     [powersafe ov
265f0 65 72 77 72 69 74 65 5d 20 70 72 6f 70 65 72 74  erwrite] propert
26600 79 20 64 6f 65 73 20 6f 72 20 64 6f 65 73 20 6e  y does or does n
26610 6f 74 20 61 70 70 6c 79 20 74 6f 20 74 68 65 0a  ot apply to the.
26620 2a 2a 20 20 20 20 20 73 74 6f 72 61 67 65 20 6d  **     storage m
26630 65 64 69 61 20 6f 6e 20 77 68 69 63 68 20 74 68  edia on which th
26640 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
26650 72 65 73 69 64 65 73 2e 0a 2a 2a 0a 2a 2a 20 20  resides..**.**  
26660 3c 6c 69 3e 20 3c 62 3e 6e 6f 6c 6f 63 6b 3c 2f  <li> <b>nolock</
26670 62 3e 3a 20 5e 54 68 65 20 6e 6f 6c 6f 63 6b 20  b>: ^The nolock 
26680 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 62  parameter is a b
26690 6f 6f 6c 65 61 6e 20 71 75 65 72 79 20 70 61 72  oolean query par
266a0 61 6d 65 74 65 72 0a 2a 2a 20 20 20 20 20 77 68  ameter.**     wh
266b0 69 63 68 20 69 66 20 73 65 74 20 64 69 73 61 62  ich if set disab
266c0 6c 65 73 20 66 69 6c 65 20 6c 6f 63 6b 69 6e 67  les file locking
266d0 20 69 6e 20 72 6f 6c 6c 62 61 63 6b 20 6a 6f 75   in rollback jou
266e0 72 6e 61 6c 20 6d 6f 64 65 73 2e 20 20 54 68 69  rnal modes.  Thi
266f0 73 0a 2a 2a 20 20 20 20 20 69 73 20 75 73 65 66  s.**     is usef
26700 75 6c 20 66 6f 72 20 61 63 63 65 73 73 69 6e 67  ul for accessing
26710 20 61 20 64 61 74 61 62 61 73 65 20 6f 6e 20 61   a database on a
26720 20 66 69 6c 65 73 79 73 74 65 6d 20 74 68 61 74   filesystem that
26730 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 20 20 20   does not.**    
26740 20 73 75 70 70 6f 72 74 20 6c 6f 63 6b 69 6e 67   support locking
26750 2e 20 20 43 61 75 74 69 6f 6e 3a 20 20 44 61 74  .  Caution:  Dat
26760 61 62 61 73 65 20 63 6f 72 72 75 70 74 69 6f 6e  abase corruption
26770 20 6d 69 67 68 74 20 72 65 73 75 6c 74 20 69 66   might result if
26780 20 74 77 6f 0a 2a 2a 20 20 20 20 20 6f 72 20 6d   two.**     or m
26790 6f 72 65 20 70 72 6f 63 65 73 73 65 73 20 77 72  ore processes wr
267a0 69 74 65 20 74 6f 20 74 68 65 20 73 61 6d 65 20  ite to the same 
267b0 64 61 74 61 62 61 73 65 20 61 6e 64 20 61 6e 79  database and any
267c0 20 6f 6e 65 20 6f 66 20 74 68 6f 73 65 0a 2a 2a   one of those.**
267d0 20 20 20 20 20 70 72 6f 63 65 73 73 65 73 20 75       processes u
267e0 73 65 73 20 6e 6f 6c 6f 63 6b 3d 31 2e 0a 2a 2a  ses nolock=1..**
267f0 0a 2a 2a 20 20 3c 6c 69 3e 20 3c 62 3e 69 6d 6d  .**  <li> <b>imm
26800 75 74 61 62 6c 65 3c 2f 62 3e 3a 20 5e 54 68 65  utable</b>: ^The
26810 20 69 6d 6d 75 74 61 62 6c 65 20 70 61 72 61 6d   immutable param
26820 65 74 65 72 20 69 73 20 61 20 62 6f 6f 6c 65 61  eter is a boolea
26830 6e 20 71 75 65 72 79 0a 2a 2a 20 20 20 20 20 70  n query.**     p
26840 61 72 61 6d 65 74 65 72 20 74 68 61 74 20 69 6e  arameter that in
26850 64 69 63 61 74 65 73 20 74 68 61 74 20 74 68 65  dicates that the
26860 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 69   database file i
26870 73 20 73 74 6f 72 65 64 20 6f 6e 0a 2a 2a 20 20  s stored on.**  
26880 20 20 20 72 65 61 64 2d 6f 6e 6c 79 20 6d 65 64     read-only med
26890 69 61 2e 20 20 5e 57 68 65 6e 20 69 6d 6d 75 74  ia.  ^When immut
268a0 61 62 6c 65 20 69 73 20 73 65 74 2c 20 53 51 4c  able is set, SQL
268b0 69 74 65 20 61 73 73 75 6d 65 73 20 74 68 61 74  ite assumes that
268c0 20 74 68 65 0a 2a 2a 20 20 20 20 20 64 61 74 61   the.**     data
268d0 62 61 73 65 20 66 69 6c 65 20 63 61 6e 6e 6f 74  base file cannot
268e0 20 62 65 20 63 68 61 6e 67 65 64 2c 20 65 76 65   be changed, eve
268f0 6e 20 62 79 20 61 20 70 72 6f 63 65 73 73 20 77  n by a process w
26900 69 74 68 20 68 69 67 68 65 72 0a 2a 2a 20 20 20  ith higher.**   
26910 20 20 70 72 69 76 69 6c 65 67 65 2c 20 61 6e 64    privilege, and
26920 20 73 6f 20 74 68 65 20 64 61 74 61 62 61 73 65   so the database
26930 20 69 73 20 6f 70 65 6e 65 64 20 72 65 61 64 2d   is opened read-
26940 6f 6e 6c 79 20 61 6e 64 20 61 6c 6c 20 6c 6f 63  only and all loc
26950 6b 69 6e 67 0a 2a 2a 20 20 20 20 20 61 6e 64 20  king.**     and 
26960 63 68 61 6e 67 65 20 64 65 74 65 63 74 69 6f 6e  change detection
26970 20 69 73 20 64 69 73 61 62 6c 65 64 2e 20 20 43   is disabled.  C
26980 61 75 74 69 6f 6e 3a 20 53 65 74 74 69 6e 67 20  aution: Setting 
26990 74 68 65 20 69 6d 6d 75 74 61 62 6c 65 0a 2a 2a  the immutable.**
269a0 20 20 20 20 20 70 72 6f 70 65 72 74 79 20 6f 6e       property on
269b0 20 61 20 64 61 74 61 62 61 73 65 20 66 69 6c 65   a database file
269c0 20 74 68 61 74 20 64 6f 65 73 20 69 6e 20 66 61   that does in fa
269d0 63 74 20 63 68 61 6e 67 65 20 63 61 6e 20 72 65  ct change can re
269e0 73 75 6c 74 0a 2a 2a 20 20 20 20 20 69 6e 20 69  sult.**     in i
269f0 6e 63 6f 72 72 65 63 74 20 71 75 65 72 79 20 72  ncorrect query r
26a00 65 73 75 6c 74 73 20 61 6e 64 2f 6f 72 20 5b 53  esults and/or [S
26a10 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 5d 20 65  QLITE_CORRUPT] e
26a20 72 72 6f 72 73 2e 0a 2a 2a 20 20 20 20 20 53 65  rrors..**     Se
26a30 65 20 61 6c 73 6f 3a 20 5b 53 51 4c 49 54 45 5f  e also: [SQLITE_
26a40 49 4f 43 41 50 5f 49 4d 4d 55 54 41 42 4c 45 5d  IOCAP_IMMUTABLE]
26a50 2e 0a 2a 2a 20 20 20 20 20 20 20 0a 2a 2a 20 3c  ..**       .** <
26a60 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 53 70 65 63  /ul>.**.** ^Spec
26a70 69 66 79 69 6e 67 20 61 6e 20 75 6e 6b 6e 6f 77  ifying an unknow
26a80 6e 20 70 61 72 61 6d 65 74 65 72 20 69 6e 20 74  n parameter in t
26a90 68 65 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65  he query compone
26aa0 6e 74 20 6f 66 20 61 20 55 52 49 20 69 73 20 6e  nt of a URI is n
26ab0 6f 74 20 61 6e 0a 2a 2a 20 65 72 72 6f 72 2e 20  ot an.** error. 
26ac0 20 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73   Future versions
26ad0 20 6f 66 20 53 51 4c 69 74 65 20 6d 69 67 68 74   of SQLite might
26ae0 20 75 6e 64 65 72 73 74 61 6e 64 20 61 64 64 69   understand addi
26af0 74 69 6f 6e 61 6c 20 71 75 65 72 79 0a 2a 2a 20  tional query.** 
26b00 70 61 72 61 6d 65 74 65 72 73 2e 20 20 53 65 65  parameters.  See
26b10 20 22 5b 71 75 65 72 79 20 70 61 72 61 6d 65 74   "[query paramet
26b20 65 72 73 20 77 69 74 68 20 73 70 65 63 69 61 6c  ers with special
26b30 20 6d 65 61 6e 69 6e 67 20 74 6f 20 53 51 4c 69   meaning to SQLi
26b40 74 65 5d 22 20 66 6f 72 0a 2a 2a 20 61 64 64 69  te]" for.** addi
26b50 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69  tional informati
26b60 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 55 52 49 20  on..**.** [[URI 
26b70 66 69 6c 65 6e 61 6d 65 20 65 78 61 6d 70 6c 65  filename example
26b80 73 5d 5d 20 3c 68 33 3e 55 52 49 20 66 69 6c 65  s]] <h3>URI file
26b90 6e 61 6d 65 20 65 78 61 6d 70 6c 65 73 3c 2f 68  name examples</h
26ba0 33 3e 0a 2a 2a 0a 2a 2a 20 3c 74 61 62 6c 65 20  3>.**.** <table 
26bb0 62 6f 72 64 65 72 3d 22 31 22 20 61 6c 69 67 6e  border="1" align
26bc0 3d 63 65 6e 74 65 72 20 63 65 6c 6c 70 61 64 64  =center cellpadd
26bd0 69 6e 67 3d 35 3e 0a 2a 2a 20 3c 74 72 3e 3c 74  ing=5>.** <tr><t
26be0 68 3e 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 73  h> URI filenames
26bf0 20 3c 74 68 3e 20 52 65 73 75 6c 74 73 0a 2a 2a   <th> Results.**
26c00 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 64   <tr><td> file:d
26c10 61 74 61 2e 64 62 20 3c 74 64 3e 20 0a 2a 2a 20  ata.db <td> .** 
26c20 20 20 20 20 20 20 20 20 20 4f 70 65 6e 20 74 68           Open th
26c30 65 20 66 69 6c 65 20 22 64 61 74 61 2e 64 62 22  e file "data.db"
26c40 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20   in the current 
26c50 64 69 72 65 63 74 6f 72 79 2e 0a 2a 2a 20 3c 74  directory..** <t
26c60 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f 68 6f 6d  r><td> file:/hom
26c70 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 3c 62  e/fred/data.db<b
26c80 72 3e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66  r>.**          f
26c90 69 6c 65 3a 2f 2f 2f 68 6f 6d 65 2f 66 72 65 64  ile:///home/fred
26ca0 2f 64 61 74 61 2e 64 62 20 3c 62 72 3e 20 0a 2a  /data.db <br> .*
26cb0 2a 20 20 20 20 20 20 20 20 20 20 66 69 6c 65 3a  *          file:
26cc0 2f 2f 6c 6f 63 61 6c 68 6f 73 74 2f 68 6f 6d 65  //localhost/home
26cd0 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 20 3c 62  /fred/data.db <b
26ce0 72 3e 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20  r> <td> .**     
26cf0 20 20 20 20 20 4f 70 65 6e 20 74 68 65 20 64 61       Open the da
26d00 74 61 62 61 73 65 20 66 69 6c 65 20 22 2f 68 6f  tabase file "/ho
26d10 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 22  me/fred/data.db"
26d20 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69  ..** <tr><td> fi
26d30 6c 65 3a 2f 2f 64 61 72 6b 73 74 61 72 2f 68 6f  le://darkstar/ho
26d40 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 20  me/fred/data.db 
26d50 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20  <td> .**        
26d60 20 20 41 6e 20 65 72 72 6f 72 2e 20 22 64 61 72    An error. "dar
26d70 6b 73 74 61 72 22 20 69 73 20 6e 6f 74 20 61 20  kstar" is not a 
26d80 72 65 63 6f 67 6e 69 7a 65 64 20 61 75 74 68 6f  recognized autho
26d90 72 69 74 79 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64  rity..** <tr><td
26da0 20 73 74 79 6c 65 3d 22 77 68 69 74 65 2d 73 70   style="white-sp
26db0 61 63 65 3a 6e 6f 77 72 61 70 22 3e 20 0a 2a 2a  ace:nowrap"> .**
26dc0 20 20 20 20 20 20 20 20 20 20 66 69 6c 65 3a 2f            file:/
26dd0 2f 2f 43 3a 2f 44 6f 63 75 6d 65 6e 74 73 25 32  //C:/Documents%2
26de0 30 61 6e 64 25 32 30 53 65 74 74 69 6e 67 73 2f  0and%20Settings/
26df0 66 72 65 64 2f 44 65 73 6b 74 6f 70 2f 64 61 74  fred/Desktop/dat
26e00 61 2e 64 62 0a 2a 2a 20 20 20 20 20 3c 74 64 3e  a.db.**     <td>
26e10 20 57 69 6e 64 6f 77 73 20 6f 6e 6c 79 3a 20 4f   Windows only: O
26e20 70 65 6e 20 74 68 65 20 66 69 6c 65 20 22 64 61  pen the file "da
26e30 74 61 2e 64 62 22 20 6f 6e 20 66 72 65 64 27 73  ta.db" on fred's
26e40 20 64 65 73 6b 74 6f 70 20 6f 6e 20 64 72 69 76   desktop on driv
26e50 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 43 3a  e.**          C:
26e60 2e 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20  . Note that the 
26e70 25 32 30 20 65 73 63 61 70 69 6e 67 20 69 6e 20  %20 escaping in 
26e80 74 68 69 73 20 65 78 61 6d 70 6c 65 20 69 73 20  this example is 
26e90 6e 6f 74 20 73 74 72 69 63 74 6c 79 20 0a 2a 2a  not strictly .**
26ea0 20 20 20 20 20 20 20 20 20 20 6e 65 63 65 73 73            necess
26eb0 61 72 79 20 2d 20 73 70 61 63 65 20 63 68 61 72  ary - space char
26ec0 61 63 74 65 72 73 20 63 61 6e 20 62 65 20 75 73  acters can be us
26ed0 65 64 20 6c 69 74 65 72 61 6c 6c 79 0a 2a 2a 20  ed literally.** 
26ee0 20 20 20 20 20 20 20 20 20 69 6e 20 55 52 49 20           in URI 
26ef0 66 69 6c 65 6e 61 6d 65 73 2e 0a 2a 2a 20 3c 74  filenames..** <t
26f00 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 64 61 74 61  r><td> file:data
26f10 2e 64 62 3f 6d 6f 64 65 3d 72 6f 26 63 61 63 68  .db?mode=ro&cach
26f20 65 3d 70 72 69 76 61 74 65 20 3c 74 64 3e 20 0a  e=private <td> .
26f30 2a 2a 20 20 20 20 20 20 20 20 20 20 4f 70 65 6e  **          Open
26f40 20 66 69 6c 65 20 22 64 61 74 61 2e 64 62 22 20   file "data.db" 
26f50 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20 64  in the current d
26f60 69 72 65 63 74 6f 72 79 20 66 6f 72 20 72 65 61  irectory for rea
26f70 64 2d 6f 6e 6c 79 20 61 63 63 65 73 73 2e 0a 2a  d-only access..*
26f80 2a 20 20 20 20 20 20 20 20 20 20 52 65 67 61 72  *          Regar
26f90 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65 72  dless of whether
26fa0 20 6f 72 20 6e 6f 74 20 73 68 61 72 65 64 2d 63   or not shared-c
26fb0 61 63 68 65 20 6d 6f 64 65 20 69 73 20 65 6e 61  ache mode is ena
26fc0 62 6c 65 64 20 62 79 0a 2a 2a 20 20 20 20 20 20  bled by.**      
26fd0 20 20 20 20 64 65 66 61 75 6c 74 2c 20 75 73 65      default, use
26fe0 20 61 20 70 72 69 76 61 74 65 20 63 61 63 68 65   a private cache
26ff0 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69  ..** <tr><td> fi
27000 6c 65 3a 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61  le:/home/fred/da
27010 74 61 2e 64 62 3f 76 66 73 3d 75 6e 69 78 2d 64  ta.db?vfs=unix-d
27020 6f 74 66 69 6c 65 20 3c 74 64 3e 0a 2a 2a 20 20  otfile <td>.**  
27030 20 20 20 20 20 20 20 20 4f 70 65 6e 20 66 69 6c          Open fil
27040 65 20 22 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61  e "/home/fred/da
27050 74 61 2e 64 62 22 2e 20 55 73 65 20 74 68 65 20  ta.db". Use the 
27060 73 70 65 63 69 61 6c 20 56 46 53 20 22 75 6e 69  special VFS "uni
27070 78 2d 64 6f 74 66 69 6c 65 22 0a 2a 2a 20 20 20  x-dotfile".**   
27080 20 20 20 20 20 20 20 74 68 61 74 20 75 73 65 73         that uses
27090 20 64 6f 74 2d 66 69 6c 65 73 20 69 6e 20 70 6c   dot-files in pl
270a0 61 63 65 20 6f 66 20 70 6f 73 69 78 20 61 64 76  ace of posix adv
270b0 69 73 6f 72 79 20 6c 6f 63 6b 69 6e 67 2e 0a 2a  isory locking..*
270c0 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a  * <tr><td> file:
270d0 64 61 74 61 2e 64 62 3f 6d 6f 64 65 3d 72 65 61  data.db?mode=rea
270e0 64 6f 6e 6c 79 20 3c 74 64 3e 20 0a 2a 2a 20 20  donly <td> .**  
270f0 20 20 20 20 20 20 20 20 41 6e 20 65 72 72 6f 72          An error
27100 2e 20 22 72 65 61 64 6f 6e 6c 79 22 20 69 73 20  . "readonly" is 
27110 6e 6f 74 20 61 20 76 61 6c 69 64 20 6f 70 74 69  not a valid opti
27120 6f 6e 20 66 6f 72 20 74 68 65 20 22 6d 6f 64 65  on for the "mode
27130 22 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20  " parameter..** 
27140 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 0a 2a 2a 20 5e  </table>.**.** ^
27150 55 52 49 20 68 65 78 61 64 65 63 69 6d 61 6c 20  URI hexadecimal 
27160 65 73 63 61 70 65 20 73 65 71 75 65 6e 63 65 73  escape sequences
27170 20 28 25 48 48 29 20 61 72 65 20 73 75 70 70 6f   (%HH) are suppo
27180 72 74 65 64 20 77 69 74 68 69 6e 20 74 68 65 20  rted within the 
27190 70 61 74 68 20 61 6e 64 0a 2a 2a 20 71 75 65 72  path and.** quer
271a0 79 20 63 6f 6d 70 6f 6e 65 6e 74 73 20 6f 66 20  y components of 
271b0 61 20 55 52 49 2e 20 41 20 68 65 78 61 64 65 63  a URI. A hexadec
271c0 69 6d 61 6c 20 65 73 63 61 70 65 20 73 65 71 75  imal escape sequ
271d0 65 6e 63 65 20 63 6f 6e 73 69 73 74 73 20 6f 66  ence consists of
271e0 20 61 0a 2a 2a 20 70 65 72 63 65 6e 74 20 73 69   a.** percent si
271f0 67 6e 20 2d 20 22 25 22 20 2d 20 66 6f 6c 6c 6f  gn - "%" - follo
27200 77 65 64 20 62 79 20 65 78 61 63 74 6c 79 20 74  wed by exactly t
27210 77 6f 20 68 65 78 61 64 65 63 69 6d 61 6c 20 64  wo hexadecimal d
27220 69 67 69 74 73 20 0a 2a 2a 20 73 70 65 63 69 66  igits .** specif
27230 79 69 6e 67 20 61 6e 20 6f 63 74 65 74 20 76 61  ying an octet va
27240 6c 75 65 2e 20 5e 42 65 66 6f 72 65 20 74 68 65  lue. ^Before the
27250 20 70 61 74 68 20 6f 72 20 71 75 65 72 79 20 63   path or query c
27260 6f 6d 70 6f 6e 65 6e 74 73 20 6f 66 20 61 0a 2a  omponents of a.*
27270 2a 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 20 61  * URI filename a
27280 72 65 20 69 6e 74 65 72 70 72 65 74 65 64 2c 20  re interpreted, 
27290 74 68 65 79 20 61 72 65 20 65 6e 63 6f 64 65 64  they are encoded
272a0 20 75 73 69 6e 67 20 55 54 46 2d 38 20 61 6e 64   using UTF-8 and
272b0 20 61 6c 6c 20 0a 2a 2a 20 68 65 78 61 64 65 63   all .** hexadec
272c0 69 6d 61 6c 20 65 73 63 61 70 65 20 73 65 71 75  imal escape sequ
272d0 65 6e 63 65 73 20 72 65 70 6c 61 63 65 64 20 62  ences replaced b
272e0 79 20 61 20 73 69 6e 67 6c 65 20 62 79 74 65 20  y a single byte 
272f0 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 0a 2a  containing the.*
27300 2a 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20  * corresponding 
27310 6f 63 74 65 74 2e 20 49 66 20 74 68 69 73 20 70  octet. If this p
27320 72 6f 63 65 73 73 20 67 65 6e 65 72 61 74 65 73  rocess generates
27330 20 61 6e 20 69 6e 76 61 6c 69 64 20 55 54 46 2d   an invalid UTF-
27340 38 20 65 6e 63 6f 64 69 6e 67 2c 0a 2a 2a 20 74  8 encoding,.** t
27350 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 75  he results are u
27360 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  ndefined..**.** 
27370 3c 62 3e 4e 6f 74 65 20 74 6f 20 57 69 6e 64 6f  <b>Note to Windo
27380 77 73 20 75 73 65 72 73 3a 3c 2f 62 3e 20 20 54  ws users:</b>  T
27390 68 65 20 65 6e 63 6f 64 69 6e 67 20 75 73 65 64  he encoding used
273a0 20 66 6f 72 20 74 68 65 20 66 69 6c 65 6e 61 6d   for the filenam
273b0 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 6f 66  e argument.** of
273c0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20   sqlite3_open() 
273d0 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  and sqlite3_open
273e0 5f 76 32 28 29 20 6d 75 73 74 20 62 65 20 55 54  _v2() must be UT
273f0 46 2d 38 2c 20 6e 6f 74 20 77 68 61 74 65 76 65  F-8, not whateve
27400 72 0a 2a 2a 20 63 6f 64 65 70 61 67 65 20 69 73  r.** codepage is
27410 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e   currently defin
27420 65 64 2e 20 20 46 69 6c 65 6e 61 6d 65 73 20 63  ed.  Filenames c
27430 6f 6e 74 61 69 6e 69 6e 67 20 69 6e 74 65 72 6e  ontaining intern
27440 61 74 69 6f 6e 61 6c 0a 2a 2a 20 63 68 61 72 61  ational.** chara
27450 63 74 65 72 73 20 6d 75 73 74 20 62 65 20 63 6f  cters must be co
27460 6e 76 65 72 74 65 64 20 74 6f 20 55 54 46 2d 38  nverted to UTF-8
27470 20 70 72 69 6f 72 20 74 6f 20 70 61 73 73 69 6e   prior to passin
27480 67 20 74 68 65 6d 20 69 6e 74 6f 0a 2a 2a 20 73  g them into.** s
27490 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72  qlite3_open() or
274a0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
274b0 28 29 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74  ()..**.** <b>Not
274c0 65 20 74 6f 20 57 69 6e 64 6f 77 73 20 52 75 6e  e to Windows Run
274d0 74 69 6d 65 20 75 73 65 72 73 3a 3c 2f 62 3e 20  time users:</b> 
274e0 20 54 68 65 20 74 65 6d 70 6f 72 61 72 79 20 64   The temporary d
274f0 69 72 65 63 74 6f 72 79 20 6d 75 73 74 20 62 65  irectory must be
27500 20 73 65 74 0a 2a 2a 20 70 72 69 6f 72 20 74 6f   set.** prior to
27510 20 63 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33   calling sqlite3
27520 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c 69 74  _open() or sqlit
27530 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 20 4f  e3_open_v2().  O
27540 74 68 65 72 77 69 73 65 2c 20 76 61 72 69 6f 75  therwise, variou
27550 73 0a 2a 2a 20 66 65 61 74 75 72 65 73 20 74 68  s.** features th
27560 61 74 20 72 65 71 75 69 72 65 20 74 68 65 20 75  at require the u
27570 73 65 20 6f 66 20 74 65 6d 70 6f 72 61 72 79 20  se of temporary 
27580 66 69 6c 65 73 20 6d 61 79 20 66 61 69 6c 2e 0a  files may fail..
27590 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20  **.** See also: 
275a0 5b 73 71 6c 69 74 65 33 5f 74 65 6d 70 5f 64 69  [sqlite3_temp_di
275b0 72 65 63 74 6f 72 79 5d 0a 2a 2f 0a 53 51 4c 49  rectory].*/.SQLI
275c0 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
275d0 65 33 5f 6f 70 65 6e 28 0a 20 20 63 6f 6e 73 74  e3_open(.  const
275e0 20 63 68 61 72 20 2a 66 69 6c 65 6e 61 6d 65 2c   char *filename,
275f0 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66     /* Database f
27600 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 38 29 20  ilename (UTF-8) 
27610 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70  */.  sqlite3 **p
27620 70 44 62 20 20 20 20 20 20 20 20 20 20 2f 2a 20  pDb          /* 
27630 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68  OUT: SQLite db h
27640 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 53 51 4c 49  andle */.);.SQLI
27650 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
27660 65 33 5f 6f 70 65 6e 31 36 28 0a 20 20 63 6f 6e  e3_open16(.  con
27670 73 74 20 76 6f 69 64 20 2a 66 69 6c 65 6e 61 6d  st void *filenam
27680 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65  e,   /* Database
27690 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 31   filename (UTF-1
276a0 36 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20  6) */.  sqlite3 
276b0 2a 2a 70 70 44 62 20 20 20 20 20 20 20 20 20 20  **ppDb          
276c0 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64  /* OUT: SQLite d
276d0 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 53  b handle */.);.S
276e0 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
276f0 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 0a 20  lite3_open_v2(. 
27700 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 66 69 6c   const char *fil
27710 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61  ename,   /* Data
27720 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 55  base filename (U
27730 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71 6c 69 74  TF-8) */.  sqlit
27740 65 33 20 2a 2a 70 70 44 62 2c 20 20 20 20 20 20  e3 **ppDb,      
27750 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74     /* OUT: SQLit
27760 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 20  e db handle */. 
27770 20 69 6e 74 20 66 6c 61 67 73 2c 20 20 20 20 20   int flags,     
27780 20 20 20 20 20 20 20 20 20 2f 2a 20 46 6c 61 67           /* Flag
27790 73 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  s */.  const cha
277a0 72 20 2a 7a 56 66 73 20 20 20 20 20 20 20 20 2f  r *zVfs        /
277b0 2a 20 4e 61 6d 65 20 6f 66 20 56 46 53 20 6d 6f  * Name of VFS mo
277c0 64 75 6c 65 20 74 6f 20 75 73 65 20 2a 2f 0a 29  dule to use */.)
277d0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
277e0 46 3a 20 4f 62 74 61 69 6e 20 56 61 6c 75 65 73  F: Obtain Values
277f0 20 46 6f 72 20 55 52 49 20 50 61 72 61 6d 65 74   For URI Paramet
27800 65 72 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ers.**.** These 
27810 61 72 65 20 75 74 69 6c 69 74 79 20 72 6f 75 74  are utility rout
27820 69 6e 65 73 2c 20 75 73 65 66 75 6c 20 74 6f 20  ines, useful to 
27830 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  VFS implementati
27840 6f 6e 73 2c 20 74 68 61 74 20 63 68 65 63 6b 0a  ons, that check.
27850 2a 2a 20 74 6f 20 73 65 65 20 69 66 20 61 20 64  ** to see if a d
27860 61 74 61 62 61 73 65 20 66 69 6c 65 20 77 61 73  atabase file was
27870 20 61 20 55 52 49 20 74 68 61 74 20 63 6f 6e 74   a URI that cont
27880 61 69 6e 65 64 20 61 20 73 70 65 63 69 66 69 63  ained a specific
27890 20 71 75 65 72 79 20 0a 2a 2a 20 70 61 72 61 6d   query .** param
278a0 65 74 65 72 2c 20 61 6e 64 20 69 66 20 73 6f 20  eter, and if so 
278b0 6f 62 74 61 69 6e 73 20 74 68 65 20 76 61 6c 75  obtains the valu
278c0 65 20 6f 66 20 74 68 61 74 20 71 75 65 72 79 20  e of that query 
278d0 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a  parameter..**.**
278e0 20 49 66 20 46 20 69 73 20 74 68 65 20 64 61 74   If F is the dat
278f0 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 70  abase filename p
27900 6f 69 6e 74 65 72 20 70 61 73 73 65 64 20 69 6e  ointer passed in
27910 74 6f 20 74 68 65 20 78 4f 70 65 6e 28 29 20 6d  to the xOpen() m
27920 65 74 68 6f 64 20 6f 66 20 0a 2a 2a 20 61 20 56  ethod of .** a V
27930 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  FS implementatio
27940 6e 20 77 68 65 6e 20 74 68 65 20 66 6c 61 67 73  n when the flags
27950 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 78 4f   parameter to xO
27960 70 65 6e 28 29 20 68 61 73 20 6f 6e 65 20 6f 72  pen() has one or
27970 20 0a 2a 2a 20 6d 6f 72 65 20 6f 66 20 74 68 65   .** more of the
27980 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52   [SQLITE_OPEN_UR
27990 49 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4f 50  I] or [SQLITE_OP
279a0 45 4e 5f 4d 41 49 4e 5f 44 42 5d 20 62 69 74 73  EN_MAIN_DB] bits
279b0 20 73 65 74 20 61 6e 64 0a 2a 2a 20 50 20 69 73   set and.** P is
279c0 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
279d0 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72   query parameter
279e0 2c 20 74 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65  , then.** sqlite
279f0 33 5f 75 72 69 5f 70 61 72 61 6d 65 74 65 72 28  3_uri_parameter(
27a00 46 2c 50 29 20 72 65 74 75 72 6e 73 20 74 68 65  F,P) returns the
27a10 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 50 0a   value of the P.
27a20 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 69 66 20  ** parameter if 
27a30 69 74 20 65 78 69 73 74 73 20 6f 72 20 61 20 4e  it exists or a N
27a40 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 66 20 50  ULL pointer if P
27a50 20 64 6f 65 73 20 6e 6f 74 20 61 70 70 65 61 72   does not appear
27a60 20 61 73 20 61 20 0a 2a 2a 20 71 75 65 72 79 20   as a .** query 
27a70 70 61 72 61 6d 65 74 65 72 20 6f 6e 20 46 2e 20  parameter on F. 
27a80 20 49 66 20 50 20 69 73 20 61 20 71 75 65 72 79   If P is a query
27a90 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 46 0a   parameter of F.
27aa0 2a 2a 20 68 61 73 20 6e 6f 20 65 78 70 6c 69 63  ** has no explic
27ab0 69 74 20 76 61 6c 75 65 2c 20 74 68 65 6e 20 73  it value, then s
27ac0 71 6c 69 74 65 33 5f 75 72 69 5f 70 61 72 61 6d  qlite3_uri_param
27ad0 65 74 65 72 28 46 2c 50 29 20 72 65 74 75 72 6e  eter(F,P) return
27ae0 73 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74  s.** a pointer t
27af0 6f 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e  o an empty strin
27b00 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  g..**.** The sql
27b10 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e  ite3_uri_boolean
27b20 28 46 2c 50 2c 42 29 20 72 6f 75 74 69 6e 65 20  (F,P,B) routine 
27b30 61 73 73 75 6d 65 73 20 74 68 61 74 20 50 20 69  assumes that P i
27b40 73 20 61 20 62 6f 6f 6c 65 61 6e 0a 2a 2a 20 70  s a boolean.** p
27b50 61 72 61 6d 65 74 65 72 20 61 6e 64 20 72 65 74  arameter and ret
27b60 75 72 6e 73 20 74 72 75 65 20 28 31 29 20 6f 72  urns true (1) or
27b70 20 66 61 6c 73 65 20 28 30 29 20 61 63 63 6f 72   false (0) accor
27b80 64 69 6e 67 20 74 6f 20 74 68 65 20 76 61 6c 75  ding to the valu
27b90 65 0a 2a 2a 20 6f 66 20 50 2e 20 20 54 68 65 20  e.** of P.  The 
27ba0 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c  sqlite3_uri_bool
27bb0 65 61 6e 28 46 2c 50 2c 42 29 20 72 6f 75 74 69  ean(F,P,B) routi
27bc0 6e 65 20 72 65 74 75 72 6e 73 20 74 72 75 65 20  ne returns true 
27bd0 28 31 29 20 69 66 20 74 68 65 0a 2a 2a 20 76 61  (1) if the.** va
27be0 6c 75 65 20 6f 66 20 71 75 65 72 79 20 70 61 72  lue of query par
27bf0 61 6d 65 74 65 72 20 50 20 69 73 20 6f 6e 65 20  ameter P is one 
27c00 6f 66 20 22 79 65 73 22 2c 20 22 74 72 75 65 22  of "yes", "true"
27c10 2c 20 6f 72 20 22 6f 6e 22 20 69 6e 20 61 6e 79  , or "on" in any
27c20 0a 2a 2a 20 63 61 73 65 20 6f 72 20 69 66 20 74  .** case or if t
27c30 68 65 20 76 61 6c 75 65 20 62 65 67 69 6e 73 20  he value begins 
27c40 77 69 74 68 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20  with a non-zero 
27c50 6e 75 6d 62 65 72 2e 20 20 54 68 65 20 0a 2a 2a  number.  The .**
27c60 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f   sqlite3_uri_boo
27c70 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 6f 75 74  lean(F,P,B) rout
27c80 69 6e 65 73 20 72 65 74 75 72 6e 73 20 66 61 6c  ines returns fal
27c90 73 65 20 28 30 29 20 69 66 20 74 68 65 20 76 61  se (0) if the va
27ca0 6c 75 65 20 6f 66 0a 2a 2a 20 71 75 65 72 79 20  lue of.** query 
27cb0 70 61 72 61 6d 65 74 65 72 20 50 20 69 73 20 6f  parameter P is o
27cc0 6e 65 20 6f 66 20 22 6e 6f 22 2c 20 22 66 61 6c  ne of "no", "fal
27cd0 73 65 22 2c 20 6f 72 20 22 6f 66 66 22 20 69 6e  se", or "off" in
27ce0 20 61 6e 79 20 63 61 73 65 20 6f 72 0a 2a 2a 20   any case or.** 
27cf0 69 66 20 74 68 65 20 76 61 6c 75 65 20 62 65 67  if the value beg
27d00 69 6e 73 20 77 69 74 68 20 61 20 6e 75 6d 65 72  ins with a numer
27d10 69 63 20 7a 65 72 6f 2e 20 20 49 66 20 50 20 69  ic zero.  If P i
27d20 73 20 6e 6f 74 20 61 20 71 75 65 72 79 0a 2a 2a  s not a query.**
27d30 20 70 61 72 61 6d 65 74 65 72 20 6f 6e 20 46 20   parameter on F 
27d40 6f 72 20 69 66 20 74 68 65 20 76 61 6c 75 65 20  or if the value 
27d50 6f 66 20 50 20 69 73 20 64 6f 65 73 20 6e 6f 74  of P is does not
27d60 20 6d 61 74 63 68 20 61 6e 79 20 6f 66 20 74 68   match any of th
27d70 65 0a 2a 2a 20 61 62 6f 76 65 2c 20 74 68 65 6e  e.** above, then
27d80 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f   sqlite3_uri_boo
27d90 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 65 74 75  lean(F,P,B) retu
27da0 72 6e 73 20 28 42 21 3d 30 29 2e 0a 2a 2a 0a 2a  rns (B!=0)..**.*
27db0 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 75 72  * The sqlite3_ur
27dc0 69 5f 69 6e 74 36 34 28 46 2c 50 2c 44 29 20 72  i_int64(F,P,D) r
27dd0 6f 75 74 69 6e 65 20 63 6f 6e 76 65 72 74 73 20  outine converts 
27de0 74 68 65 20 76 61 6c 75 65 20 6f 66 20 50 20 69  the value of P i
27df0 6e 74 6f 20 61 0a 2a 2a 20 36 34 2d 62 69 74 20  nto a.** 64-bit 
27e00 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 20 61  signed integer a
27e10 6e 64 20 72 65 74 75 72 6e 73 20 74 68 61 74 20  nd returns that 
27e20 69 6e 74 65 67 65 72 2c 20 6f 72 20 44 20 69 66  integer, or D if
27e30 20 50 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 65   P does not.** e
27e40 78 69 73 74 2e 20 20 49 66 20 74 68 65 20 76 61  xist.  If the va
27e50 6c 75 65 20 6f 66 20 50 20 69 73 20 73 6f 6d 65  lue of P is some
27e60 74 68 69 6e 67 20 6f 74 68 65 72 20 74 68 61 6e  thing other than
27e70 20 61 6e 20 69 6e 74 65 67 65 72 2c 20 74 68 65   an integer, the
27e80 6e 0a 2a 2a 20 7a 65 72 6f 20 69 73 20 72 65 74  n.** zero is ret
27e90 75 72 6e 65 64 2e 0a 2a 2a 20 0a 2a 2a 20 49 66  urned..** .** If
27ea0 20 46 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69   F is a NULL poi
27eb0 6e 74 65 72 2c 20 74 68 65 6e 20 73 71 6c 69 74  nter, then sqlit
27ec0 65 33 5f 75 72 69 5f 70 61 72 61 6d 65 74 65 72  e3_uri_parameter
27ed0 28 46 2c 50 29 20 72 65 74 75 72 6e 73 20 4e 55  (F,P) returns NU
27ee0 4c 4c 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65  LL and.** sqlite
27ef0 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c  3_uri_boolean(F,
27f00 50 2c 42 29 20 72 65 74 75 72 6e 73 20 42 2e 20  P,B) returns B. 
27f10 20 49 66 20 46 20 69 73 20 6e 6f 74 20 61 20 4e   If F is not a N
27f20 55 4c 4c 20 70 6f 69 6e 74 65 72 20 61 6e 64 0a  ULL pointer and.
27f30 2a 2a 20 69 73 20 6e 6f 74 20 61 20 64 61 74 61  ** is not a data
27f40 62 61 73 65 20 66 69 6c 65 20 70 61 74 68 6e 61  base file pathna
27f50 6d 65 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20  me pointer that 
27f60 53 51 4c 69 74 65 20 70 61 73 73 65 64 20 69 6e  SQLite passed in
27f70 74 6f 20 74 68 65 20 78 4f 70 65 6e 0a 2a 2a 20  to the xOpen.** 
27f80 56 46 53 20 6d 65 74 68 6f 64 2c 20 74 68 65 6e  VFS method, then
27f90 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66   the behavior of
27fa0 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73   this routine is
27fb0 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 20 70   undefined and p
27fc0 72 6f 62 61 62 6c 79 0a 2a 2a 20 75 6e 64 65 73  robably.** undes
27fd0 69 72 61 62 6c 65 2e 0a 2a 2f 0a 53 51 4c 49 54  irable..*/.SQLIT
27fe0 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72  E_API const char
27ff0 20 2a 73 71 6c 69 74 65 33 5f 75 72 69 5f 70 61   *sqlite3_uri_pa
28000 72 61 6d 65 74 65 72 28 63 6f 6e 73 74 20 63 68  rameter(const ch
28010 61 72 20 2a 7a 46 69 6c 65 6e 61 6d 65 2c 20 63  ar *zFilename, c
28020 6f 6e 73 74 20 63 68 61 72 20 2a 7a 50 61 72 61  onst char *zPara
28030 6d 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  m);.SQLITE_API i
28040 6e 74 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62  nt sqlite3_uri_b
28050 6f 6f 6c 65 61 6e 28 63 6f 6e 73 74 20 63 68 61  oolean(const cha
28060 72 20 2a 7a 46 69 6c 65 2c 20 63 6f 6e 73 74 20  r *zFile, const 
28070 63 68 61 72 20 2a 7a 50 61 72 61 6d 2c 20 69 6e  char *zParam, in
28080 74 20 62 44 65 66 61 75 6c 74 29 3b 0a 53 51 4c  t bDefault);.SQL
28090 49 54 45 5f 41 50 49 20 73 71 6c 69 74 65 33 5f  ITE_API sqlite3_
280a0 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 75 72  int64 sqlite3_ur
280b0 69 5f 69 6e 74 36 34 28 63 6f 6e 73 74 20 63 68  i_int64(const ch
280c0 61 72 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a  ar*, const char*
280d0 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29  , sqlite3_int64)
280e0 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  ;.../*.** CAPI3R
280f0 45 46 3a 20 45 72 72 6f 72 20 43 6f 64 65 73 20  EF: Error Codes 
28100 41 6e 64 20 4d 65 73 73 61 67 65 73 0a 2a 2a 20  And Messages.** 
28110 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a  METHOD: sqlite3.
28120 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f  **.** ^If the mo
28130 73 74 20 72 65 63 65 6e 74 20 73 71 6c 69 74 65  st recent sqlite
28140 33 5f 2a 20 41 50 49 20 63 61 6c 6c 20 61 73 73  3_* API call ass
28150 6f 63 69 61 74 65 64 20 77 69 74 68 20 0a 2a 2a  ociated with .**
28160 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
28170 63 74 69 6f 6e 5d 20 44 20 66 61 69 6c 65 64 2c  ction] D failed,
28180 20 74 68 65 6e 20 74 68 65 20 73 71 6c 69 74 65   then the sqlite
28190 33 5f 65 72 72 63 6f 64 65 28 44 29 20 69 6e 74  3_errcode(D) int
281a0 65 72 66 61 63 65 0a 2a 2a 20 72 65 74 75 72 6e  erface.** return
281b0 73 20 74 68 65 20 6e 75 6d 65 72 69 63 20 5b 72  s the numeric [r
281c0 65 73 75 6c 74 20 63 6f 64 65 5d 20 6f 72 20 5b  esult code] or [
281d0 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
281e0 63 6f 64 65 5d 20 66 6f 72 20 74 68 61 74 0a 2a  code] for that.*
281f0 2a 20 41 50 49 20 63 61 6c 6c 2e 0a 2a 2a 20 49  * API call..** I
28200 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  f the most recen
28210 74 20 41 50 49 20 63 61 6c 6c 20 77 61 73 20 73  t API call was s
28220 75 63 63 65 73 73 66 75 6c 2c 0a 2a 2a 20 74 68  uccessful,.** th
28230 65 6e 20 74 68 65 20 72 65 74 75 72 6e 20 76 61  en the return va
28240 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33  lue from sqlite3
28250 5f 65 72 72 63 6f 64 65 28 29 20 69 73 20 75 6e  _errcode() is un
28260 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 5e 54 68 65  defined..** ^The
28270 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65   sqlite3_extende
28280 64 5f 65 72 72 63 6f 64 65 28 29 0a 2a 2a 20 69  d_errcode().** i
28290 6e 74 65 72 66 61 63 65 20 69 73 20 74 68 65 20  nterface is the 
282a0 73 61 6d 65 20 65 78 63 65 70 74 20 74 68 61 74  same except that
282b0 20 69 74 20 61 6c 77 61 79 73 20 72 65 74 75 72   it always retur
282c0 6e 73 20 74 68 65 20 0a 2a 2a 20 5b 65 78 74 65  ns the .** [exte
282d0 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65  nded result code
282e0 5d 20 65 76 65 6e 20 77 68 65 6e 20 65 78 74 65  ] even when exte
282f0 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65  nded result code
28300 73 20 61 72 65 0a 2a 2a 20 64 69 73 61 62 6c 65  s are.** disable
28310 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  d..**.** ^The sq
28320 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 20 61  lite3_errmsg() a
28330 6e 64 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  nd sqlite3_errms
28340 67 31 36 28 29 20 72 65 74 75 72 6e 20 45 6e 67  g16() return Eng
28350 6c 69 73 68 2d 6c 61 6e 67 75 61 67 65 0a 2a 2a  lish-language.**
28360 20 74 65 78 74 20 74 68 61 74 20 64 65 73 63 72   text that descr
28370 69 62 65 73 20 74 68 65 20 65 72 72 6f 72 2c 20  ibes the error, 
28380 61 73 20 65 69 74 68 65 72 20 55 54 46 2d 38 20  as either UTF-8 
28390 6f 72 20 55 54 46 2d 31 36 20 72 65 73 70 65 63  or UTF-16 respec
283a0 74 69 76 65 6c 79 2e 0a 2a 2a 20 5e 28 4d 65 6d  tively..** ^(Mem
283b0 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20  ory to hold the 
283c0 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73 74  error message st
283d0 72 69 6e 67 20 69 73 20 6d 61 6e 61 67 65 64 20  ring is managed 
283e0 69 6e 74 65 72 6e 61 6c 6c 79 2e 0a 2a 2a 20 54  internally..** T
283f0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64  he application d
28400 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20  oes not need to 
28410 77 6f 72 72 79 20 61 62 6f 75 74 20 66 72 65 65  worry about free
28420 69 6e 67 20 74 68 65 20 72 65 73 75 6c 74 2e 0a  ing the result..
28430 2a 2a 20 48 6f 77 65 76 65 72 2c 20 74 68 65 20  ** However, the 
28440 65 72 72 6f 72 20 73 74 72 69 6e 67 20 6d 69 67  error string mig
28450 68 74 20 62 65 20 6f 76 65 72 77 72 69 74 74 65  ht be overwritte
28460 6e 20 6f 72 20 64 65 61 6c 6c 6f 63 61 74 65 64  n or deallocated
28470 20 62 79 0a 2a 2a 20 73 75 62 73 65 71 75 65 6e   by.** subsequen
28480 74 20 63 61 6c 6c 73 20 74 6f 20 6f 74 68 65 72  t calls to other
28490 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63   SQLite interfac
284a0 65 20 66 75 6e 63 74 69 6f 6e 73 2e 29 5e 0a 2a  e functions.)^.*
284b0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
284c0 33 5f 65 72 72 73 74 72 28 29 20 69 6e 74 65 72  3_errstr() inter
284d0 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65  face returns the
284e0 20 45 6e 67 6c 69 73 68 2d 6c 61 6e 67 75 61 67   English-languag
284f0 65 20 74 65 78 74 0a 2a 2a 20 74 68 61 74 20 64  e text.** that d
28500 65 73 63 72 69 62 65 73 20 74 68 65 20 5b 72 65  escribes the [re
28510 73 75 6c 74 20 63 6f 64 65 5d 2c 20 61 73 20 55  sult code], as U
28520 54 46 2d 38 2e 0a 2a 2a 20 5e 28 4d 65 6d 6f 72  TF-8..** ^(Memor
28530 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 65 72  y to hold the er
28540 72 6f 72 20 6d 65 73 73 61 67 65 20 73 74 72 69  ror message stri
28550 6e 67 20 69 73 20 6d 61 6e 61 67 65 64 20 69 6e  ng is managed in
28560 74 65 72 6e 61 6c 6c 79 0a 2a 2a 20 61 6e 64 20  ternally.** and 
28570 6d 75 73 74 20 6e 6f 74 20 62 65 20 66 72 65 65  must not be free
28580 64 20 62 79 20 74 68 65 20 61 70 70 6c 69 63 61  d by the applica
28590 74 69 6f 6e 29 5e 2e 0a 2a 2a 0a 2a 2a 20 57 68  tion)^..**.** Wh
285a0 65 6e 20 74 68 65 20 73 65 72 69 61 6c 69 7a 65  en the serialize
285b0 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64  d [threading mod
285c0 65 5d 20 69 73 20 69 6e 20 75 73 65 2c 20 69 74  e] is in use, it
285d0 20 6d 69 67 68 74 20 62 65 20 74 68 65 0a 2a 2a   might be the.**
285e0 20 63 61 73 65 20 74 68 61 74 20 61 20 73 65 63   case that a sec
285f0 6f 6e 64 20 65 72 72 6f 72 20 6f 63 63 75 72 73  ond error occurs
28600 20 6f 6e 20 61 20 73 65 70 61 72 61 74 65 20 74   on a separate t
28610 68 72 65 61 64 20 69 6e 20 62 65 74 77 65 65 6e  hread in between
28620 0a 2a 2a 20 74 68 65 20 74 69 6d 65 20 6f 66 20  .** the time of 
28630 74 68 65 20 66 69 72 73 74 20 65 72 72 6f 72 20  the first error 
28640 61 6e 64 20 74 68 65 20 63 61 6c 6c 20 74 6f 20  and the call to 
28650 74 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73  these interfaces
28660 2e 0a 2a 2a 20 57 68 65 6e 20 74 68 61 74 20 68  ..** When that h
28670 61 70 70 65 6e 73 2c 20 74 68 65 20 73 65 63 6f  appens, the seco
28680 6e 64 20 65 72 72 6f 72 20 77 69 6c 6c 20 62 65  nd error will be
28690 20 72 65 70 6f 72 74 65 64 20 73 69 6e 63 65 20   reported since 
286a0 74 68 65 73 65 0a 2a 2a 20 69 6e 74 65 72 66 61  these.** interfa
286b0 63 65 73 20 61 6c 77 61 79 73 20 72 65 70 6f 72  ces always repor
286c0 74 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  t the most recen
286d0 74 20 72 65 73 75 6c 74 2e 20 20 54 6f 20 61 76  t result.  To av
286e0 6f 69 64 0a 2a 2a 20 74 68 69 73 2c 20 65 61 63  oid.** this, eac
286f0 68 20 74 68 72 65 61 64 20 63 61 6e 20 6f 62 74  h thread can obt
28700 61 69 6e 20 65 78 63 6c 75 73 69 76 65 20 75 73  ain exclusive us
28710 65 20 6f 66 20 74 68 65 20 5b 64 61 74 61 62 61  e of the [databa
28720 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44  se connection] D
28730 0a 2a 2a 20 62 79 20 69 6e 76 6f 6b 69 6e 67 20  .** by invoking 
28740 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 65  [sqlite3_mutex_e
28750 6e 74 65 72 5d 28 5b 73 71 6c 69 74 65 33 5f 64  nter]([sqlite3_d
28760 62 5f 6d 75 74 65 78 5d 28 44 29 29 20 62 65 66  b_mutex](D)) bef
28770 6f 72 65 20 62 65 67 69 6e 6e 69 6e 67 0a 2a 2a  ore beginning.**
28780 20 74 6f 20 75 73 65 20 44 20 61 6e 64 20 69 6e   to use D and in
28790 76 6f 6b 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  voking [sqlite3_
287a0 6d 75 74 65 78 5f 6c 65 61 76 65 5d 28 5b 73 71  mutex_leave]([sq
287b0 6c 69 74 65 33 5f 64 62 5f 6d 75 74 65 78 5d 28  lite3_db_mutex](
287c0 44 29 29 20 61 66 74 65 72 0a 2a 2a 20 61 6c 6c  D)) after.** all
287d0 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 20 69 6e   calls to the in
287e0 74 65 72 66 61 63 65 73 20 6c 69 73 74 65 64 20  terfaces listed 
287f0 68 65 72 65 20 61 72 65 20 63 6f 6d 70 6c 65 74  here are complet
28800 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 20  ed..**.** If an 
28810 69 6e 74 65 72 66 61 63 65 20 66 61 69 6c 73 20  interface fails 
28820 77 69 74 68 20 53 51 4c 49 54 45 5f 4d 49 53 55  with SQLITE_MISU
28830 53 45 2c 20 74 68 61 74 20 6d 65 61 6e 73 20 74  SE, that means t
28840 68 65 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20  he interface.** 
28850 77 61 73 20 69 6e 76 6f 6b 65 64 20 69 6e 63 6f  was invoked inco
28860 72 72 65 63 74 6c 79 20 62 79 20 74 68 65 20 61  rrectly by the a
28870 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20 49 6e 20  pplication.  In 
28880 74 68 61 74 20 63 61 73 65 2c 20 74 68 65 0a 2a  that case, the.*
28890 2a 20 65 72 72 6f 72 20 63 6f 64 65 20 61 6e 64  * error code and
288a0 20 6d 65 73 73 61 67 65 20 6d 61 79 20 6f 72 20   message may or 
288b0 6d 61 79 20 6e 6f 74 20 62 65 20 73 65 74 2e 0a  may not be set..
288c0 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  */.SQLITE_API in
288d0 74 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64  t sqlite3_errcod
288e0 65 28 73 71 6c 69 74 65 33 20 2a 64 62 29 3b 0a  e(sqlite3 *db);.
288f0 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
28900 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f  qlite3_extended_
28910 65 72 72 63 6f 64 65 28 73 71 6c 69 74 65 33 20  errcode(sqlite3 
28920 2a 64 62 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  *db);.SQLITE_API
28930 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c   const char *sql
28940 69 74 65 33 5f 65 72 72 6d 73 67 28 73 71 6c 69  ite3_errmsg(sqli
28950 74 65 33 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50  te3*);.SQLITE_AP
28960 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  I const void *sq
28970 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 73  lite3_errmsg16(s
28980 71 6c 69 74 65 33 2a 29 3b 0a 53 51 4c 49 54 45  qlite3*);.SQLITE
28990 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20  _API const char 
289a0 2a 73 71 6c 69 74 65 33 5f 65 72 72 73 74 72 28  *sqlite3_errstr(
289b0 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  int);../*.** CAP
289c0 49 33 52 45 46 3a 20 50 72 65 70 61 72 65 64 20  I3REF: Prepared 
289d0 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74  Statement Object
289e0 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70  .** KEYWORDS: {p
289f0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
28a00 74 7d 20 7b 70 72 65 70 61 72 65 64 20 73 74 61  t} {prepared sta
28a10 74 65 6d 65 6e 74 73 7d 0a 2a 2a 0a 2a 2a 20 41  tements}.**.** A
28a20 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  n instance of th
28a30 69 73 20 6f 62 6a 65 63 74 20 72 65 70 72 65 73  is object repres
28a40 65 6e 74 73 20 61 20 73 69 6e 67 6c 65 20 53 51  ents a single SQ
28a50 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74  L statement that
28a60 0a 2a 2a 20 68 61 73 20 62 65 65 6e 20 63 6f 6d  .** has been com
28a70 70 69 6c 65 64 20 69 6e 74 6f 20 62 69 6e 61 72  piled into binar
28a80 79 20 66 6f 72 6d 20 61 6e 64 20 69 73 20 72 65  y form and is re
28a90 61 64 79 20 74 6f 20 62 65 20 65 76 61 6c 75 61  ady to be evalua
28aa0 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 6e 6b  ted..**.** Think
28ab0 20 6f 66 20 65 61 63 68 20 53 51 4c 20 73 74 61   of each SQL sta
28ac0 74 65 6d 65 6e 74 20 61 73 20 61 20 73 65 70 61  tement as a sepa
28ad0 72 61 74 65 20 63 6f 6d 70 75 74 65 72 20 70 72  rate computer pr
28ae0 6f 67 72 61 6d 2e 20 20 54 68 65 0a 2a 2a 20 6f  ogram.  The.** o
28af0 72 69 67 69 6e 61 6c 20 53 51 4c 20 74 65 78 74  riginal SQL text
28b00 20 69 73 20 73 6f 75 72 63 65 20 63 6f 64 65 2e   is source code.
28b10 20 20 41 20 70 72 65 70 61 72 65 64 20 73 74 61    A prepared sta
28b20 74 65 6d 65 6e 74 20 6f 62 6a 65 63 74 20 0a 2a  tement object .*
28b30 2a 20 69 73 20 74 68 65 20 63 6f 6d 70 69 6c 65  * is the compile
28b40 64 20 6f 62 6a 65 63 74 20 63 6f 64 65 2e 20 20  d object code.  
28b50 41 6c 6c 20 53 51 4c 20 6d 75 73 74 20 62 65 20  All SQL must be 
28b60 63 6f 6e 76 65 72 74 65 64 20 69 6e 74 6f 20 61  converted into a
28b70 0a 2a 2a 20 70 72 65 70 61 72 65 64 20 73 74 61  .** prepared sta
28b80 74 65 6d 65 6e 74 20 62 65 66 6f 72 65 20 69 74  tement before it
28b90 20 63 61 6e 20 62 65 20 72 75 6e 2e 0a 2a 2a 0a   can be run..**.
28ba0 2a 2a 20 54 68 65 20 6c 69 66 65 2d 63 79 63 6c  ** The life-cycl
28bb0 65 20 6f 66 20 61 20 70 72 65 70 61 72 65 64 20  e of a prepared 
28bc0 73 74 61 74 65 6d 65 6e 74 20 6f 62 6a 65 63 74  statement object
28bd0 20 75 73 75 61 6c 6c 79 20 67 6f 65 73 20 6c 69   usually goes li
28be0 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c  ke this:.**.** <
28bf0 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 43 72 65 61  ol>.** <li> Crea
28c00 74 65 20 74 68 65 20 70 72 65 70 61 72 65 64 20  te the prepared 
28c10 73 74 61 74 65 6d 65 6e 74 20 6f 62 6a 65 63 74  statement object
28c20 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
28c30 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2e 0a 2a  prepare_v2()]..*
28c40 2a 20 3c 6c 69 3e 20 42 69 6e 64 20 76 61 6c 75  * <li> Bind valu
28c50 65 73 20 74 6f 20 5b 70 61 72 61 6d 65 74 65 72  es to [parameter
28c60 73 5d 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c  s] using the sql
28c70 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 0a 2a 2a  ite3_bind_*().**
28c80 20 20 20 20 20 20 69 6e 74 65 72 66 61 63 65 73        interfaces
28c90 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 75 6e 20 74 68  ..** <li> Run th
28ca0 65 20 53 51 4c 20 62 79 20 63 61 6c 6c 69 6e 67  e SQL by calling
28cb0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
28cc0 5d 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69  ] one or more ti
28cd0 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 65 73  mes..** <li> Res
28ce0 65 74 20 74 68 65 20 70 72 65 70 61 72 65 64 20  et the prepared 
28cf0 73 74 61 74 65 6d 65 6e 74 20 75 73 69 6e 67 20  statement using 
28d00 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
28d10 5d 20 74 68 65 6e 20 67 6f 20 62 61 63 6b 0a 2a  ] then go back.*
28d20 2a 20 20 20 20 20 20 74 6f 20 73 74 65 70 20 32  *      to step 2
28d30 2e 20 20 44 6f 20 74 68 69 73 20 7a 65 72 6f 20  .  Do this zero 
28d40 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a 2a  or more times..*
28d50 2a 20 3c 6c 69 3e 20 44 65 73 74 72 6f 79 20 74  * <li> Destroy t
28d60 68 65 20 6f 62 6a 65 63 74 20 75 73 69 6e 67 20  he object using 
28d70 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
28d80 65 28 29 5d 2e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a  e()]..** </ol>.*
28d90 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74  /.typedef struct
28da0 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 73 71   sqlite3_stmt sq
28db0 6c 69 74 65 33 5f 73 74 6d 74 3b 0a 0a 2f 2a 0a  lite3_stmt;../*.
28dc0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e  ** CAPI3REF: Run
28dd0 2d 74 69 6d 65 20 4c 69 6d 69 74 73 0a 2a 2a 20  -time Limits.** 
28de0 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a  METHOD: sqlite3.
28df0 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 69 6e 74  **.** ^(This int
28e00 65 72 66 61 63 65 20 61 6c 6c 6f 77 73 20 74 68  erface allows th
28e10 65 20 73 69 7a 65 20 6f 66 20 76 61 72 69 6f 75  e size of variou
28e20 73 20 63 6f 6e 73 74 72 75 63 74 73 20 74 6f 20  s constructs to 
28e30 62 65 20 6c 69 6d 69 74 65 64 0a 2a 2a 20 6f 6e  be limited.** on
28e40 20 61 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 79   a connection by
28e50 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 61 73 69   connection basi
28e60 73 2e 20 20 54 68 65 20 66 69 72 73 74 20 70 61  s.  The first pa
28e70 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a  rameter is the.*
28e80 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  * [database conn
28e90 65 63 74 69 6f 6e 5d 20 77 68 6f 73 65 20 6c 69  ection] whose li
28ea0 6d 69 74 20 69 73 20 74 6f 20 62 65 20 73 65 74  mit is to be set
28eb0 20 6f 72 20 71 75 65 72 69 65 64 2e 20 20 54 68   or queried.  Th
28ec0 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 61  e.** second para
28ed0 6d 65 74 65 72 20 69 73 20 6f 6e 65 20 6f 66 20  meter is one of 
28ee0 74 68 65 20 5b 6c 69 6d 69 74 20 63 61 74 65 67  the [limit categ
28ef0 6f 72 69 65 73 5d 20 74 68 61 74 20 64 65 66 69  ories] that defi
28f00 6e 65 20 61 0a 2a 2a 20 63 6c 61 73 73 20 6f 66  ne a.** class of
28f10 20 63 6f 6e 73 74 72 75 63 74 73 20 74 6f 20 62   constructs to b
28f20 65 20 73 69 7a 65 20 6c 69 6d 69 74 65 64 2e 20  e size limited. 
28f30 20 54 68 65 20 74 68 69 72 64 20 70 61 72 61 6d   The third param
28f40 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 6e  eter is the.** n
28f50 65 77 20 6c 69 6d 69 74 20 66 6f 72 20 74 68 61  ew limit for tha
28f60 74 20 63 6f 6e 73 74 72 75 63 74 2e 29 5e 0a 2a  t construct.)^.*
28f70 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6e 65 77  *.** ^If the new
28f80 20 6c 69 6d 69 74 20 69 73 20 61 20 6e 65 67 61   limit is a nega
28f90 74 69 76 65 20 6e 75 6d 62 65 72 2c 20 74 68 65  tive number, the
28fa0 20 6c 69 6d 69 74 20 69 73 20 75 6e 63 68 61 6e   limit is unchan
28fb0 67 65 64 2e 0a 2a 2a 20 5e 28 46 6f 72 20 65 61  ged..** ^(For ea
28fc0 63 68 20 6c 69 6d 69 74 20 63 61 74 65 67 6f 72  ch limit categor
28fd0 79 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 3c  y SQLITE_LIMIT_<
28fe0 69 3e 4e 41 4d 45 3c 2f 69 3e 20 74 68 65 72 65  i>NAME</i> there
28ff0 20 69 73 20 61 20 0a 2a 2a 20 5b 6c 69 6d 69 74   is a .** [limit
29000 73 20 7c 20 68 61 72 64 20 75 70 70 65 72 20 62  s | hard upper b
29010 6f 75 6e 64 5d 0a 2a 2a 20 73 65 74 20 61 74 20  ound].** set at 
29020 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 62 79 20  compile-time by 
29030 61 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72  a C preprocessor
29040 20 6d 61 63 72 6f 20 63 61 6c 6c 65 64 0a 2a 2a   macro called.**
29050 20 5b 6c 69 6d 69 74 73 20 7c 20 53 51 4c 49 54   [limits | SQLIT
29060 45 5f 4d 41 58 5f 3c 69 3e 4e 41 4d 45 3c 2f 69  E_MAX_<i>NAME</i
29070 3e 5d 2e 0a 2a 2a 20 28 54 68 65 20 22 5f 4c 49  >]..** (The "_LI
29080 4d 49 54 5f 22 20 69 6e 20 74 68 65 20 6e 61 6d  MIT_" in the nam
29090 65 20 69 73 20 63 68 61 6e 67 65 64 20 74 6f 20  e is changed to 
290a0 22 5f 4d 41 58 5f 22 2e 29 29 5e 0a 2a 2a 20 5e  "_MAX_".))^.** ^
290b0 41 74 74 65 6d 70 74 73 20 74 6f 20 69 6e 63 72  Attempts to incr
290c0 65 61 73 65 20 61 20 6c 69 6d 69 74 20 61 62 6f  ease a limit abo
290d0 76 65 20 69 74 73 20 68 61 72 64 20 75 70 70 65  ve its hard uppe
290e0 72 20 62 6f 75 6e 64 20 61 72 65 0a 2a 2a 20 73  r bound are.** s
290f0 69 6c 65 6e 74 6c 79 20 74 72 75 6e 63 61 74 65  ilently truncate
29100 64 20 74 6f 20 74 68 65 20 68 61 72 64 20 75 70  d to the hard up
29110 70 65 72 20 62 6f 75 6e 64 2e 0a 2a 2a 0a 2a 2a  per bound..**.**
29120 20 5e 52 65 67 61 72 64 6c 65 73 73 20 6f 66 20   ^Regardless of 
29130 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74  whether or not t
29140 68 65 20 6c 69 6d 69 74 20 77 61 73 20 63 68 61  he limit was cha
29150 6e 67 65 64 2c 20 74 68 65 20 0a 2a 2a 20 5b 73  nged, the .** [s
29160 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 20  qlite3_limit()] 
29170 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
29180 73 20 74 68 65 20 70 72 69 6f 72 20 76 61 6c 75  s the prior valu
29190 65 20 6f 66 20 74 68 65 20 6c 69 6d 69 74 2e 0a  e of the limit..
291a0 2a 2a 20 5e 48 65 6e 63 65 2c 20 74 6f 20 66 69  ** ^Hence, to fi
291b0 6e 64 20 74 68 65 20 63 75 72 72 65 6e 74 20 76  nd the current v
291c0 61 6c 75 65 20 6f 66 20 61 20 6c 69 6d 69 74 20  alue of a limit 
291d0 77 69 74 68 6f 75 74 20 63 68 61 6e 67 69 6e 67  without changing
291e0 20 69 74 2c 0a 2a 2a 20 73 69 6d 70 6c 79 20 69   it,.** simply i
291f0 6e 76 6f 6b 65 20 74 68 69 73 20 69 6e 74 65 72  nvoke this inter
29200 66 61 63 65 20 77 69 74 68 20 74 68 65 20 74 68  face with the th
29210 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 73 65  ird parameter se
29220 74 20 74 6f 20 2d 31 2e 0a 2a 2a 0a 2a 2a 20 52  t to -1..**.** R
29230 75 6e 2d 74 69 6d 65 20 6c 69 6d 69 74 73 20 61  un-time limits a
29240 72 65 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20  re intended for 
29250 75 73 65 20 69 6e 20 61 70 70 6c 69 63 61 74 69  use in applicati
29260 6f 6e 73 20 74 68 61 74 20 6d 61 6e 61 67 65 0a  ons that manage.
29270 2a 2a 20 62 6f 74 68 20 74 68 65 69 72 20 6f 77  ** both their ow
29280 6e 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 62  n internal datab
29290 61 73 65 20 61 6e 64 20 61 6c 73 6f 20 64 61 74  ase and also dat
292a0 61 62 61 73 65 73 20 74 68 61 74 20 61 72 65 20  abases that are 
292b0 63 6f 6e 74 72 6f 6c 6c 65 64 0a 2a 2a 20 62 79  controlled.** by
292c0 20 75 6e 74 72 75 73 74 65 64 20 65 78 74 65 72   untrusted exter
292d0 6e 61 6c 20 73 6f 75 72 63 65 73 2e 20 20 41 6e  nal sources.  An
292e0 20 65 78 61 6d 70 6c 65 20 61 70 70 6c 69 63 61   example applica
292f0 74 69 6f 6e 20 6d 69 67 68 74 20 62 65 20 61 0a  tion might be a.
29300 2a 2a 20 77 65 62 20 62 72 6f 77 73 65 72 20 74  ** web browser t
29310 68 61 74 20 68 61 73 20 69 74 73 20 6f 77 6e 20  hat has its own 
29320 64 61 74 61 62 61 73 65 73 20 66 6f 72 20 73 74  databases for st
29330 6f 72 69 6e 67 20 68 69 73 74 6f 72 79 20 61 6e  oring history an
29340 64 0a 2a 2a 20 73 65 70 61 72 61 74 65 20 64 61  d.** separate da
29350 74 61 62 61 73 65 73 20 63 6f 6e 74 72 6f 6c 6c  tabases controll
29360 65 64 20 62 79 20 4a 61 76 61 53 63 72 69 70 74  ed by JavaScript
29370 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 64 6f   applications do
29380 77 6e 6c 6f 61 64 65 64 0a 2a 2a 20 6f 66 66 20  wnloaded.** off 
29390 74 68 65 20 49 6e 74 65 72 6e 65 74 2e 20 20 54  the Internet.  T
293a0 68 65 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61  he internal data
293b0 62 61 73 65 73 20 63 61 6e 20 62 65 20 67 69 76  bases can be giv
293c0 65 6e 20 74 68 65 0a 2a 2a 20 6c 61 72 67 65 2c  en the.** large,
293d0 20 64 65 66 61 75 6c 74 20 6c 69 6d 69 74 73 2e   default limits.
293e0 20 20 44 61 74 61 62 61 73 65 73 20 6d 61 6e 61    Databases mana
293f0 67 65 64 20 62 79 20 65 78 74 65 72 6e 61 6c 20  ged by external 
29400 73 6f 75 72 63 65 73 20 63 61 6e 0a 2a 2a 20 62  sources can.** b
29410 65 20 67 69 76 65 6e 20 6d 75 63 68 20 73 6d 61  e given much sma
29420 6c 6c 65 72 20 6c 69 6d 69 74 73 20 64 65 73 69  ller limits desi
29430 67 6e 65 64 20 74 6f 20 70 72 65 76 65 6e 74 20  gned to prevent 
29440 61 20 64 65 6e 69 61 6c 20 6f 66 20 73 65 72 76  a denial of serv
29450 69 63 65 0a 2a 2a 20 61 74 74 61 63 6b 2e 20 20  ice.** attack.  
29460 44 65 76 65 6c 6f 70 65 72 73 20 6d 69 67 68 74  Developers might
29470 20 61 6c 73 6f 20 77 61 6e 74 20 74 6f 20 75 73   also want to us
29480 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73  e the [sqlite3_s
29490 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 5d  et_authorizer()]
294a0 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 74 6f  .** interface to
294b0 20 66 75 72 74 68 65 72 20 63 6f 6e 74 72 6f 6c   further control
294c0 20 75 6e 74 72 75 73 74 65 64 20 53 51 4c 2e 20   untrusted SQL. 
294d0 20 54 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65   The size of the
294e0 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 72 65   database.** cre
294f0 61 74 65 64 20 62 79 20 61 6e 20 75 6e 74 72 75  ated by an untru
29500 73 74 65 64 20 73 63 72 69 70 74 20 63 61 6e 20  sted script can 
29510 62 65 20 63 6f 6e 74 61 69 6e 65 64 20 75 73 69  be contained usi
29520 6e 67 20 74 68 65 0a 2a 2a 20 5b 6d 61 78 5f 70  ng the.** [max_p
29530 61 67 65 5f 63 6f 75 6e 74 5d 20 5b 50 52 41 47  age_count] [PRAG
29540 4d 41 5d 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 72  MA]..**.** New r
29550 75 6e 2d 74 69 6d 65 20 6c 69 6d 69 74 20 63 61  un-time limit ca
29560 74 65 67 6f 72 69 65 73 20 6d 61 79 20 62 65 20  tegories may be 
29570 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20  added in future 
29580 72 65 6c 65 61 73 65 73 2e 0a 2a 2f 0a 53 51 4c  releases..*/.SQL
29590 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
295a0 74 65 33 5f 6c 69 6d 69 74 28 73 71 6c 69 74 65  te3_limit(sqlite
295b0 33 2a 2c 20 69 6e 74 20 69 64 2c 20 69 6e 74 20  3*, int id, int 
295c0 6e 65 77 56 61 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20  newVal);../*.** 
295d0 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 54 69  CAPI3REF: Run-Ti
295e0 6d 65 20 4c 69 6d 69 74 20 43 61 74 65 67 6f 72  me Limit Categor
295f0 69 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  ies.** KEYWORDS:
29600 20 7b 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 79   {limit category
29610 7d 20 7b 2a 6c 69 6d 69 74 20 63 61 74 65 67 6f  } {*limit catego
29620 72 69 65 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73  ries}.**.** Thes
29630 65 20 63 6f 6e 73 74 61 6e 74 73 20 64 65 66 69  e constants defi
29640 6e 65 20 76 61 72 69 6f 75 73 20 70 65 72 66 6f  ne various perfo
29650 72 6d 61 6e 63 65 20 6c 69 6d 69 74 73 0a 2a 2a  rmance limits.**
29660 20 74 68 61 74 20 63 61 6e 20 62 65 20 6c 6f 77   that can be low
29670 65 72 65 64 20 61 74 20 72 75 6e 2d 74 69 6d 65  ered at run-time
29680 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
29690 6c 69 6d 69 74 28 29 5d 2e 0a 2a 2a 20 54 68 65  limit()]..** The
296a0 20 73 79 6e 6f 70 73 69 73 20 6f 66 20 74 68 65   synopsis of the
296b0 20 6d 65 61 6e 69 6e 67 73 20 6f 66 20 74 68 65   meanings of the
296c0 20 76 61 72 69 6f 75 73 20 6c 69 6d 69 74 73 20   various limits 
296d0 69 73 20 73 68 6f 77 6e 20 62 65 6c 6f 77 2e 0a  is shown below..
296e0 2a 2a 20 41 64 64 69 74 69 6f 6e 61 6c 20 69 6e  ** Additional in
296f0 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 61 76 61  formation is ava
29700 69 6c 61 62 6c 65 20 61 74 20 5b 6c 69 6d 69 74  ilable at [limit
29710 73 20 7c 20 4c 69 6d 69 74 73 20 69 6e 20 53 51  s | Limits in SQ
29720 4c 69 74 65 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c  Lite]..**.** <dl
29730 3e 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49  >.** [[SQLITE_LI
29740 4d 49 54 5f 4c 45 4e 47 54 48 5d 5d 20 5e 28 3c  MIT_LENGTH]] ^(<
29750 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
29760 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c  LENGTH</dt>.** <
29770 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 73  dd>The maximum s
29780 69 7a 65 20 6f 66 20 61 6e 79 20 73 74 72 69 6e  ize of any strin
29790 67 20 6f 72 20 42 4c 4f 42 20 6f 72 20 74 61 62  g or BLOB or tab
297a0 6c 65 20 72 6f 77 2c 20 69 6e 20 62 79 74 65 73  le row, in bytes
297b0 2e 3c 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b  .<dd>)^.**.** [[
297c0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c  SQLITE_LIMIT_SQL
297d0 5f 4c 45 4e 47 54 48 5d 5d 20 5e 28 3c 64 74 3e  _LENGTH]] ^(<dt>
297e0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c  SQLITE_LIMIT_SQL
297f0 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20  _LENGTH</dt>.** 
29800 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
29810 6c 65 6e 67 74 68 20 6f 66 20 61 6e 20 53 51 4c  length of an SQL
29820 20 73 74 61 74 65 6d 65 6e 74 2c 20 69 6e 20 62   statement, in b
29830 79 74 65 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a  ytes.</dd>)^.**.
29840 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49  ** [[SQLITE_LIMI
29850 54 5f 43 4f 4c 55 4d 4e 5d 5d 20 5e 28 3c 64 74  T_COLUMN]] ^(<dt
29860 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f  >SQLITE_LIMIT_CO
29870 4c 55 4d 4e 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  LUMN</dt>.** <dd
29880 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d  >The maximum num
29890 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69  ber of columns i
298a0 6e 20 61 20 74 61 62 6c 65 20 64 65 66 69 6e 69  n a table defini
298b0 74 69 6f 6e 20 6f 72 20 69 6e 20 74 68 65 0a 2a  tion or in the.*
298c0 2a 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20  * result set of 
298d0 61 20 5b 53 45 4c 45 43 54 5d 20 6f 72 20 74 68  a [SELECT] or th
298e0 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72  e maximum number
298f0 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61   of columns in a
29900 6e 20 69 6e 64 65 78 0a 2a 2a 20 6f 72 20 69 6e  n index.** or in
29910 20 61 6e 20 4f 52 44 45 52 20 42 59 20 6f 72 20   an ORDER BY or 
29920 47 52 4f 55 50 20 42 59 20 63 6c 61 75 73 65 2e  GROUP BY clause.
29930 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b  </dd>)^.**.** [[
29940 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50  SQLITE_LIMIT_EXP
29950 52 5f 44 45 50 54 48 5d 5d 20 5e 28 3c 64 74 3e  R_DEPTH]] ^(<dt>
29960 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50  SQLITE_LIMIT_EXP
29970 52 5f 44 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a 20  R_DEPTH</dt>.** 
29980 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
29990 64 65 70 74 68 20 6f 66 20 74 68 65 20 70 61 72  depth of the par
299a0 73 65 20 74 72 65 65 20 6f 6e 20 61 6e 79 20 65  se tree on any e
299b0 78 70 72 65 73 73 69 6f 6e 2e 3c 2f 64 64 3e 29  xpression.</dd>)
299c0 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  ^.**.** [[SQLITE
299d0 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f  _LIMIT_COMPOUND_
299e0 53 45 4c 45 43 54 5d 5d 20 5e 28 3c 64 74 3e 53  SELECT]] ^(<dt>S
299f0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50  QLITE_LIMIT_COMP
29a00 4f 55 4e 44 5f 53 45 4c 45 43 54 3c 2f 64 74 3e  OUND_SELECT</dt>
29a10 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
29a20 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 74 65  mum number of te
29a30 72 6d 73 20 69 6e 20 61 20 63 6f 6d 70 6f 75 6e  rms in a compoun
29a40 64 20 53 45 4c 45 43 54 20 73 74 61 74 65 6d 65  d SELECT stateme
29a50 6e 74 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a  nt.</dd>)^.**.**
29a60 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f   [[SQLITE_LIMIT_
29a70 56 44 42 45 5f 4f 50 5d 5d 20 5e 28 3c 64 74 3e  VDBE_OP]] ^(<dt>
29a80 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42  SQLITE_LIMIT_VDB
29a90 45 5f 4f 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  E_OP</dt>.** <dd
29aa0 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d  >The maximum num
29ab0 62 65 72 20 6f 66 20 69 6e 73 74 72 75 63 74 69  ber of instructi
29ac0 6f 6e 73 20 69 6e 20 61 20 76 69 72 74 75 61 6c  ons in a virtual
29ad0 20 6d 61 63 68 69 6e 65 20 70 72 6f 67 72 61 6d   machine program
29ae0 0a 2a 2a 20 75 73 65 64 20 74 6f 20 69 6d 70 6c  .** used to impl
29af0 65 6d 65 6e 74 20 61 6e 20 53 51 4c 20 73 74 61  ement an SQL sta
29b00 74 65 6d 65 6e 74 2e 20 20 49 66 20 5b 73 71 6c  tement.  If [sql
29b10 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
29b20 29 5d 20 6f 72 0a 2a 2a 20 74 68 65 20 65 71 75  )] or.** the equ
29b30 69 76 61 6c 65 6e 74 20 74 72 69 65 73 20 74 6f  ivalent tries to
29b40 20 61 6c 6c 6f 63 61 74 65 20 73 70 61 63 65 20   allocate space 
29b50 66 6f 72 20 6d 6f 72 65 20 74 68 61 6e 20 74 68  for more than th
29b60 69 73 20 6d 61 6e 79 20 6f 70 63 6f 64 65 73 0a  is many opcodes.
29b70 2a 2a 20 69 6e 20 61 20 73 69 6e 67 6c 65 20 70  ** in a single p
29b80 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
29b90 74 2c 20 61 6e 20 53 51 4c 49 54 45 5f 4e 4f 4d  t, an SQLITE_NOM
29ba0 45 4d 20 65 72 72 6f 72 20 69 73 20 72 65 74 75  EM error is retu
29bb0 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a  rned.</dd>)^.**.
29bc0 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49  ** [[SQLITE_LIMI
29bd0 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 5d 5d  T_FUNCTION_ARG]]
29be0 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49   ^(<dt>SQLITE_LI
29bf0 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47  MIT_FUNCTION_ARG
29c00 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
29c10 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20   maximum number 
29c20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 6f 6e 20  of arguments on 
29c30 61 20 66 75 6e 63 74 69 6f 6e 2e 3c 2f 64 64 3e  a function.</dd>
29c40 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  )^.**.** [[SQLIT
29c50 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48 45 44  E_LIMIT_ATTACHED
29c60 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f  ]] ^(<dt>SQLITE_
29c70 4c 49 4d 49 54 5f 41 54 54 41 43 48 45 44 3c 2f  LIMIT_ATTACHED</
29c80 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
29c90 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66  aximum number of
29ca0 20 5b 41 54 54 41 43 48 20 7c 20 61 74 74 61 63   [ATTACH | attac
29cb0 68 65 64 20 64 61 74 61 62 61 73 65 73 5d 2e 29  hed databases].)
29cc0 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  ^</dd>.**.** [[S
29cd0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45  QLITE_LIMIT_LIKE
29ce0 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48 5d  _PATTERN_LENGTH]
29cf0 5d 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54  ].** ^(<dt>SQLIT
29d00 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54  E_LIMIT_LIKE_PAT
29d10 54 45 52 4e 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e  TERN_LENGTH</dt>
29d20 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
29d30 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 74 68  mum length of th
29d40 65 20 70 61 74 74 65 72 6e 20 61 72 67 75 6d 65  e pattern argume
29d50 6e 74 20 74 6f 20 74 68 65 20 5b 4c 49 4b 45 5d  nt to the [LIKE]
29d60 20 6f 72 0a 2a 2a 20 5b 47 4c 4f 42 5d 20 6f 70   or.** [GLOB] op
29d70 65 72 61 74 6f 72 73 2e 3c 2f 64 64 3e 29 5e 0a  erators.</dd>)^.
29d80 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c  **.** [[SQLITE_L
29d90 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55  IMIT_VARIABLE_NU
29da0 4d 42 45 52 5d 5d 0a 2a 2a 20 5e 28 3c 64 74 3e  MBER]].** ^(<dt>
29db0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52  SQLITE_LIMIT_VAR
29dc0 49 41 42 4c 45 5f 4e 55 4d 42 45 52 3c 2f 64 74  IABLE_NUMBER</dt
29dd0 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78  >.** <dd>The max
29de0 69 6d 75 6d 20 69 6e 64 65 78 20 6e 75 6d 62 65  imum index numbe
29df0 72 20 6f 66 20 61 6e 79 20 5b 70 61 72 61 6d 65  r of any [parame
29e00 74 65 72 5d 20 69 6e 20 61 6e 20 53 51 4c 20 73  ter] in an SQL s
29e10 74 61 74 65 6d 65 6e 74 2e 29 5e 0a 2a 2a 0a 2a  tatement.)^.**.*
29e20 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54  * [[SQLITE_LIMIT
29e30 5f 54 52 49 47 47 45 52 5f 44 45 50 54 48 5d 5d  _TRIGGER_DEPTH]]
29e40 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49   ^(<dt>SQLITE_LI
29e50 4d 49 54 5f 54 52 49 47 47 45 52 5f 44 45 50 54  MIT_TRIGGER_DEPT
29e60 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  H</dt>.** <dd>Th
29e70 65 20 6d 61 78 69 6d 75 6d 20 64 65 70 74 68 20  e maximum depth 
29e80 6f 66 20 72 65 63 75 72 73 69 6f 6e 20 66 6f 72  of recursion for
29e90 20 74 72 69 67 67 65 72 73 2e 3c 2f 64 64 3e 29   triggers.</dd>)
29ea0 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  ^.**.** [[SQLITE
29eb0 5f 4c 49 4d 49 54 5f 57 4f 52 4b 45 52 5f 54 48  _LIMIT_WORKER_TH
29ec0 52 45 41 44 53 5d 5d 20 5e 28 3c 64 74 3e 53 51  READS]] ^(<dt>SQ
29ed0 4c 49 54 45 5f 4c 49 4d 49 54 5f 57 4f 52 4b 45  LITE_LIMIT_WORKE
29ee0 52 5f 54 48 52 45 41 44 53 3c 2f 64 74 3e 0a 2a  R_THREADS</dt>.*
29ef0 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
29f00 6d 20 6e 75 6d 62 65 72 20 6f 66 20 61 75 78 69  m number of auxi
29f10 6c 69 61 72 79 20 77 6f 72 6b 65 72 20 74 68 72  liary worker thr
29f20 65 61 64 73 20 74 68 61 74 20 61 20 73 69 6e 67  eads that a sing
29f30 6c 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20  le.** [prepared 
29f40 73 74 61 74 65 6d 65 6e 74 5d 20 6d 61 79 20 73  statement] may s
29f50 74 61 72 74 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 20  tart.</dd>)^.** 
29f60 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65  </dl>.*/.#define
29f70 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45   SQLITE_LIMIT_LE
29f80 4e 47 54 48 20 20 20 20 20 20 20 20 20 20 20 20  NGTH            
29f90 20 20 20 20 20 20 20 20 30 0a 23 64 65 66 69 6e          0.#defin
29fa0 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53  e SQLITE_LIMIT_S
29fb0 51 4c 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20  QL_LENGTH       
29fc0 20 20 20 20 20 20 20 20 20 31 0a 23 64 65 66 69           1.#defi
29fd0 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
29fe0 43 4f 4c 55 4d 4e 20 20 20 20 20 20 20 20 20 20  COLUMN          
29ff0 20 20 20 20 20 20 20 20 20 20 32 0a 23 64 65 66            2.#def
2a000 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
2a010 5f 45 58 50 52 5f 44 45 50 54 48 20 20 20 20 20  _EXPR_DEPTH     
2a020 20 20 20 20 20 20 20 20 20 20 20 33 0a 23 64 65             3.#de
2a030 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
2a040 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43  T_COMPOUND_SELEC
2a050 54 20 20 20 20 20 20 20 20 20 20 20 34 0a 23 64  T           4.#d
2a060 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
2a070 49 54 5f 56 44 42 45 5f 4f 50 20 20 20 20 20 20  IT_VDBE_OP      
2a080 20 20 20 20 20 20 20 20 20 20 20 20 20 35 0a 23               5.#
2a090 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
2a0a0 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47  MIT_FUNCTION_ARG
2a0b0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 36 0a                6.
2a0c0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
2a0d0 49 4d 49 54 5f 41 54 54 41 43 48 45 44 20 20 20  IMIT_ATTACHED   
2a0e0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 37                 7
2a0f0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
2a100 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45  LIMIT_LIKE_PATTE
2a110 52 4e 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20  RN_LENGTH       
2a120 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  8.#define SQLITE
2a130 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f  _LIMIT_VARIABLE_
2a140 4e 55 4d 42 45 52 20 20 20 20 20 20 20 20 20 20  NUMBER          
2a150 20 39 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   9.#define SQLIT
2a160 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45 52 5f  E_LIMIT_TRIGGER_
2a170 44 45 50 54 48 20 20 20 20 20 20 20 20 20 20 20  DEPTH           
2a180 20 31 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   10.#define SQLI
2a190 54 45 5f 4c 49 4d 49 54 5f 57 4f 52 4b 45 52 5f  TE_LIMIT_WORKER_
2a1a0 54 48 52 45 41 44 53 20 20 20 20 20 20 20 20 20  THREADS         
2a1b0 20 20 31 31 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50    11.../*.** CAP
2a1c0 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c 69 6e 67  I3REF: Compiling
2a1d0 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e   An SQL Statemen
2a1e0 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  t.** KEYWORDS: {
2a1f0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 63 6f  SQL statement co
2a200 6d 70 69 6c 65 72 7d 0a 2a 2a 20 4d 45 54 48 4f  mpiler}.** METHO
2a210 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 20 43 4f  D: sqlite3.** CO
2a220 4e 53 54 52 55 43 54 4f 52 3a 20 73 71 6c 69 74  NSTRUCTOR: sqlit
2a230 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 54 6f  e3_stmt.**.** To
2a240 20 65 78 65 63 75 74 65 20 61 6e 20 53 51 4c 20   execute an SQL 
2a250 71 75 65 72 79 2c 20 69 74 20 6d 75 73 74 20 66  query, it must f
2a260 69 72 73 74 20 62 65 20 63 6f 6d 70 69 6c 65 64  irst be compiled
2a270 20 69 6e 74 6f 20 61 20 62 79 74 65 2d 63 6f 64   into a byte-cod
2a280 65 0a 2a 2a 20 70 72 6f 67 72 61 6d 20 75 73 69  e.** program usi
2a290 6e 67 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20  ng one of these 
2a2a0 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20  routines..**.** 
2a2b0 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
2a2c0 6e 74 2c 20 22 64 62 22 2c 20 69 73 20 61 20 5b  nt, "db", is a [
2a2d0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
2a2e0 69 6f 6e 5d 20 6f 62 74 61 69 6e 65 64 20 66 72  ion] obtained fr
2a2f0 6f 6d 20 61 0a 2a 2a 20 70 72 69 6f 72 20 73 75  om a.** prior su
2a300 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f  ccessful call to
2a310 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29   [sqlite3_open()
2a320 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ], [sqlite3_open
2a330 5f 76 32 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71  _v2()] or.** [sq
2a340 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2e  lite3_open16()].
2a350 20 20 54 68 65 20 64 61 74 61 62 61 73 65 20 63    The database c
2a360 6f 6e 6e 65 63 74 69 6f 6e 20 6d 75 73 74 20 6e  onnection must n
2a370 6f 74 20 68 61 76 65 20 62 65 65 6e 20 63 6c 6f  ot have been clo
2a380 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  sed..**.** The s
2a390 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2c 20  econd argument, 
2a3a0 22 7a 53 71 6c 22 2c 20 69 73 20 74 68 65 20 73  "zSql", is the s
2a3b0 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 20 63  tatement to be c
2a3c0 6f 6d 70 69 6c 65 64 2c 20 65 6e 63 6f 64 65 64  ompiled, encoded
2a3d0 0a 2a 2a 20 61 73 20 65 69 74 68 65 72 20 55 54  .** as either UT
2a3e0 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 2e 20 20  F-8 or UTF-16.  
2a3f0 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70  The sqlite3_prep
2a400 61 72 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65  are() and sqlite
2a410 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 0a 2a  3_prepare_v2().*
2a420 2a 20 69 6e 74 65 72 66 61 63 65 73 20 75 73 65  * interfaces use
2a430 20 55 54 46 2d 38 2c 20 61 6e 64 20 73 71 6c 69   UTF-8, and sqli
2a440 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 20  te3_prepare16() 
2a450 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70  and sqlite3_prep
2a460 61 72 65 31 36 5f 76 32 28 29 0a 2a 2a 20 75 73  are16_v2().** us
2a470 65 20 55 54 46 2d 31 36 2e 0a 2a 2a 0a 2a 2a 20  e UTF-16..**.** 
2a480 5e 49 66 20 74 68 65 20 6e 42 79 74 65 20 61 72  ^If the nByte ar
2a490 67 75 6d 65 6e 74 20 69 73 20 6e 65 67 61 74 69  gument is negati
2a4a0 76 65 2c 20 74 68 65 6e 20 7a 53 71 6c 20 69 73  ve, then zSql is
2a4b0 20 72 65 61 64 20 75 70 20 74 6f 20 74 68 65 0a   read up to the.
2a4c0 2a 2a 20 66 69 72 73 74 20 7a 65 72 6f 20 74 65  ** first zero te
2a4d0 72 6d 69 6e 61 74 6f 72 2e 20 5e 49 66 20 6e 42  rminator. ^If nB
2a4e0 79 74 65 20 69 73 20 70 6f 73 69 74 69 76 65 2c  yte is positive,
2a4f0 20 74 68 65 6e 20 69 74 20 69 73 20 74 68 65 0a   then it is the.
2a500 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  ** number of byt
2a510 65 73 20 72 65 61 64 20 66 72 6f 6d 20 7a 53 71  es read from zSq
2a520 6c 2e 20 20 5e 49 66 20 6e 42 79 74 65 20 69 73  l.  ^If nByte is
2a530 20 7a 65 72 6f 2c 20 74 68 65 6e 20 6e 6f 20 70   zero, then no p
2a540 72 65 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 65  repared.** state
2a550 6d 65 6e 74 20 69 73 20 67 65 6e 65 72 61 74 65  ment is generate
2a560 64 2e 0a 2a 2a 20 49 66 20 74 68 65 20 63 61 6c  d..** If the cal
2a570 6c 65 72 20 6b 6e 6f 77 73 20 74 68 61 74 20 74  ler knows that t
2a580 68 65 20 73 75 70 70 6c 69 65 64 20 73 74 72 69  he supplied stri
2a590 6e 67 20 69 73 20 6e 75 6c 2d 74 65 72 6d 69 6e  ng is nul-termin
2a5a0 61 74 65 64 2c 20 74 68 65 6e 0a 2a 2a 20 74 68  ated, then.** th
2a5b0 65 72 65 20 69 73 20 61 20 73 6d 61 6c 6c 20 70  ere is a small p
2a5c0 65 72 66 6f 72 6d 61 6e 63 65 20 61 64 76 61 6e  erformance advan
2a5d0 74 61 67 65 20 74 6f 20 70 61 73 73 69 6e 67 20  tage to passing 
2a5e0 61 6e 20 6e 42 79 74 65 20 70 61 72 61 6d 65 74  an nByte paramet
2a5f0 65 72 20 74 68 61 74 0a 2a 2a 20 69 73 20 74 68  er that.** is th
2a600 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  e number of byte
2a610 73 20 69 6e 20 74 68 65 20 69 6e 70 75 74 20 73  s in the input s
2a620 74 72 69 6e 67 20 3c 69 3e 69 6e 63 6c 75 64 69  tring <i>includi
2a630 6e 67 3c 2f 69 3e 0a 2a 2a 20 74 68 65 20 6e 75  ng</i>.** the nu
2a640 6c 2d 74 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a  l-terminator..**
2a650 0a 2a 2a 20 5e 49 66 20 70 7a 54 61 69 6c 20 69  .** ^If pzTail i
2a660 73 20 6e 6f 74 20 4e 55 4c 4c 20 74 68 65 6e 20  s not NULL then 
2a670 2a 70 7a 54 61 69 6c 20 69 73 20 6d 61 64 65 20  *pzTail is made 
2a680 74 6f 20 70 6f 69 6e 74 20 74 6f 20 74 68 65 20  to point to the 
2a690 66 69 72 73 74 20 62 79 74 65 0a 2a 2a 20 70 61  first byte.** pa
2a6a0 73 74 20 74 68 65 20 65 6e 64 20 6f 66 20 74 68  st the end of th
2a6b0 65 20 66 69 72 73 74 20 53 51 4c 20 73 74 61 74  e first SQL stat
2a6c0 65 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2e 20 20  ement in zSql.  
2a6d0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f  These routines o
2a6e0 6e 6c 79 0a 2a 2a 20 63 6f 6d 70 69 6c 65 20 74  nly.** compile t
2a6f0 68 65 20 66 69 72 73 74 20 73 74 61 74 65 6d 65  he first stateme
2a700 6e 74 20 69 6e 20 7a 53 71 6c 2c 20 73 6f 20 2a  nt in zSql, so *
2a710 70 7a 54 61 69 6c 20 69 73 20 6c 65 66 74 20 70  pzTail is left p
2a720 6f 69 6e 74 69 6e 67 20 74 6f 0a 2a 2a 20 77 68  ointing to.** wh
2a730 61 74 20 72 65 6d 61 69 6e 73 20 75 6e 63 6f 6d  at remains uncom
2a740 70 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 2a 70  piled..**.** ^*p
2a750 70 53 74 6d 74 20 69 73 20 6c 65 66 74 20 70 6f  pStmt is left po
2a760 69 6e 74 69 6e 67 20 74 6f 20 61 20 63 6f 6d 70  inting to a comp
2a770 69 6c 65 64 20 5b 70 72 65 70 61 72 65 64 20 73  iled [prepared s
2a780 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 63  tatement] that c
2a790 61 6e 20 62 65 0a 2a 2a 20 65 78 65 63 75 74 65  an be.** execute
2a7a0 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  d using [sqlite3
2a7b0 5f 73 74 65 70 28 29 5d 2e 20 20 5e 49 66 20 74  _step()].  ^If t
2a7c0 68 65 72 65 20 69 73 20 61 6e 20 65 72 72 6f 72  here is an error
2a7d0 2c 20 2a 70 70 53 74 6d 74 20 69 73 20 73 65 74  , *ppStmt is set
2a7e0 0a 2a 2a 20 74 6f 20 4e 55 4c 4c 2e 20 20 5e 49  .** to NULL.  ^I
2a7f0 66 20 74 68 65 20 69 6e 70 75 74 20 74 65 78 74  f the input text
2a800 20 63 6f 6e 74 61 69 6e 73 20 6e 6f 20 53 51 4c   contains no SQL
2a810 20 28 69 66 20 74 68 65 20 69 6e 70 75 74 20 69   (if the input i
2a820 73 20 61 6e 20 65 6d 70 74 79 0a 2a 2a 20 73 74  s an empty.** st
2a830 72 69 6e 67 20 6f 72 20 61 20 63 6f 6d 6d 65 6e  ring or a commen
2a840 74 29 20 74 68 65 6e 20 2a 70 70 53 74 6d 74 20  t) then *ppStmt 
2a850 69 73 20 73 65 74 20 74 6f 20 4e 55 4c 4c 2e 0a  is set to NULL..
2a860 2a 2a 20 54 68 65 20 63 61 6c 6c 69 6e 67 20 70  ** The calling p
2a870 72 6f 63 65 64 75 72 65 20 69 73 20 72 65 73 70  rocedure is resp
2a880 6f 6e 73 69 62 6c 65 20 66 6f 72 20 64 65 6c 65  onsible for dele
2a890 74 69 6e 67 20 74 68 65 20 63 6f 6d 70 69 6c 65  ting the compile
2a8a0 64 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65  d.** SQL stateme
2a8b0 6e 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  nt using [sqlite
2a8c0 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 61 66  3_finalize()] af
2a8d0 74 65 72 20 69 74 20 68 61 73 20 66 69 6e 69 73  ter it has finis
2a8e0 68 65 64 20 77 69 74 68 20 69 74 2e 0a 2a 2a 20  hed with it..** 
2a8f0 70 70 53 74 6d 74 20 6d 61 79 20 6e 6f 74 20 62  ppStmt may not b
2a900 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 4f  e NULL..**.** ^O
2a910 6e 20 73 75 63 63 65 73 73 2c 20 74 68 65 20 73  n success, the s
2a920 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29  qlite3_prepare()
2a930 20 66 61 6d 69 6c 79 20 6f 66 20 72 6f 75 74 69   family of routi
2a940 6e 65 73 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  nes return [SQLI
2a950 54 45 5f 4f 4b 5d 3b 0a 2a 2a 20 6f 74 68 65 72  TE_OK];.** other
2a960 77 69 73 65 20 61 6e 20 5b 65 72 72 6f 72 20 63  wise an [error c
2a970 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64  ode] is returned
2a980 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
2a990 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
2a9a0 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65   and sqlite3_pre
2a9b0 70 61 72 65 31 36 5f 76 32 28 29 20 69 6e 74 65  pare16_v2() inte
2a9c0 72 66 61 63 65 73 20 61 72 65 0a 2a 2a 20 72 65  rfaces are.** re
2a9d0 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 61 6c  commended for al
2a9e0 6c 20 6e 65 77 20 70 72 6f 67 72 61 6d 73 2e 20  l new programs. 
2a9f0 54 68 65 20 74 77 6f 20 6f 6c 64 65 72 20 69 6e  The two older in
2aa00 74 65 72 66 61 63 65 73 20 61 72 65 20 72 65 74  terfaces are ret
2aa10 61 69 6e 65 64 0a 2a 2a 20 66 6f 72 20 62 61 63  ained.** for bac
2aa20 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69  kwards compatibi
2aa30 6c 69 74 79 2c 20 62 75 74 20 74 68 65 69 72 20  lity, but their 
2aa40 75 73 65 20 69 73 20 64 69 73 63 6f 75 72 61 67  use is discourag
2aa50 65 64 2e 0a 2a 2a 20 5e 49 6e 20 74 68 65 20 22  ed..** ^In the "
2aa60 76 32 22 20 69 6e 74 65 72 66 61 63 65 73 2c 20  v2" interfaces, 
2aa70 74 68 65 20 70 72 65 70 61 72 65 64 20 73 74 61  the prepared sta
2aa80 74 65 6d 65 6e 74 0a 2a 2a 20 74 68 61 74 20 69  tement.** that i
2aa90 73 20 72 65 74 75 72 6e 65 64 20 28 74 68 65 20  s returned (the 
2aaa0 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f  [sqlite3_stmt] o
2aab0 62 6a 65 63 74 29 20 63 6f 6e 74 61 69 6e 73 20  bject) contains 
2aac0 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a  a copy of the.**
2aad0 20 6f 72 69 67 69 6e 61 6c 20 53 51 4c 20 74 65   original SQL te
2aae0 78 74 2e 20 54 68 69 73 20 63 61 75 73 65 73 20  xt. This causes 
2aaf0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  the [sqlite3_ste
2ab00 70 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 74  p()] interface t
2ab10 6f 0a 2a 2a 20 62 65 68 61 76 65 20 64 69 66 66  o.** behave diff
2ab20 65 72 65 6e 74 6c 79 20 69 6e 20 74 68 72 65 65  erently in three
2ab30 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c   ways:.**.** <ol
2ab40 3e 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 49 66  >.** <li>.** ^If
2ab50 20 74 68 65 20 64 61 74 61 62 61 73 65 20 73 63   the database sc
2ab60 68 65 6d 61 20 63 68 61 6e 67 65 73 2c 20 69 6e  hema changes, in
2ab70 73 74 65 61 64 20 6f 66 20 72 65 74 75 72 6e 69  stead of returni
2ab80 6e 67 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d  ng [SQLITE_SCHEM
2ab90 41 5d 20 61 73 20 69 74 0a 2a 2a 20 61 6c 77 61  A] as it.** alwa
2aba0 79 73 20 75 73 65 64 20 74 6f 20 64 6f 2c 20 5b  ys used to do, [
2abb0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
2abc0 77 69 6c 6c 20 61 75 74 6f 6d 61 74 69 63 61 6c  will automatical
2abd0 6c 79 20 72 65 63 6f 6d 70 69 6c 65 20 74 68 65  ly recompile the
2abe0 20 53 51 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 6e   SQL.** statemen
2abf0 74 20 61 6e 64 20 74 72 79 20 74 6f 20 72 75 6e  t and try to run
2ac00 20 69 74 20 61 67 61 69 6e 2e 20 41 73 20 6d 61   it again. As ma
2ac10 6e 79 20 61 73 20 5b 53 51 4c 49 54 45 5f 4d 41  ny as [SQLITE_MA
2ac20 58 5f 53 43 48 45 4d 41 5f 52 45 54 52 59 5d 0a  X_SCHEMA_RETRY].
2ac30 2a 2a 20 72 65 74 72 69 65 73 20 77 69 6c 6c 20  ** retries will 
2ac40 6f 63 63 75 72 20 62 65 66 6f 72 65 20 73 71 6c  occur before sql
2ac50 69 74 65 33 5f 73 74 65 70 28 29 20 67 69 76 65  ite3_step() give
2ac60 73 20 75 70 20 61 6e 64 20 72 65 74 75 72 6e 73  s up and returns
2ac70 20 61 6e 20 65 72 72 6f 72 2e 0a 2a 2a 20 3c 2f   an error..** </
2ac80 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a  li>.**.** <li>.*
2ac90 2a 20 5e 57 68 65 6e 20 61 6e 20 65 72 72 6f 72  * ^When an error
2aca0 20 6f 63 63 75 72 73 2c 20 5b 73 71 6c 69 74 65   occurs, [sqlite
2acb0 33 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c 20 72  3_step()] will r
2acc0 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20 74 68 65  eturn one of the
2acd0 20 64 65 74 61 69 6c 65 64 0a 2a 2a 20 5b 65 72   detailed.** [er
2ace0 72 6f 72 20 63 6f 64 65 73 5d 20 6f 72 20 5b 65  ror codes] or [e
2acf0 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f  xtended error co
2ad00 64 65 73 5d 2e 20 20 5e 54 68 65 20 6c 65 67 61  des].  ^The lega
2ad10 63 79 20 62 65 68 61 76 69 6f 72 20 77 61 73 20  cy behavior was 
2ad20 74 68 61 74 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  that.** [sqlite3
2ad30 5f 73 74 65 70 28 29 5d 20 77 6f 75 6c 64 20 6f  _step()] would o
2ad40 6e 6c 79 20 72 65 74 75 72 6e 20 61 20 67 65 6e  nly return a gen
2ad50 65 72 69 63 20 5b 53 51 4c 49 54 45 5f 45 52 52  eric [SQLITE_ERR
2ad60 4f 52 5d 20 72 65 73 75 6c 74 20 63 6f 64 65 0a  OR] result code.
2ad70 2a 2a 20 61 6e 64 20 74 68 65 20 61 70 70 6c 69  ** and the appli
2ad80 63 61 74 69 6f 6e 20 77 6f 75 6c 64 20 68 61 76  cation would hav
2ad90 65 20 74 6f 20 6d 61 6b 65 20 61 20 73 65 63 6f  e to make a seco
2ada0 6e 64 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  nd call to [sqli
2adb0 74 65 33 5f 72 65 73 65 74 28 29 5d 0a 2a 2a 20  te3_reset()].** 
2adc0 69 6e 20 6f 72 64 65 72 20 74 6f 20 66 69 6e 64  in order to find
2add0 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20   the underlying 
2ade0 63 61 75 73 65 20 6f 66 20 74 68 65 20 70 72 6f  cause of the pro
2adf0 62 6c 65 6d 2e 20 57 69 74 68 20 74 68 65 20 22  blem. With the "
2ae00 76 32 22 20 70 72 65 70 61 72 65 0a 2a 2a 20 69  v2" prepare.** i
2ae10 6e 74 65 72 66 61 63 65 73 2c 20 74 68 65 20 75  nterfaces, the u
2ae20 6e 64 65 72 6c 79 69 6e 67 20 72 65 61 73 6f 6e  nderlying reason
2ae30 20 66 6f 72 20 74 68 65 20 65 72 72 6f 72 20 69   for the error i
2ae40 73 20 72 65 74 75 72 6e 65 64 20 69 6d 6d 65 64  s returned immed
2ae50 69 61 74 65 6c 79 2e 0a 2a 2a 20 3c 2f 6c 69 3e  iately..** </li>
2ae60 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e  .**.** <li>.** ^
2ae70 49 66 20 74 68 65 20 73 70 65 63 69 66 69 63 20  If the specific 
2ae80 76 61 6c 75 65 20 62 6f 75 6e 64 20 74 6f 20 5b  value bound to [
2ae90 70 61 72 61 6d 65 74 65 72 20 7c 20 68 6f 73 74  parameter | host
2aea0 20 70 61 72 61 6d 65 74 65 72 5d 20 69 6e 20 74   parameter] in t
2aeb0 68 65 20 0a 2a 2a 20 57 48 45 52 45 20 63 6c 61  he .** WHERE cla
2aec0 75 73 65 20 6d 69 67 68 74 20 69 6e 66 6c 75 65  use might influe
2aed0 6e 63 65 20 74 68 65 20 63 68 6f 69 63 65 20 6f  nce the choice o
2aee0 66 20 71 75 65 72 79 20 70 6c 61 6e 20 66 6f 72  f query plan for
2aef0 20 61 20 73 74 61 74 65 6d 65 6e 74 2c 0a 2a 2a   a statement,.**
2af00 20 74 68 65 6e 20 74 68 65 20 73 74 61 74 65 6d   then the statem
2af10 65 6e 74 20 77 69 6c 6c 20 62 65 20 61 75 74 6f  ent will be auto
2af20 6d 61 74 69 63 61 6c 6c 79 20 72 65 63 6f 6d 70  matically recomp
2af30 69 6c 65 64 2c 20 61 73 20 69 66 20 74 68 65 72  iled, as if ther
2af40 65 20 68 61 64 20 62 65 65 6e 20 0a 2a 2a 20 61  e had been .** a
2af50 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65 2c 20   schema change, 
2af60 6f 6e 20 74 68 65 20 66 69 72 73 74 20 20 5b 73  on the first  [s
2af70 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 63  qlite3_step()] c
2af80 61 6c 6c 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e  all following an
2af90 79 20 63 68 61 6e 67 65 0a 2a 2a 20 74 6f 20 74  y change.** to t
2afa0 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  he [sqlite3_bind
2afb0 5f 74 65 78 74 20 7c 20 62 69 6e 64 69 6e 67 73  _text | bindings
2afc0 5d 20 6f 66 20 74 68 61 74 20 5b 70 61 72 61 6d  ] of that [param
2afd0 65 74 65 72 5d 2e 20 0a 2a 2a 20 5e 54 68 65 20  eter]. .** ^The 
2afe0 73 70 65 63 69 66 69 63 20 76 61 6c 75 65 20 6f  specific value o
2aff0 66 20 57 48 45 52 45 2d 63 6c 61 75 73 65 20 5b  f WHERE-clause [
2b000 70 61 72 61 6d 65 74 65 72 5d 20 6d 69 67 68 74  parameter] might
2b010 20 69 6e 66 6c 75 65 6e 63 65 20 74 68 65 20 0a   influence the .
2b020 2a 2a 20 63 68 6f 69 63 65 20 6f 66 20 71 75 65  ** choice of que
2b030 72 79 20 70 6c 61 6e 20 69 66 20 74 68 65 20 70  ry plan if the p
2b040 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20  arameter is the 
2b050 6c 65 66 74 2d 68 61 6e 64 20 73 69 64 65 20 6f  left-hand side o
2b060 66 20 61 20 5b 4c 49 4b 45 5d 0a 2a 2a 20 6f 72  f a [LIKE].** or
2b070 20 5b 47 4c 4f 42 5d 20 6f 70 65 72 61 74 6f 72   [GLOB] operator
2b080 20 6f 72 20 69 66 20 74 68 65 20 70 61 72 61 6d   or if the param
2b090 65 74 65 72 20 69 73 20 63 6f 6d 70 61 72 65 64  eter is compared
2b0a0 20 74 6f 20 61 6e 20 69 6e 64 65 78 65 64 20 63   to an indexed c
2b0b0 6f 6c 75 6d 6e 0a 2a 2a 20 61 6e 64 20 74 68 65  olumn.** and the
2b0c0 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f   [SQLITE_ENABLE_
2b0d0 53 54 41 54 33 5d 20 63 6f 6d 70 69 6c 65 2d 74  STAT3] compile-t
2b0e0 69 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20 65 6e  ime option is en
2b0f0 61 62 6c 65 64 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a  abled..** </li>.
2b100 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2f 0a 53 51 4c 49  ** </ol>.*/.SQLI
2b110 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
2b120 65 33 5f 70 72 65 70 61 72 65 28 0a 20 20 73 71  e3_prepare(.  sq
2b130 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20  lite3 *db,      
2b140 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73        /* Databas
2b150 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f  e handle */.  co
2b160 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20  nst char *zSql, 
2b170 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61        /* SQL sta
2b180 74 65 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e  tement, UTF-8 en
2b190 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e  coded */.  int n
2b1a0 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 20  Byte,           
2b1b0 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65     /* Maximum le
2b1c0 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20  ngth of zSql in 
2b1d0 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69  bytes. */.  sqli
2b1e0 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d  te3_stmt **ppStm
2b1f0 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74  t,  /* OUT: Stat
2b200 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a  ement handle */.
2b210 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70    const char **p
2b220 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54  zTail     /* OUT
2b230 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75  : Pointer to unu
2b240 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a  sed portion of z
2b250 53 71 6c 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45  Sql */.);.SQLITE
2b260 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
2b270 5f 70 72 65 70 61 72 65 5f 76 32 28 0a 20 20 73  _prepare_v2(.  s
2b280 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20  qlite3 *db,     
2b290 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61         /* Databa
2b2a0 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63  se handle */.  c
2b2b0 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c  onst char *zSql,
2b2c0 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74         /* SQL st
2b2d0 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65  atement, UTF-8 e
2b2e0 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20  ncoded */.  int 
2b2f0 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20  nByte,          
2b300 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c      /* Maximum l
2b310 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e  ength of zSql in
2b320 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c   bytes. */.  sql
2b330 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74  ite3_stmt **ppSt
2b340 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61  mt,  /* OUT: Sta
2b350 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f  tement handle */
2b360 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a  .  const char **
2b370 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55  pzTail     /* OU
2b380 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e  T: Pointer to un
2b390 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20  used portion of 
2b3a0 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54  zSql */.);.SQLIT
2b3b0 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
2b3c0 33 5f 70 72 65 70 61 72 65 31 36 28 0a 20 20 73  3_prepare16(.  s
2b3d0 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20  qlite3 *db,     
2b3e0 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61         /* Databa
2b3f0 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63  se handle */.  c
2b400 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c  onst void *zSql,
2b410 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74         /* SQL st
2b420 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20  atement, UTF-16 
2b430 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74  encoded */.  int
2b440 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20   nByte,         
2b450 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20       /* Maximum 
2b460 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69  length of zSql i
2b470 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71  n bytes. */.  sq
2b480 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53  lite3_stmt **ppS
2b490 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74  tmt,  /* OUT: St
2b4a0 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a  atement handle *
2b4b0 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a  /.  const void *
2b4c0 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f  *pzTail     /* O
2b4d0 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75  UT: Pointer to u
2b4e0 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66  nused portion of
2b4f0 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 53 51 4c 49   zSql */.);.SQLI
2b500 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
2b510 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
2b520 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20  .  sqlite3 *db, 
2b530 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61             /* Da
2b540 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f  tabase handle */
2b550 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a  .  const void *z
2b560 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51  Sql,       /* SQ
2b570 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46  L statement, UTF
2b580 2d 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20  -16 encoded */. 
2b590 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20   int nByte,     
2b5a0 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69           /* Maxi
2b5b0 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53  mum length of zS
2b5c0 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a  ql in bytes. */.
2b5d0 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a    sqlite3_stmt *
2b5e0 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54  *ppStmt,  /* OUT
2b5f0 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64  : Statement hand
2b600 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f  le */.  const vo
2b610 69 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20  id **pzTail     
2b620 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20  /* OUT: Pointer 
2b630 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f  to unused portio
2b640 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a  n of zSql */.);.
2b650 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2b660 20 52 65 74 72 69 65 76 69 6e 67 20 53 74 61 74   Retrieving Stat
2b670 65 6d 65 6e 74 20 53 51 4c 0a 2a 2a 20 4d 45 54  ement SQL.** MET
2b680 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d  HOD: sqlite3_stm
2b690 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  t.**.** ^The sql
2b6a0 69 74 65 33 5f 73 71 6c 28 50 29 20 69 6e 74 65  ite3_sql(P) inte
2b6b0 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20  rface returns a 
2b6c0 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 63 6f 70  pointer to a cop
2b6d0 79 20 6f 66 20 74 68 65 20 55 54 46 2d 38 0a 2a  y of the UTF-8.*
2b6e0 2a 20 53 51 4c 20 74 65 78 74 20 75 73 65 64 20  * SQL text used 
2b6f0 74 6f 20 63 72 65 61 74 65 20 5b 70 72 65 70 61  to create [prepa
2b700 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 50  red statement] P
2b710 20 69 66 20 50 20 77 61 73 0a 2a 2a 20 63 72 65   if P was.** cre
2b720 61 74 65 64 20 62 79 20 65 69 74 68 65 72 20 5b  ated by either [
2b730 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
2b740 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  v2()] or [sqlite
2b750 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29  3_prepare16_v2()
2b760 5d 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  ]..** ^The sqlit
2b770 65 33 5f 65 78 70 61 6e 64 65 64 5f 73 71 6c 28  e3_expanded_sql(
2b780 50 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  P) interface ret
2b790 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
2b7a0 6f 20 61 20 55 54 46 2d 38 0a 2a 2a 20 73 74 72  o a UTF-8.** str
2b7b0 69 6e 67 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74  ing containing t
2b7c0 68 65 20 53 51 4c 20 74 65 78 74 20 6f 66 20 70  he SQL text of p
2b7d0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2b7e0 74 20 50 20 77 69 74 68 0a 2a 2a 20 5b 62 6f 75  t P with.** [bou
2b7f0 6e 64 20 70 61 72 61 6d 65 74 65 72 73 5d 20 65  nd parameters] e
2b800 78 70 61 6e 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  xpanded..**.** ^
2b810 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 69 66  (For example, if
2b820 20 61 20 70 72 65 70 61 72 65 64 20 73 74 61 74   a prepared stat
2b830 65 6d 65 6e 74 20 69 73 20 63 72 65 61 74 65 64  ement is created
2b840 20 75 73 69 6e 67 20 74 68 65 20 53 51 4c 0a 2a   using the SQL.*
2b850 2a 20 74 65 78 74 20 22 53 45 4c 45 43 54 20 24  * text "SELECT $
2b860 61 62 63 2c 3a 78 79 7a 22 20 61 6e 64 20 69 66  abc,:xyz" and if
2b870 20 70 61 72 61 6d 65 74 65 72 20 24 61 62 63 20   parameter $abc 
2b880 69 73 20 62 6f 75 6e 64 20 74 6f 20 69 6e 74 65  is bound to inte
2b890 67 65 72 20 32 33 34 35 0a 2a 2a 20 61 6e 64 20  ger 2345.** and 
2b8a0 70 61 72 61 6d 65 74 65 72 20 3a 78 79 7a 20 69  parameter :xyz i
2b8b0 73 20 75 6e 62 6f 75 6e 64 2c 20 74 68 65 6e 20  s unbound, then 
2b8c0 73 71 6c 69 74 65 33 5f 73 71 6c 28 29 20 77 69  sqlite3_sql() wi
2b8d0 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 74 68 65  ll return.** the
2b8e0 20 6f 72 69 67 69 6e 61 6c 20 73 74 72 69 6e 67   original string
2b8f0 2c 20 22 53 45 4c 45 43 54 20 24 61 62 63 2c 3a  , "SELECT $abc,:
2b900 78 79 7a 22 20 62 75 74 20 73 71 6c 69 74 65 33  xyz" but sqlite3
2b910 5f 65 78 70 61 6e 64 65 64 5f 73 71 6c 28 29 0a  _expanded_sql().
2b920 2a 2a 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 22  ** will return "
2b930 53 45 4c 45 43 54 20 32 33 34 35 2c 4e 55 4c 4c  SELECT 2345,NULL
2b940 22 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ".)^.**.** ^The 
2b950 73 71 6c 69 74 65 33 5f 65 78 70 61 6e 64 65 64  sqlite3_expanded
2b960 5f 73 71 6c 28 29 20 69 6e 74 65 72 66 61 63 65  _sql() interface
2b970 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 20 69 66   returns NULL if
2b980 20 69 6e 73 75 66 66 69 63 69 65 6e 74 20 6d 65   insufficient me
2b990 6d 6f 72 79 0a 2a 2a 20 69 73 20 61 76 61 69 6c  mory.** is avail
2b9a0 61 62 6c 65 20 74 6f 20 68 6f 6c 64 20 74 68 65  able to hold the
2b9b0 20 72 65 73 75 6c 74 2c 20 6f 72 20 69 66 20 74   result, or if t
2b9c0 68 65 20 72 65 73 75 6c 74 20 77 6f 75 6c 64 20  he result would 
2b9d0 65 78 63 65 65 64 20 74 68 65 0a 2a 2a 20 74 68  exceed the.** th
2b9e0 65 20 6d 61 78 69 6d 75 6d 20 73 74 72 69 6e 67  e maximum string
2b9f0 20 6c 65 6e 67 74 68 20 64 65 74 65 72 6d 69 6e   length determin
2ba00 65 64 20 62 79 20 74 68 65 20 5b 53 51 4c 49 54  ed by the [SQLIT
2ba10 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 5d 2e  E_LIMIT_LENGTH].
2ba20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c  .**.** ^The [SQL
2ba30 49 54 45 5f 54 52 41 43 45 5f 53 49 5a 45 5f 4c  ITE_TRACE_SIZE_L
2ba40 49 4d 49 54 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  IMIT] compile-ti
2ba50 6d 65 20 6f 70 74 69 6f 6e 20 6c 69 6d 69 74 73  me option limits
2ba60 20 74 68 65 20 73 69 7a 65 20 6f 66 0a 2a 2a 20   the size of.** 
2ba70 62 6f 75 6e 64 20 70 61 72 61 6d 65 74 65 72 20  bound parameter 
2ba80 65 78 70 61 6e 73 69 6f 6e 73 2e 20 20 5e 54 68  expansions.  ^Th
2ba90 65 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 54  e [SQLITE_OMIT_T
2baa0 52 41 43 45 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  RACE] compile-ti
2bab0 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e 20 63 61 75  me.** option cau
2bac0 73 65 73 20 73 71 6c 69 74 65 33 5f 65 78 70 61  ses sqlite3_expa
2bad0 6e 64 65 64 5f 73 71 6c 28 29 20 74 6f 20 61 6c  nded_sql() to al
2bae0 77 61 79 73 20 72 65 74 75 72 6e 20 4e 55 4c 4c  ways return NULL
2baf0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 74 72  ..**.** ^The str
2bb00 69 6e 67 20 72 65 74 75 72 6e 65 64 20 62 79 20  ing returned by 
2bb10 73 71 6c 69 74 65 33 5f 73 71 6c 28 50 29 20 69  sqlite3_sql(P) i
2bb20 73 20 6d 61 6e 61 67 65 64 20 62 79 20 53 51 4c  s managed by SQL
2bb30 69 74 65 20 61 6e 64 20 69 73 0a 2a 2a 20 61 75  ite and is.** au
2bb40 74 6f 6d 61 74 69 63 61 6c 6c 79 20 66 72 65 65  tomatically free
2bb50 64 20 77 68 65 6e 20 74 68 65 20 70 72 65 70 61  d when the prepa
2bb60 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 69 73  red statement is
2bb70 20 66 69 6e 61 6c 69 7a 65 64 2e 0a 2a 2a 20 5e   finalized..** ^
2bb80 54 68 65 20 73 74 72 69 6e 67 20 72 65 74 75 72  The string retur
2bb90 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 65  ned by sqlite3_e
2bba0 78 70 61 6e 64 65 64 5f 73 71 6c 28 50 29 2c 20  xpanded_sql(P), 
2bbb0 6f 6e 20 74 68 65 20 6f 74 68 65 72 20 68 61 6e  on the other han
2bbc0 64 2c 0a 2a 2a 20 69 73 20 6f 62 74 61 69 6e 65  d,.** is obtaine
2bbd0 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  d from [sqlite3_
2bbe0 6d 61 6c 6c 6f 63 28 29 5d 20 61 6e 64 20 6d 75  malloc()] and mu
2bbf0 73 74 20 62 65 20 66 72 65 65 20 62 79 20 74 68  st be free by th
2bc00 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a  e application.**
2bc10 20 62 79 20 70 61 73 73 69 6e 67 20 69 74 20 74   by passing it t
2bc20 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  o [sqlite3_free(
2bc30 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  )]..*/.SQLITE_AP
2bc40 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  I const char *sq
2bc50 6c 69 74 65 33 5f 73 71 6c 28 73 71 6c 69 74 65  lite3_sql(sqlite
2bc60 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a  3_stmt *pStmt);.
2bc70 53 51 4c 49 54 45 5f 41 50 49 20 63 68 61 72 20  SQLITE_API char 
2bc80 2a 73 71 6c 69 74 65 33 5f 65 78 70 61 6e 64 65  *sqlite3_expande
2bc90 64 5f 73 71 6c 28 73 71 6c 69 74 65 33 5f 73 74  d_sql(sqlite3_st
2bca0 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a  mt *pStmt);../*.
2bcb0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 74  ** CAPI3REF: Det
2bcc0 65 72 6d 69 6e 65 20 49 66 20 41 6e 20 53 51 4c  ermine If An SQL
2bcd0 20 53 74 61 74 65 6d 65 6e 74 20 57 72 69 74 65   Statement Write
2bce0 73 20 54 68 65 20 44 61 74 61 62 61 73 65 0a 2a  s The Database.*
2bcf0 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65  * METHOD: sqlite
2bd00 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68  3_stmt.**.** ^Th
2bd10 65 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72  e sqlite3_stmt_r
2bd20 65 61 64 6f 6e 6c 79 28 58 29 20 69 6e 74 65 72  eadonly(X) inter
2bd30 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 72 75  face returns tru
2bd40 65 20 28 6e 6f 6e 2d 7a 65 72 6f 29 20 69 66 0a  e (non-zero) if.
2bd50 2a 2a 20 61 6e 64 20 6f 6e 6c 79 20 69 66 20 74  ** and only if t
2bd60 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
2bd70 74 65 6d 65 6e 74 5d 20 58 20 6d 61 6b 65 73 20  tement] X makes 
2bd80 6e 6f 20 64 69 72 65 63 74 20 63 68 61 6e 67 65  no direct change
2bd90 73 20 74 6f 0a 2a 2a 20 74 68 65 20 63 6f 6e 74  s to.** the cont
2bda0 65 6e 74 20 6f 66 20 74 68 65 20 64 61 74 61 62  ent of the datab
2bdb0 61 73 65 20 66 69 6c 65 2e 0a 2a 2a 0a 2a 2a 20  ase file..**.** 
2bdc0 4e 6f 74 65 20 74 68 61 74 20 5b 61 70 70 6c 69  Note that [appli
2bdd0 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53  cation-defined S
2bde0 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 20 6f 72  QL functions] or
2bdf0 0a 2a 2a 20 5b 76 69 72 74 75 61 6c 20 74 61 62  .** [virtual tab
2be00 6c 65 73 5d 20 6d 69 67 68 74 20 63 68 61 6e 67  les] might chang
2be10 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69  e the database i
2be20 6e 64 69 72 65 63 74 6c 79 20 61 73 20 61 20 73  ndirectly as a s
2be30 69 64 65 20 65 66 66 65 63 74 2e 20 20 0a 2a 2a  ide effect.  .**
2be40 20 5e 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20   ^(For example, 
2be50 69 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f  if an applicatio
2be60 6e 20 64 65 66 69 6e 65 73 20 61 20 66 75 6e 63  n defines a func
2be70 74 69 6f 6e 20 22 65 76 61 6c 28 29 22 20 74 68  tion "eval()" th
2be80 61 74 20 0a 2a 2a 20 63 61 6c 6c 73 20 5b 73 71  at .** calls [sq
2be90 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2c 20 74  lite3_exec()], t
2bea0 68 65 6e 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e  hen the followin
2beb0 67 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  g SQL statement 
2bec0 77 6f 75 6c 64 0a 2a 2a 20 63 68 61 6e 67 65 20  would.** change 
2bed0 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
2bee0 65 20 74 68 72 6f 75 67 68 20 73 69 64 65 2d 65  e through side-e
2bef0 66 66 65 63 74 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62  ffects:.**.** <b
2bf00 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a  lockquote><pre>.
2bf10 2a 2a 20 20 20 20 53 45 4c 45 43 54 20 65 76 61  **    SELECT eva
2bf20 6c 28 27 44 45 4c 45 54 45 20 46 52 4f 4d 20 74  l('DELETE FROM t
2bf30 31 27 29 20 46 52 4f 4d 20 74 32 3b 0a 2a 2a 20  1') FROM t2;.** 
2bf40 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f  </pre></blockquo
2bf50 74 65 3e 0a 2a 2a 0a 2a 2a 20 42 75 74 20 62 65  te>.**.** But be
2bf60 63 61 75 73 65 20 74 68 65 20 5b 53 45 4c 45 43  cause the [SELEC
2bf70 54 5d 20 73 74 61 74 65 6d 65 6e 74 20 64 6f 65  T] statement doe
2bf80 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65  s not change the
2bf90 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 0a 2a   database file.*
2bfa0 2a 20 64 69 72 65 63 74 6c 79 2c 20 73 71 6c 69  * directly, sqli
2bfb0 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c  te3_stmt_readonl
2bfc0 79 28 29 20 77 6f 75 6c 64 20 73 74 69 6c 6c 20  y() would still 
2bfd0 72 65 74 75 72 6e 20 74 72 75 65 2e 29 5e 0a 2a  return true.)^.*
2bfe0 2a 0a 2a 2a 20 5e 54 72 61 6e 73 61 63 74 69 6f  *.** ^Transactio
2bff0 6e 20 63 6f 6e 74 72 6f 6c 20 73 74 61 74 65 6d  n control statem
2c000 65 6e 74 73 20 73 75 63 68 20 61 73 20 5b 42 45  ents such as [BE
2c010 47 49 4e 5d 2c 20 5b 43 4f 4d 4d 49 54 5d 2c 20  GIN], [COMMIT], 
2c020 5b 52 4f 4c 4c 42 41 43 4b 5d 2c 0a 2a 2a 20 5b  [ROLLBACK],.** [
2c030 53 41 56 45 50 4f 49 4e 54 5d 2c 20 61 6e 64 20  SAVEPOINT], and 
2c040 5b 52 45 4c 45 41 53 45 5d 20 63 61 75 73 65 20  [RELEASE] cause 
2c050 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61  sqlite3_stmt_rea
2c060 64 6f 6e 6c 79 28 29 20 74 6f 20 72 65 74 75 72  donly() to retur
2c070 6e 20 74 72 75 65 2c 0a 2a 2a 20 73 69 6e 63 65  n true,.** since
2c080 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 73 20   the statements 
2c090 74 68 65 6d 73 65 6c 76 65 73 20 64 6f 20 6e 6f  themselves do no
2c0a0 74 20 61 63 74 75 61 6c 6c 79 20 6d 6f 64 69 66  t actually modif
2c0b0 79 20 74 68 65 20 64 61 74 61 62 61 73 65 20 62  y the database b
2c0c0 75 74 0a 2a 2a 20 72 61 74 68 65 72 20 74 68 65  ut.** rather the
2c0d0 79 20 63 6f 6e 74 72 6f 6c 20 74 68 65 20 74 69  y control the ti
2c0e0 6d 69 6e 67 20 6f 66 20 77 68 65 6e 20 6f 74 68  ming of when oth
2c0f0 65 72 20 73 74 61 74 65 6d 65 6e 74 73 20 6d 6f  er statements mo
2c100 64 69 66 79 20 74 68 65 20 0a 2a 2a 20 64 61 74  dify the .** dat
2c110 61 62 61 73 65 2e 20 20 5e 54 68 65 20 5b 41 54  abase.  ^The [AT
2c120 54 41 43 48 5d 20 61 6e 64 20 5b 44 45 54 41 43  TACH] and [DETAC
2c130 48 5d 20 73 74 61 74 65 6d 65 6e 74 73 20 61 6c  H] statements al
2c140 73 6f 20 63 61 75 73 65 0a 2a 2a 20 73 71 6c 69  so cause.** sqli
2c150 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c  te3_stmt_readonl
2c160 79 28 29 20 74 6f 20 72 65 74 75 72 6e 20 74 72  y() to return tr
2c170 75 65 20 73 69 6e 63 65 2c 20 77 68 69 6c 65 20  ue since, while 
2c180 74 68 6f 73 65 20 73 74 61 74 65 6d 65 6e 74 73  those statements
2c190 0a 2a 2a 20 63 68 61 6e 67 65 20 74 68 65 20 63  .** change the c
2c1a0 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 66 20  onfiguration of 
2c1b0 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  a database conne
2c1c0 63 74 69 6f 6e 2c 20 74 68 65 79 20 64 6f 20 6e  ction, they do n
2c1d0 6f 74 20 6d 61 6b 65 20 0a 2a 2a 20 63 68 61 6e  ot make .** chan
2c1e0 67 65 73 20 74 6f 20 74 68 65 20 63 6f 6e 74 65  ges to the conte
2c1f0 6e 74 20 6f 66 20 74 68 65 20 64 61 74 61 62 61  nt of the databa
2c200 73 65 20 66 69 6c 65 73 20 6f 6e 20 64 69 73 6b  se files on disk
2c210 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  ..** ^The sqlite
2c220 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28  3_stmt_readonly(
2c230 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ) interface retu
2c240 72 6e 73 20 74 72 75 65 20 66 6f 72 20 5b 42 45  rns true for [BE
2c250 47 49 4e 5d 20 73 69 6e 63 65 0a 2a 2a 20 5b 42  GIN] since.** [B
2c260 45 47 49 4e 5d 20 6d 65 72 65 6c 79 20 73 65 74  EGIN] merely set
2c270 73 20 69 6e 74 65 72 6e 61 6c 20 66 6c 61 67 73  s internal flags
2c280 2c 20 62 75 74 20 74 68 65 20 5b 42 45 47 49 4e  , but the [BEGIN
2c290 7c 42 45 47 49 4e 20 49 4d 4d 45 44 49 41 54 45  |BEGIN IMMEDIATE
2c2a0 5d 20 61 6e 64 0a 2a 2a 20 5b 42 45 47 49 4e 7c  ] and.** [BEGIN|
2c2b0 42 45 47 49 4e 20 45 58 43 4c 55 53 49 56 45 5d  BEGIN EXCLUSIVE]
2c2c0 20 63 6f 6d 6d 61 6e 64 73 20 64 6f 20 74 6f 75   commands do tou
2c2d0 63 68 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ch the database 
2c2e0 61 6e 64 20 73 6f 0a 2a 2a 20 73 71 6c 69 74 65  and so.** sqlite
2c2f0 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28  3_stmt_readonly(
2c300 29 20 72 65 74 75 72 6e 73 20 66 61 6c 73 65 20  ) returns false 
2c310 66 6f 72 20 74 68 6f 73 65 20 63 6f 6d 6d 61 6e  for those comman
2c320 64 73 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  ds..*/.SQLITE_AP
2c330 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 74  I int sqlite3_st
2c340 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 73 71 6c 69  mt_readonly(sqli
2c350 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29  te3_stmt *pStmt)
2c360 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2c370 46 3a 20 44 65 74 65 72 6d 69 6e 65 20 49 66 20  F: Determine If 
2c380 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65  A Prepared State
2c390 6d 65 6e 74 20 48 61 73 20 42 65 65 6e 20 52 65  ment Has Been Re
2c3a0 73 65 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  set.** METHOD: s
2c3b0 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a  qlite3_stmt.**.*
2c3c0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73  * ^The sqlite3_s
2c3d0 74 6d 74 5f 62 75 73 79 28 53 29 20 69 6e 74 65  tmt_busy(S) inte
2c3e0 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 72  rface returns tr
2c3f0 75 65 20 28 6e 6f 6e 2d 7a 65 72 6f 29 20 69 66  ue (non-zero) if
2c400 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65   the.** [prepare
2c410 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 68  d statement] S h
2c420 61 73 20 62 65 65 6e 20 73 74 65 70 70 65 64 20  as been stepped 
2c430 61 74 20 6c 65 61 73 74 20 6f 6e 63 65 20 75 73  at least once us
2c440 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ing .** [sqlite3
2c450 5f 73 74 65 70 28 53 29 5d 20 62 75 74 20 68 61  _step(S)] but ha
2c460 73 20 6e 65 69 74 68 65 72 20 72 75 6e 20 74 6f  s neither run to
2c470 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 28 72 65 74   completion (ret
2c480 75 72 6e 65 64 0a 2a 2a 20 5b 53 51 4c 49 54 45  urned.** [SQLITE
2c490 5f 44 4f 4e 45 5d 20 66 72 6f 6d 20 5b 73 71 6c  _DONE] from [sql
2c4a0 69 74 65 33 5f 73 74 65 70 28 53 29 5d 29 20 6e  ite3_step(S)]) n
2c4b0 6f 72 0a 2a 2a 20 62 65 65 6e 20 72 65 73 65 74  or.** been reset
2c4c0 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
2c4d0 72 65 73 65 74 28 53 29 5d 2e 20 20 5e 54 68 65  reset(S)].  ^The
2c4e0 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 62 75   sqlite3_stmt_bu
2c4f0 73 79 28 53 29 0a 2a 2a 20 69 6e 74 65 72 66 61  sy(S).** interfa
2c500 63 65 20 72 65 74 75 72 6e 73 20 66 61 6c 73 65  ce returns false
2c510 20 69 66 20 53 20 69 73 20 61 20 4e 55 4c 4c 20   if S is a NULL 
2c520 70 6f 69 6e 74 65 72 2e 20 20 49 66 20 53 20 69  pointer.  If S i
2c530 73 20 6e 6f 74 20 61 20 0a 2a 2a 20 4e 55 4c 4c  s not a .** NULL
2c540 20 70 6f 69 6e 74 65 72 20 61 6e 64 20 69 73 20   pointer and is 
2c550 6e 6f 74 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  not a pointer to
2c560 20 61 20 76 61 6c 69 64 20 5b 70 72 65 70 61 72   a valid [prepar
2c570 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a  ed statement].**
2c580 20 6f 62 6a 65 63 74 2c 20 74 68 65 6e 20 74 68   object, then th
2c590 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e  e behavior is un
2c5a0 64 65 66 69 6e 65 64 20 61 6e 64 20 70 72 6f 62  defined and prob
2c5b0 61 62 6c 79 20 75 6e 64 65 73 69 72 61 62 6c 65  ably undesirable
2c5c0 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74  ..**.** This int
2c5d0 65 72 66 61 63 65 20 63 61 6e 20 62 65 20 75 73  erface can be us
2c5e0 65 64 20 69 6e 20 63 6f 6d 62 69 6e 61 74 69 6f  ed in combinatio
2c5f0 6e 20 5b 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f  n [sqlite3_next_
2c600 73 74 6d 74 28 29 5d 0a 2a 2a 20 74 6f 20 6c 6f  stmt()].** to lo
2c610 63 61 74 65 20 61 6c 6c 20 70 72 65 70 61 72 65  cate all prepare
2c620 64 20 73 74 61 74 65 6d 65 6e 74 73 20 61 73 73  d statements ass
2c630 6f 63 69 61 74 65 64 20 77 69 74 68 20 61 20 64  ociated with a d
2c640 61 74 61 62 61 73 65 20 0a 2a 2a 20 63 6f 6e 6e  atabase .** conn
2c650 65 63 74 69 6f 6e 20 74 68 61 74 20 61 72 65 20  ection that are 
2c660 69 6e 20 6e 65 65 64 20 6f 66 20 62 65 69 6e 67  in need of being
2c670 20 72 65 73 65 74 2e 20 20 54 68 69 73 20 63 61   reset.  This ca
2c680 6e 20 62 65 20 75 73 65 64 2c 0a 2a 2a 20 66 6f  n be used,.** fo
2c690 72 20 65 78 61 6d 70 6c 65 2c 20 69 6e 20 64 69  r example, in di
2c6a0 61 67 6e 6f 73 74 69 63 20 72 6f 75 74 69 6e 65  agnostic routine
2c6b0 73 20 74 6f 20 73 65 61 72 63 68 20 66 6f 72 20  s to search for 
2c6c0 70 72 65 70 61 72 65 64 20 0a 2a 2a 20 73 74 61  prepared .** sta
2c6d0 74 65 6d 65 6e 74 73 20 74 68 61 74 20 61 72 65  tements that are
2c6e0 20 68 6f 6c 64 69 6e 67 20 61 20 74 72 61 6e 73   holding a trans
2c6f0 61 63 74 69 6f 6e 20 6f 70 65 6e 2e 0a 2a 2f 0a  action open..*/.
2c700 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
2c710 71 6c 69 74 65 33 5f 73 74 6d 74 5f 62 75 73 79  qlite3_stmt_busy
2c720 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b  (sqlite3_stmt*);
2c730 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2c740 3a 20 44 79 6e 61 6d 69 63 61 6c 6c 79 20 54 79  : Dynamically Ty
2c750 70 65 64 20 56 61 6c 75 65 20 4f 62 6a 65 63 74  ped Value Object
2c760 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70  .** KEYWORDS: {p
2c770 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
2c780 5f 76 61 6c 75 65 7d 20 7b 75 6e 70 72 6f 74 65  _value} {unprote
2c790 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
2c7a0 75 65 7d 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65  ue}.**.** SQLite
2c7b0 20 75 73 65 73 20 74 68 65 20 73 71 6c 69 74 65   uses the sqlite
2c7c0 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 74  3_value object t
2c7d0 6f 20 72 65 70 72 65 73 65 6e 74 20 61 6c 6c 20  o represent all 
2c7e0 76 61 6c 75 65 73 0a 2a 2a 20 74 68 61 74 20 63  values.** that c
2c7f0 61 6e 20 62 65 20 73 74 6f 72 65 64 20 69 6e 20  an be stored in 
2c800 61 20 64 61 74 61 62 61 73 65 20 74 61 62 6c 65  a database table
2c810 2e 20 53 51 4c 69 74 65 20 75 73 65 73 20 64 79  . SQLite uses dy
2c820 6e 61 6d 69 63 20 74 79 70 69 6e 67 0a 2a 2a 20  namic typing.** 
2c830 66 6f 72 20 74 68 65 20 76 61 6c 75 65 73 20 69  for the values i
2c840 74 20 73 74 6f 72 65 73 2e 20 20 5e 56 61 6c 75  t stores.  ^Valu
2c850 65 73 20 73 74 6f 72 65 64 20 69 6e 20 73 71 6c  es stored in sql
2c860 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
2c870 74 73 0a 2a 2a 20 63 61 6e 20 62 65 20 69 6e 74  ts.** can be int
2c880 65 67 65 72 73 2c 20 66 6c 6f 61 74 69 6e 67 20  egers, floating 
2c890 70 6f 69 6e 74 20 76 61 6c 75 65 73 2c 20 73 74  point values, st
2c8a0 72 69 6e 67 73 2c 20 42 4c 4f 42 73 2c 20 6f 72  rings, BLOBs, or
2c8b0 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20   NULL..**.** An 
2c8c0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
2c8d0 6a 65 63 74 20 6d 61 79 20 62 65 20 65 69 74 68  ject may be eith
2c8e0 65 72 20 22 70 72 6f 74 65 63 74 65 64 22 20 6f  er "protected" o
2c8f0 72 20 22 75 6e 70 72 6f 74 65 63 74 65 64 22 2e  r "unprotected".
2c900 0a 2a 2a 20 53 6f 6d 65 20 69 6e 74 65 72 66 61  .** Some interfa
2c910 63 65 73 20 72 65 71 75 69 72 65 20 61 20 70 72  ces require a pr
2c920 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
2c930 76 61 6c 75 65 2e 20 20 4f 74 68 65 72 20 69 6e  value.  Other in
2c940 74 65 72 66 61 63 65 73 0a 2a 2a 20 77 69 6c 6c  terfaces.** will
2c950 20 61 63 63 65 70 74 20 65 69 74 68 65 72 20 61   accept either a
2c960 20 70 72 6f 74 65 63 74 65 64 20 6f 72 20 61 6e   protected or an
2c970 20 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c   unprotected sql
2c980 69 74 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a 20 45  ite3_value..** E
2c990 76 65 72 79 20 69 6e 74 65 72 66 61 63 65 20 74  very interface t
2c9a0 68 61 74 20 61 63 63 65 70 74 73 20 73 71 6c 69  hat accepts sqli
2c9b0 74 65 33 5f 76 61 6c 75 65 20 61 72 67 75 6d 65  te3_value argume
2c9c0 6e 74 73 20 73 70 65 63 69 66 69 65 73 0a 2a 2a  nts specifies.**
2c9d0 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20   whether or not 
2c9e0 69 74 20 72 65 71 75 69 72 65 73 20 61 20 70 72  it requires a pr
2c9f0 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
2ca00 76 61 6c 75 65 2e 20 20 54 68 65 0a 2a 2a 20 5b  value.  The.** [
2ca10 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 64 75  sqlite3_value_du
2ca20 70 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63  p()] interface c
2ca30 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 63 6f  an be used to co
2ca40 6e 73 74 72 75 63 74 20 61 20 6e 65 77 20 0a 2a  nstruct a new .*
2ca50 2a 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  * protected sqli
2ca60 74 65 33 5f 76 61 6c 75 65 20 66 72 6f 6d 20 61  te3_value from a
2ca70 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71  n unprotected sq
2ca80 6c 69 74 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a 0a  lite3_value..**.
2ca90 2a 2a 20 54 68 65 20 74 65 72 6d 73 20 22 70 72  ** The terms "pr
2caa0 6f 74 65 63 74 65 64 22 20 61 6e 64 20 22 75 6e  otected" and "un
2cab0 70 72 6f 74 65 63 74 65 64 22 20 72 65 66 65 72  protected" refer
2cac0 20 74 6f 20 77 68 65 74 68 65 72 20 6f 72 20 6e   to whether or n
2cad0 6f 74 0a 2a 2a 20 61 20 6d 75 74 65 78 20 69 73  ot.** a mutex is
2cae0 20 68 65 6c 64 2e 20 20 41 6e 20 69 6e 74 65 72   held.  An inter
2caf0 6e 61 6c 20 6d 75 74 65 78 20 69 73 20 68 65 6c  nal mutex is hel
2cb00 64 20 66 6f 72 20 61 20 70 72 6f 74 65 63 74 65  d for a protecte
2cb10 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c  d.** sqlite3_val
2cb20 75 65 20 6f 62 6a 65 63 74 20 62 75 74 20 6e 6f  ue object but no
2cb30 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64 20 66   mutex is held f
2cb40 6f 72 20 61 6e 20 75 6e 70 72 6f 74 65 63 74 65  or an unprotecte
2cb50 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c  d.** sqlite3_val
2cb60 75 65 20 6f 62 6a 65 63 74 2e 20 20 49 66 20 53  ue object.  If S
2cb70 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65  QLite is compile
2cb80 64 20 74 6f 20 62 65 20 73 69 6e 67 6c 65 2d 74  d to be single-t
2cb90 68 72 65 61 64 65 64 0a 2a 2a 20 28 77 69 74 68  hreaded.** (with
2cba0 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53   [SQLITE_THREADS
2cbb0 41 46 45 3d 30 5d 20 61 6e 64 20 77 69 74 68 20  AFE=0] and with 
2cbc0 5b 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73  [sqlite3_threads
2cbd0 61 66 65 28 29 5d 20 72 65 74 75 72 6e 69 6e 67  afe()] returning
2cbe0 20 30 29 0a 2a 2a 20 6f 72 20 69 66 20 53 51 4c   0).** or if SQL
2cbf0 69 74 65 20 69 73 20 72 75 6e 20 69 6e 20 6f 6e  ite is run in on
2cc00 65 20 6f 66 20 72 65 64 75 63 65 64 20 6d 75 74  e of reduced mut
2cc10 65 78 20 6d 6f 64 65 73 20 0a 2a 2a 20 5b 53 51  ex modes .** [SQ
2cc20 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47  LITE_CONFIG_SING
2cc30 4c 45 54 48 52 45 41 44 5d 20 6f 72 20 5b 53 51  LETHREAD] or [SQ
2cc40 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54  LITE_CONFIG_MULT
2cc50 49 54 48 52 45 41 44 5d 0a 2a 2a 20 74 68 65 6e  ITHREAD].** then
2cc60 20 74 68 65 72 65 20 69 73 20 6e 6f 20 64 69 73   there is no dis
2cc70 74 69 6e 63 74 69 6f 6e 20 62 65 74 77 65 65 6e  tinction between
2cc80 20 70 72 6f 74 65 63 74 65 64 20 61 6e 64 20 75   protected and u
2cc90 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71  nprotected.** sq
2cca0 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
2ccb0 63 74 73 20 61 6e 64 20 74 68 65 79 20 63 61 6e  cts and they can
2ccc0 20 62 65 20 75 73 65 64 20 69 6e 74 65 72 63 68   be used interch
2ccd0 61 6e 67 65 61 62 6c 79 2e 20 20 48 6f 77 65 76  angeably.  Howev
2cce0 65 72 2c 0a 2a 2a 20 66 6f 72 20 6d 61 78 69 6d  er,.** for maxim
2ccf0 75 6d 20 63 6f 64 65 20 70 6f 72 74 61 62 69 6c  um code portabil
2cd00 69 74 79 20 69 74 20 69 73 20 72 65 63 6f 6d 6d  ity it is recomm
2cd10 65 6e 64 65 64 20 74 68 61 74 20 61 70 70 6c 69  ended that appli
2cd20 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 74 69 6c 6c  cations.** still
2cd30 20 6d 61 6b 65 20 74 68 65 20 64 69 73 74 69 6e   make the distin
2cd40 63 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 70 72  ction between pr
2cd50 6f 74 65 63 74 65 64 20 61 6e 64 20 75 6e 70 72  otected and unpr
2cd60 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74  otected.** sqlit
2cd70 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73  e3_value objects
2cd80 20 65 76 65 6e 20 77 68 65 6e 20 6e 6f 74 20 73   even when not s
2cd90 74 72 69 63 74 6c 79 20 72 65 71 75 69 72 65 64  trictly required
2cda0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
2cdb0 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
2cdc0 74 73 20 74 68 61 74 20 61 72 65 20 70 61 73 73  ts that are pass
2cdd0 65 64 20 61 73 20 70 61 72 61 6d 65 74 65 72 73  ed as parameters
2cde0 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 69 6d 70   into the.** imp
2cdf0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 5b  lementation of [
2ce00 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
2ce10 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ned SQL function
2ce20 73 5d 20 61 72 65 20 70 72 6f 74 65 63 74 65 64  s] are protected
2ce30 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  ..** ^The sqlite
2ce40 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 72  3_value object r
2ce50 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73  eturned by.** [s
2ce60 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61  qlite3_column_va
2ce70 6c 75 65 28 29 5d 20 69 73 20 75 6e 70 72 6f 74  lue()] is unprot
2ce80 65 63 74 65 64 2e 0a 2a 2a 20 55 6e 70 72 6f 74  ected..** Unprot
2ce90 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
2cea0 6c 75 65 20 6f 62 6a 65 63 74 73 20 6d 61 79 20  lue objects may 
2ceb0 6f 6e 6c 79 20 62 65 20 75 73 65 64 20 77 69 74  only be used wit
2cec0 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65  h.** [sqlite3_re
2ced0 73 75 6c 74 5f 76 61 6c 75 65 28 29 5d 20 61 6e  sult_value()] an
2cee0 64 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  d [sqlite3_bind_
2cef0 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20 54 68 65  value()]..** The
2cf00 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
2cf10 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f 76  blob | sqlite3_v
2cf20 61 6c 75 65 5f 74 79 70 65 28 29 5d 20 66 61 6d  alue_type()] fam
2cf30 69 6c 79 20 6f 66 0a 2a 2a 20 69 6e 74 65 72 66  ily of.** interf
2cf40 61 63 65 73 20 72 65 71 75 69 72 65 20 70 72 6f  aces require pro
2cf50 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
2cf60 61 6c 75 65 20 6f 62 6a 65 63 74 73 2e 0a 2a 2f  alue objects..*/
2cf70 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
2cf80 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 73 71  sqlite3_value sq
2cf90 6c 69 74 65 33 5f 76 61 6c 75 65 3b 0a 0a 2f 2a  lite3_value;../*
2cfa0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 51  .** CAPI3REF: SQ
2cfb0 4c 20 46 75 6e 63 74 69 6f 6e 20 43 6f 6e 74 65  L Function Conte
2cfc0 78 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20  xt Object.**.** 
2cfd0 54 68 65 20 63 6f 6e 74 65 78 74 20 69 6e 20 77  The context in w
2cfe0 68 69 63 68 20 61 6e 20 53 51 4c 20 66 75 6e 63  hich an SQL func
2cff0 74 69 6f 6e 20 65 78 65 63 75 74 65 73 20 69 73  tion executes is
2d000 20 73 74 6f 72 65 64 20 69 6e 20 61 6e 0a 2a 2a   stored in an.**
2d010 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74   sqlite3_context
2d020 20 6f 62 6a 65 63 74 2e 20 20 5e 41 20 70 6f 69   object.  ^A poi
2d030 6e 74 65 72 20 74 6f 20 61 6e 20 73 71 6c 69 74  nter to an sqlit
2d040 65 33 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65 63  e3_context objec
2d050 74 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 66  t.** is always f
2d060 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74  irst parameter t
2d070 6f 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  o [application-d
2d080 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74  efined SQL funct
2d090 69 6f 6e 73 5d 2e 0a 2a 2a 20 54 68 65 20 61 70  ions]..** The ap
2d0a0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
2d0b0 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69  d SQL function i
2d0c0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69  mplementation wi
2d0d0 6c 6c 20 70 61 73 73 20 74 68 69 73 0a 2a 2a 20  ll pass this.** 
2d0e0 70 6f 69 6e 74 65 72 20 74 68 72 6f 75 67 68 20  pointer through 
2d0f0 69 6e 74 6f 20 63 61 6c 6c 73 20 74 6f 20 5b 73  into calls to [s
2d100 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e  qlite3_result_in
2d110 74 20 7c 20 73 71 6c 69 74 65 33 5f 72 65 73 75  t | sqlite3_resu
2d120 6c 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74  lt()],.** [sqlit
2d130 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e  e3_aggregate_con
2d140 74 65 78 74 28 29 5d 2c 20 5b 73 71 6c 69 74 65  text()], [sqlite
2d150 33 5f 75 73 65 72 5f 64 61 74 61 28 29 5d 2c 0a  3_user_data()],.
2d160 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ** [sqlite3_cont
2d170 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 29 5d  ext_db_handle()]
2d180 2c 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 61  , [sqlite3_get_a
2d190 75 78 64 61 74 61 28 29 5d 2c 0a 2a 2a 20 61 6e  uxdata()],.** an
2d1a0 64 2f 6f 72 20 5b 73 71 6c 69 74 65 33 5f 73 65  d/or [sqlite3_se
2d1b0 74 5f 61 75 78 64 61 74 61 28 29 5d 2e 0a 2a 2f  t_auxdata()]..*/
2d1c0 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
2d1d0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20  sqlite3_context 
2d1e0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 3b  sqlite3_context;
2d1f0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2d200 3a 20 42 69 6e 64 69 6e 67 20 56 61 6c 75 65 73  : Binding Values
2d210 20 54 6f 20 50 72 65 70 61 72 65 64 20 53 74 61   To Prepared Sta
2d220 74 65 6d 65 6e 74 73 0a 2a 2a 20 4b 45 59 57 4f  tements.** KEYWO
2d230 52 44 53 3a 20 7b 68 6f 73 74 20 70 61 72 61 6d  RDS: {host param
2d240 65 74 65 72 7d 20 7b 68 6f 73 74 20 70 61 72 61  eter} {host para
2d250 6d 65 74 65 72 73 7d 20 7b 68 6f 73 74 20 70 61  meters} {host pa
2d260 72 61 6d 65 74 65 72 20 6e 61 6d 65 7d 0a 2a 2a  rameter name}.**
2d270 20 4b 45 59 57 4f 52 44 53 3a 20 7b 53 51 4c 20   KEYWORDS: {SQL 
2d280 70 61 72 61 6d 65 74 65 72 7d 20 7b 53 51 4c 20  parameter} {SQL 
2d290 70 61 72 61 6d 65 74 65 72 73 7d 20 7b 70 61 72  parameters} {par
2d2a0 61 6d 65 74 65 72 20 62 69 6e 64 69 6e 67 7d 0a  ameter binding}.
2d2b0 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
2d2c0 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 28  e3_stmt.**.** ^(
2d2d0 49 6e 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  In the SQL state
2d2e0 6d 65 6e 74 20 74 65 78 74 20 69 6e 70 75 74 20  ment text input 
2d2f0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  to [sqlite3_prep
2d300 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 69 74  are_v2()] and it
2d310 73 20 76 61 72 69 61 6e 74 73 2c 0a 2a 2a 20 6c  s variants,.** l
2d320 69 74 65 72 61 6c 73 20 6d 61 79 20 62 65 20 72  iterals may be r
2d330 65 70 6c 61 63 65 64 20 62 79 20 61 20 5b 70 61  eplaced by a [pa
2d340 72 61 6d 65 74 65 72 5d 20 74 68 61 74 20 6d 61  rameter] that ma
2d350 74 63 68 65 73 20 6f 6e 65 20 6f 66 20 66 6f 6c  tches one of fol
2d360 6c 6f 77 69 6e 67 0a 2a 2a 20 74 65 6d 70 6c 61  lowing.** templa
2d370 74 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a  tes:.**.** <ul>.
2d380 2a 2a 20 3c 6c 69 3e 20 20 3f 0a 2a 2a 20 3c 6c  ** <li>  ?.** <l
2d390 69 3e 20 20 3f 4e 4e 4e 0a 2a 2a 20 3c 6c 69 3e  i>  ?NNN.** <li>
2d3a0 20 20 3a 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20    :VVV.** <li>  
2d3b0 40 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20 24 56  @VVV.** <li>  $V
2d3c0 56 56 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a  VV.** </ul>.**.*
2d3d0 2a 20 49 6e 20 74 68 65 20 74 65 6d 70 6c 61 74  * In the templat
2d3e0 65 73 20 61 62 6f 76 65 2c 20 4e 4e 4e 20 72 65  es above, NNN re
2d3f0 70 72 65 73 65 6e 74 73 20 61 6e 20 69 6e 74 65  presents an inte
2d400 67 65 72 20 6c 69 74 65 72 61 6c 2c 0a 2a 2a 20  ger literal,.** 
2d410 61 6e 64 20 56 56 56 20 72 65 70 72 65 73 65 6e  and VVV represen
2d420 74 73 20 61 6e 20 61 6c 70 68 61 6e 75 6d 65 72  ts an alphanumer
2d430 69 63 20 69 64 65 6e 74 69 66 69 65 72 2e 29 5e  ic identifier.)^
2d440 20 20 5e 54 68 65 20 76 61 6c 75 65 73 20 6f 66    ^The values of
2d450 20 74 68 65 73 65 0a 2a 2a 20 70 61 72 61 6d 65   these.** parame
2d460 74 65 72 73 20 28 61 6c 73 6f 20 63 61 6c 6c 65  ters (also calle
2d470 64 20 22 68 6f 73 74 20 70 61 72 61 6d 65 74 65  d "host paramete
2d480 72 20 6e 61 6d 65 73 22 20 6f 72 20 22 53 51 4c  r names" or "SQL
2d490 20 70 61 72 61 6d 65 74 65 72 73 22 29 0a 2a 2a   parameters").**
2d4a0 20 63 61 6e 20 62 65 20 73 65 74 20 75 73 69 6e   can be set usin
2d4b0 67 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69  g the sqlite3_bi
2d4c0 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20  nd_*() routines 
2d4d0 64 65 66 69 6e 65 64 20 68 65 72 65 2e 0a 2a 2a  defined here..**
2d4e0 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61  .** ^The first a
2d4f0 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 73  rgument to the s
2d500 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20  qlite3_bind_*() 
2d510 72 6f 75 74 69 6e 65 73 20 69 73 20 61 6c 77 61  routines is alwa
2d520 79 73 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20  ys.** a pointer 
2d530 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
2d540 73 74 6d 74 5d 20 6f 62 6a 65 63 74 20 72 65 74  stmt] object ret
2d550 75 72 6e 65 64 20 66 72 6f 6d 0a 2a 2a 20 5b 73  urned from.** [s
2d560 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
2d570 32 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69  2()] or its vari
2d580 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ants..**.** ^The
2d590 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
2d5a0 20 69 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66   is the index of
2d5b0 20 74 68 65 20 53 51 4c 20 70 61 72 61 6d 65 74   the SQL paramet
2d5c0 65 72 20 74 6f 20 62 65 20 73 65 74 2e 0a 2a 2a  er to be set..**
2d5d0 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 53   ^The leftmost S
2d5e0 51 4c 20 70 61 72 61 6d 65 74 65 72 20 68 61 73  QL parameter has
2d5f0 20 61 6e 20 69 6e 64 65 78 20 6f 66 20 31 2e 20   an index of 1. 
2d600 20 5e 57 68 65 6e 20 74 68 65 20 73 61 6d 65 20   ^When the same 
2d610 6e 61 6d 65 64 0a 2a 2a 20 53 51 4c 20 70 61 72  named.** SQL par
2d620 61 6d 65 74 65 72 20 69 73 20 75 73 65 64 20 6d  ameter is used m
2d630 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65 2c 20 73  ore than once, s
2d640 65 63 6f 6e 64 20 61 6e 64 20 73 75 62 73 65 71  econd and subseq
2d650 75 65 6e 74 0a 2a 2a 20 6f 63 63 75 72 72 65 6e  uent.** occurren
2d660 63 65 73 20 68 61 76 65 20 74 68 65 20 73 61 6d  ces have the sam
2d670 65 20 69 6e 64 65 78 20 61 73 20 74 68 65 20 66  e index as the f
2d680 69 72 73 74 20 6f 63 63 75 72 72 65 6e 63 65 2e  irst occurrence.
2d690 0a 2a 2a 20 5e 54 68 65 20 69 6e 64 65 78 20 66  .** ^The index f
2d6a0 6f 72 20 6e 61 6d 65 64 20 70 61 72 61 6d 65 74  or named paramet
2d6b0 65 72 73 20 63 61 6e 20 62 65 20 6c 6f 6f 6b 65  ers can be looke
2d6c0 64 20 75 70 20 75 73 69 6e 67 20 74 68 65 0a 2a  d up using the.*
2d6d0 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  * [sqlite3_bind_
2d6e0 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28  parameter_index(
2d6f0 29 5d 20 41 50 49 20 69 66 20 64 65 73 69 72 65  )] API if desire
2d700 64 2e 20 20 5e 54 68 65 20 69 6e 64 65 78 0a 2a  d.  ^The index.*
2d710 2a 20 66 6f 72 20 22 3f 4e 4e 4e 22 20 70 61 72  * for "?NNN" par
2d720 61 6d 65 74 65 72 73 20 69 73 20 74 68 65 20 76  ameters is the v
2d730 61 6c 75 65 20 6f 66 20 4e 4e 4e 2e 0a 2a 2a 20  alue of NNN..** 
2d740 5e 54 68 65 20 4e 4e 4e 20 76 61 6c 75 65 20 6d  ^The NNN value m
2d750 75 73 74 20 62 65 20 62 65 74 77 65 65 6e 20 31  ust be between 1
2d760 20 61 6e 64 20 74 68 65 20 5b 73 71 6c 69 74 65   and the [sqlite
2d770 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 70 61  3_limit()].** pa
2d780 72 61 6d 65 74 65 72 20 5b 53 51 4c 49 54 45 5f  rameter [SQLITE_
2d790 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e  LIMIT_VARIABLE_N
2d7a0 55 4d 42 45 52 5d 20 28 64 65 66 61 75 6c 74 20  UMBER] (default 
2d7b0 76 61 6c 75 65 3a 20 39 39 39 29 2e 0a 2a 2a 0a  value: 999)..**.
2d7c0 2a 2a 20 5e 54 68 65 20 74 68 69 72 64 20 61 72  ** ^The third ar
2d7d0 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 76 61  gument is the va
2d7e0 6c 75 65 20 74 6f 20 62 69 6e 64 20 74 6f 20 74  lue to bind to t
2d7f0 68 65 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a  he parameter..**
2d800 20 5e 49 66 20 74 68 65 20 74 68 69 72 64 20 70   ^If the third p
2d810 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
2d820 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 29 20  te3_bind_text() 
2d830 6f 72 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  or sqlite3_bind_
2d840 74 65 78 74 31 36 28 29 0a 2a 2a 20 6f 72 20 73  text16().** or s
2d850 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
2d860 28 29 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69  () is a NULL poi
2d870 6e 74 65 72 20 74 68 65 6e 20 74 68 65 20 66 6f  nter then the fo
2d880 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 0a 2a  urth parameter.*
2d890 2a 20 69 73 20 69 67 6e 6f 72 65 64 20 61 6e 64  * is ignored and
2d8a0 20 74 68 65 20 65 6e 64 20 72 65 73 75 6c 74 20   the end result 
2d8b0 69 73 20 74 68 65 20 73 61 6d 65 20 61 73 20 73  is the same as s
2d8c0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 6e 75 6c 6c  qlite3_bind_null
2d8d0 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 74  ()..**.** ^(In t
2d8e0 68 6f 73 65 20 72 6f 75 74 69 6e 65 73 20 74 68  hose routines th
2d8f0 61 74 20 68 61 76 65 20 61 20 66 6f 75 72 74 68  at have a fourth
2d900 20 61 72 67 75 6d 65 6e 74 2c 20 69 74 73 20 76   argument, its v
2d910 61 6c 75 65 20 69 73 20 74 68 65 0a 2a 2a 20 6e  alue is the.** n
2d920 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69  umber of bytes i
2d930 6e 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e  n the parameter.
2d940 20 20 54 6f 20 62 65 20 63 6c 65 61 72 3a 20 74    To be clear: t
2d950 68 65 20 76 61 6c 75 65 20 69 73 20 74 68 65 0a  he value is the.
2d960 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 3c 75 3e  ** number of <u>
2d970 62 79 74 65 73 3c 2f 75 3e 20 69 6e 20 74 68 65  bytes</u> in the
2d980 20 76 61 6c 75 65 2c 20 6e 6f 74 20 74 68 65 20   value, not the 
2d990 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63  number of charac
2d9a0 74 65 72 73 2e 29 5e 0a 2a 2a 20 5e 49 66 20 74  ters.)^.** ^If t
2d9b0 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
2d9c0 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 62  ter to sqlite3_b
2d9d0 69 6e 64 5f 74 65 78 74 28 29 20 6f 72 20 73 71  ind_text() or sq
2d9e0 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31  lite3_bind_text1
2d9f0 36 28 29 0a 2a 2a 20 69 73 20 6e 65 67 61 74 69  6().** is negati
2da00 76 65 2c 20 74 68 65 6e 20 74 68 65 20 6c 65 6e  ve, then the len
2da10 67 74 68 20 6f 66 20 74 68 65 20 73 74 72 69 6e  gth of the strin
2da20 67 20 69 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62  g is.** the numb
2da30 65 72 20 6f 66 20 62 79 74 65 73 20 75 70 20 74  er of bytes up t
2da40 6f 20 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f  o the first zero
2da50 20 74 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 20   terminator..** 
2da60 49 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61  If the fourth pa
2da70 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
2da80 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 29 20 69  e3_bind_blob() i
2da90 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e  s negative, then
2daa0 0a 2a 2a 20 74 68 65 20 62 65 68 61 76 69 6f 72  .** the behavior
2dab0 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a   is undefined..*
2dac0 2a 20 49 66 20 61 20 6e 6f 6e 2d 6e 65 67 61 74  * If a non-negat
2dad0 69 76 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  ive fourth param
2dae0 65 74 65 72 20 69 73 20 70 72 6f 76 69 64 65 64  eter is provided
2daf0 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64   to sqlite3_bind
2db00 5f 74 65 78 74 28 29 0a 2a 2a 20 6f 72 20 73 71  _text().** or sq
2db10 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31  lite3_bind_text1
2db20 36 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 62  6() or sqlite3_b
2db30 69 6e 64 5f 74 65 78 74 36 34 28 29 20 74 68 65  ind_text64() the
2db40 6e 0a 2a 2a 20 74 68 61 74 20 70 61 72 61 6d 65  n.** that parame
2db50 74 65 72 20 6d 75 73 74 20 62 65 20 74 68 65 20  ter must be the 
2db60 62 79 74 65 20 6f 66 66 73 65 74 0a 2a 2a 20 77  byte offset.** w
2db70 68 65 72 65 20 74 68 65 20 4e 55 4c 20 74 65 72  here the NUL ter
2db80 6d 69 6e 61 74 6f 72 20 77 6f 75 6c 64 20 6f 63  minator would oc
2db90 63 75 72 20 61 73 73 75 6d 69 6e 67 20 74 68 65  cur assuming the
2dba0 20 73 74 72 69 6e 67 20 77 65 72 65 20 4e 55 4c   string were NUL
2dbb0 0a 2a 2a 20 74 65 72 6d 69 6e 61 74 65 64 2e 20  .** terminated. 
2dbc0 20 49 66 20 61 6e 79 20 4e 55 4c 20 63 68 61 72   If any NUL char
2dbd0 61 63 74 65 72 73 20 6f 63 63 75 72 20 61 74 20  acters occur at 
2dbe0 62 79 74 65 20 6f 66 66 73 65 74 73 20 6c 65 73  byte offsets les
2dbf0 73 20 74 68 61 6e 20 0a 2a 2a 20 74 68 65 20 76  s than .** the v
2dc00 61 6c 75 65 20 6f 66 20 74 68 65 20 66 6f 75 72  alue of the four
2dc10 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 68 65  th parameter the
2dc20 6e 20 74 68 65 20 72 65 73 75 6c 74 69 6e 67 20  n the resulting 
2dc30 73 74 72 69 6e 67 20 76 61 6c 75 65 20 77 69 6c  string value wil
2dc40 6c 0a 2a 2a 20 63 6f 6e 74 61 69 6e 20 65 6d 62  l.** contain emb
2dc50 65 64 64 65 64 20 4e 55 4c 73 2e 20 20 54 68 65  edded NULs.  The
2dc60 20 72 65 73 75 6c 74 20 6f 66 20 65 78 70 72 65   result of expre
2dc70 73 73 69 6f 6e 73 20 69 6e 76 6f 6c 76 69 6e 67  ssions involving
2dc80 20 73 74 72 69 6e 67 73 0a 2a 2a 20 77 69 74 68   strings.** with
2dc90 20 65 6d 62 65 64 64 65 64 20 4e 55 4c 73 20 69   embedded NULs i
2dca0 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a  s undefined..**.
2dcb0 2a 2a 20 5e 54 68 65 20 66 69 66 74 68 20 61 72  ** ^The fifth ar
2dcc0 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 42 4c  gument to the BL
2dcd0 4f 42 20 61 6e 64 20 73 74 72 69 6e 67 20 62 69  OB and string bi
2dce0 6e 64 69 6e 67 20 69 6e 74 65 72 66 61 63 65 73  nding interfaces
2dcf0 0a 2a 2a 20 69 73 20 61 20 64 65 73 74 72 75 63  .** is a destruc
2dd00 74 6f 72 20 75 73 65 64 20 74 6f 20 64 69 73 70  tor used to disp
2dd10 6f 73 65 20 6f 66 20 74 68 65 20 42 4c 4f 42 20  ose of the BLOB 
2dd20 6f 72 0a 2a 2a 20 73 74 72 69 6e 67 20 61 66 74  or.** string aft
2dd30 65 72 20 53 51 4c 69 74 65 20 68 61 73 20 66 69  er SQLite has fi
2dd40 6e 69 73 68 65 64 20 77 69 74 68 20 69 74 2e 20  nished with it. 
2dd50 20 5e 54 68 65 20 64 65 73 74 72 75 63 74 6f 72   ^The destructor
2dd60 20 69 73 20 63 61 6c 6c 65 64 0a 2a 2a 20 74 6f   is called.** to
2dd70 20 64 69 73 70 6f 73 65 20 6f 66 20 74 68 65 20   dispose of the 
2dd80 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 20 65  BLOB or string e
2dd90 76 65 6e 20 69 66 20 74 68 65 20 63 61 6c 6c 20  ven if the call 
2dda0 74 6f 20 62 69 6e 64 20 41 50 49 20 66 61 69 6c  to bind API fail
2ddb0 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69  s..** ^If the fi
2ddc0 66 74 68 20 61 72 67 75 6d 65 6e 74 20 69 73 0a  fth argument is.
2ddd0 2a 2a 20 74 68 65 20 73 70 65 63 69 61 6c 20 76  ** the special v
2dde0 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f 53 54 41  alue [SQLITE_STA
2ddf0 54 49 43 5d 2c 20 74 68 65 6e 20 53 51 4c 69 74  TIC], then SQLit
2de00 65 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 74  e assumes that t
2de10 68 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f  he.** informatio
2de20 6e 20 69 73 20 69 6e 20 73 74 61 74 69 63 2c 20  n is in static, 
2de30 75 6e 6d 61 6e 61 67 65 64 20 73 70 61 63 65 20  unmanaged space 
2de40 61 6e 64 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65  and does not nee
2de50 64 20 74 6f 20 62 65 20 66 72 65 65 64 2e 0a 2a  d to be freed..*
2de60 2a 20 5e 49 66 20 74 68 65 20 66 69 66 74 68 20  * ^If the fifth 
2de70 61 72 67 75 6d 65 6e 74 20 68 61 73 20 74 68 65  argument has the
2de80 20 76 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f 54   value [SQLITE_T
2de90 52 41 4e 53 49 45 4e 54 5d 2c 20 74 68 65 6e 0a  RANSIENT], then.
2dea0 2a 2a 20 53 51 4c 69 74 65 20 6d 61 6b 65 73 20  ** SQLite makes 
2deb0 69 74 73 20 6f 77 6e 20 70 72 69 76 61 74 65 20  its own private 
2dec0 63 6f 70 79 20 6f 66 20 74 68 65 20 64 61 74 61  copy of the data
2ded0 20 69 6d 6d 65 64 69 61 74 65 6c 79 2c 20 62 65   immediately, be
2dee0 66 6f 72 65 0a 2a 2a 20 74 68 65 20 73 71 6c 69  fore.** the sqli
2def0 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75  te3_bind_*() rou
2df00 74 69 6e 65 20 72 65 74 75 72 6e 73 2e 0a 2a 2a  tine returns..**
2df10 0a 2a 2a 20 5e 54 68 65 20 73 69 78 74 68 20 61  .** ^The sixth a
2df20 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74  rgument to sqlit
2df30 65 33 5f 62 69 6e 64 5f 74 65 78 74 36 34 28 29  e3_bind_text64()
2df40 20 6d 75 73 74 20 62 65 20 6f 6e 65 20 6f 66 0a   must be one of.
2df50 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d  ** [SQLITE_UTF8]
2df60 2c 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5d  , [SQLITE_UTF16]
2df70 2c 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 42  , [SQLITE_UTF16B
2df80 45 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55  E], or [SQLITE_U
2df90 54 46 31 36 4c 45 5d 0a 2a 2a 20 74 6f 20 73 70  TF16LE].** to sp
2dfa0 65 63 69 66 79 20 74 68 65 20 65 6e 63 6f 64 69  ecify the encodi
2dfb0 6e 67 20 6f 66 20 74 68 65 20 74 65 78 74 20 69  ng of the text i
2dfc0 6e 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61  n the third para
2dfd0 6d 65 74 65 72 2e 20 20 49 66 0a 2a 2a 20 74 68  meter.  If.** th
2dfe0 65 20 73 69 78 74 68 20 61 72 67 75 6d 65 6e 74  e sixth argument
2dff0 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64   to sqlite3_bind
2e000 5f 74 65 78 74 36 34 28 29 20 69 73 20 6e 6f 74  _text64() is not
2e010 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20 61   one of the.** a
2e020 6c 6c 6f 77 65 64 20 76 61 6c 75 65 73 20 73 68  llowed values sh
2e030 6f 77 6e 20 61 62 6f 76 65 2c 20 6f 72 20 69 66  own above, or if
2e040 20 74 68 65 20 74 65 78 74 20 65 6e 63 6f 64 69   the text encodi
2e050 6e 67 20 69 73 20 64 69 66 66 65 72 65 6e 74 0a  ng is different.
2e060 2a 2a 20 66 72 6f 6d 20 74 68 65 20 65 6e 63 6f  ** from the enco
2e070 64 69 6e 67 20 73 70 65 63 69 66 69 65 64 20 62  ding specified b
2e080 79 20 74 68 65 20 73 69 78 74 68 20 70 61 72 61  y the sixth para
2e090 6d 65 74 65 72 2c 20 74 68 65 6e 20 74 68 65 20  meter, then the 
2e0a0 62 65 68 61 76 69 6f 72 0a 2a 2a 20 69 73 20 75  behavior.** is u
2e0b0 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  ndefined..**.** 
2e0c0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e  ^The sqlite3_bin
2e0d0 64 5f 7a 65 72 6f 62 6c 6f 62 28 29 20 72 6f 75  d_zeroblob() rou
2e0e0 74 69 6e 65 20 62 69 6e 64 73 20 61 20 42 4c 4f  tine binds a BLO
2e0f0 42 20 6f 66 20 6c 65 6e 67 74 68 20 4e 20 74 68  B of length N th
2e100 61 74 0a 2a 2a 20 69 73 20 66 69 6c 6c 65 64 20  at.** is filled 
2e110 77 69 74 68 20 7a 65 72 6f 65 73 2e 20 20 5e 41  with zeroes.  ^A
2e120 20 7a 65 72 6f 62 6c 6f 62 20 75 73 65 73 20 61   zeroblob uses a
2e130 20 66 69 78 65 64 20 61 6d 6f 75 6e 74 20 6f 66   fixed amount of
2e140 20 6d 65 6d 6f 72 79 0a 2a 2a 20 28 6a 75 73 74   memory.** (just
2e150 20 61 6e 20 69 6e 74 65 67 65 72 20 74 6f 20 68   an integer to h
2e160 6f 6c 64 20 69 74 73 20 73 69 7a 65 29 20 77 68  old its size) wh
2e170 69 6c 65 20 69 74 20 69 73 20 62 65 69 6e 67 20  ile it is being 
2e180 70 72 6f 63 65 73 73 65 64 2e 0a 2a 2a 20 5a 65  processed..** Ze
2e190 72 6f 62 6c 6f 62 73 20 61 72 65 20 69 6e 74 65  roblobs are inte
2e1a0 6e 64 65 64 20 74 6f 20 73 65 72 76 65 20 61 73  nded to serve as
2e1b0 20 70 6c 61 63 65 68 6f 6c 64 65 72 73 20 66 6f   placeholders fo
2e1c0 72 20 42 4c 4f 42 73 20 77 68 6f 73 65 0a 2a 2a  r BLOBs whose.**
2e1d0 20 63 6f 6e 74 65 6e 74 20 69 73 20 6c 61 74 65   content is late
2e1e0 72 20 77 72 69 74 74 65 6e 20 75 73 69 6e 67 0a  r written using.
2e1f0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62  ** [sqlite3_blob
2e200 5f 6f 70 65 6e 20 7c 20 69 6e 63 72 65 6d 65 6e  _open | incremen
2e210 74 61 6c 20 42 4c 4f 42 20 49 2f 4f 5d 20 72 6f  tal BLOB I/O] ro
2e220 75 74 69 6e 65 73 2e 0a 2a 2a 20 5e 41 20 6e 65  utines..** ^A ne
2e230 67 61 74 69 76 65 20 76 61 6c 75 65 20 66 6f 72  gative value for
2e240 20 74 68 65 20 7a 65 72 6f 62 6c 6f 62 20 72 65   the zeroblob re
2e250 73 75 6c 74 73 20 69 6e 20 61 20 7a 65 72 6f 2d  sults in a zero-
2e260 6c 65 6e 67 74 68 20 42 4c 4f 42 2e 0a 2a 2a 0a  length BLOB..**.
2e270 2a 2a 20 5e 49 66 20 61 6e 79 20 6f 66 20 74 68  ** ^If any of th
2e280 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a  e sqlite3_bind_*
2e290 28 29 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20  () routines are 
2e2a0 63 61 6c 6c 65 64 20 77 69 74 68 20 61 20 4e 55  called with a NU
2e2b0 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 66 6f  LL pointer.** fo
2e2c0 72 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20  r the [prepared 
2e2d0 73 74 61 74 65 6d 65 6e 74 5d 20 6f 72 20 77 69  statement] or wi
2e2e0 74 68 20 61 20 70 72 65 70 61 72 65 64 20 73 74  th a prepared st
2e2f0 61 74 65 6d 65 6e 74 20 66 6f 72 20 77 68 69 63  atement for whic
2e300 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74  h.** [sqlite3_st
2e310 65 70 28 29 5d 20 68 61 73 20 62 65 65 6e 20 63  ep()] has been c
2e320 61 6c 6c 65 64 20 6d 6f 72 65 20 72 65 63 65 6e  alled more recen
2e330 74 6c 79 20 74 68 61 6e 20 5b 73 71 6c 69 74 65  tly than [sqlite
2e340 33 5f 72 65 73 65 74 28 29 5d 2c 0a 2a 2a 20 74  3_reset()],.** t
2e350 68 65 6e 20 74 68 65 20 63 61 6c 6c 20 77 69 6c  hen the call wil
2e360 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  l return [SQLITE
2e370 5f 4d 49 53 55 53 45 5d 2e 20 20 49 66 20 61 6e  _MISUSE].  If an
2e380 79 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 28  y sqlite3_bind_(
2e390 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 69 73 20  ).** routine is 
2e3a0 70 61 73 73 65 64 20 61 20 5b 70 72 65 70 61 72  passed a [prepar
2e3b0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68  ed statement] th
2e3c0 61 74 20 68 61 73 20 62 65 65 6e 20 66 69 6e 61  at has been fina
2e3d0 6c 69 7a 65 64 2c 20 74 68 65 0a 2a 2a 20 72 65  lized, the.** re
2e3e0 73 75 6c 74 20 69 73 20 75 6e 64 65 66 69 6e 65  sult is undefine
2e3f0 64 20 61 6e 64 20 70 72 6f 62 61 62 6c 79 20 68  d and probably h
2e400 61 72 6d 66 75 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 42  armful..**.** ^B
2e410 69 6e 64 69 6e 67 73 20 61 72 65 20 6e 6f 74 20  indings are not 
2e420 63 6c 65 61 72 65 64 20 62 79 20 74 68 65 20 5b  cleared by the [
2e430 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
2e440 20 72 6f 75 74 69 6e 65 2e 0a 2a 2a 20 5e 55 6e   routine..** ^Un
2e450 62 6f 75 6e 64 20 70 61 72 61 6d 65 74 65 72 73  bound parameters
2e460 20 61 72 65 20 69 6e 74 65 72 70 72 65 74 65 64   are interpreted
2e470 20 61 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20   as NULL..**.** 
2e480 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e  ^The sqlite3_bin
2e490 64 5f 2a 20 72 6f 75 74 69 6e 65 73 20 72 65 74  d_* routines ret
2e4a0 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20  urn [SQLITE_OK] 
2e4b0 6f 6e 20 73 75 63 63 65 73 73 20 6f 72 20 61 6e  on success or an
2e4c0 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d  .** [error code]
2e4d0 20 69 66 20 61 6e 79 74 68 69 6e 67 20 67 6f 65   if anything goe
2e4e0 73 20 77 72 6f 6e 67 2e 0a 2a 2a 20 5e 5b 53 51  s wrong..** ^[SQ
2e4f0 4c 49 54 45 5f 54 4f 4f 42 49 47 5d 20 6d 69 67  LITE_TOOBIG] mig
2e500 68 74 20 62 65 20 72 65 74 75 72 6e 65 64 20 69  ht be returned i
2e510 66 20 74 68 65 20 73 69 7a 65 20 6f 66 20 61 20  f the size of a 
2e520 73 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42 0a 2a  string or BLOB.*
2e530 2a 20 65 78 63 65 65 64 73 20 6c 69 6d 69 74 73  * exceeds limits
2e540 20 69 6d 70 6f 73 65 64 20 62 79 20 5b 73 71 6c   imposed by [sql
2e550 69 74 65 33 5f 6c 69 6d 69 74 5d 28 5b 53 51 4c  ite3_limit]([SQL
2e560 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48  ITE_LIMIT_LENGTH
2e570 5d 29 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45  ]) or.** [SQLITE
2e580 5f 4d 41 58 5f 4c 45 4e 47 54 48 5d 2e 0a 2a 2a  _MAX_LENGTH]..**
2e590 20 5e 5b 53 51 4c 49 54 45 5f 52 41 4e 47 45 5d   ^[SQLITE_RANGE]
2e5a0 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 66 20   is returned if 
2e5b0 74 68 65 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a  the parameter.**
2e5c0 20 69 6e 64 65 78 20 69 73 20 6f 75 74 20 6f 66   index is out of
2e5d0 20 72 61 6e 67 65 2e 20 20 5e 5b 53 51 4c 49 54   range.  ^[SQLIT
2e5e0 45 5f 4e 4f 4d 45 4d 5d 20 69 73 20 72 65 74 75  E_NOMEM] is retu
2e5f0 72 6e 65 64 20 69 66 20 6d 61 6c 6c 6f 63 28 29  rned if malloc()
2e600 20 66 61 69 6c 73 2e 0a 2a 2a 0a 2a 2a 20 53 65   fails..**.** Se
2e610 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33  e also: [sqlite3
2e620 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
2e630 63 6f 75 6e 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71  count()],.** [sq
2e640 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
2e650 65 74 65 72 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e  eter_name()], an
2e660 64 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  d [sqlite3_bind_
2e670 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28  parameter_index(
2e680 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  )]..*/.SQLITE_AP
2e690 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  I int sqlite3_bi
2e6a0 6e 64 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f  nd_blob(sqlite3_
2e6b0 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73  stmt*, int, cons
2e6c0 74 20 76 6f 69 64 2a 2c 20 69 6e 74 20 6e 2c 20  t void*, int n, 
2e6d0 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b  void(*)(void*));
2e6e0 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
2e6f0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
2e700 62 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  b64(sqlite3_stmt
2e710 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f  *, int, const vo
2e720 69 64 2a 2c 20 73 71 6c 69 74 65 33 5f 75 69 6e  id*, sqlite3_uin
2e730 74 36 34 2c 0a 20 20 20 20 20 20 20 20 20 20 20  t64,.           
2e740 20 20 20 20 20 20 20 20 20 20 20 20 20 76 6f 69               voi
2e750 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 53 51  d(*)(void*));.SQ
2e760 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
2e770 69 74 65 33 5f 62 69 6e 64 5f 64 6f 75 62 6c 65  ite3_bind_double
2e780 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
2e790 69 6e 74 2c 20 64 6f 75 62 6c 65 29 3b 0a 53 51  int, double);.SQ
2e7a0 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
2e7b0 69 74 65 33 5f 62 69 6e 64 5f 69 6e 74 28 73 71  ite3_bind_int(sq
2e7c0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
2e7d0 2c 20 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41  , int);.SQLITE_A
2e7e0 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  PI int sqlite3_b
2e7f0 69 6e 64 5f 69 6e 74 36 34 28 73 71 6c 69 74 65  ind_int64(sqlite
2e800 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 73 71  3_stmt*, int, sq
2e810 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 53 51  lite3_int64);.SQ
2e820 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
2e830 69 74 65 33 5f 62 69 6e 64 5f 6e 75 6c 6c 28 73  ite3_bind_null(s
2e840 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
2e850 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  t);.SQLITE_API i
2e860 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
2e870 74 65 78 74 28 73 71 6c 69 74 65 33 5f 73 74 6d  text(sqlite3_stm
2e880 74 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61  t*,int,const cha
2e890 72 2a 2c 69 6e 74 2c 76 6f 69 64 28 2a 29 28 76  r*,int,void(*)(v
2e8a0 6f 69 64 2a 29 29 3b 0a 53 51 4c 49 54 45 5f 41  oid*));.SQLITE_A
2e8b0 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  PI int sqlite3_b
2e8c0 69 6e 64 5f 74 65 78 74 31 36 28 73 71 6c 69 74  ind_text16(sqlit
2e8d0 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63  e3_stmt*, int, c
2e8e0 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c  onst void*, int,
2e8f0 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29   void(*)(void*))
2e900 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  ;.SQLITE_API int
2e910 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65   sqlite3_bind_te
2e920 78 74 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d  xt64(sqlite3_stm
2e930 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 63  t*, int, const c
2e940 68 61 72 2a 2c 20 73 71 6c 69 74 65 33 5f 75 69  har*, sqlite3_ui
2e950 6e 74 36 34 2c 0a 20 20 20 20 20 20 20 20 20 20  nt64,.          
2e960 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 76                 v
2e970 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 2c 20 75  oid(*)(void*), u
2e980 6e 73 69 67 6e 65 64 20 63 68 61 72 20 65 6e 63  nsigned char enc
2e990 6f 64 69 6e 67 29 3b 0a 53 51 4c 49 54 45 5f 41  oding);.SQLITE_A
2e9a0 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  PI int sqlite3_b
2e9b0 69 6e 64 5f 76 61 6c 75 65 28 73 71 6c 69 74 65  ind_value(sqlite
2e9c0 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f  3_stmt*, int, co
2e9d0 6e 73 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  nst sqlite3_valu
2e9e0 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  e*);.SQLITE_API 
2e9f0 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
2ea00 5f 7a 65 72 6f 62 6c 6f 62 28 73 71 6c 69 74 65  _zeroblob(sqlite
2ea10 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e  3_stmt*, int, in
2ea20 74 20 6e 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  t n);.SQLITE_API
2ea30 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e   int sqlite3_bin
2ea40 64 5f 7a 65 72 6f 62 6c 6f 62 36 34 28 73 71 6c  d_zeroblob64(sql
2ea50 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c  ite3_stmt*, int,
2ea60 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 29   sqlite3_uint64)
2ea70 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2ea80 46 3a 20 4e 75 6d 62 65 72 20 4f 66 20 53 51 4c  F: Number Of SQL
2ea90 20 50 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 4d   Parameters.** M
2eaa0 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73  ETHOD: sqlite3_s
2eab0 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20  tmt.**.** ^This 
2eac0 72 6f 75 74 69 6e 65 20 63 61 6e 20 62 65 20 75  routine can be u
2ead0 73 65 64 20 74 6f 20 66 69 6e 64 20 74 68 65 20  sed to find the 
2eae0 6e 75 6d 62 65 72 20 6f 66 20 5b 53 51 4c 20 70  number of [SQL p
2eaf0 61 72 61 6d 65 74 65 72 73 5d 0a 2a 2a 20 69 6e  arameters].** in
2eb00 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
2eb10 74 65 6d 65 6e 74 5d 2e 20 20 53 51 4c 20 70 61  tement].  SQL pa
2eb20 72 61 6d 65 74 65 72 73 20 61 72 65 20 74 6f 6b  rameters are tok
2eb30 65 6e 73 20 6f 66 20 74 68 65 0a 2a 2a 20 66 6f  ens of the.** fo
2eb40 72 6d 20 22 3f 22 2c 20 22 3f 4e 4e 4e 22 2c 20  rm "?", "?NNN", 
2eb50 22 3a 41 41 41 22 2c 20 22 24 41 41 41 22 2c 20  ":AAA", "$AAA", 
2eb60 6f 72 20 22 40 41 41 41 22 20 74 68 61 74 20 73  or "@AAA" that s
2eb70 65 72 76 65 20 61 73 0a 2a 2a 20 70 6c 61 63 65  erve as.** place
2eb80 68 6f 6c 64 65 72 73 20 66 6f 72 20 76 61 6c 75  holders for valu
2eb90 65 73 20 74 68 61 74 20 61 72 65 20 5b 73 71 6c  es that are [sql
2eba0 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c  ite3_bind_blob |
2ebb0 20 62 6f 75 6e 64 5d 0a 2a 2a 20 74 6f 20 74 68   bound].** to th
2ebc0 65 20 70 61 72 61 6d 65 74 65 72 73 20 61 74 20  e parameters at 
2ebd0 61 20 6c 61 74 65 72 20 74 69 6d 65 2e 0a 2a 2a  a later time..**
2ebe0 0a 2a 2a 20 5e 28 54 68 69 73 20 72 6f 75 74 69  .** ^(This routi
2ebf0 6e 65 20 61 63 74 75 61 6c 6c 79 20 72 65 74 75  ne actually retu
2ec00 72 6e 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66  rns the index of
2ec10 20 74 68 65 20 6c 61 72 67 65 73 74 20 28 72 69   the largest (ri
2ec20 67 68 74 6d 6f 73 74 29 0a 2a 2a 20 70 61 72 61  ghtmost).** para
2ec30 6d 65 74 65 72 2e 20 46 6f 72 20 61 6c 6c 20 66  meter. For all f
2ec40 6f 72 6d 73 20 65 78 63 65 70 74 20 3f 4e 4e 4e  orms except ?NNN
2ec50 2c 20 74 68 69 73 20 77 69 6c 6c 20 63 6f 72 72  , this will corr
2ec60 65 73 70 6f 6e 64 20 74 6f 20 74 68 65 0a 2a 2a  espond to the.**
2ec70 20 6e 75 6d 62 65 72 20 6f 66 20 75 6e 69 71 75   number of uniqu
2ec80 65 20 70 61 72 61 6d 65 74 65 72 73 2e 20 20 49  e parameters.  I
2ec90 66 20 70 61 72 61 6d 65 74 65 72 73 20 6f 66 20  f parameters of 
2eca0 74 68 65 20 3f 4e 4e 4e 20 66 6f 72 6d 20 61 72  the ?NNN form ar
2ecb0 65 20 75 73 65 64 2c 0a 2a 2a 20 74 68 65 72 65  e used,.** there
2ecc0 20 6d 61 79 20 62 65 20 67 61 70 73 20 69 6e 20   may be gaps in 
2ecd0 74 68 65 20 6c 69 73 74 2e 29 5e 0a 2a 2a 0a 2a  the list.)^.**.*
2ece0 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c  * See also: [sql
2ecf0 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73  ite3_bind_blob|s
2ed00 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a  qlite3_bind()],.
2ed10 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  ** [sqlite3_bind
2ed20 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28  _parameter_name(
2ed30 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69  )], and.** [sqli
2ed40 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
2ed50 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a  er_index()]..*/.
2ed60 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
2ed70 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
2ed80 6d 65 74 65 72 5f 63 6f 75 6e 74 28 73 71 6c 69  meter_count(sqli
2ed90 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a  te3_stmt*);../*.
2eda0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 61 6d  ** CAPI3REF: Nam
2edb0 65 20 4f 66 20 41 20 48 6f 73 74 20 50 61 72 61  e Of A Host Para
2edc0 6d 65 74 65 72 0a 2a 2a 20 4d 45 54 48 4f 44 3a  meter.** METHOD:
2edd0 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a   sqlite3_stmt.**
2ede0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
2edf0 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
2ee00 6e 61 6d 65 28 50 2c 4e 29 20 69 6e 74 65 72 66  name(P,N) interf
2ee10 61 63 65 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74  ace returns.** t
2ee20 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 4e  he name of the N
2ee30 2d 74 68 20 5b 53 51 4c 20 70 61 72 61 6d 65 74  -th [SQL paramet
2ee40 65 72 5d 20 69 6e 20 74 68 65 20 5b 70 72 65 70  er] in the [prep
2ee50 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
2ee60 50 2e 0a 2a 2a 20 5e 28 53 51 4c 20 70 61 72 61  P..** ^(SQL para
2ee70 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20 66 6f  meters of the fo
2ee80 72 6d 20 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41  rm "?NNN" or ":A
2ee90 41 41 22 20 6f 72 20 22 40 41 41 41 22 20 6f 72  AA" or "@AAA" or
2eea0 20 22 24 41 41 41 22 0a 2a 2a 20 68 61 76 65 20   "$AAA".** have 
2eeb0 61 20 6e 61 6d 65 20 77 68 69 63 68 20 69 73 20  a name which is 
2eec0 74 68 65 20 73 74 72 69 6e 67 20 22 3f 4e 4e 4e  the string "?NNN
2eed0 22 20 6f 72 20 22 3a 41 41 41 22 20 6f 72 20 22  " or ":AAA" or "
2eee0 40 41 41 41 22 20 6f 72 20 22 24 41 41 41 22 0a  @AAA" or "$AAA".
2eef0 2a 2a 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e  ** respectively.
2ef00 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 20 77 6f 72  .** In other wor
2ef10 64 73 2c 20 74 68 65 20 69 6e 69 74 69 61 6c 20  ds, the initial 
2ef20 22 3a 22 20 6f 72 20 22 24 22 20 6f 72 20 22 40  ":" or "$" or "@
2ef30 22 20 6f 72 20 22 3f 22 0a 2a 2a 20 69 73 20 69  " or "?".** is i
2ef40 6e 63 6c 75 64 65 64 20 61 73 20 70 61 72 74 20  ncluded as part 
2ef50 6f 66 20 74 68 65 20 6e 61 6d 65 2e 29 5e 0a 2a  of the name.)^.*
2ef60 2a 20 5e 50 61 72 61 6d 65 74 65 72 73 20 6f 66  * ^Parameters of
2ef70 20 74 68 65 20 66 6f 72 6d 20 22 3f 22 20 77 69   the form "?" wi
2ef80 74 68 6f 75 74 20 61 20 66 6f 6c 6c 6f 77 69 6e  thout a followin
2ef90 67 20 69 6e 74 65 67 65 72 20 68 61 76 65 20 6e  g integer have n
2efa0 6f 20 6e 61 6d 65 0a 2a 2a 20 61 6e 64 20 61 72  o name.** and ar
2efb0 65 20 72 65 66 65 72 72 65 64 20 74 6f 20 61 73  e referred to as
2efc0 20 22 6e 61 6d 65 6c 65 73 73 22 20 6f 72 20 22   "nameless" or "
2efd0 61 6e 6f 6e 79 6d 6f 75 73 20 70 61 72 61 6d 65  anonymous parame
2efe0 74 65 72 73 22 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ters"..**.** ^Th
2eff0 65 20 66 69 72 73 74 20 68 6f 73 74 20 70 61 72  e first host par
2f000 61 6d 65 74 65 72 20 68 61 73 20 61 6e 20 69 6e  ameter has an in
2f010 64 65 78 20 6f 66 20 31 2c 20 6e 6f 74 20 30 2e  dex of 1, not 0.
2f020 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 76  .**.** ^If the v
2f030 61 6c 75 65 20 4e 20 69 73 20 6f 75 74 20 6f 66  alue N is out of
2f040 20 72 61 6e 67 65 20 6f 72 20 69 66 20 74 68 65   range or if the
2f050 20 4e 2d 74 68 20 70 61 72 61 6d 65 74 65 72 20   N-th parameter 
2f060 69 73 0a 2a 2a 20 6e 61 6d 65 6c 65 73 73 2c 20  is.** nameless, 
2f070 74 68 65 6e 20 4e 55 4c 4c 20 69 73 20 72 65 74  then NULL is ret
2f080 75 72 6e 65 64 2e 20 20 5e 54 68 65 20 72 65 74  urned.  ^The ret
2f090 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73 0a  urned string is.
2f0a0 2a 2a 20 61 6c 77 61 79 73 20 69 6e 20 55 54 46  ** always in UTF
2f0b0 2d 38 20 65 6e 63 6f 64 69 6e 67 20 65 76 65 6e  -8 encoding even
2f0c0 20 69 66 20 74 68 65 20 6e 61 6d 65 64 20 70 61   if the named pa
2f0d0 72 61 6d 65 74 65 72 20 77 61 73 0a 2a 2a 20 6f  rameter was.** o
2f0e0 72 69 67 69 6e 61 6c 6c 79 20 73 70 65 63 69 66  riginally specif
2f0f0 69 65 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e  ied as UTF-16 in
2f100 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
2f110 65 31 36 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71  e16()] or.** [sq
2f120 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
2f130 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65  v2()]..**.** See
2f140 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f   also: [sqlite3_
2f150 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65  bind_blob|sqlite
2f160 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73  3_bind()],.** [s
2f170 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
2f180 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 20  meter_count()], 
2f190 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  and.** [sqlite3_
2f1a0 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69  bind_parameter_i
2f1b0 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49  ndex()]..*/.SQLI
2f1c0 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61  TE_API const cha
2f1d0 72 20 2a 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  r *sqlite3_bind_
2f1e0 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 73  parameter_name(s
2f1f0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
2f200 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
2f210 52 45 46 3a 20 49 6e 64 65 78 20 4f 66 20 41 20  REF: Index Of A 
2f220 50 61 72 61 6d 65 74 65 72 20 57 69 74 68 20 41  Parameter With A
2f230 20 47 69 76 65 6e 20 4e 61 6d 65 0a 2a 2a 20 4d   Given Name.** M
2f240 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73  ETHOD: sqlite3_s
2f250 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 52 65 74 75 72  tmt.**.** ^Retur
2f260 6e 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 61  n the index of a
2f270 6e 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20  n SQL parameter 
2f280 67 69 76 65 6e 20 69 74 73 20 6e 61 6d 65 2e 20  given its name. 
2f290 20 5e 54 68 65 0a 2a 2a 20 69 6e 64 65 78 20 76   ^The.** index v
2f2a0 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 69 73  alue returned is
2f2b0 20 73 75 69 74 61 62 6c 65 20 66 6f 72 20 75 73   suitable for us
2f2c0 65 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 0a  e as the second.
2f2d0 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  ** parameter to 
2f2e0 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c  [sqlite3_bind_bl
2f2f0 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28  ob|sqlite3_bind(
2f300 29 5d 2e 20 20 5e 41 20 7a 65 72 6f 0a 2a 2a 20  )].  ^A zero.** 
2f310 69 73 20 72 65 74 75 72 6e 65 64 20 69 66 20 6e  is returned if n
2f320 6f 20 6d 61 74 63 68 69 6e 67 20 70 61 72 61 6d  o matching param
2f330 65 74 65 72 20 69 73 20 66 6f 75 6e 64 2e 20 20  eter is found.  
2f340 5e 54 68 65 20 70 61 72 61 6d 65 74 65 72 0a 2a  ^The parameter.*
2f350 2a 20 6e 61 6d 65 20 6d 75 73 74 20 62 65 20 67  * name must be g
2f360 69 76 65 6e 20 69 6e 20 55 54 46 2d 38 20 65 76  iven in UTF-8 ev
2f370 65 6e 20 69 66 20 74 68 65 20 6f 72 69 67 69 6e  en if the origin
2f380 61 6c 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20  al statement.** 
2f390 77 61 73 20 70 72 65 70 61 72 65 64 20 66 72 6f  was prepared fro
2f3a0 6d 20 55 54 46 2d 31 36 20 74 65 78 74 20 75 73  m UTF-16 text us
2f3b0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  ing [sqlite3_pre
2f3c0 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a  pare16_v2()]..**
2f3d0 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73  .** See also: [s
2f3e0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
2f3f0 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d  |sqlite3_bind()]
2f400 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69  ,.** [sqlite3_bi
2f410 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75  nd_parameter_cou
2f420 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73  nt()], and.** [s
2f430 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
2f440 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d 2e 0a 2a  meter_name()]..*
2f450 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  /.SQLITE_API int
2f460 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61   sqlite3_bind_pa
2f470 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 73 71  rameter_index(sq
2f480 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 63 6f 6e  lite3_stmt*, con
2f490 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b  st char *zName);
2f4a0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2f4b0 3a 20 52 65 73 65 74 20 41 6c 6c 20 42 69 6e 64  : Reset All Bind
2f4c0 69 6e 67 73 20 4f 6e 20 41 20 50 72 65 70 61 72  ings On A Prepar
2f4d0 65 64 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 20  ed Statement.** 
2f4e0 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f  METHOD: sqlite3_
2f4f0 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e 74  stmt.**.** ^Cont
2f500 72 61 72 79 20 74 6f 20 74 68 65 20 69 6e 74 75  rary to the intu
2f510 69 74 69 6f 6e 20 6f 66 20 6d 61 6e 79 2c 20 5b  ition of many, [
2f520 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
2f530 20 64 6f 65 73 20 6e 6f 74 20 72 65 73 65 74 0a   does not reset.
2f540 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  ** the [sqlite3_
2f550 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 62 69 6e 64  bind_blob | bind
2f560 69 6e 67 73 5d 20 6f 6e 20 61 20 5b 70 72 65 70  ings] on a [prep
2f570 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e  ared statement].
2f580 0a 2a 2a 20 5e 55 73 65 20 74 68 69 73 20 72 6f  .** ^Use this ro
2f590 75 74 69 6e 65 20 74 6f 20 72 65 73 65 74 20 61  utine to reset a
2f5a0 6c 6c 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65  ll host paramete
2f5b0 72 73 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2f 0a 53  rs to NULL..*/.S
2f5c0 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
2f5d0 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64  lite3_clear_bind
2f5e0 69 6e 67 73 28 73 71 6c 69 74 65 33 5f 73 74 6d  ings(sqlite3_stm
2f5f0 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  t*);../*.** CAPI
2f600 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 4f 66 20  3REF: Number Of 
2f610 43 6f 6c 75 6d 6e 73 20 49 6e 20 41 20 52 65 73  Columns In A Res
2f620 75 6c 74 20 53 65 74 0a 2a 2a 20 4d 45 54 48 4f  ult Set.** METHO
2f630 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a  D: sqlite3_stmt.
2f640 2a 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e 20 74 68  **.** ^Return th
2f650 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75  e number of colu
2f660 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 73 75 6c  mns in the resul
2f670 74 20 73 65 74 20 72 65 74 75 72 6e 65 64 20 62  t set returned b
2f680 79 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72  y the.** [prepar
2f690 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 5e  ed statement]. ^
2f6a0 49 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  If this routine 
2f6b0 72 65 74 75 72 6e 73 20 30 2c 20 74 68 61 74 20  returns 0, that 
2f6c0 6d 65 61 6e 73 20 74 68 65 20 0a 2a 2a 20 5b 70  means the .** [p
2f6d0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2f6e0 74 5d 20 72 65 74 75 72 6e 73 20 6e 6f 20 64 61  t] returns no da
2f6f0 74 61 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20  ta (for example 
2f700 61 6e 20 5b 55 50 44 41 54 45 5d 29 2e 0a 2a 2a  an [UPDATE])..**
2f710 20 5e 48 6f 77 65 76 65 72 2c 20 6a 75 73 74 20   ^However, just 
2f720 62 65 63 61 75 73 65 20 74 68 69 73 20 72 6f 75  because this rou
2f730 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20 70  tine returns a p
2f740 6f 73 69 74 69 76 65 20 6e 75 6d 62 65 72 20 64  ositive number d
2f750 6f 65 73 20 6e 6f 74 0a 2a 2a 20 6d 65 61 6e 20  oes not.** mean 
2f760 74 68 61 74 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  that one or more
2f770 20 72 6f 77 73 20 6f 66 20 64 61 74 61 20 77 69   rows of data wi
2f780 6c 6c 20 62 65 20 72 65 74 75 72 6e 65 64 2e 20  ll be returned. 
2f790 20 5e 41 20 53 45 4c 45 43 54 20 73 74 61 74 65   ^A SELECT state
2f7a0 6d 65 6e 74 0a 2a 2a 20 77 69 6c 6c 20 61 6c 77  ment.** will alw
2f7b0 61 79 73 20 68 61 76 65 20 61 20 70 6f 73 69 74  ays have a posit
2f7c0 69 76 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ive sqlite3_colu
2f7d0 6d 6e 5f 63 6f 75 6e 74 28 29 20 62 75 74 20 64  mn_count() but d
2f7e0 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 0a  epending on the.
2f7f0 2a 2a 20 57 48 45 52 45 20 63 6c 61 75 73 65 20  ** WHERE clause 
2f800 63 6f 6e 73 74 72 61 69 6e 74 73 20 61 6e 64 20  constraints and 
2f810 74 68 65 20 74 61 62 6c 65 20 63 6f 6e 74 65 6e  the table conten
2f820 74 2c 20 69 74 20 6d 69 67 68 74 20 72 65 74 75  t, it might retu
2f830 72 6e 20 6e 6f 20 72 6f 77 73 2e 0a 2a 2a 0a 2a  rn no rows..**.*
2f840 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c  * See also: [sql
2f850 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28  ite3_data_count(
2f860 29 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  )].*/.SQLITE_API
2f870 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c   int sqlite3_col
2f880 75 6d 6e 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65  umn_count(sqlite
2f890 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a  3_stmt *pStmt);.
2f8a0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2f8b0 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 73 20 49 6e   Column Names In
2f8c0 20 41 20 52 65 73 75 6c 74 20 53 65 74 0a 2a 2a   A Result Set.**
2f8d0 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
2f8e0 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  _stmt.**.** ^The
2f8f0 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  se routines retu
2f900 72 6e 20 74 68 65 20 6e 61 6d 65 20 61 73 73 69  rn the name assi
2f910 67 6e 65 64 20 74 6f 20 61 20 70 61 72 74 69 63  gned to a partic
2f920 75 6c 61 72 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69  ular column.** i
2f930 6e 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74  n the result set
2f940 20 6f 66 20 61 20 5b 53 45 4c 45 43 54 5d 20 73   of a [SELECT] s
2f950 74 61 74 65 6d 65 6e 74 2e 20 20 5e 54 68 65 20  tatement.  ^The 
2f960 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e  sqlite3_column_n
2f970 61 6d 65 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61  ame().** interfa
2f980 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  ce returns a poi
2f990 6e 74 65 72 20 74 6f 20 61 20 7a 65 72 6f 2d 74  nter to a zero-t
2f9a0 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20  erminated UTF-8 
2f9b0 73 74 72 69 6e 67 0a 2a 2a 20 61 6e 64 20 73 71  string.** and sq
2f9c0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d  lite3_column_nam
2f9d0 65 31 36 28 29 20 72 65 74 75 72 6e 73 20 61 20  e16() returns a 
2f9e0 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 7a 65 72  pointer to a zer
2f9f0 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20  o-terminated.** 
2fa00 55 54 46 2d 31 36 20 73 74 72 69 6e 67 2e 20 20  UTF-16 string.  
2fa10 5e 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d  ^The first param
2fa20 65 74 65 72 20 69 73 20 74 68 65 20 5b 70 72 65  eter is the [pre
2fa30 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2fa40 0a 2a 2a 20 74 68 61 74 20 69 6d 70 6c 65 6d 65  .** that impleme
2fa50 6e 74 73 20 74 68 65 20 5b 53 45 4c 45 43 54 5d  nts the [SELECT]
2fa60 20 73 74 61 74 65 6d 65 6e 74 2e 20 5e 54 68 65   statement. ^The
2fa70 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
2fa80 72 20 69 73 20 74 68 65 0a 2a 2a 20 63 6f 6c 75  r is the.** colu
2fa90 6d 6e 20 6e 75 6d 62 65 72 2e 20 20 5e 54 68 65  mn number.  ^The
2faa0 20 6c 65 66 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e   leftmost column
2fab0 20 69 73 20 6e 75 6d 62 65 72 20 30 2e 0a 2a 2a   is number 0..**
2fac0 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75 72 6e 65  .** ^The returne
2fad0 64 20 73 74 72 69 6e 67 20 70 6f 69 6e 74 65 72  d string pointer
2fae0 20 69 73 20 76 61 6c 69 64 20 75 6e 74 69 6c 20   is valid until 
2faf0 65 69 74 68 65 72 20 74 68 65 20 5b 70 72 65 70  either the [prep
2fb00 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a  ared statement].
2fb10 2a 2a 20 69 73 20 64 65 73 74 72 6f 79 65 64 20  ** is destroyed 
2fb20 62 79 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  by [sqlite3_fina
2fb30 6c 69 7a 65 28 29 5d 20 6f 72 20 75 6e 74 69 6c  lize()] or until
2fb40 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69   the statement i
2fb50 73 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a  s automatically.
2fb60 2a 2a 20 72 65 70 72 65 70 61 72 65 64 20 62 79  ** reprepared by
2fb70 20 74 68 65 20 66 69 72 73 74 20 63 61 6c 6c 20   the first call 
2fb80 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  to [sqlite3_step
2fb90 28 29 5d 20 66 6f 72 20 61 20 70 61 72 74 69 63  ()] for a partic
2fba0 75 6c 61 72 20 72 75 6e 0a 2a 2a 20 6f 72 20 75  ular run.** or u
2fbb0 6e 74 69 6c 20 74 68 65 20 6e 65 78 74 20 63 61  ntil the next ca
2fbc0 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33  ll to.** sqlite3
2fbd0 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 20 6f  _column_name() o
2fbe0 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  r sqlite3_column
2fbf0 5f 6e 61 6d 65 31 36 28 29 20 6f 6e 20 74 68 65  _name16() on the
2fc00 20 73 61 6d 65 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a   same column..**
2fc10 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f  .** ^If sqlite3_
2fc20 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 73 20 64  malloc() fails d
2fc30 75 72 69 6e 67 20 74 68 65 20 70 72 6f 63 65 73  uring the proces
2fc40 73 69 6e 67 20 6f 66 20 65 69 74 68 65 72 20 72  sing of either r
2fc50 6f 75 74 69 6e 65 0a 2a 2a 20 28 66 6f 72 20 65  outine.** (for e
2fc60 78 61 6d 70 6c 65 20 64 75 72 69 6e 67 20 61 20  xample during a 
2fc70 63 6f 6e 76 65 72 73 69 6f 6e 20 66 72 6f 6d 20  conversion from 
2fc80 55 54 46 2d 38 20 74 6f 20 55 54 46 2d 31 36 29  UTF-8 to UTF-16)
2fc90 20 74 68 65 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20   then a.** NULL 
2fca0 70 6f 69 6e 74 65 72 20 69 73 20 72 65 74 75 72  pointer is retur
2fcb0 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ned..**.** ^The 
2fcc0 6e 61 6d 65 20 6f 66 20 61 20 72 65 73 75 6c 74  name of a result
2fcd0 20 63 6f 6c 75 6d 6e 20 69 73 20 74 68 65 20 76   column is the v
2fce0 61 6c 75 65 20 6f 66 20 74 68 65 20 22 41 53 22  alue of the "AS"
2fcf0 20 63 6c 61 75 73 65 20 66 6f 72 0a 2a 2a 20 74   clause for.** t
2fd00 68 61 74 20 63 6f 6c 75 6d 6e 2c 20 69 66 20 74  hat column, if t
2fd10 68 65 72 65 20 69 73 20 61 6e 20 41 53 20 63 6c  here is an AS cl
2fd20 61 75 73 65 2e 20 20 49 66 20 74 68 65 72 65 20  ause.  If there 
2fd30 69 73 20 6e 6f 20 41 53 20 63 6c 61 75 73 65 0a  is no AS clause.
2fd40 2a 2a 20 74 68 65 6e 20 74 68 65 20 6e 61 6d 65  ** then the name
2fd50 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20 69   of the column i
2fd60 73 20 75 6e 73 70 65 63 69 66 69 65 64 20 61 6e  s unspecified an
2fd70 64 20 6d 61 79 20 63 68 61 6e 67 65 20 66 72 6f  d may change fro
2fd80 6d 0a 2a 2a 20 6f 6e 65 20 72 65 6c 65 61 73 65  m.** one release
2fd90 20 6f 66 20 53 51 4c 69 74 65 20 74 6f 20 74 68   of SQLite to th
2fda0 65 20 6e 65 78 74 2e 0a 2a 2f 0a 53 51 4c 49 54  e next..*/.SQLIT
2fdb0 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72  E_API const char
2fdc0 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
2fdd0 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74  _name(sqlite3_st
2fde0 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 53 51 4c  mt*, int N);.SQL
2fdf0 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f  ITE_API const vo
2fe00 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  id *sqlite3_colu
2fe10 6d 6e 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65  mn_name16(sqlite
2fe20 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b  3_stmt*, int N);
2fe30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2fe40 3a 20 53 6f 75 72 63 65 20 4f 66 20 44 61 74 61  : Source Of Data
2fe50 20 49 6e 20 41 20 51 75 65 72 79 20 52 65 73 75   In A Query Resu
2fe60 6c 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  lt.** METHOD: sq
2fe70 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a  lite3_stmt.**.**
2fe80 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73   ^These routines
2fe90 20 70 72 6f 76 69 64 65 20 61 20 6d 65 61 6e 73   provide a means
2fea0 20 74 6f 20 64 65 74 65 72 6d 69 6e 65 20 74 68   to determine th
2feb0 65 20 64 61 74 61 62 61 73 65 2c 20 74 61 62 6c  e database, tabl
2fec0 65 2c 20 61 6e 64 0a 2a 2a 20 74 61 62 6c 65 20  e, and.** table 
2fed0 63 6f 6c 75 6d 6e 20 74 68 61 74 20 69 73 20 74  column that is t
2fee0 68 65 20 6f 72 69 67 69 6e 20 6f 66 20 61 20 70  he origin of a p
2fef0 61 72 74 69 63 75 6c 61 72 20 72 65 73 75 6c 74  articular result
2ff00 20 63 6f 6c 75 6d 6e 20 69 6e 0a 2a 2a 20 5b 53   column in.** [S
2ff10 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74  ELECT] statement
2ff20 2e 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f  ..** ^The name o
2ff30 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6f  f the database o
2ff40 72 20 74 61 62 6c 65 20 6f 72 20 63 6f 6c 75 6d  r table or colum
2ff50 6e 20 63 61 6e 20 62 65 20 72 65 74 75 72 6e 65  n can be returne
2ff60 64 20 61 73 0a 2a 2a 20 65 69 74 68 65 72 20 61  d as.** either a
2ff70 20 55 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 36   UTF-8 or UTF-16
2ff80 20 73 74 72 69 6e 67 2e 20 20 5e 54 68 65 20 5f   string.  ^The _
2ff90 64 61 74 61 62 61 73 65 5f 20 72 6f 75 74 69 6e  database_ routin
2ffa0 65 73 20 72 65 74 75 72 6e 0a 2a 2a 20 74 68 65  es return.** the
2ffb0 20 64 61 74 61 62 61 73 65 20 6e 61 6d 65 2c 20   database name, 
2ffc0 74 68 65 20 5f 74 61 62 6c 65 5f 20 72 6f 75 74  the _table_ rout
2ffd0 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65 20  ines return the 
2ffe0 74 61 62 6c 65 20 6e 61 6d 65 2c 20 61 6e 64 0a  table name, and.
2fff0 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e 5f 20 72  ** the origin_ r
30000 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74  outines return t
30010 68 65 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 2e 0a  he column name..
30020 2a 2a 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64  ** ^The returned
30030 20 73 74 72 69 6e 67 20 69 73 20 76 61 6c 69 64   string is valid
30040 20 75 6e 74 69 6c 20 74 68 65 20 5b 70 72 65 70   until the [prep
30050 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
30060 69 73 20 64 65 73 74 72 6f 79 65 64 0a 2a 2a 20  is destroyed.** 
30070 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66  using [sqlite3_f
30080 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 75 6e  inalize()] or un
30090 74 69 6c 20 74 68 65 20 73 74 61 74 65 6d 65 6e  til the statemen
300a0 74 20 69 73 20 61 75 74 6f 6d 61 74 69 63 61 6c  t is automatical
300b0 6c 79 0a 2a 2a 20 72 65 70 72 65 70 61 72 65 64  ly.** reprepared
300c0 20 62 79 20 74 68 65 20 66 69 72 73 74 20 63 61   by the first ca
300d0 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73  ll to [sqlite3_s
300e0 74 65 70 28 29 5d 20 66 6f 72 20 61 20 70 61 72  tep()] for a par
300f0 74 69 63 75 6c 61 72 20 72 75 6e 0a 2a 2a 20 6f  ticular run.** o
30100 72 20 75 6e 74 69 6c 20 74 68 65 20 73 61 6d 65  r until the same
30110 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20   information is 
30120 72 65 71 75 65 73 74 65 64 0a 2a 2a 20 61 67 61  requested.** aga
30130 69 6e 20 69 6e 20 61 20 64 69 66 66 65 72 65 6e  in in a differen
30140 74 20 65 6e 63 6f 64 69 6e 67 2e 0a 2a 2a 0a 2a  t encoding..**.*
30150 2a 20 5e 54 68 65 20 6e 61 6d 65 73 20 72 65 74  * ^The names ret
30160 75 72 6e 65 64 20 61 72 65 20 74 68 65 20 6f 72  urned are the or
30170 69 67 69 6e 61 6c 20 75 6e 2d 61 6c 69 61 73 65  iginal un-aliase
30180 64 20 6e 61 6d 65 73 20 6f 66 20 74 68 65 0a 2a  d names of the.*
30190 2a 20 64 61 74 61 62 61 73 65 2c 20 74 61 62 6c  * database, tabl
301a0 65 2c 20 61 6e 64 20 63 6f 6c 75 6d 6e 2e 0a 2a  e, and column..*
301b0 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20  *.** ^The first 
301c0 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 73  argument to thes
301d0 65 20 69 6e 74 65 72 66 61 63 65 73 20 69 73 20  e interfaces is 
301e0 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  a [prepared stat
301f0 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 54 68 65 73  ement]..** ^Thes
30200 65 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75  e functions retu
30210 72 6e 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61  rn information a
30220 62 6f 75 74 20 74 68 65 20 4e 74 68 20 72 65 73  bout the Nth res
30230 75 6c 74 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72  ult column retur
30240 6e 65 64 20 62 79 0a 2a 2a 20 74 68 65 20 73 74  ned by.** the st
30250 61 74 65 6d 65 6e 74 2c 20 77 68 65 72 65 20 4e  atement, where N
30260 20 69 73 20 74 68 65 20 73 65 63 6f 6e 64 20 66   is the second f
30270 75 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65 6e 74  unction argument
30280 2e 0a 2a 2a 20 5e 54 68 65 20 6c 65 66 74 2d 6d  ..** ^The left-m
30290 6f 73 74 20 63 6f 6c 75 6d 6e 20 69 73 20 63 6f  ost column is co
302a0 6c 75 6d 6e 20 30 20 66 6f 72 20 74 68 65 73 65  lumn 0 for these
302b0 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a   routines..**.**
302c0 20 5e 49 66 20 74 68 65 20 4e 74 68 20 63 6f 6c   ^If the Nth col
302d0 75 6d 6e 20 72 65 74 75 72 6e 65 64 20 62 79 20  umn returned by 
302e0 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73  the statement is
302f0 20 61 6e 20 65 78 70 72 65 73 73 69 6f 6e 20 6f   an expression o
30300 72 0a 2a 2a 20 73 75 62 71 75 65 72 79 20 61 6e  r.** subquery an
30310 64 20 69 73 20 6e 6f 74 20 61 20 63 6f 6c 75 6d  d is not a colum
30320 6e 20 76 61 6c 75 65 2c 20 74 68 65 6e 20 61 6c  n value, then al
30330 6c 20 6f 66 20 74 68 65 73 65 20 66 75 6e 63 74  l of these funct
30340 69 6f 6e 73 20 72 65 74 75 72 6e 0a 2a 2a 20 4e  ions return.** N
30350 55 4c 4c 2e 20 20 5e 54 68 65 73 65 20 72 6f 75  ULL.  ^These rou
30360 74 69 6e 65 20 6d 69 67 68 74 20 61 6c 73 6f 20  tine might also 
30370 72 65 74 75 72 6e 20 4e 55 4c 4c 20 69 66 20 61  return NULL if a
30380 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
30390 6f 6e 20 65 72 72 6f 72 0a 2a 2a 20 6f 63 63 75  on error.** occu
303a0 72 73 2e 20 20 5e 4f 74 68 65 72 77 69 73 65 2c  rs.  ^Otherwise,
303b0 20 74 68 65 79 20 72 65 74 75 72 6e 20 74 68 65   they return the
303c0 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 61 74 74   name of the att
303d0 61 63 68 65 64 20 64 61 74 61 62 61 73 65 2c 20  ached database, 
303e0 74 61 62 6c 65 2c 0a 2a 2a 20 6f 72 20 63 6f 6c  table,.** or col
303f0 75 6d 6e 20 74 68 61 74 20 71 75 65 72 79 20 72  umn that query r
30400 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 77 61 73  esult column was
30410 20 65 78 74 72 61 63 74 65 64 20 66 72 6f 6d 2e   extracted from.
30420 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 77 69 74 68 20  .**.** ^As with 
30430 61 6c 6c 20 6f 74 68 65 72 20 53 51 4c 69 74 65  all other SQLite
30440 20 41 50 49 73 2c 20 74 68 6f 73 65 20 77 68 6f   APIs, those who
30450 73 65 20 6e 61 6d 65 73 20 65 6e 64 20 77 69 74  se names end wit
30460 68 20 22 31 36 22 20 72 65 74 75 72 6e 0a 2a 2a  h "16" return.**
30470 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20   UTF-16 encoded 
30480 73 74 72 69 6e 67 73 20 61 6e 64 20 74 68 65 20  strings and the 
30490 6f 74 68 65 72 20 66 75 6e 63 74 69 6f 6e 73 20  other functions 
304a0 72 65 74 75 72 6e 20 55 54 46 2d 38 2e 0a 2a 2a  return UTF-8..**
304b0 0a 2a 2a 20 5e 54 68 65 73 65 20 41 50 49 73 20  .** ^These APIs 
304c0 61 72 65 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62  are only availab
304d0 6c 65 20 69 66 20 74 68 65 20 6c 69 62 72 61 72  le if the librar
304e0 79 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 77  y was compiled w
304f0 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49  ith the.** [SQLI
30500 54 45 5f 45 4e 41 42 4c 45 5f 43 4f 4c 55 4d 4e  TE_ENABLE_COLUMN
30510 5f 4d 45 54 41 44 41 54 41 5d 20 43 2d 70 72 65  _METADATA] C-pre
30520 70 72 6f 63 65 73 73 6f 72 20 73 79 6d 62 6f 6c  processor symbol
30530 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 77 6f 20 6f  ..**.** If two o
30540 72 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20 63  r more threads c
30550 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20  all one or more 
30560 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  of these routine
30570 73 20 61 67 61 69 6e 73 74 20 74 68 65 20 73 61  s against the sa
30580 6d 65 0a 2a 2a 20 70 72 65 70 61 72 65 64 20 73  me.** prepared s
30590 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 63 6f 6c  tatement and col
305a0 75 6d 6e 20 61 74 20 74 68 65 20 73 61 6d 65 20  umn at the same 
305b0 74 69 6d 65 20 74 68 65 6e 20 74 68 65 20 72 65  time then the re
305c0 73 75 6c 74 73 20 61 72 65 0a 2a 2a 20 75 6e 64  sults are.** und
305d0 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66  efined..**.** If
305e0 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 74 68 72   two or more thr
305f0 65 61 64 73 20 63 61 6c 6c 20 6f 6e 65 20 6f 72  eads call one or
30600 20 6d 6f 72 65 0a 2a 2a 20 5b 73 71 6c 69 74 65   more.** [sqlite
30610 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73  3_column_databas
30620 65 5f 6e 61 6d 65 20 7c 20 63 6f 6c 75 6d 6e 20  e_name | column 
30630 6d 65 74 61 64 61 74 61 20 69 6e 74 65 72 66 61  metadata interfa
30640 63 65 73 5d 0a 2a 2a 20 66 6f 72 20 74 68 65 20  ces].** for the 
30650 73 61 6d 65 20 5b 70 72 65 70 61 72 65 64 20 73  same [prepared s
30660 74 61 74 65 6d 65 6e 74 5d 20 61 6e 64 20 72 65  tatement] and re
30670 73 75 6c 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 61  sult column.** a
30680 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 20  t the same time 
30690 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73  then the results
306a0 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a   are undefined..
306b0 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f  */.SQLITE_API co
306c0 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65  nst char *sqlite
306d0 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73  3_column_databas
306e0 65 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73  e_name(sqlite3_s
306f0 74 6d 74 2a 2c 69 6e 74 29 3b 0a 53 51 4c 49 54  tmt*,int);.SQLIT
30700 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64  E_API const void
30710 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
30720 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 31 36  _database_name16
30730 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69  (sqlite3_stmt*,i
30740 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  nt);.SQLITE_API 
30750 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69  const char *sqli
30760 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65  te3_column_table
30770 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74  _name(sqlite3_st
30780 6d 74 2a 2c 69 6e 74 29 3b 0a 53 51 4c 49 54 45  mt*,int);.SQLITE
30790 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20  _API const void 
307a0 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
307b0 74 61 62 6c 65 5f 6e 61 6d 65 31 36 28 73 71 6c  table_name16(sql
307c0 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b  ite3_stmt*,int);
307d0 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73  .SQLITE_API cons
307e0 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
307f0 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61  column_origin_na
30800 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  me(sqlite3_stmt*
30810 2c 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50  ,int);.SQLITE_AP
30820 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  I const void *sq
30830 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69  lite3_column_ori
30840 67 69 6e 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74  gin_name16(sqlit
30850 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a  e3_stmt*,int);..
30860 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
30870 44 65 63 6c 61 72 65 64 20 44 61 74 61 74 79 70  Declared Datatyp
30880 65 20 4f 66 20 41 20 51 75 65 72 79 20 52 65 73  e Of A Query Res
30890 75 6c 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  ult.** METHOD: s
308a0 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a  qlite3_stmt.**.*
308b0 2a 20 5e 28 54 68 65 20 66 69 72 73 74 20 70 61  * ^(The first pa
308c0 72 61 6d 65 74 65 72 20 69 73 20 61 20 5b 70 72  rameter is a [pr
308d0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
308e0 5d 2e 0a 2a 2a 20 49 66 20 74 68 69 73 20 73 74  ]..** If this st
308f0 61 74 65 6d 65 6e 74 20 69 73 20 61 20 5b 53 45  atement is a [SE
30900 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 20  LECT] statement 
30910 61 6e 64 20 74 68 65 20 4e 74 68 20 63 6f 6c 75  and the Nth colu
30920 6d 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 72 65 74  mn of the.** ret
30930 75 72 6e 65 64 20 72 65 73 75 6c 74 20 73 65 74  urned result set
30940 20 6f 66 20 74 68 61 74 20 5b 53 45 4c 45 43 54   of that [SELECT
30950 5d 20 69 73 20 61 20 74 61 62 6c 65 20 63 6f 6c  ] is a table col
30960 75 6d 6e 20 28 6e 6f 74 20 61 6e 0a 2a 2a 20 65  umn (not an.** e
30970 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 73 75 62  xpression or sub
30980 71 75 65 72 79 29 20 74 68 65 6e 20 74 68 65 20  query) then the 
30990 64 65 63 6c 61 72 65 64 20 74 79 70 65 20 6f 66  declared type of
309a0 20 74 68 65 20 74 61 62 6c 65 0a 2a 2a 20 63 6f   the table.** co
309b0 6c 75 6d 6e 20 69 73 20 72 65 74 75 72 6e 65 64  lumn is returned
309c0 2e 29 5e 20 20 5e 49 66 20 74 68 65 20 4e 74 68  .)^  ^If the Nth
309d0 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72   column of the r
309e0 65 73 75 6c 74 20 73 65 74 20 69 73 20 61 6e 0a  esult set is an.
309f0 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72  ** expression or
30a00 20 73 75 62 71 75 65 72 79 2c 20 74 68 65 6e 20   subquery, then 
30a10 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69  a NULL pointer i
30a20 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 5e  s returned..** ^
30a30 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72  The returned str
30a40 69 6e 67 20 69 73 20 61 6c 77 61 79 73 20 55 54  ing is always UT
30a50 46 2d 38 20 65 6e 63 6f 64 65 64 2e 0a 2a 2a 0a  F-8 encoded..**.
30a60 2a 2a 20 5e 28 46 6f 72 20 65 78 61 6d 70 6c 65  ** ^(For example
30a70 2c 20 67 69 76 65 6e 20 74 68 65 20 64 61 74 61  , given the data
30a80 62 61 73 65 20 73 63 68 65 6d 61 3a 0a 2a 2a 0a  base schema:.**.
30a90 2a 2a 20 43 52 45 41 54 45 20 54 41 42 4c 45 20  ** CREATE TABLE 
30aa0 74 31 28 63 31 20 56 41 52 49 41 4e 54 29 3b 0a  t1(c1 VARIANT);.
30ab0 2a 2a 0a 2a 2a 20 61 6e 64 20 74 68 65 20 66 6f  **.** and the fo
30ac0 6c 6c 6f 77 69 6e 67 20 73 74 61 74 65 6d 65 6e  llowing statemen
30ad0 74 20 74 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64  t to be compiled
30ae0 3a 0a 2a 2a 0a 2a 2a 20 53 45 4c 45 43 54 20 63  :.**.** SELECT c
30af0 31 20 2b 20 31 2c 20 63 31 20 46 52 4f 4d 20 74  1 + 1, c1 FROM t
30b00 31 3b 0a 2a 2a 0a 2a 2a 20 74 68 69 73 20 72 6f  1;.**.** this ro
30b10 75 74 69 6e 65 20 77 6f 75 6c 64 20 72 65 74 75  utine would retu
30b20 72 6e 20 74 68 65 20 73 74 72 69 6e 67 20 22 56  rn the string "V
30b30 41 52 49 41 4e 54 22 20 66 6f 72 20 74 68 65 20  ARIANT" for the 
30b40 73 65 63 6f 6e 64 20 72 65 73 75 6c 74 0a 2a 2a  second result.**
30b50 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d 31 29 2c 20   column (i==1), 
30b60 61 6e 64 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  and a NULL point
30b70 65 72 20 66 6f 72 20 74 68 65 20 66 69 72 73 74  er for the first
30b80 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 28   result column (
30b90 69 3d 3d 30 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  i==0).)^.**.** ^
30ba0 53 51 4c 69 74 65 20 75 73 65 73 20 64 79 6e 61  SQLite uses dyna
30bb0 6d 69 63 20 72 75 6e 2d 74 69 6d 65 20 74 79 70  mic run-time typ
30bc0 69 6e 67 2e 20 20 5e 53 6f 20 6a 75 73 74 20 62  ing.  ^So just b
30bd0 65 63 61 75 73 65 20 61 20 63 6f 6c 75 6d 6e 0a  ecause a column.
30be0 2a 2a 20 69 73 20 64 65 63 6c 61 72 65 64 20 74  ** is declared t
30bf0 6f 20 63 6f 6e 74 61 69 6e 20 61 20 70 61 72 74  o contain a part
30c00 69 63 75 6c 61 72 20 74 79 70 65 20 64 6f 65 73  icular type does
30c10 20 6e 6f 74 20 6d 65 61 6e 20 74 68 61 74 20 74   not mean that t
30c20 68 65 0a 2a 2a 20 64 61 74 61 20 73 74 6f 72 65  he.** data store
30c30 64 20 69 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e  d in that column
30c40 20 69 73 20 6f 66 20 74 68 65 20 64 65 63 6c 61   is of the decla
30c50 72 65 64 20 74 79 70 65 2e 20 20 53 51 4c 69 74  red type.  SQLit
30c60 65 20 69 73 0a 2a 2a 20 73 74 72 6f 6e 67 6c 79  e is.** strongly
30c70 20 74 79 70 65 64 2c 20 62 75 74 20 74 68 65 20   typed, but the 
30c80 74 79 70 69 6e 67 20 69 73 20 64 79 6e 61 6d 69  typing is dynami
30c90 63 20 6e 6f 74 20 73 74 61 74 69 63 2e 20 20 5e  c not static.  ^
30ca0 54 79 70 65 0a 2a 2a 20 69 73 20 61 73 73 6f 63  Type.** is assoc
30cb0 69 61 74 65 64 20 77 69 74 68 20 69 6e 64 69 76  iated with indiv
30cc0 69 64 75 61 6c 20 76 61 6c 75 65 73 2c 20 6e 6f  idual values, no
30cd0 74 20 77 69 74 68 20 74 68 65 20 63 6f 6e 74 61  t with the conta
30ce0 69 6e 65 72 73 0a 2a 2a 20 75 73 65 64 20 74 6f  iners.** used to
30cf0 20 68 6f 6c 64 20 74 68 6f 73 65 20 76 61 6c 75   hold those valu
30d00 65 73 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  es..*/.SQLITE_AP
30d10 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  I const char *sq
30d20 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63  lite3_column_dec
30d30 6c 74 79 70 65 28 73 71 6c 69 74 65 33 5f 73 74  ltype(sqlite3_st
30d40 6d 74 2a 2c 69 6e 74 29 3b 0a 53 51 4c 49 54 45  mt*,int);.SQLITE
30d50 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20  _API const void 
30d60 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
30d70 64 65 63 6c 74 79 70 65 31 36 28 73 71 6c 69 74  decltype16(sqlit
30d80 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a  e3_stmt*,int);..
30d90 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
30da0 45 76 61 6c 75 61 74 65 20 41 6e 20 53 51 4c 20  Evaluate An SQL 
30db0 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 4d 45 54  Statement.** MET
30dc0 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d  HOD: sqlite3_stm
30dd0 74 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 61 20  t.**.** After a 
30de0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
30df0 65 6e 74 5d 20 68 61 73 20 62 65 65 6e 20 70 72  ent] has been pr
30e00 65 70 61 72 65 64 20 75 73 69 6e 67 20 65 69 74  epared using eit
30e10 68 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  her.** [sqlite3_
30e20 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72  prepare_v2()] or
30e30 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
30e40 65 31 36 5f 76 32 28 29 5d 20 6f 72 20 6f 6e 65  e16_v2()] or one
30e50 20 6f 66 20 74 68 65 20 6c 65 67 61 63 79 0a 2a   of the legacy.*
30e60 2a 20 69 6e 74 65 72 66 61 63 65 73 20 5b 73 71  * interfaces [sq
30e70 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d  lite3_prepare()]
30e80 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65   or [sqlite3_pre
30e90 70 61 72 65 31 36 28 29 5d 2c 20 74 68 69 73 20  pare16()], this 
30ea0 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74  function.** must
30eb0 20 62 65 20 63 61 6c 6c 65 64 20 6f 6e 65 20 6f   be called one o
30ec0 72 20 6d 6f 72 65 20 74 69 6d 65 73 20 74 6f 20  r more times to 
30ed0 65 76 61 6c 75 61 74 65 20 74 68 65 20 73 74 61  evaluate the sta
30ee0 74 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68  tement..**.** Th
30ef0 65 20 64 65 74 61 69 6c 73 20 6f 66 20 74 68 65  e details of the
30f00 20 62 65 68 61 76 69 6f 72 20 6f 66 20 74 68 65   behavior of the
30f10 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20   sqlite3_step() 
30f20 69 6e 74 65 72 66 61 63 65 20 64 65 70 65 6e 64  interface depend
30f30 0a 2a 2a 20 6f 6e 20 77 68 65 74 68 65 72 20 74  .** on whether t
30f40 68 65 20 73 74 61 74 65 6d 65 6e 74 20 77 61 73  he statement was
30f50 20 70 72 65 70 61 72 65 64 20 75 73 69 6e 67 20   prepared using 
30f60 74 68 65 20 6e 65 77 65 72 20 22 76 32 22 20 69  the newer "v2" i
30f70 6e 74 65 72 66 61 63 65 0a 2a 2a 20 5b 73 71 6c  nterface.** [sql
30f80 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
30f90 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
30fa0 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20  prepare16_v2()] 
30fb0 6f 72 20 74 68 65 20 6f 6c 64 65 72 20 6c 65 67  or the older leg
30fc0 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  acy.** interface
30fd0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
30fe0 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  e()] and [sqlite
30ff0 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2e 20  3_prepare16()]. 
31000 20 54 68 65 20 75 73 65 20 6f 66 20 74 68 65 0a   The use of the.
31010 2a 2a 20 6e 65 77 20 22 76 32 22 20 69 6e 74 65  ** new "v2" inte
31020 72 66 61 63 65 20 69 73 20 72 65 63 6f 6d 6d 65  rface is recomme
31030 6e 64 65 64 20 66 6f 72 20 6e 65 77 20 61 70 70  nded for new app
31040 6c 69 63 61 74 69 6f 6e 73 20 62 75 74 20 74 68  lications but th
31050 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65  e legacy.** inte
31060 72 66 61 63 65 20 77 69 6c 6c 20 63 6f 6e 74 69  rface will conti
31070 6e 75 65 20 74 6f 20 62 65 20 73 75 70 70 6f 72  nue to be suppor
31080 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 20 74  ted..**.** ^In t
31090 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66  he legacy interf
310a0 61 63 65 2c 20 74 68 65 20 72 65 74 75 72 6e 20  ace, the return 
310b0 76 61 6c 75 65 20 77 69 6c 6c 20 62 65 20 65 69  value will be ei
310c0 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 42 55 53  ther [SQLITE_BUS
310d0 59 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44  Y],.** [SQLITE_D
310e0 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 52 4f  ONE], [SQLITE_RO
310f0 57 5d 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  W], [SQLITE_ERRO
31100 52 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4d  R], or [SQLITE_M
31110 49 53 55 53 45 5d 2e 0a 2a 2a 20 5e 57 69 74 68  ISUSE]..** ^With
31120 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66   the "v2" interf
31130 61 63 65 2c 20 61 6e 79 20 6f 66 20 74 68 65 20  ace, any of the 
31140 6f 74 68 65 72 20 5b 72 65 73 75 6c 74 20 63 6f  other [result co
31150 64 65 73 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65  des] or.** [exte
31160 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65  nded result code
31170 73 5d 20 6d 69 67 68 74 20 62 65 20 72 65 74 75  s] might be retu
31180 72 6e 65 64 20 61 73 20 77 65 6c 6c 2e 0a 2a 2a  rned as well..**
31190 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 42 55 53  .** ^[SQLITE_BUS
311a0 59 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68  Y] means that th
311b0 65 20 64 61 74 61 62 61 73 65 20 65 6e 67 69 6e  e database engin
311c0 65 20 77 61 73 20 75 6e 61 62 6c 65 20 74 6f 20  e was unable to 
311d0 61 63 71 75 69 72 65 20 74 68 65 0a 2a 2a 20 64  acquire the.** d
311e0 61 74 61 62 61 73 65 20 6c 6f 63 6b 73 20 69 74  atabase locks it
311f0 20 6e 65 65 64 73 20 74 6f 20 64 6f 20 69 74 73   needs to do its
31200 20 6a 6f 62 2e 20 20 5e 49 66 20 74 68 65 20 73   job.  ^If the s
31210 74 61 74 65 6d 65 6e 74 20 69 73 20 61 20 5b 43  tatement is a [C
31220 4f 4d 4d 49 54 5d 0a 2a 2a 20 6f 72 20 6f 63 63  OMMIT].** or occ
31230 75 72 73 20 6f 75 74 73 69 64 65 20 6f 66 20 61  urs outside of a
31240 6e 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73  n explicit trans
31250 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20 79 6f 75  action, then you
31260 20 63 61 6e 20 72 65 74 72 79 20 74 68 65 0a 2a   can retry the.*
31270 2a 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 49 66  * statement.  If
31280 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69   the statement i
31290 73 20 6e 6f 74 20 61 20 5b 43 4f 4d 4d 49 54 5d  s not a [COMMIT]
312a0 20 61 6e 64 20 6f 63 63 75 72 73 20 77 69 74 68   and occurs with
312b0 69 6e 20 61 6e 0a 2a 2a 20 65 78 70 6c 69 63 69  in an.** explici
312c0 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 74 68  t transaction th
312d0 65 6e 20 79 6f 75 20 73 68 6f 75 6c 64 20 72 6f  en you should ro
312e0 6c 6c 62 61 63 6b 20 74 68 65 20 74 72 61 6e 73  llback the trans
312f0 61 63 74 69 6f 6e 20 62 65 66 6f 72 65 0a 2a 2a  action before.**
31300 20 63 6f 6e 74 69 6e 75 69 6e 67 2e 0a 2a 2a 0a   continuing..**.
31310 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 44 4f 4e 45  ** ^[SQLITE_DONE
31320 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65  ] means that the
31330 20 73 74 61 74 65 6d 65 6e 74 20 68 61 73 20 66   statement has f
31340 69 6e 69 73 68 65 64 20 65 78 65 63 75 74 69 6e  inished executin
31350 67 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 6c  g.** successfull
31360 79 2e 20 20 73 71 6c 69 74 65 33 5f 73 74 65 70  y.  sqlite3_step
31370 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65  () should not be
31380 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e   called again on
31390 20 74 68 69 73 20 76 69 72 74 75 61 6c 0a 2a 2a   this virtual.**
313a0 20 6d 61 63 68 69 6e 65 20 77 69 74 68 6f 75 74   machine without
313b0 20 66 69 72 73 74 20 63 61 6c 6c 69 6e 67 20 5b   first calling [
313c0 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
313d0 20 74 6f 20 72 65 73 65 74 20 74 68 65 20 76 69   to reset the vi
313e0 72 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65  rtual.** machine
313f0 20 62 61 63 6b 20 74 6f 20 69 74 73 20 69 6e 69   back to its ini
31400 74 69 61 6c 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a  tial state..**.*
31410 2a 20 5e 49 66 20 74 68 65 20 53 51 4c 20 73 74  * ^If the SQL st
31420 61 74 65 6d 65 6e 74 20 62 65 69 6e 67 20 65 78  atement being ex
31430 65 63 75 74 65 64 20 72 65 74 75 72 6e 73 20 61  ecuted returns a
31440 6e 79 20 64 61 74 61 2c 20 74 68 65 6e 20 5b 53  ny data, then [S
31450 51 4c 49 54 45 5f 52 4f 57 5d 0a 2a 2a 20 69 73  QLITE_ROW].** is
31460 20 72 65 74 75 72 6e 65 64 20 65 61 63 68 20 74   returned each t
31470 69 6d 65 20 61 20 6e 65 77 20 72 6f 77 20 6f 66  ime a new row of
31480 20 64 61 74 61 20 69 73 20 72 65 61 64 79 20 66   data is ready f
31490 6f 72 20 70 72 6f 63 65 73 73 69 6e 67 20 62 79  or processing by
314a0 20 74 68 65 0a 2a 2a 20 63 61 6c 6c 65 72 2e 20   the.** caller. 
314b0 54 68 65 20 76 61 6c 75 65 73 20 6d 61 79 20 62  The values may b
314c0 65 20 61 63 63 65 73 73 65 64 20 75 73 69 6e 67  e accessed using
314d0 20 74 68 65 20 5b 63 6f 6c 75 6d 6e 20 61 63 63   the [column acc
314e0 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a  ess functions]..
314f0 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  ** sqlite3_step(
31500 29 20 69 73 20 63 61 6c 6c 65 64 20 61 67 61 69  ) is called agai
31510 6e 20 74 6f 20 72 65 74 72 69 65 76 65 20 74 68  n to retrieve th
31520 65 20 6e 65 78 74 20 72 6f 77 20 6f 66 20 64 61  e next row of da
31530 74 61 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49  ta..**.** ^[SQLI
31540 54 45 5f 45 52 52 4f 52 5d 20 6d 65 61 6e 73 20  TE_ERROR] means 
31550 74 68 61 74 20 61 20 72 75 6e 2d 74 69 6d 65 20  that a run-time 
31560 65 72 72 6f 72 20 28 73 75 63 68 20 61 73 20 61  error (such as a
31570 20 63 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a 20 76   constraint.** v
31580 69 6f 6c 61 74 69 6f 6e 29 20 68 61 73 20 6f 63  iolation) has oc
31590 63 75 72 72 65 64 2e 20 20 73 71 6c 69 74 65 33  curred.  sqlite3
315a0 5f 73 74 65 70 28 29 20 73 68 6f 75 6c 64 20 6e  _step() should n
315b0 6f 74 20 62 65 20 63 61 6c 6c 65 64 20 61 67 61  ot be called aga
315c0 69 6e 20 6f 6e 0a 2a 2a 20 74 68 65 20 56 4d 2e  in on.** the VM.
315d0 20 4d 6f 72 65 20 69 6e 66 6f 72 6d 61 74 69 6f   More informatio
315e0 6e 20 6d 61 79 20 62 65 20 66 6f 75 6e 64 20 62  n may be found b
315f0 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74  y calling [sqlit
31600 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2a  e3_errmsg()]..**
31610 20 5e 57 69 74 68 20 74 68 65 20 6c 65 67 61 63   ^With the legac
31620 79 20 69 6e 74 65 72 66 61 63 65 2c 20 61 20 6d  y interface, a m
31630 6f 72 65 20 73 70 65 63 69 66 69 63 20 65 72 72  ore specific err
31640 6f 72 20 63 6f 64 65 20 28 66 6f 72 20 65 78 61  or code (for exa
31650 6d 70 6c 65 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45  mple,.** [SQLITE
31660 5f 49 4e 54 45 52 52 55 50 54 5d 2c 20 5b 53 51  _INTERRUPT], [SQ
31670 4c 49 54 45 5f 53 43 48 45 4d 41 5d 2c 20 5b 53  LITE_SCHEMA], [S
31680 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 5d 2c 20  QLITE_CORRUPT], 
31690 61 6e 64 20 73 6f 20 66 6f 72 74 68 29 0a 2a 2a  and so forth).**
316a0 20 63 61 6e 20 62 65 20 6f 62 74 61 69 6e 65 64   can be obtained
316b0 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c   by calling [sql
316c0 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 6e  ite3_reset()] on
316d0 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65   the.** [prepare
316e0 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20 5e  d statement].  ^
316f0 49 6e 20 74 68 65 20 22 76 32 22 20 69 6e 74 65  In the "v2" inte
31700 72 66 61 63 65 2c 0a 2a 2a 20 74 68 65 20 6d 6f  rface,.** the mo
31710 72 65 20 73 70 65 63 69 66 69 63 20 65 72 72 6f  re specific erro
31720 72 20 63 6f 64 65 20 69 73 20 72 65 74 75 72 6e  r code is return
31730 65 64 20 64 69 72 65 63 74 6c 79 20 62 79 20 73  ed directly by s
31740 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 0a 2a  qlite3_step()..*
31750 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 49 53  *.** [SQLITE_MIS
31760 55 53 45 5d 20 6d 65 61 6e 73 20 74 68 61 74 20  USE] means that 
31770 74 68 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65  the this routine
31780 20 77 61 73 20 63 61 6c 6c 65 64 20 69 6e 61 70   was called inap
31790 70 72 6f 70 72 69 61 74 65 6c 79 2e 0a 2a 2a 20  propriately..** 
317a0 50 65 72 68 61 70 73 20 69 74 20 77 61 73 20 63  Perhaps it was c
317b0 61 6c 6c 65 64 20 6f 6e 20 61 20 5b 70 72 65 70  alled on a [prep
317c0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
317d0 74 68 61 74 20 68 61 73 0a 2a 2a 20 61 6c 72 65  that has.** alre
317e0 61 64 79 20 62 65 65 6e 20 5b 73 71 6c 69 74 65  ady been [sqlite
317f0 33 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 66 69 6e  3_finalize | fin
31800 61 6c 69 7a 65 64 5d 20 6f 72 20 6f 6e 20 6f 6e  alized] or on on
31810 65 20 74 68 61 74 20 68 61 64 0a 2a 2a 20 70 72  e that had.** pr
31820 65 76 69 6f 75 73 6c 79 20 72 65 74 75 72 6e 65  eviously returne
31830 64 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d  d [SQLITE_ERROR]
31840 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45   or [SQLITE_DONE
31850 5d 2e 20 20 4f 72 20 69 74 20 63 6f 75 6c 64 0a  ].  Or it could.
31860 2a 2a 20 62 65 20 74 68 65 20 63 61 73 65 20 74  ** be the case t
31870 68 61 74 20 74 68 65 20 73 61 6d 65 20 64 61 74  hat the same dat
31880 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
31890 20 69 73 20 62 65 69 6e 67 20 75 73 65 64 20 62   is being used b
318a0 79 20 74 77 6f 20 6f 72 0a 2a 2a 20 6d 6f 72 65  y two or.** more
318b0 20 74 68 72 65 61 64 73 20 61 74 20 74 68 65 20   threads at the 
318c0 73 61 6d 65 20 6d 6f 6d 65 6e 74 20 69 6e 20 74  same moment in t
318d0 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 61  ime..**.** For a
318e0 6c 6c 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53  ll versions of S
318f0 51 4c 69 74 65 20 75 70 20 74 6f 20 61 6e 64 20  QLite up to and 
31900 69 6e 63 6c 75 64 69 6e 67 20 33 2e 36 2e 32 33  including 3.6.23
31910 2e 31 2c 20 61 20 63 61 6c 6c 20 74 6f 0a 2a 2a  .1, a call to.**
31920 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
31930 29 5d 20 77 61 73 20 72 65 71 75 69 72 65 64 20  )] was required 
31940 61 66 74 65 72 20 73 71 6c 69 74 65 33 5f 73 74  after sqlite3_st
31950 65 70 28 29 20 72 65 74 75 72 6e 65 64 20 61 6e  ep() returned an
31960 79 74 68 69 6e 67 0a 2a 2a 20 6f 74 68 65 72 20  ything.** other 
31970 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57  than [SQLITE_ROW
31980 5d 20 62 65 66 6f 72 65 20 61 6e 79 20 73 75 62  ] before any sub
31990 73 65 71 75 65 6e 74 20 69 6e 76 6f 63 61 74 69  sequent invocati
319a0 6f 6e 20 6f 66 0a 2a 2a 20 73 71 6c 69 74 65 33  on of.** sqlite3
319b0 5f 73 74 65 70 28 29 2e 20 20 46 61 69 6c 75 72  _step().  Failur
319c0 65 20 74 6f 20 72 65 73 65 74 20 74 68 65 20 70  e to reset the p
319d0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
319e0 74 20 75 73 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c  t using .** [sql
319f0 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 77 6f  ite3_reset()] wo
31a00 75 6c 64 20 72 65 73 75 6c 74 20 69 6e 20 61 6e  uld result in an
31a10 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d   [SQLITE_MISUSE]
31a20 20 72 65 74 75 72 6e 20 66 72 6f 6d 0a 2a 2a 20   return from.** 
31a30 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 20  sqlite3_step(). 
31a40 20 42 75 74 20 61 66 74 65 72 20 5b 76 65 72 73   But after [vers
31a50 69 6f 6e 20 33 2e 36 2e 32 33 2e 31 5d 20 28 5b  ion 3.6.23.1] ([
31a60 64 61 74 65 6f 66 3a 33 2e 36 2e 32 33 2e 31 5d  dateof:3.6.23.1]
31a70 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 65  ,.** sqlite3_ste
31a80 70 28 29 20 62 65 67 61 6e 0a 2a 2a 20 63 61 6c  p() began.** cal
31a90 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65  ling [sqlite3_re
31aa0 73 65 74 28 29 5d 20 61 75 74 6f 6d 61 74 69 63  set()] automatic
31ab0 61 6c 6c 79 20 69 6e 20 74 68 69 73 20 63 69 72  ally in this cir
31ac0 63 75 6d 73 74 61 6e 63 65 20 72 61 74 68 65 72  cumstance rather
31ad0 0a 2a 2a 20 74 68 61 6e 20 72 65 74 75 72 6e 69  .** than returni
31ae0 6e 67 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53  ng [SQLITE_MISUS
31af0 45 5d 2e 20 20 54 68 69 73 20 69 73 20 6e 6f 74  E].  This is not
31b00 20 63 6f 6e 73 69 64 65 72 65 64 20 61 20 63 6f   considered a co
31b10 6d 70 61 74 69 62 69 6c 69 74 79 0a 2a 2a 20 62  mpatibility.** b
31b20 72 65 61 6b 20 62 65 63 61 75 73 65 20 61 6e 79  reak because any
31b30 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 68 61   application tha
31b40 74 20 65 76 65 72 20 72 65 63 65 69 76 65 73 20  t ever receives 
31b50 61 6e 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  an SQLITE_MISUSE
31b60 20 65 72 72 6f 72 0a 2a 2a 20 69 73 20 62 72 6f   error.** is bro
31b70 6b 65 6e 20 62 79 20 64 65 66 69 6e 69 74 69 6f  ken by definitio
31b80 6e 2e 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  n.  The [SQLITE_
31b90 4f 4d 49 54 5f 41 55 54 4f 52 45 53 45 54 5d 20  OMIT_AUTORESET] 
31ba0 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
31bb0 69 6f 6e 0a 2a 2a 20 63 61 6e 20 62 65 20 75 73  ion.** can be us
31bc0 65 64 20 74 6f 20 72 65 73 74 6f 72 65 20 74 68  ed to restore th
31bd0 65 20 6c 65 67 61 63 79 20 62 65 68 61 76 69 6f  e legacy behavio
31be0 72 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 47 6f 6f 66  r..**.** <b>Goof
31bf0 79 20 49 6e 74 65 72 66 61 63 65 20 41 6c 65 72  y Interface Aler
31c00 74 3a 3c 2f 62 3e 20 49 6e 20 74 68 65 20 6c 65  t:</b> In the le
31c10 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20  gacy interface, 
31c20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 74 65 70  the sqlite3_step
31c30 28 29 0a 2a 2a 20 41 50 49 20 61 6c 77 61 79 73  ().** API always
31c40 20 72 65 74 75 72 6e 73 20 61 20 67 65 6e 65 72   returns a gener
31c50 69 63 20 65 72 72 6f 72 20 63 6f 64 65 2c 20 5b  ic error code, [
31c60 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c 20 66  SQLITE_ERROR], f
31c70 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79 0a 2a 2a 20  ollowing any.** 
31c80 65 72 72 6f 72 20 6f 74 68 65 72 20 74 68 61 6e  error other than
31c90 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 61   [SQLITE_BUSY] a
31ca0 6e 64 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53  nd [SQLITE_MISUS
31cb0 45 5d 2e 20 20 59 6f 75 20 6d 75 73 74 20 63 61  E].  You must ca
31cc0 6c 6c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72  ll.** [sqlite3_r
31cd0 65 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69  eset()] or [sqli
31ce0 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20  te3_finalize()] 
31cf0 69 6e 20 6f 72 64 65 72 20 74 6f 20 66 69 6e 64  in order to find
31d00 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20 73   one of the.** s
31d10 70 65 63 69 66 69 63 20 5b 65 72 72 6f 72 20 63  pecific [error c
31d20 6f 64 65 73 5d 20 74 68 61 74 20 62 65 74 74 65  odes] that bette
31d30 72 20 64 65 73 63 72 69 62 65 73 20 74 68 65 20  r describes the 
31d40 65 72 72 6f 72 2e 0a 2a 2a 20 57 65 20 61 64 6d  error..** We adm
31d50 69 74 20 74 68 61 74 20 74 68 69 73 20 69 73 20  it that this is 
31d60 61 20 67 6f 6f 66 79 20 64 65 73 69 67 6e 2e 20  a goofy design. 
31d70 20 54 68 65 20 70 72 6f 62 6c 65 6d 20 68 61 73   The problem has
31d80 20 62 65 65 6e 20 66 69 78 65 64 0a 2a 2a 20 77   been fixed.** w
31d90 69 74 68 20 74 68 65 20 22 76 32 22 20 69 6e 74  ith the "v2" int
31da0 65 72 66 61 63 65 2e 20 20 49 66 20 79 6f 75 20  erface.  If you 
31db0 70 72 65 70 61 72 65 20 61 6c 6c 20 6f 66 20 79  prepare all of y
31dc0 6f 75 72 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  our SQL statemen
31dd0 74 73 0a 2a 2a 20 75 73 69 6e 67 20 65 69 74 68  ts.** using eith
31de0 65 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  er [sqlite3_prep
31df0 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71  are_v2()] or [sq
31e00 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
31e10 76 32 28 29 5d 20 69 6e 73 74 65 61 64 0a 2a 2a  v2()] instead.**
31e20 20 6f 66 20 74 68 65 20 6c 65 67 61 63 79 20 5b   of the legacy [
31e30 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28  sqlite3_prepare(
31e40 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
31e50 70 72 65 70 61 72 65 31 36 28 29 5d 20 69 6e 74  prepare16()] int
31e60 65 72 66 61 63 65 73 2c 0a 2a 2a 20 74 68 65 6e  erfaces,.** then
31e70 20 74 68 65 20 6d 6f 72 65 20 73 70 65 63 69 66   the more specif
31e80 69 63 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d  ic [error codes]
31e90 20 61 72 65 20 72 65 74 75 72 6e 65 64 20 64 69   are returned di
31ea0 72 65 63 74 6c 79 0a 2a 2a 20 62 79 20 73 71 6c  rectly.** by sql
31eb0 69 74 65 33 5f 73 74 65 70 28 29 2e 20 20 54 68  ite3_step().  Th
31ec0 65 20 75 73 65 20 6f 66 20 74 68 65 20 22 76 32  e use of the "v2
31ed0 22 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 72  " interface is r
31ee0 65 63 6f 6d 6d 65 6e 64 65 64 2e 0a 2a 2f 0a 53  ecommended..*/.S
31ef0 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
31f00 6c 69 74 65 33 5f 73 74 65 70 28 73 71 6c 69 74  lite3_step(sqlit
31f10 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a  e3_stmt*);../*.*
31f20 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62  * CAPI3REF: Numb
31f30 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e  er of columns in
31f40 20 61 20 72 65 73 75 6c 74 20 73 65 74 0a 2a 2a   a result set.**
31f50 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
31f60 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  _stmt.**.** ^The
31f70 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f   sqlite3_data_co
31f80 75 6e 74 28 50 29 20 69 6e 74 65 72 66 61 63 65  unt(P) interface
31f90 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d   returns the num
31fa0 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69  ber of columns i
31fb0 6e 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74  n the.** current
31fc0 20 72 6f 77 20 6f 66 20 74 68 65 20 72 65 73 75   row of the resu
31fd0 6c 74 20 73 65 74 20 6f 66 20 5b 70 72 65 70 61  lt set of [prepa
31fe0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 50  red statement] P
31ff0 2e 0a 2a 2a 20 5e 49 66 20 70 72 65 70 61 72 65  ..** ^If prepare
32000 64 20 73 74 61 74 65 6d 65 6e 74 20 50 20 64 6f  d statement P do
32010 65 73 20 6e 6f 74 20 68 61 76 65 20 72 65 73 75  es not have resu
32020 6c 74 73 20 72 65 61 64 79 20 74 6f 20 72 65 74  lts ready to ret
32030 75 72 6e 0a 2a 2a 20 28 76 69 61 20 63 61 6c 6c  urn.** (via call
32040 73 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  s to the [sqlite
32050 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 20 7c 20 73  3_column_int | s
32060 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 2a 28  qlite3_column_*(
32070 29 5d 20 6f 66 0a 2a 2a 20 69 6e 74 65 72 66 61  )] of.** interfa
32080 63 65 73 29 20 74 68 65 6e 20 73 71 6c 69 74 65  ces) then sqlite
32090 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 20  3_data_count(P) 
320a0 72 65 74 75 72 6e 73 20 30 2e 0a 2a 2a 20 5e 54  returns 0..** ^T
320b0 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f  he sqlite3_data_
320c0 63 6f 75 6e 74 28 50 29 20 72 6f 75 74 69 6e 65  count(P) routine
320d0 20 61 6c 73 6f 20 72 65 74 75 72 6e 73 20 30 20   also returns 0 
320e0 69 66 20 50 20 69 73 20 61 20 4e 55 4c 4c 20 70  if P is a NULL p
320f0 6f 69 6e 74 65 72 2e 0a 2a 2a 20 5e 54 68 65 20  ointer..** ^The 
32100 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75  sqlite3_data_cou
32110 6e 74 28 50 29 20 72 6f 75 74 69 6e 65 20 72 65  nt(P) routine re
32120 74 75 72 6e 73 20 30 20 69 66 20 74 68 65 20 70  turns 0 if the p
32130 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 0a  revious call to.
32140 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  ** [sqlite3_step
32150 5d 28 50 29 20 72 65 74 75 72 6e 65 64 20 5b 53  ](P) returned [S
32160 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20 20 5e 54  QLITE_DONE].  ^T
32170 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f  he sqlite3_data_
32180 63 6f 75 6e 74 28 50 29 0a 2a 2a 20 77 69 6c 6c  count(P).** will
32190 20 72 65 74 75 72 6e 20 6e 6f 6e 2d 7a 65 72 6f   return non-zero
321a0 20 69 66 20 70 72 65 76 69 6f 75 73 20 63 61 6c   if previous cal
321b0 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74  l to [sqlite3_st
321c0 65 70 5d 28 50 29 20 72 65 74 75 72 6e 65 64 0a  ep](P) returned.
321d0 2a 2a 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c  ** [SQLITE_ROW],
321e0 20 65 78 63 65 70 74 20 69 6e 20 74 68 65 20 63   except in the c
321f0 61 73 65 20 6f 66 20 74 68 65 20 5b 50 52 41 47  ase of the [PRAG
32200 4d 41 20 69 6e 63 72 65 6d 65 6e 74 61 6c 5f 76  MA incremental_v
32210 61 63 75 75 6d 5d 0a 2a 2a 20 77 68 65 72 65 20  acuum].** where 
32220 69 74 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e  it always return
32230 73 20 7a 65 72 6f 20 73 69 6e 63 65 20 65 61 63  s zero since eac
32240 68 20 73 74 65 70 20 6f 66 20 74 68 61 74 20 6d  h step of that m
32250 75 6c 74 69 2d 73 74 65 70 0a 2a 2a 20 70 72 61  ulti-step.** pra
32260 67 6d 61 20 72 65 74 75 72 6e 73 20 30 20 63 6f  gma returns 0 co
32270 6c 75 6d 6e 73 20 6f 66 20 64 61 74 61 2e 0a 2a  lumns of data..*
32280 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b  *.** See also: [
32290 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63  sqlite3_column_c
322a0 6f 75 6e 74 28 29 5d 0a 2a 2f 0a 53 51 4c 49 54  ount()].*/.SQLIT
322b0 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
322c0 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 73 71 6c  3_data_count(sql
322d0 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74  ite3_stmt *pStmt
322e0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
322f0 45 46 3a 20 46 75 6e 64 61 6d 65 6e 74 61 6c 20  EF: Fundamental 
32300 44 61 74 61 74 79 70 65 73 0a 2a 2a 20 4b 45 59  Datatypes.** KEY
32310 57 4f 52 44 53 3a 20 53 51 4c 49 54 45 5f 54 45  WORDS: SQLITE_TE
32320 58 54 0a 2a 2a 0a 2a 2a 20 5e 28 45 76 65 72 79  XT.**.** ^(Every
32330 20 76 61 6c 75 65 20 69 6e 20 53 51 4c 69 74 65   value in SQLite
32340 20 68 61 73 20 6f 6e 65 20 6f 66 20 66 69 76 65   has one of five
32350 20 66 75 6e 64 61 6d 65 6e 74 61 6c 20 64 61 74   fundamental dat
32360 61 74 79 70 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75  atypes:.**.** <u
32370 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 69  l>.** <li> 64-bi
32380 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72  t signed integer
32390 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 74 20  .** <li> 64-bit 
323a0 49 45 45 45 20 66 6c 6f 61 74 69 6e 67 20 70 6f  IEEE floating po
323b0 69 6e 74 20 6e 75 6d 62 65 72 0a 2a 2a 20 3c 6c  int number.** <l
323c0 69 3e 20 73 74 72 69 6e 67 0a 2a 2a 20 3c 6c 69  i> string.** <li
323d0 3e 20 42 4c 4f 42 0a 2a 2a 20 3c 6c 69 3e 20 4e  > BLOB.** <li> N
323e0 55 4c 4c 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a  ULL.** </ul>)^.*
323f0 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74  *.** These const
32400 61 6e 74 73 20 61 72 65 20 63 6f 64 65 73 20 66  ants are codes f
32410 6f 72 20 65 61 63 68 20 6f 66 20 74 68 6f 73 65  or each of those
32420 20 74 79 70 65 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f   types..**.** No
32430 74 65 20 74 68 61 74 20 74 68 65 20 53 51 4c 49  te that the SQLI
32440 54 45 5f 54 45 58 54 20 63 6f 6e 73 74 61 6e 74  TE_TEXT constant
32450 20 77 61 73 20 61 6c 73 6f 20 75 73 65 64 20 69   was also used i
32460 6e 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e  n SQLite version
32470 20 32 0a 2a 2a 20 66 6f 72 20 61 20 63 6f 6d 70   2.** for a comp
32480 6c 65 74 65 6c 79 20 64 69 66 66 65 72 65 6e 74  letely different
32490 20 6d 65 61 6e 69 6e 67 2e 20 20 53 6f 66 74 77   meaning.  Softw
324a0 61 72 65 20 74 68 61 74 20 6c 69 6e 6b 73 20 61  are that links a
324b0 67 61 69 6e 73 74 20 62 6f 74 68 0a 2a 2a 20 53  gainst both.** S
324c0 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 32 20  QLite version 2 
324d0 61 6e 64 20 53 51 4c 69 74 65 20 76 65 72 73 69  and SQLite versi
324e0 6f 6e 20 33 20 73 68 6f 75 6c 64 20 75 73 65 20  on 3 should use 
324f0 53 51 4c 49 54 45 33 5f 54 45 58 54 2c 20 6e 6f  SQLITE3_TEXT, no
32500 74 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 45 58 54  t.** SQLITE_TEXT
32510 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
32520 49 54 45 5f 49 4e 54 45 47 45 52 20 20 31 0a 23  ITE_INTEGER  1.#
32530 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 4c  define SQLITE_FL
32540 4f 41 54 20 20 20 20 32 0a 23 64 65 66 69 6e 65  OAT    2.#define
32550 20 53 51 4c 49 54 45 5f 42 4c 4f 42 20 20 20 20   SQLITE_BLOB    
32560 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   4.#define SQLIT
32570 45 5f 4e 55 4c 4c 20 20 20 20 20 35 0a 23 69 66  E_NULL     5.#if
32580 64 65 66 20 53 51 4c 49 54 45 5f 54 45 58 54 0a  def SQLITE_TEXT.
32590 23 20 75 6e 64 65 66 20 53 51 4c 49 54 45 5f 54  # undef SQLITE_T
325a0 45 58 54 0a 23 65 6c 73 65 0a 23 20 64 65 66 69  EXT.#else.# defi
325b0 6e 65 20 53 51 4c 49 54 45 5f 54 45 58 54 20 20  ne SQLITE_TEXT  
325c0 20 20 20 33 0a 23 65 6e 64 69 66 0a 23 64 65 66     3.#endif.#def
325d0 69 6e 65 20 53 51 4c 49 54 45 33 5f 54 45 58 54  ine SQLITE3_TEXT
325e0 20 20 20 20 20 33 0a 0a 2f 2a 0a 2a 2a 20 43 41       3../*.** CA
325f0 50 49 33 52 45 46 3a 20 52 65 73 75 6c 74 20 56  PI3REF: Result V
32600 61 6c 75 65 73 20 46 72 6f 6d 20 41 20 51 75 65  alues From A Que
32610 72 79 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  ry.** KEYWORDS: 
32620 7b 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 66  {column access f
32630 75 6e 63 74 69 6f 6e 73 7d 0a 2a 2a 20 4d 45 54  unctions}.** MET
32640 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d  HOD: sqlite3_stm
32650 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72  t.**.** ^These r
32660 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 69  outines return i
32670 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74  nformation about
32680 20 61 20 73 69 6e 67 6c 65 20 63 6f 6c 75 6d 6e   a single column
32690 20 6f 66 20 74 68 65 20 63 75 72 72 65 6e 74 0a   of the current.
326a0 2a 2a 20 72 65 73 75 6c 74 20 72 6f 77 20 6f 66  ** result row of
326b0 20 61 20 71 75 65 72 79 2e 20 20 5e 49 6e 20 65   a query.  ^In e
326c0 76 65 72 79 20 63 61 73 65 20 74 68 65 20 66 69  very case the fi
326d0 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20  rst argument is 
326e0 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20  a pointer.** to 
326f0 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
32700 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 69 73  atement] that is
32710 20 62 65 69 6e 67 20 65 76 61 6c 75 61 74 65 64   being evaluated
32720 20 28 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73   (the [sqlite3_s
32730 74 6d 74 2a 5d 0a 2a 2a 20 74 68 61 74 20 77 61  tmt*].** that wa
32740 73 20 72 65 74 75 72 6e 65 64 20 66 72 6f 6d 20  s returned from 
32750 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
32760 5f 76 32 28 29 5d 20 6f 72 20 6f 6e 65 20 6f 66  _v2()] or one of
32770 20 69 74 73 20 76 61 72 69 61 6e 74 73 29 0a 2a   its variants).*
32780 2a 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64  * and the second
32790 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65   argument is the
327a0 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20 63 6f   index of the co
327b0 6c 75 6d 6e 20 66 6f 72 20 77 68 69 63 68 20 69  lumn for which i
327c0 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 73 68  nformation.** sh
327d0 6f 75 6c 64 20 62 65 20 72 65 74 75 72 6e 65 64  ould be returned
327e0 2e 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74 20  . ^The leftmost 
327f0 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72 65  column of the re
32800 73 75 6c 74 20 73 65 74 20 68 61 73 20 74 68 65  sult set has the
32810 20 69 6e 64 65 78 20 30 2e 0a 2a 2a 20 5e 54 68   index 0..** ^Th
32820 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75  e number of colu
32830 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 73 75 6c  mns in the resul
32840 74 20 63 61 6e 20 62 65 20 64 65 74 65 72 6d 69  t can be determi
32850 6e 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71  ned using.** [sq
32860 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75  lite3_column_cou
32870 6e 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  nt()]..**.** If 
32880 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  the SQL statemen
32890 74 20 64 6f 65 73 20 6e 6f 74 20 63 75 72 72 65  t does not curre
328a0 6e 74 6c 79 20 70 6f 69 6e 74 20 74 6f 20 61 20  ntly point to a 
328b0 76 61 6c 69 64 20 72 6f 77 2c 20 6f 72 20 69 66  valid row, or if
328c0 20 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69   the.** column i
328d0 6e 64 65 78 20 69 73 20 6f 75 74 20 6f 66 20 72  ndex is out of r
328e0 61 6e 67 65 2c 20 74 68 65 20 72 65 73 75 6c 74  ange, the result
328f0 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a   is undefined..*
32900 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
32910 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 63 61 6c   may only be cal
32920 6c 65 64 20 77 68 65 6e 20 74 68 65 20 6d 6f 73  led when the mos
32930 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f  t recent call to
32940 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  .** [sqlite3_ste
32950 70 28 29 5d 20 68 61 73 20 72 65 74 75 72 6e 65  p()] has returne
32960 64 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 61  d [SQLITE_ROW] a
32970 6e 64 20 6e 65 69 74 68 65 72 0a 2a 2a 20 5b 73  nd neither.** [s
32980 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
32990 6e 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e  nor [sqlite3_fin
329a0 61 6c 69 7a 65 28 29 5d 20 68 61 76 65 20 62 65  alize()] have be
329b0 65 6e 20 63 61 6c 6c 65 64 20 73 75 62 73 65 71  en called subseq
329c0 75 65 6e 74 6c 79 2e 0a 2a 2a 20 49 66 20 61 6e  uently..** If an
329d0 79 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69  y of these routi
329e0 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20 61  nes are called a
329f0 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 72 65  fter [sqlite3_re
32a00 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71  set()] or.** [sq
32a10 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
32a20 5d 20 6f 72 20 61 66 74 65 72 20 5b 73 71 6c 69  ] or after [sqli
32a30 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20  te3_step()] has 
32a40 72 65 74 75 72 6e 65 64 0a 2a 2a 20 73 6f 6d 65  returned.** some
32a50 74 68 69 6e 67 20 6f 74 68 65 72 20 74 68 61 6e  thing other than
32a60 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 74   [SQLITE_ROW], t
32a70 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 75  he results are u
32a80 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 49 66 20  ndefined..** If 
32a90 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
32aa0 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73   or [sqlite3_res
32ab0 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  et()] or [sqlite
32ac0 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 0a 2a 2a  3_finalize()].**
32ad0 20 61 72 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d   are called from
32ae0 20 61 20 64 69 66 66 65 72 65 6e 74 20 74 68 72   a different thr
32af0 65 61 64 20 77 68 69 6c 65 20 61 6e 79 20 6f 66  ead while any of
32b00 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 0a   these routines.
32b10 2a 2a 20 61 72 65 20 70 65 6e 64 69 6e 67 2c 20  ** are pending, 
32b20 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73  then the results
32b30 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a   are undefined..
32b40 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
32b50 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29  e3_column_type()
32b60 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
32b70 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f   the.** [SQLITE_
32b80 49 4e 54 45 47 45 52 20 7c 20 64 61 74 61 74 79  INTEGER | dataty
32b90 70 65 20 63 6f 64 65 5d 20 66 6f 72 20 74 68 65  pe code] for the
32ba0 20 69 6e 69 74 69 61 6c 20 64 61 74 61 20 74 79   initial data ty
32bb0 70 65 0a 2a 2a 20 6f 66 20 74 68 65 20 72 65 73  pe.** of the res
32bc0 75 6c 74 20 63 6f 6c 75 6d 6e 2e 20 20 5e 54 68  ult column.  ^Th
32bd0 65 20 72 65 74 75 72 6e 65 64 20 76 61 6c 75 65  e returned value
32be0 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49   is one of [SQLI
32bf0 54 45 5f 49 4e 54 45 47 45 52 5d 2c 0a 2a 2a 20  TE_INTEGER],.** 
32c00 5b 53 51 4c 49 54 45 5f 46 4c 4f 41 54 5d 2c 20  [SQLITE_FLOAT], 
32c10 5b 53 51 4c 49 54 45 5f 54 45 58 54 5d 2c 20 5b  [SQLITE_TEXT], [
32c20 53 51 4c 49 54 45 5f 42 4c 4f 42 5d 2c 20 6f 72  SQLITE_BLOB], or
32c30 20 5b 53 51 4c 49 54 45 5f 4e 55 4c 4c 5d 2e 20   [SQLITE_NULL]. 
32c40 20 54 68 65 20 76 61 6c 75 65 0a 2a 2a 20 72 65   The value.** re
32c50 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65  turned by sqlite
32c60 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20  3_column_type() 
32c70 69 73 20 6f 6e 6c 79 20 6d 65 61 6e 69 6e 67 66  is only meaningf
32c80 75 6c 20 69 66 20 6e 6f 20 74 79 70 65 0a 2a 2a  ul if no type.**
32c90 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 68 61 76   conversions hav
32ca0 65 20 6f 63 63 75 72 72 65 64 20 61 73 20 64 65  e occurred as de
32cb0 73 63 72 69 62 65 64 20 62 65 6c 6f 77 2e 20 20  scribed below.  
32cc0 41 66 74 65 72 20 61 20 74 79 70 65 20 63 6f 6e  After a type con
32cd0 76 65 72 73 69 6f 6e 2c 0a 2a 2a 20 74 68 65 20  version,.** the 
32ce0 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62  value returned b
32cf0 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  y sqlite3_column
32d00 5f 74 79 70 65 28 29 20 69 73 20 75 6e 64 65 66  _type() is undef
32d10 69 6e 65 64 2e 20 20 46 75 74 75 72 65 0a 2a 2a  ined.  Future.**
32d20 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c   versions of SQL
32d30 69 74 65 20 6d 61 79 20 63 68 61 6e 67 65 20 74  ite may change t
32d40 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20 73  he behavior of s
32d50 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79  qlite3_column_ty
32d60 70 65 28 29 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e  pe().** followin
32d70 67 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73  g a type convers
32d80 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  ion..**.** ^If t
32d90 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 42  he result is a B
32da0 4c 4f 42 20 6f 72 20 55 54 46 2d 38 20 73 74 72  LOB or UTF-8 str
32db0 69 6e 67 20 74 68 65 6e 20 74 68 65 20 73 71 6c  ing then the sql
32dc0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
32dd0 73 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72  s().** routine r
32de0 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65  eturns the numbe
32df0 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68  r of bytes in th
32e00 61 74 20 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e  at BLOB or strin
32e10 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65  g..** ^If the re
32e20 73 75 6c 74 20 69 73 20 61 20 55 54 46 2d 31 36  sult is a UTF-16
32e30 20 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 73 71   string, then sq
32e40 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
32e50 65 73 28 29 20 63 6f 6e 76 65 72 74 73 0a 2a 2a  es() converts.**
32e60 20 74 68 65 20 73 74 72 69 6e 67 20 74 6f 20 55   the string to U
32e70 54 46 2d 38 20 61 6e 64 20 74 68 65 6e 20 72 65  TF-8 and then re
32e80 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72  turns the number
32e90 20 6f 66 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 49   of bytes..** ^I
32ea0 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20  f the result is 
32eb0 61 20 6e 75 6d 65 72 69 63 20 76 61 6c 75 65 20  a numeric value 
32ec0 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c  then sqlite3_col
32ed0 75 6d 6e 5f 62 79 74 65 73 28 29 20 75 73 65 73  umn_bytes() uses
32ee0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70  .** [sqlite3_snp
32ef0 72 69 6e 74 66 28 29 5d 20 74 6f 20 63 6f 6e 76  rintf()] to conv
32f00 65 72 74 20 74 68 61 74 20 76 61 6c 75 65 20 74  ert that value t
32f10 6f 20 61 20 55 54 46 2d 38 20 73 74 72 69 6e 67  o a UTF-8 string
32f20 20 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a 2a 20   and returns.** 
32f30 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  the number of by
32f40 74 65 73 20 69 6e 20 74 68 61 74 20 73 74 72 69  tes in that stri
32f50 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72  ng..** ^If the r
32f60 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c 2c 20 74  esult is NULL, t
32f70 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  hen sqlite3_colu
32f80 6d 6e 5f 62 79 74 65 73 28 29 20 72 65 74 75 72  mn_bytes() retur
32f90 6e 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e  ns zero..**.** ^
32fa0 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73  If the result is
32fb0 20 61 20 42 4c 4f 42 20 6f 72 20 55 54 46 2d 31   a BLOB or UTF-1
32fc0 36 20 73 74 72 69 6e 67 20 74 68 65 6e 20 74 68  6 string then th
32fd0 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  e sqlite3_column
32fe0 5f 62 79 74 65 73 31 36 28 29 0a 2a 2a 20 72 6f  _bytes16().** ro
32ff0 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68  utine returns th
33000 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  e number of byte
33010 73 20 69 6e 20 74 68 61 74 20 42 4c 4f 42 20 6f  s in that BLOB o
33020 72 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66  r string..** ^If
33030 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61   the result is a
33040 20 55 54 46 2d 38 20 73 74 72 69 6e 67 2c 20 74   UTF-8 string, t
33050 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  hen sqlite3_colu
33060 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 63 6f 6e  mn_bytes16() con
33070 76 65 72 74 73 0a 2a 2a 20 74 68 65 20 73 74 72  verts.** the str
33080 69 6e 67 20 74 6f 20 55 54 46 2d 31 36 20 61 6e  ing to UTF-16 an
33090 64 20 74 68 65 6e 20 72 65 74 75 72 6e 73 20 74  d then returns t
330a0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  he number of byt
330b0 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72  es..** ^If the r
330c0 65 73 75 6c 74 20 69 73 20 61 20 6e 75 6d 65 72  esult is a numer
330d0 69 63 20 76 61 6c 75 65 20 74 68 65 6e 20 73 71  ic value then sq
330e0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
330f0 65 73 31 36 28 29 20 75 73 65 73 0a 2a 2a 20 5b  es16() uses.** [
33100 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66  sqlite3_snprintf
33110 28 29 5d 20 74 6f 20 63 6f 6e 76 65 72 74 20 74  ()] to convert t
33120 68 61 74 20 76 61 6c 75 65 20 74 6f 20 61 20 55  hat value to a U
33130 54 46 2d 31 36 20 73 74 72 69 6e 67 20 61 6e 64  TF-16 string and
33140 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20   returns.** the 
33150 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
33160 69 6e 20 74 68 61 74 20 73 74 72 69 6e 67 2e 0a  in that string..
33170 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c  ** ^If the resul
33180 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20  t is NULL, then 
33190 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
331a0 79 74 65 73 31 36 28 29 20 72 65 74 75 72 6e 73  ytes16() returns
331b0 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68   zero..**.** ^Th
331c0 65 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e 65  e values returne
331d0 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f  d by [sqlite3_co
331e0 6c 75 6d 6e 5f 62 79 74 65 73 28 29 5d 20 61 6e  lumn_bytes()] an
331f0 64 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  d .** [sqlite3_c
33200 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 5d  olumn_bytes16()]
33210 20 64 6f 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20   do not include 
33220 74 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61  the zero termina
33230 74 6f 72 73 20 61 74 20 74 68 65 20 65 6e 64 0a  tors at the end.
33240 2a 2a 20 6f 66 20 74 68 65 20 73 74 72 69 6e 67  ** of the string
33250 2e 20 20 5e 46 6f 72 20 63 6c 61 72 69 74 79 3a  .  ^For clarity:
33260 20 74 68 65 20 76 61 6c 75 65 73 20 72 65 74 75   the values retu
33270 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69  rned by.** [sqli
33280 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
33290 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
332a0 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
332b0 29 5d 20 61 72 65 20 74 68 65 20 6e 75 6d 62 65  )] are the numbe
332c0 72 20 6f 66 0a 2a 2a 20 62 79 74 65 73 20 69 6e  r of.** bytes in
332d0 20 74 68 65 20 73 74 72 69 6e 67 2c 20 6e 6f 74   the string, not
332e0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63   the number of c
332f0 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a  haracters..**.**
33300 20 5e 53 74 72 69 6e 67 73 20 72 65 74 75 72 6e   ^Strings return
33310 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f  ed by sqlite3_co
33320 6c 75 6d 6e 5f 74 65 78 74 28 29 20 61 6e 64 20  lumn_text() and 
33330 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
33340 65 78 74 31 36 28 29 2c 0a 2a 2a 20 65 76 65 6e  ext16(),.** even
33350 20 65 6d 70 74 79 20 73 74 72 69 6e 67 73 2c 20   empty strings, 
33360 61 72 65 20 61 6c 77 61 79 73 20 7a 65 72 6f 2d  are always zero-
33370 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 5e 54 68  terminated.  ^Th
33380 65 20 72 65 74 75 72 6e 0a 2a 2a 20 76 61 6c 75  e return.** valu
33390 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 63  e from sqlite3_c
333a0 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f 72  olumn_blob() for
333b0 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 42   a zero-length B
333c0 4c 4f 42 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  LOB is a NULL po
333d0 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e  inter..**.** <b>
333e0 57 61 72 6e 69 6e 67 3a 3c 2f 62 3e 20 5e 54 68  Warning:</b> ^Th
333f0 65 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65  e object returne
33400 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f  d by [sqlite3_co
33410 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73  lumn_value()] is
33420 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63   an.** [unprotec
33430 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
33440 65 5d 20 6f 62 6a 65 63 74 2e 20 20 49 6e 20 61  e] object.  In a
33450 20 6d 75 6c 74 69 74 68 72 65 61 64 65 64 20 65   multithreaded e
33460 6e 76 69 72 6f 6e 6d 65 6e 74 2c 0a 2a 2a 20 61  nvironment,.** a
33470 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71  n unprotected sq
33480 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
33490 63 74 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 75  ct may only be u
334a0 73 65 64 20 73 61 66 65 6c 79 20 77 69 74 68 0a  sed safely with.
334b0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  ** [sqlite3_bind
334c0 5f 76 61 6c 75 65 28 29 5d 20 61 6e 64 20 5b 73  _value()] and [s
334d0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61  qlite3_result_va
334e0 6c 75 65 28 29 5d 2e 0a 2a 2a 20 49 66 20 74 68  lue()]..** If th
334f0 65 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73  e [unprotected s
33500 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
33510 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20 62 79  ject returned by
33520 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  .** [sqlite3_col
33530 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20  umn_value()] is 
33540 75 73 65 64 20 69 6e 20 61 6e 79 20 6f 74 68 65  used in any othe
33550 72 20 77 61 79 2c 20 69 6e 63 6c 75 64 69 6e 67  r way, including
33560 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 72 6f 75   calls.** to rou
33570 74 69 6e 65 73 20 6c 69 6b 65 20 5b 73 71 6c 69  tines like [sqli
33580 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28 29 5d  te3_value_int()]
33590 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  , [sqlite3_value
335a0 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20  _text()],.** or 
335b0 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62  [sqlite3_value_b
335c0 79 74 65 73 28 29 5d 2c 20 74 68 65 20 62 65 68  ytes()], the beh
335d0 61 76 69 6f 72 20 69 73 20 6e 6f 74 20 74 68 72  avior is not thr
335e0 65 61 64 73 61 66 65 2e 0a 2a 2a 0a 2a 2a 20 54  eadsafe..**.** T
335f0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 74  hese routines at
33600 74 65 6d 70 74 20 74 6f 20 63 6f 6e 76 65 72 74  tempt to convert
33610 20 74 68 65 20 76 61 6c 75 65 20 77 68 65 72 65   the value where
33620 20 61 70 70 72 6f 70 72 69 61 74 65 2e 20 20 5e   appropriate.  ^
33630 46 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20  For.** example, 
33640 69 66 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20  if the internal 
33650 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 69  representation i
33660 73 20 46 4c 4f 41 54 20 61 6e 64 20 61 20 74 65  s FLOAT and a te
33670 78 74 20 72 65 73 75 6c 74 0a 2a 2a 20 69 73 20  xt result.** is 
33680 72 65 71 75 65 73 74 65 64 2c 20 5b 73 71 6c 69  requested, [sqli
33690 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20  te3_snprintf()] 
336a0 69 73 20 75 73 65 64 20 69 6e 74 65 72 6e 61 6c  is used internal
336b0 6c 79 20 74 6f 20 70 65 72 66 6f 72 6d 20 74 68  ly to perform th
336c0 65 0a 2a 2a 20 63 6f 6e 76 65 72 73 69 6f 6e 20  e.** conversion 
336d0 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20  automatically.  
336e0 5e 28 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  ^(The following 
336f0 74 61 62 6c 65 20 64 65 74 61 69 6c 73 20 74 68  table details th
33700 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 0a 2a 2a  e conversions.**
33710 20 74 68 61 74 20 61 72 65 20 61 70 70 6c 69 65   that are applie
33720 64 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71  d:.**.** <blockq
33730 75 6f 74 65 3e 0a 2a 2a 20 3c 74 61 62 6c 65 20  uote>.** <table 
33740 62 6f 72 64 65 72 3d 22 31 22 3e 0a 2a 2a 20 3c  border="1">.** <
33750 74 72 3e 3c 74 68 3e 20 49 6e 74 65 72 6e 61 6c  tr><th> Internal
33760 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e 20 52 65  <br>Type <th> Re
33770 71 75 65 73 74 65 64 3c 62 72 3e 54 79 70 65 20  quested<br>Type 
33780 3c 74 68 3e 20 20 43 6f 6e 76 65 72 73 69 6f 6e  <th>  Conversion
33790 0a 2a 2a 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  .**.** <tr><td> 
337a0 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 49 4e   NULL    <td> IN
337b0 54 45 47 45 52 20 20 20 3c 74 64 3e 20 52 65 73  TEGER   <td> Res
337c0 75 6c 74 20 69 73 20 30 0a 2a 2a 20 3c 74 72 3e  ult is 0.** <tr>
337d0 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74  <td>  NULL    <t
337e0 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64  d>  FLOAT    <td
337f0 3e 20 52 65 73 75 6c 74 20 69 73 20 30 2e 30 0a  > Result is 0.0.
33800 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c  ** <tr><td>  NUL
33810 4c 20 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54  L    <td>   TEXT
33820 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20      <td> Result 
33830 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  is a NULL pointe
33840 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e  r.** <tr><td>  N
33850 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 20 42 4c  ULL    <td>   BL
33860 4f 42 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c  OB    <td> Resul
33870 74 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  t is a NULL poin
33880 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  ter.** <tr><td> 
33890 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20 46  INTEGER  <td>  F
338a0 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 43 6f 6e  LOAT    <td> Con
338b0 76 65 72 74 20 66 72 6f 6d 20 69 6e 74 65 67 65  vert from intege
338c0 72 20 74 6f 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74  r to float.** <t
338d0 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20  r><td> INTEGER  
338e0 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c  <td>   TEXT    <
338f0 74 64 3e 20 41 53 43 49 49 20 72 65 6e 64 65 72  td> ASCII render
33900 69 6e 67 20 6f 66 20 74 68 65 20 69 6e 74 65 67  ing of the integ
33910 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49  er.** <tr><td> I
33920 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20 20 42  NTEGER  <td>   B
33930 4c 4f 42 20 20 20 20 3c 74 64 3e 20 53 61 6d 65  LOB    <td> Same
33940 20 61 73 20 49 4e 54 45 47 45 52 2d 3e 54 45 58   as INTEGER->TEX
33950 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46  T.** <tr><td>  F
33960 4c 4f 41 54 20 20 20 3c 74 64 3e 20 49 4e 54 45  LOAT   <td> INTE
33970 47 45 52 20 20 20 3c 74 64 3e 20 5b 43 41 53 54  GER   <td> [CAST
33980 5d 20 74 6f 20 49 4e 54 45 47 45 52 0a 2a 2a 20  ] to INTEGER.** 
33990 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20  <tr><td>  FLOAT 
339a0 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20    <td>   TEXT   
339b0 20 3c 74 64 3e 20 41 53 43 49 49 20 72 65 6e 64   <td> ASCII rend
339c0 65 72 69 6e 67 20 6f 66 20 74 68 65 20 66 6c 6f  ering of the flo
339d0 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  at.** <tr><td>  
339e0 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20 20 42  FLOAT   <td>   B
339f0 4c 4f 42 20 20 20 20 3c 74 64 3e 20 5b 43 41 53  LOB    <td> [CAS
33a00 54 5d 20 74 6f 20 42 4c 4f 42 0a 2a 2a 20 3c 74  T] to BLOB.** <t
33a10 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20  r><td>  TEXT    
33a20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c  <td> INTEGER   <
33a30 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20 49 4e  td> [CAST] to IN
33a40 54 45 47 45 52 0a 2a 2a 20 3c 74 72 3e 3c 74 64  TEGER.** <tr><td
33a50 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20  >  TEXT    <td> 
33a60 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 5b   FLOAT    <td> [
33a70 43 41 53 54 5d 20 74 6f 20 52 45 41 4c 0a 2a 2a  CAST] to REAL.**
33a80 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20   <tr><td>  TEXT 
33a90 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20     <td>   BLOB  
33aa0 20 20 3c 74 64 3e 20 4e 6f 20 63 68 61 6e 67 65    <td> No change
33ab0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c  .** <tr><td>  BL
33ac0 4f 42 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47  OB    <td> INTEG
33ad0 45 52 20 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d  ER   <td> [CAST]
33ae0 20 74 6f 20 49 4e 54 45 47 45 52 0a 2a 2a 20 3c   to INTEGER.** <
33af0 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20  tr><td>  BLOB   
33b00 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20   <td>  FLOAT    
33b10 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20 52  <td> [CAST] to R
33b20 45 41 4c 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  EAL.** <tr><td> 
33b30 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 20 20   BLOB    <td>   
33b40 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41 64 64  TEXT    <td> Add
33b50 20 61 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74   a zero terminat
33b60 6f 72 20 69 66 20 6e 65 65 64 65 64 0a 2a 2a 20  or if needed.** 
33b70 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 20 3c 2f 62 6c  </table>.** </bl
33b80 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a  ockquote>)^.**.*
33b90 2a 20 4e 6f 74 65 20 74 68 61 74 20 77 68 65 6e  * Note that when
33ba0 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e   type conversion
33bb0 73 20 6f 63 63 75 72 2c 20 70 6f 69 6e 74 65 72  s occur, pointer
33bc0 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 70 72  s returned by pr
33bd0 69 6f 72 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20  ior.** calls to 
33be0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
33bf0 6c 6f 62 28 29 2c 20 73 71 6c 69 74 65 33 5f 63  lob(), sqlite3_c
33c00 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 20 61 6e  olumn_text(), an
33c10 64 2f 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  d/or.** sqlite3_
33c20 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20  column_text16() 
33c30 6d 61 79 20 62 65 20 69 6e 76 61 6c 69 64 61 74  may be invalidat
33c40 65 64 2e 0a 2a 2a 20 54 79 70 65 20 63 6f 6e 76  ed..** Type conv
33c50 65 72 73 69 6f 6e 73 20 61 6e 64 20 70 6f 69 6e  ersions and poin
33c60 74 65 72 20 69 6e 76 61 6c 69 64 61 74 69 6f 6e  ter invalidation
33c70 73 20 6d 69 67 68 74 20 6f 63 63 75 72 0a 2a 2a  s might occur.**
33c80 20 69 6e 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e   in the followin
33c90 67 20 63 61 73 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c  g cases:.**.** <
33ca0 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20  ul>.** <li> The 
33cb0 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20  initial content 
33cc0 69 73 20 61 20 42 4c 4f 42 20 61 6e 64 20 73 71  is a BLOB and sq
33cd0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
33ce0 74 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73  t() or.**      s
33cf0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
33d00 78 74 31 36 28 29 20 69 73 20 63 61 6c 6c 65 64  xt16() is called
33d10 2e 20 20 41 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  .  A zero-termin
33d20 61 74 6f 72 20 6d 69 67 68 74 0a 2a 2a 20 20 20  ator might.**   
33d30 20 20 20 6e 65 65 64 20 74 6f 20 62 65 20 61 64     need to be ad
33d40 64 65 64 20 74 6f 20 74 68 65 20 73 74 72 69 6e  ded to the strin
33d50 67 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20  g.</li>.** <li> 
33d60 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74  The initial cont
33d70 65 6e 74 20 69 73 20 55 54 46 2d 38 20 74 65 78  ent is UTF-8 tex
33d80 74 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f  t and sqlite3_co
33d90 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 6f  lumn_bytes16() o
33da0 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 74 65  r.**      sqlite
33db0 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28  3_column_text16(
33dc0 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 54 68  ) is called.  Th
33dd0 65 20 63 6f 6e 74 65 6e 74 20 6d 75 73 74 20 62  e content must b
33de0 65 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 20  e converted.**  
33df0 20 20 20 20 74 6f 20 55 54 46 2d 31 36 2e 3c 2f      to UTF-16.</
33e00 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20  li>.** <li> The 
33e10 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20  initial content 
33e20 69 73 20 55 54 46 2d 31 36 20 74 65 78 74 20 61  is UTF-16 text a
33e30 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nd sqlite3_colum
33e40 6e 5f 62 79 74 65 73 28 29 20 6f 72 0a 2a 2a 20  n_bytes() or.** 
33e50 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c       sqlite3_col
33e60 75 6d 6e 5f 74 65 78 74 28 29 20 69 73 20 63 61  umn_text() is ca
33e70 6c 6c 65 64 2e 20 20 54 68 65 20 63 6f 6e 74 65  lled.  The conte
33e80 6e 74 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65  nt must be conve
33e90 72 74 65 64 0a 2a 2a 20 20 20 20 20 20 74 6f 20  rted.**      to 
33ea0 55 54 46 2d 38 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c  UTF-8.</li>.** <
33eb0 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e 76  /ul>.**.** ^Conv
33ec0 65 72 73 69 6f 6e 73 20 62 65 74 77 65 65 6e 20  ersions between 
33ed0 55 54 46 2d 31 36 62 65 20 61 6e 64 20 55 54 46  UTF-16be and UTF
33ee0 2d 31 36 6c 65 20 61 72 65 20 61 6c 77 61 79 73  -16le are always
33ef0 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65 20 61   done in place a
33f00 6e 64 20 64 6f 0a 2a 2a 20 6e 6f 74 20 69 6e 76  nd do.** not inv
33f10 61 6c 69 64 61 74 65 20 61 20 70 72 69 6f 72 20  alidate a prior 
33f20 70 6f 69 6e 74 65 72 2c 20 74 68 6f 75 67 68 20  pointer, though 
33f30 6f 66 20 63 6f 75 72 73 65 20 74 68 65 20 63 6f  of course the co
33f40 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 62 75 66  ntent of the buf
33f50 66 65 72 0a 2a 2a 20 74 68 61 74 20 74 68 65 20  fer.** that the 
33f60 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 20 72 65  prior pointer re
33f70 66 65 72 65 6e 63 65 73 20 77 69 6c 6c 20 68 61  ferences will ha
33f80 76 65 20 62 65 65 6e 20 6d 6f 64 69 66 69 65 64  ve been modified
33f90 2e 20 20 4f 74 68 65 72 20 6b 69 6e 64 73 0a 2a  .  Other kinds.*
33fa0 2a 20 6f 66 20 63 6f 6e 76 65 72 73 69 6f 6e 20  * of conversion 
33fb0 61 72 65 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63  are done in plac
33fc0 65 20 77 68 65 6e 20 69 74 20 69 73 20 70 6f 73  e when it is pos
33fd0 73 69 62 6c 65 2c 20 62 75 74 20 73 6f 6d 65 74  sible, but somet
33fe0 69 6d 65 73 20 74 68 65 79 0a 2a 2a 20 61 72 65  imes they.** are
33ff0 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 61 6e   not possible an
34000 64 20 69 6e 20 74 68 6f 73 65 20 63 61 73 65 73  d in those cases
34010 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 73 20   prior pointers 
34020 61 72 65 20 69 6e 76 61 6c 69 64 61 74 65 64 2e  are invalidated.
34030 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 61 66 65 73  .**.** The safes
34040 74 20 70 6f 6c 69 63 79 20 69 73 20 74 6f 20 69  t policy is to i
34050 6e 76 6f 6b 65 20 74 68 65 73 65 20 72 6f 75 74  nvoke these rout
34060 69 6e 65 73 0a 2a 2a 20 69 6e 20 6f 6e 65 20 6f  ines.** in one o
34070 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  f the following 
34080 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  ways:.**.** <ul>
34090 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33  .**  <li>sqlite3
340a0 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 66  _column_text() f
340b0 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74  ollowed by sqlit
340c0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
340d0 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73  )</li>.**  <li>s
340e0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c  qlite3_column_bl
340f0 6f 62 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79  ob() followed by
34100 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
34110 62 79 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20  bytes()</li>.** 
34120 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c   <li>sqlite3_col
34130 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 66 6f 6c  umn_text16() fol
34140 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65 33  lowed by sqlite3
34150 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
34160 29 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a  )</li>.** </ul>.
34170 2a 2a 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 20 77  **.** In other w
34180 6f 72 64 73 2c 20 79 6f 75 20 73 68 6f 75 6c 64  ords, you should
34190 20 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f 63 6f   call sqlite3_co
341a0 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 0a 2a 2a 20  lumn_text(),.** 
341b0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
341c0 6c 6f 62 28 29 2c 20 6f 72 20 73 71 6c 69 74 65  lob(), or sqlite
341d0 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28  3_column_text16(
341e0 29 20 66 69 72 73 74 20 74 6f 20 66 6f 72 63 65  ) first to force
341f0 20 74 68 65 20 72 65 73 75 6c 74 0a 2a 2a 20 69   the result.** i
34200 6e 74 6f 20 74 68 65 20 64 65 73 69 72 65 64 20  nto the desired 
34210 66 6f 72 6d 61 74 2c 20 74 68 65 6e 20 69 6e 76  format, then inv
34220 6f 6b 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  oke sqlite3_colu
34230 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72 0a 2a 2a  mn_bytes() or.**
34240 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
34250 62 79 74 65 73 31 36 28 29 20 74 6f 20 66 69 6e  bytes16() to fin
34260 64 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68  d the size of th
34270 65 20 72 65 73 75 6c 74 2e 20 20 44 6f 20 6e 6f  e result.  Do no
34280 74 20 6d 69 78 20 63 61 6c 6c 73 0a 2a 2a 20 74  t mix calls.** t
34290 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  o sqlite3_column
342a0 5f 74 65 78 74 28 29 20 6f 72 20 73 71 6c 69 74  _text() or sqlit
342b0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29  e3_column_blob()
342c0 20 77 69 74 68 20 63 61 6c 6c 73 20 74 6f 0a 2a   with calls to.*
342d0 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  * sqlite3_column
342e0 5f 62 79 74 65 73 31 36 28 29 2c 20 61 6e 64 20  _bytes16(), and 
342f0 64 6f 20 6e 6f 74 20 6d 69 78 20 63 61 6c 6c 73  do not mix calls
34300 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   to sqlite3_colu
34310 6d 6e 5f 74 65 78 74 31 36 28 29 0a 2a 2a 20 77  mn_text16().** w
34320 69 74 68 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c  ith calls to sql
34330 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
34340 73 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  s()..**.** ^The 
34350 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65  pointers returne
34360 64 20 61 72 65 20 76 61 6c 69 64 20 75 6e 74 69  d are valid unti
34370 6c 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73  l a type convers
34380 69 6f 6e 20 6f 63 63 75 72 73 20 61 73 0a 2a 2a  ion occurs as.**
34390 20 64 65 73 63 72 69 62 65 64 20 61 62 6f 76 65   described above
343a0 2c 20 6f 72 20 75 6e 74 69 6c 20 5b 73 71 6c 69  , or until [sqli
343b0 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 72 20 5b  te3_step()] or [
343c0 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
343d0 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   or.** [sqlite3_
343e0 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69 73 20 63  finalize()] is c
343f0 61 6c 6c 65 64 2e 20 20 5e 54 68 65 20 6d 65 6d  alled.  ^The mem
34400 6f 72 79 20 73 70 61 63 65 20 75 73 65 64 20 74  ory space used t
34410 6f 20 68 6f 6c 64 20 73 74 72 69 6e 67 73 0a 2a  o hold strings.*
34420 2a 20 61 6e 64 20 42 4c 4f 42 73 20 69 73 20 66  * and BLOBs is f
34430 72 65 65 64 20 61 75 74 6f 6d 61 74 69 63 61 6c  reed automatical
34440 6c 79 2e 20 20 44 6f 20 3c 65 6d 3e 6e 6f 74 3c  ly.  Do <em>not<
34450 2f 65 6d 3e 20 70 61 73 73 20 74 68 65 20 70 6f  /em> pass the po
34460 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64 0a  inters returned.
34470 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  ** from [sqlite3
34480 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 5d 2c  _column_blob()],
34490 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
344a0 5f 74 65 78 74 28 29 5d 2c 20 65 74 63 2e 20 69  _text()], etc. i
344b0 6e 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  nto.** [sqlite3_
344c0 66 72 65 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e  free()]..**.** ^
344d0 28 49 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c  (If a memory all
344e0 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 20 6f 63  ocation error oc
344f0 63 75 72 73 20 64 75 72 69 6e 67 20 74 68 65 20  curs during the 
34500 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20 61 6e  evaluation of an
34510 79 0a 2a 2a 20 6f 66 20 74 68 65 73 65 20 72 6f  y.** of these ro
34520 75 74 69 6e 65 73 2c 20 61 20 64 65 66 61 75 6c  utines, a defaul
34530 74 20 76 61 6c 75 65 20 69 73 20 72 65 74 75 72  t value is retur
34540 6e 65 64 2e 20 20 54 68 65 20 64 65 66 61 75 6c  ned.  The defaul
34550 74 20 76 61 6c 75 65 0a 2a 2a 20 69 73 20 65 69  t value.** is ei
34560 74 68 65 72 20 74 68 65 20 69 6e 74 65 67 65 72  ther the integer
34570 20 30 2c 20 74 68 65 20 66 6c 6f 61 74 69 6e 67   0, the floating
34580 20 70 6f 69 6e 74 20 6e 75 6d 62 65 72 20 30 2e   point number 0.
34590 30 2c 20 6f 72 20 61 20 4e 55 4c 4c 0a 2a 2a 20  0, or a NULL.** 
345a0 70 6f 69 6e 74 65 72 2e 20 20 53 75 62 73 65 71  pointer.  Subseq
345b0 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73  uent calls to [s
345c0 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29  qlite3_errcode()
345d0 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a  ] will return.**
345e0 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e   [SQLITE_NOMEM].
345f0 29 5e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  )^.*/.SQLITE_API
34600 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c   const void *sql
34610 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62  ite3_column_blob
34620 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
34630 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54  int iCol);.SQLIT
34640 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
34650 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 73  3_column_bytes(s
34660 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
34670 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f  t iCol);.SQLITE_
34680 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
34690 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 73  column_bytes16(s
346a0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
346b0 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f  t iCol);.SQLITE_
346c0 41 50 49 20 64 6f 75 62 6c 65 20 73 71 6c 69 74  API double sqlit
346d0 65 33 5f 63 6f 6c 75 6d 6e 5f 64 6f 75 62 6c 65  e3_column_double
346e0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
346f0 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54  int iCol);.SQLIT
34700 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
34710 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 28 73 71 6c  3_column_int(sql
34720 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
34730 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50  iCol);.SQLITE_AP
34740 49 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  I sqlite3_int64 
34750 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69  sqlite3_column_i
34760 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d  nt64(sqlite3_stm
34770 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53  t*, int iCol);.S
34780 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20  QLITE_API const 
34790 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20 2a 73  unsigned char *s
347a0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
347b0 78 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  xt(sqlite3_stmt*
347c0 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c  , int iCol);.SQL
347d0 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f  ITE_API const vo
347e0 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  id *sqlite3_colu
347f0 6d 6e 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65  mn_text16(sqlite
34800 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
34810 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  l);.SQLITE_API i
34820 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nt sqlite3_colum
34830 6e 5f 74 79 70 65 28 73 71 6c 69 74 65 33 5f 73  n_type(sqlite3_s
34840 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
34850 0a 53 51 4c 49 54 45 5f 41 50 49 20 73 71 6c 69  .SQLITE_API sqli
34860 74 65 33 5f 76 61 6c 75 65 20 2a 73 71 6c 69 74  te3_value *sqlit
34870 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28  e3_column_value(
34880 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
34890 6e 74 20 69 43 6f 6c 29 3b 0a 0a 2f 2a 0a 2a 2a  nt iCol);../*.**
348a0 20 43 41 50 49 33 52 45 46 3a 20 44 65 73 74 72   CAPI3REF: Destr
348b0 6f 79 20 41 20 50 72 65 70 61 72 65 64 20 53 74  oy A Prepared St
348c0 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a  atement Object.*
348d0 2a 20 44 45 53 54 52 55 43 54 4f 52 3a 20 73 71  * DESTRUCTOR: sq
348e0 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a  lite3_stmt.**.**
348f0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 66 69   ^The sqlite3_fi
34900 6e 61 6c 69 7a 65 28 29 20 66 75 6e 63 74 69 6f  nalize() functio
34910 6e 20 69 73 20 63 61 6c 6c 65 64 20 74 6f 20 64  n is called to d
34920 65 6c 65 74 65 20 61 20 5b 70 72 65 70 61 72 65  elete a [prepare
34930 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a  d statement]..**
34940 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65   ^If the most re
34950 63 65 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e 20  cent evaluation 
34960 6f 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  of the statement
34970 20 65 6e 63 6f 75 6e 74 65 72 65 64 20 6e 6f 20   encountered no 
34980 65 72 72 6f 72 73 0a 2a 2a 20 6f 72 20 69 66 20  errors.** or if 
34990 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73  the statement is
349a0 20 6e 65 76 65 72 20 62 65 65 6e 20 65 76 61 6c   never been eval
349b0 75 61 74 65 64 2c 20 74 68 65 6e 20 73 71 6c 69  uated, then sqli
349c0 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20 72  te3_finalize() r
349d0 65 74 75 72 6e 73 0a 2a 2a 20 53 51 4c 49 54 45  eturns.** SQLITE
349e0 5f 4f 4b 2e 20 20 5e 49 66 20 74 68 65 20 6d 6f  _OK.  ^If the mo
349f0 73 74 20 72 65 63 65 6e 74 20 65 76 61 6c 75 61  st recent evalua
34a00 74 69 6f 6e 20 6f 66 20 73 74 61 74 65 6d 65 6e  tion of statemen
34a10 74 20 53 20 66 61 69 6c 65 64 2c 20 74 68 65 6e  t S failed, then
34a20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 66 69 6e 61  .** sqlite3_fina
34a30 6c 69 7a 65 28 53 29 20 72 65 74 75 72 6e 73 20  lize(S) returns 
34a40 74 68 65 20 61 70 70 72 6f 70 72 69 61 74 65 20  the appropriate 
34a50 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f 72 0a  [error code] or.
34a60 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 65 72 72  ** [extended err
34a70 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20  or code]..**.** 
34a80 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6e  ^The sqlite3_fin
34a90 61 6c 69 7a 65 28 53 29 20 72 6f 75 74 69 6e 65  alize(S) routine
34aa0 20 63 61 6e 20 62 65 20 63 61 6c 6c 65 64 20 61   can be called a
34ab0 74 20 61 6e 79 20 70 6f 69 6e 74 20 64 75 72 69  t any point duri
34ac0 6e 67 0a 2a 2a 20 74 68 65 20 6c 69 66 65 20 63  ng.** the life c
34ad0 79 63 6c 65 20 6f 66 20 5b 70 72 65 70 61 72 65  ycle of [prepare
34ae0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 3a 0a  d statement] S:.
34af0 2a 2a 20 62 65 66 6f 72 65 20 73 74 61 74 65 6d  ** before statem
34b00 65 6e 74 20 53 20 69 73 20 65 76 65 72 20 65 76  ent S is ever ev
34b10 61 6c 75 61 74 65 64 2c 20 61 66 74 65 72 0a 2a  aluated, after.*
34b20 2a 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 63 61  * one or more ca
34b30 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  lls to [sqlite3_
34b40 72 65 73 65 74 28 29 5d 2c 20 6f 72 20 61 66 74  reset()], or aft
34b50 65 72 20 61 6e 79 20 63 61 6c 6c 0a 2a 2a 20 74  er any call.** t
34b60 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  o [sqlite3_step(
34b70 29 5d 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66  )] regardless of
34b80 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20   whether or not 
34b90 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 68 61  the statement ha
34ba0 73 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 64 20 65  s.** completed e
34bb0 78 65 63 75 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  xecution..**.** 
34bc0 5e 49 6e 76 6f 6b 69 6e 67 20 73 71 6c 69 74 65  ^Invoking sqlite
34bd0 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20 6f 6e 20  3_finalize() on 
34be0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69  a NULL pointer i
34bf0 73 20 61 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d  s a harmless no-
34c00 6f 70 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70  op..**.** The ap
34c10 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 66  plication must f
34c20 69 6e 61 6c 69 7a 65 20 65 76 65 72 79 20 5b 70  inalize every [p
34c30 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
34c40 74 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 61  t] in order to a
34c50 76 6f 69 64 0a 2a 2a 20 72 65 73 6f 75 72 63 65  void.** resource
34c60 20 6c 65 61 6b 73 2e 20 20 49 74 20 69 73 20 61   leaks.  It is a
34c70 20 67 72 69 65 76 6f 75 73 20 65 72 72 6f 72 20   grievous error 
34c80 66 6f 72 20 74 68 65 20 61 70 70 6c 69 63 61 74  for the applicat
34c90 69 6f 6e 20 74 6f 20 74 72 79 20 74 6f 20 75 73  ion to try to us
34ca0 65 0a 2a 2a 20 61 20 70 72 65 70 61 72 65 64 20  e.** a prepared 
34cb0 73 74 61 74 65 6d 65 6e 74 20 61 66 74 65 72 20  statement after 
34cc0 69 74 20 68 61 73 20 62 65 65 6e 20 66 69 6e 61  it has been fina
34cd0 6c 69 7a 65 64 2e 20 20 41 6e 79 20 75 73 65 20  lized.  Any use 
34ce0 6f 66 20 61 20 70 72 65 70 61 72 65 64 0a 2a 2a  of a prepared.**
34cf0 20 73 74 61 74 65 6d 65 6e 74 20 61 66 74 65 72   statement after
34d00 20 69 74 20 68 61 73 20 62 65 65 6e 20 66 69 6e   it has been fin
34d10 61 6c 69 7a 65 64 20 63 61 6e 20 72 65 73 75 6c  alized can resul
34d20 74 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 61  t in undefined a
34d30 6e 64 0a 2a 2a 20 75 6e 64 65 73 69 72 61 62 6c  nd.** undesirabl
34d40 65 20 62 65 68 61 76 69 6f 72 20 73 75 63 68 20  e behavior such 
34d50 61 73 20 73 65 67 66 61 75 6c 74 73 20 61 6e 64  as segfaults and
34d60 20 68 65 61 70 20 63 6f 72 72 75 70 74 69 6f 6e   heap corruption
34d70 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
34d80 69 6e 74 20 73 71 6c 69 74 65 33 5f 66 69 6e 61  int sqlite3_fina
34d90 6c 69 7a 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  lize(sqlite3_stm
34da0 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a  t *pStmt);../*.*
34db0 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 65  * CAPI3REF: Rese
34dc0 74 20 41 20 50 72 65 70 61 72 65 64 20 53 74 61  t A Prepared Sta
34dd0 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a  tement Object.**
34de0 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
34df0 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 54 68 65 20  _stmt.**.** The 
34e00 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 20  sqlite3_reset() 
34e10 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 61 6c 6c  function is call
34e20 65 64 20 74 6f 20 72 65 73 65 74 20 61 20 5b 70  ed to reset a [p
34e30 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
34e40 74 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 62 61 63  t].** object bac
34e50 6b 20 74 6f 20 69 74 73 20 69 6e 69 74 69 61 6c  k to its initial
34e60 20 73 74 61 74 65 2c 20 72 65 61 64 79 20 74 6f   state, ready to
34e70 20 62 65 20 72 65 2d 65 78 65 63 75 74 65 64 2e   be re-executed.
34e80 0a 2a 2a 20 5e 41 6e 79 20 53 51 4c 20 73 74 61  .** ^Any SQL sta
34e90 74 65 6d 65 6e 74 20 76 61 72 69 61 62 6c 65 73  tement variables
34ea0 20 74 68 61 74 20 68 61 64 20 76 61 6c 75 65 73   that had values
34eb0 20 62 6f 75 6e 64 20 74 6f 20 74 68 65 6d 20 75   bound to them u
34ec0 73 69 6e 67 0a 2a 2a 20 74 68 65 20 5b 73 71 6c  sing.** the [sql
34ed0 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c  ite3_bind_blob |
34ee0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28   sqlite3_bind_*(
34ef0 29 20 41 50 49 5d 20 72 65 74 61 69 6e 20 74 68  ) API] retain th
34f00 65 69 72 20 76 61 6c 75 65 73 2e 0a 2a 2a 20 55  eir values..** U
34f10 73 65 20 5b 73 71 6c 69 74 65 33 5f 63 6c 65 61  se [sqlite3_clea
34f20 72 5f 62 69 6e 64 69 6e 67 73 28 29 5d 20 74 6f  r_bindings()] to
34f30 20 72 65 73 65 74 20 74 68 65 20 62 69 6e 64 69   reset the bindi
34f40 6e 67 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ngs..**.** ^The 
34f50 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53  [sqlite3_reset(S
34f60 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 73  )] interface res
34f70 65 74 73 20 74 68 65 20 5b 70 72 65 70 61 72 65  ets the [prepare
34f80 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 0a 2a  d statement] S.*
34f90 2a 20 62 61 63 6b 20 74 6f 20 74 68 65 20 62 65  * back to the be
34fa0 67 69 6e 6e 69 6e 67 20 6f 66 20 69 74 73 20 70  ginning of its p
34fb0 72 6f 67 72 61 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 49  rogram..**.** ^I
34fc0 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  f the most recen
34fd0 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  t call to [sqlit
34fe0 65 33 5f 73 74 65 70 28 53 29 5d 20 66 6f 72 20  e3_step(S)] for 
34ff0 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64  the.** [prepared
35000 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 72 65   statement] S re
35010 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 52  turned [SQLITE_R
35020 4f 57 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44  OW] or [SQLITE_D
35030 4f 4e 45 5d 2c 0a 2a 2a 20 6f 72 20 69 66 20 5b  ONE],.** or if [
35040 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d  sqlite3_step(S)]
35050 20 68 61 73 20 6e 65 76 65 72 20 62 65 66 6f 72   has never befor
35060 65 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 6f 6e  e been called on
35070 20 53 2c 0a 2a 2a 20 74 68 65 6e 20 5b 73 71 6c   S,.** then [sql
35080 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20 72  ite3_reset(S)] r
35090 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f  eturns [SQLITE_O
350a0 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  K]..**.** ^If th
350b0 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61  e most recent ca
350c0 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73  ll to [sqlite3_s
350d0 74 65 70 28 53 29 5d 20 66 6f 72 20 74 68 65 0a  tep(S)] for the.
350e0 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  ** [prepared sta
350f0 74 65 6d 65 6e 74 5d 20 53 20 69 6e 64 69 63 61  tement] S indica
35100 74 65 64 20 61 6e 20 65 72 72 6f 72 2c 20 74 68  ted an error, th
35110 65 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72  en.** [sqlite3_r
35120 65 73 65 74 28 53 29 5d 20 72 65 74 75 72 6e 73  eset(S)] returns
35130 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65 20   an appropriate 
35140 5b 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2a  [error code]..**
35150 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65  .** ^The [sqlite
35160 33 5f 72 65 73 65 74 28 53 29 5d 20 69 6e 74 65  3_reset(S)] inte
35170 72 66 61 63 65 20 64 6f 65 73 20 6e 6f 74 20 63  rface does not c
35180 68 61 6e 67 65 20 74 68 65 20 76 61 6c 75 65 73  hange the values
35190 0a 2a 2a 20 6f 66 20 61 6e 79 20 5b 73 71 6c 69  .** of any [sqli
351a0 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 62 69  te3_bind_blob|bi
351b0 6e 64 69 6e 67 73 5d 20 6f 6e 20 74 68 65 20 5b  ndings] on the [
351c0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
351d0 6e 74 5d 20 53 2e 0a 2a 2f 0a 53 51 4c 49 54 45  nt] S..*/.SQLITE
351e0 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
351f0 5f 72 65 73 65 74 28 73 71 6c 69 74 65 33 5f 73  _reset(sqlite3_s
35200 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a  tmt *pStmt);../*
35210 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 72  .** CAPI3REF: Cr
35220 65 61 74 65 20 4f 72 20 52 65 64 65 66 69 6e 65  eate Or Redefine
35230 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 73 0a 2a   SQL Functions.*
35240 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 66 75 6e  * KEYWORDS: {fun
35250 63 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20 72  ction creation r
35260 6f 75 74 69 6e 65 73 7d 0a 2a 2a 20 4b 45 59 57  outines}.** KEYW
35270 4f 52 44 53 3a 20 7b 61 70 70 6c 69 63 61 74 69  ORDS: {applicati
35280 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66  on-defined SQL f
35290 75 6e 63 74 69 6f 6e 7d 0a 2a 2a 20 4b 45 59 57  unction}.** KEYW
352a0 4f 52 44 53 3a 20 7b 61 70 70 6c 69 63 61 74 69  ORDS: {applicati
352b0 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66  on-defined SQL f
352c0 75 6e 63 74 69 6f 6e 73 7d 0a 2a 2a 20 4d 45 54  unctions}.** MET
352d0 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a  HOD: sqlite3.**.
352e0 2a 2a 20 5e 54 68 65 73 65 20 66 75 6e 63 74 69  ** ^These functi
352f0 6f 6e 73 20 28 63 6f 6c 6c 65 63 74 69 76 65 6c  ons (collectivel
35300 79 20 6b 6e 6f 77 6e 20 61 73 20 22 66 75 6e 63  y known as "func
35310 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20 72 6f  tion creation ro
35320 75 74 69 6e 65 73 22 29 0a 2a 2a 20 61 72 65 20  utines").** are 
35330 75 73 65 64 20 74 6f 20 61 64 64 20 53 51 4c 20  used to add SQL 
35340 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20 61 67 67  functions or agg
35350 72 65 67 61 74 65 73 20 6f 72 20 74 6f 20 72 65  regates or to re
35360 64 65 66 69 6e 65 20 74 68 65 20 62 65 68 61 76  define the behav
35370 69 6f 72 0a 2a 2a 20 6f 66 20 65 78 69 73 74 69  ior.** of existi
35380 6e 67 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  ng SQL functions
35390 20 6f 72 20 61 67 67 72 65 67 61 74 65 73 2e 20   or aggregates. 
353a0 20 54 68 65 20 6f 6e 6c 79 20 64 69 66 66 65 72   The only differ
353b0 65 6e 63 65 73 20 62 65 74 77 65 65 6e 0a 2a 2a  ences between.**
353c0 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   these routines 
353d0 61 72 65 20 74 68 65 20 74 65 78 74 20 65 6e 63  are the text enc
353e0 6f 64 69 6e 67 20 65 78 70 65 63 74 65 64 20 66  oding expected f
353f0 6f 72 0a 2a 2a 20 74 68 65 20 73 65 63 6f 6e 64  or.** the second
35400 20 70 61 72 61 6d 65 74 65 72 20 28 74 68 65 20   parameter (the 
35410 6e 61 6d 65 20 6f 66 20 74 68 65 20 66 75 6e 63  name of the func
35420 74 69 6f 6e 20 62 65 69 6e 67 20 63 72 65 61 74  tion being creat
35430 65 64 29 0a 2a 2a 20 61 6e 64 20 74 68 65 20 70  ed).** and the p
35440 72 65 73 65 6e 63 65 20 6f 72 20 61 62 73 65 6e  resence or absen
35450 63 65 20 6f 66 20 61 20 64 65 73 74 72 75 63 74  ce of a destruct
35460 6f 72 20 63 61 6c 6c 62 61 63 6b 20 66 6f 72 0a  or callback for.
35470 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  ** the applicati
35480 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74 65 72 2e  on data pointer.
35490 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73  .**.** ^The firs
354a0 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74  t parameter is t
354b0 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
354c0 6e 65 63 74 69 6f 6e 5d 20 74 6f 20 77 68 69 63  nection] to whic
354d0 68 20 74 68 65 20 53 51 4c 0a 2a 2a 20 66 75 6e  h the SQL.** fun
354e0 63 74 69 6f 6e 20 69 73 20 74 6f 20 62 65 20 61  ction is to be a
354f0 64 64 65 64 2e 20 20 5e 49 66 20 61 6e 20 61 70  dded.  ^If an ap
35500 70 6c 69 63 61 74 69 6f 6e 20 75 73 65 73 20 6d  plication uses m
35510 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 64 61 74  ore than one dat
35520 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74  abase.** connect
35530 69 6f 6e 20 74 68 65 6e 20 61 70 70 6c 69 63 61  ion then applica
35540 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c  tion-defined SQL
35550 20 66 75 6e 63 74 69 6f 6e 73 20 6d 75 73 74 20   functions must 
35560 62 65 20 61 64 64 65 64 0a 2a 2a 20 74 6f 20 65  be added.** to e
35570 61 63 68 20 64 61 74 61 62 61 73 65 20 63 6f 6e  ach database con
35580 6e 65 63 74 69 6f 6e 20 73 65 70 61 72 61 74 65  nection separate
35590 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ly..**.** ^The s
355a0 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
355b0 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  is the name of t
355c0 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  he SQL function 
355d0 74 6f 20 62 65 20 63 72 65 61 74 65 64 20 6f 72  to be created or
355e0 0a 2a 2a 20 72 65 64 65 66 69 6e 65 64 2e 20 20  .** redefined.  
355f0 5e 54 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 74  ^The length of t
35600 68 65 20 6e 61 6d 65 20 69 73 20 6c 69 6d 69 74  he name is limit
35610 65 64 20 74 6f 20 32 35 35 20 62 79 74 65 73 20  ed to 255 bytes 
35620 69 6e 20 61 20 55 54 46 2d 38 0a 2a 2a 20 72 65  in a UTF-8.** re
35630 70 72 65 73 65 6e 74 61 74 69 6f 6e 2c 20 65 78  presentation, ex
35640 63 6c 75 73 69 76 65 20 6f 66 20 74 68 65 20 7a  clusive of the z
35650 65 72 6f 2d 74 65 72 6d 69 6e 61 74 6f 72 2e 20  ero-terminator. 
35660 20 5e 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20   ^Note that the 
35670 6e 61 6d 65 0a 2a 2a 20 6c 65 6e 67 74 68 20 6c  name.** length l
35680 69 6d 69 74 20 69 73 20 69 6e 20 55 54 46 2d 38  imit is in UTF-8
35690 20 62 79 74 65 73 2c 20 6e 6f 74 20 63 68 61 72   bytes, not char
356a0 61 63 74 65 72 73 20 6e 6f 72 20 55 54 46 2d 31  acters nor UTF-1
356b0 36 20 62 79 74 65 73 2e 20 20 0a 2a 2a 20 5e 41  6 bytes.  .** ^A
356c0 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20 63 72  ny attempt to cr
356d0 65 61 74 65 20 61 20 66 75 6e 63 74 69 6f 6e 20  eate a function 
356e0 77 69 74 68 20 61 20 6c 6f 6e 67 65 72 20 6e 61  with a longer na
356f0 6d 65 0a 2a 2a 20 77 69 6c 6c 20 72 65 73 75 6c  me.** will resul
35700 74 20 69 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 53  t in [SQLITE_MIS
35710 55 53 45 5d 20 62 65 69 6e 67 20 72 65 74 75 72  USE] being retur
35720 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ned..**.** ^The 
35730 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20  third parameter 
35740 28 6e 41 72 67 29 0a 2a 2a 20 69 73 20 74 68 65  (nArg).** is the
35750 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d   number of argum
35760 65 6e 74 73 20 74 68 61 74 20 74 68 65 20 53 51  ents that the SQ
35770 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a  L function or.**
35780 20 61 67 67 72 65 67 61 74 65 20 74 61 6b 65 73   aggregate takes
35790 2e 20 5e 49 66 20 74 68 69 73 20 70 61 72 61 6d  . ^If this param
357a0 65 74 65 72 20 69 73 20 2d 31 2c 20 74 68 65 6e  eter is -1, then
357b0 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f   the SQL functio
357c0 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74  n or.** aggregat
357d0 65 20 6d 61 79 20 74 61 6b 65 20 61 6e 79 20 6e  e may take any n
357e0 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e  umber of argumen
357f0 74 73 20 62 65 74 77 65 65 6e 20 30 20 61 6e 64  ts between 0 and
35800 20 74 68 65 20 6c 69 6d 69 74 0a 2a 2a 20 73 65   the limit.** se
35810 74 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c 69  t by [sqlite3_li
35820 6d 69 74 5d 28 5b 53 51 4c 49 54 45 5f 4c 49 4d  mit]([SQLITE_LIM
35830 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 5d  IT_FUNCTION_ARG]
35840 29 2e 20 20 49 66 20 74 68 65 20 74 68 69 72 64  ).  If the third
35850 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 69 73  .** parameter is
35860 20 6c 65 73 73 20 74 68 61 6e 20 2d 31 20 6f 72   less than -1 or
35870 20 67 72 65 61 74 65 72 20 74 68 61 6e 20 31 32   greater than 12
35880 37 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76  7 then the behav
35890 69 6f 72 20 69 73 0a 2a 2a 20 75 6e 64 65 66 69  ior is.** undefi
358a0 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ned..**.** ^The 
358b0 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
358c0 2c 20 65 54 65 78 74 52 65 70 2c 20 73 70 65 63  , eTextRep, spec
358d0 69 66 69 65 73 20 77 68 61 74 0a 2a 2a 20 5b 53  ifies what.** [S
358e0 51 4c 49 54 45 5f 55 54 46 38 20 7c 20 74 65 78  QLITE_UTF8 | tex
358f0 74 20 65 6e 63 6f 64 69 6e 67 5d 20 74 68 69 73  t encoding] this
35900 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 70 72   SQL function pr
35910 65 66 65 72 73 20 66 6f 72 0a 2a 2a 20 69 74 73  efers for.** its
35920 20 70 61 72 61 6d 65 74 65 72 73 2e 20 20 54 68   parameters.  Th
35930 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68  e application sh
35940 6f 75 6c 64 20 73 65 74 20 74 68 69 73 20 70 61  ould set this pa
35950 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 53  rameter to.** [S
35960 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d 20 69  QLITE_UTF16LE] i
35970 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69  f the function i
35980 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 6e  mplementation in
35990 76 6f 6b 65 73 20 0a 2a 2a 20 5b 73 71 6c 69 74  vokes .** [sqlit
359a0 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 6c  e3_value_text16l
359b0 65 28 29 5d 20 6f 6e 20 61 6e 20 69 6e 70 75 74  e()] on an input
359c0 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55 54 46  , or [SQLITE_UTF
359d0 31 36 42 45 5d 20 69 66 20 74 68 65 0a 2a 2a 20  16BE] if the.** 
359e0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69  implementation i
359f0 6e 76 6f 6b 65 73 20 5b 73 71 6c 69 74 65 33 5f  nvokes [sqlite3_
35a00 76 61 6c 75 65 5f 74 65 78 74 31 36 62 65 28 29  value_text16be()
35a10 5d 20 6f 6e 20 61 6e 20 69 6e 70 75 74 2c 20 6f  ] on an input, o
35a20 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46  r.** [SQLITE_UTF
35a30 31 36 5d 20 69 66 20 5b 73 71 6c 69 74 65 33 5f  16] if [sqlite3_
35a40 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29 5d 20  value_text16()] 
35a50 69 73 20 75 73 65 64 2c 20 6f 72 20 5b 53 51 4c  is used, or [SQL
35a60 49 54 45 5f 55 54 46 38 5d 0a 2a 2a 20 6f 74 68  ITE_UTF8].** oth
35a70 65 72 77 69 73 65 2e 20 20 5e 54 68 65 20 73 61  erwise.  ^The sa
35a80 6d 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  me SQL function 
35a90 6d 61 79 20 62 65 20 72 65 67 69 73 74 65 72 65  may be registere
35aa0 64 20 6d 75 6c 74 69 70 6c 65 20 74 69 6d 65 73  d multiple times
35ab0 20 75 73 69 6e 67 0a 2a 2a 20 64 69 66 66 65 72   using.** differ
35ac0 65 6e 74 20 70 72 65 66 65 72 72 65 64 20 74 65  ent preferred te
35ad0 78 74 20 65 6e 63 6f 64 69 6e 67 73 2c 20 77 69  xt encodings, wi
35ae0 74 68 20 64 69 66 66 65 72 65 6e 74 20 69 6d 70  th different imp
35af0 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 66 6f 72  lementations for
35b00 0a 2a 2a 20 65 61 63 68 20 65 6e 63 6f 64 69 6e  .** each encodin
35b10 67 2e 0a 2a 2a 20 5e 57 68 65 6e 20 6d 75 6c 74  g..** ^When mult
35b20 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  iple implementat
35b30 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65  ions of the same
35b40 20 66 75 6e 63 74 69 6f 6e 20 61 72 65 20 61 76   function are av
35b50 61 69 6c 61 62 6c 65 2c 20 53 51 4c 69 74 65 0a  ailable, SQLite.
35b60 2a 2a 20 77 69 6c 6c 20 70 69 63 6b 20 74 68 65  ** will pick the
35b70 20 6f 6e 65 20 74 68 61 74 20 69 6e 76 6f 6c 76   one that involv
35b80 65 73 20 74 68 65 20 6c 65 61 73 74 20 61 6d 6f  es the least amo
35b90 75 6e 74 20 6f 66 20 64 61 74 61 20 63 6f 6e 76  unt of data conv
35ba0 65 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ersion..**.** ^T
35bb0 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
35bc0 74 65 72 20 6d 61 79 20 6f 70 74 69 6f 6e 61 6c  ter may optional
35bd0 6c 79 20 62 65 20 4f 52 65 64 20 77 69 74 68 20  ly be ORed with 
35be0 5b 53 51 4c 49 54 45 5f 44 45 54 45 52 4d 49 4e  [SQLITE_DETERMIN
35bf0 49 53 54 49 43 5d 0a 2a 2a 20 74 6f 20 73 69 67  ISTIC].** to sig
35c00 6e 61 6c 20 74 68 61 74 20 74 68 65 20 66 75 6e  nal that the fun
35c10 63 74 69 6f 6e 20 77 69 6c 6c 20 61 6c 77 61 79  ction will alway
35c20 73 20 72 65 74 75 72 6e 20 74 68 65 20 73 61 6d  s return the sam
35c30 65 20 72 65 73 75 6c 74 20 67 69 76 65 6e 0a 2a  e result given.*
35c40 2a 20 74 68 65 20 73 61 6d 65 20 69 6e 70 75 74  * the same input
35c50 73 20 77 69 74 68 69 6e 20 61 20 73 69 6e 67 6c  s within a singl
35c60 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e  e SQL statement.
35c70 20 20 4d 6f 73 74 20 53 51 4c 20 66 75 6e 63 74    Most SQL funct
35c80 69 6f 6e 73 20 61 72 65 0a 2a 2a 20 64 65 74 65  ions are.** dete
35c90 72 6d 69 6e 69 73 74 69 63 2e 20 20 54 68 65 20  rministic.  The 
35ca0 62 75 69 6c 74 2d 69 6e 20 5b 72 61 6e 64 6f 6d  built-in [random
35cb0 28 29 5d 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ()] SQL function
35cc0 20 69 73 20 61 6e 20 65 78 61 6d 70 6c 65 20 6f   is an example o
35cd0 66 20 61 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  f a.** function 
35ce0 74 68 61 74 20 69 73 20 6e 6f 74 20 64 65 74 65  that is not dete
35cf0 72 6d 69 6e 69 73 74 69 63 2e 20 20 54 68 65 20  rministic.  The 
35d00 53 51 4c 69 74 65 20 71 75 65 72 79 20 70 6c 61  SQLite query pla
35d10 6e 6e 65 72 20 69 73 20 61 62 6c 65 20 74 6f 0a  nner is able to.
35d20 2a 2a 20 70 65 72 66 6f 72 6d 20 61 64 64 69 74  ** perform addit
35d30 69 6f 6e 61 6c 20 6f 70 74 69 6d 69 7a 61 74 69  ional optimizati
35d40 6f 6e 73 20 6f 6e 20 64 65 74 65 72 6d 69 6e 69  ons on determini
35d50 73 74 69 63 20 66 75 6e 63 74 69 6f 6e 73 2c 20  stic functions, 
35d60 73 6f 20 75 73 65 0a 2a 2a 20 6f 66 20 74 68 65  so use.** of the
35d70 20 5b 53 51 4c 49 54 45 5f 44 45 54 45 52 4d 49   [SQLITE_DETERMI
35d80 4e 49 53 54 49 43 5d 20 66 6c 61 67 20 69 73 20  NISTIC] flag is 
35d90 72 65 63 6f 6d 6d 65 6e 64 65 64 20 77 68 65 72  recommended wher
35da0 65 20 70 6f 73 73 69 62 6c 65 2e 0a 2a 2a 0a 2a  e possible..**.*
35db0 2a 20 5e 28 54 68 65 20 66 69 66 74 68 20 70 61  * ^(The fifth pa
35dc0 72 61 6d 65 74 65 72 20 69 73 20 61 6e 20 61 72  rameter is an ar
35dd0 62 69 74 72 61 72 79 20 70 6f 69 6e 74 65 72 2e  bitrary pointer.
35de0 20 20 54 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61    The implementa
35df0 74 69 6f 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 66  tion of the.** f
35e00 75 6e 63 74 69 6f 6e 20 63 61 6e 20 67 61 69 6e  unction can gain
35e10 20 61 63 63 65 73 73 20 74 6f 20 74 68 69 73 20   access to this 
35e20 70 6f 69 6e 74 65 72 20 75 73 69 6e 67 20 5b 73  pointer using [s
35e30 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61  qlite3_user_data
35e40 28 29 5d 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ()].)^.**.** ^Th
35e50 65 20 73 69 78 74 68 2c 20 73 65 76 65 6e 74 68  e sixth, seventh
35e60 20 61 6e 64 20 65 69 67 68 74 68 20 70 61 72 61   and eighth para
35e70 6d 65 74 65 72 73 2c 20 78 46 75 6e 63 2c 20 78  meters, xFunc, x
35e80 53 74 65 70 20 61 6e 64 20 78 46 69 6e 61 6c 2c  Step and xFinal,
35e90 20 61 72 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 73   are.** pointers
35ea0 20 74 6f 20 43 2d 6c 61 6e 67 75 61 67 65 20 66   to C-language f
35eb0 75 6e 63 74 69 6f 6e 73 20 74 68 61 74 20 69 6d  unctions that im
35ec0 70 6c 65 6d 65 6e 74 20 74 68 65 20 53 51 4c 20  plement the SQL 
35ed0 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61  function or.** a
35ee0 67 67 72 65 67 61 74 65 2e 20 5e 41 20 73 63 61  ggregate. ^A sca
35ef0 6c 61 72 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  lar SQL function
35f00 20 72 65 71 75 69 72 65 73 20 61 6e 20 69 6d 70   requires an imp
35f10 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74  lementation of t
35f20 68 65 20 78 46 75 6e 63 0a 2a 2a 20 63 61 6c 6c  he xFunc.** call
35f30 62 61 63 6b 20 6f 6e 6c 79 3b 20 4e 55 4c 4c 20  back only; NULL 
35f40 70 6f 69 6e 74 65 72 73 20 6d 75 73 74 20 62 65  pointers must be
35f50 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 78   passed as the x
35f60 53 74 65 70 20 61 6e 64 20 78 46 69 6e 61 6c 0a  Step and xFinal.
35f70 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 2e 20 5e  ** parameters. ^
35f80 41 6e 20 61 67 67 72 65 67 61 74 65 20 53 51 4c  An aggregate SQL
35f90 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72   function requir
35fa0 65 73 20 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 61  es an implementa
35fb0 74 69 6f 6e 20 6f 66 20 78 53 74 65 70 0a 2a 2a  tion of xStep.**
35fc0 20 61 6e 64 20 78 46 69 6e 61 6c 20 61 6e 64 20   and xFinal and 
35fd0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 6d 75 73  NULL pointer mus
35fe0 74 20 62 65 20 70 61 73 73 65 64 20 66 6f 72 20  t be passed for 
35ff0 78 46 75 6e 63 2e 20 5e 54 6f 20 64 65 6c 65 74  xFunc. ^To delet
36000 65 20 61 6e 20 65 78 69 73 74 69 6e 67 0a 2a 2a  e an existing.**
36010 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72   SQL function or
36020 20 61 67 67 72 65 67 61 74 65 2c 20 70 61 73 73   aggregate, pass
36030 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73 20 66   NULL pointers f
36040 6f 72 20 61 6c 6c 20 74 68 72 65 65 20 66 75 6e  or all three fun
36050 63 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63  ction.** callbac
36060 6b 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 74  ks..**.** ^(If t
36070 68 65 20 6e 69 6e 74 68 20 70 61 72 61 6d 65 74  he ninth paramet
36080 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 72  er to sqlite3_cr
36090 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32  eate_function_v2
360a0 28 29 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 0a  () is not NULL,.
360b0 2a 2a 20 74 68 65 6e 20 69 74 20 69 73 20 64 65  ** then it is de
360c0 73 74 72 75 63 74 6f 72 20 66 6f 72 20 74 68 65  structor for the
360d0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74   application dat
360e0 61 20 70 6f 69 6e 74 65 72 2e 20 0a 2a 2a 20 54  a pointer. .** T
360f0 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 69 73  he destructor is
36100 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 74 68   invoked when th
36110 65 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 64 65  e function is de
36120 6c 65 74 65 64 2c 20 65 69 74 68 65 72 20 62 79  leted, either by
36130 20 62 65 69 6e 67 0a 2a 2a 20 6f 76 65 72 6c 6f   being.** overlo
36140 61 64 65 64 20 6f 72 20 77 68 65 6e 20 74 68 65  aded or when the
36150 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
36160 74 69 6f 6e 20 63 6c 6f 73 65 73 2e 29 5e 0a 2a  tion closes.)^.*
36170 2a 20 5e 54 68 65 20 64 65 73 74 72 75 63 74 6f  * ^The destructo
36180 72 20 69 73 20 61 6c 73 6f 20 69 6e 76 6f 6b 65  r is also invoke
36190 64 20 69 66 20 74 68 65 20 63 61 6c 6c 20 74 6f  d if the call to
361a0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61  .** sqlite3_crea
361b0 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28 29  te_function_v2()
361c0 20 66 61 69 6c 73 2e 0a 2a 2a 20 5e 57 68 65 6e   fails..** ^When
361d0 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 20   the destructor 
361e0 63 61 6c 6c 62 61 63 6b 20 6f 66 20 74 68 65 20  callback of the 
361f0 74 65 6e 74 68 20 70 61 72 61 6d 65 74 65 72 20  tenth parameter 
36200 69 73 20 69 6e 76 6f 6b 65 64 2c 20 69 74 0a 2a  is invoked, it.*
36210 2a 20 69 73 20 70 61 73 73 65 64 20 61 20 73 69  * is passed a si
36220 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68  ngle argument wh
36230 69 63 68 20 69 73 20 61 20 63 6f 70 79 20 6f 66  ich is a copy of
36240 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
36250 20 64 61 74 61 20 0a 2a 2a 20 70 6f 69 6e 74 65   data .** pointe
36260 72 20 77 68 69 63 68 20 77 61 73 20 74 68 65 20  r which was the 
36270 66 69 66 74 68 20 70 61 72 61 6d 65 74 65 72 20  fifth parameter 
36280 74 6f 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  to sqlite3_creat
36290 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28 29 2e  e_function_v2().
362a0 0a 2a 2a 0a 2a 2a 20 5e 49 74 20 69 73 20 70 65  .**.** ^It is pe
362b0 72 6d 69 74 74 65 64 20 74 6f 20 72 65 67 69 73  rmitted to regis
362c0 74 65 72 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70  ter multiple imp
362d0 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20  lementations of 
362e0 74 68 65 20 73 61 6d 65 0a 2a 2a 20 66 75 6e 63  the same.** func
362f0 74 69 6f 6e 73 20 77 69 74 68 20 74 68 65 20 73  tions with the s
36300 61 6d 65 20 6e 61 6d 65 20 62 75 74 20 77 69 74  ame name but wit
36310 68 20 65 69 74 68 65 72 20 64 69 66 66 65 72 69  h either differi
36320 6e 67 20 6e 75 6d 62 65 72 73 20 6f 66 0a 2a 2a  ng numbers of.**
36330 20 61 72 67 75 6d 65 6e 74 73 20 6f 72 20 64 69   arguments or di
36340 66 66 65 72 69 6e 67 20 70 72 65 66 65 72 72 65  ffering preferre
36350 64 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 73  d text encodings
36360 2e 20 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20  .  ^SQLite will 
36370 75 73 65 0a 2a 2a 20 74 68 65 20 69 6d 70 6c 65  use.** the imple
36380 6d 65 6e 74 61 74 69 6f 6e 20 74 68 61 74 20 6d  mentation that m
36390 6f 73 74 20 63 6c 6f 73 65 6c 79 20 6d 61 74 63  ost closely matc
363a0 68 65 73 20 74 68 65 20 77 61 79 20 69 6e 20 77  hes the way in w
363b0 68 69 63 68 20 74 68 65 0a 2a 2a 20 53 51 4c 20  hich the.** SQL 
363c0 66 75 6e 63 74 69 6f 6e 20 69 73 20 75 73 65 64  function is used
363d0 2e 20 20 5e 41 20 66 75 6e 63 74 69 6f 6e 20 69  .  ^A function i
363e0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69  mplementation wi
363f0 74 68 20 61 20 6e 6f 6e 2d 6e 65 67 61 74 69 76  th a non-negativ
36400 65 0a 2a 2a 20 6e 41 72 67 20 70 61 72 61 6d 65  e.** nArg parame
36410 74 65 72 20 69 73 20 61 20 62 65 74 74 65 72 20  ter is a better 
36420 6d 61 74 63 68 20 74 68 61 6e 20 61 20 66 75 6e  match than a fun
36430 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61  ction implementa
36440 74 69 6f 6e 20 77 69 74 68 0a 2a 2a 20 61 20 6e  tion with.** a n
36450 65 67 61 74 69 76 65 20 6e 41 72 67 2e 20 20 5e  egative nArg.  ^
36460 41 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65  A function where
36470 20 74 68 65 20 70 72 65 66 65 72 72 65 64 20 74   the preferred t
36480 65 78 74 20 65 6e 63 6f 64 69 6e 67 0a 2a 2a 20  ext encoding.** 
36490 6d 61 74 63 68 65 73 20 74 68 65 20 64 61 74 61  matches the data
364a0 62 61 73 65 20 65 6e 63 6f 64 69 6e 67 20 69 73  base encoding is
364b0 20 61 20 62 65 74 74 65 72 0a 2a 2a 20 6d 61 74   a better.** mat
364c0 63 68 20 74 68 61 6e 20 61 20 66 75 6e 63 74 69  ch than a functi
364d0 6f 6e 20 77 68 65 72 65 20 74 68 65 20 65 6e 63  on where the enc
364e0 6f 64 69 6e 67 20 69 73 20 64 69 66 66 65 72 65  oding is differe
364f0 6e 74 2e 20 20 0a 2a 2a 20 5e 41 20 66 75 6e 63  nt.  .** ^A func
36500 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20 65  tion where the e
36510 6e 63 6f 64 69 6e 67 20 64 69 66 66 65 72 65 6e  ncoding differen
36520 63 65 20 69 73 20 62 65 74 77 65 65 6e 20 55 54  ce is between UT
36530 46 31 36 6c 65 20 61 6e 64 20 55 54 46 31 36 62  F16le and UTF16b
36540 65 0a 2a 2a 20 69 73 20 61 20 63 6c 6f 73 65 72  e.** is a closer
36550 20 6d 61 74 63 68 20 74 68 61 6e 20 61 20 66 75   match than a fu
36560 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65  nction where the
36570 20 65 6e 63 6f 64 69 6e 67 20 64 69 66 66 65 72   encoding differ
36580 65 6e 63 65 20 69 73 0a 2a 2a 20 62 65 74 77 65  ence is.** betwe
36590 65 6e 20 55 54 46 38 20 61 6e 64 20 55 54 46 31  en UTF8 and UTF1
365a0 36 2e 0a 2a 2a 0a 2a 2a 20 5e 42 75 69 6c 74 2d  6..**.** ^Built-
365b0 69 6e 20 66 75 6e 63 74 69 6f 6e 73 20 6d 61 79  in functions may
365c0 20 62 65 20 6f 76 65 72 6c 6f 61 64 65 64 20 62   be overloaded b
365d0 79 20 6e 65 77 20 61 70 70 6c 69 63 61 74 69 6f  y new applicatio
365e0 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
365f0 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 61  ons..**.** ^An a
36600 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
36610 65 64 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 70  ed function is p
36620 65 72 6d 69 74 74 65 64 20 74 6f 20 63 61 6c 6c  ermitted to call
36630 20 6f 74 68 65 72 0a 2a 2a 20 53 51 4c 69 74 65   other.** SQLite
36640 20 69 6e 74 65 72 66 61 63 65 73 2e 20 20 48 6f   interfaces.  Ho
36650 77 65 76 65 72 2c 20 73 75 63 68 20 63 61 6c 6c  wever, such call
36660 73 20 6d 75 73 74 20 6e 6f 74 0a 2a 2a 20 63 6c  s must not.** cl
36670 6f 73 65 20 74 68 65 20 64 61 74 61 62 61 73 65  ose the database
36680 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6e 6f 72 20   connection nor 
36690 66 69 6e 61 6c 69 7a 65 20 6f 72 20 72 65 73 65  finalize or rese
366a0 74 20 74 68 65 20 70 72 65 70 61 72 65 64 0a 2a  t the prepared.*
366b0 2a 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 77  * statement in w
366c0 68 69 63 68 20 74 68 65 20 66 75 6e 63 74 69 6f  hich the functio
366d0 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f  n is running..*/
366e0 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
366f0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
36700 75 6e 63 74 69 6f 6e 28 0a 20 20 73 71 6c 69 74  unction(.  sqlit
36710 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20  e3 *db,.  const 
36720 63 68 61 72 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e  char *zFunctionN
36730 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c  ame,.  int nArg,
36740 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c  .  int eTextRep,
36750 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20  .  void *pApp,. 
36760 20 76 6f 69 64 20 28 2a 78 46 75 6e 63 29 28 73   void (*xFunc)(s
36770 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
36780 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75  int,sqlite3_valu
36790 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78  e**),.  void (*x
367a0 53 74 65 70 29 28 73 71 6c 69 74 65 33 5f 63 6f  Step)(sqlite3_co
367b0 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74  ntext*,int,sqlit
367c0 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76  e3_value**),.  v
367d0 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29 28 73 71  oid (*xFinal)(sq
367e0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 0a  lite3_context*).
367f0 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  );.SQLITE_API in
36800 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  t sqlite3_create
36810 5f 66 75 6e 63 74 69 6f 6e 31 36 28 0a 20 20 73  _function16(.  s
36820 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f  qlite3 *db,.  co
36830 6e 73 74 20 76 6f 69 64 20 2a 7a 46 75 6e 63 74  nst void *zFunct
36840 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e  ionName,.  int n
36850 41 72 67 2c 0a 20 20 69 6e 74 20 65 54 65 78 74  Arg,.  int eText
36860 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70  Rep,.  void *pAp
36870 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 75 6e  p,.  void (*xFun
36880 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  c)(sqlite3_conte
36890 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f  xt*,int,sqlite3_
368a0 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64  value**),.  void
368b0 20 28 2a 78 53 74 65 70 29 28 73 71 6c 69 74 65   (*xStep)(sqlite
368c0 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73  3_context*,int,s
368d0 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c  qlite3_value**),
368e0 0a 20 20 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c  .  void (*xFinal
368f0 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  )(sqlite3_contex
36900 74 2a 29 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50  t*).);.SQLITE_AP
36910 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72  I int sqlite3_cr
36920 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32  eate_function_v2
36930 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
36940 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
36950 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20  FunctionName,.  
36960 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20  int nArg,.  int 
36970 65 54 65 78 74 52 65 70 2c 0a 20 20 76 6f 69 64  eTextRep,.  void
36980 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64 20 28   *pApp,.  void (
36990 2a 78 46 75 6e 63 29 28 73 71 6c 69 74 65 33 5f  *xFunc)(sqlite3_
369a0 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c  context*,int,sql
369b0 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20  ite3_value**),. 
369c0 20 76 6f 69 64 20 28 2a 78 53 74 65 70 29 28 73   void (*xStep)(s
369d0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
369e0 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75  int,sqlite3_valu
369f0 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78  e**),.  void (*x
36a00 46 69 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f 63  Final)(sqlite3_c
36a10 6f 6e 74 65 78 74 2a 29 2c 0a 20 20 76 6f 69 64  ontext*),.  void
36a20 28 2a 78 44 65 73 74 72 6f 79 29 28 76 6f 69 64  (*xDestroy)(void
36a30 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  *).);../*.** CAP
36a40 49 33 52 45 46 3a 20 54 65 78 74 20 45 6e 63 6f  I3REF: Text Enco
36a50 64 69 6e 67 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73  dings.**.** Thes
36a60 65 20 63 6f 6e 73 74 61 6e 74 20 64 65 66 69 6e  e constant defin
36a70 65 20 69 6e 74 65 67 65 72 20 63 6f 64 65 73 20  e integer codes 
36a80 74 68 61 74 20 72 65 70 72 65 73 65 6e 74 20 74  that represent t
36a90 68 65 20 76 61 72 69 6f 75 73 0a 2a 2a 20 74 65  he various.** te
36aa0 78 74 20 65 6e 63 6f 64 69 6e 67 73 20 73 75 70  xt encodings sup
36ab0 70 6f 72 74 65 64 20 62 79 20 53 51 4c 69 74 65  ported by SQLite
36ac0 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
36ad0 49 54 45 5f 55 54 46 38 20 20 20 20 20 20 20 20  ITE_UTF8        
36ae0 20 20 20 31 20 20 20 20 2f 2a 20 49 4d 50 3a 20     1    /* IMP: 
36af0 52 2d 33 37 35 31 34 2d 33 35 35 36 36 20 2a 2f  R-37514-35566 */
36b00 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
36b10 55 54 46 31 36 4c 45 20 20 20 20 20 20 20 20 32  UTF16LE        2
36b20 20 20 20 20 2f 2a 20 49 4d 50 3a 20 52 2d 30 33      /* IMP: R-03
36b30 33 37 31 2d 33 37 36 33 37 20 2a 2f 0a 23 64 65  371-37637 */.#de
36b40 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31  fine SQLITE_UTF1
36b50 36 42 45 20 20 20 20 20 20 20 20 33 20 20 20 20  6BE        3    
36b60 2f 2a 20 49 4d 50 3a 20 52 2d 35 31 39 37 31 2d  /* IMP: R-51971-
36b70 33 34 31 35 34 20 2a 2f 0a 23 64 65 66 69 6e 65  34154 */.#define
36b80 20 53 51 4c 49 54 45 5f 55 54 46 31 36 20 20 20   SQLITE_UTF16   
36b90 20 20 20 20 20 20 20 34 20 20 20 20 2f 2a 20 55         4    /* U
36ba0 73 65 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f  se native byte o
36bb0 72 64 65 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20  rder */.#define 
36bc0 53 51 4c 49 54 45 5f 41 4e 59 20 20 20 20 20 20  SQLITE_ANY      
36bd0 20 20 20 20 20 20 35 20 20 20 20 2f 2a 20 44 65        5    /* De
36be0 70 72 65 63 61 74 65 64 20 2a 2f 0a 23 64 65 66  precated */.#def
36bf0 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36  ine SQLITE_UTF16
36c00 5f 41 4c 49 47 4e 45 44 20 20 38 20 20 20 20 2f  _ALIGNED  8    /
36c10 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  * sqlite3_create
36c20 5f 63 6f 6c 6c 61 74 69 6f 6e 20 6f 6e 6c 79 20  _collation only 
36c30 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  */../*.** CAPI3R
36c40 45 46 3a 20 46 75 6e 63 74 69 6f 6e 20 46 6c 61  EF: Function Fla
36c50 67 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63  gs.**.** These c
36c60 6f 6e 73 74 61 6e 74 73 20 6d 61 79 20 62 65 20  onstants may be 
36c70 4f 52 65 64 20 74 6f 67 65 74 68 65 72 20 77 69  ORed together wi
36c80 74 68 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c 49  th the .** [SQLI
36c90 54 45 5f 55 54 46 38 20 7c 20 70 72 65 66 65 72  TE_UTF8 | prefer
36ca0 72 65 64 20 74 65 78 74 20 65 6e 63 6f 64 69 6e  red text encodin
36cb0 67 5d 20 61 73 20 74 68 65 20 66 6f 75 72 74 68  g] as the fourth
36cc0 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20   argument.** to 
36cd0 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
36ce0 66 75 6e 63 74 69 6f 6e 28 29 5d 2c 20 5b 73 71  function()], [sq
36cf0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
36d00 63 74 69 6f 6e 31 36 28 29 5d 2c 20 6f 72 0a 2a  ction16()], or.*
36d10 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  * [sqlite3_creat
36d20 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28 29 5d  e_function_v2()]
36d30 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
36d40 49 54 45 5f 44 45 54 45 52 4d 49 4e 49 53 54 49  ITE_DETERMINISTI
36d50 43 20 20 20 20 30 78 38 30 30 0a 0a 2f 2a 0a 2a  C    0x800../*.*
36d60 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 70 72  * CAPI3REF: Depr
36d70 65 63 61 74 65 64 20 46 75 6e 63 74 69 6f 6e 73  ecated Functions
36d80 0a 2a 2a 20 44 45 50 52 45 43 41 54 45 44 0a 2a  .** DEPRECATED.*
36d90 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74  *.** These funct
36da0 69 6f 6e 73 20 61 72 65 20 5b 64 65 70 72 65 63  ions are [deprec
36db0 61 74 65 64 5d 2e 20 20 49 6e 20 6f 72 64 65 72  ated].  In order
36dc0 20 74 6f 20 6d 61 69 6e 74 61 69 6e 0a 2a 2a 20   to maintain.** 
36dd0 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74  backwards compat
36de0 69 62 69 6c 69 74 79 20 77 69 74 68 20 6f 6c 64  ibility with old
36df0 65 72 20 63 6f 64 65 2c 20 74 68 65 73 65 20 66  er code, these f
36e00 75 6e 63 74 69 6f 6e 73 20 63 6f 6e 74 69 6e 75  unctions continu
36e10 65 20 0a 2a 2a 20 74 6f 20 62 65 20 73 75 70 70  e .** to be supp
36e20 6f 72 74 65 64 2e 20 20 48 6f 77 65 76 65 72 2c  orted.  However,
36e30 20 6e 65 77 20 61 70 70 6c 69 63 61 74 69 6f 6e   new application
36e40 73 20 73 68 6f 75 6c 64 20 61 76 6f 69 64 0a 2a  s should avoid.*
36e50 2a 20 74 68 65 20 75 73 65 20 6f 66 20 74 68 65  * the use of the
36e60 73 65 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 54  se functions.  T
36e70 6f 20 65 6e 63 6f 75 72 61 67 65 20 70 72 6f 67  o encourage prog
36e80 72 61 6d 6d 65 72 73 20 74 6f 20 61 76 6f 69 64  rammers to avoid
36e90 0a 2a 2a 20 74 68 65 73 65 20 66 75 6e 63 74 69  .** these functi
36ea0 6f 6e 73 2c 20 77 65 20 77 69 6c 6c 20 6e 6f 74  ons, we will not
36eb0 20 65 78 70 6c 61 69 6e 20 77 68 61 74 20 74 68   explain what th
36ec0 65 79 20 64 6f 2e 0a 2a 2f 0a 23 69 66 6e 64 65  ey do..*/.#ifnde
36ed0 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 44 45  f SQLITE_OMIT_DE
36ee0 50 52 45 43 41 54 45 44 0a 53 51 4c 49 54 45 5f  PRECATED.SQLITE_
36ef0 41 50 49 20 53 51 4c 49 54 45 5f 44 45 50 52 45  API SQLITE_DEPRE
36f00 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65  CATED int sqlite
36f10 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 75 6e  3_aggregate_coun
36f20 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  t(sqlite3_contex
36f30 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  t*);.SQLITE_API 
36f40 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45  SQLITE_DEPRECATE
36f50 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78  D int sqlite3_ex
36f60 70 69 72 65 64 28 73 71 6c 69 74 65 33 5f 73 74  pired(sqlite3_st
36f70 6d 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  mt*);.SQLITE_API
36f80 20 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54   SQLITE_DEPRECAT
36f90 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 74  ED int sqlite3_t
36fa0 72 61 6e 73 66 65 72 5f 62 69 6e 64 69 6e 67 73  ransfer_bindings
36fb0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
36fc0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a  sqlite3_stmt*);.
36fd0 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54  SQLITE_API SQLIT
36fe0 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e 74  E_DEPRECATED int
36ff0 20 73 71 6c 69 74 65 33 5f 67 6c 6f 62 61 6c 5f   sqlite3_global_
37000 72 65 63 6f 76 65 72 28 76 6f 69 64 29 3b 0a 53  recover(void);.S
37010 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45  QLITE_API SQLITE
37020 5f 44 45 50 52 45 43 41 54 45 44 20 76 6f 69 64  _DEPRECATED void
37030 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 5f   sqlite3_thread_
37040 63 6c 65 61 6e 75 70 28 76 6f 69 64 29 3b 0a 53  cleanup(void);.S
37050 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45  QLITE_API SQLITE
37060 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e 74 20  _DEPRECATED int 
37070 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 61  sqlite3_memory_a
37080 6c 61 72 6d 28 76 6f 69 64 28 2a 29 28 76 6f 69  larm(void(*)(voi
37090 64 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  d*,sqlite3_int64
370a0 2c 69 6e 74 29 2c 0a 20 20 20 20 20 20 20 20 20  ,int),.         
370b0 20 20 20 20 20 20 20 20 20 20 20 20 20 76 6f 69               voi
370c0 64 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  d*,sqlite3_int64
370d0 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a  );.#endif../*.**
370e0 20 43 41 50 49 33 52 45 46 3a 20 4f 62 74 61 69   CAPI3REF: Obtai
370f0 6e 69 6e 67 20 53 51 4c 20 56 61 6c 75 65 73 0a  ning SQL Values.
37100 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
37110 65 33 5f 76 61 6c 75 65 0a 2a 2a 0a 2a 2a 20 54  e3_value.**.** T
37120 68 65 20 43 2d 6c 61 6e 67 75 61 67 65 20 69 6d  he C-language im
37130 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
37140 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e  SQL functions an
37150 64 20 61 67 67 72 65 67 61 74 65 73 20 75 73 65  d aggregates use
37160 73 0a 2a 2a 20 74 68 69 73 20 73 65 74 20 6f 66  s.** this set of
37170 20 69 6e 74 65 72 66 61 63 65 20 72 6f 75 74 69   interface routi
37180 6e 65 73 20 74 6f 20 61 63 63 65 73 73 20 74 68  nes to access th
37190 65 20 70 61 72 61 6d 65 74 65 72 20 76 61 6c 75  e parameter valu
371a0 65 73 20 6f 6e 0a 2a 2a 20 74 68 65 20 66 75 6e  es on.** the fun
371b0 63 74 69 6f 6e 20 6f 72 20 61 67 67 72 65 67 61  ction or aggrega
371c0 74 65 2e 20 20 0a 2a 2a 0a 2a 2a 20 54 68 65 20  te.  .**.** The 
371d0 78 46 75 6e 63 20 28 66 6f 72 20 73 63 61 6c 61  xFunc (for scala
371e0 72 20 66 75 6e 63 74 69 6f 6e 73 29 20 6f 72 20  r functions) or 
371f0 78 53 74 65 70 20 28 66 6f 72 20 61 67 67 72 65  xStep (for aggre
37200 67 61 74 65 73 29 20 70 61 72 61 6d 65 74 65 72  gates) parameter
37210 73 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33  s.** to [sqlite3
37220 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
37230 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
37240 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
37250 31 36 28 29 5d 0a 2a 2a 20 64 65 66 69 6e 65 20  16()].** define 
37260 63 61 6c 6c 62 61 63 6b 73 20 74 68 61 74 20 69  callbacks that i
37270 6d 70 6c 65 6d 65 6e 74 20 74 68 65 20 53 51 4c  mplement the SQL
37280 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61   functions and a
37290 67 67 72 65 67 61 74 65 73 2e 0a 2a 2a 20 54 68  ggregates..** Th
372a0 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20  e 3rd parameter 
372b0 74 6f 20 74 68 65 73 65 20 63 61 6c 6c 62 61 63  to these callbac
372c0 6b 73 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f  ks is an array o
372d0 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 0a 2a 2a  f pointers to.**
372e0 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69   [protected sqli
372f0 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
37300 74 73 2e 20 20 54 68 65 72 65 20 69 73 20 6f 6e  ts.  There is on
37310 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  e [sqlite3_value
37320 5d 20 6f 62 6a 65 63 74 20 66 6f 72 0a 2a 2a 20  ] object for.** 
37330 65 61 63 68 20 70 61 72 61 6d 65 74 65 72 20 74  each parameter t
37340 6f 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69  o the SQL functi
37350 6f 6e 2e 20 20 54 68 65 73 65 20 72 6f 75 74 69  on.  These routi
37360 6e 65 73 20 61 72 65 20 75 73 65 64 20 74 6f 0a  nes are used to.
37370 2a 2a 20 65 78 74 72 61 63 74 20 76 61 6c 75 65  ** extract value
37380 73 20 66 72 6f 6d 20 74 68 65 20 5b 73 71 6c 69  s from the [sqli
37390 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
373a0 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ts..**.** These 
373b0 72 6f 75 74 69 6e 65 73 20 77 6f 72 6b 20 6f 6e  routines work on
373c0 6c 79 20 77 69 74 68 20 5b 70 72 6f 74 65 63 74  ly with [protect
373d0 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
373e0 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 41 6e  ] objects..** An
373f0 79 20 61 74 74 65 6d 70 74 20 74 6f 20 75 73 65  y attempt to use
37400 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   these routines 
37410 6f 6e 20 61 6e 20 5b 75 6e 70 72 6f 74 65 63 74  on an [unprotect
37420 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
37430 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 72 65 73 75  ].** object resu
37440 6c 74 73 20 69 6e 20 75 6e 64 65 66 69 6e 65 64  lts in undefined
37450 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a   behavior..**.**
37460 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73   ^These routines
37470 20 77 6f 72 6b 20 6a 75 73 74 20 6c 69 6b 65 20   work just like 
37480 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e  the correspondin
37490 67 20 5b 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73  g [column access
374a0 20 66 75 6e 63 74 69 6f 6e 73 5d 0a 2a 2a 20 65   functions].** e
374b0 78 63 65 70 74 20 74 68 61 74 20 74 68 65 73 65  xcept that these
374c0 20 72 6f 75 74 69 6e 65 73 20 74 61 6b 65 20 61   routines take a
374d0 20 73 69 6e 67 6c 65 20 5b 70 72 6f 74 65 63 74   single [protect
374e0 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
374f0 5d 20 6f 62 6a 65 63 74 0a 2a 2a 20 70 6f 69 6e  ] object.** poin
37500 74 65 72 20 69 6e 73 74 65 61 64 20 6f 66 20 61  ter instead of a
37510 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 5d   [sqlite3_stmt*]
37520 20 70 6f 69 6e 74 65 72 20 61 6e 64 20 61 6e 20   pointer and an 
37530 69 6e 74 65 67 65 72 20 63 6f 6c 75 6d 6e 20 6e  integer column n
37540 75 6d 62 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  umber..**.** ^Th
37550 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  e sqlite3_value_
37560 74 65 78 74 31 36 28 29 20 69 6e 74 65 72 66 61  text16() interfa
37570 63 65 20 65 78 74 72 61 63 74 73 20 61 20 55 54  ce extracts a UT
37580 46 2d 31 36 20 73 74 72 69 6e 67 0a 2a 2a 20 69  F-16 string.** i
37590 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 74  n the native byt
375a0 65 2d 6f 72 64 65 72 20 6f 66 20 74 68 65 20 68  e-order of the h
375b0 6f 73 74 20 6d 61 63 68 69 6e 65 2e 20 20 5e 54  ost machine.  ^T
375c0 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61  he.** sqlite3_va
375d0 6c 75 65 5f 74 65 78 74 31 36 62 65 28 29 20 61  lue_text16be() a
375e0 6e 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nd sqlite3_value
375f0 5f 74 65 78 74 31 36 6c 65 28 29 20 69 6e 74 65  _text16le() inte
37600 72 66 61 63 65 73 0a 2a 2a 20 65 78 74 72 61 63  rfaces.** extrac
37610 74 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 73  t UTF-16 strings
37620 20 61 73 20 62 69 67 2d 65 6e 64 69 61 6e 20 61   as big-endian a
37630 6e 64 20 6c 69 74 74 6c 65 2d 65 6e 64 69 61 6e  nd little-endian
37640 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a   respectively..*
37650 2a 0a 2a 2a 20 5e 28 54 68 65 20 73 71 6c 69 74  *.** ^(The sqlit
37660 65 33 5f 76 61 6c 75 65 5f 6e 75 6d 65 72 69 63  e3_value_numeric
37670 5f 74 79 70 65 28 29 20 69 6e 74 65 72 66 61 63  _type() interfac
37680 65 20 61 74 74 65 6d 70 74 73 20 74 6f 20 61 70  e attempts to ap
37690 70 6c 79 0a 2a 2a 20 6e 75 6d 65 72 69 63 20 61  ply.** numeric a
376a0 66 66 69 6e 69 74 79 20 74 6f 20 74 68 65 20 76  ffinity to the v
376b0 61 6c 75 65 2e 20 20 54 68 69 73 20 6d 65 61 6e  alue.  This mean
376c0 73 20 74 68 61 74 20 61 6e 20 61 74 74 65 6d 70  s that an attemp
376d0 74 20 69 73 0a 2a 2a 20 6d 61 64 65 20 74 6f 20  t is.** made to 
376e0 63 6f 6e 76 65 72 74 20 74 68 65 20 76 61 6c 75  convert the valu
376f0 65 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20  e to an integer 
37700 6f 72 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e  or floating poin
37710 74 2e 20 20 49 66 0a 2a 2a 20 73 75 63 68 20 61  t.  If.** such a
37720 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 70   conversion is p
37730 6f 73 73 69 62 6c 65 20 77 69 74 68 6f 75 74 20  ossible without 
37740 6c 6f 73 73 20 6f 66 20 69 6e 66 6f 72 6d 61 74  loss of informat
37750 69 6f 6e 20 28 69 6e 20 6f 74 68 65 72 0a 2a 2a  ion (in other.**
37760 20 77 6f 72 64 73 2c 20 69 66 20 74 68 65 20 76   words, if the v
37770 61 6c 75 65 20 69 73 20 61 20 73 74 72 69 6e 67  alue is a string
37780 20 74 68 61 74 20 6c 6f 6f 6b 73 20 6c 69 6b 65   that looks like
37790 20 61 20 6e 75 6d 62 65 72 29 0a 2a 2a 20 74 68   a number).** th
377a0 65 6e 20 74 68 65 20 63 6f 6e 76 65 72 73 69 6f  en the conversio
377b0 6e 20 69 73 20 70 65 72 66 6f 72 6d 65 64 2e 20  n is performed. 
377c0 20 4f 74 68 65 72 77 69 73 65 20 6e 6f 20 63 6f   Otherwise no co
377d0 6e 76 65 72 73 69 6f 6e 20 6f 63 63 75 72 73 2e  nversion occurs.
377e0 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  .** The [SQLITE_
377f0 49 4e 54 45 47 45 52 20 7c 20 64 61 74 61 74 79  INTEGER | dataty
37800 70 65 5d 20 61 66 74 65 72 20 63 6f 6e 76 65 72  pe] after conver
37810 73 69 6f 6e 20 69 73 20 72 65 74 75 72 6e 65 64  sion is returned
37820 2e 29 5e 0a 2a 2a 0a 2a 2a 20 50 6c 65 61 73 65  .)^.**.** Please
37830 20 70 61 79 20 70 61 72 74 69 63 75 6c 61 72 20   pay particular 
37840 61 74 74 65 6e 74 69 6f 6e 20 74 6f 20 74 68 65  attention to the
37850 20 66 61 63 74 20 74 68 61 74 20 74 68 65 20 70   fact that the p
37860 6f 69 6e 74 65 72 20 72 65 74 75 72 6e 65 64 0a  ointer returned.
37870 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  ** from [sqlite3
37880 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 29 5d 2c 20  _value_blob()], 
37890 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  [sqlite3_value_t
378a0 65 78 74 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73  ext()], or.** [s
378b0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
378c0 74 31 36 28 29 5d 20 63 61 6e 20 62 65 20 69 6e  t16()] can be in
378d0 76 61 6c 69 64 61 74 65 64 20 62 79 20 61 20 73  validated by a s
378e0 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 20 74  ubsequent call t
378f0 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61  o.** [sqlite3_va
37900 6c 75 65 5f 62 79 74 65 73 28 29 5d 2c 20 5b 73  lue_bytes()], [s
37910 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74  qlite3_value_byt
37920 65 73 31 36 28 29 5d 2c 20 5b 73 71 6c 69 74 65  es16()], [sqlite
37930 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c  3_value_text()],
37940 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  .** or [sqlite3_
37950 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29 5d 2e  value_text16()].
37960 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
37970 74 69 6e 65 73 20 6d 75 73 74 20 62 65 20 63 61  tines must be ca
37980 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61  lled from the sa
37990 6d 65 20 74 68 72 65 61 64 20 61 73 0a 2a 2a 20  me thread as.** 
379a0 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  the SQL function
379b0 20 74 68 61 74 20 73 75 70 70 6c 69 65 64 20 74   that supplied t
379c0 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  he [sqlite3_valu
379d0 65 2a 5d 20 70 61 72 61 6d 65 74 65 72 73 2e 0a  e*] parameters..
379e0 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f  */.SQLITE_API co
379f0 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
37a00 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 73 71 6c  3_value_blob(sql
37a10 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51  ite3_value*);.SQ
37a20 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
37a30 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73  ite3_value_bytes
37a40 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
37a50 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  ;.SQLITE_API int
37a60 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62   sqlite3_value_b
37a70 79 74 65 73 31 36 28 73 71 6c 69 74 65 33 5f 76  ytes16(sqlite3_v
37a80 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41  alue*);.SQLITE_A
37a90 50 49 20 64 6f 75 62 6c 65 20 73 71 6c 69 74 65  PI double sqlite
37aa0 33 5f 76 61 6c 75 65 5f 64 6f 75 62 6c 65 28 73  3_value_double(s
37ab0 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
37ac0 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
37ad0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74  qlite3_value_int
37ae0 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
37af0 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 73 71 6c  ;.SQLITE_API sql
37b00 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74  ite3_int64 sqlit
37b10 65 33 5f 76 61 6c 75 65 5f 69 6e 74 36 34 28 73  e3_value_int64(s
37b20 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
37b30 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74  SQLITE_API const
37b40 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20 2a   unsigned char *
37b50 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
37b60 78 74 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  xt(sqlite3_value
37b70 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63  *);.SQLITE_API c
37b80 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
37b90 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28  e3_value_text16(
37ba0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
37bb0 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73  .SQLITE_API cons
37bc0 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
37bd0 76 61 6c 75 65 5f 74 65 78 74 31 36 6c 65 28 73  value_text16le(s
37be0 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
37bf0 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74  SQLITE_API const
37c00 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76   void *sqlite3_v
37c10 61 6c 75 65 5f 74 65 78 74 31 36 62 65 28 73 71  alue_text16be(sq
37c20 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53  lite3_value*);.S
37c30 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
37c40 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 79 70 65  lite3_value_type
37c50 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
37c60 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  ;.SQLITE_API int
37c70 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 6e   sqlite3_value_n
37c80 75 6d 65 72 69 63 5f 74 79 70 65 28 73 71 6c 69  umeric_type(sqli
37c90 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 0a 2f 2a  te3_value*);../*
37ca0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 69  .** CAPI3REF: Fi
37cb0 6e 64 69 6e 67 20 54 68 65 20 53 75 62 74 79 70  nding The Subtyp
37cc0 65 20 4f 66 20 53 51 4c 20 56 61 6c 75 65 73 0a  e Of SQL Values.
37cd0 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
37ce0 65 33 5f 76 61 6c 75 65 0a 2a 2a 0a 2a 2a 20 54  e3_value.**.** T
37cf0 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  he sqlite3_value
37d00 5f 73 75 62 74 79 70 65 28 56 29 20 66 75 6e 63  _subtype(V) func
37d10 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65  tion returns the
37d20 20 73 75 62 74 79 70 65 20 66 6f 72 0a 2a 2a 20   subtype for.** 
37d30 61 6e 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d  an [application-
37d40 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63  defined SQL func
37d50 74 69 6f 6e 5d 20 61 72 67 75 6d 65 6e 74 20 56  tion] argument V
37d60 2e 20 20 54 68 65 20 73 75 62 74 79 70 65 0a 2a  .  The subtype.*
37d70 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 63 61  * information ca
37d80 6e 20 62 65 20 75 73 65 64 20 74 6f 20 70 61 73  n be used to pas
37d90 73 20 61 20 6c 69 6d 69 74 65 64 20 61 6d 6f 75  s a limited amou
37da0 6e 74 20 6f 66 20 63 6f 6e 74 65 78 74 20 66 72  nt of context fr
37db0 6f 6d 0a 2a 2a 20 6f 6e 65 20 53 51 4c 20 66 75  om.** one SQL fu
37dc0 6e 63 74 69 6f 6e 20 74 6f 20 61 6e 6f 74 68 65  nction to anothe
37dd0 72 2e 20 20 55 73 65 20 74 68 65 20 5b 73 71 6c  r.  Use the [sql
37de0 69 74 65 33 5f 72 65 73 75 6c 74 5f 73 75 62 74  ite3_result_subt
37df0 79 70 65 28 29 5d 0a 2a 2a 20 72 6f 75 74 69 6e  ype()].** routin
37e00 65 20 74 6f 20 73 65 74 20 74 68 65 20 73 75 62  e to set the sub
37e10 74 79 70 65 20 66 6f 72 20 74 68 65 20 72 65 74  type for the ret
37e20 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 61 6e 20  urn value of an 
37e30 53 51 4c 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a  SQL function..**
37e40 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 61 6b 65 73  .** SQLite makes
37e50 20 6e 6f 20 75 73 65 20 6f 66 20 73 75 62 74 79   no use of subty
37e60 70 65 20 69 74 73 65 6c 66 2e 20 20 49 74 20 6d  pe itself.  It m
37e70 65 72 65 6c 79 20 70 61 73 73 65 73 20 74 68 65  erely passes the
37e80 20 73 75 62 74 79 70 65 0a 2a 2a 20 66 72 6f 6d   subtype.** from
37e90 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66 20 6f   the result of o
37ea0 6e 65 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d  ne [application-
37eb0 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63  defined SQL func
37ec0 74 69 6f 6e 5d 20 69 6e 74 6f 20 74 68 65 0a 2a  tion] into the.*
37ed0 2a 20 69 6e 70 75 74 20 6f 66 20 61 6e 6f 74 68  * input of anoth
37ee0 65 72 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  er..*/.SQLITE_AP
37ef0 49 20 75 6e 73 69 67 6e 65 64 20 69 6e 74 20 73  I unsigned int s
37f00 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 73 75 62  qlite3_value_sub
37f10 74 79 70 65 28 73 71 6c 69 74 65 33 5f 76 61 6c  type(sqlite3_val
37f20 75 65 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ue*);../*.** CAP
37f30 49 33 52 45 46 3a 20 43 6f 70 79 20 41 6e 64 20  I3REF: Copy And 
37f40 46 72 65 65 20 53 51 4c 20 56 61 6c 75 65 73 0a  Free SQL Values.
37f50 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
37f60 65 33 5f 76 61 6c 75 65 0a 2a 2a 0a 2a 2a 20 5e  e3_value.**.** ^
37f70 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  The sqlite3_valu
37f80 65 5f 64 75 70 28 56 29 20 69 6e 74 65 72 66 61  e_dup(V) interfa
37f90 63 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20  ce makes a copy 
37fa0 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
37fb0 76 61 6c 75 65 5d 0a 2a 2a 20 6f 62 6a 65 63 74  value].** object
37fc0 20 44 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61   D and returns a
37fd0 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 61 74   pointer to that
37fe0 20 63 6f 70 79 2e 20 20 5e 54 68 65 20 5b 73 71   copy.  ^The [sq
37ff0 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 72 65 74  lite3_value] ret
38000 75 72 6e 65 64 0a 2a 2a 20 69 73 20 61 20 5b 70  urned.** is a [p
38010 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
38020 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 65  _value] object e
38030 76 65 6e 20 69 66 20 74 68 65 20 69 6e 70 75 74  ven if the input
38040 20 69 73 20 6e 6f 74 2e 0a 2a 2a 20 5e 54 68 65   is not..** ^The
38050 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 64   sqlite3_value_d
38060 75 70 28 56 29 20 69 6e 74 65 72 66 61 63 65 20  up(V) interface 
38070 72 65 74 75 72 6e 73 20 4e 55 4c 4c 20 69 66 20  returns NULL if 
38080 56 20 69 73 20 4e 55 4c 4c 20 6f 72 20 69 66 20  V is NULL or if 
38090 61 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  a.** memory allo
380a0 63 61 74 69 6f 6e 20 66 61 69 6c 73 2e 0a 2a 2a  cation fails..**
380b0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
380c0 5f 76 61 6c 75 65 5f 66 72 65 65 28 56 29 20 69  _value_free(V) i
380d0 6e 74 65 72 66 61 63 65 20 66 72 65 65 73 20 61  nterface frees a
380e0 6e 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  n [sqlite3_value
380f0 5d 20 6f 62 6a 65 63 74 0a 2a 2a 20 70 72 65 76  ] object.** prev
38100 69 6f 75 73 6c 79 20 6f 62 74 61 69 6e 65 64 20  iously obtained 
38110 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 76 61  from [sqlite3_va
38120 6c 75 65 5f 64 75 70 28 29 5d 2e 20 20 5e 49 66  lue_dup()].  ^If
38130 20 56 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69   V is a NULL poi
38140 6e 74 65 72 0a 2a 2a 20 74 68 65 6e 20 73 71 6c  nter.** then sql
38150 69 74 65 33 5f 76 61 6c 75 65 5f 66 72 65 65 28  ite3_value_free(
38160 56 29 20 69 73 20 61 20 68 61 72 6d 6c 65 73 73  V) is a harmless
38170 20 6e 6f 2d 6f 70 2e 0a 2a 2f 0a 53 51 4c 49 54   no-op..*/.SQLIT
38180 45 5f 41 50 49 20 73 71 6c 69 74 65 33 5f 76 61  E_API sqlite3_va
38190 6c 75 65 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c  lue *sqlite3_val
381a0 75 65 5f 64 75 70 28 63 6f 6e 73 74 20 73 71 6c  ue_dup(const sql
381b0 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51  ite3_value*);.SQ
381c0 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71  LITE_API void sq
381d0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 66 72 65 65  lite3_value_free
381e0 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
381f0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
38200 46 3a 20 4f 62 74 61 69 6e 20 41 67 67 72 65 67  F: Obtain Aggreg
38210 61 74 65 20 46 75 6e 63 74 69 6f 6e 20 43 6f 6e  ate Function Con
38220 74 65 78 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  text.** METHOD: 
38230 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 0a  sqlite3_context.
38240 2a 2a 0a 2a 2a 20 49 6d 70 6c 65 6d 65 6e 74 61  **.** Implementa
38250 74 69 6f 6e 73 20 6f 66 20 61 67 67 72 65 67 61  tions of aggrega
38260 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  te SQL functions
38270 20 75 73 65 20 74 68 69 73 0a 2a 2a 20 72 6f 75   use this.** rou
38280 74 69 6e 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65  tine to allocate
38290 20 6d 65 6d 6f 72 79 20 66 6f 72 20 73 74 6f 72   memory for stor
382a0 69 6e 67 20 74 68 65 69 72 20 73 74 61 74 65 2e  ing their state.
382b0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73  .**.** ^The firs
382c0 74 20 74 69 6d 65 20 74 68 65 20 73 71 6c 69 74  t time the sqlit
382d0 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e  e3_aggregate_con
382e0 74 65 78 74 28 43 2c 4e 29 20 72 6f 75 74 69 6e  text(C,N) routin
382f0 65 20 69 73 20 63 61 6c 6c 65 64 20 0a 2a 2a 20  e is called .** 
38300 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61 72  for a particular
38310 20 61 67 67 72 65 67 61 74 65 20 66 75 6e 63 74   aggregate funct
38320 69 6f 6e 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 61  ion, SQLite.** a
38330 6c 6c 6f 63 61 74 65 73 20 4e 20 6f 66 20 6d 65  llocates N of me
38340 6d 6f 72 79 2c 20 7a 65 72 6f 65 73 20 6f 75 74  mory, zeroes out
38350 20 74 68 61 74 20 6d 65 6d 6f 72 79 2c 20 61 6e   that memory, an
38360 64 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  d returns a poin
38370 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 6e 65  ter.** to the ne
38380 77 20 6d 65 6d 6f 72 79 2e 20 5e 4f 6e 20 73 65  w memory. ^On se
38390 63 6f 6e 64 20 61 6e 64 20 73 75 62 73 65 71 75  cond and subsequ
383a0 65 6e 74 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20  ent calls to.** 
383b0 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74  sqlite3_aggregat
383c0 65 5f 63 6f 6e 74 65 78 74 28 29 20 66 6f 72 20  e_context() for 
383d0 74 68 65 20 73 61 6d 65 20 61 67 67 72 65 67 61  the same aggrega
383e0 74 65 20 66 75 6e 63 74 69 6f 6e 20 69 6e 73 74  te function inst
383f0 61 6e 63 65 2c 0a 2a 2a 20 74 68 65 20 73 61 6d  ance,.** the sam
38400 65 20 62 75 66 66 65 72 20 69 73 20 72 65 74 75  e buffer is retu
38410 72 6e 65 64 2e 20 20 53 71 6c 69 74 65 33 5f 61  rned.  Sqlite3_a
38420 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74  ggregate_context
38430 28 29 20 69 73 20 6e 6f 72 6d 61 6c 6c 79 0a 2a  () is normally.*
38440 2a 20 63 61 6c 6c 65 64 20 6f 6e 63 65 20 66 6f  * called once fo
38450 72 20 65 61 63 68 20 69 6e 76 6f 63 61 74 69 6f  r each invocatio
38460 6e 20 6f 66 20 74 68 65 20 78 53 74 65 70 20 63  n of the xStep c
38470 61 6c 6c 62 61 63 6b 20 61 6e 64 20 74 68 65 6e  allback and then
38480 20 6f 6e 65 0a 2a 2a 20 6c 61 73 74 20 74 69 6d   one.** last tim
38490 65 20 77 68 65 6e 20 74 68 65 20 78 46 69 6e 61  e when the xFina
384a0 6c 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e  l callback is in
384b0 76 6f 6b 65 64 2e 20 20 5e 28 57 68 65 6e 20 6e  voked.  ^(When n
384c0 6f 20 72 6f 77 73 20 6d 61 74 63 68 0a 2a 2a 20  o rows match.** 
384d0 61 6e 20 61 67 67 72 65 67 61 74 65 20 71 75 65  an aggregate que
384e0 72 79 2c 20 74 68 65 20 78 53 74 65 70 28 29 20  ry, the xStep() 
384f0 63 61 6c 6c 62 61 63 6b 20 6f 66 20 74 68 65 20  callback of the 
38500 61 67 67 72 65 67 61 74 65 20 66 75 6e 63 74 69  aggregate functi
38510 6f 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61  on.** implementa
38520 74 69 6f 6e 20 69 73 20 6e 65 76 65 72 20 63 61  tion is never ca
38530 6c 6c 65 64 20 61 6e 64 20 78 46 69 6e 61 6c 28  lled and xFinal(
38540 29 20 69 73 20 63 61 6c 6c 65 64 20 65 78 61 63  ) is called exac
38550 74 6c 79 20 6f 6e 63 65 2e 0a 2a 2a 20 49 6e 20  tly once..** In 
38560 74 68 6f 73 65 20 63 61 73 65 73 2c 20 73 71 6c  those cases, sql
38570 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63  ite3_aggregate_c
38580 6f 6e 74 65 78 74 28 29 20 6d 69 67 68 74 20 62  ontext() might b
38590 65 20 63 61 6c 6c 65 64 20 66 6f 72 20 74 68 65  e called for the
385a0 0a 2a 2a 20 66 69 72 73 74 20 74 69 6d 65 20 66  .** first time f
385b0 72 6f 6d 20 77 69 74 68 69 6e 20 78 46 69 6e 61  rom within xFina
385c0 6c 28 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68  l().)^.**.** ^Th
385d0 65 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67  e sqlite3_aggreg
385e0 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29  ate_context(C,N)
385f0 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
38600 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
38610 0a 2a 2a 20 77 68 65 6e 20 66 69 72 73 74 20 63  .** when first c
38620 61 6c 6c 65 64 20 69 66 20 4e 20 69 73 20 6c 65  alled if N is le
38630 73 73 20 74 68 61 6e 20 6f 72 20 65 71 75 61 6c  ss than or equal
38640 20 74 6f 20 7a 65 72 6f 20 6f 72 20 69 66 20 61   to zero or if a
38650 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63   memory.** alloc
38660 61 74 65 20 65 72 72 6f 72 20 6f 63 63 75 72 73  ate error occurs
38670 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 61 6d  ..**.** ^(The am
38680 6f 75 6e 74 20 6f 66 20 73 70 61 63 65 20 61 6c  ount of space al
38690 6c 6f 63 61 74 65 64 20 62 79 20 73 71 6c 69 74  located by sqlit
386a0 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e  e3_aggregate_con
386b0 74 65 78 74 28 43 2c 4e 29 20 69 73 0a 2a 2a 20  text(C,N) is.** 
386c0 64 65 74 65 72 6d 69 6e 65 64 20 62 79 20 74 68  determined by th
386d0 65 20 4e 20 70 61 72 61 6d 65 74 65 72 20 6f 6e  e N parameter on
386e0 20 66 69 72 73 74 20 73 75 63 63 65 73 73 66 75   first successfu
386f0 6c 20 63 61 6c 6c 2e 20 20 43 68 61 6e 67 69 6e  l call.  Changin
38700 67 20 74 68 65 0a 2a 2a 20 76 61 6c 75 65 20 6f  g the.** value o
38710 66 20 4e 20 69 6e 20 73 75 62 73 65 71 75 65 6e  f N in subsequen
38720 74 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  t call to sqlite
38730 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74  3_aggregate_cont
38740 65 78 74 28 29 20 77 69 74 68 69 6e 0a 2a 2a 20  ext() within.** 
38750 74 68 65 20 73 61 6d 65 20 61 67 67 72 65 67 61  the same aggrega
38760 74 65 20 66 75 6e 63 74 69 6f 6e 20 69 6e 73 74  te function inst
38770 61 6e 63 65 20 77 69 6c 6c 20 6e 6f 74 20 72 65  ance will not re
38780 73 69 7a 65