/ Hex Artifact Content
Login

Artifact bf745d785ea9d1ba3a89a71fc2b592727a400974:


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 76 65 72 73 69 6f 6e  ** Since version
0f00: 20 33 2e 36 2e 31 38 2c 20 53 51 4c 69 74 65 20   3.6.18, SQLite 
0f10: 73 6f 75 72 63 65 20 63 6f 64 65 20 68 61 73 20  source code has 
0f20: 62 65 65 6e 20 73 74 6f 72 65 64 20 69 6e 20 74  been stored in t
0f30: 68 65 0a 2a 2a 20 3c 61 20 68 72 65 66 3d 22 68  he.** <a href="h
0f40: 74 74 70 3a 2f 2f 77 77 77 2e 66 6f 73 73 69 6c  ttp://www.fossil
0f50: 2d 73 63 6d 2e 6f 72 67 2f 22 3e 46 6f 73 73 69  -scm.org/">Fossi
0f60: 6c 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  l configuration 
0f70: 6d 61 6e 61 67 65 6d 65 6e 74 0a 2a 2a 20 73 79  management.** sy
0f80: 73 74 65 6d 3c 2f 61 3e 2e 20 20 5e 54 68 65 20  stem</a>.  ^The 
0f90: 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 44  SQLITE_SOURCE_ID
0fa0: 20 6d 61 63 72 6f 20 65 76 61 6c 75 61 74 65 73   macro evaluates
0fb0: 20 74 6f 0a 2a 2a 20 61 20 73 74 72 69 6e 67 20   to.** a string 
0fc0: 77 68 69 63 68 20 69 64 65 6e 74 69 66 69 65 73  which identifies
0fd0: 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 63 68   a particular ch
0fe0: 65 63 6b 2d 69 6e 20 6f 66 20 53 51 4c 69 74 65  eck-in of SQLite
0ff0: 0a 2a 2a 20 77 69 74 68 69 6e 20 69 74 73 20 63  .** within its c
1000: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6d 61 6e  onfiguration man
1010: 61 67 65 6d 65 6e 74 20 73 79 73 74 65 6d 2e 20  agement system. 
1020: 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 53 4f 55   ^The SQLITE_SOU
1030: 52 43 45 5f 49 44 0a 2a 2a 20 73 74 72 69 6e 67  RCE_ID.** string
1040: 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 20 64 61   contains the da
1050: 74 65 20 61 6e 64 20 74 69 6d 65 20 6f 66 20 74  te and time of t
1060: 68 65 20 63 68 65 63 6b 2d 69 6e 20 28 55 54 43  he check-in (UTC
1070: 29 20 61 6e 64 20 61 6e 20 53 48 41 31 0a 2a 2a  ) and an SHA1.**
1080: 20 68 61 73 68 20 6f 66 20 74 68 65 20 65 6e 74   hash of the ent
1090: 69 72 65 20 73 6f 75 72 63 65 20 74 72 65 65 2e  ire source tree.
10a0: 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a  .**.** See also:
10b0: 20 5b 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72   [sqlite3_libver
10c0: 73 69 6f 6e 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c  sion()],.** [sql
10d0: 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f  ite3_libversion_
10e0: 6e 75 6d 62 65 72 28 29 5d 2c 20 5b 73 71 6c 69  number()], [sqli
10f0: 74 65 33 5f 73 6f 75 72 63 65 69 64 28 29 5d 2c  te3_sourceid()],
1100: 0a 2a 2a 20 5b 73 71 6c 69 74 65 5f 76 65 72 73  .** [sqlite_vers
1110: 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  ion()] and [sqli
1120: 74 65 5f 73 6f 75 72 63 65 5f 69 64 28 29 5d 2e  te_source_id()].
1130: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
1140: 54 45 5f 56 45 52 53 49 4f 4e 20 20 20 20 20 20  TE_VERSION      
1150: 20 20 22 2d 2d 56 45 52 53 2d 2d 22 0a 23 64 65    "--VERS--".#de
1160: 66 69 6e 65 20 53 51 4c 49 54 45 5f 56 45 52 53  fine SQLITE_VERS
1170: 49 4f 4e 5f 4e 55 4d 42 45 52 20 2d 2d 56 45 52  ION_NUMBER --VER
1180: 53 49 4f 4e 2d 4e 55 4d 42 45 52 2d 2d 0a 23 64  SION-NUMBER--.#d
1190: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 4f 55  efine SQLITE_SOU
11a0: 52 43 45 5f 49 44 20 20 20 20 20 20 22 2d 2d 53  RCE_ID      "--S
11b0: 4f 55 52 43 45 2d 49 44 2d 2d 22 0a 0a 2f 2a 0a  OURCE-ID--"../*.
11c0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e  ** CAPI3REF: Run
11d0: 2d 54 69 6d 65 20 4c 69 62 72 61 72 79 20 56 65  -Time Library Ve
11e0: 72 73 69 6f 6e 20 4e 75 6d 62 65 72 73 0a 2a 2a  rsion Numbers.**
11f0: 20 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c 69 74   KEYWORDS: sqlit
1200: 65 33 5f 76 65 72 73 69 6f 6e 2c 20 73 71 6c 69  e3_version, sqli
1210: 74 65 33 5f 73 6f 75 72 63 65 69 64 0a 2a 2a 0a  te3_sourceid.**.
1220: 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 72 66 61  ** These interfa
1230: 63 65 73 20 70 72 6f 76 69 64 65 20 74 68 65 20  ces provide the 
1240: 73 61 6d 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  same information
1250: 20 61 73 20 74 68 65 20 5b 53 51 4c 49 54 45 5f   as the [SQLITE_
1260: 56 45 52 53 49 4f 4e 5d 2c 0a 2a 2a 20 5b 53 51  VERSION],.** [SQ
1270: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d  LITE_VERSION_NUM
1280: 42 45 52 5d 2c 20 61 6e 64 20 5b 53 51 4c 49 54  BER], and [SQLIT
1290: 45 5f 53 4f 55 52 43 45 5f 49 44 5d 20 43 20 70  E_SOURCE_ID] C p
12a0: 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72  reprocessor macr
12b0: 6f 73 0a 2a 2a 20 62 75 74 20 61 72 65 20 61 73  os.** but are as
12c0: 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68  sociated with th
12d0: 65 20 6c 69 62 72 61 72 79 20 69 6e 73 74 65 61  e library instea
12e0: 64 20 6f 66 20 74 68 65 20 68 65 61 64 65 72 20  d of the header 
12f0: 66 69 6c 65 2e 20 20 5e 28 43 61 75 74 69 6f 75  file.  ^(Cautiou
1300: 73 0a 2a 2a 20 70 72 6f 67 72 61 6d 6d 65 72 73  s.** programmers
1310: 20 6d 69 67 68 74 20 69 6e 63 6c 75 64 65 20 61   might include a
1320: 73 73 65 72 74 28 29 20 73 74 61 74 65 6d 65 6e  ssert() statemen
1330: 74 73 20 69 6e 20 74 68 65 69 72 20 61 70 70 6c  ts in their appl
1340: 69 63 61 74 69 6f 6e 20 74 6f 0a 2a 2a 20 76 65  ication to.** ve
1350: 72 69 66 79 20 74 68 61 74 20 76 61 6c 75 65 73  rify that values
1360: 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65   returned by the
1370: 73 65 20 69 6e 74 65 72 66 61 63 65 73 20 6d 61  se interfaces ma
1380: 74 63 68 20 74 68 65 20 6d 61 63 72 6f 73 20 69  tch the macros i
1390: 6e 0a 2a 2a 20 74 68 65 20 68 65 61 64 65 72 2c  n.** the header,
13a0: 20 61 6e 64 20 74 68 75 73 20 65 6e 73 75 72 65   and thus ensure
13b0: 20 74 68 61 74 20 74 68 65 20 61 70 70 6c 69 63   that the applic
13c0: 61 74 69 6f 6e 20 69 73 0a 2a 2a 20 63 6f 6d 70  ation is.** comp
13d0: 69 6c 65 64 20 77 69 74 68 20 6d 61 74 63 68 69  iled with matchi
13e0: 6e 67 20 6c 69 62 72 61 72 79 20 61 6e 64 20 68  ng library and h
13f0: 65 61 64 65 72 20 66 69 6c 65 73 2e 0a 2a 2a 0a  eader files..**.
1400: 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c  ** <blockquote><
1410: 70 72 65 3e 0a 2a 2a 20 61 73 73 65 72 74 28 20  pre>.** assert( 
1420: 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69  sqlite3_libversi
1430: 6f 6e 5f 6e 75 6d 62 65 72 28 29 3d 3d 53 51 4c  on_number()==SQL
1440: 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42  ITE_VERSION_NUMB
1450: 45 52 20 29 3b 0a 2a 2a 20 61 73 73 65 72 74 28  ER );.** assert(
1460: 20 73 74 72 63 6d 70 28 73 71 6c 69 74 65 33 5f   strcmp(sqlite3_
1470: 73 6f 75 72 63 65 69 64 28 29 2c 53 51 4c 49 54  sourceid(),SQLIT
1480: 45 5f 53 4f 55 52 43 45 5f 49 44 29 3d 3d 30 20  E_SOURCE_ID)==0 
1490: 29 3b 0a 2a 2a 20 61 73 73 65 72 74 28 20 73 74  );.** assert( st
14a0: 72 63 6d 70 28 73 71 6c 69 74 65 33 5f 6c 69 62  rcmp(sqlite3_lib
14b0: 76 65 72 73 69 6f 6e 28 29 2c 53 51 4c 49 54 45  version(),SQLITE
14c0: 5f 56 45 52 53 49 4f 4e 29 3d 3d 30 20 29 3b 0a  _VERSION)==0 );.
14d0: 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b  ** </pre></block
14e0: 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  quote>)^.**.** ^
14f0: 54 68 65 20 73 71 6c 69 74 65 33 5f 76 65 72 73  The sqlite3_vers
1500: 69 6f 6e 5b 5d 20 73 74 72 69 6e 67 20 63 6f 6e  ion[] string con
1510: 73 74 61 6e 74 20 63 6f 6e 74 61 69 6e 73 20 74  stant contains t
1520: 68 65 20 74 65 78 74 20 6f 66 20 5b 53 51 4c 49  he text of [SQLI
1530: 54 45 5f 56 45 52 53 49 4f 4e 5d 0a 2a 2a 20 6d  TE_VERSION].** m
1540: 61 63 72 6f 2e 20 20 5e 54 68 65 20 73 71 6c 69  acro.  ^The sqli
1550: 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29  te3_libversion()
1560: 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e   function return
1570: 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  s a pointer to t
1580: 68 65 0a 2a 2a 20 74 6f 20 74 68 65 20 73 71 6c  he.** to the sql
1590: 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b 5d 20 73  ite3_version[] s
15a0: 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e 74 2e 20  tring constant. 
15b0: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6c 69 62   The sqlite3_lib
15c0: 76 65 72 73 69 6f 6e 28 29 0a 2a 2a 20 66 75 6e  version().** fun
15d0: 63 74 69 6f 6e 20 69 73 20 70 72 6f 76 69 64 65  ction is provide
15e0: 64 20 66 6f 72 20 75 73 65 20 69 6e 20 44 4c 4c  d for use in DLL
15f0: 73 20 73 69 6e 63 65 20 44 4c 4c 20 75 73 65 72  s since DLL user
1600: 73 20 75 73 75 61 6c 6c 79 20 64 6f 20 6e 6f 74  s usually do not
1610: 20 68 61 76 65 0a 2a 2a 20 64 69 72 65 63 74 20   have.** direct 
1620: 61 63 63 65 73 73 20 74 6f 20 73 74 72 69 6e 67  access to string
1630: 20 63 6f 6e 73 74 61 6e 74 73 20 77 69 74 68 69   constants withi
1640: 6e 20 74 68 65 20 44 4c 4c 2e 20 20 5e 54 68 65  n the DLL.  ^The
1650: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6c 69 62 76  .** sqlite3_libv
1660: 65 72 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 29 20  ersion_number() 
1670: 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73  function returns
1680: 20 61 6e 20 69 6e 74 65 67 65 72 20 65 71 75 61   an integer equa
1690: 6c 20 74 6f 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  l to.** [SQLITE_
16a0: 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d 2e  VERSION_NUMBER].
16b0: 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73    ^The sqlite3_s
16c0: 6f 75 72 63 65 69 64 28 29 20 66 75 6e 63 74 69  ourceid() functi
16d0: 6f 6e 20 72 65 74 75 72 6e 73 20 0a 2a 2a 20 61  on returns .** a
16e0: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 73 74   pointer to a st
16f0: 72 69 6e 67 20 63 6f 6e 73 74 61 6e 74 20 77 68  ring constant wh
1700: 6f 73 65 20 76 61 6c 75 65 20 69 73 20 74 68 65  ose value is the
1710: 20 73 61 6d 65 20 61 73 20 74 68 65 20 0a 2a 2a   same as the .**
1720: 20 5b 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f   [SQLITE_SOURCE_
1730: 49 44 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73  ID] C preprocess
1740: 6f 72 20 6d 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20  or macro..**.** 
1750: 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74  See also: [sqlit
1760: 65 5f 76 65 72 73 69 6f 6e 28 29 5d 20 61 6e 64  e_version()] and
1770: 20 5b 73 71 6c 69 74 65 5f 73 6f 75 72 63 65 5f   [sqlite_source_
1780: 69 64 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45  id()]..*/.SQLITE
1790: 5f 45 58 54 45 52 4e 20 63 6f 6e 73 74 20 63 68  _EXTERN const ch
17a0: 61 72 20 73 71 6c 69 74 65 33 5f 76 65 72 73 69  ar sqlite3_versi
17b0: 6f 6e 5b 5d 3b 0a 63 6f 6e 73 74 20 63 68 61 72  on[];.const char
17c0: 20 2a 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72   *sqlite3_libver
17d0: 73 69 6f 6e 28 76 6f 69 64 29 3b 0a 63 6f 6e 73  sion(void);.cons
17e0: 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
17f0: 73 6f 75 72 63 65 69 64 28 76 6f 69 64 29 3b 0a  sourceid(void);.
1800: 69 6e 74 20 73 71 6c 69 74 65 33 5f 6c 69 62 76  int sqlite3_libv
1810: 65 72 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 76 6f  ersion_number(vo
1820: 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  id);../*.** CAPI
1830: 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d 65 20 4c  3REF: Run-Time L
1840: 69 62 72 61 72 79 20 43 6f 6d 70 69 6c 61 74 69  ibrary Compilati
1850: 6f 6e 20 4f 70 74 69 6f 6e 73 20 44 69 61 67 6e  on Options Diagn
1860: 6f 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20 5e 54 68  ostics.**.** ^Th
1870: 65 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c  e sqlite3_compil
1880: 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28 29 20 66  eoption_used() f
1890: 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20  unction returns 
18a0: 30 20 6f 72 20 31 20 0a 2a 2a 20 69 6e 64 69 63  0 or 1 .** indic
18b0: 61 74 69 6e 67 20 77 68 65 74 68 65 72 20 74 68  ating whether th
18c0: 65 20 73 70 65 63 69 66 69 65 64 20 6f 70 74 69  e specified opti
18d0: 6f 6e 20 77 61 73 20 64 65 66 69 6e 65 64 20 61  on was defined a
18e0: 74 20 0a 2a 2a 20 63 6f 6d 70 69 6c 65 20 74 69  t .** compile ti
18f0: 6d 65 2e 20 20 5e 54 68 65 20 53 51 4c 49 54 45  me.  ^The SQLITE
1900: 5f 20 70 72 65 66 69 78 20 6d 61 79 20 62 65 20  _ prefix may be 
1910: 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 74 68 65  omitted from the
1920: 20 0a 2a 2a 20 6f 70 74 69 6f 6e 20 6e 61 6d 65   .** option name
1930: 20 70 61 73 73 65 64 20 74 6f 20 73 71 6c 69 74   passed to sqlit
1940: 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e  e3_compileoption
1950: 5f 75 73 65 64 28 29 2e 20 20 0a 2a 2a 0a 2a 2a  _used().  .**.**
1960: 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f   ^The sqlite3_co
1970: 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28  mpileoption_get(
1980: 29 20 66 75 6e 63 74 69 6f 6e 20 61 6c 6c 6f 77  ) function allow
1990: 73 20 69 74 65 72 61 74 69 6e 67 0a 2a 2a 20 6f  s iterating.** o
19a0: 76 65 72 20 74 68 65 20 6c 69 73 74 20 6f 66 20  ver the list of 
19b0: 6f 70 74 69 6f 6e 73 20 74 68 61 74 20 77 65 72  options that wer
19c0: 65 20 64 65 66 69 6e 65 64 20 61 74 20 63 6f 6d  e defined at com
19d0: 70 69 6c 65 20 74 69 6d 65 20 62 79 0a 2a 2a 20  pile time by.** 
19e0: 72 65 74 75 72 6e 69 6e 67 20 74 68 65 20 4e 2d  returning the N-
19f0: 74 68 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 20  th compile time 
1a00: 6f 70 74 69 6f 6e 20 73 74 72 69 6e 67 2e 20 20  option string.  
1a10: 5e 49 66 20 4e 20 69 73 20 6f 75 74 20 6f 66 20  ^If N is out of 
1a20: 72 61 6e 67 65 2c 0a 2a 2a 20 73 71 6c 69 74 65  range,.** sqlite
1a30: 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f  3_compileoption_
1a40: 67 65 74 28 29 20 72 65 74 75 72 6e 73 20 61 20  get() returns a 
1a50: 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 5e  NULL pointer.  ^
1a60: 54 68 65 20 53 51 4c 49 54 45 5f 20 0a 2a 2a 20  The SQLITE_ .** 
1a70: 70 72 65 66 69 78 20 69 73 20 6f 6d 69 74 74 65  prefix is omitte
1a80: 64 20 66 72 6f 6d 20 61 6e 79 20 73 74 72 69 6e  d from any strin
1a90: 67 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 0a  gs returned by .
1aa0: 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69  ** sqlite3_compi
1ab0: 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29 2e 0a  leoption_get()..
1ac0: 2a 2a 0a 2a 2a 20 5e 53 75 70 70 6f 72 74 20 66  **.** ^Support f
1ad0: 6f 72 20 74 68 65 20 64 69 61 67 6e 6f 73 74 69  or the diagnosti
1ae0: 63 20 66 75 6e 63 74 69 6f 6e 73 20 73 71 6c 69  c functions sqli
1af0: 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f  te3_compileoptio
1b00: 6e 5f 75 73 65 64 28 29 0a 2a 2a 20 61 6e 64 20  n_used().** and 
1b10: 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f  sqlite3_compileo
1b20: 70 74 69 6f 6e 5f 67 65 74 28 29 20 6d 61 79 20  ption_get() may 
1b30: 62 65 20 6f 6d 69 74 74 65 64 20 62 79 20 73 70  be omitted by sp
1b40: 65 63 69 66 79 69 6e 67 20 74 68 65 20 0a 2a 2a  ecifying the .**
1b50: 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 43 4f   [SQLITE_OMIT_CO
1b60: 4d 50 49 4c 45 4f 50 54 49 4f 4e 5f 44 49 41 47  MPILEOPTION_DIAG
1b70: 53 5d 20 6f 70 74 69 6f 6e 20 61 74 20 63 6f 6d  S] option at com
1b80: 70 69 6c 65 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a  pile time..**.**
1b90: 20 53 65 65 20 61 6c 73 6f 3a 20 53 51 4c 20 66   See also: SQL f
1ba0: 75 6e 63 74 69 6f 6e 73 20 5b 73 71 6c 69 74 65  unctions [sqlite
1bb0: 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75  _compileoption_u
1bc0: 73 65 64 28 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73  sed()] and.** [s
1bd0: 71 6c 69 74 65 5f 63 6f 6d 70 69 6c 65 6f 70 74  qlite_compileopt
1be0: 69 6f 6e 5f 67 65 74 28 29 5d 20 61 6e 64 20 74  ion_get()] and t
1bf0: 68 65 20 5b 63 6f 6d 70 69 6c 65 5f 6f 70 74 69  he [compile_opti
1c00: 6f 6e 73 20 70 72 61 67 6d 61 5d 2e 0a 2a 2f 0a  ons pragma]..*/.
1c10: 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 4f  #ifndef SQLITE_O
1c20: 4d 49 54 5f 43 4f 4d 50 49 4c 45 4f 50 54 49 4f  MIT_COMPILEOPTIO
1c30: 4e 5f 44 49 41 47 53 0a 69 6e 74 20 73 71 6c 69  N_DIAGS.int sqli
1c40: 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f  te3_compileoptio
1c50: 6e 5f 75 73 65 64 28 63 6f 6e 73 74 20 63 68 61  n_used(const cha
1c60: 72 20 2a 7a 4f 70 74 4e 61 6d 65 29 3b 0a 63 6f  r *zOptName);.co
1c70: 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65  nst char *sqlite
1c80: 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f  3_compileoption_
1c90: 67 65 74 28 69 6e 74 20 4e 29 3b 0a 23 65 6e 64  get(int N);.#end
1ca0: 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  if../*.** CAPI3R
1cb0: 45 46 3a 20 54 65 73 74 20 54 6f 20 53 65 65 20  EF: Test To See 
1cc0: 49 66 20 54 68 65 20 4c 69 62 72 61 72 79 20 49  If The Library I
1cd0: 73 20 54 68 72 65 61 64 73 61 66 65 0a 2a 2a 0a  s Threadsafe.**.
1ce0: 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
1cf0: 74 68 72 65 61 64 73 61 66 65 28 29 20 66 75 6e  threadsafe() fun
1d00: 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 7a 65  ction returns ze
1d10: 72 6f 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69  ro if and only i
1d20: 66 0a 2a 2a 20 53 51 4c 69 74 65 20 77 61 73 20  f.** SQLite was 
1d30: 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 6d 75  compiled with mu
1d40: 74 65 78 69 6e 67 20 63 6f 64 65 20 6f 6d 69 74  texing code omit
1d50: 74 65 64 20 64 75 65 20 74 6f 20 74 68 65 0a 2a  ted due to the.*
1d60: 2a 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44  * [SQLITE_THREAD
1d70: 53 41 46 45 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  SAFE] compile-ti
1d80: 6d 65 20 6f 70 74 69 6f 6e 20 62 65 69 6e 67 20  me option being 
1d90: 73 65 74 20 74 6f 20 30 2e 0a 2a 2a 0a 2a 2a 20  set to 0..**.** 
1da0: 53 51 4c 69 74 65 20 63 61 6e 20 62 65 20 63 6f  SQLite can be co
1db0: 6d 70 69 6c 65 64 20 77 69 74 68 20 6f 72 20 77  mpiled with or w
1dc0: 69 74 68 6f 75 74 20 6d 75 74 65 78 65 73 2e 20  ithout mutexes. 
1dd0: 20 57 68 65 6e 0a 2a 2a 20 74 68 65 20 5b 53 51   When.** the [SQ
1de0: 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d  LITE_THREADSAFE]
1df0: 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20   C preprocessor 
1e00: 6d 61 63 72 6f 20 69 73 20 31 20 6f 72 20 32 2c  macro is 1 or 2,
1e10: 20 6d 75 74 65 78 65 73 0a 2a 2a 20 61 72 65 20   mutexes.** are 
1e20: 65 6e 61 62 6c 65 64 20 61 6e 64 20 53 51 4c 69  enabled and SQLi
1e30: 74 65 20 69 73 20 74 68 72 65 61 64 73 61 66 65  te is threadsafe
1e40: 2e 20 20 57 68 65 6e 20 74 68 65 0a 2a 2a 20 5b  .  When the.** [
1e50: 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
1e60: 45 5d 20 6d 61 63 72 6f 20 69 73 20 30 2c 20 0a  E] macro is 0, .
1e70: 2a 2a 20 74 68 65 20 6d 75 74 65 78 65 73 20 61  ** the mutexes a
1e80: 72 65 20 6f 6d 69 74 74 65 64 2e 20 20 57 69 74  re omitted.  Wit
1e90: 68 6f 75 74 20 74 68 65 20 6d 75 74 65 78 65 73  hout the mutexes
1ea0: 2c 20 69 74 20 69 73 20 6e 6f 74 20 73 61 66 65  , it is not safe
1eb0: 0a 2a 2a 20 74 6f 20 75 73 65 20 53 51 4c 69 74  .** to use SQLit
1ec0: 65 20 63 6f 6e 63 75 72 72 65 6e 74 6c 79 20 66  e concurrently f
1ed0: 72 6f 6d 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e  rom more than on
1ee0: 65 20 74 68 72 65 61 64 2e 0a 2a 2a 0a 2a 2a 20  e thread..**.** 
1ef0: 45 6e 61 62 6c 69 6e 67 20 6d 75 74 65 78 65 73  Enabling mutexes
1f00: 20 69 6e 63 75 72 73 20 61 20 6d 65 61 73 75 72   incurs a measur
1f10: 61 62 6c 65 20 70 65 72 66 6f 72 6d 61 6e 63 65  able performance
1f20: 20 70 65 6e 61 6c 74 79 2e 0a 2a 2a 20 53 6f 20   penalty..** So 
1f30: 69 66 20 73 70 65 65 64 20 69 73 20 6f 66 20 75  if speed is of u
1f40: 74 6d 6f 73 74 20 69 6d 70 6f 72 74 61 6e 63 65  tmost importance
1f50: 2c 20 69 74 20 6d 61 6b 65 73 20 73 65 6e 73 65  , it makes sense
1f60: 20 74 6f 20 64 69 73 61 62 6c 65 0a 2a 2a 20 74   to disable.** t
1f70: 68 65 20 6d 75 74 65 78 65 73 2e 20 20 42 75 74  he mutexes.  But
1f80: 20 66 6f 72 20 6d 61 78 69 6d 75 6d 20 73 61 66   for maximum saf
1f90: 65 74 79 2c 20 6d 75 74 65 78 65 73 20 73 68 6f  ety, mutexes sho
1fa0: 75 6c 64 20 62 65 20 65 6e 61 62 6c 65 64 2e 0a  uld be enabled..
1fb0: 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20  ** ^The default 
1fc0: 62 65 68 61 76 69 6f 72 20 69 73 20 66 6f 72 20  behavior is for 
1fd0: 6d 75 74 65 78 65 73 20 74 6f 20 62 65 20 65 6e  mutexes to be en
1fe0: 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69  abled..**.** Thi
1ff0: 73 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e 20  s interface can 
2000: 62 65 20 75 73 65 64 20 62 79 20 61 6e 20 61 70  be used by an ap
2010: 70 6c 69 63 61 74 69 6f 6e 20 74 6f 20 6d 61 6b  plication to mak
2020: 65 20 73 75 72 65 20 74 68 61 74 20 74 68 65 0a  e sure that the.
2030: 2a 2a 20 76 65 72 73 69 6f 6e 20 6f 66 20 53 51  ** version of SQ
2040: 4c 69 74 65 20 74 68 61 74 20 69 74 20 69 73 20  Lite that it is 
2050: 6c 69 6e 6b 69 6e 67 20 61 67 61 69 6e 73 74 20  linking against 
2060: 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74  was compiled wit
2070: 68 0a 2a 2a 20 74 68 65 20 64 65 73 69 72 65 64  h.** the desired
2080: 20 73 65 74 74 69 6e 67 20 6f 66 20 74 68 65 20   setting of the 
2090: 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41  [SQLITE_THREADSA
20a0: 46 45 5d 20 6d 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a  FE] macro..**.**
20b0: 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20   This interface 
20c0: 6f 6e 6c 79 20 72 65 70 6f 72 74 73 20 6f 6e 20  only reports on 
20d0: 74 68 65 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  the compile-time
20e0: 20 6d 75 74 65 78 20 73 65 74 74 69 6e 67 0a 2a   mutex setting.*
20f0: 2a 20 6f 66 20 74 68 65 20 5b 53 51 4c 49 54 45  * of the [SQLITE
2100: 5f 54 48 52 45 41 44 53 41 46 45 5d 20 66 6c 61  _THREADSAFE] fla
2110: 67 2e 20 20 49 66 20 53 51 4c 69 74 65 20 69 73  g.  If SQLite is
2120: 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a   compiled with.*
2130: 2a 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53  * SQLITE_THREADS
2140: 41 46 45 3d 31 20 6f 72 20 3d 32 20 74 68 65 6e  AFE=1 or =2 then
2150: 20 6d 75 74 65 78 65 73 20 61 72 65 20 65 6e 61   mutexes are ena
2160: 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 20  bled by default 
2170: 62 75 74 0a 2a 2a 20 63 61 6e 20 62 65 20 66 75  but.** can be fu
2180: 6c 6c 79 20 6f 72 20 70 61 72 74 69 61 6c 6c 79  lly or partially
2190: 20 64 69 73 61 62 6c 65 64 20 75 73 69 6e 67 20   disabled using 
21a0: 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  a call to [sqlit
21b0: 65 33 5f 63 6f 6e 66 69 67 28 29 5d 0a 2a 2a 20  e3_config()].** 
21c0: 77 69 74 68 20 74 68 65 20 76 65 72 62 73 20 5b  with the verbs [
21d0: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49  SQLITE_CONFIG_SI
21e0: 4e 47 4c 45 54 48 52 45 41 44 5d 2c 20 5b 53 51  NGLETHREAD], [SQ
21f0: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54  LITE_CONFIG_MULT
2200: 49 54 48 52 45 41 44 5d 2c 0a 2a 2a 20 6f 72 20  ITHREAD],.** or 
2210: 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53  [SQLITE_CONFIG_S
2220: 45 52 49 41 4c 49 5a 45 44 5d 2e 20 20 5e 28 54  ERIALIZED].  ^(T
2230: 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20  he return value 
2240: 6f 66 20 74 68 65 0a 2a 2a 20 73 71 6c 69 74 65  of the.** sqlite
2250: 33 5f 74 68 72 65 61 64 73 61 66 65 28 29 20 66  3_threadsafe() f
2260: 75 6e 63 74 69 6f 6e 20 73 68 6f 77 73 20 6f 6e  unction shows on
2270: 6c 79 20 74 68 65 20 63 6f 6d 70 69 6c 65 2d 74  ly the compile-t
2280: 69 6d 65 20 73 65 74 74 69 6e 67 20 6f 66 0a 2a  ime setting of.*
2290: 2a 20 74 68 72 65 61 64 20 73 61 66 65 74 79 2c  * thread safety,
22a0: 20 6e 6f 74 20 61 6e 79 20 72 75 6e 2d 74 69 6d   not any run-tim
22b0: 65 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68 61  e changes to tha
22c0: 74 20 73 65 74 74 69 6e 67 20 6d 61 64 65 20 62  t setting made b
22d0: 79 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6e  y.** sqlite3_con
22e0: 66 69 67 28 29 2e 20 49 6e 20 6f 74 68 65 72 20  fig(). In other 
22f0: 77 6f 72 64 73 2c 20 74 68 65 20 72 65 74 75 72  words, the retur
2300: 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c  n value from sql
2310: 69 74 65 33 5f 74 68 72 65 61 64 73 61 66 65 28  ite3_threadsafe(
2320: 29 0a 2a 2a 20 69 73 20 75 6e 63 68 61 6e 67 65  ).** is unchange
2330: 64 20 62 79 20 63 61 6c 6c 73 20 74 6f 20 73 71  d by calls to sq
2340: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 2e 29  lite3_config().)
2350: 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 74 68 65 20  ^.**.** See the 
2360: 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d  [threading mode]
2370: 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66   documentation f
2380: 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e  or additional in
2390: 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a 69 6e  formation..*/.in
23a0: 74 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64  t sqlite3_thread
23b0: 73 61 66 65 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a  safe(void);../*.
23c0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 61 74  ** CAPI3REF: Dat
23d0: 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e  abase Connection
23e0: 20 48 61 6e 64 6c 65 0a 2a 2a 20 4b 45 59 57 4f   Handle.** KEYWO
23f0: 52 44 53 3a 20 7b 64 61 74 61 62 61 73 65 20 63  RDS: {database c
2400: 6f 6e 6e 65 63 74 69 6f 6e 7d 20 7b 64 61 74 61  onnection} {data
2410: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  base connections
2420: 7d 0a 2a 2a 0a 2a 2a 20 45 61 63 68 20 6f 70 65  }.**.** Each ope
2430: 6e 20 53 51 4c 69 74 65 20 64 61 74 61 62 61 73  n SQLite databas
2440: 65 20 69 73 20 72 65 70 72 65 73 65 6e 74 65 64  e is represented
2450: 20 62 79 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   by a pointer to
2460: 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 0a   an instance of.
2470: 2a 2a 20 74 68 65 20 6f 70 61 71 75 65 20 73 74  ** the opaque st
2480: 72 75 63 74 75 72 65 20 6e 61 6d 65 64 20 22 73  ructure named "s
2490: 71 6c 69 74 65 33 22 2e 20 20 49 74 20 69 73 20  qlite3".  It is 
24a0: 75 73 65 66 75 6c 20 74 6f 20 74 68 69 6e 6b 20  useful to think 
24b0: 6f 66 20 61 6e 20 73 71 6c 69 74 65 33 0a 2a 2a  of an sqlite3.**
24c0: 20 70 6f 69 6e 74 65 72 20 61 73 20 61 6e 20 6f   pointer as an o
24d0: 62 6a 65 63 74 2e 20 20 54 68 65 20 5b 73 71 6c  bject.  The [sql
24e0: 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73  ite3_open()], [s
24f0: 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d  qlite3_open16()]
2500: 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  , and.** [sqlite
2510: 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 69 6e 74  3_open_v2()] int
2520: 65 72 66 61 63 65 73 20 61 72 65 20 69 74 73 20  erfaces are its 
2530: 63 6f 6e 73 74 72 75 63 74 6f 72 73 2c 20 61 6e  constructors, an
2540: 64 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  d [sqlite3_close
2550: 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69  ()].** and [sqli
2560: 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 5d 20  te3_close_v2()] 
2570: 61 72 65 20 69 74 73 20 64 65 73 74 72 75 63 74  are its destruct
2580: 6f 72 73 2e 20 20 54 68 65 72 65 20 61 72 65 20  ors.  There are 
2590: 6d 61 6e 79 20 6f 74 68 65 72 0a 2a 2a 20 69 6e  many other.** in
25a0: 74 65 72 66 61 63 65 73 20 28 73 75 63 68 20 61  terfaces (such a
25b0: 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72  s.** [sqlite3_pr
25c0: 65 70 61 72 65 5f 76 32 28 29 5d 2c 20 5b 73 71  epare_v2()], [sq
25d0: 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
25e0: 63 74 69 6f 6e 28 29 5d 2c 20 61 6e 64 0a 2a 2a  ction()], and.**
25f0: 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74   [sqlite3_busy_t
2600: 69 6d 65 6f 75 74 28 29 5d 20 74 6f 20 6e 61 6d  imeout()] to nam
2610: 65 20 62 75 74 20 74 68 72 65 65 29 20 74 68 61  e but three) tha
2620: 74 20 61 72 65 20 6d 65 74 68 6f 64 73 20 6f 6e  t are methods on
2630: 20 61 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 20 6f   an.** sqlite3 o
2640: 62 6a 65 63 74 2e 0a 2a 2f 0a 74 79 70 65 64 65  bject..*/.typede
2650: 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  f struct sqlite3
2660: 20 73 71 6c 69 74 65 33 3b 0a 0a 2f 2a 0a 2a 2a   sqlite3;../*.**
2670: 20 43 41 50 49 33 52 45 46 3a 20 36 34 2d 42 69   CAPI3REF: 64-Bi
2680: 74 20 49 6e 74 65 67 65 72 20 54 79 70 65 73 0a  t Integer Types.
2690: 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c  ** KEYWORDS: sql
26a0: 69 74 65 5f 69 6e 74 36 34 20 73 71 6c 69 74 65  ite_int64 sqlite
26b0: 5f 75 69 6e 74 36 34 0a 2a 2a 0a 2a 2a 20 42 65  _uint64.**.** Be
26c0: 63 61 75 73 65 20 74 68 65 72 65 20 69 73 20 6e  cause there is n
26d0: 6f 20 63 72 6f 73 73 2d 70 6c 61 74 66 6f 72 6d  o cross-platform
26e0: 20 77 61 79 20 74 6f 20 73 70 65 63 69 66 79 20   way to specify 
26f0: 36 34 2d 62 69 74 20 69 6e 74 65 67 65 72 20 74  64-bit integer t
2700: 79 70 65 73 0a 2a 2a 20 53 51 4c 69 74 65 20 69  ypes.** SQLite i
2710: 6e 63 6c 75 64 65 73 20 74 79 70 65 64 65 66 73  ncludes typedefs
2720: 20 66 6f 72 20 36 34 2d 62 69 74 20 73 69 67 6e   for 64-bit sign
2730: 65 64 20 61 6e 64 20 75 6e 73 69 67 6e 65 64 20  ed and unsigned 
2740: 69 6e 74 65 67 65 72 73 2e 0a 2a 2a 0a 2a 2a 20  integers..**.** 
2750: 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  The sqlite3_int6
2760: 34 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 75 69  4 and sqlite3_ui
2770: 6e 74 36 34 20 61 72 65 20 74 68 65 20 70 72 65  nt64 are the pre
2780: 66 65 72 72 65 64 20 74 79 70 65 20 64 65 66 69  ferred type defi
2790: 6e 69 74 69 6f 6e 73 2e 0a 2a 2a 20 54 68 65 20  nitions..** The 
27a0: 73 71 6c 69 74 65 5f 69 6e 74 36 34 20 61 6e 64  sqlite_int64 and
27b0: 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 20 74   sqlite_uint64 t
27c0: 79 70 65 73 20 61 72 65 20 73 75 70 70 6f 72 74  ypes are support
27d0: 65 64 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73  ed for backwards
27e0: 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  .** compatibilit
27f0: 79 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54  y only..**.** ^T
2800: 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  he sqlite3_int64
2810: 20 61 6e 64 20 73 71 6c 69 74 65 5f 69 6e 74 36   and sqlite_int6
2820: 34 20 74 79 70 65 73 20 63 61 6e 20 73 74 6f 72  4 types can stor
2830: 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73  e integer values
2840: 0a 2a 2a 20 62 65 74 77 65 65 6e 20 2d 39 32 32  .** between -922
2850: 33 33 37 32 30 33 36 38 35 34 37 37 35 38 30 38  3372036854775808
2860: 20 61 6e 64 20 2b 39 32 32 33 33 37 32 30 33 36   and +9223372036
2870: 38 35 34 37 37 35 38 30 37 20 69 6e 63 6c 75 73  854775807 inclus
2880: 69 76 65 2e 20 20 5e 54 68 65 0a 2a 2a 20 73 71  ive.  ^The.** sq
2890: 6c 69 74 65 33 5f 75 69 6e 74 36 34 20 61 6e 64  lite3_uint64 and
28a0: 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 20 74   sqlite_uint64 t
28b0: 79 70 65 73 20 63 61 6e 20 73 74 6f 72 65 20 69  ypes can store i
28c0: 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20 0a 2a  nteger values .*
28d0: 2a 20 62 65 74 77 65 65 6e 20 30 20 61 6e 64 20  * between 0 and 
28e0: 2b 31 38 34 34 36 37 34 34 30 37 33 37 30 39 35  +184467440737095
28f0: 35 31 36 31 35 20 69 6e 63 6c 75 73 69 76 65 2e  51615 inclusive.
2900: 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51 4c 49 54  .*/.#ifdef SQLIT
2910: 45 5f 49 4e 54 36 34 5f 54 59 50 45 0a 20 20 74  E_INT64_TYPE.  t
2920: 79 70 65 64 65 66 20 53 51 4c 49 54 45 5f 49 4e  ypedef SQLITE_IN
2930: 54 36 34 5f 54 59 50 45 20 73 71 6c 69 74 65 5f  T64_TYPE sqlite_
2940: 69 6e 74 36 34 3b 0a 20 20 74 79 70 65 64 65 66  int64;.  typedef
2950: 20 75 6e 73 69 67 6e 65 64 20 53 51 4c 49 54 45   unsigned SQLITE
2960: 5f 49 4e 54 36 34 5f 54 59 50 45 20 73 71 6c 69  _INT64_TYPE sqli
2970: 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6c 69 66  te_uint64;.#elif
2980: 20 64 65 66 69 6e 65 64 28 5f 4d 53 43 5f 56 45   defined(_MSC_VE
2990: 52 29 20 7c 7c 20 64 65 66 69 6e 65 64 28 5f 5f  R) || defined(__
29a0: 42 4f 52 4c 41 4e 44 43 5f 5f 29 0a 20 20 74 79  BORLANDC__).  ty
29b0: 70 65 64 65 66 20 5f 5f 69 6e 74 36 34 20 73 71  pedef __int64 sq
29c0: 6c 69 74 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79  lite_int64;.  ty
29d0: 70 65 64 65 66 20 75 6e 73 69 67 6e 65 64 20 5f  pedef unsigned _
29e0: 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 5f 75 69  _int64 sqlite_ui
29f0: 6e 74 36 34 3b 0a 23 65 6c 73 65 0a 20 20 74 79  nt64;.#else.  ty
2a00: 70 65 64 65 66 20 6c 6f 6e 67 20 6c 6f 6e 67 20  pedef long long 
2a10: 69 6e 74 20 73 71 6c 69 74 65 5f 69 6e 74 36 34  int sqlite_int64
2a20: 3b 0a 20 20 74 79 70 65 64 65 66 20 75 6e 73 69  ;.  typedef unsi
2a30: 67 6e 65 64 20 6c 6f 6e 67 20 6c 6f 6e 67 20 69  gned long long i
2a40: 6e 74 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34  nt sqlite_uint64
2a50: 3b 0a 23 65 6e 64 69 66 0a 74 79 70 65 64 65 66  ;.#endif.typedef
2a60: 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 20 73 71   sqlite_int64 sq
2a70: 6c 69 74 65 33 5f 69 6e 74 36 34 3b 0a 74 79 70  lite3_int64;.typ
2a80: 65 64 65 66 20 73 71 6c 69 74 65 5f 75 69 6e 74  edef sqlite_uint
2a90: 36 34 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36  64 sqlite3_uint6
2aa0: 34 3b 0a 0a 2f 2a 0a 2a 2a 20 49 66 20 63 6f 6d  4;../*.** If com
2ab0: 70 69 6c 69 6e 67 20 66 6f 72 20 61 20 70 72 6f  piling for a pro
2ac0: 63 65 73 73 6f 72 20 74 68 61 74 20 6c 61 63 6b  cessor that lack
2ad0: 73 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74  s floating point
2ae0: 20 73 75 70 70 6f 72 74 2c 0a 2a 2a 20 73 75 62   support,.** sub
2af0: 73 74 69 74 75 74 65 20 69 6e 74 65 67 65 72 20  stitute integer 
2b00: 66 6f 72 20 66 6c 6f 61 74 69 6e 67 2d 70 6f 69  for floating-poi
2b10: 6e 74 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51  nt..*/.#ifdef SQ
2b20: 4c 49 54 45 5f 4f 4d 49 54 5f 46 4c 4f 41 54 49  LITE_OMIT_FLOATI
2b30: 4e 47 5f 50 4f 49 4e 54 0a 23 20 64 65 66 69 6e  NG_POINT.# defin
2b40: 65 20 64 6f 75 62 6c 65 20 73 71 6c 69 74 65 33  e double sqlite3
2b50: 5f 69 6e 74 36 34 0a 23 65 6e 64 69 66 0a 0a 2f  _int64.#endif../
2b60: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
2b70: 6c 6f 73 69 6e 67 20 41 20 44 61 74 61 62 61 73  losing A Databas
2b80: 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20  e Connection.** 
2b90: 44 45 53 54 52 55 43 54 4f 52 3a 20 73 71 6c 69  DESTRUCTOR: sqli
2ba0: 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  te3.**.** ^The s
2bb0: 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 20 61  qlite3_close() a
2bc0: 6e 64 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  nd sqlite3_close
2bd0: 5f 76 32 28 29 20 72 6f 75 74 69 6e 65 73 20 61  _v2() routines a
2be0: 72 65 20 64 65 73 74 72 75 63 74 6f 72 73 0a 2a  re destructors.*
2bf0: 2a 20 66 6f 72 20 74 68 65 20 5b 73 71 6c 69 74  * for the [sqlit
2c00: 65 33 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 5e  e3] object..** ^
2c10: 43 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33  Calls to sqlite3
2c20: 5f 63 6c 6f 73 65 28 29 20 61 6e 64 20 73 71 6c  _close() and sql
2c30: 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20  ite3_close_v2() 
2c40: 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f  return [SQLITE_O
2c50: 4b 5d 20 69 66 0a 2a 2a 20 74 68 65 20 5b 73 71  K] if.** the [sq
2c60: 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 20 69 73  lite3] object is
2c70: 20 73 75 63 63 65 73 73 66 75 6c 6c 79 20 64 65   successfully de
2c80: 73 74 72 6f 79 65 64 20 61 6e 64 20 61 6c 6c 20  stroyed and all 
2c90: 61 73 73 6f 63 69 61 74 65 64 0a 2a 2a 20 72 65  associated.** re
2ca0: 73 6f 75 72 63 65 73 20 61 72 65 20 64 65 61 6c  sources are deal
2cb0: 6c 6f 63 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  located..**.** ^
2cc0: 49 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  If the database 
2cd0: 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 61 73  connection is as
2ce0: 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 75 6e  sociated with un
2cf0: 66 69 6e 61 6c 69 7a 65 64 20 70 72 65 70 61 72  finalized prepar
2d00: 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 73  ed.** statements
2d10: 20 6f 72 20 75 6e 66 69 6e 69 73 68 65 64 20 73   or unfinished s
2d20: 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 20 6f 62  qlite3_backup ob
2d30: 6a 65 63 74 73 20 74 68 65 6e 20 73 71 6c 69 74  jects then sqlit
2d40: 65 33 5f 63 6c 6f 73 65 28 29 0a 2a 2a 20 77 69  e3_close().** wi
2d50: 6c 6c 20 6c 65 61 76 65 20 74 68 65 20 64 61 74  ll leave the dat
2d60: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
2d70: 20 6f 70 65 6e 20 61 6e 64 20 72 65 74 75 72 6e   open and return
2d80: 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2e 0a   [SQLITE_BUSY]..
2d90: 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 63  ** ^If sqlite3_c
2da0: 6c 6f 73 65 5f 76 32 28 29 20 69 73 20 63 61 6c  lose_v2() is cal
2db0: 6c 65 64 20 77 69 74 68 20 75 6e 66 69 6e 61 6c  led with unfinal
2dc0: 69 7a 65 64 20 70 72 65 70 61 72 65 64 20 73 74  ized prepared st
2dd0: 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 61 6e 64 2f  atements.** and/
2de0: 6f 72 20 75 6e 66 69 6e 69 73 68 65 64 20 73 71  or unfinished sq
2df0: 6c 69 74 65 33 5f 62 61 63 6b 75 70 73 2c 20 74  lite3_backups, t
2e00: 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65  hen the database
2e10: 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 65 63 6f   connection beco
2e20: 6d 65 73 0a 2a 2a 20 61 6e 20 75 6e 75 73 61 62  mes.** an unusab
2e30: 6c 65 20 22 7a 6f 6d 62 69 65 22 20 77 68 69 63  le "zombie" whic
2e40: 68 20 77 69 6c 6c 20 61 75 74 6f 6d 61 74 69 63  h will automatic
2e50: 61 6c 6c 79 20 62 65 20 64 65 61 6c 6c 6f 63 61  ally be dealloca
2e60: 74 65 64 20 77 68 65 6e 20 74 68 65 0a 2a 2a 20  ted when the.** 
2e70: 6c 61 73 74 20 70 72 65 70 61 72 65 64 20 73 74  last prepared st
2e80: 61 74 65 6d 65 6e 74 20 69 73 20 66 69 6e 61 6c  atement is final
2e90: 69 7a 65 64 20 6f 72 20 74 68 65 20 6c 61 73 74  ized or the last
2ea0: 20 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 20   sqlite3_backup 
2eb0: 69 73 0a 2a 2a 20 66 69 6e 69 73 68 65 64 2e 20  is.** finished. 
2ec0: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6c 6f   The sqlite3_clo
2ed0: 73 65 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63  se_v2() interfac
2ee0: 65 20 69 73 20 69 6e 74 65 6e 64 65 64 20 66 6f  e is intended fo
2ef0: 72 20 75 73 65 20 77 69 74 68 0a 2a 2a 20 68 6f  r use with.** ho
2f00: 73 74 20 6c 61 6e 67 75 61 67 65 73 20 74 68 61  st languages tha
2f10: 74 20 61 72 65 20 67 61 72 62 61 67 65 20 63 6f  t are garbage co
2f20: 6c 6c 65 63 74 65 64 2c 20 61 6e 64 20 77 68 65  llected, and whe
2f30: 72 65 20 74 68 65 20 6f 72 64 65 72 20 69 6e 20  re the order in 
2f40: 77 68 69 63 68 0a 2a 2a 20 64 65 73 74 72 75 63  which.** destruc
2f50: 74 6f 72 73 20 61 72 65 20 63 61 6c 6c 65 64 20  tors are called 
2f60: 69 73 20 61 72 62 69 74 72 61 72 79 2e 0a 2a 2a  is arbitrary..**
2f70: 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73  .** Applications
2f80: 20 73 68 6f 75 6c 64 20 5b 73 71 6c 69 74 65 33   should [sqlite3
2f90: 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 66 69 6e 61  _finalize | fina
2fa0: 6c 69 7a 65 5d 20 61 6c 6c 20 5b 70 72 65 70 61  lize] all [prepa
2fb0: 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 2c  red statements],
2fc0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f  .** [sqlite3_blo
2fd0: 62 5f 63 6c 6f 73 65 20 7c 20 63 6c 6f 73 65 5d  b_close | close]
2fe0: 20 61 6c 6c 20 5b 42 4c 4f 42 20 68 61 6e 64 6c   all [BLOB handl
2ff0: 65 73 5d 2c 20 61 6e 64 20 0a 2a 2a 20 5b 73 71  es], and .** [sq
3000: 6c 69 74 65 33 5f 62 61 63 6b 75 70 5f 66 69 6e  lite3_backup_fin
3010: 69 73 68 20 7c 20 66 69 6e 69 73 68 5d 20 61 6c  ish | finish] al
3020: 6c 20 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b 75  l [sqlite3_backu
3030: 70 5d 20 6f 62 6a 65 63 74 73 20 61 73 73 6f 63  p] objects assoc
3040: 69 61 74 65 64 0a 2a 2a 20 77 69 74 68 20 74 68  iated.** with th
3050: 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65  e [sqlite3] obje
3060: 63 74 20 70 72 69 6f 72 20 74 6f 20 61 74 74 65  ct prior to atte
3070: 6d 70 74 69 6e 67 20 74 6f 20 63 6c 6f 73 65 20  mpting to close 
3080: 74 68 65 20 6f 62 6a 65 63 74 2e 20 20 5e 49 66  the object.  ^If
3090: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73  .** sqlite3_clos
30a0: 65 5f 76 32 28 29 20 69 73 20 63 61 6c 6c 65 64  e_v2() is called
30b0: 20 6f 6e 20 61 20 5b 64 61 74 61 62 61 73 65 20   on a [database 
30c0: 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 68 61 74  connection] that
30d0: 20 73 74 69 6c 6c 20 68 61 73 0a 2a 2a 20 6f 75   still has.** ou
30e0: 74 73 74 61 6e 64 69 6e 67 20 5b 70 72 65 70 61  tstanding [prepa
30f0: 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 2c  red statements],
3100: 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 73 5d 2c   [BLOB handles],
3110: 20 61 6e 64 2f 6f 72 0a 2a 2a 20 5b 73 71 6c 69   and/or.** [sqli
3120: 74 65 33 5f 62 61 63 6b 75 70 5d 20 6f 62 6a 65  te3_backup] obje
3130: 63 74 73 20 74 68 65 6e 20 69 74 20 72 65 74 75  cts then it retu
3140: 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20  rns [SQLITE_OK] 
3150: 61 6e 64 20 74 68 65 20 64 65 61 6c 6c 6f 63 61  and the dealloca
3160: 74 69 6f 6e 0a 2a 2a 20 6f 66 20 72 65 73 6f 75  tion.** of resou
3170: 72 63 65 73 20 69 73 20 64 65 66 65 72 72 65 64  rces is deferred
3180: 20 75 6e 74 69 6c 20 61 6c 6c 20 5b 70 72 65 70   until all [prep
3190: 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d  ared statements]
31a0: 2c 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 73 5d  , [BLOB handles]
31b0: 2c 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65  ,.** and [sqlite
31c0: 33 5f 62 61 63 6b 75 70 5d 20 6f 62 6a 65 63 74  3_backup] object
31d0: 73 20 61 72 65 20 61 6c 73 6f 20 64 65 73 74 72  s are also destr
31e0: 6f 79 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  oyed..**.** ^If 
31f0: 61 6e 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a  an [sqlite3] obj
3200: 65 63 74 20 69 73 20 64 65 73 74 72 6f 79 65 64  ect is destroyed
3210: 20 77 68 69 6c 65 20 61 20 74 72 61 6e 73 61 63   while a transac
3220: 74 69 6f 6e 20 69 73 20 6f 70 65 6e 2c 0a 2a 2a  tion is open,.**
3230: 20 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e   the transaction
3240: 20 69 73 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c   is automaticall
3250: 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a  y rolled back..*
3260: 2a 0a 2a 2a 20 54 68 65 20 43 20 70 61 72 61 6d  *.** The C param
3270: 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33  eter to [sqlite3
3280: 5f 63 6c 6f 73 65 28 43 29 5d 20 61 6e 64 20 5b  _close(C)] and [
3290: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32  sqlite3_close_v2
32a0: 28 43 29 5d 0a 2a 2a 20 6d 75 73 74 20 62 65 20  (C)].** must be 
32b0: 65 69 74 68 65 72 20 61 20 4e 55 4c 4c 0a 2a 2a  either a NULL.**
32c0: 20 70 6f 69 6e 74 65 72 20 6f 72 20 61 6e 20 5b   pointer or an [
32d0: 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 20  sqlite3] object 
32e0: 70 6f 69 6e 74 65 72 20 6f 62 74 61 69 6e 65 64  pointer obtained
32f0: 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  .** from [sqlite
3300: 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69  3_open()], [sqli
3310: 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 20 6f  te3_open16()], o
3320: 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70  r.** [sqlite3_op
3330: 65 6e 5f 76 32 28 29 5d 2c 20 61 6e 64 20 6e 6f  en_v2()], and no
3340: 74 20 70 72 65 76 69 6f 75 73 6c 79 20 63 6c 6f  t previously clo
3350: 73 65 64 2e 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67  sed..** ^Calling
3360: 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29   sqlite3_close()
3370: 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73   or sqlite3_clos
3380: 65 5f 76 32 28 29 20 77 69 74 68 20 61 20 4e 55  e_v2() with a NU
3390: 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 61 72  LL pointer.** ar
33a0: 67 75 6d 65 6e 74 20 69 73 20 61 20 68 61 72 6d  gument is a harm
33b0: 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2f 0a 69  less no-op..*/.i
33c0: 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  nt sqlite3_close
33d0: 28 73 71 6c 69 74 65 33 2a 29 3b 0a 69 6e 74 20  (sqlite3*);.int 
33e0: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32  sqlite3_close_v2
33f0: 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a  (sqlite3*);../*.
3400: 2a 2a 20 54 68 65 20 74 79 70 65 20 66 6f 72 20  ** The type for 
3410: 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  a callback funct
3420: 69 6f 6e 2e 0a 2a 2a 20 54 68 69 73 20 69 73 20  ion..** This is 
3430: 6c 65 67 61 63 79 20 61 6e 64 20 64 65 70 72 65  legacy and depre
3440: 63 61 74 65 64 2e 20 20 49 74 20 69 73 20 69 6e  cated.  It is in
3450: 63 6c 75 64 65 64 20 66 6f 72 20 68 69 73 74 6f  cluded for histo
3460: 72 69 63 61 6c 0a 2a 2a 20 63 6f 6d 70 61 74 69  rical.** compati
3470: 62 69 6c 69 74 79 20 61 6e 64 20 69 73 20 6e 6f  bility and is no
3480: 74 20 64 6f 63 75 6d 65 6e 74 65 64 2e 0a 2a 2f  t documented..*/
3490: 0a 74 79 70 65 64 65 66 20 69 6e 74 20 28 2a 73  .typedef int (*s
34a0: 71 6c 69 74 65 33 5f 63 61 6c 6c 62 61 63 6b 29  qlite3_callback)
34b0: 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68 61 72 2a  (void*,int,char*
34c0: 2a 2c 20 63 68 61 72 2a 2a 29 3b 0a 0a 2f 2a 0a  *, char**);../*.
34d0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 6e 65  ** CAPI3REF: One
34e0: 2d 53 74 65 70 20 51 75 65 72 79 20 45 78 65 63  -Step Query Exec
34f0: 75 74 69 6f 6e 20 49 6e 74 65 72 66 61 63 65 0a  ution Interface.
3500: 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
3510: 65 33 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  e3.**.** The sql
3520: 69 74 65 33 5f 65 78 65 63 28 29 20 69 6e 74 65  ite3_exec() inte
3530: 72 66 61 63 65 20 69 73 20 61 20 63 6f 6e 76 65  rface is a conve
3540: 6e 69 65 6e 63 65 20 77 72 61 70 70 65 72 20 61  nience wrapper a
3550: 72 6f 75 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  round.** [sqlite
3560: 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c  3_prepare_v2()],
3570: 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
3580: 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  ], and [sqlite3_
3590: 66 69 6e 61 6c 69 7a 65 28 29 5d 2c 0a 2a 2a 20  finalize()],.** 
35a0: 74 68 61 74 20 61 6c 6c 6f 77 73 20 61 6e 20 61  that allows an a
35b0: 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f 20 72 75  pplication to ru
35c0: 6e 20 6d 75 6c 74 69 70 6c 65 20 73 74 61 74 65  n multiple state
35d0: 6d 65 6e 74 73 20 6f 66 20 53 51 4c 0a 2a 2a 20  ments of SQL.** 
35e0: 77 69 74 68 6f 75 74 20 68 61 76 69 6e 67 20 74  without having t
35f0: 6f 20 75 73 65 20 61 20 6c 6f 74 20 6f 66 20 43  o use a lot of C
3600: 20 63 6f 64 65 2e 20 0a 2a 2a 0a 2a 2a 20 5e 54   code. .**.** ^T
3610: 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  he sqlite3_exec(
3620: 29 20 69 6e 74 65 72 66 61 63 65 20 72 75 6e 73  ) interface runs
3630: 20 7a 65 72 6f 20 6f 72 20 6d 6f 72 65 20 55 54   zero or more UT
3640: 46 2d 38 20 65 6e 63 6f 64 65 64 2c 0a 2a 2a 20  F-8 encoded,.** 
3650: 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61 72 61  semicolon-separa
3660: 74 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  te SQL statement
3670: 73 20 70 61 73 73 65 64 20 69 6e 74 6f 20 69 74  s passed into it
3680: 73 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 2c 0a  s 2nd argument,.
3690: 2a 2a 20 69 6e 20 74 68 65 20 63 6f 6e 74 65 78  ** in the contex
36a0: 74 20 6f 66 20 74 68 65 20 5b 64 61 74 61 62 61  t of the [databa
36b0: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 70  se connection] p
36c0: 61 73 73 65 64 20 69 6e 20 61 73 20 69 74 73 20  assed in as its 
36d0: 31 73 74 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 2e  1st.** argument.
36e0: 20 20 5e 49 66 20 74 68 65 20 63 61 6c 6c 62 61    ^If the callba
36f0: 63 6b 20 66 75 6e 63 74 69 6f 6e 20 6f 66 20 74  ck function of t
3700: 68 65 20 33 72 64 20 61 72 67 75 6d 65 6e 74 20  he 3rd argument 
3710: 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78  to.** sqlite3_ex
3720: 65 63 28 29 20 69 73 20 6e 6f 74 20 4e 55 4c 4c  ec() is not NULL
3730: 2c 20 74 68 65 6e 20 69 74 20 69 73 20 69 6e 76  , then it is inv
3740: 6f 6b 65 64 20 66 6f 72 20 65 61 63 68 20 72 65  oked for each re
3750: 73 75 6c 74 20 72 6f 77 0a 2a 2a 20 63 6f 6d 69  sult row.** comi
3760: 6e 67 20 6f 75 74 20 6f 66 20 74 68 65 20 65 76  ng out of the ev
3770: 61 6c 75 61 74 65 64 20 53 51 4c 20 73 74 61 74  aluated SQL stat
3780: 65 6d 65 6e 74 73 2e 20 20 5e 54 68 65 20 34 74  ements.  ^The 4t
3790: 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a  h argument to.**
37a0: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20   sqlite3_exec() 
37b0: 69 73 20 72 65 6c 61 79 65 64 20 74 68 72 6f 75  is relayed throu
37c0: 67 68 20 74 6f 20 74 68 65 20 31 73 74 20 61 72  gh to the 1st ar
37d0: 67 75 6d 65 6e 74 20 6f 66 20 65 61 63 68 0a 2a  gument of each.*
37e0: 2a 20 63 61 6c 6c 62 61 63 6b 20 69 6e 76 6f 63  * callback invoc
37f0: 61 74 69 6f 6e 2e 20 20 5e 49 66 20 74 68 65 20  ation.  ^If the 
3800: 63 61 6c 6c 62 61 63 6b 20 70 6f 69 6e 74 65 72  callback pointer
3810: 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63   to sqlite3_exec
3820: 28 29 0a 2a 2a 20 69 73 20 4e 55 4c 4c 2c 20 74  ().** is NULL, t
3830: 68 65 6e 20 6e 6f 20 63 61 6c 6c 62 61 63 6b 20  hen no callback 
3840: 69 73 20 65 76 65 72 20 69 6e 76 6f 6b 65 64 20  is ever invoked 
3850: 61 6e 64 20 72 65 73 75 6c 74 20 72 6f 77 73 20  and result rows 
3860: 61 72 65 0a 2a 2a 20 69 67 6e 6f 72 65 64 2e 0a  are.** ignored..
3870: 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20 65 72 72  **.** ^If an err
3880: 6f 72 20 6f 63 63 75 72 73 20 77 68 69 6c 65 20  or occurs while 
3890: 65 76 61 6c 75 61 74 69 6e 67 20 74 68 65 20 53  evaluating the S
38a0: 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 70 61  QL statements pa
38b0: 73 73 65 64 20 69 6e 74 6f 0a 2a 2a 20 73 71 6c  ssed into.** sql
38c0: 69 74 65 33 5f 65 78 65 63 28 29 2c 20 74 68 65  ite3_exec(), the
38d0: 6e 20 65 78 65 63 75 74 69 6f 6e 20 6f 66 20 74  n execution of t
38e0: 68 65 20 63 75 72 72 65 6e 74 20 73 74 61 74 65  he current state
38f0: 6d 65 6e 74 20 73 74 6f 70 73 20 61 6e 64 0a 2a  ment stops and.*
3900: 2a 20 73 75 62 73 65 71 75 65 6e 74 20 73 74 61  * subsequent sta
3910: 74 65 6d 65 6e 74 73 20 61 72 65 20 73 6b 69 70  tements are skip
3920: 70 65 64 2e 20 20 5e 49 66 20 74 68 65 20 35 74  ped.  ^If the 5t
3930: 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  h parameter to s
3940: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a  qlite3_exec().**
3950: 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 74 68 65   is not NULL the
3960: 6e 20 61 6e 79 20 65 72 72 6f 72 20 6d 65 73 73  n any error mess
3970: 61 67 65 20 69 73 20 77 72 69 74 74 65 6e 20 69  age is written i
3980: 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69  nto memory obtai
3990: 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c  ned.** from [sql
39a0: 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 61  ite3_malloc()] a
39b0: 6e 64 20 70 61 73 73 65 64 20 62 61 63 6b 20 74  nd passed back t
39c0: 68 72 6f 75 67 68 20 74 68 65 20 35 74 68 20 70  hrough the 5th p
39d0: 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 54 6f 20  arameter..** To 
39e0: 61 76 6f 69 64 20 6d 65 6d 6f 72 79 20 6c 65 61  avoid memory lea
39f0: 6b 73 2c 20 74 68 65 20 61 70 70 6c 69 63 61 74  ks, the applicat
3a00: 69 6f 6e 20 73 68 6f 75 6c 64 20 69 6e 76 6f 6b  ion should invok
3a10: 65 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  e [sqlite3_free(
3a20: 29 5d 0a 2a 2a 20 6f 6e 20 65 72 72 6f 72 20 6d  )].** on error m
3a30: 65 73 73 61 67 65 20 73 74 72 69 6e 67 73 20 72  essage strings r
3a40: 65 74 75 72 6e 65 64 20 74 68 72 6f 75 67 68 20  eturned through 
3a50: 74 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65  the 5th paramete
3a60: 72 20 6f 66 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  r of.** sqlite3_
3a70: 65 78 65 63 28 29 20 61 66 74 65 72 20 74 68 65  exec() after the
3a80: 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73   error message s
3a90: 74 72 69 6e 67 20 69 73 20 6e 6f 20 6c 6f 6e 67  tring is no long
3aa0: 65 72 20 6e 65 65 64 65 64 2e 0a 2a 2a 20 5e 49  er needed..** ^I
3ab0: 66 20 74 68 65 20 35 74 68 20 70 61 72 61 6d 65  f the 5th parame
3ac0: 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65  ter to sqlite3_e
3ad0: 78 65 63 28 29 20 69 73 20 6e 6f 74 20 4e 55 4c  xec() is not NUL
3ae0: 4c 20 61 6e 64 20 6e 6f 20 65 72 72 6f 72 73 0a  L and no errors.
3af0: 2a 2a 20 6f 63 63 75 72 2c 20 74 68 65 6e 20 73  ** occur, then s
3b00: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 73 65  qlite3_exec() se
3b10: 74 73 20 74 68 65 20 70 6f 69 6e 74 65 72 20 69  ts the pointer i
3b20: 6e 20 69 74 73 20 35 74 68 20 70 61 72 61 6d 65  n its 5th parame
3b30: 74 65 72 20 74 6f 0a 2a 2a 20 4e 55 4c 4c 20 62  ter to.** NULL b
3b40: 65 66 6f 72 65 20 72 65 74 75 72 6e 69 6e 67 2e  efore returning.
3b50: 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20 73 71  .**.** ^If an sq
3b60: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 63 61 6c  lite3_exec() cal
3b70: 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f  lback returns no
3b80: 6e 2d 7a 65 72 6f 2c 20 74 68 65 20 73 71 6c 69  n-zero, the sqli
3b90: 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20 72 6f  te3_exec().** ro
3ba0: 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 53 51  utine returns SQ
3bb0: 4c 49 54 45 5f 41 42 4f 52 54 20 77 69 74 68 6f  LITE_ABORT witho
3bc0: 75 74 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20  ut invoking the 
3bd0: 63 61 6c 6c 62 61 63 6b 20 61 67 61 69 6e 20 61  callback again a
3be0: 6e 64 0a 2a 2a 20 77 69 74 68 6f 75 74 20 72 75  nd.** without ru
3bf0: 6e 6e 69 6e 67 20 61 6e 79 20 73 75 62 73 65 71  nning any subseq
3c00: 75 65 6e 74 20 53 51 4c 20 73 74 61 74 65 6d 65  uent SQL stateme
3c10: 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  nts..**.** ^The 
3c20: 32 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  2nd argument to 
3c30: 74 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63  the sqlite3_exec
3c40: 28 29 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63  () callback func
3c50: 74 69 6f 6e 20 69 73 20 74 68 65 0a 2a 2a 20 6e  tion is the.** n
3c60: 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73  umber of columns
3c70: 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74 2e 20   in the result. 
3c80: 20 5e 54 68 65 20 33 72 64 20 61 72 67 75 6d 65   ^The 3rd argume
3c90: 6e 74 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65  nt to the sqlite
3ca0: 33 5f 65 78 65 63 28 29 0a 2a 2a 20 63 61 6c 6c  3_exec().** call
3cb0: 62 61 63 6b 20 69 73 20 61 6e 20 61 72 72 61 79  back is an array
3cc0: 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 20   of pointers to 
3cd0: 73 74 72 69 6e 67 73 20 6f 62 74 61 69 6e 65 64  strings obtained
3ce0: 20 61 73 20 69 66 20 66 72 6f 6d 0a 2a 2a 20 5b   as if from.** [
3cf0: 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
3d00: 65 78 74 28 29 5d 2c 20 6f 6e 65 20 66 6f 72 20  ext()], one for 
3d10: 65 61 63 68 20 63 6f 6c 75 6d 6e 2e 20 20 5e 49  each column.  ^I
3d20: 66 20 61 6e 20 65 6c 65 6d 65 6e 74 20 6f 66 20  f an element of 
3d30: 61 0a 2a 2a 20 72 65 73 75 6c 74 20 72 6f 77 20  a.** result row 
3d40: 69 73 20 4e 55 4c 4c 20 74 68 65 6e 20 74 68 65  is NULL then the
3d50: 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 73   corresponding s
3d60: 74 72 69 6e 67 20 70 6f 69 6e 74 65 72 20 66 6f  tring pointer fo
3d70: 72 20 74 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33  r the.** sqlite3
3d80: 5f 65 78 65 63 28 29 20 63 61 6c 6c 62 61 63 6b  _exec() callback
3d90: 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
3da0: 65 72 2e 20 20 5e 54 68 65 20 34 74 68 20 61 72  er.  ^The 4th ar
3db0: 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 0a 2a 2a  gument to the.**
3dc0: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20   sqlite3_exec() 
3dd0: 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 61  callback is an a
3de0: 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73  rray of pointers
3df0: 20 74 6f 20 73 74 72 69 6e 67 73 20 77 68 65 72   to strings wher
3e00: 65 20 65 61 63 68 0a 2a 2a 20 65 6e 74 72 79 20  e each.** entry 
3e10: 72 65 70 72 65 73 65 6e 74 73 20 74 68 65 20 6e  represents the n
3e20: 61 6d 65 20 6f 66 20 63 6f 72 72 65 73 70 6f 6e  ame of correspon
3e30: 64 69 6e 67 20 72 65 73 75 6c 74 20 63 6f 6c 75  ding result colu
3e40: 6d 6e 20 61 73 20 6f 62 74 61 69 6e 65 64 0a 2a  mn as obtained.*
3e50: 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  * from [sqlite3_
3e60: 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 5d 2e 0a  column_name()]..
3e70: 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 32 6e  **.** ^If the 2n
3e80: 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  d parameter to s
3e90: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 73  qlite3_exec() is
3ea0: 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c   a NULL pointer,
3eb0: 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f   a pointer.** to
3ec0: 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67   an empty string
3ed0: 2c 20 6f 72 20 61 20 70 6f 69 6e 74 65 72 20 74  , or a pointer t
3ee0: 68 61 74 20 63 6f 6e 74 61 69 6e 73 20 6f 6e 6c  hat contains onl
3ef0: 79 20 77 68 69 74 65 73 70 61 63 65 20 61 6e 64  y whitespace and
3f00: 2f 6f 72 20 0a 2a 2a 20 53 51 4c 20 63 6f 6d 6d  /or .** SQL comm
3f10: 65 6e 74 73 2c 20 74 68 65 6e 20 6e 6f 20 53 51  ents, then no SQ
3f20: 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65  L statements are
3f30: 20 65 76 61 6c 75 61 74 65 64 20 61 6e 64 20 74   evaluated and t
3f40: 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 69  he database.** i
3f50: 73 20 6e 6f 74 20 63 68 61 6e 67 65 64 2e 0a 2a  s not changed..*
3f60: 2a 0a 2a 2a 20 52 65 73 74 72 69 63 74 69 6f 6e  *.** Restriction
3f70: 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  s:.**.** <ul>.**
3f80: 20 3c 6c 69 3e 20 54 68 65 20 61 70 70 6c 69 63   <li> The applic
3f90: 61 74 69 6f 6e 20 6d 75 73 74 20 65 6e 73 75 72  ation must ensur
3fa0: 65 20 74 68 61 74 20 74 68 65 20 31 73 74 20 70  e that the 1st p
3fb0: 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
3fc0: 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20 20 20  te3_exec().**   
3fd0: 20 20 20 69 73 20 61 20 76 61 6c 69 64 20 61 6e     is a valid an
3fe0: 64 20 6f 70 65 6e 20 5b 64 61 74 61 62 61 73 65  d open [database
3ff0: 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a   connection]..**
4000: 20 3c 6c 69 3e 20 54 68 65 20 61 70 70 6c 69 63   <li> The applic
4010: 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 63  ation must not c
4020: 6c 6f 73 65 20 74 68 65 20 5b 64 61 74 61 62 61  lose the [databa
4030: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73  se connection] s
4040: 70 65 63 69 66 69 65 64 20 62 79 0a 2a 2a 20 20  pecified by.**  
4050: 20 20 20 20 74 68 65 20 31 73 74 20 70 61 72 61      the 1st para
4060: 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
4070: 5f 65 78 65 63 28 29 20 77 68 69 6c 65 20 73 71  _exec() while sq
4080: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20  lite3_exec() is 
4090: 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 3c 6c 69 3e  running..** <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 6e 6f 74 20 6d 6f 64 69 66 79   must not modify
40c0: 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
40d0: 6e 74 20 74 65 78 74 20 70 61 73 73 65 64 20 69  nt text passed i
40e0: 6e 74 6f 0a 2a 2a 20 20 20 20 20 20 74 68 65 20  nto.**      the 
40f0: 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6f 66  2nd parameter of
4100: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20   sqlite3_exec() 
4110: 77 68 69 6c 65 20 73 71 6c 69 74 65 33 5f 65 78  while sqlite3_ex
4120: 65 63 28 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e  ec() is running.
4130: 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2f 0a 69 6e 74  .** </ul>.*/.int
4140: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 0a 20   sqlite3_exec(. 
4150: 20 73 71 6c 69 74 65 33 2a 2c 20 20 20 20 20 20   sqlite3*,      
4160: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4170: 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 41              /* A
4180: 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65 20  n open database 
4190: 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  */.  const char 
41a0: 2a 73 71 6c 2c 20 20 20 20 20 20 20 20 20 20 20  *sql,           
41b0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
41c0: 2f 2a 20 53 51 4c 20 74 6f 20 62 65 20 65 76 61  /* SQL to be eva
41d0: 6c 75 61 74 65 64 20 2a 2f 0a 20 20 69 6e 74 20  luated */.  int 
41e0: 28 2a 63 61 6c 6c 62 61 63 6b 29 28 76 6f 69 64  (*callback)(void
41f0: 2a 2c 69 6e 74 2c 63 68 61 72 2a 2a 2c 63 68 61  *,int,char**,cha
4200: 72 2a 2a 29 2c 20 20 2f 2a 20 43 61 6c 6c 62 61  r**),  /* Callba
4210: 63 6b 20 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a 20  ck function */. 
4220: 20 76 6f 69 64 20 2a 2c 20 20 20 20 20 20 20 20   void *,        
4230: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4240: 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 31              /* 1
4250: 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 63  st argument to c
4260: 61 6c 6c 62 61 63 6b 20 2a 2f 0a 20 20 63 68 61  allback */.  cha
4270: 72 20 2a 2a 65 72 72 6d 73 67 20 20 20 20 20 20  r **errmsg      
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 2f 2a 20 45 72 72 6f 72          /* Error
42a0: 20 6d 73 67 20 77 72 69 74 74 65 6e 20 68 65 72   msg written her
42b0: 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  e */.);../*.** C
42c0: 41 50 49 33 52 45 46 3a 20 52 65 73 75 6c 74 20  API3REF: Result 
42d0: 43 6f 64 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44  Codes.** KEYWORD
42e0: 53 3a 20 7b 72 65 73 75 6c 74 20 63 6f 64 65 20  S: {result code 
42f0: 64 65 66 69 6e 69 74 69 6f 6e 73 7d 0a 2a 2a 0a  definitions}.**.
4300: 2a 2a 20 4d 61 6e 79 20 53 51 4c 69 74 65 20 66  ** Many SQLite f
4310: 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20  unctions return 
4320: 61 6e 20 69 6e 74 65 67 65 72 20 72 65 73 75 6c  an integer resul
4330: 74 20 63 6f 64 65 20 66 72 6f 6d 20 74 68 65 20  t code from the 
4340: 73 65 74 20 73 68 6f 77 6e 0a 2a 2a 20 68 65 72  set shown.** her
4350: 65 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 69 6e  e in order to in
4360: 64 69 63 61 74 65 20 73 75 63 63 65 73 73 20 6f  dicate success o
4370: 72 20 66 61 69 6c 75 72 65 2e 0a 2a 2a 0a 2a 2a  r failure..**.**
4380: 20 4e 65 77 20 65 72 72 6f 72 20 63 6f 64 65 73   New error codes
4390: 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e   may be added in
43a0: 20 66 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73   future versions
43b0: 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a   of SQLite..**.*
43c0: 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 65 78 74  * See also: [ext
43d0: 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
43e0: 65 20 64 65 66 69 6e 69 74 69 6f 6e 73 5d 0a 2a  e definitions].*
43f0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4400: 5f 4f 4b 20 20 20 20 20 20 20 20 20 20 20 30 20  _OK           0 
4410: 20 20 2f 2a 20 53 75 63 63 65 73 73 66 75 6c 20    /* Successful 
4420: 72 65 73 75 6c 74 20 2a 2f 0a 2f 2a 20 62 65 67  result */./* beg
4430: 69 6e 6e 69 6e 67 2d 6f 66 2d 65 72 72 6f 72 2d  inning-of-error-
4440: 63 6f 64 65 73 20 2a 2f 0a 23 64 65 66 69 6e 65  codes */.#define
4450: 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 20 20 20   SQLITE_ERROR   
4460: 20 20 20 20 20 31 20 20 20 2f 2a 20 53 51 4c 20       1   /* SQL 
4470: 65 72 72 6f 72 20 6f 72 20 6d 69 73 73 69 6e 67  error or missing
4480: 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 23 64 65   database */.#de
4490: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45  fine SQLITE_INTE
44a0: 52 4e 41 4c 20 20 20 20 20 32 20 20 20 2f 2a 20  RNAL     2   /* 
44b0: 49 6e 74 65 72 6e 61 6c 20 6c 6f 67 69 63 20 65  Internal logic e
44c0: 72 72 6f 72 20 69 6e 20 53 51 4c 69 74 65 20 2a  rror in SQLite *
44d0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
44e0: 5f 50 45 52 4d 20 20 20 20 20 20 20 20 20 33 20  _PERM         3 
44f0: 20 20 2f 2a 20 41 63 63 65 73 73 20 70 65 72 6d    /* Access perm
4500: 69 73 73 69 6f 6e 20 64 65 6e 69 65 64 20 2a 2f  ission denied */
4510: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4520: 41 42 4f 52 54 20 20 20 20 20 20 20 20 34 20 20  ABORT        4  
4530: 20 2f 2a 20 43 61 6c 6c 62 61 63 6b 20 72 6f 75   /* Callback rou
4540: 74 69 6e 65 20 72 65 71 75 65 73 74 65 64 20 61  tine requested a
4550: 6e 20 61 62 6f 72 74 20 2a 2f 0a 23 64 65 66 69  n abort */.#defi
4560: 6e 65 20 53 51 4c 49 54 45 5f 42 55 53 59 20 20  ne SQLITE_BUSY  
4570: 20 20 20 20 20 20 20 35 20 20 20 2f 2a 20 54 68         5   /* Th
4580: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
4590: 69 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64 65  is locked */.#de
45a0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b  fine SQLITE_LOCK
45b0: 45 44 20 20 20 20 20 20 20 36 20 20 20 2f 2a 20  ED       6   /* 
45c0: 41 20 74 61 62 6c 65 20 69 6e 20 74 68 65 20 64  A table in the d
45d0: 61 74 61 62 61 73 65 20 69 73 20 6c 6f 63 6b 65  atabase is locke
45e0: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  d */.#define SQL
45f0: 49 54 45 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20  ITE_NOMEM       
4600: 20 37 20 20 20 2f 2a 20 41 20 6d 61 6c 6c 6f 63   7   /* A malloc
4610: 28 29 20 66 61 69 6c 65 64 20 2a 2f 0a 23 64 65  () failed */.#de
4620: 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44  fine SQLITE_READ
4630: 4f 4e 4c 59 20 20 20 20 20 38 20 20 20 2f 2a 20  ONLY     8   /* 
4640: 41 74 74 65 6d 70 74 20 74 6f 20 77 72 69 74 65  Attempt to write
4650: 20 61 20 72 65 61 64 6f 6e 6c 79 20 64 61 74 61   a readonly data
4660: 62 61 73 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20  base */.#define 
4670: 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54  SQLITE_INTERRUPT
4680: 20 20 20 20 39 20 20 20 2f 2a 20 4f 70 65 72 61      9   /* Opera
4690: 74 69 6f 6e 20 74 65 72 6d 69 6e 61 74 65 64 20  tion terminated 
46a0: 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  by sqlite3_inter
46b0: 72 75 70 74 28 29 2a 2f 0a 23 64 65 66 69 6e 65  rupt()*/.#define
46c0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 20 20   SQLITE_IOERR   
46d0: 20 20 20 20 31 30 20 20 20 2f 2a 20 53 6f 6d 65      10   /* Some
46e0: 20 6b 69 6e 64 20 6f 66 20 64 69 73 6b 20 49 2f   kind of disk I/
46f0: 4f 20 65 72 72 6f 72 20 6f 63 63 75 72 72 65 64  O error occurred
4700: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4710: 54 45 5f 43 4f 52 52 55 50 54 20 20 20 20 20 31  TE_CORRUPT     1
4720: 31 20 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62  1   /* The datab
4730: 61 73 65 20 64 69 73 6b 20 69 6d 61 67 65 20 69  ase disk image i
4740: 73 20 6d 61 6c 66 6f 72 6d 65 64 20 2a 2f 0a 23  s malformed */.#
4750: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f  define SQLITE_NO
4760: 54 46 4f 55 4e 44 20 20 20 20 31 32 20 20 20 2f  TFOUND    12   /
4770: 2a 20 55 6e 6b 6e 6f 77 6e 20 6f 70 63 6f 64 65  * Unknown opcode
4780: 20 69 6e 20 73 71 6c 69 74 65 33 5f 66 69 6c 65   in sqlite3_file
4790: 5f 63 6f 6e 74 72 6f 6c 28 29 20 2a 2f 0a 23 64  _control() */.#d
47a0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 55 4c  efine SQLITE_FUL
47b0: 4c 20 20 20 20 20 20 20 20 31 33 20 20 20 2f 2a  L        13   /*
47c0: 20 49 6e 73 65 72 74 69 6f 6e 20 66 61 69 6c 65   Insertion faile
47d0: 64 20 62 65 63 61 75 73 65 20 64 61 74 61 62 61  d because databa
47e0: 73 65 20 69 73 20 66 75 6c 6c 20 2a 2f 0a 23 64  se is full */.#d
47f0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e  efine SQLITE_CAN
4800: 54 4f 50 45 4e 20 20 20 20 31 34 20 20 20 2f 2a  TOPEN    14   /*
4810: 20 55 6e 61 62 6c 65 20 74 6f 20 6f 70 65 6e 20   Unable to open 
4820: 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
4830: 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  e */.#define SQL
4840: 49 54 45 5f 50 52 4f 54 4f 43 4f 4c 20 20 20 20  ITE_PROTOCOL    
4850: 31 35 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65  15   /* Database
4860: 20 6c 6f 63 6b 20 70 72 6f 74 6f 63 6f 6c 20 65   lock protocol e
4870: 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20  rror */.#define 
4880: 53 51 4c 49 54 45 5f 45 4d 50 54 59 20 20 20 20  SQLITE_EMPTY    
4890: 20 20 20 31 36 20 20 20 2f 2a 20 44 61 74 61 62     16   /* Datab
48a0: 61 73 65 20 69 73 20 65 6d 70 74 79 20 2a 2f 0a  ase is empty */.
48b0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
48c0: 43 48 45 4d 41 20 20 20 20 20 20 31 37 20 20 20  CHEMA      17   
48d0: 2f 2a 20 54 68 65 20 64 61 74 61 62 61 73 65 20  /* The database 
48e0: 73 63 68 65 6d 61 20 63 68 61 6e 67 65 64 20 2a  schema changed *
48f0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4900: 5f 54 4f 4f 42 49 47 20 20 20 20 20 20 31 38 20  _TOOBIG      18 
4910: 20 20 2f 2a 20 53 74 72 69 6e 67 20 6f 72 20 42    /* String or B
4920: 4c 4f 42 20 65 78 63 65 65 64 73 20 73 69 7a 65  LOB exceeds size
4930: 20 6c 69 6d 69 74 20 2a 2f 0a 23 64 65 66 69 6e   limit */.#defin
4940: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41  e SQLITE_CONSTRA
4950: 49 4e 54 20 20 31 39 20 20 20 2f 2a 20 41 62 6f  INT  19   /* Abo
4960: 72 74 20 64 75 65 20 74 6f 20 63 6f 6e 73 74 72  rt due to constr
4970: 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 20 2a  aint violation *
4980: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4990: 5f 4d 49 53 4d 41 54 43 48 20 20 20 20 32 30 20  _MISMATCH    20 
49a0: 20 20 2f 2a 20 44 61 74 61 20 74 79 70 65 20 6d    /* Data type m
49b0: 69 73 6d 61 74 63 68 20 2a 2f 0a 23 64 65 66 69  ismatch */.#defi
49c0: 6e 65 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  ne SQLITE_MISUSE
49d0: 20 20 20 20 20 20 32 31 20 20 20 2f 2a 20 4c 69        21   /* Li
49e0: 62 72 61 72 79 20 75 73 65 64 20 69 6e 63 6f 72  brary used incor
49f0: 72 65 63 74 6c 79 20 2a 2f 0a 23 64 65 66 69 6e  rectly */.#defin
4a00: 65 20 53 51 4c 49 54 45 5f 4e 4f 4c 46 53 20 20  e SQLITE_NOLFS  
4a10: 20 20 20 20 20 32 32 20 20 20 2f 2a 20 55 73 65       22   /* Use
4a20: 73 20 4f 53 20 66 65 61 74 75 72 65 73 20 6e 6f  s OS features no
4a30: 74 20 73 75 70 70 6f 72 74 65 64 20 6f 6e 20 68  t supported on h
4a40: 6f 73 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ost */.#define S
4a50: 51 4c 49 54 45 5f 41 55 54 48 20 20 20 20 20 20  QLITE_AUTH      
4a60: 20 20 32 33 20 20 20 2f 2a 20 41 75 74 68 6f 72    23   /* Author
4a70: 69 7a 61 74 69 6f 6e 20 64 65 6e 69 65 64 20 2a  ization denied *
4a80: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4a90: 5f 46 4f 52 4d 41 54 20 20 20 20 20 20 32 34 20  _FORMAT      24 
4aa0: 20 20 2f 2a 20 41 75 78 69 6c 69 61 72 79 20 64    /* Auxiliary d
4ab0: 61 74 61 62 61 73 65 20 66 6f 72 6d 61 74 20 65  atabase format e
4ac0: 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20  rror */.#define 
4ad0: 53 51 4c 49 54 45 5f 52 41 4e 47 45 20 20 20 20  SQLITE_RANGE    
4ae0: 20 20 20 32 35 20 20 20 2f 2a 20 32 6e 64 20 70     25   /* 2nd p
4af0: 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
4b00: 74 65 33 5f 62 69 6e 64 20 6f 75 74 20 6f 66 20  te3_bind out of 
4b10: 72 61 6e 67 65 20 2a 2f 0a 23 64 65 66 69 6e 65  range */.#define
4b20: 20 53 51 4c 49 54 45 5f 4e 4f 54 41 44 42 20 20   SQLITE_NOTADB  
4b30: 20 20 20 20 32 36 20 20 20 2f 2a 20 46 69 6c 65      26   /* File
4b40: 20 6f 70 65 6e 65 64 20 74 68 61 74 20 69 73 20   opened that is 
4b50: 6e 6f 74 20 61 20 64 61 74 61 62 61 73 65 20 66  not a database f
4b60: 69 6c 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ile */.#define S
4b70: 51 4c 49 54 45 5f 4e 4f 54 49 43 45 20 20 20 20  QLITE_NOTICE    
4b80: 20 20 32 37 20 20 20 2f 2a 20 4e 6f 74 69 66 69    27   /* Notifi
4b90: 63 61 74 69 6f 6e 73 20 66 72 6f 6d 20 73 71 6c  cations from sql
4ba0: 69 74 65 33 5f 6c 6f 67 28 29 20 2a 2f 0a 23 64  ite3_log() */.#d
4bb0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 57 41 52  efine SQLITE_WAR
4bc0: 4e 49 4e 47 20 20 20 20 20 32 38 20 20 20 2f 2a  NING     28   /*
4bd0: 20 57 61 72 6e 69 6e 67 73 20 66 72 6f 6d 20 73   Warnings from s
4be0: 71 6c 69 74 65 33 5f 6c 6f 67 28 29 20 2a 2f 0a  qlite3_log() */.
4bf0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52  #define SQLITE_R
4c00: 4f 57 20 20 20 20 20 20 20 20 20 31 30 30 20 20  OW         100  
4c10: 2f 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  /* sqlite3_step(
4c20: 29 20 68 61 73 20 61 6e 6f 74 68 65 72 20 72 6f  ) has another ro
4c30: 77 20 72 65 61 64 79 20 2a 2f 0a 23 64 65 66 69  w ready */.#defi
4c40: 6e 65 20 53 51 4c 49 54 45 5f 44 4f 4e 45 20 20  ne SQLITE_DONE  
4c50: 20 20 20 20 20 20 31 30 31 20 20 2f 2a 20 73 71        101  /* sq
4c60: 6c 69 74 65 33 5f 73 74 65 70 28 29 20 68 61 73  lite3_step() has
4c70: 20 66 69 6e 69 73 68 65 64 20 65 78 65 63 75 74   finished execut
4c80: 69 6e 67 20 2a 2f 0a 2f 2a 20 65 6e 64 2d 6f 66  ing */./* end-of
4c90: 2d 65 72 72 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a  -error-codes */.
4ca0: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
4cb0: 20 45 78 74 65 6e 64 65 64 20 52 65 73 75 6c 74   Extended Result
4cc0: 20 43 6f 64 65 73 0a 2a 2a 20 4b 45 59 57 4f 52   Codes.** KEYWOR
4cd0: 44 53 3a 20 7b 65 78 74 65 6e 64 65 64 20 72 65  DS: {extended re
4ce0: 73 75 6c 74 20 63 6f 64 65 20 64 65 66 69 6e 69  sult code defini
4cf0: 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 49 6e 20  tions}.**.** In 
4d00: 69 74 73 20 64 65 66 61 75 6c 74 20 63 6f 6e 66  its default conf
4d10: 69 67 75 72 61 74 69 6f 6e 2c 20 53 51 4c 69 74  iguration, SQLit
4d20: 65 20 41 50 49 20 72 6f 75 74 69 6e 65 73 20 72  e API routines r
4d30: 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20 33 30 20  eturn one of 30 
4d40: 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 72 65 73 75  integer.** [resu
4d50: 6c 74 20 63 6f 64 65 73 5d 2e 20 20 48 6f 77 65  lt codes].  Howe
4d60: 76 65 72 2c 20 65 78 70 65 72 69 65 6e 63 65 20  ver, experience 
4d70: 68 61 73 20 73 68 6f 77 6e 20 74 68 61 74 20 6d  has shown that m
4d80: 61 6e 79 20 6f 66 0a 2a 2a 20 74 68 65 73 65 20  any of.** these 
4d90: 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65  result codes are
4da0: 20 74 6f 6f 20 63 6f 61 72 73 65 2d 67 72 61 69   too coarse-grai
4db0: 6e 65 64 2e 20 20 54 68 65 79 20 64 6f 20 6e 6f  ned.  They do no
4dc0: 74 20 70 72 6f 76 69 64 65 20 61 73 0a 2a 2a 20  t provide as.** 
4dd0: 6d 75 63 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  much information
4de0: 20 61 62 6f 75 74 20 70 72 6f 62 6c 65 6d 73 20   about problems 
4df0: 61 73 20 70 72 6f 67 72 61 6d 6d 65 72 73 20 6d  as programmers m
4e00: 69 67 68 74 20 6c 69 6b 65 2e 20 20 49 6e 20 61  ight like.  In a
4e10: 6e 20 65 66 66 6f 72 74 20 74 6f 0a 2a 2a 20 61  n effort to.** a
4e20: 64 64 72 65 73 73 20 74 68 69 73 2c 20 6e 65 77  ddress this, new
4e30: 65 72 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53  er versions of S
4e40: 51 4c 69 74 65 20 28 76 65 72 73 69 6f 6e 20 33  QLite (version 3
4e50: 2e 33 2e 38 20 61 6e 64 20 6c 61 74 65 72 29 20  .3.8 and later) 
4e60: 69 6e 63 6c 75 64 65 0a 2a 2a 20 73 75 70 70 6f  include.** suppo
4e70: 72 74 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61  rt for additiona
4e80: 6c 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 74  l result codes t
4e90: 68 61 74 20 70 72 6f 76 69 64 65 20 6d 6f 72 65  hat provide more
4ea0: 20 64 65 74 61 69 6c 65 64 20 69 6e 66 6f 72 6d   detailed inform
4eb0: 61 74 69 6f 6e 0a 2a 2a 20 61 62 6f 75 74 20 65  ation.** about e
4ec0: 72 72 6f 72 73 2e 20 54 68 65 73 65 20 5b 65 78  rrors. These [ex
4ed0: 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f  tended result co
4ee0: 64 65 73 5d 20 61 72 65 20 65 6e 61 62 6c 65 64  des] are enabled
4ef0: 20 6f 72 20 64 69 73 61 62 6c 65 64 0a 2a 2a 20   or disabled.** 
4f00: 6f 6e 20 61 20 70 65 72 20 64 61 74 61 62 61 73  on a per databas
4f10: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 61 73  e connection bas
4f20: 69 73 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20  is using the.** 
4f30: 5b 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65  [sqlite3_extende
4f40: 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 29  d_result_codes()
4f50: 5d 20 41 50 49 2e 20 20 4f 72 2c 20 74 68 65 20  ] API.  Or, the 
4f60: 65 78 74 65 6e 64 65 64 20 63 6f 64 65 20 66 6f  extended code fo
4f70: 72 0a 2a 2a 20 74 68 65 20 6d 6f 73 74 20 72 65  r.** the most re
4f80: 63 65 6e 74 20 65 72 72 6f 72 20 63 61 6e 20 62  cent error can b
4f90: 65 20 6f 62 74 61 69 6e 65 64 20 75 73 69 6e 67  e obtained using
4fa0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 74  .** [sqlite3_ext
4fb0: 65 6e 64 65 64 5f 65 72 72 63 6f 64 65 28 29 5d  ended_errcode()]
4fc0: 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
4fd0: 49 54 45 5f 49 4f 45 52 52 5f 52 45 41 44 20 20  ITE_IOERR_READ  
4fe0: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
4ff0: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 3c 3c  ITE_IOERR | (1<<
5000: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5010: 54 45 5f 49 4f 45 52 52 5f 53 48 4f 52 54 5f 52  TE_IOERR_SHORT_R
5020: 45 41 44 20 20 20 20 20 20 20 20 28 53 51 4c 49  EAD        (SQLI
5030: 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 3c 3c 38  TE_IOERR | (2<<8
5040: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5050: 45 5f 49 4f 45 52 52 5f 57 52 49 54 45 20 20 20  E_IOERR_WRITE   
5060: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
5070: 45 5f 49 4f 45 52 52 20 7c 20 28 33 3c 3c 38 29  E_IOERR | (3<<8)
5080: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5090: 5f 49 4f 45 52 52 5f 46 53 59 4e 43 20 20 20 20  _IOERR_FSYNC    
50a0: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
50b0: 5f 49 4f 45 52 52 20 7c 20 28 34 3c 3c 38 29 29  _IOERR | (4<<8))
50c0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
50d0: 49 4f 45 52 52 5f 44 49 52 5f 46 53 59 4e 43 20  IOERR_DIR_FSYNC 
50e0: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
50f0: 49 4f 45 52 52 20 7c 20 28 35 3c 3c 38 29 29 0a  IOERR | (5<<8)).
5100: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
5110: 4f 45 52 52 5f 54 52 55 4e 43 41 54 45 20 20 20  OERR_TRUNCATE   
5120: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49         (SQLITE_I
5130: 4f 45 52 52 20 7c 20 28 36 3c 3c 38 29 29 0a 23  OERR | (6<<8)).#
5140: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5150: 45 52 52 5f 46 53 54 41 54 20 20 20 20 20 20 20  ERR_FSTAT       
5160: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
5170: 45 52 52 20 7c 20 28 37 3c 3c 38 29 29 0a 23 64  ERR | (7<<8)).#d
5180: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
5190: 52 52 5f 55 4e 4c 4f 43 4b 20 20 20 20 20 20 20  RR_UNLOCK       
51a0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
51b0: 52 52 20 7c 20 28 38 3c 3c 38 29 29 0a 23 64 65  RR | (8<<8)).#de
51c0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
51d0: 52 5f 52 44 4c 4f 43 4b 20 20 20 20 20 20 20 20  R_RDLOCK        
51e0: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
51f0: 52 20 7c 20 28 39 3c 3c 38 29 29 0a 23 64 65 66  R | (9<<8)).#def
5200: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5210: 5f 44 45 4c 45 54 45 20 20 20 20 20 20 20 20 20  _DELETE         
5220: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5230: 20 7c 20 28 31 30 3c 3c 38 29 29 0a 23 64 65 66   | (10<<8)).#def
5240: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5250: 5f 42 4c 4f 43 4b 45 44 20 20 20 20 20 20 20 20  _BLOCKED        
5260: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5270: 20 7c 20 28 31 31 3c 3c 38 29 29 0a 23 64 65 66   | (11<<8)).#def
5280: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5290: 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20 20 20 20  _NOMEM          
52a0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
52b0: 20 7c 20 28 31 32 3c 3c 38 29 29 0a 23 64 65 66   | (12<<8)).#def
52c0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
52d0: 5f 41 43 43 45 53 53 20 20 20 20 20 20 20 20 20  _ACCESS         
52e0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
52f0: 20 7c 20 28 31 33 3c 3c 38 29 29 0a 23 64 65 66   | (13<<8)).#def
5300: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5310: 5f 43 48 45 43 4b 52 45 53 45 52 56 45 44 4c 4f  _CHECKRESERVEDLO
5320: 43 4b 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52  CK (SQLITE_IOERR
5330: 20 7c 20 28 31 34 3c 3c 38 29 29 0a 23 64 65 66   | (14<<8)).#def
5340: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5350: 5f 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20  _LOCK           
5360: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5370: 20 7c 20 28 31 35 3c 3c 38 29 29 0a 23 64 65 66   | (15<<8)).#def
5380: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5390: 5f 43 4c 4f 53 45 20 20 20 20 20 20 20 20 20 20  _CLOSE          
53a0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
53b0: 20 7c 20 28 31 36 3c 3c 38 29 29 0a 23 64 65 66   | (16<<8)).#def
53c0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
53d0: 5f 44 49 52 5f 43 4c 4f 53 45 20 20 20 20 20 20  _DIR_CLOSE      
53e0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
53f0: 20 7c 20 28 31 37 3c 3c 38 29 29 0a 23 64 65 66   | (17<<8)).#def
5400: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5410: 5f 53 48 4d 4f 50 45 4e 20 20 20 20 20 20 20 20  _SHMOPEN        
5420: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5430: 20 7c 20 28 31 38 3c 3c 38 29 29 0a 23 64 65 66   | (18<<8)).#def
5440: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5450: 5f 53 48 4d 53 49 5a 45 20 20 20 20 20 20 20 20  _SHMSIZE        
5460: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5470: 20 7c 20 28 31 39 3c 3c 38 29 29 0a 23 64 65 66   | (19<<8)).#def
5480: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5490: 5f 53 48 4d 4c 4f 43 4b 20 20 20 20 20 20 20 20  _SHMLOCK        
54a0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
54b0: 20 7c 20 28 32 30 3c 3c 38 29 29 0a 23 64 65 66   | (20<<8)).#def
54c0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
54d0: 5f 53 48 4d 4d 41 50 20 20 20 20 20 20 20 20 20  _SHMMAP         
54e0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
54f0: 20 7c 20 28 32 31 3c 3c 38 29 29 0a 23 64 65 66   | (21<<8)).#def
5500: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5510: 5f 53 45 45 4b 20 20 20 20 20 20 20 20 20 20 20  _SEEK           
5520: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5530: 20 7c 20 28 32 32 3c 3c 38 29 29 0a 23 64 65 66   | (22<<8)).#def
5540: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5550: 5f 44 45 4c 45 54 45 5f 4e 4f 45 4e 54 20 20 20  _DELETE_NOENT   
5560: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5570: 20 7c 20 28 32 33 3c 3c 38 29 29 0a 23 64 65 66   | (23<<8)).#def
5580: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5590: 5f 4d 4d 41 50 20 20 20 20 20 20 20 20 20 20 20  _MMAP           
55a0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
55b0: 20 7c 20 28 32 34 3c 3c 38 29 29 0a 23 64 65 66   | (24<<8)).#def
55c0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
55d0: 5f 47 45 54 54 45 4d 50 50 41 54 48 20 20 20 20  _GETTEMPPATH    
55e0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
55f0: 20 7c 20 28 32 35 3c 3c 38 29 29 0a 23 64 65 66   | (25<<8)).#def
5600: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5610: 5f 43 4f 4e 56 50 41 54 48 20 20 20 20 20 20 20  _CONVPATH       
5620: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5630: 20 7c 20 28 32 36 3c 3c 38 29 29 0a 23 64 65 66   | (26<<8)).#def
5640: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5650: 5f 56 4e 4f 44 45 20 20 20 20 20 20 20 20 20 20  _VNODE          
5660: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5670: 20 7c 20 28 32 37 3c 3c 38 29 29 0a 23 64 65 66   | (27<<8)).#def
5680: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5690: 5f 41 55 54 48 20 20 20 20 20 20 20 20 20 20 20  _AUTH           
56a0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
56b0: 20 7c 20 28 32 38 3c 3c 38 29 29 0a 23 64 65 66   | (28<<8)).#def
56c0: 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 45  ine SQLITE_LOCKE
56d0: 44 5f 53 48 41 52 45 44 43 41 43 48 45 20 20 20  D_SHAREDCACHE   
56e0: 20 20 20 28 53 51 4c 49 54 45 5f 4c 4f 43 4b 45     (SQLITE_LOCKE
56f0: 44 20 7c 20 20 28 31 3c 3c 38 29 29 0a 23 64 65  D |  (1<<8)).#de
5700: 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55 53 59  fine SQLITE_BUSY
5710: 5f 52 45 43 4f 56 45 52 59 20 20 20 20 20 20 20  _RECOVERY       
5720: 20 20 20 20 28 53 51 4c 49 54 45 5f 42 55 53 59      (SQLITE_BUSY
5730: 20 20 20 7c 20 20 28 31 3c 3c 38 29 29 0a 23 64     |  (1<<8)).#d
5740: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55 53  efine SQLITE_BUS
5750: 59 5f 53 4e 41 50 53 48 4f 54 20 20 20 20 20 20  Y_SNAPSHOT      
5760: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 42 55 53       (SQLITE_BUS
5770: 59 20 20 20 7c 20 20 28 32 3c 3c 38 29 29 0a 23  Y   |  (2<<8)).#
5780: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41  define SQLITE_CA
5790: 4e 54 4f 50 45 4e 5f 4e 4f 54 45 4d 50 44 49 52  NTOPEN_NOTEMPDIR
57a0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 41        (SQLITE_CA
57b0: 4e 54 4f 50 45 4e 20 7c 20 28 31 3c 3c 38 29 29  NTOPEN | (1<<8))
57c0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
57d0: 43 41 4e 54 4f 50 45 4e 5f 49 53 44 49 52 20 20  CANTOPEN_ISDIR  
57e0: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
57f0: 43 41 4e 54 4f 50 45 4e 20 7c 20 28 32 3c 3c 38  CANTOPEN | (2<<8
5800: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5810: 45 5f 43 41 4e 54 4f 50 45 4e 5f 46 55 4c 4c 50  E_CANTOPEN_FULLP
5820: 41 54 48 20 20 20 20 20 20 20 28 53 51 4c 49 54  ATH       (SQLIT
5830: 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28 33 3c  E_CANTOPEN | (3<
5840: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5850: 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5f 43 4f 4e  ITE_CANTOPEN_CON
5860: 56 50 41 54 48 20 20 20 20 20 20 20 28 53 51 4c  VPATH       (SQL
5870: 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28  ITE_CANTOPEN | (
5880: 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  4<<8)).#define S
5890: 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 5f 56 54  QLITE_CORRUPT_VT
58a0: 41 42 20 20 20 20 20 20 20 20 20 20 20 20 28 53  AB            (S
58b0: 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 20 7c 20  QLITE_CORRUPT | 
58c0: 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (1<<8)).#define 
58d0: 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5f  SQLITE_READONLY_
58e0: 52 45 43 4f 56 45 52 59 20 20 20 20 20 20 20 28  RECOVERY       (
58f0: 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20  SQLITE_READONLY 
5900: 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (1<<8)).#defin
5910: 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c  e SQLITE_READONL
5920: 59 5f 43 41 4e 54 4c 4f 43 4b 20 20 20 20 20 20  Y_CANTLOCK      
5930: 20 28 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c   (SQLITE_READONL
5940: 59 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66  Y | (2<<8)).#def
5950: 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f  ine SQLITE_READO
5960: 4e 4c 59 5f 52 4f 4c 4c 42 41 43 4b 20 20 20 20  NLY_ROLLBACK    
5970: 20 20 20 28 53 51 4c 49 54 45 5f 52 45 41 44 4f     (SQLITE_READO
5980: 4e 4c 59 20 7c 20 28 33 3c 3c 38 29 29 0a 23 64  NLY | (3<<8)).#d
5990: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41  efine SQLITE_REA
59a0: 44 4f 4e 4c 59 5f 44 42 4d 4f 56 45 44 20 20 20  DONLY_DBMOVED   
59b0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 52 45 41       (SQLITE_REA
59c0: 44 4f 4e 4c 59 20 7c 20 28 34 3c 3c 38 29 29 0a  DONLY | (4<<8)).
59d0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
59e0: 42 4f 52 54 5f 52 4f 4c 4c 42 41 43 4b 20 20 20  BORT_ROLLBACK   
59f0: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 41         (SQLITE_A
5a00: 42 4f 52 54 20 7c 20 28 32 3c 3c 38 29 29 0a 23  BORT | (2<<8)).#
5a10: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
5a20: 4e 53 54 52 41 49 4e 54 5f 43 48 45 43 4b 20 20  NSTRAINT_CHECK  
5a30: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f        (SQLITE_CO
5a40: 4e 53 54 52 41 49 4e 54 20 7c 20 28 31 3c 3c 38  NSTRAINT | (1<<8
5a50: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5a60: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 43 4f 4d  E_CONSTRAINT_COM
5a70: 4d 49 54 48 4f 4f 4b 20 20 20 28 53 51 4c 49 54  MITHOOK   (SQLIT
5a80: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28  E_CONSTRAINT | (
5a90: 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  2<<8)).#define S
5aa0: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54  QLITE_CONSTRAINT
5ab0: 5f 46 4f 52 45 49 47 4e 4b 45 59 20 20 20 28 53  _FOREIGNKEY   (S
5ac0: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54  QLITE_CONSTRAINT
5ad0: 20 7c 20 28 33 3c 3c 38 29 29 0a 23 64 65 66 69   | (3<<8)).#defi
5ae0: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52  ne SQLITE_CONSTR
5af0: 41 49 4e 54 5f 46 55 4e 43 54 49 4f 4e 20 20 20  AINT_FUNCTION   
5b00: 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52    (SQLITE_CONSTR
5b10: 41 49 4e 54 20 7c 20 28 34 3c 3c 38 29 29 0a 23  AINT | (4<<8)).#
5b20: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
5b30: 4e 53 54 52 41 49 4e 54 5f 4e 4f 54 4e 55 4c 4c  NSTRAINT_NOTNULL
5b40: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f        (SQLITE_CO
5b50: 4e 53 54 52 41 49 4e 54 20 7c 20 28 35 3c 3c 38  NSTRAINT | (5<<8
5b60: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5b70: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 50 52 49  E_CONSTRAINT_PRI
5b80: 4d 41 52 59 4b 45 59 20 20 20 28 53 51 4c 49 54  MARYKEY   (SQLIT
5b90: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28  E_CONSTRAINT | (
5ba0: 36 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  6<<8)).#define S
5bb0: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54  QLITE_CONSTRAINT
5bc0: 5f 54 52 49 47 47 45 52 20 20 20 20 20 20 28 53  _TRIGGER      (S
5bd0: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54  QLITE_CONSTRAINT
5be0: 20 7c 20 28 37 3c 3c 38 29 29 0a 23 64 65 66 69   | (7<<8)).#defi
5bf0: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52  ne SQLITE_CONSTR
5c00: 41 49 4e 54 5f 55 4e 49 51 55 45 20 20 20 20 20  AINT_UNIQUE     
5c10: 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52    (SQLITE_CONSTR
5c20: 41 49 4e 54 20 7c 20 28 38 3c 3c 38 29 29 0a 23  AINT | (8<<8)).#
5c30: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
5c40: 4e 53 54 52 41 49 4e 54 5f 56 54 41 42 20 20 20  NSTRAINT_VTAB   
5c50: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f        (SQLITE_CO
5c60: 4e 53 54 52 41 49 4e 54 20 7c 20 28 39 3c 3c 38  NSTRAINT | (9<<8
5c70: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5c80: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 52 4f 57  E_CONSTRAINT_ROW
5c90: 49 44 20 20 20 20 20 20 20 20 28 53 51 4c 49 54  ID        (SQLIT
5ca0: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 28 31  E_CONSTRAINT |(1
5cb0: 30 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  0<<8)).#define S
5cc0: 51 4c 49 54 45 5f 4e 4f 54 49 43 45 5f 52 45 43  QLITE_NOTICE_REC
5cd0: 4f 56 45 52 5f 57 41 4c 20 20 20 20 20 20 28 53  OVER_WAL      (S
5ce0: 51 4c 49 54 45 5f 4e 4f 54 49 43 45 20 7c 20 28  QLITE_NOTICE | (
5cf0: 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  1<<8)).#define S
5d00: 51 4c 49 54 45 5f 4e 4f 54 49 43 45 5f 52 45 43  QLITE_NOTICE_REC
5d10: 4f 56 45 52 5f 52 4f 4c 4c 42 41 43 4b 20 28 53  OVER_ROLLBACK (S
5d20: 51 4c 49 54 45 5f 4e 4f 54 49 43 45 20 7c 20 28  QLITE_NOTICE | (
5d30: 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  2<<8)).#define S
5d40: 51 4c 49 54 45 5f 57 41 52 4e 49 4e 47 5f 41 55  QLITE_WARNING_AU
5d50: 54 4f 49 4e 44 45 58 20 20 20 20 20 20 20 28 53  TOINDEX       (S
5d60: 51 4c 49 54 45 5f 57 41 52 4e 49 4e 47 20 7c 20  QLITE_WARNING | 
5d70: 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (1<<8)).#define 
5d80: 53 51 4c 49 54 45 5f 41 55 54 48 5f 55 53 45 52  SQLITE_AUTH_USER
5d90: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 28                 (
5da0: 53 51 4c 49 54 45 5f 41 55 54 48 20 7c 20 28 31  SQLITE_AUTH | (1
5db0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5dc0: 4c 49 54 45 5f 4f 4b 5f 4c 4f 41 44 5f 50 45 52  LITE_OK_LOAD_PER
5dd0: 4d 41 4e 45 4e 54 4c 59 20 20 20 20 20 28 53 51  MANENTLY     (SQ
5de0: 4c 49 54 45 5f 4f 4b 20 7c 20 28 31 3c 3c 38 29  LITE_OK | (1<<8)
5df0: 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  )../*.** CAPI3RE
5e00: 46 3a 20 46 6c 61 67 73 20 46 6f 72 20 46 69 6c  F: Flags For Fil
5e10: 65 20 4f 70 65 6e 20 4f 70 65 72 61 74 69 6f 6e  e Open Operation
5e20: 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 62 69  s.**.** These bi
5e30: 74 20 76 61 6c 75 65 73 20 61 72 65 20 69 6e 74  t values are int
5e40: 65 6e 64 65 64 20 66 6f 72 20 75 73 65 20 69 6e  ended for use in
5e50: 20 74 68 65 0a 2a 2a 20 33 72 64 20 70 61 72 61   the.** 3rd para
5e60: 6d 65 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71  meter to the [sq
5e70: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d  lite3_open_v2()]
5e80: 20 69 6e 74 65 72 66 61 63 65 20 61 6e 64 0a 2a   interface and.*
5e90: 2a 20 69 6e 20 74 68 65 20 34 74 68 20 70 61 72  * in the 4th par
5ea0: 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 5b 73  ameter to the [s
5eb0: 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e  qlite3_vfs.xOpen
5ec0: 5d 20 6d 65 74 68 6f 64 2e 0a 2a 2f 0a 23 64 65  ] method..*/.#de
5ed0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
5ee0: 5f 52 45 41 44 4f 4e 4c 59 20 20 20 20 20 20 20  _READONLY       
5ef0: 20 20 30 78 30 30 30 30 30 30 30 31 20 20 2f 2a    0x00000001  /*
5f00: 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f   Ok for sqlite3_
5f10: 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65  open_v2() */.#de
5f20: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
5f30: 5f 52 45 41 44 57 52 49 54 45 20 20 20 20 20 20  _READWRITE      
5f40: 20 20 30 78 30 30 30 30 30 30 30 32 20 20 2f 2a    0x00000002  /*
5f50: 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f   Ok for sqlite3_
5f60: 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65  open_v2() */.#de
5f70: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
5f80: 5f 43 52 45 41 54 45 20 20 20 20 20 20 20 20 20  _CREATE         
5f90: 20 20 30 78 30 30 30 30 30 30 30 34 20 20 2f 2a    0x00000004  /*
5fa0: 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f   Ok for sqlite3_
5fb0: 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65  open_v2() */.#de
5fc0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
5fd0: 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 20 20  _DELETEONCLOSE  
5fe0: 20 20 30 78 30 30 30 30 30 30 30 38 20 20 2f 2a    0x00000008  /*
5ff0: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
6000: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
6010: 5f 45 58 43 4c 55 53 49 56 45 20 20 20 20 20 20  _EXCLUSIVE      
6020: 20 20 30 78 30 30 30 30 30 30 31 30 20 20 2f 2a    0x00000010  /*
6030: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
6040: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
6050: 5f 41 55 54 4f 50 52 4f 58 59 20 20 20 20 20 20  _AUTOPROXY      
6060: 20 20 30 78 30 30 30 30 30 30 32 30 20 20 2f 2a    0x00000020  /*
6070: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
6080: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
6090: 5f 55 52 49 20 20 20 20 20 20 20 20 20 20 20 20  _URI            
60a0: 20 20 30 78 30 30 30 30 30 30 34 30 20 20 2f 2a    0x00000040  /*
60b0: 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f   Ok for sqlite3_
60c0: 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65  open_v2() */.#de
60d0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
60e0: 5f 4d 45 4d 4f 52 59 20 20 20 20 20 20 20 20 20  _MEMORY         
60f0: 20 20 30 78 30 30 30 30 30 30 38 30 20 20 2f 2a    0x00000080  /*
6100: 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f   Ok for sqlite3_
6110: 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65  open_v2() */.#de
6120: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
6130: 5f 4d 41 49 4e 5f 44 42 20 20 20 20 20 20 20 20  _MAIN_DB        
6140: 20 20 30 78 30 30 30 30 30 31 30 30 20 20 2f 2a    0x00000100  /*
6150: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
6160: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
6170: 5f 54 45 4d 50 5f 44 42 20 20 20 20 20 20 20 20  _TEMP_DB        
6180: 20 20 30 78 30 30 30 30 30 32 30 30 20 20 2f 2a    0x00000200  /*
6190: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
61a0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
61b0: 5f 54 52 41 4e 53 49 45 4e 54 5f 44 42 20 20 20  _TRANSIENT_DB   
61c0: 20 20 30 78 30 30 30 30 30 34 30 30 20 20 2f 2a    0x00000400  /*
61d0: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
61e0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
61f0: 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c 20 20 20  _MAIN_JOURNAL   
6200: 20 20 30 78 30 30 30 30 30 38 30 30 20 20 2f 2a    0x00000800  /*
6210: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
6220: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
6230: 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41 4c 20 20 20  _TEMP_JOURNAL   
6240: 20 20 30 78 30 30 30 30 31 30 30 30 20 20 2f 2a    0x00001000  /*
6250: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
6260: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
6270: 5f 53 55 42 4a 4f 55 52 4e 41 4c 20 20 20 20 20  _SUBJOURNAL     
6280: 20 20 30 78 30 30 30 30 32 30 30 30 20 20 2f 2a    0x00002000  /*
6290: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
62a0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
62b0: 5f 4d 41 53 54 45 52 5f 4a 4f 55 52 4e 41 4c 20  _MASTER_JOURNAL 
62c0: 20 20 30 78 30 30 30 30 34 30 30 30 20 20 2f 2a    0x00004000  /*
62d0: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
62e0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
62f0: 5f 4e 4f 4d 55 54 45 58 20 20 20 20 20 20 20 20  _NOMUTEX        
6300: 20 20 30 78 30 30 30 30 38 30 30 30 20 20 2f 2a    0x00008000  /*
6310: 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f   Ok for sqlite3_
6320: 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65  open_v2() */.#de
6330: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
6340: 5f 46 55 4c 4c 4d 55 54 45 58 20 20 20 20 20 20  _FULLMUTEX      
6350: 20 20 30 78 30 30 30 31 30 30 30 30 20 20 2f 2a    0x00010000  /*
6360: 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f   Ok for sqlite3_
6370: 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65  open_v2() */.#de
6380: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
6390: 5f 53 48 41 52 45 44 43 41 43 48 45 20 20 20 20  _SHAREDCACHE    
63a0: 20 20 30 78 30 30 30 32 30 30 30 30 20 20 2f 2a    0x00020000  /*
63b0: 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f   Ok for sqlite3_
63c0: 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65  open_v2() */.#de
63d0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
63e0: 5f 50 52 49 56 41 54 45 43 41 43 48 45 20 20 20  _PRIVATECACHE   
63f0: 20 20 30 78 30 30 30 34 30 30 30 30 20 20 2f 2a    0x00040000  /*
6400: 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f   Ok for sqlite3_
6410: 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65  open_v2() */.#de
6420: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
6430: 5f 57 41 4c 20 20 20 20 20 20 20 20 20 20 20 20  _WAL            
6440: 20 20 30 78 30 30 30 38 30 30 30 30 20 20 2f 2a    0x00080000  /*
6450: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
6460: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
6470: 5f 46 49 4c 45 50 52 4f 54 45 43 54 49 4f 4e 5f  _FILEPROTECTION_
6480: 4d 41 53 4b 20 20 20 20 20 20 20 20 20 20 20 20  MASK            
6490: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
64a0: 20 20 20 20 20 30 78 30 30 37 30 30 30 30 30 0a       0x00700000.
64b0: 0a 2f 2a 20 52 65 73 65 72 76 65 64 3a 20 20 20  ./* Reserved:   
64c0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
64d0: 20 20 20 20 20 20 30 78 30 30 46 30 30 30 30 30        0x00F00000
64e0: 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33   */../*.** CAPI3
64f0: 52 45 46 3a 20 44 65 76 69 63 65 20 43 68 61 72  REF: Device Char
6500: 61 63 74 65 72 69 73 74 69 63 73 0a 2a 2a 0a 2a  acteristics.**.*
6510: 2a 20 54 68 65 20 78 44 65 76 69 63 65 43 68 61  * The xDeviceCha
6520: 72 61 63 74 65 72 69 73 74 69 63 73 20 6d 65 74  racteristics met
6530: 68 6f 64 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  hod of the [sqli
6540: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a  te3_io_methods].
6550: 2a 2a 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e  ** object return
6560: 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68 69  s an integer whi
6570: 63 68 20 69 73 20 61 20 76 65 63 74 6f 72 20 6f  ch is a vector o
6580: 66 20 74 68 65 73 65 0a 2a 2a 20 62 69 74 20 76  f these.** bit v
6590: 61 6c 75 65 73 20 65 78 70 72 65 73 73 69 6e 67  alues expressing
65a0: 20 49 2f 4f 20 63 68 61 72 61 63 74 65 72 69 73   I/O characteris
65b0: 74 69 63 73 20 6f 66 20 74 68 65 20 6d 61 73 73  tics of the mass
65c0: 20 73 74 6f 72 61 67 65 0a 2a 2a 20 64 65 76 69   storage.** devi
65d0: 63 65 20 74 68 61 74 20 68 6f 6c 64 73 20 74 68  ce that holds th
65e0: 65 20 66 69 6c 65 20 74 68 61 74 20 74 68 65 20  e file that the 
65f0: 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68  [sqlite3_io_meth
6600: 6f 64 73 5d 0a 2a 2a 20 72 65 66 65 72 73 20 74  ods].** refers t
6610: 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c  o..**.** The SQL
6620: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
6630: 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20   property means 
6640: 74 68 61 74 20 61 6c 6c 20 77 72 69 74 65 73 20  that all writes 
6650: 6f 66 0a 2a 2a 20 61 6e 79 20 73 69 7a 65 20 61  of.** any size a
6660: 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20  re atomic.  The 
6670: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
6680: 4d 49 43 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a  MICnnn values.**
6690: 20 6d 65 61 6e 20 74 68 61 74 20 77 72 69 74 65   mean that write
66a0: 73 20 6f 66 20 62 6c 6f 63 6b 73 20 74 68 61 74  s of blocks that
66b0: 20 61 72 65 20 6e 6e 6e 20 62 79 74 65 73 20 69   are nnn bytes i
66c0: 6e 20 73 69 7a 65 20 61 6e 64 0a 2a 2a 20 61 72  n size and.** ar
66d0: 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20  e aligned to an 
66e0: 61 64 64 72 65 73 73 20 77 68 69 63 68 20 69 73  address which is
66f0: 20 61 6e 20 69 6e 74 65 67 65 72 20 6d 75 6c 74   an integer mult
6700: 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61  iple of.** nnn a
6710: 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20  re atomic.  The 
6720: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46  SQLITE_IOCAP_SAF
6730: 45 5f 41 50 50 45 4e 44 20 76 61 6c 75 65 20 6d  E_APPEND value m
6740: 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20 77 68 65  eans.** that whe
6750: 6e 20 64 61 74 61 20 69 73 20 61 70 70 65 6e 64  n data is append
6760: 65 64 20 74 6f 20 61 20 66 69 6c 65 2c 20 74 68  ed to a file, th
6770: 65 20 64 61 74 61 20 69 73 20 61 70 70 65 6e 64  e data is append
6780: 65 64 0a 2a 2a 20 66 69 72 73 74 20 74 68 65 6e  ed.** first then
6790: 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65   the size of the
67a0: 20 66 69 6c 65 20 69 73 20 65 78 74 65 6e 64 65   file is extende
67b0: 64 2c 20 6e 65 76 65 72 20 74 68 65 20 6f 74 68  d, never the oth
67c0: 65 72 0a 2a 2a 20 77 61 79 20 61 72 6f 75 6e 64  er.** way around
67d0: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f  .  The SQLITE_IO
67e0: 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 70  CAP_SEQUENTIAL p
67f0: 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68  roperty means th
6800: 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f  at.** informatio
6810: 6e 20 69 73 20 77 72 69 74 74 65 6e 20 74 6f 20  n is written to 
6820: 64 69 73 6b 20 69 6e 20 74 68 65 20 73 61 6d 65  disk in the same
6830: 20 6f 72 64 65 72 20 61 73 20 63 61 6c 6c 73 0a   order as calls.
6840: 2a 2a 20 74 6f 20 78 57 72 69 74 65 28 29 2e 20  ** to xWrite(). 
6850: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41   The SQLITE_IOCA
6860: 50 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52  P_POWERSAFE_OVER
6870: 57 52 49 54 45 20 70 72 6f 70 65 72 74 79 20 6d  WRITE property m
6880: 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20 61 66 74  eans that.** aft
6890: 65 72 20 72 65 62 6f 6f 74 20 66 6f 6c 6c 6f 77  er reboot follow
68a0: 69 6e 67 20 61 20 63 72 61 73 68 20 6f 72 20 70  ing a crash or p
68b0: 6f 77 65 72 20 6c 6f 73 73 2c 20 74 68 65 20 6f  ower loss, the o
68c0: 6e 6c 79 20 62 79 74 65 73 20 69 6e 20 61 0a 2a  nly bytes in a.*
68d0: 2a 20 66 69 6c 65 20 74 68 61 74 20 77 65 72 65  * file that were
68e0: 20 77 72 69 74 74 65 6e 20 61 74 20 74 68 65 20   written at the 
68f0: 61 70 70 6c 69 63 61 74 69 6f 6e 20 6c 65 76 65  application leve
6900: 6c 20 6d 69 67 68 74 20 68 61 76 65 20 63 68 61  l might have cha
6910: 6e 67 65 64 0a 2a 2a 20 61 6e 64 20 74 68 61 74  nged.** and that
6920: 20 61 64 6a 61 63 65 6e 74 20 62 79 74 65 73 2c   adjacent bytes,
6930: 20 65 76 65 6e 20 62 79 74 65 73 20 77 69 74 68   even bytes with
6940: 69 6e 20 74 68 65 20 73 61 6d 65 20 73 65 63 74  in the same sect
6950: 6f 72 20 61 72 65 0a 2a 2a 20 67 75 61 72 61 6e  or are.** guaran
6960: 74 65 65 64 20 74 6f 20 62 65 20 75 6e 63 68 61  teed to be uncha
6970: 6e 67 65 64 2e 20 20 54 68 65 20 53 51 4c 49 54  nged.  The SQLIT
6980: 45 5f 49 4f 43 41 50 5f 55 4e 44 45 4c 45 54 41  E_IOCAP_UNDELETA
6990: 42 4c 45 5f 57 48 45 4e 5f 4f 50 45 4e 0a 2a 2a  BLE_WHEN_OPEN.**
69a0: 20 66 6c 61 67 20 69 6e 64 69 63 61 74 65 20 74   flag indicate t
69b0: 68 61 74 20 61 20 66 69 6c 65 20 63 61 6e 6e 6f  hat a file canno
69c0: 74 20 62 65 20 64 65 6c 65 74 65 64 20 77 68 65  t be deleted whe
69d0: 6e 20 6f 70 65 6e 2e 20 20 54 68 65 0a 2a 2a 20  n open.  The.** 
69e0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 49 4d 4d  SQLITE_IOCAP_IMM
69f0: 55 54 41 42 4c 45 20 66 6c 61 67 20 69 6e 64 69  UTABLE flag indi
6a00: 63 61 74 65 73 20 74 68 61 74 20 74 68 65 20 66  cates that the f
6a10: 69 6c 65 20 69 73 20 6f 6e 0a 2a 2a 20 72 65 61  ile is on.** rea
6a20: 64 2d 6f 6e 6c 79 20 6d 65 64 69 61 20 61 6e 64  d-only media and
6a30: 20 63 61 6e 6e 6f 74 20 62 65 20 63 68 61 6e 67   cannot be chang
6a40: 65 64 20 65 76 65 6e 20 62 79 20 70 72 6f 63 65  ed even by proce
6a50: 73 73 65 73 20 77 69 74 68 0a 2a 2a 20 65 6c 65  sses with.** ele
6a60: 76 61 74 65 64 20 70 72 69 76 69 6c 65 67 65 73  vated privileges
6a70: 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
6a80: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
6a90: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
6aa0: 20 30 78 30 30 30 30 30 30 30 31 0a 23 64 65 66   0x00000001.#def
6ab0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
6ac0: 5f 41 54 4f 4d 49 43 35 31 32 20 20 20 20 20 20  _ATOMIC512      
6ad0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
6ae0: 30 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  02.#define SQLIT
6af0: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 4b  E_IOCAP_ATOMIC1K
6b00: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30                 0
6b10: 78 30 30 30 30 30 30 30 34 0a 23 64 65 66 69 6e  x00000004.#defin
6b20: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
6b30: 54 4f 4d 49 43 32 4b 20 20 20 20 20 20 20 20 20  TOMIC2K         
6b40: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 38        0x00000008
6b50: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6b60: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 34 4b 20 20  IOCAP_ATOMIC4K  
6b70: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30               0x0
6b80: 30 30 30 30 30 31 30 0a 23 64 65 66 69 6e 65 20  0000010.#define 
6b90: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
6ba0: 4d 49 43 38 4b 20 20 20 20 20 20 20 20 20 20 20  MIC8K           
6bb0: 20 20 20 20 30 78 30 30 30 30 30 30 32 30 0a 23      0x00000020.#
6bc0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
6bd0: 43 41 50 5f 41 54 4f 4d 49 43 31 36 4b 20 20 20  CAP_ATOMIC16K   
6be0: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
6bf0: 30 30 30 34 30 0a 23 64 65 66 69 6e 65 20 53 51  00040.#define SQ
6c00: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
6c10: 43 33 32 4b 20 20 20 20 20 20 20 20 20 20 20 20  C32K            
6c20: 20 20 30 78 30 30 30 30 30 30 38 30 0a 23 64 65    0x00000080.#de
6c30: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
6c40: 50 5f 41 54 4f 4d 49 43 36 34 4b 20 20 20 20 20  P_ATOMIC64K     
6c50: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
6c60: 31 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  100.#define SQLI
6c70: 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50  TE_IOCAP_SAFE_AP
6c80: 50 45 4e 44 20 20 20 20 20 20 20 20 20 20 20 20  PEND            
6c90: 30 78 30 30 30 30 30 32 30 30 0a 23 64 65 66 69  0x00000200.#defi
6ca0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
6cb0: 53 45 51 55 45 4e 54 49 41 4c 20 20 20 20 20 20  SEQUENTIAL      
6cc0: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 34 30         0x0000040
6cd0: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
6ce0: 5f 49 4f 43 41 50 5f 55 4e 44 45 4c 45 54 41 42  _IOCAP_UNDELETAB
6cf0: 4c 45 5f 57 48 45 4e 5f 4f 50 45 4e 20 20 30 78  LE_WHEN_OPEN  0x
6d00: 30 30 30 30 30 38 30 30 0a 23 64 65 66 69 6e 65  00000800.#define
6d10: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 50 4f   SQLITE_IOCAP_PO
6d20: 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54  WERSAFE_OVERWRIT
6d30: 45 20 20 20 20 30 78 30 30 30 30 31 30 30 30 0a  E    0x00001000.
6d40: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
6d50: 4f 43 41 50 5f 49 4d 4d 55 54 41 42 4c 45 20 20  OCAP_IMMUTABLE  
6d60: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30              0x00
6d70: 30 30 32 30 30 30 0a 0a 2f 2a 0a 2a 2a 20 43 41  002000../*.** CA
6d80: 50 49 33 52 45 46 3a 20 46 69 6c 65 20 4c 6f 63  PI3REF: File Loc
6d90: 6b 69 6e 67 20 4c 65 76 65 6c 73 0a 2a 2a 0a 2a  king Levels.**.*
6da0: 2a 20 53 51 4c 69 74 65 20 75 73 65 73 20 6f 6e  * SQLite uses on
6db0: 65 20 6f 66 20 74 68 65 73 65 20 69 6e 74 65 67  e of these integ
6dc0: 65 72 20 76 61 6c 75 65 73 20 61 73 20 74 68 65  er values as the
6dd0: 20 73 65 63 6f 6e 64 0a 2a 2a 20 61 72 67 75 6d   second.** argum
6de0: 65 6e 74 20 74 6f 20 63 61 6c 6c 73 20 69 74 20  ent to calls it 
6df0: 6d 61 6b 65 73 20 74 6f 20 74 68 65 20 78 4c 6f  makes to the xLo
6e00: 63 6b 28 29 20 61 6e 64 20 78 55 6e 6c 6f 63 6b  ck() and xUnlock
6e10: 28 29 20 6d 65 74 68 6f 64 73 0a 2a 2a 20 6f 66  () methods.** of
6e20: 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f   an [sqlite3_io_
6e30: 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 2e  methods] object.
6e40: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
6e50: 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 20 20 20 20  TE_LOCK_NONE    
6e60: 20 20 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20        0.#define 
6e70: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52  SQLITE_LOCK_SHAR
6e80: 45 44 20 20 20 20 20 20 20 20 31 0a 23 64 65 66  ED        1.#def
6e90: 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  ine SQLITE_LOCK_
6ea0: 52 45 53 45 52 56 45 44 20 20 20 20 20 20 32 0a  RESERVED      2.
6eb0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
6ec0: 4f 43 4b 5f 50 45 4e 44 49 4e 47 20 20 20 20 20  OCK_PENDING     
6ed0: 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    3.#define SQLI
6ee0: 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56  TE_LOCK_EXCLUSIV
6ef0: 45 20 20 20 20 20 34 0a 0a 2f 2a 0a 2a 2a 20 43  E     4../*.** C
6f00: 41 50 49 33 52 45 46 3a 20 53 79 6e 63 68 72 6f  API3REF: Synchro
6f10: 6e 69 7a 61 74 69 6f 6e 20 54 79 70 65 20 46 6c  nization Type Fl
6f20: 61 67 73 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 53  ags.**.** When S
6f30: 51 4c 69 74 65 20 69 6e 76 6f 6b 65 73 20 74 68  QLite invokes th
6f40: 65 20 78 53 79 6e 63 28 29 20 6d 65 74 68 6f 64  e xSync() method
6f50: 20 6f 66 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74   of an.** [sqlit
6f60: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f  e3_io_methods] o
6f70: 62 6a 65 63 74 20 69 74 20 75 73 65 73 20 61 20  bject it uses a 
6f80: 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 6f 66 0a 2a  combination of.*
6f90: 2a 20 74 68 65 73 65 20 69 6e 74 65 67 65 72 20  * these integer 
6fa0: 76 61 6c 75 65 73 20 61 73 20 74 68 65 20 73 65  values as the se
6fb0: 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a  cond argument..*
6fc0: 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 53 51  *.** When the SQ
6fd0: 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e  LITE_SYNC_DATAON
6fe0: 4c 59 20 66 6c 61 67 20 69 73 20 75 73 65 64 2c  LY flag is used,
6ff0: 20 69 74 20 6d 65 61 6e 73 20 74 68 61 74 20 74   it means that t
7000: 68 65 0a 2a 2a 20 73 79 6e 63 20 6f 70 65 72 61  he.** sync opera
7010: 74 69 6f 6e 20 6f 6e 6c 79 20 6e 65 65 64 73 20  tion only needs 
7020: 74 6f 20 66 6c 75 73 68 20 64 61 74 61 20 74 6f  to flush data to
7030: 20 6d 61 73 73 20 73 74 6f 72 61 67 65 2e 20 20   mass storage.  
7040: 49 6e 6f 64 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61  Inode.** informa
7050: 74 69 6f 6e 20 6e 65 65 64 20 6e 6f 74 20 62 65  tion need not be
7060: 20 66 6c 75 73 68 65 64 2e 20 49 66 20 74 68 65   flushed. If the
7070: 20 6c 6f 77 65 72 20 66 6f 75 72 20 62 69 74 73   lower four bits
7080: 20 6f 66 20 74 68 65 20 66 6c 61 67 0a 2a 2a 20   of the flag.** 
7090: 65 71 75 61 6c 20 53 51 4c 49 54 45 5f 53 59 4e  equal SQLITE_SYN
70a0: 43 5f 4e 4f 52 4d 41 4c 2c 20 74 68 61 74 20 6d  C_NORMAL, that m
70b0: 65 61 6e 73 20 74 6f 20 75 73 65 20 6e 6f 72 6d  eans to use norm
70c0: 61 6c 20 66 73 79 6e 63 28 29 20 73 65 6d 61 6e  al fsync() seman
70d0: 74 69 63 73 2e 0a 2a 2a 20 49 66 20 74 68 65 20  tics..** If the 
70e0: 6c 6f 77 65 72 20 66 6f 75 72 20 62 69 74 73 20  lower four bits 
70f0: 65 71 75 61 6c 20 53 51 4c 49 54 45 5f 53 59 4e  equal SQLITE_SYN
7100: 43 5f 46 55 4c 4c 2c 20 74 68 61 74 20 6d 65 61  C_FULL, that mea
7110: 6e 73 0a 2a 2a 20 74 6f 20 75 73 65 20 4d 61 63  ns.** to use Mac
7120: 20 4f 53 20 58 20 73 74 79 6c 65 20 66 75 6c 6c   OS X style full
7130: 73 79 6e 63 20 69 6e 73 74 65 61 64 20 6f 66 20  sync instead of 
7140: 66 73 79 6e 63 28 29 2e 0a 2a 2a 0a 2a 2a 20 44  fsync()..**.** D
7150: 6f 20 6e 6f 74 20 63 6f 6e 66 75 73 65 20 74 68  o not confuse th
7160: 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f  e SQLITE_SYNC_NO
7170: 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49 54 45 5f  RMAL and SQLITE_
7180: 53 59 4e 43 5f 46 55 4c 4c 20 66 6c 61 67 73 0a  SYNC_FULL flags.
7190: 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 50 52 41  ** with the [PRA
71a0: 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 5d  GMA synchronous]
71b0: 3d 4e 4f 52 4d 41 4c 20 61 6e 64 20 5b 50 52 41  =NORMAL and [PRA
71c0: 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 5d  GMA synchronous]
71d0: 3d 46 55 4c 4c 0a 2a 2a 20 73 65 74 74 69 6e 67  =FULL.** setting
71e0: 73 2e 20 20 54 68 65 20 5b 73 79 6e 63 68 72 6f  s.  The [synchro
71f0: 6e 6f 75 73 20 70 72 61 67 6d 61 5d 20 64 65 74  nous pragma] det
7200: 65 72 6d 69 6e 65 73 20 77 68 65 6e 20 63 61 6c  ermines when cal
7210: 6c 73 20 74 6f 20 74 68 65 0a 2a 2a 20 78 53 79  ls to the.** xSy
7220: 6e 63 20 56 46 53 20 6d 65 74 68 6f 64 20 6f 63  nc VFS method oc
7230: 63 75 72 20 61 6e 64 20 61 70 70 6c 69 65 73 20  cur and applies 
7240: 75 6e 69 66 6f 72 6d 6c 79 20 61 63 72 6f 73 73  uniformly across
7250: 20 61 6c 6c 20 70 6c 61 74 66 6f 72 6d 73 2e 0a   all platforms..
7260: 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 53 59  ** The SQLITE_SY
7270: 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51  NC_NORMAL and SQ
7280: 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 66  LITE_SYNC_FULL f
7290: 6c 61 67 73 20 64 65 74 65 72 6d 69 6e 65 20 68  lags determine h
72a0: 6f 77 0a 2a 2a 20 65 6e 65 72 67 65 74 69 63 20  ow.** energetic 
72b0: 6f 72 20 72 69 67 6f 72 6f 75 73 20 6f 72 20 66  or rigorous or f
72c0: 6f 72 63 65 66 75 6c 20 74 68 65 20 73 79 6e 63  orceful the sync
72d0: 20 6f 70 65 72 61 74 69 6f 6e 73 20 61 72 65 20   operations are 
72e0: 61 6e 64 0a 2a 2a 20 6f 6e 6c 79 20 6d 61 6b 65  and.** only make
72f0: 20 61 20 64 69 66 66 65 72 65 6e 63 65 20 6f 6e   a difference on
7300: 20 4d 61 63 20 4f 53 58 20 66 6f 72 20 74 68 65   Mac OSX for the
7310: 20 64 65 66 61 75 6c 74 20 53 51 4c 69 74 65 20   default SQLite 
7320: 63 6f 64 65 2e 0a 2a 2a 20 28 54 68 69 72 64 2d  code..** (Third-
7330: 70 61 72 74 79 20 56 46 53 20 69 6d 70 6c 65 6d  party VFS implem
7340: 65 6e 74 61 74 69 6f 6e 73 20 6d 69 67 68 74 20  entations might 
7350: 61 6c 73 6f 20 6d 61 6b 65 20 74 68 65 20 64 69  also make the di
7360: 73 74 69 6e 63 74 69 6f 6e 0a 2a 2a 20 62 65 74  stinction.** bet
7370: 77 65 65 6e 20 53 51 4c 49 54 45 5f 53 59 4e 43  ween SQLITE_SYNC
7380: 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49  _NORMAL and SQLI
7390: 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 2c 20 62 75  TE_SYNC_FULL, bu
73a0: 74 20 61 6d 6f 6e 67 20 74 68 65 0a 2a 2a 20 6f  t among the.** o
73b0: 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 73  perating systems
73c0: 20 6e 61 74 69 76 65 6c 79 20 73 75 70 70 6f 72   natively suppor
73d0: 74 65 64 20 62 79 20 53 51 4c 69 74 65 2c 20 6f  ted by SQLite, o
73e0: 6e 6c 79 20 4d 61 63 20 4f 53 58 0a 2a 2a 20 63  nly Mac OSX.** c
73f0: 61 72 65 73 20 61 62 6f 75 74 20 74 68 65 20 64  ares about the d
7400: 69 66 66 65 72 65 6e 63 65 2e 29 0a 2a 2f 0a 23  ifference.).*/.#
7410: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 59  define SQLITE_SY
7420: 4e 43 5f 4e 4f 52 4d 41 4c 20 20 20 20 20 20 20  NC_NORMAL       
7430: 20 30 78 30 30 30 30 32 0a 23 64 65 66 69 6e 65   0x00002.#define
7440: 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c   SQLITE_SYNC_FUL
7450: 4c 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30  L          0x000
7460: 30 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  03.#define SQLIT
7470: 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 20  E_SYNC_DATAONLY 
7480: 20 20 20 20 20 30 78 30 30 30 31 30 0a 0a 2f 2a       0x00010../*
7490: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53  .** CAPI3REF: OS
74a0: 20 49 6e 74 65 72 66 61 63 65 20 4f 70 65 6e 20   Interface Open 
74b0: 46 69 6c 65 20 48 61 6e 64 6c 65 0a 2a 2a 0a 2a  File Handle.**.*
74c0: 2a 20 41 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69  * An [sqlite3_fi
74d0: 6c 65 5d 20 6f 62 6a 65 63 74 20 72 65 70 72 65  le] object repre
74e0: 73 65 6e 74 73 20 61 6e 20 6f 70 65 6e 20 66 69  sents an open fi
74f0: 6c 65 20 69 6e 20 74 68 65 20 0a 2a 2a 20 5b 73  le in the .** [s
7500: 71 6c 69 74 65 33 5f 76 66 73 20 7c 20 4f 53 20  qlite3_vfs | OS 
7510: 69 6e 74 65 72 66 61 63 65 20 6c 61 79 65 72 5d  interface layer]
7520: 2e 20 20 49 6e 64 69 76 69 64 75 61 6c 20 4f 53  .  Individual OS
7530: 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 69 6d   interface.** im
7540: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 77 69  plementations wi
7550: 6c 6c 0a 2a 2a 20 77 61 6e 74 20 74 6f 20 73 75  ll.** want to su
7560: 62 63 6c 61 73 73 20 74 68 69 73 20 6f 62 6a 65  bclass this obje
7570: 63 74 20 62 79 20 61 70 70 65 6e 64 69 6e 67 20  ct by appending 
7580: 61 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64  additional field
7590: 73 0a 2a 2a 20 66 6f 72 20 74 68 65 69 72 20 6f  s.** for their o
75a0: 77 6e 20 75 73 65 2e 20 20 54 68 65 20 70 4d 65  wn use.  The pMe
75b0: 74 68 6f 64 73 20 65 6e 74 72 79 20 69 73 20 61  thods entry is a
75c0: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a   pointer to an.*
75d0: 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  * [sqlite3_io_me
75e0: 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 74 68  thods] object th
75f0: 61 74 20 64 65 66 69 6e 65 73 20 6d 65 74 68 6f  at defines metho
7600: 64 73 20 66 6f 72 20 70 65 72 66 6f 72 6d 69 6e  ds for performin
7610: 67 0a 2a 2a 20 49 2f 4f 20 6f 70 65 72 61 74 69  g.** I/O operati
7620: 6f 6e 73 20 6f 6e 20 74 68 65 20 6f 70 65 6e 20  ons on the open 
7630: 66 69 6c 65 2e 0a 2a 2f 0a 74 79 70 65 64 65 66  file..*/.typedef
7640: 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
7650: 66 69 6c 65 20 73 71 6c 69 74 65 33 5f 66 69 6c  file sqlite3_fil
7660: 65 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65  e;.struct sqlite
7670: 33 5f 66 69 6c 65 20 7b 0a 20 20 63 6f 6e 73 74  3_file {.  const
7680: 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
7690: 69 6f 5f 6d 65 74 68 6f 64 73 20 2a 70 4d 65 74  io_methods *pMet
76a0: 68 6f 64 73 3b 20 20 2f 2a 20 4d 65 74 68 6f 64  hods;  /* Method
76b0: 73 20 66 6f 72 20 61 6e 20 6f 70 65 6e 20 66 69  s for an open fi
76c0: 6c 65 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20  le */.};../*.** 
76d0: 43 41 50 49 33 52 45 46 3a 20 4f 53 20 49 6e 74  CAPI3REF: OS Int
76e0: 65 72 66 61 63 65 20 46 69 6c 65 20 56 69 72 74  erface File Virt
76f0: 75 61 6c 20 4d 65 74 68 6f 64 73 20 4f 62 6a 65  ual Methods Obje
7700: 63 74 0a 2a 2a 0a 2a 2a 20 45 76 65 72 79 20 66  ct.**.** Every f
7710: 69 6c 65 20 6f 70 65 6e 65 64 20 62 79 20 74 68  ile opened by th
7720: 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78  e [sqlite3_vfs.x
7730: 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 20 70 6f 70  Open] method pop
7740: 75 6c 61 74 65 73 20 61 6e 0a 2a 2a 20 5b 73 71  ulates an.** [sq
7750: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65  lite3_file] obje
7760: 63 74 20 28 6f 72 2c 20 6d 6f 72 65 20 63 6f 6d  ct (or, more com
7770: 6d 6f 6e 6c 79 2c 20 61 20 73 75 62 63 6c 61 73  monly, a subclas
7780: 73 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c  s of the.** [sql
7790: 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63  ite3_file] objec
77a0: 74 29 20 77 69 74 68 20 61 20 70 6f 69 6e 74 65  t) with a pointe
77b0: 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65  r to an instance
77c0: 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 2e   of this object.
77d0: 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 74 20  .** This object 
77e0: 64 65 66 69 6e 65 73 20 74 68 65 20 6d 65 74 68  defines the meth
77f0: 6f 64 73 20 75 73 65 64 20 74 6f 20 70 65 72 66  ods used to perf
7800: 6f 72 6d 20 76 61 72 69 6f 75 73 20 6f 70 65 72  orm various oper
7810: 61 74 69 6f 6e 73 0a 2a 2a 20 61 67 61 69 6e 73  ations.** agains
7820: 74 20 74 68 65 20 6f 70 65 6e 20 66 69 6c 65 20  t the open file 
7830: 72 65 70 72 65 73 65 6e 74 65 64 20 62 79 20 74  represented by t
7840: 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  he [sqlite3_file
7850: 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20  ] object..**.** 
7860: 49 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  If the [sqlite3_
7870: 76 66 73 2e 78 4f 70 65 6e 5d 20 6d 65 74 68 6f  vfs.xOpen] metho
7880: 64 20 73 65 74 73 20 74 68 65 20 73 71 6c 69 74  d sets the sqlit
7890: 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73  e3_file.pMethods
78a0: 20 65 6c 65 6d 65 6e 74 20 0a 2a 2a 20 74 6f 20   element .** to 
78b0: 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74  a non-NULL point
78c0: 65 72 2c 20 74 68 65 6e 20 74 68 65 20 73 71 6c  er, then the sql
78d0: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 2e  ite3_io_methods.
78e0: 78 43 6c 6f 73 65 20 6d 65 74 68 6f 64 0a 2a 2a  xClose method.**
78f0: 20 6d 61 79 20 62 65 20 69 6e 76 6f 6b 65 64 20   may be invoked 
7900: 65 76 65 6e 20 69 66 20 74 68 65 20 5b 73 71 6c  even if the [sql
7910: 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20  ite3_vfs.xOpen] 
7920: 72 65 70 6f 72 74 65 64 20 74 68 61 74 20 69 74  reported that it
7930: 20 66 61 69 6c 65 64 2e 20 20 54 68 65 0a 2a 2a   failed.  The.**
7940: 20 6f 6e 6c 79 20 77 61 79 20 74 6f 20 70 72 65   only way to pre
7950: 76 65 6e 74 20 61 20 63 61 6c 6c 20 74 6f 20 78  vent a call to x
7960: 43 6c 6f 73 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  Close following 
7970: 61 20 66 61 69 6c 65 64 20 5b 73 71 6c 69 74 65  a failed [sqlite
7980: 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 0a 2a 2a 20  3_vfs.xOpen].** 
7990: 69 73 20 66 6f 72 20 74 68 65 20 5b 73 71 6c 69  is for the [sqli
79a0: 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 74  te3_vfs.xOpen] t
79b0: 6f 20 73 65 74 20 74 68 65 20 73 71 6c 69 74 65  o set the sqlite
79c0: 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20  3_file.pMethods 
79d0: 65 6c 65 6d 65 6e 74 0a 2a 2a 20 74 6f 20 4e 55  element.** to NU
79e0: 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c  LL..**.** The fl
79f0: 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ags argument to 
7a00: 78 53 79 6e 63 20 6d 61 79 20 62 65 20 6f 6e 65  xSync may be one
7a10: 20 6f 66 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43   of [SQLITE_SYNC
7a20: 5f 4e 4f 52 4d 41 4c 5d 20 6f 72 0a 2a 2a 20 5b  _NORMAL] or.** [
7a30: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c  SQLITE_SYNC_FULL
7a40: 5d 2e 20 20 54 68 65 20 66 69 72 73 74 20 63 68  ].  The first ch
7a50: 6f 69 63 65 20 69 73 20 74 68 65 20 6e 6f 72 6d  oice is the norm
7a60: 61 6c 20 66 73 79 6e 63 28 29 2e 0a 2a 2a 20 54  al fsync()..** T
7a70: 68 65 20 73 65 63 6f 6e 64 20 63 68 6f 69 63 65  he second choice
7a80: 20 69 73 20 61 20 4d 61 63 20 4f 53 20 58 20 73   is a Mac OS X s
7a90: 74 79 6c 65 20 66 75 6c 6c 73 79 6e 63 2e 20 20  tyle fullsync.  
7aa0: 54 68 65 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43  The [SQLITE_SYNC
7ab0: 5f 44 41 54 41 4f 4e 4c 59 5d 0a 2a 2a 20 66 6c  _DATAONLY].** fl
7ac0: 61 67 20 6d 61 79 20 62 65 20 4f 52 65 64 20 69  ag may be ORed i
7ad0: 6e 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68  n to indicate th
7ae0: 61 74 20 6f 6e 6c 79 20 74 68 65 20 64 61 74 61  at only the data
7af0: 20 6f 66 20 74 68 65 20 66 69 6c 65 0a 2a 2a 20   of the file.** 
7b00: 61 6e 64 20 6e 6f 74 20 69 74 73 20 69 6e 6f 64  and not its inod
7b10: 65 20 6e 65 65 64 73 20 74 6f 20 62 65 20 73 79  e needs to be sy
7b20: 6e 63 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  nced..**.** The 
7b30: 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20 74  integer values t
7b40: 6f 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20 78 55  o xLock() and xU
7b50: 6e 6c 6f 63 6b 28 29 20 61 72 65 20 6f 6e 65 20  nlock() are one 
7b60: 6f 66 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c  of.** <ul>.** <l
7b70: 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  i> [SQLITE_LOCK_
7b80: 4e 4f 4e 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b  NONE],.** <li> [
7b90: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52  SQLITE_LOCK_SHAR
7ba0: 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  ED],.** <li> [SQ
7bb0: 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56  LITE_LOCK_RESERV
7bc0: 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  ED],.** <li> [SQ
7bd0: 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e  LITE_LOCK_PENDIN
7be0: 47 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 5b  G], or.** <li> [
7bf0: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c  SQLITE_LOCK_EXCL
7c00: 55 53 49 56 45 5d 2e 0a 2a 2a 20 3c 2f 75 6c 3e  USIVE]..** </ul>
7c10: 0a 2a 2a 20 78 4c 6f 63 6b 28 29 20 69 6e 63 72  .** xLock() incr
7c20: 65 61 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e 20  eases the lock. 
7c30: 78 55 6e 6c 6f 63 6b 28 29 20 64 65 63 72 65 61  xUnlock() decrea
7c40: 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e 0a 2a 2a  ses the lock..**
7c50: 20 54 68 65 20 78 43 68 65 63 6b 52 65 73 65 72   The xCheckReser
7c60: 76 65 64 4c 6f 63 6b 28 29 20 6d 65 74 68 6f 64  vedLock() method
7c70: 20 63 68 65 63 6b 73 20 77 68 65 74 68 65 72 20   checks whether 
7c80: 61 6e 79 20 64 61 74 61 62 61 73 65 20 63 6f 6e  any database con
7c90: 6e 65 63 74 69 6f 6e 2c 0a 2a 2a 20 65 69 74 68  nection,.** eith
7ca0: 65 72 20 69 6e 20 74 68 69 73 20 70 72 6f 63 65  er in this proce
7cb0: 73 73 20 6f 72 20 69 6e 20 73 6f 6d 65 20 6f 74  ss or in some ot
7cc0: 68 65 72 20 70 72 6f 63 65 73 73 2c 20 69 73 20  her process, is 
7cd0: 68 6f 6c 64 69 6e 67 20 61 20 52 45 53 45 52 56  holding a RESERV
7ce0: 45 44 2c 0a 2a 2a 20 50 45 4e 44 49 4e 47 2c 20  ED,.** PENDING, 
7cf0: 6f 72 20 45 58 43 4c 55 53 49 56 45 20 6c 6f 63  or EXCLUSIVE loc
7d00: 6b 20 6f 6e 20 74 68 65 20 66 69 6c 65 2e 20 20  k on the file.  
7d10: 49 74 20 72 65 74 75 72 6e 73 20 74 72 75 65 0a  It returns true.
7d20: 2a 2a 20 69 66 20 73 75 63 68 20 61 20 6c 6f 63  ** if such a loc
7d30: 6b 20 65 78 69 73 74 73 20 61 6e 64 20 66 61 6c  k exists and fal
7d40: 73 65 20 6f 74 68 65 72 77 69 73 65 2e 0a 2a 2a  se otherwise..**
7d50: 0a 2a 2a 20 54 68 65 20 78 46 69 6c 65 43 6f 6e  .** The xFileCon
7d60: 74 72 6f 6c 28 29 20 6d 65 74 68 6f 64 20 69 73  trol() method is
7d70: 20 61 20 67 65 6e 65 72 69 63 20 69 6e 74 65 72   a generic inter
7d80: 66 61 63 65 20 74 68 61 74 20 61 6c 6c 6f 77 73  face that allows
7d90: 20 63 75 73 74 6f 6d 0a 2a 2a 20 56 46 53 20 69   custom.** VFS i
7da0: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 74  mplementations t
7db0: 6f 20 64 69 72 65 63 74 6c 79 20 63 6f 6e 74 72  o directly contr
7dc0: 6f 6c 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20  ol an open file 
7dd0: 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71  using the.** [sq
7de0: 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72  lite3_file_contr
7df0: 6f 6c 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e  ol()] interface.
7e00: 20 20 54 68 65 20 73 65 63 6f 6e 64 20 22 6f 70    The second "op
7e10: 22 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 6e  " argument is an
7e20: 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6f 70 63 6f  .** integer opco
7e30: 64 65 2e 20 20 54 68 65 20 74 68 69 72 64 20 61  de.  The third a
7e40: 72 67 75 6d 65 6e 74 20 69 73 20 61 20 67 65 6e  rgument is a gen
7e50: 65 72 69 63 20 70 6f 69 6e 74 65 72 20 69 6e 74  eric pointer int
7e60: 65 6e 64 65 64 20 74 6f 0a 2a 2a 20 70 6f 69 6e  ended to.** poin
7e70: 74 20 74 6f 20 61 20 73 74 72 75 63 74 75 72 65  t to a structure
7e80: 20 74 68 61 74 20 6d 61 79 20 63 6f 6e 74 61 69   that may contai
7e90: 6e 20 61 72 67 75 6d 65 6e 74 73 20 6f 72 20 73  n arguments or s
7ea0: 70 61 63 65 20 69 6e 20 77 68 69 63 68 20 74 6f  pace in which to
7eb0: 0a 2a 2a 20 77 72 69 74 65 20 72 65 74 75 72 6e  .** write return
7ec0: 20 76 61 6c 75 65 73 2e 20 20 50 6f 74 65 6e 74   values.  Potent
7ed0: 69 61 6c 20 75 73 65 73 20 66 6f 72 20 78 46 69  ial uses for xFi
7ee0: 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d 69 67 68  leControl() migh
7ef0: 74 20 62 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  t be.** function
7f00: 73 20 74 6f 20 65 6e 61 62 6c 65 20 62 6c 6f 63  s to enable bloc
7f10: 6b 69 6e 67 20 6c 6f 63 6b 73 20 77 69 74 68 20  king locks with 
7f20: 74 69 6d 65 6f 75 74 73 2c 20 74 6f 20 63 68 61  timeouts, to cha
7f30: 6e 67 65 20 74 68 65 0a 2a 2a 20 6c 6f 63 6b 69  nge the.** locki
7f40: 6e 67 20 73 74 72 61 74 65 67 79 20 28 66 6f 72  ng strategy (for
7f50: 20 65 78 61 6d 70 6c 65 20 74 6f 20 75 73 65 20   example to use 
7f60: 64 6f 74 2d 66 69 6c 65 20 6c 6f 63 6b 73 29 2c  dot-file locks),
7f70: 20 74 6f 20 69 6e 71 75 69 72 65 0a 2a 2a 20 61   to inquire.** a
7f80: 62 6f 75 74 20 74 68 65 20 73 74 61 74 75 73 20  bout the status 
7f90: 6f 66 20 61 20 6c 6f 63 6b 2c 20 6f 72 20 74 6f  of a lock, or to
7fa0: 20 62 72 65 61 6b 20 73 74 61 6c 65 20 6c 6f 63   break stale loc
7fb0: 6b 73 2e 20 20 54 68 65 20 53 51 4c 69 74 65 0a  ks.  The SQLite.
7fc0: 2a 2a 20 63 6f 72 65 20 72 65 73 65 72 76 65 73  ** core reserves
7fd0: 20 61 6c 6c 20 6f 70 63 6f 64 65 73 20 6c 65 73   all opcodes les
7fe0: 73 20 74 68 61 6e 20 31 30 30 20 66 6f 72 20 69  s than 100 for i
7ff0: 74 73 20 6f 77 6e 20 75 73 65 2e 0a 2a 2a 20 41  ts own use..** A
8000: 20 5b 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f   [file control o
8010: 70 63 6f 64 65 73 20 7c 20 6c 69 73 74 20 6f 66  pcodes | list of
8020: 20 6f 70 63 6f 64 65 73 5d 20 6c 65 73 73 20 74   opcodes] less t
8030: 68 61 6e 20 31 30 30 20 69 73 20 61 76 61 69 6c  han 100 is avail
8040: 61 62 6c 65 2e 0a 2a 2a 20 41 70 70 6c 69 63 61  able..** Applica
8050: 74 69 6f 6e 73 20 74 68 61 74 20 64 65 66 69 6e  tions that defin
8060: 65 20 61 20 63 75 73 74 6f 6d 20 78 46 69 6c 65  e a custom xFile
8070: 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 73  Control method s
8080: 68 6f 75 6c 64 20 75 73 65 20 6f 70 63 6f 64 65  hould use opcode
8090: 73 0a 2a 2a 20 67 72 65 61 74 65 72 20 74 68 61  s.** greater tha
80a0: 6e 20 31 30 30 20 74 6f 20 61 76 6f 69 64 20 63  n 100 to avoid c
80b0: 6f 6e 66 6c 69 63 74 73 2e 20 20 56 46 53 20 69  onflicts.  VFS i
80c0: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 73  mplementations s
80d0: 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 75 72 6e 20  hould.** return 
80e0: 5b 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44  [SQLITE_NOTFOUND
80f0: 5d 20 66 6f 72 20 66 69 6c 65 20 63 6f 6e 74 72  ] for file contr
8100: 6f 6c 20 6f 70 63 6f 64 65 73 20 74 68 61 74 20  ol opcodes that 
8110: 74 68 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a 20 72  they do not.** r
8120: 65 63 6f 67 6e 69 7a 65 2e 0a 2a 2a 0a 2a 2a 20  ecognize..**.** 
8130: 54 68 65 20 78 53 65 63 74 6f 72 53 69 7a 65 28  The xSectorSize(
8140: 29 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73  ) method returns
8150: 20 74 68 65 20 73 65 63 74 6f 72 20 73 69 7a 65   the sector size
8160: 20 6f 66 20 74 68 65 0a 2a 2a 20 64 65 76 69 63   of the.** devic
8170: 65 20 74 68 61 74 20 75 6e 64 65 72 6c 69 65 73  e that underlies
8180: 20 74 68 65 20 66 69 6c 65 2e 20 20 54 68 65 20   the file.  The 
8190: 73 65 63 74 6f 72 20 73 69 7a 65 20 69 73 20 74  sector size is t
81a0: 68 65 0a 2a 2a 20 6d 69 6e 69 6d 75 6d 20 77 72  he.** minimum wr
81b0: 69 74 65 20 74 68 61 74 20 63 61 6e 20 62 65 20  ite that can be 
81c0: 70 65 72 66 6f 72 6d 65 64 20 77 69 74 68 6f 75  performed withou
81d0: 74 20 64 69 73 74 75 72 62 69 6e 67 0a 2a 2a 20  t disturbing.** 
81e0: 6f 74 68 65 72 20 62 79 74 65 73 20 69 6e 20 74  other bytes in t
81f0: 68 65 20 66 69 6c 65 2e 20 20 54 68 65 20 78 44  he file.  The xD
8200: 65 76 69 63 65 43 68 61 72 61 63 74 65 72 69 73  eviceCharacteris
8210: 74 69 63 73 28 29 0a 2a 2a 20 6d 65 74 68 6f 64  tics().** method
8220: 20 72 65 74 75 72 6e 73 20 61 20 62 69 74 20 76   returns a bit v
8230: 65 63 74 6f 72 20 64 65 73 63 72 69 62 69 6e 67  ector describing
8240: 20 62 65 68 61 76 69 6f 72 73 20 6f 66 20 74 68   behaviors of th
8250: 65 0a 2a 2a 20 75 6e 64 65 72 6c 79 69 6e 67 20  e.** underlying 
8260: 64 65 76 69 63 65 3a 0a 2a 2a 0a 2a 2a 20 3c 75  device:.**.** <u
8270: 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  l>.** <li> [SQLI
8280: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 5d  TE_IOCAP_ATOMIC]
8290: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
82a0: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 35 31 32  _IOCAP_ATOMIC512
82b0: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ].** <li> [SQLIT
82c0: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 4b  E_IOCAP_ATOMIC1K
82d0: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ].** <li> [SQLIT
82e0: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 32 4b  E_IOCAP_ATOMIC2K
82f0: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ].** <li> [SQLIT
8300: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 34 4b  E_IOCAP_ATOMIC4K
8310: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ].** <li> [SQLIT
8320: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 38 4b  E_IOCAP_ATOMIC8K
8330: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ].** <li> [SQLIT
8340: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 36  E_IOCAP_ATOMIC16
8350: 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  K].** <li> [SQLI
8360: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 33  TE_IOCAP_ATOMIC3
8370: 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  2K].** <li> [SQL
8380: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
8390: 36 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  64K].** <li> [SQ
83a0: 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f  LITE_IOCAP_SAFE_
83b0: 41 50 50 45 4e 44 5d 0a 2a 2a 20 3c 6c 69 3e 20  APPEND].** <li> 
83c0: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45  [SQLITE_IOCAP_SE
83d0: 51 55 45 4e 54 49 41 4c 5d 0a 2a 2a 20 3c 2f 75  QUENTIAL].** </u
83e0: 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c  l>.**.** The SQL
83f0: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
8400: 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20   property means 
8410: 74 68 61 74 20 61 6c 6c 20 77 72 69 74 65 73 20  that all writes 
8420: 6f 66 0a 2a 2a 20 61 6e 79 20 73 69 7a 65 20 61  of.** any size a
8430: 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20  re atomic.  The 
8440: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
8450: 4d 49 43 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a  MICnnn values.**
8460: 20 6d 65 61 6e 20 74 68 61 74 20 77 72 69 74 65   mean that write
8470: 73 20 6f 66 20 62 6c 6f 63 6b 73 20 74 68 61 74  s of blocks that
8480: 20 61 72 65 20 6e 6e 6e 20 62 79 74 65 73 20 69   are nnn bytes i
8490: 6e 20 73 69 7a 65 20 61 6e 64 0a 2a 2a 20 61 72  n size and.** ar
84a0: 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20  e aligned to an 
84b0: 61 64 64 72 65 73 73 20 77 68 69 63 68 20 69 73  address which is
84c0: 20 61 6e 20 69 6e 74 65 67 65 72 20 6d 75 6c 74   an integer mult
84d0: 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61  iple of.** nnn a
84e0: 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20  re atomic.  The 
84f0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46  SQLITE_IOCAP_SAF
8500: 45 5f 41 50 50 45 4e 44 20 76 61 6c 75 65 20 6d  E_APPEND value m
8510: 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20 77 68 65  eans.** that whe
8520: 6e 20 64 61 74 61 20 69 73 20 61 70 70 65 6e 64  n data is append
8530: 65 64 20 74 6f 20 61 20 66 69 6c 65 2c 20 74 68  ed to a file, th
8540: 65 20 64 61 74 61 20 69 73 20 61 70 70 65 6e 64  e data is append
8550: 65 64 0a 2a 2a 20 66 69 72 73 74 20 74 68 65 6e  ed.** first then
8560: 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65   the size of the
8570: 20 66 69 6c 65 20 69 73 20 65 78 74 65 6e 64 65   file is extende
8580: 64 2c 20 6e 65 76 65 72 20 74 68 65 20 6f 74 68  d, never the oth
8590: 65 72 0a 2a 2a 20 77 61 79 20 61 72 6f 75 6e 64  er.** way around
85a0: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f  .  The SQLITE_IO
85b0: 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 70  CAP_SEQUENTIAL p
85c0: 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68  roperty means th
85d0: 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f  at.** informatio
85e0: 6e 20 69 73 20 77 72 69 74 74 65 6e 20 74 6f 20  n is written to 
85f0: 64 69 73 6b 20 69 6e 20 74 68 65 20 73 61 6d 65  disk in the same
8600: 20 6f 72 64 65 72 20 61 73 20 63 61 6c 6c 73 0a   order as calls.
8610: 2a 2a 20 74 6f 20 78 57 72 69 74 65 28 29 2e 0a  ** to xWrite()..
8620: 2a 2a 0a 2a 2a 20 49 66 20 78 52 65 61 64 28 29  **.** If xRead()
8630: 20 72 65 74 75 72 6e 73 20 53 51 4c 49 54 45 5f   returns SQLITE_
8640: 49 4f 45 52 52 5f 53 48 4f 52 54 5f 52 45 41 44  IOERR_SHORT_READ
8650: 20 69 74 20 6d 75 73 74 20 61 6c 73 6f 20 66 69   it must also fi
8660: 6c 6c 0a 2a 2a 20 69 6e 20 74 68 65 20 75 6e 72  ll.** in the unr
8670: 65 61 64 20 70 6f 72 74 69 6f 6e 73 20 6f 66 20  ead portions of 
8680: 74 68 65 20 62 75 66 66 65 72 20 77 69 74 68 20  the buffer with 
8690: 7a 65 72 6f 73 2e 20 20 41 20 56 46 53 20 74 68  zeros.  A VFS th
86a0: 61 74 0a 2a 2a 20 66 61 69 6c 73 20 74 6f 20 7a  at.** fails to z
86b0: 65 72 6f 2d 66 69 6c 6c 20 73 68 6f 72 74 20 72  ero-fill short r
86c0: 65 61 64 73 20 6d 69 67 68 74 20 73 65 65 6d 20  eads might seem 
86d0: 74 6f 20 77 6f 72 6b 2e 20 20 48 6f 77 65 76 65  to work.  Howeve
86e0: 72 2c 0a 2a 2a 20 66 61 69 6c 75 72 65 20 74 6f  r,.** failure to
86f0: 20 7a 65 72 6f 2d 66 69 6c 6c 20 73 68 6f 72 74   zero-fill short
8700: 20 72 65 61 64 73 20 77 69 6c 6c 20 65 76 65 6e   reads will even
8710: 74 75 61 6c 6c 79 20 6c 65 61 64 20 74 6f 0a 2a  tually lead to.*
8720: 2a 20 64 61 74 61 62 61 73 65 20 63 6f 72 72 75  * database corru
8730: 70 74 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 65 64 65  ption..*/.typede
8740: 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  f struct sqlite3
8750: 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 73 71 6c 69  _io_methods sqli
8760: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 3b 0a  te3_io_methods;.
8770: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69  struct sqlite3_i
8780: 6f 5f 6d 65 74 68 6f 64 73 20 7b 0a 20 20 69 6e  o_methods {.  in
8790: 74 20 69 56 65 72 73 69 6f 6e 3b 0a 20 20 69 6e  t iVersion;.  in
87a0: 74 20 28 2a 78 43 6c 6f 73 65 29 28 73 71 6c 69  t (*xClose)(sqli
87b0: 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e  te3_file*);.  in
87c0: 74 20 28 2a 78 52 65 61 64 29 28 73 71 6c 69 74  t (*xRead)(sqlit
87d0: 65 33 5f 66 69 6c 65 2a 2c 20 76 6f 69 64 2a 2c  e3_file*, void*,
87e0: 20 69 6e 74 20 69 41 6d 74 2c 20 73 71 6c 69 74   int iAmt, sqlit
87f0: 65 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 29 3b  e3_int64 iOfst);
8800: 0a 20 20 69 6e 74 20 28 2a 78 57 72 69 74 65 29  .  int (*xWrite)
8810: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
8820: 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74  const void*, int
8830: 20 69 41 6d 74 2c 20 73 71 6c 69 74 65 33 5f 69   iAmt, sqlite3_i
8840: 6e 74 36 34 20 69 4f 66 73 74 29 3b 0a 20 20 69  nt64 iOfst);.  i
8850: 6e 74 20 28 2a 78 54 72 75 6e 63 61 74 65 29 28  nt (*xTruncate)(
8860: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73  sqlite3_file*, s
8870: 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 69 7a  qlite3_int64 siz
8880: 65 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 79 6e  e);.  int (*xSyn
8890: 63 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  c)(sqlite3_file*
88a0: 2c 20 69 6e 74 20 66 6c 61 67 73 29 3b 0a 20 20  , int flags);.  
88b0: 69 6e 74 20 28 2a 78 46 69 6c 65 53 69 7a 65 29  int (*xFileSize)
88c0: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
88d0: 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a 70  sqlite3_int64 *p
88e0: 53 69 7a 65 29 3b 0a 20 20 69 6e 74 20 28 2a 78  Size);.  int (*x
88f0: 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69  Lock)(sqlite3_fi
8900: 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74  le*, int);.  int
8910: 20 28 2a 78 55 6e 6c 6f 63 6b 29 28 73 71 6c 69   (*xUnlock)(sqli
8920: 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 29 3b  te3_file*, int);
8930: 0a 20 20 69 6e 74 20 28 2a 78 43 68 65 63 6b 52  .  int (*xCheckR
8940: 65 73 65 72 76 65 64 4c 6f 63 6b 29 28 73 71 6c  eservedLock)(sql
8950: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20  ite3_file*, int 
8960: 2a 70 52 65 73 4f 75 74 29 3b 0a 20 20 69 6e 74  *pResOut);.  int
8970: 20 28 2a 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 29   (*xFileControl)
8980: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
8990: 69 6e 74 20 6f 70 2c 20 76 6f 69 64 20 2a 70 41  int op, void *pA
89a0: 72 67 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 65  rg);.  int (*xSe
89b0: 63 74 6f 72 53 69 7a 65 29 28 73 71 6c 69 74 65  ctorSize)(sqlite
89c0: 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20  3_file*);.  int 
89d0: 28 2a 78 44 65 76 69 63 65 43 68 61 72 61 63 74  (*xDeviceCharact
89e0: 65 72 69 73 74 69 63 73 29 28 73 71 6c 69 74 65  eristics)(sqlite
89f0: 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 2f 2a 20 4d  3_file*);.  /* M
8a00: 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65  ethods above are
8a10: 20 76 61 6c 69 64 20 66 6f 72 20 76 65 72 73 69   valid for versi
8a20: 6f 6e 20 31 20 2a 2f 0a 20 20 69 6e 74 20 28 2a  on 1 */.  int (*
8a30: 78 53 68 6d 4d 61 70 29 28 73 71 6c 69 74 65 33  xShmMap)(sqlite3
8a40: 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 69 50 67 2c  _file*, int iPg,
8a50: 20 69 6e 74 20 70 67 73 7a 2c 20 69 6e 74 2c 20   int pgsz, int, 
8a60: 76 6f 69 64 20 76 6f 6c 61 74 69 6c 65 2a 2a 29  void volatile**)
8a70: 3b 0a 20 20 69 6e 74 20 28 2a 78 53 68 6d 4c 6f  ;.  int (*xShmLo
8a80: 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ck)(sqlite3_file
8a90: 2a 2c 20 69 6e 74 20 6f 66 66 73 65 74 2c 20 69  *, int offset, i
8aa0: 6e 74 20 6e 2c 20 69 6e 74 20 66 6c 61 67 73 29  nt n, int flags)
8ab0: 3b 0a 20 20 76 6f 69 64 20 28 2a 78 53 68 6d 42  ;.  void (*xShmB
8ac0: 61 72 72 69 65 72 29 28 73 71 6c 69 74 65 33 5f  arrier)(sqlite3_
8ad0: 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a  file*);.  int (*
8ae0: 78 53 68 6d 55 6e 6d 61 70 29 28 73 71 6c 69 74  xShmUnmap)(sqlit
8af0: 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 64 65  e3_file*, int de
8b00: 6c 65 74 65 46 6c 61 67 29 3b 0a 20 20 2f 2a 20  leteFlag);.  /* 
8b10: 4d 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72  Methods above ar
8b20: 65 20 76 61 6c 69 64 20 66 6f 72 20 76 65 72 73  e valid for vers
8b30: 69 6f 6e 20 32 20 2a 2f 0a 20 20 69 6e 74 20 28  ion 2 */.  int (
8b40: 2a 78 46 65 74 63 68 29 28 73 71 6c 69 74 65 33  *xFetch)(sqlite3
8b50: 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f  _file*, sqlite3_
8b60: 69 6e 74 36 34 20 69 4f 66 73 74 2c 20 69 6e 74  int64 iOfst, int
8b70: 20 69 41 6d 74 2c 20 76 6f 69 64 20 2a 2a 70 70   iAmt, void **pp
8b80: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 55 6e 66 65  );.  int (*xUnfe
8b90: 74 63 68 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  tch)(sqlite3_fil
8ba0: 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  e*, sqlite3_int6
8bb0: 34 20 69 4f 66 73 74 2c 20 76 6f 69 64 20 2a 70  4 iOfst, void *p
8bc0: 29 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20  );.  /* Methods 
8bd0: 61 62 6f 76 65 20 61 72 65 20 76 61 6c 69 64 20  above are valid 
8be0: 66 6f 72 20 76 65 72 73 69 6f 6e 20 33 20 2a 2f  for version 3 */
8bf0: 0a 20 20 2f 2a 20 41 64 64 69 74 69 6f 6e 61 6c  .  /* Additional
8c00: 20 6d 65 74 68 6f 64 73 20 6d 61 79 20 62 65 20   methods may be 
8c10: 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20  added in future 
8c20: 72 65 6c 65 61 73 65 73 20 2a 2f 0a 7d 3b 0a 0a  releases */.};..
8c30: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
8c40: 53 74 61 6e 64 61 72 64 20 46 69 6c 65 20 43 6f  Standard File Co
8c50: 6e 74 72 6f 6c 20 4f 70 63 6f 64 65 73 0a 2a 2a  ntrol Opcodes.**
8c60: 20 4b 45 59 57 4f 52 44 53 3a 20 7b 66 69 6c 65   KEYWORDS: {file
8c70: 20 63 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64 65 73   control opcodes
8c80: 7d 20 7b 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20  } {file control 
8c90: 6f 70 63 6f 64 65 7d 0a 2a 2a 0a 2a 2a 20 54 68  opcode}.**.** Th
8ca0: 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73  ese integer cons
8cb0: 74 61 6e 74 73 20 61 72 65 20 6f 70 63 6f 64 65  tants are opcode
8cc0: 73 20 66 6f 72 20 74 68 65 20 78 46 69 6c 65 43  s for the xFileC
8cd0: 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 0a 2a 2a  ontrol method.**
8ce0: 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
8cf0: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a  _io_methods] obj
8d00: 65 63 74 20 61 6e 64 20 66 6f 72 20 74 68 65 20  ect and for the 
8d10: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f  [sqlite3_file_co
8d20: 6e 74 72 6f 6c 28 29 5d 0a 2a 2a 20 69 6e 74 65  ntrol()].** inte
8d30: 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 3c 75 6c  rface..**.** <ul
8d40: 3e 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  >.** <li>[[SQLIT
8d50: 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54  E_FCNTL_LOCKSTAT
8d60: 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49  E]].** The [SQLI
8d70: 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41  TE_FCNTL_LOCKSTA
8d80: 54 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73  TE] opcode is us
8d90: 65 64 20 66 6f 72 20 64 65 62 75 67 67 69 6e 67  ed for debugging
8da0: 2e 20 20 54 68 69 73 0a 2a 2a 20 6f 70 63 6f 64  .  This.** opcod
8db0: 65 20 63 61 75 73 65 73 20 74 68 65 20 78 46 69  e causes the xFi
8dc0: 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64  leControl method
8dd0: 20 74 6f 20 77 72 69 74 65 20 74 68 65 20 63 75   to write the cu
8de0: 72 72 65 6e 74 20 73 74 61 74 65 20 6f 66 0a 2a  rrent state of.*
8df0: 2a 20 74 68 65 20 6c 6f 63 6b 20 28 6f 6e 65 20  * the lock (one 
8e00: 6f 66 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  of [SQLITE_LOCK_
8e10: 4e 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c  NONE], [SQLITE_L
8e20: 4f 43 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a 20  OCK_SHARED],.** 
8e30: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53  [SQLITE_LOCK_RES
8e40: 45 52 56 45 44 5d 2c 20 5b 53 51 4c 49 54 45 5f  ERVED], [SQLITE_
8e50: 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f  LOCK_PENDING], o
8e60: 72 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45  r [SQLITE_LOCK_E
8e70: 58 43 4c 55 53 49 56 45 5d 29 0a 2a 2a 20 69 6e  XCLUSIVE]).** in
8e80: 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 74 68  to an integer th
8e90: 61 74 20 74 68 65 20 70 41 72 67 20 61 72 67 75  at the pArg argu
8ea0: 6d 65 6e 74 20 70 6f 69 6e 74 73 20 74 6f 2e 20  ment points to. 
8eb0: 54 68 69 73 20 63 61 70 61 62 69 6c 69 74 79 0a  This capability.
8ec0: 2a 2a 20 69 73 20 75 73 65 64 20 64 75 72 69 6e  ** is used durin
8ed0: 67 20 74 65 73 74 69 6e 67 20 61 6e 64 20 69 73  g testing and is
8ee0: 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20   only available 
8ef0: 77 68 65 6e 20 74 68 65 20 53 51 4c 49 54 45 5f  when the SQLITE_
8f00: 54 45 53 54 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d  TEST.** compile-
8f10: 74 69 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20 75  time option is u
8f20: 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  sed..**.** <li>[
8f30: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49  [SQLITE_FCNTL_SI
8f40: 5a 45 5f 48 49 4e 54 5d 5d 0a 2a 2a 20 54 68 65  ZE_HINT]].** The
8f50: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53   [SQLITE_FCNTL_S
8f60: 49 5a 45 5f 48 49 4e 54 5d 20 6f 70 63 6f 64 65  IZE_HINT] opcode
8f70: 20 69 73 20 75 73 65 64 20 62 79 20 53 51 4c 69   is used by SQLi
8f80: 74 65 20 74 6f 20 67 69 76 65 20 74 68 65 20 56  te to give the V
8f90: 46 53 0a 2a 2a 20 6c 61 79 65 72 20 61 20 68 69  FS.** layer a hi
8fa0: 6e 74 20 6f 66 20 68 6f 77 20 6c 61 72 67 65 20  nt of how large 
8fb0: 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
8fc0: 65 20 77 69 6c 6c 20 67 72 6f 77 20 74 6f 20 62  e will grow to b
8fd0: 65 20 64 75 72 69 6e 67 20 74 68 65 0a 2a 2a 20  e during the.** 
8fe0: 63 75 72 72 65 6e 74 20 74 72 61 6e 73 61 63 74  current transact
8ff0: 69 6f 6e 2e 20 20 54 68 69 73 20 68 69 6e 74 20  ion.  This hint 
9000: 69 73 20 6e 6f 74 20 67 75 61 72 61 6e 74 65 65  is not guarantee
9010: 64 20 74 6f 20 62 65 20 61 63 63 75 72 61 74 65  d to be accurate
9020: 20 62 75 74 20 69 74 0a 2a 2a 20 69 73 20 6f 66   but it.** is of
9030: 74 65 6e 20 63 6c 6f 73 65 2e 20 20 54 68 65 20  ten close.  The 
9040: 75 6e 64 65 72 6c 79 69 6e 67 20 56 46 53 20 6d  underlying VFS m
9050: 69 67 68 74 20 63 68 6f 6f 73 65 20 74 6f 20 70  ight choose to p
9060: 72 65 61 6c 6c 6f 63 61 74 65 20 64 61 74 61 62  reallocate datab
9070: 61 73 65 0a 2a 2a 20 66 69 6c 65 20 73 70 61 63  ase.** file spac
9080: 65 20 62 61 73 65 64 20 6f 6e 20 74 68 69 73 20  e based on this 
9090: 68 69 6e 74 20 69 6e 20 6f 72 64 65 72 20 74 6f  hint in order to
90a0: 20 68 65 6c 70 20 77 72 69 74 65 73 20 74 6f 20   help writes to 
90b0: 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  the database.** 
90c0: 66 69 6c 65 20 72 75 6e 20 66 61 73 74 65 72 2e  file run faster.
90d0: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
90e0: 49 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f  ITE_FCNTL_CHUNK_
90f0: 53 49 5a 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53  SIZE]].** The [S
9100: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e  QLITE_FCNTL_CHUN
9110: 4b 5f 53 49 5a 45 5d 20 6f 70 63 6f 64 65 20 69  K_SIZE] opcode i
9120: 73 20 75 73 65 64 20 74 6f 20 72 65 71 75 65 73  s used to reques
9130: 74 20 74 68 61 74 20 74 68 65 20 56 46 53 0a 2a  t that the VFS.*
9140: 2a 20 65 78 74 65 6e 64 73 20 61 6e 64 20 74 72  * extends and tr
9150: 75 6e 63 61 74 65 73 20 74 68 65 20 64 61 74 61  uncates the data
9160: 62 61 73 65 20 66 69 6c 65 20 69 6e 20 63 68 75  base file in chu
9170: 6e 6b 73 20 6f 66 20 61 20 73 69 7a 65 20 73 70  nks of a size sp
9180: 65 63 69 66 69 65 64 0a 2a 2a 20 62 79 20 74 68  ecified.** by th
9190: 65 20 75 73 65 72 2e 20 54 68 65 20 66 6f 75 72  e user. The four
91a0: 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b  th argument to [
91b0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e  sqlite3_file_con
91c0: 74 72 6f 6c 28 29 5d 20 73 68 6f 75 6c 64 20 0a  trol()] should .
91d0: 2a 2a 20 70 6f 69 6e 74 20 74 6f 20 61 6e 20 69  ** point to an i
91e0: 6e 74 65 67 65 72 20 28 74 79 70 65 20 69 6e 74  nteger (type int
91f0: 29 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65  ) containing the
9200: 20 6e 65 77 20 63 68 75 6e 6b 2d 73 69 7a 65 20   new chunk-size 
9210: 74 6f 20 75 73 65 0a 2a 2a 20 66 6f 72 20 74 68  to use.** for th
9220: 65 20 6e 6f 6d 69 6e 61 74 65 64 20 64 61 74 61  e nominated data
9230: 62 61 73 65 2e 20 41 6c 6c 6f 63 61 74 69 6e 67  base. Allocating
9240: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 73   database file s
9250: 70 61 63 65 20 69 6e 20 6c 61 72 67 65 0a 2a 2a  pace in large.**
9260: 20 63 68 75 6e 6b 73 20 28 73 61 79 20 31 4d 42   chunks (say 1MB
9270: 20 61 74 20 61 20 74 69 6d 65 29 2c 20 6d 61 79   at a time), may
9280: 20 72 65 64 75 63 65 20 66 69 6c 65 2d 73 79 73   reduce file-sys
9290: 74 65 6d 20 66 72 61 67 6d 65 6e 74 61 74 69 6f  tem fragmentatio
92a0: 6e 20 61 6e 64 0a 2a 2a 20 69 6d 70 72 6f 76 65  n and.** improve
92b0: 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 6f 6e 20   performance on 
92c0: 73 6f 6d 65 20 73 79 73 74 65 6d 73 2e 0a 2a 2a  some systems..**
92d0: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
92e0: 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e  _FCNTL_FILE_POIN
92f0: 54 45 52 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51  TER]].** The [SQ
9300: 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f  LITE_FCNTL_FILE_
9310: 50 4f 49 4e 54 45 52 5d 20 6f 70 63 6f 64 65 20  POINTER] opcode 
9320: 69 73 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69  is used to obtai
9330: 6e 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74  n a pointer.** t
9340: 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66  o the [sqlite3_f
9350: 69 6c 65 5d 20 6f 62 6a 65 63 74 20 61 73 73 6f  ile] object asso
9360: 63 69 61 74 65 64 20 77 69 74 68 20 61 20 70 61  ciated with a pa
9370: 72 74 69 63 75 6c 61 72 20 64 61 74 61 62 61 73  rticular databas
9380: 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e  e.** connection.
9390: 20 20 53 65 65 20 61 6c 73 6f 20 5b 53 51 4c 49    See also [SQLI
93a0: 54 45 5f 46 43 4e 54 4c 5f 4a 4f 55 52 4e 41 4c  TE_FCNTL_JOURNAL
93b0: 5f 50 4f 49 4e 54 45 52 5d 2e 0a 2a 2a 0a 2a 2a  _POINTER]..**.**
93c0: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
93d0: 4e 54 4c 5f 4a 4f 55 52 4e 41 4c 5f 50 4f 49 4e  NTL_JOURNAL_POIN
93e0: 54 45 52 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51  TER]].** The [SQ
93f0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 4a 4f 55 52 4e  LITE_FCNTL_JOURN
9400: 41 4c 5f 50 4f 49 4e 54 45 52 5d 20 6f 70 63 6f  AL_POINTER] opco
9410: 64 65 20 69 73 20 75 73 65 64 20 74 6f 20 6f 62  de is used to ob
9420: 74 61 69 6e 20 61 20 70 6f 69 6e 74 65 72 0a 2a  tain a pointer.*
9430: 2a 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  * to the [sqlite
9440: 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 61  3_file] object a
9450: 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74  ssociated with t
9460: 68 65 20 6a 6f 75 72 6e 61 6c 20 66 69 6c 65 20  he journal file 
9470: 28 65 69 74 68 65 72 0a 2a 2a 20 74 68 65 20 5b  (either.** the [
9480: 72 6f 6c 6c 62 61 63 6b 20 6a 6f 75 72 6e 61 6c  rollback journal
9490: 5d 20 6f 72 20 74 68 65 20 5b 77 72 69 74 65 2d  ] or the [write-
94a0: 61 68 65 61 64 20 6c 6f 67 5d 29 20 66 6f 72 20  ahead log]) for 
94b0: 61 20 70 61 72 74 69 63 75 6c 61 72 20 64 61 74  a particular dat
94c0: 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74  abase.** connect
94d0: 69 6f 6e 2e 20 20 53 65 65 20 61 6c 73 6f 20 5b  ion.  See also [
94e0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49 4c  SQLITE_FCNTL_FIL
94f0: 45 5f 50 4f 49 4e 54 45 52 5d 2e 0a 2a 2a 0a 2a  E_POINTER]..**.*
9500: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
9510: 43 4e 54 4c 5f 53 59 4e 43 5f 4f 4d 49 54 54 45  CNTL_SYNC_OMITTE
9520: 44 5d 5d 0a 2a 2a 20 4e 6f 20 6c 6f 6e 67 65 72  D]].** No longer
9530: 20 69 6e 20 75 73 65 2e 0a 2a 2a 0a 2a 2a 20 3c   in use..**.** <
9540: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
9550: 4c 5f 53 59 4e 43 5d 5d 0a 2a 2a 20 54 68 65 20  L_SYNC]].** The 
9560: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59  [SQLITE_FCNTL_SY
9570: 4e 43 5d 20 6f 70 63 6f 64 65 20 69 73 20 67 65  NC] opcode is ge
9580: 6e 65 72 61 74 65 64 20 69 6e 74 65 72 6e 61 6c  nerated internal
9590: 6c 79 20 62 79 20 53 51 4c 69 74 65 20 61 6e 64  ly by SQLite and
95a0: 0a 2a 2a 20 73 65 6e 74 20 74 6f 20 74 68 65 20  .** sent to the 
95b0: 56 46 53 20 69 6d 6d 65 64 69 61 74 65 6c 79 20  VFS immediately 
95c0: 62 65 66 6f 72 65 20 74 68 65 20 78 53 79 6e 63  before the xSync
95d0: 20 6d 65 74 68 6f 64 20 69 73 20 69 6e 76 6f 6b   method is invok
95e0: 65 64 20 6f 6e 20 61 0a 2a 2a 20 64 61 74 61 62  ed on a.** datab
95f0: 61 73 65 20 66 69 6c 65 20 64 65 73 63 72 69 70  ase file descrip
9600: 74 6f 72 2e 20 4f 72 2c 20 69 66 20 74 68 65 20  tor. Or, if the 
9610: 78 53 79 6e 63 20 6d 65 74 68 6f 64 20 69 73 20  xSync method is 
9620: 6e 6f 74 20 69 6e 76 6f 6b 65 64 20 0a 2a 2a 20  not invoked .** 
9630: 62 65 63 61 75 73 65 20 74 68 65 20 75 73 65 72  because the user
9640: 20 68 61 73 20 63 6f 6e 66 69 67 75 72 65 64 20   has configured 
9650: 53 51 4c 69 74 65 20 77 69 74 68 20 0a 2a 2a 20  SQLite with .** 
9660: 5b 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e  [PRAGMA synchron
9670: 6f 75 73 20 7c 20 50 52 41 47 4d 41 20 73 79 6e  ous | PRAGMA syn
9680: 63 68 72 6f 6e 6f 75 73 3d 4f 46 46 5d 20 69 74  chronous=OFF] it
9690: 20 69 73 20 69 6e 76 6f 6b 65 64 20 69 6e 20 70   is invoked in p
96a0: 6c 61 63 65 20 0a 2a 2a 20 6f 66 20 74 68 65 20  lace .** of the 
96b0: 78 53 79 6e 63 20 6d 65 74 68 6f 64 2e 20 49 6e  xSync method. In
96c0: 20 6d 6f 73 74 20 63 61 73 65 73 2c 20 74 68 65   most cases, the
96d0: 20 70 6f 69 6e 74 65 72 20 61 72 67 75 6d 65 6e   pointer argumen
96e0: 74 20 70 61 73 73 65 64 20 77 69 74 68 0a 2a 2a  t passed with.**
96f0: 20 74 68 69 73 20 66 69 6c 65 2d 63 6f 6e 74 72   this file-contr
9700: 6f 6c 20 69 73 20 4e 55 4c 4c 2e 20 48 6f 77 65  ol is NULL. Howe
9710: 76 65 72 2c 20 69 66 20 74 68 65 20 64 61 74 61  ver, if the data
9720: 62 61 73 65 20 66 69 6c 65 20 69 73 20 62 65 69  base file is bei
9730: 6e 67 20 73 79 6e 63 65 64 0a 2a 2a 20 61 73 20  ng synced.** as 
9740: 70 61 72 74 20 6f 66 20 61 20 6d 75 6c 74 69 2d  part of a multi-
9750: 64 61 74 61 62 61 73 65 20 63 6f 6d 6d 69 74 2c  database commit,
9760: 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 70 6f   the argument po
9770: 69 6e 74 73 20 74 6f 20 61 20 6e 75 6c 2d 74 65  ints to a nul-te
9780: 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74 72 69  rminated.** stri
9790: 6e 67 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68  ng containing th
97a0: 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 73 20 6d  e transactions m
97b0: 61 73 74 65 72 2d 6a 6f 75 72 6e 61 6c 20 66 69  aster-journal fi
97c0: 6c 65 20 6e 61 6d 65 2e 20 56 46 53 65 73 20 74  le name. VFSes t
97d0: 68 61 74 20 0a 2a 2a 20 64 6f 20 6e 6f 74 20 6e  hat .** do not n
97e0: 65 65 64 20 74 68 69 73 20 73 69 67 6e 61 6c 20  eed this signal 
97f0: 73 68 6f 75 6c 64 20 73 69 6c 65 6e 74 6c 79 20  should silently 
9800: 69 67 6e 6f 72 65 20 74 68 69 73 20 6f 70 63 6f  ignore this opco
9810: 64 65 2e 20 41 70 70 6c 69 63 61 74 69 6f 6e 73  de. Applications
9820: 20 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e 6f 74 20   .** should not 
9830: 63 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 66 69  call [sqlite3_fi
9840: 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 77 69  le_control()] wi
9850: 74 68 20 74 68 69 73 20 6f 70 63 6f 64 65 20 61  th this opcode a
9860: 73 20 64 6f 69 6e 67 20 73 6f 20 6d 61 79 20 0a  s doing so may .
9870: 2a 2a 20 64 69 73 72 75 70 74 20 74 68 65 20 6f  ** disrupt the o
9880: 70 65 72 61 74 69 6f 6e 20 6f 66 20 74 68 65 20  peration of the 
9890: 73 70 65 63 69 61 6c 69 7a 65 64 20 56 46 53 65  specialized VFSe
98a0: 73 20 74 68 61 74 20 64 6f 20 72 65 71 75 69 72  s that do requir
98b0: 65 20 69 74 2e 20 20 0a 2a 2a 0a 2a 2a 20 3c 6c  e it.  .**.** <l
98c0: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
98d0: 5f 43 4f 4d 4d 49 54 5f 50 48 41 53 45 54 57 4f  _COMMIT_PHASETWO
98e0: 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54  ]].** The [SQLIT
98f0: 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 50  E_FCNTL_COMMIT_P
9900: 48 41 53 45 54 57 4f 5d 20 6f 70 63 6f 64 65 20  HASETWO] opcode 
9910: 69 73 20 67 65 6e 65 72 61 74 65 64 20 69 6e 74  is generated int
9920: 65 72 6e 61 6c 6c 79 20 62 79 20 53 51 4c 69 74  ernally by SQLit
9930: 65 0a 2a 2a 20 61 6e 64 20 73 65 6e 74 20 74 6f  e.** and sent to
9940: 20 74 68 65 20 56 46 53 20 61 66 74 65 72 20 61   the VFS after a
9950: 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 68 61 73   transaction has
9960: 20 62 65 65 6e 20 63 6f 6d 6d 69 74 74 65 64 20   been committed 
9970: 69 6d 6d 65 64 69 61 74 65 6c 79 0a 2a 2a 20 62  immediately.** b
9980: 75 74 20 62 65 66 6f 72 65 20 74 68 65 20 64 61  ut before the da
9990: 74 61 62 61 73 65 20 69 73 20 75 6e 6c 6f 63 6b  tabase is unlock
99a0: 65 64 2e 20 56 46 53 65 73 20 74 68 61 74 20 64  ed. VFSes that d
99b0: 6f 20 6e 6f 74 20 6e 65 65 64 20 74 68 69 73 20  o not need this 
99c0: 73 69 67 6e 61 6c 0a 2a 2a 20 73 68 6f 75 6c 64  signal.** should
99d0: 20 73 69 6c 65 6e 74 6c 79 20 69 67 6e 6f 72 65   silently ignore
99e0: 20 74 68 69 73 20 6f 70 63 6f 64 65 2e 20 41 70   this opcode. Ap
99f0: 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c  plications shoul
9a00: 64 20 6e 6f 74 20 63 61 6c 6c 0a 2a 2a 20 5b 73  d not call.** [s
9a10: 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74  qlite3_file_cont
9a20: 72 6f 6c 28 29 5d 20 77 69 74 68 20 74 68 69 73  rol()] with this
9a30: 20 6f 70 63 6f 64 65 20 61 73 20 64 6f 69 6e 67   opcode as doing
9a40: 20 73 6f 20 6d 61 79 20 64 69 73 72 75 70 74 20   so may disrupt 
9a50: 74 68 65 20 0a 2a 2a 20 6f 70 65 72 61 74 69 6f  the .** operatio
9a60: 6e 20 6f 66 20 74 68 65 20 73 70 65 63 69 61 6c  n of the special
9a70: 69 7a 65 64 20 56 46 53 65 73 20 74 68 61 74 20  ized VFSes that 
9a80: 64 6f 20 72 65 71 75 69 72 65 20 69 74 2e 20 20  do require it.  
9a90: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
9aa0: 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f  ITE_FCNTL_WIN32_
9ab0: 41 56 5f 52 45 54 52 59 5d 5d 0a 2a 2a 20 5e 54  AV_RETRY]].** ^T
9ac0: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
9ad0: 5f 57 49 4e 33 32 5f 41 56 5f 52 45 54 52 59 5d  _WIN32_AV_RETRY]
9ae0: 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20   opcode is used 
9af0: 74 6f 20 63 6f 6e 66 69 67 75 72 65 20 61 75 74  to configure aut
9b00: 6f 6d 61 74 69 63 0a 2a 2a 20 72 65 74 72 79 20  omatic.** retry 
9b10: 63 6f 75 6e 74 73 20 61 6e 64 20 69 6e 74 65 72  counts and inter
9b20: 76 61 6c 73 20 66 6f 72 20 63 65 72 74 61 69 6e  vals for certain
9b30: 20 64 69 73 6b 20 49 2f 4f 20 6f 70 65 72 61 74   disk I/O operat
9b40: 69 6f 6e 73 20 66 6f 72 20 74 68 65 0a 2a 2a 20  ions for the.** 
9b50: 77 69 6e 64 6f 77 73 20 5b 56 46 53 5d 20 69 6e  windows [VFS] in
9b60: 20 6f 72 64 65 72 20 74 6f 20 70 72 6f 76 69 64   order to provid
9b70: 65 20 72 6f 62 75 73 74 6e 65 73 73 20 69 6e 20  e robustness in 
9b80: 74 68 65 20 70 72 65 73 65 6e 63 65 20 6f 66 0a  the presence of.
9b90: 2a 2a 20 61 6e 74 69 2d 76 69 72 75 73 20 70 72  ** anti-virus pr
9ba0: 6f 67 72 61 6d 73 2e 20 20 42 79 20 64 65 66 61  ograms.  By defa
9bb0: 75 6c 74 2c 20 74 68 65 20 77 69 6e 64 6f 77 73  ult, the windows
9bc0: 20 56 46 53 20 77 69 6c 6c 20 72 65 74 72 79 20   VFS will retry 
9bd0: 66 69 6c 65 20 72 65 61 64 2c 0a 2a 2a 20 66 69  file read,.** fi
9be0: 6c 65 20 77 72 69 74 65 2c 20 61 6e 64 20 66 69  le write, and fi
9bf0: 6c 65 20 64 65 6c 65 74 65 20 6f 70 65 72 61 74  le delete operat
9c00: 69 6f 6e 73 20 75 70 20 74 6f 20 31 30 20 74 69  ions up to 10 ti
9c10: 6d 65 73 2c 20 77 69 74 68 20 61 20 64 65 6c 61  mes, with a dela
9c20: 79 0a 2a 2a 20 6f 66 20 32 35 20 6d 69 6c 6c 69  y.** of 25 milli
9c30: 73 65 63 6f 6e 64 73 20 62 65 66 6f 72 65 20 74  seconds before t
9c40: 68 65 20 66 69 72 73 74 20 72 65 74 72 79 20 61  he first retry a
9c50: 6e 64 20 77 69 74 68 20 74 68 65 20 64 65 6c 61  nd with the dela
9c60: 79 20 69 6e 63 72 65 61 73 69 6e 67 0a 2a 2a 20  y increasing.** 
9c70: 62 79 20 61 6e 20 61 64 64 69 74 69 6f 6e 61 6c  by an additional
9c80: 20 32 35 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73   25 milliseconds
9c90: 20 77 69 74 68 20 65 61 63 68 20 73 75 62 73 65   with each subse
9ca0: 71 75 65 6e 74 20 72 65 74 72 79 2e 20 20 54 68  quent retry.  Th
9cb0: 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 20 61 6c 6c  is.** opcode all
9cc0: 6f 77 73 20 74 68 65 73 65 20 74 77 6f 20 76 61  ows these two va
9cd0: 6c 75 65 73 20 28 31 30 20 72 65 74 72 69 65 73  lues (10 retries
9ce0: 20 61 6e 64 20 32 35 20 6d 69 6c 6c 69 73 65 63   and 25 millisec
9cf0: 6f 6e 64 73 20 6f 66 20 64 65 6c 61 79 29 0a 2a  onds of delay).*
9d00: 2a 20 74 6f 20 62 65 20 61 64 6a 75 73 74 65 64  * to be adjusted
9d10: 2e 20 20 54 68 65 20 76 61 6c 75 65 73 20 61 72  .  The values ar
9d20: 65 20 63 68 61 6e 67 65 64 20 66 6f 72 20 61 6c  e changed for al
9d30: 6c 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  l database conne
9d40: 63 74 69 6f 6e 73 0a 2a 2a 20 77 69 74 68 69 6e  ctions.** within
9d50: 20 74 68 65 20 73 61 6d 65 20 70 72 6f 63 65 73   the same proces
9d60: 73 2e 20 20 54 68 65 20 61 72 67 75 6d 65 6e 74  s.  The argument
9d70: 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
9d80: 20 61 6e 20 61 72 72 61 79 20 6f 66 20 74 77 6f   an array of two
9d90: 0a 2a 2a 20 69 6e 74 65 67 65 72 73 20 77 68 65  .** integers whe
9da0: 72 65 20 74 68 65 20 66 69 72 73 74 20 69 6e 74  re the first int
9db0: 65 67 65 72 20 69 20 74 68 65 20 6e 65 77 20 72  eger i the new r
9dc0: 65 74 72 79 20 63 6f 75 6e 74 20 61 6e 64 20 74  etry count and t
9dd0: 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 69 6e 74  he second.** int
9de0: 65 67 65 72 20 69 73 20 74 68 65 20 64 65 6c 61  eger is the dela
9df0: 79 2e 20 20 49 66 20 65 69 74 68 65 72 20 69 6e  y.  If either in
9e00: 74 65 67 65 72 20 69 73 20 6e 65 67 61 74 69 76  teger is negativ
9e10: 65 2c 20 74 68 65 6e 20 74 68 65 20 73 65 74 74  e, then the sett
9e20: 69 6e 67 0a 2a 2a 20 69 73 20 6e 6f 74 20 63 68  ing.** is not ch
9e30: 61 6e 67 65 64 20 62 75 74 20 69 6e 73 74 65 61  anged but instea
9e40: 64 20 74 68 65 20 70 72 69 6f 72 20 76 61 6c 75  d the prior valu
9e50: 65 20 6f 66 20 74 68 61 74 20 73 65 74 74 69 6e  e of that settin
9e60: 67 20 69 73 20 77 72 69 74 74 65 6e 0a 2a 2a 20  g is written.** 
9e70: 69 6e 74 6f 20 74 68 65 20 61 72 72 61 79 20 65  into the array e
9e80: 6e 74 72 79 2c 20 61 6c 6c 6f 77 69 6e 67 20 74  ntry, allowing t
9e90: 68 65 20 63 75 72 72 65 6e 74 20 72 65 74 72 79  he current retry
9ea0: 20 73 65 74 74 69 6e 67 73 20 74 6f 20 62 65 0a   settings to be.
9eb0: 2a 2a 20 69 6e 74 65 72 72 6f 67 61 74 65 64 2e  ** interrogated.
9ec0: 20 20 54 68 65 20 7a 44 62 4e 61 6d 65 20 70 61    The zDbName pa
9ed0: 72 61 6d 65 74 65 72 20 69 73 20 69 67 6e 6f 72  rameter is ignor
9ee0: 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  ed..**.** <li>[[
9ef0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 45 52  SQLITE_FCNTL_PER
9f00: 53 49 53 54 5f 57 41 4c 5d 5d 0a 2a 2a 20 5e 54  SIST_WAL]].** ^T
9f10: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
9f20: 5f 50 45 52 53 49 53 54 5f 57 41 4c 5d 20 6f 70  _PERSIST_WAL] op
9f30: 63 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f 20  code is used to 
9f40: 73 65 74 20 6f 72 20 71 75 65 72 79 20 74 68 65  set or query the
9f50: 0a 2a 2a 20 70 65 72 73 69 73 74 65 6e 74 20 5b  .** persistent [
9f60: 57 41 4c 20 7c 20 57 72 69 74 65 20 41 68 65 61  WAL | Write Ahea
9f70: 64 20 4c 6f 67 5d 20 73 65 74 74 69 6e 67 2e 20  d Log] setting. 
9f80: 20 42 79 20 64 65 66 61 75 6c 74 2c 20 74 68 65   By default, the
9f90: 20 61 75 78 69 6c 69 61 72 79 0a 2a 2a 20 77 72   auxiliary.** wr
9fa0: 69 74 65 20 61 68 65 61 64 20 6c 6f 67 20 61 6e  ite ahead log an
9fb0: 64 20 73 68 61 72 65 64 20 6d 65 6d 6f 72 79 20  d shared memory 
9fc0: 66 69 6c 65 73 20 75 73 65 64 20 66 6f 72 20 74  files used for t
9fd0: 72 61 6e 73 61 63 74 69 6f 6e 20 63 6f 6e 74 72  ransaction contr
9fe0: 6f 6c 0a 2a 2a 20 61 72 65 20 61 75 74 6f 6d 61  ol.** are automa
9ff0: 74 69 63 61 6c 6c 79 20 64 65 6c 65 74 65 64 20  tically deleted 
a000: 77 68 65 6e 20 74 68 65 20 6c 61 74 65 73 74 20  when the latest 
a010: 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 74 68  connection to th
a020: 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6c  e database.** cl
a030: 6f 73 65 73 2e 20 20 53 65 74 74 69 6e 67 20 70  oses.  Setting p
a040: 65 72 73 69 73 74 65 6e 74 20 57 41 4c 20 6d 6f  ersistent WAL mo
a050: 64 65 20 63 61 75 73 65 73 20 74 68 6f 73 65 20  de causes those 
a060: 66 69 6c 65 73 20 74 6f 20 70 65 72 73 69 73 74  files to persist
a070: 20 61 66 74 65 72 0a 2a 2a 20 63 6c 6f 73 65 2e   after.** close.
a080: 20 20 50 65 72 73 69 73 74 69 6e 67 20 74 68 65    Persisting the
a090: 20 66 69 6c 65 73 20 69 73 20 75 73 65 66 75 6c   files is useful
a0a0: 20 77 68 65 6e 20 6f 74 68 65 72 20 70 72 6f 63   when other proc
a0b0: 65 73 73 65 73 20 74 68 61 74 20 64 6f 20 6e 6f  esses that do no
a0c0: 74 0a 2a 2a 20 68 61 76 65 20 77 72 69 74 65 20  t.** have write 
a0d0: 70 65 72 6d 69 73 73 69 6f 6e 20 6f 6e 20 74 68  permission on th
a0e0: 65 20 64 69 72 65 63 74 6f 72 79 20 63 6f 6e 74  e directory cont
a0f0: 61 69 6e 69 6e 67 20 74 68 65 20 64 61 74 61 62  aining the datab
a100: 61 73 65 20 66 69 6c 65 20 77 61 6e 74 0a 2a 2a  ase file want.**
a110: 20 74 6f 20 72 65 61 64 20 74 68 65 20 64 61 74   to read the dat
a120: 61 62 61 73 65 20 66 69 6c 65 2c 20 61 73 20 74  abase file, as t
a130: 68 65 20 57 41 4c 20 61 6e 64 20 73 68 61 72 65  he WAL and share
a140: 64 20 6d 65 6d 6f 72 79 20 66 69 6c 65 73 20 6d  d memory files m
a150: 75 73 74 20 65 78 69 73 74 0a 2a 2a 20 69 6e 20  ust exist.** in 
a160: 6f 72 64 65 72 20 66 6f 72 20 74 68 65 20 64 61  order for the da
a170: 74 61 62 61 73 65 20 74 6f 20 62 65 20 72 65 61  tabase to be rea
a180: 64 61 62 6c 65 2e 20 20 54 68 65 20 66 6f 75 72  dable.  The four
a190: 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a  th parameter to.
a1a0: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  ** [sqlite3_file
a1b0: 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 66 6f 72 20  _control()] for 
a1c0: 74 68 69 73 20 6f 70 63 6f 64 65 20 73 68 6f 75  this opcode shou
a1d0: 6c 64 20 62 65 20 61 20 70 6f 69 6e 74 65 72 20  ld be a pointer 
a1e0: 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 2e 0a 2a  to an integer..*
a1f0: 2a 20 54 68 61 74 20 69 6e 74 65 67 65 72 20 69  * That integer i
a200: 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65 20 70  s 0 to disable p
a210: 65 72 73 69 73 74 65 6e 74 20 57 41 4c 20 6d 6f  ersistent WAL mo
a220: 64 65 20 6f 72 20 31 20 74 6f 20 65 6e 61 62 6c  de or 1 to enabl
a230: 65 20 70 65 72 73 69 73 74 65 6e 74 0a 2a 2a 20  e persistent.** 
a240: 57 41 4c 20 6d 6f 64 65 2e 20 20 49 66 20 74 68  WAL mode.  If th
a250: 65 20 69 6e 74 65 67 65 72 20 69 73 20 2d 31 2c  e integer is -1,
a260: 20 74 68 65 6e 20 69 74 20 69 73 20 6f 76 65 72   then it is over
a270: 77 72 69 74 74 65 6e 20 77 69 74 68 20 74 68 65  written with the
a280: 20 63 75 72 72 65 6e 74 0a 2a 2a 20 57 41 4c 20   current.** WAL 
a290: 70 65 72 73 69 73 74 65 6e 63 65 20 73 65 74 74  persistence sett
a2a0: 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  ing..**.** <li>[
a2b0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 4f  [SQLITE_FCNTL_PO
a2c0: 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54  WERSAFE_OVERWRIT
a2d0: 45 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c  E]].** ^The [SQL
a2e0: 49 54 45 5f 46 43 4e 54 4c 5f 50 4f 57 45 52 53  ITE_FCNTL_POWERS
a2f0: 41 46 45 5f 4f 56 45 52 57 52 49 54 45 5d 20 6f  AFE_OVERWRITE] o
a300: 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f  pcode is used to
a310: 20 73 65 74 20 6f 72 20 71 75 65 72 79 20 74 68   set or query th
a320: 65 0a 2a 2a 20 70 65 72 73 69 73 74 65 6e 74 20  e.** persistent 
a330: 22 70 6f 77 65 72 73 61 66 65 2d 6f 76 65 72 77  "powersafe-overw
a340: 72 69 74 65 22 20 6f 72 20 22 50 53 4f 57 22 20  rite" or "PSOW" 
a350: 73 65 74 74 69 6e 67 2e 20 20 54 68 65 20 50 53  setting.  The PS
a360: 4f 57 20 73 65 74 74 69 6e 67 0a 2a 2a 20 64 65  OW setting.** de
a370: 74 65 72 6d 69 6e 65 73 20 74 68 65 20 5b 53 51  termines the [SQ
a380: 4c 49 54 45 5f 49 4f 43 41 50 5f 50 4f 57 45 52  LITE_IOCAP_POWER
a390: 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45 5d 20  SAFE_OVERWRITE] 
a3a0: 62 69 74 20 6f 66 20 74 68 65 0a 2a 2a 20 78 44  bit of the.** xD
a3b0: 65 76 69 63 65 43 68 61 72 61 63 74 65 72 69 73  eviceCharacteris
a3c0: 74 69 63 73 20 6d 65 74 68 6f 64 73 2e 20 54 68  tics methods. Th
a3d0: 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
a3e0: 65 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  er to.** [sqlite
a3f0: 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29  3_file_control()
a400: 5d 20 66 6f 72 20 74 68 69 73 20 6f 70 63 6f 64  ] for this opcod
a410: 65 20 73 68 6f 75 6c 64 20 62 65 20 61 20 70 6f  e should be a po
a420: 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65  inter to an inte
a430: 67 65 72 2e 0a 2a 2a 20 54 68 61 74 20 69 6e 74  ger..** That int
a440: 65 67 65 72 20 69 73 20 30 20 74 6f 20 64 69 73  eger is 0 to dis
a450: 61 62 6c 65 20 7a 65 72 6f 2d 64 61 6d 61 67 65  able zero-damage
a460: 20 6d 6f 64 65 20 6f 72 20 31 20 74 6f 20 65 6e   mode or 1 to en
a470: 61 62 6c 65 20 7a 65 72 6f 2d 64 61 6d 61 67 65  able zero-damage
a480: 0a 2a 2a 20 6d 6f 64 65 2e 20 20 49 66 20 74 68  .** mode.  If th
a490: 65 20 69 6e 74 65 67 65 72 20 69 73 20 2d 31 2c  e integer is -1,
a4a0: 20 74 68 65 6e 20 69 74 20 69 73 20 6f 76 65 72   then it is over
a4b0: 77 72 69 74 74 65 6e 20 77 69 74 68 20 74 68 65  written with the
a4c0: 20 63 75 72 72 65 6e 74 0a 2a 2a 20 7a 65 72 6f   current.** zero
a4d0: 2d 64 61 6d 61 67 65 20 6d 6f 64 65 20 73 65 74  -damage mode set
a4e0: 74 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  ting..**.** <li>
a4f0: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f  [[SQLITE_FCNTL_O
a500: 56 45 52 57 52 49 54 45 5d 5d 0a 2a 2a 20 5e 54  VERWRITE]].** ^T
a510: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
a520: 5f 4f 56 45 52 57 52 49 54 45 5d 20 6f 70 63 6f  _OVERWRITE] opco
a530: 64 65 20 69 73 20 69 6e 76 6f 6b 65 64 20 62 79  de is invoked by
a540: 20 53 51 4c 69 74 65 20 61 66 74 65 72 20 6f 70   SQLite after op
a550: 65 6e 69 6e 67 0a 2a 2a 20 61 20 77 72 69 74 65  ening.** a write
a560: 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 74 6f 20   transaction to 
a570: 69 6e 64 69 63 61 74 65 20 74 68 61 74 2c 20 75  indicate that, u
a580: 6e 6c 65 73 73 20 69 74 20 69 73 20 72 6f 6c 6c  nless it is roll
a590: 65 64 20 62 61 63 6b 20 66 6f 72 20 73 6f 6d 65  ed back for some
a5a0: 0a 2a 2a 20 72 65 61 73 6f 6e 2c 20 74 68 65 20  .** reason, the 
a5b0: 65 6e 74 69 72 65 20 64 61 74 61 62 61 73 65 20  entire database 
a5c0: 66 69 6c 65 20 77 69 6c 6c 20 62 65 20 6f 76 65  file will be ove
a5d0: 72 77 72 69 74 74 65 6e 20 62 79 20 74 68 65 20  rwritten by the 
a5e0: 63 75 72 72 65 6e 74 20 0a 2a 2a 20 74 72 61 6e  current .** tran
a5f0: 73 61 63 74 69 6f 6e 2e 20 54 68 69 73 20 69 73  saction. This is
a600: 20 75 73 65 64 20 62 79 20 56 41 43 55 55 4d 20   used by VACUUM 
a610: 6f 70 65 72 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a  operations..**.*
a620: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
a630: 43 4e 54 4c 5f 56 46 53 4e 41 4d 45 5d 5d 0a 2a  CNTL_VFSNAME]].*
a640: 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  * ^The [SQLITE_F
a650: 43 4e 54 4c 5f 56 46 53 4e 41 4d 45 5d 20 6f 70  CNTL_VFSNAME] op
a660: 63 6f 64 65 20 63 61 6e 20 62 65 20 75 73 65 64  code can be used
a670: 20 74 6f 20 6f 62 74 61 69 6e 20 74 68 65 20 6e   to obtain the n
a680: 61 6d 65 73 20 6f 66 0a 2a 2a 20 61 6c 6c 20 5b  ames of.** all [
a690: 56 46 53 65 73 5d 20 69 6e 20 74 68 65 20 56 46  VFSes] in the VF
a6a0: 53 20 73 74 61 63 6b 2e 20 20 54 68 65 20 6e 61  S stack.  The na
a6b0: 6d 65 73 20 61 72 65 20 6f 66 20 61 6c 6c 20 56  mes are of all V
a6c0: 46 53 20 73 68 69 6d 73 20 61 6e 64 20 74 68 65  FS shims and the
a6d0: 0a 2a 2a 20 66 69 6e 61 6c 20 62 6f 74 74 6f 6d  .** final bottom
a6e0: 2d 6c 65 76 65 6c 20 56 46 53 20 61 72 65 20 77  -level VFS are w
a6f0: 72 69 74 74 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f  ritten into memo
a700: 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  ry obtained from
a710: 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61   .** [sqlite3_ma
a720: 6c 6c 6f 63 28 29 5d 20 61 6e 64 20 74 68 65 20  lloc()] and the 
a730: 72 65 73 75 6c 74 20 69 73 20 73 74 6f 72 65 64  result is stored
a740: 20 69 6e 20 74 68 65 20 63 68 61 72 2a 20 76 61   in the char* va
a750: 72 69 61 62 6c 65 0a 2a 2a 20 74 68 61 74 20 74  riable.** that t
a760: 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
a770: 74 65 72 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f  ter of [sqlite3_
a780: 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20  file_control()] 
a790: 70 6f 69 6e 74 73 20 74 6f 2e 0a 2a 2a 20 54 68  points to..** Th
a7a0: 65 20 63 61 6c 6c 65 72 20 69 73 20 72 65 73 70  e caller is resp
a7b0: 6f 6e 73 69 62 6c 65 20 66 6f 72 20 66 72 65 65  onsible for free
a7c0: 69 6e 67 20 74 68 65 20 6d 65 6d 6f 72 79 20 77  ing the memory w
a7d0: 68 65 6e 20 64 6f 6e 65 2e 20 20 41 73 20 77 69  hen done.  As wi
a7e0: 74 68 0a 2a 2a 20 61 6c 6c 20 66 69 6c 65 2d 63  th.** all file-c
a7f0: 6f 6e 74 72 6f 6c 20 61 63 74 69 6f 6e 73 2c 20  ontrol actions, 
a800: 74 68 65 72 65 20 69 73 20 6e 6f 20 67 75 61 72  there is no guar
a810: 61 6e 74 65 65 20 74 68 61 74 20 74 68 69 73 20  antee that this 
a820: 77 69 6c 6c 20 61 63 74 75 61 6c 6c 79 0a 2a 2a  will actually.**
a830: 20 64 6f 20 61 6e 79 74 68 69 6e 67 2e 20 20 43   do anything.  C
a840: 61 6c 6c 65 72 73 20 73 68 6f 75 6c 64 20 69 6e  allers should in
a850: 69 74 69 61 6c 69 7a 65 20 74 68 65 20 63 68 61  itialize the cha
a860: 72 2a 20 76 61 72 69 61 62 6c 65 20 74 6f 20 61  r* variable to a
a870: 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72   NULL.** pointer
a880: 20 69 6e 20 63 61 73 65 20 74 68 69 73 20 66 69   in case this fi
a890: 6c 65 2d 63 6f 6e 74 72 6f 6c 20 69 73 20 6e 6f  le-control is no
a8a0: 74 20 69 6d 70 6c 65 6d 65 6e 74 65 64 2e 20 20  t implemented.  
a8b0: 54 68 69 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f  This file-contro
a8c0: 6c 0a 2a 2a 20 69 73 20 69 6e 74 65 6e 64 65 64  l.** is intended
a8d0: 20 66 6f 72 20 64 69 61 67 6e 6f 73 74 69 63 20   for diagnostic 
a8e0: 75 73 65 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20  use only..**.** 
a8f0: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e  <li>[[SQLITE_FCN
a900: 54 4c 5f 56 46 53 5f 50 4f 49 4e 54 45 52 5d 5d  TL_VFS_POINTER]]
a910: 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45  .** ^The [SQLITE
a920: 5f 46 43 4e 54 4c 5f 56 46 53 5f 50 4f 49 4e 54  _FCNTL_VFS_POINT
a930: 45 52 5d 20 6f 70 63 6f 64 65 20 66 69 6e 64 73  ER] opcode finds
a940: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   a pointer to th
a950: 65 20 74 6f 70 2d 6c 65 76 65 6c 0a 2a 2a 20 5b  e top-level.** [
a960: 56 46 53 65 73 5d 20 63 75 72 72 65 6e 74 6c 79  VFSes] currently
a970: 20 69 6e 20 75 73 65 2e 20 20 5e 28 54 68 65 20   in use.  ^(The 
a980: 61 72 67 75 6d 65 6e 74 20 58 20 69 6e 0a 2a 2a  argument X in.**
a990: 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f   sqlite3_file_co
a9a0: 6e 74 72 6f 6c 28 64 62 2c 53 51 4c 49 54 45 5f  ntrol(db,SQLITE_
a9b0: 46 43 4e 54 4c 5f 56 46 53 5f 50 4f 49 4e 54 45  FCNTL_VFS_POINTE
a9c0: 52 2c 58 29 20 6d 75 73 74 20 62 65 0a 2a 2a 20  R,X) must be.** 
a9d0: 6f 66 20 74 79 70 65 20 22 5b 73 71 6c 69 74 65  of type "[sqlite
a9e0: 33 5f 76 66 73 5d 20 2a 2a 22 2e 20 20 54 68 69  3_vfs] **".  Thi
a9f0: 73 20 6f 70 63 6f 64 65 73 20 77 69 6c 6c 20 73  s opcodes will s
aa00: 65 74 20 2a 58 0a 2a 2a 20 74 6f 20 61 20 70 6f  et *X.** to a po
aa10: 69 6e 74 65 72 20 74 6f 20 74 68 65 20 74 6f 70  inter to the top
aa20: 2d 6c 65 76 65 6c 20 56 46 53 2e 29 5e 0a 2a 2a  -level VFS.)^.**
aa30: 20 5e 57 68 65 6e 20 74 68 65 72 65 20 61 72 65   ^When there are
aa40: 20 6d 75 6c 74 69 70 6c 65 20 56 46 53 20 73 68   multiple VFS sh
aa50: 69 6d 73 20 69 6e 20 74 68 65 20 73 74 61 63 6b  ims in the stack
aa60: 2c 20 74 68 69 73 20 6f 70 63 6f 64 65 20 66 69  , this opcode fi
aa70: 6e 64 73 20 74 68 65 0a 2a 2a 20 75 70 70 65 72  nds the.** upper
aa80: 2d 6d 6f 73 74 20 73 68 69 6d 20 6f 6e 6c 79 2e  -most shim only.
aa90: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
aaa0: 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41  ITE_FCNTL_PRAGMA
aab0: 5d 5d 0a 2a 2a 20 5e 57 68 65 6e 65 76 65 72 20  ]].** ^Whenever 
aac0: 61 20 5b 50 52 41 47 4d 41 5d 20 73 74 61 74 65  a [PRAGMA] state
aad0: 6d 65 6e 74 20 69 73 20 70 61 72 73 65 64 2c 20  ment is parsed, 
aae0: 61 6e 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  an [SQLITE_FCNTL
aaf0: 5f 50 52 41 47 4d 41 5d 20 0a 2a 2a 20 66 69 6c  _PRAGMA] .** fil
ab00: 65 20 63 6f 6e 74 72 6f 6c 20 69 73 20 73 65 6e  e control is sen
ab10: 74 20 74 6f 20 74 68 65 20 6f 70 65 6e 20 5b 73  t to the open [s
ab20: 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a  qlite3_file] obj
ab30: 65 63 74 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e  ect correspondin
ab40: 67 0a 2a 2a 20 74 6f 20 74 68 65 20 64 61 74 61  g.** to the data
ab50: 62 61 73 65 20 66 69 6c 65 20 74 6f 20 77 68 69  base file to whi
ab60: 63 68 20 74 68 65 20 70 72 61 67 6d 61 20 73 74  ch the pragma st
ab70: 61 74 65 6d 65 6e 74 20 72 65 66 65 72 73 2e 20  atement refers. 
ab80: 5e 54 68 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a  ^The argument.**
ab90: 20 74 6f 20 74 68 65 20 5b 53 51 4c 49 54 45 5f   to the [SQLITE_
aba0: 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69  FCNTL_PRAGMA] fi
abb0: 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73 20 61 6e  le control is an
abc0: 20 61 72 72 61 79 20 6f 66 0a 2a 2a 20 70 6f 69   array of.** poi
abd0: 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73  nters to strings
abe0: 20 28 63 68 61 72 2a 2a 29 20 69 6e 20 77 68 69   (char**) in whi
abf0: 63 68 20 74 68 65 20 73 65 63 6f 6e 64 20 65 6c  ch the second el
ac00: 65 6d 65 6e 74 20 6f 66 20 74 68 65 20 61 72 72  ement of the arr
ac10: 61 79 0a 2a 2a 20 69 73 20 74 68 65 20 6e 61 6d  ay.** is the nam
ac20: 65 20 6f 66 20 74 68 65 20 70 72 61 67 6d 61 20  e of the pragma 
ac30: 61 6e 64 20 74 68 65 20 74 68 69 72 64 20 65 6c  and the third el
ac40: 65 6d 65 6e 74 20 69 73 20 74 68 65 20 61 72 67  ement is the arg
ac50: 75 6d 65 6e 74 20 74 6f 20 74 68 65 0a 2a 2a 20  ument to the.** 
ac60: 70 72 61 67 6d 61 20 6f 72 20 4e 55 4c 4c 20 69  pragma or NULL i
ac70: 66 20 74 68 65 20 70 72 61 67 6d 61 20 68 61 73  f the pragma has
ac80: 20 6e 6f 20 61 72 67 75 6d 65 6e 74 2e 20 20 5e   no argument.  ^
ac90: 54 68 65 20 68 61 6e 64 6c 65 72 20 66 6f 72 20  The handler for 
aca0: 61 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43  an.** [SQLITE_FC
acb0: 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65  NTL_PRAGMA] file
acc0: 20 63 6f 6e 74 72 6f 6c 20 63 61 6e 20 6f 70 74   control can opt
acd0: 69 6f 6e 61 6c 6c 79 20 6d 61 6b 65 20 74 68 65  ionally make the
ace0: 20 66 69 72 73 74 20 65 6c 65 6d 65 6e 74 0a 2a   first element.*
acf0: 2a 20 6f 66 20 74 68 65 20 63 68 61 72 2a 2a 20  * of the char** 
ad00: 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e 74 20 74  argument point t
ad10: 6f 20 61 20 73 74 72 69 6e 67 20 6f 62 74 61 69  o a string obtai
ad20: 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  ned from [sqlite
ad30: 33 5f 6d 70 72 69 6e 74 66 28 29 5d 0a 2a 2a 20  3_mprintf()].** 
ad40: 6f 72 20 74 68 65 20 65 71 75 69 76 61 6c 65 6e  or the equivalen
ad50: 74 20 61 6e 64 20 74 68 61 74 20 73 74 72 69 6e  t and that strin
ad60: 67 20 77 69 6c 6c 20 62 65 63 6f 6d 65 20 74 68  g will become th
ad70: 65 20 72 65 73 75 6c 74 20 6f 66 20 74 68 65 20  e result of the 
ad80: 70 72 61 67 6d 61 20 6f 72 0a 2a 2a 20 74 68 65  pragma or.** the
ad90: 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 69   error message i
ada0: 66 20 74 68 65 20 70 72 61 67 6d 61 20 66 61 69  f the pragma fai
adb0: 6c 73 2e 20 5e 49 66 20 74 68 65 0a 2a 2a 20 5b  ls. ^If the.** [
adc0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41  SQLITE_FCNTL_PRA
add0: 47 4d 41 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f  GMA] file contro
ade0: 6c 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54  l returns [SQLIT
adf0: 45 5f 4e 4f 54 46 4f 55 4e 44 5d 2c 20 74 68 65  E_NOTFOUND], the
ae00: 6e 20 6e 6f 72 6d 61 6c 20 0a 2a 2a 20 5b 50 52  n normal .** [PR
ae10: 41 47 4d 41 5d 20 70 72 6f 63 65 73 73 69 6e 67  AGMA] processing
ae20: 20 63 6f 6e 74 69 6e 75 65 73 2e 20 20 5e 49 66   continues.  ^If
ae30: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e   the [SQLITE_FCN
ae40: 54 4c 5f 50 52 41 47 4d 41 5d 0a 2a 2a 20 66 69  TL_PRAGMA].** fi
ae50: 6c 65 20 63 6f 6e 74 72 6f 6c 20 72 65 74 75 72  le control retur
ae60: 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20  ns [SQLITE_OK], 
ae70: 74 68 65 6e 20 74 68 65 20 70 61 72 73 65 72 20  then the parser 
ae80: 61 73 73 75 6d 65 73 20 74 68 61 74 20 74 68 65  assumes that the
ae90: 0a 2a 2a 20 56 46 53 20 68 61 73 20 68 61 6e 64  .** VFS has hand
aea0: 6c 65 64 20 74 68 65 20 50 52 41 47 4d 41 20 69  led the PRAGMA i
aeb0: 74 73 65 6c 66 20 61 6e 64 20 74 68 65 20 70 61  tself and the pa
aec0: 72 73 65 72 20 67 65 6e 65 72 61 74 65 73 20 61  rser generates a
aed0: 20 6e 6f 2d 6f 70 0a 2a 2a 20 70 72 65 70 61 72   no-op.** prepar
aee0: 65 64 20 73 74 61 74 65 6d 65 6e 74 20 69 66 20  ed statement if 
aef0: 72 65 73 75 6c 74 20 73 74 72 69 6e 67 20 69 73  result string is
af00: 20 4e 55 4c 4c 2c 20 6f 72 20 74 68 61 74 20 72   NULL, or that r
af10: 65 74 75 72 6e 73 20 61 20 63 6f 70 79 0a 2a 2a  eturns a copy.**
af20: 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73   of the result s
af30: 74 72 69 6e 67 20 69 66 20 74 68 65 20 73 74 72  tring if the str
af40: 69 6e 67 20 69 73 20 6e 6f 6e 2d 4e 55 4c 4c 2e  ing is non-NULL.
af50: 0a 2a 2a 20 5e 49 66 20 74 68 65 20 5b 53 51 4c  .** ^If the [SQL
af60: 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41  ITE_FCNTL_PRAGMA
af70: 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 72  ] file control r
af80: 65 74 75 72 6e 73 0a 2a 2a 20 61 6e 79 20 72 65  eturns.** any re
af90: 73 75 6c 74 20 63 6f 64 65 20 6f 74 68 65 72 20  sult code other 
afa0: 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  than [SQLITE_OK]
afb0: 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4e 4f 54 46   or [SQLITE_NOTF
afc0: 4f 55 4e 44 5d 2c 20 74 68 61 74 20 6d 65 61 6e  OUND], that mean
afd0: 73 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 56 46  s.** that the VF
afe0: 53 20 65 6e 63 6f 75 6e 74 65 72 65 64 20 61 6e  S encountered an
aff0: 20 65 72 72 6f 72 20 77 68 69 6c 65 20 68 61 6e   error while han
b000: 64 6c 69 6e 67 20 74 68 65 20 5b 50 52 41 47 4d  dling the [PRAGM
b010: 41 5d 20 61 6e 64 20 74 68 65 0a 2a 2a 20 63 6f  A] and the.** co
b020: 6d 70 69 6c 61 74 69 6f 6e 20 6f 66 20 74 68 65  mpilation of the
b030: 20 50 52 41 47 4d 41 20 66 61 69 6c 73 20 77 69   PRAGMA fails wi
b040: 74 68 20 61 6e 20 65 72 72 6f 72 2e 20 20 5e 54  th an error.  ^T
b050: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
b060: 5f 50 52 41 47 4d 41 5d 0a 2a 2a 20 66 69 6c 65  _PRAGMA].** file
b070: 20 63 6f 6e 74 72 6f 6c 20 6f 63 63 75 72 73 20   control occurs 
b080: 61 74 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67  at the beginning
b090: 20 6f 66 20 70 72 61 67 6d 61 20 73 74 61 74 65   of pragma state
b0a0: 6d 65 6e 74 20 61 6e 61 6c 79 73 69 73 20 61 6e  ment analysis an
b0b0: 64 20 73 6f 0a 2a 2a 20 69 74 20 69 73 20 61 62  d so.** it is ab
b0c0: 6c 65 20 74 6f 20 6f 76 65 72 72 69 64 65 20 62  le to override b
b0d0: 75 69 6c 74 2d 69 6e 20 5b 50 52 41 47 4d 41 5d  uilt-in [PRAGMA]
b0e0: 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a   statements..**.
b0f0: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
b100: 46 43 4e 54 4c 5f 42 55 53 59 48 41 4e 44 4c 45  FCNTL_BUSYHANDLE
b110: 52 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c  R]].** ^The [SQL
b120: 49 54 45 5f 46 43 4e 54 4c 5f 42 55 53 59 48 41  ITE_FCNTL_BUSYHA
b130: 4e 44 4c 45 52 5d 0a 2a 2a 20 66 69 6c 65 2d 63  NDLER].** file-c
b140: 6f 6e 74 72 6f 6c 20 6d 61 79 20 62 65 20 69 6e  ontrol may be in
b150: 76 6f 6b 65 64 20 62 79 20 53 51 4c 69 74 65 20  voked by SQLite 
b160: 6f 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  on the database 
b170: 66 69 6c 65 20 68 61 6e 64 6c 65 0a 2a 2a 20 73  file handle.** s
b180: 68 6f 72 74 6c 79 20 61 66 74 65 72 20 69 74 20  hortly after it 
b190: 69 73 20 6f 70 65 6e 65 64 20 69 6e 20 6f 72 64  is opened in ord
b1a0: 65 72 20 74 6f 20 70 72 6f 76 69 64 65 20 61 20  er to provide a 
b1b0: 63 75 73 74 6f 6d 20 56 46 53 20 77 69 74 68 20  custom VFS with 
b1c0: 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20 74 68 65  access.** to the
b1d0: 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 62 75 73   connections bus
b1e0: 79 2d 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61  y-handler callba
b1f0: 63 6b 2e 20 54 68 65 20 61 72 67 75 6d 65 6e 74  ck. The argument
b200: 20 69 73 20 6f 66 20 74 79 70 65 20 28 76 6f 69   is of type (voi
b210: 64 20 2a 2a 29 0a 2a 2a 20 2d 20 61 6e 20 61 72  d **).** - an ar
b220: 72 61 79 20 6f 66 20 74 77 6f 20 28 76 6f 69 64  ray of two (void
b230: 20 2a 29 20 76 61 6c 75 65 73 2e 20 54 68 65 20   *) values. The 
b240: 66 69 72 73 74 20 28 76 6f 69 64 20 2a 29 20 61  first (void *) a
b250: 63 74 75 61 6c 6c 79 20 70 6f 69 6e 74 73 0a 2a  ctually points.*
b260: 2a 20 74 6f 20 61 20 66 75 6e 63 74 69 6f 6e 20  * to a function 
b270: 6f 66 20 74 79 70 65 20 28 69 6e 74 20 28 2a 29  of type (int (*)
b280: 28 76 6f 69 64 20 2a 29 29 2e 20 49 6e 20 6f 72  (void *)). In or
b290: 64 65 72 20 74 6f 20 69 6e 76 6f 6b 65 20 74 68  der to invoke th
b2a0: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a  e connections.**
b2b0: 20 62 75 73 79 2d 68 61 6e 64 6c 65 72 2c 20 74   busy-handler, t
b2c0: 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f  his function sho
b2d0: 75 6c 64 20 62 65 20 69 6e 76 6f 6b 65 64 20 77  uld be invoked w
b2e0: 69 74 68 20 74 68 65 20 73 65 63 6f 6e 64 20 28  ith the second (
b2f0: 76 6f 69 64 20 2a 29 20 69 6e 0a 2a 2a 20 74 68  void *) in.** th
b300: 65 20 61 72 72 61 79 20 61 73 20 74 68 65 20 6f  e array as the o
b310: 6e 6c 79 20 61 72 67 75 6d 65 6e 74 2e 20 49 66  nly argument. If
b320: 20 69 74 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d   it returns non-
b330: 7a 65 72 6f 2c 20 74 68 65 6e 20 74 68 65 20 6f  zero, then the o
b340: 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 73 68 6f 75  peration.** shou
b350: 6c 64 20 62 65 20 72 65 74 72 69 65 64 2e 20 49  ld be retried. I
b360: 66 20 69 74 20 72 65 74 75 72 6e 73 20 7a 65 72  f it returns zer
b370: 6f 2c 20 74 68 65 20 63 75 73 74 6f 6d 20 56 46  o, the custom VF
b380: 53 20 73 68 6f 75 6c 64 20 61 62 61 6e 64 6f 6e  S should abandon
b390: 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 20   the.** current 
b3a0: 6f 70 65 72 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  operation..**.**
b3b0: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
b3c0: 4e 54 4c 5f 54 45 4d 50 46 49 4c 45 4e 41 4d 45  NTL_TEMPFILENAME
b3d0: 5d 5d 0a 2a 2a 20 5e 41 70 70 6c 69 63 61 74 69  ]].** ^Applicati
b3e0: 6f 6e 20 63 61 6e 20 69 6e 76 6f 6b 65 20 74 68  on can invoke th
b3f0: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
b400: 54 45 4d 50 46 49 4c 45 4e 41 4d 45 5d 20 66 69  TEMPFILENAME] fi
b410: 6c 65 2d 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 74 6f  le-control.** to
b420: 20 68 61 76 65 20 53 51 4c 69 74 65 20 67 65 6e   have SQLite gen
b430: 65 72 61 74 65 20 61 0a 2a 2a 20 74 65 6d 70 6f  erate a.** tempo
b440: 72 61 72 79 20 66 69 6c 65 6e 61 6d 65 20 75 73  rary filename us
b450: 69 6e 67 20 74 68 65 20 73 61 6d 65 20 61 6c 67  ing the same alg
b460: 6f 72 69 74 68 6d 20 74 68 61 74 20 69 73 20 66  orithm that is f
b470: 6f 6c 6c 6f 77 65 64 20 74 6f 20 67 65 6e 65 72  ollowed to gener
b480: 61 74 65 0a 2a 2a 20 74 65 6d 70 6f 72 61 72 79  ate.** temporary
b490: 20 66 69 6c 65 6e 61 6d 65 73 20 66 6f 72 20 54   filenames for T
b4a0: 45 4d 50 20 74 61 62 6c 65 73 20 61 6e 64 20 6f  EMP tables and o
b4b0: 74 68 65 72 20 69 6e 74 65 72 6e 61 6c 20 75 73  ther internal us
b4c0: 65 73 2e 20 20 54 68 65 0a 2a 2a 20 61 72 67 75  es.  The.** argu
b4d0: 6d 65 6e 74 20 73 68 6f 75 6c 64 20 62 65 20 61  ment should be a
b4e0: 20 63 68 61 72 2a 2a 20 77 68 69 63 68 20 77 69   char** which wi
b4f0: 6c 6c 20 62 65 20 66 69 6c 6c 65 64 20 77 69 74  ll be filled wit
b500: 68 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 0a 2a  h the filename.*
b510: 2a 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 6d  * written into m
b520: 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66  emory obtained f
b530: 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  rom [sqlite3_mal
b540: 6c 6f 63 28 29 5d 2e 20 20 54 68 65 20 63 61 6c  loc()].  The cal
b550: 6c 65 72 20 73 68 6f 75 6c 64 0a 2a 2a 20 69 6e  ler should.** in
b560: 76 6f 6b 65 20 5b 73 71 6c 69 74 65 33 5f 66 72  voke [sqlite3_fr
b570: 65 65 28 29 5d 20 6f 6e 20 74 68 65 20 72 65 73  ee()] on the res
b580: 75 6c 74 20 74 6f 20 61 76 6f 69 64 20 61 20 6d  ult to avoid a m
b590: 65 6d 6f 72 79 20 6c 65 61 6b 2e 0a 2a 2a 0a 2a  emory leak..**.*
b5a0: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
b5b0: 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45 5d 5d  CNTL_MMAP_SIZE]]
b5c0: 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  .** The [SQLITE_
b5d0: 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45 5d  FCNTL_MMAP_SIZE]
b5e0: 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73   file control is
b5f0: 20 75 73 65 64 20 74 6f 20 71 75 65 72 79 20 6f   used to query o
b600: 72 20 73 65 74 20 74 68 65 0a 2a 2a 20 6d 61 78  r set the.** max
b610: 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 62  imum number of b
b620: 79 74 65 73 20 74 68 61 74 20 77 69 6c 6c 20 62  ytes that will b
b630: 65 20 75 73 65 64 20 66 6f 72 20 6d 65 6d 6f 72  e used for memor
b640: 79 2d 6d 61 70 70 65 64 20 49 2f 4f 2e 0a 2a 2a  y-mapped I/O..**
b650: 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73   The argument is
b660: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20   a pointer to a 
b670: 76 61 6c 75 65 20 6f 66 20 74 79 70 65 20 73 71  value of type sq
b680: 6c 69 74 65 33 5f 69 6e 74 36 34 20 74 68 61 74  lite3_int64 that
b690: 0a 2a 2a 20 69 73 20 61 6e 20 61 64 76 69 73 6f  .** is an adviso
b6a0: 72 79 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65  ry maximum numbe
b6b0: 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68  r of bytes in th
b6c0: 65 20 66 69 6c 65 20 74 6f 20 6d 65 6d 6f 72 79  e file to memory
b6d0: 20 6d 61 70 2e 20 20 54 68 65 0a 2a 2a 20 70 6f   map.  The.** po
b6e0: 69 6e 74 65 72 20 69 73 20 6f 76 65 72 77 72 69  inter is overwri
b6f0: 74 74 65 6e 20 77 69 74 68 20 74 68 65 20 6f 6c  tten with the ol
b700: 64 20 76 61 6c 75 65 2e 20 20 54 68 65 20 6c 69  d value.  The li
b710: 6d 69 74 20 69 73 20 6e 6f 74 20 63 68 61 6e 67  mit is not chang
b720: 65 64 20 69 66 0a 2a 2a 20 74 68 65 20 76 61 6c  ed if.** the val
b730: 75 65 20 6f 72 69 67 69 6e 61 6c 6c 79 20 70 6f  ue originally po
b740: 69 6e 74 65 64 20 74 6f 20 69 73 20 6e 65 67 61  inted to is nega
b750: 74 69 76 65 2c 20 61 6e 64 20 73 6f 20 74 68 65  tive, and so the
b760: 20 63 75 72 72 65 6e 74 20 6c 69 6d 69 74 20 0a   current limit .
b770: 2a 2a 20 63 61 6e 20 62 65 20 71 75 65 72 69 65  ** can be querie
b780: 64 20 62 79 20 70 61 73 73 69 6e 67 20 69 6e 20  d by passing in 
b790: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 6e  a pointer to a n
b7a0: 65 67 61 74 69 76 65 20 6e 75 6d 62 65 72 2e 20  egative number. 
b7b0: 20 54 68 69 73 0a 2a 2a 20 66 69 6c 65 2d 63 6f   This.** file-co
b7c0: 6e 74 72 6f 6c 20 69 73 20 75 73 65 64 20 69 6e  ntrol is used in
b7d0: 74 65 72 6e 61 6c 6c 79 20 74 6f 20 69 6d 70 6c  ternally to impl
b7e0: 65 6d 65 6e 74 20 5b 50 52 41 47 4d 41 20 6d 6d  ement [PRAGMA mm
b7f0: 61 70 5f 73 69 7a 65 5d 2e 0a 2a 2a 0a 2a 2a 20  ap_size]..**.** 
b800: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e  <li>[[SQLITE_FCN
b810: 54 4c 5f 54 52 41 43 45 5d 5d 0a 2a 2a 20 54 68  TL_TRACE]].** Th
b820: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
b830: 54 52 41 43 45 5d 20 66 69 6c 65 20 63 6f 6e 74  TRACE] file cont
b840: 72 6f 6c 20 70 72 6f 76 69 64 65 73 20 61 64 76  rol provides adv
b850: 69 73 6f 72 79 20 69 6e 66 6f 72 6d 61 74 69 6f  isory informatio
b860: 6e 0a 2a 2a 20 74 6f 20 74 68 65 20 56 46 53 20  n.** to the VFS 
b870: 61 62 6f 75 74 20 77 68 61 74 20 74 68 65 20 68  about what the h
b880: 69 67 68 65 72 20 6c 61 79 65 72 73 20 6f 66 20  igher layers of 
b890: 74 68 65 20 53 51 4c 69 74 65 20 73 74 61 63 6b  the SQLite stack
b8a0: 20 61 72 65 20 64 6f 69 6e 67 2e 0a 2a 2a 20 54   are doing..** T
b8b0: 68 69 73 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c  his file control
b8c0: 20 69 73 20 75 73 65 64 20 62 79 20 73 6f 6d 65   is used by some
b8d0: 20 56 46 53 20 61 63 74 69 76 69 74 79 20 74 72   VFS activity tr
b8e0: 61 63 69 6e 67 20 5b 73 68 69 6d 73 5d 2e 0a 2a  acing [shims]..*
b8f0: 2a 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 69  * The argument i
b900: 73 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  s a zero-termina
b910: 74 65 64 20 73 74 72 69 6e 67 2e 20 20 48 69 67  ted string.  Hig
b920: 68 65 72 20 6c 61 79 65 72 73 20 69 6e 20 74 68  her layers in th
b930: 65 0a 2a 2a 20 53 51 4c 69 74 65 20 73 74 61 63  e.** SQLite stac
b940: 6b 20 6d 61 79 20 67 65 6e 65 72 61 74 65 20 69  k may generate i
b950: 6e 73 74 61 6e 63 65 73 20 6f 66 20 74 68 69 73  nstances of this
b960: 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 66   file control if
b970: 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  .** the [SQLITE_
b980: 55 53 45 5f 46 43 4e 54 4c 5f 54 52 41 43 45 5d  USE_FCNTL_TRACE]
b990: 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
b9a0: 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 2e  tion is enabled.
b9b0: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
b9c0: 49 54 45 5f 46 43 4e 54 4c 5f 48 41 53 5f 4d 4f  ITE_FCNTL_HAS_MO
b9d0: 56 45 44 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51  VED]].** The [SQ
b9e0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 48 41 53 5f 4d  LITE_FCNTL_HAS_M
b9f0: 4f 56 45 44 5d 20 66 69 6c 65 20 63 6f 6e 74 72  OVED] file contr
ba00: 6f 6c 20 69 6e 74 65 72 70 72 65 74 73 20 69 74  ol interprets it
ba10: 73 20 61 72 67 75 6d 65 6e 74 20 61 73 20 61 0a  s argument as a.
ba20: 2a 2a 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e  ** pointer to an
ba30: 20 69 6e 74 65 67 65 72 20 61 6e 64 20 69 74 20   integer and it 
ba40: 77 72 69 74 65 73 20 61 20 62 6f 6f 6c 65 61 6e  writes a boolean
ba50: 20 69 6e 74 6f 20 74 68 61 74 20 69 6e 74 65 67   into that integ
ba60: 65 72 20 64 65 70 65 6e 64 69 6e 67 0a 2a 2a 20  er depending.** 
ba70: 6f 6e 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f  on whether or no
ba80: 74 20 74 68 65 20 66 69 6c 65 20 68 61 73 20 62  t the file has b
ba90: 65 65 6e 20 72 65 6e 61 6d 65 64 2c 20 6d 6f 76  een renamed, mov
baa0: 65 64 2c 20 6f 72 20 64 65 6c 65 74 65 64 20 73  ed, or deleted s
bab0: 69 6e 63 65 20 69 74 0a 2a 2a 20 77 61 73 20 66  ince it.** was f
bac0: 69 72 73 74 20 6f 70 65 6e 65 64 2e 0a 2a 2a 0a  irst opened..**.
bad0: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
bae0: 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 53 45 54 5f  FCNTL_WIN32_SET_
baf0: 48 41 4e 44 4c 45 5d 5d 0a 2a 2a 20 54 68 65 20  HANDLE]].** The 
bb00: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49  [SQLITE_FCNTL_WI
bb10: 4e 33 32 5f 53 45 54 5f 48 41 4e 44 4c 45 5d 20  N32_SET_HANDLE] 
bb20: 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 66  opcode is used f
bb30: 6f 72 20 64 65 62 75 67 67 69 6e 67 2e 20 20 54  or debugging.  T
bb40: 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 20 63 61  his.** opcode ca
bb50: 75 73 65 73 20 74 68 65 20 78 46 69 6c 65 43 6f  uses the xFileCo
bb60: 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 74 6f 20  ntrol method to 
bb70: 73 77 61 70 20 74 68 65 20 66 69 6c 65 20 68 61  swap the file ha
bb80: 6e 64 6c 65 20 77 69 74 68 20 74 68 65 20 6f 6e  ndle with the on
bb90: 65 0a 2a 2a 20 70 6f 69 6e 74 65 64 20 74 6f 20  e.** pointed to 
bba0: 62 79 20 74 68 65 20 70 41 72 67 20 61 72 67 75  by the pArg argu
bbb0: 6d 65 6e 74 2e 20 20 54 68 69 73 20 63 61 70 61  ment.  This capa
bbc0: 62 69 6c 69 74 79 20 69 73 20 75 73 65 64 20 64  bility is used d
bbd0: 75 72 69 6e 67 20 74 65 73 74 69 6e 67 0a 2a 2a  uring testing.**
bbe0: 20 61 6e 64 20 6f 6e 6c 79 20 6e 65 65 64 73 20   and only needs 
bbf0: 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64 20  to be supported 
bc00: 77 68 65 6e 20 53 51 4c 49 54 45 5f 54 45 53 54  when SQLITE_TEST
bc10: 20 69 73 20 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a   is defined..**.
bc20: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
bc30: 46 43 4e 54 4c 5f 57 41 4c 5f 42 4c 4f 43 4b 5d  FCNTL_WAL_BLOCK]
bc40: 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45  ].** The [SQLITE
bc50: 5f 46 43 4e 54 4c 5f 57 41 4c 5f 42 4c 4f 43 4b  _FCNTL_WAL_BLOCK
bc60: 5d 20 69 73 20 61 20 73 69 67 6e 61 6c 20 74 6f  ] is a signal to
bc70: 20 74 68 65 20 56 46 53 20 6c 61 79 65 72 20 74   the VFS layer t
bc80: 68 61 74 20 69 74 20 6d 69 67 68 74 0a 2a 2a 20  hat it might.** 
bc90: 62 65 20 61 64 76 61 6e 74 61 67 65 6f 75 73 20  be advantageous 
bca0: 74 6f 20 62 6c 6f 63 6b 20 6f 6e 20 74 68 65 20  to block on the 
bcb0: 6e 65 78 74 20 57 41 4c 20 6c 6f 63 6b 20 69 66  next WAL lock if
bcc0: 20 74 68 65 20 6c 6f 63 6b 20 69 73 20 6e 6f 74   the lock is not
bcd0: 20 69 6d 6d 65 64 69 61 74 65 6c 79 0a 2a 2a 20   immediately.** 
bce0: 61 76 61 69 6c 61 62 6c 65 2e 20 20 54 68 65 20  available.  The 
bcf0: 57 41 4c 20 73 75 62 73 79 73 74 65 6d 20 69 73  WAL subsystem is
bd00: 73 75 65 73 20 74 68 69 73 20 73 69 67 6e 61 6c  sues this signal
bd10: 20 64 75 72 69 6e 67 20 72 61 72 65 0a 2a 2a 20   during rare.** 
bd20: 63 69 72 63 75 6d 73 74 61 6e 63 65 73 20 69 6e  circumstances in
bd30: 20 6f 72 64 65 72 20 74 6f 20 66 69 78 20 61 20   order to fix a 
bd40: 70 72 6f 62 6c 65 6d 20 77 69 74 68 20 70 72 69  problem with pri
bd50: 6f 72 69 74 79 20 69 6e 76 65 72 73 69 6f 6e 2e  ority inversion.
bd60: 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73  .** Applications
bd70: 20 73 68 6f 75 6c 64 20 3c 65 6d 3e 6e 6f 74 3c   should <em>not<
bd80: 2f 65 6d 3e 20 75 73 65 20 74 68 69 73 20 66 69  /em> use this fi
bd90: 6c 65 2d 63 6f 6e 74 72 6f 6c 2e 0a 2a 2a 0a 2a  le-control..**.*
bda0: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
bdb0: 43 4e 54 4c 5f 5a 49 50 56 46 53 5d 5d 0a 2a 2a  CNTL_ZIPVFS]].**
bdc0: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e   The [SQLITE_FCN
bdd0: 54 4c 5f 5a 49 50 56 46 53 5d 20 6f 70 63 6f 64  TL_ZIPVFS] opcod
bde0: 65 20 69 73 20 69 6d 70 6c 65 6d 65 6e 74 65 64  e is implemented
bdf0: 20 62 79 20 7a 69 70 76 66 73 20 6f 6e 6c 79 2e   by zipvfs only.
be00: 20 41 6c 6c 20 6f 74 68 65 72 0a 2a 2a 20 56 46   All other.** VF
be10: 53 20 73 68 6f 75 6c 64 20 72 65 74 75 72 6e 20  S should return 
be20: 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 20  SQLITE_NOTFOUND 
be30: 66 6f 72 20 74 68 69 73 20 6f 70 63 6f 64 65 2e  for this opcode.
be40: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
be50: 49 54 45 5f 46 43 4e 54 4c 5f 52 42 55 5d 5d 0a  ITE_FCNTL_RBU]].
be60: 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  ** The [SQLITE_F
be70: 43 4e 54 4c 5f 52 42 55 5d 20 6f 70 63 6f 64 65  CNTL_RBU] opcode
be80: 20 69 73 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20   is implemented 
be90: 62 79 20 74 68 65 20 73 70 65 63 69 61 6c 20 56  by the special V
bea0: 46 53 20 75 73 65 64 20 62 79 0a 2a 2a 20 74 68  FS used by.** th
beb0: 65 20 52 42 55 20 65 78 74 65 6e 73 69 6f 6e 20  e RBU extension 
bec0: 6f 6e 6c 79 2e 20 20 41 6c 6c 20 6f 74 68 65 72  only.  All other
bed0: 20 56 46 53 20 73 68 6f 75 6c 64 20 72 65 74 75   VFS should retu
bee0: 72 6e 20 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55  rn SQLITE_NOTFOU
bef0: 4e 44 20 66 6f 72 0a 2a 2a 20 74 68 69 73 20 6f  ND for.** this o
bf00: 70 63 6f 64 65 2e 20 20 0a 2a 2a 20 3c 2f 75 6c  pcode.  .** </ul
bf10: 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  >.*/.#define SQL
bf20: 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54  ITE_FCNTL_LOCKST
bf30: 41 54 45 20 20 20 20 20 20 20 20 20 20 20 20 20  ATE             
bf40: 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    1.#define SQLI
bf50: 54 45 5f 46 43 4e 54 4c 5f 47 45 54 5f 4c 4f 43  TE_FCNTL_GET_LOC
bf60: 4b 50 52 4f 58 59 46 49 4c 45 20 20 20 20 20 20  KPROXYFILE      
bf70: 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   2.#define SQLIT
bf80: 45 5f 46 43 4e 54 4c 5f 53 45 54 5f 4c 4f 43 4b  E_FCNTL_SET_LOCK
bf90: 50 52 4f 58 59 46 49 4c 45 20 20 20 20 20 20 20  PROXYFILE       
bfa0: 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  3.#define SQLITE
bfb0: 5f 46 43 4e 54 4c 5f 4c 41 53 54 5f 45 52 52 4e  _FCNTL_LAST_ERRN
bfc0: 4f 20 20 20 20 20 20 20 20 20 20 20 20 20 20 34  O              4
bfd0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
bfe0: 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e 54 20  FCNTL_SIZE_HINT 
bff0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 35 0a                5.
c000: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
c010: 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45 20  CNTL_CHUNK_SIZE 
c020: 20 20 20 20 20 20 20 20 20 20 20 20 20 36 0a 23               6.#
c030: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
c040: 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52  NTL_FILE_POINTER
c050: 20 20 20 20 20 20 20 20 20 20 20 20 37 0a 23 64              7.#d
c060: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
c070: 54 4c 5f 53 59 4e 43 5f 4f 4d 49 54 54 45 44 20  TL_SYNC_OMITTED 
c080: 20 20 20 20 20 20 20 20 20 20 20 38 0a 23 64 65             8.#de
c090: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
c0a0: 4c 5f 57 49 4e 33 32 5f 41 56 5f 52 45 54 52 59  L_WIN32_AV_RETRY
c0b0: 20 20 20 20 20 20 20 20 20 20 39 0a 23 64 65 66            9.#def
c0c0: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
c0d0: 5f 50 45 52 53 49 53 54 5f 57 41 4c 20 20 20 20  _PERSIST_WAL    
c0e0: 20 20 20 20 20 20 20 20 31 30 0a 23 64 65 66 69          10.#defi
c0f0: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
c100: 4f 56 45 52 57 52 49 54 45 20 20 20 20 20 20 20  OVERWRITE       
c110: 20 20 20 20 20 20 20 31 31 0a 23 64 65 66 69 6e         11.#defin
c120: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56  e SQLITE_FCNTL_V
c130: 46 53 4e 41 4d 45 20 20 20 20 20 20 20 20 20 20  FSNAME          
c140: 20 20 20 20 20 20 31 32 0a 23 64 65 66 69 6e 65        12.#define
c150: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 4f   SQLITE_FCNTL_PO
c160: 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54  WERSAFE_OVERWRIT
c170: 45 20 20 20 20 31 33 0a 23 64 65 66 69 6e 65 20  E    13.#define 
c180: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41  SQLITE_FCNTL_PRA
c190: 47 4d 41 20 20 20 20 20 20 20 20 20 20 20 20 20  GMA             
c1a0: 20 20 20 20 31 34 0a 23 64 65 66 69 6e 65 20 53      14.#define S
c1b0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 55 53 59  QLITE_FCNTL_BUSY
c1c0: 48 41 4e 44 4c 45 52 20 20 20 20 20 20 20 20 20  HANDLER         
c1d0: 20 20 20 31 35 0a 23 64 65 66 69 6e 65 20 53 51     15.#define SQ
c1e0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 45 4d 50 46  LITE_FCNTL_TEMPF
c1f0: 49 4c 45 4e 41 4d 45 20 20 20 20 20 20 20 20 20  ILENAME         
c200: 20 20 31 36 0a 23 64 65 66 69 6e 65 20 53 51 4c    16.#define SQL
c210: 49 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53  ITE_FCNTL_MMAP_S
c220: 49 5a 45 20 20 20 20 20 20 20 20 20 20 20 20 20  IZE             
c230: 20 31 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   18.#define SQLI
c240: 54 45 5f 46 43 4e 54 4c 5f 54 52 41 43 45 20 20  TE_FCNTL_TRACE  
c250: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
c260: 31 39 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  19.#define SQLIT
c270: 45 5f 46 43 4e 54 4c 5f 48 41 53 5f 4d 4f 56 45  E_FCNTL_HAS_MOVE
c280: 44 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32  D              2
c290: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
c2a0: 5f 46 43 4e 54 4c 5f 53 59 4e 43 20 20 20 20 20  _FCNTL_SYNC     
c2b0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 31                21
c2c0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
c2d0: 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 50 48 41  FCNTL_COMMIT_PHA
c2e0: 53 45 54 57 4f 20 20 20 20 20 20 20 20 32 32 0a  SETWO        22.
c2f0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
c300: 43 4e 54 4c 5f 57 49 4e 33 32 5f 53 45 54 5f 48  CNTL_WIN32_SET_H
c310: 41 4e 44 4c 45 20 20 20 20 20 20 20 32 33 0a 23  ANDLE       23.#
c320: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
c330: 4e 54 4c 5f 57 41 4c 5f 42 4c 4f 43 4b 20 20 20  NTL_WAL_BLOCK   
c340: 20 20 20 20 20 20 20 20 20 20 20 32 34 0a 23 64             24.#d
c350: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
c360: 54 4c 5f 5a 49 50 56 46 53 20 20 20 20 20 20 20  TL_ZIPVFS       
c370: 20 20 20 20 20 20 20 20 20 20 32 35 0a 23 64 65            25.#de
c380: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
c390: 4c 5f 52 42 55 20 20 20 20 20 20 20 20 20 20 20  L_RBU           
c3a0: 20 20 20 20 20 20 20 20 20 32 36 0a 23 64 65 66           26.#def
c3b0: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
c3c0: 5f 56 46 53 5f 50 4f 49 4e 54 45 52 20 20 20 20  _VFS_POINTER    
c3d0: 20 20 20 20 20 20 20 20 32 37 0a 23 64 65 66 69          27.#defi
c3e0: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
c3f0: 4a 4f 55 52 4e 41 4c 5f 50 4f 49 4e 54 45 52 20  JOURNAL_POINTER 
c400: 20 20 20 20 20 20 20 32 38 0a 0a 2f 2a 20 64 65         28../* de
c410: 70 72 65 63 61 74 65 64 20 6e 61 6d 65 73 20 2a  precated names *
c420: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
c430: 5f 47 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49  _GET_LOCKPROXYFI
c440: 4c 45 20 20 20 20 20 20 53 51 4c 49 54 45 5f 46  LE      SQLITE_F
c450: 43 4e 54 4c 5f 47 45 54 5f 4c 4f 43 4b 50 52 4f  CNTL_GET_LOCKPRO
c460: 58 59 46 49 4c 45 0a 23 64 65 66 69 6e 65 20 53  XYFILE.#define S
c470: 51 4c 49 54 45 5f 53 45 54 5f 4c 4f 43 4b 50 52  QLITE_SET_LOCKPR
c480: 4f 58 59 46 49 4c 45 20 20 20 20 20 20 53 51 4c  OXYFILE      SQL
c490: 49 54 45 5f 46 43 4e 54 4c 5f 53 45 54 5f 4c 4f  ITE_FCNTL_SET_LO
c4a0: 43 4b 50 52 4f 58 59 46 49 4c 45 0a 23 64 65 66  CKPROXYFILE.#def
c4b0: 69 6e 65 20 53 51 4c 49 54 45 5f 4c 41 53 54 5f  ine SQLITE_LAST_
c4c0: 45 52 52 4e 4f 20 20 20 20 20 20 20 20 20 20 20  ERRNO           
c4d0: 20 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c    SQLITE_FCNTL_L
c4e0: 41 53 54 5f 45 52 52 4e 4f 0a 0a 0a 2f 2a 0a 2a  AST_ERRNO.../*.*
c4f0: 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 75 74 65  * CAPI3REF: Mute
c500: 78 20 48 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20 54  x Handle.**.** T
c510: 68 65 20 6d 75 74 65 78 20 6d 6f 64 75 6c 65 20  he mutex module 
c520: 77 69 74 68 69 6e 20 53 51 4c 69 74 65 20 64 65  within SQLite de
c530: 66 69 6e 65 73 20 5b 73 71 6c 69 74 65 33 5f 6d  fines [sqlite3_m
c540: 75 74 65 78 5d 20 74 6f 20 62 65 20 61 6e 0a 2a  utex] to be an.*
c550: 2a 20 61 62 73 74 72 61 63 74 20 74 79 70 65 20  * abstract type 
c560: 66 6f 72 20 61 20 6d 75 74 65 78 20 6f 62 6a 65  for a mutex obje
c570: 63 74 2e 20 20 54 68 65 20 53 51 4c 69 74 65 20  ct.  The SQLite 
c580: 63 6f 72 65 20 6e 65 76 65 72 20 6c 6f 6f 6b 73  core never looks
c590: 0a 2a 2a 20 61 74 20 74 68 65 20 69 6e 74 65 72  .** at the inter
c5a0: 6e 61 6c 20 72 65 70 72 65 73 65 6e 74 61 74 69  nal representati
c5b0: 6f 6e 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65  on of an [sqlite
c5c0: 33 5f 6d 75 74 65 78 5d 2e 20 20 49 74 20 6f 6e  3_mutex].  It on
c5d0: 6c 79 0a 2a 2a 20 64 65 61 6c 73 20 77 69 74 68  ly.** deals with
c5e0: 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 74 68 65   pointers to the
c5f0: 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d   [sqlite3_mutex]
c600: 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 4d   object..**.** M
c610: 75 74 65 78 65 73 20 61 72 65 20 63 72 65 61 74  utexes are creat
c620: 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ed using [sqlite
c630: 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29 5d  3_mutex_alloc()]
c640: 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72  ..*/.typedef str
c650: 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 75 74 65  uct sqlite3_mute
c660: 78 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 3b  x sqlite3_mutex;
c670: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
c680: 3a 20 4c 6f 61 64 61 62 6c 65 20 45 78 74 65 6e  : Loadable Exten
c690: 73 69 6f 6e 20 54 68 75 6e 6b 0a 2a 2a 0a 2a 2a  sion Thunk.**.**
c6a0: 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   A pointer to th
c6b0: 65 20 6f 70 61 71 75 65 20 73 71 6c 69 74 65 33  e opaque sqlite3
c6c0: 5f 61 70 69 5f 72 6f 75 74 69 6e 65 73 20 73 74  _api_routines st
c6d0: 72 75 63 74 75 72 65 20 69 73 20 70 61 73 73 65  ructure is passe
c6e0: 64 20 61 73 0a 2a 2a 20 74 68 65 20 74 68 69 72  d as.** the thir
c6f0: 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 65  d parameter to e
c700: 6e 74 72 79 20 70 6f 69 6e 74 73 20 6f 66 20 5b  ntry points of [
c710: 6c 6f 61 64 61 62 6c 65 20 65 78 74 65 6e 73 69  loadable extensi
c720: 6f 6e 73 5d 2e 20 20 54 68 69 73 0a 2a 2a 20 73  ons].  This.** s
c730: 74 72 75 63 74 75 72 65 20 6d 75 73 74 20 62 65  tructure must be
c740: 20 74 79 70 65 64 65 66 65 64 20 69 6e 20 6f 72   typedefed in or
c750: 64 65 72 20 74 6f 20 77 6f 72 6b 20 61 72 6f 75  der to work arou
c760: 6e 64 20 63 6f 6d 70 69 6c 65 72 20 77 61 72 6e  nd compiler warn
c770: 69 6e 67 73 0a 2a 2a 20 6f 6e 20 73 6f 6d 65 20  ings.** on some 
c780: 70 6c 61 74 66 6f 72 6d 73 2e 0a 2a 2f 0a 74 79  platforms..*/.ty
c790: 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c  pedef struct sql
c7a0: 69 74 65 33 5f 61 70 69 5f 72 6f 75 74 69 6e 65  ite3_api_routine
c7b0: 73 20 73 71 6c 69 74 65 33 5f 61 70 69 5f 72 6f  s sqlite3_api_ro
c7c0: 75 74 69 6e 65 73 3b 0a 0a 2f 2a 0a 2a 2a 20 43  utines;../*.** C
c7d0: 41 50 49 33 52 45 46 3a 20 4f 53 20 49 6e 74 65  API3REF: OS Inte
c7e0: 72 66 61 63 65 20 4f 62 6a 65 63 74 0a 2a 2a 0a  rface Object.**.
c7f0: 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f  ** An instance o
c800: 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66  f the sqlite3_vf
c810: 73 20 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73  s object defines
c820: 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 20 62   the interface b
c830: 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65 20 53 51  etween.** the SQ
c840: 4c 69 74 65 20 63 6f 72 65 20 61 6e 64 20 74 68  Lite core and th
c850: 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 6f 70 65  e underlying ope
c860: 72 61 74 69 6e 67 20 73 79 73 74 65 6d 2e 20 20  rating system.  
c870: 54 68 65 20 22 76 66 73 22 0a 2a 2a 20 69 6e 20  The "vfs".** in 
c880: 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
c890: 6f 62 6a 65 63 74 20 73 74 61 6e 64 73 20 66 6f  object stands fo
c8a0: 72 20 22 76 69 72 74 75 61 6c 20 66 69 6c 65 20  r "virtual file 
c8b0: 73 79 73 74 65 6d 22 2e 20 20 53 65 65 0a 2a 2a  system".  See.**
c8c0: 20 74 68 65 20 5b 56 46 53 20 7c 20 56 46 53 20   the [VFS | VFS 
c8d0: 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 5d 20 66  documentation] f
c8e0: 6f 72 20 66 75 72 74 68 65 72 20 69 6e 66 6f 72  or further infor
c8f0: 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68  mation..**.** Th
c900: 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 69  e value of the i
c910: 56 65 72 73 69 6f 6e 20 66 69 65 6c 64 20 69 73  Version field is
c920: 20 69 6e 69 74 69 61 6c 6c 79 20 31 20 62 75 74   initially 1 but
c930: 20 6d 61 79 20 62 65 20 6c 61 72 67 65 72 20 69   may be larger i
c940: 6e 0a 2a 2a 20 66 75 74 75 72 65 20 76 65 72 73  n.** future vers
c950: 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 20  ions of SQLite. 
c960: 20 41 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c   Additional fiel
c970: 64 73 20 6d 61 79 20 62 65 20 61 70 70 65 6e 64  ds may be append
c980: 65 64 20 74 6f 20 74 68 69 73 0a 2a 2a 20 6f 62  ed to this.** ob
c990: 6a 65 63 74 20 77 68 65 6e 20 74 68 65 20 69 56  ject when the iV
c9a0: 65 72 73 69 6f 6e 20 76 61 6c 75 65 20 69 73 20  ersion value is 
c9b0: 69 6e 63 72 65 61 73 65 64 2e 20 20 4e 6f 74 65  increased.  Note
c9c0: 20 74 68 61 74 20 74 68 65 20 73 74 72 75 63 74   that the struct
c9d0: 75 72 65 0a 2a 2a 20 6f 66 20 74 68 65 20 73 71  ure.** of the sq
c9e0: 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74  lite3_vfs object
c9f0: 20 63 68 61 6e 67 65 73 20 69 6e 20 74 68 65 20   changes in the 
ca00: 74 72 61 6e 73 61 63 74 69 6f 6e 20 62 65 74 77  transaction betw
ca10: 65 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 76 65  een.** SQLite ve
ca20: 72 73 69 6f 6e 20 33 2e 35 2e 39 20 61 6e 64 20  rsion 3.5.9 and 
ca30: 33 2e 36 2e 30 20 61 6e 64 20 79 65 74 20 74 68  3.6.0 and yet th
ca40: 65 20 69 56 65 72 73 69 6f 6e 20 66 69 65 6c 64  e iVersion field
ca50: 20 77 61 73 20 6e 6f 74 0a 2a 2a 20 6d 6f 64 69   was not.** modi
ca60: 66 69 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  fied..**.** The 
ca70: 73 7a 4f 73 46 69 6c 65 20 66 69 65 6c 64 20 69  szOsFile field i
ca80: 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68  s the size of th
ca90: 65 20 73 75 62 63 6c 61 73 73 65 64 20 5b 73 71  e subclassed [sq
caa0: 6c 69 74 65 33 5f 66 69 6c 65 5d 0a 2a 2a 20 73  lite3_file].** s
cab0: 74 72 75 63 74 75 72 65 20 75 73 65 64 20 62 79  tructure used by
cac0: 20 74 68 69 73 20 56 46 53 2e 20 20 6d 78 50 61   this VFS.  mxPa
cad0: 74 68 6e 61 6d 65 20 69 73 20 74 68 65 20 6d 61  thname is the ma
cae0: 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 0a  ximum length of.
caf0: 2a 2a 20 61 20 70 61 74 68 6e 61 6d 65 20 69 6e  ** a pathname in
cb00: 20 74 68 69 73 20 56 46 53 2e 0a 2a 2a 0a 2a 2a   this VFS..**.**
cb10: 20 52 65 67 69 73 74 65 72 65 64 20 73 71 6c 69   Registered sqli
cb20: 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 73 20  te3_vfs objects 
cb30: 61 72 65 20 6b 65 70 74 20 6f 6e 20 61 20 6c 69  are kept on a li
cb40: 6e 6b 65 64 20 6c 69 73 74 20 66 6f 72 6d 65 64  nked list formed
cb50: 20 62 79 0a 2a 2a 20 74 68 65 20 70 4e 65 78 74   by.** the pNext
cb60: 20 70 6f 69 6e 74 65 72 2e 20 20 54 68 65 20 5b   pointer.  The [
cb70: 73 71 6c 69 74 65 33 5f 76 66 73 5f 72 65 67 69  sqlite3_vfs_regi
cb80: 73 74 65 72 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b  ster()].** and [
cb90: 73 71 6c 69 74 65 33 5f 76 66 73 5f 75 6e 72 65  sqlite3_vfs_unre
cba0: 67 69 73 74 65 72 28 29 5d 20 69 6e 74 65 72 66  gister()] interf
cbb0: 61 63 65 73 20 6d 61 6e 61 67 65 20 74 68 69 73  aces manage this
cbc0: 20 6c 69 73 74 0a 2a 2a 20 69 6e 20 61 20 74 68   list.** in a th
cbd0: 72 65 61 64 2d 73 61 66 65 20 77 61 79 2e 20 20  read-safe way.  
cbe0: 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  The [sqlite3_vfs
cbf0: 5f 66 69 6e 64 28 29 5d 20 69 6e 74 65 72 66 61  _find()] interfa
cc00: 63 65 0a 2a 2a 20 73 65 61 72 63 68 65 73 20 74  ce.** searches t
cc10: 68 65 20 6c 69 73 74 2e 20 20 4e 65 69 74 68 65  he list.  Neithe
cc20: 72 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  r the applicatio
cc30: 6e 20 63 6f 64 65 20 6e 6f 72 20 74 68 65 20 56  n code nor the V
cc40: 46 53 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61  FS.** implementa
cc50: 74 69 6f 6e 20 73 68 6f 75 6c 64 20 75 73 65 20  tion should use 
cc60: 74 68 65 20 70 4e 65 78 74 20 70 6f 69 6e 74 65  the pNext pointe
cc70: 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 4e 65  r..**.** The pNe
cc80: 78 74 20 66 69 65 6c 64 20 69 73 20 74 68 65 20  xt field is the 
cc90: 6f 6e 6c 79 20 66 69 65 6c 64 20 69 6e 20 74 68  only field in th
cca0: 65 20 73 71 6c 69 74 65 33 5f 76 66 73 0a 2a 2a  e sqlite3_vfs.**
ccb0: 20 73 74 72 75 63 74 75 72 65 20 74 68 61 74 20   structure that 
ccc0: 53 51 4c 69 74 65 20 77 69 6c 6c 20 65 76 65 72  SQLite will ever
ccd0: 20 6d 6f 64 69 66 79 2e 20 20 53 51 4c 69 74 65   modify.  SQLite
cce0: 20 77 69 6c 6c 20 6f 6e 6c 79 20 61 63 63 65 73   will only acces
ccf0: 73 0a 2a 2a 20 6f 72 20 6d 6f 64 69 66 79 20 74  s.** or modify t
cd00: 68 69 73 20 66 69 65 6c 64 20 77 68 69 6c 65 20  his field while 
cd10: 68 6f 6c 64 69 6e 67 20 61 20 70 61 72 74 69 63  holding a partic
cd20: 75 6c 61 72 20 73 74 61 74 69 63 20 6d 75 74 65  ular static mute
cd30: 78 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63  x..** The applic
cd40: 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 65 76  ation should nev
cd50: 65 72 20 6d 6f 64 69 66 79 20 61 6e 79 74 68 69  er modify anythi
cd60: 6e 67 20 77 69 74 68 69 6e 20 74 68 65 20 73 71  ng within the sq
cd70: 6c 69 74 65 33 5f 76 66 73 0a 2a 2a 20 6f 62 6a  lite3_vfs.** obj
cd80: 65 63 74 20 6f 6e 63 65 20 74 68 65 20 6f 62 6a  ect once the obj
cd90: 65 63 74 20 68 61 73 20 62 65 65 6e 20 72 65 67  ect has been reg
cda0: 69 73 74 65 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  istered..**.** T
cdb0: 68 65 20 7a 4e 61 6d 65 20 66 69 65 6c 64 20 68  he zName field h
cdc0: 6f 6c 64 73 20 74 68 65 20 6e 61 6d 65 20 6f 66  olds the name of
cdd0: 20 74 68 65 20 56 46 53 20 6d 6f 64 75 6c 65 2e   the VFS module.
cde0: 20 20 54 68 65 20 6e 61 6d 65 20 6d 75 73 74 0a    The name must.
cdf0: 2a 2a 20 62 65 20 75 6e 69 71 75 65 20 61 63 72  ** be unique acr
ce00: 6f 73 73 20 61 6c 6c 20 56 46 53 20 6d 6f 64 75  oss all VFS modu
ce10: 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 73 71 6c  les..**.** [[sql
ce20: 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 5d  ite3_vfs.xOpen]]
ce30: 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 67 75 61 72  .** ^SQLite guar
ce40: 61 6e 74 65 65 73 20 74 68 61 74 20 74 68 65 20  antees that the 
ce50: 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65  zFilename parame
ce60: 74 65 72 20 74 6f 20 78 4f 70 65 6e 0a 2a 2a 20  ter to xOpen.** 
ce70: 69 73 20 65 69 74 68 65 72 20 61 20 4e 55 4c 4c  is either a NULL
ce80: 20 70 6f 69 6e 74 65 72 20 6f 72 20 73 74 72 69   pointer or stri
ce90: 6e 67 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66  ng obtained.** f
cea0: 72 6f 6d 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d  rom xFullPathnam
ceb0: 65 28 29 20 77 69 74 68 20 61 6e 20 6f 70 74 69  e() with an opti
cec0: 6f 6e 61 6c 20 73 75 66 66 69 78 20 61 64 64 65  onal suffix adde
ced0: 64 2e 0a 2a 2a 20 5e 49 66 20 61 20 73 75 66 66  d..** ^If a suff
cee0: 69 78 20 69 73 20 61 64 64 65 64 20 74 6f 20 74  ix is added to t
cef0: 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72  he zFilename par
cf00: 61 6d 65 74 65 72 2c 20 69 74 20 77 69 6c 6c 0a  ameter, it will.
cf10: 2a 2a 20 63 6f 6e 73 69 73 74 20 6f 66 20 61 20  ** consist of a 
cf20: 73 69 6e 67 6c 65 20 22 2d 22 20 63 68 61 72 61  single "-" chara
cf30: 63 74 65 72 20 66 6f 6c 6c 6f 77 65 64 20 62 79  cter followed by
cf40: 20 6e 6f 20 6d 6f 72 65 20 74 68 61 6e 0a 2a 2a   no more than.**
cf50: 20 31 31 20 61 6c 70 68 61 6e 75 6d 65 72 69 63   11 alphanumeric
cf60: 20 61 6e 64 2f 6f 72 20 22 2d 22 20 63 68 61 72   and/or "-" char
cf70: 61 63 74 65 72 73 2e 0a 2a 2a 20 5e 53 51 4c 69  acters..** ^SQLi
cf80: 74 65 20 66 75 72 74 68 65 72 20 67 75 61 72 61  te further guara
cf90: 6e 74 65 65 73 20 74 68 61 74 0a 2a 2a 20 74 68  ntees that.** th
cfa0: 65 20 73 74 72 69 6e 67 20 77 69 6c 6c 20 62 65  e string will be
cfb0: 20 76 61 6c 69 64 20 61 6e 64 20 75 6e 63 68 61   valid and uncha
cfc0: 6e 67 65 64 20 75 6e 74 69 6c 20 78 43 6c 6f 73  nged until xClos
cfd0: 65 28 29 20 69 73 0a 2a 2a 20 63 61 6c 6c 65 64  e() is.** called
cfe0: 2e 20 42 65 63 61 75 73 65 20 6f 66 20 74 68 65  . Because of the
cff0: 20 70 72 65 76 69 6f 75 73 20 73 65 6e 74 65 6e   previous senten
d000: 63 65 2c 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69  ce,.** the [sqli
d010: 74 65 33 5f 66 69 6c 65 5d 20 63 61 6e 20 73 61  te3_file] can sa
d020: 66 65 6c 79 20 73 74 6f 72 65 20 61 20 70 6f 69  fely store a poi
d030: 6e 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 66  nter to the.** f
d040: 69 6c 65 6e 61 6d 65 20 69 66 20 69 74 20 6e 65  ilename if it ne
d050: 65 64 73 20 74 6f 20 72 65 6d 65 6d 62 65 72 20  eds to remember 
d060: 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 66 6f 72  the filename for
d070: 20 73 6f 6d 65 20 72 65 61 73 6f 6e 2e 0a 2a 2a   some reason..**
d080: 20 49 66 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d   If the zFilenam
d090: 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 78  e parameter to x
d0a0: 4f 70 65 6e 20 69 73 20 61 20 4e 55 4c 4c 20 70  Open is a NULL p
d0b0: 6f 69 6e 74 65 72 20 74 68 65 6e 20 78 4f 70 65  ointer then xOpe
d0c0: 6e 0a 2a 2a 20 6d 75 73 74 20 69 6e 76 65 6e 74  n.** must invent
d0d0: 20 69 74 73 20 6f 77 6e 20 74 65 6d 70 6f 72 61   its own tempora
d0e0: 72 79 20 6e 61 6d 65 20 66 6f 72 20 74 68 65 20  ry name for the 
d0f0: 66 69 6c 65 2e 20 20 5e 57 68 65 6e 65 76 65 72  file.  ^Whenever
d100: 20 74 68 65 20 0a 2a 2a 20 78 46 69 6c 65 6e 61   the .** xFilena
d110: 6d 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  me parameter is 
d120: 4e 55 4c 4c 20 69 74 20 77 69 6c 6c 20 61 6c 73  NULL it will als
d130: 6f 20 62 65 20 74 68 65 20 63 61 73 65 20 74 68  o be the case th
d140: 61 74 20 74 68 65 0a 2a 2a 20 66 6c 61 67 73 20  at the.** flags 
d150: 70 61 72 61 6d 65 74 65 72 20 77 69 6c 6c 20 69  parameter will i
d160: 6e 63 6c 75 64 65 20 5b 53 51 4c 49 54 45 5f 4f  nclude [SQLITE_O
d170: 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53  PEN_DELETEONCLOS
d180: 45 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c  E]..**.** The fl
d190: 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ags argument to 
d1a0: 78 4f 70 65 6e 28 29 20 69 6e 63 6c 75 64 65 73  xOpen() includes
d1b0: 20 61 6c 6c 20 62 69 74 73 20 73 65 74 20 69 6e   all bits set in
d1c0: 0a 2a 2a 20 74 68 65 20 66 6c 61 67 73 20 61 72  .** the flags ar
d1d0: 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74  gument to [sqlit
d1e0: 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2e 20 20  e3_open_v2()].  
d1f0: 4f 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 6f  Or if [sqlite3_o
d200: 70 65 6e 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71  pen()].** or [sq
d210: 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 20  lite3_open16()] 
d220: 69 73 20 75 73 65 64 2c 20 74 68 65 6e 20 66 6c  is used, then fl
d230: 61 67 73 20 69 6e 63 6c 75 64 65 73 20 61 74 20  ags includes at 
d240: 6c 65 61 73 74 0a 2a 2a 20 5b 53 51 4c 49 54 45  least.** [SQLITE
d250: 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d  _OPEN_READWRITE]
d260: 20 7c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f   | [SQLITE_OPEN_
d270: 43 52 45 41 54 45 5d 2e 20 0a 2a 2a 20 49 66 20  CREATE]. .** If 
d280: 78 4f 70 65 6e 28 29 20 6f 70 65 6e 73 20 61 20  xOpen() opens a 
d290: 66 69 6c 65 20 72 65 61 64 2d 6f 6e 6c 79 20 74  file read-only t
d2a0: 68 65 6e 20 69 74 20 73 65 74 73 20 2a 70 4f 75  hen it sets *pOu
d2b0: 74 46 6c 61 67 73 20 74 6f 0a 2a 2a 20 69 6e 63  tFlags to.** inc
d2c0: 6c 75 64 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45  lude [SQLITE_OPE
d2d0: 4e 5f 52 45 41 44 4f 4e 4c 59 5d 2e 20 20 4f 74  N_READONLY].  Ot
d2e0: 68 65 72 20 62 69 74 73 20 69 6e 20 2a 70 4f 75  her bits in *pOu
d2f0: 74 46 6c 61 67 73 20 6d 61 79 20 62 65 20 73 65  tFlags may be se
d300: 74 2e 0a 2a 2a 0a 2a 2a 20 5e 28 53 51 4c 69 74  t..**.** ^(SQLit
d310: 65 20 77 69 6c 6c 20 61 6c 73 6f 20 61 64 64 20  e will also add 
d320: 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f  one of the follo
d330: 77 69 6e 67 20 66 6c 61 67 73 20 74 6f 20 74 68  wing flags to th
d340: 65 20 78 4f 70 65 6e 28 29 0a 2a 2a 20 63 61 6c  e xOpen().** cal
d350: 6c 2c 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20  l, depending on 
d360: 74 68 65 20 6f 62 6a 65 63 74 20 62 65 69 6e 67  the object being
d370: 20 6f 70 65 6e 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c   opened:.**.** <
d380: 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51  ul>.** <li>  [SQ
d390: 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44  LITE_OPEN_MAIN_D
d3a0: 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c  B].** <li>  [SQL
d3b0: 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f  ITE_OPEN_MAIN_JO
d3c0: 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20  URNAL].** <li>  
d3d0: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d  [SQLITE_OPEN_TEM
d3e0: 50 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b  P_DB].** <li>  [
d3f0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50  SQLITE_OPEN_TEMP
d400: 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69  _JOURNAL].** <li
d410: 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  >  [SQLITE_OPEN_
d420: 54 52 41 4e 53 49 45 4e 54 5f 44 42 5d 0a 2a 2a  TRANSIENT_DB].**
d430: 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f   <li>  [SQLITE_O
d440: 50 45 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c 5d 0a  PEN_SUBJOURNAL].
d450: 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45  ** <li>  [SQLITE
d460: 5f 4f 50 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55  _OPEN_MASTER_JOU
d470: 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b  RNAL].** <li>  [
d480: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 57 41 4c 5d  SQLITE_OPEN_WAL]
d490: 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a  .** </ul>)^.**.*
d4a0: 2a 20 54 68 65 20 66 69 6c 65 20 49 2f 4f 20 69  * The file I/O i
d4b0: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 63 61  mplementation ca
d4c0: 6e 20 75 73 65 20 74 68 65 20 6f 62 6a 65 63 74  n use the object
d4d0: 20 74 79 70 65 20 66 6c 61 67 73 20 74 6f 0a 2a   type flags to.*
d4e0: 2a 20 63 68 61 6e 67 65 20 74 68 65 20 77 61 79  * change the way
d4f0: 20 69 74 20 64 65 61 6c 73 20 77 69 74 68 20 66   it deals with f
d500: 69 6c 65 73 2e 20 20 46 6f 72 20 65 78 61 6d 70  iles.  For examp
d510: 6c 65 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69  le, an applicati
d520: 6f 6e 0a 2a 2a 20 74 68 61 74 20 64 6f 65 73 20  on.** that does 
d530: 6e 6f 74 20 63 61 72 65 20 61 62 6f 75 74 20 63  not care about c
d540: 72 61 73 68 20 72 65 63 6f 76 65 72 79 20 6f 72  rash recovery or
d550: 20 72 6f 6c 6c 62 61 63 6b 20 6d 69 67 68 74 20   rollback might 
d560: 6d 61 6b 65 0a 2a 2a 20 74 68 65 20 6f 70 65 6e  make.** the open
d570: 20 6f 66 20 61 20 6a 6f 75 72 6e 61 6c 20 66 69   of a journal fi
d580: 6c 65 20 61 20 6e 6f 2d 6f 70 2e 20 20 57 72 69  le a no-op.  Wri
d590: 74 65 73 20 74 6f 20 74 68 69 73 20 6a 6f 75 72  tes to this jour
d5a0: 6e 61 6c 20 77 6f 75 6c 64 0a 2a 2a 20 61 6c 73  nal would.** als
d5b0: 6f 20 62 65 20 6e 6f 2d 6f 70 73 2c 20 61 6e 64  o be no-ops, and
d5c0: 20 61 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20   any attempt to 
d5d0: 72 65 61 64 20 74 68 65 20 6a 6f 75 72 6e 61 6c  read the journal
d5e0: 20 77 6f 75 6c 64 20 72 65 74 75 72 6e 0a 2a 2a   would return.**
d5f0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 2e 20 20   SQLITE_IOERR.  
d600: 4f 72 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74  Or the implement
d610: 61 74 69 6f 6e 20 6d 69 67 68 74 20 72 65 63 6f  ation might reco
d620: 67 6e 69 7a 65 20 74 68 61 74 20 61 20 64 61 74  gnize that a dat
d630: 61 62 61 73 65 0a 2a 2a 20 66 69 6c 65 20 77 69  abase.** file wi
d640: 6c 6c 20 62 65 20 64 6f 69 6e 67 20 70 61 67 65  ll be doing page
d650: 2d 61 6c 69 67 6e 65 64 20 73 65 63 74 6f 72 20  -aligned sector 
d660: 72 65 61 64 73 20 61 6e 64 20 77 72 69 74 65 73  reads and writes
d670: 20 69 6e 20 61 20 72 61 6e 64 6f 6d 0a 2a 2a 20   in a random.** 
d680: 6f 72 64 65 72 20 61 6e 64 20 73 65 74 20 75 70  order and set up
d690: 20 69 74 73 20 49 2f 4f 20 73 75 62 73 79 73 74   its I/O subsyst
d6a0: 65 6d 20 61 63 63 6f 72 64 69 6e 67 6c 79 2e 0a  em accordingly..
d6b0: 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 69 67  **.** SQLite mig
d6c0: 68 74 20 61 6c 73 6f 20 61 64 64 20 6f 6e 65 20  ht also add one 
d6d0: 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  of the following
d6e0: 20 66 6c 61 67 73 20 74 6f 20 74 68 65 20 78 4f   flags to the xO
d6f0: 70 65 6e 20 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a  pen method:.**.*
d700: 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b  * <ul>.** <li> [
d710: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45  SQLITE_OPEN_DELE
d720: 54 45 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 3c 6c  TEONCLOSE].** <l
d730: 69 3e 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  i> [SQLITE_OPEN_
d740: 45 58 43 4c 55 53 49 56 45 5d 0a 2a 2a 20 3c 2f  EXCLUSIVE].** </
d750: 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53  ul>.**.** The [S
d760: 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54  QLITE_OPEN_DELET
d770: 45 4f 4e 43 4c 4f 53 45 5d 20 66 6c 61 67 20 6d  EONCLOSE] flag m
d780: 65 61 6e 73 20 74 68 65 20 66 69 6c 65 20 73 68  eans the file sh
d790: 6f 75 6c 64 20 62 65 0a 2a 2a 20 64 65 6c 65 74  ould be.** delet
d7a0: 65 64 20 77 68 65 6e 20 69 74 20 69 73 20 63 6c  ed when it is cl
d7b0: 6f 73 65 64 2e 20 20 5e 54 68 65 20 5b 53 51 4c  osed.  ^The [SQL
d7c0: 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f  ITE_OPEN_DELETEO
d7d0: 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 77 69 6c 6c 20  NCLOSE].** will 
d7e0: 62 65 20 73 65 74 20 66 6f 72 20 54 45 4d 50 20  be set for TEMP 
d7f0: 64 61 74 61 62 61 73 65 73 20 61 6e 64 20 74 68  databases and th
d800: 65 69 72 20 6a 6f 75 72 6e 61 6c 73 2c 20 74 72  eir journals, tr
d810: 61 6e 73 69 65 6e 74 0a 2a 2a 20 64 61 74 61 62  ansient.** datab
d820: 61 73 65 73 2c 20 61 6e 64 20 73 75 62 6a 6f 75  ases, and subjou
d830: 72 6e 61 6c 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  rnals..**.** ^Th
d840: 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45  e [SQLITE_OPEN_E
d850: 58 43 4c 55 53 49 56 45 5d 20 66 6c 61 67 20 69  XCLUSIVE] flag i
d860: 73 20 61 6c 77 61 79 73 20 75 73 65 64 20 69 6e  s always used in
d870: 20 63 6f 6e 6a 75 6e 63 74 69 6f 6e 0a 2a 2a 20   conjunction.** 
d880: 77 69 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45  with the [SQLITE
d890: 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 20 66 6c  _OPEN_CREATE] fl
d8a0: 61 67 2c 20 77 68 69 63 68 20 61 72 65 20 62 6f  ag, which are bo
d8b0: 74 68 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 61  th directly.** a
d8c0: 6e 61 6c 6f 67 6f 75 73 20 74 6f 20 74 68 65 20  nalogous to the 
d8d0: 4f 5f 45 58 43 4c 20 61 6e 64 20 4f 5f 43 52 45  O_EXCL and O_CRE
d8e0: 41 54 20 66 6c 61 67 73 20 6f 66 20 74 68 65 20  AT flags of the 
d8f0: 50 4f 53 49 58 20 6f 70 65 6e 28 29 0a 2a 2a 20  POSIX open().** 
d900: 41 50 49 2e 20 20 54 68 65 20 53 51 4c 49 54 45  API.  The SQLITE
d910: 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 20  _OPEN_EXCLUSIVE 
d920: 66 6c 61 67 2c 20 77 68 65 6e 20 70 61 69 72 65  flag, when paire
d930: 64 20 77 69 74 68 20 74 68 65 20 0a 2a 2a 20 53  d with the .** S
d940: 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54  QLITE_OPEN_CREAT
d950: 45 2c 20 69 73 20 75 73 65 64 20 74 6f 20 69 6e  E, is used to in
d960: 64 69 63 61 74 65 20 74 68 61 74 20 66 69 6c 65  dicate that file
d970: 20 73 68 6f 75 6c 64 20 61 6c 77 61 79 73 0a 2a   should always.*
d980: 2a 20 62 65 20 63 72 65 61 74 65 64 2c 20 61 6e  * be created, an
d990: 64 20 74 68 61 74 20 69 74 20 69 73 20 61 6e 20  d that it is an 
d9a0: 65 72 72 6f 72 20 69 66 20 69 74 20 61 6c 72 65  error if it alre
d9b0: 61 64 79 20 65 78 69 73 74 73 2e 0a 2a 2a 20 49  ady exists..** I
d9c0: 74 20 69 73 20 3c 69 3e 6e 6f 74 3c 2f 69 3e 20  t is <i>not</i> 
d9d0: 75 73 65 64 20 74 6f 20 69 6e 64 69 63 61 74 65  used to indicate
d9e0: 20 74 68 65 20 66 69 6c 65 20 73 68 6f 75 6c 64   the file should
d9f0: 20 62 65 20 6f 70 65 6e 65 64 20 0a 2a 2a 20 66   be opened .** f
da00: 6f 72 20 65 78 63 6c 75 73 69 76 65 20 61 63 63  or exclusive acc
da10: 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 74 20 6c  ess..**.** ^At l
da20: 65 61 73 74 20 73 7a 4f 73 46 69 6c 65 20 62 79  east szOsFile by
da30: 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 20 61 72  tes of memory ar
da40: 65 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 53  e allocated by S
da50: 51 4c 69 74 65 0a 2a 2a 20 74 6f 20 68 6f 6c 64  QLite.** to hold
da60: 20 74 68 65 20 20 5b 73 71 6c 69 74 65 33 5f 66   the  [sqlite3_f
da70: 69 6c 65 5d 20 73 74 72 75 63 74 75 72 65 20 70  ile] structure p
da80: 61 73 73 65 64 20 61 73 20 74 68 65 20 74 68 69  assed as the thi
da90: 72 64 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 74  rd.** argument t
daa0: 6f 20 78 4f 70 65 6e 2e 20 20 54 68 65 20 78 4f  o xOpen.  The xO
dab0: 70 65 6e 20 6d 65 74 68 6f 64 20 64 6f 65 73 20  pen method does 
dac0: 6e 6f 74 20 68 61 76 65 20 74 6f 0a 2a 2a 20 61  not have to.** a
dad0: 6c 6c 6f 63 61 74 65 20 74 68 65 20 73 74 72 75  llocate the stru
dae0: 63 74 75 72 65 3b 20 69 74 20 73 68 6f 75 6c 64  cture; it should
daf0: 20 6a 75 73 74 20 66 69 6c 6c 20 69 74 20 69 6e   just fill it in
db00: 2e 20 20 4e 6f 74 65 20 74 68 61 74 0a 2a 2a 20  .  Note that.** 
db10: 74 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64  the xOpen method
db20: 20 6d 75 73 74 20 73 65 74 20 74 68 65 20 73 71   must set the sq
db30: 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68  lite3_file.pMeth
db40: 6f 64 73 20 74 6f 20 65 69 74 68 65 72 0a 2a 2a  ods to either.**
db50: 20 61 20 76 61 6c 69 64 20 5b 73 71 6c 69 74 65   a valid [sqlite
db60: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62  3_io_methods] ob
db70: 6a 65 63 74 20 6f 72 20 74 6f 20 4e 55 4c 4c 2e  ject or to NULL.
db80: 20 20 78 4f 70 65 6e 20 6d 75 73 74 20 64 6f 0a    xOpen must do.
db90: 2a 2a 20 74 68 69 73 20 65 76 65 6e 20 69 66 20  ** this even if 
dba0: 74 68 65 20 6f 70 65 6e 20 66 61 69 6c 73 2e 20  the open fails. 
dbb0: 20 53 51 4c 69 74 65 20 65 78 70 65 63 74 73 20   SQLite expects 
dbc0: 74 68 61 74 20 74 68 65 20 73 71 6c 69 74 65 33  that the sqlite3
dbd0: 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 0a 2a  _file.pMethods.*
dbe0: 2a 20 65 6c 65 6d 65 6e 74 20 77 69 6c 6c 20 62  * element will b
dbf0: 65 20 76 61 6c 69 64 20 61 66 74 65 72 20 78 4f  e valid after xO
dc00: 70 65 6e 20 72 65 74 75 72 6e 73 20 72 65 67 61  pen returns rega
dc10: 72 64 6c 65 73 73 20 6f 66 20 74 68 65 20 73 75  rdless of the su
dc20: 63 63 65 73 73 0a 2a 2a 20 6f 72 20 66 61 69 6c  ccess.** or fail
dc30: 75 72 65 20 6f 66 20 74 68 65 20 78 4f 70 65 6e  ure of the xOpen
dc40: 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 73   call..**.** [[s
dc50: 71 6c 69 74 65 33 5f 76 66 73 2e 78 41 63 63 65  qlite3_vfs.xAcce
dc60: 73 73 5d 5d 0a 2a 2a 20 5e 54 68 65 20 66 6c 61  ss]].** ^The fla
dc70: 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78  gs argument to x
dc80: 41 63 63 65 73 73 28 29 20 6d 61 79 20 62 65 20  Access() may be 
dc90: 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45  [SQLITE_ACCESS_E
dca0: 58 49 53 54 53 5d 0a 2a 2a 20 74 6f 20 74 65 73  XISTS].** to tes
dcb0: 74 20 66 6f 72 20 74 68 65 20 65 78 69 73 74 65  t for the existe
dcc0: 6e 63 65 20 6f 66 20 61 20 66 69 6c 65 2c 20 6f  nce of a file, o
dcd0: 72 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53  r [SQLITE_ACCESS
dce0: 5f 52 45 41 44 57 52 49 54 45 5d 20 74 6f 0a 2a  _READWRITE] to.*
dcf0: 2a 20 74 65 73 74 20 77 68 65 74 68 65 72 20 61  * test whether a
dd00: 20 66 69 6c 65 20 69 73 20 72 65 61 64 61 62 6c   file is readabl
dd10: 65 20 61 6e 64 20 77 72 69 74 61 62 6c 65 2c 20  e and writable, 
dd20: 6f 72 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53  or [SQLITE_ACCES
dd30: 53 5f 52 45 41 44 5d 0a 2a 2a 20 74 6f 20 74 65  S_READ].** to te
dd40: 73 74 20 77 68 65 74 68 65 72 20 61 20 66 69 6c  st whether a fil
dd50: 65 20 69 73 20 61 74 20 6c 65 61 73 74 20 72 65  e is at least re
dd60: 61 64 61 62 6c 65 2e 20 20 20 54 68 65 20 66 69  adable.   The fi
dd70: 6c 65 20 63 61 6e 20 62 65 20 61 0a 2a 2a 20 64  le can be a.** d
dd80: 69 72 65 63 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20  irectory..**.** 
dd90: 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 77  ^SQLite will alw
dda0: 61 79 73 20 61 6c 6c 6f 63 61 74 65 20 61 74 20  ays allocate at 
ddb0: 6c 65 61 73 74 20 6d 78 50 61 74 68 6e 61 6d 65  least mxPathname
ddc0: 2b 31 20 62 79 74 65 73 20 66 6f 72 20 74 68 65  +1 bytes for the
ddd0: 0a 2a 2a 20 6f 75 74 70 75 74 20 62 75 66 66 65  .** output buffe
dde0: 72 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 2e  r xFullPathname.
ddf0: 20 20 54 68 65 20 65 78 61 63 74 20 73 69 7a 65    The exact size
de00: 20 6f 66 20 74 68 65 20 6f 75 74 70 75 74 20 62   of the output b
de10: 75 66 66 65 72 0a 2a 2a 20 69 73 20 61 6c 73 6f  uffer.** is also
de20: 20 70 61 73 73 65 64 20 61 73 20 61 20 70 61 72   passed as a par
de30: 61 6d 65 74 65 72 20 74 6f 20 62 6f 74 68 20 20  ameter to both  
de40: 6d 65 74 68 6f 64 73 2e 20 49 66 20 74 68 65 20  methods. If the 
de50: 6f 75 74 70 75 74 20 62 75 66 66 65 72 0a 2a 2a  output buffer.**
de60: 20 69 73 20 6e 6f 74 20 6c 61 72 67 65 20 65 6e   is not large en
de70: 6f 75 67 68 2c 20 5b 53 51 4c 49 54 45 5f 43 41  ough, [SQLITE_CA
de80: 4e 54 4f 50 45 4e 5d 20 73 68 6f 75 6c 64 20 62  NTOPEN] should b
de90: 65 20 72 65 74 75 72 6e 65 64 2e 20 53 69 6e 63  e returned. Sinc
dea0: 65 20 74 68 69 73 20 69 73 0a 2a 2a 20 68 61 6e  e this is.** han
deb0: 64 6c 65 64 20 61 73 20 61 20 66 61 74 61 6c 20  dled as a fatal 
dec0: 65 72 72 6f 72 20 62 79 20 53 51 4c 69 74 65 2c  error by SQLite,
ded0: 20 76 66 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74   vfs implementat
dee0: 69 6f 6e 73 20 73 68 6f 75 6c 64 20 65 6e 64 65  ions should ende
def0: 61 76 6f 72 0a 2a 2a 20 74 6f 20 70 72 65 76 65  avor.** to preve
df00: 6e 74 20 74 68 69 73 20 62 79 20 73 65 74 74 69  nt this by setti
df10: 6e 67 20 6d 78 50 61 74 68 6e 61 6d 65 20 74 6f  ng mxPathname to
df20: 20 61 20 73 75 66 66 69 63 69 65 6e 74 6c 79 20   a sufficiently 
df30: 6c 61 72 67 65 20 76 61 6c 75 65 2e 0a 2a 2a 0a  large value..**.
df40: 2a 2a 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65  ** The xRandomne
df50: 73 73 28 29 2c 20 78 53 6c 65 65 70 28 29 2c 20  ss(), xSleep(), 
df60: 78 43 75 72 72 65 6e 74 54 69 6d 65 28 29 2c 20  xCurrentTime(), 
df70: 61 6e 64 20 78 43 75 72 72 65 6e 74 54 69 6d 65  and xCurrentTime
df80: 49 6e 74 36 34 28 29 0a 2a 2a 20 69 6e 74 65 72  Int64().** inter
df90: 66 61 63 65 73 20 61 72 65 20 6e 6f 74 20 73 74  faces are not st
dfa0: 72 69 63 74 6c 79 20 61 20 70 61 72 74 20 6f 66  rictly a part of
dfb0: 20 74 68 65 20 66 69 6c 65 73 79 73 74 65 6d 2c   the filesystem,
dfc0: 20 62 75 74 20 74 68 65 79 20 61 72 65 0a 2a 2a   but they are.**
dfd0: 20 69 6e 63 6c 75 64 65 64 20 69 6e 20 74 68 65   included in the
dfe0: 20 56 46 53 20 73 74 72 75 63 74 75 72 65 20 66   VFS structure f
dff0: 6f 72 20 63 6f 6d 70 6c 65 74 65 6e 65 73 73 2e  or completeness.
e000: 0a 2a 2a 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e  .** The xRandomn
e010: 65 73 73 28 29 20 66 75 6e 63 74 69 6f 6e 20 61  ess() function a
e020: 74 74 65 6d 70 74 73 20 74 6f 20 72 65 74 75 72  ttempts to retur
e030: 6e 20 6e 42 79 74 65 73 20 62 79 74 65 73 0a 2a  n nBytes bytes.*
e040: 2a 20 6f 66 20 67 6f 6f 64 2d 71 75 61 6c 69 74  * of good-qualit
e050: 79 20 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74  y randomness int
e060: 6f 20 7a 4f 75 74 2e 20 20 54 68 65 20 72 65 74  o zOut.  The ret
e070: 75 72 6e 20 76 61 6c 75 65 20 69 73 0a 2a 2a 20  urn value is.** 
e080: 74 68 65 20 61 63 74 75 61 6c 20 6e 75 6d 62 65  the actual numbe
e090: 72 20 6f 66 20 62 79 74 65 73 20 6f 66 20 72 61  r of bytes of ra
e0a0: 6e 64 6f 6d 6e 65 73 73 20 6f 62 74 61 69 6e 65  ndomness obtaine
e0b0: 64 2e 0a 2a 2a 20 54 68 65 20 78 53 6c 65 65 70  d..** The xSleep
e0c0: 28 29 20 6d 65 74 68 6f 64 20 63 61 75 73 65 73  () method causes
e0d0: 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 74 68 72   the calling thr
e0e0: 65 61 64 20 74 6f 20 73 6c 65 65 70 20 66 6f 72  ead to sleep for
e0f0: 20 61 74 0a 2a 2a 20 6c 65 61 73 74 20 74 68 65   at.** least the
e100: 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 63 72 6f   number of micro
e110: 73 65 63 6f 6e 64 73 20 67 69 76 65 6e 2e 20 20  seconds given.  
e120: 5e 54 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d  ^The xCurrentTim
e130: 65 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 72 65  e().** method re
e140: 74 75 72 6e 73 20 61 20 4a 75 6c 69 61 6e 20 44  turns a Julian D
e150: 61 79 20 4e 75 6d 62 65 72 20 66 6f 72 20 74 68  ay Number for th
e160: 65 20 63 75 72 72 65 6e 74 20 64 61 74 65 20 61  e current date a
e170: 6e 64 20 74 69 6d 65 20 61 73 0a 2a 2a 20 61 20  nd time as.** a 
e180: 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76  floating point v
e190: 61 6c 75 65 2e 0a 2a 2a 20 5e 54 68 65 20 78 43  alue..** ^The xC
e1a0: 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28  urrentTimeInt64(
e1b0: 29 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73  ) method returns
e1c0: 2c 20 61 73 20 61 6e 20 69 6e 74 65 67 65 72 2c  , as an integer,
e1d0: 20 74 68 65 20 4a 75 6c 69 61 6e 0a 2a 2a 20 44   the Julian.** D
e1e0: 61 79 20 4e 75 6d 62 65 72 20 6d 75 6c 74 69 70  ay Number multip
e1f0: 6c 69 65 64 20 62 79 20 38 36 34 30 30 30 30 30  lied by 86400000
e200: 20 28 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20   (the number of 
e210: 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 69 6e 20  milliseconds in 
e220: 0a 2a 2a 20 61 20 32 34 2d 68 6f 75 72 20 64 61  .** a 24-hour da
e230: 79 29 2e 20 20 0a 2a 2a 20 5e 53 51 4c 69 74 65  y).  .** ^SQLite
e240: 20 77 69 6c 6c 20 75 73 65 20 74 68 65 20 78 43   will use the xC
e250: 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28  urrentTimeInt64(
e260: 29 20 6d 65 74 68 6f 64 20 74 6f 20 67 65 74 20  ) method to get 
e270: 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 64  the current.** d
e280: 61 74 65 20 61 6e 64 20 74 69 6d 65 20 69 66 20  ate and time if 
e290: 74 68 61 74 20 6d 65 74 68 6f 64 20 69 73 20 61  that method is a
e2a0: 76 61 69 6c 61 62 6c 65 20 28 69 66 20 69 56 65  vailable (if iVe
e2b0: 72 73 69 6f 6e 20 69 73 20 32 20 6f 72 20 0a 2a  rsion is 2 or .*
e2c0: 2a 20 67 72 65 61 74 65 72 20 61 6e 64 20 74 68  * greater and th
e2d0: 65 20 66 75 6e 63 74 69 6f 6e 20 70 6f 69 6e 74  e function point
e2e0: 65 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 29 20  er is not NULL) 
e2f0: 61 6e 64 20 77 69 6c 6c 20 66 61 6c 6c 20 62 61  and will fall ba
e300: 63 6b 0a 2a 2a 20 74 6f 20 78 43 75 72 72 65 6e  ck.** to xCurren
e310: 74 54 69 6d 65 28 29 20 69 66 20 78 43 75 72 72  tTime() if xCurr
e320: 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 20 69  entTimeInt64() i
e330: 73 20 75 6e 61 76 61 69 6c 61 62 6c 65 2e 0a 2a  s unavailable..*
e340: 2a 0a 2a 2a 20 5e 54 68 65 20 78 53 65 74 53 79  *.** ^The xSetSy
e350: 73 74 65 6d 43 61 6c 6c 28 29 2c 20 78 47 65 74  stemCall(), xGet
e360: 53 79 73 74 65 6d 43 61 6c 6c 28 29 2c 20 61 6e  SystemCall(), an
e370: 64 20 78 4e 65 73 74 53 79 73 74 65 6d 43 61 6c  d xNestSystemCal
e380: 6c 28 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a  l() interfaces.*
e390: 2a 20 61 72 65 20 6e 6f 74 20 75 73 65 64 20 62  * are not used b
e3a0: 79 20 74 68 65 20 53 51 4c 69 74 65 20 63 6f 72  y the SQLite cor
e3b0: 65 2e 20 20 54 68 65 73 65 20 6f 70 74 69 6f 6e  e.  These option
e3c0: 61 6c 20 69 6e 74 65 72 66 61 63 65 73 20 61 72  al interfaces ar
e3d0: 65 20 70 72 6f 76 69 64 65 64 0a 2a 2a 20 62 79  e provided.** by
e3e0: 20 73 6f 6d 65 20 56 46 53 65 73 20 74 6f 20 66   some VFSes to f
e3f0: 61 63 69 6c 69 74 61 74 65 20 74 65 73 74 69 6e  acilitate testin
e400: 67 20 6f 66 20 74 68 65 20 56 46 53 20 63 6f 64  g of the VFS cod
e410: 65 2e 20 42 79 20 6f 76 65 72 72 69 64 69 6e 67  e. By overriding
e420: 20 0a 2a 2a 20 73 79 73 74 65 6d 20 63 61 6c 6c   .** system call
e430: 73 20 77 69 74 68 20 66 75 6e 63 74 69 6f 6e 73  s with functions
e440: 20 75 6e 64 65 72 20 69 74 73 20 63 6f 6e 74 72   under its contr
e450: 6f 6c 2c 20 61 20 74 65 73 74 20 70 72 6f 67 72  ol, a test progr
e460: 61 6d 20 63 61 6e 0a 2a 2a 20 73 69 6d 75 6c 61  am can.** simula
e470: 74 65 20 66 61 75 6c 74 73 20 61 6e 64 20 65 72  te faults and er
e480: 72 6f 72 20 63 6f 6e 64 69 74 69 6f 6e 73 20 74  ror conditions t
e490: 68 61 74 20 77 6f 75 6c 64 20 6f 74 68 65 72 77  hat would otherw
e4a0: 69 73 65 20 62 65 20 64 69 66 66 69 63 75 6c 74  ise be difficult
e4b0: 0a 2a 2a 20 6f 72 20 69 6d 70 6f 73 73 69 62 6c  .** or impossibl
e4c0: 65 20 74 6f 20 69 6e 64 75 63 65 2e 20 20 54 68  e to induce.  Th
e4d0: 65 20 73 65 74 20 6f 66 20 73 79 73 74 65 6d 20  e set of system 
e4e0: 63 61 6c 6c 73 20 74 68 61 74 20 63 61 6e 20 62  calls that can b
e4f0: 65 20 6f 76 65 72 72 69 64 64 65 6e 0a 2a 2a 20  e overridden.** 
e500: 76 61 72 69 65 73 20 66 72 6f 6d 20 6f 6e 65 20  varies from one 
e510: 56 46 53 20 74 6f 20 61 6e 6f 74 68 65 72 2c 20  VFS to another, 
e520: 61 6e 64 20 66 72 6f 6d 20 6f 6e 65 20 76 65 72  and from one ver
e530: 73 69 6f 6e 20 6f 66 20 74 68 65 20 73 61 6d 65  sion of the same
e540: 20 56 46 53 20 74 6f 20 74 68 65 0a 2a 2a 20 6e   VFS to the.** n
e550: 65 78 74 2e 20 20 41 70 70 6c 69 63 61 74 69 6f  ext.  Applicatio
e560: 6e 73 20 74 68 61 74 20 75 73 65 20 74 68 65 73  ns that use thes
e570: 65 20 69 6e 74 65 72 66 61 63 65 73 20 6d 75 73  e interfaces mus
e580: 74 20 62 65 20 70 72 65 70 61 72 65 64 20 66 6f  t be prepared fo
e590: 72 20 61 6e 79 0a 2a 2a 20 6f 72 20 61 6c 6c 20  r any.** or all 
e5a0: 6f 66 20 74 68 65 73 65 20 69 6e 74 65 72 66 61  of these interfa
e5b0: 63 65 73 20 74 6f 20 62 65 20 4e 55 4c 4c 20 6f  ces to be NULL o
e5c0: 72 20 66 6f 72 20 74 68 65 69 72 20 62 65 68 61  r for their beha
e5d0: 76 69 6f 72 20 74 6f 20 63 68 61 6e 67 65 0a 2a  vior to change.*
e5e0: 2a 20 66 72 6f 6d 20 6f 6e 65 20 72 65 6c 65 61  * from one relea
e5f0: 73 65 20 74 6f 20 74 68 65 20 6e 65 78 74 2e 20  se to the next. 
e600: 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 6d 75   Applications mu
e610: 73 74 20 6e 6f 74 20 61 74 74 65 6d 70 74 20 74  st not attempt t
e620: 6f 20 61 63 63 65 73 73 0a 2a 2a 20 61 6e 79 20  o access.** any 
e630: 6f 66 20 74 68 65 73 65 20 6d 65 74 68 6f 64 73  of these methods
e640: 20 69 66 20 74 68 65 20 69 56 65 72 73 69 6f 6e   if the iVersion
e650: 20 6f 66 20 74 68 65 20 56 46 53 20 69 73 20 6c   of the VFS is l
e660: 65 73 73 20 74 68 61 6e 20 33 2e 0a 2a 2f 0a 74  ess than 3..*/.t
e670: 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71  ypedef struct sq
e680: 6c 69 74 65 33 5f 76 66 73 20 73 71 6c 69 74 65  lite3_vfs sqlite
e690: 33 5f 76 66 73 3b 0a 74 79 70 65 64 65 66 20 76  3_vfs;.typedef v
e6a0: 6f 69 64 20 28 2a 73 71 6c 69 74 65 33 5f 73 79  oid (*sqlite3_sy
e6b0: 73 63 61 6c 6c 5f 70 74 72 29 28 76 6f 69 64 29  scall_ptr)(void)
e6c0: 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  ;.struct sqlite3
e6d0: 5f 76 66 73 20 7b 0a 20 20 69 6e 74 20 69 56 65  _vfs {.  int iVe
e6e0: 72 73 69 6f 6e 3b 20 20 20 20 20 20 20 20 20 20  rsion;          
e6f0: 20 20 2f 2a 20 53 74 72 75 63 74 75 72 65 20 76    /* Structure v
e700: 65 72 73 69 6f 6e 20 6e 75 6d 62 65 72 20 28 63  ersion number (c
e710: 75 72 72 65 6e 74 6c 79 20 33 29 20 2a 2f 0a 20  urrently 3) */. 
e720: 20 69 6e 74 20 73 7a 4f 73 46 69 6c 65 3b 20 20   int szOsFile;  
e730: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53 69 7a            /* Siz
e740: 65 20 6f 66 20 73 75 62 63 6c 61 73 73 65 64 20  e of subclassed 
e750: 73 71 6c 69 74 65 33 5f 66 69 6c 65 20 2a 2f 0a  sqlite3_file */.
e760: 20 20 69 6e 74 20 6d 78 50 61 74 68 6e 61 6d 65    int mxPathname
e770: 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61  ;          /* Ma
e780: 78 69 6d 75 6d 20 66 69 6c 65 20 70 61 74 68 6e  ximum file pathn
e790: 61 6d 65 20 6c 65 6e 67 74 68 20 2a 2f 0a 20 20  ame length */.  
e7a0: 73 71 6c 69 74 65 33 5f 76 66 73 20 2a 70 4e 65  sqlite3_vfs *pNe
e7b0: 78 74 3b 20 20 20 20 20 20 2f 2a 20 4e 65 78 74  xt;      /* Next
e7c0: 20 72 65 67 69 73 74 65 72 65 64 20 56 46 53 20   registered VFS 
e7d0: 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  */.  const char 
e7e0: 2a 7a 4e 61 6d 65 3b 20 20 20 20 20 20 20 2f 2a  *zName;       /*
e7f0: 20 4e 61 6d 65 20 6f 66 20 74 68 69 73 20 76 69   Name of this vi
e800: 72 74 75 61 6c 20 66 69 6c 65 20 73 79 73 74 65  rtual file syste
e810: 6d 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 41 70  m */.  void *pAp
e820: 70 44 61 74 61 3b 20 20 20 20 20 20 20 20 20 20  pData;          
e830: 2f 2a 20 50 6f 69 6e 74 65 72 20 74 6f 20 61 70  /* Pointer to ap
e840: 70 6c 69 63 61 74 69 6f 6e 2d 73 70 65 63 69 66  plication-specif
e850: 69 63 20 64 61 74 61 20 2a 2f 0a 20 20 69 6e 74  ic data */.  int
e860: 20 28 2a 78 4f 70 65 6e 29 28 73 71 6c 69 74 65   (*xOpen)(sqlite
e870: 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68  3_vfs*, const ch
e880: 61 72 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69 74  ar *zName, sqlit
e890: 65 33 5f 66 69 6c 65 2a 2c 0a 20 20 20 20 20 20  e3_file*,.      
e8a0: 20 20 20 20 20 20 20 20 20 69 6e 74 20 66 6c 61           int fla
e8b0: 67 73 2c 20 69 6e 74 20 2a 70 4f 75 74 46 6c 61  gs, int *pOutFla
e8c0: 67 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65  gs);.  int (*xDe
e8d0: 6c 65 74 65 29 28 73 71 6c 69 74 65 33 5f 76 66  lete)(sqlite3_vf
e8e0: 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  s*, const char *
e8f0: 7a 4e 61 6d 65 2c 20 69 6e 74 20 73 79 6e 63 44  zName, int syncD
e900: 69 72 29 3b 0a 20 20 69 6e 74 20 28 2a 78 41 63  ir);.  int (*xAc
e910: 63 65 73 73 29 28 73 71 6c 69 74 65 33 5f 76 66  cess)(sqlite3_vf
e920: 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  s*, const char *
e930: 7a 4e 61 6d 65 2c 20 69 6e 74 20 66 6c 61 67 73  zName, int flags
e940: 2c 20 69 6e 74 20 2a 70 52 65 73 4f 75 74 29 3b  , int *pResOut);
e950: 0a 20 20 69 6e 74 20 28 2a 78 46 75 6c 6c 50 61  .  int (*xFullPa
e960: 74 68 6e 61 6d 65 29 28 73 71 6c 69 74 65 33 5f  thname)(sqlite3_
e970: 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  vfs*, const char
e980: 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 6e 4f 75   *zName, int nOu
e990: 74 2c 20 63 68 61 72 20 2a 7a 4f 75 74 29 3b 0a  t, char *zOut);.
e9a0: 20 20 76 6f 69 64 20 2a 28 2a 78 44 6c 4f 70 65    void *(*xDlOpe
e9b0: 6e 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  n)(sqlite3_vfs*,
e9c0: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 69   const char *zFi
e9d0: 6c 65 6e 61 6d 65 29 3b 0a 20 20 76 6f 69 64 20  lename);.  void 
e9e0: 28 2a 78 44 6c 45 72 72 6f 72 29 28 73 71 6c 69  (*xDlError)(sqli
e9f0: 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6e 42  te3_vfs*, int nB
ea00: 79 74 65 2c 20 63 68 61 72 20 2a 7a 45 72 72 4d  yte, char *zErrM
ea10: 73 67 29 3b 0a 20 20 76 6f 69 64 20 28 2a 28 2a  sg);.  void (*(*
ea20: 78 44 6c 53 79 6d 29 28 73 71 6c 69 74 65 33 5f  xDlSym)(sqlite3_
ea30: 76 66 73 2a 2c 76 6f 69 64 2a 2c 20 63 6f 6e 73  vfs*,void*, cons
ea40: 74 20 63 68 61 72 20 2a 7a 53 79 6d 62 6f 6c 29  t char *zSymbol)
ea50: 29 28 76 6f 69 64 29 3b 0a 20 20 76 6f 69 64 20  )(void);.  void 
ea60: 28 2a 78 44 6c 43 6c 6f 73 65 29 28 73 71 6c 69  (*xDlClose)(sqli
ea70: 74 65 33 5f 76 66 73 2a 2c 20 76 6f 69 64 2a 29  te3_vfs*, void*)
ea80: 3b 0a 20 20 69 6e 74 20 28 2a 78 52 61 6e 64 6f  ;.  int (*xRando
ea90: 6d 6e 65 73 73 29 28 73 71 6c 69 74 65 33 5f 76  mness)(sqlite3_v
eaa0: 66 73 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20  fs*, int nByte, 
eab0: 63 68 61 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 69  char *zOut);.  i
eac0: 6e 74 20 28 2a 78 53 6c 65 65 70 29 28 73 71 6c  nt (*xSleep)(sql
ead0: 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6d  ite3_vfs*, int m
eae0: 69 63 72 6f 73 65 63 6f 6e 64 73 29 3b 0a 20 20  icroseconds);.  
eaf0: 69 6e 74 20 28 2a 78 43 75 72 72 65 6e 74 54 69  int (*xCurrentTi
eb00: 6d 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  me)(sqlite3_vfs*
eb10: 2c 20 64 6f 75 62 6c 65 2a 29 3b 0a 20 20 69 6e  , double*);.  in
eb20: 74 20 28 2a 78 47 65 74 4c 61 73 74 45 72 72 6f  t (*xGetLastErro
eb30: 72 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  r)(sqlite3_vfs*,
eb40: 20 69 6e 74 2c 20 63 68 61 72 20 2a 29 3b 0a 20   int, char *);. 
eb50: 20 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74   /*.  ** The met
eb60: 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 69  hods above are i
eb70: 6e 20 76 65 72 73 69 6f 6e 20 31 20 6f 66 20 74  n version 1 of t
eb80: 68 65 20 73 71 6c 69 74 65 5f 76 66 73 20 6f 62  he sqlite_vfs ob
eb90: 6a 65 63 74 0a 20 20 2a 2a 20 64 65 66 69 6e 69  ject.  ** defini
eba0: 74 69 6f 6e 2e 20 20 54 68 6f 73 65 20 74 68 61  tion.  Those tha
ebb0: 74 20 66 6f 6c 6c 6f 77 20 61 72 65 20 61 64 64  t follow are add
ebc0: 65 64 20 69 6e 20 76 65 72 73 69 6f 6e 20 32 20  ed in version 2 
ebd0: 6f 72 20 6c 61 74 65 72 0a 20 20 2a 2f 0a 20 20  or later.  */.  
ebe0: 69 6e 74 20 28 2a 78 43 75 72 72 65 6e 74 54 69  int (*xCurrentTi
ebf0: 6d 65 49 6e 74 36 34 29 28 73 71 6c 69 74 65 33  meInt64)(sqlite3
ec00: 5f 76 66 73 2a 2c 20 73 71 6c 69 74 65 33 5f 69  _vfs*, sqlite3_i
ec10: 6e 74 36 34 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a  nt64*);.  /*.  *
ec20: 2a 20 54 68 65 20 6d 65 74 68 6f 64 73 20 61 62  * The methods ab
ec30: 6f 76 65 20 61 72 65 20 69 6e 20 76 65 72 73 69  ove are in versi
ec40: 6f 6e 73 20 31 20 61 6e 64 20 32 20 6f 66 20 74  ons 1 and 2 of t
ec50: 68 65 20 73 71 6c 69 74 65 5f 76 66 73 20 6f 62  he sqlite_vfs ob
ec60: 6a 65 63 74 2e 0a 20 20 2a 2a 20 54 68 6f 73 65  ject..  ** Those
ec70: 20 62 65 6c 6f 77 20 61 72 65 20 66 6f 72 20 76   below are for v
ec80: 65 72 73 69 6f 6e 20 33 20 61 6e 64 20 67 72 65  ersion 3 and gre
ec90: 61 74 65 72 2e 0a 20 20 2a 2f 0a 20 20 69 6e 74  ater..  */.  int
eca0: 20 28 2a 78 53 65 74 53 79 73 74 65 6d 43 61 6c   (*xSetSystemCal
ecb0: 6c 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  l)(sqlite3_vfs*,
ecc0: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61   const char *zNa
ecd0: 6d 65 2c 20 73 71 6c 69 74 65 33 5f 73 79 73 63  me, sqlite3_sysc
ece0: 61 6c 6c 5f 70 74 72 29 3b 0a 20 20 73 71 6c 69  all_ptr);.  sqli
ecf0: 74 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72 20  te3_syscall_ptr 
ed00: 28 2a 78 47 65 74 53 79 73 74 65 6d 43 61 6c 6c  (*xGetSystemCall
ed10: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
ed20: 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
ed30: 65 29 3b 0a 20 20 63 6f 6e 73 74 20 63 68 61 72  e);.  const char
ed40: 20 2a 28 2a 78 4e 65 78 74 53 79 73 74 65 6d 43   *(*xNextSystemC
ed50: 61 6c 6c 29 28 73 71 6c 69 74 65 33 5f 76 66 73  all)(sqlite3_vfs
ed60: 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  *, const char *z
ed70: 4e 61 6d 65 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a  Name);.  /*.  **
ed80: 20 54 68 65 20 6d 65 74 68 6f 64 73 20 61 62 6f   The methods abo
ed90: 76 65 20 61 72 65 20 69 6e 20 76 65 72 73 69 6f  ve are in versio
eda0: 6e 73 20 31 20 74 68 72 6f 75 67 68 20 33 20 6f  ns 1 through 3 o
edb0: 66 20 74 68 65 20 73 71 6c 69 74 65 5f 76 66 73  f the sqlite_vfs
edc0: 20 6f 62 6a 65 63 74 2e 0a 20 20 2a 2a 20 4e 65   object..  ** Ne
edd0: 77 20 66 69 65 6c 64 73 20 6d 61 79 20 62 65 20  w fields may be 
ede0: 61 70 70 65 6e 64 65 64 20 69 6e 20 66 75 74 75  appended in futu
edf0: 72 65 20 76 65 72 73 69 6f 6e 73 2e 20 20 54 68  re versions.  Th
ee00: 65 20 69 56 65 72 73 69 6f 6e 0a 20 20 2a 2a 20  e iVersion.  ** 
ee10: 76 61 6c 75 65 20 77 69 6c 6c 20 69 6e 63 72 65  value will incre
ee20: 6d 65 6e 74 20 77 68 65 6e 65 76 65 72 20 74 68  ment whenever th
ee30: 69 73 20 68 61 70 70 65 6e 73 2e 20 0a 20 20 2a  is happens. .  *
ee40: 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  /.};../*.** CAPI
ee50: 33 52 45 46 3a 20 46 6c 61 67 73 20 66 6f 72 20  3REF: Flags for 
ee60: 74 68 65 20 78 41 63 63 65 73 73 20 56 46 53 20  the xAccess VFS 
ee70: 6d 65 74 68 6f 64 0a 2a 2a 0a 2a 2a 20 54 68 65  method.**.** The
ee80: 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74  se integer const
ee90: 61 6e 74 73 20 63 61 6e 20 62 65 20 75 73 65 64  ants can be used
eea0: 20 61 73 20 74 68 65 20 74 68 69 72 64 20 70 61   as the third pa
eeb0: 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 74 68  rameter to.** th
eec0: 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64  e xAccess method
eed0: 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f   of an [sqlite3_
eee0: 76 66 73 5d 20 6f 62 6a 65 63 74 2e 20 20 54 68  vfs] object.  Th
eef0: 65 79 20 64 65 74 65 72 6d 69 6e 65 0a 2a 2a 20  ey determine.** 
ef00: 77 68 61 74 20 6b 69 6e 64 20 6f 66 20 70 65 72  what kind of per
ef10: 6d 69 73 73 69 6f 6e 73 20 74 68 65 20 78 41 63  missions the xAc
ef20: 63 65 73 73 20 6d 65 74 68 6f 64 20 69 73 20 6c  cess method is l
ef30: 6f 6f 6b 69 6e 67 20 66 6f 72 2e 0a 2a 2a 20 57  ooking for..** W
ef40: 69 74 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53  ith SQLITE_ACCES
ef50: 53 5f 45 58 49 53 54 53 2c 20 74 68 65 20 78 41  S_EXISTS, the xA
ef60: 63 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20  ccess method.** 
ef70: 73 69 6d 70 6c 79 20 63 68 65 63 6b 73 20 77 68  simply checks wh
ef80: 65 74 68 65 72 20 74 68 65 20 66 69 6c 65 20 65  ether the file e
ef90: 78 69 73 74 73 2e 0a 2a 2a 20 57 69 74 68 20 53  xists..** With S
efa0: 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41  QLITE_ACCESS_REA
efb0: 44 57 52 49 54 45 2c 20 74 68 65 20 78 41 63 63  DWRITE, the xAcc
efc0: 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 63 68  ess method.** ch
efd0: 65 63 6b 73 20 77 68 65 74 68 65 72 20 74 68 65  ecks whether the
efe0: 20 6e 61 6d 65 64 20 64 69 72 65 63 74 6f 72 79   named directory
eff0: 20 69 73 20 62 6f 74 68 20 72 65 61 64 61 62 6c   is both readabl
f000: 65 20 61 6e 64 20 77 72 69 74 61 62 6c 65 0a 2a  e and writable.*
f010: 2a 20 28 69 6e 20 6f 74 68 65 72 20 77 6f 72 64  * (in other word
f020: 73 2c 20 69 66 20 66 69 6c 65 73 20 63 61 6e 20  s, if files can 
f030: 62 65 20 61 64 64 65 64 2c 20 72 65 6d 6f 76 65  be added, remove
f040: 64 2c 20 61 6e 64 20 72 65 6e 61 6d 65 64 20 77  d, and renamed w
f050: 69 74 68 69 6e 0a 2a 2a 20 74 68 65 20 64 69 72  ithin.** the dir
f060: 65 63 74 6f 72 79 29 2e 0a 2a 2a 20 54 68 65 20  ectory)..** The 
f070: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45  SQLITE_ACCESS_RE
f080: 41 44 57 52 49 54 45 20 63 6f 6e 73 74 61 6e 74  ADWRITE constant
f090: 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20 75 73   is currently us
f0a0: 65 64 20 6f 6e 6c 79 20 62 79 20 74 68 65 0a 2a  ed only by the.*
f0b0: 2a 20 5b 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69  * [temp_store_di
f0c0: 72 65 63 74 6f 72 79 20 70 72 61 67 6d 61 5d 2c  rectory pragma],
f0d0: 20 74 68 6f 75 67 68 20 74 68 69 73 20 63 6f 75   though this cou
f0e0: 6c 64 20 63 68 61 6e 67 65 20 69 6e 20 61 20 66  ld change in a f
f0f0: 75 74 75 72 65 0a 2a 2a 20 72 65 6c 65 61 73 65  uture.** release
f100: 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 57   of SQLite..** W
f110: 69 74 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53  ith SQLITE_ACCES
f120: 53 5f 52 45 41 44 2c 20 74 68 65 20 78 41 63 63  S_READ, the xAcc
f130: 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 63 68  ess method.** ch
f140: 65 63 6b 73 20 77 68 65 74 68 65 72 20 74 68 65  ecks whether the
f150: 20 66 69 6c 65 20 69 73 20 72 65 61 64 61 62 6c   file is readabl
f160: 65 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 41  e.  The SQLITE_A
f170: 43 43 45 53 53 5f 52 45 41 44 20 63 6f 6e 73 74  CCESS_READ const
f180: 61 6e 74 20 69 73 0a 2a 2a 20 63 75 72 72 65 6e  ant is.** curren
f190: 74 6c 79 20 75 6e 75 73 65 64 2c 20 74 68 6f 75  tly unused, thou
f1a0: 67 68 20 69 74 20 6d 69 67 68 74 20 62 65 20 75  gh it might be u
f1b0: 73 65 64 20 69 6e 20 61 20 66 75 74 75 72 65 20  sed in a future 
f1c0: 72 65 6c 65 61 73 65 20 6f 66 0a 2a 2a 20 53 51  release of.** SQ
f1d0: 4c 69 74 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65  Lite..*/.#define
f1e0: 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45   SQLITE_ACCESS_E
f1f0: 58 49 53 54 53 20 20 20 20 30 0a 23 64 65 66 69  XISTS    0.#defi
f200: 6e 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53  ne SQLITE_ACCESS
f210: 5f 52 45 41 44 57 52 49 54 45 20 31 20 20 20 2f  _READWRITE 1   /
f220: 2a 20 55 73 65 64 20 62 79 20 50 52 41 47 4d 41  * Used by PRAGMA
f230: 20 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65   temp_store_dire
f240: 63 74 6f 72 79 20 2a 2f 0a 23 64 65 66 69 6e 65  ctory */.#define
f250: 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52   SQLITE_ACCESS_R
f260: 45 41 44 20 20 20 20 20 20 32 20 20 20 2f 2a 20  EAD      2   /* 
f270: 55 6e 75 73 65 64 20 2a 2f 0a 0a 2f 2a 0a 2a 2a  Unused */../*.**
f280: 20 43 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73   CAPI3REF: Flags
f290: 20 66 6f 72 20 74 68 65 20 78 53 68 6d 4c 6f 63   for the xShmLoc
f2a0: 6b 20 56 46 53 20 6d 65 74 68 6f 64 0a 2a 2a 0a  k VFS method.**.
f2b0: 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 67 65 72  ** These integer
f2c0: 20 63 6f 6e 73 74 61 6e 74 73 20 64 65 66 69 6e   constants defin
f2d0: 65 20 74 68 65 20 76 61 72 69 6f 75 73 20 6c 6f  e the various lo
f2e0: 63 6b 69 6e 67 20 6f 70 65 72 61 74 69 6f 6e 73  cking operations
f2f0: 0a 2a 2a 20 61 6c 6c 6f 77 65 64 20 62 79 20 74  .** allowed by t
f300: 68 65 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68  he xShmLock meth
f310: 6f 64 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 69  od of [sqlite3_i
f320: 6f 5f 6d 65 74 68 6f 64 73 5d 2e 20 20 54 68 65  o_methods].  The
f330: 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 72  .** following ar
f340: 65 20 74 68 65 20 6f 6e 6c 79 20 6c 65 67 61 6c  e the only legal
f350: 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 73 20 6f 66   combinations of
f360: 20 66 6c 61 67 73 20 74 6f 20 74 68 65 0a 2a 2a   flags to the.**
f370: 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64   xShmLock method
f380: 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  :.**.** <ul>.** 
f390: 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d  <li>  SQLITE_SHM
f3a0: 5f 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53  _LOCK | SQLITE_S
f3b0: 48 4d 5f 53 48 41 52 45 44 0a 2a 2a 20 3c 6c 69  HM_SHARED.** <li
f3c0: 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f  >  SQLITE_SHM_LO
f3d0: 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f  CK | SQLITE_SHM_
f3e0: 45 58 43 4c 55 53 49 56 45 0a 2a 2a 20 3c 6c 69  EXCLUSIVE.** <li
f3f0: 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e  >  SQLITE_SHM_UN
f400: 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48  LOCK | SQLITE_SH
f410: 4d 5f 53 48 41 52 45 44 0a 2a 2a 20 3c 6c 69 3e  M_SHARED.** <li>
f420: 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c    SQLITE_SHM_UNL
f430: 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d  OCK | SQLITE_SHM
f440: 5f 45 58 43 4c 55 53 49 56 45 0a 2a 2a 20 3c 2f  _EXCLUSIVE.** </
f450: 75 6c 3e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 75  ul>.**.** When u
f460: 6e 6c 6f 63 6b 69 6e 67 2c 20 74 68 65 20 73 61  nlocking, the sa
f470: 6d 65 20 53 48 41 52 45 44 20 6f 72 20 45 58 43  me SHARED or EXC
f480: 4c 55 53 49 56 45 20 66 6c 61 67 20 6d 75 73 74  LUSIVE flag must
f490: 20 62 65 20 73 75 70 70 6c 69 65 64 20 61 73 0a   be supplied as.
f4a0: 2a 2a 20 77 61 73 20 67 69 76 65 6e 20 6f 6e 20  ** was given on 
f4b0: 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e  the correspondin
f4c0: 67 20 6c 6f 63 6b 2e 20 20 0a 2a 2a 0a 2a 2a 20  g lock.  .**.** 
f4d0: 54 68 65 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74  The xShmLock met
f4e0: 68 6f 64 20 63 61 6e 20 74 72 61 6e 73 69 74 69  hod can transiti
f4f0: 6f 6e 20 62 65 74 77 65 65 6e 20 75 6e 6c 6f 63  on between unloc
f500: 6b 65 64 20 61 6e 64 20 53 48 41 52 45 44 20 6f  ked and SHARED o
f510: 72 0a 2a 2a 20 62 65 74 77 65 65 6e 20 75 6e 6c  r.** between unl
f520: 6f 63 6b 65 64 20 61 6e 64 20 45 58 43 4c 55 53  ocked and EXCLUS
f530: 49 56 45 2e 20 20 49 74 20 63 61 6e 6e 6f 74 20  IVE.  It cannot 
f540: 74 72 61 6e 73 69 74 69 6f 6e 20 62 65 74 77 65  transition betwe
f550: 65 6e 20 53 48 41 52 45 44 0a 2a 2a 20 61 6e 64  en SHARED.** and
f560: 20 45 58 43 4c 55 53 49 56 45 2e 0a 2a 2f 0a 23   EXCLUSIVE..*/.#
f570: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48  define SQLITE_SH
f580: 4d 5f 55 4e 4c 4f 43 4b 20 20 20 20 20 20 20 31  M_UNLOCK       1
f590: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
f5a0: 53 48 4d 5f 4c 4f 43 4b 20 20 20 20 20 20 20 20  SHM_LOCK        
f5b0: 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   2.#define SQLIT
f5c0: 45 5f 53 48 4d 5f 53 48 41 52 45 44 20 20 20 20  E_SHM_SHARED    
f5d0: 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c     4.#define SQL
f5e0: 49 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56  ITE_SHM_EXCLUSIV
f5f0: 45 20 20 20 20 38 0a 0a 2f 2a 0a 2a 2a 20 43 41  E    8../*.** CA
f600: 50 49 33 52 45 46 3a 20 4d 61 78 69 6d 75 6d 20  PI3REF: Maximum 
f610: 78 53 68 6d 4c 6f 63 6b 20 69 6e 64 65 78 0a 2a  xShmLock index.*
f620: 2a 0a 2a 2a 20 54 68 65 20 78 53 68 6d 4c 6f 63  *.** The xShmLoc
f630: 6b 20 6d 65 74 68 6f 64 20 6f 6e 20 5b 73 71 6c  k method on [sql
f640: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d  ite3_io_methods]
f650: 20 6d 61 79 20 75 73 65 20 76 61 6c 75 65 73 0a   may use values.
f660: 2a 2a 20 62 65 74 77 65 65 6e 20 30 20 61 6e 64  ** between 0 and
f670: 20 74 68 69 73 20 75 70 70 65 72 20 62 6f 75 6e   this upper boun
f680: 64 20 61 73 20 69 74 73 20 22 6f 66 66 73 65 74  d as its "offset
f690: 22 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 54  " argument..** T
f6a0: 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 77  he SQLite core w
f6b0: 69 6c 6c 20 6e 65 76 65 72 20 61 74 74 65 6d 70  ill never attemp
f6c0: 74 20 74 6f 20 61 63 71 75 69 72 65 20 6f 72 20  t to acquire or 
f6d0: 72 65 6c 65 61 73 65 20 61 0a 2a 2a 20 6c 6f 63  release a.** loc
f6e0: 6b 20 6f 75 74 73 69 64 65 20 6f 66 20 74 68 69  k outside of thi
f6f0: 73 20 72 61 6e 67 65 0a 2a 2f 0a 23 64 65 66 69  s range.*/.#defi
f700: 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4e 4c  ne SQLITE_SHM_NL
f710: 4f 43 4b 20 20 20 20 20 20 20 20 38 0a 0a 0a 2f  OCK        8.../
f720: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49  *.** CAPI3REF: I
f730: 6e 69 74 69 61 6c 69 7a 65 20 54 68 65 20 53 51  nitialize The SQ
f740: 4c 69 74 65 20 4c 69 62 72 61 72 79 0a 2a 2a 0a  Lite Library.**.
f750: 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
f760: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75  initialize() rou
f770: 74 69 6e 65 20 69 6e 69 74 69 61 6c 69 7a 65 73  tine initializes
f780: 20 74 68 65 0a 2a 2a 20 53 51 4c 69 74 65 20 6c   the.** SQLite l
f790: 69 62 72 61 72 79 2e 20 20 5e 54 68 65 20 73 71  ibrary.  ^The sq
f7a0: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
f7b0: 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 64 65 61 6c   routine.** deal
f7c0: 6c 6f 63 61 74 65 73 20 61 6e 79 20 72 65 73 6f  locates any reso
f7d0: 75 72 63 65 73 20 74 68 61 74 20 77 65 72 65 20  urces that were 
f7e0: 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 73 71 6c  allocated by sql
f7f0: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
f800: 29 2e 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  )..** These rout
f810: 69 6e 65 73 20 61 72 65 20 64 65 73 69 67 6e 65  ines are designe
f820: 64 20 74 6f 20 61 69 64 20 69 6e 20 70 72 6f 63  d to aid in proc
f830: 65 73 73 20 69 6e 69 74 69 61 6c 69 7a 61 74 69  ess initializati
f840: 6f 6e 20 61 6e 64 0a 2a 2a 20 73 68 75 74 64 6f  on and.** shutdo
f850: 77 6e 20 6f 6e 20 65 6d 62 65 64 64 65 64 20 73  wn on embedded s
f860: 79 73 74 65 6d 73 2e 20 20 57 6f 72 6b 73 74 61  ystems.  Worksta
f870: 74 69 6f 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  tion application
f880: 73 20 75 73 69 6e 67 0a 2a 2a 20 53 51 4c 69 74  s using.** SQLit
f890: 65 20 6e 6f 72 6d 61 6c 6c 79 20 64 6f 20 6e 6f  e normally do no
f8a0: 74 20 6e 65 65 64 20 74 6f 20 69 6e 76 6f 6b 65  t need to invoke
f8b0: 20 65 69 74 68 65 72 20 6f 66 20 74 68 65 73 65   either of these
f8c0: 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a   routines..**.**
f8d0: 20 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74   A call to sqlit
f8e0: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
f8f0: 69 73 20 61 6e 20 22 65 66 66 65 63 74 69 76 65  is an "effective
f900: 22 20 63 61 6c 6c 20 69 66 20 69 74 20 69 73 0a  " call if it is.
f910: 2a 2a 20 74 68 65 20 66 69 72 73 74 20 74 69 6d  ** the first tim
f920: 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  e sqlite3_initia
f930: 6c 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65  lize() is invoke
f940: 64 20 64 75 72 69 6e 67 20 74 68 65 20 6c 69 66  d during the lif
f950: 65 74 69 6d 65 20 6f 66 0a 2a 2a 20 74 68 65 20  etime of.** the 
f960: 70 72 6f 63 65 73 73 2c 20 6f 72 20 69 66 20 69  process, or if i
f970: 74 20 69 73 20 74 68 65 20 66 69 72 73 74 20 74  t is the first t
f980: 69 6d 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  ime sqlite3_init
f990: 69 61 6c 69 7a 65 28 29 20 69 73 20 69 6e 76 6f  ialize() is invo
f9a0: 6b 65 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67  ked.** following
f9b0: 20 61 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74   a call to sqlit
f9c0: 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20  e3_shutdown().  
f9d0: 5e 28 4f 6e 6c 79 20 61 6e 20 65 66 66 65 63 74  ^(Only an effect
f9e0: 69 76 65 20 63 61 6c 6c 0a 2a 2a 20 6f 66 20 73  ive call.** of s
f9f0: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
fa00: 65 28 29 20 64 6f 65 73 20 61 6e 79 20 69 6e 69  e() does any ini
fa10: 74 69 61 6c 69 7a 61 74 69 6f 6e 2e 20 20 41 6c  tialization.  Al
fa20: 6c 20 6f 74 68 65 72 20 63 61 6c 6c 73 0a 2a 2a  l other calls.**
fa30: 20 61 72 65 20 68 61 72 6d 6c 65 73 73 20 6e 6f   are harmless no
fa40: 2d 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 41 20  -ops.)^.**.** A 
fa50: 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f  call to sqlite3_
fa60: 73 68 75 74 64 6f 77 6e 28 29 20 69 73 20 61 6e  shutdown() is an
fa70: 20 22 65 66 66 65 63 74 69 76 65 22 20 63 61 6c   "effective" cal
fa80: 6c 20 69 66 20 69 74 20 69 73 20 74 68 65 20 66  l if it is the f
fa90: 69 72 73 74 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20  irst.** call to 
faa0: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
fab0: 28 29 20 73 69 6e 63 65 20 74 68 65 20 6c 61 73  () since the las
fac0: 74 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  t sqlite3_initia
fad0: 6c 69 7a 65 28 29 2e 20 20 5e 28 4f 6e 6c 79 0a  lize().  ^(Only.
fae0: 2a 2a 20 61 6e 20 65 66 66 65 63 74 69 76 65 20  ** an effective 
faf0: 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f  call to sqlite3_
fb00: 73 68 75 74 64 6f 77 6e 28 29 20 64 6f 65 73 20  shutdown() does 
fb10: 61 6e 79 20 64 65 69 6e 69 74 69 61 6c 69 7a 61  any deinitializa
fb20: 74 69 6f 6e 2e 0a 2a 2a 20 41 6c 6c 20 6f 74 68  tion..** All oth
fb30: 65 72 20 76 61 6c 69 64 20 63 61 6c 6c 73 20 74  er valid calls t
fb40: 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  o sqlite3_shutdo
fb50: 77 6e 28 29 20 61 72 65 20 68 61 72 6d 6c 65 73  wn() are harmles
fb60: 73 20 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a  s no-ops.)^.**.*
fb70: 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e  * The sqlite3_in
fb80: 69 74 69 61 6c 69 7a 65 28 29 20 69 6e 74 65 72  itialize() inter
fb90: 66 61 63 65 20 69 73 20 74 68 72 65 61 64 73 61  face is threadsa
fba0: 66 65 2c 20 62 75 74 20 73 71 6c 69 74 65 33 5f  fe, but sqlite3_
fbb0: 73 68 75 74 64 6f 77 6e 28 29 0a 2a 2a 20 69 73  shutdown().** is
fbc0: 20 6e 6f 74 2e 20 20 54 68 65 20 73 71 6c 69 74   not.  The sqlit
fbd0: 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 69 6e  e3_shutdown() in
fbe0: 74 65 72 66 61 63 65 20 6d 75 73 74 20 6f 6e 6c  terface must onl
fbf0: 79 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d  y be called from
fc00: 20 61 0a 2a 2a 20 73 69 6e 67 6c 65 20 74 68 72   a.** single thr
fc10: 65 61 64 2e 20 20 41 6c 6c 20 6f 70 65 6e 20 5b  ead.  All open [
fc20: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
fc30: 69 6f 6e 73 5d 20 6d 75 73 74 20 62 65 20 63 6c  ions] must be cl
fc40: 6f 73 65 64 20 61 6e 64 20 61 6c 6c 0a 2a 2a 20  osed and all.** 
fc50: 6f 74 68 65 72 20 53 51 4c 69 74 65 20 72 65 73  other SQLite res
fc60: 6f 75 72 63 65 73 20 6d 75 73 74 20 62 65 20 64  ources must be d
fc70: 65 61 6c 6c 6f 63 61 74 65 64 20 70 72 69 6f 72  eallocated prior
fc80: 20 74 6f 20 69 6e 76 6f 6b 69 6e 67 0a 2a 2a 20   to invoking.** 
fc90: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
fca0: 28 29 2e 0a 2a 2a 0a 2a 2a 20 41 6d 6f 6e 67 20  ()..**.** Among 
fcb0: 6f 74 68 65 72 20 74 68 69 6e 67 73 2c 20 5e 73  other things, ^s
fcc0: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
fcd0: 65 28 29 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 0a  e() will invoke.
fce0: 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  ** sqlite3_os_in
fcf0: 69 74 28 29 2e 20 20 53 69 6d 69 6c 61 72 6c 79  it().  Similarly
fd00: 2c 20 5e 73 71 6c 69 74 65 33 5f 73 68 75 74 64  , ^sqlite3_shutd
fd10: 6f 77 6e 28 29 0a 2a 2a 20 77 69 6c 6c 20 69 6e  own().** will in
fd20: 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f  voke sqlite3_os_
fd30: 65 6e 64 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  end()..**.** ^Th
fd40: 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  e sqlite3_initia
fd50: 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 72  lize() routine r
fd60: 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f  eturns [SQLITE_O
fd70: 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 2e 0a 2a  K] on success..*
fd80: 2a 20 5e 49 66 20 66 6f 72 20 73 6f 6d 65 20 72  * ^If for some r
fd90: 65 61 73 6f 6e 2c 20 73 71 6c 69 74 65 33 5f 69  eason, sqlite3_i
fda0: 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 75  nitialize() is u
fdb0: 6e 61 62 6c 65 20 74 6f 20 69 6e 69 74 69 61 6c  nable to initial
fdc0: 69 7a 65 0a 2a 2a 20 74 68 65 20 6c 69 62 72 61  ize.** the libra
fdd0: 72 79 20 28 70 65 72 68 61 70 73 20 69 74 20 69  ry (perhaps it i
fde0: 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f  s unable to allo
fdf0: 63 61 74 65 20 61 20 6e 65 65 64 65 64 20 72 65  cate a needed re
fe00: 73 6f 75 72 63 65 20 73 75 63 68 0a 2a 2a 20 61  source such.** a
fe10: 73 20 61 20 6d 75 74 65 78 29 20 69 74 20 72 65  s a mutex) it re
fe20: 74 75 72 6e 73 20 61 6e 20 5b 65 72 72 6f 72 20  turns an [error 
fe30: 63 6f 64 65 5d 20 6f 74 68 65 72 20 74 68 61 6e  code] other than
fe40: 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a   [SQLITE_OK]..**
fe50: 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
fe60: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f  _initialize() ro
fe70: 75 74 69 6e 65 20 69 73 20 63 61 6c 6c 65 64 20  utine is called 
fe80: 69 6e 74 65 72 6e 61 6c 6c 79 20 62 79 20 6d 61  internally by ma
fe90: 6e 79 20 6f 74 68 65 72 0a 2a 2a 20 53 51 4c 69  ny other.** SQLi
fea0: 74 65 20 69 6e 74 65 72 66 61 63 65 73 20 73 6f  te interfaces so
feb0: 20 74 68 61 74 20 61 6e 20 61 70 70 6c 69 63 61   that an applica
fec0: 74 69 6f 6e 20 75 73 75 61 6c 6c 79 20 64 6f 65  tion usually doe
fed0: 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 0a 2a 2a  s not need to.**
fee0: 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f   invoke sqlite3_
fef0: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 69 72  initialize() dir
ff00: 65 63 74 6c 79 2e 20 20 46 6f 72 20 65 78 61 6d  ectly.  For exam
ff10: 70 6c 65 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70  ple, [sqlite3_op
ff20: 65 6e 28 29 5d 0a 2a 2a 20 63 61 6c 6c 73 20 73  en()].** calls s
ff30: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
ff40: 65 28 29 20 73 6f 20 74 68 65 20 53 51 4c 69 74  e() so the SQLit
ff50: 65 20 6c 69 62 72 61 72 79 20 77 69 6c 6c 20 62  e library will b
ff60: 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a  e automatically.
ff70: 2a 2a 20 69 6e 69 74 69 61 6c 69 7a 65 64 20 77  ** initialized w
ff80: 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  hen [sqlite3_ope
ff90: 6e 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 20 69  n()] is called i
ffa0: 66 20 69 74 20 68 61 73 20 6e 6f 74 20 62 65 20  f it has not be 
ffb0: 69 6e 69 74 69 61 6c 69 7a 65 64 0a 2a 2a 20 61  initialized.** a
ffc0: 6c 72 65 61 64 79 2e 20 20 5e 48 6f 77 65 76 65  lready.  ^Howeve
ffd0: 72 2c 20 69 66 20 53 51 4c 69 74 65 20 69 73 20  r, if SQLite is 
ffe0: 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68  compiled with th
fff0: 65 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41  e [SQLITE_OMIT_A
10000 55 54 4f 49 4e 49 54 5d 0a 2a 2a 20 63 6f 6d 70  UTOINIT].** comp
10010 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2c  ile-time option,
10020 20 74 68 65 6e 20 74 68 65 20 61 75 74 6f 6d 61   then the automa
10030 74 69 63 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c  tic calls to sql
10040 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
10050 29 0a 2a 2a 20 61 72 65 20 6f 6d 69 74 74 65 64  ).** are omitted
10060 20 61 6e 64 20 74 68 65 20 61 70 70 6c 69 63 61   and the applica
10070 74 69 6f 6e 20 6d 75 73 74 20 63 61 6c 6c 20 73  tion must call s
10080 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
10090 65 28 29 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20  e() directly.** 
100a0 70 72 69 6f 72 20 74 6f 20 75 73 69 6e 67 20 61  prior to using a
100b0 6e 79 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20  ny other SQLite 
100c0 69 6e 74 65 72 66 61 63 65 2e 20 20 46 6f 72 20  interface.  For 
100d0 6d 61 78 69 6d 75 6d 20 70 6f 72 74 61 62 69 6c  maximum portabil
100e0 69 74 79 2c 0a 2a 2a 20 69 74 20 69 73 20 72 65  ity,.** it is re
100f0 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 61  commended that a
10100 70 70 6c 69 63 61 74 69 6f 6e 73 20 61 6c 77 61  pplications alwa
10110 79 73 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65  ys invoke sqlite
10120 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 0a 2a  3_initialize().*
10130 2a 20 64 69 72 65 63 74 6c 79 20 70 72 69 6f 72  * directly prior
10140 20 74 6f 20 75 73 69 6e 67 20 61 6e 79 20 6f 74   to using any ot
10150 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72  her SQLite inter
10160 66 61 63 65 2e 20 20 46 75 74 75 72 65 20 72 65  face.  Future re
10170 6c 65 61 73 65 73 0a 2a 2a 20 6f 66 20 53 51 4c  leases.** of SQL
10180 69 74 65 20 6d 61 79 20 72 65 71 75 69 72 65 20  ite may require 
10190 74 68 69 73 2e 20 20 49 6e 20 6f 74 68 65 72 20  this.  In other 
101a0 77 6f 72 64 73 2c 20 74 68 65 20 62 65 68 61 76  words, the behav
101b0 69 6f 72 20 65 78 68 69 62 69 74 65 64 0a 2a 2a  ior exhibited.**
101c0 20 77 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20   when SQLite is 
101d0 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 5b 53  compiled with [S
101e0 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 49  QLITE_OMIT_AUTOI
101f0 4e 49 54 5d 20 6d 69 67 68 74 20 62 65 63 6f 6d  NIT] might becom
10200 65 20 74 68 65 0a 2a 2a 20 64 65 66 61 75 6c 74  e the.** default
10210 20 62 65 68 61 76 69 6f 72 20 69 6e 20 73 6f 6d   behavior in som
10220 65 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65  e future release
10230 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a   of SQLite..**.*
10240 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73  * The sqlite3_os
10250 5f 69 6e 69 74 28 29 20 72 6f 75 74 69 6e 65 20  _init() routine 
10260 64 6f 65 73 20 6f 70 65 72 61 74 69 6e 67 2d 73  does operating-s
10270 79 73 74 65 6d 20 73 70 65 63 69 66 69 63 0a 2a  ystem specific.*
10280 2a 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e  * initialization
10290 20 6f 66 20 74 68 65 20 53 51 4c 69 74 65 20 6c   of the SQLite l
102a0 69 62 72 61 72 79 2e 20 20 54 68 65 20 73 71 6c  ibrary.  The sql
102b0 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a  ite3_os_end().**
102c0 20 72 6f 75 74 69 6e 65 20 75 6e 64 6f 65 73 20   routine undoes 
102d0 74 68 65 20 65 66 66 65 63 74 20 6f 66 20 73 71  the effect of sq
102e0 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 2e  lite3_os_init().
102f0 20 20 54 79 70 69 63 61 6c 20 74 61 73 6b 73 0a    Typical tasks.
10300 2a 2a 20 70 65 72 66 6f 72 6d 65 64 20 62 79 20  ** performed by 
10310 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 69  these routines i
10320 6e 63 6c 75 64 65 20 61 6c 6c 6f 63 61 74 69 6f  nclude allocatio
10330 6e 20 6f 72 20 64 65 61 6c 6c 6f 63 61 74 69 6f  n or deallocatio
10340 6e 0a 2a 2a 20 6f 66 20 73 74 61 74 69 63 20 72  n.** of static r
10350 65 73 6f 75 72 63 65 73 2c 20 69 6e 69 74 69 61  esources, initia
10360 6c 69 7a 61 74 69 6f 6e 20 6f 66 20 67 6c 6f 62  lization of glob
10370 61 6c 20 76 61 72 69 61 62 6c 65 73 2c 0a 2a 2a  al variables,.**
10380 20 73 65 74 74 69 6e 67 20 75 70 20 61 20 64 65   setting up a de
10390 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76  fault [sqlite3_v
103a0 66 73 5d 20 6d 6f 64 75 6c 65 2c 20 6f 72 20 73  fs] module, or s
103b0 65 74 74 69 6e 67 20 75 70 0a 2a 2a 20 61 20 64  etting up.** a d
103c0 65 66 61 75 6c 74 20 63 6f 6e 66 69 67 75 72 61  efault configura
103d0 74 69 6f 6e 20 75 73 69 6e 67 20 5b 73 71 6c 69  tion using [sqli
103e0 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 2e 0a 2a  te3_config()]..*
103f0 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61  *.** The applica
10400 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 65 76 65  tion should neve
10410 72 20 69 6e 76 6f 6b 65 20 65 69 74 68 65 72 20  r invoke either 
10420 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28  sqlite3_os_init(
10430 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f  ).** or sqlite3_
10440 6f 73 5f 65 6e 64 28 29 20 64 69 72 65 63 74 6c  os_end() directl
10450 79 2e 20 20 54 68 65 20 61 70 70 6c 69 63 61 74  y.  The applicat
10460 69 6f 6e 20 73 68 6f 75 6c 64 20 6f 6e 6c 79 20  ion should only 
10470 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65  invoke.** sqlite
10480 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 61  3_initialize() a
10490 6e 64 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64  nd sqlite3_shutd
104a0 6f 77 6e 28 29 2e 20 20 54 68 65 20 73 71 6c 69  own().  The sqli
104b0 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a  te3_os_init().**
104c0 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 63 61   interface is ca
104d0 6c 6c 65 64 20 61 75 74 6f 6d 61 74 69 63 61 6c  lled automatical
104e0 6c 79 20 62 79 20 73 71 6c 69 74 65 33 5f 69 6e  ly by sqlite3_in
104f0 69 74 69 61 6c 69 7a 65 28 29 20 61 6e 64 0a 2a  itialize() and.*
10500 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64  * sqlite3_os_end
10510 28 29 20 69 73 20 63 61 6c 6c 65 64 20 62 79 20  () is called by 
10520 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
10530 28 29 2e 20 20 41 70 70 72 6f 70 72 69 61 74 65  ().  Appropriate
10540 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  .** implementati
10550 6f 6e 73 20 66 6f 72 20 73 71 6c 69 74 65 33 5f  ons for sqlite3_
10560 6f 73 5f 69 6e 69 74 28 29 20 61 6e 64 20 73 71  os_init() and sq
10570 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a  lite3_os_end().*
10580 2a 20 61 72 65 20 62 75 69 6c 74 20 69 6e 74 6f  * are built into
10590 20 53 51 4c 69 74 65 20 77 68 65 6e 20 69 74 20   SQLite when it 
105a0 69 73 20 63 6f 6d 70 69 6c 65 64 20 66 6f 72 20  is compiled for 
105b0 55 6e 69 78 2c 20 57 69 6e 64 6f 77 73 2c 20 6f  Unix, Windows, o
105c0 72 20 4f 53 2f 32 2e 0a 2a 2a 20 57 68 65 6e 20  r OS/2..** When 
105d0 5b 63 75 73 74 6f 6d 20 62 75 69 6c 64 73 20 7c  [custom builds |
105e0 20 62 75 69 6c 74 20 66 6f 72 20 6f 74 68 65 72   built for other
105f0 20 70 6c 61 74 66 6f 72 6d 73 5d 0a 2a 2a 20 28   platforms].** (
10600 75 73 69 6e 67 20 74 68 65 20 5b 53 51 4c 49 54  using the [SQLIT
10610 45 5f 4f 53 5f 4f 54 48 45 52 3d 31 5d 20 63 6f  E_OS_OTHER=1] co
10620 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70  mpile-time.** op
10630 74 69 6f 6e 29 20 74 68 65 20 61 70 70 6c 69 63  tion) the applic
10640 61 74 69 6f 6e 20 6d 75 73 74 20 73 75 70 70 6c  ation must suppl
10650 79 20 61 20 73 75 69 74 61 62 6c 65 20 69 6d 70  y a suitable imp
10660 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 0a  lementation for.
10670 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  ** sqlite3_os_in
10680 69 74 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  it() and sqlite3
10690 5f 6f 73 5f 65 6e 64 28 29 2e 20 20 41 6e 20 61  _os_end().  An a
106a0 70 70 6c 69 63 61 74 69 6f 6e 2d 73 75 70 70 6c  pplication-suppl
106b0 69 65 64 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74  ied.** implement
106c0 61 74 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33  ation of sqlite3
106d0 5f 6f 73 5f 69 6e 69 74 28 29 20 6f 72 20 73 71  _os_init() or sq
106e0 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a  lite3_os_end().*
106f0 2a 20 6d 75 73 74 20 72 65 74 75 72 6e 20 5b 53  * must return [S
10700 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63  QLITE_OK] on suc
10710 63 65 73 73 20 61 6e 64 20 73 6f 6d 65 20 6f 74  cess and some ot
10720 68 65 72 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d  her [error code]
10730 20 75 70 6f 6e 0a 2a 2a 20 66 61 69 6c 75 72 65   upon.** failure
10740 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
10750 5f 69 6e 69 74 69 61 6c 69 7a 65 28 76 6f 69 64  _initialize(void
10760 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73  );.int sqlite3_s
10770 68 75 74 64 6f 77 6e 28 76 6f 69 64 29 3b 0a 69  hutdown(void);.i
10780 6e 74 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  nt sqlite3_os_in
10790 69 74 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71  it(void);.int sq
107a0 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 76 6f 69  lite3_os_end(voi
107b0 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  d);../*.** CAPI3
107c0 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 69 6e 67  REF: Configuring
107d0 20 54 68 65 20 53 51 4c 69 74 65 20 4c 69 62 72   The SQLite Libr
107e0 61 72 79 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  ary.**.** The sq
107f0 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69  lite3_config() i
10800 6e 74 65 72 66 61 63 65 20 69 73 20 75 73 65 64  nterface is used
10810 20 74 6f 20 6d 61 6b 65 20 67 6c 6f 62 61 6c 20   to make global 
10820 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 0a 2a 2a  configuration.**
10830 20 63 68 61 6e 67 65 73 20 74 6f 20 53 51 4c 69   changes to SQLi
10840 74 65 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 74  te in order to t
10850 75 6e 65 20 53 51 4c 69 74 65 20 74 6f 20 74 68  une SQLite to th
10860 65 20 73 70 65 63 69 66 69 63 20 6e 65 65 64 73  e specific needs
10870 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69   of.** the appli
10880 63 61 74 69 6f 6e 2e 20 20 54 68 65 20 64 65 66  cation.  The def
10890 61 75 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 69  ault configurati
108a0 6f 6e 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65  on is recommende
108b0 64 20 66 6f 72 20 6d 6f 73 74 0a 2a 2a 20 61 70  d for most.** ap
108c0 70 6c 69 63 61 74 69 6f 6e 73 20 61 6e 64 20 73  plications and s
108d0 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69  o this routine i
108e0 73 20 75 73 75 61 6c 6c 79 20 6e 6f 74 20 6e 65  s usually not ne
108f0 63 65 73 73 61 72 79 2e 20 20 49 74 20 69 73 0a  cessary.  It is.
10900 2a 2a 20 70 72 6f 76 69 64 65 64 20 74 6f 20 73  ** provided to s
10910 75 70 70 6f 72 74 20 72 61 72 65 20 61 70 70 6c  upport rare appl
10920 69 63 61 74 69 6f 6e 73 20 77 69 74 68 20 75 6e  ications with un
10930 75 73 75 61 6c 20 6e 65 65 64 73 2e 0a 2a 2a 0a  usual needs..**.
10940 2a 2a 20 3c 62 3e 54 68 65 20 73 71 6c 69 74 65  ** <b>The sqlite
10950 33 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72  3_config() inter
10960 66 61 63 65 20 69 73 20 6e 6f 74 20 74 68 72 65  face is not thre
10970 61 64 73 61 66 65 2e 20 54 68 65 20 61 70 70 6c  adsafe. The appl
10980 69 63 61 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20  ication.** must 
10990 65 6e 73 75 72 65 20 74 68 61 74 20 6e 6f 20 6f  ensure that no o
109a0 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65  ther SQLite inte
109b0 72 66 61 63 65 73 20 61 72 65 20 69 6e 76 6f 6b  rfaces are invok
109c0 65 64 20 62 79 20 6f 74 68 65 72 0a 2a 2a 20 74  ed by other.** t
109d0 68 72 65 61 64 73 20 77 68 69 6c 65 20 73 71 6c  hreads while sql
109e0 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 73  ite3_config() is
109f0 20 72 75 6e 6e 69 6e 67 2e 3c 2f 62 3e 0a 2a 2a   running.</b>.**
10a00 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
10a10 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61  config() interfa
10a20 63 65 0a 2a 2a 20 6d 61 79 20 6f 6e 6c 79 20 62  ce.** may only b
10a30 65 20 69 6e 76 6f 6b 65 64 20 70 72 69 6f 72 20  e invoked prior 
10a40 74 6f 20 6c 69 62 72 61 72 79 20 69 6e 69 74 69  to library initi
10a50 61 6c 69 7a 61 74 69 6f 6e 20 75 73 69 6e 67 0a  alization using.
10a60 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74  ** [sqlite3_init
10a70 69 61 6c 69 7a 65 28 29 5d 20 6f 72 20 61 66 74  ialize()] or aft
10a80 65 72 20 73 68 75 74 64 6f 77 6e 20 62 79 20 5b  er shutdown by [
10a90 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
10aa0 28 29 5d 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69  ()]..** ^If sqli
10ab0 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 20  te3_config() is 
10ac0 63 61 6c 6c 65 64 20 61 66 74 65 72 20 5b 73 71  called after [sq
10ad0 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
10ae0 28 29 5d 20 61 6e 64 20 62 65 66 6f 72 65 0a 2a  ()] and before.*
10af0 2a 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64  * [sqlite3_shutd
10b00 6f 77 6e 28 29 5d 20 74 68 65 6e 20 69 74 20 77  own()] then it w
10b10 69 6c 6c 20 72 65 74 75 72 6e 20 53 51 4c 49 54  ill return SQLIT
10b20 45 5f 4d 49 53 55 53 45 2e 0a 2a 2a 20 4e 6f 74  E_MISUSE..** Not
10b30 65 2c 20 68 6f 77 65 76 65 72 2c 20 74 68 61 74  e, however, that
10b40 20 5e 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   ^sqlite3_config
10b50 28 29 20 63 61 6e 20 62 65 20 63 61 6c 6c 65 64  () can be called
10b60 20 61 73 20 70 61 72 74 20 6f 66 20 74 68 65 0a   as part of the.
10b70 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ** implementatio
10b80 6e 20 6f 66 20 61 6e 20 61 70 70 6c 69 63 61 74  n of an applicat
10b90 69 6f 6e 2d 64 65 66 69 6e 65 64 20 5b 73 71 6c  ion-defined [sql
10ba0 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 5d 2e  ite3_os_init()].
10bb0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74  .**.** The first
10bc0 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c   argument to sql
10bd0 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 73  ite3_config() is
10be0 20 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a 20 5b   an integer.** [
10bf0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
10c00 74 69 6f 6e 5d 20 74 68 61 74 20 64 65 74 65 72  tion] that deter
10c10 6d 69 6e 65 73 0a 2a 2a 20 77 68 61 74 20 70 72  mines.** what pr
10c20 6f 70 65 72 74 79 20 6f 66 20 53 51 4c 69 74 65  operty of SQLite
10c30 20 69 73 20 74 6f 20 62 65 20 63 6f 6e 66 69 67   is to be config
10c40 75 72 65 64 2e 20 20 53 75 62 73 65 71 75 65 6e  ured.  Subsequen
10c50 74 20 61 72 67 75 6d 65 6e 74 73 0a 2a 2a 20 76  t arguments.** v
10c60 61 72 79 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e  ary depending on
10c70 20 74 68 65 20 5b 63 6f 6e 66 69 67 75 72 61 74   the [configurat
10c80 69 6f 6e 20 6f 70 74 69 6f 6e 5d 0a 2a 2a 20 69  ion option].** i
10c90 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  n the first argu
10ca0 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 65  ment..**.** ^Whe
10cb0 6e 20 61 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  n a configuratio
10cc0 6e 20 6f 70 74 69 6f 6e 20 69 73 20 73 65 74 2c  n option is set,
10cd0 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28   sqlite3_config(
10ce0 29 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54  ) returns [SQLIT
10cf0 45 5f 4f 4b 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68  E_OK]..** ^If th
10d00 65 20 6f 70 74 69 6f 6e 20 69 73 20 75 6e 6b 6e  e option is unkn
10d10 6f 77 6e 20 6f 72 20 53 51 4c 69 74 65 20 69 73  own or SQLite is
10d20 20 75 6e 61 62 6c 65 20 74 6f 20 73 65 74 20 74   unable to set t
10d30 68 65 20 6f 70 74 69 6f 6e 0a 2a 2a 20 74 68 65  he option.** the
10d40 6e 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 72  n this routine r
10d50 65 74 75 72 6e 73 20 61 20 6e 6f 6e 2d 7a 65 72  eturns a non-zer
10d60 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a  o [error code]..
10d70 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  */.int sqlite3_c
10d80 6f 6e 66 69 67 28 69 6e 74 2c 20 2e 2e 2e 29 3b  onfig(int, ...);
10d90 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
10da0 3a 20 43 6f 6e 66 69 67 75 72 65 20 64 61 74 61  : Configure data
10db0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  base connections
10dc0 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
10dd0 74 65 33 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  te3.**.** The sq
10de0 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28  lite3_db_config(
10df0 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 75  ) interface is u
10e00 73 65 64 20 74 6f 20 6d 61 6b 65 20 63 6f 6e 66  sed to make conf
10e10 69 67 75 72 61 74 69 6f 6e 0a 2a 2a 20 63 68 61  iguration.** cha
10e20 6e 67 65 73 20 74 6f 20 61 20 5b 64 61 74 61 62  nges to a [datab
10e30 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e  ase connection].
10e40 20 20 54 68 65 20 69 6e 74 65 72 66 61 63 65 20    The interface 
10e50 69 73 20 73 69 6d 69 6c 61 72 20 74 6f 0a 2a 2a  is similar to.**
10e60 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
10e70 28 29 5d 20 65 78 63 65 70 74 20 74 68 61 74 20  ()] except that 
10e80 74 68 65 20 63 68 61 6e 67 65 73 20 61 70 70 6c  the changes appl
10e90 79 20 74 6f 20 61 20 73 69 6e 67 6c 65 0a 2a 2a  y to a single.**
10ea0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
10eb0 63 74 69 6f 6e 5d 20 28 73 70 65 63 69 66 69 65  ction] (specifie
10ec0 64 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61  d in the first a
10ed0 72 67 75 6d 65 6e 74 29 2e 0a 2a 2a 0a 2a 2a 20  rgument)..**.** 
10ee0 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  The second argum
10ef0 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 64  ent to sqlite3_d
10f00 62 5f 63 6f 6e 66 69 67 28 44 2c 56 2c 2e 2e 2e  b_config(D,V,...
10f10 29 20 20 69 73 20 74 68 65 0a 2a 2a 20 5b 53 51  )  is the.** [SQ
10f20 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f  LITE_DBCONFIG_LO
10f30 4f 4b 41 53 49 44 45 20 7c 20 63 6f 6e 66 69 67  OKASIDE | config
10f40 75 72 61 74 69 6f 6e 20 76 65 72 62 5d 20 2d 20  uration verb] - 
10f50 61 6e 20 69 6e 74 65 67 65 72 20 63 6f 64 65 20  an integer code 
10f60 0a 2a 2a 20 74 68 61 74 20 69 6e 64 69 63 61 74  .** that indicat
10f70 65 73 20 77 68 61 74 20 61 73 70 65 63 74 20 6f  es what aspect o
10f80 66 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  f the [database 
10f90 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 73 20 62  connection] is b
10fa0 65 69 6e 67 20 63 6f 6e 66 69 67 75 72 65 64 2e  eing configured.
10fb0 0a 2a 2a 20 53 75 62 73 65 71 75 65 6e 74 20 61  .** Subsequent a
10fc0 72 67 75 6d 65 6e 74 73 20 76 61 72 79 20 64 65  rguments vary de
10fd0 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 63  pending on the c
10fe0 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 76 65 72  onfiguration ver
10ff0 62 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 73 20  b..**.** ^Calls 
11000 74 6f 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f  to sqlite3_db_co
11010 6e 66 69 67 28 29 20 72 65 74 75 72 6e 20 53 51  nfig() return SQ
11020 4c 49 54 45 5f 4f 4b 20 69 66 20 61 6e 64 20 6f  LITE_OK if and o
11030 6e 6c 79 20 69 66 0a 2a 2a 20 74 68 65 20 63 61  nly if.** the ca
11040 6c 6c 20 69 73 20 63 6f 6e 73 69 64 65 72 65 64  ll is considered
11050 20 73 75 63 63 65 73 73 66 75 6c 2e 0a 2a 2f 0a   successful..*/.
11060 69 6e 74 20 73 71 6c 69 74 65 33 5f 64 62 5f 63  int sqlite3_db_c
11070 6f 6e 66 69 67 28 73 71 6c 69 74 65 33 2a 2c 20  onfig(sqlite3*, 
11080 69 6e 74 20 6f 70 2c 20 2e 2e 2e 29 3b 0a 0a 2f  int op, ...);../
11090 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d  *.** CAPI3REF: M
110a0 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f 6e  emory Allocation
110b0 20 52 6f 75 74 69 6e 65 73 0a 2a 2a 0a 2a 2a 20   Routines.**.** 
110c0 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  An instance of t
110d0 68 69 73 20 6f 62 6a 65 63 74 20 64 65 66 69 6e  his object defin
110e0 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  es the interface
110f0 20 62 65 74 77 65 65 6e 20 53 51 4c 69 74 65 0a   between SQLite.
11100 2a 2a 20 61 6e 64 20 6c 6f 77 2d 6c 65 76 65 6c  ** and low-level
11110 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
11120 6f 6e 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a  on routines..**.
11130 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 74 20 69  ** This object i
11140 73 20 75 73 65 64 20 69 6e 20 6f 6e 6c 79 20 6f  s used in only o
11150 6e 65 20 70 6c 61 63 65 20 69 6e 20 74 68 65 20  ne place in the 
11160 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65  SQLite interface
11170 2e 0a 2a 2a 20 41 20 70 6f 69 6e 74 65 72 20 74  ..** A pointer t
11180 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66  o an instance of
11190 20 74 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20   this object is 
111a0 74 68 65 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a  the argument to.
111b0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  ** [sqlite3_conf
111c0 69 67 28 29 5d 20 77 68 65 6e 20 74 68 65 20 63  ig()] when the c
111d0 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
111e0 69 6f 6e 20 69 73 0a 2a 2a 20 5b 53 51 4c 49 54  ion is.** [SQLIT
111f0 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d  E_CONFIG_MALLOC]
11200 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46   or [SQLITE_CONF
11210 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 5d 2e 20 20  IG_GETMALLOC].  
11220 0a 2a 2a 20 42 79 20 63 72 65 61 74 69 6e 67 20  .** By creating 
11230 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  an instance of t
11240 68 69 73 20 6f 62 6a 65 63 74 0a 2a 2a 20 61 6e  his object.** an
11250 64 20 70 61 73 73 69 6e 67 20 69 74 20 74 6f 20  d passing it to 
11260 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 5d  [sqlite3_config]
11270 28 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  ([SQLITE_CONFIG_
11280 4d 41 4c 4c 4f 43 5d 29 0a 2a 2a 20 64 75 72 69  MALLOC]).** duri
11290 6e 67 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ng configuration
112a0 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  , an application
112b0 20 63 61 6e 20 73 70 65 63 69 66 79 20 61 6e 20   can specify an 
112c0 61 6c 74 65 72 6e 61 74 69 76 65 0a 2a 2a 20 6d  alternative.** m
112d0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
112e0 20 73 75 62 73 79 73 74 65 6d 20 66 6f 72 20 53   subsystem for S
112f0 51 4c 69 74 65 20 74 6f 20 75 73 65 20 66 6f 72  QLite to use for
11300 20 61 6c 6c 20 6f 66 20 69 74 73 0a 2a 2a 20 64   all of its.** d
11310 79 6e 61 6d 69 63 20 6d 65 6d 6f 72 79 20 6e 65  ynamic memory ne
11320 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20  eds..**.** Note 
11330 74 68 61 74 20 53 51 4c 69 74 65 20 63 6f 6d 65  that SQLite come
11340 73 20 77 69 74 68 20 73 65 76 65 72 61 6c 20 5b  s with several [
11350 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20  built-in memory 
11360 61 6c 6c 6f 63 61 74 6f 72 73 5d 0a 2a 2a 20 74  allocators].** t
11370 68 61 74 20 61 72 65 20 70 65 72 66 65 63 74 6c  hat are perfectl
11380 79 20 61 64 65 71 75 61 74 65 20 66 6f 72 20 74  y adequate for t
11390 68 65 20 6f 76 65 72 77 68 65 6c 6d 69 6e 67 20  he overwhelming 
113a0 6d 61 6a 6f 72 69 74 79 20 6f 66 20 61 70 70 6c  majority of appl
113b0 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 61 6e 64 20  ications.** and 
113c0 74 68 61 74 20 74 68 69 73 20 6f 62 6a 65 63 74  that this object
113d0 20 69 73 20 6f 6e 6c 79 20 75 73 65 66 75 6c 20   is only useful 
113e0 74 6f 20 61 20 74 69 6e 79 20 6d 69 6e 6f 72 69  to a tiny minori
113f0 74 79 20 6f 66 20 61 70 70 6c 69 63 61 74 69 6f  ty of applicatio
11400 6e 73 0a 2a 2a 20 77 69 74 68 20 73 70 65 63 69  ns.** with speci
11410 61 6c 69 7a 65 64 20 6d 65 6d 6f 72 79 20 61 6c  alized memory al
11420 6c 6f 63 61 74 69 6f 6e 20 72 65 71 75 69 72 65  location require
11430 6d 65 6e 74 73 2e 20 20 54 68 69 73 20 6f 62 6a  ments.  This obj
11440 65 63 74 20 69 73 0a 2a 2a 20 61 6c 73 6f 20 75  ect is.** also u
11450 73 65 64 20 64 75 72 69 6e 67 20 74 65 73 74 69  sed during testi
11460 6e 67 20 6f 66 20 53 51 4c 69 74 65 20 69 6e 20  ng of SQLite in 
11470 6f 72 64 65 72 20 74 6f 20 73 70 65 63 69 66 79  order to specify
11480 20 61 6e 20 61 6c 74 65 72 6e 61 74 69 76 65 0a   an alternative.
11490 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  ** memory alloca
114a0 74 6f 72 20 74 68 61 74 20 73 69 6d 75 6c 61 74  tor that simulat
114b0 65 73 20 6d 65 6d 6f 72 79 20 6f 75 74 2d 6f 66  es memory out-of
114c0 2d 6d 65 6d 6f 72 79 20 63 6f 6e 64 69 74 69 6f  -memory conditio
114d0 6e 73 20 69 6e 0a 2a 2a 20 6f 72 64 65 72 20 74  ns in.** order t
114e0 6f 20 76 65 72 69 66 79 20 74 68 61 74 20 53 51  o verify that SQ
114f0 4c 69 74 65 20 72 65 63 6f 76 65 72 73 20 67 72  Lite recovers gr
11500 61 63 65 66 75 6c 6c 79 20 66 72 6f 6d 20 73 75  acefully from su
11510 63 68 0a 2a 2a 20 63 6f 6e 64 69 74 69 6f 6e 73  ch.** conditions
11520 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 4d 61 6c  ..**.** The xMal
11530 6c 6f 63 2c 20 78 52 65 61 6c 6c 6f 63 2c 20 61  loc, xRealloc, a
11540 6e 64 20 78 46 72 65 65 20 6d 65 74 68 6f 64 73  nd xFree methods
11550 20 6d 75 73 74 20 77 6f 72 6b 20 6c 69 6b 65 20   must work like 
11560 74 68 65 0a 2a 2a 20 6d 61 6c 6c 6f 63 28 29 2c  the.** malloc(),
11570 20 72 65 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66   realloc() and f
11580 72 65 65 28 29 20 66 75 6e 63 74 69 6f 6e 73 20  ree() functions 
11590 66 72 6f 6d 20 74 68 65 20 73 74 61 6e 64 61 72  from the standar
115a0 64 20 43 20 6c 69 62 72 61 72 79 2e 0a 2a 2a 20  d C library..** 
115b0 5e 53 51 4c 69 74 65 20 67 75 61 72 61 6e 74 65  ^SQLite guarante
115c0 65 73 20 74 68 61 74 20 74 68 65 20 73 65 63 6f  es that the seco
115d0 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a  nd argument to.*
115e0 2a 20 78 52 65 61 6c 6c 6f 63 20 69 73 20 61 6c  * xRealloc is al
115f0 77 61 79 73 20 61 20 76 61 6c 75 65 20 72 65 74  ways a value ret
11600 75 72 6e 65 64 20 62 79 20 61 20 70 72 69 6f 72  urned by a prior
11610 20 63 61 6c 6c 20 74 6f 20 78 52 6f 75 6e 64 75   call to xRoundu
11620 70 2e 0a 2a 2a 0a 2a 2a 20 78 53 69 7a 65 20 73  p..**.** xSize s
11630 68 6f 75 6c 64 20 72 65 74 75 72 6e 20 74 68 65  hould return the
11640 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65 20   allocated size 
11650 6f 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  of a memory allo
11660 63 61 74 69 6f 6e 0a 2a 2a 20 70 72 65 76 69 6f  cation.** previo
11670 75 73 6c 79 20 6f 62 74 61 69 6e 65 64 20 66 72  usly obtained fr
11680 6f 6d 20 78 4d 61 6c 6c 6f 63 20 6f 72 20 78 52  om xMalloc or xR
11690 65 61 6c 6c 6f 63 2e 20 20 54 68 65 20 61 6c 6c  ealloc.  The all
116a0 6f 63 61 74 65 64 20 73 69 7a 65 0a 2a 2a 20 69  ocated size.** i
116b0 73 20 61 6c 77 61 79 73 20 61 74 20 6c 65 61 73  s always at leas
116c0 74 20 61 73 20 62 69 67 20 61 73 20 74 68 65 20  t as big as the 
116d0 72 65 71 75 65 73 74 65 64 20 73 69 7a 65 20 62  requested size b
116e0 75 74 20 6d 61 79 20 62 65 20 6c 61 72 67 65 72  ut may be larger
116f0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 52 6f 75  ..**.** The xRou
11700 6e 64 75 70 20 6d 65 74 68 6f 64 20 72 65 74 75  ndup method retu
11710 72 6e 73 20 77 68 61 74 20 77 6f 75 6c 64 20 62  rns what would b
11720 65 20 74 68 65 20 61 6c 6c 6f 63 61 74 65 64 20  e the allocated 
11730 73 69 7a 65 20 6f 66 0a 2a 2a 20 61 20 6d 65 6d  size of.** a mem
11740 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 67  ory allocation g
11750 69 76 65 6e 20 61 20 70 61 72 74 69 63 75 6c 61  iven a particula
11760 72 20 72 65 71 75 65 73 74 65 64 20 73 69 7a 65  r requested size
11770 2e 20 20 4d 6f 73 74 20 6d 65 6d 6f 72 79 0a 2a  .  Most memory.*
11780 2a 20 61 6c 6c 6f 63 61 74 6f 72 73 20 72 6f 75  * allocators rou
11790 6e 64 20 75 70 20 6d 65 6d 6f 72 79 20 61 6c 6c  nd up memory all
117a0 6f 63 61 74 69 6f 6e 73 20 61 74 20 6c 65 61 73  ocations at leas
117b0 74 20 74 6f 20 74 68 65 20 6e 65 78 74 20 6d 75  t to the next mu
117c0 6c 74 69 70 6c 65 0a 2a 2a 20 6f 66 20 38 2e 20  ltiple.** of 8. 
117d0 20 53 6f 6d 65 20 61 6c 6c 6f 63 61 74 6f 72 73   Some allocators
117e0 20 72 6f 75 6e 64 20 75 70 20 74 6f 20 61 20 6c   round up to a l
117f0 61 72 67 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f  arger multiple o
11800 72 20 74 6f 20 61 20 70 6f 77 65 72 20 6f 66 20  r to a power of 
11810 32 2e 0a 2a 2a 20 45 76 65 72 79 20 6d 65 6d 6f  2..** Every memo
11820 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 65  ry allocation re
11830 71 75 65 73 74 20 63 6f 6d 69 6e 67 20 69 6e 20  quest coming in 
11840 74 68 72 6f 75 67 68 20 5b 73 71 6c 69 74 65 33  through [sqlite3
11850 5f 6d 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 6f 72  _malloc()].** or
11860 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f   [sqlite3_reallo
11870 63 28 29 5d 20 66 69 72 73 74 20 63 61 6c 6c 73  c()] first calls
11880 20 78 52 6f 75 6e 64 75 70 2e 20 20 49 66 20 78   xRoundup.  If x
11890 52 6f 75 6e 64 75 70 20 72 65 74 75 72 6e 73 20  Roundup returns 
118a0 30 2c 20 0a 2a 2a 20 74 68 61 74 20 63 61 75 73  0, .** that caus
118b0 65 73 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e  es the correspon
118c0 64 69 6e 67 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  ding memory allo
118d0 63 61 74 69 6f 6e 20 74 6f 20 66 61 69 6c 2e 0a  cation to fail..
118e0 2a 2a 0a 2a 2a 20 54 68 65 20 78 49 6e 69 74 20  **.** The xInit 
118f0 6d 65 74 68 6f 64 20 69 6e 69 74 69 61 6c 69 7a  method initializ
11900 65 73 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c  es the memory al
11910 6c 6f 63 61 74 6f 72 2e 20 20 46 6f 72 20 65 78  locator.  For ex
11920 61 6d 70 6c 65 2c 0a 2a 2a 20 69 74 20 6d 69 67  ample,.** it mig
11930 68 74 20 61 6c 6c 6f 63 61 74 65 20 61 6e 79 20  ht allocate any 
11940 72 65 71 75 69 72 65 20 6d 75 74 65 78 65 73 20  require mutexes 
11950 6f 72 20 69 6e 69 74 69 61 6c 69 7a 65 20 69 6e  or initialize in
11960 74 65 72 6e 61 6c 20 64 61 74 61 0a 2a 2a 20 73  ternal data.** s
11970 74 72 75 63 74 75 72 65 73 2e 20 20 54 68 65 20  tructures.  The 
11980 78 53 68 75 74 64 6f 77 6e 20 6d 65 74 68 6f 64  xShutdown method
11990 20 69 73 20 69 6e 76 6f 6b 65 64 20 28 69 6e 64   is invoked (ind
119a0 69 72 65 63 74 6c 79 29 20 62 79 0a 2a 2a 20 5b  irectly) by.** [
119b0 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
119c0 28 29 5d 20 61 6e 64 20 73 68 6f 75 6c 64 20 64  ()] and should d
119d0 65 61 6c 6c 6f 63 61 74 65 20 61 6e 79 20 72 65  eallocate any re
119e0 73 6f 75 72 63 65 73 20 61 63 71 75 69 72 65 64  sources acquired
119f0 0a 2a 2a 20 62 79 20 78 49 6e 69 74 2e 20 20 54  .** by xInit.  T
11a00 68 65 20 70 41 70 70 44 61 74 61 20 70 6f 69 6e  he pAppData poin
11a10 74 65 72 20 69 73 20 75 73 65 64 20 61 73 20 74  ter is used as t
11a20 68 65 20 6f 6e 6c 79 20 70 61 72 61 6d 65 74 65  he only paramete
11a30 72 20 74 6f 0a 2a 2a 20 78 49 6e 69 74 20 61 6e  r to.** xInit an
11a40 64 20 78 53 68 75 74 64 6f 77 6e 2e 0a 2a 2a 0a  d xShutdown..**.
11a50 2a 2a 20 53 51 4c 69 74 65 20 68 6f 6c 64 73 20  ** SQLite holds 
11a60 74 68 65 20 5b 53 51 4c 49 54 45 5f 4d 55 54 45  the [SQLITE_MUTE
11a70 58 5f 53 54 41 54 49 43 5f 4d 41 53 54 45 52 5d  X_STATIC_MASTER]
11a80 20 6d 75 74 65 78 20 77 68 65 6e 20 69 74 20 69   mutex when it i
11a90 6e 76 6f 6b 65 73 0a 2a 2a 20 74 68 65 20 78 49  nvokes.** the xI
11aa0 6e 69 74 20 6d 65 74 68 6f 64 2c 20 73 6f 20 74  nit method, so t
11ab0 68 65 20 78 49 6e 69 74 20 6d 65 74 68 6f 64 20  he xInit method 
11ac0 6e 65 65 64 20 6e 6f 74 20 62 65 20 74 68 72 65  need not be thre
11ad0 61 64 73 61 66 65 2e 20 20 54 68 65 0a 2a 2a 20  adsafe.  The.** 
11ae0 78 53 68 75 74 64 6f 77 6e 20 6d 65 74 68 6f 64  xShutdown method
11af0 20 69 73 20 6f 6e 6c 79 20 63 61 6c 6c 65 64 20   is only called 
11b00 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 73 68  from [sqlite3_sh
11b10 75 74 64 6f 77 6e 28 29 5d 20 73 6f 20 69 74 20  utdown()] so it 
11b20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 6e 65 65 64  does.** not need
11b30 20 74 6f 20 62 65 20 74 68 72 65 61 64 73 61 66   to be threadsaf
11b40 65 20 65 69 74 68 65 72 2e 20 20 46 6f 72 20 61  e either.  For a
11b50 6c 6c 20 6f 74 68 65 72 20 6d 65 74 68 6f 64 73  ll other methods
11b60 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 68 6f 6c 64  , SQLite.** hold
11b70 73 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4d 55  s the [SQLITE_MU
11b80 54 45 58 5f 53 54 41 54 49 43 5f 4d 45 4d 5d 20  TEX_STATIC_MEM] 
11b90 6d 75 74 65 78 20 61 73 20 6c 6f 6e 67 20 61 73  mutex as long as
11ba0 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f   the.** [SQLITE_
11bb0 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53  CONFIG_MEMSTATUS
11bc0 5d 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  ] configuration 
11bd0 6f 70 74 69 6f 6e 20 69 73 20 74 75 72 6e 65 64  option is turned
11be0 20 6f 6e 20 28 77 68 69 63 68 0a 2a 2a 20 69 74   on (which.** it
11bf0 20 69 73 20 62 79 20 64 65 66 61 75 6c 74 29 20   is by default) 
11c00 61 6e 64 20 73 6f 20 74 68 65 20 6d 65 74 68 6f  and so the metho
11c10 64 73 20 61 72 65 20 61 75 74 6f 6d 61 74 69 63  ds are automatic
11c20 61 6c 6c 79 20 73 65 72 69 61 6c 69 7a 65 64 2e  ally serialized.
11c30 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20 69 66 20  .** However, if 
11c40 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
11c50 45 4d 53 54 41 54 55 53 5d 20 69 73 20 64 69 73  EMSTATUS] is dis
11c60 61 62 6c 65 64 2c 20 74 68 65 6e 20 74 68 65 20  abled, then the 
11c70 6f 74 68 65 72 0a 2a 2a 20 6d 65 74 68 6f 64 73  other.** methods
11c80 20 6d 75 73 74 20 62 65 20 74 68 72 65 61 64 73   must be threads
11c90 61 66 65 20 6f 72 20 65 6c 73 65 20 6d 61 6b 65  afe or else make
11ca0 20 74 68 65 69 72 20 6f 77 6e 20 61 72 72 61 6e   their own arran
11cb0 67 65 6d 65 6e 74 73 20 66 6f 72 0a 2a 2a 20 73  gements for.** s
11cc0 65 72 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a  erialization..**
11cd0 0a 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  .** SQLite will 
11ce0 6e 65 76 65 72 20 69 6e 76 6f 6b 65 20 78 49 6e  never invoke xIn
11cf0 69 74 28 29 20 6d 6f 72 65 20 74 68 61 6e 20 6f  it() more than o
11d00 6e 63 65 20 77 69 74 68 6f 75 74 20 61 6e 20 69  nce without an i
11d10 6e 74 65 72 76 65 6e 69 6e 67 0a 2a 2a 20 63 61  ntervening.** ca
11d20 6c 6c 20 74 6f 20 78 53 68 75 74 64 6f 77 6e 28  ll to xShutdown(
11d30 29 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74  )..*/.typedef st
11d40 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d  ruct sqlite3_mem
11d50 5f 6d 65 74 68 6f 64 73 20 73 71 6c 69 74 65 33  _methods sqlite3
11d60 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 3b 0a 73 74  _mem_methods;.st
11d70 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d  ruct sqlite3_mem
11d80 5f 6d 65 74 68 6f 64 73 20 7b 0a 20 20 76 6f 69  _methods {.  voi
11d90 64 20 2a 28 2a 78 4d 61 6c 6c 6f 63 29 28 69 6e  d *(*xMalloc)(in
11da0 74 29 3b 20 20 20 20 20 20 20 20 20 2f 2a 20 4d  t);         /* M
11db0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
11dc0 20 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a 20 20 76   function */.  v
11dd0 6f 69 64 20 28 2a 78 46 72 65 65 29 28 76 6f 69  oid (*xFree)(voi
11de0 64 2a 29 3b 20 20 20 20 20 20 20 20 20 20 2f 2a  d*);          /*
11df0 20 46 72 65 65 20 61 20 70 72 69 6f 72 20 61 6c   Free a prior al
11e00 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f  location */.  vo
11e10 69 64 20 2a 28 2a 78 52 65 61 6c 6c 6f 63 29 28  id *(*xRealloc)(
11e20 76 6f 69 64 2a 2c 69 6e 74 29 3b 20 20 2f 2a 20  void*,int);  /* 
11e30 52 65 73 69 7a 65 20 61 6e 20 61 6c 6c 6f 63 61  Resize an alloca
11e40 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20 28 2a  tion */.  int (*
11e50 78 53 69 7a 65 29 28 76 6f 69 64 2a 29 3b 20 20  xSize)(void*);  
11e60 20 20 20 20 20 20 20 20 20 2f 2a 20 52 65 74 75           /* Retu
11e70 72 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20 61  rn the size of a
11e80 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a  n allocation */.
11e90 20 20 69 6e 74 20 28 2a 78 52 6f 75 6e 64 75 70    int (*xRoundup
11ea0 29 28 69 6e 74 29 3b 20 20 20 20 20 20 20 20 20  )(int);         
11eb0 20 2f 2a 20 52 6f 75 6e 64 20 75 70 20 72 65 71   /* Round up req
11ec0 75 65 73 74 20 73 69 7a 65 20 74 6f 20 61 6c 6c  uest size to all
11ed0 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20 2a 2f 0a  ocation size */.
11ee0 20 20 69 6e 74 20 28 2a 78 49 6e 69 74 29 28 76    int (*xInit)(v
11ef0 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 20 20 20  oid*);          
11f00 20 2f 2a 20 49 6e 69 74 69 61 6c 69 7a 65 20 74   /* Initialize t
11f10 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  he memory alloca
11f20 74 6f 72 20 2a 2f 0a 20 20 76 6f 69 64 20 28 2a  tor */.  void (*
11f30 78 53 68 75 74 64 6f 77 6e 29 28 76 6f 69 64 2a  xShutdown)(void*
11f40 29 3b 20 20 20 20 20 20 2f 2a 20 44 65 69 6e 69  );      /* Deini
11f50 74 69 61 6c 69 7a 65 20 74 68 65 20 6d 65 6d 6f  tialize the memo
11f60 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a  ry allocator */.
11f70 20 20 76 6f 69 64 20 2a 70 41 70 70 44 61 74 61    void *pAppData
11f80 3b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ;               
11f90 20 2f 2a 20 41 72 67 75 6d 65 6e 74 20 74 6f 20   /* Argument to 
11fa0 78 49 6e 69 74 28 29 20 61 6e 64 20 78 53 68 75  xInit() and xShu
11fb0 74 64 6f 77 6e 28 29 20 2a 2f 0a 7d 3b 0a 0a 2f  tdown() */.};../
11fc0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
11fd0 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 4f 70 74  onfiguration Opt
11fe0 69 6f 6e 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  ions.** KEYWORDS
11ff0 3a 20 7b 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  : {configuration
12000 20 6f 70 74 69 6f 6e 7d 0a 2a 2a 0a 2a 2a 20 54   option}.**.** T
12010 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61  hese constants a
12020 72 65 20 74 68 65 20 61 76 61 69 6c 61 62 6c 65  re the available
12030 20 69 6e 74 65 67 65 72 20 63 6f 6e 66 69 67 75   integer configu
12040 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 74  ration options t
12050 68 61 74 0a 2a 2a 20 63 61 6e 20 62 65 20 70 61  hat.** can be pa
12060 73 73 65 64 20 61 73 20 74 68 65 20 66 69 72 73  ssed as the firs
12070 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  t argument to th
12080 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  e [sqlite3_confi
12090 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a  g()] interface..
120a0 2a 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66 69 67  **.** New config
120b0 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20  uration options 
120c0 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20  may be added in 
120d0 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20  future releases 
120e0 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 45 78  of SQLite..** Ex
120f0 69 73 74 69 6e 67 20 63 6f 6e 66 69 67 75 72 61  isting configura
12100 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 69 67  tion options mig
12110 68 74 20 62 65 20 64 69 73 63 6f 6e 74 69 6e 75  ht be discontinu
12120 65 64 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e  ed.  Application
12130 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 63 68 65 63  s.** should chec
12140 6b 20 74 68 65 20 72 65 74 75 72 6e 20 63 6f 64  k the return cod
12150 65 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  e from [sqlite3_
12160 63 6f 6e 66 69 67 28 29 5d 20 74 6f 20 6d 61 6b  config()] to mak
12170 65 20 73 75 72 65 20 74 68 61 74 0a 2a 2a 20 74  e sure that.** t
12180 68 65 20 63 61 6c 6c 20 77 6f 72 6b 65 64 2e 20  he call worked. 
12190 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f   The [sqlite3_co
121a0 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63  nfig()] interfac
121b0 65 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 61 0a  e will return a.
121c0 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72  ** non-zero [err
121d0 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 20 64 69  or code] if a di
121e0 73 63 6f 6e 74 69 6e 75 65 64 20 6f 72 20 75 6e  scontinued or un
121f0 73 75 70 70 6f 72 74 65 64 20 63 6f 6e 66 69 67  supported config
12200 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a  uration option.*
12210 2a 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a  * is invoked..**
12220 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 51  .** <dl>.** [[SQ
12230 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47  LITE_CONFIG_SING
12240 4c 45 54 48 52 45 41 44 5d 5d 20 3c 64 74 3e 53  LETHREAD]] <dt>S
12250 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e  QLITE_CONFIG_SIN
12260 47 4c 45 54 48 52 45 41 44 3c 2f 64 74 3e 0a 2a  GLETHREAD</dt>.*
12270 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20  * <dd>There are 
12280 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20  no arguments to 
12290 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54  this option.  ^T
122a0 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20  his option sets 
122b0 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e  the.** [threadin
122c0 67 20 6d 6f 64 65 5d 20 74 6f 20 53 69 6e 67 6c  g mode] to Singl
122d0 65 2d 74 68 72 65 61 64 2e 20 20 49 6e 20 6f 74  e-thread.  In ot
122e0 68 65 72 20 77 6f 72 64 73 2c 20 69 74 20 64 69  her words, it di
122f0 73 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20 6d 75  sables.** all mu
12300 74 65 78 69 6e 67 20 61 6e 64 20 70 75 74 73 20  texing and puts 
12310 53 51 4c 69 74 65 20 69 6e 74 6f 20 61 20 6d 6f  SQLite into a mo
12320 64 65 20 77 68 65 72 65 20 69 74 20 63 61 6e 20  de where it can 
12330 6f 6e 6c 79 20 62 65 20 75 73 65 64 0a 2a 2a 20  only be used.** 
12340 62 79 20 61 20 73 69 6e 67 6c 65 20 74 68 72 65  by a single thre
12350 61 64 2e 20 20 20 5e 49 66 20 53 51 4c 69 74 65  ad.   ^If SQLite
12360 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74   is compiled wit
12370 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45  h.** the [SQLITE
12380 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20 53 51  _THREADSAFE | SQ
12390 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d  LITE_THREADSAFE=
123a0 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  0] compile-time 
123b0 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69  option then.** i
123c0 74 20 69 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c  t is not possibl
123d0 65 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65 20  e to change the 
123e0 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d  [threading mode]
123f0 20 66 72 6f 6d 20 69 74 73 20 64 65 66 61 75 6c   from its defaul
12400 74 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 53 69  t.** value of Si
12410 6e 67 6c 65 2d 74 68 72 65 61 64 20 61 6e 64 20  ngle-thread and 
12420 73 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  so [sqlite3_conf
12430 69 67 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72  ig()] will retur
12440 6e 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52  n .** [SQLITE_ER
12450 52 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64 20 77  ROR] if called w
12460 69 74 68 20 74 68 65 20 53 51 4c 49 54 45 5f 43  ith the SQLITE_C
12470 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45  ONFIG_SINGLETHRE
12480 41 44 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74  AD.** configurat
12490 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e  ion option.</dd>
124a0 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
124b0 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45  CONFIG_MULTITHRE
124c0 41 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  AD]] <dt>SQLITE_
124d0 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45  CONFIG_MULTITHRE
124e0 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  AD</dt>.** <dd>T
124f0 68 65 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75  here are no argu
12500 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70  ments to this op
12510 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74  tion.  ^This opt
12520 69 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20  ion sets the.** 
12530 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d  [threading mode]
12540 20 74 6f 20 4d 75 6c 74 69 2d 74 68 72 65 61 64   to Multi-thread
12550 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64  .  In other word
12560 73 2c 20 69 74 20 64 69 73 61 62 6c 65 73 0a 2a  s, it disables.*
12570 2a 20 6d 75 74 65 78 69 6e 67 20 6f 6e 20 5b 64  * mutexing on [d
12580 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
12590 6f 6e 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65  on] and [prepare
125a0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 62 6a  d statement] obj
125b0 65 63 74 73 2e 0a 2a 2a 20 54 68 65 20 61 70 70  ects..** The app
125c0 6c 69 63 61 74 69 6f 6e 20 69 73 20 72 65 73 70  lication is resp
125d0 6f 6e 73 69 62 6c 65 20 66 6f 72 20 73 65 72 69  onsible for seri
125e0 61 6c 69 7a 69 6e 67 20 61 63 63 65 73 73 20 74  alizing access t
125f0 6f 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63  o.** [database c
12600 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 61 6e 64 20  onnections] and 
12610 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
12620 65 6e 74 73 5d 2e 20 20 42 75 74 20 6f 74 68 65  ents].  But othe
12630 72 20 6d 75 74 65 78 65 73 0a 2a 2a 20 61 72 65  r mutexes.** are
12640 20 65 6e 61 62 6c 65 64 20 73 6f 20 74 68 61 74   enabled so that
12650 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 62 65 20   SQLite will be 
12660 73 61 66 65 20 74 6f 20 75 73 65 20 69 6e 20 61  safe to use in a
12670 20 6d 75 6c 74 69 2d 74 68 72 65 61 64 65 64 0a   multi-threaded.
12680 2a 2a 20 65 6e 76 69 72 6f 6e 6d 65 6e 74 20 61  ** environment a
12690 73 20 6c 6f 6e 67 20 61 73 20 6e 6f 20 74 77 6f  s long as no two
126a0 20 74 68 72 65 61 64 73 20 61 74 74 65 6d 70 74   threads attempt
126b0 20 74 6f 20 75 73 65 20 74 68 65 20 73 61 6d 65   to use the same
126c0 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f  .** [database co
126d0 6e 6e 65 63 74 69 6f 6e 5d 20 61 74 20 74 68 65  nnection] at the
126e0 20 73 61 6d 65 20 74 69 6d 65 2e 20 20 5e 49 66   same time.  ^If
126f0 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69   SQLite is compi
12700 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20  led with.** the 
12710 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41  [SQLITE_THREADSA
12720 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45  FE | SQLITE_THRE
12730 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c  ADSAFE=0] compil
12740 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68  e-time option th
12750 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20  en.** it is not 
12760 70 6f 73 73 69 62 6c 65 20 74 6f 20 73 65 74 20  possible to set 
12770 74 68 65 20 4d 75 6c 74 69 2d 74 68 72 65 61 64  the Multi-thread
12780 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65   [threading mode
12790 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  ] and.** [sqlite
127a0 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c  3_config()] will
127b0 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
127c0 45 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64  ERROR] if called
127d0 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 53 51 4c   with the.** SQL
127e0 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49  ITE_CONFIG_MULTI
127f0 54 48 52 45 41 44 20 63 6f 6e 66 69 67 75 72 61  THREAD configura
12800 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64  tion option.</dd
12810 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
12820 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a  _CONFIG_SERIALIZ
12830 45 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  ED]] <dt>SQLITE_
12840 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45  CONFIG_SERIALIZE
12850 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  D</dt>.** <dd>Th
12860 65 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d  ere are no argum
12870 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74  ents to this opt
12880 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74 69  ion.  ^This opti
12890 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b  on sets the.** [
128a0 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20  threading mode] 
128b0 74 6f 20 53 65 72 69 61 6c 69 7a 65 64 2e 20 49  to Serialized. I
128c0 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74  n other words, t
128d0 68 69 73 20 6f 70 74 69 6f 6e 20 65 6e 61 62 6c  his option enabl
128e0 65 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65 78 65  es.** all mutexe
128f0 73 20 69 6e 63 6c 75 64 69 6e 67 20 74 68 65 20  s including the 
12900 72 65 63 75 72 73 69 76 65 0a 2a 2a 20 6d 75 74  recursive.** mut
12910 65 78 65 73 20 6f 6e 20 5b 64 61 74 61 62 61 73  exes on [databas
12920 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e  e connection] an
12930 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  d [prepared stat
12940 65 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 73 2e 0a  ement] objects..
12950 2a 2a 20 49 6e 20 74 68 69 73 20 6d 6f 64 65 20  ** In this mode 
12960 28 77 68 69 63 68 20 69 73 20 74 68 65 20 64 65  (which is the de
12970 66 61 75 6c 74 20 77 68 65 6e 20 53 51 4c 69 74  fault when SQLit
12980 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69  e is compiled wi
12990 74 68 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 54 48  th.** [SQLITE_TH
129a0 52 45 41 44 53 41 46 45 3d 31 5d 29 20 74 68 65  READSAFE=1]) the
129b0 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 20   SQLite library 
129c0 77 69 6c 6c 20 69 74 73 65 6c 66 20 73 65 72 69  will itself seri
129d0 61 6c 69 7a 65 20 61 63 63 65 73 73 0a 2a 2a 20  alize access.** 
129e0 74 6f 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  to [database con
129f0 6e 65 63 74 69 6f 6e 73 5d 20 61 6e 64 20 5b 70  nections] and [p
12a00 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
12a10 74 73 5d 20 73 6f 20 74 68 61 74 20 74 68 65 0a  ts] so that the.
12a20 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69  ** application i
12a30 73 20 66 72 65 65 20 74 6f 20 75 73 65 20 74 68  s free to use th
12a40 65 20 73 61 6d 65 20 5b 64 61 74 61 62 61 73 65  e same [database
12a50 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 72 20   connection] or 
12a60 74 68 65 0a 2a 2a 20 73 61 6d 65 20 5b 70 72 65  the.** same [pre
12a70 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
12a80 20 69 6e 20 64 69 66 66 65 72 65 6e 74 20 74 68   in different th
12a90 72 65 61 64 73 20 61 74 20 74 68 65 20 73 61 6d  reads at the sam
12aa0 65 20 74 69 6d 65 2e 0a 2a 2a 20 5e 49 66 20 53  e time..** ^If S
12ab0 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65  QLite is compile
12ac0 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53  d with.** the [S
12ad0 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
12ae0 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44   | SQLITE_THREAD
12af0 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d  SAFE=0] compile-
12b00 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e  time option then
12b10 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20 70 6f  .** it is not po
12b20 73 73 69 62 6c 65 20 74 6f 20 73 65 74 20 74 68  ssible to set th
12b30 65 20 53 65 72 69 61 6c 69 7a 65 64 20 5b 74 68  e Serialized [th
12b40 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61 6e  reading mode] an
12b50 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  d.** [sqlite3_co
12b60 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20 72 65 74  nfig()] will ret
12b70 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  urn [SQLITE_ERRO
12b80 52 5d 20 69 66 20 63 61 6c 6c 65 64 20 77 69 74  R] if called wit
12b90 68 20 74 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f  h the.** SQLITE_
12ba0 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45  CONFIG_SERIALIZE
12bb0 44 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  D configuration 
12bc0 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a  option.</dd>.**.
12bd0 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
12be0 49 47 5f 4d 41 4c 4c 4f 43 5d 5d 20 3c 64 74 3e  IG_MALLOC]] <dt>
12bf0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41  SQLITE_CONFIG_MA
12c00 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  LLOC</dt>.** <dd
12c10 3e 20 5e 28 54 68 65 20 53 51 4c 49 54 45 5f 43  > ^(The SQLITE_C
12c20 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 20 6f 70 74  ONFIG_MALLOC opt
12c30 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67  ion takes a sing
12c40 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63  le argument whic
12c50 68 20 69 73 20 0a 2a 2a 20 61 20 70 6f 69 6e 74  h is .** a point
12c60 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63  er to an instanc
12c70 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  e of the [sqlite
12c80 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73  3_mem_methods] s
12c90 74 72 75 63 74 75 72 65 2e 0a 2a 2a 20 54 68 65  tructure..** The
12ca0 20 61 72 67 75 6d 65 6e 74 20 73 70 65 63 69 66   argument specif
12cb0 69 65 73 0a 2a 2a 20 61 6c 74 65 72 6e 61 74 69  ies.** alternati
12cc0 76 65 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d  ve low-level mem
12cd0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72  ory allocation r
12ce0 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20 75 73  outines to be us
12cf0 65 64 20 69 6e 20 70 6c 61 63 65 20 6f 66 0a 2a  ed in place of.*
12d00 2a 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c  * the memory all
12d10 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73  ocation routines
12d20 20 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69   built into SQLi
12d30 74 65 2e 29 5e 20 5e 53 51 4c 69 74 65 20 6d 61  te.)^ ^SQLite ma
12d40 6b 65 73 0a 2a 2a 20 69 74 73 20 6f 77 6e 20 70  kes.** its own p
12d50 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20 74  rivate copy of t
12d60 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68  he content of th
12d70 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d  e [sqlite3_mem_m
12d80 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72  ethods] structur
12d90 65 0a 2a 2a 20 62 65 66 6f 72 65 20 74 68 65 20  e.** before the 
12da0 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
12db0 29 5d 20 63 61 6c 6c 20 72 65 74 75 72 6e 73 2e  )] call returns.
12dc0 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
12dd0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d  LITE_CONFIG_GETM
12de0 41 4c 4c 4f 43 5d 5d 20 3c 64 74 3e 53 51 4c 49  ALLOC]] <dt>SQLI
12df0 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c  TE_CONFIG_GETMAL
12e00 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  LOC</dt>.** <dd>
12e10 20 5e 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f   ^(The SQLITE_CO
12e20 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 20 6f  NFIG_GETMALLOC o
12e30 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69  ption takes a si
12e40 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68  ngle argument wh
12e50 69 63 68 0a 2a 2a 20 69 73 20 61 20 70 6f 69 6e  ich.** is a poin
12e60 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e  ter to an instan
12e70 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  ce of the [sqlit
12e80 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20  e3_mem_methods] 
12e90 73 74 72 75 63 74 75 72 65 2e 0a 2a 2a 20 54 68  structure..** Th
12ea0 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d  e [sqlite3_mem_m
12eb0 65 74 68 6f 64 73 5d 0a 2a 2a 20 73 74 72 75 63  ethods].** struc
12ec0 74 75 72 65 20 69 73 20 66 69 6c 6c 65 64 20 77  ture is filled w
12ed0 69 74 68 20 74 68 65 20 63 75 72 72 65 6e 74 6c  ith the currentl
12ee0 79 20 64 65 66 69 6e 65 64 20 6d 65 6d 6f 72 79  y defined memory
12ef0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74   allocation rout
12f00 69 6e 65 73 2e 29 5e 0a 2a 2a 20 54 68 69 73 20  ines.)^.** This 
12f10 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 73  option can be us
12f20 65 64 20 74 6f 20 6f 76 65 72 6c 6f 61 64 20 74  ed to overload t
12f30 68 65 20 64 65 66 61 75 6c 74 20 6d 65 6d 6f 72  he default memor
12f40 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20  y allocation.** 
12f50 72 6f 75 74 69 6e 65 73 20 77 69 74 68 20 61 20  routines with a 
12f60 77 72 61 70 70 65 72 20 74 68 61 74 20 73 69 6d  wrapper that sim
12f70 75 6c 61 74 69 6f 6e 73 20 6d 65 6d 6f 72 79 20  ulations memory 
12f80 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 75  allocation failu
12f90 72 65 20 6f 72 0a 2a 2a 20 74 72 61 63 6b 73 20  re or.** tracks 
12fa0 6d 65 6d 6f 72 79 20 75 73 61 67 65 2c 20 66 6f  memory usage, fo
12fb0 72 20 65 78 61 6d 70 6c 65 2e 20 3c 2f 64 64 3e  r example. </dd>
12fc0 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
12fd0 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53  CONFIG_MEMSTATUS
12fe0 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
12ff0 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 3c 2f  NFIG_MEMSTATUS</
13000 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 65  dt>.** <dd> ^The
13010 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d   SQLITE_CONFIG_M
13020 45 4d 53 54 41 54 55 53 20 6f 70 74 69 6f 6e 20  EMSTATUS option 
13030 74 61 6b 65 73 20 73 69 6e 67 6c 65 20 61 72 67  takes single arg
13040 75 6d 65 6e 74 20 6f 66 20 74 79 70 65 20 69 6e  ument of type in
13050 74 2c 0a 2a 2a 20 69 6e 74 65 72 70 72 65 74 65  t,.** interprete
13060 64 20 61 73 20 61 20 62 6f 6f 6c 65 61 6e 2c 20  d as a boolean, 
13070 77 68 69 63 68 20 65 6e 61 62 6c 65 73 20 6f 72  which enables or
13080 20 64 69 73 61 62 6c 65 73 20 74 68 65 20 63 6f   disables the co
13090 6c 6c 65 63 74 69 6f 6e 20 6f 66 0a 2a 2a 20 6d  llection of.** m
130a0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
130b0 20 73 74 61 74 69 73 74 69 63 73 2e 20 5e 28 57   statistics. ^(W
130c0 68 65 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  hen memory alloc
130d0 61 74 69 6f 6e 20 73 74 61 74 69 73 74 69 63 73  ation statistics
130e0 20 61 72 65 0a 2a 2a 20 64 69 73 61 62 6c 65 64   are.** disabled
130f0 2c 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  , the following 
13100 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65  SQLite interface
13110 73 20 62 65 63 6f 6d 65 20 6e 6f 6e 2d 6f 70 65  s become non-ope
13120 72 61 74 69 6f 6e 61 6c 3a 0a 2a 2a 20 20 20 3c  rational:.**   <
13130 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73  ul>.**   <li> [s
13140 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73  qlite3_memory_us
13150 65 64 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20  ed()].**   <li> 
13160 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f  [sqlite3_memory_
13170 68 69 67 68 77 61 74 65 72 28 29 5d 0a 2a 2a 20  highwater()].** 
13180 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f    <li> [sqlite3_
13190 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 36  soft_heap_limit6
131a0 34 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b  4()].**   <li> [
131b0 73 71 6c 69 74 65 33 5f 73 74 61 74 75 73 36 34  sqlite3_status64
131c0 28 29 5d 0a 2a 2a 20 20 20 3c 2f 75 6c 3e 29 5e  ()].**   </ul>)^
131d0 0a 2a 2a 20 5e 4d 65 6d 6f 72 79 20 61 6c 6c 6f  .** ^Memory allo
131e0 63 61 74 69 6f 6e 20 73 74 61 74 69 73 74 69 63  cation statistic
131f0 73 20 61 72 65 20 65 6e 61 62 6c 65 64 20 62 79  s are enabled by
13200 20 64 65 66 61 75 6c 74 20 75 6e 6c 65 73 73 20   default unless 
13210 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20 63 6f 6d  SQLite is.** com
13220 70 69 6c 65 64 20 77 69 74 68 20 5b 53 51 4c 49  piled with [SQLI
13230 54 45 5f 44 45 46 41 55 4c 54 5f 4d 45 4d 53 54  TE_DEFAULT_MEMST
13240 41 54 55 53 5d 3d 30 20 69 6e 20 77 68 69 63 68  ATUS]=0 in which
13250 20 63 61 73 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20   case memory.** 
13260 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 69  allocation stati
13270 73 74 69 63 73 20 61 72 65 20 64 69 73 61 62 6c  stics are disabl
13280 65 64 20 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a  ed by default..*
13290 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  * </dd>.**.** [[
132a0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43  SQLITE_CONFIG_SC
132b0 52 41 54 43 48 5d 5d 20 3c 64 74 3e 53 51 4c 49  RATCH]] <dt>SQLI
132c0 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43  TE_CONFIG_SCRATC
132d0 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  H</dt>.** <dd> ^
132e0 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  The SQLITE_CONFI
132f0 47 5f 53 43 52 41 54 43 48 20 6f 70 74 69 6f 6e  G_SCRATCH option
13300 20 73 70 65 63 69 66 69 65 73 20 61 20 73 74 61   specifies a sta
13310 74 69 63 20 6d 65 6d 6f 72 79 20 62 75 66 66 65  tic memory buffe
13320 72 0a 2a 2a 20 74 68 61 74 20 53 51 4c 69 74 65  r.** that SQLite
13330 20 63 61 6e 20 75 73 65 20 66 6f 72 20 73 63 72   can use for scr
13340 61 74 63 68 20 6d 65 6d 6f 72 79 2e 20 20 5e 28  atch memory.  ^(
13350 54 68 65 72 65 20 61 72 65 20 74 68 72 65 65 20  There are three 
13360 61 72 67 75 6d 65 6e 74 73 0a 2a 2a 20 74 6f 20  arguments.** to 
13370 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43  SQLITE_CONFIG_SC
13380 52 41 54 43 48 3a 20 20 41 20 70 6f 69 6e 74 65  RATCH:  A pointe
13390 72 20 61 6e 20 38 2d 62 79 74 65 0a 2a 2a 20 61  r an 8-byte.** a
133a0 6c 69 67 6e 65 64 20 6d 65 6d 6f 72 79 20 62 75  ligned memory bu
133b0 66 66 65 72 20 66 72 6f 6d 20 77 68 69 63 68 20  ffer from which 
133c0 74 68 65 20 73 63 72 61 74 63 68 20 61 6c 6c 6f  the scratch allo
133d0 63 61 74 69 6f 6e 73 20 77 69 6c 6c 20 62 65 0a  cations will be.
133e0 2a 2a 20 64 72 61 77 6e 2c 20 74 68 65 20 73 69  ** drawn, the si
133f0 7a 65 20 6f 66 20 65 61 63 68 20 73 63 72 61 74  ze of each scrat
13400 63 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 28 73  ch allocation (s
13410 7a 29 2c 0a 2a 2a 20 61 6e 64 20 74 68 65 20 6d  z),.** and the m
13420 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66  aximum number of
13430 20 73 63 72 61 74 63 68 20 61 6c 6c 6f 63 61 74   scratch allocat
13440 69 6f 6e 73 20 28 4e 29 2e 29 5e 0a 2a 2a 20 54  ions (N).)^.** T
13450 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
13460 74 20 6d 75 73 74 20 62 65 20 61 20 70 6f 69 6e  t must be a poin
13470 74 65 72 20 74 6f 20 61 6e 20 38 2d 62 79 74 65  ter to an 8-byte
13480 20 61 6c 69 67 6e 65 64 20 62 75 66 66 65 72 0a   aligned buffer.
13490 2a 2a 20 6f 66 20 61 74 20 6c 65 61 73 74 20 73  ** of at least s
134a0 7a 2a 4e 20 62 79 74 65 73 20 6f 66 20 6d 65 6d  z*N bytes of mem
134b0 6f 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20  ory..** ^SQLite 
134c0 77 69 6c 6c 20 6e 6f 74 20 75 73 65 20 6d 6f 72  will not use mor
134d0 65 20 74 68 61 6e 20 6f 6e 65 20 73 63 72 61 74  e than one scrat
134e0 63 68 20 62 75 66 66 65 72 73 20 70 65 72 20 74  ch buffers per t
134f0 68 72 65 61 64 2e 0a 2a 2a 20 5e 53 51 4c 69 74  hread..** ^SQLit
13500 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 72 65 71  e will never req
13510 75 65 73 74 20 61 20 73 63 72 61 74 63 68 20 62  uest a scratch b
13520 75 66 66 65 72 20 74 68 61 74 20 69 73 20 6d 6f  uffer that is mo
13530 72 65 20 74 68 61 6e 20 36 0a 2a 2a 20 74 69 6d  re than 6.** tim
13540 65 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20  es the database 
13550 70 61 67 65 20 73 69 7a 65 2e 0a 2a 2a 20 5e 49  page size..** ^I
13560 66 20 53 51 4c 69 74 65 20 6e 65 65 64 73 20 6e  f SQLite needs n
13570 65 65 64 73 20 61 64 64 69 74 69 6f 6e 61 6c 0a  eeds additional.
13580 2a 2a 20 73 63 72 61 74 63 68 20 6d 65 6d 6f 72  ** scratch memor
13590 79 20 62 65 79 6f 6e 64 20 77 68 61 74 20 69 73  y beyond what is
135a0 20 70 72 6f 76 69 64 65 64 20 62 79 20 74 68 69   provided by thi
135b0 73 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  s configuration 
135c0 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 20 0a 2a 2a  option, then .**
135d0 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
135e0 28 29 5d 20 77 69 6c 6c 20 62 65 20 75 73 65 64  ()] will be used
135f0 20 74 6f 20 6f 62 74 61 69 6e 20 74 68 65 20 6d   to obtain the m
13600 65 6d 6f 72 79 20 6e 65 65 64 65 64 2e 3c 70 3e  emory needed.<p>
13610 0a 2a 2a 20 5e 57 68 65 6e 20 74 68 65 20 61 70  .** ^When the ap
13620 70 6c 69 63 61 74 69 6f 6e 20 70 72 6f 76 69 64  plication provid
13630 65 73 20 61 6e 79 20 61 6d 6f 75 6e 74 20 6f 66  es any amount of
13640 20 73 63 72 61 74 63 68 20 6d 65 6d 6f 72 79 20   scratch memory 
13650 75 73 69 6e 67 0a 2a 2a 20 53 51 4c 49 54 45 5f  using.** SQLITE_
13660 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 2c 20  CONFIG_SCRATCH, 
13670 53 51 4c 69 74 65 20 61 76 6f 69 64 73 20 75 6e  SQLite avoids un
13680 6e 65 63 65 73 73 61 72 79 20 6c 61 72 67 65 0a  necessary large.
13690 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  ** [sqlite3_mall
136a0 6f 63 7c 68 65 61 70 20 61 6c 6c 6f 63 61 74 69  oc|heap allocati
136b0 6f 6e 73 5d 2e 0a 2a 2a 20 54 68 69 73 20 63 61  ons]..** This ca
136c0 6e 20 68 65 6c 70 20 5b 52 6f 62 73 6f 6e 20 70  n help [Robson p
136d0 72 6f 6f 66 7c 70 72 65 76 65 6e 74 20 6d 65 6d  roof|prevent mem
136e0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66  ory allocation f
136f0 61 69 6c 75 72 65 73 5d 20 64 75 65 20 74 6f 20  ailures] due to 
13700 68 65 61 70 0a 2a 2a 20 66 72 61 67 6d 65 6e 74  heap.** fragment
13710 61 74 69 6f 6e 20 69 6e 20 6c 6f 77 2d 6d 65 6d  ation in low-mem
13720 6f 72 79 20 65 6d 62 65 64 64 65 64 20 73 79 73  ory embedded sys
13730 74 65 6d 73 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a  tems..** </dd>.*
13740 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
13750 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 5d 5d  NFIG_PAGECACHE]]
13760 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
13770 49 47 5f 50 41 47 45 43 41 43 48 45 3c 2f 64 74  IG_PAGECACHE</dt
13780 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 65 20 53  >.** <dd> ^The S
13790 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47  QLITE_CONFIG_PAG
137a0 45 43 41 43 48 45 20 6f 70 74 69 6f 6e 20 73 70  ECACHE option sp
137b0 65 63 69 66 69 65 73 20 61 20 6d 65 6d 6f 72 79  ecifies a memory
137c0 20 70 6f 6f 6c 0a 2a 2a 20 74 68 61 74 20 53 51   pool.** that SQ
137d0 4c 69 74 65 20 63 61 6e 20 75 73 65 20 66 6f 72  Lite can use for
137e0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 70 61   the database pa
137f0 67 65 20 63 61 63 68 65 20 77 69 74 68 20 74 68  ge cache with th
13800 65 20 64 65 66 61 75 6c 74 20 70 61 67 65 0a 2a  e default page.*
13810 2a 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e  * cache implemen
13820 74 61 74 69 6f 6e 2e 20 20 0a 2a 2a 20 54 68 69  tation.  .** Thi
13830 73 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  s configuration 
13840 6f 70 74 69 6f 6e 20 69 73 20 61 20 6e 6f 2d 6f  option is a no-o
13850 70 20 69 66 20 61 6e 20 61 70 70 6c 69 63 61 74  p if an applicat
13860 69 6f 6e 2d 64 65 66 69 6e 65 20 70 61 67 65 0a  ion-define page.
13870 2a 2a 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65  ** cache impleme
13880 6e 74 61 74 69 6f 6e 20 69 73 20 6c 6f 61 64 65  ntation is loade
13890 64 20 75 73 69 6e 67 20 74 68 65 20 5b 53 51 4c  d using the [SQL
138a0 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48  ITE_CONFIG_PCACH
138b0 45 32 5d 2e 0a 2a 2a 20 5e 54 68 65 72 65 20 61  E2]..** ^There a
138c0 72 65 20 74 68 72 65 65 20 61 72 67 75 6d 65 6e  re three argumen
138d0 74 73 20 74 6f 20 53 51 4c 49 54 45 5f 43 4f 4e  ts to SQLITE_CON
138e0 46 49 47 5f 50 41 47 45 43 41 43 48 45 3a 20 41  FIG_PAGECACHE: A
138f0 20 70 6f 69 6e 74 65 72 20 74 6f 0a 2a 2a 20 38   pointer to.** 8
13900 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 20 6d 65  -byte aligned me
13910 6d 6f 72 79 20 28 70 4d 65 6d 29 2c 20 74 68 65  mory (pMem), the
13920 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20 70 61   size of each pa
13930 67 65 20 63 61 63 68 65 20 6c 69 6e 65 20 28 73  ge cache line (s
13940 7a 29 2c 0a 2a 2a 20 61 6e 64 20 74 68 65 20 6e  z),.** and the n
13950 75 6d 62 65 72 20 6f 66 20 63 61 63 68 65 20 6c  umber of cache l
13960 69 6e 65 73 20 28 4e 29 2e 0a 2a 2a 20 54 68 65  ines (N)..** The
13970 20 73 7a 20 61 72 67 75 6d 65 6e 74 20 73 68 6f   sz argument sho
13980 75 6c 64 20 62 65 20 74 68 65 20 73 69 7a 65 20  uld be the size 
13990 6f 66 20 74 68 65 20 6c 61 72 67 65 73 74 20 64  of the largest d
139a0 61 74 61 62 61 73 65 20 70 61 67 65 0a 2a 2a 20  atabase page.** 
139b0 28 61 20 70 6f 77 65 72 20 6f 66 20 74 77 6f 20  (a power of two 
139c0 62 65 74 77 65 65 6e 20 35 31 32 20 61 6e 64 20  between 512 and 
139d0 36 35 35 33 36 29 20 70 6c 75 73 20 73 6f 6d 65  65536) plus some
139e0 20 65 78 74 72 61 20 62 79 74 65 73 20 66 6f 72   extra bytes for
139f0 20 65 61 63 68 0a 2a 2a 20 70 61 67 65 20 68 65   each.** page he
13a00 61 64 65 72 2e 20 20 5e 54 68 65 20 6e 75 6d 62  ader.  ^The numb
13a10 65 72 20 6f 66 20 65 78 74 72 61 20 62 79 74 65  er of extra byte
13a20 73 20 6e 65 65 64 65 64 20 62 79 20 74 68 65 20  s needed by the 
13a30 70 61 67 65 20 68 65 61 64 65 72 0a 2a 2a 20 63  page header.** c
13a40 61 6e 20 62 65 20 64 65 74 65 72 6d 69 6e 65 64  an be determined
13a50 20 75 73 69 6e 67 20 5b 53 51 4c 49 54 45 5f 43   using [SQLITE_C
13a60 4f 4e 46 49 47 5f 50 43 41 43 48 45 5f 48 44 52  ONFIG_PCACHE_HDR
13a70 53 5a 5d 2e 0a 2a 2a 20 5e 49 74 20 69 73 20 68  SZ]..** ^It is h
13a80 61 72 6d 6c 65 73 73 2c 20 61 70 61 72 74 20 66  armless, apart f
13a90 72 6f 6d 20 74 68 65 20 77 61 73 74 65 64 20 6d  rom the wasted m
13aa0 65 6d 6f 72 79 2c 0a 2a 2a 20 66 6f 72 20 74 68  emory,.** for th
13ab0 65 20 73 7a 20 70 61 72 61 6d 65 74 65 72 20 74  e sz parameter t
13ac0 6f 20 62 65 20 6c 61 72 67 65 72 20 74 68 61 6e  o be larger than
13ad0 20 6e 65 63 65 73 73 61 72 79 2e 20 20 54 68 65   necessary.  The
13ae0 20 70 4d 65 6d 0a 2a 2a 20 61 72 67 75 6d 65 6e   pMem.** argumen
13af0 74 20 6d 75 73 74 20 62 65 20 65 69 74 68 65 72  t must be either
13b00 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
13b10 6f 72 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  or a pointer to 
13b20 61 6e 20 38 2d 62 79 74 65 0a 2a 2a 20 61 6c 69  an 8-byte.** ali
13b30 67 6e 65 64 20 62 6c 6f 63 6b 20 6f 66 20 6d 65  gned block of me
13b40 6d 6f 72 79 20 6f 66 20 61 74 20 6c 65 61 73 74  mory of at least
13b50 20 73 7a 2a 4e 20 62 79 74 65 73 2c 20 6f 74 68   sz*N bytes, oth
13b60 65 72 77 69 73 65 0a 2a 2a 20 73 75 62 73 65 71  erwise.** subseq
13b70 75 65 6e 74 20 62 65 68 61 76 69 6f 72 20 69 73  uent behavior is
13b80 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 5e   undefined..** ^
13b90 57 68 65 6e 20 70 4d 65 6d 20 69 73 20 6e 6f 74  When pMem is not
13ba0 20 4e 55 4c 4c 2c 20 53 51 4c 69 74 65 20 77 69   NULL, SQLite wi
13bb0 6c 6c 20 73 74 72 69 76 65 20 74 6f 20 75 73 65  ll strive to use
13bc0 20 74 68 65 20 6d 65 6d 6f 72 79 20 70 72 6f 76   the memory prov
13bd0 69 64 65 64 0a 2a 2a 20 74 6f 20 73 61 74 69 73  ided.** to satis
13be0 66 79 20 70 61 67 65 20 63 61 63 68 65 20 6e 65  fy page cache ne
13bf0 65 64 73 2c 20 66 61 6c 6c 69 6e 67 20 62 61 63  eds, falling bac
13c00 6b 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6d 61  k to [sqlite3_ma
13c10 6c 6c 6f 63 28 29 5d 20 69 66 0a 2a 2a 20 61 20  lloc()] if.** a 
13c20 70 61 67 65 20 63 61 63 68 65 20 6c 69 6e 65 20  page cache line 
13c30 69 73 20 6c 61 72 67 65 72 20 74 68 61 6e 20 73  is larger than s
13c40 7a 20 62 79 74 65 73 20 6f 72 20 69 66 20 61 6c  z bytes or if al
13c50 6c 20 6f 66 20 74 68 65 20 70 4d 65 6d 20 62 75  l of the pMem bu
13c60 66 66 65 72 0a 2a 2a 20 69 73 20 65 78 68 61 75  ffer.** is exhau
13c70 73 74 65 64 2e 0a 2a 2a 20 5e 49 66 20 70 4d 65  sted..** ^If pMe
13c80 6d 20 69 73 20 4e 55 4c 4c 20 61 6e 64 20 4e 20  m is NULL and N 
13c90 69 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65  is non-zero, the
13ca0 6e 20 65 61 63 68 20 64 61 74 61 62 61 73 65 20  n each database 
13cb0 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 64 6f  connection.** do
13cc0 65 73 20 61 6e 20 69 6e 69 74 69 61 6c 20 62 75  es an initial bu
13cd0 6c 6b 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 6f  lk allocation fo
13ce0 72 20 70 61 67 65 20 63 61 63 68 65 20 6d 65 6d  r page cache mem
13cf0 6f 72 79 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c  ory.** from [sql
13d00 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 73  ite3_malloc()] s
13d10 75 66 66 69 63 69 65 6e 74 20 66 6f 72 20 4e 20  ufficient for N 
13d20 63 61 63 68 65 20 6c 69 6e 65 73 20 69 66 20 4e  cache lines if N
13d30 20 69 73 20 70 6f 73 69 74 69 76 65 20 6f 72 0a   is positive or.
13d40 2a 2a 20 6f 66 20 2d 31 30 32 34 2a 4e 20 62 79  ** of -1024*N by
13d50 74 65 73 20 69 66 20 4e 20 69 73 20 6e 65 67 61  tes if N is nega
13d60 74 69 76 65 2c 20 2e 20 5e 49 66 20 61 64 64 69  tive, . ^If addi
13d70 74 69 6f 6e 61 6c 0a 2a 2a 20 70 61 67 65 20 63  tional.** page c
13d80 61 63 68 65 20 6d 65 6d 6f 72 79 20 69 73 20 6e  ache memory is n
13d90 65 65 64 65 64 20 62 65 79 6f 6e 64 20 77 68 61  eeded beyond wha
13da0 74 20 69 73 20 70 72 6f 76 69 64 65 64 20 62 79  t is provided by
13db0 20 74 68 65 20 69 6e 69 74 69 61 6c 0a 2a 2a 20   the initial.** 
13dc0 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20 74 68 65 6e  allocation, then
13dd0 20 53 51 4c 69 74 65 20 67 6f 65 73 20 74 6f 20   SQLite goes to 
13de0 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
13df0 29 5d 20 73 65 70 61 72 61 74 65 6c 79 20 66 6f  )] separately fo
13e00 72 20 65 61 63 68 0a 2a 2a 20 61 64 64 69 74 69  r each.** additi
13e10 6f 6e 61 6c 20 63 61 63 68 65 20 6c 69 6e 65 2e  onal cache line.
13e20 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53   </dd>.**.** [[S
13e30 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41  QLITE_CONFIG_HEA
13e40 50 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  P]] <dt>SQLITE_C
13e50 4f 4e 46 49 47 5f 48 45 41 50 3c 2f 64 74 3e 0a  ONFIG_HEAP</dt>.
13e60 2a 2a 20 3c 64 64 3e 20 5e 54 68 65 20 53 51 4c  ** <dd> ^The SQL
13e70 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 20  ITE_CONFIG_HEAP 
13e80 6f 70 74 69 6f 6e 20 73 70 65 63 69 66 69 65 73  option specifies
13e90 20 61 20 73 74 61 74 69 63 20 6d 65 6d 6f 72 79   a static memory
13ea0 20 62 75 66 66 65 72 20 0a 2a 2a 20 74 68 61 74   buffer .** that
13eb0 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65   SQLite will use
13ec0 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73 20   for all of its 
13ed0 64 79 6e 61 6d 69 63 20 6d 65 6d 6f 72 79 20 61  dynamic memory a
13ee0 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 0a  llocation needs.
13ef0 2a 2a 20 62 65 79 6f 6e 64 20 74 68 6f 73 65 20  ** beyond those 
13f00 70 72 6f 76 69 64 65 64 20 66 6f 72 20 62 79 20  provided for by 
13f10 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53  [SQLITE_CONFIG_S
13f20 43 52 41 54 43 48 5d 20 61 6e 64 0a 2a 2a 20 5b  CRATCH] and.** [
13f30 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41  SQLITE_CONFIG_PA
13f40 47 45 43 41 43 48 45 5d 2e 0a 2a 2a 20 5e 54 68  GECACHE]..** ^Th
13f50 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
13f60 48 45 41 50 20 6f 70 74 69 6f 6e 20 69 73 20 6f  HEAP option is o
13f70 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 69 66  nly available if
13f80 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69   SQLite is compi
13f90 6c 65 64 0a 2a 2a 20 77 69 74 68 20 65 69 74 68  led.** with eith
13fa0 65 72 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c  er [SQLITE_ENABL
13fb0 45 5f 4d 45 4d 53 59 53 33 5d 20 6f 72 20 5b 53  E_MEMSYS3] or [S
13fc0 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d  QLITE_ENABLE_MEM
13fd0 53 59 53 35 5d 20 61 6e 64 20 72 65 74 75 72 6e  SYS5] and return
13fe0 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52  s.** [SQLITE_ERR
13ff0 4f 52 5d 20 69 66 20 69 6e 76 6f 6b 65 64 20 6f  OR] if invoked o
14000 74 68 65 72 77 69 73 65 2e 0a 2a 2a 20 5e 54 68  therwise..** ^Th
14010 65 72 65 20 61 72 65 20 74 68 72 65 65 20 61 72  ere are three ar
14020 67 75 6d 65 6e 74 73 20 74 6f 20 53 51 4c 49 54  guments to SQLIT
14030 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 3a 0a 2a  E_CONFIG_HEAP:.*
14040 2a 20 41 6e 20 38 2d 62 79 74 65 20 61 6c 69 67  * An 8-byte alig
14050 6e 65 64 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  ned pointer to t
14060 68 65 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20 74 68  he memory,.** th
14070 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  e number of byte
14080 73 20 69 6e 20 74 68 65 20 6d 65 6d 6f 72 79 20  s in the memory 
14090 62 75 66 66 65 72 2c 20 61 6e 64 20 74 68 65 20  buffer, and the 
140a0 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69  minimum allocati
140b0 6f 6e 20 73 69 7a 65 2e 0a 2a 2a 20 5e 49 66 20  on size..** ^If 
140c0 74 68 65 20 66 69 72 73 74 20 70 6f 69 6e 74 65  the first pointe
140d0 72 20 28 74 68 65 20 6d 65 6d 6f 72 79 20 70 6f  r (the memory po
140e0 69 6e 74 65 72 29 20 69 73 20 4e 55 4c 4c 2c 20  inter) is NULL, 
140f0 74 68 65 6e 20 53 51 4c 69 74 65 20 72 65 76 65  then SQLite reve
14100 72 74 73 0a 2a 2a 20 74 6f 20 75 73 69 6e 67 20  rts.** to using 
14110 69 74 73 20 64 65 66 61 75 6c 74 20 6d 65 6d 6f  its default memo
14120 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 28 74 68  ry allocator (th
14130 65 20 73 79 73 74 65 6d 20 6d 61 6c 6c 6f 63 28  e system malloc(
14140 29 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  ) implementation
14150 29 2c 0a 2a 2a 20 75 6e 64 6f 69 6e 67 20 61 6e  ),.** undoing an
14160 79 20 70 72 69 6f 72 20 69 6e 76 6f 63 61 74 69  y prior invocati
14170 6f 6e 20 6f 66 20 5b 53 51 4c 49 54 45 5f 43 4f  on of [SQLITE_CO
14180 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 2e 20 20 5e  NFIG_MALLOC].  ^
14190 49 66 20 74 68 65 0a 2a 2a 20 6d 65 6d 6f 72 79  If the.** memory
141a0 20 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74 20   pointer is not 
141b0 4e 55 4c 4c 20 74 68 65 6e 20 74 68 65 20 61 6c  NULL then the al
141c0 74 65 72 6e 61 74 69 76 65 20 6d 65 6d 6f 72 79  ternative memory
141d0 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72 20 69 73  .** allocator is
141e0 20 65 6e 67 61 67 65 64 20 74 6f 20 68 61 6e 64   engaged to hand
141f0 6c 65 20 61 6c 6c 20 6f 66 20 53 51 4c 69 74 65  le all of SQLite
14200 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  s memory allocat
14210 69 6f 6e 20 6e 65 65 64 73 2e 0a 2a 2a 20 54 68  ion needs..** Th
14220 65 20 66 69 72 73 74 20 70 6f 69 6e 74 65 72 20  e first pointer 
14230 28 74 68 65 20 6d 65 6d 6f 72 79 20 70 6f 69 6e  (the memory poin
14240 74 65 72 29 20 6d 75 73 74 20 62 65 20 61 6c 69  ter) must be ali
14250 67 6e 65 64 20 74 6f 20 61 6e 20 38 2d 62 79 74  gned to an 8-byt
14260 65 0a 2a 2a 20 62 6f 75 6e 64 61 72 79 20 6f 72  e.** boundary or
14270 20 73 75 62 73 65 71 75 65 6e 74 20 62 65 68 61   subsequent beha
14280 76 69 6f 72 20 6f 66 20 53 51 4c 69 74 65 20 77  vior of SQLite w
14290 69 6c 6c 20 62 65 20 75 6e 64 65 66 69 6e 65 64  ill be undefined
142a0 2e 0a 2a 2a 20 54 68 65 20 6d 69 6e 69 6d 75 6d  ..** The minimum
142b0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65   allocation size
142c0 20 69 73 20 63 61 70 70 65 64 20 61 74 20 32 2a   is capped at 2*
142d0 2a 31 32 2e 20 52 65 61 73 6f 6e 61 62 6c 65 20  *12. Reasonable 
142e0 76 61 6c 75 65 73 0a 2a 2a 20 66 6f 72 20 74 68  values.** for th
142f0 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61  e minimum alloca
14300 74 69 6f 6e 20 73 69 7a 65 20 61 72 65 20 32 2a  tion size are 2*
14310 2a 35 20 74 68 72 6f 75 67 68 20 32 2a 2a 38 2e  *5 through 2**8.
14320 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
14330 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45  LITE_CONFIG_MUTE
14340 58 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  X]] <dt>SQLITE_C
14350 4f 4e 46 49 47 5f 4d 55 54 45 58 3c 2f 64 74 3e  ONFIG_MUTEX</dt>
14360 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 53  .** <dd> ^(The S
14370 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54  QLITE_CONFIG_MUT
14380 45 58 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  EX option takes 
14390 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e  a single argumen
143a0 74 20 77 68 69 63 68 20 69 73 20 61 0a 2a 2a 20  t which is a.** 
143b0 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e  pointer to an in
143c0 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73  stance of the [s
143d0 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74  qlite3_mutex_met
143e0 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e  hods] structure.
143f0 0a 2a 2a 20 54 68 65 20 61 72 67 75 6d 65 6e 74  .** The argument
14400 20 73 70 65 63 69 66 69 65 73 20 61 6c 74 65 72   specifies alter
14410 6e 61 74 69 76 65 20 6c 6f 77 2d 6c 65 76 65 6c  native low-level
14420 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73 20   mutex routines 
14430 74 6f 20 62 65 20 75 73 65 64 0a 2a 2a 20 69 6e  to be used.** in
14440 20 70 6c 61 63 65 20 74 68 65 20 6d 75 74 65 78   place the mutex
14450 20 72 6f 75 74 69 6e 65 73 20 62 75 69 6c 74 20   routines built 
14460 69 6e 74 6f 20 53 51 4c 69 74 65 2e 29 5e 20 20  into SQLite.)^  
14470 5e 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 61 20  ^SQLite makes a 
14480 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 63  copy of.** the c
14490 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 5b 73  ontent of the [s
144a0 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74  qlite3_mutex_met
144b0 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 20  hods] structure 
144c0 62 65 66 6f 72 65 20 74 68 65 20 63 61 6c 6c 20  before the call 
144d0 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  to.** [sqlite3_c
144e0 6f 6e 66 69 67 28 29 5d 20 72 65 74 75 72 6e 73  onfig()] returns
144f0 2e 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20  . ^If SQLite is 
14500 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a  compiled with.**
14510 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52   the [SQLITE_THR
14520 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45  EADSAFE | SQLITE
14530 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63  _THREADSAFE=0] c
14540 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
14550 6f 6e 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 65  on then.** the e
14560 6e 74 69 72 65 20 6d 75 74 65 78 69 6e 67 20 73  ntire mutexing s
14570 75 62 73 79 73 74 65 6d 20 69 73 20 6f 6d 69 74  ubsystem is omit
14580 74 65 64 20 66 72 6f 6d 20 74 68 65 20 62 75 69  ted from the bui
14590 6c 64 20 61 6e 64 20 68 65 6e 63 65 20 63 61 6c  ld and hence cal
145a0 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  ls to.** [sqlite
145b0 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 74 68  3_config()] with
145c0 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46   the SQLITE_CONF
145d0 49 47 5f 4d 55 54 45 58 20 63 6f 6e 66 69 67 75  IG_MUTEX configu
145e0 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 77 69  ration option wi
145f0 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51  ll.** return [SQ
14600 4c 49 54 45 5f 45 52 52 4f 52 5d 2e 3c 2f 64 64  LITE_ERROR].</dd
14610 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
14620 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58  _CONFIG_GETMUTEX
14630 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
14640 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 3c 2f 64  NFIG_GETMUTEX</d
14650 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65  t>.** <dd> ^(The
14660 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47   SQLITE_CONFIG_G
14670 45 54 4d 55 54 45 58 20 6f 70 74 69 6f 6e 20 74  ETMUTEX option t
14680 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72  akes a single ar
14690 67 75 6d 65 6e 74 20 77 68 69 63 68 0a 2a 2a 20  gument which.** 
146a0 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
146b0 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  an instance of t
146c0 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  he [sqlite3_mute
146d0 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63  x_methods] struc
146e0 74 75 72 65 2e 20 20 54 68 65 0a 2a 2a 20 5b 73  ture.  The.** [s
146f0 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74  qlite3_mutex_met
14700 68 6f 64 73 5d 0a 2a 2a 20 73 74 72 75 63 74 75  hods].** structu
14710 72 65 20 69 73 20 66 69 6c 6c 65 64 20 77 69 74  re is filled wit
14720 68 20 74 68 65 20 63 75 72 72 65 6e 74 6c 79 20  h the currently 
14730 64 65 66 69 6e 65 64 20 6d 75 74 65 78 20 72 6f  defined mutex ro
14740 75 74 69 6e 65 73 2e 29 5e 0a 2a 2a 20 54 68 69  utines.)^.** Thi
14750 73 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20  s option can be 
14760 75 73 65 64 20 74 6f 20 6f 76 65 72 6c 6f 61 64  used to overload
14770 20 74 68 65 20 64 65 66 61 75 6c 74 20 6d 75 74   the default mut
14780 65 78 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a  ex allocation.**
14790 20 72 6f 75 74 69 6e 65 73 20 77 69 74 68 20 61   routines with a
147a0 20 77 72 61 70 70 65 72 20 75 73 65 64 20 74 6f   wrapper used to
147b0 20 74 72 61 63 6b 20 6d 75 74 65 78 20 75 73 61   track mutex usa
147c0 67 65 20 66 6f 72 20 70 65 72 66 6f 72 6d 61 6e  ge for performan
147d0 63 65 0a 2a 2a 20 70 72 6f 66 69 6c 69 6e 67 20  ce.** profiling 
147e0 6f 72 20 74 65 73 74 69 6e 67 2c 20 66 6f 72 20  or testing, for 
147f0 65 78 61 6d 70 6c 65 2e 20 20 20 5e 49 66 20 53  example.   ^If S
14800 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65  QLite is compile
14810 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53  d with.** the [S
14820 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
14830 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44   | SQLITE_THREAD
14840 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d  SAFE=0] compile-
14850 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e  time option then
14860 0a 2a 2a 20 74 68 65 20 65 6e 74 69 72 65 20 6d  .** the entire m
14870 75 74 65 78 69 6e 67 20 73 75 62 73 79 73 74 65  utexing subsyste
14880 6d 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f  m is omitted fro
14890 6d 20 74 68 65 20 62 75 69 6c 64 20 61 6e 64 20  m the build and 
148a0 68 65 6e 63 65 20 63 61 6c 6c 73 20 74 6f 0a 2a  hence calls to.*
148b0 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  * [sqlite3_confi
148c0 67 28 29 5d 20 77 69 74 68 20 74 68 65 20 53 51  g()] with the SQ
148d0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d  LITE_CONFIG_GETM
148e0 55 54 45 58 20 63 6f 6e 66 69 67 75 72 61 74 69  UTEX configurati
148f0 6f 6e 20 6f 70 74 69 6f 6e 20 77 69 6c 6c 0a 2a  on option will.*
14900 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  * return [SQLITE
14910 5f 45 52 52 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a  _ERROR].</dd>.**
14920 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
14930 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 5d 20  FIG_LOOKASIDE]] 
14940 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
14950 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64 74 3e  G_LOOKASIDE</dt>
14960 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 53  .** <dd> ^(The S
14970 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f  QLITE_CONFIG_LOO
14980 4b 41 53 49 44 45 20 6f 70 74 69 6f 6e 20 74 61  KASIDE option ta
14990 6b 65 73 20 74 77 6f 20 61 72 67 75 6d 65 6e 74  kes two argument
149a0 73 20 74 68 61 74 20 64 65 74 65 72 6d 69 6e 65  s that determine
149b0 0a 2a 2a 20 74 68 65 20 64 65 66 61 75 6c 74 20  .** the default 
149c0 73 69 7a 65 20 6f 66 20 6c 6f 6f 6b 61 73 69 64  size of lookasid
149d0 65 20 6d 65 6d 6f 72 79 20 6f 6e 20 65 61 63 68  e memory on each
149e0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
149f0 63 74 69 6f 6e 5d 2e 0a 2a 2a 20 54 68 65 20 66  ction]..** The f
14a00 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73  irst argument is
14a10 20 74 68 65 0a 2a 2a 20 73 69 7a 65 20 6f 66 20   the.** size of 
14a20 65 61 63 68 20 6c 6f 6f 6b 61 73 69 64 65 20 62  each lookaside b
14a30 75 66 66 65 72 20 73 6c 6f 74 20 61 6e 64 20 74  uffer slot and t
14a40 68 65 20 73 65 63 6f 6e 64 20 69 73 20 74 68 65  he second is the
14a50 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 73 6c   number of.** sl
14a60 6f 74 73 20 61 6c 6c 6f 63 61 74 65 64 20 74 6f  ots allocated to
14a70 20 65 61 63 68 20 64 61 74 61 62 61 73 65 20 63   each database c
14a80 6f 6e 6e 65 63 74 69 6f 6e 2e 29 5e 20 20 5e 28  onnection.)^  ^(
14a90 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f  SQLITE_CONFIG_LO
14aa0 4f 4b 41 53 49 44 45 0a 2a 2a 20 73 65 74 73 20  OKASIDE.** sets 
14ab0 74 68 65 20 3c 69 3e 64 65 66 61 75 6c 74 3c 2f  the <i>default</
14ac0 69 3e 20 6c 6f 6f 6b 61 73 69 64 65 20 73 69 7a  i> lookaside siz
14ad0 65 2e 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 44  e. The [SQLITE_D
14ae0 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44  BCONFIG_LOOKASID
14af0 45 5d 0a 2a 2a 20 6f 70 74 69 6f 6e 20 74 6f 20  E].** option to 
14b00 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66  [sqlite3_db_conf
14b10 69 67 28 29 5d 20 63 61 6e 20 62 65 20 75 73 65  ig()] can be use
14b20 64 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65 20  d to change the 
14b30 6c 6f 6f 6b 61 73 69 64 65 0a 2a 2a 20 63 6f 6e  lookaside.** con
14b40 66 69 67 75 72 61 74 69 6f 6e 20 6f 6e 20 69 6e  figuration on in
14b50 64 69 76 69 64 75 61 6c 20 63 6f 6e 6e 65 63 74  dividual connect
14b60 69 6f 6e 73 2e 29 5e 20 3c 2f 64 64 3e 0a 2a 2a  ions.)^ </dd>.**
14b70 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
14b80 46 49 47 5f 50 43 41 43 48 45 32 5d 5d 20 3c 64  FIG_PCACHE2]] <d
14b90 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
14ba0 50 43 41 43 48 45 32 3c 2f 64 74 3e 0a 2a 2a 20  PCACHE2</dt>.** 
14bb0 3c 64 64 3e 20 5e 28 54 68 65 20 53 51 4c 49 54  <dd> ^(The SQLIT
14bc0 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32  E_CONFIG_PCACHE2
14bd0 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20   option takes a 
14be0 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20  single argument 
14bf0 77 68 69 63 68 20 69 73 20 0a 2a 2a 20 61 20 70  which is .** a p
14c00 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 5b 73 71  ointer to an [sq
14c10 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74  lite3_pcache_met
14c20 68 6f 64 73 32 5d 20 6f 62 6a 65 63 74 2e 20 20  hods2] object.  
14c30 54 68 69 73 20 6f 62 6a 65 63 74 20 73 70 65 63  This object spec
14c40 69 66 69 65 73 0a 2a 2a 20 74 68 65 20 69 6e 74  ifies.** the int
14c50 65 72 66 61 63 65 20 74 6f 20 61 20 63 75 73 74  erface to a cust
14c60 6f 6d 20 70 61 67 65 20 63 61 63 68 65 20 69 6d  om page cache im
14c70 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 29 5e 0a  plementation.)^.
14c80 2a 2a 20 5e 53 51 4c 69 74 65 20 6d 61 6b 65 73  ** ^SQLite makes
14c90 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 5b   a copy of the [
14ca0 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d  sqlite3_pcache_m
14cb0 65 74 68 6f 64 73 32 5d 20 6f 62 6a 65 63 74 2e  ethods2] object.
14cc0 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
14cd0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50  LITE_CONFIG_GETP
14ce0 43 41 43 48 45 32 5d 5d 20 3c 64 74 3e 53 51 4c  CACHE2]] <dt>SQL
14cf0 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43  ITE_CONFIG_GETPC
14d00 41 43 48 45 32 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ACHE2</dt>.** <d
14d10 64 3e 20 5e 28 54 68 65 20 53 51 4c 49 54 45 5f  d> ^(The SQLITE_
14d20 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45  CONFIG_GETPCACHE
14d30 32 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61  2 option takes a
14d40 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74   single argument
14d50 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 61 20 70   which.** is a p
14d60 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 5b 73 71  ointer to an [sq
14d70 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74  lite3_pcache_met
14d80 68 6f 64 73 32 5d 20 6f 62 6a 65 63 74 2e 20 20  hods2] object.  
14d90 53 51 4c 69 74 65 20 63 6f 70 69 65 73 20 6f 66  SQLite copies of
14da0 0a 2a 2a 20 74 68 65 20 63 75 72 72 65 6e 74 20  .** the current 
14db0 70 61 67 65 20 63 61 63 68 65 20 69 6d 70 6c 65  page cache imple
14dc0 6d 65 6e 74 61 74 69 6f 6e 20 69 6e 74 6f 20 74  mentation into t
14dd0 68 61 74 20 6f 62 6a 65 63 74 2e 29 5e 20 3c 2f  hat object.)^ </
14de0 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
14df0 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 5d 5d 20  TE_CONFIG_LOG]] 
14e00 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
14e10 47 5f 4c 4f 47 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  G_LOG</dt>.** <d
14e20 64 3e 20 54 68 65 20 53 51 4c 49 54 45 5f 43 4f  d> The SQLITE_CO
14e30 4e 46 49 47 5f 4c 4f 47 20 6f 70 74 69 6f 6e 20  NFIG_LOG option 
14e40 69 73 20 75 73 65 64 20 74 6f 20 63 6f 6e 66 69  is used to confi
14e50 67 75 72 65 20 74 68 65 20 53 51 4c 69 74 65 0a  gure the SQLite.
14e60 2a 2a 20 67 6c 6f 62 61 6c 20 5b 65 72 72 6f 72  ** global [error
14e70 20 6c 6f 67 5d 2e 0a 2a 2a 20 28 5e 54 68 65 20   log]..** (^The 
14e80 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f  SQLITE_CONFIG_LO
14e90 47 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 74  G option takes t
14ea0 77 6f 20 61 72 67 75 6d 65 6e 74 73 3a 20 61 20  wo arguments: a 
14eb0 70 6f 69 6e 74 65 72 20 74 6f 20 61 0a 2a 2a 20  pointer to a.** 
14ec0 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 61 20  function with a 
14ed0 63 61 6c 6c 20 73 69 67 6e 61 74 75 72 65 20 6f  call signature o
14ee0 66 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c  f void(*)(void*,
14ef0 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29  int,const char*)
14f00 2c 20 0a 2a 2a 20 61 6e 64 20 61 20 70 6f 69 6e  , .** and a poin
14f10 74 65 72 20 74 6f 20 76 6f 69 64 2e 20 5e 49 66  ter to void. ^If
14f20 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 70 6f   the function po
14f30 69 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e 55 4c  inter is not NUL
14f40 4c 2c 20 69 74 20 69 73 0a 2a 2a 20 69 6e 76 6f  L, it is.** invo
14f50 6b 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  ked by [sqlite3_
14f60 6c 6f 67 28 29 5d 20 74 6f 20 70 72 6f 63 65 73  log()] to proces
14f70 73 20 65 61 63 68 20 6c 6f 67 67 69 6e 67 20 65  s each logging e
14f80 76 65 6e 74 2e 20 20 5e 49 66 20 74 68 65 0a 2a  vent.  ^If the.*
14f90 2a 20 66 75 6e 63 74 69 6f 6e 20 70 6f 69 6e 74  * function point
14fa0 65 72 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 20  er is NULL, the 
14fb0 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20  [sqlite3_log()] 
14fc0 69 6e 74 65 72 66 61 63 65 20 62 65 63 6f 6d 65  interface become
14fd0 73 20 61 20 6e 6f 2d 6f 70 2e 0a 2a 2a 20 5e 54  s a no-op..** ^T
14fe0 68 65 20 76 6f 69 64 20 70 6f 69 6e 74 65 72 20  he void pointer 
14ff0 74 68 61 74 20 69 73 20 74 68 65 20 73 65 63 6f  that is the seco
15000 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 53  nd argument to S
15010 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47  QLITE_CONFIG_LOG
15020 20 69 73 0a 2a 2a 20 70 61 73 73 65 64 20 74 68   is.** passed th
15030 72 6f 75 67 68 20 61 73 20 74 68 65 20 66 69 72  rough as the fir
15040 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  st parameter to 
15050 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
15060 64 65 66 69 6e 65 64 20 6c 6f 67 67 65 72 0a 2a  defined logger.*
15070 2a 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 6e 65  * function whene
15080 76 65 72 20 74 68 61 74 20 66 75 6e 63 74 69 6f  ver that functio
15090 6e 20 69 73 20 69 6e 76 6f 6b 65 64 2e 20 20 5e  n is invoked.  ^
150a0 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  The second param
150b0 65 74 65 72 20 74 6f 0a 2a 2a 20 74 68 65 20 6c  eter to.** the l
150c0 6f 67 67 65 72 20 66 75 6e 63 74 69 6f 6e 20 69  ogger function i
150d0 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20  s a copy of the 
150e0 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
150f0 74 6f 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e  to the correspon
15100 64 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ding.** [sqlite3
15110 5f 6c 6f 67 28 29 5d 20 63 61 6c 6c 20 61 6e 64  _log()] call and
15120 20 69 73 20 69 6e 74 65 6e 64 65 64 20 74 6f 20   is intended to 
15130 62 65 20 61 20 5b 72 65 73 75 6c 74 20 63 6f 64  be a [result cod
15140 65 5d 20 6f 72 20 61 6e 0a 2a 2a 20 5b 65 78 74  e] or an.** [ext
15150 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
15160 65 5d 2e 20 20 5e 54 68 65 20 74 68 69 72 64 20  e].  ^The third 
15170 70 61 72 61 6d 65 74 65 72 20 70 61 73 73 65 64  parameter passed
15180 20 74 6f 20 74 68 65 20 6c 6f 67 67 65 72 20 69   to the logger i
15190 73 0a 2a 2a 20 6c 6f 67 20 6d 65 73 73 61 67 65  s.** log message
151a0 20 61 66 74 65 72 20 66 6f 72 6d 61 74 74 69 6e   after formattin
151b0 67 20 76 69 61 20 5b 73 71 6c 69 74 65 33 5f 73  g via [sqlite3_s
151c0 6e 70 72 69 6e 74 66 28 29 5d 2e 0a 2a 2a 20 54  nprintf()]..** T
151d0 68 65 20 53 51 4c 69 74 65 20 6c 6f 67 67 69 6e  he SQLite loggin
151e0 67 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 6e  g interface is n
151f0 6f 74 20 72 65 65 6e 74 72 61 6e 74 3b 20 74 68  ot reentrant; th
15200 65 20 6c 6f 67 67 65 72 20 66 75 6e 63 74 69 6f  e logger functio
15210 6e 0a 2a 2a 20 73 75 70 70 6c 69 65 64 20 62 79  n.** supplied by
15220 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
15230 20 6d 75 73 74 20 6e 6f 74 20 69 6e 76 6f 6b 65   must not invoke
15240 20 61 6e 79 20 53 51 4c 69 74 65 20 69 6e 74 65   any SQLite inte
15250 72 66 61 63 65 2e 0a 2a 2a 20 49 6e 20 61 20 6d  rface..** In a m
15260 75 6c 74 69 2d 74 68 72 65 61 64 65 64 20 61 70  ulti-threaded ap
15270 70 6c 69 63 61 74 69 6f 6e 2c 20 74 68 65 20 61  plication, the a
15280 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
15290 65 64 20 6c 6f 67 67 65 72 0a 2a 2a 20 66 75 6e  ed logger.** fun
152a0 63 74 69 6f 6e 20 6d 75 73 74 20 62 65 20 74 68  ction must be th
152b0 72 65 61 64 73 61 66 65 2e 20 3c 2f 64 64 3e 0a  readsafe. </dd>.
152c0 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
152d0 4f 4e 46 49 47 5f 55 52 49 5d 5d 20 3c 64 74 3e  ONFIG_URI]] <dt>
152e0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52  SQLITE_CONFIG_UR
152f0 49 0a 2a 2a 20 3c 64 64 3e 5e 28 54 68 65 20 53  I.** <dd>^(The S
15300 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49  QLITE_CONFIG_URI
15310 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20   option takes a 
15320 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20  single argument 
15330 6f 66 20 74 79 70 65 20 69 6e 74 2e 0a 2a 2a 20  of type int..** 
15340 49 66 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65  If non-zero, the
15350 6e 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 20 69  n URI handling i
15360 73 20 67 6c 6f 62 61 6c 6c 79 20 65 6e 61 62 6c  s globally enabl
15370 65 64 2e 20 49 66 20 74 68 65 20 70 61 72 61 6d  ed. If the param
15380 65 74 65 72 20 69 73 20 7a 65 72 6f 2c 0a 2a 2a  eter is zero,.**
15390 20 74 68 65 6e 20 55 52 49 20 68 61 6e 64 6c 69   then URI handli
153a0 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20 64  ng is globally d
153b0 69 73 61 62 6c 65 64 2e 29 5e 20 5e 49 66 20 55  isabled.)^ ^If U
153c0 52 49 20 68 61 6e 64 6c 69 6e 67 20 69 73 20 67  RI handling is g
153d0 6c 6f 62 61 6c 6c 79 0a 2a 2a 20 65 6e 61 62 6c  lobally.** enabl
153e0 65 64 2c 20 61 6c 6c 20 66 69 6c 65 6e 61 6d 65  ed, all filename
153f0 73 20 70 61 73 73 65 64 20 74 6f 20 5b 73 71 6c  s passed to [sql
15400 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73  ite3_open()], [s
15410 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
15420 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f  ],.** [sqlite3_o
15430 70 65 6e 31 36 28 29 5d 20 6f 72 0a 2a 2a 20 73  pen16()] or.** s
15440 70 65 63 69 66 69 65 64 20 61 73 20 70 61 72 74  pecified as part
15450 20 6f 66 20 5b 41 54 54 41 43 48 5d 20 63 6f 6d   of [ATTACH] com
15460 6d 61 6e 64 73 20 61 72 65 20 69 6e 74 65 72 70  mands are interp
15470 72 65 74 65 64 20 61 73 20 55 52 49 73 2c 20 72  reted as URIs, r
15480 65 67 61 72 64 6c 65 73 73 0a 2a 2a 20 6f 66 20  egardless.** of 
15490 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74  whether or not t
154a0 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  he [SQLITE_OPEN_
154b0 55 52 49 5d 20 66 6c 61 67 20 69 73 20 73 65 74  URI] flag is set
154c0 20 77 68 65 6e 20 74 68 65 20 64 61 74 61 62 61   when the databa
154d0 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e  se.** connection
154e0 20 69 73 20 6f 70 65 6e 65 64 2e 20 5e 49 66 20   is opened. ^If 
154f0 69 74 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20 64  it is globally d
15500 69 73 61 62 6c 65 64 2c 20 66 69 6c 65 6e 61 6d  isabled, filenam
15510 65 73 20 61 72 65 0a 2a 2a 20 6f 6e 6c 79 20 69  es are.** only i
15520 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 55 52  nterpreted as UR
15530 49 73 20 69 66 20 74 68 65 20 53 51 4c 49 54 45  Is if the SQLITE
15540 5f 4f 50 45 4e 5f 55 52 49 20 66 6c 61 67 20 69  _OPEN_URI flag i
15550 73 20 73 65 74 20 77 68 65 6e 20 74 68 65 0a 2a  s set when the.*
15560 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  * database conne
15570 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e 65 64 2e  ction is opened.
15580 20 5e 28 42 79 20 64 65 66 61 75 6c 74 2c 20 55   ^(By default, U
15590 52 49 20 68 61 6e 64 6c 69 6e 67 20 69 73 20 67  RI handling is g
155a0 6c 6f 62 61 6c 6c 79 0a 2a 2a 20 64 69 73 61 62  lobally.** disab
155b0 6c 65 64 2e 20 54 68 65 20 64 65 66 61 75 6c 74  led. The default
155c0 20 76 61 6c 75 65 20 6d 61 79 20 62 65 20 63 68   value may be ch
155d0 61 6e 67 65 64 20 62 79 20 63 6f 6d 70 69 6c 69  anged by compili
155e0 6e 67 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b  ng with the.** [
155f0 53 51 4c 49 54 45 5f 55 53 45 5f 55 52 49 5d 20  SQLITE_USE_URI] 
15600 73 79 6d 62 6f 6c 20 64 65 66 69 6e 65 64 2e 29  symbol defined.)
15610 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  ^.**.** [[SQLITE
15620 5f 43 4f 4e 46 49 47 5f 43 4f 56 45 52 49 4e 47  _CONFIG_COVERING
15630 5f 49 4e 44 45 58 5f 53 43 41 4e 5d 5d 20 3c 64  _INDEX_SCAN]] <d
15640 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
15650 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53  COVERING_INDEX_S
15660 43 41 4e 0a 2a 2a 20 3c 64 64 3e 5e 54 68 65 20  CAN.** <dd>^The 
15670 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f  SQLITE_CONFIG_CO
15680 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41  VERING_INDEX_SCA
15690 4e 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61  N option takes a
156a0 20 73 69 6e 67 6c 65 20 69 6e 74 65 67 65 72 0a   single integer.
156b0 2a 2a 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63  ** argument whic
156c0 68 20 69 73 20 69 6e 74 65 72 70 72 65 74 65 64  h is interpreted
156d0 20 61 73 20 61 20 62 6f 6f 6c 65 61 6e 20 69 6e   as a boolean in
156e0 20 6f 72 64 65 72 20 74 6f 20 65 6e 61 62 6c 65   order to enable
156f0 20 6f 72 20 64 69 73 61 62 6c 65 0a 2a 2a 20 74   or disable.** t
15700 68 65 20 75 73 65 20 6f 66 20 63 6f 76 65 72 69  he use of coveri
15710 6e 67 20 69 6e 64 69 63 65 73 20 66 6f 72 20 66  ng indices for f
15720 75 6c 6c 20 74 61 62 6c 65 20 73 63 61 6e 73 20  ull table scans 
15730 69 6e 20 74 68 65 20 71 75 65 72 79 20 6f 70 74  in the query opt
15740 69 6d 69 7a 65 72 2e 0a 2a 2a 20 5e 54 68 65 20  imizer..** ^The 
15750 64 65 66 61 75 6c 74 20 73 65 74 74 69 6e 67 20  default setting 
15760 69 73 20 64 65 74 65 72 6d 69 6e 65 64 0a 2a 2a  is determined.**
15770 20 62 79 20 74 68 65 20 5b 53 51 4c 49 54 45 5f   by the [SQLITE_
15780 41 4c 4c 4f 57 5f 43 4f 56 45 52 49 4e 47 5f 49  ALLOW_COVERING_I
15790 4e 44 45 58 5f 53 43 41 4e 5d 20 63 6f 6d 70 69  NDEX_SCAN] compi
157a0 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2c 20  le-time option, 
157b0 6f 72 20 69 73 20 22 6f 6e 22 0a 2a 2a 20 69 66  or is "on".** if
157c0 20 74 68 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69   that compile-ti
157d0 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20 6f 6d 69  me option is omi
157e0 74 74 65 64 2e 0a 2a 2a 20 54 68 65 20 61 62 69  tted..** The abi
157f0 6c 69 74 79 20 74 6f 20 64 69 73 61 62 6c 65 20  lity to disable 
15800 74 68 65 20 75 73 65 20 6f 66 20 63 6f 76 65 72  the use of cover
15810 69 6e 67 20 69 6e 64 69 63 65 73 20 66 6f 72 20  ing indices for 
15820 66 75 6c 6c 20 74 61 62 6c 65 20 73 63 61 6e 73  full table scans
15830 0a 2a 2a 20 69 73 20 62 65 63 61 75 73 65 20 73  .** is because s
15840 6f 6d 65 20 69 6e 63 6f 72 72 65 63 74 6c 79 20  ome incorrectly 
15850 63 6f 64 65 64 20 6c 65 67 61 63 79 20 61 70 70  coded legacy app
15860 6c 69 63 61 74 69 6f 6e 73 20 6d 69 67 68 74 20  lications might 
15870 6d 61 6c 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 77  malfunction.** w
15880 68 65 6e 20 74 68 65 20 6f 70 74 69 6d 69 7a 61  hen the optimiza
15890 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 2e  tion is enabled.
158a0 20 20 50 72 6f 76 69 64 69 6e 67 20 74 68 65 20    Providing the 
158b0 61 62 69 6c 69 74 79 20 74 6f 0a 2a 2a 20 64 69  ability to.** di
158c0 73 61 62 6c 65 20 74 68 65 20 6f 70 74 69 6d 69  sable the optimi
158d0 7a 61 74 69 6f 6e 20 61 6c 6c 6f 77 73 20 74 68  zation allows th
158e0 65 20 6f 6c 64 65 72 2c 20 62 75 67 67 79 20 61  e older, buggy a
158f0 70 70 6c 69 63 61 74 69 6f 6e 20 63 6f 64 65 20  pplication code 
15900 74 6f 20 77 6f 72 6b 0a 2a 2a 20 77 69 74 68 6f  to work.** witho
15910 75 74 20 63 68 61 6e 67 65 20 65 76 65 6e 20 77  ut change even w
15920 69 74 68 20 6e 65 77 65 72 20 76 65 72 73 69 6f  ith newer versio
15930 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a  ns of SQLite..**
15940 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
15950 46 49 47 5f 50 43 41 43 48 45 5d 5d 20 5b 5b 53  FIG_PCACHE]] [[S
15960 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
15970 50 43 41 43 48 45 5d 5d 0a 2a 2a 20 3c 64 74 3e  PCACHE]].** <dt>
15980 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43  SQLITE_CONFIG_PC
15990 41 43 48 45 20 61 6e 64 20 53 51 4c 49 54 45 5f  ACHE and SQLITE_
159a0 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45  CONFIG_GETPCACHE
159b0 0a 2a 2a 20 3c 64 64 3e 20 54 68 65 73 65 20 6f  .** <dd> These o
159c0 70 74 69 6f 6e 73 20 61 72 65 20 6f 62 73 6f 6c  ptions are obsol
159d0 65 74 65 20 61 6e 64 20 73 68 6f 75 6c 64 20 6e  ete and should n
159e0 6f 74 20 62 65 20 75 73 65 64 20 62 79 20 6e 65  ot be used by ne
159f0 77 20 63 6f 64 65 2e 0a 2a 2a 20 54 68 65 79 20  w code..** They 
15a00 61 72 65 20 72 65 74 61 69 6e 65 64 20 66 6f 72  are retained for
15a10 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61   backwards compa
15a20 74 69 62 69 6c 69 74 79 20 62 75 74 20 61 72 65  tibility but are
15a30 20 6e 6f 77 20 6e 6f 2d 6f 70 73 2e 0a 2a 2a 20   now no-ops..** 
15a40 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
15a50 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 51 4c 4c  LITE_CONFIG_SQLL
15a60 4f 47 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  OG]].** <dt>SQLI
15a70 54 45 5f 43 4f 4e 46 49 47 5f 53 51 4c 4c 4f 47  TE_CONFIG_SQLLOG
15a80 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 6f 70 74  .** <dd>This opt
15a90 69 6f 6e 20 69 73 20 6f 6e 6c 79 20 61 76 61 69  ion is only avai
15aa0 6c 61 62 6c 65 20 69 66 20 73 71 6c 69 74 65 20  lable if sqlite 
15ab0 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  is compiled with
15ac0 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f   the.** [SQLITE_
15ad0 45 4e 41 42 4c 45 5f 53 51 4c 4c 4f 47 5d 20 70  ENABLE_SQLLOG] p
15ae0 72 65 2d 70 72 6f 63 65 73 73 6f 72 20 6d 61 63  re-processor mac
15af0 72 6f 20 64 65 66 69 6e 65 64 2e 20 54 68 65 20  ro defined. The 
15b00 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 73  first argument s
15b10 68 6f 75 6c 64 0a 2a 2a 20 62 65 20 61 20 70 6f  hould.** be a po
15b20 69 6e 74 65 72 20 74 6f 20 61 20 66 75 6e 63 74  inter to a funct
15b30 69 6f 6e 20 6f 66 20 74 79 70 65 20 76 6f 69 64  ion of type void
15b40 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65  (*)(void*,sqlite
15b50 33 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20  3*,const char*, 
15b60 69 6e 74 29 2e 0a 2a 2a 20 54 68 65 20 73 65 63  int)..** The sec
15b70 6f 6e 64 20 73 68 6f 75 6c 64 20 62 65 20 6f 66  ond should be of
15b80 20 74 79 70 65 20 28 76 6f 69 64 2a 29 2e 20 54   type (void*). T
15b90 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69  he callback is i
15ba0 6e 76 6f 6b 65 64 20 62 79 20 74 68 65 20 6c 69  nvoked by the li
15bb0 62 72 61 72 79 0a 2a 2a 20 69 6e 20 74 68 72 65  brary.** in thre
15bc0 65 20 73 65 70 61 72 61 74 65 20 63 69 72 63 75  e separate circu
15bd0 6d 73 74 61 6e 63 65 73 2c 20 69 64 65 6e 74 69  mstances, identi
15be0 66 69 65 64 20 62 79 20 74 68 65 20 76 61 6c 75  fied by the valu
15bf0 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65 0a  e passed as the.
15c00 2a 2a 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  ** fourth parame
15c10 74 65 72 2e 20 49 66 20 74 68 65 20 66 6f 75 72  ter. If the four
15c20 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  th parameter is 
15c30 30 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74 61  0, then the data
15c40 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a  base connection.
15c50 2a 2a 20 70 61 73 73 65 64 20 61 73 20 74 68 65  ** passed as the
15c60 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
15c70 20 68 61 73 20 6a 75 73 74 20 62 65 65 6e 20 6f   has just been o
15c80 70 65 6e 65 64 2e 20 54 68 65 20 74 68 69 72 64  pened. The third
15c90 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 70 6f 69   argument.** poi
15ca0 6e 74 73 20 74 6f 20 61 20 62 75 66 66 65 72 20  nts to a buffer 
15cb0 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 6e  containing the n
15cc0 61 6d 65 20 6f 66 20 74 68 65 20 6d 61 69 6e 20  ame of the main 
15cd0 64 61 74 61 62 61 73 65 20 66 69 6c 65 2e 20 49  database file. I
15ce0 66 20 74 68 65 0a 2a 2a 20 66 6f 75 72 74 68 20  f the.** fourth 
15cf0 70 61 72 61 6d 65 74 65 72 20 69 73 20 31 2c 20  parameter is 1, 
15d00 74 68 65 6e 20 74 68 65 20 53 51 4c 20 73 74 61  then the SQL sta
15d10 74 65 6d 65 6e 74 20 74 68 61 74 20 74 68 65 20  tement that the 
15d20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 0a  third parameter.
15d30 2a 2a 20 70 6f 69 6e 74 73 20 74 6f 20 68 61 73  ** points to has
15d40 20 6a 75 73 74 20 62 65 65 6e 20 65 78 65 63 75   just been execu
15d50 74 65 64 2e 20 4f 72 2c 20 69 66 20 74 68 65 20  ted. Or, if the 
15d60 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
15d70 20 69 73 20 32 2c 20 74 68 65 6e 0a 2a 2a 20 74   is 2, then.** t
15d80 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 65  he connection be
15d90 69 6e 67 20 70 61 73 73 65 64 20 61 73 20 74 68  ing passed as th
15da0 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
15db0 65 72 20 69 73 20 62 65 69 6e 67 20 63 6c 6f 73  er is being clos
15dc0 65 64 2e 20 54 68 65 0a 2a 2a 20 74 68 69 72 64  ed. The.** third
15dd0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 70 61   parameter is pa
15de0 73 73 65 64 20 4e 55 4c 4c 20 49 6e 20 74 68 69  ssed NULL In thi
15df0 73 20 63 61 73 65 2e 20 20 41 6e 20 65 78 61 6d  s case.  An exam
15e00 70 6c 65 20 6f 66 20 75 73 69 6e 67 20 74 68 69  ple of using thi
15e10 73 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69  s.** configurati
15e20 6f 6e 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65  on option can be
15e30 20 73 65 65 6e 20 69 6e 20 74 68 65 20 22 74 65   seen in the "te
15e40 73 74 5f 73 71 6c 6c 6f 67 2e 63 22 20 73 6f 75  st_sqllog.c" sou
15e50 72 63 65 20 66 69 6c 65 20 69 6e 0a 2a 2a 20 74  rce file in.** t
15e60 68 65 20 63 61 6e 6f 6e 69 63 61 6c 20 53 51 4c  he canonical SQL
15e70 69 74 65 20 73 6f 75 72 63 65 20 74 72 65 65 2e  ite source tree.
15e80 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
15e90 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41 50  LITE_CONFIG_MMAP
15ea0 5f 53 49 5a 45 5d 5d 0a 2a 2a 20 3c 64 74 3e 53  _SIZE]].** <dt>S
15eb0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41  QLITE_CONFIG_MMA
15ec0 50 5f 53 49 5a 45 0a 2a 2a 20 3c 64 64 3e 5e 53  P_SIZE.** <dd>^S
15ed0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41  QLITE_CONFIG_MMA
15ee0 50 5f 53 49 5a 45 20 74 61 6b 65 73 20 74 77 6f  P_SIZE takes two
15ef0 20 36 34 2d 62 69 74 20 69 6e 74 65 67 65 72 20   64-bit integer 
15f00 28 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 20  (sqlite3_int64) 
15f10 76 61 6c 75 65 73 0a 2a 2a 20 74 68 61 74 20 61  values.** that a
15f20 72 65 20 74 68 65 20 64 65 66 61 75 6c 74 20 6d  re the default m
15f30 6d 61 70 20 73 69 7a 65 20 6c 69 6d 69 74 20 28  map size limit (
15f40 74 68 65 20 64 65 66 61 75 6c 74 20 73 65 74 74  the default sett
15f50 69 6e 67 20 66 6f 72 0a 2a 2a 20 5b 50 52 41 47  ing for.** [PRAG
15f60 4d 41 20 6d 6d 61 70 5f 73 69 7a 65 5d 29 20 61  MA mmap_size]) a
15f70 6e 64 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 61  nd the maximum a
15f80 6c 6c 6f 77 65 64 20 6d 6d 61 70 20 73 69 7a 65  llowed mmap size
15f90 20 6c 69 6d 69 74 2e 0a 2a 2a 20 5e 54 68 65 20   limit..** ^The 
15fa0 64 65 66 61 75 6c 74 20 73 65 74 74 69 6e 67 20  default setting 
15fb0 63 61 6e 20 62 65 20 6f 76 65 72 72 69 64 64 65  can be overridde
15fc0 6e 20 62 79 20 65 61 63 68 20 64 61 74 61 62 61  n by each databa
15fd0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 75 73  se connection us
15fe0 69 6e 67 0a 2a 2a 20 65 69 74 68 65 72 20 74 68  ing.** either th
15ff0 65 20 5b 50 52 41 47 4d 41 20 6d 6d 61 70 5f 73  e [PRAGMA mmap_s
16000 69 7a 65 5d 20 63 6f 6d 6d 61 6e 64 2c 20 6f 72  ize] command, or
16010 20 62 79 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a   by using the.**
16020 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4d   [SQLITE_FCNTL_M
16030 4d 41 50 5f 53 49 5a 45 5d 20 66 69 6c 65 20 63  MAP_SIZE] file c
16040 6f 6e 74 72 6f 6c 2e 20 20 5e 28 54 68 65 20 6d  ontrol.  ^(The m
16050 61 78 69 6d 75 6d 20 61 6c 6c 6f 77 65 64 20 6d  aximum allowed m
16060 6d 61 70 20 73 69 7a 65 0a 2a 2a 20 77 69 6c 6c  map size.** will
16070 20 62 65 20 73 69 6c 65 6e 74 6c 79 20 74 72 75   be silently tru
16080 6e 63 61 74 65 64 20 69 66 20 6e 65 63 65 73 73  ncated if necess
16090 61 72 79 20 73 6f 20 74 68 61 74 20 69 74 20 64  ary so that it d
160a0 6f 65 73 20 6e 6f 74 20 65 78 63 65 65 64 20 74  oes not exceed t
160b0 68 65 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74 69  he.** compile-ti
160c0 6d 65 20 6d 61 78 69 6d 75 6d 20 6d 6d 61 70 20  me maximum mmap 
160d0 73 69 7a 65 20 73 65 74 20 62 79 20 74 68 65 0a  size set by the.
160e0 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 41 58 5f 4d  ** [SQLITE_MAX_M
160f0 4d 41 50 5f 53 49 5a 45 5d 20 63 6f 6d 70 69 6c  MAP_SIZE] compil
16100 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2e 29 5e  e-time option.)^
16110 0a 2a 2a 20 5e 49 66 20 65 69 74 68 65 72 20 61  .** ^If either a
16120 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 69 73 20  rgument to this 
16130 6f 70 74 69 6f 6e 20 69 73 20 6e 65 67 61 74 69  option is negati
16140 76 65 2c 20 74 68 65 6e 20 74 68 61 74 20 61 72  ve, then that ar
16150 67 75 6d 65 6e 74 20 69 73 0a 2a 2a 20 63 68 61  gument is.** cha
16160 6e 67 65 64 20 74 6f 20 69 74 73 20 63 6f 6d 70  nged to its comp
16170 69 6c 65 2d 74 69 6d 65 20 64 65 66 61 75 6c 74  ile-time default
16180 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  ..**.** [[SQLITE
16190 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f 48 45  _CONFIG_WIN32_HE
161a0 41 50 53 49 5a 45 5d 5d 0a 2a 2a 20 3c 64 74 3e  APSIZE]].** <dt>
161b0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 57 49  SQLITE_CONFIG_WI
161c0 4e 33 32 5f 48 45 41 50 53 49 5a 45 0a 2a 2a 20  N32_HEAPSIZE.** 
161d0 3c 64 64 3e 5e 54 68 65 20 53 51 4c 49 54 45 5f  <dd>^The SQLITE_
161e0 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f 48 45 41  CONFIG_WIN32_HEA
161f0 50 53 49 5a 45 20 6f 70 74 69 6f 6e 20 69 73 20  PSIZE option is 
16200 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 69  only available i
16210 66 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20 63  f SQLite is.** c
16220 6f 6d 70 69 6c 65 64 20 66 6f 72 20 57 69 6e 64  ompiled for Wind
16230 6f 77 73 20 77 69 74 68 20 74 68 65 20 5b 53 51  ows with the [SQ
16240 4c 49 54 45 5f 57 49 4e 33 32 5f 4d 41 4c 4c 4f  LITE_WIN32_MALLO
16250 43 5d 20 70 72 65 2d 70 72 6f 63 65 73 73 6f 72  C] pre-processor
16260 20 6d 61 63 72 6f 0a 2a 2a 20 64 65 66 69 6e 65   macro.** define
16270 64 2e 20 5e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  d. ^SQLITE_CONFI
16280 47 5f 57 49 4e 33 32 5f 48 45 41 50 53 49 5a 45  G_WIN32_HEAPSIZE
16290 20 74 61 6b 65 73 20 61 20 33 32 2d 62 69 74 20   takes a 32-bit 
162a0 75 6e 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72  unsigned integer
162b0 20 76 61 6c 75 65 0a 2a 2a 20 74 68 61 74 20 73   value.** that s
162c0 70 65 63 69 66 69 65 73 20 74 68 65 20 6d 61 78  pecifies the max
162d0 69 6d 75 6d 20 73 69 7a 65 20 6f 66 20 74 68 65  imum size of the
162e0 20 63 72 65 61 74 65 64 20 68 65 61 70 2e 0a 2a   created heap..*
162f0 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
16300 4e 46 49 47 5f 50 43 41 43 48 45 5f 48 44 52 53  NFIG_PCACHE_HDRS
16310 5a 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  Z]].** <dt>SQLIT
16320 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 5f  E_CONFIG_PCACHE_
16330 48 44 52 53 5a 0a 2a 2a 20 3c 64 64 3e 5e 54 68  HDRSZ.** <dd>^Th
16340 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
16350 50 43 41 43 48 45 5f 48 44 52 53 5a 20 6f 70 74  PCACHE_HDRSZ opt
16360 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67  ion takes a sing
16370 6c 65 20 70 61 72 61 6d 65 74 65 72 20 77 68 69  le parameter whi
16380 63 68 0a 2a 2a 20 69 73 20 61 20 70 6f 69 6e 74  ch.** is a point
16390 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72  er to an integer
163a0 20 61 6e 64 20 77 72 69 74 65 73 20 69 6e 74 6f   and writes into
163b0 20 74 68 61 74 20 69 6e 74 65 67 65 72 20 74 68   that integer th
163c0 65 20 6e 75 6d 62 65 72 20 6f 66 20 65 78 74 72  e number of extr
163d0 61 0a 2a 2a 20 62 79 74 65 73 20 70 65 72 20 70  a.** bytes per p
163e0 61 67 65 20 72 65 71 75 69 72 65 64 20 66 6f 72  age required for
163f0 20 65 61 63 68 20 70 61 67 65 20 69 6e 20 5b 53   each page in [S
16400 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47  QLITE_CONFIG_PAG
16410 45 43 41 43 48 45 5d 2e 0a 2a 2a 20 54 68 65 20  ECACHE]..** The 
16420 61 6d 6f 75 6e 74 20 6f 66 20 65 78 74 72 61 20  amount of extra 
16430 73 70 61 63 65 20 72 65 71 75 69 72 65 64 20 63  space required c
16440 61 6e 20 63 68 61 6e 67 65 20 64 65 70 65 6e 64  an change depend
16450 69 6e 67 20 6f 6e 20 74 68 65 20 63 6f 6d 70 69  ing on the compi
16460 6c 65 72 2c 0a 2a 2a 20 74 61 72 67 65 74 20 70  ler,.** target p
16470 6c 61 74 66 6f 72 6d 2c 20 61 6e 64 20 53 51 4c  latform, and SQL
16480 69 74 65 20 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a  ite version..**.
16490 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
164a0 49 47 5f 50 4d 41 53 5a 5d 5d 0a 2a 2a 20 3c 64  IG_PMASZ]].** <d
164b0 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
164c0 50 4d 41 53 5a 0a 2a 2a 20 3c 64 64 3e 5e 54 68  PMASZ.** <dd>^Th
164d0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
164e0 50 4d 41 53 5a 20 6f 70 74 69 6f 6e 20 74 61 6b  PMASZ option tak
164f0 65 73 20 61 20 73 69 6e 67 6c 65 20 70 61 72 61  es a single para
16500 6d 65 74 65 72 20 77 68 69 63 68 0a 2a 2a 20 69  meter which.** i
16510 73 20 61 6e 20 75 6e 73 69 67 6e 65 64 20 69 6e  s an unsigned in
16520 74 65 67 65 72 20 61 6e 64 20 73 65 74 73 20 74  teger and sets t
16530 68 65 20 22 4d 69 6e 69 6d 75 6d 20 50 4d 41 20  he "Minimum PMA 
16540 53 69 7a 65 22 20 66 6f 72 20 74 68 65 20 6d 75  Size" for the mu
16550 6c 74 69 74 68 72 65 61 64 65 64 0a 2a 2a 20 73  ltithreaded.** s
16560 6f 72 74 65 72 20 74 6f 20 74 68 61 74 20 69 6e  orter to that in
16570 74 65 67 65 72 2e 20 20 54 68 65 20 64 65 66 61  teger.  The defa
16580 75 6c 74 20 6d 69 6e 69 6d 75 6d 20 50 4d 41 20  ult minimum PMA 
16590 53 69 7a 65 20 69 73 20 73 65 74 20 62 79 20 74  Size is set by t
165a0 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 53 4f  he.** [SQLITE_SO
165b0 52 54 45 52 5f 50 4d 41 53 5a 5d 20 63 6f 6d 70  RTER_PMASZ] comp
165c0 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2e  ile-time option.
165d0 20 20 4e 65 77 20 74 68 72 65 61 64 73 20 61 72    New threads ar
165e0 65 20 6c 61 75 6e 63 68 65 64 0a 2a 2a 20 74 6f  e launched.** to
165f0 20 68 65 6c 70 20 77 69 74 68 20 73 6f 72 74 20   help with sort 
16600 6f 70 65 72 61 74 69 6f 6e 73 20 77 68 65 6e 20  operations when 
16610 6d 75 6c 74 69 74 68 72 65 61 64 65 64 20 73 6f  multithreaded so
16620 72 74 69 6e 67 0a 2a 2a 20 69 73 20 65 6e 61 62  rting.** is enab
16630 6c 65 64 20 28 75 73 69 6e 67 20 74 68 65 20 5b  led (using the [
16640 50 52 41 47 4d 41 20 74 68 72 65 61 64 73 5d 20  PRAGMA threads] 
16650 63 6f 6d 6d 61 6e 64 29 20 61 6e 64 20 74 68 65  command) and the
16660 20 61 6d 6f 75 6e 74 20 6f 66 20 63 6f 6e 74 65   amount of conte
16670 6e 74 0a 2a 2a 20 74 6f 20 62 65 20 73 6f 72 74  nt.** to be sort
16680 65 64 20 65 78 63 65 65 64 73 20 74 68 65 20 70  ed exceeds the p
16690 61 67 65 20 73 69 7a 65 20 74 69 6d 65 73 20 74  age size times t
166a0 68 65 20 6d 69 6e 69 6d 75 6d 20 6f 66 20 74 68  he minimum of th
166b0 65 0a 2a 2a 20 5b 50 52 41 47 4d 41 20 63 61 63  e.** [PRAGMA cac
166c0 68 65 5f 73 69 7a 65 5d 20 73 65 74 74 69 6e 67  he_size] setting
166d0 20 61 6e 64 20 74 68 69 73 20 76 61 6c 75 65 2e   and this value.
166e0 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
166f0 43 4f 4e 46 49 47 5f 53 54 4d 54 4a 52 4e 4c 5f  CONFIG_STMTJRNL_
16700 53 50 49 4c 4c 5d 5d 0a 2a 2a 20 3c 64 74 3e 53  SPILL]].** <dt>S
16710 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 54 4d  QLITE_CONFIG_STM
16720 54 4a 52 4e 4c 5f 53 50 49 4c 4c 0a 2a 2a 20 3c  TJRNL_SPILL.** <
16730 64 64 3e 5e 54 68 65 20 53 51 4c 49 54 45 5f 43  dd>^The SQLITE_C
16740 4f 4e 46 49 47 5f 53 54 4d 54 4a 52 4e 4c 5f 53  ONFIG_STMTJRNL_S
16750 50 49 4c 4c 20 6f 70 74 69 6f 6e 20 74 61 6b 65  PILL option take
16760 73 20 61 20 73 69 6e 67 6c 65 20 70 61 72 61 6d  s a single param
16770 65 74 65 72 20 77 68 69 63 68 0a 2a 2a 20 62 65  eter which.** be
16780 63 6f 6d 65 73 20 74 68 65 20 5b 73 74 61 74 65  comes the [state
16790 6d 65 6e 74 20 6a 6f 75 72 6e 61 6c 5d 20 73 70  ment journal] sp
167a0 69 6c 6c 2d 74 6f 2d 64 69 73 6b 20 74 68 72 65  ill-to-disk thre
167b0 73 68 6f 6c 64 2e 20 20 0a 2a 2a 20 5b 53 74 61  shold.  .** [Sta
167c0 74 65 6d 65 6e 74 20 6a 6f 75 72 6e 61 6c 73 5d  tement journals]
167d0 20 61 72 65 20 68 65 6c 64 20 69 6e 20 6d 65 6d   are held in mem
167e0 6f 72 79 20 75 6e 74 69 6c 20 74 68 65 69 72 20  ory until their 
167f0 73 69 7a 65 20 28 69 6e 20 62 79 74 65 73 29 0a  size (in bytes).
16800 2a 2a 20 65 78 63 65 65 64 73 20 74 68 69 73 20  ** exceeds this 
16810 74 68 72 65 73 68 6f 6c 64 2c 20 61 74 20 77 68  threshold, at wh
16820 69 63 68 20 70 6f 69 6e 74 20 74 68 65 79 20 61  ich point they a
16830 72 65 20 77 72 69 74 74 65 6e 20 74 6f 20 64 69  re written to di
16840 73 6b 2e 0a 2a 2a 20 4f 72 20 69 66 20 74 68 65  sk..** Or if the
16850 20 74 68 72 65 73 68 6f 6c 64 20 69 73 20 2d 31   threshold is -1
16860 2c 20 73 74 61 74 65 6d 65 6e 74 20 6a 6f 75 72  , statement jour
16870 6e 61 6c 73 20 61 72 65 20 61 6c 77 61 79 73 20  nals are always 
16880 68 65 6c 64 0a 2a 2a 20 65 78 63 6c 75 73 69 76  held.** exclusiv
16890 65 6c 79 20 69 6e 20 6d 65 6d 6f 72 79 2e 0a 2a  ely in memory..*
168a0 2a 20 53 69 6e 63 65 20 6d 61 6e 79 20 73 74 61  * Since many sta
168b0 74 65 6d 65 6e 74 20 6a 6f 75 72 6e 61 6c 73 20  tement journals 
168c0 6e 65 76 65 72 20 62 65 63 6f 6d 65 20 6c 61 72  never become lar
168d0 67 65 2c 20 73 65 74 74 69 6e 67 20 74 68 65 20  ge, setting the 
168e0 73 70 69 6c 6c 0a 2a 2a 20 74 68 72 65 73 68 6f  spill.** thresho
168f0 6c 64 20 74 6f 20 61 20 76 61 6c 75 65 20 73 75  ld to a value su
16900 63 68 20 61 73 20 36 34 4b 69 42 20 63 61 6e 20  ch as 64KiB can 
16910 67 72 65 61 74 6c 79 20 72 65 64 75 63 65 20 74  greatly reduce t
16920 68 65 20 61 6d 6f 75 6e 74 20 6f 66 0a 2a 2a 20  he amount of.** 
16930 49 2f 4f 20 72 65 71 75 69 72 65 64 20 74 6f 20  I/O required to 
16940 73 75 70 70 6f 72 74 20 73 74 61 74 65 6d 65 6e  support statemen
16950 74 20 72 6f 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 54  t rollback..** T
16960 68 65 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65  he default value
16970 20 66 6f 72 20 74 68 69 73 20 73 65 74 74 69 6e   for this settin
16980 67 20 69 73 20 63 6f 6e 74 72 6f 6c 6c 65 64 20  g is controlled 
16990 62 79 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54  by the.** [SQLIT
169a0 45 5f 53 54 4d 54 4a 52 4e 4c 5f 53 50 49 4c 4c  E_STMTJRNL_SPILL
169b0 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
169c0 70 74 69 6f 6e 2e 0a 2a 2a 20 3c 2f 64 6c 3e 0a  ption..** </dl>.
169d0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
169e0 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54  E_CONFIG_SINGLET
169f0 48 52 45 41 44 20 20 31 20 20 2f 2a 20 6e 69 6c  HREAD  1  /* nil
16a00 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
16a10 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54  TE_CONFIG_MULTIT
16a20 48 52 45 41 44 20 20 20 32 20 20 2f 2a 20 6e 69  HREAD   2  /* ni
16a30 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  l */.#define SQL
16a40 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41  ITE_CONFIG_SERIA
16a50 4c 49 5a 45 44 20 20 20 20 33 20 20 2f 2a 20 6e  LIZED    3  /* n
16a60 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  il */.#define SQ
16a70 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c  LITE_CONFIG_MALL
16a80 4f 43 20 20 20 20 20 20 20 20 34 20 20 2f 2a 20  OC        4  /* 
16a90 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68  sqlite3_mem_meth
16aa0 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20  ods* */.#define 
16ab0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
16ac0 54 4d 41 4c 4c 4f 43 20 20 20 20 20 35 20 20 2f  TMALLOC     5  /
16ad0 2a 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65  * sqlite3_mem_me
16ae0 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e  thods* */.#defin
16af0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
16b00 53 43 52 41 54 43 48 20 20 20 20 20 20 20 36 20  SCRATCH       6 
16b10 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 73   /* void*, int s
16b20 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23 64 65 66  z, int N */.#def
16b30 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
16b40 47 5f 50 41 47 45 43 41 43 48 45 20 20 20 20 20  G_PAGECACHE     
16b50 37 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74  7  /* void*, int
16b60 20 73 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23 64   sz, int N */.#d
16b70 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
16b80 46 49 47 5f 48 45 41 50 20 20 20 20 20 20 20 20  FIG_HEAP        
16b90 20 20 38 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69    8  /* void*, i
16ba0 6e 74 20 6e 42 79 74 65 2c 20 69 6e 74 20 6d 69  nt nByte, int mi
16bb0 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  n */.#define SQL
16bc0 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54  ITE_CONFIG_MEMST
16bd0 41 54 55 53 20 20 20 20 20 39 20 20 2f 2a 20 62  ATUS     9  /* b
16be0 6f 6f 6c 65 61 6e 20 2a 2f 0a 23 64 65 66 69 6e  oolean */.#defin
16bf0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
16c00 4d 55 54 45 58 20 20 20 20 20 20 20 20 31 30 20  MUTEX        10 
16c10 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74 65   /* sqlite3_mute
16c20 78 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64  x_methods* */.#d
16c30 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
16c40 46 49 47 5f 47 45 54 4d 55 54 45 58 20 20 20 20  FIG_GETMUTEX    
16c50 20 31 31 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f   11  /* sqlite3_
16c60 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 2a 20 2a  mutex_methods* *
16c70 2f 0a 2f 2a 20 70 72 65 76 69 6f 75 73 6c 79 20  /./* previously 
16c80 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 48  SQLITE_CONFIG_CH
16c90 55 4e 4b 41 4c 4c 4f 43 20 31 32 20 77 68 69 63  UNKALLOC 12 whic
16ca0 68 20 69 73 20 6e 6f 77 20 75 6e 75 73 65 64 2e  h is now unused.
16cb0 20 2a 2f 20 0a 23 64 65 66 69 6e 65 20 53 51 4c   */ .#define SQL
16cc0 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41  ITE_CONFIG_LOOKA
16cd0 53 49 44 45 20 20 20 20 31 33 20 20 2f 2a 20 69  SIDE    13  /* i
16ce0 6e 74 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e  nt int */.#defin
16cf0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
16d00 50 43 41 43 48 45 20 20 20 20 20 20 20 31 34 20  PCACHE       14 
16d10 20 2f 2a 20 6e 6f 2d 6f 70 20 2a 2f 0a 23 64 65   /* no-op */.#de
16d20 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
16d30 49 47 5f 47 45 54 50 43 41 43 48 45 20 20 20 20  IG_GETPCACHE    
16d40 31 35 20 20 2f 2a 20 6e 6f 2d 6f 70 20 2a 2f 0a  15  /* no-op */.
16d50 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
16d60 4f 4e 46 49 47 5f 4c 4f 47 20 20 20 20 20 20 20  ONFIG_LOG       
16d70 20 20 20 31 36 20 20 2f 2a 20 78 46 75 6e 63 2c     16  /* xFunc,
16d80 20 76 6f 69 64 2a 20 2a 2f 0a 23 64 65 66 69 6e   void* */.#defin
16d90 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
16da0 55 52 49 20 20 20 20 20 20 20 20 20 20 31 37 20  URI          17 
16db0 20 2f 2a 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69   /* int */.#defi
16dc0 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
16dd0 5f 50 43 41 43 48 45 32 20 20 20 20 20 20 31 38  _PCACHE2      18
16de0 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 70 63 61    /* sqlite3_pca
16df0 63 68 65 5f 6d 65 74 68 6f 64 73 32 2a 20 2a 2f  che_methods2* */
16e00 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
16e10 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45  CONFIG_GETPCACHE
16e20 32 20 20 20 31 39 20 20 2f 2a 20 73 71 6c 69 74  2   19  /* sqlit
16e30 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64  e3_pcache_method
16e40 73 32 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  s2* */.#define S
16e50 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56  QLITE_CONFIG_COV
16e60 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e  ERING_INDEX_SCAN
16e70 20 32 30 20 20 2f 2a 20 69 6e 74 20 2a 2f 0a 23   20  /* int */.#
16e80 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
16e90 4e 46 49 47 5f 53 51 4c 4c 4f 47 20 20 20 20 20  NFIG_SQLLOG     
16ea0 20 20 32 31 20 20 2f 2a 20 78 53 71 6c 6c 6f 67    21  /* xSqllog
16eb0 2c 20 76 6f 69 64 2a 20 2a 2f 0a 23 64 65 66 69  , void* */.#defi
16ec0 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
16ed0 5f 4d 4d 41 50 5f 53 49 5a 45 20 20 20 20 32 32  _MMAP_SIZE    22
16ee0 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 69 6e 74    /* sqlite3_int
16ef0 36 34 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  64, sqlite3_int6
16f00 34 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  4 */.#define SQL
16f10 49 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32  ITE_CONFIG_WIN32
16f20 5f 48 45 41 50 53 49 5a 45 20 20 20 20 20 20 32  _HEAPSIZE      2
16f30 33 20 20 2f 2a 20 69 6e 74 20 6e 42 79 74 65 20  3  /* int nByte 
16f40 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
16f50 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 5f  E_CONFIG_PCACHE_
16f60 48 44 52 53 5a 20 20 20 20 20 20 20 20 32 34 20  HDRSZ        24 
16f70 20 2f 2a 20 69 6e 74 20 2a 70 73 7a 20 2a 2f 0a   /* int *psz */.
16f80 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
16f90 4f 4e 46 49 47 5f 50 4d 41 53 5a 20 20 20 20 20  ONFIG_PMASZ     
16fa0 20 20 20 20 20 20 20 20 20 20 32 35 20 20 2f 2a            25  /*
16fb0 20 75 6e 73 69 67 6e 65 64 20 69 6e 74 20 73 7a   unsigned int sz
16fc0 50 6d 61 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  Pma */.#define S
16fd0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 54 4d  QLITE_CONFIG_STM
16fe0 54 4a 52 4e 4c 5f 53 50 49 4c 4c 20 20 20 20 20  TJRNL_SPILL     
16ff0 20 32 36 20 20 2f 2a 20 69 6e 74 20 6e 42 79 74   26  /* int nByt
17000 65 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  e */../*.** CAPI
17010 33 52 45 46 3a 20 44 61 74 61 62 61 73 65 20 43  3REF: Database C
17020 6f 6e 6e 65 63 74 69 6f 6e 20 43 6f 6e 66 69 67  onnection Config
17030 75 72 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 0a  uration Options.
17040 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73  **.** These cons
17050 74 61 6e 74 73 20 61 72 65 20 74 68 65 20 61 76  tants are the av
17060 61 69 6c 61 62 6c 65 20 69 6e 74 65 67 65 72 20  ailable integer 
17070 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
17080 74 69 6f 6e 73 20 74 68 61 74 0a 2a 2a 20 63 61  tions that.** ca
17090 6e 20 62 65 20 70 61 73 73 65 64 20 61 73 20 74  n be passed as t
170a0 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
170b0 6e 74 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74  nt to the [sqlit
170c0 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20  e3_db_config()] 
170d0 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a  interface..**.**
170e0 20 4e 65 77 20 63 6f 6e 66 69 67 75 72 61 74 69   New configurati
170f0 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 61 79 20 62  on options may b
17100 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72  e added in futur
17110 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51  e releases of SQ
17120 4c 69 74 65 2e 0a 2a 2a 20 45 78 69 73 74 69 6e  Lite..** Existin
17130 67 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  g configuration 
17140 6f 70 74 69 6f 6e 73 20 6d 69 67 68 74 20 62 65  options might be
17150 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 2e 20 20   discontinued.  
17160 41 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20  Applications.** 
17170 73 68 6f 75 6c 64 20 63 68 65 63 6b 20 74 68 65  should check the
17180 20 72 65 74 75 72 6e 20 63 6f 64 65 20 66 72 6f   return code fro
17190 6d 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f  m [sqlite3_db_co
171a0 6e 66 69 67 28 29 5d 20 74 6f 20 6d 61 6b 65 20  nfig()] to make 
171b0 73 75 72 65 20 74 68 61 74 0a 2a 2a 20 74 68 65  sure that.** the
171c0 20 63 61 6c 6c 20 77 6f 72 6b 65 64 2e 20 20 5e   call worked.  ^
171d0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f  The [sqlite3_db_
171e0 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66  config()] interf
171f0 61 63 65 20 77 69 6c 6c 20 72 65 74 75 72 6e 20  ace will return 
17200 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65  a.** non-zero [e
17210 72 72 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 20  rror code] if a 
17220 64 69 73 63 6f 6e 74 69 6e 75 65 64 20 6f 72 20  discontinued or 
17230 75 6e 73 75 70 70 6f 72 74 65 64 20 63 6f 6e 66  unsupported conf
17240 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
17250 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a  .** is invoked..
17260 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64  **.** <dl>.** <d
17270 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49  t>SQLITE_DBCONFI
17280 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64 74 3e  G_LOOKASIDE</dt>
17290 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f  .** <dd> ^This o
172a0 70 74 69 6f 6e 20 74 61 6b 65 73 20 74 68 72 65  ption takes thre
172b0 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 67  e additional arg
172c0 75 6d 65 6e 74 73 20 74 68 61 74 20 64 65 74 65  uments that dete
172d0 72 6d 69 6e 65 20 74 68 65 20 0a 2a 2a 20 5b 6c  rmine the .** [l
172e0 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20  ookaside memory 
172f0 61 6c 6c 6f 63 61 74 6f 72 5d 20 63 6f 6e 66 69  allocator] confi
17300 67 75 72 61 74 69 6f 6e 20 66 6f 72 20 74 68 65  guration for the
17310 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
17320 63 74 69 6f 6e 5d 2e 0a 2a 2a 20 5e 54 68 65 20  ction]..** ^The 
17330 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 28  first argument (
17340 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65  the third parame
17350 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  ter to [sqlite3_
17360 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69 73 20  db_config()] is 
17370 61 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74 6f 20  a.** pointer to 
17380 61 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20  a memory buffer 
17390 74 6f 20 75 73 65 20 66 6f 72 20 6c 6f 6f 6b 61  to use for looka
173a0 73 69 64 65 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20  side memory..** 
173b0 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d  ^The first argum
173c0 65 6e 74 20 61 66 74 65 72 20 74 68 65 20 53 51  ent after the SQ
173d0 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f  LITE_DBCONFIG_LO
173e0 4f 4b 41 53 49 44 45 20 76 65 72 62 0a 2a 2a 20  OKASIDE verb.** 
173f0 6d 61 79 20 62 65 20 4e 55 4c 4c 20 69 6e 20 77  may be NULL in w
17400 68 69 63 68 20 63 61 73 65 20 53 51 4c 69 74 65  hich case SQLite
17410 20 77 69 6c 6c 20 61 6c 6c 6f 63 61 74 65 20 74   will allocate t
17420 68 65 0a 2a 2a 20 6c 6f 6f 6b 61 73 69 64 65 20  he.** lookaside 
17430 62 75 66 66 65 72 20 69 74 73 65 6c 66 20 75 73  buffer itself us
17440 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  ing [sqlite3_mal
17450 6c 6f 63 28 29 5d 2e 20 5e 54 68 65 20 73 65 63  loc()]. ^The sec
17460 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20  ond argument is 
17470 74 68 65 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 65  the.** size of e
17480 61 63 68 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75  ach lookaside bu
17490 66 66 65 72 20 73 6c 6f 74 2e 20 20 5e 54 68 65  ffer slot.  ^The
174a0 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20   third argument 
174b0 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  is the number of
174c0 0a 2a 2a 20 73 6c 6f 74 73 2e 20 20 54 68 65 20  .** slots.  The 
174d0 73 69 7a 65 20 6f 66 20 74 68 65 20 62 75 66 66  size of the buff
174e0 65 72 20 69 6e 20 74 68 65 20 66 69 72 73 74 20  er in the first 
174f0 61 72 67 75 6d 65 6e 74 20 6d 75 73 74 20 62 65  argument must be
17500 20 67 72 65 61 74 65 72 20 74 68 61 6e 0a 2a 2a   greater than.**
17510 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 74 68 65   or equal to the
17520 20 70 72 6f 64 75 63 74 20 6f 66 20 74 68 65 20   product of the 
17530 73 65 63 6f 6e 64 20 61 6e 64 20 74 68 69 72 64  second and third
17540 20 61 72 67 75 6d 65 6e 74 73 2e 20 20 54 68 65   arguments.  The
17550 20 62 75 66 66 65 72 0a 2a 2a 20 6d 75 73 74 20   buffer.** must 
17560 62 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e  be aligned to an
17570 20 38 2d 62 79 74 65 20 62 6f 75 6e 64 61 72 79   8-byte boundary
17580 2e 20 20 5e 49 66 20 74 68 65 20 73 65 63 6f 6e  .  ^If the secon
17590 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a  d argument to.**
175a0 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47   SQLITE_DBCONFIG
175b0 5f 4c 4f 4f 4b 41 53 49 44 45 20 69 73 20 6e 6f  _LOOKASIDE is no
175c0 74 20 61 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20  t a multiple of 
175d0 38 2c 20 69 74 20 69 73 20 69 6e 74 65 72 6e 61  8, it is interna
175e0 6c 6c 79 0a 2a 2a 20 72 6f 75 6e 64 65 64 20 64  lly.** rounded d
175f0 6f 77 6e 20 74 6f 20 74 68 65 20 6e 65 78 74 20  own to the next 
17600 73 6d 61 6c 6c 65 72 20 6d 75 6c 74 69 70 6c 65  smaller multiple
17610 20 6f 66 20 38 2e 20 20 5e 28 54 68 65 20 6c 6f   of 8.  ^(The lo
17620 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 0a 2a  okaside memory.*
17630 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  * configuration 
17640 66 6f 72 20 61 20 64 61 74 61 62 61 73 65 20 63  for a database c
17650 6f 6e 6e 65 63 74 69 6f 6e 20 63 61 6e 20 6f 6e  onnection can on
17660 6c 79 20 62 65 20 63 68 61 6e 67 65 64 20 77 68  ly be changed wh
17670 65 6e 20 74 68 61 74 0a 2a 2a 20 63 6f 6e 6e 65  en that.** conne
17680 63 74 69 6f 6e 20 69 73 20 6e 6f 74 20 63 75 72  ction is not cur
17690 72 65 6e 74 6c 79 20 75 73 69 6e 67 20 6c 6f 6f  rently using loo
176a0 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 2c 20 6f  kaside memory, o
176b0 72 20 69 6e 20 6f 74 68 65 72 20 77 6f 72 64 73  r in other words
176c0 0a 2a 2a 20 77 68 65 6e 20 74 68 65 20 22 63 75  .** when the "cu
176d0 72 72 65 6e 74 20 76 61 6c 75 65 22 20 72 65 74  rrent value" ret
176e0 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c  urned by.** [sql
176f0 69 74 65 33 5f 64 62 5f 73 74 61 74 75 73 5d 28  ite3_db_status](
17700 44 2c 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  D,[SQLITE_CONFIG
17710 5f 4c 4f 4f 4b 41 53 49 44 45 5d 2c 2e 2e 2e 29  _LOOKASIDE],...)
17720 20 69 73 20 7a 65 72 6f 2e 0a 2a 2a 20 41 6e 79   is zero..** Any
17730 20 61 74 74 65 6d 70 74 20 74 6f 20 63 68 61 6e   attempt to chan
17740 67 65 20 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65  ge the lookaside
17750 20 6d 65 6d 6f 72 79 20 63 6f 6e 66 69 67 75 72   memory configur
17760 61 74 69 6f 6e 20 77 68 65 6e 20 6c 6f 6f 6b 61  ation when looka
17770 73 69 64 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 69  side.** memory i
17780 73 20 69 6e 20 75 73 65 20 6c 65 61 76 65 73 20  s in use leaves 
17790 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  the configuratio
177a0 6e 20 75 6e 63 68 61 6e 67 65 64 20 61 6e 64 20  n unchanged and 
177b0 72 65 74 75 72 6e 73 20 0a 2a 2a 20 5b 53 51 4c  returns .** [SQL
177c0 49 54 45 5f 42 55 53 59 5d 2e 29 5e 3c 2f 64 64  ITE_BUSY].)^</dd
177d0 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  >.**.** <dt>SQLI
177e0 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42  TE_DBCONFIG_ENAB
177f0 4c 45 5f 46 4b 45 59 3c 2f 64 74 3e 0a 2a 2a 20  LE_FKEY</dt>.** 
17800 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f  <dd> ^This optio
17810 6e 20 69 73 20 75 73 65 64 20 74 6f 20 65 6e 61  n is used to ena
17820 62 6c 65 20 6f 72 20 64 69 73 61 62 6c 65 20 74  ble or disable t
17830 68 65 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 6f  he enforcement o
17840 66 0a 2a 2a 20 5b 66 6f 72 65 69 67 6e 20 6b 65  f.** [foreign ke
17850 79 20 63 6f 6e 73 74 72 61 69 6e 74 73 5d 2e 20  y constraints]. 
17860 20 54 68 65 72 65 20 73 68 6f 75 6c 64 20 62 65   There should be
17870 20 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20   two additional 
17880 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20 54 68  arguments..** Th
17890 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
178a0 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77   is an integer w
178b0 68 69 63 68 20 69 73 20 30 20 74 6f 20 64 69 73  hich is 0 to dis
178c0 61 62 6c 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d  able FK enforcem
178d0 65 6e 74 2c 0a 2a 2a 20 70 6f 73 69 74 69 76 65  ent,.** positive
178e0 20 74 6f 20 65 6e 61 62 6c 65 20 46 4b 20 65 6e   to enable FK en
178f0 66 6f 72 63 65 6d 65 6e 74 20 6f 72 20 6e 65 67  forcement or neg
17900 61 74 69 76 65 20 74 6f 20 6c 65 61 76 65 20 46  ative to leave F
17910 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 0a 2a 2a  K enforcement.**
17920 20 75 6e 63 68 61 6e 67 65 64 2e 20 20 54 68 65   unchanged.  The
17930 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
17940 72 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  r is a pointer t
17950 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 69 6e 74  o an integer int
17960 6f 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 77 72  o which.** is wr
17970 69 74 74 65 6e 20 30 20 6f 72 20 31 20 74 6f 20  itten 0 or 1 to 
17980 69 6e 64 69 63 61 74 65 20 77 68 65 74 68 65 72  indicate whether
17990 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20   FK enforcement 
179a0 69 73 20 6f 66 66 20 6f 72 20 6f 6e 0a 2a 2a 20  is off or on.** 
179b0 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 69 73 20 63  following this c
179c0 61 6c 6c 2e 20 20 54 68 65 20 73 65 63 6f 6e 64  all.  The second
179d0 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62   parameter may b
179e0 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  e a NULL pointer
179f0 2c 20 69 6e 0a 2a 2a 20 77 68 69 63 68 20 63 61  , in.** which ca
17a00 73 65 20 74 68 65 20 46 4b 20 65 6e 66 6f 72 63  se the FK enforc
17a10 65 6d 65 6e 74 20 73 65 74 74 69 6e 67 20 69 73  ement setting is
17a20 20 6e 6f 74 20 72 65 70 6f 72 74 65 64 20 62 61   not reported ba
17a30 63 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ck. </dd>.**.** 
17a40 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e  <dt>SQLITE_DBCON
17a50 46 49 47 5f 45 4e 41 42 4c 45 5f 54 52 49 47 47  FIG_ENABLE_TRIGG
17a60 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  ER</dt>.** <dd> 
17a70 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20  ^This option is 
17a80 75 73 65 64 20 74 6f 20 65 6e 61 62 6c 65 20 6f  used to enable o
17a90 72 20 64 69 73 61 62 6c 65 20 5b 43 52 45 41 54  r disable [CREAT
17aa0 45 20 54 52 49 47 47 45 52 20 7c 20 74 72 69 67  E TRIGGER | trig
17ab0 67 65 72 73 5d 2e 0a 2a 2a 20 54 68 65 72 65 20  gers]..** There 
17ac0 73 68 6f 75 6c 64 20 62 65 20 74 77 6f 20 61 64  should be two ad
17ad0 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e  ditional argumen
17ae0 74 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74  ts..** The first
17af0 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 6e 20   argument is an 
17b00 69 6e 74 65 67 65 72 20 77 68 69 63 68 20 69 73  integer which is
17b10 20 30 20 74 6f 20 64 69 73 61 62 6c 65 20 74 72   0 to disable tr
17b20 69 67 67 65 72 73 2c 0a 2a 2a 20 70 6f 73 69 74  iggers,.** posit
17b30 69 76 65 20 74 6f 20 65 6e 61 62 6c 65 20 74 72  ive to enable tr
17b40 69 67 67 65 72 73 20 6f 72 20 6e 65 67 61 74 69  iggers or negati
17b50 76 65 20 74 6f 20 6c 65 61 76 65 20 74 68 65 20  ve to leave the 
17b60 73 65 74 74 69 6e 67 20 75 6e 63 68 61 6e 67 65  setting unchange
17b70 64 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64  d..** The second
17b80 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20   parameter is a 
17b90 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e  pointer to an in
17ba0 74 65 67 65 72 20 69 6e 74 6f 20 77 68 69 63 68  teger into which
17bb0 0a 2a 2a 20 69 73 20 77 72 69 74 74 65 6e 20 30  .** is written 0
17bc0 20 6f 72 20 31 20 74 6f 20 69 6e 64 69 63 61 74   or 1 to indicat
17bd0 65 20 77 68 65 74 68 65 72 20 74 72 69 67 67 65  e whether trigge
17be0 72 73 20 61 72 65 20 64 69 73 61 62 6c 65 64 20  rs are disabled 
17bf0 6f 72 20 65 6e 61 62 6c 65 64 0a 2a 2a 20 66 6f  or enabled.** fo
17c00 6c 6c 6f 77 69 6e 67 20 74 68 69 73 20 63 61 6c  llowing this cal
17c10 6c 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 70  l.  The second p
17c20 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20  arameter may be 
17c30 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20  a NULL pointer, 
17c40 69 6e 0a 2a 2a 20 77 68 69 63 68 20 63 61 73 65  in.** which case
17c50 20 74 68 65 20 74 72 69 67 67 65 72 20 73 65 74   the trigger set
17c60 74 69 6e 67 20 69 73 20 6e 6f 74 20 72 65 70 6f  ting is not repo
17c70 72 74 65 64 20 62 61 63 6b 2e 20 3c 2f 64 64 3e  rted back. </dd>
17c80 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  .**.** <dt>SQLIT
17c90 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c  E_DBCONFIG_ENABL
17ca0 45 5f 46 54 53 33 5f 54 4f 4b 45 4e 49 5a 45 52  E_FTS3_TOKENIZER
17cb0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54  </dt>.** <dd> ^T
17cc0 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 75 73  his option is us
17cd0 65 64 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20  ed to enable or 
17ce0 64 69 73 61 62 6c 65 20 74 68 65 20 74 77 6f 2d  disable the two-
17cf0 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 76 65 72 73  argument.** vers
17d00 69 6f 6e 20 6f 66 20 74 68 65 20 5b 66 74 73 33  ion of the [fts3
17d10 5f 74 6f 6b 65 6e 69 7a 65 72 28 29 5d 20 66 75  _tokenizer()] fu
17d20 6e 63 74 69 6f 6e 20 77 68 69 63 68 20 69 73 20  nction which is 
17d30 70 61 72 74 20 6f 66 20 74 68 65 0a 2a 2a 20 5b  part of the.** [
17d40 46 54 53 33 5d 20 66 75 6c 6c 2d 74 65 78 74 20  FTS3] full-text 
17d50 73 65 61 72 63 68 20 65 6e 67 69 6e 65 20 65 78  search engine ex
17d60 74 65 6e 73 69 6f 6e 2e 0a 2a 2a 20 54 68 65 72  tension..** Ther
17d70 65 20 73 68 6f 75 6c 64 20 62 65 20 74 77 6f 20  e should be two 
17d80 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d  additional argum
17d90 65 6e 74 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72  ents..** The fir
17da0 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61  st argument is a
17db0 6e 20 69 6e 74 65 67 65 72 20 77 68 69 63 68 20  n integer which 
17dc0 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65 20  is 0 to disable 
17dd0 66 74 73 33 5f 74 6f 6b 65 6e 69 7a 65 72 28 29  fts3_tokenizer()
17de0 20 6f 72 0a 2a 2a 20 70 6f 73 69 74 69 76 65 20   or.** positive 
17df0 74 6f 20 65 6e 61 62 6c 65 20 66 74 73 33 5f 74  to enable fts3_t
17e00 6f 6b 65 6e 69 7a 65 72 28 29 20 6f 72 20 6e 65  okenizer() or ne
17e10 67 61 74 69 76 65 20 74 6f 20 6c 65 61 76 65 20  gative to leave 
17e20 74 68 65 20 73 65 74 74 69 6e 67 0a 2a 2a 20 75  the setting.** u
17e30 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 20 54 68 65  nchanged..** The
17e40 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
17e50 72 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  r is a pointer t
17e60 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 69 6e 74  o an integer int
17e70 6f 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 77 72  o which.** is wr
17e80 69 74 74 65 6e 20 30 20 6f 72 20 31 20 74 6f 20  itten 0 or 1 to 
17e90 69 6e 64 69 63 61 74 65 20 77 68 65 74 68 65 72  indicate whether
17ea0 20 66 74 73 33 5f 74 6f 6b 65 6e 69 7a 65 72 20   fts3_tokenizer 
17eb0 69 73 20 64 69 73 61 62 6c 65 64 20 6f 72 20 65  is disabled or e
17ec0 6e 61 62 6c 65 64 0a 2a 2a 20 66 6f 6c 6c 6f 77  nabled.** follow
17ed0 69 6e 67 20 74 68 69 73 20 63 61 6c 6c 2e 20 20  ing this call.  
17ee0 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  The second param
17ef0 65 74 65 72 20 6d 61 79 20 62 65 20 61 20 4e 55  eter may be a NU
17f00 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69 6e 0a 2a  LL pointer, in.*
17f10 2a 20 77 68 69 63 68 20 63 61 73 65 20 74 68 65  * which case the
17f20 20 6e 65 77 20 73 65 74 74 69 6e 67 20 69 73 20   new setting is 
17f30 6e 6f 74 20 72 65 70 6f 72 74 65 64 20 62 61 63  not reported bac
17f40 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c  k. </dd>.**.** <
17f50 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46  dt>SQLITE_DBCONF
17f60 49 47 5f 45 4e 41 42 4c 45 5f 4c 4f 41 44 5f 45  IG_ENABLE_LOAD_E
17f70 58 54 45 4e 53 49 4f 4e 3c 2f 64 74 3e 0a 2a 2a  XTENSION</dt>.**
17f80 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69   <dd> ^This opti
17f90 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20 65 6e  on is used to en
17fa0 61 62 6c 65 20 6f 72 20 64 69 73 61 62 6c 65 20  able or disable 
17fb0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 61  the [sqlite3_loa
17fc0 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d 0a 2a  d_extension()].*
17fd0 2a 20 69 6e 74 65 72 66 61 63 65 20 69 6e 64 65  * interface inde
17fe0 70 65 6e 64 65 6e 74 6c 79 20 6f 66 20 74 68 65  pendently of the
17ff0 20 5b 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e   [load_extension
18000 28 29 5d 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ()] SQL function
18010 2e 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65  ..** The [sqlite
18020 33 5f 65 6e 61 62 6c 65 5f 6c 6f 61 64 5f 65 78  3_enable_load_ex
18030 74 65 6e 73 69 6f 6e 28 29 5d 20 41 50 49 20 65  tension()] API e
18040 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62 6c  nables or disabl
18050 65 73 20 62 6f 74 68 20 74 68 65 0a 2a 2a 20 43  es both the.** C
18060 2d 41 50 49 20 5b 73 71 6c 69 74 65 33 5f 6c 6f  -API [sqlite3_lo
18070 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d 20  ad_extension()] 
18080 61 6e 64 20 74 68 65 20 53 51 4c 20 66 75 6e 63  and the SQL func
18090 74 69 6f 6e 20 5b 6c 6f 61 64 5f 65 78 74 65 6e  tion [load_exten
180a0 73 69 6f 6e 28 29 5d 2e 0a 2a 2a 20 54 68 65 72  sion()]..** Ther
180b0 65 20 73 68 6f 75 6c 64 20 62 65 20 74 77 6f 20  e should be two 
180c0 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d  additional argum
180d0 65 6e 74 73 2e 0a 2a 2a 20 57 68 65 6e 20 74 68  ents..** When th
180e0 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
180f0 20 74 6f 20 74 68 69 73 20 69 6e 74 65 72 66 61   to this interfa
18100 63 65 20 69 73 20 31 2c 20 74 68 65 6e 20 6f 6e  ce is 1, then on
18110 6c 79 20 74 68 65 20 43 2d 41 50 49 20 69 73 0a  ly the C-API is.
18120 2a 2a 20 65 6e 61 62 6c 65 64 20 61 6e 64 20 74  ** enabled and t
18130 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  he SQL function 
18140 72 65 6d 61 69 6e 73 20 64 69 73 61 62 6c 65 64  remains disabled
18150 2e 20 20 49 66 20 74 68 65 20 66 69 72 73 74 20  .  If the first 
18160 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 74  argument to.** t
18170 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 69 73  his interface is
18180 20 30 2c 20 74 68 65 6e 20 62 6f 74 68 20 74 68   0, then both th
18190 65 20 43 2d 41 50 49 20 61 6e 64 20 74 68 65 20  e C-API and the 
181a0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 61 72 65  SQL function are
181b0 20 64 69 73 61 62 6c 65 64 2e 0a 2a 2a 20 49 66   disabled..** If
181c0 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
181d0 65 6e 74 20 69 73 20 2d 31 2c 20 74 68 65 6e 20  ent is -1, then 
181e0 6e 6f 20 63 68 61 6e 67 65 73 20 61 72 65 20 6d  no changes are m
181f0 61 64 65 20 74 6f 20 73 74 61 74 65 20 6f 66 20  ade to state of 
18200 65 69 74 68 65 72 20 74 68 65 0a 2a 2a 20 43 2d  either the.** C-
18210 41 50 49 20 6f 72 20 74 68 65 20 53 51 4c 20 66  API or the SQL f
18220 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 54 68 65 20  unction..** The 
18230 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
18240 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
18250 20 61 6e 20 69 6e 74 65 67 65 72 20 69 6e 74 6f   an integer into
18260 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 77 72 69   which.** is wri
18270 74 74 65 6e 20 30 20 6f 72 20 31 20 74 6f 20 69  tten 0 or 1 to i
18280 6e 64 69 63 61 74 65 20 77 68 65 74 68 65 72 20  ndicate whether 
18290 5b 73 71 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 78  [sqlite3_load_ex
182a0 74 65 6e 73 69 6f 6e 28 29 5d 20 69 6e 74 65 72  tension()] inter
182b0 66 61 63 65 0a 2a 2a 20 69 73 20 64 69 73 61 62  face.** is disab
182c0 6c 65 64 20 6f 72 20 65 6e 61 62 6c 65 64 20 66  led or enabled f
182d0 6f 6c 6c 6f 77 69 6e 67 20 74 68 69 73 20 63 61  ollowing this ca
182e0 6c 6c 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20  ll.  The second 
182f0 70 61 72 61 6d 65 74 65 72 20 6d 61 79 0a 2a 2a  parameter may.**
18300 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   be a NULL point
18310 65 72 2c 20 69 6e 20 77 68 69 63 68 20 63 61 73  er, in which cas
18320 65 20 74 68 65 20 6e 65 77 20 73 65 74 74 69 6e  e the new settin
18330 67 20 69 73 20 6e 6f 74 20 72 65 70 6f 72 74 65  g is not reporte
18340 64 20 62 61 63 6b 2e 0a 2a 2a 20 3c 2f 64 64 3e  d back..** </dd>
18350 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  .**.** <dt>SQLIT
18360 45 5f 44 42 43 4f 4e 46 49 47 5f 4d 41 49 4e 44  E_DBCONFIG_MAIND
18370 42 4e 41 4d 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  BNAME</dt>.** <d
18380 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20  d> ^This option 
18390 69 73 20 75 73 65 64 20 74 6f 20 63 68 61 6e 67  is used to chang
183a0 65 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  e the name of th
183b0 65 20 22 6d 61 69 6e 22 20 64 61 74 61 62 61 73  e "main" databas
183c0 65 0a 2a 2a 20 73 63 68 65 6d 61 2e 20 20 5e 54  e.** schema.  ^T
183d0 68 65 20 73 6f 6c 65 20 61 72 67 75 6d 65 6e 74  he sole argument
183e0 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
183f0 20 61 20 63 6f 6e 73 74 61 6e 74 20 55 54 46 38   a constant UTF8
18400 20 73 74 72 69 6e 67 0a 2a 2a 20 77 68 69 63 68   string.** which
18410 20 77 69 6c 6c 20 62 65 63 6f 6d 65 20 74 68 65   will become the
18420 20 6e 65 77 20 73 63 68 65 6d 61 20 6e 61 6d 65   new schema name
18430 20 69 6e 20 70 6c 61 63 65 20 6f 66 20 22 6d 61   in place of "ma
18440 69 6e 22 2e 20 20 5e 53 51 4c 69 74 65 0a 2a 2a  in".  ^SQLite.**
18450 20 64 6f 65 73 20 6e 6f 74 20 6d 61 6b 65 20 61   does not make a
18460 20 63 6f 70 79 20 6f 66 20 74 68 65 20 6e 65 77   copy of the new
18470 20 6d 61 69 6e 20 73 63 68 65 6d 61 20 6e 61 6d   main schema nam
18480 65 20 73 74 72 69 6e 67 2c 20 73 6f 20 74 68 65  e string, so the
18490 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20   application.** 
184a0 6d 75 73 74 20 65 6e 73 75 72 65 20 74 68 61 74  must ensure that
184b0 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 70 61   the argument pa
184c0 73 73 65 64 20 69 6e 74 6f 20 74 68 69 73 20 44  ssed into this D
184d0 42 43 4f 4e 46 49 47 20 6f 70 74 69 6f 6e 20 69  BCONFIG option i
184e0 73 20 75 6e 63 68 61 6e 67 65 64 0a 2a 2a 20 75  s unchanged.** u
184f0 6e 74 69 6c 20 61 66 74 65 72 20 74 68 65 20 64  ntil after the d
18500 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
18510 6f 6e 20 63 6c 6f 73 65 73 2e 0a 2a 2a 20 3c 2f  on closes..** </
18520 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 2f 64 6c 3e 0a  dd>.**.** </dl>.
18530 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
18540 45 5f 44 42 43 4f 4e 46 49 47 5f 4d 41 49 4e 44  E_DBCONFIG_MAIND
18550 42 4e 41 4d 45 20 20 20 20 20 20 20 20 20 20 20  BNAME           
18560 20 31 30 30 30 20 2f 2a 20 63 6f 6e 73 74 20 63   1000 /* const c
18570 68 61 72 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20  har* */.#define 
18580 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
18590 4c 4f 4f 4b 41 53 49 44 45 20 20 20 20 20 20 20  LOOKASIDE       
185a0 20 20 20 20 20 20 31 30 30 31 20 2f 2a 20 76 6f        1001 /* vo
185b0 69 64 2a 20 69 6e 74 20 69 6e 74 20 2a 2f 0a 23  id* int int */.#
185c0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42  define SQLITE_DB
185d0 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 46 4b  CONFIG_ENABLE_FK
185e0 45 59 20 20 20 20 20 20 20 20 20 20 20 31 30 30  EY           100
185f0 32 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f  2 /* int int* */
18600 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
18610 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f  DBCONFIG_ENABLE_
18620 54 52 49 47 47 45 52 20 20 20 20 20 20 20 20 31  TRIGGER        1
18630 30 30 33 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 20  003 /* int int* 
18640 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
18650 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c  E_DBCONFIG_ENABL
18660 45 5f 46 54 53 33 5f 54 4f 4b 45 4e 49 5a 45 52  E_FTS3_TOKENIZER
18670 20 31 30 30 34 20 2f 2a 20 69 6e 74 20 69 6e 74   1004 /* int int
18680 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  * */.#define SQL
18690 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41  ITE_DBCONFIG_ENA
186a0 42 4c 45 5f 4c 4f 41 44 5f 45 58 54 45 4e 53 49  BLE_LOAD_EXTENSI
186b0 4f 4e 20 31 30 30 35 20 2f 2a 20 69 6e 74 20 69  ON 1005 /* int i
186c0 6e 74 2a 20 2a 2f 0a 0a 0a 2f 2a 0a 2a 2a 20 43  nt* */.../*.** C
186d0 41 50 49 33 52 45 46 3a 20 45 6e 61 62 6c 65 20  API3REF: Enable 
186e0 4f 72 20 44 69 73 61 62 6c 65 20 45 78 74 65 6e  Or Disable Exten
186f0 64 65 64 20 52 65 73 75 6c 74 20 43 6f 64 65 73  ded Result Codes
18700 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
18710 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  te3.**.** ^The s
18720 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f  qlite3_extended_
18730 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 29 20 72  result_codes() r
18740 6f 75 74 69 6e 65 20 65 6e 61 62 6c 65 73 20 6f  outine enables o
18750 72 20 64 69 73 61 62 6c 65 73 20 74 68 65 0a 2a  r disables the.*
18760 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75  * [extended resu
18770 6c 74 20 63 6f 64 65 73 5d 20 66 65 61 74 75 72  lt codes] featur
18780 65 20 6f 66 20 53 51 4c 69 74 65 2e 20 5e 54 68  e of SQLite. ^Th
18790 65 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c  e extended resul
187a0 74 0a 2a 2a 20 63 6f 64 65 73 20 61 72 65 20 64  t.** codes are d
187b0 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 61 75  isabled by defau
187c0 6c 74 20 66 6f 72 20 68 69 73 74 6f 72 69 63 61  lt for historica
187d0 6c 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e  l compatibility.
187e0 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
187f0 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f  extended_result_
18800 63 6f 64 65 73 28 73 71 6c 69 74 65 33 2a 2c 20  codes(sqlite3*, 
18810 69 6e 74 20 6f 6e 6f 66 66 29 3b 0a 0a 2f 2a 0a  int onoff);../*.
18820 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4c 61 73  ** CAPI3REF: Las
18830 74 20 49 6e 73 65 72 74 20 52 6f 77 69 64 0a 2a  t Insert Rowid.*
18840 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65  * METHOD: sqlite
18850 33 0a 2a 2a 0a 2a 2a 20 5e 45 61 63 68 20 65 6e  3.**.** ^Each en
18860 74 72 79 20 69 6e 20 6d 6f 73 74 20 53 51 4c 69  try in most SQLi
18870 74 65 20 74 61 62 6c 65 73 20 28 65 78 63 65 70  te tables (excep
18880 74 20 66 6f 72 20 5b 57 49 54 48 4f 55 54 20 52  t for [WITHOUT R
18890 4f 57 49 44 5d 20 74 61 62 6c 65 73 29 0a 2a 2a  OWID] tables).**
188a0 20 68 61 73 20 61 20 75 6e 69 71 75 65 20 36 34   has a unique 64
188b0 2d 62 69 74 20 73 69 67 6e 65 64 0a 2a 2a 20 69  -bit signed.** i
188c0 6e 74 65 67 65 72 20 6b 65 79 20 63 61 6c 6c 65  nteger key calle
188d0 64 20 74 68 65 20 5b 52 4f 57 49 44 20 7c 20 22  d the [ROWID | "
188e0 72 6f 77 69 64 22 5d 2e 20 5e 54 68 65 20 72 6f  rowid"]. ^The ro
188f0 77 69 64 20 69 73 20 61 6c 77 61 79 73 20 61 76  wid is always av
18900 61 69 6c 61 62 6c 65 0a 2a 2a 20 61 73 20 61 6e  ailable.** as an
18910 20 75 6e 64 65 63 6c 61 72 65 64 20 63 6f 6c 75   undeclared colu
18920 6d 6e 20 6e 61 6d 65 64 20 52 4f 57 49 44 2c 20  mn named ROWID, 
18930 4f 49 44 2c 20 6f 72 20 5f 52 4f 57 49 44 5f 20  OID, or _ROWID_ 
18940 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 6f 73 65  as long as those
18950 0a 2a 2a 20 6e 61 6d 65 73 20 61 72 65 20 6e 6f  .** names are no
18960 74 20 61 6c 73 6f 20 75 73 65 64 20 62 79 20 65  t also used by e
18970 78 70 6c 69 63 69 74 6c 79 20 64 65 63 6c 61 72  xplicitly declar
18980 65 64 20 63 6f 6c 75 6d 6e 73 2e 20 5e 49 66 0a  ed columns. ^If.
18990 2a 2a 20 74 68 65 20 74 61 62 6c 65 20 68 61 73  ** the table has
189a0 20 61 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 79 70   a column of typ
189b0 65 20 5b 49 4e 54 45 47 45 52 20 50 52 49 4d 41  e [INTEGER PRIMA
189c0 52 59 20 4b 45 59 5d 20 74 68 65 6e 20 74 68 61  RY KEY] then tha
189d0 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20 61  t column.** is a
189e0 6e 6f 74 68 65 72 20 61 6c 69 61 73 20 66 6f 72  nother alias for
189f0 20 74 68 65 20 72 6f 77 69 64 2e 0a 2a 2a 0a 2a   the rowid..**.*
18a00 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6c  * ^The sqlite3_l
18a10 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64  ast_insert_rowid
18a20 28 44 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  (D) interface re
18a30 74 75 72 6e 73 20 74 68 65 20 5b 72 6f 77 69 64  turns the [rowid
18a40 5d 20 6f 66 20 74 68 65 20 0a 2a 2a 20 6d 6f 73  ] of the .** mos
18a50 74 20 72 65 63 65 6e 74 20 73 75 63 63 65 73 73  t recent success
18a60 66 75 6c 20 5b 49 4e 53 45 52 54 5d 20 69 6e 74  ful [INSERT] int
18a70 6f 20 61 20 72 6f 77 69 64 20 74 61 62 6c 65 20  o a rowid table 
18a80 6f 72 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c  or [virtual tabl
18a90 65 5d 0a 2a 2a 20 6f 6e 20 64 61 74 61 62 61 73  e].** on databas
18aa0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2e 0a  e connection D..
18ab0 2a 2a 20 5e 49 6e 73 65 72 74 73 20 69 6e 74 6f  ** ^Inserts into
18ac0 20 5b 57 49 54 48 4f 55 54 20 52 4f 57 49 44 5d   [WITHOUT ROWID]
18ad0 20 74 61 62 6c 65 73 20 61 72 65 20 6e 6f 74 20   tables are not 
18ae0 72 65 63 6f 72 64 65 64 2e 0a 2a 2a 20 5e 49 66  recorded..** ^If
18af0 20 6e 6f 20 73 75 63 63 65 73 73 66 75 6c 20 5b   no successful [
18b00 49 4e 53 45 52 54 5d 73 20 69 6e 74 6f 20 72 6f  INSERT]s into ro
18b10 77 69 64 20 74 61 62 6c 65 73 0a 2a 2a 20 68 61  wid tables.** ha
18b20 76 65 20 65 76 65 72 20 6f 63 63 75 72 72 65 64  ve ever occurred
18b30 20 6f 6e 20 74 68 65 20 64 61 74 61 62 61 73 65   on the database
18b40 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2c 20 0a   connection D, .
18b50 2a 2a 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  ** then sqlite3_
18b60 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69  last_insert_rowi
18b70 64 28 44 29 20 72 65 74 75 72 6e 73 20 7a 65 72  d(D) returns zer
18b80 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 61 6e  o..**.** ^(If an
18b90 20 5b 49 4e 53 45 52 54 5d 20 6f 63 63 75 72 73   [INSERT] occurs
18ba0 20 77 69 74 68 69 6e 20 61 20 74 72 69 67 67 65   within a trigge
18bb0 72 20 6f 72 20 77 69 74 68 69 6e 20 61 20 5b 76  r or within a [v
18bc0 69 72 74 75 61 6c 20 74 61 62 6c 65 5d 0a 2a 2a  irtual table].**
18bd0 20 6d 65 74 68 6f 64 2c 20 74 68 65 6e 20 74 68   method, then th
18be0 69 73 20 72 6f 75 74 69 6e 65 20 77 69 6c 6c 20  is routine will 
18bf0 72 65 74 75 72 6e 20 74 68 65 20 5b 72 6f 77 69  return the [rowi
18c00 64 5d 20 6f 66 20 74 68 65 20 69 6e 73 65 72 74  d] of the insert
18c10 65 64 0a 2a 2a 20 72 6f 77 20 61 73 20 6c 6f 6e  ed.** row as lon
18c20 67 20 61 73 20 74 68 65 20 74 72 69 67 67 65 72  g as the trigger
18c30 20 6f 72 20 76 69 72 74 75 61 6c 20 74 61 62 6c   or virtual tabl
18c40 65 20 6d 65 74 68 6f 64 20 69 73 20 72 75 6e 6e  e method is runn
18c50 69 6e 67 2e 0a 2a 2a 20 42 75 74 20 6f 6e 63 65  ing..** But once
18c60 20 74 68 65 20 74 72 69 67 67 65 72 20 6f 72 20   the trigger or 
18c70 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 65  virtual table me
18c80 74 68 6f 64 20 65 6e 64 73 2c 20 74 68 65 20 76  thod ends, the v
18c90 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 0a 2a  alue returned .*
18ca0 2a 20 62 79 20 74 68 69 73 20 72 6f 75 74 69 6e  * by this routin
18cb0 65 20 72 65 76 65 72 74 73 20 74 6f 20 77 68 61  e reverts to wha
18cc0 74 20 69 74 20 77 61 73 20 62 65 66 6f 72 65 20  t it was before 
18cd0 74 68 65 20 74 72 69 67 67 65 72 20 6f 72 20 76  the trigger or v
18ce0 69 72 74 75 61 6c 0a 2a 2a 20 74 61 62 6c 65 20  irtual.** table 
18cf0 6d 65 74 68 6f 64 20 62 65 67 61 6e 2e 29 5e 0a  method began.)^.
18d00 2a 2a 0a 2a 2a 20 5e 41 6e 20 5b 49 4e 53 45 52  **.** ^An [INSER
18d10 54 5d 20 74 68 61 74 20 66 61 69 6c 73 20 64 75  T] that fails du
18d20 65 20 74 6f 20 61 20 63 6f 6e 73 74 72 61 69 6e  e to a constrain
18d30 74 20 76 69 6f 6c 61 74 69 6f 6e 20 69 73 20 6e  t violation is n
18d40 6f 74 20 61 0a 2a 2a 20 73 75 63 63 65 73 73 66  ot a.** successf
18d50 75 6c 20 5b 49 4e 53 45 52 54 5d 20 61 6e 64 20  ul [INSERT] and 
18d60 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67 65 20  does not change 
18d70 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e  the value return
18d80 65 64 20 62 79 20 74 68 69 73 0a 2a 2a 20 72 6f  ed by this.** ro
18d90 75 74 69 6e 65 2e 20 20 5e 54 68 75 73 20 49 4e  utine.  ^Thus IN
18da0 53 45 52 54 20 4f 52 20 46 41 49 4c 2c 20 49 4e  SERT OR FAIL, IN
18db0 53 45 52 54 20 4f 52 20 49 47 4e 4f 52 45 2c 20  SERT OR IGNORE, 
18dc0 49 4e 53 45 52 54 20 4f 52 20 52 4f 4c 4c 42 41  INSERT OR ROLLBA
18dd0 43 4b 2c 0a 2a 2a 20 61 6e 64 20 49 4e 53 45 52  CK,.** and INSER
18de0 54 20 4f 52 20 41 42 4f 52 54 20 6d 61 6b 65 20  T OR ABORT make 
18df0 6e 6f 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68  no changes to th
18e00 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f  e return value o
18e10 66 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e  f this.** routin
18e20 65 20 77 68 65 6e 20 74 68 65 69 72 20 69 6e 73  e when their ins
18e30 65 72 74 69 6f 6e 20 66 61 69 6c 73 2e 20 20 5e  ertion fails.  ^
18e40 28 57 68 65 6e 20 49 4e 53 45 52 54 20 4f 52 20  (When INSERT OR 
18e50 52 45 50 4c 41 43 45 0a 2a 2a 20 65 6e 63 6f 75  REPLACE.** encou
18e60 6e 74 65 72 73 20 61 20 63 6f 6e 73 74 72 61 69  nters a constrai
18e70 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 2c 20 69 74  nt violation, it
18e80 20 64 6f 65 73 20 6e 6f 74 20 66 61 69 6c 2e 20   does not fail. 
18e90 20 54 68 65 0a 2a 2a 20 49 4e 53 45 52 54 20 63   The.** INSERT c
18ea0 6f 6e 74 69 6e 75 65 73 20 74 6f 20 63 6f 6d 70  ontinues to comp
18eb0 6c 65 74 69 6f 6e 20 61 66 74 65 72 20 64 65 6c  letion after del
18ec0 65 74 69 6e 67 20 72 6f 77 73 20 74 68 61 74 20  eting rows that 
18ed0 63 61 75 73 65 64 0a 2a 2a 20 74 68 65 20 63 6f  caused.** the co
18ee0 6e 73 74 72 61 69 6e 74 20 70 72 6f 62 6c 65 6d  nstraint problem
18ef0 20 73 6f 20 49 4e 53 45 52 54 20 4f 52 20 52 45   so INSERT OR RE
18f00 50 4c 41 43 45 20 77 69 6c 6c 20 61 6c 77 61 79  PLACE will alway
18f10 73 20 63 68 61 6e 67 65 0a 2a 2a 20 74 68 65 20  s change.** the 
18f20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20  return value of 
18f30 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 2e 29  this interface.)
18f40 5e 0a 2a 2a 0a 2a 2a 20 5e 46 6f 72 20 74 68 65  ^.**.** ^For the
18f50 20 70 75 72 70 6f 73 65 73 20 6f 66 20 74 68 69   purposes of thi
18f60 73 20 72 6f 75 74 69 6e 65 2c 20 61 6e 20 5b 49  s routine, an [I
18f70 4e 53 45 52 54 5d 20 69 73 20 63 6f 6e 73 69 64  NSERT] is consid
18f80 65 72 65 64 20 74 6f 0a 2a 2a 20 62 65 20 73 75  ered to.** be su
18f90 63 63 65 73 73 66 75 6c 20 65 76 65 6e 20 69 66  ccessful even if
18fa0 20 69 74 20 69 73 20 73 75 62 73 65 71 75 65 6e   it is subsequen
18fb0 74 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b 2e  tly rolled back.
18fc0 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63  .**.** This func
18fd0 74 69 6f 6e 20 69 73 20 61 63 63 65 73 73 69 62  tion is accessib
18fe0 6c 65 20 74 6f 20 53 51 4c 20 73 74 61 74 65 6d  le to SQL statem
18ff0 65 6e 74 73 20 76 69 61 20 74 68 65 0a 2a 2a 20  ents via the.** 
19000 5b 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77  [last_insert_row
19010 69 64 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f  id() SQL functio
19020 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73  n]..**.** If a s
19030 65 70 61 72 61 74 65 20 74 68 72 65 61 64 20 70  eparate thread p
19040 65 72 66 6f 72 6d 73 20 61 20 6e 65 77 20 5b 49  erforms a new [I
19050 4e 53 45 52 54 5d 20 6f 6e 20 74 68 65 20 73 61  NSERT] on the sa
19060 6d 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63  me.** database c
19070 6f 6e 6e 65 63 74 69 6f 6e 20 77 68 69 6c 65 20  onnection while 
19080 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73  the [sqlite3_las
19090 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29  t_insert_rowid()
190a0 5d 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73  ].** function is
190b0 20 72 75 6e 6e 69 6e 67 20 61 6e 64 20 74 68 75   running and thu
190c0 73 20 63 68 61 6e 67 65 73 20 74 68 65 20 6c 61  s changes the la
190d0 73 74 20 69 6e 73 65 72 74 20 5b 72 6f 77 69 64  st insert [rowid
190e0 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 76  ],.** then the v
190f0 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79  alue returned by
19100 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69   [sqlite3_last_i
19110 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 5d 20 69  nsert_rowid()] i
19120 73 0a 2a 2a 20 75 6e 70 72 65 64 69 63 74 61 62  s.** unpredictab
19130 6c 65 20 61 6e 64 20 6d 69 67 68 74 20 6e 6f 74  le and might not
19140 20 65 71 75 61 6c 20 65 69 74 68 65 72 20 74 68   equal either th
19150 65 20 6f 6c 64 20 6f 72 20 74 68 65 20 6e 65 77  e old or the new
19160 0a 2a 2a 20 6c 61 73 74 20 69 6e 73 65 72 74 20  .** last insert 
19170 5b 72 6f 77 69 64 5d 2e 0a 2a 2f 0a 73 71 6c 69  [rowid]..*/.sqli
19180 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65  te3_int64 sqlite
19190 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f  3_last_insert_ro
191a0 77 69 64 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a  wid(sqlite3*);..
191b0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
191c0 43 6f 75 6e 74 20 54 68 65 20 4e 75 6d 62 65 72  Count The Number
191d0 20 4f 66 20 52 6f 77 73 20 4d 6f 64 69 66 69 65   Of Rows Modifie
191e0 64 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  d.** METHOD: sql
191f0 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73  ite3.**.** ^This
19200 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e   function return
19210 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
19220 72 6f 77 73 20 6d 6f 64 69 66 69 65 64 2c 20 69  rows modified, i
19230 6e 73 65 72 74 65 64 20 6f 72 0a 2a 2a 20 64 65  nserted or.** de
19240 6c 65 74 65 64 20 62 79 20 74 68 65 20 6d 6f 73  leted by the mos
19250 74 20 72 65 63 65 6e 74 6c 79 20 63 6f 6d 70 6c  t recently compl
19260 65 74 65 64 20 49 4e 53 45 52 54 2c 20 55 50 44  eted INSERT, UPD
19270 41 54 45 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a  ATE or DELETE.**
19280 20 73 74 61 74 65 6d 65 6e 74 20 6f 6e 20 74 68   statement on th
19290 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
192a0 63 74 69 6f 6e 20 73 70 65 63 69 66 69 65 64 20  ction specified 
192b0 62 79 20 74 68 65 20 6f 6e 6c 79 20 70 61 72 61  by the only para
192c0 6d 65 74 65 72 2e 0a 2a 2a 20 5e 45 78 65 63 75  meter..** ^Execu
192d0 74 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 74  ting any other t
192e0 79 70 65 20 6f 66 20 53 51 4c 20 73 74 61 74 65  ype of SQL state
192f0 6d 65 6e 74 20 64 6f 65 73 20 6e 6f 74 20 6d 6f  ment does not mo
19300 64 69 66 79 20 74 68 65 20 76 61 6c 75 65 0a 2a  dify the value.*
19310 2a 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68  * returned by th
19320 69 73 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a  is function..**.
19330 2a 2a 20 5e 4f 6e 6c 79 20 63 68 61 6e 67 65 73  ** ^Only changes
19340 20 6d 61 64 65 20 64 69 72 65 63 74 6c 79 20 62   made directly b
19350 79 20 74 68 65 20 49 4e 53 45 52 54 2c 20 55 50  y the INSERT, UP
19360 44 41 54 45 20 6f 72 20 44 45 4c 45 54 45 20 73  DATE or DELETE s
19370 74 61 74 65 6d 65 6e 74 20 61 72 65 0a 2a 2a 20  tatement are.** 
19380 63 6f 6e 73 69 64 65 72 65 64 20 2d 20 61 75 78  considered - aux
19390 69 6c 69 61 72 79 20 63 68 61 6e 67 65 73 20 63  iliary changes c
193a0 61 75 73 65 64 20 62 79 20 5b 43 52 45 41 54 45  aused by [CREATE
193b0 20 54 52 49 47 47 45 52 20 7c 20 74 72 69 67 67   TRIGGER | trigg
193c0 65 72 73 5d 2c 20 0a 2a 2a 20 5b 66 6f 72 65 69  ers], .** [forei
193d0 67 6e 20 6b 65 79 20 61 63 74 69 6f 6e 73 5d 20  gn key actions] 
193e0 6f 72 20 5b 52 45 50 4c 41 43 45 5d 20 63 6f 6e  or [REPLACE] con
193f0 73 74 72 61 69 6e 74 20 72 65 73 6f 6c 75 74 69  straint resoluti
19400 6f 6e 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74  on are not count
19410 65 64 2e 0a 2a 2a 20 0a 2a 2a 20 43 68 61 6e 67  ed..** .** Chang
19420 65 73 20 74 6f 20 61 20 76 69 65 77 20 74 68 61  es to a view tha
19430 74 20 61 72 65 20 69 6e 74 65 72 63 65 70 74 65  t are intercepte
19440 64 20 62 79 20 0a 2a 2a 20 5b 49 4e 53 54 45 41  d by .** [INSTEA
19450 44 20 4f 46 20 74 72 69 67 67 65 72 20 7c 20 49  D OF trigger | I
19460 4e 53 54 45 41 44 20 4f 46 20 74 72 69 67 67 65  NSTEAD OF trigge
19470 72 73 5d 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e  rs] are not coun
19480 74 65 64 2e 20 5e 54 68 65 20 76 61 6c 75 65 20  ted. ^The value 
19490 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 79 20  .** returned by 
194a0 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28  sqlite3_changes(
194b0 29 20 69 6d 6d 65 64 69 61 74 65 6c 79 20 61 66  ) immediately af
194c0 74 65 72 20 61 6e 20 49 4e 53 45 52 54 2c 20 55  ter an INSERT, U
194d0 50 44 41 54 45 20 6f 72 20 0a 2a 2a 20 44 45 4c  PDATE or .** DEL
194e0 45 54 45 20 73 74 61 74 65 6d 65 6e 74 20 72 75  ETE statement ru
194f0 6e 20 6f 6e 20 61 20 76 69 65 77 20 69 73 20 61  n on a view is a
19500 6c 77 61 79 73 20 7a 65 72 6f 2e 20 4f 6e 6c 79  lways zero. Only
19510 20 63 68 61 6e 67 65 73 20 6d 61 64 65 20 74 6f   changes made to
19520 20 72 65 61 6c 20 0a 2a 2a 20 74 61 62 6c 65 73   real .** tables
19530 20 61 72 65 20 63 6f 75 6e 74 65 64 2e 0a 2a 2a   are counted..**
19540 0a 2a 2a 20 54 68 69 6e 67 73 20 61 72 65 20 6d  .** Things are m
19550 6f 72 65 20 63 6f 6d 70 6c 69 63 61 74 65 64 20  ore complicated 
19560 69 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63  if the sqlite3_c
19570 68 61 6e 67 65 73 28 29 20 66 75 6e 63 74 69 6f  hanges() functio
19580 6e 20 69 73 0a 2a 2a 20 65 78 65 63 75 74 65 64  n is.** executed
19590 20 77 68 69 6c 65 20 61 20 74 72 69 67 67 65 72   while a trigger
195a0 20 70 72 6f 67 72 61 6d 20 69 73 20 72 75 6e 6e   program is runn
195b0 69 6e 67 2e 20 54 68 69 73 20 6d 61 79 20 68 61  ing. This may ha
195c0 70 70 65 6e 20 69 66 20 74 68 65 0a 2a 2a 20 70  ppen if the.** p
195d0 72 6f 67 72 61 6d 20 75 73 65 73 20 74 68 65 20  rogram uses the 
195e0 5b 63 68 61 6e 67 65 73 28 29 20 53 51 4c 20 66  [changes() SQL f
195f0 75 6e 63 74 69 6f 6e 5d 2c 20 6f 72 20 69 66 20  unction], or if 
19600 73 6f 6d 65 20 6f 74 68 65 72 20 63 61 6c 6c 62  some other callb
19610 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  ack.** function 
19620 69 6e 76 6f 6b 65 73 20 73 71 6c 69 74 65 33 5f  invokes sqlite3_
19630 63 68 61 6e 67 65 73 28 29 20 64 69 72 65 63 74  changes() direct
19640 6c 79 2e 20 45 73 73 65 6e 74 69 61 6c 6c 79 3a  ly. Essentially:
19650 0a 2a 2a 20 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  .** .** <ul>.** 
19660 20 20 3c 6c 69 3e 20 5e 28 42 65 66 6f 72 65 20    <li> ^(Before 
19670 65 6e 74 65 72 69 6e 67 20 61 20 74 72 69 67 67  entering a trigg
19680 65 72 20 70 72 6f 67 72 61 6d 20 74 68 65 20 76  er program the v
19690 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79  alue returned by
196a0 0a 2a 2a 20 20 20 20 20 20 20 20 73 71 6c 69 74  .**        sqlit
196b0 65 33 5f 63 68 61 6e 67 65 73 28 29 20 66 75 6e  e3_changes() fun
196c0 63 74 69 6f 6e 20 69 73 20 73 61 76 65 64 2e 20  ction is saved. 
196d0 41 66 74 65 72 20 74 68 65 20 74 72 69 67 67 65  After the trigge
196e0 72 20 70 72 6f 67 72 61 6d 20 0a 2a 2a 20 20 20  r program .**   
196f0 20 20 20 20 20 68 61 73 20 66 69 6e 69 73 68 65       has finishe
19700 64 2c 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20  d, the original 
19710 76 61 6c 75 65 20 69 73 20 72 65 73 74 6f 72 65  value is restore
19720 64 2e 29 5e 0a 2a 2a 20 0a 2a 2a 20 20 20 3c 6c  d.)^.** .**   <l
19730 69 3e 20 5e 28 57 69 74 68 69 6e 20 61 20 74 72  i> ^(Within a tr
19740 69 67 67 65 72 20 70 72 6f 67 72 61 6d 20 65 61  igger program ea
19750 63 68 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54  ch INSERT, UPDAT
19760 45 20 61 6e 64 20 44 45 4c 45 54 45 20 0a 2a 2a  E and DELETE .**
19770 20 20 20 20 20 20 20 20 73 74 61 74 65 6d 65 6e          statemen
19780 74 20 73 65 74 73 20 74 68 65 20 76 61 6c 75 65  t sets the value
19790 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c   returned by sql
197a0 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20 0a  ite3_changes() .
197b0 2a 2a 20 20 20 20 20 20 20 20 75 70 6f 6e 20 63  **        upon c
197c0 6f 6d 70 6c 65 74 69 6f 6e 20 61 73 20 6e 6f 72  ompletion as nor
197d0 6d 61 6c 2e 20 4f 66 20 63 6f 75 72 73 65 2c 20  mal. Of course, 
197e0 74 68 69 73 20 76 61 6c 75 65 20 77 69 6c 6c 20  this value will 
197f0 6e 6f 74 20 69 6e 63 6c 75 64 65 20 0a 2a 2a 20  not include .** 
19800 20 20 20 20 20 20 20 61 6e 79 20 63 68 61 6e 67         any chang
19810 65 73 20 70 65 72 66 6f 72 6d 65 64 20 62 79 20  es performed by 
19820 73 75 62 2d 74 72 69 67 67 65 72 73 2c 20 61 73  sub-triggers, as
19830 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 68 61   the sqlite3_cha
19840 6e 67 65 73 28 29 20 0a 2a 2a 20 20 20 20 20 20  nges() .**      
19850 20 20 76 61 6c 75 65 20 77 69 6c 6c 20 62 65 20    value will be 
19860 73 61 76 65 64 20 61 6e 64 20 72 65 73 74 6f 72  saved and restor
19870 65 64 20 61 66 74 65 72 20 65 61 63 68 20 73 75  ed after each su
19880 62 2d 74 72 69 67 67 65 72 20 68 61 73 20 72 75  b-trigger has ru
19890 6e 2e 29 5e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a  n.)^.** </ul>.**
198a0 20 0a 2a 2a 20 5e 54 68 69 73 20 6d 65 61 6e 73   .** ^This means
198b0 20 74 68 61 74 20 69 66 20 74 68 65 20 63 68 61   that if the cha
198c0 6e 67 65 73 28 29 20 53 51 4c 20 66 75 6e 63 74  nges() SQL funct
198d0 69 6f 6e 20 28 6f 72 20 73 69 6d 69 6c 61 72 29  ion (or similar)
198e0 20 69 73 20 75 73 65 64 0a 2a 2a 20 62 79 20 74   is used.** by t
198f0 68 65 20 66 69 72 73 74 20 49 4e 53 45 52 54 2c  he first INSERT,
19900 20 55 50 44 41 54 45 20 6f 72 20 44 45 4c 45 54   UPDATE or DELET
19910 45 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68  E statement with
19920 69 6e 20 61 20 74 72 69 67 67 65 72 2c 20 69 74  in a trigger, it
19930 20 0a 2a 2a 20 72 65 74 75 72 6e 73 20 74 68 65   .** returns the
19940 20 76 61 6c 75 65 20 61 73 20 73 65 74 20 77 68   value as set wh
19950 65 6e 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 73  en the calling s
19960 74 61 74 65 6d 65 6e 74 20 62 65 67 61 6e 20 65  tatement began e
19970 78 65 63 75 74 69 6e 67 2e 0a 2a 2a 20 5e 49 66  xecuting..** ^If
19980 20 69 74 20 69 73 20 75 73 65 64 20 62 79 20 74   it is used by t
19990 68 65 20 73 65 63 6f 6e 64 20 6f 72 20 73 75 62  he second or sub
199a0 73 65 71 75 65 6e 74 20 73 75 63 68 20 73 74 61  sequent such sta
199b0 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 61 20  tement within a 
199c0 74 72 69 67 67 65 72 20 0a 2a 2a 20 70 72 6f 67  trigger .** prog
199d0 72 61 6d 2c 20 74 68 65 20 76 61 6c 75 65 20 72  ram, the value r
199e0 65 74 75 72 6e 65 64 20 72 65 66 6c 65 63 74 73  eturned reflects
199f0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 72   the number of r
19a00 6f 77 73 20 6d 6f 64 69 66 69 65 64 20 62 79 20  ows modified by 
19a10 74 68 65 20 0a 2a 2a 20 70 72 65 76 69 6f 75 73  the .** previous
19a20 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 20   INSERT, UPDATE 
19a30 6f 72 20 44 45 4c 45 54 45 20 73 74 61 74 65 6d  or DELETE statem
19a40 65 6e 74 20 77 69 74 68 69 6e 20 74 68 65 20 73  ent within the s
19a50 61 6d 65 20 74 72 69 67 67 65 72 2e 0a 2a 2a 0a  ame trigger..**.
19a60 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74 68 65 20  ** See also the 
19a70 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63  [sqlite3_total_c
19a80 68 61 6e 67 65 73 28 29 5d 20 69 6e 74 65 72 66  hanges()] interf
19a90 61 63 65 2c 20 74 68 65 0a 2a 2a 20 5b 63 6f 75  ace, the.** [cou
19aa0 6e 74 5f 63 68 61 6e 67 65 73 20 70 72 61 67 6d  nt_changes pragm
19ab0 61 5d 2c 20 61 6e 64 20 74 68 65 20 5b 63 68 61  a], and the [cha
19ac0 6e 67 65 73 28 29 20 53 51 4c 20 66 75 6e 63 74  nges() SQL funct
19ad0 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61  ion]..**.** If a
19ae0 20 73 65 70 61 72 61 74 65 20 74 68 72 65 61 64   separate thread
19af0 20 6d 61 6b 65 73 20 63 68 61 6e 67 65 73 20 6f   makes changes o
19b00 6e 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62  n the same datab
19b10 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a  ase connection.*
19b20 2a 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 65 33  * while [sqlite3
19b30 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 73 20 72  _changes()] is r
19b40 75 6e 6e 69 6e 67 20 74 68 65 6e 20 74 68 65 20  unning then the 
19b50 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 0a 2a  value returned.*
19b60 2a 20 69 73 20 75 6e 70 72 65 64 69 63 74 61 62  * is unpredictab
19b70 6c 65 20 61 6e 64 20 6e 6f 74 20 6d 65 61 6e 69  le and not meani
19b80 6e 67 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71  ngful..*/.int sq
19b90 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 73 71  lite3_changes(sq
19ba0 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  lite3*);../*.** 
19bb0 43 41 50 49 33 52 45 46 3a 20 54 6f 74 61 6c 20  CAPI3REF: Total 
19bc0 4e 75 6d 62 65 72 20 4f 66 20 52 6f 77 73 20 4d  Number Of Rows M
19bd0 6f 64 69 66 69 65 64 0a 2a 2a 20 4d 45 54 48 4f  odified.** METHO
19be0 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a  D: sqlite3.**.**
19bf0 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20   ^This function 
19c00 72 65 74 75 72 6e 73 20 74 68 65 20 74 6f 74 61  returns the tota
19c10 6c 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73  l number of rows
19c20 20 69 6e 73 65 72 74 65 64 2c 20 6d 6f 64 69 66   inserted, modif
19c30 69 65 64 20 6f 72 0a 2a 2a 20 64 65 6c 65 74 65  ied or.** delete
19c40 64 20 62 79 20 61 6c 6c 20 5b 49 4e 53 45 52 54  d by all [INSERT
19c50 5d 2c 20 5b 55 50 44 41 54 45 5d 20 6f 72 20 5b  ], [UPDATE] or [
19c60 44 45 4c 45 54 45 5d 20 73 74 61 74 65 6d 65 6e  DELETE] statemen
19c70 74 73 20 63 6f 6d 70 6c 65 74 65 64 0a 2a 2a 20  ts completed.** 
19c80 73 69 6e 63 65 20 74 68 65 20 64 61 74 61 62 61  since the databa
19c90 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 77 61  se connection wa
19ca0 73 20 6f 70 65 6e 65 64 2c 20 69 6e 63 6c 75 64  s opened, includ
19cb0 69 6e 67 20 74 68 6f 73 65 20 65 78 65 63 75 74  ing those execut
19cc0 65 64 20 61 73 0a 2a 2a 20 70 61 72 74 20 6f 66  ed as.** part of
19cd0 20 74 72 69 67 67 65 72 20 70 72 6f 67 72 61 6d   trigger program
19ce0 73 2e 20 5e 45 78 65 63 75 74 69 6e 67 20 61 6e  s. ^Executing an
19cf0 79 20 6f 74 68 65 72 20 74 79 70 65 20 6f 66 20  y other type of 
19d00 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a  SQL statement.**
19d10 20 64 6f 65 73 20 6e 6f 74 20 61 66 66 65 63 74   does not affect
19d20 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72   the value retur
19d30 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 74  ned by sqlite3_t
19d40 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 2e 0a  otal_changes()..
19d50 2a 2a 20 0a 2a 2a 20 5e 43 68 61 6e 67 65 73 20  ** .** ^Changes 
19d60 6d 61 64 65 20 61 73 20 70 61 72 74 20 6f 66 20  made as part of 
19d70 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20 61 63 74  [foreign key act
19d80 69 6f 6e 73 5d 20 61 72 65 20 69 6e 63 6c 75 64  ions] are includ
19d90 65 64 20 69 6e 20 74 68 65 0a 2a 2a 20 63 6f 75  ed in the.** cou
19da0 6e 74 2c 20 62 75 74 20 74 68 6f 73 65 20 6d 61  nt, but those ma
19db0 64 65 20 61 73 20 70 61 72 74 20 6f 66 20 52 45  de as part of RE
19dc0 50 4c 41 43 45 20 63 6f 6e 73 74 72 61 69 6e 74  PLACE constraint
19dd0 20 72 65 73 6f 6c 75 74 69 6f 6e 20 61 72 65 0a   resolution are.
19de0 2a 2a 20 6e 6f 74 2e 20 5e 43 68 61 6e 67 65 73  ** not. ^Changes
19df0 20 74 6f 20 61 20 76 69 65 77 20 74 68 61 74 20   to a view that 
19e00 61 72 65 20 69 6e 74 65 72 63 65 70 74 65 64 20  are intercepted 
19e10 62 79 20 49 4e 53 54 45 41 44 20 4f 46 20 74 72  by INSTEAD OF tr
19e20 69 67 67 65 72 73 20 0a 2a 2a 20 61 72 65 20 6e  iggers .** are n
19e30 6f 74 20 63 6f 75 6e 74 65 64 2e 0a 2a 2a 20 0a  ot counted..** .
19e40 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74 68 65 20  ** See also the 
19e50 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73  [sqlite3_changes
19e60 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2c 20 74  ()] interface, t
19e70 68 65 0a 2a 2a 20 5b 63 6f 75 6e 74 5f 63 68 61  he.** [count_cha
19e80 6e 67 65 73 20 70 72 61 67 6d 61 5d 2c 20 61 6e  nges pragma], an
19e90 64 20 74 68 65 20 5b 74 6f 74 61 6c 5f 63 68 61  d the [total_cha
19ea0 6e 67 65 73 28 29 20 53 51 4c 20 66 75 6e 63 74  nges() SQL funct
19eb0 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61  ion]..**.** If a
19ec0 20 73 65 70 61 72 61 74 65 20 74 68 72 65 61 64   separate thread
19ed0 20 6d 61 6b 65 73 20 63 68 61 6e 67 65 73 20 6f   makes changes o
19ee0 6e 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62  n the same datab
19ef0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a  ase connection.*
19f00 2a 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 65 33  * while [sqlite3
19f10 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29  _total_changes()
19f20 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65  ] is running the
19f30 6e 20 74 68 65 20 76 61 6c 75 65 0a 2a 2a 20 72  n the value.** r
19f40 65 74 75 72 6e 65 64 20 69 73 20 75 6e 70 72 65  eturned is unpre
19f50 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6e 6f 74  dictable and not
19f60 20 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a   meaningful..*/.
19f70 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 6f 74 61  int sqlite3_tota
19f80 6c 5f 63 68 61 6e 67 65 73 28 73 71 6c 69 74 65  l_changes(sqlite
19f90 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  3*);../*.** CAPI
19fa0 33 52 45 46 3a 20 49 6e 74 65 72 72 75 70 74 20  3REF: Interrupt 
19fb0 41 20 4c 6f 6e 67 2d 52 75 6e 6e 69 6e 67 20 51  A Long-Running Q
19fc0 75 65 72 79 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  uery.** METHOD: 
19fd0 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54  sqlite3.**.** ^T
19fe0 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 63 61 75  his function cau
19ff0 73 65 73 20 61 6e 79 20 70 65 6e 64 69 6e 67 20  ses any pending 
1a000 64 61 74 61 62 61 73 65 20 6f 70 65 72 61 74 69  database operati
1a010 6f 6e 20 74 6f 20 61 62 6f 72 74 20 61 6e 64 0a  on to abort and.
1a020 2a 2a 20 72 65 74 75 72 6e 20 61 74 20 69 74 73  ** return at its
1a030 20 65 61 72 6c 69 65 73 74 20 6f 70 70 6f 72 74   earliest opport
1a040 75 6e 69 74 79 2e 20 54 68 69 73 20 72 6f 75 74  unity. This rout
1a050 69 6e 65 20 69 73 20 74 79 70 69 63 61 6c 6c 79  ine is typically
1a060 0a 2a 2a 20 63 61 6c 6c 65 64 20 69 6e 20 72 65  .** called in re
1a070 73 70 6f 6e 73 65 20 74 6f 20 61 20 75 73 65 72  sponse to a user
1a080 20 61 63 74 69 6f 6e 20 73 75 63 68 20 61 73 20   action such as 
1a090 70 72 65 73 73 69 6e 67 20 22 43 61 6e 63 65 6c  pressing "Cancel
1a0a0 22 0a 2a 2a 20 6f 72 20 43 74 72 6c 2d 43 20 77  ".** or Ctrl-C w
1a0b0 68 65 72 65 20 74 68 65 20 75 73 65 72 20 77 61  here the user wa
1a0c0 6e 74 73 20 61 20 6c 6f 6e 67 20 71 75 65 72 79  nts a long query
1a0d0 20 6f 70 65 72 61 74 69 6f 6e 20 74 6f 20 68 61   operation to ha
1a0e0 6c 74 0a 2a 2a 20 69 6d 6d 65 64 69 61 74 65 6c  lt.** immediatel
1a0f0 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74 20 69 73 20  y..**.** ^It is 
1a100 73 61 66 65 20 74 6f 20 63 61 6c 6c 20 74 68 69  safe to call thi
1a110 73 20 72 6f 75 74 69 6e 65 20 66 72 6f 6d 20 61  s routine from a
1a120 20 74 68 72 65 61 64 20 64 69 66 66 65 72 65 6e   thread differen
1a130 74 20 66 72 6f 6d 20 74 68 65 0a 2a 2a 20 74 68  t from the.** th
1a140 72 65 61 64 20 74 68 61 74 20 69 73 20 63 75 72  read that is cur
1a150 72 65 6e 74 6c 79 20 72 75 6e 6e 69 6e 67 20 74  rently running t
1a160 68 65 20 64 61 74 61 62 61 73 65 20 6f 70 65 72  he database oper
1a170 61 74 69 6f 6e 2e 20 20 42 75 74 20 69 74 0a 2a  ation.  But it.*
1a180 2a 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f  * is not safe to
1a190 20 63 61 6c 6c 20 74 68 69 73 20 72 6f 75 74 69   call this routi
1a1a0 6e 65 20 77 69 74 68 20 61 20 5b 64 61 74 61 62  ne with a [datab
1a1b0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
1a1c0 74 68 61 74 0a 2a 2a 20 69 73 20 63 6c 6f 73 65  that.** is close
1a1d0 64 20 6f 72 20 6d 69 67 68 74 20 63 6c 6f 73 65  d or might close
1a1e0 20 62 65 66 6f 72 65 20 73 71 6c 69 74 65 33 5f   before sqlite3_
1a1f0 69 6e 74 65 72 72 75 70 74 28 29 20 72 65 74 75  interrupt() retu
1a200 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61  rns..**.** ^If a
1a210 6e 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20  n SQL operation 
1a220 69 73 20 76 65 72 79 20 6e 65 61 72 6c 79 20 66  is very nearly f
1a230 69 6e 69 73 68 65 64 20 61 74 20 74 68 65 20 74  inished at the t
1a240 69 6d 65 20 77 68 65 6e 0a 2a 2a 20 73 71 6c 69  ime when.** sqli
1a250 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20  te3_interrupt() 
1a260 69 73 20 63 61 6c 6c 65 64 2c 20 74 68 65 6e 20  is called, then 
1a270 69 74 20 6d 69 67 68 74 20 6e 6f 74 20 68 61 76  it might not hav
1a280 65 20 61 6e 20 6f 70 70 6f 72 74 75 6e 69 74 79  e an opportunity
1a290 0a 2a 2a 20 74 6f 20 62 65 20 69 6e 74 65 72 72  .** to be interr
1a2a0 75 70 74 65 64 20 61 6e 64 20 6d 69 67 68 74 20  upted and might 
1a2b0 63 6f 6e 74 69 6e 75 65 20 74 6f 20 63 6f 6d 70  continue to comp
1a2c0 6c 65 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 41  letion..**.** ^A
1a2d0 6e 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20  n SQL operation 
1a2e0 74 68 61 74 20 69 73 20 69 6e 74 65 72 72 75 70  that is interrup
1a2f0 74 65 64 20 77 69 6c 6c 20 72 65 74 75 72 6e 20  ted will return 
1a300 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50  [SQLITE_INTERRUP
1a310 54 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 69  T]..** ^If the i
1a320 6e 74 65 72 72 75 70 74 65 64 20 53 51 4c 20 6f  nterrupted SQL o
1a330 70 65 72 61 74 69 6f 6e 20 69 73 20 61 6e 20 49  peration is an I
1a340 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f  NSERT, UPDATE, o
1a350 72 20 44 45 4c 45 54 45 0a 2a 2a 20 74 68 61 74  r DELETE.** that
1a360 20 69 73 20 69 6e 73 69 64 65 20 61 6e 20 65 78   is inside an ex
1a370 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74 69  plicit transacti
1a380 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 65 6e 74  on, then the ent
1a390 69 72 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 0a  ire transaction.
1a3a0 2a 2a 20 77 69 6c 6c 20 62 65 20 72 6f 6c 6c 65  ** will be rolle
1a3b0 64 20 62 61 63 6b 20 61 75 74 6f 6d 61 74 69 63  d back automatic
1a3c0 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ally..**.** ^The
1a3d0 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75   sqlite3_interru
1a3e0 70 74 28 44 29 20 63 61 6c 6c 20 69 73 20 69 6e  pt(D) call is in
1a3f0 20 65 66 66 65 63 74 20 75 6e 74 69 6c 20 61 6c   effect until al
1a400 6c 20 63 75 72 72 65 6e 74 6c 79 20 72 75 6e 6e  l currently runn
1a410 69 6e 67 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65  ing.** SQL state
1a420 6d 65 6e 74 73 20 6f 6e 20 5b 64 61 74 61 62 61  ments on [databa
1a430 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44  se connection] D
1a440 20 63 6f 6d 70 6c 65 74 65 2e 20 20 5e 41 6e 79   complete.  ^Any
1a450 20 6e 65 77 20 53 51 4c 20 73 74 61 74 65 6d 65   new SQL stateme
1a460 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20  nts.** that are 
1a470 73 74 61 72 74 65 64 20 61 66 74 65 72 20 74 68  started after th
1a480 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72  e sqlite3_interr
1a490 75 70 74 28 29 20 63 61 6c 6c 20 61 6e 64 20 62  upt() call and b
1a4a0 65 66 6f 72 65 20 74 68 65 20 0a 2a 2a 20 72 75  efore the .** ru
1a4b0 6e 6e 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 73  nning statements
1a4c0 20 72 65 61 63 68 65 73 20 7a 65 72 6f 20 61 72   reaches zero ar
1a4d0 65 20 69 6e 74 65 72 72 75 70 74 65 64 20 61 73  e interrupted as
1a4e0 20 69 66 20 74 68 65 79 20 68 61 64 20 62 65 65   if they had bee
1a4f0 6e 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20 70 72 69  n.** running pri
1a500 6f 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65  or to the sqlite
1a510 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 63 61  3_interrupt() ca
1a520 6c 6c 2e 20 20 5e 4e 65 77 20 53 51 4c 20 73 74  ll.  ^New SQL st
1a530 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74  atements.** that
1a540 20 61 72 65 20 73 74 61 72 74 65 64 20 61 66 74   are started aft
1a550 65 72 20 74 68 65 20 72 75 6e 6e 69 6e 67 20 73  er the running s
1a560 74 61 74 65 6d 65 6e 74 20 63 6f 75 6e 74 20 72  tatement count r
1a570 65 61 63 68 65 73 20 7a 65 72 6f 20 61 72 65 0a  eaches zero are.
1a580 2a 2a 20 6e 6f 74 20 65 66 66 65 63 74 65 64 20  ** not effected 
1a590 62 79 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69  by the sqlite3_i
1a5a0 6e 74 65 72 72 75 70 74 28 29 2e 0a 2a 2a 20 5e  nterrupt()..** ^
1a5b0 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  A call to sqlite
1a5c0 33 5f 69 6e 74 65 72 72 75 70 74 28 44 29 20 74  3_interrupt(D) t
1a5d0 68 61 74 20 6f 63 63 75 72 73 20 77 68 65 6e 20  hat occurs when 
1a5e0 74 68 65 72 65 20 61 72 65 20 6e 6f 20 72 75 6e  there are no run
1a5f0 6e 69 6e 67 0a 2a 2a 20 53 51 4c 20 73 74 61 74  ning.** SQL stat
1a600 65 6d 65 6e 74 73 20 69 73 20 61 20 6e 6f 2d 6f  ements is a no-o
1a610 70 20 61 6e 64 20 68 61 73 20 6e 6f 20 65 66 66  p and has no eff
1a620 65 63 74 20 6f 6e 20 53 51 4c 20 73 74 61 74 65  ect on SQL state
1a630 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61 72  ments.** that ar
1a640 65 20 73 74 61 72 74 65 64 20 61 66 74 65 72 20  e started after 
1a650 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65  the sqlite3_inte
1a660 72 72 75 70 74 28 29 20 63 61 6c 6c 20 72 65 74  rrupt() call ret
1a670 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74  urns..**.** If t
1a680 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
1a690 65 63 74 69 6f 6e 20 63 6c 6f 73 65 73 20 77 68  ection closes wh
1a6a0 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74  ile [sqlite3_int
1a6b0 65 72 72 75 70 74 28 29 5d 0a 2a 2a 20 69 73 20  errupt()].** is 
1a6c0 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20 62 61 64  running then bad
1a6d0 20 74 68 69 6e 67 73 20 77 69 6c 6c 20 6c 69 6b   things will lik
1a6e0 65 6c 79 20 68 61 70 70 65 6e 2e 0a 2a 2f 0a 76  ely happen..*/.v
1a6f0 6f 69 64 20 73 71 6c 69 74 65 33 5f 69 6e 74 65  oid sqlite3_inte
1a700 72 72 75 70 74 28 73 71 6c 69 74 65 33 2a 29 3b  rrupt(sqlite3*);
1a710 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1a720 3a 20 44 65 74 65 72 6d 69 6e 65 20 49 66 20 41  : Determine If A
1a730 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20  n SQL Statement 
1a740 49 73 20 43 6f 6d 70 6c 65 74 65 0a 2a 2a 0a 2a  Is Complete.**.*
1a750 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
1a760 20 61 72 65 20 75 73 65 66 75 6c 20 64 75 72 69   are useful duri
1a770 6e 67 20 63 6f 6d 6d 61 6e 64 2d 6c 69 6e 65 20  ng command-line 
1a780 69 6e 70 75 74 20 74 6f 20 64 65 74 65 72 6d 69  input to determi
1a790 6e 65 20 69 66 20 74 68 65 0a 2a 2a 20 63 75 72  ne if the.** cur
1a7a0 72 65 6e 74 6c 79 20 65 6e 74 65 72 65 64 20 74  rently entered t
1a7b0 65 78 74 20 73 65 65 6d 73 20 74 6f 20 66 6f 72  ext seems to for
1a7c0 6d 20 61 20 63 6f 6d 70 6c 65 74 65 20 53 51 4c  m a complete SQL
1a7d0 20 73 74 61 74 65 6d 65 6e 74 20 6f 72 0a 2a 2a   statement or.**
1a7e0 20 69 66 20 61 64 64 69 74 69 6f 6e 61 6c 20 69   if additional i
1a7f0 6e 70 75 74 20 69 73 20 6e 65 65 64 65 64 20 62  nput is needed b
1a800 65 66 6f 72 65 20 73 65 6e 64 69 6e 67 20 74 68  efore sending th
1a810 65 20 74 65 78 74 20 69 6e 74 6f 0a 2a 2a 20 53  e text into.** S
1a820 51 4c 69 74 65 20 66 6f 72 20 70 61 72 73 69 6e  QLite for parsin
1a830 67 2e 20 20 5e 54 68 65 73 65 20 72 6f 75 74 69  g.  ^These routi
1a840 6e 65 73 20 72 65 74 75 72 6e 20 31 20 69 66 20  nes return 1 if 
1a850 74 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67  the input string
1a860 0a 2a 2a 20 61 70 70 65 61 72 73 20 74 6f 20 62  .** appears to b
1a870 65 20 61 20 63 6f 6d 70 6c 65 74 65 20 53 51 4c  e a complete SQL
1a880 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 41 20   statement.  ^A 
1a890 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6a 75 64  statement is jud
1a8a0 67 65 64 20 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d  ged to be.** com
1a8b0 70 6c 65 74 65 20 69 66 20 69 74 20 65 6e 64 73  plete if it ends
1a8c0 20 77 69 74 68 20 61 20 73 65 6d 69 63 6f 6c 6f   with a semicolo
1a8d0 6e 20 74 6f 6b 65 6e 20 61 6e 64 20 69 73 20 6e  n token and is n
1a8e0 6f 74 20 61 20 70 72 65 66 69 78 20 6f 66 20 61  ot a prefix of a
1a8f0 0a 2a 2a 20 77 65 6c 6c 2d 66 6f 72 6d 65 64 20  .** well-formed 
1a900 43 52 45 41 54 45 20 54 52 49 47 47 45 52 20 73  CREATE TRIGGER s
1a910 74 61 74 65 6d 65 6e 74 2e 20 20 5e 53 65 6d 69  tatement.  ^Semi
1a920 63 6f 6c 6f 6e 73 20 74 68 61 74 20 61 72 65 20  colons that are 
1a930 65 6d 62 65 64 64 65 64 20 77 69 74 68 69 6e 0a  embedded within.
1a940 2a 2a 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61  ** string litera
1a950 6c 73 20 6f 72 20 71 75 6f 74 65 64 20 69 64 65  ls or quoted ide
1a960 6e 74 69 66 69 65 72 20 6e 61 6d 65 73 20 6f 72  ntifier names or
1a970 20 63 6f 6d 6d 65 6e 74 73 20 61 72 65 20 6e 6f   comments are no
1a980 74 0a 2a 2a 20 69 6e 64 65 70 65 6e 64 65 6e 74  t.** independent
1a990 20 74 6f 6b 65 6e 73 20 28 74 68 65 79 20 61 72   tokens (they ar
1a9a0 65 20 70 61 72 74 20 6f 66 20 74 68 65 20 74 6f  e part of the to
1a9b0 6b 65 6e 20 69 6e 20 77 68 69 63 68 20 74 68 65  ken in which the
1a9c0 79 20 61 72 65 0a 2a 2a 20 65 6d 62 65 64 64 65  y are.** embedde
1a9d0 64 29 20 61 6e 64 20 74 68 75 73 20 64 6f 20 6e  d) and thus do n
1a9e0 6f 74 20 63 6f 75 6e 74 20 61 73 20 61 20 73 74  ot count as a st
1a9f0 61 74 65 6d 65 6e 74 20 74 65 72 6d 69 6e 61 74  atement terminat
1aa00 6f 72 2e 20 20 5e 57 68 69 74 65 73 70 61 63 65  or.  ^Whitespace
1aa10 0a 2a 2a 20 61 6e 64 20 63 6f 6d 6d 65 6e 74 73  .** and comments
1aa20 20 74 68 61 74 20 66 6f 6c 6c 6f 77 20 74 68 65   that follow the
1aa30 20 66 69 6e 61 6c 20 73 65 6d 69 63 6f 6c 6f 6e   final semicolon
1aa40 20 61 72 65 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a   are ignored..**
1aa50 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69  .** ^These routi
1aa60 6e 65 73 20 72 65 74 75 72 6e 20 30 20 69 66 20  nes return 0 if 
1aa70 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73  the statement is
1aa80 20 69 6e 63 6f 6d 70 6c 65 74 65 2e 20 20 5e 49   incomplete.  ^I
1aa90 66 20 61 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c  f a.** memory al
1aaa0 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 73 2c 20  location fails, 
1aab0 74 68 65 6e 20 53 51 4c 49 54 45 5f 4e 4f 4d 45  then SQLITE_NOME
1aac0 4d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a  M is returned..*
1aad0 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74  *.** ^These rout
1aae0 69 6e 65 73 20 64 6f 20 6e 6f 74 20 70 61 72 73  ines do not pars
1aaf0 65 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  e the SQL statem
1ab00 65 6e 74 73 20 74 68 75 73 0a 2a 2a 20 77 69 6c  ents thus.** wil
1ab10 6c 20 6e 6f 74 20 64 65 74 65 63 74 20 73 79 6e  l not detect syn
1ab20 74 61 63 74 69 63 61 6c 6c 79 20 69 6e 63 6f 72  tactically incor
1ab30 72 65 63 74 20 53 51 4c 2e 0a 2a 2a 0a 2a 2a 20  rect SQL..**.** 
1ab40 5e 28 49 66 20 53 51 4c 69 74 65 20 68 61 73 20  ^(If SQLite has 
1ab50 6e 6f 74 20 62 65 65 6e 20 69 6e 69 74 69 61 6c  not been initial
1ab60 69 7a 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69  ized using [sqli
1ab70 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
1ab80 5d 20 70 72 69 6f 72 20 0a 2a 2a 20 74 6f 20 69  ] prior .** to i
1ab90 6e 76 6f 6b 69 6e 67 20 73 71 6c 69 74 65 33 5f  nvoking sqlite3_
1aba0 63 6f 6d 70 6c 65 74 65 31 36 28 29 20 74 68 65  complete16() the
1abb0 6e 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  n sqlite3_initia
1abc0 6c 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65  lize() is invoke
1abd0 64 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c  d.** automatical
1abe0 6c 79 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f  ly by sqlite3_co
1abf0 6d 70 6c 65 74 65 31 36 28 29 2e 20 20 49 66 20  mplete16().  If 
1ac00 74 68 61 74 20 69 6e 69 74 69 61 6c 69 7a 61 74  that initializat
1ac10 69 6f 6e 20 66 61 69 6c 73 2c 0a 2a 2a 20 74 68  ion fails,.** th
1ac20 65 6e 20 74 68 65 20 72 65 74 75 72 6e 20 76 61  en the return va
1ac30 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33  lue from sqlite3
1ac40 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 20 77 69  _complete16() wi
1ac50 6c 6c 20 62 65 20 6e 6f 6e 2d 7a 65 72 6f 0a 2a  ll be non-zero.*
1ac60 2a 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20  * regardless of 
1ac70 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74  whether or not t
1ac80 68 65 20 69 6e 70 75 74 20 53 51 4c 20 69 73 20  he input SQL is 
1ac90 63 6f 6d 70 6c 65 74 65 2e 29 5e 0a 2a 2a 0a 2a  complete.)^.**.*
1aca0 2a 20 54 68 65 20 69 6e 70 75 74 20 74 6f 20 5b  * The input to [
1acb0 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65  sqlite3_complete
1acc0 28 29 5d 20 6d 75 73 74 20 62 65 20 61 20 7a 65  ()] must be a ze
1acd0 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a  ro-terminated.**
1ace0 20 55 54 46 2d 38 20 73 74 72 69 6e 67 2e 0a 2a   UTF-8 string..*
1acf0 2a 0a 2a 2a 20 54 68 65 20 69 6e 70 75 74 20 74  *.** The input t
1ad00 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c  o [sqlite3_compl
1ad10 65 74 65 31 36 28 29 5d 20 6d 75 73 74 20 62 65  ete16()] must be
1ad20 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74   a zero-terminat
1ad30 65 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73 74 72  ed.** UTF-16 str
1ad40 69 6e 67 20 69 6e 20 6e 61 74 69 76 65 20 62 79  ing in native by
1ad50 74 65 20 6f 72 64 65 72 2e 0a 2a 2f 0a 69 6e 74  te order..*/.int
1ad60 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74   sqlite3_complet
1ad70 65 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  e(const char *sq
1ad80 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  l);.int sqlite3_
1ad90 63 6f 6d 70 6c 65 74 65 31 36 28 63 6f 6e 73 74  complete16(const
1ada0 20 76 6f 69 64 20 2a 73 71 6c 29 3b 0a 0a 2f 2a   void *sql);../*
1adb0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65  .** CAPI3REF: Re
1adc0 67 69 73 74 65 72 20 41 20 43 61 6c 6c 62 61 63  gister A Callbac
1add0 6b 20 54 6f 20 48 61 6e 64 6c 65 20 53 51 4c 49  k To Handle SQLI
1ade0 54 45 5f 42 55 53 59 20 45 72 72 6f 72 73 0a 2a  TE_BUSY Errors.*
1adf0 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 62 75 73  * KEYWORDS: {bus
1ae00 79 2d 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61  y-handler callba
1ae10 63 6b 7d 20 7b 62 75 73 79 20 68 61 6e 64 6c 65  ck} {busy handle
1ae20 72 7d 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  r}.** METHOD: sq
1ae30 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  lite3.**.** ^The
1ae40 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61   sqlite3_busy_ha
1ae50 6e 64 6c 65 72 28 44 2c 58 2c 50 29 20 72 6f 75  ndler(D,X,P) rou
1ae60 74 69 6e 65 20 73 65 74 73 20 61 20 63 61 6c 6c  tine sets a call
1ae70 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 58 0a  back function X.
1ae80 2a 2a 20 74 68 61 74 20 6d 69 67 68 74 20 62 65  ** that might be
1ae90 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 61 72   invoked with ar
1aea0 67 75 6d 65 6e 74 20 50 20 77 68 65 6e 65 76 65  gument P wheneve
1aeb0 72 0a 2a 2a 20 61 6e 20 61 74 74 65 6d 70 74 20  r.** an attempt 
1aec0 69 73 20 6d 61 64 65 20 74 6f 20 61 63 63 65 73  is made to acces
1aed0 73 20 61 20 64 61 74 61 62 61 73 65 20 74 61 62  s a database tab
1aee0 6c 65 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  le associated wi
1aef0 74 68 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20  th.** [database 
1af00 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 77 68  connection] D wh
1af10 65 6e 20 61 6e 6f 74 68 65 72 20 74 68 72 65 61  en another threa
1af20 64 0a 2a 2a 20 6f 72 20 70 72 6f 63 65 73 73 20  d.** or process 
1af30 68 61 73 20 74 68 65 20 74 61 62 6c 65 20 6c 6f  has the table lo
1af40 63 6b 65 64 2e 0a 2a 2a 20 54 68 65 20 73 71 6c  cked..** The sql
1af50 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65  ite3_busy_handle
1af60 72 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73  r() interface is
1af70 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65   used to impleme
1af80 6e 74 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  nt.** [sqlite3_b
1af90 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d 20 61  usy_timeout()] a
1afa0 6e 64 20 5b 50 52 41 47 4d 41 20 62 75 73 79 5f  nd [PRAGMA busy_
1afb0 74 69 6d 65 6f 75 74 5d 2e 0a 2a 2a 0a 2a 2a 20  timeout]..**.** 
1afc0 5e 49 66 20 74 68 65 20 62 75 73 79 20 63 61 6c  ^If the busy cal
1afd0 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c 2c 20 74  lback is NULL, t
1afe0 68 65 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  hen [SQLITE_BUSY
1aff0 5d 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64  ].** is returned
1b000 20 69 6d 6d 65 64 69 61 74 65 6c 79 20 75 70 6f   immediately upo
1b010 6e 20 65 6e 63 6f 75 6e 74 65 72 69 6e 67 20 74  n encountering t
1b020 68 65 20 6c 6f 63 6b 2e 20 20 5e 49 66 20 74 68  he lock.  ^If th
1b030 65 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 0a  e busy callback.
1b040 2a 2a 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20  ** is not NULL, 
1b050 74 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63  then the callbac
1b060 6b 20 6d 69 67 68 74 20 62 65 20 69 6e 76 6f 6b  k might be invok
1b070 65 64 20 77 69 74 68 20 74 77 6f 20 61 72 67 75  ed with two argu
1b080 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ments..**.** ^Th
1b090 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
1b0a0 20 74 6f 20 74 68 65 20 62 75 73 79 20 68 61 6e   to the busy han
1b0b0 64 6c 65 72 20 69 73 20 61 20 63 6f 70 79 20 6f  dler is a copy o
1b0c0 66 20 74 68 65 20 76 6f 69 64 2a 20 70 6f 69 6e  f the void* poin
1b0d0 74 65 72 20 77 68 69 63 68 0a 2a 2a 20 69 73 20  ter which.** is 
1b0e0 74 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65  the third argume
1b0f0 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 75  nt to sqlite3_bu
1b100 73 79 5f 68 61 6e 64 6c 65 72 28 29 2e 20 20 5e  sy_handler().  ^
1b110 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  The second argum
1b120 65 6e 74 20 74 6f 0a 2a 2a 20 74 68 65 20 62 75  ent to.** the bu
1b130 73 79 20 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62  sy handler callb
1b140 61 63 6b 20 69 73 20 74 68 65 20 6e 75 6d 62 65  ack is the numbe
1b150 72 20 6f 66 20 74 69 6d 65 73 20 74 68 61 74 20  r of times that 
1b160 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72  the busy handler
1b170 20 68 61 73 0a 2a 2a 20 62 65 65 6e 20 69 6e 76   has.** been inv
1b180 6f 6b 65 64 20 70 72 65 76 69 6f 75 73 6c 79 20  oked previously 
1b190 66 6f 72 20 74 68 65 20 73 61 6d 65 20 6c 6f 63  for the same loc
1b1a0 6b 69 6e 67 20 65 76 65 6e 74 2e 20 20 5e 49 66  king event.  ^If
1b1b0 20 74 68 65 0a 2a 2a 20 62 75 73 79 20 63 61 6c   the.** busy cal
1b1c0 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 30 2c  lback returns 0,
1b1d0 20 74 68 65 6e 20 6e 6f 20 61 64 64 69 74 69 6f   then no additio
1b1e0 6e 61 6c 20 61 74 74 65 6d 70 74 73 20 61 72 65  nal attempts are
1b1f0 20 6d 61 64 65 20 74 6f 0a 2a 2a 20 61 63 63 65   made to.** acce
1b200 73 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ss the database 
1b210 61 6e 64 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  and [SQLITE_BUSY
1b220 5d 20 69 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a  ] is returned.**
1b230 20 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74   to the applicat
1b240 69 6f 6e 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ion..** ^If the 
1b250 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73  callback returns
1b260 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20   non-zero, then 
1b270 61 6e 6f 74 68 65 72 20 61 74 74 65 6d 70 74 0a  another attempt.
1b280 2a 2a 20 69 73 20 6d 61 64 65 20 74 6f 20 61 63  ** is made to ac
1b290 63 65 73 73 20 74 68 65 20 64 61 74 61 62 61 73  cess the databas
1b2a0 65 20 61 6e 64 20 74 68 65 20 63 79 63 6c 65 20  e and the cycle 
1b2b0 72 65 70 65 61 74 73 2e 0a 2a 2a 0a 2a 2a 20 54  repeats..**.** T
1b2c0 68 65 20 70 72 65 73 65 6e 63 65 20 6f 66 20 61  he presence of a
1b2d0 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 64 6f   busy handler do
1b2e0 65 73 20 6e 6f 74 20 67 75 61 72 61 6e 74 65 65  es not guarantee
1b2f0 20 74 68 61 74 20 69 74 20 77 69 6c 6c 20 62 65   that it will be
1b300 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 77 68 65 6e   invoked.** when
1b310 20 74 68 65 72 65 20 69 73 20 6c 6f 63 6b 20 63   there is lock c
1b320 6f 6e 74 65 6e 74 69 6f 6e 2e 20 5e 49 66 20 53  ontention. ^If S
1b330 51 4c 69 74 65 20 64 65 74 65 72 6d 69 6e 65 73  QLite determines
1b340 20 74 68 61 74 20 69 6e 76 6f 6b 69 6e 67 20 74   that invoking t
1b350 68 65 20 62 75 73 79 0a 2a 2a 20 68 61 6e 64 6c  he busy.** handl
1b360 65 72 20 63 6f 75 6c 64 20 72 65 73 75 6c 74 20  er could result 
1b370 69 6e 20 61 20 64 65 61 64 6c 6f 63 6b 2c 20 69  in a deadlock, i
1b380 74 20 77 69 6c 6c 20 67 6f 20 61 68 65 61 64 20  t will go ahead 
1b390 61 6e 64 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  and return [SQLI
1b3a0 54 45 5f 42 55 53 59 5d 0a 2a 2a 20 74 6f 20 74  TE_BUSY].** to t
1b3b0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69  he application i
1b3c0 6e 73 74 65 61 64 20 6f 66 20 69 6e 76 6f 6b 69  nstead of invoki
1b3d0 6e 67 20 74 68 65 20 0a 2a 2a 20 62 75 73 79 20  ng the .** busy 
1b3e0 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 43 6f 6e 73  handler..** Cons
1b3f0 69 64 65 72 20 61 20 73 63 65 6e 61 72 69 6f 20  ider a scenario 
1b400 77 68 65 72 65 20 6f 6e 65 20 70 72 6f 63 65 73  where one proces
1b410 73 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 72  s is holding a r
1b420 65 61 64 20 6c 6f 63 6b 20 74 68 61 74 0a 2a 2a  ead lock that.**
1b430 20 69 74 20 69 73 20 74 72 79 69 6e 67 20 74 6f   it is trying to
1b440 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61 20 72 65   promote to a re
1b450 73 65 72 76 65 64 20 6c 6f 63 6b 20 61 6e 64 0a  served lock and.
1b460 2a 2a 20 61 20 73 65 63 6f 6e 64 20 70 72 6f 63  ** a second proc
1b470 65 73 73 20 69 73 20 68 6f 6c 64 69 6e 67 20 61  ess is holding a
1b480 20 72 65 73 65 72 76 65 64 20 6c 6f 63 6b 20 74   reserved lock t
1b490 68 61 74 20 69 74 20 69 73 20 74 72 79 69 6e 67  hat it is trying
1b4a0 0a 2a 2a 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74  .** to promote t
1b4b0 6f 20 61 6e 20 65 78 63 6c 75 73 69 76 65 20 6c  o an exclusive l
1b4c0 6f 63 6b 2e 20 20 54 68 65 20 66 69 72 73 74 20  ock.  The first 
1b4d0 70 72 6f 63 65 73 73 20 63 61 6e 6e 6f 74 20 70  process cannot p
1b4e0 72 6f 63 65 65 64 0a 2a 2a 20 62 65 63 61 75 73  roceed.** becaus
1b4f0 65 20 69 74 20 69 73 20 62 6c 6f 63 6b 65 64 20  e it is blocked 
1b500 62 79 20 74 68 65 20 73 65 63 6f 6e 64 20 61 6e  by the second an
1b510 64 20 74 68 65 20 73 65 63 6f 6e 64 20 70 72 6f  d the second pro
1b520 63 65 73 73 20 63 61 6e 6e 6f 74 0a 2a 2a 20 70  cess cannot.** p
1b530 72 6f 63 65 65 64 20 62 65 63 61 75 73 65 20 69  roceed because i
1b540 74 20 69 73 20 62 6c 6f 63 6b 65 64 20 62 79 20  t is blocked by 
1b550 74 68 65 20 66 69 72 73 74 2e 20 20 49 66 20 62  the first.  If b
1b560 6f 74 68 20 70 72 6f 63 65 73 73 65 73 0a 2a 2a  oth processes.**
1b570 20 69 6e 76 6f 6b 65 20 74 68 65 20 62 75 73 79   invoke the busy
1b580 20 68 61 6e 64 6c 65 72 73 2c 20 6e 65 69 74 68   handlers, neith
1b590 65 72 20 77 69 6c 6c 20 6d 61 6b 65 20 61 6e 79  er will make any
1b5a0 20 70 72 6f 67 72 65 73 73 2e 20 20 54 68 65 72   progress.  Ther
1b5b0 65 66 6f 72 65 2c 0a 2a 2a 20 53 51 4c 69 74 65  efore,.** SQLite
1b5c0 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
1b5d0 5f 42 55 53 59 5d 20 66 6f 72 20 74 68 65 20 66  _BUSY] for the f
1b5e0 69 72 73 74 20 70 72 6f 63 65 73 73 2c 20 68 6f  irst process, ho
1b5f0 70 69 6e 67 20 74 68 61 74 20 74 68 69 73 0a 2a  ping that this.*
1b600 2a 20 77 69 6c 6c 20 69 6e 64 75 63 65 20 74 68  * will induce th
1b610 65 20 66 69 72 73 74 20 70 72 6f 63 65 73 73 20  e first process 
1b620 74 6f 20 72 65 6c 65 61 73 65 20 69 74 73 20 72  to release its r
1b630 65 61 64 20 6c 6f 63 6b 20 61 6e 64 20 61 6c 6c  ead lock and all
1b640 6f 77 0a 2a 2a 20 74 68 65 20 73 65 63 6f 6e 64  ow.** the second
1b650 20 70 72 6f 63 65 73 73 20 74 6f 20 70 72 6f 63   process to proc
1b660 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  eed..**.** ^The 
1b670 64 65 66 61 75 6c 74 20 62 75 73 79 20 63 61 6c  default busy cal
1b680 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c 2e 0a 2a  lback is NULL..*
1b690 2a 0a 2a 2a 20 5e 28 54 68 65 72 65 20 63 61 6e  *.** ^(There can
1b6a0 20 6f 6e 6c 79 20 62 65 20 61 20 73 69 6e 67 6c   only be a singl
1b6b0 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 64  e busy handler d
1b6c0 65 66 69 6e 65 64 20 66 6f 72 20 65 61 63 68 0a  efined for each.
1b6d0 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ** [database con
1b6e0 6e 65 63 74 69 6f 6e 5d 2e 20 20 53 65 74 74 69  nection].  Setti
1b6f0 6e 67 20 61 20 6e 65 77 20 62 75 73 79 20 68 61  ng a new busy ha
1b700 6e 64 6c 65 72 20 63 6c 65 61 72 73 20 61 6e 79  ndler clears any
1b710 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 73  .** previously s
1b720 65 74 20 68 61 6e 64 6c 65 72 2e 29 5e 20 20 5e  et handler.)^  ^
1b730 4e 6f 74 65 20 74 68 61 74 20 63 61 6c 6c 69 6e  Note that callin
1b740 67 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f  g [sqlite3_busy_
1b750 74 69 6d 65 6f 75 74 28 29 5d 0a 2a 2a 20 6f 72  timeout()].** or
1b760 20 65 76 61 6c 75 61 74 69 6e 67 20 5b 50 52 41   evaluating [PRA
1b770 47 4d 41 20 62 75 73 79 5f 74 69 6d 65 6f 75 74  GMA busy_timeout
1b780 3d 4e 5d 20 77 69 6c 6c 20 63 68 61 6e 67 65 20  =N] will change 
1b790 74 68 65 0a 2a 2a 20 62 75 73 79 20 68 61 6e 64  the.** busy hand
1b7a0 6c 65 72 20 61 6e 64 20 74 68 75 73 20 63 6c 65  ler and thus cle
1b7b0 61 72 20 61 6e 79 20 70 72 65 76 69 6f 75 73 6c  ar any previousl
1b7c0 79 20 73 65 74 20 62 75 73 79 20 68 61 6e 64 6c  y set busy handl
1b7d0 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 62 75  er..**.** The bu
1b7e0 73 79 20 63 61 6c 6c 62 61 63 6b 20 73 68 6f 75  sy callback shou
1b7f0 6c 64 20 6e 6f 74 20 74 61 6b 65 20 61 6e 79 20  ld not take any 
1b800 61 63 74 69 6f 6e 73 20 77 68 69 63 68 20 6d 6f  actions which mo
1b810 64 69 66 79 20 74 68 65 0a 2a 2a 20 64 61 74 61  dify the.** data
1b820 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
1b830 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65  that invoked the
1b840 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 20 20   busy handler.  
1b850 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 0a  In other words,.
1b860 2a 2a 20 74 68 65 20 62 75 73 79 20 68 61 6e 64  ** the busy hand
1b870 6c 65 72 20 69 73 20 6e 6f 74 20 72 65 65 6e 74  ler is not reent
1b880 72 61 6e 74 2e 20 20 41 6e 79 20 73 75 63 68 20  rant.  Any such 
1b890 61 63 74 69 6f 6e 73 0a 2a 2a 20 72 65 73 75 6c  actions.** resul
1b8a0 74 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 62  t in undefined b
1b8b0 65 68 61 76 69 6f 72 2e 0a 2a 2a 20 0a 2a 2a 20  ehavior..** .** 
1b8c0 41 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 6d  A busy handler m
1b8d0 75 73 74 20 6e 6f 74 20 63 6c 6f 73 65 20 74 68  ust not close th
1b8e0 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
1b8f0 63 74 69 6f 6e 0a 2a 2a 20 6f 72 20 5b 70 72 65  ction.** or [pre
1b900 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
1b910 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68   that invoked th
1b920 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a  e busy handler..
1b930 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  */.int sqlite3_b
1b940 75 73 79 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69  usy_handler(sqli
1b950 74 65 33 2a 2c 69 6e 74 28 2a 29 28 76 6f 69 64  te3*,int(*)(void
1b960 2a 2c 69 6e 74 29 2c 76 6f 69 64 2a 29 3b 0a 0a  *,int),void*);..
1b970 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1b980 53 65 74 20 41 20 42 75 73 79 20 54 69 6d 65 6f  Set A Busy Timeo
1b990 75 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  ut.** METHOD: sq
1b9a0 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 69  lite3.**.** ^Thi
1b9b0 73 20 72 6f 75 74 69 6e 65 20 73 65 74 73 20 61  s routine sets a
1b9c0 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68   [sqlite3_busy_h
1b9d0 61 6e 64 6c 65 72 20 7c 20 62 75 73 79 20 68 61  andler | busy ha
1b9e0 6e 64 6c 65 72 5d 20 74 68 61 74 20 73 6c 65 65  ndler] that slee
1b9f0 70 73 0a 2a 2a 20 66 6f 72 20 61 20 73 70 65 63  ps.** for a spec
1ba00 69 66 69 65 64 20 61 6d 6f 75 6e 74 20 6f 66 20  ified amount of 
1ba10 74 69 6d 65 20 77 68 65 6e 20 61 20 74 61 62 6c  time when a tabl
1ba20 65 20 69 73 20 6c 6f 63 6b 65 64 2e 20 20 5e 54  e is locked.  ^T
1ba30 68 65 20 68 61 6e 64 6c 65 72 0a 2a 2a 20 77 69  he handler.** wi
1ba40 6c 6c 20 73 6c 65 65 70 20 6d 75 6c 74 69 70 6c  ll sleep multipl
1ba50 65 20 74 69 6d 65 73 20 75 6e 74 69 6c 20 61 74  e times until at
1ba60 20 6c 65 61 73 74 20 22 6d 73 22 20 6d 69 6c 6c   least "ms" mill
1ba70 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65  iseconds of slee
1ba80 70 69 6e 67 0a 2a 2a 20 68 61 76 65 20 61 63 63  ping.** have acc
1ba90 75 6d 75 6c 61 74 65 64 2e 20 20 5e 41 66 74 65  umulated.  ^Afte
1baa0 72 20 61 74 20 6c 65 61 73 74 20 22 6d 73 22 20  r at least "ms" 
1bab0 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20  milliseconds of 
1bac0 73 6c 65 65 70 69 6e 67 2c 0a 2a 2a 20 74 68 65  sleeping,.** the
1bad0 20 68 61 6e 64 6c 65 72 20 72 65 74 75 72 6e 73   handler returns
1bae0 20 30 20 77 68 69 63 68 20 63 61 75 73 65 73 20   0 which causes 
1baf0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
1bb00 20 74 6f 20 72 65 74 75 72 6e 0a 2a 2a 20 5b 53   to return.** [S
1bb10 51 4c 49 54 45 5f 42 55 53 59 5d 2e 0a 2a 2a 0a  QLITE_BUSY]..**.
1bb20 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 74 68 69 73  ** ^Calling this
1bb30 20 72 6f 75 74 69 6e 65 20 77 69 74 68 20 61 6e   routine with an
1bb40 20 61 72 67 75 6d 65 6e 74 20 6c 65 73 73 20 74   argument less t
1bb50 68 61 6e 20 6f 72 20 65 71 75 61 6c 20 74 6f 20  han or equal to 
1bb60 7a 65 72 6f 0a 2a 2a 20 74 75 72 6e 73 20 6f 66  zero.** turns of
1bb70 66 20 61 6c 6c 20 62 75 73 79 20 68 61 6e 64 6c  f all busy handl
1bb80 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65  ers..**.** ^(The
1bb90 72 65 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 61  re can only be a
1bba0 20 73 69 6e 67 6c 65 20 62 75 73 79 20 68 61 6e   single busy han
1bbb0 64 6c 65 72 20 66 6f 72 20 61 20 70 61 72 74 69  dler for a parti
1bbc0 63 75 6c 61 72 0a 2a 2a 20 5b 64 61 74 61 62 61  cular.** [databa
1bbd0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61  se connection] a
1bbe0 74 20 61 6e 79 20 67 69 76 65 6e 20 6d 6f 6d 65  t any given mome
1bbf0 6e 74 2e 20 20 49 66 20 61 6e 6f 74 68 65 72 20  nt.  If another 
1bc00 62 75 73 79 20 68 61 6e 64 6c 65 72 0a 2a 2a 20  busy handler.** 
1bc10 77 61 73 20 64 65 66 69 6e 65 64 20 20 28 75 73  was defined  (us
1bc20 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 62 75 73  ing [sqlite3_bus
1bc30 79 5f 68 61 6e 64 6c 65 72 28 29 5d 29 20 70 72  y_handler()]) pr
1bc40 69 6f 72 20 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a  ior to calling.*
1bc50 2a 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2c 20  * this routine, 
1bc60 74 68 61 74 20 6f 74 68 65 72 20 62 75 73 79 20  that other busy 
1bc70 68 61 6e 64 6c 65 72 20 69 73 20 63 6c 65 61 72  handler is clear
1bc80 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  ed.)^.**.** See 
1bc90 61 6c 73 6f 3a 20 20 5b 50 52 41 47 4d 41 20 62  also:  [PRAGMA b
1bca0 75 73 79 5f 74 69 6d 65 6f 75 74 5d 0a 2a 2f 0a  usy_timeout].*/.
1bcb0 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 75 73 79  int sqlite3_busy
1bcc0 5f 74 69 6d 65 6f 75 74 28 73 71 6c 69 74 65 33  _timeout(sqlite3
1bcd0 2a 2c 20 69 6e 74 20 6d 73 29 3b 0a 0a 2f 2a 0a  *, int ms);../*.
1bce0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e  ** CAPI3REF: Con
1bcf0 76 65 6e 69 65 6e 63 65 20 52 6f 75 74 69 6e 65  venience Routine
1bd00 73 20 46 6f 72 20 52 75 6e 6e 69 6e 67 20 51 75  s For Running Qu
1bd10 65 72 69 65 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a  eries.** METHOD:
1bd20 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 54   sqlite3.**.** T
1bd30 68 69 73 20 69 73 20 61 20 6c 65 67 61 63 79 20  his is a legacy 
1bd40 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 20 69  interface that i
1bd50 73 20 70 72 65 73 65 72 76 65 64 20 66 6f 72 20  s preserved for 
1bd60 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74  backwards compat
1bd70 69 62 69 6c 69 74 79 2e 0a 2a 2a 20 55 73 65 20  ibility..** Use 
1bd80 6f 66 20 74 68 69 73 20 69 6e 74 65 72 66 61 63  of this interfac
1bd90 65 20 69 73 20 6e 6f 74 20 72 65 63 6f 6d 6d 65  e is not recomme
1bda0 6e 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 44 65 66 69  nded..**.** Defi
1bdb0 6e 69 74 69 6f 6e 3a 20 41 20 3c 62 3e 72 65 73  nition: A <b>res
1bdc0 75 6c 74 20 74 61 62 6c 65 3c 2f 62 3e 20 69 73  ult table</b> is
1bdd0 20 6d 65 6d 6f 72 79 20 64 61 74 61 20 73 74 72   memory data str
1bde0 75 63 74 75 72 65 20 63 72 65 61 74 65 64 20 62  ucture created b
1bdf0 79 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  y the.** [sqlite
1be00 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 20 69  3_get_table()] i
1be10 6e 74 65 72 66 61 63 65 2e 20 20 41 20 72 65 73  nterface.  A res
1be20 75 6c 74 20 74 61 62 6c 65 20 72 65 63 6f 72 64  ult table record
1be30 73 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74  s the.** complet
1be40 65 20 71 75 65 72 79 20 72 65 73 75 6c 74 73 20  e query results 
1be50 66 72 6f 6d 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  from one or more
1be60 20 71 75 65 72 69 65 73 2e 0a 2a 2a 0a 2a 2a 20   queries..**.** 
1be70 54 68 65 20 74 61 62 6c 65 20 63 6f 6e 63 65 70  The table concep
1be80 74 75 61 6c 6c 79 20 68 61 73 20 61 20 6e 75 6d  tually has a num
1be90 62 65 72 20 6f 66 20 72 6f 77 73 20 61 6e 64 20  ber of rows and 
1bea0 63 6f 6c 75 6d 6e 73 2e 20 20 42 75 74 0a 2a 2a  columns.  But.**
1beb0 20 74 68 65 73 65 20 6e 75 6d 62 65 72 73 20 61   these numbers a
1bec0 72 65 20 6e 6f 74 20 70 61 72 74 20 6f 66 20 74  re not part of t
1bed0 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20  he result table 
1bee0 69 74 73 65 6c 66 2e 20 20 54 68 65 73 65 0a 2a  itself.  These.*
1bef0 2a 20 6e 75 6d 62 65 72 73 20 61 72 65 20 6f 62  * numbers are ob
1bf00 74 61 69 6e 65 64 20 73 65 70 61 72 61 74 65 6c  tained separatel
1bf10 79 2e 20 20 4c 65 74 20 4e 20 62 65 20 74 68 65  y.  Let N be the
1bf20 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 0a   number of rows.
1bf30 2a 2a 20 61 6e 64 20 4d 20 62 65 20 74 68 65 20  ** and M be the 
1bf40 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e  number of column
1bf50 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 6c  s..**.** A resul
1bf60 74 20 74 61 62 6c 65 20 69 73 20 61 6e 20 61 72  t table is an ar
1bf70 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20  ray of pointers 
1bf80 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74  to zero-terminat
1bf90 65 64 20 55 54 46 2d 38 20 73 74 72 69 6e 67 73  ed UTF-8 strings
1bfa0 2e 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20 28  ..** There are (
1bfb0 4e 2b 31 29 2a 4d 20 65 6c 65 6d 65 6e 74 73 20  N+1)*M elements 
1bfc0 69 6e 20 74 68 65 20 61 72 72 61 79 2e 20 20 54  in the array.  T
1bfd0 68 65 20 66 69 72 73 74 20 4d 20 70 6f 69 6e 74  he first M point
1bfe0 65 72 73 20 70 6f 69 6e 74 0a 2a 2a 20 74 6f 20  ers point.** to 
1bff0 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20  zero-terminated 
1c000 73 74 72 69 6e 67 73 20 74 68 61 74 20 20 63 6f  strings that  co
1c010 6e 74 61 69 6e 20 74 68 65 20 6e 61 6d 65 73 20  ntain the names 
1c020 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 73 2e 0a  of the columns..
1c030 2a 2a 20 54 68 65 20 72 65 6d 61 69 6e 69 6e 67  ** The remaining
1c040 20 65 6e 74 72 69 65 73 20 61 6c 6c 20 70 6f 69   entries all poi
1c050 6e 74 20 74 6f 20 71 75 65 72 79 20 72 65 73 75  nt to query resu
1c060 6c 74 73 2e 20 20 4e 55 4c 4c 20 76 61 6c 75 65  lts.  NULL value
1c070 73 20 72 65 73 75 6c 74 0a 2a 2a 20 69 6e 20 4e  s result.** in N
1c080 55 4c 4c 20 70 6f 69 6e 74 65 72 73 2e 20 20 41  ULL pointers.  A
1c090 6c 6c 20 6f 74 68 65 72 20 76 61 6c 75 65 73 20  ll other values 
1c0a0 61 72 65 20 69 6e 20 74 68 65 69 72 20 55 54 46  are in their UTF
1c0b0 2d 38 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74  -8 zero-terminat
1c0c0 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20 72 65 70  ed.** string rep
1c0d0 72 65 73 65 6e 74 61 74 69 6f 6e 20 61 73 20 72  resentation as r
1c0e0 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69  eturned by [sqli
1c0f0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
1c100 29 5d 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73 75  )]..**.** A resu
1c110 6c 74 20 74 61 62 6c 65 20 6d 69 67 68 74 20 63  lt table might c
1c120 6f 6e 73 69 73 74 20 6f 66 20 6f 6e 65 20 6f 72  onsist of one or
1c130 20 6d 6f 72 65 20 6d 65 6d 6f 72 79 20 61 6c 6c   more memory all
1c140 6f 63 61 74 69 6f 6e 73 2e 0a 2a 2a 20 49 74 20  ocations..** It 
1c150 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 70  is not safe to p
1c160 61 73 73 20 61 20 72 65 73 75 6c 74 20 74 61 62  ass a result tab
1c170 6c 65 20 64 69 72 65 63 74 6c 79 20 74 6f 20 5b  le directly to [
1c180 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e  sqlite3_free()].
1c190 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 61 62  .** A result tab
1c1a0 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 64 65 61  le should be dea
1c1b0 6c 6c 6f 63 61 74 65 64 20 75 73 69 6e 67 20 5b  llocated using [
1c1c0 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62  sqlite3_free_tab
1c1d0 6c 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 41  le()]..**.** ^(A
1c1e0 73 20 61 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20  s an example of 
1c1f0 74 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65  the result table
1c200 20 66 6f 72 6d 61 74 2c 20 73 75 70 70 6f 73 65   format, suppose
1c210 20 61 20 71 75 65 72 79 20 72 65 73 75 6c 74 0a   a query result.
1c220 2a 2a 20 69 73 20 61 73 20 66 6f 6c 6c 6f 77 73  ** is as follows
1c230 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  :.**.** <blockqu
1c240 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20  ote><pre>.**    
1c250 20 20 20 20 4e 61 6d 65 20 20 20 20 20 20 20 20      Name        
1c260 7c 20 41 67 65 0a 2a 2a 20 20 20 20 20 20 20 20  | Age.**        
1c270 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
1c280 2d 2d 2d 2d 2d 2d 2d 0a 2a 2a 20 20 20 20 20 20  -------.**      
1c290 20 20 41 6c 69 63 65 20 20 20 20 20 20 20 7c 20    Alice       | 
1c2a0 34 33 0a 2a 2a 20 20 20 20 20 20 20 20 42 6f 62  43.**        Bob
1c2b0 20 20 20 20 20 20 20 20 20 7c 20 32 38 0a 2a 2a           | 28.**
1c2c0 20 20 20 20 20 20 20 20 43 69 6e 64 79 20 20 20          Cindy   
1c2d0 20 20 20 20 7c 20 32 31 0a 2a 2a 20 3c 2f 70 72      | 21.** </pr
1c2e0 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a  e></blockquote>.
1c2f0 2a 2a 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20  **.** There are 
1c300 74 77 6f 20 63 6f 6c 75 6d 6e 20 28 4d 3d 3d 32  two column (M==2
1c310 29 20 61 6e 64 20 74 68 72 65 65 20 72 6f 77 73  ) and three rows
1c320 20 28 4e 3d 3d 33 29 2e 20 20 54 68 75 73 20 74   (N==3).  Thus t
1c330 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 74 61 62  he.** result tab
1c340 6c 65 20 68 61 73 20 38 20 65 6e 74 72 69 65 73  le has 8 entries
1c350 2e 20 20 53 75 70 70 6f 73 65 20 74 68 65 20 72  .  Suppose the r
1c360 65 73 75 6c 74 20 74 61 62 6c 65 20 69 73 20 73  esult table is s
1c370 74 6f 72 65 64 0a 2a 2a 20 69 6e 20 61 6e 20 61  tored.** in an a
1c380 72 72 61 79 20 6e 61 6d 65 73 20 61 7a 52 65 73  rray names azRes
1c390 75 6c 74 2e 20 20 54 68 65 6e 20 61 7a 52 65 73  ult.  Then azRes
1c3a0 75 6c 74 20 68 6f 6c 64 73 20 74 68 69 73 20 63  ult holds this c
1c3b0 6f 6e 74 65 6e 74 3a 0a 2a 2a 0a 2a 2a 20 3c 62  ontent:.**.** <b
1c3c0 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a  lockquote><pre>.
1c3d0 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75  **        azResu
1c3e0 6c 74 26 23 39 31 3b 30 5d 20 3d 20 22 4e 61 6d  lt&#91;0] = "Nam
1c3f0 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a  e";.**        az
1c400 52 65 73 75 6c 74 26 23 39 31 3b 31 5d 20 3d 20  Result&#91;1] = 
1c410 22 41 67 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20  "Age";.**       
1c420 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 32 5d   azResult&#91;2]
1c430 20 3d 20 22 41 6c 69 63 65 22 3b 0a 2a 2a 20 20   = "Alice";.**  
1c440 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23        azResult&#
1c450 39 31 3b 33 5d 20 3d 20 22 34 33 22 3b 0a 2a 2a  91;3] = "43";.**
1c460 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74          azResult
1c470 26 23 39 31 3b 34 5d 20 3d 20 22 42 6f 62 22 3b  &#91;4] = "Bob";
1c480 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73  .**        azRes
1c490 75 6c 74 26 23 39 31 3b 35 5d 20 3d 20 22 32 38  ult&#91;5] = "28
1c4a0 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52  ";.**        azR
1c4b0 65 73 75 6c 74 26 23 39 31 3b 36 5d 20 3d 20 22  esult&#91;6] = "
1c4c0 43 69 6e 64 79 22 3b 0a 2a 2a 20 20 20 20 20 20  Cindy";.**      
1c4d0 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 37    azResult&#91;7
1c4e0 5d 20 3d 20 22 32 31 22 3b 0a 2a 2a 20 3c 2f 70  ] = "21";.** </p
1c4f0 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e  re></blockquote>
1c500 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  )^.**.** ^The sq
1c510 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28  lite3_get_table(
1c520 29 20 66 75 6e 63 74 69 6f 6e 20 65 76 61 6c 75  ) function evalu
1c530 61 74 65 73 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  ates one or more
1c540 0a 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65  .** semicolon-se
1c550 70 61 72 61 74 65 64 20 53 51 4c 20 73 74 61 74  parated SQL stat
1c560 65 6d 65 6e 74 73 20 69 6e 20 74 68 65 20 7a 65  ements in the ze
1c570 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54  ro-terminated UT
1c580 46 2d 38 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 66  F-8.** string of
1c590 20 69 74 73 20 32 6e 64 20 70 61 72 61 6d 65 74   its 2nd paramet
1c5a0 65 72 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61  er and returns a
1c5b0 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 74 6f   result table to
1c5c0 20 74 68 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 20   the.** pointer 
1c5d0 67 69 76 65 6e 20 69 6e 20 69 74 73 20 33 72 64  given in its 3rd
1c5e0 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a   parameter..**.*
1c5f0 2a 20 41 66 74 65 72 20 74 68 65 20 61 70 70 6c  * After the appl
1c600 69 63 61 74 69 6f 6e 20 68 61 73 20 66 69 6e 69  ication has fini
1c610 73 68 65 64 20 77 69 74 68 20 74 68 65 20 72 65  shed with the re
1c620 73 75 6c 74 20 66 72 6f 6d 20 73 71 6c 69 74 65  sult from sqlite
1c630 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 2c 0a 2a  3_get_table(),.*
1c640 2a 20 69 74 20 6d 75 73 74 20 70 61 73 73 20 74  * it must pass t
1c650 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20  he result table 
1c660 70 6f 69 6e 74 65 72 20 74 6f 20 73 71 6c 69 74  pointer to sqlit
1c670 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 20  e3_free_table() 
1c680 69 6e 20 6f 72 64 65 72 20 74 6f 0a 2a 2a 20 72  in order to.** r
1c690 65 6c 65 61 73 65 20 74 68 65 20 6d 65 6d 6f 72  elease the memor
1c6a0 79 20 74 68 61 74 20 77 61 73 20 6d 61 6c 6c 6f  y that was mallo
1c6b0 63 65 64 2e 20 20 42 65 63 61 75 73 65 20 6f 66  ced.  Because of
1c6c0 20 74 68 65 20 77 61 79 20 74 68 65 0a 2a 2a 20   the way the.** 
1c6d0 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
1c6e0 29 5d 20 68 61 70 70 65 6e 73 20 77 69 74 68 69  )] happens withi
1c6f0 6e 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61  n sqlite3_get_ta
1c700 62 6c 65 28 29 2c 20 74 68 65 20 63 61 6c 6c 69  ble(), the calli
1c710 6e 67 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 6d  ng.** function m
1c720 75 73 74 20 6e 6f 74 20 74 72 79 20 74 6f 20 63  ust not try to c
1c730 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  all [sqlite3_fre
1c740 65 28 29 5d 20 64 69 72 65 63 74 6c 79 2e 20 20  e()] directly.  
1c750 4f 6e 6c 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  Only.** [sqlite3
1c760 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 5d 20 69  _free_table()] i
1c770 73 20 61 62 6c 65 20 74 6f 20 72 65 6c 65 61 73  s able to releas
1c780 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 70 72 6f  e the memory pro
1c790 70 65 72 6c 79 20 61 6e 64 20 73 61 66 65 6c 79  perly and safely
1c7a0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
1c7b0 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20  te3_get_table() 
1c7c0 69 6e 74 65 72 66 61 63 65 20 69 73 20 69 6d 70  interface is imp
1c7d0 6c 65 6d 65 6e 74 65 64 20 61 73 20 61 20 77 72  lemented as a wr
1c7e0 61 70 70 65 72 20 61 72 6f 75 6e 64 0a 2a 2a 20  apper around.** 
1c7f0 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d  [sqlite3_exec()]
1c800 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 67  .  The sqlite3_g
1c810 65 74 5f 74 61 62 6c 65 28 29 20 72 6f 75 74 69  et_table() routi
1c820 6e 65 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 65  ne does not have
1c830 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20 61 6e   access.** to an
1c840 79 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 20  y internal data 
1c850 73 74 72 75 63 74 75 72 65 73 20 6f 66 20 53 51  structures of SQ
1c860 4c 69 74 65 2e 20 20 49 74 20 75 73 65 73 20 6f  Lite.  It uses o
1c870 6e 6c 79 20 74 68 65 20 70 75 62 6c 69 63 0a 2a  nly the public.*
1c880 2a 20 69 6e 74 65 72 66 61 63 65 20 64 65 66 69  * interface defi
1c890 6e 65 64 20 68 65 72 65 2e 20 20 41 73 20 61 20  ned here.  As a 
1c8a0 63 6f 6e 73 65 71 75 65 6e 63 65 2c 20 65 72 72  consequence, err
1c8b0 6f 72 73 20 74 68 61 74 20 6f 63 63 75 72 20 69  ors that occur i
1c8c0 6e 20 74 68 65 0a 2a 2a 20 77 72 61 70 70 65 72  n the.** wrapper
1c8d0 20 6c 61 79 65 72 20 6f 75 74 73 69 64 65 20 6f   layer outside o
1c8e0 66 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 5b  f the internal [
1c8f0 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20  sqlite3_exec()] 
1c900 63 61 6c 6c 20 61 72 65 20 6e 6f 74 0a 2a 2a 20  call are not.** 
1c910 72 65 66 6c 65 63 74 65 64 20 69 6e 20 73 75 62  reflected in sub
1c920 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f  sequent calls to
1c930 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64   [sqlite3_errcod
1c940 65 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69  e()] or.** [sqli
1c950 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a  te3_errmsg()]..*
1c960 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 67 65  /.int sqlite3_ge
1c970 74 5f 74 61 62 6c 65 28 0a 20 20 73 71 6c 69 74  t_table(.  sqlit
1c980 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20  e3 *db,         
1c990 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64 61 74 61   /* An open data
1c9a0 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  base */.  const 
1c9b0 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20  char *zSql,     
1c9c0 2f 2a 20 53 51 4c 20 74 6f 20 62 65 20 65 76 61  /* SQL to be eva
1c9d0 6c 75 61 74 65 64 20 2a 2f 0a 20 20 63 68 61 72  luated */.  char
1c9e0 20 2a 2a 2a 70 61 7a 52 65 73 75 6c 74 2c 20 20   ***pazResult,  
1c9f0 20 20 2f 2a 20 52 65 73 75 6c 74 73 20 6f 66 20    /* Results of 
1ca00 74 68 65 20 71 75 65 72 79 20 2a 2f 0a 20 20 69  the query */.  i
1ca10 6e 74 20 2a 70 6e 52 6f 77 2c 20 20 20 20 20 20  nt *pnRow,      
1ca20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f       /* Number o
1ca30 66 20 72 65 73 75 6c 74 20 72 6f 77 73 20 77 72  f result rows wr
1ca40 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 20 20  itten here */.  
1ca50 69 6e 74 20 2a 70 6e 43 6f 6c 75 6d 6e 2c 20 20  int *pnColumn,  
1ca60 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20        /* Number 
1ca70 6f 66 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e  of result column
1ca80 73 20 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a  s written here *
1ca90 2f 0a 20 20 63 68 61 72 20 2a 2a 70 7a 45 72 72  /.  char **pzErr
1caa0 6d 73 67 20 20 20 20 20 20 20 2f 2a 20 45 72 72  msg       /* Err
1cab0 6f 72 20 6d 73 67 20 77 72 69 74 74 65 6e 20 68  or msg written h
1cac0 65 72 65 20 2a 2f 0a 29 3b 0a 76 6f 69 64 20 73  ere */.);.void s
1cad0 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c  qlite3_free_tabl
1cae0 65 28 63 68 61 72 20 2a 2a 72 65 73 75 6c 74 29  e(char **result)
1caf0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
1cb00 46 3a 20 46 6f 72 6d 61 74 74 65 64 20 53 74 72  F: Formatted Str
1cb10 69 6e 67 20 50 72 69 6e 74 69 6e 67 20 46 75 6e  ing Printing Fun
1cb20 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65  ctions.**.** The
1cb30 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20  se routines are 
1cb40 77 6f 72 6b 2d 61 6c 69 6b 65 73 20 6f 66 20 74  work-alikes of t
1cb50 68 65 20 22 70 72 69 6e 74 66 28 29 22 20 66 61  he "printf()" fa
1cb60 6d 69 6c 79 20 6f 66 20 66 75 6e 63 74 69 6f 6e  mily of function
1cb70 73 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20 73 74  s.** from the st
1cb80 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 79  andard C library
1cb90 2e 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  ..** These routi
1cba0 6e 65 73 20 75 6e 64 65 72 73 74 61 6e 64 20 6d  nes understand m
1cbb0 6f 73 74 20 6f 66 20 74 68 65 20 63 6f 6d 6d 6f  ost of the commo
1cbc0 6e 20 4b 26 52 20 66 6f 72 6d 61 74 74 69 6e 67  n K&R formatting
1cbd0 20 6f 70 74 69 6f 6e 73 2c 0a 2a 2a 20 70 6c 75   options,.** plu
1cbe0 73 20 73 6f 6d 65 20 61 64 64 69 74 69 6f 6e 61  s some additiona
1cbf0 6c 20 6e 6f 6e 2d 73 74 61 6e 64 61 72 64 20 66  l non-standard f
1cc00 6f 72 6d 61 74 73 2c 20 64 65 74 61 69 6c 65 64  ormats, detailed
1cc10 20 62 65 6c 6f 77 2e 0a 2a 2a 20 4e 6f 74 65 20   below..** Note 
1cc20 74 68 61 74 20 73 6f 6d 65 20 6f 66 20 74 68 65  that some of the
1cc30 20 6d 6f 72 65 20 6f 62 73 63 75 72 65 20 66 6f   more obscure fo
1cc40 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 73  rmatting options
1cc50 20 66 72 6f 6d 20 72 65 63 65 6e 74 0a 2a 2a 20   from recent.** 
1cc60 43 2d 6c 69 62 72 61 72 79 20 73 74 61 6e 64 61  C-library standa
1cc70 72 64 73 20 61 72 65 20 6f 6d 69 74 74 65 64 20  rds are omitted 
1cc80 66 72 6f 6d 20 74 68 69 73 20 69 6d 70 6c 65 6d  from this implem
1cc90 65 6e 74 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  entation..**.** 
1cca0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 70 72  ^The sqlite3_mpr
1ccb0 69 6e 74 66 28 29 20 61 6e 64 20 73 71 6c 69 74  intf() and sqlit
1ccc0 65 33 5f 76 6d 70 72 69 6e 74 66 28 29 20 72 6f  e3_vmprintf() ro
1ccd0 75 74 69 6e 65 73 20 77 72 69 74 65 20 74 68 65  utines write the
1cce0 69 72 0a 2a 2a 20 72 65 73 75 6c 74 73 20 69 6e  ir.** results in
1ccf0 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e  to memory obtain
1cd00 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  ed from [sqlite3
1cd10 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2a 20 54  _malloc()]..** T
1cd20 68 65 20 73 74 72 69 6e 67 73 20 72 65 74 75 72  he strings retur
1cd30 6e 65 64 20 62 79 20 74 68 65 73 65 20 74 77 6f  ned by these two
1cd40 20 72 6f 75 74 69 6e 65 73 20 73 68 6f 75 6c 64   routines should
1cd50 20 62 65 0a 2a 2a 20 72 65 6c 65 61 73 65 64 20   be.** released 
1cd60 62 79 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  by [sqlite3_free
1cd70 28 29 5d 2e 20 20 5e 42 6f 74 68 20 72 6f 75 74  ()].  ^Both rout
1cd80 69 6e 65 73 20 72 65 74 75 72 6e 20 61 0a 2a 2a  ines return a.**
1cd90 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 66   NULL pointer if
1cda0 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
1cdb0 28 29 5d 20 69 73 20 75 6e 61 62 6c 65 20 74 6f  ()] is unable to
1cdc0 20 61 6c 6c 6f 63 61 74 65 20 65 6e 6f 75 67 68   allocate enough
1cdd0 0a 2a 2a 20 6d 65 6d 6f 72 79 20 74 6f 20 68 6f  .** memory to ho
1cde0 6c 64 20 74 68 65 20 72 65 73 75 6c 74 69 6e 67  ld the resulting
1cdf0 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e   string..**.** ^
1ce00 28 54 68 65 20 73 71 6c 69 74 65 33 5f 73 6e 70  (The sqlite3_snp
1ce10 72 69 6e 74 66 28 29 20 72 6f 75 74 69 6e 65 20  rintf() routine 
1ce20 69 73 20 73 69 6d 69 6c 61 72 20 74 6f 20 22 73  is similar to "s
1ce30 6e 70 72 69 6e 74 66 28 29 22 20 66 72 6f 6d 0a  nprintf()" from.
1ce40 2a 2a 20 74 68 65 20 73 74 61 6e 64 61 72 64 20  ** the standard 
1ce50 43 20 6c 69 62 72 61 72 79 2e 20 20 54 68 65 20  C library.  The 
1ce60 72 65 73 75 6c 74 20 69 73 20 77 72 69 74 74 65  result is writte
1ce70 6e 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 62 75  n into the.** bu
1ce80 66 66 65 72 20 73 75 70 70 6c 69 65 64 20 61 73  ffer supplied as
1ce90 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   the second para
1cea0 6d 65 74 65 72 20 77 68 6f 73 65 20 73 69 7a 65  meter whose size
1ceb0 20 69 73 20 67 69 76 65 6e 20 62 79 0a 2a 2a 20   is given by.** 
1cec0 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  the first parame
1ced0 74 65 72 2e 20 4e 6f 74 65 20 74 68 61 74 20 74  ter. Note that t
1cee0 68 65 20 6f 72 64 65 72 20 6f 66 20 74 68 65 0a  he order of the.
1cef0 2a 2a 20 66 69 72 73 74 20 74 77 6f 20 70 61 72  ** first two par
1cf00 61 6d 65 74 65 72 73 20 69 73 20 72 65 76 65 72  ameters is rever
1cf10 73 65 64 20 66 72 6f 6d 20 73 6e 70 72 69 6e 74  sed from snprint
1cf20 66 28 29 2e 29 5e 20 20 54 68 69 73 20 69 73 20  f().)^  This is 
1cf30 61 6e 0a 2a 2a 20 68 69 73 74 6f 72 69 63 61 6c  an.** historical
1cf40 20 61 63 63 69 64 65 6e 74 20 74 68 61 74 20 63   accident that c
1cf50 61 6e 6e 6f 74 20 62 65 20 66 69 78 65 64 20 77  annot be fixed w
1cf60 69 74 68 6f 75 74 20 62 72 65 61 6b 69 6e 67 0a  ithout breaking.
1cf70 2a 2a 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d  ** backwards com
1cf80 70 61 74 69 62 69 6c 69 74 79 2e 20 20 5e 28 4e  patibility.  ^(N
1cf90 6f 74 65 20 61 6c 73 6f 20 74 68 61 74 20 73 71  ote also that sq
1cfa0 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29  lite3_snprintf()
1cfb0 0a 2a 2a 20 72 65 74 75 72 6e 73 20 61 20 70 6f  .** returns a po
1cfc0 69 6e 74 65 72 20 74 6f 20 69 74 73 20 62 75 66  inter to its buf
1cfd0 66 65 72 20 69 6e 73 74 65 61 64 20 6f 66 20 74  fer instead of t
1cfe0 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20  he number of.** 
1cff0 63 68 61 72 61 63 74 65 72 73 20 61 63 74 75 61  characters actua
1d000 6c 6c 79 20 77 72 69 74 74 65 6e 20 69 6e 74 6f  lly written into
1d010 20 74 68 65 20 62 75 66 66 65 72 2e 29 5e 20 20   the buffer.)^  
1d020 57 65 20 61 64 6d 69 74 20 74 68 61 74 0a 2a 2a  We admit that.**
1d030 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63   the number of c
1d040 68 61 72 61 63 74 65 72 73 20 77 72 69 74 74 65  haracters writte
1d050 6e 20 77 6f 75 6c 64 20 62 65 20 61 20 6d 6f 72  n would be a mor
1d060 65 20 75 73 65 66 75 6c 20 72 65 74 75 72 6e 0a  e useful return.
1d070 2a 2a 20 76 61 6c 75 65 20 62 75 74 20 77 65 20  ** value but we 
1d080 63 61 6e 6e 6f 74 20 63 68 61 6e 67 65 20 74 68  cannot change th
1d090 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
1d0a0 20 6f 66 20 73 71 6c 69 74 65 33 5f 73 6e 70 72   of sqlite3_snpr
1d0b0 69 6e 74 66 28 29 0a 2a 2a 20 6e 6f 77 20 77 69  intf().** now wi
1d0c0 74 68 6f 75 74 20 62 72 65 61 6b 69 6e 67 20 63  thout breaking c
1d0d0 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a  ompatibility..**
1d0e0 0a 2a 2a 20 5e 41 73 20 6c 6f 6e 67 20 61 73 20  .** ^As long as 
1d0f0 74 68 65 20 62 75 66 66 65 72 20 73 69 7a 65 20  the buffer size 
1d100 69 73 20 67 72 65 61 74 65 72 20 74 68 61 6e 20  is greater than 
1d110 7a 65 72 6f 2c 20 73 71 6c 69 74 65 33 5f 73 6e  zero, sqlite3_sn
1d120 70 72 69 6e 74 66 28 29 0a 2a 2a 20 67 75 61 72  printf().** guar
1d130 61 6e 74 65 65 73 20 74 68 61 74 20 74 68 65 20  antees that the 
1d140 62 75 66 66 65 72 20 69 73 20 61 6c 77 61 79 73  buffer is always
1d150 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
1d160 2e 20 20 5e 54 68 65 20 66 69 72 73 74 0a 2a 2a  .  ^The first.**
1d170 20 70 61 72 61 6d 65 74 65 72 20 22 6e 22 20 69   parameter "n" i
1d180 73 20 74 68 65 20 74 6f 74 61 6c 20 73 69 7a 65  s the total size
1d190 20 6f 66 20 74 68 65 20 62 75 66 66 65 72 2c 20   of the buffer, 
1d1a0 69 6e 63 6c 75 64 69 6e 67 20 73 70 61 63 65 20  including space 
1d1b0 66 6f 72 0a 2a 2a 20 74 68 65 20 7a 65 72 6f 20  for.** the zero 
1d1c0 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20 53 6f 20  terminator.  So 
1d1d0 74 68 65 20 6c 6f 6e 67 65 73 74 20 73 74 72 69  the longest stri
1d1e0 6e 67 20 74 68 61 74 20 63 61 6e 20 62 65 20 63  ng that can be c
1d1f0 6f 6d 70 6c 65 74 65 6c 79 0a 2a 2a 20 77 72 69  ompletely.** wri
1d200 74 74 65 6e 20 77 69 6c 6c 20 62 65 20 6e 2d 31  tten will be n-1
1d210 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a   characters..**.
1d220 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
1d230 76 73 6e 70 72 69 6e 74 66 28 29 20 72 6f 75 74  vsnprintf() rout
1d240 69 6e 65 20 69 73 20 61 20 76 61 72 61 72 67 73  ine is a varargs
1d250 20 76 65 72 73 69 6f 6e 20 6f 66 20 73 71 6c 69   version of sqli
1d260 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 2e 0a  te3_snprintf()..
1d270 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
1d280 69 6e 65 73 20 61 6c 6c 20 69 6d 70 6c 65 6d 65  ines all impleme
1d290 6e 74 20 73 6f 6d 65 20 61 64 64 69 74 69 6f 6e  nt some addition
1d2a0 61 6c 20 66 6f 72 6d 61 74 74 69 6e 67 0a 2a 2a  al formatting.**
1d2b0 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 20 61 72   options that ar
1d2c0 65 20 75 73 65 66 75 6c 20 66 6f 72 20 63 6f 6e  e useful for con
1d2d0 73 74 72 75 63 74 69 6e 67 20 53 51 4c 20 73 74  structing SQL st
1d2e0 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20 41 6c 6c  atements..** All
1d2f0 20 6f 66 20 74 68 65 20 75 73 75 61 6c 20 70 72   of the usual pr
1d300 69 6e 74 66 28 29 20 66 6f 72 6d 61 74 74 69 6e  intf() formattin
1d310 67 20 6f 70 74 69 6f 6e 73 20 61 70 70 6c 79 2e  g options apply.
1d320 20 20 49 6e 20 61 64 64 69 74 69 6f 6e 2c 20 74    In addition, t
1d330 68 65 72 65 0a 2a 2a 20 69 73 20 61 72 65 20 22  here.** is are "
1d340 25 71 22 2c 20 22 25 51 22 2c 20 22 25 77 22 20  %q", "%Q", "%w" 
1d350 61 6e 64 20 22 25 7a 22 20 6f 70 74 69 6f 6e 73  and "%z" options
1d360 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 25 71  ..**.** ^(The %q
1d370 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69   option works li
1d380 6b 65 20 25 73 20 69 6e 20 74 68 61 74 20 69 74  ke %s in that it
1d390 20 73 75 62 73 74 69 74 75 74 65 73 20 61 20 6e   substitutes a n
1d3a0 75 6c 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a  ul-terminated.**
1d3b0 20 73 74 72 69 6e 67 20 66 72 6f 6d 20 74 68 65   string from the
1d3c0 20 61 72 67 75 6d 65 6e 74 20 6c 69 73 74 2e 20   argument list. 
1d3d0 20 42 75 74 20 25 71 20 61 6c 73 6f 20 64 6f 75   But %q also dou
1d3e0 62 6c 65 73 20 65 76 65 72 79 20 27 5c 27 27 20  bles every '\'' 
1d3f0 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 25 71  character..** %q
1d400 20 69 73 20 64 65 73 69 67 6e 65 64 20 66 6f 72   is designed for
1d410 20 75 73 65 20 69 6e 73 69 64 65 20 61 20 73 74   use inside a st
1d420 72 69 6e 67 20 6c 69 74 65 72 61 6c 2e 29 5e 20  ring literal.)^ 
1d430 20 42 79 20 64 6f 75 62 6c 69 6e 67 20 65 61 63   By doubling eac
1d440 68 20 27 5c 27 27 0a 2a 2a 20 63 68 61 72 61 63  h '\''.** charac
1d450 74 65 72 20 69 74 20 65 73 63 61 70 65 73 20 74  ter it escapes t
1d460 68 61 74 20 63 68 61 72 61 63 74 65 72 20 61 6e  hat character an
1d470 64 20 61 6c 6c 6f 77 73 20 69 74 20 74 6f 20 62  d allows it to b
1d480 65 20 69 6e 73 65 72 74 65 64 20 69 6e 74 6f 0a  e inserted into.
1d490 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 2e 0a 2a  ** the string..*
1d4a0 2a 0a 2a 2a 20 46 6f 72 20 65 78 61 6d 70 6c 65  *.** For example
1d4b0 2c 20 61 73 73 75 6d 65 20 74 68 65 20 73 74 72  , assume the str
1d4c0 69 6e 67 20 76 61 72 69 61 62 6c 65 20 7a 54 65  ing variable zTe
1d4d0 78 74 20 63 6f 6e 74 61 69 6e 73 20 74 65 78 74  xt contains text
1d4e0 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a   as follows:.**.
1d4f0 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c  ** <blockquote><
1d500 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a  pre>.**  char *z
1d510 54 65 78 74 20 3d 20 22 49 74 27 73 20 61 20 68  Text = "It's a h
1d520 61 70 70 79 20 64 61 79 21 22 3b 0a 2a 2a 20 3c  appy day!";.** <
1d530 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
1d540 65 3e 0a 2a 2a 0a 2a 2a 20 4f 6e 65 20 63 61 6e  e>.**.** One can
1d550 20 75 73 65 20 74 68 69 73 20 74 65 78 74 20 69   use this text i
1d560 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65  n an SQL stateme
1d570 6e 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a  nt as follows:.*
1d580 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65  *.** <blockquote
1d590 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20  ><pre>.**  char 
1d5a0 2a 7a 53 51 4c 20 3d 20 73 71 6c 69 74 65 33 5f  *zSQL = sqlite3_
1d5b0 6d 70 72 69 6e 74 66 28 22 49 4e 53 45 52 54 20  mprintf("INSERT 
1d5c0 49 4e 54 4f 20 74 61 62 6c 65 20 56 41 4c 55 45  INTO table VALUE
1d5d0 53 28 27 25 71 27 29 22 2c 20 7a 54 65 78 74 29  S('%q')", zText)
1d5e0 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 65 78  ;.**  sqlite3_ex
1d5f0 65 63 28 64 62 2c 20 7a 53 51 4c 2c 20 30 2c 20  ec(db, zSQL, 0, 
1d600 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 71 6c 69 74  0, 0);.**  sqlit
1d610 65 33 5f 66 72 65 65 28 7a 53 51 4c 29 3b 0a 2a  e3_free(zSQL);.*
1d620 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71  * </pre></blockq
1d630 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 42 65 63 61  uote>.**.** Beca
1d640 75 73 65 20 74 68 65 20 25 71 20 66 6f 72 6d 61  use the %q forma
1d650 74 20 73 74 72 69 6e 67 20 69 73 20 75 73 65 64  t string is used
1d660 2c 20 74 68 65 20 27 5c 27 27 20 63 68 61 72 61  , the '\'' chara
1d670 63 74 65 72 20 69 6e 20 7a 54 65 78 74 0a 2a 2a  cter in zText.**
1d680 20 69 73 20 65 73 63 61 70 65 64 20 61 6e 64 20   is escaped and 
1d690 74 68 65 20 53 51 4c 20 67 65 6e 65 72 61 74 65  the SQL generate
1d6a0 64 20 69 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a  d is as follows:
1d6b0 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f  .**.** <blockquo
1d6c0 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e 53  te><pre>.**  INS
1d6d0 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 31 20  ERT INTO table1 
1d6e0 56 41 4c 55 45 53 28 27 49 74 27 27 73 20 61 20  VALUES('It''s a 
1d6f0 68 61 70 70 79 20 64 61 79 21 27 29 0a 2a 2a 20  happy day!').** 
1d700 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f  </pre></blockquo
1d710 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69  te>.**.** This i
1d720 73 20 63 6f 72 72 65 63 74 2e 20 20 48 61 64 20  s correct.  Had 
1d730 77 65 20 75 73 65 64 20 25 73 20 69 6e 73 74 65  we used %s inste
1d740 61 64 20 6f 66 20 25 71 2c 20 74 68 65 20 67 65  ad of %q, the ge
1d750 6e 65 72 61 74 65 64 20 53 51 4c 0a 2a 2a 20 77  nerated SQL.** w
1d760 6f 75 6c 64 20 68 61 76 65 20 6c 6f 6f 6b 65 64  ould have looked
1d770 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a   like this:.**.*
1d780 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70  * <blockquote><p
1d790 72 65 3e 0a 2a 2a 20 20 49 4e 53 45 52 54 20 49  re>.**  INSERT I
1d7a0 4e 54 4f 20 74 61 62 6c 65 31 20 56 41 4c 55 45  NTO table1 VALUE
1d7b0 53 28 27 49 74 27 73 20 61 20 68 61 70 70 79 20  S('It's a happy 
1d7c0 64 61 79 21 27 29 3b 0a 2a 2a 20 3c 2f 70 72 65  day!');.** </pre
1d7d0 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a  ></blockquote>.*
1d7e0 2a 0a 2a 2a 20 54 68 69 73 20 73 65 63 6f 6e 64  *.** This second
1d7f0 20 65 78 61 6d 70 6c 65 20 69 73 20 61 6e 20 53   example is an S
1d800 51 4c 20 73 79 6e 74 61 78 20 65 72 72 6f 72 2e  QL syntax error.
1d810 20 20 41 73 20 61 20 67 65 6e 65 72 61 6c 20 72    As a general r
1d820 75 6c 65 20 79 6f 75 20 73 68 6f 75 6c 64 0a 2a  ule you should.*
1d830 2a 20 61 6c 77 61 79 73 20 75 73 65 20 25 71 20  * always use %q 
1d840 69 6e 73 74 65 61 64 20 6f 66 20 25 73 20 77 68  instead of %s wh
1d850 65 6e 20 69 6e 73 65 72 74 69 6e 67 20 74 65 78  en inserting tex
1d860 74 20 69 6e 74 6f 20 61 20 73 74 72 69 6e 67 20  t into a string 
1d870 6c 69 74 65 72 61 6c 2e 0a 2a 2a 0a 2a 2a 20 5e  literal..**.** ^
1d880 28 54 68 65 20 25 51 20 6f 70 74 69 6f 6e 20 77  (The %Q option w
1d890 6f 72 6b 73 20 6c 69 6b 65 20 25 71 20 65 78 63  orks like %q exc
1d8a0 65 70 74 20 69 74 20 61 6c 73 6f 20 61 64 64 73  ept it also adds
1d8b0 20 73 69 6e 67 6c 65 20 71 75 6f 74 65 73 20 61   single quotes a
1d8c0 72 6f 75 6e 64 0a 2a 2a 20 74 68 65 20 6f 75 74  round.** the out
1d8d0 73 69 64 65 20 6f 66 20 74 68 65 20 74 6f 74 61  side of the tota
1d8e0 6c 20 73 74 72 69 6e 67 2e 20 20 41 64 64 69 74  l string.  Addit
1d8f0 69 6f 6e 61 6c 6c 79 2c 20 69 66 20 74 68 65 20  ionally, if the 
1d900 70 61 72 61 6d 65 74 65 72 20 69 6e 20 74 68 65  parameter in the
1d910 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6c 69 73  .** argument lis
1d920 74 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  t is a NULL poin
1d930 74 65 72 2c 20 25 51 20 73 75 62 73 74 69 74 75  ter, %Q substitu
1d940 74 65 73 20 74 68 65 20 74 65 78 74 20 22 4e 55  tes the text "NU
1d950 4c 4c 22 20 28 77 69 74 68 6f 75 74 0a 2a 2a 20  LL" (without.** 
1d960 73 69 6e 67 6c 65 20 71 75 6f 74 65 73 29 2e 29  single quotes).)
1d970 5e 20 20 53 6f 2c 20 66 6f 72 20 65 78 61 6d 70  ^  So, for examp
1d980 6c 65 2c 20 6f 6e 65 20 63 6f 75 6c 64 20 73 61  le, one could sa
1d990 79 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71  y:.**.** <blockq
1d9a0 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63  uote><pre>.**  c
1d9b0 68 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71 6c 69  har *zSQL = sqli
1d9c0 74 65 33 5f 6d 70 72 69 6e 74 66 28 22 49 4e 53  te3_mprintf("INS
1d9d0 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 20 56  ERT INTO table V
1d9e0 41 4c 55 45 53 28 25 51 29 22 2c 20 7a 54 65 78  ALUES(%Q)", zTex
1d9f0 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f  t);.**  sqlite3_
1da00 65 78 65 63 28 64 62 2c 20 7a 53 51 4c 2c 20 30  exec(db, zSQL, 0
1da10 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 71 6c  , 0, 0);.**  sql
1da20 69 74 65 33 5f 66 72 65 65 28 7a 53 51 4c 29 3b  ite3_free(zSQL);
1da30 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63  .** </pre></bloc
1da40 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68  kquote>.**.** Th
1da50 65 20 63 6f 64 65 20 61 62 6f 76 65 20 77 69 6c  e code above wil
1da60 6c 20 72 65 6e 64 65 72 20 61 20 63 6f 72 72 65  l render a corre
1da70 63 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ct SQL statement
1da80 20 69 6e 20 74 68 65 20 7a 53 51 4c 0a 2a 2a 20   in the zSQL.** 
1da90 76 61 72 69 61 62 6c 65 20 65 76 65 6e 20 69 66  variable even if
1daa0 20 74 68 65 20 7a 54 65 78 74 20 76 61 72 69 61   the zText varia
1dab0 62 6c 65 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  ble is a NULL po
1dac0 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54  inter..**.** ^(T
1dad0 68 65 20 22 25 77 22 20 66 6f 72 6d 61 74 74 69  he "%w" formatti
1dae0 6e 67 20 6f 70 74 69 6f 6e 20 69 73 20 6c 69 6b  ng option is lik
1daf0 65 20 22 25 71 22 20 65 78 63 65 70 74 20 74 68  e "%q" except th
1db00 61 74 20 69 74 20 65 78 70 65 63 74 73 20 74 6f  at it expects to
1db10 0a 2a 2a 20 62 65 20 63 6f 6e 74 61 69 6e 65 64  .** be contained
1db20 20 77 69 74 68 69 6e 20 64 6f 75 62 6c 65 2d 71   within double-q
1db30 75 6f 74 65 73 20 69 6e 73 74 65 61 64 20 6f 66  uotes instead of
1db40 20 73 69 6e 67 6c 65 20 71 75 6f 74 65 73 2c 20   single quotes, 
1db50 61 6e 64 20 69 74 0a 2a 2a 20 65 73 63 61 70 65  and it.** escape
1db60 73 20 74 68 65 20 64 6f 75 62 6c 65 2d 71 75 6f  s the double-quo
1db70 74 65 20 63 68 61 72 61 63 74 65 72 20 69 6e 73  te character ins
1db80 74 65 61 64 20 6f 66 20 74 68 65 20 73 69 6e 67  tead of the sing
1db90 6c 65 2d 71 75 6f 74 65 0a 2a 2a 20 63 68 61 72  le-quote.** char
1dba0 61 63 74 65 72 2e 29 5e 20 20 54 68 65 20 22 25  acter.)^  The "%
1dbb0 77 22 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70  w" formatting op
1dbc0 74 69 6f 6e 20 69 73 20 69 6e 74 65 6e 64 65 64  tion is intended
1dbd0 20 66 6f 72 20 73 61 66 65 6c 79 20 69 6e 73 65   for safely inse
1dbe0 72 74 69 6e 67 0a 2a 2a 20 74 61 62 6c 65 20 61  rting.** table a
1dbf0 6e 64 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 73 20  nd column names 
1dc00 69 6e 74 6f 20 61 20 63 6f 6e 73 74 72 75 63 74  into a construct
1dc10 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ed SQL statement
1dc20 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 22 25  ..**.** ^(The "%
1dc30 7a 22 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70  z" formatting op
1dc40 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20  tion works like 
1dc50 22 25 73 22 20 62 75 74 20 77 69 74 68 20 74 68  "%s" but with th
1dc60 65 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 20 74 68  e.** addition th
1dc70 61 74 20 61 66 74 65 72 20 74 68 65 20 73 74 72  at after the str
1dc80 69 6e 67 20 68 61 73 20 62 65 65 6e 20 72 65 61  ing has been rea
1dc90 64 20 61 6e 64 20 63 6f 70 69 65 64 20 69 6e 74  d and copied int
1dca0 6f 0a 2a 2a 20 74 68 65 20 72 65 73 75 6c 74 2c  o.** the result,
1dcb0 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
1dcc0 5d 20 69 73 20 63 61 6c 6c 65 64 20 6f 6e 20 74  ] is called on t
1dcd0 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67 2e  he input string.
1dce0 29 5e 0a 2a 2f 0a 63 68 61 72 20 2a 73 71 6c 69  )^.*/.char *sqli
1dcf0 74 65 33 5f 6d 70 72 69 6e 74 66 28 63 6f 6e 73  te3_mprintf(cons
1dd00 74 20 63 68 61 72 2a 2c 2e 2e 2e 29 3b 0a 63 68  t char*,...);.ch
1dd10 61 72 20 2a 73 71 6c 69 74 65 33 5f 76 6d 70 72  ar *sqlite3_vmpr
1dd20 69 6e 74 66 28 63 6f 6e 73 74 20 63 68 61 72 2a  intf(const char*
1dd30 2c 20 76 61 5f 6c 69 73 74 29 3b 0a 63 68 61 72  , va_list);.char
1dd40 20 2a 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e   *sqlite3_snprin
1dd50 74 66 28 69 6e 74 2c 63 68 61 72 2a 2c 63 6f 6e  tf(int,char*,con
1dd60 73 74 20 63 68 61 72 2a 2c 20 2e 2e 2e 29 3b 0a  st char*, ...);.
1dd70 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 76 73  char *sqlite3_vs
1dd80 6e 70 72 69 6e 74 66 28 69 6e 74 2c 63 68 61 72  nprintf(int,char
1dd90 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 76  *,const char*, v
1dda0 61 5f 6c 69 73 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  a_list);../*.** 
1ddb0 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79  CAPI3REF: Memory
1ddc0 20 41 6c 6c 6f 63 61 74 69 6f 6e 20 53 75 62 73   Allocation Subs
1ddd0 79 73 74 65 6d 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ystem.**.** The 
1dde0 53 51 4c 69 74 65 20 63 6f 72 65 20 75 73 65 73  SQLite core uses
1ddf0 20 74 68 65 73 65 20 74 68 72 65 65 20 72 6f 75   these three rou
1de00 74 69 6e 65 73 20 66 6f 72 20 61 6c 6c 20 6f 66  tines for all of
1de10 20 69 74 73 20 6f 77 6e 0a 2a 2a 20 69 6e 74 65   its own.** inte
1de20 72 6e 61 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  rnal memory allo
1de30 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e 20 22 43  cation needs. "C
1de40 6f 72 65 22 20 69 6e 20 74 68 65 20 70 72 65 76  ore" in the prev
1de50 69 6f 75 73 20 73 65 6e 74 65 6e 63 65 0a 2a 2a  ious sentence.**
1de60 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64   does not includ
1de70 65 20 6f 70 65 72 61 74 69 6e 67 2d 73 79 73 74  e operating-syst
1de80 65 6d 20 73 70 65 63 69 66 69 63 20 56 46 53 20  em specific VFS 
1de90 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20  implementation. 
1dea0 20 54 68 65 0a 2a 2a 20 57 69 6e 64 6f 77 73 20   The.** Windows 
1deb0 56 46 53 20 75 73 65 73 20 6e 61 74 69 76 65 20  VFS uses native 
1dec0 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 65  malloc() and fre
1ded0 65 28 29 20 66 6f 72 20 73 6f 6d 65 20 6f 70 65  e() for some ope
1dee0 72 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e  rations..**.** ^
1def0 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  The sqlite3_mall
1df00 6f 63 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74  oc() routine ret
1df10 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
1df20 6f 20 61 20 62 6c 6f 63 6b 0a 2a 2a 20 6f 66 20  o a block.** of 
1df30 6d 65 6d 6f 72 79 20 61 74 20 6c 65 61 73 74 20  memory at least 
1df40 4e 20 62 79 74 65 73 20 69 6e 20 6c 65 6e 67 74  N bytes in lengt
1df50 68 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74 68  h, where N is th
1df60 65 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20  e parameter..** 
1df70 5e 49 66 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  ^If sqlite3_mall
1df80 6f 63 28 29 20 69 73 20 75 6e 61 62 6c 65 20 74  oc() is unable t
1df90 6f 20 6f 62 74 61 69 6e 20 73 75 66 66 69 63 69  o obtain suffici
1dfa0 65 6e 74 20 66 72 65 65 0a 2a 2a 20 6d 65 6d 6f  ent free.** memo
1dfb0 72 79 2c 20 69 74 20 72 65 74 75 72 6e 73 20 61  ry, it returns a
1dfc0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20   NULL pointer.  
1dfd0 5e 49 66 20 74 68 65 20 70 61 72 61 6d 65 74 65  ^If the paramete
1dfe0 72 20 4e 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65  r N to.** sqlite
1dff0 33 5f 6d 61 6c 6c 6f 63 28 29 20 69 73 20 7a 65  3_malloc() is ze
1e000 72 6f 20 6f 72 20 6e 65 67 61 74 69 76 65 20 74  ro or negative t
1e010 68 65 6e 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  hen sqlite3_mall
1e020 6f 63 28 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20  oc() returns.** 
1e030 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a  a NULL pointer..
1e040 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
1e050 65 33 5f 6d 61 6c 6c 6f 63 36 34 28 4e 29 20 72  e3_malloc64(N) r
1e060 6f 75 74 69 6e 65 20 77 6f 72 6b 73 20 6a 75 73  outine works jus
1e070 74 20 6c 69 6b 65 0a 2a 2a 20 73 71 6c 69 74 65  t like.** sqlite
1e080 33 5f 6d 61 6c 6c 6f 63 28 4e 29 20 65 78 63 65  3_malloc(N) exce
1e090 70 74 20 74 68 61 74 20 4e 20 69 73 20 61 6e 20  pt that N is an 
1e0a0 75 6e 73 69 67 6e 65 64 20 36 34 2d 62 69 74 20  unsigned 64-bit 
1e0b0 69 6e 74 65 67 65 72 20 69 6e 73 74 65 61 64 0a  integer instead.
1e0c0 2a 2a 20 6f 66 20 61 20 73 69 67 6e 65 64 20 33  ** of a signed 3
1e0d0 32 2d 62 69 74 20 69 6e 74 65 67 65 72 2e 0a 2a  2-bit integer..*
1e0e0 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 73 71  *.** ^Calling sq
1e0f0 6c 69 74 65 33 5f 66 72 65 65 28 29 20 77 69 74  lite3_free() wit
1e100 68 20 61 20 70 6f 69 6e 74 65 72 20 70 72 65 76  h a pointer prev
1e110 69 6f 75 73 6c 79 20 72 65 74 75 72 6e 65 64 0a  iously returned.
1e120 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 6d 61  ** by sqlite3_ma
1e130 6c 6c 6f 63 28 29 20 6f 72 20 73 71 6c 69 74 65  lloc() or sqlite
1e140 33 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65 6c 65  3_realloc() rele
1e150 61 73 65 73 20 74 68 61 74 20 6d 65 6d 6f 72 79  ases that memory
1e160 20 73 6f 0a 2a 2a 20 74 68 61 74 20 69 74 20 6d   so.** that it m
1e170 69 67 68 74 20 62 65 20 72 65 75 73 65 64 2e 20  ight be reused. 
1e180 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 66 72   ^The sqlite3_fr
1e190 65 65 28 29 20 72 6f 75 74 69 6e 65 20 69 73 0a  ee() routine is.
1e1a0 2a 2a 20 61 20 6e 6f 2d 6f 70 20 69 66 20 69 73  ** a no-op if is
1e1b0 20 63 61 6c 6c 65 64 20 77 69 74 68 20 61 20 4e   called with a N
1e1c0 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 50 61  ULL pointer.  Pa
1e1d0 73 73 69 6e 67 20 61 20 4e 55 4c 4c 20 70 6f 69  ssing a NULL poi
1e1e0 6e 74 65 72 0a 2a 2a 20 74 6f 20 73 71 6c 69 74  nter.** to sqlit
1e1f0 65 33 5f 66 72 65 65 28 29 20 69 73 20 68 61 72  e3_free() is har
1e200 6d 6c 65 73 73 2e 20 20 41 66 74 65 72 20 62 65  mless.  After be
1e210 69 6e 67 20 66 72 65 65 64 2c 20 6d 65 6d 6f 72  ing freed, memor
1e220 79 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e 65 69 74  y.** should neit
1e230 68 65 72 20 62 65 20 72 65 61 64 20 6e 6f 72 20  her be read nor 
1e240 77 72 69 74 74 65 6e 2e 20 20 45 76 65 6e 20 72  written.  Even r
1e250 65 61 64 69 6e 67 20 70 72 65 76 69 6f 75 73 6c  eading previousl
1e260 79 20 66 72 65 65 64 0a 2a 2a 20 6d 65 6d 6f 72  y freed.** memor
1e270 79 20 6d 69 67 68 74 20 72 65 73 75 6c 74 20 69  y might result i
1e280 6e 20 61 20 73 65 67 6d 65 6e 74 61 74 69 6f 6e  n a segmentation
1e290 20 66 61 75 6c 74 20 6f 72 20 6f 74 68 65 72 20   fault or other 
1e2a0 73 65 76 65 72 65 20 65 72 72 6f 72 2e 0a 2a 2a  severe error..**
1e2b0 20 4d 65 6d 6f 72 79 20 63 6f 72 72 75 70 74 69   Memory corrupti
1e2c0 6f 6e 2c 20 61 20 73 65 67 6d 65 6e 74 61 74 69  on, a segmentati
1e2d0 6f 6e 20 66 61 75 6c 74 2c 20 6f 72 20 6f 74 68  on fault, or oth
1e2e0 65 72 20 73 65 76 65 72 65 20 65 72 72 6f 72 0a  er severe error.
1e2f0 2a 2a 20 6d 69 67 68 74 20 72 65 73 75 6c 74 20  ** might result 
1e300 69 66 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28  if sqlite3_free(
1e310 29 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74 68  ) is called with
1e320 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e   a non-NULL poin
1e330 74 65 72 20 74 68 61 74 0a 2a 2a 20 77 61 73 20  ter that.** was 
1e340 6e 6f 74 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  not obtained fro
1e350 6d 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  m sqlite3_malloc
1e360 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65  () or sqlite3_re
1e370 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e  alloc()..**.** ^
1e380 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 61 6c  The sqlite3_real
1e390 6c 6f 63 28 58 2c 4e 29 20 69 6e 74 65 72 66 61  loc(X,N) interfa
1e3a0 63 65 20 61 74 74 65 6d 70 74 73 20 74 6f 20 72  ce attempts to r
1e3b0 65 73 69 7a 65 20 61 0a 2a 2a 20 70 72 69 6f 72  esize a.** prior
1e3c0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
1e3d0 6f 6e 20 58 20 74 6f 20 62 65 20 61 74 20 6c 65  on X to be at le
1e3e0 61 73 74 20 4e 20 62 79 74 65 73 2e 0a 2a 2a 20  ast N bytes..** 
1e3f0 5e 49 66 20 74 68 65 20 58 20 70 61 72 61 6d 65  ^If the X parame
1e400 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72  ter to sqlite3_r
1e410 65 61 6c 6c 6f 63 28 58 2c 4e 29 0a 2a 2a 20 69  ealloc(X,N).** i
1e420 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
1e430 20 74 68 65 6e 20 69 74 73 20 62 65 68 61 76 69   then its behavi
1e440 6f 72 20 69 73 20 69 64 65 6e 74 69 63 61 6c 20  or is identical 
1e450 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71  to calling.** sq
1e460 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29 2e  lite3_malloc(N).
1e470 0a 2a 2a 20 5e 49 66 20 74 68 65 20 4e 20 70 61  .** ^If the N pa
1e480 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
1e490 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 20  e3_realloc(X,N) 
1e4a0 69 73 20 7a 65 72 6f 20 6f 72 0a 2a 2a 20 6e 65  is zero or.** ne
1e4b0 67 61 74 69 76 65 20 74 68 65 6e 20 74 68 65 20  gative then the 
1e4c0 62 65 68 61 76 69 6f 72 20 69 73 20 65 78 61 63  behavior is exac
1e4d0 74 6c 79 20 74 68 65 20 73 61 6d 65 20 61 73 20  tly the same as 
1e4e0 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69 74  calling.** sqlit
1e4f0 65 33 5f 66 72 65 65 28 58 29 2e 0a 2a 2a 20 5e  e3_free(X)..** ^
1e500 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
1e510 58 2c 4e 29 20 72 65 74 75 72 6e 73 20 61 20 70  X,N) returns a p
1e520 6f 69 6e 74 65 72 20 74 6f 20 61 20 6d 65 6d 6f  ointer to a memo
1e530 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a  ry allocation.**
1e540 20 6f 66 20 61 74 20 6c 65 61 73 74 20 4e 20 62   of at least N b
1e550 79 74 65 73 20 69 6e 20 73 69 7a 65 20 6f 72 20  ytes in size or 
1e560 4e 55 4c 4c 20 69 66 20 69 6e 73 75 66 66 69 63  NULL if insuffic
1e570 69 65 6e 74 20 6d 65 6d 6f 72 79 20 69 73 20 61  ient memory is a
1e580 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20 5e 49 66  vailable..** ^If
1e590 20 4d 20 69 73 20 74 68 65 20 73 69 7a 65 20 6f   M is the size o
1e5a0 66 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f  f the prior allo
1e5b0 63 61 74 69 6f 6e 2c 20 74 68 65 6e 20 6d 69 6e  cation, then min
1e5c0 28 4e 2c 4d 29 20 62 79 74 65 73 0a 2a 2a 20 6f  (N,M) bytes.** o
1e5d0 66 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f  f the prior allo
1e5e0 63 61 74 69 6f 6e 20 61 72 65 20 63 6f 70 69 65  cation are copie
1e5f0 64 20 69 6e 74 6f 20 74 68 65 20 62 65 67 69 6e  d into the begin
1e600 6e 69 6e 67 20 6f 66 20 62 75 66 66 65 72 20 72  ning of buffer r
1e610 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71  eturned.** by sq
1e620 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c  lite3_realloc(X,
1e630 4e 29 20 61 6e 64 20 74 68 65 20 70 72 69 6f 72  N) and the prior
1e640 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 73 20 66   allocation is f
1e650 72 65 65 64 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c  reed..** ^If sql
1e660 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e  ite3_realloc(X,N
1e670 29 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 20 61  ) returns NULL a
1e680 6e 64 20 4e 20 69 73 20 70 6f 73 69 74 69 76 65  nd N is positive
1e690 2c 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 70 72  , then the.** pr
1e6a0 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69  ior allocation i
1e6b0 73 20 6e 6f 74 20 66 72 65 65 64 2e 0a 2a 2a 0a  s not freed..**.
1e6c0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
1e6d0 72 65 61 6c 6c 6f 63 36 34 28 58 2c 4e 29 20 69  realloc64(X,N) i
1e6e0 6e 74 65 72 66 61 63 65 73 20 77 6f 72 6b 73 20  nterfaces works 
1e6f0 74 68 65 20 73 61 6d 65 20 61 73 0a 2a 2a 20 73  the same as.** s
1e700 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58  qlite3_realloc(X
1e710 2c 4e 29 20 65 78 63 65 70 74 20 74 68 61 74 20  ,N) except that 
1e720 4e 20 69 73 20 61 20 36 34 2d 62 69 74 20 75 6e  N is a 64-bit un
1e730 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 20 69  signed integer i
1e740 6e 73 74 65 61 64 0a 2a 2a 20 6f 66 20 61 20 33  nstead.** of a 3
1e750 32 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74  2-bit signed int
1e760 65 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  eger..**.** ^If 
1e770 58 20 69 73 20 61 20 6d 65 6d 6f 72 79 20 61 6c  X is a memory al
1e780 6c 6f 63 61 74 69 6f 6e 20 70 72 65 76 69 6f 75  location previou
1e790 73 6c 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  sly obtained fro
1e7a0 6d 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  m sqlite3_malloc
1e7b0 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d  (),.** sqlite3_m
1e7c0 61 6c 6c 6f 63 36 34 28 29 2c 20 73 71 6c 69 74  alloc64(), sqlit
1e7d0 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2c 20 6f 72  e3_realloc(), or
1e7e0 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
1e7f0 36 34 28 29 2c 20 74 68 65 6e 0a 2a 2a 20 73 71  64(), then.** sq
1e800 6c 69 74 65 33 5f 6d 73 69 7a 65 28 58 29 20 72  lite3_msize(X) r
1e810 65 74 75 72 6e 73 20 74 68 65 20 73 69 7a 65 20  eturns the size 
1e820 6f 66 20 74 68 61 74 20 6d 65 6d 6f 72 79 20 61  of that memory a
1e830 6c 6c 6f 63 61 74 69 6f 6e 20 69 6e 20 62 79 74  llocation in byt
1e840 65 73 2e 0a 2a 2a 20 5e 54 68 65 20 76 61 6c 75  es..** ^The valu
1e850 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71  e returned by sq
1e860 6c 69 74 65 33 5f 6d 73 69 7a 65 28 58 29 20 6d  lite3_msize(X) m
1e870 69 67 68 74 20 62 65 20 6c 61 72 67 65 72 20 74  ight be larger t
1e880 68 61 6e 20 74 68 65 20 6e 75 6d 62 65 72 0a 2a  han the number.*
1e890 2a 20 6f 66 20 62 79 74 65 73 20 72 65 71 75 65  * of bytes reque
1e8a0 73 74 65 64 20 77 68 65 6e 20 58 20 77 61 73 20  sted when X was 
1e8b0 61 6c 6c 6f 63 61 74 65 64 2e 20 20 5e 49 66 20  allocated.  ^If 
1e8c0 58 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  X is a NULL poin
1e8d0 74 65 72 20 74 68 65 6e 0a 2a 2a 20 73 71 6c 69  ter then.** sqli
1e8e0 74 65 33 5f 6d 73 69 7a 65 28 58 29 20 72 65 74  te3_msize(X) ret
1e8f0 75 72 6e 73 20 7a 65 72 6f 2e 20 20 49 66 20 58  urns zero.  If X
1e900 20 70 6f 69 6e 74 73 20 74 6f 20 73 6f 6d 65 74   points to somet
1e910 68 69 6e 67 20 74 68 61 74 20 69 73 20 6e 6f 74  hing that is not
1e920 0a 2a 2a 20 74 68 65 20 62 65 67 69 6e 6e 69 6e  .** the beginnin
1e930 67 20 6f 66 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  g of memory allo
1e940 63 61 74 69 6f 6e 2c 20 6f 72 20 69 66 20 69 74  cation, or if it
1e950 20 70 6f 69 6e 74 73 20 74 6f 20 61 20 66 6f 72   points to a for
1e960 6d 65 72 6c 79 0a 2a 2a 20 76 61 6c 69 64 20 6d  merly.** valid m
1e970 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
1e980 20 74 68 61 74 20 68 61 73 20 6e 6f 77 20 62 65   that has now be
1e990 65 6e 20 66 72 65 65 64 2c 20 74 68 65 6e 20 74  en freed, then t
1e9a0 68 65 20 62 65 68 61 76 69 6f 72 0a 2a 2a 20 6f  he behavior.** o
1e9b0 66 20 73 71 6c 69 74 65 33 5f 6d 73 69 7a 65 28  f sqlite3_msize(
1e9c0 58 29 20 69 73 20 75 6e 64 65 66 69 6e 65 64 20  X) is undefined 
1e9d0 61 6e 64 20 70 6f 73 73 69 62 6c 79 20 68 61 72  and possibly har
1e9e0 6d 66 75 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  mful..**.** ^The
1e9f0 20 6d 65 6d 6f 72 79 20 72 65 74 75 72 6e 65 64   memory returned
1ea00 20 62 79 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c   by sqlite3_mall
1ea10 6f 63 28 29 2c 20 73 71 6c 69 74 65 33 5f 72 65  oc(), sqlite3_re
1ea20 61 6c 6c 6f 63 28 29 2c 0a 2a 2a 20 73 71 6c 69  alloc(),.** sqli
1ea30 74 65 33 5f 6d 61 6c 6c 6f 63 36 34 28 29 2c 20  te3_malloc64(), 
1ea40 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 61 6c  and sqlite3_real
1ea50 6c 6f 63 36 34 28 29 0a 2a 2a 20 69 73 20 61 6c  loc64().** is al
1ea60 77 61 79 73 20 61 6c 69 67 6e 65 64 20 74 6f 20  ways aligned to 
1ea70 61 74 20 6c 65 61 73 74 20 61 6e 20 38 20 62 79  at least an 8 by
1ea80 74 65 20 62 6f 75 6e 64 61 72 79 2c 20 6f 72 20  te boundary, or 
1ea90 74 6f 20 61 0a 2a 2a 20 34 20 62 79 74 65 20 62  to a.** 4 byte b
1eaa0 6f 75 6e 64 61 72 79 20 69 66 20 74 68 65 20 5b  oundary if the [
1eab0 53 51 4c 49 54 45 5f 34 5f 42 59 54 45 5f 41 4c  SQLITE_4_BYTE_AL
1eac0 49 47 4e 45 44 5f 4d 41 4c 4c 4f 43 5d 20 63 6f  IGNED_MALLOC] co
1ead0 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70  mpile-time.** op
1eae0 74 69 6f 6e 20 69 73 20 75 73 65 64 2e 0a 2a 2a  tion is used..**
1eaf0 0a 2a 2a 20 49 6e 20 53 51 4c 69 74 65 20 76 65  .** In SQLite ve
1eb00 72 73 69 6f 6e 20 33 2e 35 2e 30 20 61 6e 64 20  rsion 3.5.0 and 
1eb10 33 2e 35 2e 31 2c 20 69 74 20 77 61 73 20 70 6f  3.5.1, it was po
1eb20 73 73 69 62 6c 65 20 74 6f 20 64 65 66 69 6e 65  ssible to define
1eb30 0a 2a 2a 20 74 68 65 20 53 51 4c 49 54 45 5f 4f  .** the SQLITE_O
1eb40 4d 49 54 5f 4d 45 4d 4f 52 59 5f 41 4c 4c 4f 43  MIT_MEMORY_ALLOC
1eb50 41 54 49 4f 4e 20 77 68 69 63 68 20 77 6f 75 6c  ATION which woul
1eb60 64 20 63 61 75 73 65 20 74 68 65 20 62 75 69 6c  d cause the buil
1eb70 74 2d 69 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e  t-in.** implemen
1eb80 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 73 65 20  tation of these 
1eb90 72 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20 6f  routines to be o
1eba0 6d 69 74 74 65 64 2e 20 20 54 68 61 74 20 63 61  mitted.  That ca
1ebb0 70 61 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20 6e  pability.** is n
1ebc0 6f 20 6c 6f 6e 67 65 72 20 70 72 6f 76 69 64 65  o longer provide
1ebd0 64 2e 20 20 4f 6e 6c 79 20 62 75 69 6c 74 2d 69  d.  Only built-i
1ebe0 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  n memory allocat
1ebf0 6f 72 73 20 63 61 6e 20 62 65 20 75 73 65 64 2e  ors can be used.
1ec00 0a 2a 2a 0a 2a 2a 20 50 72 69 6f 72 20 74 6f 20  .**.** Prior to 
1ec10 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33  SQLite version 3
1ec20 2e 37 2e 31 30 2c 20 74 68 65 20 57 69 6e 64 6f  .7.10, the Windo
1ec30 77 73 20 4f 53 20 69 6e 74 65 72 66 61 63 65 20  ws OS interface 
1ec40 6c 61 79 65 72 20 63 61 6c 6c 65 64 0a 2a 2a 20  layer called.** 
1ec50 74 68 65 20 73 79 73 74 65 6d 20 6d 61 6c 6c 6f  the system mallo
1ec60 63 28 29 20 61 6e 64 20 66 72 65 65 28 29 20 64  c() and free() d
1ec70 69 72 65 63 74 6c 79 20 77 68 65 6e 20 63 6f 6e  irectly when con
1ec80 76 65 72 74 69 6e 67 0a 2a 2a 20 66 69 6c 65 6e  verting.** filen
1ec90 61 6d 65 73 20 62 65 74 77 65 65 6e 20 74 68 65  ames between the
1eca0 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 20   UTF-8 encoding 
1ecb0 75 73 65 64 20 62 79 20 53 51 4c 69 74 65 0a 2a  used by SQLite.*
1ecc0 2a 20 61 6e 64 20 77 68 61 74 65 76 65 72 20 66  * and whatever f
1ecd0 69 6c 65 6e 61 6d 65 20 65 6e 63 6f 64 69 6e 67  ilename encoding
1ece0 20 69 73 20 75 73 65 64 20 62 79 20 74 68 65 20   is used by the 
1ecf0 70 61 72 74 69 63 75 6c 61 72 20 57 69 6e 64 6f  particular Windo
1ed00 77 73 0a 2a 2a 20 69 6e 73 74 61 6c 6c 61 74 69  ws.** installati
1ed10 6f 6e 2e 20 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f  on.  Memory allo
1ed20 63 61 74 69 6f 6e 20 65 72 72 6f 72 73 20 77 65  cation errors we
1ed30 72 65 20 64 65 74 65 63 74 65 64 2c 20 62 75 74  re detected, but
1ed40 0a 2a 2a 20 74 68 65 79 20 77 65 72 65 20 72 65  .** they were re
1ed50 70 6f 72 74 65 64 20 62 61 63 6b 20 61 73 20 5b  ported back as [
1ed60 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5d  SQLITE_CANTOPEN]
1ed70 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49   or.** [SQLITE_I
1ed80 4f 45 52 52 5d 20 72 61 74 68 65 72 20 74 68 61  OERR] rather tha
1ed90 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d  n [SQLITE_NOMEM]
1eda0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 6f 69 6e  ..**.** The poin
1edb0 74 65 72 20 61 72 67 75 6d 65 6e 74 73 20 74 6f  ter arguments to
1edc0 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
1edd0 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72  ] and [sqlite3_r
1ede0 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 6d 75 73  ealloc()].** mus
1edf0 74 20 62 65 20 65 69 74 68 65 72 20 4e 55 4c 4c  t be either NULL
1ee00 20 6f 72 20 65 6c 73 65 20 70 6f 69 6e 74 65 72   or else pointer
1ee10 73 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  s obtained from 
1ee20 61 20 70 72 69 6f 72 0a 2a 2a 20 69 6e 76 6f 63  a prior.** invoc
1ee30 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65  ation of [sqlite
1ee40 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6f 72 20 5b  3_malloc()] or [
1ee50 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
1ee60 29 5d 20 74 68 61 74 20 68 61 76 65 0a 2a 2a 20  )] that have.** 
1ee70 6e 6f 74 20 79 65 74 20 62 65 65 6e 20 72 65 6c  not yet been rel
1ee80 65 61 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  eased..**.** The
1ee90 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73   application mus
1eea0 74 20 6e 6f 74 20 72 65 61 64 20 6f 72 20 77 72  t not read or wr
1eeb0 69 74 65 20 61 6e 79 20 70 61 72 74 20 6f 66 0a  ite any part of.
1eec0 2a 2a 20 61 20 62 6c 6f 63 6b 20 6f 66 20 6d 65  ** a block of me
1eed0 6d 6f 72 79 20 61 66 74 65 72 20 69 74 20 68 61  mory after it ha
1eee0 73 20 62 65 65 6e 20 72 65 6c 65 61 73 65 64 20  s been released 
1eef0 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65  using.** [sqlite
1ef00 33 5f 66 72 65 65 28 29 5d 20 6f 72 20 5b 73 71  3_free()] or [sq
1ef10 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d  lite3_realloc()]
1ef20 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74  ..*/.void *sqlit
1ef30 65 33 5f 6d 61 6c 6c 6f 63 28 69 6e 74 29 3b 0a  e3_malloc(int);.
1ef40 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 6d 61  void *sqlite3_ma
1ef50 6c 6c 6f 63 36 34 28 73 71 6c 69 74 65 33 5f 75  lloc64(sqlite3_u
1ef60 69 6e 74 36 34 29 3b 0a 76 6f 69 64 20 2a 73 71  int64);.void *sq
1ef70 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 76 6f  lite3_realloc(vo
1ef80 69 64 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20  id*, int);.void 
1ef90 2a 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63  *sqlite3_realloc
1efa0 36 34 28 76 6f 69 64 2a 2c 20 73 71 6c 69 74 65  64(void*, sqlite
1efb0 33 5f 75 69 6e 74 36 34 29 3b 0a 76 6f 69 64 20  3_uint64);.void 
1efc0 73 71 6c 69 74 65 33 5f 66 72 65 65 28 76 6f 69  sqlite3_free(voi
1efd0 64 2a 29 3b 0a 73 71 6c 69 74 65 33 5f 75 69 6e  d*);.sqlite3_uin
1efe0 74 36 34 20 73 71 6c 69 74 65 33 5f 6d 73 69 7a  t64 sqlite3_msiz
1eff0 65 28 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  e(void*);../*.**
1f000 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72   CAPI3REF: Memor
1f010 79 20 41 6c 6c 6f 63 61 74 6f 72 20 53 74 61 74  y Allocator Stat
1f020 69 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20 53 51 4c  istics.**.** SQL
1f030 69 74 65 20 70 72 6f 76 69 64 65 73 20 74 68 65  ite provides the
1f040 73 65 20 74 77 6f 20 69 6e 74 65 72 66 61 63 65  se two interface
1f050 73 20 66 6f 72 20 72 65 70 6f 72 74 69 6e 67 20  s for reporting 
1f060 6f 6e 20 74 68 65 20 73 74 61 74 75 73 0a 2a 2a  on the status.**
1f070 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
1f080 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 20 5b 73 71 6c  _malloc()], [sql
1f090 69 74 65 33 5f 66 72 65 65 28 29 5d 2c 20 61 6e  ite3_free()], an
1f0a0 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  d [sqlite3_reall
1f0b0 6f 63 28 29 5d 0a 2a 2a 20 72 6f 75 74 69 6e 65  oc()].** routine
1f0c0 73 2c 20 77 68 69 63 68 20 66 6f 72 6d 20 74 68  s, which form th
1f0d0 65 20 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72  e built-in memor
1f0e0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62  y allocation sub
1f0f0 73 79 73 74 65 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 54  system..**.** ^T
1f100 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  he [sqlite3_memo
1f110 72 79 5f 75 73 65 64 28 29 5d 20 72 6f 75 74 69  ry_used()] routi
1f120 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e  ne returns the n
1f130 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 0a 2a  umber of bytes.*
1f140 2a 20 6f 66 20 6d 65 6d 6f 72 79 20 63 75 72 72  * of memory curr
1f150 65 6e 74 6c 79 20 6f 75 74 73 74 61 6e 64 69 6e  ently outstandin
1f160 67 20 28 6d 61 6c 6c 6f 63 65 64 20 62 75 74 20  g (malloced but 
1f170 6e 6f 74 20 66 72 65 65 64 29 2e 0a 2a 2a 20 5e  not freed)..** ^
1f180 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  The [sqlite3_mem
1f190 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d  ory_highwater()]
1f1a0 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
1f1b0 20 74 68 65 20 6d 61 78 69 6d 75 6d 0a 2a 2a 20   the maximum.** 
1f1c0 76 61 6c 75 65 20 6f 66 20 5b 73 71 6c 69 74 65  value of [sqlite
1f1d0 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d  3_memory_used()]
1f1e0 20 73 69 6e 63 65 20 74 68 65 20 68 69 67 68 2d   since the high-
1f1f0 77 61 74 65 72 20 6d 61 72 6b 0a 2a 2a 20 77 61  water mark.** wa
1f200 73 20 6c 61 73 74 20 72 65 73 65 74 2e 20 20 5e  s last reset.  ^
1f210 54 68 65 20 76 61 6c 75 65 73 20 72 65 74 75 72  The values retur
1f220 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  ned by [sqlite3_
1f230 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 61  memory_used()] a
1f240 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d  nd.** [sqlite3_m
1f250 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28  emory_highwater(
1f260 29 5d 20 69 6e 63 6c 75 64 65 20 61 6e 79 20 6f  )] include any o
1f270 76 65 72 68 65 61 64 0a 2a 2a 20 61 64 64 65 64  verhead.** added
1f280 20 62 79 20 53 51 4c 69 74 65 20 69 6e 20 69 74   by SQLite in it
1f290 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  s implementation
1f2a0 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c   of [sqlite3_mal
1f2b0 6c 6f 63 28 29 5d 2c 0a 2a 2a 20 62 75 74 20 6e  loc()],.** but n
1f2c0 6f 74 20 6f 76 65 72 68 65 61 64 20 61 64 64 65  ot overhead adde
1f2d0 64 20 62 79 20 74 68 65 20 61 6e 79 20 75 6e 64  d by the any und
1f2e0 65 72 6c 79 69 6e 67 20 73 79 73 74 65 6d 20 6c  erlying system l
1f2f0 69 62 72 61 72 79 0a 2a 2a 20 72 6f 75 74 69 6e  ibrary.** routin
1f300 65 73 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33  es that [sqlite3
1f310 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6d 61 79 20 63  _malloc()] may c
1f320 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  all..**.** ^The 
1f330 6d 65 6d 6f 72 79 20 68 69 67 68 2d 77 61 74 65  memory high-wate
1f340 72 20 6d 61 72 6b 20 69 73 20 72 65 73 65 74 20  r mark is reset 
1f350 74 6f 20 74 68 65 20 63 75 72 72 65 6e 74 20 76  to the current v
1f360 61 6c 75 65 20 6f 66 0a 2a 2a 20 5b 73 71 6c 69  alue of.** [sqli
1f370 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28  te3_memory_used(
1f380 29 5d 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69  )] if and only i
1f390 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20  f the parameter 
1f3a0 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d  to.** [sqlite3_m
1f3b0 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28  emory_highwater(
1f3c0 29 5d 20 69 73 20 74 72 75 65 2e 20 20 5e 54 68  )] is true.  ^Th
1f3d0 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  e value returned
1f3e0 0a 2a 2a 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  .** by [sqlite3_
1f3f0 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72  memory_highwater
1f400 28 31 29 5d 20 69 73 20 74 68 65 20 68 69 67 68  (1)] is the high
1f410 2d 77 61 74 65 72 20 6d 61 72 6b 0a 2a 2a 20 70  -water mark.** p
1f420 72 69 6f 72 20 74 6f 20 74 68 65 20 72 65 73 65  rior to the rese
1f430 74 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 69 6e  t..*/.sqlite3_in
1f440 74 36 34 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  t64 sqlite3_memo
1f450 72 79 5f 75 73 65 64 28 76 6f 69 64 29 3b 0a 73  ry_used(void);.s
1f460 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c  qlite3_int64 sql
1f470 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68  ite3_memory_high
1f480 77 61 74 65 72 28 69 6e 74 20 72 65 73 65 74 46  water(int resetF
1f490 6c 61 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  lag);../*.** CAP
1f4a0 49 33 52 45 46 3a 20 50 73 65 75 64 6f 2d 52 61  I3REF: Pseudo-Ra
1f4b0 6e 64 6f 6d 20 4e 75 6d 62 65 72 20 47 65 6e 65  ndom Number Gene
1f4c0 72 61 74 6f 72 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  rator.**.** SQLi
1f4d0 74 65 20 63 6f 6e 74 61 69 6e 73 20 61 20 68 69  te contains a hi
1f4e0 67 68 2d 71 75 61 6c 69 74 79 20 70 73 65 75 64  gh-quality pseud
1f4f0 6f 2d 72 61 6e 64 6f 6d 20 6e 75 6d 62 65 72 20  o-random number 
1f500 67 65 6e 65 72 61 74 6f 72 20 28 50 52 4e 47 29  generator (PRNG)
1f510 20 75 73 65 64 20 74 6f 0a 2a 2a 20 73 65 6c 65   used to.** sele
1f520 63 74 20 72 61 6e 64 6f 6d 20 5b 52 4f 57 49 44  ct random [ROWID
1f530 20 7c 20 52 4f 57 49 44 73 5d 20 77 68 65 6e 20   | ROWIDs] when 
1f540 69 6e 73 65 72 74 69 6e 67 20 6e 65 77 20 72 65  inserting new re
1f550 63 6f 72 64 73 20 69 6e 74 6f 20 61 20 74 61 62  cords into a tab
1f560 6c 65 20 74 68 61 74 0a 2a 2a 20 61 6c 72 65 61  le that.** alrea
1f570 64 79 20 75 73 65 73 20 74 68 65 20 6c 61 72 67  dy uses the larg
1f580 65 73 74 20 70 6f 73 73 69 62 6c 65 20 5b 52 4f  est possible [RO
1f590 57 49 44 5d 2e 20 20 54 68 65 20 50 52 4e 47 20  WID].  The PRNG 
1f5a0 69 73 20 61 6c 73 6f 20 75 73 65 64 20 66 6f 72  is also used for
1f5b0 0a 2a 2a 20 74 68 65 20 62 75 69 6c 64 2d 69 6e  .** the build-in
1f5c0 20 72 61 6e 64 6f 6d 28 29 20 61 6e 64 20 72 61   random() and ra
1f5d0 6e 64 6f 6d 62 6c 6f 62 28 29 20 53 51 4c 20 66  ndomblob() SQL f
1f5e0 75 6e 63 74 69 6f 6e 73 2e 20 20 54 68 69 73 20  unctions.  This 
1f5f0 69 6e 74 65 72 66 61 63 65 20 61 6c 6c 6f 77 73  interface allows
1f600 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  .** applications
1f610 20 74 6f 20 61 63 63 65 73 73 20 74 68 65 20 73   to access the s
1f620 61 6d 65 20 50 52 4e 47 20 66 6f 72 20 6f 74 68  ame PRNG for oth
1f630 65 72 20 70 75 72 70 6f 73 65 73 2e 0a 2a 2a 0a  er purposes..**.
1f640 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 6f 20 74 68  ** ^A call to th
1f650 69 73 20 72 6f 75 74 69 6e 65 20 73 74 6f 72 65  is routine store
1f660 73 20 4e 20 62 79 74 65 73 20 6f 66 20 72 61 6e  s N bytes of ran
1f670 64 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 62 75 66  domness into buf
1f680 66 65 72 20 50 2e 0a 2a 2a 20 5e 54 68 65 20 50  fer P..** ^The P
1f690 20 70 61 72 61 6d 65 74 65 72 20 63 61 6e 20 62   parameter can b
1f6a0 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  e a NULL pointer
1f6b0 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 69 73  ..**.** ^If this
1f6c0 20 72 6f 75 74 69 6e 65 20 68 61 73 20 6e 6f 74   routine has not
1f6d0 20 62 65 65 6e 20 70 72 65 76 69 6f 75 73 6c 79   been previously
1f6e0 20 63 61 6c 6c 65 64 20 6f 72 20 69 66 20 74 68   called or if th
1f6f0 65 20 70 72 65 76 69 6f 75 73 0a 2a 2a 20 63 61  e previous.** ca
1f700 6c 6c 20 68 61 64 20 4e 20 6c 65 73 73 20 74 68  ll had N less th
1f710 61 6e 20 6f 6e 65 20 6f 72 20 61 20 4e 55 4c 4c  an one or a NULL
1f720 20 70 6f 69 6e 74 65 72 20 66 6f 72 20 50 2c 20   pointer for P, 
1f730 74 68 65 6e 20 74 68 65 20 50 52 4e 47 20 69 73  then the PRNG is
1f740 0a 2a 2a 20 73 65 65 64 65 64 20 75 73 69 6e 67  .** seeded using
1f750 20 72 61 6e 64 6f 6d 6e 65 73 73 20 6f 62 74 61   randomness obta
1f760 69 6e 65 64 20 66 72 6f 6d 20 74 68 65 20 78 52  ined from the xR
1f770 61 6e 64 6f 6d 6e 65 73 73 20 6d 65 74 68 6f 64  andomness method
1f780 20 6f 66 0a 2a 2a 20 74 68 65 20 64 65 66 61 75   of.** the defau
1f790 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d  lt [sqlite3_vfs]
1f7a0 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 5e 49 66 20   object..** ^If 
1f7b0 74 68 65 20 70 72 65 76 69 6f 75 73 20 63 61 6c  the previous cal
1f7c0 6c 20 74 6f 20 74 68 69 73 20 72 6f 75 74 69 6e  l to this routin
1f7d0 65 20 68 61 64 20 61 6e 20 4e 20 6f 66 20 31 20  e had an N of 1 
1f7e0 6f 72 20 6d 6f 72 65 20 61 6e 64 20 61 0a 2a 2a  or more and a.**
1f7f0 20 6e 6f 6e 2d 4e 55 4c 4c 20 50 20 74 68 65 6e   non-NULL P then
1f800 20 74 68 65 20 70 73 65 75 64 6f 2d 72 61 6e 64   the pseudo-rand
1f810 6f 6d 6e 65 73 73 20 69 73 20 67 65 6e 65 72 61  omness is genera
1f820 74 65 64 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c 6c  ted.** internall
1f830 79 20 61 6e 64 20 77 69 74 68 6f 75 74 20 72 65  y and without re
1f840 63 6f 75 72 73 65 20 74 6f 20 74 68 65 20 5b 73  course to the [s
1f850 71 6c 69 74 65 33 5f 76 66 73 5d 20 78 52 61 6e  qlite3_vfs] xRan
1f860 64 6f 6d 6e 65 73 73 0a 2a 2a 20 6d 65 74 68 6f  domness.** metho
1f870 64 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74  d..*/.void sqlit
1f880 65 33 5f 72 61 6e 64 6f 6d 6e 65 73 73 28 69 6e  e3_randomness(in
1f890 74 20 4e 2c 20 76 6f 69 64 20 2a 50 29 3b 0a 0a  t N, void *P);..
1f8a0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1f8b0 43 6f 6d 70 69 6c 65 2d 54 69 6d 65 20 41 75 74  Compile-Time Aut
1f8c0 68 6f 72 69 7a 61 74 69 6f 6e 20 43 61 6c 6c 62  horization Callb
1f8d0 61 63 6b 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  acks.** METHOD: 
1f8e0 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54  sqlite3.**.** ^T
1f8f0 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 67 69  his routine regi
1f900 73 74 65 72 73 20 61 6e 20 61 75 74 68 6f 72 69  sters an authori
1f910 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 77 69 74  zer callback wit
1f920 68 20 61 20 70 61 72 74 69 63 75 6c 61 72 0a 2a  h a particular.*
1f930 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  * [database conn
1f940 65 63 74 69 6f 6e 5d 2c 20 73 75 70 70 6c 69 65  ection], supplie
1f950 64 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61  d in the first a
1f960 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65  rgument..** ^The
1f970 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
1f980 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20  back is invoked 
1f990 61 73 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  as SQL statement
1f9a0 73 20 61 72 65 20 62 65 69 6e 67 20 63 6f 6d 70  s are being comp
1f9b0 69 6c 65 64 0a 2a 2a 20 62 79 20 5b 73 71 6c 69  iled.** by [sqli
1f9c0 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f  te3_prepare()] o
1f9d0 72 20 69 74 73 20 76 61 72 69 61 6e 74 73 20 5b  r its variants [
1f9e0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
1f9f0 76 32 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74  v2()],.** [sqlit
1fa00 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 20  e3_prepare16()] 
1fa10 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  and [sqlite3_pre
1fa20 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 20 20 5e  pare16_v2()].  ^
1fa30 41 74 20 76 61 72 69 6f 75 73 0a 2a 2a 20 70 6f  At various.** po
1fa40 69 6e 74 73 20 64 75 72 69 6e 67 20 74 68 65 20  ints during the 
1fa50 63 6f 6d 70 69 6c 61 74 69 6f 6e 20 70 72 6f 63  compilation proc
1fa60 65 73 73 2c 20 61 73 20 6c 6f 67 69 63 20 69 73  ess, as logic is
1fa70 20 62 65 69 6e 67 20 63 72 65 61 74 65 64 0a 2a   being created.*
1fa80 2a 20 74 6f 20 70 65 72 66 6f 72 6d 20 76 61 72  * to perform var
1fa90 69 6f 75 73 20 61 63 74 69 6f 6e 73 2c 20 74 68  ious actions, th
1faa0 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
1fab0 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64  lback is invoked
1fac0 20 74 6f 0a 2a 2a 20 73 65 65 20 69 66 20 74 68   to.** see if th
1fad0 6f 73 65 20 61 63 74 69 6f 6e 73 20 61 72 65 20  ose actions are 
1fae0 61 6c 6c 6f 77 65 64 2e 20 20 5e 54 68 65 20 61  allowed.  ^The a
1faf0 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
1fb00 63 6b 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74  ck should.** ret
1fb10 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20  urn [SQLITE_OK] 
1fb20 74 6f 20 61 6c 6c 6f 77 20 74 68 65 20 61 63 74  to allow the act
1fb30 69 6f 6e 2c 20 5b 53 51 4c 49 54 45 5f 49 47 4e  ion, [SQLITE_IGN
1fb40 4f 52 45 5d 20 74 6f 20 64 69 73 61 6c 6c 6f 77  ORE] to disallow
1fb50 20 74 68 65 0a 2a 2a 20 73 70 65 63 69 66 69 63   the.** specific
1fb60 20 61 63 74 69 6f 6e 20 62 75 74 20 61 6c 6c 6f   action but allo
1fb70 77 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  w the SQL statem
1fb80 65 6e 74 20 74 6f 20 63 6f 6e 74 69 6e 75 65 20  ent to continue 
1fb90 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70 69 6c 65  to be.** compile
1fba0 64 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 45  d, or [SQLITE_DE
1fbb0 4e 59 5d 20 74 6f 20 63 61 75 73 65 20 74 68 65  NY] to cause the
1fbc0 20 65 6e 74 69 72 65 20 53 51 4c 20 73 74 61 74   entire SQL stat
1fbd0 65 6d 65 6e 74 20 74 6f 20 62 65 0a 2a 2a 20 72  ement to be.** r
1fbe0 65 6a 65 63 74 65 64 20 77 69 74 68 20 61 6e 20  ejected with an 
1fbf0 65 72 72 6f 72 2e 20 20 5e 49 66 20 74 68 65 20  error.  ^If the 
1fc00 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
1fc10 61 63 6b 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61  ack returns.** a
1fc20 6e 79 20 76 61 6c 75 65 20 6f 74 68 65 72 20 74  ny value other t
1fc30 68 61 6e 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f  han [SQLITE_IGNO
1fc40 52 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  RE], [SQLITE_OK]
1fc50 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e  , or [SQLITE_DEN
1fc60 59 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 5b  Y].** then the [
1fc70 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
1fc80 76 32 28 29 5d 20 6f 72 20 65 71 75 69 76 61 6c  v2()] or equival
1fc90 65 6e 74 20 63 61 6c 6c 20 74 68 61 74 20 74 72  ent call that tr
1fca0 69 67 67 65 72 65 64 0a 2a 2a 20 74 68 65 20 61  iggered.** the a
1fcb0 75 74 68 6f 72 69 7a 65 72 20 77 69 6c 6c 20 66  uthorizer will f
1fcc0 61 69 6c 20 77 69 74 68 20 61 6e 20 65 72 72 6f  ail with an erro
1fcd0 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 0a 2a 2a  r message..**.**
1fce0 20 57 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61   When the callba
1fcf0 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49  ck returns [SQLI
1fd00 54 45 5f 4f 4b 5d 2c 20 74 68 61 74 20 6d 65 61  TE_OK], that mea
1fd10 6e 73 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e  ns the operation
1fd20 0a 2a 2a 20 72 65 71 75 65 73 74 65 64 20 69 73  .** requested is
1fd30 20 6f 6b 2e 20 20 5e 57 68 65 6e 20 74 68 65 20   ok.  ^When the 
1fd40 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73  callback returns
1fd50 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 2c 20   [SQLITE_DENY], 
1fd60 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
1fd70 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72  prepare_v2()] or
1fd80 20 65 71 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c   equivalent call
1fd90 20 74 68 61 74 20 74 72 69 67 67 65 72 65 64 20   that triggered 
1fda0 74 68 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65  the.** authorize
1fdb0 72 20 77 69 6c 6c 20 66 61 69 6c 20 77 69 74 68  r will fail with
1fdc0 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67   an error messag
1fdd0 65 20 65 78 70 6c 61 69 6e 69 6e 67 20 74 68 61  e explaining tha
1fde0 74 0a 2a 2a 20 61 63 63 65 73 73 20 69 73 20 64  t.** access is d
1fdf0 65 6e 69 65 64 2e 20 0a 2a 2a 0a 2a 2a 20 5e 54  enied. .**.** ^T
1fe00 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
1fe10 65 72 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72  er to the author
1fe20 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73  izer callback is
1fe30 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 74   a copy of the t
1fe40 68 69 72 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65  hird.** paramete
1fe50 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33  r to the sqlite3
1fe60 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28  _set_authorizer(
1fe70 29 20 69 6e 74 65 72 66 61 63 65 2e 20 5e 54 68  ) interface. ^Th
1fe80 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
1fe90 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c  er.** to the cal
1fea0 6c 62 61 63 6b 20 69 73 20 61 6e 20 69 6e 74 65  lback is an inte
1feb0 67 65 72 20 5b 53 51 4c 49 54 45 5f 43 4f 50 59  ger [SQLITE_COPY
1fec0 20 7c 20 61 63 74 69 6f 6e 20 63 6f 64 65 5d 20   | action code] 
1fed0 74 68 61 74 20 73 70 65 63 69 66 69 65 73 0a 2a  that specifies.*
1fee0 2a 20 74 68 65 20 70 61 72 74 69 63 75 6c 61 72  * the particular
1fef0 20 61 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 75   action to be au
1ff00 74 68 6f 72 69 7a 65 64 2e 20 5e 54 68 65 20 74  thorized. ^The t
1ff10 68 69 72 64 20 74 68 72 6f 75 67 68 20 73 69 78  hird through six
1ff20 74 68 20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a  th parameters.**
1ff30 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b   to the callback
1ff40 20 61 72 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e   are zero-termin
1ff50 61 74 65 64 20 73 74 72 69 6e 67 73 20 74 68 61  ated strings tha
1ff60 74 20 63 6f 6e 74 61 69 6e 20 61 64 64 69 74 69  t contain additi
1ff70 6f 6e 61 6c 0a 2a 2a 20 64 65 74 61 69 6c 73 20  onal.** details 
1ff80 61 62 6f 75 74 20 74 68 65 20 61 63 74 69 6f 6e  about the action
1ff90 20 74 6f 20 62 65 20 61 75 74 68 6f 72 69 7a 65   to be authorize
1ffa0 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  d..**.** ^If the
1ffb0 20 61 63 74 69 6f 6e 20 63 6f 64 65 20 69 73 20   action code is 
1ffc0 5b 53 51 4c 49 54 45 5f 52 45 41 44 5d 0a 2a 2a  [SQLITE_READ].**
1ffd0 20 61 6e 64 20 74 68 65 20 63 61 6c 6c 62 61 63   and the callbac
1ffe0 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54  k returns [SQLIT
1fff0 45 5f 49 47 4e 4f 52 45 5d 20 74 68 65 6e 20 74  E_IGNORE] then t
20000 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20  he.** [prepared 
20010 73 74 61 74 65 6d 65 6e 74 5d 20 73 74 61 74 65  statement] state
20020 6d 65 6e 74 20 69 73 20 63 6f 6e 73 74 72 75 63  ment is construc
20030 74 65 64 20 74 6f 20 73 75 62 73 74 69 74 75 74  ted to substitut
20040 65 0a 2a 2a 20 61 20 4e 55 4c 4c 20 76 61 6c 75  e.** a NULL valu
20050 65 20 69 6e 20 70 6c 61 63 65 20 6f 66 20 74 68  e in place of th
20060 65 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74  e table column t
20070 68 61 74 20 77 6f 75 6c 64 20 68 61 76 65 0a 2a  hat would have.*
20080 2a 20 62 65 65 6e 20 72 65 61 64 20 69 66 20 5b  * been read if [
20090 53 51 4c 49 54 45 5f 4f 4b 5d 20 68 61 64 20 62  SQLITE_OK] had b
200a0 65 65 6e 20 72 65 74 75 72 6e 65 64 2e 20 20 54  een returned.  T
200b0 68 65 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52  he [SQLITE_IGNOR
200c0 45 5d 0a 2a 2a 20 72 65 74 75 72 6e 20 63 61 6e  E].** return can
200d0 20 62 65 20 75 73 65 64 20 74 6f 20 64 65 6e 79   be used to deny
200e0 20 61 6e 20 75 6e 74 72 75 73 74 65 64 20 75 73   an untrusted us
200f0 65 72 20 61 63 63 65 73 73 20 74 6f 20 69 6e 64  er access to ind
20100 69 76 69 64 75 61 6c 0a 2a 2a 20 63 6f 6c 75 6d  ividual.** colum
20110 6e 73 20 6f 66 20 61 20 74 61 62 6c 65 2e 0a 2a  ns of a table..*
20120 2a 20 5e 49 66 20 74 68 65 20 61 63 74 69 6f 6e  * ^If the action
20130 20 63 6f 64 65 20 69 73 20 5b 53 51 4c 49 54 45   code is [SQLITE
20140 5f 44 45 4c 45 54 45 5d 20 61 6e 64 20 74 68 65  _DELETE] and the
20150 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e   callback return
20160 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 47 4e  s.** [SQLITE_IGN
20170 4f 52 45 5d 20 74 68 65 6e 20 74 68 65 20 5b 44  ORE] then the [D
20180 45 4c 45 54 45 5d 20 6f 70 65 72 61 74 69 6f 6e  ELETE] operation
20190 20 70 72 6f 63 65 65 64 73 20 62 75 74 20 74 68   proceeds but th
201a0 65 0a 2a 2a 20 5b 74 72 75 6e 63 61 74 65 20 6f  e.** [truncate o
201b0 70 74 69 6d 69 7a 61 74 69 6f 6e 5d 20 69 73 20  ptimization] is 
201c0 64 69 73 61 62 6c 65 64 20 61 6e 64 20 61 6c 6c  disabled and all
201d0 20 72 6f 77 73 20 61 72 65 20 64 65 6c 65 74 65   rows are delete
201e0 64 20 69 6e 64 69 76 69 64 75 61 6c 6c 79 2e 0a  d individually..
201f0 2a 2a 0a 2a 2a 20 41 6e 20 61 75 74 68 6f 72 69  **.** An authori
20200 7a 65 72 20 69 73 20 75 73 65 64 20 77 68 65 6e  zer is used when
20210 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
20220 65 20 7c 20 70 72 65 70 61 72 69 6e 67 5d 0a 2a  e | preparing].*
20230 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  * SQL statements
20240 20 66 72 6f 6d 20 61 6e 20 75 6e 74 72 75 73 74   from an untrust
20250 65 64 20 73 6f 75 72 63 65 2c 20 74 6f 20 65 6e  ed source, to en
20260 73 75 72 65 20 74 68 61 74 20 74 68 65 20 53 51  sure that the SQ
20270 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20  L statements.** 
20280 64 6f 20 6e 6f 74 20 74 72 79 20 74 6f 20 61 63  do not try to ac
20290 63 65 73 73 20 64 61 74 61 20 74 68 65 79 20 61  cess data they a
202a0 72 65 20 6e 6f 74 20 61 6c 6c 6f 77 65 64 20 74  re not allowed t
202b0 6f 20 73 65 65 2c 20 6f 72 20 74 68 61 74 20 74  o see, or that t
202c0 68 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a 20 74 72  hey do not.** tr
202d0 79 20 74 6f 20 65 78 65 63 75 74 65 20 6d 61 6c  y to execute mal
202e0 69 63 69 6f 75 73 20 73 74 61 74 65 6d 65 6e 74  icious statement
202f0 73 20 74 68 61 74 20 64 61 6d 61 67 65 20 74 68  s that damage th
20300 65 20 64 61 74 61 62 61 73 65 2e 20 20 46 6f 72  e database.  For
20310 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 61 6e 20  .** example, an 
20320 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 61 79 20  application may 
20330 61 6c 6c 6f 77 20 61 20 75 73 65 72 20 74 6f 20  allow a user to 
20340 65 6e 74 65 72 20 61 72 62 69 74 72 61 72 79 0a  enter arbitrary.
20350 2a 2a 20 53 51 4c 20 71 75 65 72 69 65 73 20 66  ** SQL queries f
20360 6f 72 20 65 76 61 6c 75 61 74 69 6f 6e 20 62 79  or evaluation by
20370 20 61 20 64 61 74 61 62 61 73 65 2e 20 20 42 75   a database.  Bu
20380 74 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  t the applicatio
20390 6e 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 77 61  n does.** not wa
203a0 6e 74 20 74 68 65 20 75 73 65 72 20 74 6f 20 62  nt the user to b
203b0 65 20 61 62 6c 65 20 74 6f 20 6d 61 6b 65 20 61  e able to make a
203c0 72 62 69 74 72 61 72 79 20 63 68 61 6e 67 65 73  rbitrary changes
203d0 20 74 6f 20 74 68 65 0a 2a 2a 20 64 61 74 61 62   to the.** datab
203e0 61 73 65 2e 20 20 41 6e 20 61 75 74 68 6f 72 69  ase.  An authori
203f0 7a 65 72 20 63 6f 75 6c 64 20 74 68 65 6e 20 62  zer could then b
20400 65 20 70 75 74 20 69 6e 20 70 6c 61 63 65 20 77  e put in place w
20410 68 69 6c 65 20 74 68 65 0a 2a 2a 20 75 73 65 72  hile the.** user
20420 2d 65 6e 74 65 72 65 64 20 53 51 4c 20 69 73 20  -entered SQL is 
20430 62 65 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70  being [sqlite3_p
20440 72 65 70 61 72 65 20 7c 20 70 72 65 70 61 72 65  repare | prepare
20450 64 5d 20 74 68 61 74 0a 2a 2a 20 64 69 73 61 6c  d] that.** disal
20460 6c 6f 77 73 20 65 76 65 72 79 74 68 69 6e 67 20  lows everything 
20470 65 78 63 65 70 74 20 5b 53 45 4c 45 43 54 5d 20  except [SELECT] 
20480 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a  statements..**.*
20490 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74  * Applications t
204a0 68 61 74 20 6e 65 65 64 20 74 6f 20 70 72 6f 63  hat need to proc
204b0 65 73 73 20 53 51 4c 20 66 72 6f 6d 20 75 6e 74  ess SQL from unt
204c0 72 75 73 74 65 64 20 73 6f 75 72 63 65 73 0a 2a  rusted sources.*
204d0 2a 20 6d 69 67 68 74 20 61 6c 73 6f 20 63 6f 6e  * might also con
204e0 73 69 64 65 72 20 6c 6f 77 65 72 69 6e 67 20 72  sider lowering r
204f0 65 73 6f 75 72 63 65 20 6c 69 6d 69 74 73 20 75  esource limits u
20500 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6c 69  sing [sqlite3_li
20510 6d 69 74 28 29 5d 0a 2a 2a 20 61 6e 64 20 6c 69  mit()].** and li
20520 6d 69 74 69 6e 67 20 64 61 74 61 62 61 73 65 20  miting database 
20530 73 69 7a 65 20 75 73 69 6e 67 20 74 68 65 20 5b  size using the [
20540 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e 74 5d 20  max_page_count] 
20550 5b 50 52 41 47 4d 41 5d 0a 2a 2a 20 69 6e 20 61  [PRAGMA].** in a
20560 64 64 69 74 69 6f 6e 20 74 6f 20 75 73 69 6e 67  ddition to using
20570 20 61 6e 20 61 75 74 68 6f 72 69 7a 65 72 2e 0a   an authorizer..
20580 2a 2a 0a 2a 2a 20 5e 28 4f 6e 6c 79 20 61 20 73  **.** ^(Only a s
20590 69 6e 67 6c 65 20 61 75 74 68 6f 72 69 7a 65 72  ingle authorizer
205a0 20 63 61 6e 20 62 65 20 69 6e 20 70 6c 61 63 65   can be in place
205b0 20 6f 6e 20 61 20 64 61 74 61 62 61 73 65 20 63   on a database c
205c0 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 61 74 20  onnection.** at 
205d0 61 20 74 69 6d 65 2e 20 20 45 61 63 68 20 63 61  a time.  Each ca
205e0 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 65  ll to sqlite3_se
205f0 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 6f 76 65  t_authorizer ove
20600 72 72 69 64 65 73 20 74 68 65 0a 2a 2a 20 70 72  rrides the.** pr
20610 65 76 69 6f 75 73 20 63 61 6c 6c 2e 29 5e 20 20  evious call.)^  
20620 5e 44 69 73 61 62 6c 65 20 74 68 65 20 61 75 74  ^Disable the aut
20630 68 6f 72 69 7a 65 72 20 62 79 20 69 6e 73 74 61  horizer by insta
20640 6c 6c 69 6e 67 20 61 20 4e 55 4c 4c 20 63 61 6c  lling a NULL cal
20650 6c 62 61 63 6b 2e 0a 2a 2a 20 54 68 65 20 61 75  lback..** The au
20660 74 68 6f 72 69 7a 65 72 20 69 73 20 64 69 73 61  thorizer is disa
20670 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 2e  bled by default.
20680 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f  .**.** The autho
20690 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d  rizer callback m
206a0 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68  ust not do anyth
206b0 69 6e 67 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f  ing that will mo
206c0 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 61 74 61  dify.** the data
206d0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
206e0 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65  that invoked the
206f0 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
20700 62 61 63 6b 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68  back..** Note th
20710 61 74 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  at [sqlite3_prep
20720 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73  are_v2()] and [s
20730 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 62  qlite3_step()] b
20740 6f 74 68 20 6d 6f 64 69 66 79 20 74 68 65 69 72  oth modify their
20750 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e  .** database con
20760 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20 74 68 65  nections for the
20770 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64   meaning of "mod
20780 69 66 79 22 20 69 6e 20 74 68 69 73 20 70 61 72  ify" in this par
20790 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a 20 5e 57  agraph..**.** ^W
207a0 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  hen [sqlite3_pre
207b0 70 61 72 65 5f 76 32 28 29 5d 20 69 73 20 75 73  pare_v2()] is us
207c0 65 64 20 74 6f 20 70 72 65 70 61 72 65 20 61 20  ed to prepare a 
207d0 73 74 61 74 65 6d 65 6e 74 2c 20 74 68 65 0a 2a  statement, the.*
207e0 2a 20 73 74 61 74 65 6d 65 6e 74 20 6d 69 67 68  * statement migh
207f0 74 20 62 65 20 72 65 2d 70 72 65 70 61 72 65 64  t be re-prepared
20800 20 64 75 72 69 6e 67 20 5b 73 71 6c 69 74 65 33   during [sqlite3
20810 5f 73 74 65 70 28 29 5d 20 64 75 65 20 74 6f 20  _step()] due to 
20820 61 20 0a 2a 2a 20 73 63 68 65 6d 61 20 63 68 61  a .** schema cha
20830 6e 67 65 2e 20 20 48 65 6e 63 65 2c 20 74 68 65  nge.  Hence, the
20840 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f   application sho
20850 75 6c 64 20 65 6e 73 75 72 65 20 74 68 61 74 20  uld ensure that 
20860 74 68 65 0a 2a 2a 20 63 6f 72 72 65 63 74 20 61  the.** correct a
20870 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
20880 63 6b 20 72 65 6d 61 69 6e 73 20 69 6e 20 70 6c  ck remains in pl
20890 61 63 65 20 64 75 72 69 6e 67 20 74 68 65 20 5b  ace during the [
208a0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e  sqlite3_step()].
208b0 0a 2a 2a 0a 2a 2a 20 5e 4e 6f 74 65 20 74 68 61  .**.** ^Note tha
208c0 74 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72  t the authorizer
208d0 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76   callback is inv
208e0 6f 6b 65 64 20 6f 6e 6c 79 20 64 75 72 69 6e 67  oked only during
208f0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  .** [sqlite3_pre
20900 70 61 72 65 28 29 5d 20 6f 72 20 69 74 73 20 76  pare()] or its v
20910 61 72 69 61 6e 74 73 2e 20 20 41 75 74 68 6f 72  ariants.  Author
20920 69 7a 61 74 69 6f 6e 20 69 73 20 6e 6f 74 0a 2a  ization is not.*
20930 2a 20 70 65 72 66 6f 72 6d 65 64 20 64 75 72 69  * performed duri
20940 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 65 76 61  ng statement eva
20950 6c 75 61 74 69 6f 6e 20 69 6e 20 5b 73 71 6c 69  luation in [sqli
20960 74 65 33 5f 73 74 65 70 28 29 5d 2c 20 75 6e 6c  te3_step()], unl
20970 65 73 73 0a 2a 2a 20 61 73 20 73 74 61 74 65 64  ess.** as stated
20980 20 69 6e 20 74 68 65 20 70 72 65 76 69 6f 75 73   in the previous
20990 20 70 61 72 61 67 72 61 70 68 2c 20 73 71 6c 69   paragraph, sqli
209a0 74 65 33 5f 73 74 65 70 28 29 20 69 6e 76 6f 6b  te3_step() invok
209b0 65 73 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 70 72  es.** sqlite3_pr
209c0 65 70 61 72 65 5f 76 32 28 29 20 74 6f 20 72 65  epare_v2() to re
209d0 70 72 65 70 61 72 65 20 61 20 73 74 61 74 65 6d  prepare a statem
209e0 65 6e 74 20 61 66 74 65 72 20 61 20 73 63 68 65  ent after a sche
209f0 6d 61 20 63 68 61 6e 67 65 2e 0a 2a 2f 0a 69 6e  ma change..*/.in
20a00 74 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75  t sqlite3_set_au
20a10 74 68 6f 72 69 7a 65 72 28 0a 20 20 73 71 6c 69  thorizer(.  sqli
20a20 74 65 33 2a 2c 0a 20 20 69 6e 74 20 28 2a 78 41  te3*,.  int (*xA
20a30 75 74 68 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63  uth)(void*,int,c
20a40 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74  onst char*,const
20a50 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61   char*,const cha
20a60 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c  r*,const char*),
20a70 0a 20 20 76 6f 69 64 20 2a 70 55 73 65 72 44 61  .  void *pUserDa
20a80 74 61 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ta.);../*.** CAP
20a90 49 33 52 45 46 3a 20 41 75 74 68 6f 72 69 7a 65  I3REF: Authorize
20aa0 72 20 52 65 74 75 72 6e 20 43 6f 64 65 73 0a 2a  r Return Codes.*
20ab0 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65  *.** The [sqlite
20ac0 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72  3_set_authorizer
20ad0 20 7c 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61   | authorizer ca
20ae0 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 5d  llback function]
20af0 20 6d 75 73 74 0a 2a 2a 20 72 65 74 75 72 6e 20   must.** return 
20b00 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 4f  either [SQLITE_O
20b10 4b 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65  K] or one of the
20b20 73 65 20 74 77 6f 20 63 6f 6e 73 74 61 6e 74 73  se two constants
20b30 20 69 6e 20 6f 72 64 65 72 0a 2a 2a 20 74 6f 20   in order.** to 
20b40 73 69 67 6e 61 6c 20 53 51 4c 69 74 65 20 77 68  signal SQLite wh
20b50 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65  ether or not the
20b60 20 61 63 74 69 6f 6e 20 69 73 20 70 65 72 6d 69   action is permi
20b70 74 74 65 64 2e 20 20 53 65 65 20 74 68 65 0a 2a  tted.  See the.*
20b80 2a 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  * [sqlite3_set_a
20b90 75 74 68 6f 72 69 7a 65 72 20 7c 20 61 75 74 68  uthorizer | auth
20ba0 6f 72 69 7a 65 72 20 64 6f 63 75 6d 65 6e 74 61  orizer documenta
20bb0 74 69 6f 6e 5d 20 66 6f 72 20 61 64 64 69 74 69  tion] for additi
20bc0 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74  onal.** informat
20bd0 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20  ion..**.** Note 
20be0 74 68 61 74 20 53 51 4c 49 54 45 5f 49 47 4e 4f  that SQLITE_IGNO
20bf0 52 45 20 69 73 20 61 6c 73 6f 20 75 73 65 64 20  RE is also used 
20c00 61 73 20 61 20 5b 63 6f 6e 66 6c 69 63 74 20 72  as a [conflict r
20c10 65 73 6f 6c 75 74 69 6f 6e 20 6d 6f 64 65 5d 0a  esolution mode].
20c20 2a 2a 20 72 65 74 75 72 6e 65 64 20 66 72 6f 6d  ** returned from
20c30 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 74   the [sqlite3_vt
20c40 61 62 5f 6f 6e 5f 63 6f 6e 66 6c 69 63 74 28 29  ab_on_conflict()
20c50 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2f 0a  ] interface..*/.
20c60 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
20c70 45 4e 59 20 20 20 31 20 20 20 2f 2a 20 41 62 6f  ENY   1   /* Abo
20c80 72 74 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  rt the SQL state
20c90 6d 65 6e 74 20 77 69 74 68 20 61 6e 20 65 72 72  ment with an err
20ca0 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  or */.#define SQ
20cb0 4c 49 54 45 5f 49 47 4e 4f 52 45 20 32 20 20 20  LITE_IGNORE 2   
20cc0 2f 2a 20 44 6f 6e 27 74 20 61 6c 6c 6f 77 20 61  /* Don't allow a
20cd0 63 63 65 73 73 2c 20 62 75 74 20 64 6f 6e 27 74  ccess, but don't
20ce0 20 67 65 6e 65 72 61 74 65 20 61 6e 20 65 72 72   generate an err
20cf0 6f 72 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  or */../*.** CAP
20d00 49 33 52 45 46 3a 20 41 75 74 68 6f 72 69 7a 65  I3REF: Authorize
20d10 72 20 41 63 74 69 6f 6e 20 43 6f 64 65 73 0a 2a  r Action Codes.*
20d20 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65  *.** The [sqlite
20d30 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72  3_set_authorizer
20d40 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65  ()] interface re
20d50 67 69 73 74 65 72 73 20 61 20 63 61 6c 6c 62 61  gisters a callba
20d60 63 6b 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 74  ck function.** t
20d70 68 61 74 20 69 73 20 69 6e 76 6f 6b 65 64 20 74  hat is invoked t
20d80 6f 20 61 75 74 68 6f 72 69 7a 65 20 63 65 72 74  o authorize cert
20d90 61 69 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ain SQL statemen
20da0 74 20 61 63 74 69 6f 6e 73 2e 20 20 54 68 65 0a  t actions.  The.
20db0 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  ** second parame
20dc0 74 65 72 20 74 6f 20 74 68 65 20 63 61 6c 6c 62  ter to the callb
20dd0 61 63 6b 20 69 73 20 61 6e 20 69 6e 74 65 67 65  ack is an intege
20de0 72 20 63 6f 64 65 20 74 68 61 74 20 73 70 65 63  r code that spec
20df0 69 66 69 65 73 0a 2a 2a 20 77 68 61 74 20 61 63  ifies.** what ac
20e00 74 69 6f 6e 20 69 73 20 62 65 69 6e 67 20 61 75  tion is being au
20e10 74 68 6f 72 69 7a 65 64 2e 20 20 54 68 65 73 65  thorized.  These
20e20 20 61 72 65 20 74 68 65 20 69 6e 74 65 67 65 72   are the integer
20e30 20 61 63 74 69 6f 6e 20 63 6f 64 65 73 20 74 68   action codes th
20e40 61 74 0a 2a 2a 20 74 68 65 20 61 75 74 68 6f 72  at.** the author
20e50 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d 61  izer callback ma
20e60 79 20 62 65 20 70 61 73 73 65 64 2e 0a 2a 2a 0a  y be passed..**.
20e70 2a 2a 20 54 68 65 73 65 20 61 63 74 69 6f 6e 20  ** These action 
20e80 63 6f 64 65 20 76 61 6c 75 65 73 20 73 69 67 6e  code values sign
20e90 69 66 79 20 77 68 61 74 20 6b 69 6e 64 20 6f 66  ify what kind of
20ea0 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 74 6f   operation is to
20eb0 20 62 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65   be.** authorize
20ec0 64 2e 20 20 54 68 65 20 33 72 64 20 61 6e 64 20  d.  The 3rd and 
20ed0 34 74 68 20 70 61 72 61 6d 65 74 65 72 73 20 74  4th parameters t
20ee0 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a 61 74  o the authorizat
20ef0 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20  ion.** callback 
20f00 66 75 6e 63 74 69 6f 6e 20 77 69 6c 6c 20 62 65  function will be
20f10 20 70 61 72 61 6d 65 74 65 72 73 20 6f 72 20 4e   parameters or N
20f20 55 4c 4c 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e  ULL depending on
20f30 20 77 68 69 63 68 20 6f 66 20 74 68 65 73 65 0a   which of these.
20f40 2a 2a 20 63 6f 64 65 73 20 69 73 20 75 73 65 64  ** codes is used
20f50 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70   as the second p
20f60 61 72 61 6d 65 74 65 72 2e 20 20 5e 28 54 68 65  arameter.  ^(The
20f70 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 74   5th parameter t
20f80 6f 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f 72 69  o the.** authori
20f90 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  zer callback is 
20fa0 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
20fb0 64 61 74 61 62 61 73 65 20 28 22 6d 61 69 6e 22  database ("main"
20fc0 2c 20 22 74 65 6d 70 22 2c 0a 2a 2a 20 65 74 63  , "temp",.** etc
20fd0 2e 29 20 69 66 20 61 70 70 6c 69 63 61 62 6c 65  .) if applicable
20fe0 2e 29 5e 20 20 5e 54 68 65 20 36 74 68 20 70 61  .)^  ^The 6th pa
20ff0 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61  rameter to the a
21000 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
21010 63 6b 0a 2a 2a 20 69 73 20 74 68 65 20 6e 61 6d  ck.** is the nam
21020 65 20 6f 66 20 74 68 65 20 69 6e 6e 65 72 2d 6d  e of the inner-m
21030 6f 73 74 20 74 72 69 67 67 65 72 20 6f 72 20 76  ost trigger or v
21040 69 65 77 20 74 68 61 74 20 69 73 20 72 65 73 70  iew that is resp
21050 6f 6e 73 69 62 6c 65 20 66 6f 72 0a 2a 2a 20 74  onsible for.** t
21060 68 65 20 61 63 63 65 73 73 20 61 74 74 65 6d 70  he access attemp
21070 74 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 69  t or NULL if thi
21080 73 20 61 63 63 65 73 73 20 61 74 74 65 6d 70 74  s access attempt
21090 20 69 73 20 64 69 72 65 63 74 6c 79 20 66 72 6f   is directly fro
210a0 6d 0a 2a 2a 20 74 6f 70 2d 6c 65 76 65 6c 20 53  m.** top-level S
210b0 51 4c 20 63 6f 64 65 2e 0a 2a 2f 0a 2f 2a 2a 2a  QL code..*/./***
210c0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
210d0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
210e0 2a 2a 2a 2a 2a 2a 2a 2a 20 33 72 64 20 2a 2a 2a  ******** 3rd ***
210f0 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 34 74 68 20 2a 2a  ********* 4th **
21100 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 23 64 65 66 69  *********/.#defi
21110 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45  ne SQLITE_CREATE
21120 5f 49 4e 44 45 58 20 20 20 20 20 20 20 20 20 20  _INDEX          
21130 31 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d  1   /* Index Nam
21140 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d  e      Table Nam
21150 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  e      */.#defin
21160 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f  e SQLITE_CREATE_
21170 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 32  TABLE          2
21180 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
21190 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
211a0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
211b0 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54   SQLITE_CREATE_T
211c0 45 4d 50 5f 49 4e 44 45 58 20 20 20 20 20 33 20  EMP_INDEX     3 
211d0 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20    /* Index Name 
211e0 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20       Table Name 
211f0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
21200 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45  SQLITE_CREATE_TE
21210 4d 50 5f 54 41 42 4c 45 20 20 20 20 20 34 20 20  MP_TABLE     4  
21220 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
21230 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
21240 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
21250 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d  QLITE_CREATE_TEM
21260 50 5f 54 52 49 47 47 45 52 20 20 20 35 20 20 20  P_TRIGGER   5   
21270 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20  /* Trigger Name 
21280 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20     Table Name   
21290 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
212a0 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50  LITE_CREATE_TEMP
212b0 5f 56 49 45 57 20 20 20 20 20 20 36 20 20 20 2f  _VIEW      6   /
212c0 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20  * View Name     
212d0 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
212e0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
212f0 49 54 45 5f 43 52 45 41 54 45 5f 54 52 49 47 47  ITE_CREATE_TRIGG
21300 45 52 20 20 20 20 20 20 20 20 37 20 20 20 2f 2a  ER        7   /*
21310 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20   Trigger Name   
21320 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
21330 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
21340 54 45 5f 43 52 45 41 54 45 5f 56 49 45 57 20 20  TE_CREATE_VIEW  
21350 20 20 20 20 20 20 20 20 20 38 20 20 20 2f 2a 20           8   /* 
21360 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20  View Name       
21370 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
21380 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
21390 45 5f 44 45 4c 45 54 45 20 20 20 20 20 20 20 20  E_DELETE        
213a0 20 20 20 20 20 20 20 20 39 20 20 20 2f 2a 20 54          9   /* T
213b0 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e  able Name      N
213c0 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
213d0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
213e0 5f 44 52 4f 50 5f 49 4e 44 45 58 20 20 20 20 20  _DROP_INDEX     
213f0 20 20 20 20 20 20 31 30 20 20 20 2f 2a 20 49 6e        10   /* In
21400 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61  dex Name      Ta
21410 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f  ble Name      */
21420 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
21430 44 52 4f 50 5f 54 41 42 4c 45 20 20 20 20 20 20  DROP_TABLE      
21440 20 20 20 20 20 31 31 20 20 20 2f 2a 20 54 61 62       11   /* Tab
21450 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c  le Name      NUL
21460 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
21470 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
21480 52 4f 50 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20  ROP_TEMP_INDEX  
21490 20 20 20 20 31 32 20 20 20 2f 2a 20 49 6e 64 65      12   /* Inde
214a0 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c  x Name      Tabl
214b0 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23  e Name      */.#
214c0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52  define SQLITE_DR
214d0 4f 50 5f 54 45 4d 50 5f 54 41 42 4c 45 20 20 20  OP_TEMP_TABLE   
214e0 20 20 20 31 33 20 20 20 2f 2a 20 54 61 62 6c 65     13   /* Table
214f0 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20   Name      NULL 
21500 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
21510 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f  efine SQLITE_DRO
21520 50 5f 54 45 4d 50 5f 54 52 49 47 47 45 52 20 20  P_TEMP_TRIGGER  
21530 20 20 31 34 20 20 20 2f 2a 20 54 72 69 67 67 65    14   /* Trigge
21540 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20  r Name    Table 
21550 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65  Name      */.#de
21560 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50  fine SQLITE_DROP
21570 5f 54 45 4d 50 5f 56 49 45 57 20 20 20 20 20 20  _TEMP_VIEW      
21580 20 31 35 20 20 20 2f 2a 20 56 69 65 77 20 4e 61   15   /* View Na
21590 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  me       NULL   
215a0 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
215b0 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f  ine SQLITE_DROP_
215c0 54 52 49 47 47 45 52 20 20 20 20 20 20 20 20 20  TRIGGER         
215d0 31 36 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20  16   /* Trigger 
215e0 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61  Name    Table Na
215f0 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  me      */.#defi
21600 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56  ne SQLITE_DROP_V
21610 49 45 57 20 20 20 20 20 20 20 20 20 20 20 20 31  IEW            1
21620 37 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65  7   /* View Name
21630 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20         NULL     
21640 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
21650 65 20 53 51 4c 49 54 45 5f 49 4e 53 45 52 54 20  e SQLITE_INSERT 
21660 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31 38                18
21670 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
21680 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
21690 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
216a0 20 53 51 4c 49 54 45 5f 50 52 41 47 4d 41 20 20   SQLITE_PRAGMA  
216b0 20 20 20 20 20 20 20 20 20 20 20 20 20 31 39 20               19 
216c0 20 20 2f 2a 20 50 72 61 67 6d 61 20 4e 61 6d 65    /* Pragma Name
216d0 20 20 20 20 20 31 73 74 20 61 72 67 20 6f 72 20       1st arg or 
216e0 4e 55 4c 4c 20 2a 2f 0a 23 64 65 66 69 6e 65 20  NULL */.#define 
216f0 53 51 4c 49 54 45 5f 52 45 41 44 20 20 20 20 20  SQLITE_READ     
21700 20 20 20 20 20 20 20 20 20 20 20 20 32 30 20 20              20  
21710 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
21720 20 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20      Column Name 
21730 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
21740 51 4c 49 54 45 5f 53 45 4c 45 43 54 20 20 20 20  QLITE_SELECT    
21750 20 20 20 20 20 20 20 20 20 20 20 32 31 20 20 20             21   
21760 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20  /* NULL         
21770 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
21780 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
21790 4c 49 54 45 5f 54 52 41 4e 53 41 43 54 49 4f 4e  LITE_TRANSACTION
217a0 20 20 20 20 20 20 20 20 20 20 32 32 20 20 20 2f            22   /
217b0 2a 20 4f 70 65 72 61 74 69 6f 6e 20 20 20 20 20  * Operation     
217c0 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
217d0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
217e0 49 54 45 5f 55 50 44 41 54 45 20 20 20 20 20 20  ITE_UPDATE      
217f0 20 20 20 20 20 20 20 20 20 32 33 20 20 20 2f 2a           23   /*
21800 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
21810 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20   Column Name    
21820 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
21830 54 45 5f 41 54 54 41 43 48 20 20 20 20 20 20 20  TE_ATTACH       
21840 20 20 20 20 20 20 20 20 32 34 20 20 20 2f 2a 20          24   /* 
21850 46 69 6c 65 6e 61 6d 65 20 20 20 20 20 20 20 20  Filename        
21860 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
21870 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
21880 45 5f 44 45 54 41 43 48 20 20 20 20 20 20 20 20  E_DETACH        
21890 20 20 20 20 20 20 20 32 35 20 20 20 2f 2a 20 44         25   /* D
218a0 61 74 61 62 61 73 65 20 4e 61 6d 65 20 20 20 4e  atabase Name   N
218b0 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
218c0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
218d0 5f 41 4c 54 45 52 5f 54 41 42 4c 45 20 20 20 20  _ALTER_TABLE    
218e0 20 20 20 20 20 20 32 36 20 20 20 2f 2a 20 44 61        26   /* Da
218f0 74 61 62 61 73 65 20 4e 61 6d 65 20 20 20 54 61  tabase Name   Ta
21900 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f  ble Name      */
21910 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
21920 52 45 49 4e 44 45 58 20 20 20 20 20 20 20 20 20  REINDEX         
21930 20 20 20 20 20 32 37 20 20 20 2f 2a 20 49 6e 64       27   /* Ind
21940 65 78 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c  ex Name      NUL
21950 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
21960 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
21970 4e 41 4c 59 5a 45 20 20 20 20 20 20 20 20 20 20  NALYZE          
21980 20 20 20 20 32 38 20 20 20 2f 2a 20 54 61 62 6c      28   /* Tabl
21990 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c  e Name      NULL
219a0 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
219b0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52  define SQLITE_CR
219c0 45 41 54 45 5f 56 54 41 42 4c 45 20 20 20 20 20  EATE_VTABLE     
219d0 20 20 20 32 39 20 20 20 2f 2a 20 54 61 62 6c 65     29   /* Table
219e0 20 4e 61 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c   Name      Modul
219f0 65 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64  e Name     */.#d
21a00 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f  efine SQLITE_DRO
21a10 50 5f 56 54 41 42 4c 45 20 20 20 20 20 20 20 20  P_VTABLE        
21a20 20 20 33 30 20 20 20 2f 2a 20 54 61 62 6c 65 20    30   /* Table 
21a30 4e 61 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c 65  Name      Module
21a40 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65   Name     */.#de
21a50 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 55 4e 43  fine SQLITE_FUNC
21a60 54 49 4f 4e 20 20 20 20 20 20 20 20 20 20 20 20  TION            
21a70 20 33 31 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20   31   /* NULL   
21a80 20 20 20 20 20 20 20 20 20 46 75 6e 63 74 69 6f           Functio
21a90 6e 20 4e 61 6d 65 20 20 20 2a 2f 0a 23 64 65 66  n Name   */.#def
21aa0 69 6e 65 20 53 51 4c 49 54 45 5f 53 41 56 45 50  ine SQLITE_SAVEP
21ab0 4f 49 4e 54 20 20 20 20 20 20 20 20 20 20 20 20  OINT            
21ac0 33 32 20 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f  32   /* Operatio
21ad0 6e 20 20 20 20 20 20 20 53 61 76 65 70 6f 69 6e  n       Savepoin
21ae0 74 20 4e 61 6d 65 20 20 2a 2f 0a 23 64 65 66 69  t Name  */.#defi
21af0 6e 65 20 53 51 4c 49 54 45 5f 43 4f 50 59 20 20  ne SQLITE_COPY  
21b00 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
21b10 30 20 20 20 2f 2a 20 4e 6f 20 6c 6f 6e 67 65 72  0   /* No longer
21b20 20 75 73 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65   used */.#define
21b30 20 53 51 4c 49 54 45 5f 52 45 43 55 52 53 49 56   SQLITE_RECURSIV
21b40 45 20 20 20 20 20 20 20 20 20 20 20 20 33 33 20  E            33 
21b50 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20    /* NULL       
21b60 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
21b70 20 20 20 20 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43       */../*.** C
21b80 41 50 49 33 52 45 46 3a 20 54 72 61 63 69 6e 67  API3REF: Tracing
21b90 20 41 6e 64 20 50 72 6f 66 69 6c 69 6e 67 20 46   And Profiling F
21ba0 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 4d 45 54 48  unctions.** METH
21bb0 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a  OD: sqlite3.**.*
21bc0 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
21bd0 20 61 72 65 20 64 65 70 72 65 63 61 74 65 64 2e   are deprecated.
21be0 20 55 73 65 20 74 68 65 20 5b 73 71 6c 69 74 65   Use the [sqlite
21bf0 33 5f 74 72 61 63 65 5f 76 32 28 29 5d 20 69 6e  3_trace_v2()] in
21c00 74 65 72 66 61 63 65 0a 2a 2a 20 69 6e 73 74 65  terface.** inste
21c10 61 64 20 6f 66 20 74 68 65 20 72 6f 75 74 69 6e  ad of the routin
21c20 65 73 20 64 65 73 63 72 69 62 65 64 20 68 65 72  es described her
21c30 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  e..**.** These r
21c40 6f 75 74 69 6e 65 73 20 72 65 67 69 73 74 65 72  outines register
21c50 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
21c60 6f 6e 73 20 74 68 61 74 20 63 61 6e 20 62 65 20  ons that can be 
21c70 75 73 65 64 20 66 6f 72 0a 2a 2a 20 74 72 61 63  used for.** trac
21c80 69 6e 67 20 61 6e 64 20 70 72 6f 66 69 6c 69 6e  ing and profilin
21c90 67 20 74 68 65 20 65 78 65 63 75 74 69 6f 6e 20  g the execution 
21ca0 6f 66 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  of SQL statement
21cb0 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 61  s..**.** ^The ca
21cc0 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
21cd0 72 65 67 69 73 74 65 72 65 64 20 62 79 20 73 71  registered by sq
21ce0 6c 69 74 65 33 5f 74 72 61 63 65 28 29 20 69 73  lite3_trace() is
21cf0 20 69 6e 76 6f 6b 65 64 20 61 74 0a 2a 2a 20 76   invoked at.** v
21d00 61 72 69 6f 75 73 20 74 69 6d 65 73 20 77 68 65  arious times whe
21d10 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65  n an SQL stateme
21d20 6e 74 20 69 73 20 62 65 69 6e 67 20 72 75 6e 20  nt is being run 
21d30 62 79 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  by [sqlite3_step
21d40 28 29 5d 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ()]..** ^The sql
21d50 69 74 65 33 5f 74 72 61 63 65 28 29 20 63 61 6c  ite3_trace() cal
21d60 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64  lback is invoked
21d70 20 77 69 74 68 20 61 20 55 54 46 2d 38 20 72 65   with a UTF-8 re
21d80 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65 0a 2a  ndering of the.*
21d90 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  * SQL statement 
21da0 74 65 78 74 20 61 73 20 74 68 65 20 73 74 61 74  text as the stat
21db0 65 6d 65 6e 74 20 66 69 72 73 74 20 62 65 67 69  ement first begi
21dc0 6e 73 20 65 78 65 63 75 74 69 6e 67 2e 0a 2a 2a  ns executing..**
21dd0 20 5e 28 41 64 64 69 74 69 6f 6e 61 6c 20 73 71   ^(Additional sq
21de0 6c 69 74 65 33 5f 74 72 61 63 65 28 29 20 63 61  lite3_trace() ca
21df0 6c 6c 62 61 63 6b 73 20 6d 69 67 68 74 20 6f 63  llbacks might oc
21e00 63 75 72 0a 2a 2a 20 61 73 20 65 61 63 68 20 74  cur.** as each t
21e10 72 69 67 67 65 72 65 64 20 73 75 62 70 72 6f 67  riggered subprog
21e20 72 61 6d 20 69 73 20 65 6e 74 65 72 65 64 2e 20  ram is entered. 
21e30 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 73 20 66   The callbacks f
21e40 6f 72 20 74 72 69 67 67 65 72 73 0a 2a 2a 20 63  or triggers.** c
21e50 6f 6e 74 61 69 6e 20 61 20 55 54 46 2d 38 20 53  ontain a UTF-8 S
21e60 51 4c 20 63 6f 6d 6d 65 6e 74 20 74 68 61 74 20  QL comment that 
21e70 69 64 65 6e 74 69 66 69 65 73 20 74 68 65 20 74  identifies the t
21e80 72 69 67 67 65 72 2e 29 5e 0a 2a 2a 0a 2a 2a 20  rigger.)^.**.** 
21e90 54 68 65 20 5b 53 51 4c 49 54 45 5f 54 52 41 43  The [SQLITE_TRAC
21ea0 45 5f 53 49 5a 45 5f 4c 49 4d 49 54 5d 20 63 6f  E_SIZE_LIMIT] co
21eb0 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
21ec0 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  n can be used to
21ed0 20 6c 69 6d 69 74 0a 2a 2a 20 74 68 65 20 6c 65   limit.** the le
21ee0 6e 67 74 68 20 6f 66 20 5b 62 6f 75 6e 64 20 70  ngth of [bound p
21ef0 61 72 61 6d 65 74 65 72 5d 20 65 78 70 61 6e 73  arameter] expans
21f00 69 6f 6e 20 69 6e 20 74 68 65 20 6f 75 74 70 75  ion in the outpu
21f10 74 20 6f 66 20 73 71 6c 69 74 65 33 5f 74 72 61  t of sqlite3_tra
21f20 63 65 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ce()..**.** ^The
21f30 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
21f40 6f 6e 20 72 65 67 69 73 74 65 72 65 64 20 62 79  on registered by
21f50 20 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65   sqlite3_profile
21f60 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a  () is invoked.**
21f70 20 61 73 20 65 61 63 68 20 53 51 4c 20 73 74 61   as each SQL sta
21f80 74 65 6d 65 6e 74 20 66 69 6e 69 73 68 65 73 2e  tement finishes.
21f90 20 20 5e 54 68 65 20 70 72 6f 66 69 6c 65 20 63    ^The profile c
21fa0 61 6c 6c 62 61 63 6b 20 63 6f 6e 74 61 69 6e 73  allback contains
21fb0 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e 61 6c  .** the original
21fc0 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20   statement text 
21fd0 61 6e 64 20 61 6e 20 65 73 74 69 6d 61 74 65 20  and an estimate 
21fe0 6f 66 20 77 61 6c 6c 2d 63 6c 6f 63 6b 20 74 69  of wall-clock ti
21ff0 6d 65 0a 2a 2a 20 6f 66 20 68 6f 77 20 6c 6f 6e  me.** of how lon
22000 67 20 74 68 61 74 20 73 74 61 74 65 6d 65 6e 74  g that statement
22010 20 74 6f 6f 6b 20 74 6f 20 72 75 6e 2e 20 20 5e   took to run.  ^
22020 54 68 65 20 70 72 6f 66 69 6c 65 20 63 61 6c 6c  The profile call
22030 62 61 63 6b 0a 2a 2a 20 74 69 6d 65 20 69 73 20  back.** time is 
22040 69 6e 20 75 6e 69 74 73 20 6f 66 20 6e 61 6e 6f  in units of nano
22050 73 65 63 6f 6e 64 73 2c 20 68 6f 77 65 76 65 72  seconds, however
22060 20 74 68 65 20 63 75 72 72 65 6e 74 20 69 6d 70   the current imp
22070 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20 69  lementation.** i
22080 73 20 6f 6e 6c 79 20 63 61 70 61 62 6c 65 20 6f  s only capable o
22090 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 20 72 65  f millisecond re
220a0 73 6f 6c 75 74 69 6f 6e 20 73 6f 20 74 68 65 20  solution so the 
220b0 73 69 78 20 6c 65 61 73 74 20 73 69 67 6e 69 66  six least signif
220c0 69 63 61 6e 74 0a 2a 2a 20 64 69 67 69 74 73 20  icant.** digits 
220d0 69 6e 20 74 68 65 20 74 69 6d 65 20 61 72 65 20  in the time are 
220e0 6d 65 61 6e 69 6e 67 6c 65 73 73 2e 20 20 46 75  meaningless.  Fu
220f0 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66  ture versions of
22100 20 53 51 4c 69 74 65 0a 2a 2a 20 6d 69 67 68 74   SQLite.** might
22110 20 70 72 6f 76 69 64 65 20 67 72 65 61 74 65 72   provide greater
22120 20 72 65 73 6f 6c 75 74 69 6f 6e 20 6f 6e 20 74   resolution on t
22130 68 65 20 70 72 6f 66 69 6c 65 72 20 63 61 6c 6c  he profiler call
22140 62 61 63 6b 2e 20 20 54 68 65 0a 2a 2a 20 73 71  back.  The.** sq
22150 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 29 20  lite3_profile() 
22160 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 6f 6e 73  function is cons
22170 69 64 65 72 65 64 20 65 78 70 65 72 69 6d 65 6e  idered experimen
22180 74 61 6c 20 61 6e 64 20 69 73 0a 2a 2a 20 73 75  tal and is.** su
22190 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67 65 20  bject to change 
221a0 69 6e 20 66 75 74 75 72 65 20 76 65 72 73 69 6f  in future versio
221b0 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f  ns of SQLite..*/
221c0 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54  .SQLITE_DEPRECAT
221d0 45 44 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  ED void *sqlite3
221e0 5f 74 72 61 63 65 28 73 71 6c 69 74 65 33 2a 2c  _trace(sqlite3*,
221f0 0a 20 20 20 76 6f 69 64 28 2a 78 54 72 61 63 65  .   void(*xTrace
22200 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 63 68  )(void*,const ch
22210 61 72 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 53 51  ar*), void*);.SQ
22220 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20  LITE_DEPRECATED 
22230 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 70 72  void *sqlite3_pr
22240 6f 66 69 6c 65 28 73 71 6c 69 74 65 33 2a 2c 0a  ofile(sqlite3*,.
22250 20 20 20 76 6f 69 64 28 2a 78 50 72 6f 66 69 6c     void(*xProfil
22260 65 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 63  e)(void*,const c
22270 68 61 72 2a 2c 73 71 6c 69 74 65 33 5f 75 69 6e  har*,sqlite3_uin
22280 74 36 34 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f  t64), void*);../
22290 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53  *.** CAPI3REF: S
222a0 51 4c 20 54 72 61 63 65 20 45 76 65 6e 74 20 43  QL Trace Event C
222b0 6f 64 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  odes.** KEYWORDS
222c0 3a 20 53 51 4c 49 54 45 5f 54 52 41 43 45 0a 2a  : SQLITE_TRACE.*
222d0 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74  *.** These const
222e0 61 6e 74 73 20 69 64 65 6e 74 69 66 79 20 63 6c  ants identify cl
222f0 61 73 73 65 73 20 6f 66 20 65 76 65 6e 74 73 20  asses of events 
22300 74 68 61 74 20 63 61 6e 20 62 65 20 6d 6f 6e 69  that can be moni
22310 74 6f 72 65 64 0a 2a 2a 20 75 73 69 6e 67 20 74  tored.** using t
22320 68 65 20 5b 73 71 6c 69 74 65 33 5f 74 72 61 63  he [sqlite3_trac
22330 65 5f 76 32 28 29 5d 20 74 72 61 63 69 6e 67 20  e_v2()] tracing 
22340 6c 6f 67 69 63 2e 20 20 54 68 65 20 74 68 69 72  logic.  The thir
22350 64 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f  d argument.** to
22360 20 5b 73 71 6c 69 74 65 33 5f 74 72 61 63 65 5f   [sqlite3_trace_
22370 76 32 28 29 5d 20 69 73 20 61 6e 20 4f 52 2d 65  v2()] is an OR-e
22380 64 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 6f 66  d combination of
22390 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6f 66 0a   one or more of.
223a0 2a 2a 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  ** the following
223b0 20 63 6f 6e 73 74 61 6e 74 73 2e 20 20 5e 54 68   constants.  ^Th
223c0 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
223d0 20 74 6f 20 74 68 65 20 74 72 61 63 65 20 63 61   to the trace ca
223e0 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 6f 6e 65  llback.** is one
223f0 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e   of the followin
22400 67 20 63 6f 6e 73 74 61 6e 74 73 2e 0a 2a 2a 0a  g constants..**.
22410 2a 2a 20 4e 65 77 20 74 72 61 63 69 6e 67 20 63  ** New tracing c
22420 6f 6e 73 74 61 6e 74 73 20 6d 61 79 20 62 65 20  onstants may be 
22430 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20  added in future 
22440 72 65 6c 65 61 73 65 73 2e 0a 2a 2a 0a 2a 2a 20  releases..**.** 
22450 5e 41 20 74 72 61 63 65 20 63 61 6c 6c 62 61 63  ^A trace callbac
22460 6b 20 68 61 73 20 66 6f 75 72 20 61 72 67 75 6d  k has four argum
22470 65 6e 74 73 3a 20 78 43 61 6c 6c 62 61 63 6b 28  ents: xCallback(
22480 54 2c 43 2c 50 2c 58 29 2e 0a 2a 2a 20 5e 54 68  T,C,P,X)..** ^Th
22490 65 20 54 20 61 72 67 75 6d 65 6e 74 20 69 73 20  e T argument is 
224a0 6f 6e 65 20 6f 66 20 74 68 65 20 69 6e 74 65 67  one of the integ
224b0 65 72 20 74 79 70 65 20 63 6f 64 65 73 20 61 62  er type codes ab
224c0 6f 76 65 2e 0a 2a 2a 20 5e 54 68 65 20 43 20 61  ove..** ^The C a
224d0 72 67 75 6d 65 6e 74 20 69 73 20 61 20 63 6f 70  rgument is a cop
224e0 79 20 6f 66 20 74 68 65 20 63 6f 6e 74 65 78 74  y of the context
224f0 20 70 6f 69 6e 74 65 72 20 70 61 73 73 65 64 20   pointer passed 
22500 69 6e 20 61 73 20 74 68 65 0a 2a 2a 20 66 6f 75  in as the.** fou
22510 72 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  rth argument to 
22520 5b 73 71 6c 69 74 65 33 5f 74 72 61 63 65 5f 76  [sqlite3_trace_v
22530 32 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 50 20 61  2()]..** The P a
22540 6e 64 20 58 20 61 72 67 75 6d 65 6e 74 73 20 61  nd X arguments a
22550 72 65 20 70 6f 69 6e 74 65 72 73 20 77 68 6f 73  re pointers whos
22560 65 20 6d 65 61 6e 69 6e 67 73 20 64 65 70 65 6e  e meanings depen
22570 64 20 6f 6e 20 54 2e 0a 2a 2a 0a 2a 2a 20 3c 64  d on T..**.** <d
22580 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 54  l>.** [[SQLITE_T
22590 52 41 43 45 5f 53 54 4d 54 5d 5d 20 3c 64 74 3e  RACE_STMT]] <dt>
225a0 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 53 54 4d  SQLITE_TRACE_STM
225b0 54 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 5e 41  T</dt>.** <dd>^A
225c0 6e 20 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 53  n SQLITE_TRACE_S
225d0 54 4d 54 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  TMT callback is 
225e0 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 61 20 70  invoked when a p
225f0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
22600 74 0a 2a 2a 20 66 69 72 73 74 20 62 65 67 69 6e  t.** first begin
22610 73 20 72 75 6e 6e 69 6e 67 20 61 6e 64 20 70 6f  s running and po
22620 73 73 69 62 6c 79 20 61 74 20 6f 74 68 65 72 20  ssibly at other 
22630 74 69 6d 65 73 20 64 75 72 69 6e 67 20 74 68 65  times during the
22640 0a 2a 2a 20 65 78 65 63 75 74 69 6f 6e 20 6f 66  .** execution of
22650 20 74 68 65 20 70 72 65 70 61 72 65 64 20 73 74   the prepared st
22660 61 74 65 6d 65 6e 74 2c 20 73 75 63 68 20 61 73  atement, such as
22670 20 61 74 20 74 68 65 20 73 74 61 72 74 20 6f 66   at the start of
22680 20 65 61 63 68 0a 2a 2a 20 74 72 69 67 67 65 72   each.** trigger
22690 20 73 75 62 70 72 6f 67 72 61 6d 2e 20 5e 54 68   subprogram. ^Th
226a0 65 20 50 20 61 72 67 75 6d 65 6e 74 20 69 73 20  e P argument is 
226b0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
226c0 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74  .** [prepared st
226d0 61 74 65 6d 65 6e 74 5d 2e 20 5e 54 68 65 20 58  atement]. ^The X
226e0 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70   argument is a p
226f0 6f 69 6e 74 65 72 20 74 6f 20 61 20 73 74 72 69  ointer to a stri
22700 6e 67 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 74  ng which.** is t
22710 68 65 20 75 6e 65 78 70 61 6e 64 65 64 20 53 51  he unexpanded SQ
22720 4c 20 74 65 78 74 20 6f 66 20 74 68 65 20 70 72  L text of the pr
22730 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
22740 20 6f 72 20 61 6e 20 53 51 4c 20 63 6f 6d 6d 65   or an SQL comme
22750 6e 74 20 0a 2a 2a 20 74 68 61 74 20 69 6e 64 69  nt .** that indi
22760 63 61 74 65 73 20 74 68 65 20 69 6e 76 6f 63 61  cates the invoca
22770 74 69 6f 6e 20 6f 66 20 61 20 74 72 69 67 67 65  tion of a trigge
22780 72 2e 20 20 5e 54 68 65 20 63 61 6c 6c 62 61 63  r.  ^The callbac
22790 6b 20 63 61 6e 20 63 6f 6d 70 75 74 65 0a 2a 2a  k can compute.**
227a0 20 74 68 65 20 73 61 6d 65 20 74 65 78 74 20 74   the same text t
227b0 68 61 74 20 77 6f 75 6c 64 20 68 61 76 65 20 62  hat would have b
227c0 65 65 6e 20 72 65 74 75 72 6e 65 64 20 62 79 20  een returned by 
227d0 74 68 65 20 6c 65 67 61 63 79 20 5b 73 71 6c 69  the legacy [sqli
227e0 74 65 33 5f 74 72 61 63 65 28 29 5d 0a 2a 2a 20  te3_trace()].** 
227f0 69 6e 74 65 72 66 61 63 65 20 62 79 20 75 73 69  interface by usi
22800 6e 67 20 74 68 65 20 58 20 61 72 67 75 6d 65 6e  ng the X argumen
22810 74 20 77 68 65 6e 20 58 20 62 65 67 69 6e 73 20  t when X begins 
22820 77 69 74 68 20 22 2d 2d 22 20 61 6e 64 20 69 6e  with "--" and in
22830 76 6f 6b 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74  voking.** [sqlit
22840 65 33 5f 65 78 70 61 6e 64 65 64 5f 73 71 6c 28  e3_expanded_sql(
22850 50 29 5d 20 6f 74 68 65 72 77 69 73 65 2e 0a 2a  P)] otherwise..*
22860 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 54 52  *.** [[SQLITE_TR
22870 41 43 45 5f 50 52 4f 46 49 4c 45 5d 5d 20 3c 64  ACE_PROFILE]] <d
22880 74 3e 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 50  t>SQLITE_TRACE_P
22890 52 4f 46 49 4c 45 3c 2f 64 74 3e 0a 2a 2a 20 3c  ROFILE</dt>.** <
228a0 64 64 3e 5e 41 6e 20 53 51 4c 49 54 45 5f 54 52  dd>^An SQLITE_TR
228b0 41 43 45 5f 50 52 4f 46 49 4c 45 20 63 61 6c 6c  ACE_PROFILE call
228c0 62 61 63 6b 20 70 72 6f 76 69 64 65 73 20 61 70  back provides ap
228d0 70 72 6f 78 69 6d 61 74 65 6c 79 20 74 68 65 20  proximately the 
228e0 73 61 6d 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74  same.** informat
228f0 69 6f 6e 20 61 73 20 69 73 20 70 72 6f 76 69 64  ion as is provid
22900 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74  ed by the [sqlit
22910 65 33 5f 70 72 6f 66 69 6c 65 28 29 5d 20 63 61  e3_profile()] ca
22920 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 5e 54 68 65 20  llback..** ^The 
22930 50 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20  P argument is a 
22940 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b  pointer to the [
22950 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
22960 6e 74 5d 20 61 6e 64 20 74 68 65 0a 2a 2a 20 58  nt] and the.** X
22970 20 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e 74 73   argument points
22980 20 74 6f 20 61 20 36 34 2d 62 69 74 20 69 6e 74   to a 64-bit int
22990 65 67 65 72 20 77 68 69 63 68 20 69 73 20 74 68  eger which is th
229a0 65 20 65 73 74 69 6d 61 74 65 64 20 6f 66 0a 2a  e estimated of.*
229b0 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  * the number of 
229c0 6e 61 6e 6f 73 65 63 6f 6e 64 20 74 68 61 74 20  nanosecond that 
229d0 74 68 65 20 70 72 65 70 61 72 65 64 20 73 74 61  the prepared sta
229e0 74 65 6d 65 6e 74 20 74 6f 6f 6b 20 74 6f 20 72  tement took to r
229f0 75 6e 2e 0a 2a 2a 20 5e 54 68 65 20 53 51 4c 49  un..** ^The SQLI
22a00 54 45 5f 54 52 41 43 45 5f 50 52 4f 46 49 4c 45  TE_TRACE_PROFILE
22a10 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76   callback is inv
22a20 6f 6b 65 64 20 77 68 65 6e 20 74 68 65 20 73 74  oked when the st
22a30 61 74 65 6d 65 6e 74 20 66 69 6e 69 73 68 65 73  atement finishes
22a40 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  ..**.** [[SQLITE
22a50 5f 54 52 41 43 45 5f 52 4f 57 5d 5d 20 3c 64 74  _TRACE_ROW]] <dt
22a60 3e 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 52 4f  >SQLITE_TRACE_RO
22a70 57 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 5e 41  W</dt>.** <dd>^A
22a80 6e 20 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 52  n SQLITE_TRACE_R
22a90 4f 57 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69  OW callback is i
22aa0 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 20  nvoked whenever 
22ab0 61 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74  a prepared.** st
22ac0 61 74 65 6d 65 6e 74 20 67 65 6e 65 72 61 74 65  atement generate
22ad0 73 20 61 20 73 69 6e 67 6c 65 20 72 6f 77 20 6f  s a single row o
22ae0 66 20 72 65 73 75 6c 74 2e 20 20 0a 2a 2a 20 5e  f result.  .** ^
22af0 54 68 65 20 50 20 61 72 67 75 6d 65 6e 74 20 69  The P argument i
22b00 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  s a pointer to t
22b10 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
22b20 74 65 6d 65 6e 74 5d 20 61 6e 64 20 74 68 65 0a  tement] and the.
22b30 2a 2a 20 58 20 61 72 67 75 6d 65 6e 74 20 69 73  ** X argument is
22b40 20 75 6e 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 5b   unused..**.** [
22b50 5b 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 43 4c  [SQLITE_TRACE_CL
22b60 4f 53 45 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45  OSE]] <dt>SQLITE
22b70 5f 54 52 41 43 45 5f 43 4c 4f 53 45 3c 2f 64 74  _TRACE_CLOSE</dt
22b80 3e 0a 2a 2a 20 3c 64 64 3e 5e 41 6e 20 53 51 4c  >.** <dd>^An SQL
22b90 49 54 45 5f 54 52 41 43 45 5f 43 4c 4f 53 45 20  ITE_TRACE_CLOSE 
22ba0 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f  callback is invo
22bb0 6b 65 64 20 77 68 65 6e 20 61 20 64 61 74 61 62  ked when a datab
22bc0 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f  ase.** connectio
22bd0 6e 20 63 6c 6f 73 65 73 2e 0a 2a 2a 20 5e 54 68  n closes..** ^Th
22be0 65 20 50 20 61 72 67 75 6d 65 6e 74 20 69 73 20  e P argument is 
22bf0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
22c00 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
22c10 63 74 69 6f 6e 5d 20 6f 62 6a 65 63 74 0a 2a 2a  ction] object.**
22c20 20 61 6e 64 20 74 68 65 20 58 20 61 72 67 75 6d   and the X argum
22c30 65 6e 74 20 69 73 20 75 6e 75 73 65 64 2e 0a 2a  ent is unused..*
22c40 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69  * </dl>.*/.#defi
22c50 6e 65 20 53 51 4c 49 54 45 5f 54 52 41 43 45 5f  ne SQLITE_TRACE_
22c60 53 54 4d 54 20 20 20 20 20 20 20 30 78 30 31 0a  STMT       0x01.
22c70 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54  #define SQLITE_T
22c80 52 41 43 45 5f 50 52 4f 46 49 4c 45 20 20 20 20  RACE_PROFILE    
22c90 30 78 30 32 0a 23 64 65 66 69 6e 65 20 53 51 4c  0x02.#define SQL
22ca0 49 54 45 5f 54 52 41 43 45 5f 52 4f 57 20 20 20  ITE_TRACE_ROW   
22cb0 20 20 20 20 20 30 78 30 34 0a 23 64 65 66 69 6e       0x04.#defin
22cc0 65 20 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 43  e SQLITE_TRACE_C
22cd0 4c 4f 53 45 20 20 20 20 20 20 30 78 30 38 0a 0a  LOSE      0x08..
22ce0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
22cf0 53 51 4c 20 54 72 61 63 65 20 48 6f 6f 6b 0a 2a  SQL Trace Hook.*
22d00 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65  * METHOD: sqlite
22d10 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  3.**.** ^The sql
22d20 69 74 65 33 5f 74 72 61 63 65 5f 76 32 28 44 2c  ite3_trace_v2(D,
22d30 4d 2c 58 2c 50 29 20 69 6e 74 65 72 66 61 63 65  M,X,P) interface
22d40 20 72 65 67 69 73 74 65 72 73 20 61 20 74 72 61   registers a tra
22d50 63 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66  ce callback.** f
22d60 75 6e 63 74 69 6f 6e 20 58 20 61 67 61 69 6e 73  unction X agains
22d70 74 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  t [database conn
22d80 65 63 74 69 6f 6e 5d 20 44 2c 20 75 73 69 6e 67  ection] D, using
22d90 20 70 72 6f 70 65 72 74 79 20 6d 61 73 6b 20 4d   property mask M
22da0 0a 2a 2a 20 61 6e 64 20 63 6f 6e 74 65 78 74 20  .** and context 
22db0 70 6f 69 6e 74 65 72 20 50 2e 20 20 5e 49 66 20  pointer P.  ^If 
22dc0 74 68 65 20 58 20 63 61 6c 6c 62 61 63 6b 20 69  the X callback i
22dd0 73 0a 2a 2a 20 4e 55 4c 4c 20 6f 72 20 69 66 20  s.** NULL or if 
22de0 74 68 65 20 4d 20 6d 61 73 6b 20 69 73 20 7a 65  the M mask is ze
22df0 72 6f 2c 20 74 68 65 6e 20 74 72 61 63 69 6e 67  ro, then tracing
22e00 20 69 73 20 64 69 73 61 62 6c 65 64 2e 20 20 54   is disabled.  T
22e10 68 65 0a 2a 2a 20 4d 20 61 72 67 75 6d 65 6e 74  he.** M argument
22e20 20 73 68 6f 75 6c 64 20 62 65 20 74 68 65 20 62   should be the b
22e30 69 74 77 69 73 65 20 4f 52 2d 65 64 20 63 6f 6d  itwise OR-ed com
22e40 62 69 6e 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20 7a  bination of.** z
22e50 65 72 6f 20 6f 72 20 6d 6f 72 65 20 5b 53 51 4c  ero or more [SQL
22e60 49 54 45 5f 54 52 41 43 45 5d 20 63 6f 6e 73 74  ITE_TRACE] const
22e70 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 45 61 63  ants..**.** ^Eac
22e80 68 20 63 61 6c 6c 20 74 6f 20 65 69 74 68 65 72  h call to either
22e90 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29   sqlite3_trace()
22ea0 20 6f 72 20 73 71 6c 69 74 65 33 5f 74 72 61 63   or sqlite3_trac
22eb0 65 5f 76 32 28 29 20 6f 76 65 72 72 69 64 65 73  e_v2() overrides
22ec0 20 0a 2a 2a 20 28 63 61 6e 63 65 6c 73 29 20 61   .** (cancels) a
22ed0 6e 79 20 70 72 69 6f 72 20 63 61 6c 6c 73 20 74  ny prior calls t
22ee0 6f 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28  o sqlite3_trace(
22ef0 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 74 72 61  ) or sqlite3_tra
22f00 63 65 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e  ce_v2()..**.** ^
22f10 54 68 65 20 58 20 63 61 6c 6c 62 61 63 6b 20 69  The X callback i
22f20 73 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76  s invoked whenev
22f30 65 72 20 61 6e 79 20 6f 66 20 74 68 65 20 65 76  er any of the ev
22f40 65 6e 74 73 20 69 64 65 6e 74 69 66 69 65 64 20  ents identified 
22f50 62 79 20 0a 2a 2a 20 6d 61 73 6b 20 4d 20 6f 63  by .** mask M oc
22f60 63 75 72 2e 20 20 5e 54 68 65 20 69 6e 74 65 67  cur.  ^The integ
22f70 65 72 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20  er return value 
22f80 66 72 6f 6d 20 74 68 65 20 63 61 6c 6c 62 61 63  from the callbac
22f90 6b 20 69 73 20 63 75 72 72 65 6e 74 6c 79 0a 2a  k is currently.*
22fa0 2a 20 69 67 6e 6f 72 65 64 2c 20 74 68 6f 75 67  * ignored, thoug
22fb0 68 20 74 68 69 73 20 6d 61 79 20 63 68 61 6e 67  h this may chang
22fc0 65 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65  e in future rele
22fd0 61 73 65 73 2e 20 20 43 61 6c 6c 62 61 63 6b 0a  ases.  Callback.
22fe0 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ** implementatio
22ff0 6e 73 20 73 68 6f 75 6c 64 20 72 65 74 75 72 6e  ns should return
23000 20 7a 65 72 6f 20 74 6f 20 65 6e 73 75 72 65 20   zero to ensure 
23010 66 75 74 75 72 65 20 63 6f 6d 70 61 74 69 62 69  future compatibi
23020 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 41 20 74  lity..**.** ^A t
23030 72 61 63 65 20 63 61 6c 6c 62 61 63 6b 20 69 73  race callback is
23040 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 66 6f   invoked with fo
23050 75 72 20 61 72 67 75 6d 65 6e 74 73 3a 20 63 61  ur arguments: ca
23060 6c 6c 62 61 63 6b 28 54 2c 43 2c 50 2c 58 29 2e  llback(T,C,P,X).
23070 0a 2a 2a 20 5e 54 68 65 20 54 20 61 72 67 75 6d  .** ^The T argum
23080 65 6e 74 20 69 73 20 6f 6e 65 20 6f 66 20 74 68  ent is one of th
23090 65 20 5b 53 51 4c 49 54 45 5f 54 52 41 43 45 5d  e [SQLITE_TRACE]
230a0 0a 2a 2a 20 63 6f 6e 73 74 61 6e 74 73 20 74 6f  .** constants to
230b0 20 69 6e 64 69 63 61 74 65 20 77 68 79 20 74 68   indicate why th
230c0 65 20 63 61 6c 6c 62 61 63 6b 20 77 61 73 20 69  e callback was i
230d0 6e 76 6f 6b 65 64 2e 0a 2a 2a 20 5e 54 68 65 20  nvoked..** ^The 
230e0 43 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20  C argument is a 
230f0 63 6f 70 79 20 6f 66 20 74 68 65 20 63 6f 6e 74  copy of the cont
23100 65 78 74 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 20  ext pointer..** 
23110 54 68 65 20 50 20 61 6e 64 20 58 20 61 72 67 75  The P and X argu
23120 6d 65 6e 74 73 20 61 72 65 20 70 6f 69 6e 74 65  ments are pointe
23130 72 73 20 77 68 6f 73 65 20 6d 65 61 6e 69 6e 67  rs whose meaning
23140 73 20 64 65 70 65 6e 64 20 6f 6e 20 54 2e 0a 2a  s depend on T..*
23150 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
23160 5f 74 72 61 63 65 5f 76 32 28 29 20 69 6e 74 65  _trace_v2() inte
23170 72 66 61 63 65 20 69 73 20 69 6e 74 65 6e 64 65  rface is intende
23180 64 20 74 6f 20 72 65 70 6c 61 63 65 20 74 68 65  d to replace the
23190 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72   legacy.** inter
231a0 66 61 63 65 73 20 5b 73 71 6c 69 74 65 33 5f 74  faces [sqlite3_t
231b0 72 61 63 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c  race()] and [sql
231c0 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 29 5d 2c  ite3_profile()],
231d0 20 62 6f 74 68 20 6f 66 20 77 68 69 63 68 0a 2a   both of which.*
231e0 2a 20 61 72 65 20 64 65 70 72 65 63 61 74 65 64  * are deprecated
231f0 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
23200 5f 74 72 61 63 65 5f 76 32 28 0a 20 20 73 71 6c  _trace_v2(.  sql
23210 69 74 65 33 2a 2c 0a 20 20 75 6e 73 69 67 6e 65  ite3*,.  unsigne
23220 64 20 75 4d 61 73 6b 2c 0a 20 20 69 6e 74 28 2a  d uMask,.  int(*
23230 78 43 61 6c 6c 62 61 63 6b 29 28 75 6e 73 69 67  xCallback)(unsig
23240 6e 65 64 2c 76 6f 69 64 2a 2c 76 6f 69 64 2a 2c  ned,void*,void*,
23250 76 6f 69 64 2a 29 2c 0a 20 20 76 6f 69 64 20 2a  void*),.  void *
23260 70 43 74 78 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  pCtx.);../*.** C
23270 41 50 49 33 52 45 46 3a 20 51 75 65 72 79 20 50  API3REF: Query P
23280 72 6f 67 72 65 73 73 20 43 61 6c 6c 62 61 63 6b  rogress Callback
23290 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  s.** METHOD: sql
232a0 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ite3.**.** ^The 
232b0 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73  sqlite3_progress
232c0 5f 68 61 6e 64 6c 65 72 28 44 2c 4e 2c 58 2c 50  _handler(D,N,X,P
232d0 29 20 69 6e 74 65 72 66 61 63 65 20 63 61 75 73  ) interface caus
232e0 65 73 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 0a  es the callback.
232f0 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 58 20 74 6f  ** function X to
23300 20 62 65 20 69 6e 76 6f 6b 65 64 20 70 65 72 69   be invoked peri
23310 6f 64 69 63 61 6c 6c 79 20 64 75 72 69 6e 67 20  odically during 
23320 6c 6f 6e 67 20 72 75 6e 6e 69 6e 67 20 63 61 6c  long running cal
23330 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  ls to.** [sqlite
23340 33 5f 65 78 65 63 28 29 5d 2c 20 5b 73 71 6c 69  3_exec()], [sqli
23350 74 65 33 5f 73 74 65 70 28 29 5d 20 61 6e 64 20  te3_step()] and 
23360 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62  [sqlite3_get_tab
23370 6c 65 28 29 5d 20 66 6f 72 0a 2a 2a 20 64 61 74  le()] for.** dat
23380 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
23390 20 44 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65 20   D.  An example 
233a0 75 73 65 20 66 6f 72 20 74 68 69 73 0a 2a 2a 20  use for this.** 
233b0 69 6e 74 65 72 66 61 63 65 20 69 73 20 74 6f 20  interface is to 
233c0 6b 65 65 70 20 61 20 47 55 49 20 75 70 64 61 74  keep a GUI updat
233d0 65 64 20 64 75 72 69 6e 67 20 61 20 6c 61 72 67  ed during a larg
233e0 65 20 71 75 65 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e  e query..**.** ^
233f0 54 68 65 20 70 61 72 61 6d 65 74 65 72 20 50 20  The parameter P 
23400 69 73 20 70 61 73 73 65 64 20 74 68 72 6f 75 67  is passed throug
23410 68 20 61 73 20 74 68 65 20 6f 6e 6c 79 20 70 61  h as the only pa
23420 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 0a  rameter to the .
23430 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63  ** callback func
23440 74 69 6f 6e 20 58 2e 20 20 5e 54 68 65 20 70 61  tion X.  ^The pa
23450 72 61 6d 65 74 65 72 20 4e 20 69 73 20 74 68 65  rameter N is the
23460 20 61 70 70 72 6f 78 69 6d 61 74 65 20 6e 75 6d   approximate num
23470 62 65 72 20 6f 66 20 0a 2a 2a 20 5b 76 69 72 74  ber of .** [virt
23480 75 61 6c 20 6d 61 63 68 69 6e 65 20 69 6e 73 74  ual machine inst
23490 72 75 63 74 69 6f 6e 73 5d 20 74 68 61 74 20 61  ructions] that a
234a0 72 65 20 65 76 61 6c 75 61 74 65 64 20 62 65 74  re evaluated bet
234b0 77 65 65 6e 20 73 75 63 63 65 73 73 69 76 65 0a  ween successive.
234c0 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f  ** invocations o
234d0 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 58  f the callback X
234e0 2e 20 20 5e 49 66 20 4e 20 69 73 20 6c 65 73 73  .  ^If N is less
234f0 20 74 68 61 6e 20 6f 6e 65 20 74 68 65 6e 20 74   than one then t
23500 68 65 20 70 72 6f 67 72 65 73 73 0a 2a 2a 20 68  he progress.** h
23510 61 6e 64 6c 65 72 20 69 73 20 64 69 73 61 62 6c  andler is disabl
23520 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 6c 79 20  ed..**.** ^Only 
23530 61 20 73 69 6e 67 6c 65 20 70 72 6f 67 72 65 73  a single progres
23540 73 20 68 61 6e 64 6c 65 72 20 6d 61 79 20 62 65  s handler may be
23550 20 64 65 66 69 6e 65 64 20 61 74 20 6f 6e 65 20   defined at one 
23560 74 69 6d 65 20 70 65 72 0a 2a 2a 20 5b 64 61 74  time per.** [dat
23570 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
23580 5d 3b 20 73 65 74 74 69 6e 67 20 61 20 6e 65 77  ]; setting a new
23590 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65   progress handle
235a0 72 20 63 61 6e 63 65 6c 73 20 74 68 65 0a 2a 2a  r cancels the.**
235b0 20 6f 6c 64 20 6f 6e 65 2e 20 20 5e 53 65 74 74   old one.  ^Sett
235c0 69 6e 67 20 70 61 72 61 6d 65 74 65 72 20 58 20  ing parameter X 
235d0 74 6f 20 4e 55 4c 4c 20 64 69 73 61 62 6c 65 73  to NULL disables
235e0 20 74 68 65 20 70 72 6f 67 72 65 73 73 20 68 61   the progress ha
235f0 6e 64 6c 65 72 2e 0a 2a 2a 20 5e 54 68 65 20 70  ndler..** ^The p
23600 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20  rogress handler 
23610 69 73 20 61 6c 73 6f 20 64 69 73 61 62 6c 65 64  is also disabled
23620 20 62 79 20 73 65 74 74 69 6e 67 20 4e 20 74 6f   by setting N to
23630 20 61 20 76 61 6c 75 65 20 6c 65 73 73 0a 2a 2a   a value less.**
23640 20 74 68 61 6e 20 31 2e 0a 2a 2a 0a 2a 2a 20 5e   than 1..**.** ^
23650 49 66 20 74 68 65 20 70 72 6f 67 72 65 73 73 20  If the progress 
23660 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73  callback returns
23670 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 20 6f   non-zero, the o
23680 70 65 72 61 74 69 6f 6e 20 69 73 0a 2a 2a 20 69  peration is.** i
23690 6e 74 65 72 72 75 70 74 65 64 2e 20 20 54 68 69  nterrupted.  Thi
236a0 73 20 66 65 61 74 75 72 65 20 63 61 6e 20 62 65  s feature can be
236b0 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65   used to impleme
236c0 6e 74 20 61 0a 2a 2a 20 22 43 61 6e 63 65 6c 22  nt a.** "Cancel"
236d0 20 62 75 74 74 6f 6e 20 6f 6e 20 61 20 47 55 49   button on a GUI
236e0 20 70 72 6f 67 72 65 73 73 20 64 69 61 6c 6f 67   progress dialog
236f0 20 62 6f 78 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20   box..**.** The 
23700 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72  progress handler
23710 20 63 61 6c 6c 62 61 63 6b 20 6d 75 73 74 20 6e   callback must n
23720 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e 67 20 74  ot do anything t
23730 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a  hat will modify.
23740 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ** the database 
23750 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20  connection that 
23760 69 6e 76 6f 6b 65 64 20 74 68 65 20 70 72 6f 67  invoked the prog
23770 72 65 73 73 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a  ress handler..**
23780 20 4e 6f 74 65 20 74 68 61 74 20 5b 73 71 6c 69   Note that [sqli
23790 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
237a0 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73  ] and [sqlite3_s
237b0 74 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69  tep()] both modi
237c0 66 79 20 74 68 65 69 72 0a 2a 2a 20 64 61 74 61  fy their.** data
237d0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  base connections
237e0 20 66 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e 67   for the meaning
237f0 20 6f 66 20 22 6d 6f 64 69 66 79 22 20 69 6e 20   of "modify" in 
23800 74 68 69 73 20 70 61 72 61 67 72 61 70 68 2e 0a  this paragraph..
23810 2a 2a 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74  **.*/.void sqlit
23820 65 33 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e 64  e3_progress_hand
23830 6c 65 72 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e  ler(sqlite3*, in
23840 74 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a 29  t, int(*)(void*)
23850 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  , void*);../*.**
23860 20 43 41 50 49 33 52 45 46 3a 20 4f 70 65 6e 69   CAPI3REF: Openi
23870 6e 67 20 41 20 4e 65 77 20 44 61 74 61 62 61 73  ng A New Databas
23880 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20  e Connection.** 
23890 43 4f 4e 53 54 52 55 43 54 4f 52 3a 20 73 71 6c  CONSTRUCTOR: sql
238a0 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73  ite3.**.** ^Thes
238b0 65 20 72 6f 75 74 69 6e 65 73 20 6f 70 65 6e 20  e routines open 
238c0 61 6e 20 53 51 4c 69 74 65 20 64 61 74 61 62 61  an SQLite databa
238d0 73 65 20 66 69 6c 65 20 61 73 20 73 70 65 63 69  se file as speci
238e0 66 69 65 64 20 62 79 20 74 68 65 20 0a 2a 2a 20  fied by the .** 
238f0 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e  filename argumen
23900 74 2e 20 5e 54 68 65 20 66 69 6c 65 6e 61 6d 65  t. ^The filename
23910 20 61 72 67 75 6d 65 6e 74 20 69 73 20 69 6e 74   argument is int
23920 65 72 70 72 65 74 65 64 20 61 73 20 55 54 46 2d  erpreted as UTF-
23930 38 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33  8 for.** sqlite3
23940 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69  _open() and sqli
23950 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 61 6e  te3_open_v2() an
23960 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20 74  d as UTF-16 in t
23970 68 65 20 6e 61 74 69 76 65 20 62 79 74 65 0a 2a  he native byte.*
23980 2a 20 6f 72 64 65 72 20 66 6f 72 20 73 71 6c 69  * order for sqli
23990 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e 20 5e 28  te3_open16(). ^(
239a0 41 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  A [database conn
239b0 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 20 69  ection] handle i
239c0 73 20 75 73 75 61 6c 6c 79 0a 2a 2a 20 72 65 74  s usually.** ret
239d0 75 72 6e 65 64 20 69 6e 20 2a 70 70 44 62 2c 20  urned in *ppDb, 
239e0 65 76 65 6e 20 69 66 20 61 6e 20 65 72 72 6f 72  even if an error
239f0 20 6f 63 63 75 72 73 2e 20 20 54 68 65 20 6f 6e   occurs.  The on
23a00 6c 79 20 65 78 63 65 70 74 69 6f 6e 20 69 73 20  ly exception is 
23a10 74 68 61 74 0a 2a 2a 20 69 66 20 53 51 4c 69 74  that.** if SQLit
23a20 65 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 61  e is unable to a
23a30 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20 74  llocate memory t
23a40 6f 20 68 6f 6c 64 20 74 68 65 20 5b 73 71 6c 69  o hold the [sqli
23a50 74 65 33 5d 20 6f 62 6a 65 63 74 2c 0a 2a 2a 20  te3] object,.** 
23a60 61 20 4e 55 4c 4c 20 77 69 6c 6c 20 62 65 20 77  a NULL will be w
23a70 72 69 74 74 65 6e 20 69 6e 74 6f 20 2a 70 70 44  ritten into *ppD
23a80 62 20 69 6e 73 74 65 61 64 20 6f 66 20 61 20 70  b instead of a p
23a90 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 73  ointer to the [s
23aa0 71 6c 69 74 65 33 5d 0a 2a 2a 20 6f 62 6a 65 63  qlite3].** objec
23ab0 74 2e 29 5e 20 5e 28 49 66 20 74 68 65 20 64 61  t.)^ ^(If the da
23ac0 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64  tabase is opened
23ad0 20 28 61 6e 64 2f 6f 72 20 63 72 65 61 74 65 64   (and/or created
23ae0 29 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2c 20  ) successfully, 
23af0 74 68 65 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  then.** [SQLITE_
23b00 4f 4b 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e  OK] is returned.
23b10 20 20 4f 74 68 65 72 77 69 73 65 20 61 6e 20 5b    Otherwise an [
23b20 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72  error code] is r
23b30 65 74 75 72 6e 65 64 2e 29 5e 20 5e 54 68 65 0a  eturned.)^ ^The.
23b40 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d  ** [sqlite3_errm
23b50 73 67 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  sg()] or [sqlite
23b60 33 5f 65 72 72 6d 73 67 31 36 28 29 5d 20 72 6f  3_errmsg16()] ro
23b70 75 74 69 6e 65 73 20 63 61 6e 20 62 65 20 75 73  utines can be us
23b80 65 64 20 74 6f 20 6f 62 74 61 69 6e 0a 2a 2a 20  ed to obtain.** 
23b90 61 6e 20 45 6e 67 6c 69 73 68 20 6c 61 6e 67 75  an English langu
23ba0 61 67 65 20 64 65 73 63 72 69 70 74 69 6f 6e 20  age description 
23bb0 6f 66 20 74 68 65 20 65 72 72 6f 72 20 66 6f 6c  of the error fol
23bc0 6c 6f 77 69 6e 67 20 61 20 66 61 69 6c 75 72 65  lowing a failure
23bd0 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66 20 74 68   of any.** of th
23be0 65 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29  e sqlite3_open()
23bf0 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a   routines..**.**
23c00 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20 65 6e   ^The default en
23c10 63 6f 64 69 6e 67 20 77 69 6c 6c 20 62 65 20 55  coding will be U
23c20 54 46 2d 38 20 66 6f 72 20 64 61 74 61 62 61 73  TF-8 for databas
23c30 65 73 20 63 72 65 61 74 65 64 20 75 73 69 6e 67  es created using
23c40 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  .** sqlite3_open
23c50 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70  () or sqlite3_op
23c60 65 6e 5f 76 32 28 29 2e 20 20 5e 54 68 65 20 64  en_v2().  ^The d
23c70 65 66 61 75 6c 74 20 65 6e 63 6f 64 69 6e 67 20  efault encoding 
23c80 66 6f 72 20 64 61 74 61 62 61 73 65 73 0a 2a 2a  for databases.**
23c90 20 63 72 65 61 74 65 64 20 75 73 69 6e 67 20 73   created using s
23ca0 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 20  qlite3_open16() 
23cb0 77 69 6c 6c 20 62 65 20 55 54 46 2d 31 36 20 69  will be UTF-16 i
23cc0 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 74  n the native byt
23cd0 65 20 6f 72 64 65 72 2e 0a 2a 2a 0a 2a 2a 20 57  e order..**.** W
23ce0 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 61 6e  hether or not an
23cf0 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 77 68   error occurs wh
23d00 65 6e 20 69 74 20 69 73 20 6f 70 65 6e 65 64 2c  en it is opened,
23d10 20 72 65 73 6f 75 72 63 65 73 0a 2a 2a 20 61 73   resources.** as
23d20 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68  sociated with th
23d30 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
23d40 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 20 73  ection] handle s
23d50 68 6f 75 6c 64 20 62 65 20 72 65 6c 65 61 73 65  hould be release
23d60 64 20 62 79 0a 2a 2a 20 70 61 73 73 69 6e 67 20  d by.** passing 
23d70 69 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  it to [sqlite3_c
23d80 6c 6f 73 65 28 29 5d 20 77 68 65 6e 20 69 74 20  lose()] when it 
23d90 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 72 65 71  is no longer req
23da0 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  uired..**.** The
23db0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
23dc0 28 29 20 69 6e 74 65 72 66 61 63 65 20 77 6f 72  () interface wor
23dd0 6b 73 20 6c 69 6b 65 20 73 71 6c 69 74 65 33 5f  ks like sqlite3_
23de0 6f 70 65 6e 28 29 0a 2a 2a 20 65 78 63 65 70 74  open().** except
23df0 20 74 68 61 74 20 69 74 20 61 63 63 65 70 74 73   that it accepts
23e00 20 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20   two additional 
23e10 70 61 72 61 6d 65 74 65 72 73 20 66 6f 72 20 61  parameters for a
23e20 64 64 69 74 69 6f 6e 61 6c 20 63 6f 6e 74 72 6f  dditional contro
23e30 6c 0a 2a 2a 20 6f 76 65 72 20 74 68 65 20 6e 65  l.** over the ne
23e40 77 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  w database conne
23e50 63 74 69 6f 6e 2e 20 20 5e 28 54 68 65 20 66 6c  ction.  ^(The fl
23e60 61 67 73 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ags parameter to
23e70 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  .** sqlite3_open
23e80 5f 76 32 28 29 20 63 61 6e 20 74 61 6b 65 20 6f  _v2() can take o
23e90 6e 65 20 6f 66 0a 2a 2a 20 74 68 65 20 66 6f 6c  ne of.** the fol
23ea0 6c 6f 77 69 6e 67 20 74 68 72 65 65 20 76 61 6c  lowing three val
23eb0 75 65 73 2c 20 6f 70 74 69 6f 6e 61 6c 6c 79 20  ues, optionally 
23ec0 63 6f 6d 62 69 6e 65 64 20 77 69 74 68 20 74 68  combined with th
23ed0 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50  e .** [SQLITE_OP
23ee0 45 4e 5f 4e 4f 4d 55 54 45 58 5d 2c 20 5b 53 51  EN_NOMUTEX], [SQ
23ef0 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55  LITE_OPEN_FULLMU
23f00 54 45 58 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 50  TEX], [SQLITE_OP
23f10 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45 5d 2c  EN_SHAREDCACHE],
23f20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  .** [SQLITE_OPEN
23f30 5f 50 52 49 56 41 54 45 43 41 43 48 45 5d 2c 20  _PRIVATECACHE], 
23f40 61 6e 64 2f 6f 72 20 5b 53 51 4c 49 54 45 5f 4f  and/or [SQLITE_O
23f50 50 45 4e 5f 55 52 49 5d 20 66 6c 61 67 73 3a 29  PEN_URI] flags:)
23f60 5e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20  ^.**.** <dl>.** 
23f70 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50  ^(<dt>[SQLITE_OP
23f80 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 3c 2f 64 74  EN_READONLY]</dt
23f90 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 74  >.** <dd>The dat
23fa0 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20  abase is opened 
23fb0 69 6e 20 72 65 61 64 2d 6f 6e 6c 79 20 6d 6f 64  in read-only mod
23fc0 65 2e 20 20 49 66 20 74 68 65 20 64 61 74 61 62  e.  If the datab
23fd0 61 73 65 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20  ase does not.** 
23fe0 61 6c 72 65 61 64 79 20 65 78 69 73 74 2c 20 61  already exist, a
23ff0 6e 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 72  n error is retur
24000 6e 65 64 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a  ned.</dd>)^.**.*
24010 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 45 5f  * ^(<dt>[SQLITE_
24020 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 3c  OPEN_READWRITE]<
24030 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
24040 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e  database is open
24050 65 64 20 66 6f 72 20 72 65 61 64 69 6e 67 20 61  ed for reading a
24060 6e 64 20 77 72 69 74 69 6e 67 20 69 66 20 70 6f  nd writing if po
24070 73 73 69 62 6c 65 2c 20 6f 72 20 72 65 61 64 69  ssible, or readi
24080 6e 67 0a 2a 2a 20 6f 6e 6c 79 20 69 66 20 74 68  ng.** only if th
24090 65 20 66 69 6c 65 20 69 73 20 77 72 69 74 65 20  e file is write 
240a0 70 72 6f 74 65 63 74 65 64 20 62 79 20 74 68 65  protected by the
240b0 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65   operating syste
240c0 6d 2e 20 20 49 6e 20 65 69 74 68 65 72 0a 2a 2a  m.  In either.**
240d0 20 63 61 73 65 20 74 68 65 20 64 61 74 61 62 61   case the databa
240e0 73 65 20 6d 75 73 74 20 61 6c 72 65 61 64 79 20  se must already 
240f0 65 78 69 73 74 2c 20 6f 74 68 65 72 77 69 73 65  exist, otherwise
24100 20 61 6e 20 65 72 72 6f 72 20 69 73 20 72 65 74   an error is ret
24110 75 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a  urned.</dd>)^.**
24120 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54  .** ^(<dt>[SQLIT
24130 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45  E_OPEN_READWRITE
24140 5d 20 7c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  ] | [SQLITE_OPEN
24150 5f 43 52 45 41 54 45 5d 3c 2f 64 74 3e 0a 2a 2a  _CREATE]</dt>.**
24160 20 3c 64 64 3e 54 68 65 20 64 61 74 61 62 61 73   <dd>The databas
24170 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20  e is opened for 
24180 72 65 61 64 69 6e 67 20 61 6e 64 20 77 72 69 74  reading and writ
24190 69 6e 67 2c 20 61 6e 64 20 69 73 20 63 72 65 61  ing, and is crea
241a0 74 65 64 20 69 66 0a 2a 2a 20 69 74 20 64 6f 65  ted if.** it doe
241b0 73 20 6e 6f 74 20 61 6c 72 65 61 64 79 20 65 78  s not already ex
241c0 69 73 74 2e 20 54 68 69 73 20 69 73 20 74 68 65  ist. This is the
241d0 20 62 65 68 61 76 69 6f 72 20 74 68 61 74 20 69   behavior that i
241e0 73 20 61 6c 77 61 79 73 20 75 73 65 64 20 66 6f  s always used fo
241f0 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65  r.** sqlite3_ope
24200 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  n() and sqlite3_
24210 6f 70 65 6e 31 36 28 29 2e 3c 2f 64 64 3e 29 5e  open16().</dd>)^
24220 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2a 0a 2a 2a 20  .** </dl>.**.** 
24230 49 66 20 74 68 65 20 33 72 64 20 70 61 72 61 6d  If the 3rd param
24240 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
24250 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 6e 6f 74  open_v2() is not
24260 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20 63   one of the.** c
24270 6f 6d 62 69 6e 61 74 69 6f 6e 73 20 73 68 6f 77  ombinations show
24280 6e 20 61 62 6f 76 65 20 6f 70 74 69 6f 6e 61 6c  n above optional
24290 6c 79 20 63 6f 6d 62 69 6e 65 64 20 77 69 74 68  ly combined with
242a0 20 6f 74 68 65 72 0a 2a 2a 20 5b 53 51 4c 49 54   other.** [SQLIT
242b0 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 20  E_OPEN_READONLY 
242c0 7c 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 2a 20  | SQLITE_OPEN_* 
242d0 62 69 74 73 5d 0a 2a 2a 20 74 68 65 6e 20 74 68  bits].** then th
242e0 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e  e behavior is un
242f0 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  defined..**.** ^
24300 49 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f  If the [SQLITE_O
24310 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 20 66 6c 61  PEN_NOMUTEX] fla
24320 67 20 69 73 20 73 65 74 2c 20 74 68 65 6e 20 74  g is set, then t
24330 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
24340 65 63 74 69 6f 6e 0a 2a 2a 20 6f 70 65 6e 73 20  ection.** opens 
24350 69 6e 20 74 68 65 20 6d 75 6c 74 69 2d 74 68 72  in the multi-thr
24360 65 61 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d  ead [threading m
24370 6f 64 65 5d 20 61 73 20 6c 6f 6e 67 20 61 73 20  ode] as long as 
24380 74 68 65 20 73 69 6e 67 6c 65 2d 74 68 72 65 61  the single-threa
24390 64 0a 2a 2a 20 6d 6f 64 65 20 68 61 73 20 6e 6f  d.** mode has no
243a0 74 20 62 65 65 6e 20 73 65 74 20 61 74 20 63 6f  t been set at co
243b0 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 72 20 73 74  mpile-time or st
243c0 61 72 74 2d 74 69 6d 65 2e 20 20 5e 49 66 20 74  art-time.  ^If t
243d0 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50  he.** [SQLITE_OP
243e0 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d 20 66 6c  EN_FULLMUTEX] fl
243f0 61 67 20 69 73 20 73 65 74 20 74 68 65 6e 20 74  ag is set then t
24400 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
24410 65 63 74 69 6f 6e 20 6f 70 65 6e 73 0a 2a 2a 20  ection opens.** 
24420 69 6e 20 74 68 65 20 73 65 72 69 61 6c 69 7a 65  in the serialize
24430 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64  d [threading mod
24440 65 5d 20 75 6e 6c 65 73 73 20 73 69 6e 67 6c 65  e] unless single
24450 2d 74 68 72 65 61 64 20 77 61 73 0a 2a 2a 20 70  -thread was.** p
24460 72 65 76 69 6f 75 73 6c 79 20 73 65 6c 65 63 74  reviously select
24470 65 64 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69  ed at compile-ti
24480 6d 65 20 6f 72 20 73 74 61 72 74 2d 74 69 6d 65  me or start-time
24490 2e 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54  ..** ^The [SQLIT
244a0 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43  E_OPEN_SHAREDCAC
244b0 48 45 5d 20 66 6c 61 67 20 63 61 75 73 65 73 20  HE] flag causes 
244c0 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
244d0 6e 65 63 74 69 6f 6e 20 74 6f 20 62 65 0a 2a 2a  nection to be.**
244e0 20 65 6c 69 67 69 62 6c 65 20 74 6f 20 75 73 65   eligible to use
244f0 20 5b 73 68 61 72 65 64 20 63 61 63 68 65 20 6d   [shared cache m
24500 6f 64 65 5d 2c 20 72 65 67 61 72 64 6c 65 73 73  ode], regardless
24510 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e   of whether or n
24520 6f 74 20 73 68 61 72 65 64 0a 2a 2a 20 63 61 63  ot shared.** cac
24530 68 65 20 69 73 20 65 6e 61 62 6c 65 64 20 75 73  he is enabled us
24540 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65 6e 61  ing [sqlite3_ena
24550 62 6c 65 5f 73 68 61 72 65 64 5f 63 61 63 68 65  ble_shared_cache
24560 28 29 5d 2e 20 20 5e 54 68 65 0a 2a 2a 20 5b 53  ()].  ^The.** [S
24570 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41  QLITE_OPEN_PRIVA
24580 54 45 43 41 43 48 45 5d 20 66 6c 61 67 20 63 61  TECACHE] flag ca
24590 75 73 65 73 20 74 68 65 20 64 61 74 61 62 61 73  uses the databas
245a0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20  e connection to 
245b0 6e 6f 74 0a 2a 2a 20 70 61 72 74 69 63 69 70 61  not.** participa
245c0 74 65 20 69 6e 20 5b 73 68 61 72 65 64 20 63 61  te in [shared ca
245d0 63 68 65 20 6d 6f 64 65 5d 20 65 76 65 6e 20 69  che mode] even i
245e0 66 20 69 74 20 69 73 20 65 6e 61 62 6c 65 64 2e  f it is enabled.
245f0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 72  .**.** ^The four
24600 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
24610 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
24620 29 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66  ) is the name of
24630 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
24640 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20 74 68 61  _vfs] object tha
24650 74 20 64 65 66 69 6e 65 73 20 74 68 65 20 6f 70  t defines the op
24660 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20 69  erating system i
24670 6e 74 65 72 66 61 63 65 20 74 68 61 74 0a 2a 2a  nterface that.**
24680 20 74 68 65 20 6e 65 77 20 64 61 74 61 62 61 73   the new databas
24690 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 68 6f  e connection sho
246a0 75 6c 64 20 75 73 65 2e 20 20 5e 49 66 20 74 68  uld use.  ^If th
246b0 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
246c0 65 72 20 69 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20  er is.** a NULL 
246d0 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 74 68 65  pointer then the
246e0 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65   default [sqlite
246f0 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20 69 73  3_vfs] object is
24700 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66   used..**.** ^If
24710 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73   the filename is
24720 20 22 3a 6d 65 6d 6f 72 79 3a 22 2c 20 74 68 65   ":memory:", the
24730 6e 20 61 20 70 72 69 76 61 74 65 2c 20 74 65 6d  n a private, tem
24740 70 6f 72 61 72 79 20 69 6e 2d 6d 65 6d 6f 72 79  porary in-memory
24750 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 69 73 20   database.** is 
24760 63 72 65 61 74 65 64 20 66 6f 72 20 74 68 65 20  created for the 
24770 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 5e 54 68  connection.  ^Th
24780 69 73 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74  is in-memory dat
24790 61 62 61 73 65 20 77 69 6c 6c 20 76 61 6e 69 73  abase will vanis
247a0 68 20 77 68 65 6e 0a 2a 2a 20 74 68 65 20 64 61  h when.** the da
247b0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
247c0 6e 20 69 73 20 63 6c 6f 73 65 64 2e 20 20 46 75  n is closed.  Fu
247d0 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66  ture versions of
247e0 20 53 51 4c 69 74 65 20 6d 69 67 68 74 0a 2a 2a   SQLite might.**
247f0 20 6d 61 6b 65 20 75 73 65 20 6f 66 20 61 64 64   make use of add
24800 69 74 69 6f 6e 61 6c 20 73 70 65 63 69 61 6c 20  itional special 
24810 66 69 6c 65 6e 61 6d 65 73 20 74 68 61 74 20 62  filenames that b
24820 65 67 69 6e 20 77 69 74 68 20 74 68 65 20 22 3a  egin with the ":
24830 22 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20  " character..** 
24840 49 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65  It is recommende
24850 64 20 74 68 61 74 20 77 68 65 6e 20 61 20 64 61  d that when a da
24860 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20  tabase filename 
24870 61 63 74 75 61 6c 6c 79 20 64 6f 65 73 20 62 65  actually does be
24880 67 69 6e 20 77 69 74 68 0a 2a 2a 20 61 20 22 3a  gin with.** a ":
24890 22 20 63 68 61 72 61 63 74 65 72 20 79 6f 75 20  " character you 
248a0 73 68 6f 75 6c 64 20 70 72 65 66 69 78 20 74 68  should prefix th
248b0 65 20 66 69 6c 65 6e 61 6d 65 20 77 69 74 68 20  e filename with 
248c0 61 20 70 61 74 68 6e 61 6d 65 20 73 75 63 68 20  a pathname such 
248d0 61 73 0a 2a 2a 20 22 2e 2f 22 20 74 6f 20 61 76  as.** "./" to av
248e0 6f 69 64 20 61 6d 62 69 67 75 69 74 79 2e 0a 2a  oid ambiguity..*
248f0 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 6c  *.** ^If the fil
24900 65 6e 61 6d 65 20 69 73 20 61 6e 20 65 6d 70 74  ename is an empt
24910 79 20 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 61  y string, then a
24920 20 70 72 69 76 61 74 65 2c 20 74 65 6d 70 6f 72   private, tempor
24930 61 72 79 0a 2a 2a 20 6f 6e 2d 64 69 73 6b 20 64  ary.** on-disk d
24940 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62 65 20  atabase will be 
24950 63 72 65 61 74 65 64 2e 20 20 5e 54 68 69 73 20  created.  ^This 
24960 70 72 69 76 61 74 65 20 64 61 74 61 62 61 73 65  private database
24970 20 77 69 6c 6c 20 62 65 0a 2a 2a 20 61 75 74 6f   will be.** auto
24980 6d 61 74 69 63 61 6c 6c 79 20 64 65 6c 65 74 65  matically delete
24990 64 20 61 73 20 73 6f 6f 6e 20 61 73 20 74 68 65  d as soon as the
249a0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
249b0 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e 0a  tion is closed..
249c0 2a 2a 0a 2a 2a 20 5b 5b 55 52 49 20 66 69 6c 65  **.** [[URI file
249d0 6e 61 6d 65 73 20 69 6e 20 73 71 6c 69 74 65 33  names in sqlite3
249e0 5f 6f 70 65 6e 28 29 5d 5d 20 3c 68 33 3e 55 52  _open()]] <h3>UR
249f0 49 20 46 69 6c 65 6e 61 6d 65 73 3c 2f 68 33 3e  I Filenames</h3>
24a00 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 5b 55 52 49 20  .**.** ^If [URI 
24a10 66 69 6c 65 6e 61 6d 65 5d 20 69 6e 74 65 72 70  filename] interp
24a20 72 65 74 61 74 69 6f 6e 20 69 73 20 65 6e 61 62  retation is enab
24a30 6c 65 64 2c 20 61 6e 64 20 74 68 65 20 66 69 6c  led, and the fil
24a40 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 0a 2a  ename argument.*
24a50 2a 20 62 65 67 69 6e 73 20 77 69 74 68 20 22 66  * begins with "f
24a60 69 6c 65 3a 22 2c 20 74 68 65 6e 20 74 68 65 20  ile:", then the 
24a70 66 69 6c 65 6e 61 6d 65 20 69 73 20 69 6e 74 65  filename is inte
24a80 72 70 72 65 74 65 64 20 61 73 20 61 20 55 52 49  rpreted as a URI
24a90 2e 20 5e 55 52 49 0a 2a 2a 20 66 69 6c 65 6e 61  . ^URI.** filena
24aa0 6d 65 20 69 6e 74 65 72 70 72 65 74 61 74 69 6f  me interpretatio
24ab0 6e 20 69 73 20 65 6e 61 62 6c 65 64 20 69 66 20  n is enabled if 
24ac0 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  the [SQLITE_OPEN
24ad0 5f 55 52 49 5d 20 66 6c 61 67 20 69 73 0a 2a 2a  _URI] flag is.**
24ae0 20 73 65 74 20 69 6e 20 74 68 65 20 66 6f 75 72   set in the four
24af0 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73  th argument to s
24b00 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
24b10 2c 20 6f 72 20 69 66 20 69 74 20 68 61 73 0a 2a  , or if it has.*
24b20 2a 20 62 65 65 6e 20 65 6e 61 62 6c 65 64 20 67  * been enabled g
24b30 6c 6f 62 61 6c 6c 79 20 75 73 69 6e 67 20 74 68  lobally using th
24b40 65 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  e [SQLITE_CONFIG
24b50 5f 55 52 49 5d 20 6f 70 74 69 6f 6e 20 77 69 74  _URI] option wit
24b60 68 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  h the.** [sqlite
24b70 33 5f 63 6f 6e 66 69 67 28 29 5d 20 6d 65 74 68  3_config()] meth
24b80 6f 64 20 6f 72 20 62 79 20 74 68 65 20 5b 53 51  od or by the [SQ
24b90 4c 49 54 45 5f 55 53 45 5f 55 52 49 5d 20 63 6f  LITE_USE_URI] co
24ba0 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
24bb0 6e 2e 0a 2a 2a 20 41 73 20 6f 66 20 53 51 4c 69  n..** As of SQLi
24bc0 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 37 2e 37  te version 3.7.7
24bd0 2c 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 20 69  , URI filename i
24be0 6e 74 65 72 70 72 65 74 61 74 69 6f 6e 20 69 73  nterpretation is
24bf0 20 74 75 72 6e 65 64 20 6f 66 66 0a 2a 2a 20 62   turned off.** b
24c00 79 20 64 65 66 61 75 6c 74 2c 20 62 75 74 20 66  y default, but f
24c10 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f  uture releases o
24c20 66 20 53 51 4c 69 74 65 20 6d 69 67 68 74 20 65  f SQLite might e
24c30 6e 61 62 6c 65 20 55 52 49 20 66 69 6c 65 6e 61  nable URI filena
24c40 6d 65 0a 2a 2a 20 69 6e 74 65 72 70 72 65 74 61  me.** interpreta
24c50 74 69 6f 6e 20 62 79 20 64 65 66 61 75 6c 74 2e  tion by default.
24c60 20 20 53 65 65 20 22 5b 55 52 49 20 66 69 6c 65    See "[URI file
24c70 6e 61 6d 65 73 5d 22 20 66 6f 72 20 61 64 64 69  names]" for addi
24c80 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d  tional.** inform
24c90 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 55 52 49  ation..**.** URI
24ca0 20 66 69 6c 65 6e 61 6d 65 73 20 61 72 65 20 70   filenames are p
24cb0 61 72 73 65 64 20 61 63 63 6f 72 64 69 6e 67 20  arsed according 
24cc0 74 6f 20 52 46 43 20 33 39 38 36 2e 20 5e 49 66  to RFC 3986. ^If
24cd0 20 74 68 65 20 55 52 49 20 63 6f 6e 74 61 69 6e   the URI contain
24ce0 73 20 61 6e 0a 2a 2a 20 61 75 74 68 6f 72 69 74  s an.** authorit
24cf0 79 2c 20 74 68 65 6e 20 69 74 20 6d 75 73 74 20  y, then it must 
24d00 62 65 20 65 69 74 68 65 72 20 61 6e 20 65 6d 70  be either an emp
24d10 74 79 20 73 74 72 69 6e 67 20 6f 72 20 74 68 65  ty string or the
24d20 20 73 74 72 69 6e 67 20 0a 2a 2a 20 22 6c 6f 63   string .** "loc
24d30 61 6c 68 6f 73 74 22 2e 20 5e 49 66 20 74 68 65  alhost". ^If the
24d40 20 61 75 74 68 6f 72 69 74 79 20 69 73 20 6e 6f   authority is no
24d50 74 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e  t an empty strin
24d60 67 20 6f 72 20 22 6c 6f 63 61 6c 68 6f 73 74 22  g or "localhost"
24d70 2c 20 61 6e 20 0a 2a 2a 20 65 72 72 6f 72 20 69  , an .** error i
24d80 73 20 72 65 74 75 72 6e 65 64 20 74 6f 20 74 68  s returned to th
24d90 65 20 63 61 6c 6c 65 72 2e 20 5e 54 68 65 20 66  e caller. ^The f
24da0 72 61 67 6d 65 6e 74 20 63 6f 6d 70 6f 6e 65 6e  ragment componen
24db0 74 20 6f 66 20 61 20 55 52 49 2c 20 69 66 20 0a  t of a URI, if .
24dc0 2a 2a 20 70 72 65 73 65 6e 74 2c 20 69 73 20 69  ** present, is i
24dd0 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 53  gnored..**.** ^S
24de0 51 4c 69 74 65 20 75 73 65 73 20 74 68 65 20 70  QLite uses the p
24df0 61 74 68 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66  ath component of
24e00 20 74 68 65 20 55 52 49 20 61 73 20 74 68 65 20   the URI as the 
24e10 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 69 73 6b  name of the disk
24e20 20 66 69 6c 65 0a 2a 2a 20 77 68 69 63 68 20 63   file.** which c
24e30 6f 6e 74 61 69 6e 73 20 74 68 65 20 64 61 74 61  ontains the data
24e40 62 61 73 65 2e 20 5e 49 66 20 74 68 65 20 70 61  base. ^If the pa
24e50 74 68 20 62 65 67 69 6e 73 20 77 69 74 68 20 61  th begins with a
24e60 20 27 2f 27 20 63 68 61 72 61 63 74 65 72 2c 20   '/' character, 
24e70 0a 2a 2a 20 74 68 65 6e 20 69 74 20 69 73 20 69  .** then it is i
24e80 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 61 6e  nterpreted as an
24e90 20 61 62 73 6f 6c 75 74 65 20 70 61 74 68 2e 20   absolute path. 
24ea0 5e 49 66 20 74 68 65 20 70 61 74 68 20 64 6f 65  ^If the path doe
24eb0 73 20 6e 6f 74 20 62 65 67 69 6e 20 0a 2a 2a 20  s not begin .** 
24ec0 77 69 74 68 20 61 20 27 2f 27 20 28 6d 65 61 6e  with a '/' (mean
24ed0 69 6e 67 20 74 68 61 74 20 74 68 65 20 61 75 74  ing that the aut
24ee0 68 6f 72 69 74 79 20 73 65 63 74 69 6f 6e 20 69  hority section i
24ef0 73 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 74  s omitted from t
24f00 68 65 20 55 52 49 29 0a 2a 2a 20 74 68 65 6e 20  he URI).** then 
24f10 74 68 65 20 70 61 74 68 20 69 73 20 69 6e 74 65  the path is inte
24f20 72 70 72 65 74 65 64 20 61 73 20 61 20 72 65 6c  rpreted as a rel
24f30 61 74 69 76 65 20 70 61 74 68 2e 20 0a 2a 2a 20  ative path. .** 
24f40 5e 28 4f 6e 20 77 69 6e 64 6f 77 73 2c 20 74 68  ^(On windows, th
24f50 65 20 66 69 72 73 74 20 63 6f 6d 70 6f 6e 65 6e  e first componen
24f60 74 20 6f 66 20 61 6e 20 61 62 73 6f 6c 75 74 65  t of an absolute
24f70 20 70 61 74 68 20 0a 2a 2a 20 69 73 20 61 20 64   path .** is a d
24f80 72 69 76 65 20 73 70 65 63 69 66 69 63 61 74 69  rive specificati
24f90 6f 6e 20 28 65 2e 67 2e 20 22 43 3a 22 29 2e 29  on (e.g. "C:").)
24fa0 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 63 6f 72 65 20 55  ^.**.** [[core U
24fb0 52 49 20 71 75 65 72 79 20 70 61 72 61 6d 65 74  RI query paramet
24fc0 65 72 73 5d 5d 0a 2a 2a 20 54 68 65 20 71 75 65  ers]].** The que
24fd0 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20  ry component of 
24fe0 61 20 55 52 49 20 6d 61 79 20 63 6f 6e 74 61 69  a URI may contai
24ff0 6e 20 70 61 72 61 6d 65 74 65 72 73 20 74 68 61  n parameters tha
25000 74 20 61 72 65 20 69 6e 74 65 72 70 72 65 74 65  t are interprete
25010 64 0a 2a 2a 20 65 69 74 68 65 72 20 62 79 20 53  d.** either by S
25020 51 4c 69 74 65 20 69 74 73 65 6c 66 2c 20 6f 72  QLite itself, or
25030 20 62 79 20 61 20 5b 56 46 53 20 7c 20 63 75 73   by a [VFS | cus
25040 74 6f 6d 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e  tom VFS implemen
25050 74 61 74 69 6f 6e 5d 2e 0a 2a 2a 20 53 51 4c 69  tation]..** SQLi
25060 74 65 20 61 6e 64 20 69 74 73 20 62 75 69 6c 74  te and its built
25070 2d 69 6e 20 5b 56 46 53 65 73 5d 20 69 6e 74 65  -in [VFSes] inte
25080 72 70 72 65 74 20 74 68 65 0a 2a 2a 20 66 6f 6c  rpret the.** fol
25090 6c 6f 77 69 6e 67 20 71 75 65 72 79 20 70 61 72  lowing query par
250a0 61 6d 65 74 65 72 73 3a 0a 2a 2a 0a 2a 2a 20 3c  ameters:.**.** <
250b0 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62  ul>.**   <li> <b
250c0 3e 76 66 73 3c 2f 62 3e 3a 20 5e 54 68 65 20 22  >vfs</b>: ^The "
250d0 76 66 73 22 20 70 61 72 61 6d 65 74 65 72 20 6d  vfs" parameter m
250e0 61 79 20 62 65 20 75 73 65 64 20 74 6f 20 73 70  ay be used to sp
250f0 65 63 69 66 79 20 74 68 65 20 6e 61 6d 65 20 6f  ecify the name o
25100 66 0a 2a 2a 20 20 20 20 20 61 20 56 46 53 20 6f  f.**     a VFS o
25110 62 6a 65 63 74 20 74 68 61 74 20 70 72 6f 76 69  bject that provi
25120 64 65 73 20 74 68 65 20 6f 70 65 72 61 74 69 6e  des the operatin
25130 67 20 73 79 73 74 65 6d 20 69 6e 74 65 72 66 61  g system interfa
25140 63 65 20 74 68 61 74 20 73 68 6f 75 6c 64 0a 2a  ce that should.*
25150 2a 20 20 20 20 20 62 65 20 75 73 65 64 20 74 6f  *     be used to
25160 20 61 63 63 65 73 73 20 74 68 65 20 64 61 74 61   access the data
25170 62 61 73 65 20 66 69 6c 65 20 6f 6e 20 64 69 73  base file on dis
25180 6b 2e 20 5e 49 66 20 74 68 69 73 20 6f 70 74 69  k. ^If this opti
25190 6f 6e 20 69 73 20 73 65 74 20 74 6f 0a 2a 2a 20  on is set to.** 
251a0 20 20 20 20 61 6e 20 65 6d 70 74 79 20 73 74 72      an empty str
251b0 69 6e 67 20 74 68 65 20 64 65 66 61 75 6c 74 20  ing the default 
251c0 56 46 53 20 6f 62 6a 65 63 74 20 69 73 20 75 73  VFS object is us
251d0 65 64 2e 20 5e 53 70 65 63 69 66 79 69 6e 67 20  ed. ^Specifying 
251e0 61 6e 20 75 6e 6b 6e 6f 77 6e 0a 2a 2a 20 20 20  an unknown.**   
251f0 20 20 56 46 53 20 69 73 20 61 6e 20 65 72 72 6f    VFS is an erro
25200 72 2e 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6f  r. ^If sqlite3_o
25210 70 65 6e 5f 76 32 28 29 20 69 73 20 75 73 65 64  pen_v2() is used
25220 20 61 6e 64 20 74 68 65 20 76 66 73 20 6f 70 74   and the vfs opt
25230 69 6f 6e 20 69 73 0a 2a 2a 20 20 20 20 20 70 72  ion is.**     pr
25240 65 73 65 6e 74 2c 20 74 68 65 6e 20 74 68 65 20  esent, then the 
25250 56 46 53 20 73 70 65 63 69 66 69 65 64 20 62 79  VFS specified by
25260 20 74 68 65 20 6f 70 74 69 6f 6e 20 74 61 6b 65   the option take
25270 73 20 70 72 65 63 65 64 65 6e 63 65 20 6f 76 65  s precedence ove
25280 72 0a 2a 2a 20 20 20 20 20 74 68 65 20 76 61 6c  r.**     the val
25290 75 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65  ue passed as the
252a0 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
252b0 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65  r to sqlite3_ope
252c0 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 20 20  n_v2()..**.**   
252d0 3c 6c 69 3e 20 3c 62 3e 6d 6f 64 65 3c 2f 62 3e  <li> <b>mode</b>
252e0 3a 20 5e 28 54 68 65 20 6d 6f 64 65 20 70 61 72  : ^(The mode par
252f0 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20 73 65  ameter may be se
25300 74 20 74 6f 20 65 69 74 68 65 72 20 22 72 6f 22  t to either "ro"
25310 2c 20 22 72 77 22 2c 0a 2a 2a 20 20 20 20 20 22  , "rw",.**     "
25320 72 77 63 22 2c 20 6f 72 20 22 6d 65 6d 6f 72 79  rwc", or "memory
25330 22 2e 20 41 74 74 65 6d 70 74 69 6e 67 20 74 6f  ". Attempting to
25340 20 73 65 74 20 69 74 20 74 6f 20 61 6e 79 20 6f   set it to any o
25350 74 68 65 72 20 76 61 6c 75 65 20 69 73 0a 2a 2a  ther value is.**
25360 20 20 20 20 20 61 6e 20 65 72 72 6f 72 29 5e 2e       an error)^.
25370 20 0a 2a 2a 20 20 20 20 20 5e 49 66 20 22 72 6f   .**     ^If "ro
25380 22 20 69 73 20 73 70 65 63 69 66 69 65 64 2c 20  " is specified, 
25390 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73  then the databas
253a0 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20  e is opened for 
253b0 72 65 61 64 2d 6f 6e 6c 79 20 0a 2a 2a 20 20 20  read-only .**   
253c0 20 20 61 63 63 65 73 73 2c 20 6a 75 73 74 20 61    access, just a
253d0 73 20 69 66 20 74 68 65 20 5b 53 51 4c 49 54 45  s if the [SQLITE
253e0 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 20  _OPEN_READONLY] 
253f0 66 6c 61 67 20 68 61 64 20 62 65 65 6e 20 73 65  flag had been se
25400 74 20 69 6e 20 74 68 65 20 0a 2a 2a 20 20 20 20  t in the .**    
25410 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20   third argument 
25420 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  to sqlite3_open_
25430 76 32 28 29 2e 20 5e 49 66 20 74 68 65 20 6d 6f  v2(). ^If the mo
25440 64 65 20 6f 70 74 69 6f 6e 20 69 73 20 73 65 74  de option is set
25450 20 74 6f 20 0a 2a 2a 20 20 20 20 20 22 72 77 22   to .**     "rw"
25460 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62  , then the datab
25470 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f  ase is opened fo
25480 72 20 72 65 61 64 2d 77 72 69 74 65 20 28 62 75  r read-write (bu
25490 74 20 6e 6f 74 20 63 72 65 61 74 65 29 20 0a 2a  t not create) .*
254a0 2a 20 20 20 20 20 61 63 63 65 73 73 2c 20 61 73  *     access, as
254b0 20 69 66 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f   if SQLITE_OPEN_
254c0 52 45 41 44 57 52 49 54 45 20 28 62 75 74 20 6e  READWRITE (but n
254d0 6f 74 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43  ot SQLITE_OPEN_C
254e0 52 45 41 54 45 29 20 68 61 64 20 0a 2a 2a 20 20  REATE) had .**  
254f0 20 20 20 62 65 65 6e 20 73 65 74 2e 20 5e 56 61     been set. ^Va
25500 6c 75 65 20 22 72 77 63 22 20 69 73 20 65 71 75  lue "rwc" is equ
25510 69 76 61 6c 65 6e 74 20 74 6f 20 73 65 74 74 69  ivalent to setti
25520 6e 67 20 62 6f 74 68 20 0a 2a 2a 20 20 20 20 20  ng both .**     
25530 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44  SQLITE_OPEN_READ
25540 57 52 49 54 45 20 61 6e 64 20 53 51 4c 49 54 45  WRITE and SQLITE
25550 5f 4f 50 45 4e 5f 43 52 45 41 54 45 2e 20 20 5e  _OPEN_CREATE.  ^
25560 49 66 20 74 68 65 20 6d 6f 64 65 20 6f 70 74 69  If the mode opti
25570 6f 6e 20 69 73 0a 2a 2a 20 20 20 20 20 73 65 74  on is.**     set
25580 20 74 6f 20 22 6d 65 6d 6f 72 79 22 20 74 68 65   to "memory" the
25590 6e 20 61 20 70 75 72 65 20 5b 69 6e 2d 6d 65 6d  n a pure [in-mem
255a0 6f 72 79 20 64 61 74 61 62 61 73 65 5d 20 74 68  ory database] th
255b0 61 74 20 6e 65 76 65 72 20 72 65 61 64 73 0a 2a  at never reads.*
255c0 2a 20 20 20 20 20 6f 72 20 77 72 69 74 65 73 20  *     or writes 
255d0 66 72 6f 6d 20 64 69 73 6b 20 69 73 20 75 73 65  from disk is use
255e0 64 2e 20 5e 49 74 20 69 73 20 61 6e 20 65 72 72  d. ^It is an err
255f0 6f 72 20 74 6f 20 73 70 65 63 69 66 79 20 61 20  or to specify a 
25600 76 61 6c 75 65 20 66 6f 72 0a 2a 2a 20 20 20 20  value for.**    
25610 20 74 68 65 20 6d 6f 64 65 20 70 61 72 61 6d 65   the mode parame
25620 74 65 72 20 74 68 61 74 20 69 73 20 6c 65 73 73  ter that is less
25630 20 72 65 73 74 72 69 63 74 69 76 65 20 74 68 61   restrictive tha
25640 6e 20 74 68 61 74 20 73 70 65 63 69 66 69 65 64  n that specified
25650 20 62 79 0a 2a 2a 20 20 20 20 20 74 68 65 20 66   by.**     the f
25660 6c 61 67 73 20 70 61 73 73 65 64 20 69 6e 20 74  lags passed in t
25670 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  he third paramet
25680 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70  er to sqlite3_op
25690 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 20  en_v2()..**.**  
256a0 20 3c 6c 69 3e 20 3c 62 3e 63 61 63 68 65 3c 2f   <li> <b>cache</
256b0 62 3e 3a 20 5e 54 68 65 20 63 61 63 68 65 20 70  b>: ^The cache p
256c0 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20  arameter may be 
256d0 73 65 74 20 74 6f 20 65 69 74 68 65 72 20 22 73  set to either "s
256e0 68 61 72 65 64 22 20 6f 72 0a 2a 2a 20 20 20 20  hared" or.**    
256f0 20 22 70 72 69 76 61 74 65 22 2e 20 5e 53 65 74   "private". ^Set
25700 74 69 6e 67 20 69 74 20 74 6f 20 22 73 68 61 72  ting it to "shar
25710 65 64 22 20 69 73 20 65 71 75 69 76 61 6c 65 6e  ed" is equivalen
25720 74 20 74 6f 20 73 65 74 74 69 6e 67 20 74 68 65  t to setting the
25730 0a 2a 2a 20 20 20 20 20 53 51 4c 49 54 45 5f 4f  .**     SQLITE_O
25740 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45 20  PEN_SHAREDCACHE 
25750 62 69 74 20 69 6e 20 74 68 65 20 66 6c 61 67 73  bit in the flags
25760 20 61 72 67 75 6d 65 6e 74 20 70 61 73 73 65 64   argument passed
25770 20 74 6f 0a 2a 2a 20 20 20 20 20 73 71 6c 69 74   to.**     sqlit
25780 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 5e 53  e3_open_v2(). ^S
25790 65 74 74 69 6e 67 20 74 68 65 20 63 61 63 68 65  etting the cache
257a0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 22 70   parameter to "p
257b0 72 69 76 61 74 65 22 20 69 73 20 0a 2a 2a 20 20  rivate" is .**  
257c0 20 20 20 65 71 75 69 76 61 6c 65 6e 74 20 74 6f     equivalent to
257d0 20 73 65 74 74 69 6e 67 20 74 68 65 20 53 51 4c   setting the SQL
257e0 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45  ITE_OPEN_PRIVATE
257f0 43 41 43 48 45 20 62 69 74 2e 0a 2a 2a 20 20 20  CACHE bit..**   
25800 20 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6f 70    ^If sqlite3_op
25810 65 6e 5f 76 32 28 29 20 69 73 20 75 73 65 64 20  en_v2() is used 
25820 61 6e 64 20 74 68 65 20 22 63 61 63 68 65 22 20  and the "cache" 
25830 70 61 72 61 6d 65 74 65 72 20 69 73 20 70 72 65  parameter is pre
25840 73 65 6e 74 20 69 6e 0a 2a 2a 20 20 20 20 20 61  sent in.**     a
25850 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 2c 20 69   URI filename, i
25860 74 73 20 76 61 6c 75 65 20 6f 76 65 72 72 69 64  ts value overrid
25870 65 73 20 61 6e 79 20 62 65 68 61 76 69 6f 72 20  es any behavior 
25880 72 65 71 75 65 73 74 65 64 20 62 79 20 73 65 74  requested by set
25890 74 69 6e 67 0a 2a 2a 20 20 20 20 20 53 51 4c 49  ting.**     SQLI
258a0 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43  TE_OPEN_PRIVATEC
258b0 41 43 48 45 20 6f 72 20 53 51 4c 49 54 45 5f 4f  ACHE or SQLITE_O
258c0 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45 20  PEN_SHAREDCACHE 
258d0 66 6c 61 67 2e 0a 2a 2a 0a 2a 2a 20 20 3c 6c 69  flag..**.**  <li
258e0 3e 20 3c 62 3e 70 73 6f 77 3c 2f 62 3e 3a 20 5e  > <b>psow</b>: ^
258f0 54 68 65 20 70 73 6f 77 20 70 61 72 61 6d 65 74  The psow paramet
25900 65 72 20 69 6e 64 69 63 61 74 65 73 20 77 68 65  er indicates whe
25910 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 0a  ther or not the.
25920 2a 2a 20 20 20 20 20 5b 70 6f 77 65 72 73 61 66  **     [powersaf
25930 65 20 6f 76 65 72 77 72 69 74 65 5d 20 70 72 6f  e overwrite] pro
25940 70 65 72 74 79 20 64 6f 65 73 20 6f 72 20 64 6f  perty does or do
25950 65 73 20 6e 6f 74 20 61 70 70 6c 79 20 74 6f 20  es not apply to 
25960 74 68 65 0a 2a 2a 20 20 20 20 20 73 74 6f 72 61  the.**     stora
25970 67 65 20 6d 65 64 69 61 20 6f 6e 20 77 68 69 63  ge media on whic
25980 68 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  h the database f
25990 69 6c 65 20 72 65 73 69 64 65 73 2e 0a 2a 2a 0a  ile resides..**.
259a0 2a 2a 20 20 3c 6c 69 3e 20 3c 62 3e 6e 6f 6c 6f  **  <li> <b>nolo
259b0 63 6b 3c 2f 62 3e 3a 20 5e 54 68 65 20 6e 6f 6c  ck</b>: ^The nol
259c0 6f 63 6b 20 70 61 72 61 6d 65 74 65 72 20 69 73  ock parameter is
259d0 20 61 20 62 6f 6f 6c 65 61 6e 20 71 75 65 72 79   a boolean query
259e0 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 20 20   parameter.**   
259f0 20 20 77 68 69 63 68 20 69 66 20 73 65 74 20 64    which if set d
25a00 69 73 61 62 6c 65 73 20 66 69 6c 65 20 6c 6f 63  isables file loc
25a10 6b 69 6e 67 20 69 6e 20 72 6f 6c 6c 62 61 63 6b  king in rollback
25a20 20 6a 6f 75 72 6e 61 6c 20 6d 6f 64 65 73 2e 20   journal modes. 
25a30 20 54 68 69 73 0a 2a 2a 20 20 20 20 20 69 73 20   This.**     is 
25a40 75 73 65 66 75 6c 20 66 6f 72 20 61 63 63 65 73  useful for acces
25a50 73 69 6e 67 20 61 20 64 61 74 61 62 61 73 65 20  sing a database 
25a60 6f 6e 20 61 20 66 69 6c 65 73 79 73 74 65 6d 20  on a filesystem 
25a70 74 68 61 74 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a  that does not.**
25a80 20 20 20 20 20 73 75 70 70 6f 72 74 20 6c 6f 63       support loc
25a90 6b 69 6e 67 2e 20 20 43 61 75 74 69 6f 6e 3a 20  king.  Caution: 
25aa0 20 44 61 74 61 62 61 73 65 20 63 6f 72 72 75 70   Database corrup
25ab0 74 69 6f 6e 20 6d 69 67 68 74 20 72 65 73 75 6c  tion might resul
25ac0 74 20 69 66 20 74 77 6f 0a 2a 2a 20 20 20 20 20  t if two.**     
25ad0 6f 72 20 6d 6f 72 65 20 70 72 6f 63 65 73 73 65  or more processe
25ae0 73 20 77 72 69 74 65 20 74 6f 20 74 68 65 20 73  s write to the s
25af0 61 6d 65 20 64 61 74 61 62 61 73 65 20 61 6e 64  ame database and
25b00 20 61 6e 79 20 6f 6e 65 20 6f 66 20 74 68 6f 73   any one of thos
25b10 65 0a 2a 2a 20 20 20 20 20 70 72 6f 63 65 73 73  e.**     process
25b20 65 73 20 75 73 65 73 20 6e 6f 6c 6f 63 6b 3d 31  es uses nolock=1
25b30 2e 0a 2a 2a 0a 2a 2a 20 20 3c 6c 69 3e 20 3c 62  ..**.**  <li> <b
25b40 3e 69 6d 6d 75 74 61 62 6c 65 3c 2f 62 3e 3a 20  >immutable</b>: 
25b50 5e 54 68 65 20 69 6d 6d 75 74 61 62 6c 65 20 70  ^The immutable p
25b60 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 62 6f  arameter is a bo
25b70 6f 6c 65 61 6e 20 71 75 65 72 79 0a 2a 2a 20 20  olean query.**  
25b80 20 20 20 70 61 72 61 6d 65 74 65 72 20 74 68 61     parameter tha
25b90 74 20 69 6e 64 69 63 61 74 65 73 20 74 68 61 74  t indicates that
25ba0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
25bb0 6c 65 20 69 73 20 73 74 6f 72 65 64 20 6f 6e 0a  le is stored on.
25bc0 2a 2a 20 20 20 20 20 72 65 61 64 2d 6f 6e 6c 79  **     read-only
25bd0 20 6d 65 64 69 61 2e 20 20 5e 57 68 65 6e 20 69   media.  ^When i
25be0 6d 6d 75 74 61 62 6c 65 20 69 73 20 73 65 74 2c  mmutable is set,
25bf0 20 53 51 4c 69 74 65 20 61 73 73 75 6d 65 73 20   SQLite assumes 
25c00 74 68 61 74 20 74 68 65 0a 2a 2a 20 20 20 20 20  that the.**     
25c10 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 63 61  database file ca
25c20 6e 6e 6f 74 20 62 65 20 63 68 61 6e 67 65 64 2c  nnot be changed,
25c30 20 65 76 65 6e 20 62 79 20 61 20 70 72 6f 63 65   even by a proce
25c40 73 73 20 77 69 74 68 20 68 69 67 68 65 72 0a 2a  ss with higher.*
25c50 2a 20 20 20 20 20 70 72 69 76 69 6c 65 67 65 2c  *     privilege,
25c60 20 61 6e 64 20 73 6f 20 74 68 65 20 64 61 74 61   and so the data
25c70 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 72  base is opened r
25c80 65 61 64 2d 6f 6e 6c 79 20 61 6e 64 20 61 6c 6c  ead-only and all
25c90 20 6c 6f 63 6b 69 6e 67 0a 2a 2a 20 20 20 20 20   locking.**     
25ca0 61 6e 64 20 63 68 61 6e 67 65 20 64 65 74 65 63  and change detec
25cb0 74 69 6f 6e 20 69 73 20 64 69 73 61 62 6c 65 64  tion is disabled
25cc0 2e 20 20 43 61 75 74 69 6f 6e 3a 20 53 65 74 74  .  Caution: Sett
25cd0 69 6e 67 20 74 68 65 20 69 6d 6d 75 74 61 62 6c  ing the immutabl
25ce0 65 0a 2a 2a 20 20 20 20 20 70 72 6f 70 65 72 74  e.**     propert
25cf0 79 20 6f 6e 20 61 20 64 61 74 61 62 61 73 65 20  y on a database 
25d00 66 69 6c 65 20 74 68 61 74 20 64 6f 65 73 20 69  file that does i
25d10 6e 20 66 61 63 74 20 63 68 61 6e 67 65 20 63 61  n fact change ca
25d20 6e 20 72 65 73 75 6c 74 0a 2a 2a 20 20 20 20 20  n result.**     
25d30 69 6e 20 69 6e 63 6f 72 72 65 63 74 20 71 75 65  in incorrect que
25d40 72 79 20 72 65 73 75 6c 74 73 20 61 6e 64 2f 6f  ry results and/o
25d50 72 20 5b 53 51 4c 49 54 45 5f 43 4f 52 52 55 50  r [SQLITE_CORRUP
25d60 54 5d 20 65 72 72 6f 72 73 2e 0a 2a 2a 20 20 20  T] errors..**   
25d70 20 20 53 65 65 20 61 6c 73 6f 3a 20 5b 53 51 4c    See also: [SQL
25d80 49 54 45 5f 49 4f 43 41 50 5f 49 4d 4d 55 54 41  ITE_IOCAP_IMMUTA
25d90 42 4c 45 5d 2e 0a 2a 2a 20 20 20 20 20 20 20 0a  BLE]..**       .
25da0 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e  ** </ul>.**.** ^
25db0 53 70 65 63 69 66 79 69 6e 67 20 61 6e 20 75 6e  Specifying an un
25dc0 6b 6e 6f 77 6e 20 70 61 72 61 6d 65 74 65 72 20  known parameter 
25dd0 69 6e 20 74 68 65 20 71 75 65 72 79 20 63 6f 6d  in the query com
25de0 70 6f 6e 65 6e 74 20 6f 66 20 61 20 55 52 49 20  ponent of a URI 
25df0 69 73 20 6e 6f 74 20 61 6e 0a 2a 2a 20 65 72 72  is not an.** err
25e00 6f 72 2e 20 20 46 75 74 75 72 65 20 76 65 72 73  or.  Future vers
25e10 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d  ions of SQLite m
25e20 69 67 68 74 20 75 6e 64 65 72 73 74 61 6e 64 20  ight understand 
25e30 61 64 64 69 74 69 6f 6e 61 6c 20 71 75 65 72 79  additional query
25e40 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 2e 20  .** parameters. 
25e50 20 53 65 65 20 22 5b 71 75 65 72 79 20 70 61 72   See "[query par
25e60 61 6d 65 74 65 72 73 20 77 69 74 68 20 73 70 65  ameters with spe
25e70 63 69 61 6c 20 6d 65 61 6e 69 6e 67 20 74 6f 20  cial meaning to 
25e80 53 51 4c 69 74 65 5d 22 20 66 6f 72 0a 2a 2a 20  SQLite]" for.** 
25e90 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72  additional infor
25ea0 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5b 5b  mation..**.** [[
25eb0 55 52 49 20 66 69 6c 65 6e 61 6d 65 20 65 78 61  URI filename exa
25ec0 6d 70 6c 65 73 5d 5d 20 3c 68 33 3e 55 52 49 20  mples]] <h3>URI 
25ed0 66 69 6c 65 6e 61 6d 65 20 65 78 61 6d 70 6c 65  filename example
25ee0 73 3c 2f 68 33 3e 0a 2a 2a 0a 2a 2a 20 3c 74 61  s</h3>.**.** <ta
25ef0 62 6c 65 20 62 6f 72 64 65 72 3d 22 31 22 20 61  ble border="1" a
25f00 6c 69 67 6e 3d 63 65 6e 74 65 72 20 63 65 6c 6c  lign=center cell
25f10 70 61 64 64 69 6e 67 3d 35 3e 0a 2a 2a 20 3c 74  padding=5>.** <t
25f20 72 3e 3c 74 68 3e 20 55 52 49 20 66 69 6c 65 6e  r><th> URI filen
25f30 61 6d 65 73 20 3c 74 68 3e 20 52 65 73 75 6c 74  ames <th> Result
25f40 73 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69  s.** <tr><td> fi
25f50 6c 65 3a 64 61 74 61 2e 64 62 20 3c 74 64 3e 20  le:data.db <td> 
25f60 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4f 70 65  .**          Ope
25f70 6e 20 74 68 65 20 66 69 6c 65 20 22 64 61 74 61  n the file "data
25f80 2e 64 62 22 20 69 6e 20 74 68 65 20 63 75 72 72  .db" in the curr
25f90 65 6e 74 20 64 69 72 65 63 74 6f 72 79 2e 0a 2a  ent directory..*
25fa0 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a  * <tr><td> file:
25fb0 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e  /home/fred/data.
25fc0 64 62 3c 62 72 3e 0a 2a 2a 20 20 20 20 20 20 20  db<br>.**       
25fd0 20 20 20 66 69 6c 65 3a 2f 2f 2f 68 6f 6d 65 2f     file:///home/
25fe0 66 72 65 64 2f 64 61 74 61 2e 64 62 20 3c 62 72  fred/data.db <br
25ff0 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66  > .**          f
26000 69 6c 65 3a 2f 2f 6c 6f 63 61 6c 68 6f 73 74 2f  ile://localhost/
26010 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64  home/fred/data.d
26020 62 20 3c 62 72 3e 20 3c 74 64 3e 20 0a 2a 2a 20  b <br> <td> .** 
26030 20 20 20 20 20 20 20 20 20 4f 70 65 6e 20 74 68           Open th
26040 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
26050 22 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61  "/home/fred/data
26060 2e 64 62 22 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64  .db"..** <tr><td
26070 3e 20 66 69 6c 65 3a 2f 2f 64 61 72 6b 73 74 61  > file://darksta
26080 72 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61  r/home/fred/data
26090 2e 64 62 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20  .db <td> .**    
260a0 20 20 20 20 20 20 41 6e 20 65 72 72 6f 72 2e 20        An error. 
260b0 22 64 61 72 6b 73 74 61 72 22 20 69 73 20 6e 6f  "darkstar" is no
260c0 74 20 61 20 72 65 63 6f 67 6e 69 7a 65 64 20 61  t a recognized a
260d0 75 74 68 6f 72 69 74 79 2e 0a 2a 2a 20 3c 74 72  uthority..** <tr
260e0 3e 3c 74 64 20 73 74 79 6c 65 3d 22 77 68 69 74  ><td style="whit
260f0 65 2d 73 70 61 63 65 3a 6e 6f 77 72 61 70 22 3e  e-space:nowrap">
26100 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 69   .**          fi
26110 6c 65 3a 2f 2f 2f 43 3a 2f 44 6f 63 75 6d 65 6e  le:///C:/Documen
26120 74 73 25 32 30 61 6e 64 25 32 30 53 65 74 74 69  ts%20and%20Setti
26130 6e 67 73 2f 66 72 65 64 2f 44 65 73 6b 74 6f 70  ngs/fred/Desktop
26140 2f 64 61 74 61 2e 64 62 0a 2a 2a 20 20 20 20 20  /data.db.**     
26150 3c 74 64 3e 20 57 69 6e 64 6f 77 73 20 6f 6e 6c  <td> Windows onl
26160 79 3a 20 4f 70 65 6e 20 74 68 65 20 66 69 6c 65  y: Open the file
26170 20 22 64 61 74 61 2e 64 62 22 20 6f 6e 20 66 72   "data.db" on fr
26180 65 64 27 73 20 64 65 73 6b 74 6f 70 20 6f 6e 20  ed's desktop on 
26190 64 72 69 76 65 0a 2a 2a 20 20 20 20 20 20 20 20  drive.**        
261a0 20 20 43 3a 2e 20 4e 6f 74 65 20 74 68 61 74 20    C:. Note that 
261b0 74 68 65 20 25 32 30 20 65 73 63 61 70 69 6e 67  the %20 escaping
261c0 20 69 6e 20 74 68 69 73 20 65 78 61 6d 70 6c 65   in this example
261d0 20 69 73 20 6e 6f 74 20 73 74 72 69 63 74 6c 79   is not strictly
261e0 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 65   .**          ne
261f0 63 65 73 73 61 72 79 20 2d 20 73 70 61 63 65 20  cessary - space 
26200 63 68 61 72 61 63 74 65 72 73 20 63 61 6e 20 62  characters can b
26210 65 20 75 73 65 64 20 6c 69 74 65 72 61 6c 6c 79  e used literally
26220 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 20  .**          in 
26230 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 2e 0a 2a  URI filenames..*
26240 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a  * <tr><td> file:
26250 64 61 74 61 2e 64 62 3f 6d 6f 64 65 3d 72 6f 26  data.db?mode=ro&
26260 63 61 63 68 65 3d 70 72 69 76 61 74 65 20 3c 74  cache=private <t
26270 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  d> .**          
26280 4f 70 65 6e 20 66 69 6c 65 20 22 64 61 74 61 2e  Open file "data.
26290 64 62 22 20 69 6e 20 74 68 65 20 63 75 72 72 65  db" in the curre
262a0 6e 74 20 64 69 72 65 63 74 6f 72 79 20 66 6f 72  nt directory for
262b0 20 72 65 61 64 2d 6f 6e 6c 79 20 61 63 63 65 73   read-only acces
262c0 73 2e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 52  s..**          R
262d0 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65  egardless of whe
262e0 74 68 65 72 20 6f 72 20 6e 6f 74 20 73 68 61 72  ther or not shar
262f0 65 64 2d 63 61 63 68 65 20 6d 6f 64 65 20 69 73  ed-cache mode is
26300 20 65 6e 61 62 6c 65 64 20 62 79 0a 2a 2a 20 20   enabled by.**  
26310 20 20 20 20 20 20 20 20 64 65 66 61 75 6c 74 2c          default,
26320 20 75 73 65 20 61 20 70 72 69 76 61 74 65 20 63   use a private c
26330 61 63 68 65 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64  ache..** <tr><td
26340 3e 20 66 69 6c 65 3a 2f 68 6f 6d 65 2f 66 72 65  > file:/home/fre
26350 64 2f 64 61 74 61 2e 64 62 3f 76 66 73 3d 75 6e  d/data.db?vfs=un
26360 69 78 2d 64 6f 74 66 69 6c 65 20 3c 74 64 3e 0a  ix-dotfile <td>.
26370 2a 2a 20 20 20 20 20 20 20 20 20 20 4f 70 65 6e  **          Open
26380 20 66 69 6c 65 20 22 2f 68 6f 6d 65 2f 66 72 65   file "/home/fre
26390 64 2f 64 61 74 61 2e 64 62 22 2e 20 55 73 65 20  d/data.db". Use 
263a0 74 68 65 20 73 70 65 63 69 61 6c 20 56 46 53 20  the special VFS 
263b0 22 75 6e 69 78 2d 64 6f 74 66 69 6c 65 22 0a 2a  "unix-dotfile".*
263c0 2a 20 20 20 20 20 20 20 20 20 20 74 68 61 74 20  *          that 
263d0 75 73 65 73 20 64 6f 74 2d 66 69 6c 65 73 20 69  uses dot-files i
263e0 6e 20 70 6c 61 63 65 20 6f 66 20 70 6f 73 69 78  n place of posix
263f0 20 61 64 76 69 73 6f 72 79 20 6c 6f 63 6b 69 6e   advisory lockin
26400 67 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66  g..** <tr><td> f
26410 69 6c 65 3a 64 61 74 61 2e 64 62 3f 6d 6f 64 65  ile:data.db?mode
26420 3d 72 65 61 64 6f 6e 6c 79 20 3c 74 64 3e 20 0a  =readonly <td> .
26430 2a 2a 20 20 20 20 20 20 20 20 20 20 41 6e 20 65  **          An e
26440 72 72 6f 72 2e 20 22 72 65 61 64 6f 6e 6c 79 22  rror. "readonly"
26450 20 69 73 20 6e 6f 74 20 61 20 76 61 6c 69 64 20   is not a valid 
26460 6f 70 74 69 6f 6e 20 66 6f 72 20 74 68 65 20 22  option for the "
26470 6d 6f 64 65 22 20 70 61 72 61 6d 65 74 65 72 2e  mode" parameter.
26480 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 0a  .** </table>.**.
26490 2a 2a 20 5e 55 52 49 20 68 65 78 61 64 65 63 69  ** ^URI hexadeci
264a0 6d 61 6c 20 65 73 63 61 70 65 20 73 65 71 75 65  mal escape seque
264b0 6e 63 65 73 20 28 25 48 48 29 20 61 72 65 20 73  nces (%HH) are s
264c0 75 70 70 6f 72 74 65 64 20 77 69 74 68 69 6e 20  upported within 
264d0 74 68 65 20 70 61 74 68 20 61 6e 64 0a 2a 2a 20  the path and.** 
264e0 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 73  query components
264f0 20 6f 66 20 61 20 55 52 49 2e 20 41 20 68 65 78   of a URI. A hex
26500 61 64 65 63 69 6d 61 6c 20 65 73 63 61 70 65 20  adecimal escape 
26510 73 65 71 75 65 6e 63 65 20 63 6f 6e 73 69 73 74  sequence consist
26520 73 20 6f 66 20 61 0a 2a 2a 20 70 65 72 63 65 6e  s of a.** percen
26530 74 20 73 69 67 6e 20 2d 20 22 25 22 20 2d 20 66  t sign - "%" - f
26540 6f 6c 6c 6f 77 65 64 20 62 79 20 65 78 61 63 74  ollowed by exact
26550 6c 79 20 74 77 6f 20 68 65 78 61 64 65 63 69 6d  ly two hexadecim
26560 61 6c 20 64 69 67 69 74 73 20 0a 2a 2a 20 73 70  al digits .** sp
26570 65 63 69 66 79 69 6e 67 20 61 6e 20 6f 63 74 65  ecifying an octe
26580 74 20 76 61 6c 75 65 2e 20 5e 42 65 66 6f 72 65  t value. ^Before
26590 20 74 68 65 20 70 61 74 68 20 6f 72 20 71 75 65   the path or que
265a0 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 73 20 6f 66  ry components of
265b0 20 61 0a 2a 2a 20 55 52 49 20 66 69 6c 65 6e 61   a.** URI filena
265c0 6d 65 20 61 72 65 20 69 6e 74 65 72 70 72 65 74  me are interpret
265d0 65 64 2c 20 74 68 65 79 20 61 72 65 20 65 6e 63  ed, they are enc
265e0 6f 64 65 64 20 75 73 69 6e 67 20 55 54 46 2d 38  oded using UTF-8
265f0 20 61 6e 64 20 61 6c 6c 20 0a 2a 2a 20 68 65 78   and all .** hex
26600 61 64 65 63 69 6d 61 6c 20 65 73 63 61 70 65 20  adecimal escape 
26610 73 65 71 75 65 6e 63 65 73 20 72 65 70 6c 61 63  sequences replac
26620 65 64 20 62 79 20 61 20 73 69 6e 67 6c 65 20 62  ed by a single b
26630 79 74 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74  yte containing t
26640 68 65 0a 2a 2a 20 63 6f 72 72 65 73 70 6f 6e 64  he.** correspond
26650 69 6e 67 20 6f 63 74 65 74 2e 20 49 66 20 74 68  ing octet. If th
26660 69 73 20 70 72 6f 63 65 73 73 20 67 65 6e 65 72  is process gener
26670 61 74 65 73 20 61 6e 20 69 6e 76 61 6c 69 64 20  ates an invalid 
26680 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 2c 0a  UTF-8 encoding,.
26690 2a 2a 20 74 68 65 20 72 65 73 75 6c 74 73 20 61  ** the results a
266a0 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  re undefined..**
266b0 0a 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74 6f 20 57  .** <b>Note to W
266c0 69 6e 64 6f 77 73 20 75 73 65 72 73 3a 3c 2f 62  indows users:</b
266d0 3e 20 20 54 68 65 20 65 6e 63 6f 64 69 6e 67 20  >  The encoding 
266e0 75 73 65 64 20 66 6f 72 20 74 68 65 20 66 69 6c  used for the fil
266f0 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 0a 2a  ename argument.*
26700 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 70 65  * of sqlite3_ope
26710 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  n() and sqlite3_
26720 6f 70 65 6e 5f 76 32 28 29 20 6d 75 73 74 20 62  open_v2() must b
26730 65 20 55 54 46 2d 38 2c 20 6e 6f 74 20 77 68 61  e UTF-8, not wha
26740 74 65 76 65 72 0a 2a 2a 20 63 6f 64 65 70 61 67  tever.** codepag
26750 65 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20 64  e is currently d
26760 65 66 69 6e 65 64 2e 20 20 46 69 6c 65 6e 61 6d  efined.  Filenam
26770 65 73 20 63 6f 6e 74 61 69 6e 69 6e 67 20 69 6e  es containing in
26780 74 65 72 6e 61 74 69 6f 6e 61 6c 0a 2a 2a 20 63  ternational.** c
26790 68 61 72 61 63 74 65 72 73 20 6d 75 73 74 20 62  haracters must b
267a0 65 20 63 6f 6e 76 65 72 74 65 64 20 74 6f 20 55  e converted to U
267b0 54 46 2d 38 20 70 72 69 6f 72 20 74 6f 20 70 61  TF-8 prior to pa
267c0 73 73 69 6e 67 20 74 68 65 6d 20 69 6e 74 6f 0a  ssing them into.
267d0 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  ** sqlite3_open(
267e0 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65  ) or sqlite3_ope
267f0 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 3c 62  n_v2()..**.** <b
26800 3e 4e 6f 74 65 20 74 6f 20 57 69 6e 64 6f 77 73  >Note to Windows
26810 20 52 75 6e 74 69 6d 65 20 75 73 65 72 73 3a 3c   Runtime users:<
26820 2f 62 3e 20 20 54 68 65 20 74 65 6d 70 6f 72 61  /b>  The tempora
26830 72 79 20 64 69 72 65 63 74 6f 72 79 20 6d 75 73  ry directory mus
26840 74 20 62 65 20 73 65 74 0a 2a 2a 20 70 72 69 6f  t be set.** prio
26850 72 20 74 6f 20 63 61 6c 6c 69 6e 67 20 73 71 6c  r to calling sql
26860 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73  ite3_open() or s
26870 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
26880 2e 20 20 4f 74 68 65 72 77 69 73 65 2c 20 76 61  .  Otherwise, va
26890 72 69 6f 75 73 0a 2a 2a 20 66 65 61 74 75 72 65  rious.** feature
268a0 73 20 74 68 61 74 20 72 65 71 75 69 72 65 20 74  s that require t
268b0 68 65 20 75 73 65 20 6f 66 20 74 65 6d 70 6f 72  he use of tempor
268c0 61 72 79 20 66 69 6c 65 73 20 6d 61 79 20 66 61  ary files may fa
268d0 69 6c 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  il..**.** See al
268e0 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 74 65 6d  so: [sqlite3_tem
268f0 70 5f 64 69 72 65 63 74 6f 72 79 5d 0a 2a 2f 0a  p_directory].*/.
26900 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  int sqlite3_open
26910 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  (.  const char *
26920 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44  filename,   /* D
26930 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65  atabase filename
26940 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71   (UTF-8) */.  sq
26950 6c 69 74 65 33 20 2a 2a 70 70 44 62 20 20 20 20  lite3 **ppDb    
26960 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51        /* OUT: SQ
26970 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a  Lite db handle *
26980 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  /.);.int sqlite3
26990 5f 6f 70 65 6e 31 36 28 0a 20 20 63 6f 6e 73 74  _open16(.  const
269a0 20 76 6f 69 64 20 2a 66 69 6c 65 6e 61 6d 65 2c   void *filename,
269b0 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66     /* Database f
269c0 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 31 36 29  ilename (UTF-16)
269d0 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a   */.  sqlite3 **
269e0 70 70 44 62 20 20 20 20 20 20 20 20 20 20 2f 2a  ppDb          /*
269f0 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20   OUT: SQLite db 
26a00 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 69 6e 74  handle */.);.int
26a10 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
26a20 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  (.  const char *
26a30 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44  filename,   /* D
26a40 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65  atabase filename
26a50 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71   (UTF-8) */.  sq
26a60 6c 69 74 65 33 20 2a 2a 70 70 44 62 2c 20 20 20  lite3 **ppDb,   
26a70 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51        /* OUT: SQ
26a80 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a  Lite db handle *
26a90 2f 0a 20 20 69 6e 74 20 66 6c 61 67 73 2c 20 20  /.  int flags,  
26aa0 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 46              /* F
26ab0 6c 61 67 73 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  lags */.  const 
26ac0 63 68 61 72 20 2a 7a 56 66 73 20 20 20 20 20 20  char *zVfs      
26ad0 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 56 46 53    /* Name of VFS
26ae0 20 6d 6f 64 75 6c 65 20 74 6f 20 75 73 65 20 2a   module to use *
26af0 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  /.);../*.** CAPI
26b00 33 52 45 46 3a 20 4f 62 74 61 69 6e 20 56 61 6c  3REF: Obtain Val
26b10 75 65 73 20 46 6f 72 20 55 52 49 20 50 61 72 61  ues For URI Para
26b20 6d 65 74 65 72 73 0a 2a 2a 0a 2a 2a 20 54 68 65  meters.**.** The
26b30 73 65 20 61 72 65 20 75 74 69 6c 69 74 79 20 72  se are utility r
26b40 6f 75 74 69 6e 65 73 2c 20 75 73 65 66 75 6c 20  outines, useful 
26b50 74 6f 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74  to VFS implement
26b60 61 74 69 6f 6e 73 2c 20 74 68 61 74 20 63 68 65  ations, that che
26b70 63 6b 0a 2a 2a 20 74 6f 20 73 65 65 20 69 66 20  ck.** to see if 
26b80 61 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  a database file 
26b90 77 61 73 20 61 20 55 52 49 20 74 68 61 74 20 63  was a URI that c
26ba0 6f 6e 74 61 69 6e 65 64 20 61 20 73 70 65 63 69  ontained a speci
26bb0 66 69 63 20 71 75 65 72 79 20 0a 2a 2a 20 70 61  fic query .** pa
26bc0 72 61 6d 65 74 65 72 2c 20 61 6e 64 20 69 66 20  rameter, and if 
26bd0 73 6f 20 6f 62 74 61 69 6e 73 20 74 68 65 20 76  so obtains the v
26be0 61 6c 75 65 20 6f 66 20 74 68 61 74 20 71 75 65  alue of that que
26bf0 72 79 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a  ry parameter..**
26c00 0a 2a 2a 20 49 66 20 46 20 69 73 20 74 68 65 20  .** If F is the 
26c10 64 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d  database filenam
26c20 65 20 70 6f 69 6e 74 65 72 20 70 61 73 73 65 64  e pointer passed
26c30 20 69 6e 74 6f 20 74 68 65 20 78 4f 70 65 6e 28   into the xOpen(
26c40 29 20 6d 65 74 68 6f 64 20 6f 66 20 0a 2a 2a 20  ) method of .** 
26c50 61 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61  a VFS implementa
26c60 74 69 6f 6e 20 77 68 65 6e 20 74 68 65 20 66 6c  tion when the fl
26c70 61 67 73 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ags parameter to
26c80 20 78 4f 70 65 6e 28 29 20 68 61 73 20 6f 6e 65   xOpen() has one
26c90 20 6f 72 20 0a 2a 2a 20 6d 6f 72 65 20 6f 66 20   or .** more of 
26ca0 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  the [SQLITE_OPEN
26cb0 5f 55 52 49 5d 20 6f 72 20 5b 53 51 4c 49 54 45  _URI] or [SQLITE
26cc0 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 5d 20 62  _OPEN_MAIN_DB] b
26cd0 69 74 73 20 73 65 74 20 61 6e 64 0a 2a 2a 20 50  its set and.** P
26ce0 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20   is the name of 
26cf0 74 68 65 20 71 75 65 72 79 20 70 61 72 61 6d 65  the query parame
26d00 74 65 72 2c 20 74 68 65 6e 0a 2a 2a 20 73 71 6c  ter, then.** sql
26d10 69 74 65 33 5f 75 72 69 5f 70 61 72 61 6d 65 74  ite3_uri_paramet
26d20 65 72 28 46 2c 50 29 20 72 65 74 75 72 6e 73 20  er(F,P) returns 
26d30 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65  the value of the
26d40 20 50 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20   P.** parameter 
26d50 69 66 20 69 74 20 65 78 69 73 74 73 20 6f 72 20  if it exists or 
26d60 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69  a NULL pointer i
26d70 66 20 50 20 64 6f 65 73 20 6e 6f 74 20 61 70 70  f P does not app
26d80 65 61 72 20 61 73 20 61 20 0a 2a 2a 20 71 75 65  ear as a .** que
26d90 72 79 20 70 61 72 61 6d 65 74 65 72 20 6f 6e 20  ry parameter on 
26da0 46 2e 20 20 49 66 20 50 20 69 73 20 61 20 71 75  F.  If P is a qu
26db0 65 72 79 20 70 61 72 61 6d 65 74 65 72 20 6f 66  ery parameter of
26dc0 20 46 0a 2a 2a 20 68 61 73 20 6e 6f 20 65 78 70   F.** has no exp
26dd0 6c 69 63 69 74 20 76 61 6c 75 65 2c 20 74 68 65  licit value, the
26de0 6e 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 70 61  n sqlite3_uri_pa
26df0 72 61 6d 65 74 65 72 28 46 2c 50 29 20 72 65 74  rameter(F,P) ret
26e00 75 72 6e 73 0a 2a 2a 20 61 20 70 6f 69 6e 74 65  urns.** a pointe
26e10 72 20 74 6f 20 61 6e 20 65 6d 70 74 79 20 73 74  r to an empty st
26e20 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ring..**.** The 
26e30 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c  sqlite3_uri_bool
26e40 65 61 6e 28 46 2c 50 2c 42 29 20 72 6f 75 74 69  ean(F,P,B) routi
26e50 6e 65 20 61 73 73 75 6d 65 73 20 74 68 61 74 20  ne assumes that 
26e60 50 20 69 73 20 61 20 62 6f 6f 6c 65 61 6e 0a 2a  P is a boolean.*
26e70 2a 20 70 61 72 61 6d 65 74 65 72 20 61 6e 64 20  * parameter and 
26e80 72 65 74 75 72 6e 73 20 74 72 75 65 20 28 31 29  returns true (1)
26e90 20 6f 72 20 66 61 6c 73 65 20 28 30 29 20 61 63   or false (0) ac
26ea0 63 6f 72 64 69 6e 67 20 74 6f 20 74 68 65 20 76  cording to the v
26eb0 61 6c 75 65 0a 2a 2a 20 6f 66 20 50 2e 20 20 54  alue.** of P.  T
26ec0 68 65 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62  he sqlite3_uri_b
26ed0 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 6f  oolean(F,P,B) ro
26ee0 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 72  utine returns tr
26ef0 75 65 20 28 31 29 20 69 66 20 74 68 65 0a 2a 2a  ue (1) if the.**
26f00 20 76 61 6c 75 65 20 6f 66 20 71 75 65 72 79 20   value of query 
26f10 70 61 72 61 6d 65 74 65 72 20 50 20 69 73 20 6f  parameter P is o
26f20 6e 65 20 6f 66 20 22 79 65 73 22 2c 20 22 74 72  ne of "yes", "tr
26f30 75 65 22 2c 20 6f 72 20 22 6f 6e 22 20 69 6e 20  ue", or "on" in 
26f40 61 6e 79 0a 2a 2a 20 63 61 73 65 20 6f 72 20 69  any.** case or i
26f50 66 20 74 68 65 20 76 61 6c 75 65 20 62 65 67 69  f the value begi
26f60 6e 73 20 77 69 74 68 20 61 20 6e 6f 6e 2d 7a 65  ns with a non-ze
26f70 72 6f 20 6e 75 6d 62 65 72 2e 20 20 54 68 65 20  ro number.  The 
26f80 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75 72 69 5f  .** sqlite3_uri_
26f90 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72  boolean(F,P,B) r
26fa0 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 73 20  outines returns 
26fb0 66 61 6c 73 65 20 28 30 29 20 69 66 20 74 68 65  false (0) if the
26fc0 20 76 61 6c 75 65 20 6f 66 0a 2a 2a 20 71 75 65   value of.** que
26fd0 72 79 20 70 61 72 61 6d 65 74 65 72 20 50 20 69  ry parameter P i
26fe0 73 20 6f 6e 65 20 6f 66 20 22 6e 6f 22 2c 20 22  s one of "no", "
26ff0 66 61 6c 73 65 22 2c 20 6f 72 20 22 6f 66 66 22  false", or "off"
27000 20 69 6e 20 61 6e 79 20 63 61 73 65 20 6f 72 0a   in any case or.
27010 2a 2a 20 69 66 20 74 68 65 20 76 61 6c 75 65 20  ** if the value 
27020 62 65 67 69 6e 73 20 77 69 74 68 20 61 20 6e 75  begins with a nu
27030 6d 65 72 69 63 20 7a 65 72 6f 2e 20 20 49 66 20  meric zero.  If 
27040 50 20 69 73 20 6e 6f 74 20 61 20 71 75 65 72 79  P is not a query
27050 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 6f 6e  .** parameter on
27060 20 46 20 6f 72 20 69 66 20 74 68 65 20 76 61 6c   F or if the val
27070 75 65 20 6f 66 20 50 20 69 73 20 64 6f 65 73 20  ue of P is does 
27080 6e 6f 74 20 6d 61 74 63 68 20 61 6e 79 20 6f 66  not match any of
27090 20 74 68 65 0a 2a 2a 20 61 62 6f 76 65 2c 20 74   the.** above, t
270a0 68 65 6e 20 73 71 6c 69 74 65 33 5f 75 72 69 5f  hen sqlite3_uri_
270b0 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72  boolean(F,P,B) r
270c0 65 74 75 72 6e 73 20 28 42 21 3d 30 29 2e 0a 2a  eturns (B!=0)..*
270d0 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
270e0 5f 75 72 69 5f 69 6e 74 36 34 28 46 2c 50 2c 44  _uri_int64(F,P,D
270f0 29 20 72 6f 75 74 69 6e 65 20 63 6f 6e 76 65 72  ) routine conver
27100 74 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20  ts the value of 
27110 50 20 69 6e 74 6f 20 61 0a 2a 2a 20 36 34 2d 62  P into a.** 64-b
27120 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65  it signed intege
27130 72 20 61 6e 64 20 72 65 74 75 72 6e 73 20 74 68  r and returns th
27140 61 74 20 69 6e 74 65 67 65 72 2c 20 6f 72 20 44  at integer, or D
27150 20 69 66 20 50 20 64 6f 65 73 20 6e 6f 74 0a 2a   if P does not.*
27160 2a 20 65 78 69 73 74 2e 20 20 49 66 20 74 68 65  * exist.  If the
27170 20 76 61 6c 75 65 20 6f 66 20 50 20 69 73 20 73   value of P is s
27180 6f 6d 65 74 68 69 6e 67 20 6f 74 68 65 72 20 74  omething other t
27190 68 61 6e 20 61 6e 20 69 6e 74 65 67 65 72 2c 20  han an integer, 
271a0 74 68 65 6e 0a 2a 2a 20 7a 65 72 6f 20 69 73 20  then.** zero is 
271b0 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 0a 2a 2a  returned..** .**
271c0 20 49 66 20 46 20 69 73 20 61 20 4e 55 4c 4c 20   If F is a NULL 
271d0 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 73 71  pointer, then sq
271e0 6c 69 74 65 33 5f 75 72 69 5f 70 61 72 61 6d 65  lite3_uri_parame
271f0 74 65 72 28 46 2c 50 29 20 72 65 74 75 72 6e 73  ter(F,P) returns
27200 20 4e 55 4c 4c 20 61 6e 64 0a 2a 2a 20 73 71 6c   NULL and.** sql
27210 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e  ite3_uri_boolean
27220 28 46 2c 50 2c 42 29 20 72 65 74 75 72 6e 73 20  (F,P,B) returns 
27230 42 2e 20 20 49 66 20 46 20 69 73 20 6e 6f 74 20  B.  If F is not 
27240 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 61  a NULL pointer a
27250 6e 64 0a 2a 2a 20 69 73 20 6e 6f 74 20 61 20 64  nd.** is not a d
27260 61 74 61 62 61 73 65 20 66 69 6c 65 20 70 61 74  atabase file pat
27270 68 6e 61 6d 65 20 70 6f 69 6e 74 65 72 20 74 68  hname pointer th
27280 61 74 20 53 51 4c 69 74 65 20 70 61 73 73 65 64  at SQLite passed
27290 20 69 6e 74 6f 20 74 68 65 20 78 4f 70 65 6e 0a   into the xOpen.
272a0 2a 2a 20 56 46 53 20 6d 65 74 68 6f 64 2c 20 74  ** VFS method, t
272b0 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72  hen the behavior
272c0 20 6f 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65   of this routine
272d0 20 69 73 20 75 6e 64 65 66 69 6e 65 64 20 61 6e   is undefined an
272e0 64 20 70 72 6f 62 61 62 6c 79 0a 2a 2a 20 75 6e  d probably.** un
272f0 64 65 73 69 72 61 62 6c 65 2e 0a 2a 2f 0a 63 6f  desirable..*/.co
27300 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65  nst char *sqlite
27310 33 5f 75 72 69 5f 70 61 72 61 6d 65 74 65 72 28  3_uri_parameter(
27320 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c  const char *zFil
27330 65 6e 61 6d 65 2c 20 63 6f 6e 73 74 20 63 68 61  ename, const cha
27340 72 20 2a 7a 50 61 72 61 6d 29 3b 0a 69 6e 74 20  r *zParam);.int 
27350 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c  sqlite3_uri_bool
27360 65 61 6e 28 63 6f 6e 73 74 20 63 68 61 72 20 2a  ean(const char *
27370 7a 46 69 6c 65 2c 20 63 6f 6e 73 74 20 63 68 61  zFile, const cha
27380 72 20 2a 7a 50 61 72 61 6d 2c 20 69 6e 74 20 62  r *zParam, int b
27390 44 65 66 61 75 6c 74 29 3b 0a 73 71 6c 69 74 65  Default);.sqlite
273a0 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f  3_int64 sqlite3_
273b0 75 72 69 5f 69 6e 74 36 34 28 63 6f 6e 73 74 20  uri_int64(const 
273c0 63 68 61 72 2a 2c 20 63 6f 6e 73 74 20 63 68 61  char*, const cha
273d0 72 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  r*, sqlite3_int6
273e0 34 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  4);.../*.** CAPI
273f0 33 52 45 46 3a 20 45 72 72 6f 72 20 43 6f 64 65  3REF: Error Code
27400 73 20 41 6e 64 20 4d 65 73 73 61 67 65 73 0a 2a  s And Messages.*
27410 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65  * METHOD: sqlite
27420 33 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  3.**.** ^If the 
27430 6d 6f 73 74 20 72 65 63 65 6e 74 20 73 71 6c 69  most recent sqli
27440 74 65 33 5f 2a 20 41 50 49 20 63 61 6c 6c 20 61  te3_* API call a
27450 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 0a  ssociated with .
27460 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ** [database con
27470 6e 65 63 74 69 6f 6e 5d 20 44 20 66 61 69 6c 65  nection] D faile
27480 64 2c 20 74 68 65 6e 20 74 68 65 20 73 71 6c 69  d, then the sqli
27490 74 65 33 5f 65 72 72 63 6f 64 65 28 44 29 20 69  te3_errcode(D) i
274a0 6e 74 65 72 66 61 63 65 0a 2a 2a 20 72 65 74 75  nterface.** retu
274b0 72 6e 73 20 74 68 65 20 6e 75 6d 65 72 69 63 20  rns the numeric 
274c0 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 6f 72  [result code] or
274d0 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c   [extended resul
274e0 74 20 63 6f 64 65 5d 20 66 6f 72 20 74 68 61 74  t code] for that
274f0 0a 2a 2a 20 41 50 49 20 63 61 6c 6c 2e 0a 2a 2a  .** API call..**
27500 20 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63   If the most rec
27510 65 6e 74 20 41 50 49 20 63 61 6c 6c 20 77 61 73  ent API call was
27520 20 73 75 63 63 65 73 73 66 75 6c 2c 0a 2a 2a 20   successful,.** 
27530 74 68 65 6e 20 74 68 65 20 72 65 74 75 72 6e 20  then the return 
27540 76 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74  value from sqlit
27550 65 33 5f 65 72 72 63 6f 64 65 28 29 20 69 73 20  e3_errcode() is 
27560 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 5e 54  undefined..** ^T
27570 68 65 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e  he sqlite3_exten
27580 64 65 64 5f 65 72 72 63 6f 64 65 28 29 0a 2a 2a  ded_errcode().**
27590 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 74 68   interface is th
275a0 65 20 73 61 6d 65 20 65 78 63 65 70 74 20 74 68  e same except th
275b0 61 74 20 69 74 20 61 6c 77 61 79 73 20 72 65 74  at it always ret
275c0 75 72 6e 73 20 74 68 65 20 0a 2a 2a 20 5b 65 78  urns the .** [ex
275d0 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f  tended result co
275e0 64 65 5d 20 65 76 65 6e 20 77 68 65 6e 20 65 78  de] even when ex
275f0 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f  tended result co
27600 64 65 73 20 61 72 65 0a 2a 2a 20 64 69 73 61 62  des are.** disab
27610 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  led..**.** ^The 
27620 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29  sqlite3_errmsg()
27630 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 65 72 72   and sqlite3_err
27640 6d 73 67 31 36 28 29 20 72 65 74 75 72 6e 20 45  msg16() return E
27650 6e 67 6c 69 73 68 2d 6c 61 6e 67 75 61 67 65 0a  nglish-language.
27660 2a 2a 20 74 65 78 74 20 74 68 61 74 20 64 65 73  ** text that des
27670 63 72 69 62 65 73 20 74 68 65 20 65 72 72 6f 72  cribes the error
27680 2c 20 61 73 20 65 69 74 68 65 72 20 55 54 46 2d  , as either UTF-
27690 38 20 6f 72 20 55 54 46 2d 31 36 20 72 65 73 70  8 or UTF-16 resp
276a0 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 5e 28 4d  ectively..** ^(M
276b0 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68  emory to hold th
276c0 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20  e error message 
276d0 73 74 72 69 6e 67 20 69 73 20 6d 61 6e 61 67 65  string is manage
276e0 64 20 69 6e 74 65 72 6e 61 6c 6c 79 2e 0a 2a 2a  d internally..**
276f0 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   The application
27700 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74   does not need t
27710 6f 20 77 6f 72 72 79 20 61 62 6f 75 74 20 66 72  o worry about fr
27720 65 65 69 6e 67 20 74 68 65 20 72 65 73 75 6c 74  eeing the result
27730 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20 74 68  ..** However, th
27740 65 20 65 72 72 6f 72 20 73 74 72 69 6e 67 20 6d  e error string m
27750 69 67 68 74 20 62 65 20 6f 76 65 72 77 72 69 74  ight be overwrit
27760 74 65 6e 20 6f 72 20 64 65 61 6c 6c 6f 63 61 74  ten or deallocat
27770 65 64 20 62 79 0a 2a 2a 20 73 75 62 73 65 71 75  ed by.** subsequ
27780 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 6f 74 68  ent calls to oth
27790 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66  er SQLite interf
277a0 61 63 65 20 66 75 6e 63 74 69 6f 6e 73 2e 29 5e  ace functions.)^
277b0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
277c0 74 65 33 5f 65 72 72 73 74 72 28 29 20 69 6e 74  te3_errstr() int
277d0 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74  erface returns t
277e0 68 65 20 45 6e 67 6c 69 73 68 2d 6c 61 6e 67 75  he English-langu
277f0 61 67 65 20 74 65 78 74 0a 2a 2a 20 74 68 61 74  age text.** that
27800 20 64 65 73 63 72 69 62 65 73 20 74 68 65 20 5b   describes the [
27810 72 65 73 75 6c 74 20 63 6f 64 65 5d 2c 20 61 73  result code], as
27820 20 55 54 46 2d 38 2e 0a 2a 2a 20 5e 28 4d 65 6d   UTF-8..** ^(Mem
27830 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20  ory to hold the 
27840 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73 74  error message st
27850 72 69 6e 67 20 69 73 20 6d 61 6e 61 67 65 64 20  ring is managed 
27860 69 6e 74 65 72 6e 61 6c 6c 79 0a 2a 2a 20 61 6e  internally.** an
27870 64 20 6d 75 73 74 20 6e 6f 74 20 62 65 20 66 72  d must not be fr
27880 65 65 64 20 62 79 20 74 68 65 20 61 70 70 6c 69  eed by the appli
27890 63 61 74 69 6f 6e 29 5e 2e 0a 2a 2a 0a 2a 2a 20  cation)^..**.** 
278a0 57 68 65 6e 20 74 68 65 20 73 65 72 69 61 6c 69  When the seriali
278b0 7a 65 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d  zed [threading m
278c0 6f 64 65 5d 20 69 73 20 69 6e 20 75 73 65 2c 20  ode] is in use, 
278d0 69 74 20 6d 69 67 68 74 20 62 65 20 74 68 65 0a  it might be the.
278e0 2a 2a 20 63 61 73 65 20 74 68 61 74 20 61 20 73  ** case that a s
278f0 65 63 6f 6e 64 20 65 72 72 6f 72 20 6f 63 63 75  econd error occu
27900 72 73 20 6f 6e 20 61 20 73 65 70 61 72 61 74 65  rs on a separate
27910 20 74 68 72 65 61 64 20 69 6e 20 62 65 74 77 65   thread in betwe
27920 65 6e 0a 2a 2a 20 74 68 65 20 74 69 6d 65 20 6f  en.** the time o
27930 66 20 74 68 65 20 66 69 72 73 74 20 65 72 72 6f  f the first erro
27940 72 20 61 6e 64 20 74 68 65 20 63 61 6c 6c 20 74  r and the call t
27950 6f 20 74 68 65 73 65 20 69 6e 74 65 72 66 61 63  o these interfac
27960 65 73 2e 0a 2a 2a 20 57 68 65 6e 20 74 68 61 74  es..** When that
27970 20 68 61 70 70 65 6e 73 2c 20 74 68 65 20 73 65   happens, the se
27980 63 6f 6e 64 20 65 72 72 6f 72 20 77 69 6c 6c 20  cond error will 
27990 62 65 20 72 65 70 6f 72 74 65 64 20 73 69 6e 63  be reported sinc
279a0 65 20 74 68 65 73 65 0a 2a 2a 20 69 6e 74 65 72  e these.** inter
279b0 66 61 63 65 73 20 61 6c 77 61 79 73 20 72 65 70  faces always rep
279c0 6f 72 74 20 74 68 65 20 6d 6f 73 74 20 72 65 63  ort the most rec
279d0 65 6e 74 20 72 65 73 75 6c 74 2e 20 20 54 6f 20  ent result.  To 
279e0 61 76 6f 69 64 0a 2a 2a 20 74 68 69 73 2c 20 65  avoid.** this, e
279f0 61 63 68 20 74 68 72 65 61 64 20 63 61 6e 20 6f  ach thread can o
27a00 62 74 61 69 6e 20 65 78 63 6c 75 73 69 76 65 20  btain exclusive 
27a10 75 73 65 20 6f 66 20 74 68 65 20 5b 64 61 74 61  use of the [data
27a20 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
27a30 20 44 0a 2a 2a 20 62 79 20 69 6e 76 6f 6b 69 6e   D.** by invokin
27a40 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  g [sqlite3_mutex
27a50 5f 65 6e 74 65 72 5d 28 5b 73 71 6c 69 74 65 33  _enter]([sqlite3
27a60 5f 64 62 5f 6d 75 74 65 78 5d 28 44 29 29 20 62  _db_mutex](D)) b
27a70 65 66 6f 72 65 20 62 65 67 69 6e 6e 69 6e 67 0a  efore beginning.
27a80 2a 2a 20 74 6f 20 75 73 65 20 44 20 61 6e 64 20  ** to use D and 
27a90 69 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c 69 74 65  invoking [sqlite
27aa0 33 5f 6d 75 74 65 78 5f 6c 65 61 76 65 5d 28 5b  3_mutex_leave]([
27ab0 73 71 6c 69 74 65 33 5f 64 62 5f 6d 75 74 65 78  sqlite3_db_mutex
27ac0 5d 28 44 29 29 20 61 66 74 65 72 0a 2a 2a 20 61  ](D)) after.** a
27ad0 6c 6c 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 20  ll calls to the 
27ae0 69 6e 74 65 72 66 61 63 65 73 20 6c 69 73 74 65  interfaces liste
27af0 64 20 68 65 72 65 20 61 72 65 20 63 6f 6d 70 6c  d here are compl
27b00 65 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61  eted..**.** If a
27b10 6e 20 69 6e 74 65 72 66 61 63 65 20 66 61 69 6c  n interface fail
27b20 73 20 77 69 74 68 20 53 51 4c 49 54 45 5f 4d 49  s with SQLITE_MI
27b30 53 55 53 45 2c 20 74 68 61 74 20 6d 65 61 6e 73  SUSE, that means
27b40 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 0a 2a   the interface.*
27b50 2a 20 77 61 73 20 69 6e 76 6f 6b 65 64 20 69 6e  * was invoked in
27b60 63 6f 72 72 65 63 74 6c 79 20 62 79 20 74 68 65  correctly by the
27b70 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20 49   application.  I
27b80 6e 20 74 68 61 74 20 63 61 73 65 2c 20 74 68 65  n that case, the
27b90 0a 2a 2a 20 65 72 72 6f 72 20 63 6f 64 65 20 61  .** error code a
27ba0 6e 64 20 6d 65 73 73 61 67 65 20 6d 61 79 20 6f  nd message may o
27bb0 72 20 6d 61 79 20 6e 6f 74 20 62 65 20 73 65 74  r may not be set
27bc0 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
27bd0 5f 65 72 72 63 6f 64 65 28 73 71 6c 69 74 65 33  _errcode(sqlite3
27be0 20 2a 64 62 29 3b 0a 69 6e 74 20 73 71 6c 69 74   *db);.int sqlit
27bf0 65 33 5f 65 78 74 65 6e 64 65 64 5f 65 72 72 63  e3_extended_errc
27c00 6f 64 65 28 73 71 6c 69 74 65 33 20 2a 64 62 29  ode(sqlite3 *db)
27c10 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  ;.const char *sq
27c20 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 73 71 6c  lite3_errmsg(sql
27c30 69 74 65 33 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f  ite3*);.const vo
27c40 69 64 20 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d  id *sqlite3_errm
27c50 73 67 31 36 28 73 71 6c 69 74 65 33 2a 29 3b 0a  sg16(sqlite3*);.
27c60 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69  const char *sqli
27c70 74 65 33 5f 65 72 72 73 74 72 28 69 6e 74 29 3b  te3_errstr(int);
27c80 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
27c90 3a 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65  : Prepared State
27ca0 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b  ment Object.** K
27cb0 45 59 57 4f 52 44 53 3a 20 7b 70 72 65 70 61 72  EYWORDS: {prepar
27cc0 65 64 20 73 74 61 74 65 6d 65 6e 74 7d 20 7b 70  ed statement} {p
27cd0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
27ce0 74 73 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73  ts}.**.** An ins
27cf0 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62  tance of this ob
27d00 6a 65 63 74 20 72 65 70 72 65 73 65 6e 74 73 20  ject represents 
27d10 61 20 73 69 6e 67 6c 65 20 53 51 4c 20 73 74 61  a single SQL sta
27d20 74 65 6d 65 6e 74 20 74 68 61 74 0a 2a 2a 20 68  tement that.** h
27d30 61 73 20 62 65 65 6e 20 63 6f 6d 70 69 6c 65 64  as been compiled
27d40 20 69 6e 74 6f 20 62 69 6e 61 72 79 20 66 6f 72   into binary for
27d50 6d 20 61 6e 64 20 69 73 20 72 65 61 64 79 20 74  m and is ready t
27d60 6f 20 62 65 20 65 76 61 6c 75 61 74 65 64 2e 0a  o be evaluated..
27d70 2a 2a 0a 2a 2a 20 54 68 69 6e 6b 20 6f 66 20 65  **.** Think of e
27d80 61 63 68 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ach SQL statemen
27d90 74 20 61 73 20 61 20 73 65 70 61 72 61 74 65 20  t as a separate 
27da0 63 6f 6d 70 75 74 65 72 20 70 72 6f 67 72 61 6d  computer program
27db0 2e 20 20 54 68 65 0a 2a 2a 20 6f 72 69 67 69 6e  .  The.** origin
27dc0 61 6c 20 53 51 4c 20 74 65 78 74 20 69 73 20 73  al SQL text is s
27dd0 6f 75 72 63 65 20 63 6f 64 65 2e 20 20 41 20 70  ource code.  A p
27de0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
27df0 74 20 6f 62 6a 65 63 74 20 0a 2a 2a 20 69 73 20  t object .** is 
27e00 74 68 65 20 63 6f 6d 70 69 6c 65 64 20 6f 62 6a  the compiled obj
27e10 65 63 74 20 63 6f 64 65 2e 20 20 41 6c 6c 20 53  ect code.  All S
27e20 51 4c 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65  QL must be conve
27e30 72 74 65 64 20 69 6e 74 6f 20 61 0a 2a 2a 20 70  rted into a.** p
27e40 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
27e50 74 20 62 65 66 6f 72 65 20 69 74 20 63 61 6e 20  t before it can 
27e60 62 65 20 72 75 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68  be run..**.** Th
27e70 65 20 6c 69 66 65 2d 63 79 63 6c 65 20 6f 66 20  e life-cycle of 
27e80 61 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  a prepared state
27e90 6d 65 6e 74 20 6f 62 6a 65 63 74 20 75 73 75 61  ment object usua
27ea0 6c 6c 79 20 67 6f 65 73 20 6c 69 6b 65 20 74 68  lly goes like th
27eb0 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a  is:.**.** <ol>.*
27ec0 2a 20 3c 6c 69 3e 20 43 72 65 61 74 65 20 74 68  * <li> Create th
27ed0 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  e prepared state
27ee0 6d 65 6e 74 20 6f 62 6a 65 63 74 20 75 73 69 6e  ment object usin
27ef0 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  g [sqlite3_prepa
27f00 72 65 5f 76 32 28 29 5d 2e 0a 2a 2a 20 3c 6c 69  re_v2()]..** <li
27f10 3e 20 42 69 6e 64 20 76 61 6c 75 65 73 20 74 6f  > Bind values to
27f20 20 5b 70 61 72 61 6d 65 74 65 72 73 5d 20 75 73   [parameters] us
27f30 69 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33 5f  ing the sqlite3_
27f40 62 69 6e 64 5f 2a 28 29 0a 2a 2a 20 20 20 20 20  bind_*().**     
27f50 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20   interfaces..** 
27f60 3c 6c 69 3e 20 52 75 6e 20 74 68 65 20 53 51 4c  <li> Run the SQL
27f70 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c   by calling [sql
27f80 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 6e 65  ite3_step()] one
27f90 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a   or more times..
27fa0 2a 2a 20 3c 6c 69 3e 20 52 65 73 65 74 20 74 68  ** <li> Reset th
27fb0 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  e prepared state
27fc0 6d 65 6e 74 20 75 73 69 6e 67 20 5b 73 71 6c 69  ment using [sqli
27fd0 74 65 33 5f 72 65 73 65 74 28 29 5d 20 74 68 65  te3_reset()] the
27fe0 6e 20 67 6f 20 62 61 63 6b 0a 2a 2a 20 20 20 20  n go back.**    
27ff0 20 20 74 6f 20 73 74 65 70 20 32 2e 20 20 44 6f    to step 2.  Do
28000 20 74 68 69 73 20 7a 65 72 6f 20 6f 72 20 6d 6f   this zero or mo
28010 72 65 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69  re times..** <li
28020 3e 20 44 65 73 74 72 6f 79 20 74 68 65 20 6f 62  > Destroy the ob
28030 6a 65 63 74 20 75 73 69 6e 67 20 5b 73 71 6c 69  ject using [sqli
28040 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 2e  te3_finalize()].
28050 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2f 0a 74 79 70  .** </ol>.*/.typ
28060 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69  edef struct sqli
28070 74 65 33 5f 73 74 6d 74 20 73 71 6c 69 74 65 33  te3_stmt sqlite3
28080 5f 73 74 6d 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  _stmt;../*.** CA
28090 50 49 33 52 45 46 3a 20 52 75 6e 2d 74 69 6d 65  PI3REF: Run-time
280a0 20 4c 69 6d 69 74 73 0a 2a 2a 20 4d 45 54 48 4f   Limits.** METHO
280b0 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a  D: sqlite3.**.**
280c0 20 5e 28 54 68 69 73 20 69 6e 74 65 72 66 61 63   ^(This interfac
280d0 65 20 61 6c 6c 6f 77 73 20 74 68 65 20 73 69 7a  e allows the siz
280e0 65 20 6f 66 20 76 61 72 69 6f 75 73 20 63 6f 6e  e of various con
280f0 73 74 72 75 63 74 73 20 74 6f 20 62 65 20 6c 69  structs to be li
28100 6d 69 74 65 64 0a 2a 2a 20 6f 6e 20 61 20 63 6f  mited.** on a co
28110 6e 6e 65 63 74 69 6f 6e 20 62 79 20 63 6f 6e 6e  nnection by conn
28120 65 63 74 69 6f 6e 20 62 61 73 69 73 2e 20 20 54  ection basis.  T
28130 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
28140 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 5b 64 61  er is the.** [da
28150 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
28160 6e 5d 20 77 68 6f 73 65 20 6c 69 6d 69 74 20 69  n] whose limit i
28170 73 20 74 6f 20 62 65 20 73 65 74 20 6f 72 20 71  s to be set or q
28180 75 65 72 69 65 64 2e 20 20 54 68 65 0a 2a 2a 20  ueried.  The.** 
28190 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
281a0 20 69 73 20 6f 6e 65 20 6f 66 20 74 68 65 20 5b   is one of the [
281b0 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73  limit categories
281c0 5d 20 74 68 61 74 20 64 65 66 69 6e 65 20 61 0a  ] that define a.
281d0 2a 2a 20 63 6c 61 73 73 20 6f 66 20 63 6f 6e 73  ** class of cons
281e0 74 72 75 63 74 73 20 74 6f 20 62 65 20 73 69 7a  tructs to be siz
281f0 65 20 6c 69 6d 69 74 65 64 2e 20 20 54 68 65 20  e limited.  The 
28200 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20  third parameter 
28210 69 73 20 74 68 65 0a 2a 2a 20 6e 65 77 20 6c 69  is the.** new li
28220 6d 69 74 20 66 6f 72 20 74 68 61 74 20 63 6f 6e  mit for that con
28230 73 74 72 75 63 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20  struct.)^.**.** 
28240 5e 49 66 20 74 68 65 20 6e 65 77 20 6c 69 6d 69  ^If the new limi
28250 74 20 69 73 20 61 20 6e 65 67 61 74 69 76 65 20  t is a negative 
28260 6e 75 6d 62 65 72 2c 20 74 68 65 20 6c 69 6d 69  number, the limi
28270 74 20 69 73 20 75 6e 63 68 61 6e 67 65 64 2e 0a  t is unchanged..
28280 2a 2a 20 5e 28 46 6f 72 20 65 61 63 68 20 6c 69  ** ^(For each li
28290 6d 69 74 20 63 61 74 65 67 6f 72 79 20 53 51 4c  mit category SQL
282a0 49 54 45 5f 4c 49 4d 49 54 5f 3c 69 3e 4e 41 4d  ITE_LIMIT_<i>NAM
282b0 45 3c 2f 69 3e 20 74 68 65 72 65 20 69 73 20 61  E</i> there is a
282c0 20 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c 20 68   .** [limits | h
282d0 61 72 64 20 75 70 70 65 72 20 62 6f 75 6e 64 5d  ard upper bound]
282e0 0a 2a 2a 20 73 65 74 20 61 74 20 63 6f 6d 70 69  .** set at compi
282f0 6c 65 2d 74 69 6d 65 20 62 79 20 61 20 43 20 70  le-time by a C p
28300 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72  reprocessor macr
28310 6f 20 63 61 6c 6c 65 64 0a 2a 2a 20 5b 6c 69 6d  o called.** [lim
28320 69 74 73 20 7c 20 53 51 4c 49 54 45 5f 4d 41 58  its | SQLITE_MAX
28330 5f 3c 69 3e 4e 41 4d 45 3c 2f 69 3e 5d 2e 0a 2a  _<i>NAME</i>]..*
28340 2a 20 28 54 68 65 20 22 5f 4c 49 4d 49 54 5f 22  * (The "_LIMIT_"
28350 20 69 6e 20 74 68 65 20 6e 61 6d 65 20 69 73 20   in the name is 
28360 63 68 61 6e 67 65 64 20 74 6f 20 22 5f 4d 41 58  changed to "_MAX
28370 5f 22 2e 29 29 5e 0a 2a 2a 20 5e 41 74 74 65 6d  _".))^.** ^Attem
28380 70 74 73 20 74 6f 20 69 6e 63 72 65 61 73 65 20  pts to increase 
28390 61 20 6c 69 6d 69 74 20 61 62 6f 76 65 20 69 74  a limit above it
283a0 73 20 68 61 72 64 20 75 70 70 65 72 20 62 6f 75  s hard upper bou
283b0 6e 64 20 61 72 65 0a 2a 2a 20 73 69 6c 65 6e 74  nd are.** silent
283c0 6c 79 20 74 72 75 6e 63 61 74 65 64 20 74 6f 20  ly truncated to 
283d0 74 68 65 20 68 61 72 64 20 75 70 70 65 72 20 62  the hard upper b
283e0 6f 75 6e 64 2e 0a 2a 2a 0a 2a 2a 20 5e 52 65 67  ound..**.** ^Reg
283f0 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68  ardless of wheth
28400 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 6c 69  er or not the li
28410 6d 69 74 20 77 61 73 20 63 68 61 6e 67 65 64 2c  mit was changed,
28420 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c 69 74 65   the .** [sqlite
28430 33 5f 6c 69 6d 69 74 28 29 5d 20 69 6e 74 65 72  3_limit()] inter
28440 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65  face returns the
28450 20 70 72 69 6f 72 20 76 61 6c 75 65 20 6f 66 20   prior value of 
28460 74 68 65 20 6c 69 6d 69 74 2e 0a 2a 2a 20 5e 48  the limit..** ^H
28470 65 6e 63 65 2c 20 74 6f 20 66 69 6e 64 20 74 68  ence, to find th
28480 65 20 63 75 72 72 65 6e 74 20 76 61 6c 75 65 20  e current value 
28490 6f 66 20 61 20 6c 69 6d 69 74 20 77 69 74 68 6f  of a limit witho
284a0 75 74 20 63 68 61 6e 67 69 6e 67 20 69 74 2c 0a  ut changing it,.
284b0 2a 2a 20 73 69 6d 70 6c 79 20 69 6e 76 6f 6b 65  ** simply invoke
284c0 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 20   this interface 
284d0 77 69 74 68 20 74 68 65 20 74 68 69 72 64 20 70  with the third p
284e0 61 72 61 6d 65 74 65 72 20 73 65 74 20 74 6f 20  arameter set to 
284f0 2d 31 2e 0a 2a 2a 0a 2a 2a 20 52 75 6e 2d 74 69  -1..**.** Run-ti
28500 6d 65 20 6c 69 6d 69 74 73 20 61 72 65 20 69 6e  me limits are in
28510 74 65 6e 64 65 64 20 66 6f 72 20 75 73 65 20 69  tended for use i
28520 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 74  n applications t
28530 68 61 74 20 6d 61 6e 61 67 65 0a 2a 2a 20 62 6f  hat manage.** bo
28540 74 68 20 74 68 65 69 72 20 6f 77 6e 20 69 6e 74  th their own int
28550 65 72 6e 61 6c 20 64 61 74 61 62 61 73 65 20 61  ernal database a
28560 6e 64 20 61 6c 73 6f 20 64 61 74 61 62 61 73 65  nd also database
28570 73 20 74 68 61 74 20 61 72 65 20 63 6f 6e 74 72  s that are contr
28580 6f 6c 6c 65 64 0a 2a 2a 20 62 79 20 75 6e 74 72  olled.** by untr
28590 75 73 74 65 64 20 65 78 74 65 72 6e 61 6c 20 73  usted external s
285a0 6f 75 72 63 65 73 2e 20 20 41 6e 20 65 78 61 6d  ources.  An exam
285b0 70 6c 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  ple application 
285c0 6d 69 67 68 74 20 62 65 20 61 0a 2a 2a 20 77 65  might be a.** we
285d0 62 20 62 72 6f 77 73 65 72 20 74 68 61 74 20 68  b browser that h
285e0 61 73 20 69 74 73 20 6f 77 6e 20 64 61 74 61 62  as its own datab
285f0 61 73 65 73 20 66 6f 72 20 73 74 6f 72 69 6e 67  ases for storing
28600 20 68 69 73 74 6f 72 79 20 61 6e 64 0a 2a 2a 20   history and.** 
28610 73 65 70 61 72 61 74 65 20 64 61 74 61 62 61 73  separate databas
28620 65 73 20 63 6f 6e 74 72 6f 6c 6c 65 64 20 62 79  es controlled by
28630 20 4a 61 76 61 53 63 72 69 70 74 20 61 70 70 6c   JavaScript appl
28640 69 63 61 74 69 6f 6e 73 20 64 6f 77 6e 6c 6f 61  ications downloa
28650 64 65 64 0a 2a 2a 20 6f 66 66 20 74 68 65 20 49  ded.** off the I
28660 6e 74 65 72 6e 65 74 2e 20 20 54 68 65 20 69 6e  nternet.  The in
28670 74 65 72 6e 61 6c 20 64 61 74 61 62 61 73 65 73  ternal databases
28680 20 63 61 6e 20 62 65 20 67 69 76 65 6e 20 74 68   can be given th
28690 65 0a 2a 2a 20 6c 61 72 67 65 2c 20 64 65 66 61  e.** large, defa
286a0 75 6c 74 20 6c 69 6d 69 74 73 2e 20 20 44 61 74  ult limits.  Dat
286b0 61 62 61 73 65 73 20 6d 61 6e 61 67 65 64 20 62  abases managed b
286c0 79 20 65 78 74 65 72 6e 61 6c 20 73 6f 75 72 63  y external sourc
286d0 65 73 20 63 61 6e 0a 2a 2a 20 62 65 20 67 69 76  es can.** be giv
286e0 65 6e 20 6d 75 63 68 20 73 6d 61 6c 6c 65 72 20  en much smaller 
286f0 6c 69 6d 69 74 73 20 64 65 73 69 67 6e 65 64 20  limits designed 
28700 74 6f 20 70 72 65 76 65 6e 74 20 61 20 64 65 6e  to prevent a den
28710 69 61 6c 20 6f 66 20 73 65 72 76 69 63 65 0a 2a  ial of service.*
28720 2a 20 61 74 74 61 63 6b 2e 20 20 44 65 76 65 6c  * attack.  Devel
28730 6f 70 65 72 73 20 6d 69 67 68 74 20 61 6c 73 6f  opers might also
28740 20 77 61 6e 74 20 74 6f 20 75 73 65 20 74 68 65   want to use the
28750 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75   [sqlite3_set_au
28760 74 68 6f 72 69 7a 65 72 28 29 5d 0a 2a 2a 20 69  thorizer()].** i
28770 6e 74 65 72 66 61 63 65 20 74 6f 20 66 75 72 74  nterface to furt
28780 68 65 72 20 63 6f 6e 74 72 6f 6c 20 75 6e 74 72  her control untr
28790 75 73 74 65 64 20 53 51 4c 2e 20 20 54 68 65 20  usted SQL.  The 
287a0 73 69 7a 65 20 6f 66 20 74 68 65 20 64 61 74 61  size of the data
287b0 62 61 73 65 0a 2a 2a 20 63 72 65 61 74 65 64 20  base.** created 
287c0 62 79 20 61 6e 20 75 6e 74 72 75 73 74 65 64 20  by an untrusted 
287d0 73 63 72 69 70 74 20 63 61 6e 20 62 65 20 63 6f  script can be co
287e0 6e 74 61 69 6e 65 64 20 75 73 69 6e 67 20 74 68  ntained using th
287f0 65 0a 2a 2a 20 5b 6d 61 78 5f 70 61 67 65 5f 63  e.** [max_page_c
28800 6f 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d 2e 0a  ount] [PRAGMA]..
28810 2a 2a 0a 2a 2a 20 4e 65 77 20 72 75 6e 2d 74 69  **.** New run-ti
28820 6d 65 20 6c 69 6d 69 74 20 63 61 74 65 67 6f 72  me limit categor
28830 69 65 73 20 6d 61 79 20 62 65 20 61 64 64 65 64  ies may be added
28840 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61   in future relea
28850 73 65 73 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ses..*/.int sqli
28860 74 65 33 5f 6c 69 6d 69 74 28 73 71 6c 69 74 65  te3_limit(sqlite
28870 33 2a 2c 20 69 6e 74 20 69 64 2c 20 69 6e 74 20  3*, int id, int 
28880 6e 65 77 56 61 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20  newVal);../*.** 
28890 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 54 69  CAPI3REF: Run-Ti
288a0 6d 65 20 4c 69 6d 69 74 20 43 61 74 65 67 6f 72  me Limit Categor
288b0 69 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  ies.** KEYWORDS:
288c0 20 7b 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 79   {limit category
288d0 7d 20 7b 2a 6c 69 6d 69 74 20 63 61 74 65 67 6f  } {*limit catego
288e0 72 69 65 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73  ries}.**.** Thes
288f0 65 20 63 6f 6e 73 74 61 6e 74 73 20 64 65 66 69  e constants defi
28900 6e 65 20 76 61 72 69 6f 75 73 20 70 65 72 66 6f  ne various perfo
28910 72 6d 61 6e 63 65 20 6c 69 6d 69 74 73 0a 2a 2a  rmance limits.**
28920 20 74 68 61 74 20 63 61 6e 20 62 65 20 6c 6f 77   that can be low
28930 65 72 65 64 20 61 74 20 72 75 6e 2d 74 69 6d 65  ered at run-time
28940 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
28950 6c 69 6d 69 74 28 29 5d 2e 0a 2a 2a 20 54 68 65  limit()]..** The
28960 20 73 79 6e 6f 70 73 69 73 20 6f 66 20 74 68 65   synopsis of the
28970 20 6d 65 61 6e 69 6e 67 73 20 6f 66 20 74 68 65   meanings of the
28980 20 76 61 72 69 6f 75 73 20 6c 69 6d 69 74 73 20   various limits 
28990 69 73 20 73 68 6f 77 6e 20 62 65 6c 6f 77 2e 0a  is shown below..
289a0 2a 2a 20 41 64 64 69 74 69 6f 6e 61 6c 20 69 6e  ** Additional in
289b0 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 61 76 61  formation is ava
289c0 69 6c 61 62 6c 65 20 61 74 20 5b 6c 69 6d 69 74  ilable at [limit
289d0 73 20 7c 20 4c 69 6d 69 74 73 20 69 6e 20 53 51  s | Limits in SQ
289e0 4c 69 74 65 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c  Lite]..**.** <dl
289f0 3e 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49  >.** [[SQLITE_LI
28a00 4d 49 54 5f 4c 45 4e 47 54 48 5d 5d 20 5e 28 3c  MIT_LENGTH]] ^(<
28a10 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
28a20 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c  LENGTH</dt>.** <
28a30 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 73  dd>The maximum s
28a40 69 7a 65 20 6f 66 20 61 6e 79 20 73 74 72 69 6e  ize of any strin
28a50 67 20 6f 72 20 42 4c 4f 42 20 6f 72 20 74 61 62  g or BLOB or tab
28a60 6c 65 20 72 6f 77 2c 20 69 6e 20 62 79 74 65 73  le row, in bytes
28a70 2e 3c 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b  .<dd>)^.**.** [[
28a80 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c  SQLITE_LIMIT_SQL
28a90 5f 4c 45 4e 47 54 48 5d 5d 20 5e 28 3c 64 74 3e  _LENGTH]] ^(<dt>
28aa0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c  SQLITE_LIMIT_SQL
28ab0 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20  _LENGTH</dt>.** 
28ac0 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
28ad0 6c 65 6e 67 74 68 20 6f 66 20 61 6e 20 53 51 4c  length of an SQL
28ae0 20 73 74 61 74 65 6d 65 6e 74 2c 20 69 6e 20 62   statement, in b
28af0 79 74 65 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a  ytes.</dd>)^.**.
28b00 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49  ** [[SQLITE_LIMI
28b10 54 5f 43 4f 4c 55 4d 4e 5d 5d 20 5e 28 3c 64 74  T_COLUMN]] ^(<dt
28b20 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f  >SQLITE_LIMIT_CO
28b30 4c 55 4d 4e 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  LUMN</dt>.** <dd
28b40 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d  >The maximum num
28b50 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69  ber of columns i
28b60 6e 20 61 20 74 61 62 6c 65 20 64 65 66 69 6e 69  n a table defini
28b70 74 69 6f 6e 20 6f 72 20 69 6e 20 74 68 65 0a 2a  tion or in the.*
28b80 2a 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20  * result set of 
28b90 61 20 5b 53 45 4c 45 43 54 5d 20 6f 72 20 74 68  a [SELECT] or th
28ba0 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72  e maximum number
28bb0 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61   of columns in a
28bc0 6e 20 69 6e 64 65 78 0a 2a 2a 20 6f 72 20 69 6e  n index.** or in
28bd0 20 61 6e 20 4f 52 44 45 52 20 42 59 20 6f 72 20   an ORDER BY or 
28be0 47 52 4f 55 50 20 42 59 20 63 6c 61 75 73 65 2e  GROUP BY clause.
28bf0 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b  </dd>)^.**.** [[
28c00 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50  SQLITE_LIMIT_EXP
28c10 52 5f 44 45 50 54 48 5d 5d 20 5e 28 3c 64 74 3e  R_DEPTH]] ^(<dt>
28c20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50  SQLITE_LIMIT_EXP
28c30 52 5f 44 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a 20  R_DEPTH</dt>.** 
28c40 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
28c50 64 65 70 74 68 20 6f 66 20 74 68 65 20 70 61 72  depth of the par
28c60 73 65 20 74 72 65 65 20 6f 6e 20 61 6e 79 20 65  se tree on any e
28c70 78 70 72 65 73 73 69 6f 6e 2e 3c 2f 64 64 3e 29  xpression.</dd>)
28c80 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  ^.**.** [[SQLITE
28c90 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f  _LIMIT_COMPOUND_
28ca0 53 45 4c 45 43 54 5d 5d 20 5e 28 3c 64 74 3e 53  SELECT]] ^(<dt>S
28cb0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50  QLITE_LIMIT_COMP
28cc0 4f 55 4e 44 5f 53 45 4c 45 43 54 3c 2f 64 74 3e  OUND_SELECT</dt>
28cd0 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
28ce0 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 74 65  mum number of te
28cf0 72 6d 73 20 69 6e 20 61 20 63 6f 6d 70 6f 75 6e  rms in a compoun
28d00 64 20 53 45 4c 45 43 54 20 73 74 61 74 65 6d 65  d SELECT stateme
28d10 6e 74 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a  nt.</dd>)^.**.**
28d20 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f   [[SQLITE_LIMIT_
28d30 56 44 42 45 5f 4f 50 5d 5d 20 5e 28 3c 64 74 3e  VDBE_OP]] ^(<dt>
28d40 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42  SQLITE_LIMIT_VDB
28d50 45 5f 4f 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  E_OP</dt>.** <dd
28d60 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d  >The maximum num
28d70 62 65 72 20 6f 66 20 69 6e 73 74 72 75 63 74 69  ber of instructi
28d80 6f 6e 73 20 69 6e 20 61 20 76 69 72 74 75 61 6c  ons in a virtual
28d90 20 6d 61 63 68 69 6e 65 20 70 72 6f 67 72 61 6d   machine program
28da0 0a 2a 2a 20 75 73 65 64 20 74 6f 20 69 6d 70 6c  .** used to impl
28db0 65 6d 65 6e 74 20 61 6e 20 53 51 4c 20 73 74 61  ement an SQL sta
28dc0 74 65 6d 65 6e 74 2e 20 20 54 68 69 73 20 6c 69  tement.  This li
28dd0 6d 69 74 20 69 73 20 6e 6f 74 20 63 75 72 72 65  mit is not curre
28de0 6e 74 6c 79 0a 2a 2a 20 65 6e 66 6f 72 63 65 64  ntly.** enforced
28df0 2c 20 74 68 6f 75 67 68 20 74 68 61 74 20 6d 69  , though that mi
28e00 67 68 74 20 62 65 20 61 64 64 65 64 20 69 6e 20  ght be added in 
28e10 73 6f 6d 65 20 66 75 74 75 72 65 20 72 65 6c 65  some future rele
28e20 61 73 65 20 6f 66 0a 2a 2a 20 53 51 4c 69 74 65  ase of.** SQLite
28e30 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b  .</dd>)^.**.** [
28e40 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55  [SQLITE_LIMIT_FU
28e50 4e 43 54 49 4f 4e 5f 41 52 47 5d 5d 20 5e 28 3c  NCTION_ARG]] ^(<
28e60 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
28e70 46 55 4e 43 54 49 4f 4e 5f 41 52 47 3c 2f 64 74  FUNCTION_ARG</dt
28e80 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78  >.** <dd>The max
28e90 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 61  imum number of a
28ea0 72 67 75 6d 65 6e 74 73 20 6f 6e 20 61 20 66 75  rguments on a fu
28eb0 6e 63 74 69 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a  nction.</dd>)^.*
28ec0 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49  *.** [[SQLITE_LI
28ed0 4d 49 54 5f 41 54 54 41 43 48 45 44 5d 5d 20 5e  MIT_ATTACHED]] ^
28ee0 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49  (<dt>SQLITE_LIMI
28ef0 54 5f 41 54 54 41 43 48 45 44 3c 2f 64 74 3e 0a  T_ATTACHED</dt>.
28f00 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
28f10 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 5b 41 54  um number of [AT
28f20 54 41 43 48 20 7c 20 61 74 74 61 63 68 65 64 20  TACH | attached 
28f30 64 61 74 61 62 61 73 65 73 5d 2e 29 5e 3c 2f 64  databases].)^</d
28f40 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
28f50 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54  E_LIMIT_LIKE_PAT
28f60 54 45 52 4e 5f 4c 45 4e 47 54 48 5d 5d 0a 2a 2a  TERN_LENGTH]].**
28f70 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49   ^(<dt>SQLITE_LI
28f80 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e  MIT_LIKE_PATTERN
28f90 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20  _LENGTH</dt>.** 
28fa0 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
28fb0 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20 70 61  length of the pa
28fc0 74 74 65 72 6e 20 61 72 67 75 6d 65 6e 74 20 74  ttern argument t
28fd0 6f 20 74 68 65 20 5b 4c 49 4b 45 5d 20 6f 72 0a  o the [LIKE] or.
28fe0 2a 2a 20 5b 47 4c 4f 42 5d 20 6f 70 65 72 61 74  ** [GLOB] operat
28ff0 6f 72 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a  ors.</dd>)^.**.*
29000 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54  * [[SQLITE_LIMIT
29010 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52  _VARIABLE_NUMBER
29020 5d 5d 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49  ]].** ^(<dt>SQLI
29030 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c  TE_LIMIT_VARIABL
29040 45 5f 4e 55 4d 42 45 52 3c 2f 64 74 3e 0a 2a 2a  E_NUMBER</dt>.**
29050 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
29060 20 69 6e 64 65 78 20 6e 75 6d 62 65 72 20 6f 66   index number of
29070 20 61 6e 79 20 5b 70 61 72 61 6d 65 74 65 72 5d   any [parameter]
29080 20 69 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65   in an SQL state
29090 6d 65 6e 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b  ment.)^.**.** [[
290a0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49  SQLITE_LIMIT_TRI
290b0 47 47 45 52 5f 44 45 50 54 48 5d 5d 20 5e 28 3c  GGER_DEPTH]] ^(<
290c0 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
290d0 54 52 49 47 47 45 52 5f 44 45 50 54 48 3c 2f 64  TRIGGER_DEPTH</d
290e0 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61  t>.** <dd>The ma
290f0 78 69 6d 75 6d 20 64 65 70 74 68 20 6f 66 20 72  ximum depth of r
29100 65 63 75 72 73 69 6f 6e 20 66 6f 72 20 74 72 69  ecursion for tri
29110 67 67 65 72 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a  ggers.</dd>)^.**
29120 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d  .** [[SQLITE_LIM
29130 49 54 5f 57 4f 52 4b 45 52 5f 54 48 52 45 41 44  IT_WORKER_THREAD
29140 53 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45  S]] ^(<dt>SQLITE
29150 5f 4c 49 4d 49 54 5f 57 4f 52 4b 45 52 5f 54 48  _LIMIT_WORKER_TH
29160 52 45 41 44 53 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  READS</dt>.** <d
29170 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75  d>The maximum nu
29180 6d 62 65 72 20 6f 66 20 61 75 78 69 6c 69 61 72  mber of auxiliar
29190 79 20 77 6f 72 6b 65 72 20 74 68 72 65 61 64 73  y worker threads
291a0 20 74 68 61 74 20 61 20 73 69 6e 67 6c 65 0a 2a   that a single.*
291b0 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  * [prepared stat
291c0 65 6d 65 6e 74 5d 20 6d 61 79 20 73 74 61 72 74  ement] may start
291d0 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c  .</dd>)^.** </dl
291e0 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  >.*/.#define SQL
291f0 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48  ITE_LIMIT_LENGTH
29200 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
29210 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51      0.#define SQ
29220 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c  LITE_LIMIT_SQL_L
29230 45 4e 47 54 48 20 20 20 20 20 20 20 20 20 20 20  ENGTH           
29240 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53       1.#define S
29250 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55  QLITE_LIMIT_COLU
29260 4d 4e 20 20 20 20 20 20 20 20 20 20 20 20 20 20  MN              
29270 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20        2.#define 
29280 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50  SQLITE_LIMIT_EXP
29290 52 5f 44 45 50 54 48 20 20 20 20 20 20 20 20 20  R_DEPTH         
292a0 20 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65         3.#define
292b0 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f   SQLITE_LIMIT_CO
292c0 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 20 20 20  MPOUND_SELECT   
292d0 20 20 20 20 20 20 20 20 34 0a 23 64 65 66 69 6e          4.#defin
292e0 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56  e SQLITE_LIMIT_V
292f0 44 42 45 5f 4f 50 20 20 20 20 20 20 20 20 20 20  DBE_OP          
29300 20 20 20 20 20 20 20 20 20 35 0a 23 64 65 66 69           5.#defi
29310 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
29320 46 55 4e 43 54 49 4f 4e 5f 41 52 47 20 20 20 20  FUNCTION_ARG    
29330 20 20 20 20 20 20 20 20 20 20 36 0a 23 64 65 66            6.#def
29340 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
29350 5f 41 54 54 41 43 48 45 44 20 20 20 20 20 20 20  _ATTACHED       
29360 20 20 20 20 20 20 20 20 20 20 20 37 0a 23 64 65             7.#de
29370 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
29380 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c  T_LIKE_PATTERN_L
29390 45 4e 47 54 48 20 20 20 20 20 20 20 38 0a 23 64  ENGTH       8.#d
293a0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
293b0 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42  IT_VARIABLE_NUMB
293c0 45 52 20 20 20 20 20 20 20 20 20 20 20 39 0a 23  ER           9.#
293d0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
293e0 4d 49 54 5f 54 52 49 47 47 45 52 5f 44 45 50 54  MIT_TRIGGER_DEPT
293f0 48 20 20 20 20 20 20 20 20 20 20 20 20 31 30 0a  H            10.
29400 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
29410 49 4d 49 54 5f 57 4f 52 4b 45 52 5f 54 48 52 45  IMIT_WORKER_THRE
29420 41 44 53 20 20 20 20 20 20 20 20 20 20 20 31 31  ADS           11
29430 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
29440 3a 20 43 6f 6d 70 69 6c 69 6e 67 20 41 6e 20 53  : Compiling An S
29450 51 4c 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 20  QL Statement.** 
29460 4b 45 59 57 4f 52 44 53 3a 20 7b 53 51 4c 20 73  KEYWORDS: {SQL s
29470 74 61 74 65 6d 65 6e 74 20 63 6f 6d 70 69 6c 65  tatement compile
29480 72 7d 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  r}.** METHOD: sq
29490 6c 69 74 65 33 0a 2a 2a 20 43 4f 4e 53 54 52 55  lite3.** CONSTRU
294a0 43 54 4f 52 3a 20 73 71 6c 69 74 65 33 5f 73 74  CTOR: sqlite3_st
294b0 6d 74 0a 2a 2a 0a 2a 2a 20 54 6f 20 65 78 65 63  mt.**.** To exec
294c0 75 74 65 20 61 6e 20 53 51 4c 20 71 75 65 72 79  ute an SQL query
294d0 2c 20 69 74 20 6d 75 73 74 20 66 69 72 73 74 20  , it must first 
294e0 62 65 20 63 6f 6d 70 69 6c 65 64 20 69 6e 74 6f  be compiled into
294f0 20 61 20 62 79 74 65 2d 63 6f 64 65 0a 2a 2a 20   a byte-code.** 
29500 70 72 6f 67 72 61 6d 20 75 73 69 6e 67 20 6f 6e  program using on
29510 65 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69  e of these routi
29520 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66  nes..**.** The f
29530 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2c 20 22  irst argument, "
29540 64 62 22 2c 20 69 73 20 61 20 5b 64 61 74 61 62  db", is a [datab
29550 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
29560 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 61 0a  obtained from a.
29570 2a 2a 20 70 72 69 6f 72 20 73 75 63 63 65 73 73  ** prior success
29580 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  ful call to [sql
29590 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73  ite3_open()], [s
295a0 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
295b0 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ] or.** [sqlite3
295c0 5f 6f 70 65 6e 31 36 28 29 5d 2e 20 20 54 68 65  _open16()].  The
295d0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
295e0 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 68 61  tion must not ha
295f0 76 65 20 62 65 65 6e 20 63 6c 6f 73 65 64 2e 0a  ve been closed..
29600 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64  **.** The second
29610 20 61 72 67 75 6d 65 6e 74 2c 20 22 7a 53 71 6c   argument, "zSql
29620 22 2c 20 69 73 20 74 68 65 20 73 74 61 74 65 6d  ", is the statem
29630 65 6e 74 20 74 6f 20 62 65 20 63 6f 6d 70 69 6c  ent to be compil
29640 65 64 2c 20 65 6e 63 6f 64 65 64 0a 2a 2a 20 61  ed, encoded.** a
29650 73 20 65 69 74 68 65 72 20 55 54 46 2d 38 20 6f  s either UTF-8 o
29660 72 20 55 54 46 2d 31 36 2e 20 20 54 68 65 20 73  r UTF-16.  The s
29670 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29  qlite3_prepare()
29680 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65   and sqlite3_pre
29690 70 61 72 65 5f 76 32 28 29 0a 2a 2a 20 69 6e 74  pare_v2().** int
296a0 65 72 66 61 63 65 73 20 75 73 65 20 55 54 46 2d  erfaces use UTF-
296b0 38 2c 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70  8, and sqlite3_p
296c0 72 65 70 61 72 65 31 36 28 29 20 61 6e 64 20 73  repare16() and s
296d0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
296e0 5f 76 32 28 29 0a 2a 2a 20 75 73 65 20 55 54 46  _v2().** use UTF
296f0 2d 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  -16..**.** ^If t
29700 68 65 20 6e 42 79 74 65 20 61 72 67 75 6d 65 6e  he nByte argumen
29710 74 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74  t is negative, t
29720 68 65 6e 20 7a 53 71 6c 20 69 73 20 72 65 61 64  hen zSql is read
29730 20 75 70 20 74 6f 20 74 68 65 0a 2a 2a 20 66 69   up to the.** fi
29740 72 73 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61  rst zero termina
29750 74 6f 72 2e 20 5e 49 66 20 6e 42 79 74 65 20 69  tor. ^If nByte i
29760 73 20 70 6f 73 69 74 69 76 65 2c 20 74 68 65 6e  s positive, then
29770 20 69 74 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75   it is the.** nu
29780 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 72 65  mber of bytes re
29790 61 64 20 66 72 6f 6d 20 7a 53 71 6c 2e 20 20 5e  ad from zSql.  ^
297a0 49 66 20 6e 42 79 74 65 20 69 73 20 7a 65 72 6f  If nByte is zero
297b0 2c 20 74 68 65 6e 20 6e 6f 20 70 72 65 70 61 72  , then no prepar
297c0 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20  ed.** statement 
297d0 69 73 20 67 65 6e 65 72 61 74 65 64 2e 0a 2a 2a  is generated..**
297e0 20 49 66 20 74 68 65 20 63 61 6c 6c 65 72 20 6b   If the caller k
297f0 6e 6f 77 73 20 74 68 61 74 20 74 68 65 20 73 75  nows that the su
29800 70 70 6c 69 65 64 20 73 74 72 69 6e 67 20 69 73  pplied string is
29810 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 65 64 2c   nul-terminated,
29820 20 74 68 65 6e 0a 2a 2a 20 74 68 65 72 65 20 69   then.** there i
29830 73 20 61 20 73 6d 61 6c 6c 20 70 65 72 66 6f 72  s a small perfor
29840 6d 61 6e 63 65 20 61 64 76 61 6e 74 61 67 65 20  mance advantage 
29850 74 6f 20 70 61 73 73 69 6e 67 20 61 6e 20 6e 42  to passing an nB
29860 79 74 65 20 70 61 72 61 6d 65 74 65 72 20 74 68  yte parameter th
29870 61 74 0a 2a 2a 20 69 73 20 74 68 65 20 6e 75 6d  at.** is the num
29880 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20  ber of bytes in 
29890 74 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67  the input string
298a0 20 3c 69 3e 69 6e 63 6c 75 64 69 6e 67 3c 2f 69   <i>including</i
298b0 3e 0a 2a 2a 20 74 68 65 20 6e 75 6c 2d 74 65 72  >.** the nul-ter
298c0 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 0a 2a 2a 20 5e  minator..**.** ^
298d0 49 66 20 70 7a 54 61 69 6c 20 69 73 20 6e 6f 74  If pzTail is not
298e0 20 4e 55 4c 4c 20 74 68 65 6e 20 2a 70 7a 54 61   NULL then *pzTa
298f0 69 6c 20 69 73 20 6d 61 64 65 20 74 6f 20 70 6f  il is made to po
29900 69 6e 74 20 74 6f 20 74 68 65 20 66 69 72 73 74  int to the first
29910 20 62 79 74 65 0a 2a 2a 20 70 61 73 74 20 74 68   byte.** past th
29920 65 20 65 6e 64 20 6f 66 20 74 68 65 20 66 69 72  e end of the fir
29930 73 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  st SQL statement
29940 20 69 6e 20 7a 53 71 6c 2e 20 20 54 68 65 73 65   in zSql.  These
29950 20 72 6f 75 74 69 6e 65 73 20 6f 6e 6c 79 0a 2a   routines only.*
29960 2a 20 63 6f 6d 70 69 6c 65 20 74 68 65 20 66 69  * compile the fi
29970 72 73 74 20 73 74 61 74 65 6d 65 6e 74 20 69 6e  rst statement in
29980 20 7a 53 71 6c 2c 20 73 6f 20 2a 70 7a 54 61 69   zSql, so *pzTai
29990 6c 20 69 73 20 6c 65 66 74 20 70 6f 69 6e 74 69  l is left pointi
299a0 6e 67 20 74 6f 0a 2a 2a 20 77 68 61 74 20 72 65  ng to.** what re
299b0 6d 61 69 6e 73 20 75 6e 63 6f 6d 70 69 6c 65 64  mains uncompiled
299c0 2e 0a 2a 2a 0a 2a 2a 20 5e 2a 70 70 53 74 6d 74  ..**.** ^*ppStmt
299d0 20 69 73 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e   is left pointin
299e0 67 20 74 6f 20 61 20 63 6f 6d 70 69 6c 65 64 20  g to a compiled 
299f0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
29a00 65 6e 74 5d 20 74 68 61 74 20 63 61 6e 20 62 65  ent] that can be
29a10 0a 2a 2a 20 65 78 65 63 75 74 65 64 20 75 73 69  .** executed usi
29a20 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  ng [sqlite3_step
29a30 28 29 5d 2e 20 20 5e 49 66 20 74 68 65 72 65 20  ()].  ^If there 
29a40 69 73 20 61 6e 20 65 72 72 6f 72 2c 20 2a 70 70  is an error, *pp
29a50 53 74 6d 74 20 69 73 20 73 65 74 0a 2a 2a 20 74  Stmt is set.** t
29a60 6f 20 4e 55 4c 4c 2e 20 20 5e 49 66 20 74 68 65  o NULL.  ^If the
29a70 20 69 6e 70 75 74 20 74 65 78 74 20 63 6f 6e 74   input text cont
29a80 61 69 6e 73 20 6e 6f 20 53 51 4c 20 28 69 66 20  ains no SQL (if 
29a90 74 68 65 20 69 6e 70 75 74 20 69 73 20 61 6e 20  the input is an 
29aa0 65 6d 70 74 79 0a 2a 2a 20 73 74 72 69 6e 67 20  empty.** string 
29ab0 6f 72 20 61 20 63 6f 6d 6d 65 6e 74 29 20 74 68  or a comment) th
29ac0 65 6e 20 2a 70 70 53 74 6d 74 20 69 73 20 73 65  en *ppStmt is se
29ad0 74 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 20 54 68  t to NULL..** Th
29ae0 65 20 63 61 6c 6c 69 6e 67 20 70 72 6f 63 65 64  e calling proced
29af0 75 72 65 20 69 73 20 72 65 73 70 6f 6e 73 69 62  ure is responsib
29b00 6c 65 20 66 6f 72 20 64 65 6c 65 74 69 6e 67 20  le for deleting 
29b10 74 68 65 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20  the compiled.** 
29b20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 75 73  SQL statement us
29b30 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e  ing [sqlite3_fin
29b40 61 6c 69 7a 65 28 29 5d 20 61 66 74 65 72 20 69  alize()] after i
29b50 74 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 77  t has finished w
29b60 69 74 68 20 69 74 2e 0a 2a 2a 20 70 70 53 74 6d  ith it..** ppStm
29b70 74 20 6d 61 79 20 6e 6f 74 20 62 65 20 4e 55 4c  t may not be NUL
29b80 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 20 73 75 63  L..**.** ^On suc
29b90 63 65 73 73 2c 20 74 68 65 20 73 71 6c 69 74 65  cess, the sqlite
29ba0 33 5f 70 72 65 70 61 72 65 28 29 20 66 61 6d 69  3_prepare() fami
29bb0 6c 79 20 6f 66 20 72 6f 75 74 69 6e 65 73 20 72  ly of routines r
29bc0 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b  eturn [SQLITE_OK
29bd0 5d 3b 0a 2a 2a 20 6f 74 68 65 72 77 69 73 65 20  ];.** otherwise 
29be0 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20  an [error code] 
29bf0 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a  is returned..**.
29c00 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 70  ** The sqlite3_p
29c10 72 65 70 61 72 65 5f 76 32 28 29 20 61 6e 64 20  repare_v2() and 
29c20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
29c30 36 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63 65  6_v2() interface
29c40 73 20 61 72 65 0a 2a 2a 20 72 65 63 6f 6d 6d 65  s are.** recomme
29c50 6e 64 65 64 20 66 6f 72 20 61 6c 6c 20 6e 65 77  nded for all new
29c60 20 70 72 6f 67 72 61 6d 73 2e 20 54 68 65 20 74   programs. The t
29c70 77 6f 20 6f 6c 64 65 72 20 69 6e 74 65 72 66 61  wo older interfa
29c80 63 65 73 20 61 72 65 20 72 65 74 61 69 6e 65 64  ces are retained
29c90 0a 2a 2a 20 66 6f 72 20 62 61 63 6b 77 61 72 64  .** for backward
29ca0 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2c  s compatibility,
29cb0 20 62 75 74 20 74 68 65 69 72 20 75 73 65 20 69   but their use i
29cc0 73 20 64 69 73 63 6f 75 72 61 67 65 64 2e 0a 2a  s discouraged..*
29cd0 2a 20 5e 49 6e 20 74 68 65 20 22 76 32 22 20 69  * ^In the "v2" i
29ce0 6e 74 65 72 66 61 63 65 73 2c 20 74 68 65 20 70  nterfaces, the p
29cf0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
29d00 74 0a 2a 2a 20 74 68 61 74 20 69 73 20 72 65 74  t.** that is ret
29d10 75 72 6e 65 64 20 28 74 68 65 20 5b 73 71 6c 69  urned (the [sqli
29d20 74 65 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74  te3_stmt] object
29d30 29 20 63 6f 6e 74 61 69 6e 73 20 61 20 63 6f 70  ) contains a cop
29d40 79 20 6f 66 20 74 68 65 0a 2a 2a 20 6f 72 69 67  y of the.** orig
29d50 69 6e 61 6c 20 53 51 4c 20 74 65 78 74 2e 20 54  inal SQL text. T
29d60 68 69 73 20 63 61 75 73 65 73 20 74 68 65 20 5b  his causes the [
29d70 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
29d80 69 6e 74 65 72 66 61 63 65 20 74 6f 0a 2a 2a 20  interface to.** 
29d90 62 65 68 61 76 65 20 64 69 66 66 65 72 65 6e 74  behave different
29da0 6c 79 20 69 6e 20 74 68 72 65 65 20 77 61 79 73  ly in three ways
29db0 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20  :.**.** <ol>.** 
29dc0 3c 6c 69 3e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  <li>.** ^If the 
29dd0 64 61 74 61 62 61 73 65 20 73 63 68 65 6d 61 20  database schema 
29de0 63 68 61 6e 67 65 73 2c 20 69 6e 73 74 65 61 64  changes, instead
29df0 20 6f 66 20 72 65 74 75 72 6e 69 6e 67 20 5b 53   of returning [S
29e00 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 20 61 73  QLITE_SCHEMA] as
29e10 20 69 74 0a 2a 2a 20 61 6c 77 61 79 73 20 75 73   it.** always us
29e20 65 64 20 74 6f 20 64 6f 2c 20 5b 73 71 6c 69 74  ed to do, [sqlit
29e30 65 33 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c 20  e3_step()] will 
29e40 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 65  automatically re
29e50 63 6f 6d 70 69 6c 65 20 74 68 65 20 53 51 4c 0a  compile the SQL.
29e60 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64  ** statement and
29e70 20 74 72 79 20 74 6f 20 72 75 6e 20 69 74 20 61   try to run it a
29e80 67 61 69 6e 2e 20 41 73 20 6d 61 6e 79 20 61 73  gain. As many as
29e90 20 5b 53 51 4c 49 54 45 5f 4d 41 58 5f 53 43 48   [SQLITE_MAX_SCH
29ea0 45 4d 41 5f 52 45 54 52 59 5d 0a 2a 2a 20 72 65  EMA_RETRY].** re
29eb0 74 72 69 65 73 20 77 69 6c 6c 20 6f 63 63 75 72  tries will occur
29ec0 20 62 65 66 6f 72 65 20 73 71 6c 69 74 65 33 5f   before sqlite3_
29ed0 73 74 65 70 28 29 20 67 69 76 65 73 20 75 70 20  step() gives up 
29ee0 61 6e 64 20 72 65 74 75 72 6e 73 20 61 6e 20 65  and returns an e
29ef0 72 72 6f 72 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a  rror..** </li>.*
29f00 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 57 68  *.** <li>.** ^Wh
29f10 65 6e 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75  en an error occu
29f20 72 73 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  rs, [sqlite3_ste
29f30 70 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e  p()] will return
29f40 20 6f 6e 65 20 6f 66 20 74 68 65 20 64 65 74 61   one of the deta
29f50 69 6c 65 64 0a 2a 2a 20 5b 65 72 72 6f 72 20 63  iled.** [error c
29f60 6f 64 65 73 5d 20 6f 72 20 5b 65 78 74 65 6e 64  odes] or [extend
29f70 65 64 20 65 72 72 6f 72 20 63 6f 64 65 73 5d 2e  ed error codes].
29f80 20 20 5e 54 68 65 20 6c 65 67 61 63 79 20 62 65    ^The legacy be
29f90 68 61 76 69 6f 72 20 77 61 73 20 74 68 61 74 0a  havior was that.
29fa0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  ** [sqlite3_step
29fb0 28 29 5d 20 77 6f 75 6c 64 20 6f 6e 6c 79 20 72  ()] would only r
29fc0 65 74 75 72 6e 20 61 20 67 65 6e 65 72 69 63 20  eturn a generic 
29fd0 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 72  [SQLITE_ERROR] r
29fe0 65 73 75 6c 74 20 63 6f 64 65 0a 2a 2a 20 61 6e  esult code.** an
29ff0 64 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  d the applicatio
2a000 6e 20 77 6f 75 6c 64 20 68 61 76 65 20 74 6f 20  n would have to 
2a010 6d 61 6b 65 20 61 20 73 65 63 6f 6e 64 20 63 61  make a second ca
2a020 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72  ll to [sqlite3_r
2a030 65 73 65 74 28 29 5d 0a 2a 2a 20 69 6e 20 6f 72  eset()].** in or
2a040 64 65 72 20 74 6f 20 66 69 6e 64 20 74 68 65 20  der to find the 
2a050 75 6e 64 65 72 6c 79 69 6e 67 20 63 61 75 73 65  underlying cause
2a060 20 6f 66 20 74 68 65 20 70 72 6f 62 6c 65 6d 2e   of the problem.
2a070 20 57 69 74 68 20 74 68 65 20 22 76 32 22 20 70   With the "v2" p
2a080 72 65 70 61 72 65 0a 2a 2a 20 69 6e 74 65 72 66  repare.** interf
2a090 61 63 65 73 2c 20 74 68 65 20 75 6e 64 65 72 6c  aces, the underl
2a0a0 79 69 6e 67 20 72 65 61 73 6f 6e 20 66 6f 72 20  ying reason for 
2a0b0 74 68 65 20 65 72 72 6f 72 20 69 73 20 72 65 74  the error is ret
2a0c0 75 72 6e 65 64 20 69 6d 6d 65 64 69 61 74 65 6c  urned immediatel
2a0d0 79 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a  y..** </li>.**.*
2a0e0 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 49 66 20 74 68  * <li>.** ^If th
2a0f0 65 20 73 70 65 63 69 66 69 63 20 76 61 6c 75 65  e specific value
2a100 20 62 6f 75 6e 64 20 74 6f 20 5b 70 61 72 61 6d   bound to [param
2a110 65 74 65 72 20 7c 20 68 6f 73 74 20 70 61 72 61  eter | host para
2a120 6d 65 74 65 72 5d 20 69 6e 20 74 68 65 20 0a 2a  meter] in the .*
2a130 2a 20 57 48 45 52 45 20 63 6c 61 75 73 65 20 6d  * WHERE clause m
2a140 69 67 68 74 20 69 6e 66 6c 75 65 6e 63 65 20 74  ight influence t
2a150 68 65 20 63 68 6f 69 63 65 20 6f 66 20 71 75 65  he choice of que
2a160 72 79 20 70 6c 61 6e 20 66 6f 72 20 61 20 73 74  ry plan for a st
2a170 61 74 65 6d 65 6e 74 2c 0a 2a 2a 20 74 68 65 6e  atement,.** then
2a180 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 77   the statement w
2a190 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61 74 69 63  ill be automatic
2a1a0 61 6c 6c 79 20 72 65 63 6f 6d 70 69 6c 65 64 2c  ally recompiled,
2a1b0 20 61 73 20 69 66 20 74 68 65 72 65 20 68 61 64   as if there had
2a1c0 20 62 65 65 6e 20 0a 2a 2a 20 61 20 73 63 68 65   been .** a sche
2a1d0 6d 61 20 63 68 61 6e 67 65 2c 20 6f 6e 20 74 68  ma change, on th
2a1e0 65 20 66 69 72 73 74 20 20 5b 73 71 6c 69 74 65  e first  [sqlite
2a1f0 33 5f 73 74 65 70 28 29 5d 20 63 61 6c 6c 20 66  3_step()] call f
2a200 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79 20 63 68 61  ollowing any cha
2a210 6e 67 65 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73  nge.** to the [s
2a220 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
2a230 20 7c 20 62 69 6e 64 69 6e 67 73 5d 20 6f 66 20   | bindings] of 
2a240 74 68 61 74 20 5b 70 61 72 61 6d 65 74 65 72 5d  that [parameter]
2a250 2e 20 0a 2a 2a 20 5e 54 68 65 20 73 70 65 63 69  . .** ^The speci
2a260 66 69 63 20 76 61 6c 75 65 20 6f 66 20 57 48 45  fic value of WHE
2a270 52 45 2d 63 6c 61 75 73 65 20 5b 70 61 72 61 6d  RE-clause [param
2a280 65 74 65 72 5d 20 6d 69 67 68 74 20 69 6e 66 6c  eter] might infl
2a290 75 65 6e 63 65 20 74 68 65 20 0a 2a 2a 20 63 68  uence the .** ch
2a2a0 6f 69 63 65 20 6f 66 20 71 75 65 72 79 20 70 6c  oice of query pl
2a2b0 61 6e 20 69 66 20 74 68 65 20 70 61 72 61 6d 65  an if the parame
2a2c0 74 65 72 20 69 73 20 74 68 65 20 6c 65 66 74 2d  ter is the left-
2a2d0 68 61 6e 64 20 73 69 64 65 20 6f 66 20 61 20 5b  hand side of a [
2a2e0 4c 49 4b 45 5d 0a 2a 2a 20 6f 72 20 5b 47 4c 4f  LIKE].** or [GLO
2a2f0 42 5d 20 6f 70 65 72 61 74 6f 72 20 6f 72 20 69  B] operator or i
2a300 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20  f the parameter 
2a310 69 73 20 63 6f 6d 70 61 72 65 64 20 74 6f 20 61  is compared to a
2a320 6e 20 69 6e 64 65 78 65 64 20 63 6f 6c 75 6d 6e  n indexed column
2a330 0a 2a 2a 20 61 6e 64 20 74 68 65 20 5b 53 51 4c  .** and the [SQL
2a340 49 54 45 5f 45 4e 41 42 4c 45 5f 53 54 41 54 33  ITE_ENABLE_STAT3
2a350 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
2a360 70 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64  ption is enabled
2a370 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f  ..** </li>.** </
2a380 6f 6c 3e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  ol>.*/.int sqlit
2a390 65 33 5f 70 72 65 70 61 72 65 28 0a 20 20 73 71  e3_prepare(.  sq
2a3a0 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20  lite3 *db,      
2a3b0 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73        /* Databas
2a3c0 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f  e handle */.  co
2a3d0 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20  nst char *zSql, 
2a3e0 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61        /* SQL sta
2a3f0 74 65 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e  tement, UTF-8 en
2a400 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e  coded */.  int n
2a410 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 20  Byte,           
2a420 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65     /* Maximum le
2a430 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20  ngth of zSql in 
2a440 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69  bytes. */.  sqli
2a450 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d  te3_stmt **ppStm
2a460 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74  t,  /* OUT: Stat
2a470 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a  ement handle */.
2a480 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70    const char **p
2a490 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54  zTail     /* OUT
2a4a0 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75  : Pointer to unu
2a4b0 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a  sed portion of z
2a4c0 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71  Sql */.);.int sq
2a4d0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
2a4e0 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
2a4f0 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44              /* D
2a500 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a  atabase handle *
2a510 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  /.  const char *
2a520 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53  zSql,       /* S
2a530 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54  QL statement, UT
2a540 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20  F-8 encoded */. 
2a550 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20   int nByte,     
2a560 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69           /* Maxi
2a570 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53  mum length of zS
2a580 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a  ql in bytes. */.
2a590 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a    sqlite3_stmt *
2a5a0 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54  *ppStmt,  /* OUT
2a5b0 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64  : Statement hand
2a5c0 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68  le */.  const ch
2a5d0 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20  ar **pzTail     
2a5e0 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20  /* OUT: Pointer 
2a5f0 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f  to unused portio
2a600 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a  n of zSql */.);.
2a610 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70  int sqlite3_prep
2a620 61 72 65 31 36 28 0a 20 20 73 71 6c 69 74 65 33  are16(.  sqlite3
2a630 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20   *db,           
2a640 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e   /* Database han
2a650 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76  dle */.  const v
2a660 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20  oid *zSql,      
2a670 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   /* SQL statemen
2a680 74 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65  t, UTF-16 encode
2a690 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65  d */.  int nByte
2a6a0 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f  ,              /
2a6b0 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68  * Maximum length
2a6c0 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65   of zSql in byte
2a6d0 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f  s. */.  sqlite3_
2a6e0 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20  stmt **ppStmt,  
2a6f0 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e  /* OUT: Statemen
2a700 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f  t handle */.  co
2a710 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69  nst void **pzTai
2a720 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f  l     /* OUT: Po
2a730 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20  inter to unused 
2a740 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20  portion of zSql 
2a750 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  */.);.int sqlite
2a760 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 0a  3_prepare16_v2(.
2a770 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20    sqlite3 *db,  
2a780 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74            /* Dat
2a790 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a  abase handle */.
2a7a0 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53    const void *zS
2a7b0 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c  ql,       /* SQL
2a7c0 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d   statement, UTF-
2a7d0 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20  16 encoded */.  
2a7e0 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20  int nByte,      
2a7f0 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d          /* Maxim
2a800 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71  um length of zSq
2a810 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20  l in bytes. */. 
2a820 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a   sqlite3_stmt **
2a830 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a  ppStmt,  /* OUT:
2a840 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c   Statement handl
2a850 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69  e */.  const voi
2a860 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f  d **pzTail     /
2a870 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74  * OUT: Pointer t
2a880 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e  o unused portion
2a890 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 0a   of zSql */.);..
2a8a0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
2a8b0 52 65 74 72 69 65 76 69 6e 67 20 53 74 61 74 65  Retrieving State
2a8c0 6d 65 6e 74 20 53 51 4c 0a 2a 2a 20 4d 45 54 48  ment SQL.** METH
2a8d0 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  OD: sqlite3_stmt
2a8e0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
2a8f0 74 65 33 5f 73 71 6c 28 50 29 20 69 6e 74 65 72  te3_sql(P) inter
2a900 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 70  face returns a p
2a910 6f 69 6e 74 65 72 20 74 6f 20 61 20 63 6f 70 79  ointer to a copy
2a920 20 6f 66 20 74 68 65 20 55 54 46 2d 38 0a 2a 2a   of the UTF-8.**
2a930 20 53 51 4c 20 74 65 78 74 20 75 73 65 64 20 74   SQL text used t
2a940 6f 20 63 72 65 61 74 65 20 5b 70 72 65 70 61 72  o create [prepar
2a950 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 50 20  ed statement] P 
2a960 69 66 20 50 20 77 61 73 0a 2a 2a 20 63 72 65 61  if P was.** crea
2a970 74 65 64 20 62 79 20 65 69 74 68 65 72 20 5b 73  ted by either [s
2a980 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
2a990 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  2()] or [sqlite3
2a9a0 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d  _prepare16_v2()]
2a9b0 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  ..** ^The sqlite
2a9c0 33 5f 65 78 70 61 6e 64 65 64 5f 73 71 6c 28 50  3_expanded_sql(P
2a9d0 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ) interface retu
2a9e0 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
2a9f0 20 61 20 55 54 46 2d 38 0a 2a 2a 20 73 74 72 69   a UTF-8.** stri
2aa00 6e 67 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68  ng containing th
2aa10 65 20 53 51 4c 20 74 65 78 74 20 6f 66 20 70 72  e SQL text of pr
2aa20 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2aa30 20 50 20 77 69 74 68 0a 2a 2a 20 5b 62 6f 75 6e   P with.** [boun
2aa40 64 20 70 61 72 61 6d 65 74 65 72 73 5d 20 65 78  d parameters] ex
2aa50 70 61 6e 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28  panded..**.** ^(
2aa60 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 69 66 20  For example, if 
2aa70 61 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  a prepared state
2aa80 6d 65 6e 74 20 69 73 20 63 72 65 61 74 65 64 20  ment is created 
2aa90 75 73 69 6e 67 20 74 68 65 20 53 51 4c 0a 2a 2a  using the SQL.**
2aaa0 20 74 65 78 74 20 22 53 45 4c 45 43 54 20 24 61   text "SELECT $a
2aab0 62 63 2c 3a 78 79 7a 22 20 61 6e 64 20 69 66 20  bc,:xyz" and if 
2aac0 70 61 72 61 6d 65 74 65 72 20 24 61 62 63 20 69  parameter $abc i
2aad0 73 20 62 6f 75 6e 64 20 74 6f 20 69 6e 74 65 67  s bound to integ
2aae0 65 72 20 32 33 34 35 0a 2a 2a 20 61 6e 64 20 70  er 2345.** and p
2aaf0 61 72 61 6d 65 74 65 72 20 3a 78 79 7a 20 69 73  arameter :xyz is
2ab00 20 75 6e 62 6f 75 6e 64 2c 20 74 68 65 6e 20 73   unbound, then s
2ab10 71 6c 69 74 65 33 5f 73 71 6c 28 29 20 77 69 6c  qlite3_sql() wil
2ab20 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 74 68 65 20  l return.** the 
2ab30 6f 72 69 67 69 6e 61 6c 20 73 74 72 69 6e 67 2c  original string,
2ab40 20 22 53 45 4c 45 43 54 20 24 61 62 63 2c 3a 78   "SELECT $abc,:x
2ab50 79 7a 22 20 62 75 74 20 73 71 6c 69 74 65 33 5f  yz" but sqlite3_
2ab60 65 78 70 61 6e 64 65 64 5f 73 71 6c 28 29 0a 2a  expanded_sql().*
2ab70 2a 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 22 53  * will return "S
2ab80 45 4c 45 43 54 20 32 33 34 35 2c 4e 55 4c 4c 22  ELECT 2345,NULL"
2ab90 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  .)^.**.** ^The s
2aba0 71 6c 69 74 65 33 5f 65 78 70 61 6e 64 65 64 5f  qlite3_expanded_
2abb0 73 71 6c 28 29 20 69 6e 74 65 72 66 61 63 65 20  sql() interface 
2abc0 72 65 74 75 72 6e 73 20 4e 55 4c 4c 20 69 66 20  returns NULL if 
2abd0 69 6e 73 75 66 66 69 63 69 65 6e 74 20 6d 65 6d  insufficient mem
2abe0 6f 72 79 0a 2a 2a 20 69 73 20 61 76 61 69 6c 61  ory.** is availa
2abf0 62 6c 65 20 74 6f 20 68 6f 6c 64 20 74 68 65 20  ble to hold the 
2ac00 72 65 73 75 6c 74 2c 20 6f 72 20 69 66 20 74 68  result, or if th
2ac10 65 20 72 65 73 75 6c 74 20 77 6f 75 6c 64 20 65  e result would e
2ac20 78 63 65 65 64 20 74 68 65 0a 2a 2a 20 74 68 65  xceed the.** the
2ac30 20 6d 61 78 69 6d 75 6d 20 73 74 72 69 6e 67 20   maximum string 
2ac40 6c 65 6e 67 74 68 20 64 65 74 65 72 6d 69 6e 65  length determine
2ac50 64 20 62 79 20 74 68 65 20 5b 53 51 4c 49 54 45  d by the [SQLITE
2ac60 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 5d 2e 0a  _LIMIT_LENGTH]..
2ac70 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49  **.** ^The [SQLI
2ac80 54 45 5f 54 52 41 43 45 5f 53 49 5a 45 5f 4c 49  TE_TRACE_SIZE_LI
2ac90 4d 49 54 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  MIT] compile-tim
2aca0 65 20 6f 70 74 69 6f 6e 20 6c 69 6d 69 74 73 20  e option limits 
2acb0 74 68 65 20 73 69 7a 65 20 6f 66 0a 2a 2a 20 62  the size of.** b
2acc0 6f 75 6e 64 20 70 61 72 61 6d 65 74 65 72 20 65  ound parameter e
2acd0 78 70 61 6e 73 69 6f 6e 73 2e 20 20 5e 54 68 65  xpansions.  ^The
2ace0 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 54 52   [SQLITE_OMIT_TR
2acf0 41 43 45 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  ACE] compile-tim
2ad00 65 0a 2a 2a 20 6f 70 74 69 6f 6e 20 63 61 75 73  e.** option caus
2ad10 65 73 20 73 71 6c 69 74 65 33 5f 65 78 70 61 6e  es sqlite3_expan
2ad20 64 65 64 5f 73 71 6c 28 29 20 74 6f 20 61 6c 77  ded_sql() to alw
2ad30 61 79 73 20 72 65 74 75 72 6e 20 4e 55 4c 4c 2e  ays return NULL.
2ad40 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 74 72 69  .**.** ^The stri
2ad50 6e 67 20 72 65 74 75 72 6e 65 64 20 62 79 20 73  ng returned by s
2ad60 71 6c 69 74 65 33 5f 73 71 6c 28 50 29 20 69 73  qlite3_sql(P) is
2ad70 20 6d 61 6e 61 67 65 64 20 62 79 20 53 51 4c 69   managed by SQLi
2ad80 74 65 20 61 6e 64 20 69 73 0a 2a 2a 20 61 75 74  te and is.** aut
2ad90 6f 6d 61 74 69 63 61 6c 6c 79 20 66 72 65 65 64  omatically freed
2ada0 20 77 68 65 6e 20 74 68 65 20 70 72 65 70 61 72   when the prepar
2adb0 65 64 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  ed statement is 
2adc0 66 69 6e 61 6c 69 7a 65 64 2e 0a 2a 2a 20 5e 54  finalized..** ^T
2add0 68 65 20 73 74 72 69 6e 67 20 72 65 74 75 72 6e  he string return
2ade0 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 65 78  ed by sqlite3_ex
2adf0 70 61 6e 64 65 64 5f 73 71 6c 28 50 29 2c 20 6f  panded_sql(P), o
2ae00 6e 20 74 68 65 20 6f 74 68 65 72 20 68 61 6e 64  n the other hand
2ae10 2c 0a 2a 2a 20 69 73 20 6f 62 74 61 69 6e 65 64  ,.** is obtained
2ae20 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d   from [sqlite3_m
2ae30 61 6c 6c 6f 63 28 29 5d 20 61 6e 64 20 6d 75 73  alloc()] and mus
2ae40 74 20 62 65 20 66 72 65 65 20 62 79 20 74 68 65  t be free by the
2ae50 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20   application.** 
2ae60 62 79 20 70 61 73 73 69 6e 67 20 69 74 20 74 6f  by passing it to
2ae70 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
2ae80 5d 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72  ]..*/.const char
2ae90 20 2a 73 71 6c 69 74 65 33 5f 73 71 6c 28 73 71   *sqlite3_sql(sq
2aea0 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d  lite3_stmt *pStm
2aeb0 74 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74 65  t);.char *sqlite
2aec0 33 5f 65 78 70 61 6e 64 65 64 5f 73 71 6c 28 73  3_expanded_sql(s
2aed0 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74  qlite3_stmt *pSt
2aee0 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  mt);../*.** CAPI
2aef0 33 52 45 46 3a 20 44 65 74 65 72 6d 69 6e 65 20  3REF: Determine 
2af00 49 66 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d  If An SQL Statem
2af10 65 6e 74 20 57 72 69 74 65 73 20 54 68 65 20 44  ent Writes The D
2af20 61 74 61 62 61 73 65 0a 2a 2a 20 4d 45 54 48 4f  atabase.** METHO
2af30 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a  D: sqlite3_stmt.
2af40 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
2af50 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79  e3_stmt_readonly
2af60 28 58 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  (X) interface re
2af70 74 75 72 6e 73 20 74 72 75 65 20 28 6e 6f 6e 2d  turns true (non-
2af80 7a 65 72 6f 29 20 69 66 0a 2a 2a 20 61 6e 64 20  zero) if.** and 
2af90 6f 6e 6c 79 20 69 66 20 74 68 65 20 5b 70 72 65  only if the [pre
2afa0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2afb0 20 58 20 6d 61 6b 65 73 20 6e 6f 20 64 69 72 65   X makes no dire
2afc0 63 74 20 63 68 61 6e 67 65 73 20 74 6f 0a 2a 2a  ct changes to.**
2afd0 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20   the content of 
2afe0 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
2aff0 65 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68  e..**.** Note th
2b000 61 74 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d  at [application-
2b010 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63  defined SQL func
2b020 74 69 6f 6e 73 5d 20 6f 72 0a 2a 2a 20 5b 76 69  tions] or.** [vi
2b030 72 74 75 61 6c 20 74 61 62 6c 65 73 5d 20 6d 69  rtual tables] mi
2b040 67 68 74 20 63 68 61 6e 67 65 20 74 68 65 20 64  ght change the d
2b050 61 74 61 62 61 73 65 20 69 6e 64 69 72 65 63 74  atabase indirect
2b060 6c 79 20 61 73 20 61 20 73 69 64 65 20 65 66 66  ly as a side eff
2b070 65 63 74 2e 20 20 0a 2a 2a 20 5e 28 46 6f 72 20  ect.  .** ^(For 
2b080 65 78 61 6d 70 6c 65 2c 20 69 66 20 61 6e 20 61  example, if an a
2b090 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 6e  pplication defin
2b0a0 65 73 20 61 20 66 75 6e 63 74 69 6f 6e 20 22 65  es a function "e
2b0b0 76 61 6c 28 29 22 20 74 68 61 74 20 0a 2a 2a 20  val()" that .** 
2b0c0 63 61 6c 6c 73 20 5b 73 71 6c 69 74 65 33 5f 65  calls [sqlite3_e
2b0d0 78 65 63 28 29 5d 2c 20 74 68 65 6e 20 74 68 65  xec()], then the
2b0e0 20 66 6f 6c 6c 6f 77 69 6e 67 20 53 51 4c 20 73   following SQL s
2b0f0 74 61 74 65 6d 65 6e 74 20 77 6f 75 6c 64 0a 2a  tatement would.*
2b100 2a 20 63 68 61 6e 67 65 20 74 68 65 20 64 61 74  * change the dat
2b110 61 62 61 73 65 20 66 69 6c 65 20 74 68 72 6f 75  abase file throu
2b120 67 68 20 73 69 64 65 2d 65 66 66 65 63 74 73 3a  gh side-effects:
2b130 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f  .**.** <blockquo
2b140 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 53  te><pre>.**    S
2b150 45 4c 45 43 54 20 65 76 61 6c 28 27 44 45 4c 45  ELECT eval('DELE
2b160 54 45 20 46 52 4f 4d 20 74 31 27 29 20 46 52 4f  TE FROM t1') FRO
2b170 4d 20 74 32 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c  M t2;.** </pre><
2b180 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a  /blockquote>.**.
2b190 2a 2a 20 42 75 74 20 62 65 63 61 75 73 65 20 74  ** But because t
2b1a0 68 65 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74  he [SELECT] stat
2b1b0 65 6d 65 6e 74 20 64 6f 65 73 20 6e 6f 74 20 63  ement does not c
2b1c0 68 61 6e 67 65 20 74 68 65 20 64 61 74 61 62 61  hange the databa
2b1d0 73 65 20 66 69 6c 65 0a 2a 2a 20 64 69 72 65 63  se file.** direc
2b1e0 74 6c 79 2c 20 73 71 6c 69 74 65 33 5f 73 74 6d  tly, sqlite3_stm
2b1f0 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20 77 6f 75  t_readonly() wou
2b200 6c 64 20 73 74 69 6c 6c 20 72 65 74 75 72 6e 20  ld still return 
2b210 74 72 75 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54  true.)^.**.** ^T
2b220 72 61 6e 73 61 63 74 69 6f 6e 20 63 6f 6e 74 72  ransaction contr
2b230 6f 6c 20 73 74 61 74 65 6d 65 6e 74 73 20 73 75  ol statements su
2b240 63 68 20 61 73 20 5b 42 45 47 49 4e 5d 2c 20 5b  ch as [BEGIN], [
2b250 43 4f 4d 4d 49 54 5d 2c 20 5b 52 4f 4c 4c 42 41  COMMIT], [ROLLBA
2b260 43 4b 5d 2c 0a 2a 2a 20 5b 53 41 56 45 50 4f 49  CK],.** [SAVEPOI
2b270 4e 54 5d 2c 20 61 6e 64 20 5b 52 45 4c 45 41 53  NT], and [RELEAS
2b280 45 5d 20 63 61 75 73 65 20 73 71 6c 69 74 65 33  E] cause sqlite3
2b290 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29  _stmt_readonly()
2b2a0 20 74 6f 20 72 65 74 75 72 6e 20 74 72 75 65 2c   to return true,
2b2b0 0a 2a 2a 20 73 69 6e 63 65 20 74 68 65 20 73 74  .** since the st
2b2c0 61 74 65 6d 65 6e 74 73 20 74 68 65 6d 73 65 6c  atements themsel
2b2d0 76 65 73 20 64 6f 20 6e 6f 74 20 61 63 74 75 61  ves do not actua
2b2e0 6c 6c 79 20 6d 6f 64 69 66 79 20 74 68 65 20 64  lly modify the d
2b2f0 61 74 61 62 61 73 65 20 62 75 74 0a 2a 2a 20 72  atabase but.** r
2b300 61 74 68 65 72 20 74 68 65 79 20 63 6f 6e 74 72  ather they contr
2b310 6f 6c 20 74 68 65 20 74 69 6d 69 6e 67 20 6f 66  ol the timing of
2b320 20 77 68 65 6e 20 6f 74 68 65 72 20 73 74 61 74   when other stat
2b330 65 6d 65 6e 74 73 20 6d 6f 64 69 66 79 20 74 68  ements modify th
2b340 65 20 0a 2a 2a 20 64 61 74 61 62 61 73 65 2e 20  e .** database. 
2b350 20 5e 54 68 65 20 5b 41 54 54 41 43 48 5d 20 61   ^The [ATTACH] a
2b360 6e 64 20 5b 44 45 54 41 43 48 5d 20 73 74 61 74  nd [DETACH] stat
2b370 65 6d 65 6e 74 73 20 61 6c 73 6f 20 63 61 75 73  ements also caus
2b380 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 6d  e.** sqlite3_stm
2b390 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20 74 6f 20  t_readonly() to 
2b3a0 72 65 74 75 72 6e 20 74 72 75 65 20 73 69 6e 63  return true sinc
2b3b0 65 2c 20 77 68 69 6c 65 20 74 68 6f 73 65 20 73  e, while those s
2b3c0 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 63 68 61  tatements.** cha
2b3d0 6e 67 65 20 74 68 65 20 63 6f 6e 66 69 67 75 72  nge the configur
2b3e0 61 74 69 6f 6e 20 6f 66 20 61 20 64 61 74 61 62  ation of a datab
2b3f0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 20  ase connection, 
2b400 74 68 65 79 20 64 6f 20 6e 6f 74 20 6d 61 6b 65  they do not make
2b410 20 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f 20   .** changes to 
2b420 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74  the content of t
2b430 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
2b440 73 20 6f 6e 20 64 69 73 6b 2e 0a 2a 2f 0a 69 6e  s on disk..*/.in
2b450 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72  t sqlite3_stmt_r
2b460 65 61 64 6f 6e 6c 79 28 73 71 6c 69 74 65 33 5f  eadonly(sqlite3_
2b470 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f  stmt *pStmt);../
2b480 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
2b490 65 74 65 72 6d 69 6e 65 20 49 66 20 41 20 50 72  etermine If A Pr
2b4a0 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74  epared Statement
2b4b0 20 48 61 73 20 42 65 65 6e 20 52 65 73 65 74 0a   Has Been Reset.
2b4c0 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
2b4d0 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54  e3_stmt.**.** ^T
2b4e0 68 65 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f  he sqlite3_stmt_
2b4f0 62 75 73 79 28 53 29 20 69 6e 74 65 72 66 61 63  busy(S) interfac
2b500 65 20 72 65 74 75 72 6e 73 20 74 72 75 65 20 28  e returns true (
2b510 6e 6f 6e 2d 7a 65 72 6f 29 20 69 66 20 74 68 65  non-zero) if the
2b520 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74  .** [prepared st
2b530 61 74 65 6d 65 6e 74 5d 20 53 20 68 61 73 20 62  atement] S has b
2b540 65 65 6e 20 73 74 65 70 70 65 64 20 61 74 20 6c  een stepped at l
2b550 65 61 73 74 20 6f 6e 63 65 20 75 73 69 6e 67 20  east once using 
2b560 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  .** [sqlite3_ste
2b570 70 28 53 29 5d 20 62 75 74 20 68 61 73 20 6e 65  p(S)] but has ne
2b580 69 74 68 65 72 20 72 75 6e 20 74 6f 20 63 6f 6d  ither run to com
2b590 70 6c 65 74 69 6f 6e 20 28 72 65 74 75 72 6e 65  pletion (returne
2b5a0 64 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 4f 4e  d.** [SQLITE_DON
2b5b0 45 5d 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  E] from [sqlite3
2b5c0 5f 73 74 65 70 28 53 29 5d 29 20 6e 6f 72 0a 2a  _step(S)]) nor.*
2b5d0 2a 20 62 65 65 6e 20 72 65 73 65 74 20 75 73 69  * been reset usi
2b5e0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  ng [sqlite3_rese
2b5f0 74 28 53 29 5d 2e 20 20 5e 54 68 65 20 73 71 6c  t(S)].  ^The sql
2b600 69 74 65 33 5f 73 74 6d 74 5f 62 75 73 79 28 53  ite3_stmt_busy(S
2b610 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 72  ).** interface r
2b620 65 74 75 72 6e 73 20 66 61 6c 73 65 20 69 66 20  eturns false if 
2b630 53 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  S is a NULL poin
2b640 74 65 72 2e 20 20 49 66 20 53 20 69 73 20 6e 6f  ter.  If S is no
2b650 74 20 61 20 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69  t a .** NULL poi
2b660 6e 74 65 72 20 61 6e 64 20 69 73 20 6e 6f 74 20  nter and is not 
2b670 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 76  a pointer to a v
2b680 61 6c 69 64 20 5b 70 72 65 70 61 72 65 64 20 73  alid [prepared s
2b690 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 6a  tatement].** obj
2b6a0 65 63 74 2c 20 74 68 65 6e 20 74 68 65 20 62 65  ect, then the be
2b6b0 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69  havior is undefi
2b6c0 6e 65 64 20 61 6e 64 20 70 72 6f 62 61 62 6c 79  ned and probably
2b6d0 20 75 6e 64 65 73 69 72 61 62 6c 65 2e 0a 2a 2a   undesirable..**
2b6e0 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61  .** This interfa
2b6f0 63 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 69  ce can be used i
2b700 6e 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 5b 73  n combination [s
2b710 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73 74 6d 74  qlite3_next_stmt
2b720 28 29 5d 0a 2a 2a 20 74 6f 20 6c 6f 63 61 74 65  ()].** to locate
2b730 20 61 6c 6c 20 70 72 65 70 61 72 65 64 20 73 74   all prepared st
2b740 61 74 65 6d 65 6e 74 73 20 61 73 73 6f 63 69 61  atements associa
2b750 74 65 64 20 77 69 74 68 20 61 20 64 61 74 61 62  ted with a datab
2b760 61 73 65 20 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69  ase .** connecti
2b770 6f 6e 20 74 68 61 74 20 61 72 65 20 69 6e 20 6e  on that are in n
2b780 65 65 64 20 6f 66 20 62 65 69 6e 67 20 72 65 73  eed of being res
2b790 65 74 2e 20 20 54 68 69 73 20 63 61 6e 20 62 65  et.  This can be
2b7a0 20 75 73 65 64 2c 0a 2a 2a 20 66 6f 72 20 65 78   used,.** for ex
2b7b0 61 6d 70 6c 65 2c 20 69 6e 20 64 69 61 67 6e 6f  ample, in diagno
2b7c0 73 74 69 63 20 72 6f 75 74 69 6e 65 73 20 74 6f  stic routines to
2b7d0 20 73 65 61 72 63 68 20 66 6f 72 20 70 72 65 70   search for prep
2b7e0 61 72 65 64 20 0a 2a 2a 20 73 74 61 74 65 6d 65  ared .** stateme
2b7f0 6e 74 73 20 74 68 61 74 20 61 72 65 20 68 6f 6c  nts that are hol
2b800 64 69 6e 67 20 61 20 74 72 61 6e 73 61 63 74 69  ding a transacti
2b810 6f 6e 20 6f 70 65 6e 2e 0a 2a 2f 0a 69 6e 74 20  on open..*/.int 
2b820 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 62 75 73  sqlite3_stmt_bus
2b830 79 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29  y(sqlite3_stmt*)
2b840 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2b850 46 3a 20 44 79 6e 61 6d 69 63 61 6c 6c 79 20 54  F: Dynamically T
2b860 79 70 65 64 20 56 61 6c 75 65 20 4f 62 6a 65 63  yped Value Objec
2b870 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  t.** KEYWORDS: {
2b880 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
2b890 33 5f 76 61 6c 75 65 7d 20 7b 75 6e 70 72 6f 74  3_value} {unprot
2b8a0 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
2b8b0 6c 75 65 7d 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74  lue}.**.** SQLit
2b8c0 65 20 75 73 65 73 20 74 68 65 20 73 71 6c 69 74  e uses the sqlit
2b8d0 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20  e3_value object 
2b8e0 74 6f 20 72 65 70 72 65 73 65 6e 74 20 61 6c 6c  to represent all
2b8f0 20 76 61 6c 75 65 73 0a 2a 2a 20 74 68 61 74 20   values.** that 
2b900 63 61 6e 20 62 65 20 73 74 6f 72 65 64 20 69 6e  can be stored in
2b910 20 61 20 64 61 74 61 62 61 73 65 20 74 61 62 6c   a database tabl
2b920 65 2e 20 53 51 4c 69 74 65 20 75 73 65 73 20 64  e. SQLite uses d
2b930 79 6e 61 6d 69 63 20 74 79 70 69 6e 67 0a 2a 2a  ynamic typing.**
2b940 20 66 6f 72 20 74 68 65 20 76 61 6c 75 65 73 20   for the values 
2b950 69 74 20 73 74 6f 72 65 73 2e 20 20 5e 56 61 6c  it stores.  ^Val
2b960 75 65 73 20 73 74 6f 72 65 64 20 69 6e 20 73 71  ues stored in sq
2b970 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
2b980 63 74 73 0a 2a 2a 20 63 61 6e 20 62 65 20 69 6e  cts.** can be in
2b990 74 65 67 65 72 73 2c 20 66 6c 6f 61 74 69 6e 67  tegers, floating
2b9a0 20 70 6f 69 6e 74 20 76 61 6c 75 65 73 2c 20 73   point values, s
2b9b0 74 72 69 6e 67 73 2c 20 42 4c 4f 42 73 2c 20 6f  trings, BLOBs, o
2b9c0 72 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 41 6e  r NULL..**.** An
2b9d0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
2b9e0 62 6a 65 63 74 20 6d 61 79 20 62 65 20 65 69 74  bject may be eit
2b9f0 68 65 72 20 22 70 72 6f 74 65 63 74 65 64 22 20  her "protected" 
2ba00 6f 72 20 22 75 6e 70 72 6f 74 65 63 74 65 64 22  or "unprotected"
2ba10 2e 0a 2a 2a 20 53 6f 6d 65 20 69 6e 74 65 72 66  ..** Some interf
2ba20 61 63 65 73 20 72 65 71 75 69 72 65 20 61 20 70  aces require a p
2ba30 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
2ba40 5f 76 61 6c 75 65 2e 20 20 4f 74 68 65 72 20 69  _value.  Other i
2ba50 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 77 69 6c  nterfaces.** wil
2ba60 6c 20 61 63 63 65 70 74 20 65 69 74 68 65 72 20  l accept either 
2ba70 61 20 70 72 6f 74 65 63 74 65 64 20 6f 72 20 61  a protected or a
2ba80 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71  n unprotected sq
2ba90 6c 69 74 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a 20  lite3_value..** 
2baa0 45 76 65 72 79 20 69 6e 74 65 72 66 61 63 65 20  Every interface 
2bab0 74 68 61 74 20 61 63 63 65 70 74 73 20 73 71 6c  that accepts sql
2bac0 69 74 65 33 5f 76 61 6c 75 65 20 61 72 67 75 6d  ite3_value argum
2bad0 65 6e 74 73 20 73 70 65 63 69 66 69 65 73 0a 2a  ents specifies.*
2bae0 2a 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  * whether or not
2baf0 20 69 74 20 72 65 71 75 69 72 65 73 20 61 20 70   it requires a p
2bb00 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
2bb10 5f 76 61 6c 75 65 2e 20 20 54 68 65 0a 2a 2a 20  _value.  The.** 
2bb20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 64  [sqlite3_value_d
2bb30 75 70 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20  up()] interface 
2bb40 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 63  can be used to c
2bb50 6f 6e 73 74 72 75 63 74 20 61 20 6e 65 77 20 0a  onstruct a new .
2bb60 2a 2a 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c  ** protected sql
2bb70 69 74 65 33 5f 76 61 6c 75 65 20 66 72 6f 6d 20  ite3_value from 
2bb80 61 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 20 73  an unprotected s
2bb90 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a  qlite3_value..**
2bba0 0a 2a 2a 20 54 68 65 20 74 65 72 6d 73 20 22 70  .** The terms "p
2bbb0 72 6f 74 65 63 74 65 64 22 20 61 6e 64 20 22 75  rotected" and "u
2bbc0 6e 70 72 6f 74 65 63 74 65 64 22 20 72 65 66 65  nprotected" refe
2bbd0 72 20 74 6f 20 77 68 65 74 68 65 72 20 6f 72 20  r to whether or 
2bbe0 6e 6f 74 0a 2a 2a 20 61 20 6d 75 74 65 78 20 69  not.** a mutex i
2bbf0 73 20 68 65 6c 64 2e 20 20 41 6e 20 69 6e 74 65  s held.  An inte
2bc00 72 6e 61 6c 20 6d 75 74 65 78 20 69 73 20 68 65  rnal mutex is he
2bc10 6c 64 20 66 6f 72 20 61 20 70 72 6f 74 65 63 74  ld for a protect
2bc20 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61  ed.** sqlite3_va
2bc30 6c 75 65 20 6f 62 6a 65 63 74 20 62 75 74 20 6e  lue object but n
2bc40 6f 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64 20  o mutex is held 
2bc50 66 6f 72 20 61 6e 20 75 6e 70 72 6f 74 65 63 74  for an unprotect
2bc60 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61  ed.** sqlite3_va
2bc70 6c 75 65 20 6f 62 6a 65 63 74 2e 20 20 49 66 20  lue object.  If 
2bc80 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  SQLite is compil
2bc90 65 64 20 74 6f 20 62 65 20 73 69 6e 67 6c 65 2d  ed to be single-
2bca0 74 68 72 65 61 64 65 64 0a 2a 2a 20 28 77 69 74  threaded.** (wit
2bcb0 68 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44  h [SQLITE_THREAD
2bcc0 53 41 46 45 3d 30 5d 20 61 6e 64 20 77 69 74 68  SAFE=0] and with
2bcd0 20 5b 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64   [sqlite3_thread
2bce0 73 61 66 65 28 29 5d 20 72 65 74 75 72 6e 69 6e  safe()] returnin
2bcf0 67 20 30 29 0a 2a 2a 20 6f 72 20 69 66 20 53 51  g 0).** or if SQ
2bd00 4c 69 74 65 20 69 73 20 72 75 6e 20 69 6e 20 6f  Lite is run in o
2bd10 6e 65 20 6f 66 20 72 65 64 75 63 65 64 20 6d 75  ne of reduced mu
2bd20 74 65 78 20 6d 6f 64 65 73 20 0a 2a 2a 20 5b 53  tex modes .** [S
2bd30 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e  QLITE_CONFIG_SIN
2bd40 47 4c 45 54 48 52 45 41 44 5d 20 6f 72 20 5b 53  GLETHREAD] or [S
2bd50 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c  QLITE_CONFIG_MUL
2bd60 54 49 54 48 52 45 41 44 5d 0a 2a 2a 20 74 68 65  TITHREAD].** the
2bd70 6e 20 74 68 65 72 65 20 69 73 20 6e 6f 20 64 69  n there is no di
2bd80 73 74 69 6e 63 74 69 6f 6e 20 62 65 74 77 65 65  stinction betwee
2bd90 6e 20 70 72 6f 74 65 63 74 65 64 20 61 6e 64 20  n protected and 
2bda0 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73  unprotected.** s
2bdb0 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
2bdc0 65 63 74 73 20 61 6e 64 20 74 68 65 79 20 63 61  ects and they ca
2bdd0 6e 20 62 65 20 75 73 65 64 20 69 6e 74 65 72 63  n be used interc
2bde0 68 61 6e 67 65 61 62 6c 79 2e 20 20 48 6f 77 65  hangeably.  Howe
2bdf0 76 65 72 2c 0a 2a 2a 20 66 6f 72 20 6d 61 78 69  ver,.** for maxi
2be00 6d 75 6d 20 63 6f 64 65 20 70 6f 72 74 61 62 69  mum code portabi
2be10 6c 69 74 79 20 69 74 20 69 73 20 72 65 63 6f 6d  lity it is recom
2be20 6d 65 6e 64 65 64 20 74 68 61 74 20 61 70 70 6c  mended that appl
2be30 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 74 69 6c  ications.** stil
2be40 6c 20 6d 61 6b 65 20 74 68 65 20 64 69 73 74 69  l make the disti
2be50 6e 63 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 70  nction between p
2be60 72 6f 74 65 63 74 65 64 20 61 6e 64 20 75 6e 70  rotected and unp
2be70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69  rotected.** sqli
2be80 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
2be90 73 20 65 76 65 6e 20 77 68 65 6e 20 6e 6f 74 20  s even when not 
2bea0 73 74 72 69 63 74 6c 79 20 72 65 71 75 69 72 65  strictly require
2beb0 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  d..**.** ^The sq
2bec0 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
2bed0 63 74 73 20 74 68 61 74 20 61 72 65 20 70 61 73  cts that are pas
2bee0 73 65 64 20 61 73 20 70 61 72 61 6d 65 74 65 72  sed as parameter
2bef0 73 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 69 6d  s into the.** im
2bf00 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
2bf10 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66  [application-def
2bf20 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f  ined SQL functio
2bf30 6e 73 5d 20 61 72 65 20 70 72 6f 74 65 63 74 65  ns] are protecte
2bf40 64 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  d..** ^The sqlit
2bf50 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20  e3_value object 
2bf60 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b  returned by.** [
2bf70 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76  sqlite3_column_v
2bf80 61 6c 75 65 28 29 5d 20 69 73 20 75 6e 70 72 6f  alue()] is unpro
2bf90 74 65 63 74 65 64 2e 0a 2a 2a 20 55 6e 70 72 6f  tected..** Unpro
2bfa0 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
2bfb0 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 6d 61 79  alue objects may
2bfc0 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 20 77 69   only be used wi
2bfd0 74 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72  th.** [sqlite3_r
2bfe0 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 5d 20 61  esult_value()] a
2bff0 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  nd [sqlite3_bind
2c000 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20 54 68  _value()]..** Th
2c010 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  e [sqlite3_value
2c020 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f  _blob | sqlite3_
2c030 76 61 6c 75 65 5f 74 79 70 65 28 29 5d 20 66 61  value_type()] fa
2c040 6d 69 6c 79 20 6f 66 0a 2a 2a 20 69 6e 74 65 72  mily of.** inter
2c050 66 61 63 65 73 20 72 65 71 75 69 72 65 20 70 72  faces require pr
2c060 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
2c070 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 2e 0a 2a  value objects..*
2c080 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74  /.typedef struct
2c090 20 4d 65 6d 20 73 71 6c 69 74 65 33 5f 76 61 6c   Mem sqlite3_val
2c0a0 75 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  ue;../*.** CAPI3
2c0b0 52 45 46 3a 20 53 51 4c 20 46 75 6e 63 74 69 6f  REF: SQL Functio
2c0c0 6e 20 43 6f 6e 74 65 78 74 20 4f 62 6a 65 63 74  n Context Object
2c0d0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 6e 74 65  .**.** The conte
2c0e0 78 74 20 69 6e 20 77 68 69 63 68 20 61 6e 20 53  xt in which an S
2c0f0 51 4c 20 66 75 6e 63 74 69 6f 6e 20 65 78 65 63  QL function exec
2c100 75 74 65 73 20 69 73 20 73 74 6f 72 65 64 20 69  utes is stored i
2c110 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  n an.** sqlite3_
2c120 63 6f 6e 74 65 78 74 20 6f 62 6a 65 63 74 2e 20  context object. 
2c130 20 5e 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 61   ^A pointer to a
2c140 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  n sqlite3_contex
2c150 74 20 6f 62 6a 65 63 74 0a 2a 2a 20 69 73 20 61  t object.** is a
2c160 6c 77 61 79 73 20 66 69 72 73 74 20 70 61 72 61  lways first para
2c170 6d 65 74 65 72 20 74 6f 20 5b 61 70 70 6c 69 63  meter to [applic
2c180 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51  ation-defined SQ
2c190 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a  L functions]..**
2c1a0 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   The application
2c1b0 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e  -defined SQL fun
2c1c0 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61  ction implementa
2c1d0 74 69 6f 6e 20 77 69 6c 6c 20 70 61 73 73 20 74  tion will pass t
2c1e0 68 69 73 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74  his.** pointer t
2c1f0 68 72 6f 75 67 68 20 69 6e 74 6f 20 63 61 6c 6c  hrough into call
2c200 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65  s to [sqlite3_re
2c210 73 75 6c 74 5f 69 6e 74 20 7c 20 73 71 6c 69 74  sult_int | sqlit
2c220 65 33 5f 72 65 73 75 6c 74 28 29 5d 2c 0a 2a 2a  e3_result()],.**
2c230 20 5b 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67   [sqlite3_aggreg
2c240 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 5d 2c 20  ate_context()], 
2c250 5b 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61  [sqlite3_user_da
2c260 74 61 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74  ta()],.** [sqlit
2c270 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61  e3_context_db_ha
2c280 6e 64 6c 65 28 29 5d 2c 20 5b 73 71 6c 69 74 65  ndle()], [sqlite
2c290 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29 5d  3_get_auxdata()]
2c2a0 2c 0a 2a 2a 20 61 6e 64 2f 6f 72 20 5b 73 71 6c  ,.** and/or [sql
2c2b0 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61  ite3_set_auxdata
2c2c0 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  ()]..*/.typedef 
2c2d0 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 63  struct sqlite3_c
2c2e0 6f 6e 74 65 78 74 20 73 71 6c 69 74 65 33 5f 63  ontext sqlite3_c
2c2f0 6f 6e 74 65 78 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ontext;../*.** C
2c300 41 50 49 33 52 45 46 3a 20 42 69 6e 64 69 6e 67  API3REF: Binding
2c310 20 56 61 6c 75 65 73 20 54 6f 20 50 72 65 70 61   Values To Prepa
2c320 72 65 64 20 53 74 61 74 65 6d 65 6e 74 73 0a 2a  red Statements.*
2c330 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 68 6f 73  * KEYWORDS: {hos
2c340 74 20 70 61 72 61 6d 65 74 65 72 7d 20 7b 68 6f  t parameter} {ho
2c350 73 74 20 70 61 72 61 6d 65 74 65 72 73 7d 20 7b  st parameters} {
2c360 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20 6e  host parameter n
2c370 61 6d 65 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  ame}.** KEYWORDS
2c380 3a 20 7b 53 51 4c 20 70 61 72 61 6d 65 74 65 72  : {SQL parameter
2c390 7d 20 7b 53 51 4c 20 70 61 72 61 6d 65 74 65 72  } {SQL parameter
2c3a0 73 7d 20 7b 70 61 72 61 6d 65 74 65 72 20 62 69  s} {parameter bi
2c3b0 6e 64 69 6e 67 7d 0a 2a 2a 20 4d 45 54 48 4f 44  nding}.** METHOD
2c3c0 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a  : sqlite3_stmt.*
2c3d0 2a 0a 2a 2a 20 5e 28 49 6e 20 74 68 65 20 53 51  *.** ^(In the SQ
2c3e0 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74  L statement text
2c3f0 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 74   input to [sqlit
2c400 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
2c410 20 61 6e 64 20 69 74 73 20 76 61 72 69 61 6e 74   and its variant
2c420 73 2c 0a 2a 2a 20 6c 69 74 65 72 61 6c 73 20 6d  s,.** literals m
2c430 61 79 20 62 65 20 72 65 70 6c 61 63 65 64 20 62  ay be replaced b
2c440 79 20 61 20 5b 70 61 72 61 6d 65 74 65 72 5d 20  y a [parameter] 
2c450 74 68 61 74 20 6d 61 74 63 68 65 73 20 6f 6e 65  that matches one
2c460 20 6f 66 20 66 6f 6c 6c 6f 77 69 6e 67 0a 2a 2a   of following.**
2c470 20 74 65 6d 70 6c 61 74 65 73 3a 0a 2a 2a 0a 2a   templates:.**.*
2c480 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20  * <ul>.** <li>  
2c490 3f 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 4e 4e 4e 0a  ?.** <li>  ?NNN.
2c4a0 2a 2a 20 3c 6c 69 3e 20 20 3a 56 56 56 0a 2a 2a  ** <li>  :VVV.**
2c4b0 20 3c 6c 69 3e 20 20 40 56 56 56 0a 2a 2a 20 3c   <li>  @VVV.** <
2c4c0 6c 69 3e 20 20 24 56 56 56 0a 2a 2a 20 3c 2f 75  li>  $VVV.** </u
2c4d0 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68 65 20  l>.**.** In the 
2c4e0 74 65 6d 70 6c 61 74 65 73 20 61 62 6f 76 65 2c  templates above,
2c4f0 20 4e 4e 4e 20 72 65 70 72 65 73 65 6e 74 73 20   NNN represents 
2c500 61 6e 20 69 6e 74 65 67 65 72 20 6c 69 74 65 72  an integer liter
2c510 61 6c 2c 0a 2a 2a 20 61 6e 64 20 56 56 56 20 72  al,.** and VVV r
2c520 65 70 72 65 73 65 6e 74 73 20 61 6e 20 61 6c 70  epresents an alp
2c530 68 61 6e 75 6d 65 72 69 63 20 69 64 65 6e 74 69  hanumeric identi
2c540 66 69 65 72 2e 29 5e 20 20 5e 54 68 65 20 76 61  fier.)^  ^The va
2c550 6c 75 65 73 20 6f 66 20 74 68 65 73 65 0a 2a 2a  lues of these.**
2c560 20 70 61 72 61 6d 65 74 65 72 73 20 28 61 6c 73   parameters (als
2c570 6f 20 63 61 6c 6c 65 64 20 22 68 6f 73 74 20 70  o called "host p
2c580 61 72 61 6d 65 74 65 72 20 6e 61 6d 65 73 22 20  arameter names" 
2c590 6f 72 20 22 53 51 4c 20 70 61 72 61 6d 65 74 65  or "SQL paramete
2c5a0 72 73 22 29 0a 2a 2a 20 63 61 6e 20 62 65 20 73  rs").** can be s
2c5b0 65 74 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c  et using the sql
2c5c0 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f  ite3_bind_*() ro
2c5d0 75 74 69 6e 65 73 20 64 65 66 69 6e 65 64 20 68  utines defined h
2c5e0 65 72 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ere..**.** ^The 
2c5f0 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74  first argument t
2c600 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69  o the sqlite3_bi
2c610 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20  nd_*() routines 
2c620 69 73 20 61 6c 77 61 79 73 0a 2a 2a 20 61 20 70  is always.** a p
2c630 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 73  ointer to the [s
2c640 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62 6a  qlite3_stmt] obj
2c650 65 63 74 20 72 65 74 75 72 6e 65 64 20 66 72 6f  ect returned fro
2c660 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72  m.** [sqlite3_pr
2c670 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 69  epare_v2()] or i
2c680 74 73 20 76 61 72 69 61 6e 74 73 2e 0a 2a 2a 0a  ts variants..**.
2c690 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 61  ** ^The second a
2c6a0 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 69  rgument is the i
2c6b0 6e 64 65 78 20 6f 66 20 74 68 65 20 53 51 4c 20  ndex of the SQL 
2c6c0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 62 65 20  parameter to be 
2c6d0 73 65 74 2e 0a 2a 2a 20 5e 54 68 65 20 6c 65 66  set..** ^The lef
2c6e0 74 6d 6f 73 74 20 53 51 4c 20 70 61 72 61 6d 65  tmost SQL parame
2c6f0 74 65 72 20 68 61 73 20 61 6e 20 69 6e 64 65 78  ter has an index
2c700 20 6f 66 20 31 2e 20 20 5e 57 68 65 6e 20 74 68   of 1.  ^When th
2c710 65 20 73 61 6d 65 20 6e 61 6d 65 64 0a 2a 2a 20  e same named.** 
2c720 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 69 73  SQL parameter is
2c730 20 75 73 65 64 20 6d 6f 72 65 20 74 68 61 6e 20   used more than 
2c740 6f 6e 63 65 2c 20 73 65 63 6f 6e 64 20 61 6e 64  once, second and
2c750 20 73 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20 6f   subsequent.** o
2c760 63 63 75 72 72 65 6e 63 65 73 20 68 61 76 65 20  ccurrences have 
2c770 74 68 65 20 73 61 6d 65 20 69 6e 64 65 78 20 61  the same index a
2c780 73 20 74 68 65 20 66 69 72 73 74 20 6f 63 63 75  s the first occu
2c790 72 72 65 6e 63 65 2e 0a 2a 2a 20 5e 54 68 65 20  rrence..** ^The 
2c7a0 69 6e 64 65 78 20 66 6f 72 20 6e 61 6d 65 64 20  index for named 
2c7b0 70 61 72 61 6d 65 74 65 72 73 20 63 61 6e 20 62  parameters can b
2c7c0 65 20 6c 6f 6f 6b 65 64 20 75 70 20 75 73 69 6e  e looked up usin
2c7d0 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  g the.** [sqlite
2c7e0 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
2c7f0 5f 69 6e 64 65 78 28 29 5d 20 41 50 49 20 69 66  _index()] API if
2c800 20 64 65 73 69 72 65 64 2e 20 20 5e 54 68 65 20   desired.  ^The 
2c810 69 6e 64 65 78 0a 2a 2a 20 66 6f 72 20 22 3f 4e  index.** for "?N
2c820 4e 4e 22 20 70 61 72 61 6d 65 74 65 72 73 20 69  NN" parameters i
2c830 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 4e  s the value of N
2c840 4e 4e 2e 0a 2a 2a 20 5e 54 68 65 20 4e 4e 4e 20  NN..** ^The NNN 
2c850 76 61 6c 75 65 20 6d 75 73 74 20 62 65 20 62 65  value must be be
2c860 74 77 65 65 6e 20 31 20 61 6e 64 20 74 68 65 20  tween 1 and the 
2c870 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29  [sqlite3_limit()
2c880 5d 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 5b  ].** parameter [
2c890 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52  SQLITE_LIMIT_VAR
2c8a0 49 41 42 4c 45 5f 4e 55 4d 42 45 52 5d 20 28 64  IABLE_NUMBER] (d
2c8b0 65 66 61 75 6c 74 20 76 61 6c 75 65 3a 20 39 39  efault value: 99
2c8c0 39 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74  9)..**.** ^The t
2c8d0 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73  hird argument is
2c8e0 20 74 68 65 20 76 61 6c 75 65 20 74 6f 20 62 69   the value to bi
2c8f0 6e 64 20 74 6f 20 74 68 65 20 70 61 72 61 6d 65  nd to the parame
2c900 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ter..** ^If the 
2c910 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20  third parameter 
2c920 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  to sqlite3_bind_
2c930 74 65 78 74 28 29 20 6f 72 20 73 71 6c 69 74 65  text() or sqlite
2c940 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 29 0a  3_bind_text16().
2c950 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 69  ** or sqlite3_bi
2c960 6e 64 5f 62 6c 6f 62 28 29 20 69 73 20 61 20 4e  nd_blob() is a N
2c970 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e  ULL pointer then
2c980 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61   the fourth para
2c990 6d 65 74 65 72 0a 2a 2a 20 69 73 20 69 67 6e 6f  meter.** is igno
2c9a0 72 65 64 20 61 6e 64 20 74 68 65 20 65 6e 64 20  red and the end 
2c9b0 72 65 73 75 6c 74 20 69 73 20 74 68 65 20 73 61  result is the sa
2c9c0 6d 65 20 61 73 20 73 71 6c 69 74 65 33 5f 62 69  me as sqlite3_bi
2c9d0 6e 64 5f 6e 75 6c 6c 28 29 2e 0a 2a 2a 0a 2a 2a  nd_null()..**.**
2c9e0 20 5e 28 49 6e 20 74 68 6f 73 65 20 72 6f 75 74   ^(In those rout
2c9f0 69 6e 65 73 20 74 68 61 74 20 68 61 76 65 20 61  ines that have a
2ca00 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74   fourth argument
2ca10 2c 20 69 74 73 20 76 61 6c 75 65 20 69 73 20 74  , its value is t
2ca20 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20  he.** number of 
2ca30 62 79 74 65 73 20 69 6e 20 74 68 65 20 70 61 72  bytes in the par
2ca40 61 6d 65 74 65 72 2e 20 20 54 6f 20 62 65 20 63  ameter.  To be c
2ca50 6c 65 61 72 3a 20 74 68 65 20 76 61 6c 75 65 20  lear: the value 
2ca60 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72  is the.** number
2ca70 20 6f 66 20 3c 75 3e 62 79 74 65 73 3c 2f 75 3e   of <u>bytes</u>
2ca80 20 69 6e 20 74 68 65 20 76 61 6c 75 65 2c 20 6e   in the value, n
2ca90 6f 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ot the number of
2caa0 20 63 68 61 72 61 63 74 65 72 73 2e 29 5e 0a 2a   characters.)^.*
2cab0 2a 20 5e 49 66 20 74 68 65 20 66 6f 75 72 74 68  * ^If the fourth
2cac0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
2cad0 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28  lite3_bind_text(
2cae0 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 69 6e  ) or sqlite3_bin
2caf0 64 5f 74 65 78 74 31 36 28 29 0a 2a 2a 20 69 73  d_text16().** is
2cb00 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20   negative, then 
2cb10 74 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 74 68  the length of th
2cb20 65 20 73 74 72 69 6e 67 20 69 73 0a 2a 2a 20 74  e string is.** t
2cb30 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  he number of byt
2cb40 65 73 20 75 70 20 74 6f 20 74 68 65 20 66 69 72  es up to the fir
2cb50 73 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74  st zero terminat
2cb60 6f 72 2e 0a 2a 2a 20 49 66 20 74 68 65 20 66 6f  or..** If the fo
2cb70 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74  urth parameter t
2cb80 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62  o sqlite3_bind_b
2cb90 6c 6f 62 28 29 20 69 73 20 6e 65 67 61 74 69 76  lob() is negativ
2cba0 65 2c 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 62  e, then.** the b
2cbb0 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66  ehavior is undef
2cbc0 69 6e 65 64 2e 0a 2a 2a 20 49 66 20 61 20 6e 6f  ined..** If a no
2cbd0 6e 2d 6e 65 67 61 74 69 76 65 20 66 6f 75 72 74  n-negative fourt
2cbe0 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 70  h parameter is p
2cbf0 72 6f 76 69 64 65 64 20 74 6f 20 73 71 6c 69 74  rovided to sqlit
2cc00 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 29 0a 2a  e3_bind_text().*
2cc10 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 69 6e  * or sqlite3_bin
2cc20 64 5f 74 65 78 74 31 36 28 29 20 6f 72 20 73 71  d_text16() or sq
2cc30 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 36  lite3_bind_text6
2cc40 34 28 29 20 74 68 65 6e 0a 2a 2a 20 74 68 61 74  4() then.** that
2cc50 20 70 61 72 61 6d 65 74 65 72 20 6d 75 73 74 20   parameter must 
2cc60 62 65 20 74 68 65 20 62 79 74 65 20 6f 66 66 73  be the byte offs
2cc70 65 74 0a 2a 2a 20 77 68 65 72 65 20 74 68 65 20  et.** where the 
2cc80 4e 55 4c 20 74 65 72 6d 69 6e 61 74 6f 72 20 77  NUL terminator w
2cc90 6f 75 6c 64 20 6f 63 63 75 72 20 61 73 73 75 6d  ould occur assum
2cca0 69 6e 67 20 74 68 65 20 73 74 72 69 6e 67 20 77  ing the string w
2ccb0 65 72 65 20 4e 55 4c 0a 2a 2a 20 74 65 72 6d 69  ere NUL.** termi
2ccc0 6e 61 74 65 64 2e 20 20 49 66 20 61 6e 79 20 4e  nated.  If any N
2ccd0 55 4c 20 63 68 61 72 61 63 74 65 72 73 20 6f 63  UL characters oc
2cce0 63 75 72 20 61 74 20 62 79 74 65 20 6f 66 66 73  cur at byte offs
2ccf0 65 74 73 20 6c 65 73 73 20 74 68 61 6e 20 0a 2a  ets less than .*
2cd00 2a 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74  * the value of t
2cd10 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
2cd20 74 65 72 20 74 68 65 6e 20 74 68 65 20 72 65 73  ter then the res
2cd30 75 6c 74 69 6e 67 20 73 74 72 69 6e 67 20 76 61  ulting string va
2cd40 6c 75 65 20 77 69 6c 6c 0a 2a 2a 20 63 6f 6e 74  lue will.** cont
2cd50 61 69 6e 20 65 6d 62 65 64 64 65 64 20 4e 55 4c  ain embedded NUL
2cd60 73 2e 20 20 54 68 65 20 72 65 73 75 6c 74 20 6f  s.  The result o
2cd70 66 20 65 78 70 72 65 73 73 69 6f 6e 73 20 69 6e  f expressions in
2cd80 76 6f 6c 76 69 6e 67 20 73 74 72 69 6e 67 73 0a  volving strings.
2cd90 2a 2a 20 77 69 74 68 20 65 6d 62 65 64 64 65 64  ** with embedded
2cda0 20 4e 55 4c 73 20 69 73 20 75 6e 64 65 66 69 6e   NULs is undefin
2cdb0 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66  ed..**.** ^The f
2cdc0 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f  ifth argument to
2cdd0 20 74 68 65 20 42 4c 4f 42 20 61 6e 64 20 73 74   the BLOB and st
2cde0 72 69 6e 67 20 62 69 6e 64 69 6e 67 20 69 6e 74  ring binding int
2cdf0 65 72 66 61 63 65 73 0a 2a 2a 20 69 73 20 61 20  erfaces.** is a 
2ce00 64 65 73 74 72 75 63 74 6f 72 20 75 73 65 64 20  destructor used 
2ce10 74 6f 20 64 69 73 70 6f 73 65 20 6f 66 20 74 68  to dispose of th
2ce20 65 20 42 4c 4f 42 20 6f 72 0a 2a 2a 20 73 74 72  e BLOB or.** str
2ce30 69 6e 67 20 61 66 74 65 72 20 53 51 4c 69 74 65  ing after SQLite
2ce40 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 77 69   has finished wi
2ce50 74 68 20 69 74 2e 20 20 5e 54 68 65 20 64 65 73  th it.  ^The des
2ce60 74 72 75 63 74 6f 72 20 69 73 20 63 61 6c 6c 65  tructor is calle
2ce70 64 0a 2a 2a 20 74 6f 20 64 69 73 70 6f 73 65 20  d.** to dispose 
2ce80 6f 66 20 74 68 65 20 42 4c 4f 42 20 6f 72 20 73  of the BLOB or s
2ce90 74 72 69 6e 67 20 65 76 65 6e 20 69 66 20 74 68  tring even if th
2cea0 65 20 63 61 6c 6c 20 74 6f 20 62 69 6e 64 20 41  e call to bind A
2ceb0 50 49 20 66 61 69 6c 73 2e 0a 2a 2a 20 5e 49 66  PI fails..** ^If
2cec0 20 74 68 65 20 66 69 66 74 68 20 61 72 67 75 6d   the fifth argum
2ced0 65 6e 74 20 69 73 0a 2a 2a 20 74 68 65 20 73 70  ent is.** the sp
2cee0 65 63 69 61 6c 20 76 61 6c 75 65 20 5b 53 51 4c  ecial value [SQL
2cef0 49 54 45 5f 53 54 41 54 49 43 5d 2c 20 74 68 65  ITE_STATIC], the
2cf00 6e 20 53 51 4c 69 74 65 20 61 73 73 75 6d 65 73  n SQLite assumes
2cf10 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 69 6e 66   that the.** inf
2cf20 6f 72 6d 61 74 69 6f 6e 20 69 73 20 69 6e 20 73  ormation is in s
2cf30 74 61 74 69 63 2c 20 75 6e 6d 61 6e 61 67 65 64  tatic, unmanaged
2cf40 20 73 70 61 63 65 20 61 6e 64 20 64 6f 65 73 20   space and does 
2cf50 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20 66  not need to be f
2cf60 72 65 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  reed..** ^If the
2cf70 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20   fifth argument 
2cf80 68 61 73 20 74 68 65 20 76 61 6c 75 65 20 5b 53  has the value [S
2cf90 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 5d  QLITE_TRANSIENT]
2cfa0 2c 20 74 68 65 6e 0a 2a 2a 20 53 51 4c 69 74 65  , then.** SQLite
2cfb0 20 6d 61 6b 65 73 20 69 74 73 20 6f 77 6e 20 70   makes its own p
2cfc0 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20 74  rivate copy of t
2cfd0 68 65 20 64 61 74 61 20 69 6d 6d 65 64 69 61 74  he data immediat
2cfe0 65 6c 79 2c 20 62 65 66 6f 72 65 0a 2a 2a 20 74  ely, before.** t
2cff0 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  he sqlite3_bind_
2d000 2a 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75  *() routine retu
2d010 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  rns..**.** ^The 
2d020 73 69 78 74 68 20 61 72 67 75 6d 65 6e 74 20 74  sixth argument t
2d030 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74  o sqlite3_bind_t
2d040 65 78 74 36 34 28 29 20 6d 75 73 74 20 62 65 20  ext64() must be 
2d050 6f 6e 65 20 6f 66 0a 2a 2a 20 5b 53 51 4c 49 54  one of.** [SQLIT
2d060 45 5f 55 54 46 38 5d 2c 20 5b 53 51 4c 49 54 45  E_UTF8], [SQLITE
2d070 5f 55 54 46 31 36 5d 2c 20 5b 53 51 4c 49 54 45  _UTF16], [SQLITE
2d080 5f 55 54 46 31 36 42 45 5d 2c 20 6f 72 20 5b 53  _UTF16BE], or [S
2d090 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d 0a 2a  QLITE_UTF16LE].*
2d0a0 2a 20 74 6f 20 73 70 65 63 69 66 79 20 74 68 65  * to specify the
2d0b0 20 65 6e 63 6f 64 69 6e 67 20 6f 66 20 74 68 65   encoding of the
2d0c0 20 74 65 78 74 20 69 6e 20 74 68 65 20 74 68 69   text in the thi
2d0d0 72 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20 49  rd parameter.  I
2d0e0 66 0a 2a 2a 20 74 68 65 20 73 69 78 74 68 20 61  f.** the sixth a
2d0f0 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74  rgument to sqlit
2d100 65 33 5f 62 69 6e 64 5f 74 65 78 74 36 34 28 29  e3_bind_text64()
2d110 20 69 73 20 6e 6f 74 20 6f 6e 65 20 6f 66 20 74   is not one of t
2d120 68 65 0a 2a 2a 20 61 6c 6c 6f 77 65 64 20 76 61  he.** allowed va
2d130 6c 75 65 73 20 73 68 6f 77 6e 20 61 62 6f 76 65  lues shown above
2d140 2c 20 6f 72 20 69 66 20 74 68 65 20 74 65 78 74  , or if the text
2d150 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 64 69 66   encoding is dif
2d160 66 65 72 65 6e 74 0a 2a 2a 20 66 72 6f 6d 20 74  ferent.** from t
2d170 68 65 20 65 6e 63 6f 64 69 6e 67 20 73 70 65 63  he encoding spec
2d180 69 66 69 65 64 20 62 79 20 74 68 65 20 73 69 78  ified by the six
2d190 74 68 20 70 61 72 61 6d 65 74 65 72 2c 20 74 68  th parameter, th
2d1a0 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 0a  en the behavior.
2d1b0 2a 2a 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e  ** is undefined.
2d1c0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
2d1d0 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f  te3_bind_zeroblo
2d1e0 62 28 29 20 72 6f 75 74 69 6e 65 20 62 69 6e 64  b() routine bind
2d1f0 73 20 61 20 42 4c 4f 42 20 6f 66 20 6c 65 6e 67  s a BLOB of leng
2d200 74 68 20 4e 20 74 68 61 74 0a 2a 2a 20 69 73 20  th N that.** is 
2d210 66 69 6c 6c 65 64 20 77 69 74 68 20 7a 65 72 6f  filled with zero
2d220 65 73 2e 20 20 5e 41 20 7a 65 72 6f 62 6c 6f 62  es.  ^A zeroblob
2d230 20 75 73 65 73 20 61 20 66 69 78 65 64 20 61 6d   uses a fixed am
2d240 6f 75 6e 74 20 6f 66 20 6d 65 6d 6f 72 79 0a 2a  ount of memory.*
2d250 2a 20 28 6a 75 73 74 20 61 6e 20 69 6e 74 65 67  * (just an integ
2d260 65 72 20 74 6f 20 68 6f 6c 64 20 69 74 73 20 73  er to hold its s
2d270 69 7a 65 29 20 77 68 69 6c 65 20 69 74 20 69 73  ize) while it is
2d280 20 62 65 69 6e 67 20 70 72 6f 63 65 73 73 65 64   being processed
2d290 2e 0a 2a 2a 20 5a 65 72 6f 62 6c 6f 62 73 20 61  ..** Zeroblobs a
2d2a0 72 65 20 69 6e 74 65 6e 64 65 64 20 74 6f 20 73  re intended to s
2d2b0 65 72 76 65 20 61 73 20 70 6c 61 63 65 68 6f 6c  erve as placehol
2d2c0 64 65 72 73 20 66 6f 72 20 42 4c 4f 42 73 20 77  ders for BLOBs w
2d2d0 68 6f 73 65 0a 2a 2a 20 63 6f 6e 74 65 6e 74 20  hose.** content 
2d2e0 69 73 20 6c 61 74 65 72 20 77 72 69 74 74 65 6e  is later written
2d2f0 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74   using.** [sqlit
2d300 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 20 7c 20 69  e3_blob_open | i
2d310 6e 63 72 65 6d 65 6e 74 61 6c 20 42 4c 4f 42 20  ncremental BLOB 
2d320 49 2f 4f 5d 20 72 6f 75 74 69 6e 65 73 2e 0a 2a  I/O] routines..*
2d330 2a 20 5e 41 20 6e 65 67 61 74 69 76 65 20 76 61  * ^A negative va
2d340 6c 75 65 20 66 6f 72 20 74 68 65 20 7a 65 72 6f  lue for the zero
2d350 62 6c 6f 62 20 72 65 73 75 6c 74 73 20 69 6e 20  blob results in 
2d360 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 42 4c  a zero-length BL
2d370 4f 42 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e  OB..**.** ^If an
2d380 79 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33  y of the sqlite3
2d390 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e  _bind_*() routin
2d3a0 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20 77 69  es are called wi
2d3b0 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  th a NULL pointe
2d3c0 72 0a 2a 2a 20 66 6f 72 20 74 68 65 20 5b 70 72  r.** for the [pr
2d3d0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2d3e0 5d 20 6f 72 20 77 69 74 68 20 61 20 70 72 65 70  ] or with a prep
2d3f0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 66  ared statement f
2d400 6f 72 20 77 68 69 63 68 0a 2a 2a 20 5b 73 71 6c  or which.** [sql
2d410 69 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73  ite3_step()] has
2d420 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 6d 6f 72   been called mor
2d430 65 20 72 65 63 65 6e 74 6c 79 20 74 68 61 6e 20  e recently than 
2d440 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
2d450 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 63  ],.** then the c
2d460 61 6c 6c 20 77 69 6c 6c 20 72 65 74 75 72 6e 20  all will return 
2d470 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e  [SQLITE_MISUSE].
2d480 20 20 49 66 20 61 6e 79 20 73 71 6c 69 74 65 33    If any sqlite3
2d490 5f 62 69 6e 64 5f 28 29 0a 2a 2a 20 72 6f 75 74  _bind_().** rout
2d4a0 69 6e 65 20 69 73 20 70 61 73 73 65 64 20 61 20  ine is passed a 
2d4b0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2d4c0 65 6e 74 5d 20 74 68 61 74 20 68 61 73 20 62 65  ent] that has be
2d4d0 65 6e 20 66 69 6e 61 6c 69 7a 65 64 2c 20 74 68  en finalized, th
2d4e0 65 0a 2a 2a 20 72 65 73 75 6c 74 20 69 73 20 75  e.** result is u
2d4f0 6e 64 65 66 69 6e 65 64 20 61 6e 64 20 70 72 6f  ndefined and pro
2d500 62 61 62 6c 79 20 68 61 72 6d 66 75 6c 2e 0a 2a  bably harmful..*
2d510 2a 0a 2a 2a 20 5e 42 69 6e 64 69 6e 67 73 20 61  *.** ^Bindings a
2d520 72 65 20 6e 6f 74 20 63 6c 65 61 72 65 64 20 62  re not cleared b
2d530 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 72  y the [sqlite3_r
2d540 65 73 65 74 28 29 5d 20 72 6f 75 74 69 6e 65 2e  eset()] routine.
2d550 0a 2a 2a 20 5e 55 6e 62 6f 75 6e 64 20 70 61 72  .** ^Unbound par
2d560 61 6d 65 74 65 72 73 20 61 72 65 20 69 6e 74 65  ameters are inte
2d570 72 70 72 65 74 65 64 20 61 73 20 4e 55 4c 4c 2e  rpreted as NULL.
2d580 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
2d590 74 65 33 5f 62 69 6e 64 5f 2a 20 72 6f 75 74 69  te3_bind_* routi
2d5a0 6e 65 73 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  nes return [SQLI
2d5b0 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73  TE_OK] on succes
2d5c0 73 20 6f 72 20 61 6e 0a 2a 2a 20 5b 65 72 72 6f  s or an.** [erro
2d5d0 72 20 63 6f 64 65 5d 20 69 66 20 61 6e 79 74 68  r code] if anyth
2d5e0 69 6e 67 20 67 6f 65 73 20 77 72 6f 6e 67 2e 0a  ing goes wrong..
2d5f0 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 54 4f 4f 42  ** ^[SQLITE_TOOB
2d600 49 47 5d 20 6d 69 67 68 74 20 62 65 20 72 65 74  IG] might be ret
2d610 75 72 6e 65 64 20 69 66 20 74 68 65 20 73 69 7a  urned if the siz
2d620 65 20 6f 66 20 61 20 73 74 72 69 6e 67 20 6f 72  e of a string or
2d630 20 42 4c 4f 42 0a 2a 2a 20 65 78 63 65 65 64 73   BLOB.** exceeds
2d640 20 6c 69 6d 69 74 73 20 69 6d 70 6f 73 65 64 20   limits imposed 
2d650 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69  by [sqlite3_limi
2d660 74 5d 28 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54  t]([SQLITE_LIMIT
2d670 5f 4c 45 4e 47 54 48 5d 29 20 6f 72 0a 2a 2a 20  _LENGTH]) or.** 
2d680 5b 53 51 4c 49 54 45 5f 4d 41 58 5f 4c 45 4e 47  [SQLITE_MAX_LENG
2d690 54 48 5d 2e 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45  TH]..** ^[SQLITE
2d6a0 5f 52 41 4e 47 45 5d 20 69 73 20 72 65 74 75 72  _RANGE] is retur
2d6b0 6e 65 64 20 69 66 20 74 68 65 20 70 61 72 61 6d  ned if the param
2d6c0 65 74 65 72 0a 2a 2a 20 69 6e 64 65 78 20 69 73  eter.** index is
2d6d0 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 2e 20 20   out of range.  
2d6e0 5e 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 20  ^[SQLITE_NOMEM] 
2d6f0 69 73 20 72 65 74 75 72 6e 65 64 20 69 66 20 6d  is returned if m
2d700 61 6c 6c 6f 63 28 29 20 66 61 69 6c 73 2e 0a 2a  alloc() fails..*
2d710 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b  *.** See also: [
2d720 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
2d730 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c  ameter_count()],
2d740 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  .** [sqlite3_bin
2d750 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65  d_parameter_name
2d760 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65  ()], and [sqlite
2d770 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
2d780 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 69 6e  _index()]..*/.in
2d790 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62  t sqlite3_bind_b
2d7a0 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  lob(sqlite3_stmt
2d7b0 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f  *, int, const vo
2d7c0 69 64 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f 69 64  id*, int n, void
2d7d0 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74  (*)(void*));.int
2d7e0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c   sqlite3_bind_bl
2d7f0 6f 62 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d  ob64(sqlite3_stm
2d800 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76  t*, int, const v
2d810 6f 69 64 2a 2c 20 73 71 6c 69 74 65 33 5f 75 69  oid*, sqlite3_ui
2d820 6e 74 36 34 2c 0a 20 20 20 20 20 20 20 20 20 20  nt64,.          
2d830 20 20 20 20 20 20 20 20 20 20 20 20 20 20 76 6f                vo
2d840 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69  id(*)(void*));.i
2d850 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
2d860 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 73  double(sqlite3_s
2d870 74 6d 74 2a 2c 20 69 6e 74 2c 20 64 6f 75 62 6c  tmt*, int, doubl
2d880 65 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  e);.int sqlite3_
2d890 62 69 6e 64 5f 69 6e 74 28 73 71 6c 69 74 65 33  bind_int(sqlite3
2d8a0 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74  _stmt*, int, int
2d8b0 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  );.int sqlite3_b
2d8c0 69 6e 64 5f 69 6e 74 36 34 28 73 71 6c 69 74 65  ind_int64(sqlite
2d8d0 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 73 71  3_stmt*, int, sq
2d8e0 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 69 6e  lite3_int64);.in
2d8f0 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 6e  t sqlite3_bind_n
2d900 75 6c 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ull(sqlite3_stmt
2d910 2a 2c 20 69 6e 74 29 3b 0a 69 6e 74 20 73 71 6c  *, int);.int sql
2d920 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 73  ite3_bind_text(s
2d930 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74  qlite3_stmt*,int
2d940 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 69 6e 74  ,const char*,int
2d950 2c 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29  ,void(*)(void*))
2d960 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  ;.int sqlite3_bi
2d970 6e 64 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65  nd_text16(sqlite
2d980 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f  3_stmt*, int, co
2d990 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20  nst void*, int, 
2d9a0 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b  void(*)(void*));
2d9b0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e  .int sqlite3_bin
2d9c0 64 5f 74 65 78 74 36 34 28 73 71 6c 69 74 65 33  d_text64(sqlite3
2d9d0 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e  _stmt*, int, con
2d9e0 73 74 20 63 68 61 72 2a 2c 20 73 71 6c 69 74 65  st char*, sqlite
2d9f0 33 5f 75 69 6e 74 36 34 2c 0a 20 20 20 20 20 20  3_uint64,.      
2da00 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2da10 20 20 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a     void(*)(void*
2da20 29 2c 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72  ), unsigned char
2da30 20 65 6e 63 6f 64 69 6e 67 29 3b 0a 69 6e 74 20   encoding);.int 
2da40 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c  sqlite3_bind_val
2da50 75 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  ue(sqlite3_stmt*
2da60 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 73 71 6c  , int, const sql
2da70 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e  ite3_value*);.in
2da80 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a  t sqlite3_bind_z
2da90 65 72 6f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f  eroblob(sqlite3_
2daa0 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 20  stmt*, int, int 
2dab0 6e 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  n);.int sqlite3_
2dac0 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 36 34 28  bind_zeroblob64(
2dad0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
2dae0 6e 74 2c 20 73 71 6c 69 74 65 33 5f 75 69 6e 74  nt, sqlite3_uint
2daf0 36 34 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  64);../*.** CAPI
2db00 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 4f 66 20  3REF: Number Of 
2db10 53 51 4c 20 50 61 72 61 6d 65 74 65 72 73 0a 2a  SQL Parameters.*
2db20 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65  * METHOD: sqlite
2db30 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68  3_stmt.**.** ^Th
2db40 69 73 20 72 6f 75 74 69 6e 65 20 63 61 6e 20 62  is routine can b
2db50 65 20 75 73 65 64 20 74 6f 20 66 69 6e 64 20 74  e used to find t
2db60 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 5b 53 51  he number of [SQ
2db70 4c 20 70 61 72 61 6d 65 74 65 72 73 5d 0a 2a 2a  L parameters].**
2db80 20 69 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20   in a [prepared 
2db90 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20 53 51 4c  statement].  SQL
2dba0 20 70 61 72 61 6d 65 74 65 72 73 20 61 72 65 20   parameters are 
2dbb0 74 6f 6b 65 6e 73 20 6f 66 20 74 68 65 0a 2a 2a  tokens of the.**
2dbc0 20 66 6f 72 6d 20 22 3f 22 2c 20 22 3f 4e 4e 4e   form "?", "?NNN
2dbd0 22 2c 20 22 3a 41 41 41 22 2c 20 22 24 41 41 41  ", ":AAA", "$AAA
2dbe0 22 2c 20 6f 72 20 22 40 41 41 41 22 20 74 68 61  ", or "@AAA" tha
2dbf0 74 20 73 65 72 76 65 20 61 73 0a 2a 2a 20 70 6c  t serve as.** pl
2dc00 61 63 65 68 6f 6c 64 65 72 73 20 66 6f 72 20 76  aceholders for v
2dc10 61 6c 75 65 73 20 74 68 61 74 20 61 72 65 20 5b  alues that are [
2dc20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
2dc30 62 20 7c 20 62 6f 75 6e 64 5d 0a 2a 2a 20 74 6f  b | bound].** to
2dc40 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 73 20   the parameters 
2dc50 61 74 20 61 20 6c 61 74 65 72 20 74 69 6d 65 2e  at a later time.
2dc60 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 72 6f  .**.** ^(This ro
2dc70 75 74 69 6e 65 20 61 63 74 75 61 6c 6c 79 20 72  utine actually r
2dc80 65 74 75 72 6e 73 20 74 68 65 20 69 6e 64 65 78  eturns the index
2dc90 20 6f 66 20 74 68 65 20 6c 61 72 67 65 73 74 20   of the largest 
2dca0 28 72 69 67 68 74 6d 6f 73 74 29 0a 2a 2a 20 70  (rightmost).** p
2dcb0 61 72 61 6d 65 74 65 72 2e 20 46 6f 72 20 61 6c  arameter. For al
2dcc0 6c 20 66 6f 72 6d 73 20 65 78 63 65 70 74 20 3f  l forms except ?
2dcd0 4e 4e 4e 2c 20 74 68 69 73 20 77 69 6c 6c 20 63  NNN, this will c
2dce0 6f 72 72 65 73 70 6f 6e 64 20 74 6f 20 74 68 65  orrespond to the
2dcf0 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 75 6e  .** number of un
2dd00 69 71 75 65 20 70 61 72 61 6d 65 74 65 72 73 2e  ique parameters.
2dd10 20 20 49 66 20 70 61 72 61 6d 65 74 65 72 73 20    If parameters 
2dd20 6f 66 20 74 68 65 20 3f 4e 4e 4e 20 66 6f 72 6d  of the ?NNN form
2dd30 20 61 72 65 20 75 73 65 64 2c 0a 2a 2a 20 74 68   are used,.** th
2dd40 65 72 65 20 6d 61 79 20 62 65 20 67 61 70 73 20  ere may be gaps 
2dd50 69 6e 20 74 68 65 20 6c 69 73 74 2e 29 5e 0a 2a  in the list.)^.*
2dd60 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b  *.** See also: [
2dd70 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
2dd80 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29  b|sqlite3_bind()
2dd90 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  ],.** [sqlite3_b
2dda0 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61  ind_parameter_na
2ddb0 6d 65 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73  me()], and.** [s
2ddc0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
2ddd0 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a  meter_index()]..
2dde0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  */.int sqlite3_b
2ddf0 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f  ind_parameter_co
2de00 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  unt(sqlite3_stmt
2de10 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
2de20 52 45 46 3a 20 4e 61 6d 65 20 4f 66 20 41 20 48  REF: Name Of A H
2de30 6f 73 74 20 50 61 72 61 6d 65 74 65 72 0a 2a 2a  ost Parameter.**
2de40 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
2de50 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  _stmt.**.** ^The
2de60 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61   sqlite3_bind_pa
2de70 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 50 2c 4e  rameter_name(P,N
2de80 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ) interface retu
2de90 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20  rns.** the name 
2dea0 6f 66 20 74 68 65 20 4e 2d 74 68 20 5b 53 51 4c  of the N-th [SQL
2deb0 20 70 61 72 61 6d 65 74 65 72 5d 20 69 6e 20 74   parameter] in t
2dec0 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
2ded0 74 65 6d 65 6e 74 5d 20 50 2e 0a 2a 2a 20 5e 28  tement] P..** ^(
2dee0 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 20 6f  SQL parameters o
2def0 66 20 74 68 65 20 66 6f 72 6d 20 22 3f 4e 4e 4e  f the form "?NNN
2df00 22 20 6f 72 20 22 3a 41 41 41 22 20 6f 72 20 22  " or ":AAA" or "
2df10 40 41 41 41 22 20 6f 72 20 22 24 41 41 41 22 0a  @AAA" or "$AAA".
2df20 2a 2a 20 68 61 76 65 20 61 20 6e 61 6d 65 20 77  ** have a name w
2df30 68 69 63 68 20 69 73 20 74 68 65 20 73 74 72 69  hich is the stri
2df40 6e 67 20 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41  ng "?NNN" or ":A
2df50 41 41 22 20 6f 72 20 22 40 41 41 41 22 20 6f 72  AA" or "@AAA" or
2df60 20 22 24 41 41 41 22 0a 2a 2a 20 72 65 73 70 65   "$AAA".** respe
2df70 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 49 6e 20 6f  ctively..** In o
2df80 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20  ther words, the 
2df90 69 6e 69 74 69 61 6c 20 22 3a 22 20 6f 72 20 22  initial ":" or "
2dfa0 24 22 20 6f 72 20 22 40 22 20 6f 72 20 22 3f 22  $" or "@" or "?"
2dfb0 0a 2a 2a 20 69 73 20 69 6e 63 6c 75 64 65 64 20  .** is included 
2dfc0 61 73 20 70 61 72 74 20 6f 66 20 74 68 65 20 6e  as part of the n
2dfd0 61 6d 65 2e 29 5e 0a 2a 2a 20 5e 50 61 72 61 6d  ame.)^.** ^Param
2dfe0 65 74 65 72 73 20 6f 66 20 74 68 65 20 66 6f 72  eters of the for
2dff0 6d 20 22 3f 22 20 77 69 74 68 6f 75 74 20 61 20  m "?" without a 
2e000 66 6f 6c 6c 6f 77 69 6e 67 20 69 6e 74 65 67 65  following intege
2e010 72 20 68 61 76 65 20 6e 6f 20 6e 61 6d 65 0a 2a  r have no name.*
2e020 2a 20 61 6e 64 20 61 72 65 20 72 65 66 65 72 72  * and are referr
2e030 65 64 20 74 6f 20 61 73 20 22 6e 61 6d 65 6c 65  ed to as "namele
2e040 73 73 22 20 6f 72 20 22 61 6e 6f 6e 79 6d 6f 75  ss" or "anonymou
2e050 73 20 70 61 72 61 6d 65 74 65 72 73 22 2e 0a 2a  s parameters"..*
2e060 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20  *.** ^The first 
2e070 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20 68  host parameter h
2e080 61 73 20 61 6e 20 69 6e 64 65 78 20 6f 66 20 31  as an index of 1
2e090 2c 20 6e 6f 74 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e  , not 0..**.** ^
2e0a0 49 66 20 74 68 65 20 76 61 6c 75 65 20 4e 20 69  If the value N i
2e0b0 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 20 6f  s out of range o
2e0c0 72 20 69 66 20 74 68 65 20 4e 2d 74 68 20 70 61  r if the N-th pa
2e0d0 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20 6e 61  rameter is.** na
2e0e0 6d 65 6c 65 73 73 2c 20 74 68 65 6e 20 4e 55 4c  meless, then NUL
2e0f0 4c 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20  L is returned.  
2e100 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 74  ^The returned st
2e110 72 69 6e 67 20 69 73 0a 2a 2a 20 61 6c 77 61 79  ring is.** alway
2e120 73 20 69 6e 20 55 54 46 2d 38 20 65 6e 63 6f 64  s in UTF-8 encod
2e130 69 6e 67 20 65 76 65 6e 20 69 66 20 74 68 65 20  ing even if the 
2e140 6e 61 6d 65 64 20 70 61 72 61 6d 65 74 65 72 20  named parameter 
2e150 77 61 73 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 6c  was.** originall
2e160 79 20 73 70 65 63 69 66 69 65 64 20 61 73 20 55  y specified as U
2e170 54 46 2d 31 36 20 69 6e 20 5b 73 71 6c 69 74 65  TF-16 in [sqlite
2e180 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 20 6f  3_prepare16()] o
2e190 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72  r.** [sqlite3_pr
2e1a0 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a  epare16_v2()]..*
2e1b0 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b  *.** See also: [
2e1c0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
2e1d0 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29  b|sqlite3_bind()
2e1e0 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  ],.** [sqlite3_b
2e1f0 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f  ind_parameter_co
2e200 75 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b  unt()], and.** [
2e210 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
2e220 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e  ameter_index()].
2e230 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a  .*/.const char *
2e240 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
2e250 61 6d 65 74 65 72 5f 6e 61 6d 65 28 73 71 6c 69  ameter_name(sqli
2e260 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 29 3b  te3_stmt*, int);
2e270 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2e280 3a 20 49 6e 64 65 78 20 4f 66 20 41 20 50 61 72  : Index Of A Par
2e290 61 6d 65 74 65 72 20 57 69 74 68 20 41 20 47 69  ameter With A Gi
2e2a0 76 65 6e 20 4e 61 6d 65 0a 2a 2a 20 4d 45 54 48  ven Name.** METH
2e2b0 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  OD: sqlite3_stmt
2e2c0 0a 2a 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e 20 74  .**.** ^Return t
2e2d0 68 65 20 69 6e 64 65 78 20 6f 66 20 61 6e 20 53  he index of an S
2e2e0 51 4c 20 70 61 72 61 6d 65 74 65 72 20 67 69 76  QL parameter giv
2e2f0 65 6e 20 69 74 73 20 6e 61 6d 65 2e 20 20 5e 54  en its name.  ^T
2e300 68 65 0a 2a 2a 20 69 6e 64 65 78 20 76 61 6c 75  he.** index valu
2e310 65 20 72 65 74 75 72 6e 65 64 20 69 73 20 73 75  e returned is su
2e320 69 74 61 62 6c 65 20 66 6f 72 20 75 73 65 20 61  itable for use a
2e330 73 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20  s the second.** 
2e340 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71  parameter to [sq
2e350 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c  lite3_bind_blob|
2e360 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2e  sqlite3_bind()].
2e370 20 20 5e 41 20 7a 65 72 6f 0a 2a 2a 20 69 73 20    ^A zero.** is 
2e380 72 65 74 75 72 6e 65 64 20 69 66 20 6e 6f 20 6d  returned if no m
2e390 61 74 63 68 69 6e 67 20 70 61 72 61 6d 65 74 65  atching paramete
2e3a0 72 20 69 73 20 66 6f 75 6e 64 2e 20 20 5e 54 68  r is found.  ^Th
2e3b0 65 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 6e  e parameter.** n
2e3c0 61 6d 65 20 6d 75 73 74 20 62 65 20 67 69 76 65  ame must be give
2e3d0 6e 20 69 6e 20 55 54 46 2d 38 20 65 76 65 6e 20  n in UTF-8 even 
2e3e0 69 66 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20  if the original 
2e3f0 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 77 61 73  statement.** was
2e400 20 70 72 65 70 61 72 65 64 20 66 72 6f 6d 20 55   prepared from U
2e410 54 46 2d 31 36 20 74 65 78 74 20 75 73 69 6e 67  TF-16 text using
2e420 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
2e430 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a  e16_v2()]..**.**
2e440 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69   See also: [sqli
2e450 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71  te3_bind_blob|sq
2e460 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a  lite3_bind()],.*
2e470 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  * [sqlite3_bind_
2e480 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28  parameter_count(
2e490 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69  )], and.** [sqli
2e4a0 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
2e4b0 65 72 5f 6e 61 6d 65 28 29 5d 2e 0a 2a 2f 0a 69  er_name()]..*/.i
2e4c0 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
2e4d0 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28  parameter_index(
2e4e0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 63  sqlite3_stmt*, c
2e4f0 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65  onst char *zName
2e500 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2e510 45 46 3a 20 52 65 73 65 74 20 41 6c 6c 20 42 69  EF: Reset All Bi
2e520 6e 64 69 6e 67 73 20 4f 6e 20 41 20 50 72 65 70  ndings On A Prep
2e530 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 0a 2a  ared Statement.*
2e540 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65  * METHOD: sqlite
2e550 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 43 6f  3_stmt.**.** ^Co
2e560 6e 74 72 61 72 79 20 74 6f 20 74 68 65 20 69 6e  ntrary to the in
2e570 74 75 69 74 69 6f 6e 20 6f 66 20 6d 61 6e 79 2c  tuition of many,
2e580 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
2e590 29 5d 20 64 6f 65 73 20 6e 6f 74 20 72 65 73 65  )] does not rese
2e5a0 74 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65  t.** the [sqlite
2e5b0 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 62 69  3_bind_blob | bi
2e5c0 6e 64 69 6e 67 73 5d 20 6f 6e 20 61 20 5b 70 72  ndings] on a [pr
2e5d0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2e5e0 5d 2e 0a 2a 2a 20 5e 55 73 65 20 74 68 69 73 20  ]..** ^Use this 
2e5f0 72 6f 75 74 69 6e 65 20 74 6f 20 72 65 73 65 74  routine to reset
2e600 20 61 6c 6c 20 68 6f 73 74 20 70 61 72 61 6d 65   all host parame
2e610 74 65 72 73 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2f  ters to NULL..*/
2e620 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c 65  .int sqlite3_cle
2e630 61 72 5f 62 69 6e 64 69 6e 67 73 28 73 71 6c 69  ar_bindings(sqli
2e640 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a  te3_stmt*);../*.
2e650 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d  ** CAPI3REF: Num
2e660 62 65 72 20 4f 66 20 43 6f 6c 75 6d 6e 73 20 49  ber Of Columns I
2e670 6e 20 41 20 52 65 73 75 6c 74 20 53 65 74 0a 2a  n A Result Set.*
2e680 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65  * METHOD: sqlite
2e690 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 52 65  3_stmt.**.** ^Re
2e6a0 74 75 72 6e 20 74 68 65 20 6e 75 6d 62 65 72 20  turn the number 
2e6b0 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68  of columns in th
2e6c0 65 20 72 65 73 75 6c 74 20 73 65 74 20 72 65 74  e result set ret
2e6d0 75 72 6e 65 64 20 62 79 20 74 68 65 0a 2a 2a 20  urned by the.** 
2e6e0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2e6f0 65 6e 74 5d 2e 20 5e 54 68 69 73 20 72 6f 75 74  ent]. ^This rout
2e700 69 6e 65 20 72 65 74 75 72 6e 73 20 30 20 69 66  ine returns 0 if
2e710 20 70 53 74 6d 74 20 69 73 20 61 6e 20 53 51 4c   pStmt is an SQL
2e720 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 74 68  .** statement th
2e730 61 74 20 64 6f 65 73 20 6e 6f 74 20 72 65 74 75  at does not retu
2e740 72 6e 20 64 61 74 61 20 28 66 6f 72 20 65 78 61  rn data (for exa
2e750 6d 70 6c 65 20 61 6e 20 5b 55 50 44 41 54 45 5d  mple an [UPDATE]
2e760 29 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  )..**.** See als
2e770 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 64 61 74 61  o: [sqlite3_data
2e780 5f 63 6f 75 6e 74 28 29 5d 0a 2a 2f 0a 69 6e 74  _count()].*/.int
2e790 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2e7a0 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74  count(sqlite3_st
2e7b0 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a  mt *pStmt);../*.
2e7c0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6c  ** CAPI3REF: Col
2e7d0 75 6d 6e 20 4e 61 6d 65 73 20 49 6e 20 41 20 52  umn Names In A R
2e7e0 65 73 75 6c 74 20 53 65 74 0a 2a 2a 20 4d 45 54  esult Set.** MET
2e7f0 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d  HOD: sqlite3_stm
2e800 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72  t.**.** ^These r
2e810 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74  outines return t
2e820 68 65 20 6e 61 6d 65 20 61 73 73 69 67 6e 65 64  he name assigned
2e830 20 74 6f 20 61 20 70 61 72 74 69 63 75 6c 61 72   to a particular
2e840 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 6e 20 74 68   column.** in th
2e850 65 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20  e result set of 
2e860 61 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65  a [SELECT] state
2e870 6d 65 6e 74 2e 20 20 5e 54 68 65 20 73 71 6c 69  ment.  ^The sqli
2e880 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28  te3_column_name(
2e890 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 72  ).** interface r
2e8a0 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
2e8b0 20 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69   to a zero-termi
2e8c0 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74 72 69  nated UTF-8 stri
2e8d0 6e 67 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74 65  ng.** and sqlite
2e8e0 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28  3_column_name16(
2e8f0 29 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  ) returns a poin
2e900 74 65 72 20 74 6f 20 61 20 7a 65 72 6f 2d 74 65  ter to a zero-te
2e910 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d  rminated.** UTF-
2e920 31 36 20 73 74 72 69 6e 67 2e 20 20 5e 54 68 65  16 string.  ^The
2e930 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
2e940 20 69 73 20 74 68 65 20 5b 70 72 65 70 61 72 65   is the [prepare
2e950 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20  d statement].** 
2e960 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 73 20  that implements 
2e970 74 68 65 20 5b 53 45 4c 45 43 54 5d 20 73 74 61  the [SELECT] sta
2e980 74 65 6d 65 6e 74 2e 20 5e 54 68 65 20 73 65 63  tement. ^The sec
2e990 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73  ond parameter is
2e9a0 20 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 6e   the.** column n
2e9b0 75 6d 62 65 72 2e 20 20 5e 54 68 65 20 6c 65 66  umber.  ^The lef
2e9c0 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 69 73 20  tmost column is 
2e9d0 6e 75 6d 62 65 72 20 30 2e 0a 2a 2a 0a 2a 2a 20  number 0..**.** 
2e9e0 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 74  ^The returned st
2e9f0 72 69 6e 67 20 70 6f 69 6e 74 65 72 20 69 73 20  ring pointer is 
2ea00 76 61 6c 69 64 20 75 6e 74 69 6c 20 65 69 74 68  valid until eith
2ea10 65 72 20 74 68 65 20 5b 70 72 65 70 61 72 65 64  er the [prepared
2ea20 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 69   statement].** i
2ea30 73 20 64 65 73 74 72 6f 79 65 64 20 62 79 20 5b  s destroyed by [
2ea40 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
2ea50 28 29 5d 20 6f 72 20 75 6e 74 69 6c 20 74 68 65  ()] or until the
2ea60 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 75   statement is au
2ea70 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 72  tomatically.** r
2ea80 65 70 72 65 70 61 72 65 64 20 62 79 20 74 68 65  eprepared by the
2ea90 20 66 69 72 73 74 20 63 61 6c 6c 20 74 6f 20 5b   first call to [
2eaa0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
2eab0 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61 72  for a particular
2eac0 20 72 75 6e 0a 2a 2a 20 6f 72 20 75 6e 74 69 6c   run.** or until
2ead0 20 74 68 65 20 6e 65 78 74 20 63 61 6c 6c 20 74   the next call t
2eae0 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c  o.** sqlite3_col
2eaf0 75 6d 6e 5f 6e 61 6d 65 28 29 20 6f 72 20 73 71  umn_name() or sq
2eb00 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d  lite3_column_nam
2eb10 65 31 36 28 29 20 6f 6e 20 74 68 65 20 73 61 6d  e16() on the sam
2eb20 65 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20  e column..**.** 
2eb30 5e 49 66 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  ^If sqlite3_mall
2eb40 6f 63 28 29 20 66 61 69 6c 73 20 64 75 72 69 6e  oc() fails durin
2eb50 67 20 74 68 65 20 70 72 6f 63 65 73 73 69 6e 67  g the processing
2eb60 20 6f 66 20 65 69 74 68 65 72 20 72 6f 75 74 69   of either routi
2eb70 6e 65 0a 2a 2a 20 28 66 6f 72 20 65 78 61 6d 70  ne.** (for examp
2eb80 6c 65 20 64 75 72 69 6e 67 20 61 20 63 6f 6e 76  le during a conv
2eb90 65 72 73 69 6f 6e 20 66 72 6f 6d 20 55 54 46 2d  ersion from UTF-
2eba0 38 20 74 6f 20 55 54 46 2d 31 36 29 20 74 68 65  8 to UTF-16) the
2ebb0 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e  n a.** NULL poin
2ebc0 74 65 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e  ter is returned.
2ebd0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65  .**.** ^The name
2ebe0 20 6f 66 20 61 20 72 65 73 75 6c 74 20 63 6f 6c   of a result col
2ebf0 75 6d 6e 20 69 73 20 74 68 65 20 76 61 6c 75 65  umn is the value
2ec00 20 6f 66 20 74 68 65 20 22 41 53 22 20 63 6c 61   of the "AS" cla
2ec10 75 73 65 20 66 6f 72 0a 2a 2a 20 74 68 61 74 20  use for.** that 
2ec20 63 6f 6c 75 6d 6e 2c 20 69 66 20 74 68 65 72 65  column, if there
2ec30 20 69 73 20 61 6e 20 41 53 20 63 6c 61 75 73 65   is an AS clause
2ec40 2e 20 20 49 66 20 74 68 65 72 65 20 69 73 20 6e  .  If there is n
2ec50 6f 20 41 53 20 63 6c 61 75 73 65 0a 2a 2a 20 74  o AS clause.** t
2ec60 68 65 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 20  hen the name of 
2ec70 74 68 65 20 63 6f 6c 75 6d 6e 20 69 73 20 75 6e  the column is un
2ec80 73 70 65 63 69 66 69 65 64 20 61 6e 64 20 6d 61  specified and ma
2ec90 79 20 63 68 61 6e 67 65 20 66 72 6f 6d 0a 2a 2a  y change from.**
2eca0 20 6f 6e 65 20 72 65 6c 65 61 73 65 20 6f 66 20   one release of 
2ecb0 53 51 4c 69 74 65 20 74 6f 20 74 68 65 20 6e 65  SQLite to the ne
2ecc0 78 74 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61  xt..*/.const cha
2ecd0 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  r *sqlite3_colum
2ece0 6e 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73  n_name(sqlite3_s
2ecf0 74 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 63 6f  tmt*, int N);.co
2ed00 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
2ed10 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28  3_column_name16(
2ed20 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
2ed30 6e 74 20 4e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  nt N);../*.** CA
2ed40 50 49 33 52 45 46 3a 20 53 6f 75 72 63 65 20 4f  PI3REF: Source O
2ed50 66 20 44 61 74 61 20 49 6e 20 41 20 51 75 65 72  f Data In A Quer
2ed60 79 20 52 65 73 75 6c 74 0a 2a 2a 20 4d 45 54 48  y Result.** METH
2ed70 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  OD: sqlite3_stmt
2ed80 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f  .**.** ^These ro
2ed90 75 74 69 6e 65 73 20 70 72 6f 76 69 64 65 20 61  utines provide a
2eda0 20 6d 65 61 6e 73 20 74 6f 20 64 65 74 65 72 6d   means to determ
2edb0 69 6e 65 20 74 68 65 20 64 61 74 61 62 61 73 65  ine the database
2edc0 2c 20 74 61 62 6c 65 2c 20 61 6e 64 0a 2a 2a 20  , table, and.** 
2edd0 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61  table column tha
2ede0 74 20 69 73 20 74 68 65 20 6f 72 69 67 69 6e 20  t is the origin 
2edf0 6f 66 20 61 20 70 61 72 74 69 63 75 6c 61 72 20  of a particular 
2ee00 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 6e  result column in
2ee10 0a 2a 2a 20 5b 53 45 4c 45 43 54 5d 20 73 74 61  .** [SELECT] sta
2ee20 74 65 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20  tement..** ^The 
2ee30 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61  name of the data
2ee40 62 61 73 65 20 6f 72 20 74 61 62 6c 65 20 6f 72  base or table or
2ee50 20 63 6f 6c 75 6d 6e 20 63 61 6e 20 62 65 20 72   column can be r
2ee60 65 74 75 72 6e 65 64 20 61 73 0a 2a 2a 20 65 69  eturned as.** ei
2ee70 74 68 65 72 20 61 20 55 54 46 2d 38 20 6f 72 20  ther a UTF-8 or 
2ee80 55 54 46 2d 31 36 20 73 74 72 69 6e 67 2e 20 20  UTF-16 string.  
2ee90 5e 54 68 65 20 5f 64 61 74 61 62 61 73 65 5f 20  ^The _database_ 
2eea0 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 0a  routines return.
2eeb0 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ** the database 
2eec0 6e 61 6d 65 2c 20 74 68 65 20 5f 74 61 62 6c 65  name, the _table
2eed0 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  _ routines retur
2eee0 6e 20 74 68 65 20 74 61 62 6c 65 20 6e 61 6d 65  n the table name
2eef0 2c 20 61 6e 64 0a 2a 2a 20 74 68 65 20 6f 72 69  , and.** the ori
2ef00 67 69 6e 5f 20 72 6f 75 74 69 6e 65 73 20 72 65  gin_ routines re
2ef10 74 75 72 6e 20 74 68 65 20 63 6f 6c 75 6d 6e 20  turn the column 
2ef20 6e 61 6d 65 2e 0a 2a 2a 20 5e 54 68 65 20 72 65  name..** ^The re
2ef30 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73  turned string is
2ef40 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 74 68 65   valid until the
2ef50 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2ef60 6d 65 6e 74 5d 20 69 73 20 64 65 73 74 72 6f 79  ment] is destroy
2ef70 65 64 0a 2a 2a 20 75 73 69 6e 67 20 5b 73 71 6c  ed.** using [sql
2ef80 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
2ef90 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 73 74   or until the st
2efa0 61 74 65 6d 65 6e 74 20 69 73 20 61 75 74 6f 6d  atement is autom
2efb0 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 72 65 70 72  atically.** repr
2efc0 65 70 61 72 65 64 20 62 79 20 74 68 65 20 66 69  epared by the fi
2efd0 72 73 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  rst call to [sql
2efe0 69 74 65 33 5f 73 74 65 70 28 29 5d 20 66 6f 72  ite3_step()] for
2eff0 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 72 75   a particular ru
2f000 6e 0a 2a 2a 20 6f 72 20 75 6e 74 69 6c 20 74 68  n.** or until th
2f010 65 20 73 61 6d 65 20 69 6e 66 6f 72 6d 61 74 69  e same informati
2f020 6f 6e 20 69 73 20 72 65 71 75 65 73 74 65 64 0a  on is requested.
2f030 2a 2a 20 61 67 61 69 6e 20 69 6e 20 61 20 64 69  ** again in a di
2f040 66 66 65 72 65 6e 74 20 65 6e 63 6f 64 69 6e 67  fferent encoding
2f050 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d  ..**.** ^The nam
2f060 65 73 20 72 65 74 75 72 6e 65 64 20 61 72 65 20  es returned are 
2f070 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 75 6e 2d  the original un-
2f080 61 6c 69 61 73 65 64 20 6e 61 6d 65 73 20 6f 66  aliased names of
2f090 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65   the.** database
2f0a0 2c 20 74 61 62 6c 65 2c 20 61 6e 64 20 63 6f 6c  , table, and col
2f0b0 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  umn..**.** ^The 
2f0c0 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74  first argument t
2f0d0 6f 20 74 68 65 73 65 20 69 6e 74 65 72 66 61 63  o these interfac
2f0e0 65 73 20 69 73 20 61 20 5b 70 72 65 70 61 72 65  es is a [prepare
2f0f0 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a  d statement]..**
2f100 20 5e 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e   ^These function
2f110 73 20 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d 61  s return informa
2f120 74 69 6f 6e 20 61 62 6f 75 74 20 74 68 65 20 4e  tion about the N
2f130 74 68 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e  th result column
2f140 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20   returned by.** 
2f150 74 68 65 20 73 74 61 74 65 6d 65 6e 74 2c 20 77  the statement, w
2f160 68 65 72 65 20 4e 20 69 73 20 74 68 65 20 73 65  here N is the se
2f170 63 6f 6e 64 20 66 75 6e 63 74 69 6f 6e 20 61 72  cond function ar
2f180 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20  gument..** ^The 
2f190 6c 65 66 74 2d 6d 6f 73 74 20 63 6f 6c 75 6d 6e  left-most column
2f1a0 20 69 73 20 63 6f 6c 75 6d 6e 20 30 20 66 6f 72   is column 0 for
2f1b0 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e   these routines.
2f1c0 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 4e  .**.** ^If the N
2f1d0 74 68 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e  th column return
2f1e0 65 64 20 62 79 20 74 68 65 20 73 74 61 74 65 6d  ed by the statem
2f1f0 65 6e 74 20 69 73 20 61 6e 20 65 78 70 72 65 73  ent is an expres
2f200 73 69 6f 6e 20 6f 72 0a 2a 2a 20 73 75 62 71 75  sion or.** subqu
2f210 65 72 79 20 61 6e 64 20 69 73 20 6e 6f 74 20 61  ery and is not a
2f220 20 63 6f 6c 75 6d 6e 20 76 61 6c 75 65 2c 20 74   column value, t
2f230 68 65 6e 20 61 6c 6c 20 6f 66 20 74 68 65 73 65  hen all of these
2f240 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72   functions retur
2f250 6e 0a 2a 2a 20 4e 55 4c 4c 2e 20 20 5e 54 68 65  n.** NULL.  ^The
2f260 73 65 20 72 6f 75 74 69 6e 65 20 6d 69 67 68 74  se routine might
2f270 20 61 6c 73 6f 20 72 65 74 75 72 6e 20 4e 55 4c   also return NUL
2f280 4c 20 69 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c  L if a memory al
2f290 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 0a 2a  location error.*
2f2a0 2a 20 6f 63 63 75 72 73 2e 20 20 5e 4f 74 68 65  * occurs.  ^Othe
2f2b0 72 77 69 73 65 2c 20 74 68 65 79 20 72 65 74 75  rwise, they retu
2f2c0 72 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  rn the name of t
2f2d0 68 65 20 61 74 74 61 63 68 65 64 20 64 61 74 61  he attached data
2f2e0 62 61 73 65 2c 20 74 61 62 6c 65 2c 0a 2a 2a 20  base, table,.** 
2f2f0 6f 72 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 71  or column that q
2f300 75 65 72 79 20 72 65 73 75 6c 74 20 63 6f 6c 75  uery result colu
2f310 6d 6e 20 77 61 73 20 65 78 74 72 61 63 74 65 64  mn was extracted
2f320 20 66 72 6f 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73   from..**.** ^As
2f330 20 77 69 74 68 20 61 6c 6c 20 6f 74 68 65 72 20   with all other 
2f340 53 51 4c 69 74 65 20 41 50 49 73 2c 20 74 68 6f  SQLite APIs, tho
2f350 73 65 20 77 68 6f 73 65 20 6e 61 6d 65 73 20 65  se whose names e
2f360 6e 64 20 77 69 74 68 20 22 31 36 22 20 72 65 74  nd with "16" ret
2f370 75 72 6e 0a 2a 2a 20 55 54 46 2d 31 36 20 65 6e  urn.** UTF-16 en
2f380 63 6f 64 65 64 20 73 74 72 69 6e 67 73 20 61 6e  coded strings an
2f390 64 20 74 68 65 20 6f 74 68 65 72 20 66 75 6e 63  d the other func
2f3a0 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 55 54 46  tions return UTF
2f3b0 2d 38 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65  -8..**.** ^These
2f3c0 20 41 50 49 73 20 61 72 65 20 6f 6e 6c 79 20 61   APIs are only a
2f3d0 76 61 69 6c 61 62 6c 65 20 69 66 20 74 68 65 20  vailable if the 
2f3e0 6c 69 62 72 61 72 79 20 77 61 73 20 63 6f 6d 70  library was comp
2f3f0 69 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a  iled with the.**
2f400 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f   [SQLITE_ENABLE_
2f410 43 4f 4c 55 4d 4e 5f 4d 45 54 41 44 41 54 41 5d  COLUMN_METADATA]
2f420 20 43 2d 70 72 65 70 72 6f 63 65 73 73 6f 72 20   C-preprocessor 
2f430 73 79 6d 62 6f 6c 2e 0a 2a 2a 0a 2a 2a 20 49 66  symbol..**.** If
2f440 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 74 68 72   two or more thr
2f450 65 61 64 73 20 63 61 6c 6c 20 6f 6e 65 20 6f 72  eads call one or
2f460 20 6d 6f 72 65 20 6f 66 20 74 68 65 73 65 20 72   more of these r
2f470 6f 75 74 69 6e 65 73 20 61 67 61 69 6e 73 74 20  outines against 
2f480 74 68 65 20 73 61 6d 65 0a 2a 2a 20 70 72 65 70  the same.** prep
2f490 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 61  ared statement a
2f4a0 6e 64 20 63 6f 6c 75 6d 6e 20 61 74 20 74 68 65  nd column at the
2f4b0 20 73 61 6d 65 20 74 69 6d 65 20 74 68 65 6e 20   same time then 
2f4c0 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 0a  the results are.
2f4d0 2a 2a 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  ** undefined..**
2f4e0 0a 2a 2a 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f  .** If two or mo
2f4f0 72 65 20 74 68 72 65 61 64 73 20 63 61 6c 6c 20  re threads call 
2f500 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 5b  one or more.** [
2f510 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64  sqlite3_column_d
2f520 61 74 61 62 61 73 65 5f 6e 61 6d 65 20 7c 20 63  atabase_name | c
2f530 6f 6c 75 6d 6e 20 6d 65 74 61 64 61 74 61 20 69  olumn metadata i
2f540 6e 74 65 72 66 61 63 65 73 5d 0a 2a 2a 20 66 6f  nterfaces].** fo
2f550 72 20 74 68 65 20 73 61 6d 65 20 5b 70 72 65 70  r the same [prep
2f560 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
2f570 61 6e 64 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d  and result colum
2f580 6e 0a 2a 2a 20 61 74 20 74 68 65 20 73 61 6d 65  n.** at the same
2f590 20 74 69 6d 65 20 74 68 65 6e 20 74 68 65 20 72   time then the r
2f5a0 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66  esults are undef
2f5b0 69 6e 65 64 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63  ined..*/.const c
2f5c0 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  har *sqlite3_col
2f5d0 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d  umn_database_nam
2f5e0 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
2f5f0 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64  int);.const void
2f600 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
2f610 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 31 36  _database_name16
2f620 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69  (sqlite3_stmt*,i
2f630 6e 74 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20  nt);.const char 
2f640 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
2f650 74 61 62 6c 65 5f 6e 61 6d 65 28 73 71 6c 69 74  table_name(sqlit
2f660 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63  e3_stmt*,int);.c
2f670 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
2f680 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f  e3_column_table_
2f690 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73  name16(sqlite3_s
2f6a0 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74  tmt*,int);.const
2f6b0 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63   char *sqlite3_c
2f6c0 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d  olumn_origin_nam
2f6d0 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
2f6e0 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64  int);.const void
2f6f0 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
2f700 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 31 36 28 73  _origin_name16(s
2f710 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74  qlite3_stmt*,int
2f720 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2f730 45 46 3a 20 44 65 63 6c 61 72 65 64 20 44 61 74  EF: Declared Dat
2f740 61 74 79 70 65 20 4f 66 20 41 20 51 75 65 72 79  atype Of A Query
2f750 20 52 65 73 75 6c 74 0a 2a 2a 20 4d 45 54 48 4f   Result.** METHO
2f760 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a  D: sqlite3_stmt.
2f770 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 66 69 72 73  **.** ^(The firs
2f780 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61  t parameter is a
2f790 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2f7a0 6d 65 6e 74 5d 2e 0a 2a 2a 20 49 66 20 74 68 69  ment]..** If thi
2f7b0 73 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61  s statement is a
2f7c0 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d   [SELECT] statem
2f7d0 65 6e 74 20 61 6e 64 20 74 68 65 20 4e 74 68 20  ent and the Nth 
2f7e0 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 0a 2a 2a  column of the.**
2f7f0 20 72 65 74 75 72 6e 65 64 20 72 65 73 75 6c 74   returned result
2f800 20 73 65 74 20 6f 66 20 74 68 61 74 20 5b 53 45   set of that [SE
2f810 4c 45 43 54 5d 20 69 73 20 61 20 74 61 62 6c 65  LECT] is a table
2f820 20 63 6f 6c 75 6d 6e 20 28 6e 6f 74 20 61 6e 0a   column (not an.
2f830 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72  ** expression or
2f840 20 73 75 62 71 75 65 72 79 29 20 74 68 65 6e 20   subquery) then 
2f850 74 68 65 20 64 65 63 6c 61 72 65 64 20 74 79 70  the declared typ
2f860 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65 0a 2a  e of the table.*
2f870 2a 20 63 6f 6c 75 6d 6e 20 69 73 20 72 65 74 75  * column is retu
2f880 72 6e 65 64 2e 29 5e 20 20 5e 49 66 20 74 68 65  rned.)^  ^If the
2f890 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 74   Nth column of t
2f8a0 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 69 73  he result set is
2f8b0 20 61 6e 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f   an.** expressio
2f8c0 6e 20 6f 72 20 73 75 62 71 75 65 72 79 2c 20 74  n or subquery, t
2f8d0 68 65 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  hen a NULL point
2f8e0 65 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a  er is returned..
2f8f0 2a 2a 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64  ** ^The returned
2f900 20 73 74 72 69 6e 67 20 69 73 20 61 6c 77 61 79   string is alway
2f910 73 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 2e  s UTF-8 encoded.
2f920 0a 2a 2a 0a 2a 2a 20 5e 28 46 6f 72 20 65 78 61  .**.** ^(For exa
2f930 6d 70 6c 65 2c 20 67 69 76 65 6e 20 74 68 65 20  mple, given the 
2f940 64 61 74 61 62 61 73 65 20 73 63 68 65 6d 61 3a  database schema:
2f950 0a 2a 2a 0a 2a 2a 20 43 52 45 41 54 45 20 54 41  .**.** CREATE TA
2f960 42 4c 45 20 74 31 28 63 31 20 56 41 52 49 41 4e  BLE t1(c1 VARIAN
2f970 54 29 3b 0a 2a 2a 0a 2a 2a 20 61 6e 64 20 74 68  T);.**.** and th
2f980 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 73 74 61 74  e following stat
2f990 65 6d 65 6e 74 20 74 6f 20 62 65 20 63 6f 6d 70  ement to be comp
2f9a0 69 6c 65 64 3a 0a 2a 2a 0a 2a 2a 20 53 45 4c 45  iled:.**.** SELE
2f9b0 43 54 20 63 31 20 2b 20 31 2c 20 63 31 20 46 52  CT c1 + 1, c1 FR
2f9c0 4f 4d 20 74 31 3b 0a 2a 2a 0a 2a 2a 20 74 68 69  OM t1;.**.** thi
2f9d0 73 20 72 6f 75 74 69 6e 65 20 77 6f 75 6c 64 20  s routine would 
2f9e0 72 65 74 75 72 6e 20 74 68 65 20 73 74 72 69 6e  return the strin
2f9f0 67 20 22 56 41 52 49 41 4e 54 22 20 66 6f 72 20  g "VARIANT" for 
2fa00 74 68 65 20 73 65 63 6f 6e 64 20 72 65 73 75 6c  the second resul
2fa10 74 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d  t.** column (i==
2fa20 31 29 2c 20 61 6e 64 20 61 20 4e 55 4c 4c 20 70  1), and a NULL p
2fa30 6f 69 6e 74 65 72 20 66 6f 72 20 74 68 65 20 66  ointer for the f
2fa40 69 72 73 74 20 72 65 73 75 6c 74 20 63 6f 6c 75  irst result colu
2fa50 6d 6e 20 28 69 3d 3d 30 29 2e 29 5e 0a 2a 2a 0a  mn (i==0).)^.**.
2fa60 2a 2a 20 5e 53 51 4c 69 74 65 20 75 73 65 73 20  ** ^SQLite uses 
2fa70 64 79 6e 61 6d 69 63 20 72 75 6e 2d 74 69 6d 65  dynamic run-time
2fa80 20 74 79 70 69 6e 67 2e 20 20 5e 53 6f 20 6a 75   typing.  ^So ju
2fa90 73 74 20 62 65 63 61 75 73 65 20 61 20 63 6f 6c  st because a col
2faa0 75 6d 6e 0a 2a 2a 20 69 73 20 64 65 63 6c 61 72  umn.** is declar
2fab0 65 64 20 74 6f 20 63 6f 6e 74 61 69 6e 20 61 20  ed to contain a 
2fac0 70 61 72 74 69 63 75 6c 61 72 20 74 79 70 65 20  particular type 
2fad0 64 6f 65 73 20 6e 6f 74 20 6d 65 61 6e 20 74 68  does not mean th
2fae0 61 74 20 74 68 65 0a 2a 2a 20 64 61 74 61 20 73  at the.** data s
2faf0 74 6f 72 65 64 20 69 6e 20 74 68 61 74 20 63 6f  tored in that co
2fb00 6c 75 6d 6e 20 69 73 20 6f 66 20 74 68 65 20 64  lumn is of the d
2fb10 65 63 6c 61 72 65 64 20 74 79 70 65 2e 20 20 53  eclared type.  S
2fb20 51 4c 69 74 65 20 69 73 0a 2a 2a 20 73 74 72 6f  QLite is.** stro
2fb30 6e 67 6c 79 20 74 79 70 65 64 2c 20 62 75 74 20  ngly typed, but 
2fb40 74 68 65 20 74 79 70 69 6e 67 20 69 73 20 64 79  the typing is dy
2fb50 6e 61 6d 69 63 20 6e 6f 74 20 73 74 61 74 69 63  namic not static
2fb60 2e 20 20 5e 54 79 70 65 0a 2a 2a 20 69 73 20 61  .  ^Type.** is a
2fb70 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 69  ssociated with i
2fb80 6e 64 69 76 69 64 75 61 6c 20 76 61 6c 75 65 73  ndividual values
2fb90 2c 20 6e 6f 74 20 77 69 74 68 20 74 68 65 20 63  , not with the c
2fba0 6f 6e 74 61 69 6e 65 72 73 0a 2a 2a 20 75 73 65  ontainers.** use
2fbb0 64 20 74 6f 20 68 6f 6c 64 20 74 68 6f 73 65 20  d to hold those 
2fbc0 76 61 6c 75 65 73 2e 0a 2a 2f 0a 63 6f 6e 73 74  values..*/.const
2fbd0 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63   char *sqlite3_c
2fbe0 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 28 73  olumn_decltype(s
2fbf0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74  qlite3_stmt*,int
2fc00 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  );.const void *s
2fc10 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65  qlite3_column_de
2fc20 63 6c 74 79 70 65 31 36 28 73 71 6c 69 74 65 33  cltype16(sqlite3
2fc30 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a  _stmt*,int);../*
2fc40 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 76  .** CAPI3REF: Ev
2fc50 61 6c 75 61 74 65 20 41 6e 20 53 51 4c 20 53 74  aluate An SQL St
2fc60 61 74 65 6d 65 6e 74 0a 2a 2a 20 4d 45 54 48 4f  atement.** METHO
2fc70 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a  D: sqlite3_stmt.
2fc80 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 61 20 5b 70  **.** After a [p
2fc90 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2fca0 74 5d 20 68 61 73 20 62 65 65 6e 20 70 72 65 70  t] has been prep
2fcb0 61 72 65 64 20 75 73 69 6e 67 20 65 69 74 68 65  ared using eithe
2fcc0 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72  r.** [sqlite3_pr
2fcd0 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b  epare_v2()] or [
2fce0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
2fcf0 36 5f 76 32 28 29 5d 20 6f 72 20 6f 6e 65 20 6f  6_v2()] or one o
2fd00 66 20 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20  f the legacy.** 
2fd10 69 6e 74 65 72 66 61 63 65 73 20 5b 73 71 6c 69  interfaces [sqli
2fd20 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f  te3_prepare()] o
2fd30 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  r [sqlite3_prepa
2fd40 72 65 31 36 28 29 5d 2c 20 74 68 69 73 20 66 75  re16()], this fu
2fd50 6e 63 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 62  nction.** must b
2fd60 65 20 63 61 6c 6c 65 64 20 6f 6e 65 20 6f 72 20  e called one or 
2fd70 6d 6f 72 65 20 74 69 6d 65 73 20 74 6f 20 65 76  more times to ev
2fd80 61 6c 75 61 74 65 20 74 68 65 20 73 74 61 74 65  aluate the state
2fd90 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ment..**.** The 
2fda0 64 65 74 61 69 6c 73 20 6f 66 20 74 68 65 20 62  details of the b
2fdb0 65 68 61 76 69 6f 72 20 6f 66 20 74 68 65 20 73  ehavior of the s
2fdc0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69 6e  qlite3_step() in
2fdd0 74 65 72 66 61 63 65 20 64 65 70 65 6e 64 0a 2a  terface depend.*
2fde0 2a 20 6f 6e 20 77 68 65 74 68 65 72 20 74 68 65  * on whether the
2fdf0 20 73 74 61 74 65 6d 65 6e 74 20 77 61 73 20 70   statement was p
2fe00 72 65 70 61 72 65 64 20 75 73 69 6e 67 20 74 68  repared using th
2fe10 65 20 6e 65 77 65 72 20 22 76 32 22 20 69 6e 74  e newer "v2" int
2fe20 65 72 66 61 63 65 0a 2a 2a 20 5b 73 71 6c 69 74  erface.** [sqlit
2fe30 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
2fe40 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72   and [sqlite3_pr
2fe50 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20 6f 72  epare16_v2()] or
2fe60 20 74 68 65 20 6f 6c 64 65 72 20 6c 65 67 61 63   the older legac
2fe70 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 5b  y.** interface [
2fe80 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28  sqlite3_prepare(
2fe90 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
2fea0 70 72 65 70 61 72 65 31 36 28 29 5d 2e 20 20 54  prepare16()].  T
2feb0 68 65 20 75 73 65 20 6f 66 20 74 68 65 0a 2a 2a  he use of the.**
2fec0 20 6e 65 77 20 22 76 32 22 20 69 6e 74 65 72 66   new "v2" interf
2fed0 61 63 65 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64  ace is recommend
2fee0 65 64 20 66 6f 72 20 6e 65 77 20 61 70 70 6c 69  ed for new appli
2fef0 63 61 74 69 6f 6e 73 20 62 75 74 20 74 68 65 20  cations but the 
2ff00 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66  legacy.** interf
2ff10 61 63 65 20 77 69 6c 6c 20 63 6f 6e 74 69 6e 75  ace will continu
2ff20 65 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65  e to be supporte
2ff30 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 20 74 68 65  d..**.** ^In the
2ff40 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 63   legacy interfac
2ff50 65 2c 20 74 68 65 20 72 65 74 75 72 6e 20 76 61  e, the return va
2ff60 6c 75 65 20 77 69 6c 6c 20 62 65 20 65 69 74 68  lue will be eith
2ff70 65 72 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  er [SQLITE_BUSY]
2ff80 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 4f 4e  ,.** [SQLITE_DON
2ff90 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d  E], [SQLITE_ROW]
2ffa0 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d  , [SQLITE_ERROR]
2ffb0 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4d 49 53  , or [SQLITE_MIS
2ffc0 55 53 45 5d 2e 0a 2a 2a 20 5e 57 69 74 68 20 74  USE]..** ^With t
2ffd0 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63  he "v2" interfac
2ffe0 65 2c 20 61 6e 79 20 6f 66 20 74 68 65 20 6f 74  e, any of the ot
2fff0 68 65 72 20 5b 72 65 73 75 6c 74 20 63 6f 64 65  her [result code
30000 73 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64  s] or.** [extend
30010 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d  ed result codes]
30020 20 6d 69 67 68 74 20 62 65 20 72 65 74 75 72 6e   might be return
30030 65 64 20 61 73 20 77 65 6c 6c 2e 0a 2a 2a 0a 2a  ed as well..**.*
30040 2a 20 5e 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  * ^[SQLITE_BUSY]
30050 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20   means that the 
30060 64 61 74 61 62 61 73 65 20 65 6e 67 69 6e 65 20  database engine 
30070 77 61 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 63  was unable to ac
30080 71 75 69 72 65 20 74 68 65 0a 2a 2a 20 64 61 74  quire the.** dat
30090 61 62 61 73 65 20 6c 6f 63 6b 73 20 69 74 20 6e  abase locks it n
300a0 65 65 64 73 20 74 6f 20 64 6f 20 69 74 73 20 6a  eeds to do its j
300b0 6f 62 2e 20 20 5e 49 66 20 74 68 65 20 73 74 61  ob.  ^If the sta
300c0 74 65 6d 65 6e 74 20 69 73 20 61 20 5b 43 4f 4d  tement is a [COM
300d0 4d 49 54 5d 0a 2a 2a 20 6f 72 20 6f 63 63 75 72  MIT].** or occur
300e0 73 20 6f 75 74 73 69 64 65 20 6f 66 20 61 6e 20  s outside of an 
300f0 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63  explicit transac
30100 74 69 6f 6e 2c 20 74 68 65 6e 20 79 6f 75 20 63  tion, then you c
30110 61 6e 20 72 65 74 72 79 20 74 68 65 0a 2a 2a 20  an retry the.** 
30120 73 74 61 74 65 6d 65 6e 74 2e 20 20 49 66 20 74  statement.  If t
30130 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  he statement is 
30140 6e 6f 74 20 61 20 5b 43 4f 4d 4d 49 54 5d 20 61  not a [COMMIT] a
30150 6e 64 20 6f 63 63 75 72 73 20 77 69 74 68 69 6e  nd occurs within
30160 20 61 6e 0a 2a 2a 20 65 78 70 6c 69 63 69 74 20   an.** explicit 
30170 74 72 61 6e 73 61 63 74 69 6f 6e 20 74 68 65 6e  transaction then
30180 20 79 6f 75 20 73 68 6f 75 6c 64 20 72 6f 6c 6c   you should roll
30190 62 61 63 6b 20 74 68 65 20 74 72 61 6e 73 61 63  back the transac
301a0 74 69 6f 6e 20 62 65 66 6f 72 65 0a 2a 2a 20 63  tion before.** c
301b0 6f 6e 74 69 6e 75 69 6e 67 2e 0a 2a 2a 0a 2a 2a  ontinuing..**.**
301c0 20 5e 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 20   ^[SQLITE_DONE] 
301d0 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 73  means that the s
301e0 74 61 74 65 6d 65 6e 74 20 68 61 73 20 66 69 6e  tatement has fin
301f0 69 73 68 65 64 20 65 78 65 63 75 74 69 6e 67 0a  ished executing.
30200 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2e  ** successfully.
30210 20 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29    sqlite3_step()
30220 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63   should not be c
30230 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e 20 74  alled again on t
30240 68 69 73 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d  his virtual.** m
30250 61 63 68 69 6e 65 20 77 69 74 68 6f 75 74 20 66  achine without f
30260 69 72 73 74 20 63 61 6c 6c 69 6e 67 20 5b 73 71  irst calling [sq
30270 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 74  lite3_reset()] t
30280 6f 20 72 65 73 65 74 20 74 68 65 20 76 69 72 74  o reset the virt
30290 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 62  ual.** machine b
302a0 61 63 6b 20 74 6f 20 69 74 73 20 69 6e 69 74 69  ack to its initi
302b0 61 6c 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20  al state..**.** 
302c0 5e 49 66 20 74 68 65 20 53 51 4c 20 73 74 61 74  ^If the SQL stat
302d0 65 6d 65 6e 74 20 62 65 69 6e 67 20 65 78 65 63  ement being exec
302e0 75 74 65 64 20 72 65 74 75 72 6e 73 20 61 6e 79  uted returns any
302f0 20 64 61 74 61 2c 20 74 68 65 6e 20 5b 53 51 4c   data, then [SQL
30300 49 54 45 5f 52 4f 57 5d 0a 2a 2a 20 69 73 20 72  ITE_ROW].** is r
30310 65 74 75 72 6e 65 64 20 65 61 63 68 20 74 69 6d  eturned each tim
30320 65 20 61 20 6e 65 77 20 72 6f 77 20 6f 66 20 64  e a new row of d
30330 61 74 61 20 69 73 20 72 65 61 64 79 20 66 6f 72  ata is ready for
30340 20 70 72 6f 63 65 73 73 69 6e 67 20 62 79 20 74   processing by t
30350 68 65 0a 2a 2a 20 63 61 6c 6c 65 72 2e 20 54 68  he.** caller. Th
30360 65 20 76 61 6c 75 65 73 20 6d 61 79 20 62 65 20  e values may be 
30370 61 63 63 65 73 73 65 64 20 75 73 69 6e 67 20 74  accessed using t
30380 68 65 20 5b 63 6f 6c 75 6d 6e 20 61 63 63 65 73  he [column acces
30390 73 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a  s functions]..**
303a0 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20   sqlite3_step() 
303b0 69 73 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20  is called again 
303c0 74 6f 20 72 65 74 72 69 65 76 65 20 74 68 65 20  to retrieve the 
303d0 6e 65 78 74 20 72 6f 77 20 6f 66 20 64 61 74 61  next row of data
303e0 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45  ..**.** ^[SQLITE
303f0 5f 45 52 52 4f 52 5d 20 6d 65 61 6e 73 20 74 68  _ERROR] means th
30400 61 74 20 61 20 72 75 6e 2d 74 69 6d 65 20 65 72  at a run-time er
30410 72 6f 72 20 28 73 75 63 68 20 61 73 20 61 20 63  ror (such as a c
30420 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a 20 76 69 6f  onstraint.** vio
30430 6c 61 74 69 6f 6e 29 20 68 61 73 20 6f 63 63 75  lation) has occu
30440 72 72 65 64 2e 20 20 73 71 6c 69 74 65 33 5f 73  rred.  sqlite3_s
30450 74 65 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74  tep() should not
30460 20 62 65 20 63 61 6c 6c 65 64 20 61 67 61 69 6e   be called again
30470 20 6f 6e 0a 2a 2a 20 74 68 65 20 56 4d 2e 20 4d   on.** the VM. M
30480 6f 72 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  ore information 
30490 6d 61 79 20 62 65 20 66 6f 75 6e 64 20 62 79 20  may be found by 
304a0 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33  calling [sqlite3
304b0 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2a 20 5e  _errmsg()]..** ^
304c0 57 69 74 68 20 74 68 65 20 6c 65 67 61 63 79 20  With the legacy 
304d0 69 6e 74 65 72 66 61 63 65 2c 20 61 20 6d 6f 72  interface, a mor
304e0 65 20 73 70 65 63 69 66 69 63 20 65 72 72 6f 72  e specific error
304f0 20 63 6f 64 65 20 28 66 6f 72 20 65 78 61 6d 70   code (for examp
30500 6c 65 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49  le,.** [SQLITE_I
30510 4e 54 45 52 52 55 50 54 5d 2c 20 5b 53 51 4c 49  NTERRUPT], [SQLI
30520 54 45 5f 53 43 48 45 4d 41 5d 2c 20 5b 53 51 4c  TE_SCHEMA], [SQL
30530 49 54 45 5f 43 4f 52 52 55 50 54 5d 2c 20 61 6e  ITE_CORRUPT], an
30540 64 20 73 6f 20 66 6f 72 74 68 29 0a 2a 2a 20 63  d so forth).** c
30550 61 6e 20 62 65 20 6f 62 74 61 69 6e 65 64 20 62  an be obtained b
30560 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74  y calling [sqlit
30570 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 6e 20 74  e3_reset()] on t
30580 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20  he.** [prepared 
30590 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20 5e 49 6e  statement].  ^In
305a0 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66   the "v2" interf
305b0 61 63 65 2c 0a 2a 2a 20 74 68 65 20 6d 6f 72 65  ace,.** the more
305c0 20 73 70 65 63 69 66 69 63 20 65 72 72 6f 72 20   specific error 
305d0 63 6f 64 65 20 69 73 20 72 65 74 75 72 6e 65 64  code is returned
305e0 20 64 69 72 65 63 74 6c 79 20 62 79 20 73 71 6c   directly by sql
305f0 69 74 65 33 5f 73 74 65 70 28 29 2e 0a 2a 2a 0a  ite3_step()..**.
30600 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53  ** [SQLITE_MISUS
30610 45 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68  E] means that th
30620 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77  e this routine w
30630 61 73 20 63 61 6c 6c 65 64 20 69 6e 61 70 70 72  as called inappr
30640 6f 70 72 69 61 74 65 6c 79 2e 0a 2a 2a 20 50 65  opriately..** Pe
30650 72 68 61 70 73 20 69 74 20 77 61 73 20 63 61 6c  rhaps it was cal
30660 6c 65 64 20 6f 6e 20 61 20 5b 70 72 65 70 61 72  led on a [prepar
30670 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68  ed statement] th
30680 61 74 20 68 61 73 0a 2a 2a 20 61 6c 72 65 61 64  at has.** alread
30690 79 20 62 65 65 6e 20 5b 73 71 6c 69 74 65 33 5f  y been [sqlite3_
306a0 66 69 6e 61 6c 69 7a 65 20 7c 20 66 69 6e 61 6c  finalize | final
306b0 69 7a 65 64 5d 20 6f 72 20 6f 6e 20 6f 6e 65 20  ized] or on one 
306c0 74 68 61 74 20 68 61 64 0a 2a 2a 20 70 72 65 76  that had.** prev
306d0 69 6f 75 73 6c 79 20 72 65 74 75 72 6e 65 64 20  iously returned 
306e0 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 6f  [SQLITE_ERROR] o
306f0 72 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e  r [SQLITE_DONE].
30700 20 20 4f 72 20 69 74 20 63 6f 75 6c 64 0a 2a 2a    Or it could.**
30710 20 62 65 20 74 68 65 20 63 61 73 65 20 74 68 61   be the case tha
30720 74 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62  t the same datab
30730 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69  ase connection i
30740 73 20 62 65 69 6e 67 20 75 73 65 64 20 62 79 20  s being used by 
30750 74 77 6f 20 6f 72 0a 2a 2a 20 6d 6f 72 65 20 74  two or.** more t
30760 68 72 65 61 64 73 20 61 74 20 74 68 65 20 73 61  hreads at the sa
30770 6d 65 20 6d 6f 6d 65 6e 74 20 69 6e 20 74 69 6d  me moment in tim
30780 65 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 61 6c 6c  e..**.** For all
30790 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c   versions of SQL
307a0 69 74 65 20 75 70 20 74 6f 20 61 6e 64 20 69 6e  ite up to and in
307b0 63 6c 75 64 69 6e 67 20 33 2e 36 2e 32 33 2e 31  cluding 3.6.23.1
307c0 2c 20 61 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b  , a call to.** [
307d0 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
307e0 20 77 61 73 20 72 65 71 75 69 72 65 64 20 61 66   was required af
307f0 74 65 72 20 73 71 6c 69 74 65 33 5f 73 74 65 70  ter sqlite3_step
30800 28 29 20 72 65 74 75 72 6e 65 64 20 61 6e 79 74  () returned anyt
30810 68 69 6e 67 0a 2a 2a 20 6f 74 68 65 72 20 74 68  hing.** other th
30820 61 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20  an [SQLITE_ROW] 
30830 62 65 66 6f 72 65 20 61 6e 79 20 73 75 62 73 65  before any subse
30840 71 75 65 6e 74 20 69 6e 76 6f 63 61 74 69 6f 6e  quent invocation
30850 20 6f 66 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73   of.** sqlite3_s
30860 74 65 70 28 29 2e 20 20 46 61 69 6c 75 72 65 20  tep().  Failure 
30870 74 6f 20 72 65 73 65 74 20 74 68 65 20 70 72 65  to reset the pre
30880 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20  pared statement 
30890 75 73 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c 69 74  using .** [sqlit
308a0 65 33 5f 72 65 73 65 74 28 29 5d 20 77 6f 75 6c  e3_reset()] woul
308b0 64 20 72 65 73 75 6c 74 20 69 6e 20 61 6e 20 5b  d result in an [
308c0 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 72  SQLITE_MISUSE] r
308d0 65 74 75 72 6e 20 66 72 6f 6d 0a 2a 2a 20 73 71  eturn from.** sq
308e0 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 20 20 42  lite3_step().  B
308f0 75 74 20 61 66 74 65 72 20 76 65 72 73 69 6f 6e  ut after version
30900 20 33 2e 36 2e 32 33 2e 31 2c 20 73 71 6c 69 74   3.6.23.1, sqlit
30910 65 33 5f 73 74 65 70 28 29 20 62 65 67 61 6e 0a  e3_step() began.
30920 2a 2a 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69  ** calling [sqli
30930 74 65 33 5f 72 65 73 65 74 28 29 5d 20 61 75 74  te3_reset()] aut
30940 6f 6d 61 74 69 63 61 6c 6c 79 20 69 6e 20 74 68  omatically in th
30950 69 73 20 63 69 72 63 75 6d 73 74 61 6e 63 65 20  is circumstance 
30960 72 61 74 68 65 72 0a 2a 2a 20 74 68 61 6e 20 72  rather.** than r
30970 65 74 75 72 6e 69 6e 67 20 5b 53 51 4c 49 54 45  eturning [SQLITE
30980 5f 4d 49 53 55 53 45 5d 2e 20 20 54 68 69 73 20  _MISUSE].  This 
30990 69 73 20 6e 6f 74 20 63 6f 6e 73 69 64 65 72 65  is not considere
309a0 64 20 61 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  d a compatibilit
309b0 79 0a 2a 2a 20 62 72 65 61 6b 20 62 65 63 61 75  y.** break becau
309c0 73 65 20 61 6e 79 20 61 70 70 6c 69 63 61 74 69  se any applicati
309d0 6f 6e 20 74 68 61 74 20 65 76 65 72 20 72 65 63  on that ever rec
309e0 65 69 76 65 73 20 61 6e 20 53 51 4c 49 54 45 5f  eives an SQLITE_
309f0 4d 49 53 55 53 45 20 65 72 72 6f 72 0a 2a 2a 20  MISUSE error.** 
30a00 69 73 20 62 72 6f 6b 65 6e 20 62 79 20 64 65 66  is broken by def
30a10 69 6e 69 74 69 6f 6e 2e 20 20 54 68 65 20 5b 53  inition.  The [S
30a20 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 52  QLITE_OMIT_AUTOR
30a30 45 53 45 54 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  ESET] compile-ti
30a40 6d 65 20 6f 70 74 69 6f 6e 0a 2a 2a 20 63 61 6e  me option.** can
30a50 20 62 65 20 75 73 65 64 20 74 6f 20 72 65 73 74   be used to rest
30a60 6f 72 65 20 74 68 65 20 6c 65 67 61 63 79 20 62  ore the legacy b
30a70 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 3c  ehavior..**.** <
30a80 62 3e 47 6f 6f 66 79 20 49 6e 74 65 72 66 61 63  b>Goofy Interfac
30a90 65 20 41 6c 65 72 74 3a 3c 2f 62 3e 20 49 6e 20  e Alert:</b> In 
30aa0 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72  the legacy inter
30ab0 66 61 63 65 2c 20 74 68 65 20 73 71 6c 69 74 65  face, the sqlite
30ac0 33 5f 73 74 65 70 28 29 0a 2a 2a 20 41 50 49 20  3_step().** API 
30ad0 61 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20 61  always returns a
30ae0 20 67 65 6e 65 72 69 63 20 65 72 72 6f 72 20 63   generic error c
30af0 6f 64 65 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52  ode, [SQLITE_ERR
30b00 4f 52 5d 2c 20 66 6f 6c 6c 6f 77 69 6e 67 20 61  OR], following a
30b10 6e 79 0a 2a 2a 20 65 72 72 6f 72 20 6f 74 68 65  ny.** error othe
30b20 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 42  r than [SQLITE_B
30b30 55 53 59 5d 20 61 6e 64 20 5b 53 51 4c 49 54 45  USY] and [SQLITE
30b40 5f 4d 49 53 55 53 45 5d 2e 20 20 59 6f 75 20 6d  _MISUSE].  You m
30b50 75 73 74 20 63 61 6c 6c 0a 2a 2a 20 5b 73 71 6c  ust call.** [sql
30b60 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72  ite3_reset()] or
30b70 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
30b80 7a 65 28 29 5d 20 69 6e 20 6f 72 64 65 72 20 74  ze()] in order t
30b90 6f 20 66 69 6e 64 20 6f 6e 65 20 6f 66 20 74 68  o find one of th
30ba0 65 0a 2a 2a 20 73 70 65 63 69 66 69 63 20 5b 65  e.** specific [e
30bb0 72 72 6f 72 20 63 6f 64 65 73 5d 20 74 68 61 74  rror codes] that
30bc0 20 62 65 74 74 65 72 20 64 65 73 63 72 69 62 65   better describe
30bd0 73 20 74 68 65 20 65 72 72 6f 72 2e 0a 2a 2a 20  s the error..** 
30be0 57 65 20 61 64 6d 69 74 20 74 68 61 74 20 74 68  We admit that th
30bf0 69 73 20 69 73 20 61 20 67 6f 6f 66 79 20 64 65  is is a goofy de
30c00 73 69 67 6e 2e 20 20 54 68 65 20 70 72 6f 62 6c  sign.  The probl
30c10 65 6d 20 68 61 73 20 62 65 65 6e 20 66 69 78 65  em has been fixe
30c20 64 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 22 76  d.** with the "v
30c30 32 22 20 69 6e 74 65 72 66 61 63 65 2e 20 20 49  2" interface.  I
30c40 66 20 79 6f 75 20 70 72 65 70 61 72 65 20 61 6c  f you prepare al
30c50 6c 20 6f 66 20 79 6f 75 72 20 53 51 4c 20 73 74  l of your SQL st
30c60 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 75 73 69 6e  atements.** usin
30c70 67 20 65 69 74 68 65 72 20 5b 73 71 6c 69 74 65  g either [sqlite
30c80 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
30c90 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  or [sqlite3_prep
30ca0 61 72 65 31 36 5f 76 32 28 29 5d 20 69 6e 73 74  are16_v2()] inst
30cb0 65 61 64 0a 2a 2a 20 6f 66 20 74 68 65 20 6c 65  ead.** of the le
30cc0 67 61 63 79 20 5b 73 71 6c 69 74 65 33 5f 70 72  gacy [sqlite3_pr
30cd0 65 70 61 72 65 28 29 5d 20 61 6e 64 20 5b 73 71  epare()] and [sq
30ce0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28  lite3_prepare16(
30cf0 29 5d 20 69 6e 74 65 72 66 61 63 65 73 2c 0a 2a  )] interfaces,.*
30d00 2a 20 74 68 65 6e 20 74 68 65 20 6d 6f 72 65 20  * then the more 
30d10 73 70 65 63 69 66 69 63 20 5b 65 72 72 6f 72 20  specific [error 
30d20 63 6f 64 65 73 5d 20 61 72 65 20 72 65 74 75 72  codes] are retur
30d30 6e 65 64 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20  ned directly.** 
30d40 62 79 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  by sqlite3_step(
30d50 29 2e 20 20 54 68 65 20 75 73 65 20 6f 66 20 74  ).  The use of t
30d60 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63  he "v2" interfac
30d70 65 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64  e is recommended
30d80 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
30d90 5f 73 74 65 70 28 73 71 6c 69 74 65 33 5f 73 74  _step(sqlite3_st
30da0 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  mt*);../*.** CAP
30db0 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 6f 66  I3REF: Number of
30dc0 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 72 65   columns in a re
30dd0 73 75 6c 74 20 73 65 74 0a 2a 2a 20 4d 45 54 48  sult set.** METH
30de0 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  OD: sqlite3_stmt
30df0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
30e00 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50  te3_data_count(P
30e10 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ) interface retu
30e20 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  rns the number o
30e30 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65  f columns in the
30e40 0a 2a 2a 20 63 75 72 72 65 6e 74 20 72 6f 77 20  .** current row 
30e50 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65  of the result se
30e60 74 20 6f 66 20 5b 70 72 65 70 61 72 65 64 20 73  t of [prepared s
30e70 74 61 74 65 6d 65 6e 74 5d 20 50 2e 0a 2a 2a 20  tatement] P..** 
30e80 5e 49 66 20 70 72 65 70 61 72 65 64 20 73 74 61  ^If prepared sta
30e90 74 65 6d 65 6e 74 20 50 20 64 6f 65 73 20 6e 6f  tement P does no
30ea0 74 20 68 61 76 65 20 72 65 73 75 6c 74 73 20 72  t have results r
30eb0 65 61 64 79 20 74 6f 20 72 65 74 75 72 6e 0a 2a  eady to return.*
30ec0 2a 20 28 76 69 61 20 63 61 6c 6c 73 20 74 6f 20  * (via calls to 
30ed0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  the [sqlite3_col
30ee0 75 6d 6e 5f 69 6e 74 20 7c 20 73 71 6c 69 74 65  umn_int | sqlite
30ef0 33 5f 63 6f 6c 75 6d 6e 5f 2a 28 29 5d 20 6f 66  3_column_*()] of
30f00 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 29 20  .** interfaces) 
30f10 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 64 61 74  then sqlite3_dat
30f20 61 5f 63 6f 75 6e 74 28 50 29 20 72 65 74 75 72  a_count(P) retur
30f30 6e 73 20 30 2e 0a 2a 2a 20 5e 54 68 65 20 73 71  ns 0..** ^The sq
30f40 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74  lite3_data_count
30f50 28 50 29 20 72 6f 75 74 69 6e 65 20 61 6c 73 6f  (P) routine also
30f60 20 72 65 74 75 72 6e 73 20 30 20 69 66 20 50 20   returns 0 if P 
30f70 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  is a NULL pointe
30f80 72 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  r..** ^The sqlit
30f90 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29  e3_data_count(P)
30fa0 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
30fb0 20 30 20 69 66 20 74 68 65 20 70 72 65 76 69 6f   0 if the previo
30fc0 75 73 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73  us call to.** [s
30fd0 71 6c 69 74 65 33 5f 73 74 65 70 5d 28 50 29 20  qlite3_step](P) 
30fe0 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45  returned [SQLITE
30ff0 5f 44 4f 4e 45 5d 2e 20 20 5e 54 68 65 20 73 71  _DONE].  ^The sq
31000 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74  lite3_data_count
31010 28 50 29 0a 2a 2a 20 77 69 6c 6c 20 72 65 74 75  (P).** will retu
31020 72 6e 20 6e 6f 6e 2d 7a 65 72 6f 20 69 66 20 70  rn non-zero if p
31030 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20  revious call to 
31040 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 5d 28 50  [sqlite3_step](P
31050 29 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 5b 53  ) returned.** [S
31060 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 65 78 63 65  QLITE_ROW], exce
31070 70 74 20 69 6e 20 74 68 65 20 63 61 73 65 20 6f  pt in the case o
31080 66 20 74 68 65 20 5b 50 52 41 47 4d 41 20 69 6e  f the [PRAGMA in
31090 63 72 65 6d 65 6e 74 61 6c 5f 76 61 63 75 75 6d  cremental_vacuum
310a0 5d 0a 2a 2a 20 77 68 65 72 65 20 69 74 20 61 6c  ].** where it al
310b0 77 61 79 73 20 72 65 74 75 72 6e 73 20 7a 65 72  ways returns zer
310c0 6f 20 73 69 6e 63 65 20 65 61 63 68 20 73 74 65  o since each ste
310d0 70 20 6f 66 20 74 68 61 74 20 6d 75 6c 74 69 2d  p of that multi-
310e0 73 74 65 70 0a 2a 2a 20 70 72 61 67 6d 61 20 72  step.** pragma r
310f0 65 74 75 72 6e 73 20 30 20 63 6f 6c 75 6d 6e 73  eturns 0 columns
31100 20 6f 66 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20   of data..**.** 
31110 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74  See also: [sqlit
31120 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28  e3_column_count(
31130 29 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  )].*/.int sqlite
31140 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 73 71 6c  3_data_count(sql
31150 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74  ite3_stmt *pStmt
31160 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
31170 45 46 3a 20 46 75 6e 64 61 6d 65 6e 74 61 6c 20  EF: Fundamental 
31180 44 61 74 61 74 79 70 65 73 0a 2a 2a 20 4b 45 59  Datatypes.** KEY
31190 57 4f 52 44 53 3a 20 53 51 4c 49 54 45 5f 54 45  WORDS: SQLITE_TE
311a0 58 54 0a 2a 2a 0a 2a 2a 20 5e 28 45 76 65 72 79  XT.**.** ^(Every
311b0 20 76 61 6c 75 65 20 69 6e 20 53 51 4c 69 74 65   value in SQLite
311c0 20 68 61 73 20 6f 6e 65 20 6f 66 20 66 69 76 65   has one of five
311d0 20 66 75 6e 64 61 6d 65 6e 74 61 6c 20 64 61 74   fundamental dat
311e0 61 74 79 70 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75  atypes:.**.** <u
311f0 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 69  l>.** <li> 64-bi
31200 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72  t signed integer
31210 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 74 20  .** <li> 64-bit 
31220 49 45 45 45 20 66 6c 6f 61 74 69 6e 67 20 70 6f  IEEE floating po
31230 69 6e 74 20 6e 75 6d 62 65 72 0a 2a 2a 20 3c 6c  int number.** <l
31240 69 3e 20 73 74 72 69 6e 67 0a 2a 2a 20 3c 6c 69  i> string.** <li
31250 3e 20 42 4c 4f 42 0a 2a 2a 20 3c 6c 69 3e 20 4e  > BLOB.** <li> N
31260 55 4c 4c 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a  ULL.** </ul>)^.*
31270 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74  *.** These const
31280 61 6e 74 73 20 61 72 65 20 63 6f 64 65 73 20 66  ants are codes f
31290 6f 72 20 65 61 63 68 20 6f 66 20 74 68 6f 73 65  or each of those
312a0 20 74 79 70 65 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f   types..**.** No
312b0 74 65 20 74 68 61 74 20 74 68 65 20 53 51 4c 49  te that the SQLI
312c0 54 45 5f 54 45 58 54 20 63 6f 6e 73 74 61 6e 74  TE_TEXT constant
312d0 20 77 61 73 20 61 6c 73 6f 20 75 73 65 64 20 69   was also used i
312e0 6e 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e  n SQLite version
312f0 20 32 0a 2a 2a 20 66 6f 72 20 61 20 63 6f 6d 70   2.** for a comp
31300 6c 65 74 65 6c 79 20 64 69 66 66 65 72 65 6e 74  letely different
31310 20 6d 65 61 6e 69 6e 67 2e 20 20 53 6f 66 74 77   meaning.  Softw
31320 61 72 65 20 74 68 61 74 20 6c 69 6e 6b 73 20 61  are that links a
31330 67 61 69 6e 73 74 20 62 6f 74 68 0a 2a 2a 20 53  gainst both.** S
31340 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 32 20  QLite version 2 
31350 61 6e 64 20 53 51 4c 69 74 65 20 76 65 72 73 69  and SQLite versi
31360 6f 6e 20 33 20 73 68 6f 75 6c 64 20 75 73 65 20  on 3 should use 
31370 53 51 4c 49 54 45 33 5f 54 45 58 54 2c 20 6e 6f  SQLITE3_TEXT, no
31380 74 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 45 58 54  t.** SQLITE_TEXT
31390 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
313a0 49 54 45 5f 49 4e 54 45 47 45 52 20 20 31 0a 23  ITE_INTEGER  1.#
313b0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 4c  define SQLITE_FL
313c0 4f 41 54 20 20 20 20 32 0a 23 64 65 66 69 6e 65  OAT    2.#define
313d0 20 53 51 4c 49 54 45 5f 42 4c 4f 42 20 20 20 20   SQLITE_BLOB    
313e0 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   4.#define SQLIT
313f0 45 5f 4e 55 4c 4c 20 20 20 20 20 35 0a 23 69 66  E_NULL     5.#if
31400 64 65 66 20 53 51 4c 49 54 45 5f 54 45 58 54 0a  def SQLITE_TEXT.
31410 23 20 75 6e 64 65 66 20 53 51 4c 49 54 45 5f 54  # undef SQLITE_T
31420 45 58 54 0a 23 65 6c 73 65 0a 23 20 64 65 66 69  EXT.#else.# defi
31430 6e 65 20 53 51 4c 49 54 45 5f 54 45 58 54 20 20  ne SQLITE_TEXT  
31440 20 20 20 33 0a 23 65 6e 64 69 66 0a 23 64 65 66     3.#endif.#def
31450 69 6e 65 20 53 51 4c 49 54 45 33 5f 54 45 58 54  ine SQLITE3_TEXT
31460 20 20 20 20 20 33 0a 0a 2f 2a 0a 2a 2a 20 43 41       3../*.** CA
31470 50 49 33 52 45 46 3a 20 52 65 73 75 6c 74 20 56  PI3REF: Result V
31480 61 6c 75 65 73 20 46 72 6f 6d 20 41 20 51 75 65  alues From A Que
31490 72 79 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  ry.** KEYWORDS: 
314a0 7b 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 66  {column access f
314b0 75 6e 63 74 69 6f 6e 73 7d 0a 2a 2a 20 4d 45 54  unctions}.** MET
314c0 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d  HOD: sqlite3_stm
314d0 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72  t.**.** ^These r
314e0 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 69  outines return i
314f0 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74  nformation about
31500 20 61 20 73 69 6e 67 6c 65 20 63 6f 6c 75 6d 6e   a single column
31510 20 6f 66 20 74 68 65 20 63 75 72 72 65 6e 74 0a   of the current.
31520 2a 2a 20 72 65 73 75 6c 74 20 72 6f 77 20 6f 66  ** result row of
31530 20 61 20 71 75 65 72 79 2e 20 20 5e 49 6e 20 65   a query.  ^In e
31540 76 65 72 79 20 63 61 73 65 20 74 68 65 20 66 69  very case the fi
31550 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20  rst argument is 
31560 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20  a pointer.** to 
31570 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
31580 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 69 73  atement] that is
31590 20 62 65 69 6e 67 20 65 76 61 6c 75 61 74 65 64   being evaluated
315a0 20 28 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73   (the [sqlite3_s
315b0 74 6d 74 2a 5d 0a 2a 2a 20 74 68 61 74 20 77 61  tmt*].** that wa
315c0 73 20 72 65 74 75 72 6e 65 64 20 66 72 6f 6d 20  s returned from 
315d0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
315e0 5f 76 32 28 29 5d 20 6f 72 20 6f 6e 65 20 6f 66  _v2()] or one of
315f0 20 69 74 73 20 76 61 72 69 61 6e 74 73 29 0a 2a   its variants).*
31600 2a 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64  * and the second
31610 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65   argument is the
31620 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20 63 6f   index of the co
31630 6c 75 6d 6e 20 66 6f 72 20 77 68 69 63 68 20 69  lumn for which i
31640 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 73 68  nformation.** sh
31650 6f 75 6c 64 20 62 65 20 72 65 74 75 72 6e 65 64  ould be returned
31660 2e 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74 20  . ^The leftmost 
31670 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72 65  column of the re
31680 73 75 6c 74 20 73 65 74 20 68 61 73 20 74 68 65  sult set has the
31690 20 69 6e 64 65 78 20 30 2e 0a 2a 2a 20 5e 54 68   index 0..** ^Th
316a0 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75  e number of colu
316b0 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 73 75 6c  mns in the resul
316c0 74 20 63 61 6e 20 62 65 20 64 65 74 65 72 6d 69  t can be determi
316d0 6e 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71  ned using.** [sq
316e0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75  lite3_column_cou
316f0 6e 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  nt()]..**.** If 
31700 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  the SQL statemen
31710 74 20 64 6f 65 73 20 6e 6f 74 20 63 75 72 72 65  t does not curre
31720 6e 74 6c 79 20 70 6f 69 6e 74 20 74 6f 20 61 20  ntly point to a 
31730 76 61 6c 69 64 20 72 6f 77 2c 20 6f 72 20 69 66  valid row, or if
31740 20 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69   the.** column i
31750 6e 64 65 78 20 69 73 20 6f 75 74 20 6f 66 20 72  ndex is out of r
31760 61 6e 67 65 2c 20 74 68 65 20 72 65 73 75 6c 74  ange, the result
31770 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a   is undefined..*
31780 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
31790 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 63 61 6c   may only be cal
317a0 6c 65 64 20 77 68 65 6e 20 74 68 65 20 6d 6f 73  led when the mos
317b0 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f  t recent call to
317c0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  .** [sqlite3_ste
317d0 70 28 29 5d 20 68 61 73 20 72 65 74 75 72 6e 65  p()] has returne
317e0 64 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 61  d [SQLITE_ROW] a
317f0 6e 64 20 6e 65 69 74 68 65 72 0a 2a 2a 20 5b 73  nd neither.** [s
31800 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
31810 6e 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e  nor [sqlite3_fin
31820 61 6c 69 7a 65 28 29 5d 20 68 61 76 65 20 62 65  alize()] have be
31830 65 6e 20 63 61 6c 6c 65 64 20 73 75 62 73 65 71  en called subseq
31840 75 65 6e 74 6c 79 2e 0a 2a 2a 20 49 66 20 61 6e  uently..** If an
31850 79 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69  y of these routi
31860 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20 61  nes are called a
31870 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 72 65  fter [sqlite3_re
31880 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71  set()] or.** [sq
31890 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
318a0 5d 20 6f 72 20 61 66 74 65 72 20 5b 73 71 6c 69  ] or after [sqli
318b0 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20  te3_step()] has 
318c0 72 65 74 75 72 6e 65 64 0a 2a 2a 20 73 6f 6d 65  returned.** some
318d0 74 68 69 6e 67 20 6f 74 68 65 72 20 74 68 61 6e  thing other than
318e0 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 74   [SQLITE_ROW], t
318f0 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 75  he results are u
31900 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 49 66 20  ndefined..** If 
31910 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
31920 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73   or [sqlite3_res
31930 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  et()] or [sqlite
31940 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 0a 2a 2a  3_finalize()].**
31950 20 61 72 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d   are called from
31960 20 61 20 64 69 66 66 65 72 65 6e 74 20 74 68 72   a different thr
31970 65 61 64 20 77 68 69 6c 65 20 61 6e 79 20 6f 66  ead while any of
31980 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 0a   these routines.
31990 2a 2a 20 61 72 65 20 70 65 6e 64 69 6e 67 2c 20  ** are pending, 
319a0 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73  then the results
319b0 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a   are undefined..
319c0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
319d0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29  e3_column_type()
319e0 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
319f0 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f   the.** [SQLITE_
31a00 49 4e 54 45 47 45 52 20 7c 20 64 61 74 61 74 79  INTEGER | dataty
31a10 70 65 20 63 6f 64 65 5d 20 66 6f 72 20 74 68 65  pe code] for the
31a20 20 69 6e 69 74 69 61 6c 20 64 61 74 61 20 74 79   initial data ty
31a30 70 65 0a 2a 2a 20 6f 66 20 74 68 65 20 72 65 73  pe.** of the res
31a40 75 6c 74 20 63 6f 6c 75 6d 6e 2e 20 20 5e 54 68  ult column.  ^Th
31a50 65 20 72 65 74 75 72 6e 65 64 20 76 61 6c 75 65  e returned value
31a60 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49   is one of [SQLI
31a70 54 45 5f 49 4e 54 45 47 45 52 5d 2c 0a 2a 2a 20  TE_INTEGER],.** 
31a80 5b 53 51 4c 49 54 45 5f 46 4c 4f 41 54 5d 2c 20  [SQLITE_FLOAT], 
31a90 5b 53 51 4c 49 54 45 5f 54 45 58 54 5d 2c 20 5b  [SQLITE_TEXT], [
31aa0 53 51 4c 49 54 45 5f 42 4c 4f 42 5d 2c 20 6f 72  SQLITE_BLOB], or
31ab0 20 5b 53 51 4c 49 54 45 5f 4e 55 4c 4c 5d 2e 20   [SQLITE_NULL]. 
31ac0 20 54 68 65 20 76 61 6c 75 65 0a 2a 2a 20 72 65   The value.** re
31ad0 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65  turned by sqlite
31ae0 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20  3_column_type() 
31af0 69 73 20 6f 6e 6c 79 20 6d 65 61 6e 69 6e 67 66  is only meaningf
31b00 75 6c 20 69 66 20 6e 6f 20 74 79 70 65 0a 2a 2a  ul if no type.**
31b10 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 68 61 76   conversions hav
31b20 65 20 6f 63 63 75 72 72 65 64 20 61 73 20 64 65  e occurred as de
31b30 73 63 72 69 62 65 64 20 62 65 6c 6f 77 2e 20 20  scribed below.  
31b40 41 66 74 65 72 20 61 20 74 79 70 65 20 63 6f 6e  After a type con
31b50 76 65 72 73 69 6f 6e 2c 0a 2a 2a 20 74 68 65 20  version,.** the 
31b60 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62  value returned b
31b70 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  y sqlite3_column
31b80 5f 74 79 70 65 28 29 20 69 73 20 75 6e 64 65 66  _type() is undef
31b90 69 6e 65 64 2e 20 20 46 75 74 75 72 65 0a 2a 2a  ined.  Future.**
31ba0 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c   versions of SQL
31bb0 69 74 65 20 6d 61 79 20 63 68 61 6e 67 65 20 74  ite may change t
31bc0 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20 73  he behavior of s
31bd0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79  qlite3_column_ty
31be0 70 65 28 29 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e  pe().** followin
31bf0 67 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73  g a type convers
31c00 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  ion..**.** ^If t
31c10 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 42  he result is a B
31c20 4c 4f 42 20 6f 72 20 55 54 46 2d 38 20 73 74 72  LOB or UTF-8 str
31c30 69 6e 67 20 74 68 65 6e 20 74 68 65 20 73 71 6c  ing then the sql
31c40 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
31c50 73 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72  s().** routine r
31c60 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65  eturns the numbe
31c70 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68  r of bytes in th
31c80 61 74 20 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e  at BLOB or strin
31c90 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65  g..** ^If the re
31ca0 73 75 6c 74 20 69 73 20 61 20 55 54 46 2d 31 36  sult is a UTF-16
31cb0 20 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 73 71   string, then sq
31cc0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
31cd0 65 73 28 29 20 63 6f 6e 76 65 72 74 73 0a 2a 2a  es() converts.**
31ce0 20 74 68 65 20 73 74 72 69 6e 67 20 74 6f 20 55   the string to U
31cf0 54 46 2d 38 20 61 6e 64 20 74 68 65 6e 20 72 65  TF-8 and then re
31d00 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72  turns the number
31d10 20 6f 66 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 49   of bytes..** ^I
31d20 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20  f the result is 
31d30 61 20 6e 75 6d 65 72 69 63 20 76 61 6c 75 65 20  a numeric value 
31d40 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c  then sqlite3_col
31d50 75 6d 6e 5f 62 79 74 65 73 28 29 20 75 73 65 73  umn_bytes() uses
31d60 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70  .** [sqlite3_snp
31d70 72 69 6e 74 66 28 29 5d 20 74 6f 20 63 6f 6e 76  rintf()] to conv
31d80 65 72 74 20 74 68 61 74 20 76 61 6c 75 65 20 74  ert that value t
31d90 6f 20 61 20 55 54 46 2d 38 20 73 74 72 69 6e 67  o a UTF-8 string
31da0 20 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a 2a 20   and returns.** 
31db0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  the number of by
31dc0 74 65 73 20 69 6e 20 74 68 61 74 20 73 74 72 69  tes in that stri
31dd0 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72  ng..** ^If the r
31de0 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c 2c 20 74  esult is NULL, t
31df0 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  hen sqlite3_colu
31e00 6d 6e 5f 62 79 74 65 73 28 29 20 72 65 74 75 72  mn_bytes() retur
31e10 6e 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e  ns zero..**.** ^
31e20 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73  If the result is
31e30 20 61 20 42 4c 4f 42 20 6f 72 20 55 54 46 2d 31   a BLOB or UTF-1
31e40 36 20 73 74 72 69 6e 67 20 74 68 65 6e 20 74 68  6 string then th
31e50 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  e sqlite3_column
31e60 5f 62 79 74 65 73 31 36 28 29 0a 2a 2a 20 72 6f  _bytes16().** ro
31e70 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68  utine returns th
31e80 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  e number of byte
31e90 73 20 69 6e 20 74 68 61 74 20 42 4c 4f 42 20 6f  s in that BLOB o
31ea0 72 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66  r string..** ^If
31eb0 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61   the result is a
31ec0 20 55 54 46 2d 38 20 73 74 72 69 6e 67 2c 20 74   UTF-8 string, t
31ed0 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  hen sqlite3_colu
31ee0 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 63 6f 6e  mn_bytes16() con
31ef0 76 65 72 74 73 0a 2a 2a 20 74 68 65 20 73 74 72  verts.** the str
31f00 69 6e 67 20 74 6f 20 55 54 46 2d 31 36 20 61 6e  ing to UTF-16 an
31f10 64 20 74 68 65 6e 20 72 65 74 75 72 6e 73 20 74  d then returns t
31f20 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  he number of byt
31f30 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72  es..** ^If the r
31f40 65 73 75 6c 74 20 69 73 20 61 20 6e 75 6d 65 72  esult is a numer
31f50 69 63 20 76 61 6c 75 65 20 74 68 65 6e 20 73 71  ic value then sq
31f60 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
31f70 65 73 31 36 28 29 20 75 73 65 73 0a 2a 2a 20 5b  es16() uses.** [
31f80 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66  sqlite3_snprintf
31f90 28 29 5d 20 74 6f 20 63 6f 6e 76 65 72 74 20 74  ()] to convert t
31fa0 68 61 74 20 76 61 6c 75 65 20 74 6f 20 61 20 55  hat value to a U
31fb0 54 46 2d 31 36 20 73 74 72 69 6e 67 20 61 6e 64  TF-16 string and
31fc0 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20   returns.** the 
31fd0 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
31fe0 69 6e 20 74 68 61 74 20 73 74 72 69 6e 67 2e 0a  in that string..
31ff0 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c  ** ^If the resul
32000 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20  t is NULL, then 
32010 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
32020 79 74 65 73 31 36 28 29 20 72 65 74 75 72 6e 73  ytes16() returns
32030 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68   zero..**.** ^Th
32040 65 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e 65  e values returne
32050 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f  d by [sqlite3_co
32060 6c 75 6d 6e 5f 62 79 74 65 73 28 29 5d 20 61 6e  lumn_bytes()] an
32070 64 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  d .** [sqlite3_c
32080 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 5d  olumn_bytes16()]
32090 20 64 6f 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20   do not include 
320a0 74 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61  the zero termina
320b0 74 6f 72 73 20 61 74 20 74 68 65 20 65 6e 64 0a  tors at the end.
320c0 2a 2a 20 6f 66 20 74 68 65 20 73 74 72 69 6e 67  ** of the string
320d0 2e 20 20 5e 46 6f 72 20 63 6c 61 72 69 74 79 3a  .  ^For clarity:
320e0 20 74 68 65 20 76 61 6c 75 65 73 20 72 65 74 75   the values retu
320f0 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69  rned by.** [sqli
32100 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
32110 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
32120 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
32130 29 5d 20 61 72 65 20 74 68 65 20 6e 75 6d 62 65  )] are the numbe
32140 72 20 6f 66 0a 2a 2a 20 62 79 74 65 73 20 69 6e  r of.** bytes in
32150 20 74 68 65 20 73 74 72 69 6e 67 2c 20 6e 6f 74   the string, not
32160 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63   the number of c
32170 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a  haracters..**.**
32180 20 5e 53 74 72 69 6e 67 73 20 72 65 74 75 72 6e   ^Strings return
32190 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f  ed by sqlite3_co
321a0 6c 75 6d 6e 5f 74 65 78 74 28 29 20 61 6e 64 20  lumn_text() and 
321b0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
321c0 65 78 74 31 36 28 29 2c 0a 2a 2a 20 65 76 65 6e  ext16(),.** even
321d0 20 65 6d 70 74 79 20 73 74 72 69 6e 67 73 2c 20   empty strings, 
321e0 61 72 65 20 61 6c 77 61 79 73 20 7a 65 72 6f 2d  are always zero-
321f0 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 5e 54 68  terminated.  ^Th
32200 65 20 72 65 74 75 72 6e 0a 2a 2a 20 76 61 6c 75  e return.** valu
32210 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 63  e from sqlite3_c
32220 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f 72  olumn_blob() for
32230 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 42   a zero-length B
32240 4c 4f 42 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  LOB is a NULL po
32250 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e  inter..**.** <b>
32260 57 61 72 6e 69 6e 67 3a 3c 2f 62 3e 20 5e 54 68  Warning:</b> ^Th
32270 65 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65  e object returne
32280 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f  d by [sqlite3_co
32290 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73  lumn_value()] is
322a0 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63   an.** [unprotec
322b0 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
322c0 65 5d 20 6f 62 6a 65 63 74 2e 20 20 49 6e 20 61  e] object.  In a
322d0 20 6d 75 6c 74 69 74 68 72 65 61 64 65 64 20 65   multithreaded e
322e0 6e 76 69 72 6f 6e 6d 65 6e 74 2c 0a 2a 2a 20 61  nvironment,.** a
322f0 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71  n unprotected sq
32300 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
32310 63 74 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 75  ct may only be u
32320 73 65 64 20 73 61 66 65 6c 79 20 77 69 74 68 0a  sed safely with.
32330 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  ** [sqlite3_bind
32340 5f 76 61 6c 75 65 28 29 5d 20 61 6e 64 20 5b 73  _value()] and [s
32350 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61  qlite3_result_va
32360 6c 75 65 28 29 5d 2e 0a 2a 2a 20 49 66 20 74 68  lue()]..** If th
32370 65 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73  e [unprotected s
32380 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
32390 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20 62 79  ject returned by
323a0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  .** [sqlite3_col
323b0 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20  umn_value()] is 
323c0 75 73 65 64 20 69 6e 20 61 6e 79 20 6f 74 68 65  used in any othe
323d0 72 20 77 61 79 2c 20 69 6e 63 6c 75 64 69 6e 67  r way, including
323e0 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 72 6f 75   calls.** to rou
323f0 74 69 6e 65 73 20 6c 69 6b 65 20 5b 73 71 6c 69  tines like [sqli
32400 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28 29 5d  te3_value_int()]
32410 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  , [sqlite3_value
32420 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20  _text()],.** or 
32430 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62  [sqlite3_value_b
32440 79 74 65 73 28 29 5d 2c 20 74 68 65 20 62 65 68  ytes()], the beh
32450 61 76 69 6f 72 20 69 73 20 6e 6f 74 20 74 68 72  avior is not thr
32460 65 61 64 73 61 66 65 2e 0a 2a 2a 0a 2a 2a 20 54  eadsafe..**.** T
32470 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 74  hese routines at
32480 74 65 6d 70 74 20 74 6f 20 63 6f 6e 76 65 72 74  tempt to convert
32490 20 74 68 65 20 76 61 6c 75 65 20 77 68 65 72 65   the value where
324a0 20 61 70 70 72 6f 70 72 69 61 74 65 2e 20 20 5e   appropriate.  ^
324b0 46 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20  For.** example, 
324c0 69 66 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20  if the internal 
324d0 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 69  representation i
324e0 73 20 46 4c 4f 41 54 20 61 6e 64 20 61 20 74 65  s FLOAT and a te
324f0 78 74 20 72 65 73 75 6c 74 0a 2a 2a 20 69 73 20  xt result.** is 
32500 72 65 71 75 65 73 74 65 64 2c 20 5b 73 71 6c 69  requested, [sqli
32510 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20  te3_snprintf()] 
32520 69 73 20 75 73 65 64 20 69 6e 74 65 72 6e 61 6c  is used internal
32530 6c 79 20 74 6f 20 70 65 72 66 6f 72 6d 20 74 68  ly to perform th
32540 65 0a 2a 2a 20 63 6f 6e 76 65 72 73 69 6f 6e 20  e.** conversion 
32550 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20  automatically.  
32560 5e 28 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  ^(The following 
32570 74 61 62 6c 65 20 64 65 74 61 69 6c 73 20 74 68  table details th
32580 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 0a 2a 2a  e conversions.**
32590 20 74 68 61 74 20 61 72 65 20 61 70 70 6c 69 65   that are applie
325a0 64 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71  d:.**.** <blockq
325b0 75 6f 74 65 3e 0a 2a 2a 20 3c 74 61 62 6c 65 20  uote>.** <table 
325c0 62 6f 72 64 65 72 3d 22 31 22 3e 0a 2a 2a 20 3c  border="1">.** <
325d0 74 72 3e 3c 74 68 3e 20 49 6e 74 65 72 6e 61 6c  tr><th> Internal
325e0 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e 20 52 65  <br>Type <th> Re
325f0 71 75 65 73 74 65 64 3c 62 72 3e 54 79 70 65 20  quested<br>Type 
32600 3c 74 68 3e 20 20 43 6f 6e 76 65 72 73 69 6f 6e  <th>  Conversion
32610 0a 2a 2a 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  .**.** <tr><td> 
32620 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 49 4e   NULL    <td> IN
32630 54 45 47 45 52 20 20 20 3c 74 64 3e 20 52 65 73  TEGER   <td> Res
32640 75 6c 74 20 69 73 20 30 0a 2a 2a 20 3c 74 72 3e  ult is 0.** <tr>
32650 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74  <td>  NULL    <t
32660 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64  d>  FLOAT    <td
32670 3e 20 52 65 73 75 6c 74 20 69 73 20 30 2e 30 0a  > Result is 0.0.
32680 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c  ** <tr><td>  NUL
32690 4c 20 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54  L    <td>   TEXT
326a0 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20      <td> Result 
326b0 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  is a NULL pointe
326c0 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e  r.** <tr><td>  N
326d0 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 20 42 4c  ULL    <td>   BL
326e0 4f 42 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c  OB    <td> Resul
326f0 74 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  t is a NULL poin
32700 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  ter.** <tr><td> 
32710 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20 46  INTEGER  <td>  F
32720 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 43 6f 6e  LOAT    <td> Con
32730 76 65 72 74 20 66 72 6f 6d 20 69 6e 74 65 67 65  vert from intege
32740 72 20 74 6f 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74  r to float.** <t
32750 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20  r><td> INTEGER  
32760 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c  <td>   TEXT    <
32770 74 64 3e 20 41 53 43 49 49 20 72 65 6e 64 65 72  td> ASCII render
32780 69 6e 67 20 6f 66 20 74 68 65 20 69 6e 74 65 67  ing of the integ
32790 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49  er.** <tr><td> I
327a0 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20 20 42  NTEGER  <td>   B
327b0 4c 4f 42 20 20 20 20 3c 74 64 3e 20 53 61 6d 65  LOB    <td> Same
327c0 20 61 73 20 49 4e 54 45 47 45 52 2d 3e 54 45 58   as INTEGER->TEX
327d0 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46  T.** <tr><td>  F
327e0 4c 4f 41 54 20 20 20 3c 74 64 3e 20 49 4e 54 45  LOAT   <td> INTE
327f0 47 45 52 20 20 20 3c 74 64 3e 20 5b 43 41 53 54  GER   <td> [CAST
32800 5d 20 74 6f 20 49 4e 54 45 47 45 52 0a 2a 2a 20  ] to INTEGER.** 
32810 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20  <tr><td>  FLOAT 
32820 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20    <td>   TEXT   
32830 20 3c 74 64 3e 20 41 53 43 49 49 20 72 65 6e 64   <td> ASCII rend
32840 65 72 69 6e 67 20 6f 66 20 74 68 65 20 66 6c 6f  ering of the flo
32850 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  at.** <tr><td>  
32860 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20 20 42  FLOAT   <td>   B
32870 4c 4f 42 20 20 20 20 3c 74 64 3e 20 5b 43 41 53  LOB    <td> [CAS
32880 54 5d 20 74 6f 20 42 4c 4f 42 0a 2a 2a 20 3c 74  T] to BLOB.** <t
32890 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20  r><td>  TEXT    
328a0 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c  <td> INTEGER   <
328b0 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20 49 4e  td> [CAST] to IN
328c0 54 45 47 45 52 0a 2a 2a 20 3c 74 72 3e 3c 74 64  TEGER.** <tr><td
328d0 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20  >  TEXT    <td> 
328e0 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 5b   FLOAT    <td> [
328f0 43 41 53 54 5d 20 74 6f 20 52 45 41 4c 0a 2a 2a  CAST] to REAL.**
32900 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20   <tr><td>  TEXT 
32910 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20     <td>   BLOB  
32920 20 20 3c 74 64 3e 20 4e 6f 20 63 68 61 6e 67 65    <td> No change
32930 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c  .** <tr><td>  BL
32940 4f 42 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47  OB    <td> INTEG
32950 45 52 20 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d  ER   <td> [CAST]
32960 20 74 6f 20 49 4e 54 45 47 45 52 0a 2a 2a 20 3c   to INTEGER.** <
32970 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20  tr><td>  BLOB   
32980 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20   <td>  FLOAT    
32990 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20 52  <td> [CAST] to R
329a0 45 41 4c 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  EAL.** <tr><td> 
329b0 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 20 20   BLOB    <td>   
329c0 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41 64 64  TEXT    <td> Add
329d0 20 61 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74   a zero terminat
329e0 6f 72 20 69 66 20 6e 65 65 64 65 64 0a 2a 2a 20  or if needed.** 
329f0 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 20 3c 2f 62 6c  </table>.** </bl
32a00 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a  ockquote>)^.**.*
32a10 2a 20 4e 6f 74 65 20 74 68 61 74 20 77 68 65 6e  * Note that when
32a20 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e   type conversion
32a30 73 20 6f 63 63 75 72 2c 20 70 6f 69 6e 74 65 72  s occur, pointer
32a40 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 70 72  s returned by pr
32a50 69 6f 72 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20  ior.** calls to 
32a60 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
32a70 6c 6f 62 28 29 2c 20 73 71 6c 69 74 65 33 5f 63  lob(), sqlite3_c
32a80 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 20 61 6e  olumn_text(), an
32a90 64 2f 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  d/or.** sqlite3_
32aa0 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20  column_text16() 
32ab0 6d 61 79 20 62 65 20 69 6e 76 61 6c 69 64 61 74  may be invalidat
32ac0 65 64 2e 0a 2a 2a 20 54 79 70 65 20 63 6f 6e 76  ed..** Type conv
32ad0 65 72 73 69 6f 6e 73 20 61 6e 64 20 70 6f 69 6e  ersions and poin
32ae0 74 65 72 20 69 6e 76 61 6c 69 64 61 74 69 6f 6e  ter invalidation
32af0 73 20 6d 69 67 68 74 20 6f 63 63 75 72 0a 2a 2a  s might occur.**
32b00 20 69 6e 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e   in the followin
32b10 67 20 63 61 73 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c  g cases:.**.** <
32b20 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20  ul>.** <li> The 
32b30 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20  initial content 
32b40 69 73 20 61 20 42 4c 4f 42 20 61 6e 64 20 73 71  is a BLOB and sq
32b50 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
32b60 74 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73  t() or.**      s
32b70 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
32b80 78 74 31 36 28 29 20 69 73 20 63 61 6c 6c 65 64  xt16() is called
32b90 2e 20 20 41 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  .  A zero-termin
32ba0 61 74 6f 72 20 6d 69 67 68 74 0a 2a 2a 20 20 20  ator might.**   
32bb0 20 20 20 6e 65 65 64 20 74 6f 20 62 65 20 61 64     need to be ad
32bc0 64 65 64 20 74 6f 20 74 68 65 20 73 74 72 69 6e  ded to the strin
32bd0 67 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20  g.</li>.** <li> 
32be0 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74  The initial cont
32bf0 65 6e 74 20 69 73 20 55 54 46 2d 38 20 74 65 78  ent is UTF-8 tex
32c00 74 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f  t and sqlite3_co
32c10 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 6f  lumn_bytes16() o
32c20 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 74 65  r.**      sqlite
32c30 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28  3_column_text16(
32c40 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 54 68  ) is called.  Th
32c50 65 20 63 6f 6e 74 65 6e 74 20 6d 75 73 74 20 62  e content must b
32c60 65 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 20  e converted.**  
32c70 20 20 20 20 74 6f 20 55 54 46 2d 31 36 2e 3c 2f      to UTF-16.</
32c80 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20  li>.** <li> The 
32c90 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20  initial content 
32ca0 69 73 20 55 54 46 2d 31 36 20 74 65 78 74 20 61  is UTF-16 text a
32cb0 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nd sqlite3_colum
32cc0 6e 5f 62 79 74 65 73 28 29 20 6f 72 0a 2a 2a 20  n_bytes() or.** 
32cd0 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c       sqlite3_col
32ce0 75 6d 6e 5f 74 65 78 74 28 29 20 69 73 20 63 61  umn_text() is ca
32cf0 6c 6c 65 64 2e 20 20 54 68 65 20 63 6f 6e 74 65  lled.  The conte
32d00 6e 74 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65  nt must be conve
32d10 72 74 65 64 0a 2a 2a 20 20 20 20 20 20 74 6f 20  rted.**      to 
32d20 55 54 46 2d 38 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c  UTF-8.</li>.** <
32d30 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e 76  /ul>.**.** ^Conv
32d40 65 72 73 69 6f 6e 73 20 62 65 74 77 65 65 6e 20  ersions between 
32d50 55 54 46 2d 31 36 62 65 20 61 6e 64 20 55 54 46  UTF-16be and UTF
32d60 2d 31 36 6c 65 20 61 72 65 20 61 6c 77 61 79 73  -16le are always
32d70 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65 20 61   done in place a
32d80 6e 64 20 64 6f 0a 2a 2a 20 6e 6f 74 20 69 6e 76  nd do.** not inv
32d90 61 6c 69 64 61 74 65 20 61 20 70 72 69 6f 72 20  alidate a prior 
32da0 70 6f 69 6e 74 65 72 2c 20 74 68 6f 75 67 68 20  pointer, though 
32db0 6f 66 20 63 6f 75 72 73 65 20 74 68 65 20 63 6f  of course the co
32dc0 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 62 75 66  ntent of the buf
32dd0 66 65 72 0a 2a 2a 20 74 68 61 74 20 74 68 65 20  fer.** that the 
32de0 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 20 72 65  prior pointer re
32df0 66 65 72 65 6e 63 65 73 20 77 69 6c 6c 20 68 61  ferences will ha
32e00 76 65 20 62 65 65 6e 20 6d 6f 64 69 66 69 65 64  ve been modified
32e10 2e 20 20 4f 74 68 65 72 20 6b 69 6e 64 73 0a 2a  .  Other kinds.*
32e20 2a 20 6f 66 20 63 6f 6e 76 65 72 73 69 6f 6e 20  * of conversion 
32e30 61 72 65 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63  are done in plac
32e40 65 20 77 68 65 6e 20 69 74 20 69 73 20 70 6f 73  e when it is pos
32e50 73 69 62 6c 65 2c 20 62 75 74 20 73 6f 6d 65 74  sible, but somet
32e60 69 6d 65 73 20 74 68 65 79 0a 2a 2a 20 61 72 65  imes they.** are
32e70 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 61 6e   not possible an
32e80 64 20 69 6e 20 74 68 6f 73 65 20 63 61 73 65 73  d in those cases
32e90 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 73 20   prior pointers 
32ea0 61 72 65 20 69 6e 76 61 6c 69 64 61 74 65 64 2e  are invalidated.
32eb0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 61 66 65 73  .**.** The safes
32ec0 74 20 70 6f 6c 69 63 79 20 69 73 20 74 6f 20 69  t policy is to i
32ed0 6e 76 6f 6b 65 20 74 68 65 73 65 20 72 6f 75 74  nvoke these rout
32ee0 69 6e 65 73 0a 2a 2a 20 69 6e 20 6f 6e 65 20 6f  ines.** in one o
32ef0 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  f the following 
32f00 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  ways:.**.** <ul>
32f10 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33  .**  <li>sqlite3
32f20 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 66  _column_text() f
32f30 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74  ollowed by sqlit
32f40 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
32f50 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73  )</li>.**  <li>s
32f60 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c  qlite3_column_bl
32f70 6f 62 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79  ob() followed by
32f80 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
32f90 62 79 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20  bytes()</li>.** 
32fa0 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c   <li>sqlite3_col
32fb0 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 66 6f 6c  umn_text16() fol
32fc0 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65 33  lowed by sqlite3
32fd0 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
32fe0 29 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a  )</li>.** </ul>.
32ff0 2a 2a 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 20 77  **.** In other w
33000 6f 72 64 73 2c 20 79 6f 75 20 73 68 6f 75 6c 64  ords, you should
33010 20 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f 63 6f   call sqlite3_co
33020 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 0a 2a 2a 20  lumn_text(),.** 
33030 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
33040 6c 6f 62 28 29 2c 20 6f 72 20 73 71 6c 69 74 65  lob(), or sqlite
33050 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28  3_column_text16(
33060 29 20 66 69 72 73 74 20 74 6f 20 66 6f 72 63 65  ) first to force
33070 20 74 68 65 20 72 65 73 75 6c 74 0a 2a 2a 20 69   the result.** i
33080 6e 74 6f 20 74 68 65 20 64 65 73 69 72 65 64 20  nto the desired 
33090 66 6f 72 6d 61 74 2c 20 74 68 65 6e 20 69 6e 76  format, then inv
330a0 6f 6b 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  oke sqlite3_colu
330b0 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72 0a 2a 2a  mn_bytes() or.**
330c0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
330d0 62 79 74 65 73 31 36 28 29 20 74 6f 20 66 69 6e  bytes16() to fin
330e0 64 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68  d the size of th
330f0 65 20 72 65 73 75 6c 74 2e 20 20 44 6f 20 6e 6f  e result.  Do no
33100 74 20 6d 69 78 20 63 61 6c 6c 73 0a 2a 2a 20 74  t mix calls.** t
33110 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  o sqlite3_column
33120 5f 74 65 78 74 28 29 20 6f 72 20 73 71 6c 69 74  _text() or sqlit
33130 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29  e3_column_blob()
33140 20 77 69 74 68 20 63 61 6c 6c 73 20 74 6f 0a 2a   with calls to.*
33150 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  * sqlite3_column
33160 5f 62 79 74 65 73 31 36 28 29 2c 20 61 6e 64 20  _bytes16(), and 
33170 64 6f 20 6e 6f 74 20 6d 69 78 20 63 61 6c 6c 73  do not mix calls
33180 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   to sqlite3_colu
33190 6d 6e 5f 74 65 78 74 31 36 28 29 0a 2a 2a 20 77  mn_text16().** w
331a0 69 74 68 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c  ith calls to sql
331b0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
331c0 73 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  s()..**.** ^The 
331d0 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65  pointers returne
331e0 64 20 61 72 65 20 76 61 6c 69 64 20 75 6e 74 69  d are valid unti
331f0 6c 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73  l a type convers
33200 69 6f 6e 20 6f 63 63 75 72 73 20 61 73 0a 2a 2a  ion occurs as.**
33210 20 64 65 73 63 72 69 62 65 64 20 61 62 6f 76 65   described above
33220 2c 20 6f 72 20 75 6e 74 69 6c 20 5b 73 71 6c 69  , or until [sqli
33230 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 72 20 5b  te3_step()] or [
33240 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
33250 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   or.** [sqlite3_
33260 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69 73 20 63  finalize()] is c
33270 61 6c 6c 65 64 2e 20 20 5e 54 68 65 20 6d 65 6d  alled.  ^The mem
33280 6f 72 79 20 73 70 61 63 65 20 75 73 65 64 20 74  ory space used t
33290 6f 20 68 6f 6c 64 20 73 74 72 69 6e 67 73 0a 2a  o hold strings.*
332a0 2a 20 61 6e 64 20 42 4c 4f 42 73 20 69 73 20 66  * and BLOBs is f
332b0 72 65 65 64 20 61 75 74 6f 6d 61 74 69 63 61 6c  reed automatical
332c0 6c 79 2e 20 20 44 6f 20 3c 65 6d 3e 6e 6f 74 3c  ly.  Do <em>not<
332d0 2f 65 6d 3e 20 70 61 73 73 20 74 68 65 20 70 6f  /em> pass the po
332e0 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64 0a  inters returned.
332f0 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  ** from [sqlite3
33300 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 5d 2c  _column_blob()],
33310 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
33320 5f 74 65 78 74 28 29 5d 2c 20 65 74 63 2e 20 69  _text()], etc. i
33330 6e 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  nto.** [sqlite3_
33340 66 72 65 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e  free()]..**.** ^
33350 28 49 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c  (If a memory all
33360 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 20 6f 63  ocation error oc
33370 63 75 72 73 20 64 75 72 69 6e 67 20 74 68 65 20  curs during the 
33380 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20 61 6e  evaluation of an
33390 79 0a 2a 2a 20 6f 66 20 74 68 65 73 65 20 72 6f  y.** of these ro
333a0 75 74 69 6e 65 73 2c 20 61 20 64 65 66 61 75 6c  utines, a defaul
333b0 74 20 76 61 6c 75 65 20 69 73 20 72 65 74 75 72  t value is retur
333c0 6e 65 64 2e 20 20 54 68 65 20 64 65 66 61 75 6c  ned.  The defaul
333d0 74 20 76 61 6c 75 65 0a 2a 2a 20 69 73 20 65 69  t value.** is ei
333e0 74 68 65 72 20 74 68 65 20 69 6e 74 65 67 65 72  ther the integer
333f0 20 30 2c 20 74 68 65 20 66 6c 6f 61 74 69 6e 67   0, the floating
33400 20 70 6f 69 6e 74 20 6e 75 6d 62 65 72 20 30 2e   point number 0.
33410 30 2c 20 6f 72 20 61 20 4e 55 4c 4c 0a 2a 2a 20  0, or a NULL.** 
33420 70 6f 69 6e 74 65 72 2e 20 20 53 75 62 73 65 71  pointer.  Subseq
33430 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73  uent calls to [s
33440 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29  qlite3_errcode()
33450 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a  ] will return.**
33460 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e   [SQLITE_NOMEM].
33470 29 5e 0a 2a 2f 0a 63 6f 6e 73 74 20 76 6f 69 64  )^.*/.const void
33480 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
33490 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74  _blob(sqlite3_st
334a0 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
334b0 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  int sqlite3_colu
334c0 6d 6e 5f 62 79 74 65 73 28 73 71 6c 69 74 65 33  mn_bytes(sqlite3
334d0 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
334e0 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  );.int sqlite3_c
334f0 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 73 71  olumn_bytes16(sq
33500 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
33510 20 69 43 6f 6c 29 3b 0a 64 6f 75 62 6c 65 20 73   iCol);.double s
33520 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 6f  qlite3_column_do
33530 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  uble(sqlite3_stm
33540 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69  t*, int iCol);.i
33550 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nt sqlite3_colum
33560 6e 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 73 74  n_int(sqlite3_st
33570 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
33580 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71  sqlite3_int64 sq
33590 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74  lite3_column_int
335a0 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  64(sqlite3_stmt*
335b0 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 63 6f 6e  , int iCol);.con
335c0 73 74 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72  st unsigned char
335d0 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
335e0 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f 73 74  _text(sqlite3_st
335f0 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
33600 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
33610 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31  te3_column_text1
33620 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  6(sqlite3_stmt*,
33630 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20   int iCol);.int 
33640 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
33650 79 70 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ype(sqlite3_stmt
33660 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 73 71  *, int iCol);.sq
33670 6c 69 74 65 33 5f 76 61 6c 75 65 20 2a 73 71 6c  lite3_value *sql
33680 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75  ite3_column_valu
33690 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
336a0 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 0a 2f 2a 0a   int iCol);../*.
336b0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 73  ** CAPI3REF: Des
336c0 74 72 6f 79 20 41 20 50 72 65 70 61 72 65 64 20  troy A Prepared 
336d0 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74  Statement Object
336e0 0a 2a 2a 20 44 45 53 54 52 55 43 54 4f 52 3a 20  .** DESTRUCTOR: 
336f0 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a  sqlite3_stmt.**.
33700 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
33710 66 69 6e 61 6c 69 7a 65 28 29 20 66 75 6e 63 74  finalize() funct
33720 69 6f 6e 20 69 73 20 63 61 6c 6c 65 64 20 74 6f  ion is called to
33730 20 64 65 6c 65 74 65 20 61 20 5b 70 72 65 70 61   delete a [prepa
33740 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a  red statement]..
33750 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20  ** ^If the most 
33760 72 65 63 65 6e 74 20 65 76 61 6c 75 61 74 69 6f  recent evaluatio
33770 6e 20 6f 66 20 74 68 65 20 73 74 61 74 65 6d 65  n of the stateme
33780 6e 74 20 65 6e 63 6f 75 6e 74 65 72 65 64 20 6e  nt encountered n
33790 6f 20 65 72 72 6f 72 73 0a 2a 2a 20 6f 72 20 69  o errors.** or i
337a0 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  f the statement 
337b0 69 73 20 6e 65 76 65 72 20 62 65 65 6e 20 65 76  is never been ev
337c0 61 6c 75 61 74 65 64 2c 20 74 68 65 6e 20 73 71  aluated, then sq
337d0 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
337e0 20 72 65 74 75 72 6e 73 0a 2a 2a 20 53 51 4c 49   returns.** SQLI
337f0 54 45 5f 4f 4b 2e 20 20 5e 49 66 20 74 68 65 20  TE_OK.  ^If the 
33800 6d 6f 73 74 20 72 65 63 65 6e 74 20 65 76 61 6c  most recent eval
33810 75 61 74 69 6f 6e 20 6f 66 20 73 74 61 74 65 6d  uation of statem
33820 65 6e 74 20 53 20 66 61 69 6c 65 64 2c 20 74 68  ent S failed, th
33830 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 66 69  en.** sqlite3_fi
33840 6e 61 6c 69 7a 65 28 53 29 20 72 65 74 75 72 6e  nalize(S) return
33850 73 20 74 68 65 20 61 70 70 72 6f 70 72 69 61 74  s the appropriat
33860 65 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f  e [error code] o
33870 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 65  r.** [extended e
33880 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a  rror code]..**.*
33890 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 66  * ^The sqlite3_f
338a0 69 6e 61 6c 69 7a 65 28 53 29 20 72 6f 75 74 69  inalize(S) routi
338b0 6e 65 20 63 61 6e 20 62 65 20 63 61 6c 6c 65 64  ne can be called
338c0 20 61 74 20 61 6e 79 20 70 6f 69 6e 74 20 64 75   at any point du
338d0 72 69 6e 67 0a 2a 2a 20 74 68 65 20 6c 69 66 65  ring.** the life
338e0 20 63 79 63 6c 65 20 6f 66 20 5b 70 72 65 70 61   cycle of [prepa
338f0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53  red statement] S
33900 3a 0a 2a 2a 20 62 65 66 6f 72 65 20 73 74 61 74  :.** before stat
33910 65 6d 65 6e 74 20 53 20 69 73 20 65 76 65 72 20  ement S is ever 
33920 65 76 61 6c 75 61 74 65 64 2c 20 61 66 74 65 72  evaluated, after
33930 0a 2a 2a 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20  .** one or more 
33940 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65  calls to [sqlite
33950 33 5f 72 65 73 65 74 28 29 5d 2c 20 6f 72 20 61  3_reset()], or a
33960 66 74 65 72 20 61 6e 79 20 63 61 6c 6c 0a 2a 2a  fter any call.**
33970 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65   to [sqlite3_ste
33980 70 28 29 5d 20 72 65 67 61 72 64 6c 65 73 73 20  p()] regardless 
33990 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f  of whether or no
339a0 74 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  t the statement 
339b0 68 61 73 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 64  has.** completed
339c0 20 65 78 65 63 75 74 69 6f 6e 2e 0a 2a 2a 0a 2a   execution..**.*
339d0 2a 20 5e 49 6e 76 6f 6b 69 6e 67 20 73 71 6c 69  * ^Invoking sqli
339e0 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20 6f  te3_finalize() o
339f0 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  n a NULL pointer
33a00 20 69 73 20 61 20 68 61 72 6d 6c 65 73 73 20 6e   is a harmless n
33a10 6f 2d 6f 70 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  o-op..**.** The 
33a20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74  application must
33a30 20 66 69 6e 61 6c 69 7a 65 20 65 76 65 72 79 20   finalize every 
33a40 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
33a50 65 6e 74 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f  ent] in order to
33a60 20 61 76 6f 69 64 0a 2a 2a 20 72 65 73 6f 75 72   avoid.** resour
33a70 63 65 20 6c 65 61 6b 73 2e 20 20 49 74 20 69 73  ce leaks.  It is
33a80 20 61 20 67 72 69 65 76 6f 75 73 20 65 72 72 6f   a grievous erro
33a90 72 20 66 6f 72 20 74 68 65 20 61 70 70 6c 69 63  r for the applic
33aa0 61 74 69 6f 6e 20 74 6f 20 74 72 79 20 74 6f 20  ation to try to 
33ab0 75 73 65 0a 2a 2a 20 61 20 70 72 65 70 61 72 65  use.** a prepare
33ac0 64 20 73 74 61 74 65 6d 65 6e 74 20 61 66 74 65  d statement afte
33ad0 72 20 69 74 20 68 61 73 20 62 65 65 6e 20 66 69  r it has been fi
33ae0 6e 61 6c 69 7a 65 64 2e 20 20 41 6e 79 20 75 73  nalized.  Any us
33af0 65 20 6f 66 20 61 20 70 72 65 70 61 72 65 64 0a  e of a prepared.
33b00 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 61 66 74  ** statement aft
33b10 65 72 20 69 74 20 68 61 73 20 62 65 65 6e 20 66  er it has been f
33b20 69 6e 61 6c 69 7a 65 64 20 63 61 6e 20 72 65 73  inalized can res
33b30 75 6c 74 20 69 6e 20 75 6e 64 65 66 69 6e 65 64  ult in undefined
33b40 20 61 6e 64 0a 2a 2a 20 75 6e 64 65 73 69 72 61   and.** undesira
33b50 62 6c 65 20 62 65 68 61 76 69 6f 72 20 73 75 63  ble behavior suc
33b60 68 20 61 73 20 73 65 67 66 61 75 6c 74 73 20 61  h as segfaults a
33b70 6e 64 20 68 65 61 70 20 63 6f 72 72 75 70 74 69  nd heap corrupti
33b80 6f 6e 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  on..*/.int sqlit
33b90 65 33 5f 66 69 6e 61 6c 69 7a 65 28 73 71 6c 69  e3_finalize(sqli
33ba0 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29  te3_stmt *pStmt)
33bb0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
33bc0 46 3a 20 52 65 73 65 74 20 41 20 50 72 65 70 61  F: Reset A Prepa
33bd0 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20 4f 62  red Statement Ob
33be0 6a 65 63 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  ject.** METHOD: 
33bf0 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a  sqlite3_stmt.**.
33c00 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72  ** The sqlite3_r
33c10 65 73 65 74 28 29 20 66 75 6e 63 74 69 6f 6e 20  eset() function 
33c20 69 73 20 63 61 6c 6c 65 64 20 74 6f 20 72 65 73  is called to res
33c30 65 74 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  et a [prepared s
33c40 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 6a  tatement].** obj
33c50 65 63 74 20 62 61 63 6b 20 74 6f 20 69 74 73 20  ect back to its 
33c60 69 6e 69 74 69 61 6c 20 73 74 61 74 65 2c 20 72  initial state, r
33c70 65 61 64 79 20 74 6f 20 62 65 20 72 65 2d 65 78  eady to be re-ex
33c80 65 63 75 74 65 64 2e 0a 2a 2a 20 5e 41 6e 79 20  ecuted..** ^Any 
33c90 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 76 61  SQL statement va
33ca0 72 69 61 62 6c 65 73 20 74 68 61 74 20 68 61 64  riables that had
33cb0 20 76 61 6c 75 65 73 20 62 6f 75 6e 64 20 74 6f   values bound to
33cc0 20 74 68 65 6d 20 75 73 69 6e 67 0a 2a 2a 20 74   them using.** t
33cd0 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  he [sqlite3_bind
33ce0 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f  _blob | sqlite3_
33cf0 62 69 6e 64 5f 2a 28 29 20 41 50 49 5d 20 72 65  bind_*() API] re
33d00 74 61 69 6e 20 74 68 65 69 72 20 76 61 6c 75 65  tain their value
33d10 73 2e 0a 2a 2a 20 55 73 65 20 5b 73 71 6c 69 74  s..** Use [sqlit
33d20 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67  e3_clear_binding
33d30 73 28 29 5d 20 74 6f 20 72 65 73 65 74 20 74 68  s()] to reset th
33d40 65 20 62 69 6e 64 69 6e 67 73 2e 0a 2a 2a 0a 2a  e bindings..**.*
33d50 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  * ^The [sqlite3_
33d60 72 65 73 65 74 28 53 29 5d 20 69 6e 74 65 72 66  reset(S)] interf
33d70 61 63 65 20 72 65 73 65 74 73 20 74 68 65 20 5b  ace resets the [
33d80 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
33d90 6e 74 5d 20 53 0a 2a 2a 20 62 61 63 6b 20 74 6f  nt] S.** back to
33da0 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f   the beginning o
33db0 66 20 69 74 73 20 70 72 6f 67 72 61 6d 2e 0a 2a  f its program..*
33dc0 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73  *.** ^If the mos
33dd0 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f  t recent call to
33de0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53   [sqlite3_step(S
33df0 29 5d 20 66 6f 72 20 74 68 65 0a 2a 2a 20 5b 70  )] for the.** [p
33e00 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
33e10 74 5d 20 53 20 72 65 74 75 72 6e 65 64 20 5b 53  t] S returned [S
33e20 51 4c 49 54 45 5f 52 4f 57 5d 20 6f 72 20 5b 53  QLITE_ROW] or [S
33e30 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c 0a 2a 2a 20  QLITE_DONE],.** 
33e40 6f 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 73  or if [sqlite3_s
33e50 74 65 70 28 53 29 5d 20 68 61 73 20 6e 65 76 65  tep(S)] has neve
33e60 72 20 62 65 66 6f 72 65 20 62 65 65 6e 20 63 61  r before been ca
33e70 6c 6c 65 64 20 6f 6e 20 53 2c 0a 2a 2a 20 74 68  lled on S,.** th
33e80 65 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  en [sqlite3_rese
33e90 74 28 53 29 5d 20 72 65 74 75 72 6e 73 20 5b 53  t(S)] returns [S
33ea0 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a  QLITE_OK]..**.**
33eb0 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65   ^If the most re
33ec0 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71  cent call to [sq
33ed0 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 66  lite3_step(S)] f
33ee0 6f 72 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61  or the.** [prepa
33ef0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53  red statement] S
33f00 20 69 6e 64 69 63 61 74 65 64 20 61 6e 20 65 72   indicated an er
33f10 72 6f 72 2c 20 74 68 65 6e 0a 2a 2a 20 5b 73 71  ror, then.** [sq
33f20 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20  lite3_reset(S)] 
33f30 72 65 74 75 72 6e 73 20 61 6e 20 61 70 70 72 6f  returns an appro
33f40 70 72 69 61 74 65 20 5b 65 72 72 6f 72 20 63 6f  priate [error co
33f50 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  de]..**.** ^The 
33f60 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53  [sqlite3_reset(S
33f70 29 5d 20 69 6e 74 65 72 66 61 63 65 20 64 6f 65  )] interface doe
33f80 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65  s not change the
33f90 20 76 61 6c 75 65 73 0a 2a 2a 20 6f 66 20 61 6e   values.** of an
33fa0 79 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  y [sqlite3_bind_
33fb0 62 6c 6f 62 7c 62 69 6e 64 69 6e 67 73 5d 20 6f  blob|bindings] o
33fc0 6e 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20  n the [prepared 
33fd0 73 74 61 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2f  statement] S..*/
33fe0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 72 65 73  .int sqlite3_res
33ff0 65 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  et(sqlite3_stmt 
34000 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  *pStmt);../*.** 
34010 43 41 50 49 33 52 45 46 3a 20 43 72 65 61 74 65  CAPI3REF: Create
34020 20 4f 72 20 52 65 64 65 66 69 6e 65 20 53 51 4c   Or Redefine SQL
34030 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 4b 45   Functions.** KE
34040 59 57 4f 52 44 53 3a 20 7b 66 75 6e 63 74 69 6f  YWORDS: {functio
34050 6e 20 63 72 65 61 74 69 6f 6e 20 72 6f 75 74 69  n creation routi
34060 6e 65 73 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  nes}.** KEYWORDS
34070 3a 20 7b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  : {application-d
34080 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74  efined SQL funct
34090 69 6f 6e 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  ion}.** KEYWORDS
340a0 3a 20 7b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  : {application-d
340b0 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74  efined SQL funct
340c0 69 6f 6e 73 7d 0a 2a 2a 20 4d 45 54 48 4f 44 3a  ions}.** METHOD:
340d0 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e   sqlite3.**.** ^
340e0 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20  These functions 
340f0 28 63 6f 6c 6c 65 63 74 69 76 65 6c 79 20 6b 6e  (collectively kn
34100 6f 77 6e 20 61 73 20 22 66 75 6e 63 74 69 6f 6e  own as "function
34110 20 63 72 65 61 74 69 6f 6e 20 72 6f 75 74 69 6e   creation routin
34120 65 73 22 29 0a 2a 2a 20 61 72 65 20 75 73 65 64  es").** are used
34130 20 74 6f 20 61 64 64 20 53 51 4c 20 66 75 6e 63   to add SQL func
34140 74 69 6f 6e 73 20 6f 72 20 61 67 67 72 65 67 61  tions or aggrega
34150 74 65 73 20 6f 72 20 74 6f 20 72 65 64 65 66 69  tes or to redefi
34160 6e 65 20 74 68 65 20 62 65 68 61 76 69 6f 72 0a  ne the behavior.
34170 2a 2a 20 6f 66 20 65 78 69 73 74 69 6e 67 20 53  ** of existing S
34180 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20  QL functions or 
34190 61 67 67 72 65 67 61 74 65 73 2e 20 20 54 68 65  aggregates.  The
341a0 20 6f 6e 6c 79 20 64 69 66 66 65 72 65 6e 63 65   only difference
341b0 73 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65  s between.** the
341c0 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20  se routines are 
341d0 74 68 65 20 74 65 78 74 20 65 6e 63 6f 64 69 6e  the text encodin
341e0 67 20 65 78 70 65 63 74 65 64 20 66 6f 72 0a 2a  g expected for.*
341f0 2a 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72  * the second par
34200 61 6d 65 74 65 72 20 28 74 68 65 20 6e 61 6d 65  ameter (the name
34210 20 6f 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e   of the function
34220 20 62 65 69 6e 67 20 63 72 65 61 74 65 64 29 0a   being created).
34230 2a 2a 20 61 6e 64 20 74 68 65 20 70 72 65 73 65  ** and the prese
34240 6e 63 65 20 6f 72 20 61 62 73 65 6e 63 65 20 6f  nce or absence o
34250 66 20 61 20 64 65 73 74 72 75 63 74 6f 72 20 63  f a destructor c
34260 61 6c 6c 62 61 63 6b 20 66 6f 72 0a 2a 2a 20 74  allback for.** t
34270 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64  he application d
34280 61 74 61 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a  ata pointer..**.
34290 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 70 61  ** ^The first pa
342a0 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 5b  rameter is the [
342b0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
342c0 69 6f 6e 5d 20 74 6f 20 77 68 69 63 68 20 74 68  ion] to which th
342d0 65 20 53 51 4c 0a 2a 2a 20 66 75 6e 63 74 69 6f  e SQL.** functio
342e0 6e 20 69 73 20 74 6f 20 62 65 20 61 64 64 65 64  n is to be added
342f0 2e 20 20 5e 49 66 20 61 6e 20 61 70 70 6c 69 63  .  ^If an applic
34300 61 74 69 6f 6e 20 75 73 65 73 20 6d 6f 72 65 20  ation uses more 
34310 74 68 61 6e 20 6f 6e 65 20 64 61 74 61 62 61 73  than one databas
34320 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  e.** connection 
34330 74 68 65 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  then application
34340 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e  -defined SQL fun
34350 63 74 69 6f 6e 73 20 6d 75 73 74 20 62 65 20 61  ctions must be a
34360 64 64 65 64 0a 2a 2a 20 74 6f 20 65 61 63 68 20  dded.** to each 
34370 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
34380 69 6f 6e 20 73 65 70 61 72 61 74 65 6c 79 2e 0a  ion separately..
34390 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e  **.** ^The secon
343a0 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74  d parameter is t
343b0 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 53  he name of the S
343c0 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62  QL function to b
343d0 65 20 63 72 65 61 74 65 64 20 6f 72 0a 2a 2a 20  e created or.** 
343e0 72 65 64 65 66 69 6e 65 64 2e 20 20 5e 54 68 65  redefined.  ^The
343f0 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20 6e   length of the n
34400 61 6d 65 20 69 73 20 6c 69 6d 69 74 65 64 20 74  ame is limited t
34410 6f 20 32 35 35 20 62 79 74 65 73 20 69 6e 20 61  o 255 bytes in a
34420 20 55 54 46 2d 38 0a 2a 2a 20 72 65 70 72 65 73   UTF-8.** repres
34430 65 6e 74 61 74 69 6f 6e 2c 20 65 78 63 6c 75 73  entation, exclus
34440 69 76 65 20 6f 66 20 74 68 65 20 7a 65 72 6f 2d  ive of the zero-
34450 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20 5e 4e 6f  terminator.  ^No
34460 74 65 20 74 68 61 74 20 74 68 65 20 6e 61 6d 65  te that the name
34470 0a 2a 2a 20 6c 65 6e 67 74 68 20 6c 69 6d 69 74  .** length limit
34480 20 69 73 20 69 6e 20 55 54 46 2d 38 20 62 79 74   is in UTF-8 byt
34490 65 73 2c 20 6e 6f 74 20 63 68 61 72 61 63 74 65  es, not characte
344a0 72 73 20 6e 6f 72 20 55 54 46 2d 31 36 20 62 79  rs nor UTF-16 by
344b0 74 65 73 2e 20 20 0a 2a 2a 20 5e 41 6e 79 20 61  tes.  .** ^Any a
344c0 74 74 65 6d 70 74 20 74 6f 20 63 72 65 61 74 65  ttempt to create
344d0 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68   a function with
344e0 20 61 20 6c 6f 6e 67 65 72 20 6e 61 6d 65 0a 2a   a longer name.*
344f0 2a 20 77 69 6c 6c 20 72 65 73 75 6c 74 20 69 6e  * will result in
34500 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d   [SQLITE_MISUSE]
34510 20 62 65 69 6e 67 20 72 65 74 75 72 6e 65 64 2e   being returned.
34520 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74 68 69 72  .**.** ^The thir
34530 64 20 70 61 72 61 6d 65 74 65 72 20 28 6e 41 72  d parameter (nAr
34540 67 29 0a 2a 2a 20 69 73 20 74 68 65 20 6e 75 6d  g).** is the num
34550 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73  ber of arguments
34560 20 74 68 61 74 20 74 68 65 20 53 51 4c 20 66 75   that the SQL fu
34570 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67  nction or.** agg
34580 72 65 67 61 74 65 20 74 61 6b 65 73 2e 20 5e 49  regate takes. ^I
34590 66 20 74 68 69 73 20 70 61 72 61 6d 65 74 65 72  f this parameter
345a0 20 69 73 20 2d 31 2c 20 74 68 65 6e 20 74 68 65   is -1, then the
345b0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72   SQL function or
345c0 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 20 6d 61  .** aggregate ma
345d0 79 20 74 61 6b 65 20 61 6e 79 20 6e 75 6d 62 65  y take any numbe
345e0 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 62  r of arguments b
345f0 65 74 77 65 65 6e 20 30 20 61 6e 64 20 74 68 65  etween 0 and the
34600 20 6c 69 6d 69 74 0a 2a 2a 20 73 65 74 20 62 79   limit.** set by
34610 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 5d   [sqlite3_limit]
34620 28 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46  ([SQLITE_LIMIT_F
34630 55 4e 43 54 49 4f 4e 5f 41 52 47 5d 29 2e 20 20  UNCTION_ARG]).  
34640 49 66 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20  If the third.** 
34650 70 61 72 61 6d 65 74 65 72 20 69 73 20 6c 65 73  parameter is les
34660 73 20 74 68 61 6e 20 2d 31 20 6f 72 20 67 72 65  s than -1 or gre
34670 61 74 65 72 20 74 68 61 6e 20 31 32 37 20 74 68  ater than 127 th
34680 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  en the behavior 
34690 69 73 0a 2a 2a 20 75 6e 64 65 66 69 6e 65 64 2e  is.** undefined.
346a0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 72  .**.** ^The four
346b0 74 68 20 70 61 72 61 6d 65 74 65 72 2c 20 65 54  th parameter, eT
346c0 65 78 74 52 65 70 2c 20 73 70 65 63 69 66 69 65  extRep, specifie
346d0 73 20 77 68 61 74 0a 2a 2a 20 5b 53 51 4c 49 54  s what.** [SQLIT
346e0 45 5f 55 54 46 38 20 7c 20 74 65 78 74 20 65 6e  E_UTF8 | text en
346f0 63 6f 64 69 6e 67 5d 20 74 68 69 73 20 53 51 4c  coding] this SQL
34700 20 66 75 6e 63 74 69 6f 6e 20 70 72 65 66 65 72   function prefer
34710 73 20 66 6f 72 0a 2a 2a 20 69 74 73 20 70 61 72  s for.** its par
34720 61 6d 65 74 65 72 73 2e 20 20 54 68 65 20 61 70  ameters.  The ap
34730 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64  plication should
34740 20 73 65 74 20 74 68 69 73 20 70 61 72 61 6d 65   set this parame
34750 74 65 72 20 74 6f 0a 2a 2a 20 5b 53 51 4c 49 54  ter to.** [SQLIT
34760 45 5f 55 54 46 31 36 4c 45 5d 20 69 66 20 74 68  E_UTF16LE] if th
34770 65 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65  e function imple
34780 6d 65 6e 74 61 74 69 6f 6e 20 69 6e 76 6f 6b 65  mentation invoke
34790 73 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76  s .** [sqlite3_v
347a0 61 6c 75 65 5f 74 65 78 74 31 36 6c 65 28 29 5d  alue_text16le()]
347b0 20 6f 6e 20 61 6e 20 69 6e 70 75 74 2c 20 6f 72   on an input, or
347c0 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45   [SQLITE_UTF16BE
347d0 5d 20 69 66 20 74 68 65 0a 2a 2a 20 69 6d 70 6c  ] if the.** impl
347e0 65 6d 65 6e 74 61 74 69 6f 6e 20 69 6e 76 6f 6b  ementation invok
347f0 65 73 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  es [sqlite3_valu
34800 65 5f 74 65 78 74 31 36 62 65 28 29 5d 20 6f 6e  e_text16be()] on
34810 20 61 6e 20 69 6e 70 75 74 2c 20 6f 72 0a 2a 2a   an input, or.**
34820 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5d 20   [SQLITE_UTF16] 
34830 69 66 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  if [sqlite3_valu
34840 65 5f 74 65 78 74 31 36 28 29 5d 20 69 73 20 75  e_text16()] is u
34850 73 65 64 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f  sed, or [SQLITE_
34860 55 54 46 38 5d 0a 2a 2a 20 6f 74 68 65 72 77 69  UTF8].** otherwi
34870 73 65 2e 20 20 5e 54 68 65 20 73 61 6d 65 20 53  se.  ^The same S
34880 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79 20  QL function may 
34890 62 65 20 72 65 67 69 73 74 65 72 65 64 20 6d 75  be registered mu
348a0 6c 74 69 70 6c 65 20 74 69 6d 65 73 20 75 73 69  ltiple times usi
348b0 6e 67 0a 2a 2a 20 64 69 66 66 65 72 65 6e 74 20  ng.** different 
348c0 70 72 65 66 65 72 72 65 64 20 74 65 78 74 20 65  preferred text e
348d0 6e 63 6f 64 69 6e 67 73 2c 20 77 69 74 68 20 64  ncodings, with d
348e0 69 66 66 65 72 65 6e 74 20 69 6d 70 6c 65 6d 65  ifferent impleme
348f0 6e 74 61 74 69 6f 6e 73 20 66 6f 72 0a 2a 2a 20  ntations for.** 
34900 65 61 63 68 20 65 6e 63 6f 64 69 6e 67 2e 0a 2a  each encoding..*
34910 2a 20 5e 57 68 65 6e 20 6d 75 6c 74 69 70 6c 65  * ^When multiple
34920 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
34930 20 6f 66 20 74 68 65 20 73 61 6d 65 20 66 75 6e   of the same fun
34940 63 74 69 6f 6e 20 61 72 65 20 61 76 61 69 6c 61  ction are availa
34950 62 6c 65 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 77  ble, SQLite.** w
34960 69 6c 6c 20 70 69 63 6b 20 74 68 65 20 6f 6e 65  ill pick the one
34970 20 74 68 61 74 20 69 6e 76 6f 6c 76 65 73 20 74   that involves t
34980 68 65 20 6c 65 61 73 74 20 61 6d 6f 75 6e 74 20  he least amount 
34990 6f 66 20 64 61 74 61 20 63 6f 6e 76 65 72 73 69  of data conversi
349a0 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66  on..**.** ^The f
349b0 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
349c0 6d 61 79 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 62  may optionally b
349d0 65 20 4f 52 65 64 20 77 69 74 68 20 5b 53 51 4c  e ORed with [SQL
349e0 49 54 45 5f 44 45 54 45 52 4d 49 4e 49 53 54 49  ITE_DETERMINISTI
349f0 43 5d 0a 2a 2a 20 74 6f 20 73 69 67 6e 61 6c 20  C].** to signal 
34a00 74 68 61 74 20 74 68 65 20 66 75 6e 63 74 69 6f  that the functio
34a10 6e 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 72 65  n will always re
34a20 74 75 72 6e 20 74 68 65 20 73 61 6d 65 20 72 65  turn the same re
34a30 73 75 6c 74 20 67 69 76 65 6e 0a 2a 2a 20 74 68  sult given.** th
34a40 65 20 73 61 6d 65 20 69 6e 70 75 74 73 20 77 69  e same inputs wi
34a50 74 68 69 6e 20 61 20 73 69 6e 67 6c 65 20 53 51  thin a single SQ
34a60 4c 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 4d 6f  L statement.  Mo
34a70 73 74 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  st SQL functions
34a80 20 61 72 65 0a 2a 2a 20 64 65 74 65 72 6d 69 6e   are.** determin
34a90 69 73 74 69 63 2e 20 20 54 68 65 20 62 75 69 6c  istic.  The buil
34aa0 74 2d 69 6e 20 5b 72 61 6e 64 6f 6d 28 29 5d 20  t-in [random()] 
34ab0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  SQL function is 
34ac0 61 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20 61 0a  an example of a.
34ad0 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74  ** function that
34ae0 20 69 73 20 6e 6f 74 20 64 65 74 65 72 6d 69 6e   is not determin
34af0 69 73 74 69 63 2e 20 20 54 68 65 20 53 51 4c 69  istic.  The SQLi
34b00 74 65 20 71 75 65 72 79 20 70 6c 61 6e 6e 65 72  te query planner
34b10 20 69 73 20 61 62 6c 65 20 74 6f 0a 2a 2a 20 70   is able to.** p
34b20 65 72 66 6f 72 6d 20 61 64 64 69 74 69 6f 6e 61  erform additiona
34b30 6c 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 73 20  l optimizations 
34b40 6f 6e 20 64 65 74 65 72 6d 69 6e 69 73 74 69 63  on deterministic
34b50 20 66 75 6e 63 74 69 6f 6e 73 2c 20 73 6f 20 75   functions, so u
34b60 73 65 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 53 51  se.** of the [SQ
34b70 4c 49 54 45 5f 44 45 54 45 52 4d 49 4e 49 53 54  LITE_DETERMINIST
34b80 49 43 5d 20 66 6c 61 67 20 69 73 20 72 65 63 6f  IC] flag is reco
34b90 6d 6d 65 6e 64 65 64 20 77 68 65 72 65 20 70 6f  mmended where po
34ba0 73 73 69 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28  ssible..**.** ^(
34bb0 54 68 65 20 66 69 66 74 68 20 70 61 72 61 6d 65  The fifth parame
34bc0 74 65 72 20 69 73 20 61 6e 20 61 72 62 69 74 72  ter is an arbitr
34bd0 61 72 79 20 70 6f 69 6e 74 65 72 2e 20 20 54 68  ary pointer.  Th
34be0 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
34bf0 20 6f 66 20 74 68 65 0a 2a 2a 20 66 75 6e 63 74   of the.** funct
34c00 69 6f 6e 20 63 61 6e 20 67 61 69 6e 20 61 63 63  ion can gain acc
34c10 65 73 73 20 74 6f 20 74 68 69 73 20 70 6f 69 6e  ess to this poin
34c20 74 65 72 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ter using [sqlit
34c30 65 33 5f 75 73 65 72 5f 64 61 74 61 28 29 5d 2e  e3_user_data()].
34c40 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 69  )^.**.** ^The si
34c50 78 74 68 2c 20 73 65 76 65 6e 74 68 20 61 6e 64  xth, seventh and
34c60 20 65 69 67 68 74 68 20 70 61 72 61 6d 65 74 65   eighth paramete
34c70 72 73 2c 20 78 46 75 6e 63 2c 20 78 53 74 65 70  rs, xFunc, xStep
34c80 20 61 6e 64 20 78 46 69 6e 61 6c 2c 20 61 72 65   and xFinal, are
34c90 0a 2a 2a 20 70 6f 69 6e 74 65 72 73 20 74 6f 20  .** pointers to 
34ca0 43 2d 6c 61 6e 67 75 61 67 65 20 66 75 6e 63 74  C-language funct
34cb0 69 6f 6e 73 20 74 68 61 74 20 69 6d 70 6c 65 6d  ions that implem
34cc0 65 6e 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63  ent the SQL func
34cd0 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65  tion or.** aggre
34ce0 67 61 74 65 2e 20 5e 41 20 73 63 61 6c 61 72 20  gate. ^A scalar 
34cf0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65 71  SQL function req
34d00 75 69 72 65 73 20 61 6e 20 69 6d 70 6c 65 6d 65  uires an impleme
34d10 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 78  ntation of the x
34d20 46 75 6e 63 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b  Func.** callback
34d30 20 6f 6e 6c 79 3b 20 4e 55 4c 4c 20 70 6f 69 6e   only; NULL poin
34d40 74 65 72 73 20 6d 75 73 74 20 62 65 20 70 61 73  ters must be pas
34d50 73 65 64 20 61 73 20 74 68 65 20 78 53 74 65 70  sed as the xStep
34d60 20 61 6e 64 20 78 46 69 6e 61 6c 0a 2a 2a 20 70   and xFinal.** p
34d70 61 72 61 6d 65 74 65 72 73 2e 20 5e 41 6e 20 61  arameters. ^An a
34d80 67 67 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e  ggregate SQL fun
34d90 63 74 69 6f 6e 20 72 65 71 75 69 72 65 73 20 61  ction requires a
34da0 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  n implementation
34db0 20 6f 66 20 78 53 74 65 70 0a 2a 2a 20 61 6e 64   of xStep.** and
34dc0 20 78 46 69 6e 61 6c 20 61 6e 64 20 4e 55 4c 4c   xFinal and NULL
34dd0 20 70 6f 69 6e 74 65 72 20 6d 75 73 74 20 62 65   pointer must be
34de0 20 70 61 73 73 65 64 20 66 6f 72 20 78 46 75 6e   passed for xFun
34df0 63 2e 20 5e 54 6f 20 64 65 6c 65 74 65 20 61 6e  c. ^To delete an
34e00 20 65 78 69 73 74 69 6e 67 0a 2a 2a 20 53 51 4c   existing.** SQL
34e10 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67   function or agg
34e20 72 65 67 61 74 65 2c 20 70 61 73 73 20 4e 55 4c  regate, pass NUL
34e30 4c 20 70 6f 69 6e 74 65 72 73 20 66 6f 72 20 61  L pointers for a
34e40 6c 6c 20 74 68 72 65 65 20 66 75 6e 63 74 69 6f  ll three functio
34e50 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 73 2e 0a  n.** callbacks..
34e60 2a 2a 0a 2a 2a 20 5e 28 49 66 20 74 68 65 20 6e  **.** ^(If the n
34e70 69 6e 74 68 20 70 61 72 61 6d 65 74 65 72 20 74  inth parameter t
34e80 6f 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  o sqlite3_create
34e90 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28 29 20 69  _function_v2() i
34ea0 73 20 6e 6f 74 20 4e 55 4c 4c 2c 0a 2a 2a 20 74  s not NULL,.** t
34eb0 68 65 6e 20 69 74 20 69 73 20 64 65 73 74 72 75  hen it is destru
34ec0 63 74 6f 72 20 66 6f 72 20 74 68 65 20 61 70 70  ctor for the app
34ed0 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20 70 6f  lication data po
34ee0 69 6e 74 65 72 2e 20 0a 2a 2a 20 54 68 65 20 64  inter. .** The d
34ef0 65 73 74 72 75 63 74 6f 72 20 69 73 20 69 6e 76  estructor is inv
34f00 6f 6b 65 64 20 77 68 65 6e 20 74 68 65 20 66 75  oked when the fu
34f10 6e 63 74 69 6f 6e 20 69 73 20 64 65 6c 65 74 65  nction is delete
34f20 64 2c 20 65 69 74 68 65 72 20 62 79 20 62 65 69  d, either by bei
34f30 6e 67 0a 2a 2a 20 6f 76 65 72 6c 6f 61 64 65 64  ng.** overloaded
34f40 20 6f 72 20 77 68 65 6e 20 74 68 65 20 64 61 74   or when the dat
34f50 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
34f60 20 63 6c 6f 73 65 73 2e 29 5e 0a 2a 2a 20 5e 54   closes.)^.** ^T
34f70 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 69 73  he destructor is
34f80 20 61 6c 73 6f 20 69 6e 76 6f 6b 65 64 20 69 66   also invoked if
34f90 20 74 68 65 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20   the call to.** 
34fa0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
34fb0 75 6e 63 74 69 6f 6e 5f 76 32 28 29 20 66 61 69  unction_v2() fai
34fc0 6c 73 2e 0a 2a 2a 20 5e 57 68 65 6e 20 74 68 65  ls..** ^When the
34fd0 20 64 65 73 74 72 75 63 74 6f 72 20 63 61 6c 6c   destructor call
34fe0 62 61 63 6b 20 6f 66 20 74 68 65 20 74 65 6e 74  back of the tent
34ff0 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 69  h parameter is i
35000 6e 76 6f 6b 65 64 2c 20 69 74 0a 2a 2a 20 69 73  nvoked, it.** is
35010 20 70 61 73 73 65 64 20 61 20 73 69 6e 67 6c 65   passed a single
35020 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20   argument which 
35030 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  is a copy of the
35040 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74   application dat
35050 61 20 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 77 68  a .** pointer wh
35060 69 63 68 20 77 61 73 20 74 68 65 20 66 69 66 74  ich was the fift
35070 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  h parameter to s
35080 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
35090 6e 63 74 69 6f 6e 5f 76 32 28 29 2e 0a 2a 2a 0a  nction_v2()..**.
350a0 2a 2a 20 5e 49 74 20 69 73 20 70 65 72 6d 69 74  ** ^It is permit
350b0 74 65 64 20 74 6f 20 72 65 67 69 73 74 65 72 20  ted to register 
350c0 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65  multiple impleme
350d0 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20  ntations of the 
350e0 73 61 6d 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  same.** function
350f0 73 20 77 69 74 68 20 74 68 65 20 73 61 6d 65 20  s with the same 
35100 6e 61 6d 65 20 62 75 74 20 77 69 74 68 20 65 69  name but with ei
35110 74 68 65 72 20 64 69 66 66 65 72 69 6e 67 20 6e  ther differing n
35120 75 6d 62 65 72 73 20 6f 66 0a 2a 2a 20 61 72 67  umbers of.** arg
35130 75 6d 65 6e 74 73 20 6f 72 20 64 69 66 66 65 72  uments or differ
35140 69 6e 67 20 70 72 65 66 65 72 72 65 64 20 74 65  ing preferred te
35150 78 74 20 65 6e 63 6f 64 69 6e 67 73 2e 20 20 5e  xt encodings.  ^
35160 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 0a  SQLite will use.
35170 2a 2a 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74  ** the implement
35180 61 74 69 6f 6e 20 74 68 61 74 20 6d 6f 73 74 20  ation that most 
35190 63 6c 6f 73 65 6c 79 20 6d 61 74 63 68 65 73 20  closely matches 
351a0 74 68 65 20 77 61 79 20 69 6e 20 77 68 69 63 68  the way in which
351b0 20 74 68 65 0a 2a 2a 20 53 51 4c 20 66 75 6e 63   the.** SQL func
351c0 74 69 6f 6e 20 69 73 20 75 73 65 64 2e 20 20 5e  tion is used.  ^
351d0 41 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65  A function imple
351e0 6d 65 6e 74 61 74 69 6f 6e 20 77 69 74 68 20 61  mentation with a
351f0 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 0a 2a 2a   non-negative.**
35200 20 6e 41 72 67 20 70 61 72 61 6d 65 74 65 72 20   nArg parameter 
35210 69 73 20 61 20 62 65 74 74 65 72 20 6d 61 74 63  is a better matc
35220 68 20 74 68 61 6e 20 61 20 66 75 6e 63 74 69 6f  h than a functio
35230 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  n implementation
35240 20 77 69 74 68 0a 2a 2a 20 61 20 6e 65 67 61 74   with.** a negat
35250 69 76 65 20 6e 41 72 67 2e 20 20 5e 41 20 66 75  ive nArg.  ^A fu
35260 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65  nction where the
35270 20 70 72 65 66 65 72 72 65 64 20 74 65 78 74 20   preferred text 
35280 65 6e 63 6f 64 69 6e 67 0a 2a 2a 20 6d 61 74 63  encoding.** matc
35290 68 65 73 20 74 68 65 20 64 61 74 61 62 61 73 65  hes the database
352a0 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 61 20 62   encoding is a b
352b0 65 74 74 65 72 0a 2a 2a 20 6d 61 74 63 68 20 74  etter.** match t
352c0 68 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 77  han a function w
352d0 68 65 72 65 20 74 68 65 20 65 6e 63 6f 64 69 6e  here the encodin
352e0 67 20 69 73 20 64 69 66 66 65 72 65 6e 74 2e 20  g is different. 
352f0 20 0a 2a 2a 20 5e 41 20 66 75 6e 63 74 69 6f 6e   .** ^A function
35300 20 77 68 65 72 65 20 74 68 65 20 65 6e 63 6f 64   where the encod
35310 69 6e 67 20 64 69 66 66 65 72 65 6e 63 65 20 69  ing difference i
35320 73 20 62 65 74 77 65 65 6e 20 55 54 46 31 36 6c  s between UTF16l
35330 65 20 61 6e 64 20 55 54 46 31 36 62 65 0a 2a 2a  e and UTF16be.**
35340 20 69 73 20 61 20 63 6c 6f 73 65 72 20 6d 61 74   is a closer mat
35350 63 68 20 74 68 61 6e 20 61 20 66 75 6e 63 74 69  ch than a functi
35360 6f 6e 20 77 68 65 72 65 20 74 68 65 20 65 6e 63  on where the enc
35370 6f 64 69 6e 67 20 64 69 66 66 65 72 65 6e 63 65  oding difference
35380 20 69 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20 55   is.** between U
35390 54 46 38 20 61 6e 64 20 55 54 46 31 36 2e 0a 2a  TF8 and UTF16..*
353a0 2a 0a 2a 2a 20 5e 42 75 69 6c 74 2d 69 6e 20 66  *.** ^Built-in f
353b0 75 6e 63 74 69 6f 6e 73 20 6d 61 79 20 62 65 20  unctions may be 
353c0 6f 76 65 72 6c 6f 61 64 65 64 20 62 79 20 6e 65  overloaded by ne
353d0 77 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  w application-de
353e0 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 73 2e  fined functions.
353f0 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 61 70 70 6c 69  .**.** ^An appli
35400 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
35410 75 6e 63 74 69 6f 6e 20 69 73 20 70 65 72 6d 69  unction is permi
35420 74 74 65 64 20 74 6f 20 63 61 6c 6c 20 6f 74 68  tted to call oth
35430 65 72 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74  er.** SQLite int
35440 65 72 66 61 63 65 73 2e 20 20 48 6f 77 65 76 65  erfaces.  Howeve
35450 72 2c 20 73 75 63 68 20 63 61 6c 6c 73 20 6d 75  r, such calls mu
35460 73 74 20 6e 6f 74 0a 2a 2a 20 63 6c 6f 73 65 20  st not.** close 
35470 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
35480 6e 65 63 74 69 6f 6e 20 6e 6f 72 20 66 69 6e 61  nection nor fina
35490 6c 69 7a 65 20 6f 72 20 72 65 73 65 74 20 74 68  lize or reset th
354a0 65 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74  e prepared.** st
354b0 61 74 65 6d 65 6e 74 20 69 6e 20 77 68 69 63 68  atement in which
354c0 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 73   the function is
354d0 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 69 6e 74   running..*/.int
354e0 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
354f0 66 75 6e 63 74 69 6f 6e 28 0a 20 20 73 71 6c 69  function(.  sqli
35500 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74  te3 *db,.  const
35510 20 63 68 61 72 20 2a 7a 46 75 6e 63 74 69 6f 6e   char *zFunction
35520 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67  Name,.  int nArg
35530 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70  ,.  int eTextRep
35540 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a  ,.  void *pApp,.
35550 20 20 76 6f 69 64 20 28 2a 78 46 75 6e 63 29 28    void (*xFunc)(
35560 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
35570 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c  ,int,sqlite3_val
35580 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a  ue**),.  void (*
35590 78 53 74 65 70 29 28 73 71 6c 69 74 65 33 5f 63  xStep)(sqlite3_c
355a0 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69  ontext*,int,sqli
355b0 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20  te3_value**),.  
355c0 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29 28 73  void (*xFinal)(s
355d0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29  qlite3_context*)
355e0 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .);.int sqlite3_
355f0 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31  create_function1
35600 36 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  6(.  sqlite3 *db
35610 2c 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a  ,.  const void *
35620 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20  zFunctionName,. 
35630 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74   int nArg,.  int
35640 20 65 54 65 78 74 52 65 70 2c 0a 20 20 76 6f 69   eTextRep,.  voi
35650 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64 20  d *pApp,.  void 
35660 28 2a 78 46 75 6e 63 29 28 73 71 6c 69 74 65 33  (*xFunc)(sqlite3
35670 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71  _context*,int,sq
35680 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a  lite3_value**),.
35690 20 20 76 6f 69 64 20 28 2a 78 53 74 65 70 29 28    void (*xStep)(
356a0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
356b0 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c  ,int,sqlite3_val
356c0 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a  ue**),.  void (*
356d0 78 46 69 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f  xFinal)(sqlite3_
356e0 63 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a 69 6e 74  context*).);.int
356f0 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
35700 66 75 6e 63 74 69 6f 6e 5f 76 32 28 0a 20 20 73  function_v2(.  s
35710 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f  qlite3 *db,.  co
35720 6e 73 74 20 63 68 61 72 20 2a 7a 46 75 6e 63 74  nst char *zFunct
35730 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e  ionName,.  int n
35740 41 72 67 2c 0a 20 20 69 6e 74 20 65 54 65 78 74  Arg,.  int eText
35750 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70  Rep,.  void *pAp
35760 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 75 6e  p,.  void (*xFun
35770 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  c)(sqlite3_conte
35780 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f  xt*,int,sqlite3_
35790 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64  value**),.  void
357a0 20 28 2a 78 53 74 65 70 29 28 73 71 6c 69 74 65   (*xStep)(sqlite
357b0 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73  3_context*,int,s
357c0 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c  qlite3_value**),
357d0 0a 20 20 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c  .  void (*xFinal
357e0 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  )(sqlite3_contex
357f0 74 2a 29 2c 0a 20 20 76 6f 69 64 28 2a 78 44 65  t*),.  void(*xDe
35800 73 74 72 6f 79 29 28 76 6f 69 64 2a 29 0a 29 3b  stroy)(void*).);
35810 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
35820 3a 20 54 65 78 74 20 45 6e 63 6f 64 69 6e 67 73  : Text Encodings
35830 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e  .**.** These con
35840 73 74 61 6e 74 20 64 65 66 69 6e 65 20 69 6e 74  stant define int
35850 65 67 65 72 20 63 6f 64 65 73 20 74 68 61 74 20  eger codes that 
35860 72 65 70 72 65 73 65 6e 74 20 74 68 65 20 76 61  represent the va
35870 72 69 6f 75 73 0a 2a 2a 20 74 65 78 74 20 65 6e  rious.** text en
35880 63 6f 64 69 6e 67 73 20 73 75 70 70 6f 72 74 65  codings supporte
35890 64 20 62 79 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a  d by SQLite..*/.
358a0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55  #define SQLITE_U
358b0 54 46 38 20 20 20 20 20 20 20 20 20 20 20 31 20  TF8           1 
358c0 20 20 20 2f 2a 20 49 4d 50 3a 20 52 2d 33 37 35     /* IMP: R-375
358d0 31 34 2d 33 35 35 36 36 20 2a 2f 0a 23 64 65 66  14-35566 */.#def
358e0 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36  ine SQLITE_UTF16
358f0 4c 45 20 20 20 20 20 20 20 20 32 20 20 20 20 2f  LE        2    /
35900 2a 20 49 4d 50 3a 20 52 2d 30 33 33 37 31 2d 33  * IMP: R-03371-3
35910 37 36 33 37 20 2a 2f 0a 23 64 65 66 69 6e 65 20  7637 */.#define 
35920 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45 20 20  SQLITE_UTF16BE  
35930 20 20 20 20 20 20 33 20 20 20 20 2f 2a 20 49 4d        3    /* IM
35940 50 3a 20 52 2d 35 31 39 37 31 2d 33 34 31 35 34  P: R-51971-34154
35950 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
35960 54 45 5f 55 54 46 31 36 20 20 20 20 20 20 20 20  TE_UTF16        
35970 20 20 34 20 20 20 20 2f 2a 20 55 73 65 20 6e 61    4    /* Use na
35980 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 20  tive byte order 
35990 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
359a0 45 5f 41 4e 59 20 20 20 20 20 20 20 20 20 20 20  E_ANY           
359b0 20 35 20 20 20 20 2f 2a 20 44 65 70 72 65 63 61   5    /* Depreca
359c0 74 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ted */.#define S
359d0 51 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c 49 47  QLITE_UTF16_ALIG
359e0 4e 45 44 20 20 38 20 20 20 20 2f 2a 20 73 71 6c  NED  8    /* sql
359f0 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
35a00 61 74 69 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a 0a 2f  ation only */../
35a10 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46  *.** CAPI3REF: F
35a20 75 6e 63 74 69 6f 6e 20 46 6c 61 67 73 0a 2a 2a  unction Flags.**
35a30 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61  .** These consta
35a40 6e 74 73 20 6d 61 79 20 62 65 20 4f 52 65 64 20  nts may be ORed 
35a50 74 6f 67 65 74 68 65 72 20 77 69 74 68 20 74 68  together with th
35a60 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54  e .** [SQLITE_UT
35a70 46 38 20 7c 20 70 72 65 66 65 72 72 65 64 20 74  F8 | preferred t
35a80 65 78 74 20 65 6e 63 6f 64 69 6e 67 5d 20 61 73  ext encoding] as
35a90 20 74 68 65 20 66 6f 75 72 74 68 20 61 72 67 75   the fourth argu
35aa0 6d 65 6e 74 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69  ment.** to [sqli
35ab0 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
35ac0 69 6f 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  ion()], [sqlite3
35ad0 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
35ae0 31 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71  16()], or.** [sq
35af0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
35b00 63 74 69 6f 6e 5f 76 32 28 29 5d 2e 0a 2a 2f 0a  ction_v2()]..*/.
35b10 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
35b20 45 54 45 52 4d 49 4e 49 53 54 49 43 20 20 20 20  ETERMINISTIC    
35b30 30 78 38 30 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  0x800../*.** CAP
35b40 49 33 52 45 46 3a 20 44 65 70 72 65 63 61 74 65  I3REF: Deprecate
35b50 64 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 44  d Functions.** D
35b60 45 50 52 45 43 41 54 45 44 0a 2a 2a 0a 2a 2a 20  EPRECATED.**.** 
35b70 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20  These functions 
35b80 61 72 65 20 5b 64 65 70 72 65 63 61 74 65 64 5d  are [deprecated]
35b90 2e 20 20 49 6e 20 6f 72 64 65 72 20 74 6f 20 6d  .  In order to m
35ba0 61 69 6e 74 61 69 6e 0a 2a 2a 20 62 61 63 6b 77  aintain.** backw
35bb0 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69  ards compatibili
35bc0 74 79 20 77 69 74 68 20 6f 6c 64 65 72 20 63 6f  ty with older co
35bd0 64 65 2c 20 74 68 65 73 65 20 66 75 6e 63 74 69  de, these functi
35be0 6f 6e 73 20 63 6f 6e 74 69 6e 75 65 20 0a 2a 2a  ons continue .**
35bf0 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64   to be supported
35c00 2e 20 20 48 6f 77 65 76 65 72 2c 20 6e 65 77 20  .  However, new 
35c10 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f  applications sho
35c20 75 6c 64 20 61 76 6f 69 64 0a 2a 2a 20 74 68 65  uld avoid.** the
35c30 20 75 73 65 20 6f 66 20 74 68 65 73 65 20 66 75   use of these fu
35c40 6e 63 74 69 6f 6e 73 2e 20 20 54 6f 20 65 6e 63  nctions.  To enc
35c50 6f 75 72 61 67 65 20 70 72 6f 67 72 61 6d 6d 65  ourage programme
35c60 72 73 20 74 6f 20 61 76 6f 69 64 0a 2a 2a 20 74  rs to avoid.** t
35c70 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 2c 20  hese functions, 
35c80 77 65 20 77 69 6c 6c 20 6e 6f 74 20 65 78 70 6c  we will not expl
35c90 61 69 6e 20 77 68 61 74 20 74 68 65 79 20 64 6f  ain what they do
35ca0 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c  ..*/.#ifndef SQL
35cb0 49 54 45 5f 4f 4d 49 54 5f 44 45 50 52 45 43 41  ITE_OMIT_DEPRECA
35cc0 54 45 44 0a 53 51 4c 49 54 45 5f 44 45 50 52 45  TED.SQLITE_DEPRE
35cd0 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65  CATED int sqlite
35ce0 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 75 6e  3_aggregate_coun
35cf0 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  t(sqlite3_contex
35d00 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52  t*);.SQLITE_DEPR
35d10 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74  ECATED int sqlit
35d20 65 33 5f 65 78 70 69 72 65 64 28 73 71 6c 69 74  e3_expired(sqlit
35d30 65 33 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c 49 54  e3_stmt*);.SQLIT
35d40 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e 74  E_DEPRECATED int
35d50 20 73 71 6c 69 74 65 33 5f 74 72 61 6e 73 66 65   sqlite3_transfe
35d60 72 5f 62 69 6e 64 69 6e 67 73 28 73 71 6c 69 74  r_bindings(sqlit
35d70 65 33 5f 73 74 6d 74 2a 2c 20 73 71 6c 69 74 65  e3_stmt*, sqlite
35d80 33 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c 49 54 45  3_stmt*);.SQLITE
35d90 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e 74 20  _DEPRECATED int 
35da0 73 71 6c 69 74 65 33 5f 67 6c 6f 62 61 6c 5f 72  sqlite3_global_r
35db0 65 63 6f 76 65 72 28 76 6f 69 64 29 3b 0a 53 51  ecover(void);.SQ
35dc0 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20  LITE_DEPRECATED 
35dd0 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 74 68 72  void sqlite3_thr
35de0 65 61 64 5f 63 6c 65 61 6e 75 70 28 76 6f 69 64  ead_cleanup(void
35df0 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43  );.SQLITE_DEPREC
35e00 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33  ATED int sqlite3
35e10 5f 6d 65 6d 6f 72 79 5f 61 6c 61 72 6d 28 76 6f  _memory_alarm(vo
35e20 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69  id(*)(void*,sqli
35e30 74 65 33 5f 69 6e 74 36 34 2c 69 6e 74 29 2c 0a  te3_int64,int),.
35e40 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
35e50 20 20 20 20 20 20 76 6f 69 64 2a 2c 73 71 6c 69        void*,sqli
35e60 74 65 33 5f 69 6e 74 36 34 29 3b 0a 23 65 6e 64  te3_int64);.#end
35e70 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  if../*.** CAPI3R
35e80 45 46 3a 20 4f 62 74 61 69 6e 69 6e 67 20 53 51  EF: Obtaining SQ
35e90 4c 20 56 61 6c 75 65 73 0a 2a 2a 20 4d 45 54 48  L Values.** METH
35ea0 4f 44 3a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  OD: sqlite3_valu
35eb0 65 0a 2a 2a 0a 2a 2a 20 54 68 65 20 43 2d 6c 61  e.**.** The C-la
35ec0 6e 67 75 61 67 65 20 69 6d 70 6c 65 6d 65 6e 74  nguage implement
35ed0 61 74 69 6f 6e 20 6f 66 20 53 51 4c 20 66 75 6e  ation of SQL fun
35ee0 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 65  ctions and aggre
35ef0 67 61 74 65 73 20 75 73 65 73 0a 2a 2a 20 74 68  gates uses.** th
35f00 69 73 20 73 65 74 20 6f 66 20 69 6e 74 65 72 66  is set of interf
35f10 61 63 65 20 72 6f 75 74 69 6e 65 73 20 74 6f 20  ace routines to 
35f20 61 63 63 65 73 73 20 74 68 65 20 70 61 72 61 6d  access the param
35f30 65 74 65 72 20 76 61 6c 75 65 73 20 6f 6e 0a 2a  eter values on.*
35f40 2a 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 6f  * the function o
35f50 72 20 61 67 67 72 65 67 61 74 65 2e 20 20 0a 2a  r aggregate.  .*
35f60 2a 0a 2a 2a 20 54 68 65 20 78 46 75 6e 63 20 28  *.** The xFunc (
35f70 66 6f 72 20 73 63 61 6c 61 72 20 66 75 6e 63 74  for scalar funct
35f80 69 6f 6e 73 29 20 6f 72 20 78 53 74 65 70 20 28  ions) or xStep (
35f90 66 6f 72 20 61 67 67 72 65 67 61 74 65 73 29 20  for aggregates) 
35fa0 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 74 6f  parameters.** to
35fb0 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
35fc0 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 20 61 6e 64  _function()] and
35fd0 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
35fe0 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 0a 2a  _function16()].*
35ff0 2a 20 64 65 66 69 6e 65 20 63 61 6c 6c 62 61 63  * define callbac
36000 6b 73 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e  ks that implemen
36010 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69  t the SQL functi
36020 6f 6e 73 20 61 6e 64 20 61 67 67 72 65 67 61 74  ons and aggregat
36030 65 73 2e 0a 2a 2a 20 54 68 65 20 33 72 64 20 70  es..** The 3rd p
36040 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 73  arameter to thes
36050 65 20 63 61 6c 6c 62 61 63 6b 73 20 69 73 20 61  e callbacks is a
36060 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74  n array of point
36070 65 72 73 20 74 6f 0a 2a 2a 20 5b 70 72 6f 74 65  ers to.** [prote
36080 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
36090 75 65 5d 20 6f 62 6a 65 63 74 73 2e 20 20 54 68  ue] objects.  Th
360a0 65 72 65 20 69 73 20 6f 6e 65 20 5b 73 71 6c 69  ere is one [sqli
360b0 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
360c0 74 20 66 6f 72 0a 2a 2a 20 65 61 63 68 20 70 61  t for.** each pa
360d0 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 53  rameter to the S
360e0 51 4c 20 66 75 6e 63 74 69 6f 6e 2e 20 20 54 68  QL function.  Th
360f0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65  ese routines are
36100 20 75 73 65 64 20 74 6f 0a 2a 2a 20 65 78 74 72   used to.** extr
36110 61 63 74 20 76 61 6c 75 65 73 20 66 72 6f 6d 20  act values from 
36120 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  the [sqlite3_val
36130 75 65 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 0a  ue] objects..**.
36140 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
36150 73 20 77 6f 72 6b 20 6f 6e 6c 79 20 77 69 74 68  s work only with
36160 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69   [protected sqli
36170 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
36180 74 73 2e 0a 2a 2a 20 41 6e 79 20 61 74 74 65 6d  ts..** Any attem
36190 70 74 20 74 6f 20 75 73 65 20 74 68 65 73 65 20  pt to use these 
361a0 72 6f 75 74 69 6e 65 73 20 6f 6e 20 61 6e 20 5b  routines on an [
361b0 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  unprotected sqli
361c0 74 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20 6f 62  te3_value].** ob
361d0 6a 65 63 74 20 72 65 73 75 6c 74 73 20 69 6e 20  ject results in 
361e0 75 6e 64 65 66 69 6e 65 64 20 62 65 68 61 76 69  undefined behavi
361f0 6f 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65  or..**.** ^These
36200 20 72 6f 75 74 69 6e 65 73 20 77 6f 72 6b 20 6a   routines work j
36210 75 73 74 20 6c 69 6b 65 20 74 68 65 20 63 6f 72  ust like the cor
36220 72 65 73 70 6f 6e 64 69 6e 67 20 5b 63 6f 6c 75  responding [colu
36230 6d 6e 20 61 63 63 65 73 73 20 66 75 6e 63 74 69  mn access functi
36240 6f 6e 73 5d 0a 2a 2a 20 65 78 63 65 70 74 20 74  ons].** except t
36250 68 61 74 20 74 68 65 73 65 20 72 6f 75 74 69 6e  hat these routin
36260 65 73 20 74 61 6b 65 20 61 20 73 69 6e 67 6c 65  es take a single
36270 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69   [protected sqli
36280 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
36290 74 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 69 6e 73  t.** pointer ins
362a0 74 65 61 64 20 6f 66 20 61 20 5b 73 71 6c 69 74  tead of a [sqlit
362b0 65 33 5f 73 74 6d 74 2a 5d 20 70 6f 69 6e 74 65  e3_stmt*] pointe
362c0 72 20 61 6e 64 20 61 6e 20 69 6e 74 65 67 65 72  r and an integer
362d0 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e 0a   column number..
362e0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
362f0 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28  e3_value_text16(
36300 29 20 69 6e 74 65 72 66 61 63 65 20 65 78 74 72  ) interface extr
36310 61 63 74 73 20 61 20 55 54 46 2d 31 36 20 73 74  acts a UTF-16 st
36320 72 69 6e 67 0a 2a 2a 20 69 6e 20 74 68 65 20 6e  ring.** in the n
36330 61 74 69 76 65 20 62 79 74 65 2d 6f 72 64 65 72  ative byte-order
36340 20 6f 66 20 74 68 65 20 68 6f 73 74 20 6d 61 63   of the host mac
36350 68 69 6e 65 2e 20 20 5e 54 68 65 0a 2a 2a 20 73  hine.  ^The.** s
36360 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
36370 74 31 36 62 65 28 29 20 61 6e 64 20 73 71 6c 69  t16be() and sqli
36380 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36  te3_value_text16
36390 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65 73 0a  le() interfaces.
363a0 2a 2a 20 65 78 74 72 61 63 74 20 55 54 46 2d 31  ** extract UTF-1
363b0 36 20 73 74 72 69 6e 67 73 20 61 73 20 62 69 67  6 strings as big
363c0 2d 65 6e 64 69 61 6e 20 61 6e 64 20 6c 69 74 74  -endian and litt
363d0 6c 65 2d 65 6e 64 69 61 6e 20 72 65 73 70 65 63  le-endian respec
363e0 74 69 76 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 28  tively..**.** ^(
363f0 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  The sqlite3_valu
36400 65 5f 6e 75 6d 65 72 69 63 5f 74 79 70 65 28 29  e_numeric_type()
36410 20 69 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d   interface attem
36420 70 74 73 20 74 6f 20 61 70 70 6c 79 0a 2a 2a 20  pts to apply.** 
36430 6e 75 6d 65 72 69 63 20 61 66 66 69 6e 69 74 79  numeric affinity
36440 20 74 6f 20 74 68 65 20 76 61 6c 75 65 2e 20 20   to the value.  
36450 54 68 69 73 20 6d 65 61 6e 73 20 74 68 61 74 20  This means that 
36460 61 6e 20 61 74 74 65 6d 70 74 20 69 73 0a 2a 2a  an attempt is.**
36470 20 6d 61 64 65 20 74 6f 20 63 6f 6e 76 65 72 74   made to convert
36480 20 74 68 65 20 76 61 6c 75 65 20 74 6f 20 61 6e   the value to an
36490 20 69 6e 74 65 67 65 72 20 6f 72 20 66 6c 6f 61   integer or floa
364a0 74 69 6e 67 20 70 6f 69 6e 74 2e 20 20 49 66 0a  ting point.  If.
364b0 2a 2a 20 73 75 63 68 20 61 20 63 6f 6e 76 65 72  ** such a conver
364c0 73 69 6f 6e 20 69 73 20 70 6f 73 73 69 62 6c 65  sion is possible
364d0 20 77 69 74 68 6f 75 74 20 6c 6f 73 73 20 6f 66   without loss of
364e0 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 28 69 6e   information (in
364f0 20 6f 74 68 65 72 0a 2a 2a 20 77 6f 72 64 73 2c   other.** words,
36500 20 69 66 20 74 68 65 20 76 61 6c 75 65 20 69 73   if the value is
36510 20 61 20 73 74 72 69 6e 67 20 74 68 61 74 20 6c   a string that l
36520 6f 6f 6b 73 20 6c 69 6b 65 20 61 20 6e 75 6d 62  ooks like a numb
36530 65 72 29 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20  er).** then the 
36540 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 70 65  conversion is pe
36550 72 66 6f 72 6d 65 64 2e 20 20 4f 74 68 65 72 77  rformed.  Otherw
36560 69 73 65 20 6e 6f 20 63 6f 6e 76 65 72 73 69 6f  ise no conversio
36570 6e 20 6f 63 63 75 72 73 2e 0a 2a 2a 20 54 68 65  n occurs..** The
36580 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52   [SQLITE_INTEGER
36590 20 7c 20 64 61 74 61 74 79 70 65 5d 20 61 66 74   | datatype] aft
365a0 65 72 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73  er conversion is
365b0 20 72 65 74 75 72 6e 65 64 2e 29 5e 0a 2a 2a 0a   returned.)^.**.
365c0 2a 2a 20 50 6c 65 61 73 65 20 70 61 79 20 70 61  ** Please pay pa
365d0 72 74 69 63 75 6c 61 72 20 61 74 74 65 6e 74 69  rticular attenti
365e0 6f 6e 20 74 6f 20 74 68 65 20 66 61 63 74 20 74  on to the fact t
365f0 68 61 74 20 74 68 65 20 70 6f 69 6e 74 65 72 20  hat the pointer 
36600 72 65 74 75 72 6e 65 64 0a 2a 2a 20 66 72 6f 6d  returned.** from
36610 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
36620 62 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c 69 74 65  blob()], [sqlite
36630 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c  3_value_text()],
36640 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   or.** [sqlite3_
36650 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29 5d 20  value_text16()] 
36660 63 61 6e 20 62 65 20 69 6e 76 61 6c 69 64 61 74  can be invalidat
36670 65 64 20 62 79 20 61 20 73 75 62 73 65 71 75 65  ed by a subseque
36680 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73  nt call to.** [s
36690 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74  qlite3_value_byt
366a0 65 73 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  es()], [sqlite3_
366b0 76 61 6c 75 65 5f 62 79 74 65 73 31 36 28 29 5d  value_bytes16()]
366c0 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  , [sqlite3_value
366d0 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20  _text()],.** or 
366e0 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  [sqlite3_value_t
366f0 65 78 74 31 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  ext16()]..**.** 
36700 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d  These routines m
36710 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72  ust be called fr
36720 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72 65  om the same thre
36730 61 64 20 61 73 0a 2a 2a 20 74 68 65 20 53 51 4c  ad as.** the SQL
36740 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 73   function that s
36750 75 70 70 6c 69 65 64 20 74 68 65 20 5b 73 71 6c  upplied the [sql
36760 69 74 65 33 5f 76 61 6c 75 65 2a 5d 20 70 61 72  ite3_value*] par
36770 61 6d 65 74 65 72 73 2e 0a 2a 2f 0a 63 6f 6e 73  ameters..*/.cons
36780 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
36790 76 61 6c 75 65 5f 62 6c 6f 62 28 73 71 6c 69 74  value_blob(sqlit
367a0 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20  e3_value*);.int 
367b0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79  sqlite3_value_by
367c0 74 65 73 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  tes(sqlite3_valu
367d0 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  e*);.int sqlite3
367e0 5f 76 61 6c 75 65 5f 62 79 74 65 73 31 36 28 73  _value_bytes16(s
367f0 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
36800 64 6f 75 62 6c 65 20 73 71 6c 69 74 65 33 5f 76  double sqlite3_v
36810 61 6c 75 65 5f 64 6f 75 62 6c 65 28 73 71 6c 69  alue_double(sqli
36820 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74  te3_value*);.int
36830 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69   sqlite3_value_i
36840 6e 74 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt(sqlite3_value
36850 2a 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36  *);.sqlite3_int6
36860 34 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  4 sqlite3_value_
36870 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 76 61  int64(sqlite3_va
36880 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 75 6e 73  lue*);.const uns
36890 69 67 6e 65 64 20 63 68 61 72 20 2a 73 71 6c 69  igned char *sqli
368a0 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 73  te3_value_text(s
368b0 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
368c0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
368d0 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36  te3_value_text16
368e0 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
368f0 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  ;.const void *sq
36900 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
36910 31 36 6c 65 28 73 71 6c 69 74 65 33 5f 76 61 6c  16le(sqlite3_val
36920 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64  ue*);.const void
36930 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   *sqlite3_value_
36940 74 65 78 74 31 36 62 65 28 73 71 6c 69 74 65 33  text16be(sqlite3
36950 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71  _value*);.int sq
36960 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 79 70 65  lite3_value_type
36970 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
36980 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61  ;.int sqlite3_va
36990 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 74 79 70 65  lue_numeric_type
369a0 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
369b0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
369c0 46 3a 20 46 69 6e 64 69 6e 67 20 54 68 65 20 53  F: Finding The S
369d0 75 62 74 79 70 65 20 4f 66 20 53 51 4c 20 56 61  ubtype Of SQL Va
369e0 6c 75 65 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  lues.** METHOD: 
369f0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 0a 2a 2a  sqlite3_value.**
36a00 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
36a10 76 61 6c 75 65 5f 73 75 62 74 79 70 65 28 56 29  value_subtype(V)
36a20 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e   function return
36a30 73 20 74 68 65 20 73 75 62 74 79 70 65 20 66 6f  s the subtype fo
36a40 72 0a 2a 2a 20 61 6e 20 5b 61 70 70 6c 69 63 61  r.** an [applica
36a50 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c  tion-defined SQL
36a60 20 66 75 6e 63 74 69 6f 6e 5d 20 61 72 67 75 6d   function] argum
36a70 65 6e 74 20 56 2e 20 20 54 68 65 20 73 75 62 74  ent V.  The subt
36a80 79 70 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69  ype.** informati
36a90 6f 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20 74  on can be used t
36aa0 6f 20 70 61 73 73 20 61 20 6c 69 6d 69 74 65 64  o pass a limited
36ab0 20 61 6d 6f 75 6e 74 20 6f 66 20 63 6f 6e 74 65   amount of conte
36ac0 78 74 20 66 72 6f 6d 0a 2a 2a 20 6f 6e 65 20 53  xt from.** one S
36ad0 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 61  QL function to a
36ae0 6e 6f 74 68 65 72 2e 20 20 55 73 65 20 74 68 65  nother.  Use the
36af0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74   [sqlite3_result
36b00 5f 73 75 62 74 79 70 65 28 29 5d 0a 2a 2a 20 72  _subtype()].** r
36b10 6f 75 74 69 6e 65 20 74 6f 20 73 65 74 20 74 68  outine to set th
36b20 65 20 73 75 62 74 79 70 65 20 66 6f 72 20 74 68  e subtype for th
36b30 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f  e return value o
36b40 66 20 61 6e 20 53 51 4c 20 66 75 6e 63 74 69 6f  f an SQL functio
36b50 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20  n..**.** SQLite 
36b60 6d 61 6b 65 73 20 6e 6f 20 75 73 65 20 6f 66 20  makes no use of 
36b70 73 75 62 74 79 70 65 20 69 74 73 65 6c 66 2e 20  subtype itself. 
36b80 20 49 74 20 6d 65 72 65 6c 79 20 70 61 73 73 65   It merely passe
36b90 73 20 74 68 65 20 73 75 62 74 79 70 65 0a 2a 2a  s the subtype.**
36ba0 20 66 72 6f 6d 20 74 68 65 20 72 65 73 75 6c 74   from the result
36bb0 20 6f 66 20 6f 6e 65 20 5b 61 70 70 6c 69 63 61   of one [applica
36bc0 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c  tion-defined SQL
36bd0 20 66 75 6e 63 74 69 6f 6e 5d 20 69 6e 74 6f 20   function] into 
36be0 74 68 65 0a 2a 2a 20 69 6e 70 75 74 20 6f 66 20  the.** input of 
36bf0 61 6e 6f 74 68 65 72 2e 0a 2a 2f 0a 75 6e 73 69  another..*/.unsi
36c00 67 6e 65 64 20 69 6e 74 20 73 71 6c 69 74 65 33  gned int sqlite3
36c10 5f 76 61 6c 75 65 5f 73 75 62 74 79 70 65 28 73  _value_subtype(s
36c20 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
36c30 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
36c40 20 43 6f 70 79 20 41 6e 64 20 46 72 65 65 20 53   Copy And Free S
36c50 51 4c 20 56 61 6c 75 65 73 0a 2a 2a 20 4d 45 54  QL Values.** MET
36c60 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 76 61 6c  HOD: sqlite3_val
36c70 75 65 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  ue.**.** ^The sq
36c80 6c 69 74 65 33 5f 76 61 6c 75 65 5f 64 75 70 28  lite3_value_dup(
36c90 56 29 20 69 6e 74 65 72 66 61 63 65 20 6d 61 6b  V) interface mak
36ca0 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  es a copy of the
36cb0 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d   [sqlite3_value]
36cc0 0a 2a 2a 20 6f 62 6a 65 63 74 20 44 20 61 6e 64  .** object D and
36cd0 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
36ce0 65 72 20 74 6f 20 74 68 61 74 20 63 6f 70 79 2e  er to that copy.
36cf0 20 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f    ^The [sqlite3_
36d00 76 61 6c 75 65 5d 20 72 65 74 75 72 6e 65 64 0a  value] returned.
36d10 2a 2a 20 69 73 20 61 20 5b 70 72 6f 74 65 63 74  ** is a [protect
36d20 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
36d30 5d 20 6f 62 6a 65 63 74 20 65 76 65 6e 20 69 66  ] object even if
36d40 20 74 68 65 20 69 6e 70 75 74 20 69 73 20 6e 6f   the input is no
36d50 74 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  t..** ^The sqlit
36d60 65 33 5f 76 61 6c 75 65 5f 64 75 70 28 56 29 20  e3_value_dup(V) 
36d70 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
36d80 73 20 4e 55 4c 4c 20 69 66 20 56 20 69 73 20 4e  s NULL if V is N
36d90 55 4c 4c 20 6f 72 20 69 66 20 61 0a 2a 2a 20 6d  ULL or if a.** m
36da0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
36db0 20 66 61 69 6c 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54   fails..**.** ^T
36dc0 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  he sqlite3_value
36dd0 5f 66 72 65 65 28 56 29 20 69 6e 74 65 72 66 61  _free(V) interfa
36de0 63 65 20 66 72 65 65 73 20 61 6e 20 5b 73 71 6c  ce frees an [sql
36df0 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
36e00 63 74 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79  ct.** previously
36e10 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b   obtained from [
36e20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 64 75  sqlite3_value_du
36e30 70 28 29 5d 2e 20 20 5e 49 66 20 56 20 69 73 20  p()].  ^If V is 
36e40 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a  a NULL pointer.*
36e50 2a 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 76  * then sqlite3_v
36e60 61 6c 75 65 5f 66 72 65 65 28 56 29 20 69 73 20  alue_free(V) is 
36e70 61 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70  a harmless no-op
36e80 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 76 61 6c  ..*/.sqlite3_val
36e90 75 65 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75  ue *sqlite3_valu
36ea0 65 5f 64 75 70 28 63 6f 6e 73 74 20 73 71 6c 69  e_dup(const sqli
36eb0 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 76 6f 69  te3_value*);.voi
36ec0 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  d sqlite3_value_
36ed0 66 72 65 65 28 73 71 6c 69 74 65 33 5f 76 61 6c  free(sqlite3_val
36ee0 75 65 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ue*);../*.** CAP
36ef0 49 33 52 45 46 3a 20 4f 62 74 61 69 6e 20 41 67  I3REF: Obtain Ag
36f00 67 72 65 67 61 74 65 20 46 75 6e 63 74 69 6f 6e  gregate Function
36f10 20 43 6f 6e 74 65 78 74 0a 2a 2a 20 4d 45 54 48   Context.** METH
36f20 4f 44 3a 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74  OD: sqlite3_cont
36f30 65 78 74 0a 2a 2a 0a 2a 2a 20 49 6d 70 6c 65 6d  ext.**.** Implem
36f40 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 61 67 67  entations of agg
36f50 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74  regate SQL funct
36f60 69 6f 6e 73 20 75 73 65 20 74 68 69 73 0a 2a 2a  ions use this.**
36f70 20 72 6f 75 74 69 6e 65 20 74 6f 20 61 6c 6c 6f   routine to allo
36f80 63 61 74 65 20 6d 65 6d 6f 72 79 20 66 6f 72 20  cate memory for 
36f90 73 74 6f 72 69 6e 67 20 74 68 65 69 72 20 73 74  storing their st
36fa0 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ate..**.** ^The 
36fb0 66 69 72 73 74 20 74 69 6d 65 20 74 68 65 20 73  first time the s
36fc0 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65  qlite3_aggregate
36fd0 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20 72 6f  _context(C,N) ro
36fe0 75 74 69 6e 65 20 69 73 20 63 61 6c 6c 65 64 20  utine is called 
36ff0 0a 2a 2a 20 66 6f 72 20 61 20 70 61 72 74 69 63  .** for a partic
37000 75 6c 61 72 20 61 67 67 72 65 67 61 74 65 20 66  ular aggregate f
37010 75 6e 63 74 69 6f 6e 2c 20 53 51 4c 69 74 65 0a  unction, SQLite.
37020 2a 2a 20 61 6c 6c 6f 63 61 74 65 73 20 4e 20 6f  ** allocates N o
37030 66 20 6d 65 6d 6f 72 79 2c 20 7a 65 72 6f 65 73  f memory, zeroes
37040 20 6f 75 74 20 74 68 61 74 20 6d 65 6d 6f 72 79   out that memory
37050 2c 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20  , and returns a 
37060 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68  pointer.** to th
37070 65 20 6e 65 77 20 6d 65 6d 6f 72 79 2e 20 5e 4f  e new memory. ^O
37080 6e 20 73 65 63 6f 6e 64 20 61 6e 64 20 73 75 62  n second and sub
37090 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f  sequent calls to
370a0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 61 67 67 72  .** sqlite3_aggr
370b0 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20  egate_context() 
370c0 66 6f 72 20 74 68 65 20 73 61 6d 65 20 61 67 67  for the same agg
370d0 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 20  regate function 
370e0 69 6e 73 74 61 6e 63 65 2c 0a 2a 2a 20 74 68 65  instance,.** the
370f0 20 73 61 6d 65 20 62 75 66 66 65 72 20 69 73 20   same buffer is 
37100 72 65 74 75 72 6e 65 64 2e 20 20 53 71 6c 69 74  returned.  Sqlit
37110 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e  e3_aggregate_con
37120 74 65 78 74 28 29 20 69 73 20 6e 6f 72 6d 61 6c  text() is normal
37130 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64 20 6f 6e 63  ly.** called onc
37140 65 20 66 6f 72 20 65 61 63 68 20 69 6e 76 6f 63  e for each invoc
37150 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 78 53 74  ation of the xSt
37160 65 70 20 63 61 6c 6c 62 61 63 6b 20 61 6e 64 20  ep callback and 
37170 74 68 65 6e 20 6f 6e 65 0a 2a 2a 20 6c 61 73 74  then one.** last
37180 20 74 69 6d 65 20 77 68 65 6e 20 74 68 65 20 78   time when the x
37190 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 20 69  Final callback i
371a0 73 20 69 6e 76 6f 6b 65 64 2e 20 20 5e 28 57 68  s invoked.  ^(Wh
371b0 65 6e 20 6e 6f 20 72 6f 77 73 20 6d 61 74 63 68  en no rows match
371c0 0a 2a 2a 20 61 6e 20 61 67 67 72 65 67 61 74 65  .** an aggregate
371d0 20 71 75 65 72 79 2c 20 74 68 65 20 78 53 74 65   query, the xSte
371e0 70 28 29 20 63 61 6c 6c 62 61 63 6b 20 6f 66 20  p() callback of 
371f0 74 68 65 20 61 67 67 72 65 67 61 74 65 20 66 75  the aggregate fu
37200 6e 63 74 69 6f 6e 0a 2a 2a 20 69 6d 70 6c 65 6d  nction.** implem
37210 65 6e 74 61 74 69 6f 6e 20 69 73 20 6e 65 76 65  entation is neve
37220 72 20 63 61 6c 6c 65 64 20 61 6e 64 20 78 46 69  r called and xFi
37230 6e 61 6c 28 29 20 69 73 20 63 61 6c 6c 65 64 20  nal() is called 
37240 65 78 61 63 74 6c 79 20 6f 6e 63 65 2e 0a 2a 2a  exactly once..**
37250 20 49 6e 20 74 68 6f 73 65 20 63 61 73 65 73 2c   In those cases,
37260 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61   sqlite3_aggrega
37270 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 6d 69 67  te_context() mig
37280 68 74 20 62 65 20 63 61 6c 6c 65 64 20 66 6f 72  ht be called for
37290 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 74 69   the.** first ti
372a0 6d 65 20 66 72 6f 6d 20 77 69 74 68 69 6e 20 78  me from within x
372b0 46 69 6e 61 6c 28 29 2e 29 5e 0a 2a 2a 0a 2a 2a  Final().)^.**.**
372c0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 61 67   ^The sqlite3_ag
372d0 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28  gregate_context(
372e0 43 2c 4e 29 20 72 6f 75 74 69 6e 65 20 72 65 74  C,N) routine ret
372f0 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  urns a NULL poin
37300 74 65 72 20 0a 2a 2a 20 77 68 65 6e 20 66 69 72  ter .** when fir
37310 73 74 20 63 61 6c 6c 65 64 20 69 66 20 4e 20 69  st called if N i
37320 73 20 6c 65 73 73 20 74 68 61 6e 20 6f 72 20 65  s less than or e
37330 71 75 61 6c 20 74 6f 20 7a 65 72 6f 20 6f 72 20  qual to zero or 
37340 69 66 20 61 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61  if a memory.** a
37350 6c 6c 6f 63 61 74 65 20 65 72 72 6f 72 20 6f 63  llocate error oc
37360 63 75 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  curs..**.** ^(Th
37370 65 20 61 6d 6f 75 6e 74 20 6f 66 20 73 70 61 63  e amount of spac
37380 65 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 73  e allocated by s
37390 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65  qlite3_aggregate
373a0 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20 69 73  _context(C,N) is
373b0 0a 2a 2a 20 64 65 74 65 72 6d 69 6e 65 64 20 62  .** determined b
373c0 79 20 74 68 65 20 4e 20 70 61 72 61 6d 65 74 65  y the N paramete
373d0 72 20 6f 6e 20 66 69 72 73 74 20 73 75 63 63 65  r on first succe
373e0 73 73 66 75 6c 20 63 61 6c 6c 2e 20 20 43 68 61  ssful call.  Cha
373f0 6e 67 69 6e 67 20 74 68 65 0a 2a 2a 20 76 61 6c  nging the.** val
37400 75 65 20 6f 66 20 4e 20 69 6e 20 73 75 62 73 65  ue of N in subse
37410 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f 20 73 71  quent call to sq
37420 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f  lite3_aggregate_
37430 63 6f 6e 74 65 78 74 28 29 20 77 69 74 68 69 6e  context() within
37440 0a 2a 2a 20 74 68 65 20 73 61 6d 65 20 61 67 67  .** the same agg
37450 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 20  regate function 
37460 69 6e 73 74 61 6e 63 65 20 77 69 6c 6c 20 6e 6f  instance will no
37470 74 20 72 65 73 69 7a 65 20 74 68 65 20 6d 65 6d  t resize the mem
37480 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f  ory.** allocatio
37490 6e 2e 29 5e 20 20 57 69 74 68 69 6e 20 74 68 65  n.)^  Within the
374a0 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b   xFinal callback
374b0 2c 20 69 74 20 69 73 20 63 75 73 74 6f 6d 61 72  , it is customar
374c0 79 20 74 6f 20 73 65 74 0a 2a 2a 20 4e 3d 30 20  y to set.** N=0 
374d0 69 6e 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69  in calls to sqli
374e0 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f  te3_aggregate_co
374f0 6e 74 65 78 74 28 43 2c 4e 29 20 73 6f 20 74 68  ntext(C,N) so th
37500 61 74 20 6e 6f 20 0a 2a 2a 20 70 6f 69 6e 74 6c  at no .** pointl
37510 65 73 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ess memory alloc
37520 61 74 69 6f 6e 73 20 6f 63 63 75 72 2e 0a 2a 2a  ations occur..**
37530 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 61 75 74 6f  .** ^SQLite auto
37540 6d 61 74 69 63 61 6c 6c 79 20 66 72 65 65 73 20  matically frees 
37550 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  the memory alloc
37560 61 74 65 64 20 62 79 20 0a 2a 2a 20 73 71 6c 69  ated by .** sqli
37570 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f  te3_aggregate_co
37580 6e 74 65 78 74 28 29 20 77 68 65 6e 20 74 68 65  ntext() when the
37590 20 61 67 67 72 65 67 61 74 65 20 71 75 65 72 79   aggregate query
375a0 20 63 6f 6e 63 6c 75 64 65 73 2e 0a 2a 2a 0a 2a   concludes..**.*
375b0 2a 20 54 68 65 20 66 69 72 73 74 20 70 61 72 61  * The first para
375c0 6d 65 74 65 72 20 6d 75 73 74 20 62 65 20 61 20  meter must be a 
375d0 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 5b  copy of the.** [
375e0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20  sqlite3_context 
375f0 7c 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 63  | SQL function c
37600 6f 6e 74 65 78 74 5d 20 74 68 61 74 20 69 73 20  ontext] that is 
37610 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  the first parame
37620 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 78 53  ter.** to the xS
37630 74 65 70 20 6f 72 20 78 46 69 6e 61 6c 20 63 61  tep or xFinal ca
37640 6c 6c 62 61 63 6b 20 72 6f 75 74 69 6e 65 20 74  llback routine t
37650 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74  hat implements t
37660 68 65 20 61 67 67 72 65 67 61 74 65 0a 2a 2a 20  he aggregate.** 
37670 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  function..**.** 
37680 54 68 69 73 20 72 6f 75 74 69 6e 65 20 6d 75 73  This routine mus
37690 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d  t be called from
376a0 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64   the same thread
376b0 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68 65   in which.** the
376c0 20 61 67 67 72 65 67 61 74 65 20 53 51 4c 20 66   aggregate SQL f
376d0 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69  unction is runni
376e0 6e 67 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c  ng..*/.void *sql
376f0 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63  ite3_aggregate_c
37700 6f 6e 74 65 78 74 28 73 71 6c 69 74 65 33 5f 63  ontext(sqlite3_c
37710 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 6e 42 79  ontext*, int nBy
37720 74 65 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  tes);../*.** CAP
37730 49 33 52 45 46 3a 20 55 73 65 72 20 44 61 74 61  I3REF: User Data
37740 20 46 6f 72 20 46 75 6e 63 74 69 6f 6e 73 0a 2a   For Functions.*
37750 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65  * METHOD: sqlite
37760 33 5f 63 6f 6e 74 65 78 74 0a 2a 2a 0a 2a 2a 20  3_context.**.** 
37770 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 75 73 65  ^The sqlite3_use
37780 72 5f 64 61 74 61 28 29 20 69 6e 74 65 72 66 61  r_data() interfa
37790 63 65 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70  ce returns a cop
377a0 79 20 6f 66 0a 2a 2a 20 74 68 65 20 70 6f 69 6e  y of.** the poin
377b0 74 65 72 20 74 68 61 74 20 77 61 73 20 74 68 65  ter that was the
377c0 20 70 55 73 65 72 44 61 74 61 20 70 61 72 61 6d   pUserData param
377d0 65 74 65 72 20 28 74 68 65 20 35 74 68 20 70 61  eter (the 5th pa
377e0 72 61 6d 65 74 65 72 29 0a 2a 2a 20 6f 66 20 74  rameter).** of t
377f0 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  he [sqlite3_crea
37800 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a  te_function()].*
37810 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63  * and [sqlite3_c
37820 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36  reate_function16
37830 28 29 5d 20 72 6f 75 74 69 6e 65 73 20 74 68 61  ()] routines tha
37840 74 20 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20  t originally.** 
37850 72 65 67 69 73 74 65 72 65 64 20 74 68 65 20 61  registered the a
37860 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 6e  pplication defin
37870 65 64 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a  ed function..**.
37880 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20  ** This routine 
37890 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66  must be called f
378a0 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72  rom the same thr
378b0 65 61 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20  ead in which.** 
378c0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
378d0 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
378e0 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a   is running..*/.
378f0 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 75 73  void *sqlite3_us
37900 65 72 5f 64 61 74 61 28 73 71 6c 69 74 65 33 5f  er_data(sqlite3_
37910 63 6f 6e 74 65 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a  context*);../*.*
37920 2a 20 43 41 50 49 33 52 45 46 3a 20 44 61 74 61  * CAPI3REF: Data
37930 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20  base Connection 
37940 46 6f 72 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a  For Functions.**
37950 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
37960 5f 63 6f 6e 74 65 78 74 0a 2a 2a 0a 2a 2a 20 5e  _context.**.** ^
37970 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74  The sqlite3_cont
37980 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 29 20  ext_db_handle() 
37990 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
379a0 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74  s a copy of.** t
379b0 68 65 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68  he pointer to th
379c0 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
379d0 65 63 74 69 6f 6e 5d 20 28 74 68 65 20 31 73 74  ection] (the 1st
379e0 20 70 61 72 61 6d 65 74 65 72 29 0a 2a 2a 20 6f   parameter).** o
379f0 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  f the [sqlite3_c
37a00 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29  reate_function()
37a10 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65  ].** and [sqlite
37a20 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
37a30 6e 31 36 28 29 5d 20 72 6f 75 74 69 6e 65 73 20  n16()] routines 
37a40 74 68 61 74 20 6f 72 69 67 69 6e 61 6c 6c 79 0a  that originally.
37a50 2a 2a 20 72 65 67 69 73 74 65 72 65 64 20 74 68  ** registered th
37a60 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 65  e application de
37a70 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 0a  fined function..
37a80 2a 2f 0a 73 71 6c 69 74 65 33 20 2a 73 71 6c 69  */.sqlite3 *sqli
37a90 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68  te3_context_db_h
37aa0 61 6e 64 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f  andle(sqlite3_co
37ab0 6e 74 65 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  ntext*);../*.** 
37ac0 43 41 50 49 33 52 45 46 3a 20 46 75 6e 63 74 69  CAPI3REF: Functi
37ad0 6f 6e 20 41 75 78 69 6c 69 61 72 79 20 44 61 74  on Auxiliary Dat
37ae0 61 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  a.** METHOD: sql
37af0 69 74 65 33 5f 63 6f 6e 74 65 78 74 0a 2a 2a 0a  ite3_context.**.
37b00 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69 6f  ** These functio
37b10 6e 73 20 6d 61 79 20 62 65 20 75 73 65 64 20 62  ns may be used b
37b20 79 20 28 6e 6f 6e 2d 61 67 67 72 65 67 61 74 65  y (non-aggregate
37b30 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20  ) SQL functions 
37b40 74 6f 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 20  to.** associate 
37b50 6d 65 74 61 64 61 74 61 20 77 69 74 68 20 61 72  metadata with ar
37b60 67 75 6d 65 6e 74 20 76 61 6c 75 65 73 2e 20 49  gument values. I
37b70 66 20 74 68 65 20 73 61 6d 65 20 76 61 6c 75 65  f the same value
37b80 20 69 73 20 70 61 73 73 65 64 20 74 6f 0a 2a 2a   is passed to.**
37b90 20 6d 75 6c 74 69 70 6c 65 20 69 6e 76 6f 63 61   multiple invoca
37ba0 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d  tions of the sam
37bb0 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 64  e SQL function d
37bc0 75 72 69 6e 67 20 71 75 65 72 79 20 65 78 65 63  uring query exec
37bd0 75 74 69 6f 6e 2c 20 75 6e 64 65 72 0a 2a 2a 20  ution, under.** 
37be0 73 6f 6d 65 20 63 69 72 63 75 6d 73 74 61 6e 63  some circumstanc
37bf0 65 73 20 74 68 65 20 61 73 73 6f 63 69 61 74 65  es the associate
37c00 64 20 6d 65 74 61 64 61 74 61 20 6d 61 79 20 62  d metadata may b
37c10 65 20 70 72 65 73 65 72 76 65 64 2e 20 20 41 6e  e preserved.  An
37c20 20 65 78 61 6d 70 6c 65 0a 2a 2a 20 6f 66 20 77   example.** of w
37c30 68 65 72 65 20 74 68 69 73 20 6d 69 67 68 74 20  here this might 
37c40 62 65 20 75 73 65 66 75 6c 20 69 73 20 69 6e 20  be useful is in 
37c50 61 20 72 65 67 75 6c 61 72 2d 65 78 70 72 65 73  a regular-expres
37c60 73 69 6f 6e 20 6d 61 74 63 68 69 6e 67 0a 2a 2a  sion matching.**
37c70 20 66 75 6e 63 74 69 6f 6e 2e 20 54 68 65 20 63   function. The c
37c80 6f 6d 70 69 6c 65 64 20 76 65 72 73 69 6f 6e 20  ompiled version 
37c90 6f 66 20 74 68 65 20 72 65 67 75 6c 61 72 20 65  of the regular e
37ca0 78 70 72 65 73 73 69 6f 6e 20 63 61 6e 20 62 65  xpression can be
37cb0 20 73 74 6f 72 65 64 20 61 73 0a 2a 2a 20 6d 65   stored as.** me
37cc0 74 61 64 61 74 61 20 61 73 73 6f 63 69 61 74 65  tadata associate
37cd0 64 20 77 69 74 68 20 74 68 65 20 70 61 74 74 65  d with the patte
37ce0 72 6e 20 73 74 72 69 6e 67 2e 20 20 0a 2a 2a 20  rn string.  .** 
37cf0 54 68 65 6e 20 61 73 20 6c 6f 6e 67 20 61 73 20  Then as long as 
37d00 74 68 65 20 70 61 74 74 65 72 6e 20 73 74 72 69  the pattern stri
37d10 6e 67 20 72 65 6d 61 69 6e 73 20 74 68 65 20 73  ng remains the s
37d20 61 6d 65 2c 0a 2a 2a 20 74 68 65 20 63 6f 6d 70  ame,.** the comp
37d30 69 6c 65 64 20 72 65 67 75 6c 61 72 20 65 78 70  iled regular exp
37d40 72 65 73 73 69 6f 6e 20 63 61 6e 20 62 65 20 72  ression can be r
37d50 65 75 73 65 64 20 6f 6e 20 6d 75 6c 74 69 70 6c  eused on multipl
37d60 65 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 73  e.** invocations
37d70 20 6f 66 20 74 68 65 20 73 61 6d 65 20 66 75 6e   of the same fun
37d80 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ction..**.** ^Th
37d90 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75  e sqlite3_get_au
37da0 78 64 61 74 61 28 29 20 69 6e 74 65 72 66 61 63  xdata() interfac
37db0 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  e returns a poin
37dc0 74 65 72 20 74 6f 20 74 68 65 20 6d 65 74 61 64  ter to the metad
37dd0 61 74 61 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65  ata.** associate
37de0 64 20 62 79 20 74 68 65 20 73 71 6c 69 74 65 33  d by the sqlite3
37df0 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 20 66  _set_auxdata() f
37e00 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 74 68 65  unction with the
37e10 20 4e 74 68 20 61 72 67 75 6d 65 6e 74 0a 2a 2a   Nth argument.**
37e20 20 76 61 6c 75 65 20 74 6f 20 74 68 65 20 61 70   value to the ap
37e30 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
37e40 64 20 66 75 6e 63 74 69 6f 6e 2e 20 5e 49 66 20  d function. ^If 
37e50 74 68 65 72 65 20 69 73 20 6e 6f 20 6d 65 74 61  there is no meta
37e60 64 61 74 61 0a 2a 2a 20 61 73 73 6f 63 69 61 74  data.** associat
37e70 65 64 20 77 69 74 68 20 74 68 65 20 66 75 6e 63  ed with the func
37e80 74 69 6f 6e 20 61 72 67 75 6d 65 6e 74 2c 20 74  tion argument, t
37e90 68 69 73 20 73 71 6c 69 74 65 33 5f 67 65 74 5f  his sqlite3_get_
37ea0 61 75 78 64 61 74 61 28 29 20 69 6e 74 65 72 66  auxdata() interf
37eb0 61 63 65 0a 2a 2a 20 72 65 74 75 72 6e 73 20 61  ace.** returns a
37ec0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a   NULL pointer..*
37ed0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
37ee0 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 43 2c  3_set_auxdata(C,
37ef0 4e 2c 50 2c 58 29 20 69 6e 74 65 72 66 61 63 65  N,P,X) interface
37f00 20 73 61 76 65 73 20 50 20 61 73 20 6d 65 74 61   saves P as meta
37f10 64 61 74 61 20 66 6f 72 20 74 68 65 20 4e 2d 74  data for the N-t
37f20 68 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6f 66  h.** argument of
37f30 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
37f40 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
37f50 6e 2e 20 20 5e 53 75 62 73 65 71 75 65 6e 74 0a  n.  ^Subsequent.
37f60 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69  ** calls to sqli
37f70 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28  te3_get_auxdata(
37f80 43 2c 4e 29 20 72 65 74 75 72 6e 20 50 20 66 72  C,N) return P fr
37f90 6f 6d 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  om the most rece
37fa0 6e 74 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 65  nt.** sqlite3_se
37fb0 74 5f 61 75 78 64 61 74 61 28 43 2c 4e 2c 50 2c  t_auxdata(C,N,P,
37fc0 58 29 20 63 61 6c 6c 20 69 66 20 74 68 65 20 6d  X) call if the m
37fd0 65 74 61 64 61 74 61 20 69 73 20 73 74 69 6c 6c  etadata is still
37fe0 20 76 61 6c 69 64 20 6f 72 0a 2a 2a 20 4e 55 4c   valid or.** NUL
37ff0 4c 20 69 66 20 74 68 65 20 6d 65 74 61 64 61 74  L if the metadat
38000 61 20 68 61 73 20 62 65 65 6e 20 64 69 73 63 61  a has been disca
38010 72 64 65 64 2e 0a 2a 2a 20 5e 41 66 74 65 72 20  rded..** ^After 
38020 65 61 63 68 20 63 61 6c 6c 20 74 6f 20 73 71 6c  each call to sql
38030 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61  ite3_set_auxdata
38040 28 43 2c 4e 2c 50 2c 58 29 20 77 68 65 72 65 20  (C,N,P,X) where 
38050 58 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 0a 2a  X is not NULL,.*
38060 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 69 6e  * SQLite will in
38070 76 6f 6b 65 20 74 68 65 20 64 65 73 74 72 75 63  voke the destruc
38080 74 6f 72 20 66 75 6e 63 74 69 6f 6e 20 58 20 77  tor function X w
38090 69 74 68 20 70 61 72 61 6d 65 74 65 72 20 50 20  ith parameter P 
380a0 65 78 61 63 74 6c 79 0a 2a 2a 20 6f 6e 63 65 2c  exactly.** once,
380b0 20 77 68 65 6e 20 74 68 65 20 6d 65 74 61 64 61   when the metada
380c0 74 61 20 69 73 20 64 69 73 63 61 72 64 65 64 2e  ta is discarded.
380d0 0a 2a 2a 20 53 51 4c 69 74 65 20 69 73 20 66 72  .** SQLite is fr
380e0 65 65 20 74 6f 20 64 69 73 63 61 72 64 20 74 68  ee to discard th
380f0 65 20 6d 65 74 61 64 61 74 61 20 61 74 20 61 6e  e metadata at an
38100 79 20 74 69 6d 65 2c 20 69 6e 63 6c 75 64 69 6e  y time, includin
38110 67 3a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20  g: <ul>.** <li> 
38120 5e 28 77 68 65 6e 20 74 68 65 20 63 6f 72 72 65  ^(when the corre
38130 73 70 6f 6e 64 69 6e 67 20 66 75 6e 63 74 69 6f  sponding functio
38140 6e 20 70 61 72 61 6d 65 74 65 72 20 63 68 61 6e  n parameter chan
38150 67 65 73 29 5e 2c 20 6f 72 0a 2a 2a 20 3c 6c 69  ges)^, or.** <li
38160 3e 20 5e 28 77 68 65 6e 20 5b 73 71 6c 69 74 65  > ^(when [sqlite
38170 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 20 5b 73  3_reset()] or [s
38180 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
38190 29 5d 20 69 73 20 63 61 6c 6c 65 64 20 66 6f 72  )] is called for
381a0 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 53 51 4c   the.**      SQL
381b0 20 73 74 61 74 65 6d 65 6e 74 29 5e 2c 20 6f 72   statement)^, or
381c0 0a 2a 2a 20 3c 6c 69 3e 20 5e 28 77 68 65 6e 20  .** <li> ^(when 
381d0 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64  sqlite3_set_auxd
381e0 61 74 61 28 29 20 69 73 20 69 6e 76 6f 6b 65 64  ata() is invoked
381f0 20 61 67 61 69 6e 20 6f 6e 20 74 68 65 20 73 61   again on the sa
38200 6d 65 0a 2a 2a 20 20 20 20 20 20 20 70 61 72 61  me.**       para
38210 6d 65 74 65 72 29 5e 2c 20 6f 72 0a 2a 2a 20 3c  meter)^, or.** <
38220 6c 69 3e 20 5e 28 64 75 72 69 6e 67 20 74 68 65  li> ^(during the
38230 20 6f 72 69 67 69 6e 61 6c 20 73 71 6c 69 74 65   original sqlite
38240 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 20  3_set_auxdata() 
38250 63 61 6c 6c 20 77 68 65 6e 20 61 20 6d 65 6d 6f  call when a memo
38260 72 79 20 0a 2a 2a 20 20 20 20 20 20 61 6c 6c 6f  ry .**      allo
38270 63 61 74 69 6f 6e 20 65 72 72 6f 72 20 6f 63 63  cation error occ
38280 75 72 73 2e 29 5e 20 3c 2f 75 6c 3e 0a 2a 2a 0a  urs.)^ </ul>.**.
38290 2a 2a 20 4e 6f 74 65 20 74 68 65 20 6c 61 73 74  ** Note the last
382a0 20 62 75 6c 6c 65 74 20 69 6e 20 70 61 72 74 69   bullet in parti
382b0 63 75 6c 61 72 2e 20 20 54 68 65 20 64 65 73 74  cular.  The dest
382c0 72 75 63 74 6f 72 20 58 20 69 6e 20 0a 2a 2a 20  ructor X in .** 
382d0 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64  sqlite3_set_auxd
382e0 61 74 61 28 43 2c 4e 2c 50 2c 58 29 20 6d 69 67  ata(C,N,P,X) mig
382f0 68 74 20 62 65 20 63 61 6c 6c 65 64 20 69 6d 6d  ht be called imm
38300 65 64 69 61 74 65 6c 79 2c 20 62 65 66 6f 72 65  ediately, before
38310 20 74 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   the.** sqlite3_
38320 73 65 74 5f 61 75 78 64 61 74 61 28 29 20 69 6e  set_auxdata() in
38330 74 65 72 66 61 63 65 20 65 76 65 6e 20 72 65 74  terface even ret
38340 75 72 6e 73 2e 20 20 48 65 6e 63 65 20 73 71 6c  urns.  Hence sql
38350 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61  ite3_set_auxdata
38360 28 29 0a 2a 2a 20 73 68 6f 75 6c 64 20 62 65 20  ().** should be 
38370 63 61 6c 6c 65 64 20 6e 65 61 72 20 74 68 65 20  called near the 
38380 65 6e 64 20 6f 66 20 74 68 65 20 66 75 6e 63 74  end of the funct
38390 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ion implementati
383a0 6f 6e 20 61 6e 64 20 74 68 65 0a 2a 2a 20 66 75  on and the.** fu
383b0 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74  nction implement
383c0 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 6f 74  ation should not
383d0 20 6d 61 6b 65 20 61 6e 79 20 75 73 65 20 6f 66   make any use of
383e0 20 50 20 61 66 74 65 72 0a 2a 2a 20 73 71 6c 69   P after.** sqli
383f0 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28  te3_set_auxdata(
38400 29 20 68 61 73 20 62 65 65 6e 20 63 61 6c 6c 65  ) has been calle
38410 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 70 72  d..**.** ^(In pr
38420 61 63 74 69 63 65 2c 20 6d 65 74 61 64 61 74 61  actice, metadata
38430 20 69 73 20 70 72 65 73 65 72 76 65 64 20 62 65   is preserved be
38440 74 77 65 65 6e 20 66 75 6e 63 74 69 6f 6e 20 63  tween function c
38450 61 6c 6c 73 20 66 6f 72 0a 2a 2a 20 66 75 6e 63  alls for.** func
38460 74 69 6f 6e 20 70 61 72 61 6d 65 74 65 72 73 20  tion parameters 
38470 74 68 61 74 20 61 72 65 20 63 6f 6d 70 69 6c 65  that are compile
38480 2d 74 69 6d 65 20 63 6f 6e 73 74 61 6e 74 73 2c  -time constants,
38490 20 69 6e 63 6c 75 64 69 6e 67 20 6c 69 74 65 72   including liter
384a0 61 6c 0a 2a 2a 20 76 61 6c 75 65 73 20 61 6e 64  al.** values and
384b0 20 5b 70 61 72 61 6d 65 74 65 72 73 5d 20 61 6e   [parameters] an
384c0 64 20 65 78 70 72 65 73 73 69 6f 6e 73 20 63 6f  d expressions co
384d0 6d 70 6f 73 65 64 20 66 72 6f 6d 20 74 68 65 20  mposed from the 
384e0 73 61 6d 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68  same.)^.**.** Th
384f0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 75 73  ese routines mus
38500 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d  t be called from
38510 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64   the same thread
38520 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68 65   in which.** the
38530 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73   SQL function is
38540 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76 6f 69   running..*/.voi
38550 64 20 2a 73 71 6c 69 74 65 33 5f 67 65 74 5f 61  d *sqlite3_get_a
38560 75 78 64 61 74 61 28 73 71 6c 69 74 65 33 5f 63  uxdata(sqlite3_c
38570 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 4e 29 3b  ontext*, int N);
38580 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 73 65  .void sqlite3_se
38590 74 5f 61 75 78 64 61 74 61 28 73 71 6c 69 74 65  t_auxdata(sqlite
385a0 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20  3_context*, int 
385b0 4e 2c 20 76 6f 69 64 2a 2c 20 76 6f 69 64 20 28  N, void*, void (
385c0 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 0a 0a 2f 2a  *)(void*));.../*
385d0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
385e0 6e 73 74 61 6e 74 73 20 44 65 66 69 6e 69 6e 67  nstants Defining
385f0 20 53 70 65 63 69 61 6c 20 44 65 73 74 72 75 63   Special Destruc
38600 74 6f 72 20 42 65 68 61 76 69 6f 72 0a 2a 2a 0a  tor Behavior.**.
38610 2a 2a 20 54 68 65 73 65 20 61 72 65 20 73 70 65  ** These are spe
38620 63 69 61 6c 20 76 61 6c 75 65 73 20 66 6f 72 20  cial values for 
38630 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 74  the destructor t
38640 68 61 74 20 69 73 20 70 61 73 73 65 64 20 69 6e  hat is passed in
38650 20 61 73 20 74 68 65 0a 2a 2a 20 66 69 6e 61 6c   as the.** final
38660 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 72 6f 75   argument to rou
38670 74 69 6e 65 73 20 6c 69 6b 65 20 5b 73 71 6c 69  tines like [sqli
38680 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28  te3_result_blob(
38690 29 5d 2e 20 20 5e 49 66 20 74 68 65 20 64 65 73  )].  ^If the des
386a0 74 72 75 63 74 6f 72 0a 2a 2a 20 61 72 67 75 6d  tructor.** argum
386b0 65 6e 74 20 69 73 20 53 51 4c 49 54 45 5f 53 54  ent is SQLITE_ST
386c0 41 54 49 43 2c 20 69 74 20 6d 65 61 6e 73 20 74  ATIC, it means t
386d0 68 61 74 20 74 68 65 20 63 6f 6e 74 65 6e 74 20  hat the content 
386e0 70 6f 69 6e 74 65 72 20 69 73 20 63 6f 6e 73 74  pointer is const
386f0 61 6e 74 0a 2a 2a 20 61 6e 64 20 77 69 6c 6c 20  ant.** and will 
38700 6e 65 76 65 72 20 63 68 61 6e 67 65 2e 20 20 49  never change.  I
38710 74 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20  t does not need 
38720 74 6f 20 62 65 20 64 65 73 74 72 6f 79 65 64 2e  to be destroyed.
38730 20 20 5e 54 68 65 0a 2a 2a 20 53 51 4c 49 54 45    ^The.** SQLITE
38740 5f 54 52 41 4e 53 49 45 4e 54 20 76 61 6c 75 65  _TRANSIENT value
38750 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20   means that the 
38760 63 6f 6e 74 65 6e 74 20 77 69 6c 6c 20 6c 69 6b  content will lik
38770 65 6c 79 20 63 68 61 6e 67 65 20 69 6e 0a 2a 2a  ely change in.**
38780 20 74 68 65 20 6e 65 61 72 20 66 75 74 75 72 65   the near future
38790 20 61 6e 64 20 74 68 61 74 20 53 51 4c 69 74 65   and that SQLite
387a0 20 73 68 6f 75 6c 64 20 6d 61 6b 65 20 69 74 73   should make its
387b0 20 6f 77 6e 20 70 72 69 76 61 74 65 20 63 6f 70   own private cop
387c0 79 20 6f 66 0a 2a 2a 20 74 68 65 20 63 6f 6e 74  y of.** the cont
387d0 65 6e 74 20 62 65 66 6f 72 65 20 72 65 74 75 72  ent before retur
387e0 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ning..**.** The 
387f0 74 79 70 65 64 65 66 20 69 73 20 6e 6